dsh-tacit 0.2.2 → 0.3.0

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(),
+  }
+}

package/lib/routes.js

@@ -10,7 +10,14 @@
  * into one ctx.effect so a fiber unload removes every route.
  */
 
-function withService(ctx, serviceName, fn) {
+/**
+ * Run `fn(service)` as soon as `serviceName` exists — immediately when it is
+ * already registered, otherwise once on the next `internal/service` event for
+ * it (the listener removes itself). Exported so the service layer can wait on
+ * optional siblings (e.g. `costMeter`) the same way the routes wait on
+ * `webServer`.
+ */
+export function withService(ctx, serviceName, fn) {
   const existing = ctx.get !== undefined && typeof ctx.get === 'function' ? ctx.get(serviceName) : undefined
   if (existing !== undefined && existing !== null) {
     fn(existing)
@@ -126,18 +133,24 @@ export function registerWebRoutes(ctx, service) {
       }))
     }
 
-    route('POST', '/api/tacit/state', () => service.getState())
+    route('POST', '/api/tacit/state', (body) => service.getState(body))
     route('POST', '/api/tacit/reports', (body) => service.getReports(body))
     route('POST', '/api/tacit/history', (body) => service.listHistory(body))
     route('POST', '/api/tacit/analyze', (body) => service.analyzeTurn(body))
+    route('POST', '/api/tacit/analyze-batch', (body) => service.analyzeBatch(body))
     route('POST', '/api/tacit/improve', (body) => service.improveDraft(body))
     route('POST', '/api/tacit/feedback', (body) => service.feedback(body))
     route('POST', '/api/tacit/applied', (body) => service.applied(body))
     route('POST', '/api/tacit/directives', (body) => service.directives(body))
     route('POST', '/api/tacit/stats', (body) => service.stats(body))
     route('POST', '/api/tacit/bootstrap', (body) => service.bootstrap(body))
+    route('POST', '/api/tacit/bootstrap-preview', (body) => service.bootstrapPreview(body))
     route('POST', '/api/tacit/config', (body) => service.updateConfig(body))
     route('POST', '/api/tacit/clear', () => service.clearReports())
+    route('POST', '/api/tacit/usage', (body) => service.usageReport(body))
+    route('POST', '/api/tacit/usage-run', (body) => service.usageRun(body))
+    route('POST', '/api/tacit/usage-clear', () => service.usageClear())
+    route('POST', '/api/tacit/pricing-refresh', () => service.pricingRefresh())
 
     ctx.effect(() => () => {
       for (const dispose of disposers.splice(0).reverse()) {