dsh-tacit 0.2.3 → 0.3.0

package/docs/README.zh.md

@@ -45,7 +45,7 @@ DeepSeek API Key（Tacit 从不读取它）。
 | **零点击学习** | 不顺的轮次和你自己的纠正会在后台被分析，并带上上一轮作为上下文；自动分析每天有上限（默认 30 次） | 每次 $0.001–0.003 |
 | **指令要靠表现留下** | 学到的指令作为一小段系统提示注入，你可以查看、编辑、开关或删除；新指令先是*候选*，如果你的不顺轮次比例变差就会退役 | 免费 |
 | **✨ 改进** | 输入框里的按钮，用 Tacit 学到的东西重写当前草稿，带前后对比预览和 👍/👎 | 每次点击 $0.001–0.002 |
-| **测量而非猜测** | 设置页显示你的真实趋势：不顺轮次比例和每轮 token 数，最早 20 轮 vs 最近 20 轮 | 免费 |
+| **测量而非猜测** | 设置页显示你的真实趋势：不顺轮次比例和每轮 token 数，最早 20 轮 vs 最近 20 轮——以及 Tacit 自己的花费：每次调用都被计量并按目录价定价，显示在设置页里 | 免费 |
 
 ## 它是怎么工作的
 
@@ -63,8 +63,8 @@ DeepSeek API Key（Tacit 从不读取它）。
 
 Tacit 从不接触你的 API Key（所有调用都经过 harness 自己的模型服务），只通过你会话
 自己的 provider 路由调用白名单里的官方模型，报告和指令都存放在
-`~/.dsh/storages/tacit/`，拒绝对自身路由的跨站请求，除了自己的报告之外从不删除任何
-东西。美元数字是按公开价格的估算；`dsh-cost-meter` 这样的成本插件会显示真实花费。
+`~/.dsh/storages/tacit/`，拒绝对自身路由的跨站请求，除了自己的报告和过期的用量记录
+之外从不删除任何东西。美元数字是按公开价格的估算；`dsh-cost-meter` 这样的成本插件会显示真实花费。
 完整的数据流与成本表、以及坦白的限制清单（英文）：
 [Privacy, cost & limitations](https://github.com/hackernotfound/dsh-tacit/blob/main/docs/privacy-and-cost.md)。
 

package/lib/analyze.js

@@ -90,11 +90,11 @@ export const ANALYSIS_TOOL = {
 
 export const IMPROVE_TOOL = {
   name: 'improved',
-  description: 'Submit the rewritten draft.',
+  description: 'Submit the final rewritten draft, or the draft verbatim when it is already complete.',
   parameters: {
     type: 'object',
     properties: {
-      improved: { type: 'string', description: 'the rewritten prompt' },
+      improved: { type: 'string', description: 'the final prompt (the draft verbatim if already complete)' },
       rationale: { type: 'string', description: '1-2 sentences on what changed and why' },
     },
     required: ['improved', 'rationale'],
@@ -347,18 +347,52 @@ export const ANALYSIS_SYSTEM_PROMPT = [
 
 export const IMPROVE_SYSTEM_PROMPT = [
   'You are a prompt-improvement assistant inside DeepSeek Harness.',
-  'The user typed a draft prompt into the composer. Rewrite it to be more',
-  'precise, complete, and token-efficient, while PRESERVING its intent.',
-  'Do not add requirements the user did not ask for; fill in only what is',
-  'genuinely underspecified (scope, constraints, format, acceptance criteria).',
-  'Learn from the user\'s recurring mistake patterns when provided.',
+  'The user typed a draft prompt for a coding agent into the composer. You get',
+  'ONE pass: return the prompt the user would arrive at after several rounds of',
+  'editing. Leave nothing for a second pass.',
+  '',
+  'A finished prompt has every item below (skip an item only when the draft or',
+  'context makes it obviously unnecessary):',
+  '- GOAL — one sentence: the outcome and what "done" looks like.',
+  '- CONTEXT — the concrete facts the agent would otherwise have to discover:',
+  '  file paths, URLs, names, versions, decisions already made. Take them from',
+  '  the draft and from RECENT CONVERSATION CONTEXT. Never invent facts.',
+  '- SCOPE — what is in and out; what to leave untouched.',
+  '- CONSTRAINTS — what not to do, limits, style, language, budget.',
+  '- OUTPUT FORMAT — the shape of the answer: list, table, diff, code only,',
+  '  prioritized, length.',
+  '- EFFICIENCY — what the agent need not explore or verify, so it finishes',
+  '  in fewer steps and tool calls.',
+  '',
+  'Rules:',
+  '- Preserve the user\'s intent; add nothing they did not ask for or clearly',
+  '  imply.',
+  '- Only fill what is genuinely underspecified. Keep the draft\'s wording where',
+  '  it already works.',
+  '- Be as short as completeness allows: no filler, no role preambles ("You are',
+  '  an expert…"), no restating what the agent already knows.',
+  '- Follow the STYLE RULES, NEGATIVE FEEDBACK and RECURRING MISTAKE PATTERNS',
+  '  when provided; they describe this user\'s habits.',
+  '- Silently check the draft against every item first, then write the whole',
+  '  prompt once.',
+  '- FIXED POINT: if the draft already satisfies every item, return it',
+  '  VERBATIM (character for character) with the rationale "Already complete."',
+  '  Never make cosmetic edits — a prompt you improved must come back',
+  '  unchanged when improved again.',
+  '',
+  'Example',
+  'draft: what do you think we can do to market our plugin today',
+  'context: the plugin was just published at https://github.com/x/y',
+  'improved: The plugin is now public at https://github.com/x/y. How do we',
+  'market it and get it noticed? Give a prioritized list of concrete actions,',
+  'easiest first, biggest impact last, with the expected effort for each.',
   '',
   'RESPONSE FORMAT — this is mandatory and machine-parsed:',
   'Your ENTIRE response must be ONE JSON object and nothing else. No preamble,',
   'no narration, no explanations outside the JSON, no markdown fences.',
   'Start directly with "{" and end with "}".',
   '{',
-  '  "improved": "<the rewritten prompt>",',
+  '  "improved": "<the final prompt — the draft verbatim if already complete>",',
   '  "rationale": "<1-2 sentences on what you changed and why>"',
   '}',
   '',
@@ -989,8 +1023,12 @@ export function lastDownReasons(profile, n = 3) {
  * NEVER returned as the answer (chain of thought is not a report). A
  * deployment that rejects the reasoning effort gets one retry without it.
  * Returns the answer text ('' when the model produced nothing usable).
+ *
+ * When `onUsage(record)` is given, it is called once per underlying `run()`
+ * (twice on the reasoning-effort retry) with a usage/cost record. A sink
+ * that throws never fails the model call.
  */
-export async function callCoachModel(ctx, { provider, model, system, userText, maxTokens, timeoutMs, tool, sessionId, reasoningEffort = COACH_REASONING_EFFORT }) {
+export async function callCoachModel(ctx, { provider, model, system, userText, maxTokens, timeoutMs, tool, sessionId, reasoningEffort = COACH_REASONING_EFFORT, onUsage }) {
   const llm = ctx.get !== undefined && typeof ctx.get === 'function' ? ctx.get('llm') : undefined
   if (llm === undefined || typeof llm.stream !== 'function') {
     const error = new Error('the harness LLM service is unavailable')
@@ -1003,35 +1041,81 @@ export async function callCoachModel(ctx, { provider, model, system, userText, m
     content: [{ type: 'text', text: userText }],
     source: { kind: 'plugin', plugin: 'dsh-tacit' },
   })
+  const toCount = (value) => (Number.isFinite(value) && value >= 0 ? value : 0)
   const run = async (effort) => {
+    const startedAt = Date.now()
     let text = ''
     let toolArgs = ''
     let toolDeltas = ''
-    let finish = ''
-    for await (const chunk of llm.stream({
-      provider,
-      model,
-      messages: [message],
-      system,
-      maxTokens,
-      signal: controller.signal,
-      ...(effort !== undefined ? { reasoningEffort: effort } : {}),
-      ...(tool !== undefined ? { tools: [tool] } : {}),
-      ...(typeof sessionId === 'string' && sessionId.length > 0 ? { sessionId } : {}),
-    })) {
-      if (chunk === null || typeof chunk !== 'object') continue
-      if (chunk.type === 'finish' && typeof chunk.reason === 'string') finish = chunk.reason
-      if (chunk.type === 'text-delta' && typeof chunk.text === 'string') text += chunk.text
-      else if (chunk.type === 'tool-call-delta' && typeof chunk.argumentsDelta === 'string') toolDeltas += chunk.argumentsDelta
-      else if (chunk.type === 'block-end' && chunk.block !== null && typeof chunk.block === 'object'
-        && chunk.block.type === 'tool-call' && typeof chunk.block.arguments === 'string' && toolArgs === '') {
-        toolArgs = chunk.block.arguments
+    let finishKind = ''
+    let failure = null
+    let usage = null
+    let thrown = null
+    try {
+      for await (const chunk of llm.stream({
+        provider,
+        model,
+        messages: [message],
+        system,
+        maxTokens,
+        signal: controller.signal,
+        ...(effort !== undefined ? { reasoningEffort: effort } : {}),
+        ...(tool !== undefined ? { tools: [tool] } : {}),
+        ...(typeof sessionId === 'string' && sessionId.length > 0 ? { sessionId } : {}),
+      })) {
+        if (chunk === null || typeof chunk !== 'object') continue
+        if (chunk.type === 'usage' && chunk.usage !== null && typeof chunk.usage === 'object') {
+          usage = {
+            inputTokens: toCount(chunk.usage.inputTokens),
+            outputTokens: toCount(chunk.usage.outputTokens),
+            cacheReadTokens: toCount(chunk.usage.cacheReadTokens),
+            cacheWriteTokens: toCount(chunk.usage.cacheWriteTokens),
+            reasoningTokens: toCount(chunk.usage.reasoningTokens),
+          }
+        } else if (chunk.type === 'finish') {
+          finishKind = typeof chunk.reason === 'string' ? chunk.reason : (chunk.reason?.kind ?? '')
+          failure = chunk.reason?.failure ?? null
+        } else if (chunk.type === 'text-delta' && typeof chunk.text === 'string') text += chunk.text
+        else if (chunk.type === 'tool-call-delta' && typeof chunk.argumentsDelta === 'string') toolDeltas += chunk.argumentsDelta
+        else if (chunk.type === 'block-end' && chunk.block !== null && typeof chunk.block === 'object'
+          && chunk.block.type === 'tool-call' && typeof chunk.block.arguments === 'string' && toolArgs === '') {
+          toolArgs = chunk.block.arguments
+        }
+      }
+      if (finishKind === 'error' || finishKind === 'aborted') {
+        thrown = Object.assign(new Error(failure?.message ?? finishKind), { code: failure?.code ?? finishKind.toUpperCase() })
+        throw thrown
+      }
+    } catch (error) {
+      thrown = thrown ?? error
+      throw error
+    } finally {
+      if (typeof onUsage === 'function') {
+        const code = (thrown !== null && typeof thrown === 'object' ? thrown.code : undefined) ?? failure?.code ?? ''
+        const status = thrown !== null || finishKind === 'error' || finishKind === 'aborted'
+          ? 'failed'
+          : (usage === null ? 'unmetered' : 'ok')
+        try {
+          onUsage({
+            startedAt,
+            durationMs: Date.now() - startedAt,
+            model,
+            provider,
+            reasoningEffort: effort ?? null,
+            finish: finishKind,
+            status,
+            code,
+            usage,
+          })
+        } catch {
+          // a sink bug must never fail a model call
+        }
       }
     }
     if (toolArgs.length > 0) return toolArgs
     if (toolDeltas.length > 0) return toolDeltas
-    if (text.length === 0 && finish.length > 0 && finish !== 'stop') {
-      console.warn('[tacit] model call ended without an answer (finish: ' + finish + ', maxTokens: ' + String(maxTokens) + ')')
+    if (text.length === 0 && finishKind.length > 0 && finishKind !== 'stop') {
+      console.warn('[tacit] model call ended without an answer (finish: ' + finishKind + ', maxTokens: ' + String(maxTokens) + ')')
     }
     return text
   }

package/lib/index.js

@@ -94,6 +94,8 @@ export function apply(ctx, config) {
   }
 
   ctx.effect(() => () => {
-    // Nothing to flush: all writes are atomic and complete at call time.
+    // Reports and the profile are written atomically at call time; only the
+    // usage ledger keeps debounced state, so an unload flushes it.
+    service.usage.flush()
   }, 'tacit: dispose')
 }

package/lib/pricing-source.js

@@ -0,0 +1,133 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 hackernotfound — https://github.com/hackernotfound/dsh-tacit
+/**
+ * dsh-tacit — the price table behind the usage tracker.
+ *
+ * Wraps the pure `lib/pricing.js` with one optional input: the sibling
+ * `dsh-cost-meter` plugin's `costMeter` service. When that service is
+ * installed and hands over a usable state, its prices win; otherwise the
+ * bundled DeepSeek list prices apply. The service is fully duck-typed and
+ * never trusted: `refresh()` never throws, never blocks longer than
+ * `timeoutMs`, and any failure (absent, throwing, hanging, junk) leaves the
+ * source on the bundled table with a human-readable `error`.
+ *
+ * A model call must never wait on this — the service refreshes it in the
+ * background and every `priceCall` reads whatever snapshot is current.
+ */
+
+import { priceCall as priceCallWith, normalizeCostMeterState, tierAt, PRICES_AS_OF, BUNDLED_PRICES } from './pricing.js'
+import { COACH_MODELS } from './schema.js'
+
+/** A `{cacheHit, cacheMiss, output}` triple as a fresh object (never a reference into a shared table). */
+function copyTriple(triple) {
+  return { cacheHit: triple.cacheHit, cacheMiss: triple.cacheMiss, output: triple.output }
+}
+
+/** A normalized snapshot is only worth using if it actually carries a price. */
+function hasPrices(snapshot) {
+  if (snapshot === null || typeof snapshot !== 'object') return false
+  const models = snapshot.models !== null && typeof snapshot.models === 'object' ? Object.keys(snapshot.models) : []
+  const providers = snapshot.providers !== null && typeof snapshot.providers === 'object' ? Object.keys(snapshot.providers) : []
+  return models.length > 0 || providers.length > 0
+}
+
+/** Whatever was thrown/rejected, as a short message. */
+function messageOf(error) {
+  if (error !== null && typeof error === 'object' && typeof error.message === 'string' && error.message.length > 0) return error.message
+  return String(error)
+}
+
+/** Reject after `ms`; the timer is unref'd so a pending refresh never holds the process open. */
+function rejectAfter(ms) {
+  let timer = null
+  const promise = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => reject(new Error(`costMeter getState() timed out after ${ms}ms`)), ms)
+    if (typeof timer?.unref === 'function') timer.unref()
+  })
+  return { promise, cancel: () => { if (timer !== null) clearTimeout(timer) } }
+}
+
+/**
+ * The price source the tracker and the reports read from.
+ * `now`/`timeoutMs` are injectable so tests can drive the clock and the
+ * hang path without waiting five seconds.
+ */
+export function createPricingSource(ctx, { now = Date.now, timeoutMs = 5000 } = {}) {
+  const state = { snapshot: null, source: 'bundled', refreshedAt: 0, error: '' }
+
+  /** Drop back to the bundled table, remembering why. */
+  function fallBack(error) {
+    state.snapshot = null
+    state.source = 'bundled'
+    state.refreshedAt = 0
+    state.error = error
+  }
+
+  async function refresh() {
+    const service = ctx !== null && typeof ctx === 'object' && typeof ctx.get === 'function' ? ctx.get('costMeter') : undefined
+    if (service === undefined || service === null || typeof service.getState !== 'function') {
+      fallBack('the costMeter service is not available — using bundled list prices')
+      return
+    }
+    const timeout = rejectAfter(timeoutMs)
+    let raw
+    try {
+      raw = await Promise.race([Promise.resolve(service.getState()), timeout.promise])
+    } catch (error) {
+      fallBack(messageOf(error))
+      return
+    } finally {
+      timeout.cancel()
+    }
+    const snapshot = normalizeCostMeterState(raw)
+    if (!hasPrices(snapshot)) {
+      fallBack('the costMeter state carried no usable prices — using bundled list prices')
+      return
+    }
+    state.snapshot = snapshot
+    state.source = 'costMeter'
+    state.refreshedAt = now()
+    state.error = ''
+  }
+
+  /** {@link priceCallWith} against the current snapshot (bundled when there is none). */
+  function priceCall(args) {
+    return priceCallWith({ ...args, table: state.snapshot })
+  }
+
+  /**
+   * What the Pricing card shows about the source itself. `tierNow` is read
+   * off the same snapshot `priceCall` prices against — a cost-meter table
+   * that turns peak pricing off, shifts the windows, or dates them into the
+   * future must not leave the card quoting the bundled schedule.
+   */
+  function status() {
+    const snapshot = state.snapshot
+    const tierNow = snapshot === null
+      ? tierAt(now())
+      : tierAt(now(), { windows: snapshot.windows, effectiveAtMs: snapshot.effectiveAtMs, peakEnabled: snapshot.peakEnabled !== false })
+    return {
+      source: state.source,
+      asOf: typeof snapshot?.asOf === 'string' ? snapshot.asOf : PRICES_AS_OF,
+      refreshedAt: state.refreshedAt,
+      tierNow,
+      error: state.error,
+    }
+  }
+
+  /** `{model: {offPeak, peak}}` for both coach models — snapshot first, bundled per model otherwise. */
+  function rates() {
+    const models = state.snapshot?.models
+    const out = {}
+    for (const model of COACH_MODELS) {
+      const entry = models !== null && typeof models === 'object' ? models[model] : undefined
+      const source = entry !== null && typeof entry === 'object' && entry.offPeak !== undefined && entry.peak !== undefined
+        ? entry
+        : BUNDLED_PRICES[model]
+      out[model] = { offPeak: copyTriple(source.offPeak), peak: copyTriple(source.peak) }
+    }
+    return out
+  }
+
+  return { refresh, priceCall, status, rates }
+}

package/lib/pricing.js

@@ -0,0 +1,311 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 hackernotfound — https://github.com/hackernotfound/dsh-tacit
+/**
+ * dsh-tacit — pure pricing (no I/O).
+ *
+ * Prices one model call from its token usage against either the bundled
+ * DeepSeek list prices (peak / off-peak / Beijing-weekend tiers) or a price
+ * table sourced from the `dsh-cost-meter` plugin's state. Nothing here
+ * touches the network, the store, or the service — `lib/pricing-source.js`
+ * is responsible for fetching the cost-meter state, normalizing it with
+ * `normalizeCostMeterState`, and handing the result in as `table`.
+ *
+ * Tier is decided once, at the request's start time (`atMs`) — not at
+ * finish, so a call that straddles a boundary is priced consistently.
+ */
+
+export const PRICES_AS_OF = '2026-08-22'
+
+/**
+ * `reasoningTokens` (DeepSeek adapter) is always a subset of `outputTokens`,
+ * never a separate quantity — so it must not be billed again. Kept as a
+ * named constant (rather than inlined `false`) so it can be flipped if a
+ * future adapter ever reports reasoning as additional to output.
+ */
+export const REASONING_BILLED_SEPARATELY = false
+
+/** Provider ids that route through DeepSeek's own API (bundled list prices apply). */
+export const OFFICIAL_PROVIDERS = ['deepseek-official', 'deepseek']
+
+/** USD per 1M tokens, as of {@link PRICES_AS_OF}. */
+export const BUNDLED_PRICES = {
+  'deepseek-v4-flash': {
+    offPeak: { cacheHit: 0.007, cacheMiss: 0.22, output: 0.66 },
+    peak: { cacheHit: 0.014, cacheMiss: 0.44, output: 1.32 },
+  },
+  'deepseek-v4-pro': {
+    offPeak: { cacheHit: 0.022, cacheMiss: 0.66, output: 1.98 },
+    peak: { cacheHit: 0.044, cacheMiss: 1.32, output: 3.96 },
+  },
+}
+
+/** Peak hour windows, UTC, `[start, end)`. */
+export const PEAK_WINDOWS_UTC = [{ start: 1, end: 4 }, { start: 6, end: 10 }]
+
+/** Beijing-weekend off-peak rule only applies from this moment on. */
+export const WEEKEND_OFFPEAK_FROM = Date.parse('2026-08-22T16:00:00Z')
+
+const MS_PER_HOUR = 3600 * 1000
+
+function isFiniteNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value)
+}
+
+function isPositiveNumber(value) {
+  return isFiniteNumber(value) && value > 0
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+/** Is the day-of-week of `ms + 8h`, in UTC, a Saturday or Sunday (Beijing calendar)? */
+export function isBeijingWeekend(ms) {
+  if (!isFiniteNumber(ms)) return false
+  const day = new Date(ms + 8 * MS_PER_HOUR).getUTCDay()
+  return day === 0 || day === 6
+}
+
+/**
+ * The pricing tier in effect at `ms`. `offPeak` when `!peakEnabled`, when
+ * `ms < effectiveAtMs`, when it's a Beijing weekend at/after
+ * {@link WEEKEND_OFFPEAK_FROM}, or when the UTC hour falls outside every
+ * window; `peak` otherwise.
+ */
+export function tierAt(ms, { windows = PEAK_WINDOWS_UTC, effectiveAtMs = 0, peakEnabled = true } = {}) {
+  if (!peakEnabled) return 'offPeak'
+  if (!isFiniteNumber(ms)) return 'offPeak'
+  if (isFiniteNumber(effectiveAtMs) && ms < effectiveAtMs) return 'offPeak'
+  if (ms >= WEEKEND_OFFPEAK_FROM && isBeijingWeekend(ms)) return 'offPeak'
+
+  const hour = new Date(ms).getUTCHours()
+  const activeWindows = Array.isArray(windows) ? windows : PEAK_WINDOWS_UTC
+  const inWindow = activeWindows.some(
+    (w) => isPlainObject(w) && isFiniteNumber(w.start) && isFiniteNumber(w.end) && hour >= w.start && hour < w.end,
+  )
+  return inWindow ? 'peak' : 'offPeak'
+}
+
+/**
+ * Does `provider` route through DeepSeek's own API (as opposed to a
+ * proxy/custom route)? Case-folded: a harness reporting `DeepSeek-Official`
+ * names the same route, and an exact match would leave its calls unpriced.
+ */
+export function isOfficialRoute(provider) {
+  return typeof provider === 'string' && OFFICIAL_PROVIDERS.includes(provider.toLowerCase())
+}
+
+/** A well-formed `{cacheHit, cacheMiss, output}` triple, or `null`. */
+function isRateTriple(triple) {
+  return isPlainObject(triple) && isFiniteNumber(triple.cacheHit) && isFiniteNumber(triple.cacheMiss) && isFiniteNumber(triple.output)
+}
+
+/** Look up `table.models[model]`'s tiered rates for an official-route call, or `null`. */
+function costMeterModelRates(table, model, atMs) {
+  const models = isPlainObject(table.models) ? table.models : null
+  const entry = models === null ? undefined : models[model]
+  if (!isPlainObject(entry) || !isRateTriple(entry.offPeak) || !isRateTriple(entry.peak)) return null
+  const tier = tierAt(atMs, {
+    windows: table.windows,
+    effectiveAtMs: table.effectiveAtMs,
+    peakEnabled: table.peakEnabled !== false,
+  })
+  return { tier, rates: entry[tier] }
+}
+
+/**
+ * Look up `table.providers[provider][model]`'s flat rates, or `null`. The key
+ * is case-folded on both sides (`normalizeCostMeterState` lower-cases what it
+ * stores): the cost-meter table is a foreign schema whose provider ids are
+ * whatever its own user typed, and a casing mismatch must not silently drop
+ * the call through to bundled pricing.
+ */
+function costMeterProviderRates(table, provider, model) {
+  const providers = isPlainObject(table.providers) ? table.providers : null
+  const key = typeof provider === 'string' ? provider.toLowerCase() : provider
+  const providerEntry = providers === null ? undefined : providers[key]
+  const flat = isPlainObject(providerEntry) ? providerEntry[model] : undefined
+  return isRateTriple(flat) ? flat : null
+}
+
+/**
+ * Resolve the price source and rates for one call. Resolution order:
+ * (1) `table.models[model]` when the route is official → `costMeter`, tier
+ *     from `tierAt` using the table's own windows/effectiveAt/peakEnabled;
+ * (2) `table.providers[provider][model]` → `costMeter`, `tier:'flat'`;
+ * (3) the bundled list price, when the route is official and the model is
+ *     known → `bundled`;
+ * (4) `null`.
+ *
+ * Always returns fresh copies of `rates` — never a reference into
+ * `BUNDLED_PRICES` or `table`.
+ */
+export function ratesFor({ model, provider, atMs, table = null }) {
+  if (isPlainObject(table)) {
+    if (isOfficialRoute(provider)) {
+      const found = costMeterModelRates(table, model, atMs)
+      if (found !== null) {
+        return {
+          source: 'costMeter',
+          tier: found.tier,
+          rates: { ...found.rates },
+          asOf: typeof table.asOf === 'string' ? table.asOf : PRICES_AS_OF,
+        }
+      }
+    }
+    const flat = costMeterProviderRates(table, provider, model)
+    if (flat !== null) {
+      return {
+        source: 'costMeter',
+        tier: 'flat',
+        rates: { ...flat },
+        asOf: typeof table.asOf === 'string' ? table.asOf : PRICES_AS_OF,
+      }
+    }
+  }
+
+  if (isOfficialRoute(provider) && Object.prototype.hasOwnProperty.call(BUNDLED_PRICES, model)) {
+    const tier = tierAt(atMs)
+    return {
+      source: 'bundled',
+      tier,
+      rates: { ...BUNDLED_PRICES[model][tier] },
+      asOf: PRICES_AS_OF,
+    }
+  }
+
+  return null
+}
+
+/** Read a usage field as a non-negative finite number, defaulting to 0. */
+function tokensOf(usage, key) {
+  const value = usage === null || typeof usage !== 'object' ? undefined : usage[key]
+  return isFiniteNumber(value) && value >= 0 ? value : 0
+}
+
+/**
+ * USD cost of `usage` at `rates`. `inputTokens` is uncached input, billed at
+ * `cacheMiss`; `cacheReadTokens` + `cacheWriteTokens` bill at `cacheHit`;
+ * `reasoningTokens` is added to output only if {@link REASONING_BILLED_SEPARATELY}.
+ */
+export function costOf(usage, rates) {
+  const input = tokensOf(usage, 'inputTokens')
+  const output = tokensOf(usage, 'outputTokens')
+  const cacheRead = tokensOf(usage, 'cacheReadTokens')
+  const cacheWrite = tokensOf(usage, 'cacheWriteTokens')
+  const reasoning = tokensOf(usage, 'reasoningTokens')
+  const billedOutput = REASONING_BILLED_SEPARATELY ? output + reasoning : output
+  const cacheHitTokens = cacheRead + cacheWrite
+
+  const cacheHit = isFiniteNumber(rates?.cacheHit) ? rates.cacheHit : 0
+  const cacheMiss = isFiniteNumber(rates?.cacheMiss) ? rates.cacheMiss : 0
+  const outputRate = isFiniteNumber(rates?.output) ? rates.output : 0
+
+  return (input * cacheMiss + cacheHitTokens * cacheHit + billedOutput * outputRate) / 1e6
+}
+
+/** Price one call end to end: resolve rates via {@link ratesFor}, then cost via {@link costOf}. */
+export function priceCall({ model, provider, atMs, usage, table = null }) {
+  const priced = ratesFor({ model, provider, atMs, table })
+  if (priced === null) return null
+  return { ...priced, usd: costOf(usage, priced.rates) }
+}
+
+// ── costMeter state normalization ───────────────────────────────────────
+
+const DEFAULT_EXCHANGE_RATE = 7.2
+
+/** A `{cacheHit, cacheMiss, output}` triple, currency-converted; `null` if any rate is invalid. */
+function normalizeTriple(triple, currency, exchangeRate) {
+  if (!isRateTriple(triple) || triple.cacheHit < 0 || triple.cacheMiss < 0 || triple.output < 0) return null
+  const divisor = currency === 'CNY' ? (isPositiveNumber(exchangeRate) ? exchangeRate : DEFAULT_EXCHANGE_RATE) : 1
+  return { cacheHit: triple.cacheHit / divisor, cacheMiss: triple.cacheMiss / divisor, output: triple.output / divisor }
+}
+
+/** A model price entry (`{cacheHit,cacheMiss,output}` or `{offPeak,peak}`) → `{offPeak, peak}`, or `null`. */
+function normalizeModelEntry(entry, currency, exchangeRate) {
+  if (!isPlainObject(entry)) return null
+  if (entry.offPeak !== undefined || entry.peak !== undefined) {
+    const offPeak = normalizeTriple(entry.offPeak, currency, exchangeRate)
+    const peak = normalizeTriple(entry.peak, currency, exchangeRate)
+    return offPeak === null || peak === null ? null : { offPeak, peak }
+  }
+  const flat = normalizeTriple(entry, currency, exchangeRate)
+  return flat === null ? null : { offPeak: flat, peak: { ...flat } }
+}
+
+/** A provider price entry `{input, cachedInput?, output}` → `{cacheMiss, cacheHit, output}`, or `null`. */
+function normalizeProviderModelEntry(entry, currency, exchangeRate) {
+  if (!isPlainObject(entry)) return null
+  const cachedInput = entry.cachedInput !== undefined ? entry.cachedInput : entry.input
+  return normalizeTriple({ cacheMiss: entry.input, cacheHit: cachedInput, output: entry.output }, currency, exchangeRate)
+}
+
+/**
+ * Duck-typed normalization of the `dsh-cost-meter` service state (or its
+ * `config` sub-object) into the shape {@link ratesFor} consumes:
+ * `{models, providers, windows, effectiveAtMs, peakEnabled, asOf}`.
+ * Invalid rates (non-finite or negative) drop the entry that carries them;
+ * a non-object input (or config root) yields `null`.
+ */
+/** Epoch ms from either a number or an ISO-ish date string; 0 when it is neither. */
+function normalizeMoment(value) {
+  if (isFiniteNumber(value)) return value
+  if (typeof value !== 'string' || value.length === 0) return 0
+  const parsed = Date.parse(value)
+  return Number.isFinite(parsed) ? parsed : 0
+}
+
+export function normalizeCostMeterState(state) {
+  if (!isPlainObject(state)) return null
+  const config = isPlainObject(state.config) ? state.config : state
+  if (!isPlainObject(config)) return null
+
+  const prices = isPlainObject(config.prices) ? config.prices : {}
+  const currency = prices.currency === 'CNY' ? 'CNY' : 'USD'
+  const exchangeRate = isPositiveNumber(config.exchangeRate) ? config.exchangeRate : DEFAULT_EXCHANGE_RATE
+
+  const models = {}
+  const rawModels = isPlainObject(prices.models) ? prices.models : {}
+  for (const [id, entry] of Object.entries(rawModels)) {
+    const normalized = normalizeModelEntry(entry, currency, exchangeRate)
+    if (normalized !== null) models[id] = normalized
+  }
+
+  const providers = {}
+  const rawProviders = isPlainObject(prices.providers) ? prices.providers : {}
+  for (const [providerId, providerEntry] of Object.entries(rawProviders)) {
+    if (!isPlainObject(providerEntry)) continue
+    const rawProviderModels = isPlainObject(providerEntry.models) ? providerEntry.models : {}
+    const byModel = {}
+    for (const [modelId, entry] of Object.entries(rawProviderModels)) {
+      const normalized = normalizeProviderModelEntry(entry, currency, exchangeRate)
+      if (normalized !== null) byModel[modelId] = normalized
+    }
+    // Lower-cased so a lookup can match whatever case the caller reports; two
+    // keys differing only by case merge, and the first one listed wins.
+    const key = String(providerId).toLowerCase()
+    if (Object.keys(byModel).length > 0 && providers[key] === undefined) providers[key] = byModel
+  }
+
+  // An array that filters down to nothing says as little as no array at all —
+  // and an empty window list would silently price every call off-peak.
+  const rawWindows = Array.isArray(config.peakWindows)
+    ? config.peakWindows.filter((w) => isPlainObject(w) && isFiniteNumber(w.start) && isFiniteNumber(w.end))
+    : []
+  const windows = rawWindows.length > 0
+    ? rawWindows.map((w) => ({ start: w.start, end: w.end }))
+    : PEAK_WINDOWS_UTC.map((w) => ({ ...w }))
+
+  const effectiveAtMs = normalizeMoment(config.peakEffectiveAt)
+  const peakEnabled = typeof config.peakEnabled === 'boolean' ? config.peakEnabled : true
+
+  return {
+    models,
+    providers,
+    windows,
+    effectiveAtMs,
+    peakEnabled,
+    asOf: new Date().toISOString(),
+  }
+}