@rayadesu/dsh-llm-billing 0.3.12 → 0.3.13

package/lib/types/today-spend.d.ts

@@ -13,13 +13,23 @@
  *   every 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.
+ *   adopting the fold it already priced for a session whose persisted revision
+ *   is unchanged since the last pass.
  *
  * Both strategies run behind the same {@link TodaySpendCache}, so a miss
  * happens at most once per 60 seconds per process, and a manual refresh
  * (`force`) bypasses the time window but keeps the revision caches — an
- * unchanged log provably cannot change the aggregate.
+ * unchanged log provably cannot change the aggregate. That proof is what makes
+ * a revision gate a CACHE: both strategies therefore adopt the resolution they
+ * remember for an unchanged revision instead of skipping the session, so an
+ * unchanged log costs no I/O and still contributes its full spend (and title)
+ * to the aggregate and the ranking on every scan.
+ *
+ * The per-session ranking is a per-CONVERSATION ranking: a subagent child is
+ * work the delegating conversation paid for, not a session the user opened, so
+ * every subagent row is folded into the row of the top-level session at the
+ * root of its `parentSession` chain (see {@link rollUpSubagentSpend}). The
+ * aggregate is unaffected — it sums the same sessions either way.
  *
  * Forked sessions never double-count: a fork child's log opens with a
  * verbatim copy of its source session's events (its inherited boundary), so
@@ -44,6 +54,7 @@
 import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session';
 import type { SessionPersistenceRevision } from '@deepseek-ai/dsh-session-persistence';
 import type { ResolvedBilling } from './billing.ts';
+import type { BillingFoldState } from './billing.ts';
 import type { DeepSeekTodaySessionSpend, DeepSeekTodaySessionsSpend, DeepSeekTodaySpend } from './types.ts';
 import { BILLING_UNIT_KEY, type BillingUnitFold, type BillingUnitState } from './projection.ts';
 /**
@@ -55,6 +66,77 @@ import { BILLING_UNIT_KEY, type BillingUnitFold, type BillingUnitState } from '.
  * @returns the session's current title, or `null` when untitled.
  */
 export declare function foldSessionTitle(events: readonly SessionEvent[]): string | null;
+/**
+ * Structural slice of a session's durable lineage: the header fields DSH
+ * stamps on a delegation child (`origin: 'subagent'`, the delegating session's
+ * id, and the depth that survives persistence). All three are read
+ * structurally, so the scanner works on every runtime family — a log written
+ * before the fields existed simply carries none of them and reads as a
+ * top-level session.
+ */
+export interface SessionLineage {
+    /** The session this one was forked from or delegated by; absent for a top-level session. */
+    readonly parentSession?: SessionId;
+    /** DSH's subagent-child classification (`childSessionMeta` stamps it). */
+    readonly origin?: 'subagent';
+    /** Delegation depth: absent (zero) at the top level, parent depth + 1 for a subagent child. */
+    readonly delegationDepth?: number;
+}
+/**
+ * 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 declare function isSubagentSession(header: SessionLineage | undefined): boolean;
+/**
+ * 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 declare function topLevelSessionOf(id: SessionId, lineage: ReadonlyMap<SessionId, SessionLineage>): SessionId;
+/**
+ * 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 declare function rollUpSubagentSpend(rows: readonly DeepSeekTodaySessionSpend[], lineage: ReadonlyMap<SessionId, SessionLineage>, titles?: ReadonlyMap<SessionId, string | null>): DeepSeekTodaySessionSpend[];
+/**
+ * Structural slice of a live session's header: the fork boundary of both DSH
+ * runtime families plus the delegation lineage the ranking roll-up reads.
+ */
+export interface SessionHeaderSlice extends SessionLineage {
+    /** ≤ 0.1.1-rc.2: the durable fork boundary carried by the header; absent for an unseeded session. */
+    readonly seedLength?: number;
+    /** 0.1.2-alpha.4+: whether the session has a fork-inherited prefix. */
+    readonly isSeeded?: boolean;
+    /**
+     * Durable creation instant (epoch ms). The conversation read uses it to tell
+     * whether a session's spend can span more than the queried day; it is also
+     * part of the projection-cache record identity.
+     */
+    readonly createdAt?: number;
+}
 /**
  * Structural slice of a live session the scanner reads, accepting both DSH
  * runtime families: the ≤ 0.1.1-rc.2 baseline exposes the log as
@@ -69,11 +151,8 @@ export interface ScannerSession {
     snapshotEvents?(fromSeq?: number, toSeqExclusive?: number): readonly SessionEvent[];
     /** 0.1.2-alpha.4+: the durable inherited-prefix length (0 for an unseeded session). */
     readonly inheritedEventCount?: number;
-    /** Durable header slice: `seedLength` (older runtime) or `isSeeded` (newer runtime). */
-    readonly header?: {
-        readonly seedLength?: number;
-        readonly isSeeded?: boolean;
-    };
+    /** Durable header slice: `seedLength` (older runtime) or `isSeeded` (newer runtime), plus lineage. */
+    readonly header?: SessionHeaderSlice;
 }
 /**
  * Read one live session's complete event log across both runtime families.
@@ -83,16 +162,10 @@ export interface ScannerSession {
  */
 export declare function liveSessionEvents(session: ScannerSession): readonly SessionEvent[];
 /** Structural slice of a listed persisted session (the snapshot header is a full SessionHeader). */
-export interface ScannerPersistedHeader {
+export interface ScannerPersistedHeader extends SessionHeaderSlice {
     readonly id: SessionId;
-    /** ≤ 0.1.1-rc.2: the durable fork boundary carried by the snapshot header; absent for an unseeded session. */
-    readonly seedLength?: number;
-    /** 0.1.2-alpha.4+: whether the session has a fork-inherited prefix (exact cut arrives with the inspect result). */
-    readonly isSeeded?: boolean;
     /** Session format generation; part of the projection-cache record identity. */
     readonly version?: number;
-    /** Session creation time; part of the projection-cache record identity. */
-    readonly createdAt?: number;
     /** Working directory recorded on the header; part of the projection-cache record identity. */
     readonly cwd?: string;
 }
@@ -109,10 +182,7 @@ export interface ScannerPersistenceLegacy {
         revision: SessionPersistenceRevision;
     }[]>;
     inspect(id: SessionId): Promise<{
-        meta?: {
-            readonly seedLength?: number;
-            readonly isSeeded?: boolean;
-        };
+        meta?: SessionHeaderSlice;
         /** 0.1.2-alpha.4+: the exact inherited cut travels beside, not inside, the header. */
         inheritedEventCount?: number;
         events: readonly SessionEvent[];
@@ -140,10 +210,7 @@ export interface ScannerPersistenceHandle {
         revision: SessionPersistenceRevision;
     }[]>;
     open(id: SessionId, access: 'read'): Promise<{
-        readonly header?: {
-            readonly seedLength?: number;
-            readonly isSeeded?: boolean;
-        };
+        readonly header?: SessionHeaderSlice;
         /** 0.1.2-alpha.5+: the handle carries the exact inherited cut beside the header. */
         readonly inheritedEventCount?: number;
         read(): Promise<ScannerHandleRead>;
@@ -264,22 +331,86 @@ export interface TodaySpendDetail {
     aggregate: DeepSeekTodaySpend;
     /** Today's per-session rows, sorted by cost descending. */
     sessions: DeepSeekTodaySessionSpend[];
+    /** The Beijing day this pass was computed for (the key its day filters used). */
+    dayKey: string;
+    /**
+     * WHOLE-session own spend of every session this pass priced, by id: all days
+     * the log covers, the fork prefix already excluded, subagents not yet merged.
+     * The ranking only reports the queried day, but the same fold carries the
+     * whole-session total, so a conversation read ({@link delegatedSpendOf}) costs
+     * no second scan.
+     */
+    ownSpend: ReadonlyMap<SessionId, DeepSeekTodaySpend>;
+    /** Lineage of every session this pass saw, by id: the delegation tree's shape. */
+    lineage: ReadonlyMap<SessionId, SessionLineage>;
+    /**
+     * Durable creation instant of every session this pass saw, by id (absent when
+     * the header carried none). The panel's today share is gated on the session
+     * having been created BEFORE the queried day, which this answers without
+     * another read.
+     */
+    createdAt: ReadonlyMap<SessionId, number>;
+}
+/**
+ * The merged whole-session spend of every subagent session delegated FROM one
+ * session, transitively: the subagent subtotal a conversation's own log cannot
+ * price. Only sessions DSH marked as delegation children count, so a user fork
+ * (which names a `parentSession` too) is never billed into its source. A
+ * malformed lineage that points back at the queried session is ignored rather
+ * than counted twice.
+ * @param id - the session whose delegated subtree to sum.
+ * @param ownSpend - whole-session own spend per session, from one scan pass.
+ * @param lineage - lineage per session, from the same pass.
+ * @returns the merged subtree spend; empty when the session delegated nothing priced.
+ */
+export declare function delegatedSpendOf(id: SessionId, ownSpend: ReadonlyMap<SessionId, DeepSeekTodaySpend>, lineage: ReadonlyMap<SessionId, SessionLineage>): DeepSeekTodaySpend;
+/**
+ * One cold session's resolution, as {@link TodaySpendScanner} remembers it: the
+ * persisted revision the resolution read, the session's OWN-events billing fold
+ * (its fork boundary already applied), and the display title folded from the
+ * same read. The revision is the adoption gate — a later scan adopts the entry
+ * only while the session's persisted revision is unchanged, which is exactly
+ * the proof that re-reading the log could not change the fold.
+ */
+export interface ColdResolution {
+    /** The persisted revision this resolution read. */
+    readonly revision: SessionPersistenceRevision;
+    /** The session's own-events fold (`BillingUnitState` names the same shape). */
+    readonly fold: BillingFoldState;
+    /** The session's display title from the same read; `null` when untitled or unresolved. */
+    readonly title: string | null;
 }
 /**
  * The aggregate computation behind a cache miss. Chooses the projection path
  * when the projection registry is composed, the events path otherwise; both
- * gate cold reads on persisted revisions so steady-state scans touch only
- * sessions whose logs actually changed.
+ * gate cold reads on persisted revisions AND adopt the fold they already hold
+ * for an unchanged log, so steady-state scans re-read only sessions whose logs
+ * actually changed while every unchanged session keeps contributing.
  */
 export declare class TodaySpendScanner {
     private readonly deps;
-    /** Cold sessions resolved on the projection path: id → revision + unit state + title. */
+    /**
+     * Cold sessions resolved by either strategy: id → the persisted revision the
+     * resolution saw, the session's OWN-events fold, and its folded title.
+     *
+     * The two strategies differ in how they PRICE a cold log (an eager projection
+     * cell plus the cache ladder, or a local fold over the read log), never in
+     * what an unchanged log contributes to the day — so one memory serves both.
+     * The projection path reuses the resolved unit; the events path reuses the
+     * fold it priced on the previous pass. A strategy that skipped an unchanged
+     * log WITHOUT adopting its remembered fold would silently drop that session
+     * from the aggregate and the ranking on every scan after the first.
+     */
     private readonly coldResolved;
     /** Cold sessions whose resolution failed: id → revision (retried only when the log changes). */
     private readonly coldFailed;
-    /** Cold sessions resolved on the events path: id → revision (events were collected). */
-    private lastEventsScan;
     constructor(deps: TodaySpendScannerDeps);
+    /**
+     * Remember one cold session's resolution, bounded by
+     * {@link COLD_RESOLVE_CACHE_LIMIT}: evicting the oldest entry (instead of
+     * clearing) keeps the other sessions' resolved state warm across scans.
+     */
+    private rememberCold;
     /**
      * Compute today's aggregate for one Beijing day.
      * @param dayKey - the Beijing-time calendar-day key to aggregate.
@@ -288,8 +419,11 @@ export declare class TodaySpendScanner {
     scan(dayKey: string): Promise<DeepSeekTodaySpend>;
     /**
      * 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.
+     * descending. One row per top-level session: sessions with no priced usage
+     * on the day are omitted (unless their subagents priced something, which the
+     * roll-up merges into their row), every subagent session is folded into the
+     * top-level session that delegated it, and 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.
      */
@@ -300,12 +434,15 @@ export declare class TodaySpendScanner {
      * read, unit fold, and title fold instead of scanning twice. Chooses the
      * projection path when the projection registry is composed, the events path
      * otherwise.
+     *
+     * The aggregate sums every priced session, subagents included — the ranking's
+     * subagent roll-up only regroups rows, so neither total moves.
      * @param dayKey - the Beijing-time calendar-day key to aggregate.
      * @returns the aggregate plus per-session rows sorted by cost descending.
      */
     scanDetail(dayKey: string): Promise<TodaySpendDetail>;
     /**
-     * Resolve one cold session's billing unit state and display title.
+     * Resolve one cold session's billing fold state and display title.
      *
      * The zero-I/O projection-cache row answers the query directly whenever its
      * own latest priced day is NOT the queried day: the row then proves the
@@ -323,7 +460,7 @@ export declare class TodaySpendScanner {
      * @param header - the listed session header (the cache identity witness).
      * @param seeded - whether the session carries a fork-inherited prefix.
      * @param dayKey - the Beijing-time day being aggregated.
-     * @returns the resolved state and title, or `undefined` when unreadable.
+     * @returns the resolved fold state and title, or `undefined` when unreadable.
      */
     private resolveCold;
     /**
@@ -336,11 +473,11 @@ export declare class TodaySpendScanner {
     /**
      * Cold-ladder adopt: for every stored session not live, either the
      * revision-gated resolution already in {@link coldResolved} is adopted
-     * (unchanged log costs nothing) or the session is queued behind a bounded
-     * parallel fan-out, resolved, remembered, and then adopted. A session whose
-     * resolution failed is remembered too (by revision), so an unreadable log
-     * is not re-read on every scan; a changed revision retries it. One
-     * unreadable session never blanks the whole-day aggregate.
+     * (unchanged log costs nothing and still counts) or the session is queued
+     * behind a bounded parallel fan-out, resolved, remembered, and then adopted.
+     * A session whose resolution failed is remembered too (by revision), so an
+     * unreadable log is not re-read on every scan; a changed revision retries it.
+     * One unreadable session never blanks the whole-day aggregate.
      * @param liveIds - ids of sessions already folded from the live store.
      * @param snapshots - stored snapshot list (either runtime family).
      * @param dayKey - the Beijing-time day being aggregated.
@@ -350,14 +487,17 @@ export declare class TodaySpendScanner {
     /**
      * Events-path collection shared by both aggregate and per-session scans:
      * fold each session's log with the shared pricing fold (attempt samples with
-     * same-step replacement) and announce the session's latest-day spend, gated
-     * by revisions — a persisted session whose log did not change since the last
-     * scan is skipped. A fork child's inherited prefix (`seq < seedLength`) is
-     * skipped, so each model output is priced only in its source session. The
-     * hard cap counts the queried day's events; the revision watermark only
-     * advances on a complete pass.
+     * same-step replacement) and announce the session's latest-day spend. A
+     * persisted session whose log did not change since it was last resolved is
+     * answered from {@link coldResolved} instead of being re-read: it keeps
+     * counting toward the aggregate and the ranking at zero cost, which is what
+     * makes the revision gate a cache rather than a way to lose sessions. A fork
+     * child's inherited prefix (`seq < seedLength`) is skipped, so each model
+     * output is priced only in its source session. The hard cap counts the
+     * queried day's events; a truncated pass remembers nothing it read, so the
+     * next one re-reads whatever this one cut short.
      * @param dayKey - the Beijing-time calendar-day key to aggregate.
-     * @param onSession - fold one session's state plus its complete log.
+     * @param onSession - adopt one session's fold, title, and lineage.
      * @returns whether the hard cap truncated the scan.
      */
     private collectTodayEvents;
@@ -366,18 +506,23 @@ export declare class TodaySpendScanner {
      * (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 answered from the projection cache). A fork child's cell covers its
-     * inherited prefix, so its own-events fold supplies both outputs.
+     * inherited prefix, so its own-events fold supplies both outputs. Lineage
+     * (which session delegated which) comes from the same headers the boundary
+     * does, so the ranking's subagent roll-up costs no extra read.
      * @param dayKey - the Beijing-time calendar-day key to aggregate.
      * @returns the aggregate plus per-session rows, sorted by cost descending.
      */
     private scanDetailProjections;
     /**
      * Events path, one pass for both outputs: price today's events (per-event
-     * Beijing-day filter during collection, hard cap), gated by revisions. A
+     * Beijing-day filter during collection, hard cap), revision-gated so an
+     * unchanged log is adopted from {@link coldResolved} instead of re-read. A
      * fork child's inherited prefix (`seq < seedLength`) is skipped, so each
      * model output is priced only in its source session. 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.
+     * rename is reflected as soon as the session's log is re-read, and an
+     * unchanged session keeps the title its earlier read folded. Lineage comes
+     * from the same headers, which the ranking roll-up needs.
      * @param dayKey - the Beijing-time calendar-day key to aggregate.
      * @returns the aggregate plus per-session rows, sorted by cost descending.
      */