@chenmiao8563/dsh-token-ledger 0.1.1 → 0.2.0

package/lib/index.js

@@ -23,6 +23,7 @@
  */
 
 import { UsageLedger, inheritedCut, isForkSession } from './ledger.js'
+import { createOverviewRoute, OVERVIEW_PATH } from './route.js'
 import { ledgerPaths, loadLedger, saveLedger, writeFileAtomic } from './store.js'
 import { join } from 'node:path'
 
@@ -248,6 +249,29 @@ export function apply(ctx, config = {}) {
     })
   }
 
+  // The browser half reads this route, which is a read-only view of the live
+  // ledger. Without a web server the plugin is still fully usable through
+  // /tokens and the CLI, so the service is optional rather than injected.
+  //
+  // Registration is logged because the settings page can only report that it
+  // could not read the route. The log is what distinguishes "this profile has no
+  // web server" from "the route failed to register"; from the browser the two
+  // look identical.
+  if (typeof ctx.inject === 'function') {
+    ctx.inject(['webServer'], (webCtx) => {
+      ctx.effect(() => {
+        const dispose = webCtx.webServer.register(
+          createOverviewRoute({
+            ledger,
+            options: { onError: (error) => log.warn('[token-ledger] overview route failed: %o', error) },
+          }),
+        )
+        log.info('[token-ledger] settings page route ready at %s', OVERVIEW_PATH)
+        return dispose
+      }, 'token-ledger: overview route')
+    })
+  }
+
   if (typeof ctx.effect === 'function') {
     ctx.effect(
       () => () => {

package/lib/overview.js

@@ -0,0 +1,228 @@
+/**
+ * The overview payload the browser half renders.
+ *
+ * Kept separate from the plugin so it is a pure function of a ledger snapshot
+ * and a clock, and therefore testable without a host, a browser or a socket.
+ * The host route is then a thin wrapper: take the live snapshot, call this,
+ * serialize.
+ *
+ * ## Why the payload is shaped like this
+ *
+ * The page the client draws has three parts — range totals, today, and a
+ * calendar. Each is answered here rather than in the browser so the client
+ * stays dumb and two clients cannot disagree:
+ *
+ * - `ranges` carries the totals for the three selectable ranges, plus the
+ *   derived cache-hit rate, so switching a tab is a re-render and not a
+ *   re-fetch.
+ * - `today` carries the current local day's numbers, which is what "live"
+ *   means for a ledger: a value that moves as steps complete.
+ * - `daily` is a **contiguous** day series including zero-token days, because
+ *   a calendar grid needs every cell, and gap-filling in one place is better
+ *   than in every view.
+ *
+ * @module dsh-token-ledger/overview
+ */
+
+/** How many days of daily series to publish, bounding the payload. */
+export const SERIES_DAYS = 366
+
+/**
+ * Render a local calendar day as `YYYY-MM-DD`.
+ *
+ * @param {Date} date - the day.
+ * @returns {string} the key.
+ */
+export function dayKey(date) {
+  const pad = (value) => (value < 10 ? `0${value}` : String(value))
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`
+}
+
+/**
+ * Parse a `YYYY-MM-DD` key back into a local midnight `Date`.
+ *
+ * @param {string} key - the day key.
+ * @returns {Date} local midnight of that day.
+ */
+export function parseDayKey(key) {
+  const [year, month, day] = String(key).split('-').map((part) => Number.parseInt(part, 10))
+  return new Date(year, (month ?? 1) - 1, day ?? 1)
+}
+
+/**
+ * The local date a range starts on.
+ *
+ * `week` is the trailing seven days including today, because "7 天" reads as a
+ * rolling window; `month` and `year` are calendar periods, because "本月" and
+ * "本年" read as the period you are in.
+ *
+ * @param {'week'|'month'|'year'} kind - the range.
+ * @param {Date} now - the current time.
+ * @returns {Date} local midnight of the first day in range.
+ */
+export function rangeStart(kind, now) {
+  if (kind === 'week') {
+    const start = new Date(now.getFullYear(), now.getMonth(), now.getDate())
+    start.setDate(start.getDate() - 6)
+    return start
+  }
+  if (kind === 'month') return new Date(now.getFullYear(), now.getMonth(), 1)
+  if (kind === 'year') return new Date(now.getFullYear(), 0, 1)
+  throw new Error(`unknown range "${kind}" (expected week, month, or year)`)
+}
+
+/**
+ * An empty counter set in the shape the ledger emits.
+ *
+ * @returns {{ inputTokens: number, outputTokens: number, cacheReadTokens: number, cacheWriteTokens: number, totalTokens: number, reasoningTokens: number }} zeroed counters.
+ */
+function emptyTotals() {
+  return {
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+    totalTokens: 0,
+    reasoningTokens: 0,
+  }
+}
+
+/**
+ * Add one day row into an accumulator.
+ *
+ * @param {ReturnType<typeof emptyTotals>} target - mutated accumulator.
+ * @param {object} row - a ledger daily row.
+ * @returns {void}
+ */
+function accumulate(target, row) {
+  for (const key of ['inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTokens', 'totalTokens', 'reasoningTokens']) {
+    const value = row?.[key]
+    if (typeof value === 'number' && Number.isFinite(value)) target[key] += value
+  }
+}
+
+/**
+ * The share of input tokens served from the prompt cache.
+ *
+ * Defined over input only: a cache read is an input token that did not have to
+ * be re-sent, so `cacheRead / (cacheRead + uncachedInput)` is the fraction of
+ * input the cache absorbed. Returns `null` when there was no input at all,
+ * which the client renders as a dash rather than as a misleading 0%.
+ *
+ * @param {{ inputTokens: number, cacheReadTokens: number }} totals - the counters.
+ * @returns {number|null} a fraction between 0 and 1, or null when undefined.
+ */
+export function cacheHitRate(totals) {
+  const denominator = (totals.cacheReadTokens ?? 0) + (totals.inputTokens ?? 0)
+  if (denominator <= 0) return null
+  return totals.cacheReadTokens / denominator
+}
+
+/**
+ * Fold a set of day rows into one range summary.
+ *
+ * @param {object[]} rows - day rows inside the range.
+ * @returns {{ totals: ReturnType<typeof emptyTotals>, calls: number, activeDays: number, cacheHitRate: number|null }} the summary.
+ */
+export function summarize(rows) {
+  const totals = emptyTotals()
+  let calls = 0
+  let activeDays = 0
+  for (const row of rows) {
+    accumulate(totals, row)
+    if (typeof row?.calls === 'number' && Number.isFinite(row.calls)) calls += row.calls
+    if ((row?.totalTokens ?? 0) > 0) activeDays += 1
+  }
+  return { totals, calls, activeDays, cacheHitRate: cacheHitRate(totals) }
+}
+
+/**
+ * A contiguous day series ending today, gaps filled with zeroes.
+ *
+ * @param {Map<string, object>} byDay - ledger daily rows keyed by day.
+ * @param {Date} now - the current time.
+ * @param {number} [limit] - maximum number of days emitted.
+ * @returns {object[]} ascending day rows, one per calendar day.
+ */
+export function buildSeries(byDay, now, limit = SERIES_DAYS) {
+  const today = new Date(now.getFullYear(), now.getMonth(), now.getDate())
+  const keys = [...byDay.keys()].sort()
+  const earliest = keys.length > 0 ? parseDayKey(keys[0]) : today
+  const span = Math.min(limit, Math.max(1, Math.round((today - earliest) / 86400000) + 1))
+
+  const series = []
+  for (let offset = span - 1; offset >= 0; offset -= 1) {
+    const date = new Date(today.getFullYear(), today.getMonth(), today.getDate() - offset)
+    const key = dayKey(date)
+    const row = byDay.get(key)
+    series.push({
+      date: key,
+      calls: typeof row?.calls === 'number' ? row.calls : 0,
+      inputTokens: row?.inputTokens ?? 0,
+      outputTokens: row?.outputTokens ?? 0,
+      cacheReadTokens: row?.cacheReadTokens ?? 0,
+      cacheWriteTokens: row?.cacheWriteTokens ?? 0,
+      totalTokens: row?.totalTokens ?? 0,
+      reasoningTokens: row?.reasoningTokens ?? 0,
+    })
+  }
+  return series
+}
+
+/**
+ * Build the whole overview payload.
+ *
+ * @param {object} snapshot - a `UsageLedger#snapshot()` value.
+ * @param {{ now?: Date }} [options] - clock override for tests.
+ * @returns {object} the JSON payload the client renders. Every field is a
+ *   primitive, a plain object or an array, so it serializes losslessly.
+ */
+export function buildOverview(snapshot, { now = new Date() } = {}) {
+  const dailyRows = Array.isArray(snapshot?.daily) ? snapshot.daily : []
+  const byDay = new Map()
+  for (const row of dailyRows) {
+    if (typeof row?.date === 'string') byDay.set(row.date, row)
+  }
+
+  const series = buildSeries(byDay, now)
+  const todayKey = dayKey(now)
+
+  const ranges = {}
+  for (const kind of ['week', 'month', 'year']) {
+    const startKey = dayKey(rangeStart(kind, now))
+    const inRange = [...byDay.entries()]
+      .filter(([key]) => key >= startKey && key <= todayKey)
+      .map(([, row]) => row)
+    ranges[kind] = { kind, from: startKey, to: todayKey, ...summarize(inRange) }
+  }
+
+  const todayRow = byDay.get(todayKey)
+  const todaySummary = summarize(todayRow === undefined ? [] : [todayRow])
+
+  const models = (Array.isArray(snapshot?.models) ? snapshot.models : [])
+    .slice(0, 12)
+    .map((model) => ({
+      model: String(model?.model ?? 'unknown'),
+      calls: typeof model?.calls === 'number' ? model.calls : 0,
+      totalTokens: model?.totalTokens ?? 0,
+      cacheReadTokens: model?.cacheReadTokens ?? 0,
+      inputTokens: model?.inputTokens ?? 0,
+      cacheHitRate: cacheHitRate({ cacheReadTokens: model?.cacheReadTokens ?? 0, inputTokens: model?.inputTokens ?? 0 }),
+    }))
+
+  return {
+    plugin: 'token-ledger',
+    generatedAt: now.getTime(),
+    ledgerUpdatedAt: typeof snapshot?.updatedAt === 'number' ? snapshot.updatedAt : null,
+    totals: {
+      ...emptyTotals(),
+      ...(snapshot?.totals ?? {}),
+      cacheHitRate: cacheHitRate(snapshot?.totals ?? {}),
+    },
+    ranges,
+    today: { date: todayKey, lastEventAt: typeof snapshot?.updatedAt === 'number' ? snapshot.updatedAt : null, ...todaySummary },
+    series,
+    models,
+    sessionCount: Array.isArray(snapshot?.sessions) ? snapshot.sessions.length : 0,
+  }
+}

package/lib/route.js

@@ -0,0 +1,141 @@
+/**
+ * The host route that feeds the browser half.
+ *
+ * ## Why a route instead of the settings namespace
+ *
+ * The obvious channel for plugin data is a settings namespace, and the reference
+ * UI plugins use one. This plugin deliberately does not, for two reasons:
+ *
+ * 1. A settings namespace needs a schema, and the schema library is a real
+ *    dependency. This package's whole installability claim is that it has none.
+ * 2. Settings are persisted. Publishing token aggregates through them would
+ *    rewrite `settings.yaml` on every debounce and grow it with data that is
+ *    derived and reproducible, which is exactly the mistake that left a 185 kB
+ *    settings backup on the machine this was developed against.
+ *
+ * The ledger file stays the store of record; this route is a read-only view of
+ * the live in-memory ledger.
+ *
+ * ## The guard
+ *
+ * The route exposes local usage counts, which are not secrets but are also
+ * nobody else's business. The web server binds loopback by default, but an
+ * operator may bind `0.0.0.0`, so the handler checks the peer itself: an
+ * address is accepted only when it is loopback, and an `Origin` header is
+ * accepted only when it is loopback or absent.
+ *
+ * Absent is allowed because the desktop build loads the front end over
+ * `file://` and carries `fetch` over an IPC bridge, where a socket address may
+ * be unavailable. Refusing that case would break the desktop app to protect
+ * against a request that never left the machine.
+ *
+ * @module dsh-token-ledger/route
+ */
+
+import { buildOverview } from './overview.js'
+
+/** The path the browser half fetches. */
+export const OVERVIEW_PATH = '/api/token-ledger/summary'
+
+/**
+ * Whether a peer address is loopback.
+ *
+ * @param {string|undefined} address - `req.socket.remoteAddress`.
+ * @returns {boolean} true for IPv4 or IPv6 loopback.
+ */
+export function isLoopbackAddress(address) {
+  if (typeof address !== 'string') return false
+  return address === '127.0.0.1' || address === '::1' || address === '::ffff:127.0.0.1'
+}
+
+/**
+ * Whether an `Origin` header belongs to a local page.
+ *
+ * @param {string|undefined} origin - the header value.
+ * @returns {boolean} true when absent, `null`, `file://`, or a loopback host.
+ */
+export function isLocalOrigin(origin) {
+  if (origin === undefined || origin === '' || origin === 'null') return true
+  if (origin.startsWith('file://')) return true
+  try {
+    const url = new URL(origin)
+    // WHATWG URL keeps the brackets on an IPv6 host: `new URL('http://[::1]/').hostname`
+    // is `'[::1]'`, so they have to come off before comparing.
+    const hostname = url.hostname.replace(/^\[|\]$/g, '')
+    return hostname === '127.0.0.1' || hostname === '::1' || hostname === 'localhost'
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Decide whether a request may read the overview.
+ *
+ * @param {object} req - a node `IncomingMessage`-shaped object.
+ * @returns {boolean} whether to serve it.
+ */
+export function isAllowedPeer(req) {
+  const address = req?.socket?.remoteAddress
+  // An unrecognized address means the request did not arrive over a socket we
+  // can judge (the desktop IPC bridge), not that it came from a stranger.
+  if (typeof address === 'string' && address !== '' && !isLoopbackAddress(address)) return false
+  return isLocalOrigin(req?.headers?.origin)
+}
+
+/**
+ * Write a JSON response.
+ *
+ * @param {object} res - a node `ServerResponse`-shaped object.
+ * @param {number} status - the HTTP status.
+ * @param {unknown} body - the JSON value.
+ * @returns {void}
+ */
+function sendJson(res, status, body) {
+  const text = JSON.stringify(body)
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'content-length': Buffer.byteLength(text),
+    // The numbers move as steps complete, so a cached copy is always wrong.
+    'cache-control': 'no-store',
+  })
+  res.end(text)
+}
+
+/**
+ * Build the route definition to hand to `ctx.webServer.register`.
+ *
+ * The handler never throws: a fault becomes a 500 with a JSON body, because the
+ * web server logs a warning and destroys the socket when a handler throws, and
+ * a client that cannot reach the plugin should be able to say why.
+ *
+ * @param {object} input - the route's dependencies.
+ * @param {{ snapshot: () => object }} input.ledger - the live ledger.
+ * @param {{ now?: () => Date, onError?: (error: unknown) => void }} [input.options] - clock and diagnostics.
+ * @returns {{ kind: 'exact', path: string, handler: (req: object, res: object) => void }} the route.
+ */
+export function createOverviewRoute({ ledger, options = {} }) {
+  const now = options.now ?? (() => new Date())
+  const onError = options.onError ?? (() => {})
+
+  return {
+    kind: 'exact',
+    path: OVERVIEW_PATH,
+    handler: (req, res) => {
+      if (!isAllowedPeer(req)) {
+        sendJson(res, 403, { error: 'forbidden' })
+        return
+      }
+      const method = req?.method ?? 'GET'
+      if (method !== 'GET' && method !== 'HEAD') {
+        sendJson(res, 405, { error: 'method not allowed' })
+        return
+      }
+      try {
+        sendJson(res, 200, buildOverview(ledger.snapshot(), { now: now() }))
+      } catch (error) {
+        onError(error)
+        sendJson(res, 500, { error: 'overview unavailable' })
+      }
+    },
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chenmiao8563/dsh-token-ledger",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Transparent, auditable token accounting for DeepSeek Harness: a restart-safe ledger over the durable session log, plus a CLI that recomputes it from raw logs and diffs the result.",
   "keywords": [
     "dsh",
@@ -26,6 +26,9 @@
     "./ledger": "./lib/ledger.js",
     "./session-log": "./lib/session-log.js",
     "./store": "./lib/store.js",
+    "./overview": "./lib/overview.js",
+    "./route": "./lib/route.js",
+    "./client": "./lib/client.js",
     "./cordis.patch.yml": "./cordis.patch.yml",
     "./package.json": "./package.json"
   },
@@ -52,11 +55,23 @@
     "verify": "node scripts/verify-package.mjs",
     "prepublishOnly": "npm run verify && npm test"
   },
+  "devDependencies": {
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.2-rc.1",
+    "react": "18.3.1",
+    "react-dom": "18.3.1"
+  },
   "dsh": {
     "pluginType": "feature",
     "bundle": {
       "patch": "./cordis.patch.yml"
     },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-settings-general"
+      ]
+    },
     "compatibility": {
       "dsh": ">=0.1.2-alpha.1"
     }