@rayadesu/dsh-llm-billing 0.2.3 → 0.2.4

package/lib/types/today-spend.js

@@ -22,6 +22,27 @@
  */
 import { beijingDayKey, emptyTodaySpend, mergeTodaySpend, priceEvent, SpendAccumulator } from "./billing.js";
 import { BILLING_UNIT_KEY, foldBillingUnit } 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;
+}
 /**
  * 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
@@ -42,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;
@@ -52,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;
@@ -101,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;
@@ -119,12 +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?.();
-        const cache = projectionCache?.();
         let total = emptyTodaySpend();
         const liveIds = new Set();
         if (sessions !== undefined) {
@@ -156,27 +227,9 @@ export class TodaySpendScanner {
             pending.push({ id: header.id, revision });
         }
         await withConcurrency(pending, 8, async ({ id, revision }) => {
-            let value;
-            if (cache !== undefined) {
-                try {
-                    value = (await cache.coldSnapshot(id)).values[BILLING_UNIT_KEY];
-                }
-                catch (error) {
-                    logger.warn(`llm-billing: projection cold read for session ${id} failed: ${String(error)}`);
-                }
-            }
-            if (value === undefined) {
-                try {
-                    const inspection = await persistenceService.inspect(id);
-                    value = foldBillingUnit(unit, inspection.events);
-                }
-                catch (error) {
-                    // One unreadable session must not blank the whole-day aggregate.
-                    logger.warn(`llm-billing: skipping unreadable session ${id}: ${String(error)}`);
-                }
-            }
-            if (value !== undefined)
-                this.coldResolved.set(id, { revision, value });
+            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);
@@ -251,5 +304,141 @@ export class TodaySpendScanner {
             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,
+                        });
+                    }
+                }
+            }
+        }
+        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) {
+                rows.set(id, { sessionId: id, title: resolved.title, total: resolved.value.spend.total });
+            }
+        }
+        return [...rows.values()];
+    }
+    /**
+     * 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 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);
+                    collect(session.id, session.events);
+                    if (truncated)
+                        break;
+                }
+            }
+        }
+        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 {
+                    collect(header.id, (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 ${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 [...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.3",
+  "version": "0.2.4",
   "publishConfig": {
     "access": "public"
   },