@rayadesu/dsh-llm-billing 0.2.2 → 0.2.4

package/lib/types/today-spend.js

@@ -9,9 +9,10 @@
  *   with write-back) or, without the cache service, one detached local fold
  *   over a full `inspect`. Persisted revisions gate every cold read, so a
  *   session whose log did not change since the last resolution costs nothing.
- * - events path (plans A2/A3): collect only today's events (per-event
- *   Beijing-day filter during collection) with a hard cap, skipping sessions
- *   whose persisted revision is unchanged since the last scan.
+ * - events path (plans A2/A3): collect and price only today's events in one
+ *   pass (per-event Beijing-day filter during collection) with a hard cap,
+ *   skipping sessions whose persisted revision is unchanged since the last
+ *   scan.
  *
  * Both strategies run behind the same {@link TodaySpendCache}, so a miss
  * happens at most once per 60 seconds per process, and a manual refresh
@@ -19,14 +20,42 @@
  * unchanged log provably cannot change the aggregate.
  * @module @rayadesu/dsh-llm-billing/today-spend
  */
-import { beijingDayKey, computeTodaySpend, emptyTodaySpend, mergeTodaySpend } from "./billing.js";
+import { beijingDayKey, emptyTodaySpend, mergeTodaySpend, priceEvent, SpendAccumulator } from "./billing.js";
 import { BILLING_UNIT_KEY, foldBillingUnit } from "./projection.js";
-/** Bounded parallel fan-out: run `run` over `items` with at most `limit` in flight. */
+/**
+ * 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;
+}
+/**
+ * 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 queue = [...items];
-    await Promise.all(Array.from({ length: Math.min(limit, queue.length) }, async () => {
-        for (let job = queue.shift(); job !== undefined; job = queue.shift())
-            await run(job);
+    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]);
+        }
     }));
 }
 /**
@@ -34,6 +63,8 @@ async function withConcurrency(items, limit, run) {
  * 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;
@@ -44,9 +75,9 @@ export class TodaySpendCache {
     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).
-     * @param scan - the aggregate computation behind a miss.
      */
     constructor(scan, ttlMs = 60_000, now = () => new Date()) {
         this.scan = scan;
@@ -93,7 +124,7 @@ export class TodaySpendCache {
  */
 export class TodaySpendScanner {
     deps;
-    /** Cold sessions resolved on the projection path: id → revision + unit state. */
+    /** Cold sessions resolved on the projection path: id → revision + unit state + title. */
     coldResolved = new Map();
     /** Cold sessions resolved on the events path: id → revision (events were collected). */
     lastEventsScan;
@@ -111,9 +142,60 @@ export class TodaySpendScanner {
         this.deps.ensureUnit?.();
         return this.scanProjections(dayKey);
     }
+    /**
+     * Compute today's per-session spend for one Beijing day, sorted by cost
+     * descending. Sessions with no priced usage on the day are omitted; each
+     * row carries the session's durable title folded from its log.
+     * @param dayKey - the Beijing-time calendar-day key to aggregate.
+     * @returns today's per-session rows, highest first.
+     */
+    async scanSessions(dayKey) {
+        const rows = this.deps.projections?.() === undefined
+            ? await this.scanSessionsEvents(dayKey)
+            : await this.scanSessionsProjections(dayKey);
+        rows.sort((left, right) => right.total - left.total);
+        return { sessions: rows };
+    }
+    /**
+     * Resolve one cold session's billing unit state and display title through
+     * the projection-cache ladder (cached row first, then a detached local
+     * fold over a full inspect). A cache-served value carries no title (the
+     * ladder only stores projection values), so such rows report `title: null`
+     * until the session is inspected again.
+     * @param id - the cold session's id.
+     * @returns the resolved state and title, or `undefined` when unreadable.
+     */
+    async resolveCold(id) {
+        const { persistence, projectionCache, unit, logger } = this.deps;
+        const cache = projectionCache?.();
+        if (cache !== undefined) {
+            try {
+                const value = (await cache.coldSnapshot(id)).values[BILLING_UNIT_KEY];
+                if (value !== undefined)
+                    return { value, title: null };
+            }
+            catch (error) {
+                logger.warn(`llm-billing: projection cold read for session ${id} failed: ${String(error)}`);
+            }
+        }
+        const persistenceService = persistence?.();
+        if (persistenceService === undefined)
+            return undefined;
+        try {
+            const inspection = await persistenceService.inspect(id);
+            return { value: foldBillingUnit(unit, inspection.events), title: foldSessionTitle(inspection.events) };
+        }
+        catch (error) {
+            // One unreadable session must not blank the whole-day aggregate.
+            logger.warn(`llm-billing: skipping unreadable session ${id}: ${String(error)}`);
+            return undefined;
+        }
+    }
     /** Projection path: eager cells for live sessions, revision-gated cold ladder for the rest. */
     async scanProjections(dayKey) {
-        const { sessions, persistence, projections, projectionCache, unit, logger } = this.deps;
+        const { sessions, persistence, projections } = this.deps;
+        // Services resolve once per scan, not per session / per cold task.
+        const projectionsService = projections?.();
         let total = emptyTodaySpend();
         const liveIds = new Set();
         if (sessions !== undefined) {
@@ -121,7 +203,7 @@ export class TodaySpendScanner {
             if (store !== undefined) {
                 for (const session of store.list()) {
                     liveIds.add(session.id);
-                    const state = projections?.()?.stateOf(session, BILLING_UNIT_KEY);
+                    const state = projectionsService?.stateOf(session, BILLING_UNIT_KEY);
                     if (state !== undefined && state.dayKey === dayKey) {
                         total = mergeTodaySpend(total, state.spend);
                     }
@@ -145,57 +227,183 @@ export class TodaySpendScanner {
             pending.push({ id: header.id, revision });
         }
         await withConcurrency(pending, 8, async ({ id, revision }) => {
-            let value;
-            const cache = projectionCache?.();
-            if (cache !== undefined) {
-                try {
-                    value = (await cache.coldSnapshot(id)).values[BILLING_UNIT_KEY];
+            const resolved = await this.resolveCold(id);
+            if (resolved !== undefined)
+                this.coldResolved.set(id, { revision, ...resolved });
+        });
+        for (const { id } of pending) {
+            const resolved = this.coldResolved.get(id);
+            if (resolved !== undefined && resolved.value.dayKey === dayKey) {
+                total = mergeTodaySpend(total, resolved.value.spend);
+            }
+        }
+        return total;
+    }
+    /**
+     * Events path: price today's events in a single pass (per-event Beijing-day
+     * filter during collection, hard cap), gated by revisions.
+     */
+    async scanEvents(dayKey) {
+        const { sessions, persistence, maxEvents, logger, billing, catalog } = this.deps;
+        const names = new Map(catalog.map(model => [model.id, model.name]));
+        const accumulator = new SpendAccumulator();
+        const liveIds = new Set();
+        let collected = 0;
+        let truncated = false;
+        const collect = (events) => {
+            for (const event of events) {
+                if (beijingDayKey(new Date(event.time)) !== dayKey)
+                    continue;
+                collected += 1;
+                if (collected > maxEvents) {
+                    truncated = true;
+                    return;
                 }
-                catch (error) {
-                    logger.warn(`llm-billing: projection cold read for session ${id} failed: ${String(error)}`);
+                const priced = priceEvent(event, billing, names);
+                if (priced !== undefined)
+                    accumulator.add(priced);
+            }
+        };
+        if (sessions !== undefined) {
+            const store = sessions();
+            if (store !== undefined) {
+                for (const session of store.list()) {
+                    liveIds.add(session.id);
+                    collect(session.events);
+                    if (truncated)
+                        break;
                 }
             }
-            if (value === undefined) {
+        }
+        const persistenceService = persistence?.();
+        if (!truncated && persistenceService !== undefined) {
+            const snapshots = await persistenceService.listSnapshots();
+            for (const { header, revision } of snapshots) {
+                if (liveIds.has(header.id))
+                    continue;
+                if (this.lastEventsScan?.get(header.id) === revision)
+                    continue;
                 try {
-                    const inspection = await persistenceService.inspect(id);
-                    value = foldBillingUnit(unit, inspection.events);
+                    collect((await persistenceService.inspect(header.id)).events);
                 }
                 catch (error) {
                     // One unreadable session must not blank the whole-day aggregate.
-                    logger.warn(`llm-billing: skipping unreadable session ${id}: ${String(error)}`);
+                    logger.warn(`llm-billing: skipping unreadable session ${header.id}: ${String(error)}`);
+                }
+                if (truncated)
+                    break;
+            }
+            // Only a complete pass may advance the revision watermark: a truncated
+            // pass left sessions unread, and recording them would skip their events
+            // on the next scan.
+            if (!truncated) {
+                this.lastEventsScan = new Map(snapshots.map(snapshot => [snapshot.header.id, snapshot.revision]));
+            }
+        }
+        if (truncated)
+            logger.warn(`llm-billing: today's events exceeded ${maxEvents}; result truncated`);
+        return accumulator.finish();
+    }
+    /**
+     * Projection-path per-session scan: 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` when served from the projection cache).
+     * @param dayKey - the Beijing-time calendar-day key to aggregate.
+     * @returns unsorted per-session rows for the day.
+     */
+    async scanSessionsProjections(dayKey) {
+        const { sessions, persistence, projections } = this.deps;
+        const projectionsService = projections?.();
+        const rows = new Map();
+        const liveIds = new Set();
+        if (sessions !== undefined) {
+            const store = sessions();
+            if (store !== undefined) {
+                for (const session of store.list()) {
+                    liveIds.add(session.id);
+                    const state = projectionsService?.stateOf(session, BILLING_UNIT_KEY);
+                    if (state !== undefined && state.dayKey === dayKey) {
+                        rows.set(session.id, {
+                            sessionId: session.id,
+                            title: foldSessionTitle(session.events),
+                            total: state.spend.total,
+                        });
+                    }
                 }
             }
-            if (value !== undefined)
-                this.coldResolved.set(id, { revision, value });
+        }
+        const persistenceService = persistence?.();
+        if (persistenceService === undefined)
+            return [...rows.values()];
+        const snapshots = await persistenceService.listSnapshots();
+        const pending = [];
+        for (const { header, revision } of snapshots) {
+            if (liveIds.has(header.id))
+                continue;
+            const resolved = this.coldResolved.get(header.id);
+            if (resolved !== undefined && resolved.revision === revision) {
+                if (resolved.value.dayKey === dayKey) {
+                    rows.set(header.id, { sessionId: header.id, title: resolved.title, total: resolved.value.spend.total });
+                }
+                continue;
+            }
+            pending.push({ id: header.id, revision });
+        }
+        await withConcurrency(pending, 8, async ({ id, revision }) => {
+            const resolved = await this.resolveCold(id);
+            if (resolved !== undefined)
+                this.coldResolved.set(id, { revision, ...resolved });
         });
         for (const { id } of pending) {
             const resolved = this.coldResolved.get(id);
             if (resolved !== undefined && resolved.value.dayKey === dayKey) {
-                total = mergeTodaySpend(total, resolved.value.spend);
+                rows.set(id, { sessionId: id, title: resolved.title, total: resolved.value.spend.total });
             }
         }
-        return total;
+        return [...rows.values()];
     }
-    /** Events path: collect only today's events (capped), gated by revisions. */
-    async scanEvents(dayKey) {
+    /**
+     * Events-path per-session scan: price today's events in a single pass,
+     * accumulating per session (per-event Beijing-day filter during collection,
+     * hard cap), gated by revisions. Titles fold from each session's complete
+     * log — a `session/title` event can predate today — so a rename is reflected
+     * as soon as the session's log is re-read.
+     * @param dayKey - the Beijing-time calendar-day key to aggregate.
+     * @returns unsorted per-session rows for the day.
+     */
+    async scanSessionsEvents(dayKey) {
         const { sessions, persistence, maxEvents, logger, billing, catalog } = this.deps;
-        const events = [];
+        const names = new Map(catalog.map(model => [model.id, model.name]));
+        const rows = new Map();
         const liveIds = new Set();
+        let collected = 0;
         let truncated = false;
+        const collect = (id, events) => {
+            let row = rows.get(id);
+            if (row === undefined) {
+                row = { title: foldSessionTitle(events), total: 0 };
+                rows.set(id, row);
+            }
+            for (const event of events) {
+                if (beijingDayKey(new Date(event.time)) !== dayKey)
+                    continue;
+                collected += 1;
+                if (collected > maxEvents) {
+                    truncated = true;
+                    return;
+                }
+                const priced = priceEvent(event, billing, names);
+                if (priced !== undefined)
+                    row.total += priced.cost;
+            }
+        };
         if (sessions !== undefined) {
             const store = sessions();
             if (store !== undefined) {
                 for (const session of store.list()) {
                     liveIds.add(session.id);
-                    for (const event of session.events) {
-                        if (beijingDayKey(new Date(event.time)) !== dayKey)
-                            continue;
-                        events.push(event);
-                        if (events.length >= maxEvents) {
-                            truncated = true;
-                            break;
-                        }
-                    }
+                    collect(session.id, session.events);
                     if (truncated)
                         break;
                 }
@@ -210,16 +418,7 @@ export class TodaySpendScanner {
                 if (this.lastEventsScan?.get(header.id) === revision)
                     continue;
                 try {
-                    const inspection = await persistenceService.inspect(header.id);
-                    for (const event of inspection.events) {
-                        if (beijingDayKey(new Date(event.time)) !== dayKey)
-                            continue;
-                        events.push(event);
-                        if (events.length >= maxEvents) {
-                            truncated = true;
-                            break;
-                        }
-                    }
+                    collect(header.id, (await persistenceService.inspect(header.id)).events);
                 }
                 catch (error) {
                     // One unreadable session must not blank the whole-day aggregate.
@@ -237,10 +436,9 @@ export class TodaySpendScanner {
         }
         if (truncated)
             logger.warn(`llm-billing: today's events exceeded ${maxEvents}; result truncated`);
-        // The reference moment is derived from the day key (UTC midnight on that
-        // date is 08:00 Beijing the same day), so the pricing re-check cannot
-        // drift from the collection filter across a Beijing-day boundary.
-        return computeTodaySpend(events, billing, catalog, new Date(`${dayKey}T00:00:00Z`));
+        return [...rows.entries()]
+            .filter(([, row]) => row.total > 0)
+            .map(([sessionId, row]) => ({ sessionId, title: row.title, total: row.total }));
     }
 }
 //# sourceMappingURL=today-spend.js.map

package/lib/types/types.d.ts

@@ -3,6 +3,7 @@
  * its generated artifacts, and the web UI.
  * @module @rayadesu/dsh-llm-billing/types
  */
+import type { SessionId } from '@deepseek-ai/dsh-session';
 /** One currency line of the account balance returned by `GET /user/balance`. */
 export interface DeepSeekBalanceLine {
     /** Currency code, e.g. `CNY` or `USD`. */
@@ -60,4 +61,26 @@ export interface DeepSeekTodaySpend {
     /** One row per model that reported usage AND has a pricing row; empty when today has no priced usage. */
     models: readonly DeepSeekSessionSpendModel[];
 }
+/** One session's billed spend on one Beijing-time calendar day, priced per event by its Beijing-time hour and weekday (peak hours apply Monday–Friday only; weekends are off-peak). */
+export interface DeepSeekTodaySessionSpend {
+    /** The session's durable identity. */
+    sessionId: SessionId;
+    /**
+     * The session's display title: the latest `session/title` event's text, or
+     * `null` when the session has no title (or the title could not be resolved).
+     */
+    title: string | null;
+    /** Billed cost in CNY on the queried Beijing day. */
+    total: number;
+}
+/** Today's per-session billed spend across every session with a non-zero cost. */
+export interface DeepSeekTodaySessionsSpend {
+    /** Sessions with today's spend, sorted by `total` descending. */
+    sessions: readonly DeepSeekTodaySessionSpend[];
+}
+/** The billed cost of one completed Turn, priced per event by its Beijing-time hour and weekday (peak hours apply Monday–Friday only; weekends are off-peak). */
+export interface DeepSeekTurnSpend {
+    /** Total billed cost in CNY across every priced model in the Turn. */
+    total: number;
+}
 //# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rayadesu/dsh-llm-billing",
   "description": "Standalone DeepSeek account-balance and session-spend provider exposed through the billing Remote",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "publishConfig": {
     "access": "public"
   },