dsh-token-bill 0.0.0-stage → 2.0.2

package/lib/fold.js

@@ -0,0 +1,281 @@
+/**
+ * The `dshTokenBill` session projection: a replay-stable fold of every billed
+ * model call in one Session log into token buckets, kept per route
+ * (provider + model) and per DeepSeek billing tier (peak / off-peak).
+ *
+ * The state holds tokens only. Prices are applied by the view (see
+ * `lib/pricing.js`), so a price edit re-prices every Session without
+ * re-folding its log, and a checkpoint stays valid across price changes.
+ */
+import { buildView, tierAt } from './pricing.js'
+
+/** Projection key; distinct from v1's `tokenCost` so both versions can coexist during an upgrade. */
+export const PROJECTION_KEY = 'dshTokenBill'
+
+/** Bump whenever the state shape or fold semantics change: stale checkpoints are then discarded. */
+export const STATE_VERSION = 2
+
+const FIELDS = Object.freeze(['input', 'cacheRead', 'cacheWrite', 'output', 'reasoning'])
+
+const UNKNOWN_ROUTE = Object.freeze({ provider: '', model: '' })
+
+/** @returns {object} an all-zero bucket set. */
+export function emptyBuckets() {
+  return { input: 0, cacheRead: 0, cacheWrite: 0, output: 0, reasoning: 0 }
+}
+
+function count(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.round(value) : 0
+}
+
+/**
+ * Bucket one provider usage sample. `inputTokens` is the uncached (cache-miss)
+ * prompt part, as the built-in token meter reads it; reasoning tokens are a
+ * subset of output and only reported for display.
+ * @param {object} usage - an LLM usage record.
+ * @returns {object} bucket set.
+ */
+export function bucketsFromUsage(usage) {
+  const output = count(usage.outputTokens)
+  return {
+    input: count(usage.inputTokens),
+    cacheRead: count(usage.cacheReadTokens),
+    cacheWrite: count(usage.cacheWriteTokens),
+    output,
+    reasoning: Math.min(count(usage.reasoningTokens), output),
+  }
+}
+
+function bucketsEqual(a, b) {
+  return FIELDS.every(field => a[field] === b[field])
+}
+
+function bucketsEmpty(buckets) {
+  return FIELDS.every(field => buckets[field] === 0)
+}
+
+function routeOf(provider, model) {
+  if (typeof model !== 'string' || model.length === 0) return undefined
+  return { provider: typeof provider === 'string' ? provider : '', model }
+}
+
+function sameRoute(a, b) {
+  return a != null && b != null && a.provider === b.provider && a.model === b.model
+}
+
+/**
+ * Add (`sign` = 1) or remove (`sign` = -1) one bucket set from a ledger without
+ * mutating it. An entry that drops to zero is removed.
+ * @param {ReadonlyArray<object>} ledger - route entries.
+ * @param {{ provider: string, model: string }} route - the call's route.
+ * @param {'peak' | 'offPeak'} tier - the call's billing tier.
+ * @param {object} buckets - the call's buckets.
+ * @param {1 | -1} sign - direction.
+ * @returns {ReadonlyArray<object>} the next ledger.
+ */
+export function ledgerAdd(ledger, route, tier, buckets, sign) {
+  if (bucketsEmpty(buckets)) return ledger
+  const index = ledger.findIndex(entry => sameRoute(entry, route))
+  if (index < 0 && sign < 0) return ledger
+  const base = index >= 0
+    ? ledger[index]
+    : { provider: route.provider, model: route.model, peak: emptyBuckets(), offPeak: emptyBuckets() }
+  const next = {}
+  for (const field of FIELDS) next[field] = Math.max(0, base[tier][field] + sign * buckets[field])
+  const entry = { ...base, [tier]: next }
+  if (index < 0) return [...ledger, entry]
+  if (bucketsEmpty(entry.peak) && bucketsEmpty(entry.offPeak)) return ledger.filter((_, i) => i !== index)
+  const copy = ledger.slice()
+  copy[index] = entry
+  return copy
+}
+
+/** The usage sample of one Assistant settlement, mirroring the built-in token meter. */
+function usageOf(event) {
+  const data = event.data
+  if (event.type === 'assistant/message' && data.usage != null) return data.usage
+  const stream = data.stream
+  if (!Array.isArray(stream)) return undefined
+  for (let index = stream.length - 1; index >= 0; index -= 1) {
+    const record = stream[index]
+    if (record != null && record.type === 'chunk' && record.chunk != null && record.chunk.type === 'usage') {
+      return record.chunk.usage
+    }
+  }
+  return undefined
+}
+
+/**
+ * Initial state. Events below `inheritedEventCount` were copied from the parent
+ * when this Session was forked; they were billed there, so they are not billed
+ * again here.
+ * @param {number} [inheritedEventCount] - fork-inherited cut.
+ * @returns {object} state.
+ */
+export function initialState(inheritedEventCount) {
+  return {
+    inherited: typeof inheritedEventCount === 'number' && inheritedEventCount > 0 ? inheritedEventCount : 0,
+    total: [],
+    compaction: [],
+    calls: 0,
+    compactions: 0,
+    turn: null,
+    turnNo: null,
+    last: null,
+    header: null,
+  }
+}
+
+function inherited(state, event) {
+  return typeof event.seq === 'number' && event.seq < state.inherited
+}
+
+/** One `assistant/attempt` or `assistant/message`: a billed model call, or the final sample of one. */
+function foldSettlement(state, event, tierOf) {
+  if (inherited(state, event)) return state
+  const data = event.data
+  const sample = usageOf(event)
+  if (typeof sample !== 'object' || sample === null) return state
+  const { turn, step } = data
+  if (typeof turn !== 'number' || typeof step !== 'number') return state
+
+  const source = event.type === 'assistant/message' && data.message != null ? data.message.source : undefined
+  const route = (source != null ? routeOf(source.provider, source.model) : undefined) ?? state.header ?? UNKNOWN_ROUTE
+  const tier = tierOf(event.time)
+  const buckets = bucketsFromUsage(sample)
+
+  // A final message sample replaces the streaming sample of the same attempt;
+  // `llm/retry-started` closes that slot, so a retried attempt adds instead.
+  const previous = state.last !== null && state.last.turn === turn && state.last.step === step ? state.last : null
+  if (previous !== null && previous.tier === tier && sameRoute(previous.route, route) && bucketsEqual(previous.buckets, buckets)) {
+    return state
+  }
+
+  let total = state.total
+  let current = state.turn !== null && state.turn.no === turn ? state.turn.ledger : []
+  if (previous !== null) {
+    total = ledgerAdd(total, previous.route, previous.tier, previous.buckets, -1)
+    current = ledgerAdd(current, previous.route, previous.tier, previous.buckets, -1)
+  }
+  return {
+    ...state,
+    total: ledgerAdd(total, route, tier, buckets, 1),
+    turn: { no: turn, ledger: ledgerAdd(current, route, tier, buckets, 1) },
+    calls: previous === null ? state.calls + 1 : state.calls,
+    last: { turn, step, route: { provider: route.provider, model: route.model }, tier, buckets },
+  }
+}
+
+/** One `compaction/summary`: the summarizer's own model call, which the built-in meter does not count. */
+function foldCompaction(state, event, tierOf) {
+  if (inherited(state, event)) return state
+  const data = event.data
+  if (typeof data.usage !== 'object' || data.usage === null) return state
+  const buckets = bucketsFromUsage(data.usage)
+  if (bucketsEmpty(buckets)) return state
+  const route = routeOf(data.provider, data.model) ?? state.header ?? UNKNOWN_ROUTE
+  const tier = tierOf(event.time)
+  const no = typeof state.turnNo === 'number' ? state.turnNo : state.turn !== null ? state.turn.no : 0
+  const current = state.turn !== null && state.turn.no === no ? state.turn.ledger : []
+  return {
+    ...state,
+    total: ledgerAdd(state.total, route, tier, buckets, 1),
+    compaction: ledgerAdd(state.compaction, route, tier, buckets, 1),
+    compactions: state.compactions + 1,
+    turn: { no, ledger: ledgerAdd(current, route, tier, buckets, 1) },
+  }
+}
+
+/**
+ * Fold one committed Session event. Returns the same reference for events
+ * that do not concern this unit, as the registry requires.
+ * @param {object} state - current state.
+ * @param {object} event - committed Session event.
+ * @param {(time: number) => 'peak' | 'offPeak'} tierOf - billing tier classifier.
+ * @returns {object} next state.
+ */
+export function foldEvent(state, event, tierOf) {
+  const data = event.data
+  if (typeof data !== 'object' || data === null) return state
+  switch (event.type) {
+    case 'request/header': {
+      const config = data.header != null ? data.header.config : undefined
+      const route = config != null ? routeOf(config.provider, config.model) : undefined
+      return route === undefined || sameRoute(route, state.header) ? state : { ...state, header: route }
+    }
+    case 'turn/start':
+      return typeof data.turn !== 'number' || data.turn === state.turnNo ? state : { ...state, turnNo: data.turn }
+    case 'llm/retry-started':
+      return state.last !== null && state.last.turn === data.turn && state.last.step === data.step
+        ? { ...state, last: null }
+        : state
+    case 'assistant/attempt':
+    case 'assistant/message':
+      return foldSettlement(state, event, tierOf)
+    case 'compaction/summary':
+      return foldCompaction(state, event, tierOf)
+    default:
+      return state
+  }
+}
+
+function isCount(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0
+}
+
+function isBuckets(value) {
+  return typeof value === 'object' && value !== null && FIELDS.every(field => isCount(value[field]))
+}
+
+function isLedger(value) {
+  return Array.isArray(value) && value.every(entry => typeof entry === 'object' && entry !== null
+    && typeof entry.provider === 'string' && typeof entry.model === 'string'
+    && isBuckets(entry.peak) && isBuckets(entry.offPeak))
+}
+
+/**
+ * Validate a state restored from a persisted checkpoint. The registry discards
+ * rows whose version differs; this guards against a corrupted row of the right
+ * version reaching the fold.
+ * @param {unknown} value - candidate state.
+ * @returns {object} the same value.
+ * @throws {Error} when the value is not a state of this version.
+ */
+export function parseState(value) {
+  const ok = typeof value === 'object' && value !== null
+    && isCount(value.inherited) && isLedger(value.total) && isLedger(value.compaction)
+    && isCount(value.calls) && isCount(value.compactions)
+    && (value.turn === null || (typeof value.turn === 'object' && isCount(value.turn.no) && isLedger(value.turn.ledger)))
+    && (value.turnNo === null || isCount(value.turnNo))
+    && (value.header === null || (typeof value.header === 'object' && typeof value.header.model === 'string'))
+    && (value.last === null || (typeof value.last === 'object' && isBuckets(value.last.buckets)))
+  if (!ok) throw new Error('dsh-token-bill: invalid projection state')
+  return value
+}
+
+/**
+ * The projection definition registered with `ctx.sessionProjections`.
+ * @param {object} pricing - result of `resolvePricing(config)`.
+ * @returns {object} projection definition.
+ */
+export function createTokenCostProjection(pricing) {
+  const tierOf = time => tierAt(time, pricing.holidays)
+  return {
+    key: PROJECTION_KEY,
+    stateVersion: STATE_VERSION,
+    stateSchema: { parse: parseState },
+    init: (_header, inheritedEventCount) => initialState(inheritedEventCount),
+    apply: (state, event) => foldEvent(state, event, tierOf),
+    wire: {
+      viewSchema: {
+        parse: (value) => {
+          if (typeof value !== 'object' || value === null || typeof value.then === 'function') {
+            throw new Error('dsh-token-bill: view must be a plain object')
+          }
+          return value
+        },
+      },
+      view: state => buildView(state, pricing),
+    },
+  }
+}

package/lib/pricing.js

@@ -0,0 +1,330 @@
+/**
+ * Price tables, DeepSeek peak/off-peak tiers, and the priced client view.
+ *
+ * Pure module with no Harness imports, so the same code runs inside the Host
+ * and under plain `node --test`. Every price is per one million tokens.
+ */
+
+/** Date the built-in DeepSeek table was last checked against the official page. */
+export const PRICES_AS_OF = '2026-11-07'
+
+/** Official price page the built-in table mirrors. */
+export const PRICE_SOURCE = 'https://api-docs.deepseek.com/zh-cn/quick_start/pricing'
+
+/** One rate card: per-1M-token prices for each billed bucket. */
+function rate(input, cacheHit, output) {
+  return Object.freeze({ input, cacheHit, cacheWrite: input, output })
+}
+
+/**
+ * Official DeepSeek API prices. Off-peak is half of peak; see {@link tierAt}.
+ * Cache writes are billed as ordinary (cache-miss) input.
+ */
+export const BUILTIN_PRICES = Object.freeze({
+  'deepseek-flash': Object.freeze({
+    CNY: Object.freeze({ peak: rate(2, 0.04, 8), offPeak: rate(1, 0.02, 4) }),
+    USD: Object.freeze({ peak: rate(0.3, 0.006, 1.2), offPeak: rate(0.15, 0.003, 0.6) }),
+  }),
+  'deepseek-v4-pro': Object.freeze({
+    CNY: Object.freeze({ peak: rate(9, 0.3, 27), offPeak: rate(4.5, 0.15, 13.5) }),
+    USD: Object.freeze({ peak: rate(1.32, 0.044, 3.96), offPeak: rate(0.66, 0.022, 1.98) }),
+  }),
+})
+
+/** Retired model ids the API still accepts and bills at another model's price. */
+export const MODEL_ALIASES = Object.freeze({
+  'deepseek-v4-flash': 'deepseek-flash',
+  'deepseek-v4-flash-vision-exp': 'deepseek-flash',
+})
+
+/**
+ * Days off under the State Council's 2026 holiday notice (2025-11-04), as
+ * Beijing dates. Weekends are off-peak anyway; listing whole breaks keeps the
+ * table easy to check against the notice. Make-up workdays on weekends stay
+ * off-peak, because DeepSeek's rule counts every weekend as off-peak.
+ */
+export const CN_HOLIDAYS = Object.freeze([
+  // New Year
+  '2026-01-01', '2026-01-02', '2026-01-03',
+  // Spring Festival
+  '2026-02-15', '2026-02-16', '2026-02-17', '2026-02-18', '2026-02-19',
+  '2026-02-20', '2026-02-21', '2026-02-22', '2026-02-23',
+  // Qingming
+  '2026-04-04', '2026-04-05', '2026-04-06',
+  // Labour Day
+  '2026-05-01', '2026-05-02', '2026-05-03', '2026-05-04', '2026-05-05',
+  // Dragon Boat
+  '2026-06-19', '2026-06-20', '2026-06-21',
+  // Mid-Autumn
+  '2026-09-25', '2026-09-26', '2026-09-27',
+  // National Day
+  '2026-10-01', '2026-10-02', '2026-10-03', '2026-10-04', '2026-10-05',
+  '2026-10-06', '2026-10-07',
+])
+
+/** Peak windows in Beijing minutes after midnight, as [start, end). */
+export const PEAK_WINDOWS = Object.freeze([[9 * 60, 12 * 60], [14 * 60, 18 * 60]])
+
+/** Beijing has no daylight saving time, so a fixed offset is exact. */
+const BEIJING_OFFSET_MS = 8 * 60 * 60 * 1000
+
+/** The two billing tiers every ledger entry keeps apart. */
+export const TIERS = Object.freeze(['peak', 'offPeak'])
+
+const CURRENCY_SYMBOLS = Object.freeze({ CNY: '¥', USD: '$', EUR: '€', GBP: '£', JPY: '¥', HKD: 'HK$' })
+
+const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/
+
+/**
+ * Beijing calendar facts of one instant.
+ * @param {number} time - epoch milliseconds.
+ * @returns {{ date: string, weekday: number, minute: number }} ISO date, 0 = Sunday, minutes after midnight.
+ */
+export function beijingParts(time) {
+  const shifted = new Date(time + BEIJING_OFFSET_MS)
+  return {
+    date: shifted.toISOString().slice(0, 10),
+    weekday: shifted.getUTCDay(),
+    minute: shifted.getUTCHours() * 60 + shifted.getUTCMinutes(),
+  }
+}
+
+/**
+ * DeepSeek billing tier of one instant: peak is Beijing time Monday to Friday,
+ * 09:00-12:00 and 14:00-18:00, except Chinese public holidays; everything else
+ * is off-peak. An instant that cannot be read counts as peak, the higher price.
+ * @param {number} time - epoch milliseconds of the billed event.
+ * @param {ReadonlySet<string>} holidays - Beijing dates (YYYY-MM-DD) that are off-peak all day.
+ * @returns {'peak' | 'offPeak'} the tier.
+ */
+export function tierAt(time, holidays) {
+  if (typeof time !== 'number' || !Number.isFinite(time)) return 'peak'
+  const { date, weekday, minute } = beijingParts(time)
+  if (weekday === 0 || weekday === 6 || holidays.has(date)) return 'offPeak'
+  for (const [start, end] of PEAK_WINDOWS) {
+    if (minute >= start && minute < end) return 'peak'
+  }
+  return 'offPeak'
+}
+
+function isObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** A non-negative finite price; numeric strings are accepted because YAML authors quote numbers. */
+function price(value) {
+  const number = typeof value === 'string' && value.trim() !== '' ? Number(value) : value
+  return typeof number === 'number' && Number.isFinite(number) && number >= 0 ? number : undefined
+}
+
+/**
+ * Normalize one user rate card. `input` and `output` are required unless the
+ * base supplies them; `cacheHit` and `cacheWrite` default to the input price.
+ * The v1 names `inputPrice`, `cacheHitPrice`, and `outputPrice` are accepted.
+ * @param {unknown} raw - user value.
+ * @param {object} [base] - rate card the missing fields inherit from.
+ * @returns {object | undefined} a complete rate card, or undefined when unusable.
+ */
+export function normalizeRate(raw, base) {
+  if (!isObject(raw)) return undefined
+  const input = price(raw.input ?? raw.inputPrice) ?? base?.input
+  const output = price(raw.output ?? raw.outputPrice) ?? base?.output
+  if (input === undefined || output === undefined) return undefined
+  const cacheHit = price(raw.cacheHit ?? raw.cacheRead ?? raw.cacheHitPrice) ?? base?.cacheHit ?? input
+  const cacheWrite = price(raw.cacheWrite ?? raw.cacheWritePrice) ?? base?.cacheWrite ?? input
+  return Object.freeze({ input, cacheHit, cacheWrite, output })
+}
+
+/**
+ * Normalize one user price entry: a rate card plus an optional `offPeak` card
+ * whose missing fields inherit from the main one.
+ * @param {unknown} raw - user value.
+ * @returns {{ peak: object, offPeak?: object } | undefined} the entry, or undefined when unusable.
+ */
+export function normalizeEntry(raw) {
+  const peak = normalizeRate(raw)
+  if (peak === undefined) return undefined
+  const offPeak = isObject(raw.offPeak) ? normalizeRate(raw.offPeak, peak) : undefined
+  return Object.freeze(offPeak === undefined ? { peak } : { peak, offPeak })
+}
+
+/**
+ * Resolve the plugin's raw config into the pricing used by the fold and view.
+ * Unknown or malformed fields fall back to defaults instead of failing, so a
+ * typo never takes the badge down.
+ * @param {unknown} config - the Loader row's config object.
+ * @returns {object} frozen pricing facts plus `priceFor(provider, model)`.
+ */
+export function resolvePricing(config) {
+  const cfg = isObject(config) ? config : {}
+  const currency = typeof cfg.currency === 'string' && cfg.currency.trim() !== ''
+    ? cfg.currency.trim().toUpperCase()
+    : 'CNY'
+  const symbol = typeof cfg.symbol === 'string' ? cfg.symbol : CURRENCY_SYMBOLS[currency] ?? `${currency} `
+  const timeOfDay = cfg.timeOfDayPricing !== false
+  const extraHolidays = Array.isArray(cfg.holidays)
+    ? cfg.holidays.filter(day => typeof day === 'string' && DATE_PATTERN.test(day.trim())).map(day => day.trim())
+    : []
+  const holidays = new Set([...CN_HOLIDAYS, ...extraHolidays])
+
+  const models = new Map()
+  if (isObject(cfg.models)) {
+    for (const [key, raw] of Object.entries(cfg.models)) {
+      const entry = normalizeEntry(raw)
+      if (entry !== undefined && key.trim() !== '') models.set(key.trim().toLowerCase(), entry)
+    }
+  }
+
+  // `fallback` prices every model without its own entry. The v1 top-level
+  // fields keep working as that fallback.
+  const legacy = cfg.inputPrice !== undefined || cfg.outputPrice !== undefined
+    ? normalizeEntry({ input: cfg.inputPrice, cacheHit: cfg.cacheHitPrice, output: cfg.outputPrice })
+    : undefined
+  const fallback = (isObject(cfg.fallback) ? normalizeEntry(cfg.fallback) : undefined) ?? legacy
+
+  const builtin = (model) => {
+    const table = BUILTIN_PRICES[MODEL_ALIASES[model] ?? model]
+    return table === undefined ? undefined : table[currency]
+  }
+
+  /**
+   * Price entry of one route: `provider/model` override, then `model`
+   * override, then the built-in table, then the fallback.
+   * @param {string} provider - provider id the message was routed through.
+   * @param {string} model - model id.
+   * @returns {{ peak: object, offPeak?: object } | undefined} the entry, or undefined when unpriced.
+   */
+  const priceFor = (provider, model) => {
+    const m = String(model ?? '').toLowerCase()
+    const p = String(provider ?? '').toLowerCase()
+    return models.get(`${p}/${m}`) ?? models.get(m) ?? builtin(m) ?? fallback
+  }
+
+  return Object.freeze({
+    currency,
+    symbol,
+    timeOfDay,
+    holidays,
+    showInSessionList: cfg.showInSessionList !== false,
+    priceFor,
+  })
+}
+
+const PER_TOKENS = 1_000_000
+
+/** Cost of one bucket set under one rate card, per bucket. */
+function bucketCosts(buckets, card) {
+  return {
+    input: buckets.input * card.input / PER_TOKENS,
+    cacheRead: buckets.cacheRead * card.cacheHit / PER_TOKENS,
+    cacheWrite: buckets.cacheWrite * card.cacheWrite / PER_TOKENS,
+    output: buckets.output * card.output / PER_TOKENS,
+  }
+}
+
+function sumCosts(costs) {
+  return costs.input + costs.cacheRead + costs.cacheWrite + costs.output
+}
+
+function hasTokens(buckets) {
+  return buckets.input + buckets.cacheRead + buckets.cacheWrite + buckets.output > 0
+}
+
+/** Drop float noise so equal ledgers produce equal views. */
+function money(value) {
+  return Number(value.toFixed(8))
+}
+
+/**
+ * Price one ledger (route entries split into peak and off-peak buckets).
+ * @param {ReadonlyArray<object>} ledger - fold ledger.
+ * @param {object} pricing - result of {@link resolvePricing}.
+ * @returns {object} totals, per-bucket costs, per-model rows, and off-peak savings.
+ */
+export function priceLedger(ledger, pricing) {
+  const tokens = { input: 0, cacheRead: 0, cacheWrite: 0, output: 0, reasoning: 0 }
+  const costs = { input: 0, cacheRead: 0, cacheWrite: 0, output: 0 }
+  let saved = 0
+  let complete = true
+  const models = []
+  for (const entry of ledger) {
+    const prices = pricing.priceFor(entry.provider, entry.model)
+    let modelCost = prices === undefined ? null : 0
+    let modelTokens = 0
+    for (const tier of TIERS) {
+      const buckets = entry[tier]
+      tokens.input += buckets.input
+      tokens.cacheRead += buckets.cacheRead
+      tokens.cacheWrite += buckets.cacheWrite
+      tokens.output += buckets.output
+      tokens.reasoning += buckets.reasoning
+      modelTokens += buckets.input + buckets.cacheRead + buckets.cacheWrite + buckets.output
+      if (prices === undefined) {
+        if (hasTokens(buckets)) complete = false
+        continue
+      }
+      const discounted = tier === 'offPeak' && pricing.timeOfDay && prices.offPeak !== undefined
+      const tierCosts = bucketCosts(buckets, discounted ? prices.offPeak : prices.peak)
+      costs.input += tierCosts.input
+      costs.cacheRead += tierCosts.cacheRead
+      costs.cacheWrite += tierCosts.cacheWrite
+      costs.output += tierCosts.output
+      modelCost += sumCosts(tierCosts)
+      if (discounted) saved += sumCosts(bucketCosts(buckets, prices.peak)) - sumCosts(tierCosts)
+    }
+    models.push({
+      provider: entry.provider,
+      model: entry.model,
+      tokens: modelTokens,
+      cost: modelCost === null ? null : money(modelCost),
+    })
+  }
+  models.sort((a, b) => (b.cost ?? -1) - (a.cost ?? -1) || b.tokens - a.tokens)
+  return {
+    cost: money(sumCosts(costs)),
+    complete,
+    tokens,
+    costs: {
+      input: money(costs.input),
+      cacheRead: money(costs.cacheRead),
+      cacheWrite: money(costs.cacheWrite),
+      output: money(costs.output),
+    },
+    saved: money(saved),
+    models,
+  }
+}
+
+/**
+ * The client view of one fold state: everything the badge, the detail panel,
+ * and the session-list label render. Pricing is applied here, at read time,
+ * so editing prices re-prices every session without re-folding its log.
+ * @param {object} state - fold state from `lib/fold.js`.
+ * @param {object} pricing - result of {@link resolvePricing}.
+ * @returns {object} JSON view.
+ */
+export function buildView(state, pricing) {
+  const total = priceLedger(state.total, pricing)
+  const prompt = total.tokens.input + total.tokens.cacheRead + total.tokens.cacheWrite
+  const turn = state.turn === null ? null : priceLedger(state.turn.ledger, pricing)
+  const compaction = state.compactions > 0 ? priceLedger(state.compaction, pricing) : null
+  return {
+    v: 2,
+    currency: pricing.currency,
+    symbol: pricing.symbol,
+    cost: total.cost,
+    complete: total.complete,
+    calls: state.calls,
+    tokens: total.tokens,
+    costs: total.costs,
+    cacheHitRate: prompt > 0 ? Number((total.tokens.cacheRead / prompt).toFixed(4)) : null,
+    tiered: pricing.timeOfDay,
+    saved: total.saved,
+    turn: turn === null ? null : { no: state.turn.no, cost: turn.cost, complete: turn.complete },
+    compaction: compaction === null
+      ? null
+      : { calls: state.compactions, cost: compaction.cost, complete: compaction.complete },
+    models: total.models,
+    showInList: pricing.showInSessionList,
+  }
+}

package/locale/en.json

@@ -0,0 +1,7 @@
+{
+  "meta": {
+    "title": "Conversation cost",
+    "description": "Estimated cost of every conversation: a badge with a breakdown under the composer and a cost beside each conversation in the sidebar, priced per model and by DeepSeek peak / off-peak hours.",
+    "detail": "README.en.md"
+  }
+}

package/locale/zh.json

@@ -0,0 +1,7 @@
+{
+  "meta": {
+    "title": "对话费用",
+    "description": "估算每个对话的费用：输入框下方显示本会话费用并可展开明细，侧边栏显示每个对话的费用；按模型、按 DeepSeek 高峰/空闲时段分别计价。",
+    "detail": "README.md"
+  }
+}