dsh-plugin-usage 0.2.0 → 0.3.0

package/lib/host/scan.js

@@ -1,9 +1,22 @@
 /**
  * Live/persisted session scanning + startup backfill.
  *
- * P1-6: optimization lives here — bounded-concurrency backfill, per-session
- * failure backoff, progress notifications, and an optional onProgress/
- * onDone callback so the host can push a usage/updated event to clients.
+ * DSH 0.2.x session accessors (verified against @deepseek-ai/dsh-session and
+ * @deepseek-ai/dsh-session-persistence 0.2.0-rc.2 / 0.2.1-rc.2):
+ *
+ *  - live:     `ctx.sessions.list()` -> `Session`, events via
+ *              `session.snapshotEvents(fromSeq)`.
+ *  - persisted: `ctx.sessionPersistence.list()` -> `{ header, revision,
+ *              eventCount?, sizeBytes? }`, then `open(id, 'read')` and
+ *              `handle.read(offset)`; the handle carries
+ *              `inheritedEventCount` and must be closed.
+ *
+ * A forked session replays its parent's prefix; `inheritedEventCount` is the
+ * 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.
  */
 import { foldNew } from './fold.js';
 /** How many persisted headers are read concurrently per batch. */
@@ -17,28 +30,94 @@ const BATCH_SIZE = 8;
 const backoffBySession = new Map();
 /** True while a scanPersisted pass is in flight; overlapping passes are dropped. */
 let persistedInFlight = false;
+/**
+ * Events of one live session at or after `fromSeq`.
+ *
+ * @param {any} session - live Session.
+ * @param {number} fromSeq - first seq to return.
+ * @returns {ReadonlyArray<object>} events in log order.
+ */
+export function liveEvents(session, fromSeq) {
+    if (session === null || typeof session !== 'object')
+        return [];
+    if (typeof session.snapshotEvents === 'function')
+        return session.snapshotEvents(fromSeq);
+    // Legacy pre-0.2 sessions exposed the whole log as `events`.
+    if (Array.isArray(session.events)) {
+        return session.events.filter((event) => !event || typeof event.seq !== 'number' || event.seq >= fromSeq);
+    }
+    return [];
+}
 /** Scan live in-memory sessions (cheap, every tick). */
 export function scanLive(ctx, state) {
     const sessions = ctx.get('sessions');
-    if (sessions === undefined)
+    if (sessions === undefined || sessions === null)
         return;
     for (const s of sessions.list()) {
         if (!s || !s.id)
             continue;
         const wm = state.watermarks.get(s.id) ?? -1;
-        const next = foldNew(state, s.id, s.events || [], wm);
+        // Never bill the fork-inherited prefix to the child.
+        const inherited = typeof s.inheritedEventCount === 'number' ? s.inheritedEventCount : 0;
+        const from = Math.max(wm + 1, inherited);
+        const next = foldNew(state, s.id, liveEvents(s, from), wm);
         if (next > wm)
             state.watermarks.set(s.id, next);
     }
 }
+/** Id of one persistence listing snapshot (`{header:{id}}` in 0.2.x). */
+function snapshotId(snap) {
+    if (!snap || typeof snap !== 'object')
+        return undefined;
+    if (snap.header && typeof snap.header.id === 'string')
+        return snap.header.id;
+    if (typeof snap.id === 'string')
+        return snap.id;
+    return undefined;
+}
+/**
+ * Read events for one persisted session at or after `fromSeq`, preferring the
+ * 0.2.x handle API and falling back to a legacy `readFrom` backend.
+ *
+ * @param {any} persistence - sessionPersistence service.
+ * @param {string} id - session id.
+ * @param {number} fromSeq - first seq to return.
+ * @returns {Promise<{ events: ReadonlyArray<object>, inherited: number }>} events + fork cut.
+ */
+export async function readSessionEvents(persistence, id, fromSeq) {
+    if (typeof persistence.open === 'function') {
+        const handle = await persistence.open(id, 'read');
+        try {
+            const inherited = typeof handle.inheritedEventCount === 'number' ? handle.inheritedEventCount : 0;
+            const page = await handle.read(Math.max(fromSeq, inherited));
+            return { events: (page && page.events) || [], inherited };
+        }
+        finally {
+            if (handle && typeof handle.close === 'function') {
+                try {
+                    await handle.close();
+                }
+                catch {
+                    // A close failure must not turn a successful read into a failed scan.
+                }
+            }
+        }
+    }
+    if (typeof persistence.readFrom === 'function') {
+        const page = await persistence.readFrom(id, fromSeq);
+        return { events: (page && page.events) || [], inherited: 0 };
+    }
+    return { events: [], inherited: 0 };
+}
 /**
  * Incremental scan of persisted sessions (slow cadence). Headers are read in
- * small concurrent batches; a failing session is backed off for an
- * exponentially growing number of passes instead of aborting the pass.
+ * small concurrent batches; unchanged revisions are skipped; a failing session
+ * is backed off for an exponentially growing number of passes instead of
+ * aborting the pass.
  */
 export async function scanPersisted(ctx, state, options) {
     const sp = ctx.get('sessionPersistence');
-    if (sp === undefined)
+    if (sp === undefined || sp === null)
         return;
     if (persistedInFlight)
         return; // previous pass still running: skip this tick
@@ -65,22 +144,36 @@ export async function scanPersisted(ctx, state, options) {
     }
 }
 /** Read + fold one persisted session header; bounded by the batch caller. */
-async function processHeader(sp, state, h, options) {
-    if (!h || !h.id)
+async function processHeader(sp, state, snap, options) {
+    const id = snapshotId(snap);
+    if (id === undefined)
         return;
-    const id = h.id;
     const backoff = backoffBySession.get(id);
     if (backoff && backoff.skipLeft > 0) {
         backoff.skipLeft -= 1; // decay the skip count one pass at a time
         return;
     }
-    const wm = state.watermarks.get(id) ?? -1;
     try {
-        const page = await sp.readFrom(id, wm + 1);
-        const events = (page && page.events) || [];
+        const revision = snap && snap.revision;
+        if (revision !== undefined && Object.is(state.revisions.get(id), revision)) {
+            // The backend reports the same change token: the log is unchanged.
+            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.
+        if (typeof snap.eventCount === 'number' && wm >= snap.eventCount) {
+            wm = -1;
+            state.watermarks.set(id, -1);
+            state.lastSample.delete(id);
+        }
+        const { events } = await readSessionEvents(sp, id, wm + 1);
         const next = foldNew(state, id, events, wm);
         if (next > wm)
             state.watermarks.set(id, next);
+        if (revision !== undefined)
+            state.revisions.set(id, revision);
         backoffBySession.delete(id); // success resets the consecutive-failure chain
     }
     catch (error) {
@@ -107,7 +200,7 @@ async function processHeader(sp, state, h, options) {
 /** Full history scan, once at startup. */
 export async function runBackfill(ctx, state, options) {
     const sp = ctx.get('sessionPersistence');
-    if (sp === undefined) {
+    if (sp === undefined || sp === null) {
         state.backfill.status = 'done';
         fireBackfillDone(options, state);
         return;

package/lib/host/settings.js

@@ -1,29 +1,98 @@
 /**
  * Price table + cost computation.
  *
- * P0-1: createPriceStore() keeps the process-memory table. The optimization
- * adds a durable settings-namespace backend via `ctx.settings` (official
- * dsh-settings) with the in-memory store as fallback — implemented by the
- * settings workstream inside this file only.
+ * 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.
+ *
+ * The store below stays the in-memory view the aggregation code reads.
  */
 export const DEFAULT_CURRENCY = '¥';
+/**
+ * Currency the price table is denominated in.
+ *
+ * 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.
+ */
+export const PRICE_UNIT_CURRENCY = 'USD';
+/** Display currencies; `perUsd` is how many units of it one USD buys. */
+export const CURRENCIES = {
+    USD: { code: 'USD', symbol: '$', perUsd: 1 },
+    CNY: { code: 'CNY', symbol: '¥', perUsd: 7 },
+};
+function currencyCodeOf(value) {
+    const raw = typeof value === 'string' ? value.trim().toUpperCase() : '';
+    if (raw === 'USD' || raw === '$' || raw === 'US$')
+        return 'USD';
+    if (raw === 'CNY' || raw === '¥' || raw === 'RMB' || raw === 'CN¥')
+        return 'CNY';
+    return '';
+}
+/**
+ * Resolve a configured currency (ISO code or the bare symbol the store has
+ * always held) to a CURRENCIES entry. Unknown values fall back to `fallback`,
+ * then to the default display currency — never throw on user input.
+ *
+ * @param {unknown} value
+ * @param {unknown} [fallback]
+ */
+export function currencyOf(value, fallback) {
+    const hit = CURRENCIES[currencyCodeOf(value)];
+    if (hit)
+        return hit;
+    const fb = CURRENCIES[currencyCodeOf(fallback)];
+    if (fb)
+        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 },
 };
+/**
+ * Shallow-merge configured prices over the defaults.
+ *
+ * @param {unknown} incoming - configured per-model prices.
+ * @returns {Record<string, object>} complete price table.
+ */
+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,
+                };
+            }
+        }
+    }
+    return merged;
+}
 export function createPriceStore(defaultPrices, defaultCurrency) {
     const prices = Object.assign({}, defaultPrices);
     let currency = defaultCurrency || DEFAULT_CURRENCY;
     const store = {
         prices,
         get currency() { return currency; },
-        /** Write-through slot wired by initSettings(); null without a settings service. */
-        persist: null,
         /** Merge incoming per-model prices (each field coerced to a number). */
         setPrices(incoming) {
             if (!incoming || typeof incoming !== 'object')
@@ -38,15 +107,10 @@ export function createPriceStore(defaultPrices, defaultCurrency) {
                     };
                 }
             }
-            if (typeof store.persist === 'function')
-                store.persist({ prices: Object.assign({}, prices) });
         },
         setCurrency(v) {
-            if (typeof v === 'string' && v.length > 0) {
+            if (typeof v === 'string' && v.length > 0)
                 currency = v;
-                if (typeof store.persist === 'function')
-                    store.persist({ currency });
-            }
         },
         /** Look up a price by `provider/model` composite first, then bare model. */
         priceOf(r) {
@@ -73,90 +137,3 @@ export function createPriceStore(defaultPrices, defaultCurrency) {
     };
     return store;
 }
-const USAGE_PRICES_NS = 'usage.prices';
-/** JSON-schema-shaped descriptor for the usage.prices settings section. */
-const PRICE_SECTION_DESCRIPTOR = {
-    type: 'object',
-    properties: {
-        prices: {
-            type: 'object',
-            description: 'Per-model prices (cost per 1M tokens, in `currency`).',
-            additionalProperties: {
-                type: 'object',
-                properties: {
-                    inputPerM: { type: 'number' },
-                    outputPerM: { type: 'number' },
-                    cacheReadPerM: { type: 'number' },
-                    cacheWritePerM: { type: 'number' },
-                },
-                required: ['inputPerM', 'outputPerM', 'cacheReadPerM', 'cacheWritePerM'],
-            },
-        },
-        currency: { type: 'string' },
-    },
-    required: ['prices', 'currency'],
-};
-/** Apply a resolved settings section onto the in-memory price store. */
-function applySection(store, section) {
-    if (!section || typeof section !== 'object')
-        return;
-    if (typeof store.setPrices === 'function' && section.prices && typeof section.prices === 'object' && !Array.isArray(section.prices)) {
-        store.setPrices(section.prices);
-    }
-    if (typeof store.setCurrency === 'function' && typeof section.currency === 'string')
-        store.setCurrency(section.currency);
-}
-/**
- * P0-1: wire the price store to the official `ctx.settings` namespace
- * (durable, shown in the official Plugins config tab) when available.
- * Registers `usage.prices`, seeds the store from the resolved section, and
- * writes every setPrices/setCurrency mutation through. Falls back to the
- * in-memory store whenever the settings service is missing or unavailable.
- */
-export function initSettings(ctx, store) {
-    if (!ctx || typeof ctx.get !== 'function' || !store || typeof store !== 'object')
-        return;
-    let settings;
-    try {
-        settings = ctx.get('settings');
-    }
-    catch {
-        return;
-    }
-    if (!settings || typeof settings.register !== 'function')
-        return;
-    let scope;
-    try {
-        scope = settings.register(USAGE_PRICES_NS, PRICE_SECTION_DESCRIPTOR, { base: { prices: DEFAULT_PRICES, currency: DEFAULT_CURRENCY }, applies: 'live' });
-    }
-    catch {
-        return; // registration failed — keep the current in-memory behavior
-    }
-    store.persist = (patch) => {
-        try {
-            if (scope && typeof scope.update === 'function')
-                return scope.update(USAGE_PRICES_NS, patch);
-            if (settings && typeof settings.update === 'function')
-                return settings.update(USAGE_PRICES_NS, patch);
-        }
-        catch {
-            // Never throw when the settings scope is unavailable.
-        }
-    };
-    let section;
-    try {
-        if (scope && typeof scope.get === 'function')
-            section = scope.get();
-        else if (settings && typeof settings.get === 'function')
-            section = settings.get(USAGE_PRICES_NS);
-    }
-    catch {
-        section = undefined;
-    }
-    if (section && typeof section.then === 'function') {
-        section.then((resolved) => applySection(store, resolved)).catch(() => { });
-    }
-    else {
-        applySection(store, section);
-    }
-}

package/lib/host/state.js

@@ -1,11 +1,20 @@
 /**
  * Mutable runtime state capsule for the usage host half.
  *
- * - records: folded usage records, one per assistant/message with usage.
+ * - records: folded usage records, one per billed assistant settlement
+ *   (`assistant/message` or `assistant/attempt`) that reported usage.
  * - watermarks: sessionId -> last folded event seq.
+ * - revisions: sessionId -> last persisted revision folded (opaque equality
+ *   token from `sessionPersistence.list()`); lets the slow scan skip sessions
+ *   whose log did not change.
  * - backfill: progress counters surfaced through query results.
  * - prices: the price store from settings.js.
- * - dedup: (sessionId, turn, step) -> index in records; owned by fold.js.
+ * - lastSample: sessionId -> { turn, step, record } — the replacement slot the
+ *   official tokenUsage projection keeps, so a later sample for the same
+ *   (turn, step) replaces in place and `llm/retry-started` clears it.
+ * - route: sessionId -> { provider, model } from the latest request route,
+ *   used to attribute settlements that carry no `message.source`
+ *   (`assistant/attempt` never does).
  * - index: incremental aggregation index (aggregate.js), kept in sync by
  *   fold.js and consumed by query.js.
  */
@@ -13,9 +22,11 @@ export function createState(priceStore) {
     return {
         records: [],
         watermarks: new Map(),
+        revisions: new Map(),
         backfill: { status: 'idle', total: 0, done: 0 },
         prices: priceStore,
-        dedup: new Map(),
+        lastSample: new Map(),
+        route: new Map(),
         index: null, // wired by apply() after createUsageIndex(state)
     };
 }

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Usage Statistics",
+    "description": "Token, call and reference-cost statistics by day and by model, with model filters and a yearly heatmap."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "用量统计",
+    "description": "按天、按模型查看 Token、调用次数与参考成本，支持模型筛选与年度热力图。"
+  }
+}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "dsh-plugin-usage",
   "description": "Token usage statistics for DeepSeek Harness — daily/custom-range views, model filters, call counts and cost, inspired by CC Switch statistics.",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/bennett-dsh/dsh-plugin-usage.git"
   },
   "type": "module",
+  "icon": "./icon.svg",
   "main": "lib/host/index.js",
   "exports": {
     ".": {
@@ -17,11 +18,16 @@
       "default": "./lib/client/index.js"
     },
     "./cordis.patch.yml": "./cordis.patch.yml",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json"
   },
   "files": [
     "lib",
-    "cordis.patch.yml"
+    "cordis.patch.yml",
+    "icon.svg",
+    "locale",
+    "image.png",
+    "image-1.png"
   ],
   "keywords": [
     "dsh",
@@ -32,7 +38,12 @@
     "statistics",
     "cost"
   ],
+  "engines": {
+    "node": ">=22",
+    "dsh": ">=0.2.0-rc.2 <0.3.0"
+  },
   "dsh": {
+    "manifestVersion": 1,
     "bundle": {
       "patch": "./cordis.patch.yml"
     },
@@ -45,12 +56,14 @@
       "platform": "web"
     }
   },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "~3.18.5"
+  },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "react": "^18.2.0"
+    "@deepseek-ai/cordis": "~4.0.5"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/cordis": "~4.0.5",
     "@types/react": "~18.3.1",
     "react": "^18.2.0",
     "typescript": "^5.5.0"
@@ -59,6 +72,6 @@
     "build": "tsc -p tsconfig.json && node scripts/build-client.js",
     "test": "node --test tests/*.test.js",
     "watch": "tsc -p tsconfig.json --watch",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build && npm test"
   }
-}
+}