dsh-plugin-usage 0.4.0 → 0.5.0

package/lib/host/scan.js

@@ -15,10 +15,14 @@
  * cut, so folding starts there and the parent is never billed twice.
  *
  * Optimization lives here: bounded-concurrency backfill, per-session failure
- * backoff, revision-based skip (unchanged logs are not re-read), progress
- * callbacks, and watermark repair when a log shrank.
+ * backoff, revision-based skip (unchanged logs are not re-read), the on-disk fold
+ * cache (unchanged logs are not even opened after a restart), progress callbacks,
+ * and watermark repair when a log shrank.
  */
 import { foldNew } from './fold.js';
+import { cacheDir, readEntry, writeEntry } from './fold-cache.js';
+import { writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 /** How many persisted headers are read concurrently per batch. */
 const BATCH_SIZE = 8;
 /**
@@ -109,6 +113,114 @@ export async function readSessionEvents(persistence, id, fromSeq) {
     }
     return { events: [], inherited: 0 };
 }
+/* -------------------------------------------------------------------------- *
+ * Fold cache plumbing
+ * -------------------------------------------------------------------------- */
+/**
+ * Open one scan pass.
+ *
+ * The cache is optional and never required: a pass without it behaves exactly as
+ * before, which is what a failing cache degrades to.
+ *
+ * @param {{ cache?: boolean, cacheDir?: string }} [options]
+ * @returns {{ dir: string | null, scanned: Set<string>, hydrated: number }}
+ */
+function beginPass(options) {
+    const enabled = !(options && options.cache === false);
+    return {
+        dir: enabled ? (options && options.cacheDir) || cacheDir() : null,
+        scanned: new Set(),
+        hydrated: 0,
+        startedAt: Date.now(),
+        listMs: 0,
+    };
+}
+/**
+ * One line per pass, so a slow start explains itself instead of being guessed at.
+ *
+ * The line goes to the logger AND into `state.lastPass`, which the dashboard
+ * response carries: on this host the plugin logger does not reliably reach the
+ * desktop log file, and a probe nobody can read is not a probe.
+ */
+function reportPass(pass, counts, log) {
+    const ms = Date.now() - pass.startedAt;
+    const summary = {
+        at: pass.startedAt,
+        sessions: counts.total,
+        hydrated: counts.hydrated,
+        folded: counts.folded,
+        listMs: pass.listMs,
+        totalMs: ms,
+    };
+    return summary;
+}
+/** Records grouped by owning session, in one pass over the record array. */
+function groupRecordsBySession(records) {
+    const by = new Map();
+    for (const record of records) {
+        const id = record && record.session;
+        if (typeof id !== 'string')
+            continue;
+        let list = by.get(id);
+        if (list === undefined) {
+            list = [];
+            by.set(id, list);
+        }
+        list.push(record);
+    }
+    return by;
+}
+/**
+ * Cache one hydrated session's records and bookkeeping into the live state.
+ *
+ * Refuses an entry whose records do not belong to `id`: a mixed-up file would
+ * otherwise attribute one session's tokens to another.
+ *
+ * @returns {boolean} whether the entry was usable (and therefore consumed).
+ */
+function hydrateFromCache(state, id, entry, revision) {
+    for (const record of entry.records) {
+        if (!record || record.session !== id)
+            return false;
+    }
+    for (const record of entry.records) {
+        state.records.push(record);
+        if (state.index)
+            state.index.add(record);
+    }
+    state.watermarks.set(id, entry.watermark);
+    if (revision !== undefined)
+        state.revisions.set(id, revision);
+    return true;
+}
+/**
+ * Persist what this pass folded, then drop sessions that no longer exist.
+ *
+ * Only sessions this pass actually folded are rewritten: an untouched session's
+ * entry stays valid because its revision did not change.
+ */
+function finishPass(state, headers, pass) {
+    if (pass.dir === null)
+        return;
+    if (pass.scanned.size > 0) {
+        const bySession = groupRecordsBySession(state.records);
+        for (const id of pass.scanned) {
+            writeEntry(pass.dir, id, {
+                revision: state.revisions.get(id),
+                watermark: state.watermarks.get(id) ?? -1,
+                records: bySession.get(id) || [],
+            });
+        }
+    }
+    // ⚠️ Do NOT prune entries missing from this listing. `sp.list()` returns a
+    // PARTIAL list while the session store is still warming up after a start, and a
+    // prune keyed on "absent here" therefore deletes entries that are perfectly
+    // valid. That is not hypothetical: it wiped 257 of 258 entries on a live
+    // instance at 00:18 and every following start had to fold the whole history
+    // again — the "numbers climb for 30 s" symptom. A stale entry costs disk and
+    // nothing else (it is only read by id from a listing), so it is never worth
+    // deleting speculatively.
+}
 /**
  * Incremental scan of persisted sessions (slow cadence). Headers are read in
  * small concurrent batches; unchanged revisions are skipped; a failing session
@@ -118,18 +230,44 @@ export async function readSessionEvents(persistence, id, fromSeq) {
 export async function scanPersisted(ctx, state, options) {
     const sp = ctx.get('sessionPersistence');
     if (sp === undefined || sp === null)
-        return;
+        return false;
     if (persistedInFlight)
-        return; // previous pass still running: skip this tick
+        return false; // previous pass still running: skip this tick
     persistedInFlight = true;
+    const pass = beginPass(options);
     try {
+        const listedAt = Date.now();
         const headers = await sp.list();
+        pass.listMs = Date.now() - listedAt;
         if (!Array.isArray(headers))
-            return;
+            return true;
         state.backfill.total = headers.length;
         for (let i = 0; i < headers.length; i += BATCH_SIZE) {
             const batch = headers.slice(i, i + BATCH_SIZE);
-            await Promise.all(batch.map((h) => processHeader(sp, state, h, options)));
+            await Promise.all(batch.map((h) => processHeader(sp, state, h, options, pass)));
+        }
+        finishPass(state, headers, pass);
+        // The counters must agree at the end, WHOEVER started the pass: a cadence
+        // pass runs while status is already 'done', and gating on status left
+        // `{status: done, total: 258, done: 0}` in the response — which reads as
+        // "nothing was scanned" while every record was in fact loaded.
+        state.backfill.done = headers.length;
+        const summary = reportPass(pass, { total: headers.length, hydrated: pass.hydrated, folded: pass.scanned.size });
+        state.lastPass = summary;
+        // Also leave it on disk: the log line needs a logger that reaches the host
+        // log (this host does not always), while the file is readable without a
+        // browser. Best effort: a failed diagnostic must never fail the pass.
+        if (pass.dir !== null) {
+            try {
+                writeFileSync(join(dirname(pass.dir), 'last-pass.json'), JSON.stringify(summary, null, 2));
+            }
+            catch {
+                // diagnostics only
+            }
+        }
+        if (options && typeof options.log === 'function') {
+            safeLog(options.log, '[usage] scan pass: ' + summary.sessions + ' sessions, ' + summary.hydrated
+                + ' from cache, ' + summary.folded + ' folded, list ' + summary.listMs + 'ms, total ' + summary.totalMs + 'ms');
         }
     }
     finally {
@@ -144,7 +282,7 @@ export async function scanPersisted(ctx, state, options) {
     }
 }
 /** Read + fold one persisted session header; bounded by the batch caller. */
-async function processHeader(sp, state, snap, options) {
+async function processHeader(sp, state, snap, options, pass) {
     const id = snapshotId(snap);
     if (id === undefined)
         return;
@@ -160,6 +298,18 @@ async function processHeader(sp, state, snap, options) {
             backoffBySession.delete(id);
             return;
         }
+        // Cache hit: same change token as the snapshot on disk, so the folded
+        // records are still exactly what a fresh fold would produce. This is the
+        // whole point of the cache — after a restart, an unchanged session costs one
+        // JSON read instead of a full log read + inflate + fold.
+        if (pass !== undefined && pass !== null && pass.dir !== null && revision !== undefined) {
+            const entry = readEntry(pass.dir, id);
+            if (entry !== null && entry.revision === revision && hydrateFromCache(state, id, entry, revision)) {
+                pass.hydrated += 1;
+                backoffBySession.delete(id);
+                return;
+            }
+        }
         let wm = state.watermarks.get(id) ?? -1;
         // A crash-repaired or migrated log can shrink below our watermark; the
         // backend reports the current event count, so repair instead of stalling.
@@ -174,6 +324,8 @@ async function processHeader(sp, state, snap, options) {
             state.watermarks.set(id, next);
         if (revision !== undefined)
             state.revisions.set(id, revision);
+        if (pass !== undefined && pass !== null)
+            pass.scanned.add(id);
         backoffBySession.delete(id); // success resets the consecutive-failure chain
     }
     catch (error) {
@@ -197,7 +349,40 @@ async function processHeader(sp, state, snap, options) {
         }
     }
 }
-/** Full history scan, once at startup. */
+/**
+ * Start the full-history scan on demand, from the first query.
+ *
+ * Why not at activation: the pass is the only moment "缓存加载" is visible, and it
+ * takes ~0.8 s warm (12 s cold). Started from `apply` it finishes before anyone
+ * opens the panel, so the loading state can never be seen — the user restarted a
+ * dozen times and saw nothing. Started from the first query, the panel's own
+ * opening *is* the computation window, so the skeleton and the progress line are
+ * on screen for exactly as long as the work takes.
+ *
+ * Returns true when this call started it, false when it was already started.
+ */
+export function startBackfillOnDemand(ctx, state, options) {
+    if (state.backfill.started === true)
+        return false;
+    // Flip the visible state first: the caller renders the response for this very
+    // request, and it must already say "running" or the client shows the empty
+    // dashboard for one frame. `runBackfill` flips `started` synchronously.
+    state.backfill.status = 'running';
+    state.backfill.done = 0;
+    const log = options && typeof options.log === 'function' ? options.log : undefined;
+    // Fire-and-forget **with** a catch. An unhandled rejection here is fatal on this
+    // host, and `runBackfill`'s own try only begins after its `ctx.get(...)` probe,
+    // so a throwing context access would otherwise crash the process from a plain
+    // read request. Same failure class as the `logSink(...).warn` crash: background
+    // work must never be able to take the host down.
+    void runBackfill(ctx, state, options).catch((error) => {
+        state.backfill.status = 'done';
+        if (log !== undefined)
+            safeLog(log, '[usage] backfill rejected: ' + (error && error.message ? error.message : String(error)));
+    });
+    return true;
+}
+/** Full history scan, once per process (lazily, from `startBackfillOnDemand`). */
 export async function runBackfill(ctx, state, options) {
     const sp = ctx.get('sessionPersistence');
     if (sp === undefined || sp === null) {
@@ -205,23 +390,57 @@ export async function runBackfill(ctx, state, options) {
         fireBackfillDone(options, state);
         return;
     }
+    // "只跑一次"由 `started` 记，不由 `status` 记：按需启动时调用方会先把 status
+    // 置成 running（好让发起查询的那一帧就带上加载态），用 status 当守卫会把真正
+    // 要干的活挡在门外。
+    if (state.backfill.started === true)
+        return;
+    state.backfill.started = true;
     state.backfill.status = 'running';
     state.backfill.done = 0;
     // Delegate progress while the pass runs; onDone is fired right here exactly
     // once so the pass callback does not double-report backfill completion.
-    const scanOptions = options && typeof options.onProgress === 'function'
-        ? { onProgress: options.onProgress }
-        : undefined;
+    const log = options && typeof options.log === 'function' ? options.log : undefined;
+    // Forward every scan option (cache / cacheDir included) instead of rebuilding
+    // the object: rebuilding dropped `cache: false` and quietly used the real cache
+    // directory in tests. `onDone` stays here — runBackfill fires it exactly once.
+    const { onDone: ignoredOnDone, ...scanOptions } = options || {};
+    if (log !== undefined)
+        scanOptions.log = log;
     try {
-        await scanPersisted(ctx, state, scanOptions);
+        let ran = await scanPersisted(ctx, state, scanOptions);
+        // A cadence pass may already be in flight when the plugin activates. That pass
+        // does the work, but "done" must not be announced before anything was read —
+        // that is how the response ended up saying `done: 0` while every record was
+        // loaded.
+        for (let attempt = 0; ran === false && attempt < 40; attempt += 1) {
+            await new Promise((resolve) => setTimeout(resolve, 250));
+            ran = await scanPersisted(ctx, state, scanOptions);
+        }
         state.backfill.status = 'done';
         fireBackfillDone(options, state);
     }
     catch (error) {
+        // A failed pass must not wedge the plugin in `running` — but it must not
+        // vanish either: "the dashboard never filled in" is unanswerable if the
+        // reason was swallowed here.
+        // Logging is best-effort: a broken sink must cost one line, never the host.
+        // (This catch used to re-throw through a bad logger and took dsh down.)
         state.backfill.status = 'done';
+        if (log !== undefined)
+            safeLog(log, '[usage] backfill failed: ' + (error && error.message ? error.message : String(error)));
         fireBackfillDone(options, state);
     }
 }
+/** Call a diagnostic sink without ever letting it throw into the work. */
+function safeLog(sink, message) {
+    try {
+        sink(message);
+    }
+    catch {
+        // A logger that throws is a logging problem, not a scanning problem.
+    }
+}
 function fireBackfillDone(options, state) {
     if (options && typeof options.onDone === 'function') {
         options.onDone({

package/lib/host/settings.js

@@ -1,26 +1,37 @@
 /**
- * Price table + cost computation.
+ * Currency + the user's own price table + the in-memory price store.
  *
- * Persistence is the official plugin-config path: `index.js` exports a
- * schemastery `Config`, so DSH materializes a form under the plugin entry's
- * id (`usage`) in the Plugins settings tab and stores values in the profile
- * patch. There is deliberately no private `settings.yaml` / settings-service
- * registration here — DSH 0.2.x `ctx.settings` (SettingsForms) only offers
- * `describe/update/replace/mutate/configure`, and hand-rolled namespaces are
- * not reachable from the client config surface.
+ * There is exactly one pricing policy in this plugin, and it lives in
+ * pricing.js: the ladder. This file owns the two things around it that are not
+ * policy —
  *
- * The store below stays the in-memory view the aggregation code reads.
- */
-export const DEFAULT_CURRENCY = '¥';
-/**
- * Currency the price table is denominated in.
+ *  - the display currency, converted once at the query boundary;
+ *  - the user's explicit price rows, which are an *override*, never a catalogue.
+ *
+ * That last point is the whole reason this file lost its `DEFAULT_PRICES`: a
+ * hard-coded copy of a vendor price is a second source of truth that outranks
+ * the generated table (the ladder checks the user table first), so it silently
+ * wins even when it is stale. It was: one row carried a cached-input price 13.3×
+ * the official list, and seven of ten rows named ids the vendor had retired. A
+ * price the reference table can answer belongs in the generation script; a price
+ * only the user knows (an odd relay id) belongs here.
+ *
+ * Spelling: the config form persists `inputPerM`-style fields because that is
+ * what older profiles already contain, and renaming them would zero every saved
+ * price on the next save. `normalizePrices` / `configPrices` are the only two
+ * places that know this, and the store works in the canonical
+ * `{ input, output, cacheRead, cacheWrite }` shape that `ratesOf` reads.
  *
- * DEFAULT_PRICES carries DeepSeek's USD list price per 1M tokens (0.27 input /
- * 1.10 output / 0.07 cache-read for `deepseek-chat`, which is exactly 2 / 8 /
- * 0.5 CNY at the fixed 7:1). The table is never rewritten at runtime: a display
- * switch converts on the way out, so a query can never pollute the next one.
+ * Persistence stays the official plugin-config path: `index.js` exports a
+ * schemastery `Config`, so DSH materializes a form under the plugin entry's id
+ * (`usage`) in the Plugins settings tab. There is deliberately no private
+ * `settings.yaml` / settings-service registration here — DSH 0.2.x
+ * `ctx.settings` (SettingsForms) only offers `describe/update/replace/mutate/
+ * configure`, and hand-rolled namespaces are not reachable from the client
+ * config surface.
  */
-export const PRICE_UNIT_CURRENCY = 'USD';
+import { costOf, resolvePrice } from './pricing.js';
+export const DEFAULT_CURRENCY = '¥';
 /** Display currencies; `perUsd` is how many units of it one USD buys. */
 export const CURRENCIES = {
     USD: { code: 'USD', symbol: '$', perUsd: 1 },
@@ -51,85 +62,117 @@ export function currencyOf(value, fallback) {
         return fb;
     return CURRENCIES[currencyCodeOf(DEFAULT_CURRENCY)] || CURRENCIES.CNY;
 }
-export 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-v4.1-flash': { inputPerM: 0.14, outputPerM: 0.56, cacheReadPerM: 0.04, cacheWritePerM: 0.14 },
-    'deepseek-v4.1-flash-1017': { inputPerM: 0.14, outputPerM: 0.56, cacheReadPerM: 0.04, cacheWritePerM: 0.14 },
-    // DSH's routed default model id (`magpie` provider) aliases the same route;
-    // without this entry every session bills as "unpriced" on a stock install.
-    'group/auto-deepseek-v4-1-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 },
-};
+/** Rate field on the canonical row, and the name the config form persists. */
+const RATE_FIELDS = [
+    ['input', 'inputPerM'],
+    ['output', 'outputPerM'],
+    ['cacheRead', 'cacheReadPerM'],
+    ['cacheWrite', 'cacheWritePerM'],
+];
 /**
- * Shallow-merge configured prices over the defaults.
+ * Turn configured rows into the canonical rate shape the ladder reads.
+ *
+ * Accepts both spellings, drops entries that are not objects, and coerces every
+ * rate to a number (a form field saved as a string must not become NaN and then
+ * a zero cost). Unknown keys are dropped: a typo must not become a price.
  *
- * @param {unknown} incoming - configured per-model prices.
- * @returns {Record<string, object>} complete price table.
+ * @param {unknown} incoming - rows from the plugin config or the `prices` RPC.
+ * @returns {Record<string, { input: number, output: number, cacheRead: number, cacheWrite: number }>}
  */
-export function mergePrices(incoming) {
-    const merged = Object.assign({}, DEFAULT_PRICES);
-    if (incoming && typeof incoming === 'object' && !Array.isArray(incoming)) {
-        for (const [model, price] of Object.entries(incoming)) {
-            if (price && typeof price === 'object') {
-                merged[model] = {
-                    inputPerM: Number(price.inputPerM) || 0,
-                    outputPerM: Number(price.outputPerM) || 0,
-                    cacheReadPerM: Number(price.cacheReadPerM) || 0,
-                    cacheWritePerM: Number(price.cacheWritePerM) || 0,
-                };
-            }
+export function normalizePrices(incoming) {
+    const out = {};
+    if (!incoming || typeof incoming !== 'object' || Array.isArray(incoming))
+        return out;
+    for (const [key, row] of Object.entries(incoming)) {
+        if (!row || typeof row !== 'object')
+            continue;
+        const rate = {};
+        for (const [canonical, legacy] of RATE_FIELDS) {
+            const v = row[canonical] !== undefined ? row[canonical] : row[legacy];
+            rate[canonical] = Number(v) || 0;
         }
+        out[key] = rate;
     }
-    return merged;
+    return out;
 }
-export function createPriceStore(defaultPrices, defaultCurrency) {
-    const prices = Object.assign({}, defaultPrices);
+/**
+ * The inverse of `normalizePrices`, for the config form.
+ *
+ * Only needed because the persisted schema still spells `inputPerM`; keeping the
+ * mapper here means the rest of the codebase never sees that spelling.
+ *
+ * @param {Record<string, object>} prices - canonical rows.
+ * @returns {Record<string, object>} rows the Config schema accepts.
+ */
+export function configPrices(prices) {
+    const out = {};
+    for (const [key, row] of Object.entries(prices || {})) {
+        const rate = {};
+        for (const [canonical, legacy] of RATE_FIELDS)
+            rate[legacy] = Number(row[canonical]) || 0;
+        out[key] = rate;
+    }
+    return out;
+}
+/**
+ * The in-memory pricing view the aggregation code reads.
+ *
+ * It owns no policy: every answer comes from `resolvePrice` / `costOf`, so the
+ * dashboard, the dialog and the settings form cannot disagree about what a model
+ * costs.
+ *
+ * @param {unknown} defaultPrices - configured price rows (any spelling).
+ * @param {string} [defaultCurrency] - display currency.
+ * @param {{ matches?: Record<string,string>|(() => Record<string,string>) }} [options]
+ *   confirmed matches, or a getter for the live map (a commit replaces the map,
+ *   so a store closing over a snapshot would price from the pre-commit state).
+ */
+export function createPriceStore(defaultPrices, defaultCurrency, options = {}) {
+    const prices = normalizePrices(defaultPrices);
     let currency = defaultCurrency || DEFAULT_CURRENCY;
+    const matchesOf = typeof options.matches === 'function'
+        ? options.matches
+        : () => (options.matches && typeof options.matches === 'object' ? options.matches : null);
+    const isRecord = (r) => r !== null && typeof r === 'object';
     const store = {
         prices,
         get currency() { return currency; },
-        /** Merge incoming per-model prices (each field coerced to a number). */
+        /** Merge incoming rows over the current ones (both normalized). */
         setPrices(incoming) {
-            if (!incoming || typeof incoming !== 'object')
-                return;
-            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,
-                    };
-                }
-            }
+            Object.assign(prices, normalizePrices(incoming));
         },
         setCurrency(v) {
             if (typeof v === 'string' && v.length > 0)
                 currency = v;
         },
-        /** Look up a price by `provider/model` composite first, then bare model. */
+        /**
+         * Resolve one record to a price.
+         *
+         * @param {{ provider?: string, model?: string }} r - a usage record.
+         * @returns {{ price: object|null, how: string, state: string, target: string|null, why: string }}
+         */
+        lookup(r) {
+            if (!isRecord(r))
+                return { price: null, how: 'unmatched', state: 'none', target: null, why: '' };
+            return resolvePrice({
+                model: typeof r.model === 'string' ? r.model : '',
+                provider: typeof r.provider === 'string' ? r.provider : '',
+                custom: prices,
+                matches: matchesOf(),
+            });
+        },
+        /** The first hit of the ladder, keeping the old `undefined when absent` contract. */
         priceOf(r) {
-            const composite = r.provider ? r.provider + '/' + r.model : '';
-            return prices[composite] || prices[r.model];
+            const hit = store.lookup(r);
+            return hit.price === null ? undefined : hit.price;
         },
-        /** Whether an explicit price entry exists (composite first, then bare model). */
+        /** Whether the ladder found a price at all. */
         hasPrice(r) {
-            const composite = r.provider ? r.provider + '/' + r.model : '';
-            return composite in prices || r.model in prices;
+            return store.lookup(r).price !== null;
         },
         costOf(r) {
-            const p = store.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;
+            const hit = store.lookup(r);
+            return hit.price === null ? 0 : costOf(r, hit.price);
         },
         snapshot() {
             return { prices: Object.assign({}, prices), currency };

package/lib/host/state.js

@@ -2,7 +2,9 @@
  * Mutable runtime state capsule for the usage host half.
  *
  * - records: folded usage records, one per billed assistant settlement
- *   (`assistant/message` or `assistant/attempt`) that reported usage.
+ *   (`assistant/message` or `assistant/attempt`) that reported usage. A record
+ *   may also carry `tokens: { peak?, off? }` — the same usage split by the price
+ *   tier its own timestamp fell into (see fold.js).
  * - watermarks: sessionId -> last folded event seq.
  * - revisions: sessionId -> last persisted revision folded (opaque equality
  *   token from `sessionPersistence.list()`); lets the slow scan skip sessions
@@ -17,16 +19,30 @@
  *   (`assistant/attempt` never does).
  * - index: incremental aggregation index (aggregate.js), kept in sync by
  *   fold.js and consumed by query.js.
+ * - peakOf: `(atMs) => boolean` price-tier test, injected by apply(). Absent
+ *   means "record flat token fields only", which is what the tests rely on.
+ * - matchMap: model key -> reference model id, the user's confirmed matches.
+ *   A key that is present overrides the automatic ladder in pricing.js.
  */
 export function createState(priceStore) {
     return {
         records: [],
         watermarks: new Map(),
         revisions: new Map(),
-        backfill: { status: 'idle', total: 0, done: 0 },
+        // 启动回填是**按需**触发的：`idle` 一直保持到第一次查询（面板真正要被看）。
+        // 这样"缓存加载"这件事发生在用户眼前，而不是在进程启动的头一秒里悄悄做完。
+        // `started` 与 `status` 分开：调用方会先把 status 置 running 好让这一帧就带上
+        // 加载态，所以不能用 status 当"只跑一次"的守卫。
+        backfill: { status: 'idle', total: 0, done: 0, started: false },
+        // Last scan pass summary: how long listing took, how much came from the fold
+        // cache, how long the whole pass took. Surfaced in the dashboard response —
+        // the plugin logger does not reliably reach the host log file on this host.
+        lastPass: null,
         prices: priceStore,
         lastSample: new Map(),
         route: new Map(),
         index: null, // wired by apply() after createUsageIndex(state)
+        peakOf: null, // wired by apply() once the holiday calendar is known
+        matchMap: {},
     };
 }