@rayadesu/dsh-llm-billing 0.3.16 → 0.3.17

package/lib/types/today-spend.js

@@ -7,7 +7,7 @@
  *   `billingTodaySpend` projection cell; cold sessions are answered from the
  *   zero-I/O projection-cache row whenever that row's own day is not the
  *   queried one, and otherwise resolved through one detached local fold over
- *   a full `inspect`. Persisted revisions gate every cold read, so a session
+ *   a full `open` + handle read. Persisted revisions gate every cold read, so a session
  *   whose log did not change since the last resolution costs nothing — and a
  *   failed resolution is remembered by revision instead of being retried on
  *   every scan.
@@ -38,258 +38,29 @@
  * cut, and `apply` skips events below it), so the eager cell is correct for a
  * fork child; the cold path skips the projection cache for a seeded session
  * (its cached row may predate the boundary) and folds its own events with the
- * durable cut instead. The boundary is the durable session state, read across
- * both DSH runtime families — a resumed fork child keeps its original
+ * durable cut instead. The boundary is the durable session state, read from the
+ * live-session and handle surfaces — a resumed fork child keeps its original
  * boundary and an unseeded session stays at 0.
  *
  * The live `Session` log surface changed in 0.1.2-alpha.4: `Session.events`
  * was removed and replaced by `Session.snapshotEvents()` / `ownEvents()`, and
  * `SessionHeader.seedLength` moved to `Session.inheritedEventCount` (the
- * persistence `inspect` result carries it alongside `meta`). Reads go through
- * {@link liveSessionEvents} / {@link forkBoundaryOf}, which accept both
- * families structurally, so the scanner runs on the ≤ 0.1.1-rc.2 npm baseline
- * and on the newer runtime.
+ * opened `SessionHandle` carries it alongside `header`). Reads go through
+ * {@link liveSessionEvents} / {@link forkBoundaryOf}, which accept the
+ * live-session and handle shapes structurally, so the scanner runs on the
+ * older `events` runtime and on the newer `snapshotEvents` runtime.
  * @module @rayadesu/dsh-llm-billing/today-spend
  */
-import { beijingDayKey, beijingPartsOf, BillingFolder, emptyTodaySpend, forkBoundaryOf, isSeededSession, mergeTodaySpend } from "./billing.js";
+import { beijingDayRangeOfKey, beijingPartsOf, BillingFolder, emptyTodaySpend, forkBoundaryOf, isSeededSession, mergeTodaySpend } from "./billing.js";
 import { BILLING_UNIT_KEY, foldOwnBilling } from "./projection.js";
-/**
- * Fold one session's durable display title: the latest `session/title`
- * event's text (last-wins, matching the `title` projection), or `null` before
- * the first title lands. The fold runs over the complete log, so an explicit
- * user rename is picked up as soon as its event commits.
- * @param events - one session's complete event log.
- * @returns the session's current title, or `null` when untitled.
- */
-export function foldSessionTitle(events) {
-    for (let index = events.length - 1; index >= 0; index--) {
-        const event = events[index];
-        // `session/title` joined the SessionEvent union after the npm
-        // 0.1.1-rc.2 baseline this package builds against; read its payload
-        // through the structural escape hatch (runtime logs carry it).
-        if (event.type !== 'session/title')
-            continue;
-        const data = event.data;
-        return typeof data.title === 'string' ? data.title : null;
-    }
-    return null;
-}
-/**
- * Whether one session's durable header marks it as a subagent child. Either
- * marker is enough: `origin` is DSH's navigation classification and
- * `delegationDepth` is its persisted recursion budget, so a header carrying
- * only the depth (or only the origin) is still a delegation child. A session
- * created without either — an ordinary session, a user fork, or a cold resume
- * — is top-level.
- * @param header - the session's lineage slice; `undefined` reads as top-level.
- * @returns true when the session was created as a subagent child.
- */
-export function isSubagentSession(header) {
-    if (header === undefined)
-        return false;
-    return header.origin === 'subagent' || (header.delegationDepth ?? 0) > 0;
-}
-/**
- * The top-level session one session's ranking row belongs to: the session
- * itself for a top-level session, and for a subagent child the first ancestor
- * up the `parentSession` chain that is not itself a subagent child. A
- * multi-generation delegation (a subagent that spawned subagents) therefore
- * lands on the same root row as its parent, and a child whose parent header is
- * unknown is attributed to the parent id its own header names — the parent is
- * authoritative even when its log is not part of this scan.
- * @param id - the session whose row is being attributed.
- * @param lineage - lineage of every session this scan saw, by id.
- * @returns the session id whose ranking row the input belongs to.
- */
-export function topLevelSessionOf(id, lineage) {
-    let current = id;
-    // A malformed log could claim a delegation cycle; each step visits a
-    // distinct ancestor, so a repeat ends the walk instead of spinning.
-    const seen = new Set([current]);
-    for (;;) {
-        const header = lineage.get(current);
-        if (!isSubagentSession(header))
-            return current;
-        const parent = header?.parentSession;
-        if (parent === undefined || seen.has(parent))
-            return current;
-        seen.add(parent);
-        current = parent;
-    }
-}
-/**
- * Fold every subagent child's row into the top-level row it belongs to
- * ({@link topLevelSessionOf}), so the ranking lists conversations rather than
- * every delegation a conversation started. A child's spend is added to its
- * ancestor's `total`; the ancestor's `ownTotal` keeps its own spend only. A
- * top-level session whose own day was empty but whose subagents priced
- * something still gets a row (with `ownTotal` 0), carrying the title the scan
- * resolved for it in `titles`.
- * @param rows - one row per session that priced something today (own spends).
- * @param lineage - lineage of every session this scan saw, by id.
- * @param titles - resolved display titles by session id; a session absent from
- *   the map has no resolved title and its created row reports `null`.
- * @returns the merged rows, sorted by `total` descending.
- */
-export function rollUpSubagentSpend(rows, lineage, titles = new Map()) {
-    const merged = new Map();
-    for (const row of rows) {
-        const target = topLevelSessionOf(row.sessionId, lineage);
-        const carried = merged.get(target);
-        if (carried === undefined) {
-            // A row's own session keeps its own total as `ownTotal`; a row created
-            // for an ancestor that priced nothing today carries zero there.
-            merged.set(target, target === row.sessionId
-                ? row
-                : { sessionId: target, title: titles.get(target) ?? null, total: row.total, ownTotal: 0 });
-            continue;
-        }
-        merged.set(target, { ...carried, total: carried.total + row.total });
-    }
-    return [...merged.values()].sort((left, right) => right.total - left.total);
-}
-/**
- * Read one live session's complete event log across both runtime families.
- * @throws when the session exposes neither the legacy `events` snapshot nor
- *   the newer `snapshotEvents()` reader — an unknown runtime surface must
- *   fail loudly rather than silently price an empty log.
- */
-export function liveSessionEvents(session) {
-    if (session.events !== undefined)
-        return session.events;
-    // Optional-call form keeps the receiver bound (snapshotEvents uses `this`).
-    if (session.snapshotEvents !== undefined)
-        return session.snapshotEvents();
-    throw new Error('llm-billing: session log surface is neither Session.events nor Session.snapshotEvents');
-}
-/**
- * Unwrap a handle read across both return shapes.
- * @param read - the handle's read result.
- * @returns the event array.
- */
-export function handleReadEvents(read) {
-    // `Array.isArray` does not narrow readonly arrays out of a union, so the
-    // branches are asserted explicitly.
-    if (Array.isArray(read))
-        return read;
-    return read.events;
-}
-function isHandlePersistence(persistence) {
-    return typeof persistence.open === 'function';
-}
-/**
- * List every stored session snapshot across both persistence runtime families:
- * `listSnapshots` (≤ 0.1.1-rc.2) or `list` (0.1.2-alpha.5+).
- * @param persistence - the persistence service slice.
- * @returns one snapshot per stored session.
- */
-export function persistenceListSnapshots(persistence) {
-    return isHandlePersistence(persistence)
-        ? persistence.list()
-        : persistence.listSnapshots();
-}
-/**
- * Read one stored session's complete event log and durable inherited boundary
- * across both persistence runtime families: legacy `inspect` (≤ 0.1.1-rc.2)
- * or `open` + handle `read` (0.1.2-alpha.5+; the handle is closed after the
- * read). Both throw when the session does not exist.
- * @param persistence - the persistence service slice.
- * @param id - the stored session to read.
- * @returns the session's complete event log plus its inherited-prefix boundary.
- */
-export async function persistenceInspect(persistence, id) {
-    if (isHandlePersistence(persistence)) {
-        const handle = await persistence.open(id, 'read');
-        try {
-            return { events: handleReadEvents(await handle.read()), seedLength: forkBoundaryOf(handle) };
-        }
-        finally {
-            await handle.close();
-        }
-    }
-    const inspection = await persistence.inspect(id);
-    return { events: inspection.events, seedLength: forkBoundaryOf(inspection) };
-}
-/**
- * Bounded parallel fan-out: run `run` over `items` with at most `limit` in
- * flight. A shared index counter hands each worker its next job, so the
- * dispatch is O(n) overall (array `shift()` would be O(n) per pop).
- */
-async function withConcurrency(items, limit, run) {
-    const total = items.length;
-    let next = 0;
-    await Promise.all(Array.from({ length: Math.min(limit, total) }, async () => {
-        for (let job = next; job < total; job = next) {
-            next += 1;
-            await run(items[job]);
-        }
-    }));
-}
-/**
- * The A1 cache: one Beijing-day key + a 60s window, an in-flight promise that
- * coalesces concurrent misses, and a `force` bypass for the manual refresh
- * path. Cross-day invalidation is automatic (the day key changes); a failed
- * scan leaves the previous value in place and retries on the next call.
- * @typeParam T - the cached aggregate's value shape (the spend or its
- *   per-session breakdown).
- */
-export class TodaySpendCache {
-    scan;
-    ttlMs;
-    now;
-    cachedDayKey;
-    cachedValue;
-    cachedAt = 0;
-    inFlight;
-    /**
-     * @param scan - the aggregate computation behind a miss.
-     * @param ttlMs - time window in milliseconds (default 60 000).
-     * @param now - clock source (injectable for tests).
-     */
-    constructor(scan, ttlMs = 60_000, now = () => new Date()) {
-        this.scan = scan;
-        this.ttlMs = ttlMs;
-        this.now = now;
-    }
-    /**
-     * Read today's spend, cached per Beijing day within the TTL window.
-     * @param force - bypass the time window (manual refresh); the day-key gate
-     *   and the in-flight coalescing still apply to non-force callers.
-     * @returns today's spend.
-     */
-    get(force = false) {
-        const now = this.now();
-        const dayKey = beijingDayKey(now);
-        if (!force && this.cachedDayKey === dayKey && this.cachedValue !== undefined
-            && now.getTime() - this.cachedAt < this.ttlMs) {
-            return Promise.resolve(this.cachedValue);
-        }
-        // A scan already in flight is fresh by definition, so a forced caller
-        // joins it instead of starting a second pass.
-        if (this.inFlight !== undefined)
-            return this.inFlight;
-        const run = (async () => {
-            try {
-                const value = await this.scan(dayKey);
-                this.cachedDayKey = dayKey;
-                this.cachedValue = value;
-                this.cachedAt = now.getTime();
-                return value;
-            }
-            finally {
-                this.inFlight = undefined;
-            }
-        })();
-        this.inFlight = run;
-        return run;
-    }
-}
-/** Max session-ids kept in the scanner's cold-resolution cache before eviction. */
-export const COLD_RESOLVE_CACHE_LIMIT = 1024;
-/** Max session-ids kept in the scanner's cold-failure cache before eviction. */
-export const COLD_FAILED_CACHE_LIMIT = 1024;
-/** Bounded parallel fan-out for cold-session resolution. */
-export const COLD_RESOLVE_CONCURRENCY = 8;
+import { foldSessionTitle, isSubagentSession, rollUpSubagentSpend } from "./session-lineage.js";
+import { COLD_FAILED_CACHE_LIMIT, COLD_FAILED_RETRY_MS, COLD_RESOLVE_CACHE_LIMIT, COLD_RESOLVE_CONCURRENCY, SCAN_YIELD_SESSIONS, withConcurrency, yieldToEventLoop } from "./cache.js";
+import { liveSessionEvents, persistenceInspect, persistenceListSnapshots } from "./persistence.js";
+// Re-exported so the package's import surface is unchanged: these names were
+// declared here before the module was split.
+export * from "./session-lineage.js";
+export * from "./persistence.js";
+export * from "./cache.js";
 /**
  * Bounded-map eviction: drop the oldest inserted entry once `size` reached
  * `limit`. Evicting one entry (instead of clearing) keeps the other sessions'
@@ -367,7 +138,12 @@ export class TodaySpendScanner {
      * from the aggregate and the ranking on every scan after the first.
      */
     coldResolved = new Map();
-    /** Cold sessions whose resolution failed: id → revision (retried only when the log changes). */
+    /**
+     * Cold sessions whose resolution failed, id → the revision it failed at plus
+     * when. Keyed by revision too, so an unchanged log is not re-read every scan,
+     * but the retry is TIME-boxed: a purely revision-keyed failure would hide a
+     * session permanently when its log never changes again.
+     */
     coldFailed = new Map();
     constructor(deps) {
         this.deps = deps;
@@ -410,7 +186,10 @@ export class TodaySpendScanner {
      * otherwise.
      *
      * The aggregate sums every priced session, subagents included — the ranking's
-     * subagent roll-up only regroups rows, so neither total moves.
+     * subagent roll-up only regroups rows, so neither total moves. Both paths
+     * fold in slices and hand the host's event loop back every
+     * {@link SCAN_YIELD_SESSIONS} sessions, so a long scan never starves the
+     * GUI's own round trips.
      * @param dayKey - the Beijing-time calendar-day key to aggregate.
      * @returns the aggregate plus per-session rows sorted by cost descending.
      */
@@ -427,14 +206,14 @@ export class TodaySpendScanner {
      * own latest priced day is NOT the queried day: the row then proves the
      * session contributed nothing to the queried day, so the log is never read.
      * When the row IS the queried day (or no usable row exists) the session is
-     * inspected and folded locally, because the row may trail the log (a crash
+     * opened and folded locally, because the row may trail the log (a crash
      * between the last checkpoint and the session's last event).
      *
      * A cache-served value carries no title (the ladder only stores projection
      * values), so such rows report `title: null`. A SEEDED session (fork child)
      * skips the cache entirely: its cached row was folded over the inherited
-     * prefix too, so it always detaches through inspect with the durable
-     * boundary (the inspect result's inherited count or `meta.seedLength`,
+     * prefix too, so it always detaches through a handle read with the durable
+     * boundary (the handle's `inheritedEventCount` or `header.seedLength`,
      * depending on the runtime family) applied to the local fold.
      * @param header - the listed session header (the cache identity witness).
      * @param seeded - whether the session carries a fork-inherited prefix.
@@ -508,11 +287,23 @@ export class TodaySpendScanner {
                 adopt(header.id, resolved);
                 continue;
             }
-            if (this.coldFailed.get(header.id) === revision)
+            // Skipped while the SAME revision is still inside its retry window; once
+            // the window lapses the read is attempted again even though nothing
+            // changed, which is what rescues a transient failure.
+            const failed = this.coldFailed.get(header.id);
+            if (failed !== undefined && failed.revision === revision
+                && Date.now() - failed.at < COLD_FAILED_RETRY_MS)
                 continue;
             pending.push({ header, revision, seeded });
         }
+        let resolvedCount = 0;
         await withConcurrency(pending, COLD_RESOLVE_CONCURRENCY, async ({ header, revision, seeded }) => {
+            // A resolution answered straight from the projection cache performs no
+            // I/O, so without this the fan-out would run a long microtask chain that
+            // never reaches the event loop's poll phase.
+            resolvedCount += 1;
+            if (resolvedCount % SCAN_YIELD_SESSIONS === 0)
+                await yieldToEventLoop();
             const resolved = await this.resolveCold(header, seeded, dayKey);
             if (resolved !== undefined) {
                 this.coldFailed.delete(header.id);
@@ -520,10 +311,16 @@ export class TodaySpendScanner {
             }
             else if (persistenceAvailable) {
                 evictOldest(this.coldFailed, COLD_FAILED_CACHE_LIMIT);
-                this.coldFailed.set(header.id, revision);
+                this.coldFailed.set(header.id, { revision, at: Date.now() });
             }
         });
+        let adopted = 0;
         for (const { header } of pending) {
+            // The adopt below merges synchronously; a day with many cold sessions
+            // must not fold them all in one uninterrupted slice.
+            adopted += 1;
+            if (adopted % SCAN_YIELD_SESSIONS === 0)
+                await yieldToEventLoop();
             const resolved = this.coldResolved.get(header.id);
             if (resolved !== undefined)
                 adopt(header.id, resolved);
@@ -550,6 +347,14 @@ export class TodaySpendScanner {
         const liveIds = new Set();
         let collected = 0;
         let truncated = false;
+        // The queried day as numbers — one conversion per scan instead of a date
+        // string per event, since the counting below walks every event of every
+        // log. A key that does not parse falls back to the string test rather than
+        // silently claiming no event belongs to the day.
+        const dayRange = beijingDayRangeOfKey(dayKey);
+        const onDay = dayRange === undefined
+            ? (event) => beijingPartsOf(event.time).dayKey === dayKey
+            : (event) => event.time >= dayRange.start && event.time < dayRange.end;
         /** Price one complete log, announce it, and return what to remember. */
         const collect = (id, events, seedLength, lineage) => {
             const folder = new BillingFolder(billing, catalog, seedLength);
@@ -557,7 +362,7 @@ export class TodaySpendScanner {
                 // The cap counts the queried day's events; the fold still sees every
                 // event up to the cap (model tracking and attempt replacement need
                 // the surrounding events).
-                if (beijingPartsOf(event.time).dayKey === dayKey) {
+                if (onDay(event)) {
                     collected += 1;
                     if (collected > maxEvents) {
                         truncated = true;
@@ -574,7 +379,14 @@ export class TodaySpendScanner {
         if (sessions !== undefined) {
             const store = sessions();
             if (store !== undefined) {
+                let folded = 0;
                 for (const session of store.list()) {
+                    // The fold below walks this session's whole log synchronously on the
+                    // host's main loop; hand the loop back every few sessions so the GUI's
+                    // own round trips still get served during a long scan.
+                    folded += 1;
+                    if (folded % SCAN_YIELD_SESSIONS === 0)
+                        await yieldToEventLoop();
                     liveIds.add(session.id);
                     collect(session.id, liveSessionEvents(session), forkBoundaryOf(session), session.header ?? {});
                     if (truncated)
@@ -618,7 +430,7 @@ export class TodaySpendScanner {
     /**
      * Projection path, one pass for both outputs: eager cells for live sessions
      * (title folded from the live log, so a rename is reflected immediately),
-     * revision-gated cold ladder for the rest (title resolved on inspect, `null`
+     * revision-gated cold ladder for the rest (title resolved on the handle read, `null`
      * when answered from the projection cache). A fork child's cell covers its
      * inherited prefix, so its own-events fold supplies both outputs. Lineage
      * (which session delegated which) comes from the same headers the boundary
@@ -640,7 +452,14 @@ export class TodaySpendScanner {
         if (sessions !== undefined) {
             const store = sessions();
             if (store !== undefined) {
+                let folded = 0;
                 for (const { session, state } of this.liveBillingEntries(store, projectionsService)) {
+                    // The title fold below materialises and walks this session's whole
+                    // log synchronously on the host's main loop; hand the loop back every
+                    // few sessions so the GUI's own round trips still get served.
+                    folded += 1;
+                    if (folded % SCAN_YIELD_SESSIONS === 0)
+                        await yieldToEventLoop();
                     liveIds.add(session.id);
                     lineage.set(session.id, session.header ?? {});
                     const born = session.header?.createdAt;

package/lib/types/types.d.ts

@@ -65,6 +65,26 @@ export interface DeepSeekSessionSpend {
     total: number;
     /** One row per model that reported usage AND has a pricing row; empty when the session has no priced usage. */
     models: readonly DeepSeekSessionSpendModel[];
+    /**
+     * Samples that carried usage but have NO pricing row, and so contribute
+     * nothing to {@link total} — so a session that only ever used an unlisted
+     * model does not read as "no usage" beside a today row that says otherwise.
+     */
+    unpriced?: DeepSeekUnpricedUsage | undefined;
+}
+/**
+ * Provider-reported usage that could NOT be billed: it matched no pricing row,
+ * and no rate is ever guessed from a similar-looking model id. Purely advisory
+ * — it never changes a spend's `total`, and the whole field is omitted when
+ * every sample was priced against its own row.
+ */
+export interface DeepSeekUnpricedUsage {
+    /** Number of usage samples affected. */
+    events: number;
+    /** Token count affected: input + cache read + cache write + output tokens. */
+    tokens: number;
+    /** The wire model ids affected, in first-seen order. */
+    models: readonly string[];
 }
 /** The billed spend of every session on one Beijing-time calendar day. */
 export interface DeepSeekTodaySpend {
@@ -72,6 +92,14 @@ export interface DeepSeekTodaySpend {
     total: number;
     /** One row per model that reported usage AND has a pricing row; empty when today has no priced usage. */
     models: readonly DeepSeekSessionSpendModel[];
+    /**
+     * Samples that carried usage but have NO pricing row, and so contribute
+     * nothing to {@link total}. Without this, an upstream model that ships before
+     * its rate row reads exactly like "no usage" (see MiMo-V2.6, which arrived
+     * before the table knew it) — the difference is what this field exists to
+     * report. Add the row under `billing.models` to price these.
+     */
+    unpriced?: DeepSeekUnpricedUsage | undefined;
 }
 /** One session's billed spend on one Beijing-time calendar day. */
 export interface DeepSeekTodaySessionSpend {

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Billing Core",
+    "description": "DeepSeek account balance and session/today spend behind the billing Remote (peak/off-peak pricing)."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "计费核心",
+    "description": "余额、峰谷计价与会话/今日花费（billing Remote 提供方）。"
+  }
+}

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@rayadesu/dsh-llm-billing",
   "description": "Standalone DeepSeek account-balance and session-spend provider exposed through the billing Remote",
-  "version": "0.3.16",
+  "icon": "./icon.svg",
+  "version": "0.3.17",
   "publishConfig": {
     "access": "public"
   },
@@ -39,9 +40,12 @@
       "default": "./lib/typert.remote-client.js"
     },
     "./src/*": "./src/*",
+    "./locale/*.json": "./locale/*.json",
     "./package.json": "./package.json"
   },
   "files": [
+    "locale/*.json",
+    "icon.svg",
     "lib/index.js",
     "lib/invariant.js",
     "lib/types/**/*.js",