dsh-all-usage 1.1.2 → 1.1.4

package/lib/usage-core.js

@@ -0,0 +1,171 @@
+const TOKEN_FIELDS = Object.freeze({
+  input: 'inputTokens',
+  output: 'outputTokens',
+  cacheRead: 'cacheReadTokens',
+  cacheWrite: 'cacheWriteTokens',
+  reasoning: 'reasoningTokens',
+})
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+export function validEventTime(value) {
+  return typeof value === 'number' && Number.isFinite(value) && Math.abs(value) <= 8640000000000000
+}
+
+function tokenValue(source, field) {
+  const value = source[TOKEN_FIELDS[field]] !== undefined ? source[TOKEN_FIELDS[field]] : source[field]
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : 0
+}
+
+export function normalizeUsageValues(usage) {
+  if (!isRecord(usage)) return null
+  return {
+    input: tokenValue(usage, 'input'),
+    output: tokenValue(usage, 'output'),
+    cacheRead: tokenValue(usage, 'cacheRead'),
+    cacheWrite: tokenValue(usage, 'cacheWrite'),
+    reasoning: tokenValue(usage, 'reasoning'),
+  }
+}
+
+export function hasUsageValues(values) {
+  return values !== null && values !== undefined && (values.input > 0 || values.output > 0 || values.cacheRead > 0 || values.cacheWrite > 0 || values.reasoning > 0)
+}
+
+function stepIndex(value) {
+  return Number.isSafeInteger(value) && value >= 0 ? value : null
+}
+
+/** Extract the provider usage carried by one supported DSH event shape. */
+export function extractUsageEvent(event) {
+  if (!isRecord(event) || !isRecord(event.data) || !validEventTime(event.time)) return null
+  const data = event.data
+  let kind
+  let usage
+  if (event.type === 'assistant/chunk') {
+    if (!isRecord(data.chunk) || data.chunk.type !== 'usage') return null
+    kind = 'chunk'
+    usage = data.chunk.usage
+  } else if (event.type === 'assistant/message') {
+    if (!Object.hasOwn(data, 'usage') || data.usage === undefined) return null
+    kind = 'message'
+    usage = data.usage
+  } else {
+    return null
+  }
+  const values = normalizeUsageValues(usage)
+  if (!hasUsageValues(values)) return null
+  const turn = stepIndex(data.turn)
+  const step = stepIndex(data.step)
+  if (turn === null || step === null) return null
+  return { kind, data, usage, values, turn, step }
+}
+
+function stableJson(value, ancestors = new Set()) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean' || typeof value === 'number') return JSON.stringify(value)
+  if (value === undefined) return 'null'
+  if (typeof value !== 'object') return JSON.stringify(String(value))
+  if (ancestors.has(value)) return '"[Circular]"'
+  ancestors.add(value)
+  let result
+  if (Array.isArray(value)) {
+    result = '[' + value.map((item) => stableJson(item, ancestors)).join(',') + ']'
+  } else {
+    result = '{' + Object.keys(value).sort().map((key) => JSON.stringify(key) + ':' + stableJson(value[key], ancestors)).join(',') + '}'
+  }
+  ancestors.delete(value)
+  return result
+}
+
+function stableIdentity(value) {
+  if (typeof value === 'string' && value.trim() !== '') return value.trim()
+  if (typeof value === 'number' && Number.isFinite(value)) return String(value)
+  return null
+}
+
+/** Build a stable logical usage key across live, scan, and flush materializations. */
+export function usageStepKey(sid, data, seq, fallback) {
+  const safeSid = typeof sid === 'string' ? sid : String(sid === undefined || sid === null ? '' : sid)
+  const turn = stepIndex(data && data.turn)
+  const step = stepIndex(data && data.step)
+  if (turn !== null && step !== null) return safeSid + ':step:' + turn + ':' + step
+  const message = data && isRecord(data.message) ? data.message : null
+  const logicalId = [
+    data && data.usageId,
+    data && data.sampleId,
+    data && data.requestId,
+    data && data.callId,
+    data && data.stepId,
+    data && data.messageId,
+    message && message.id,
+  ].map(stableIdentity).find((value) => value !== null)
+  if (logicalId !== undefined) return safeSid + ':logical:' + logicalId
+  if (Number.isSafeInteger(seq) && seq >= 0) return safeSid + ':event:' + seq
+  const serialized = stableJson(isRecord(data) ? data : {})
+  return safeSid + ':event:' + (serialized === undefined ? String(fallback === undefined ? '' : fallback) : serialized)
+}
+
+/** Recalculate the billing instant for a re-priced sample, preferring the recorded request time. */
+export function billingInstantOf(item, oldCost) {
+  const oldAt = oldCost != null && Number.isFinite(oldCost.pricingAt) ? oldCost.pricingAt : null
+  const at = Number.isFinite(item.pricingAt) ? item.pricingAt : oldAt !== null ? oldAt : validEventTime(item.time) ? item.time : null
+  const oldSource = oldCost != null && (oldCost.pricingTimeSource === 'request-context' || oldCost.pricingTimeSource === 'usage-event') ? oldCost.pricingTimeSource : null
+  const source = typeof item.pricingTimeSource === 'string' && (item.pricingTimeSource === 'request-context' || item.pricingTimeSource === 'usage-event') ? item.pricingTimeSource : (oldSource || 'usage-event')
+  return { at, source }
+}
+
+/** Bounded context archive shared by the live fold and the persisted ledger. */
+export const MAX_CONTEXT_TIMES = 512
+
+/** Insert-or-refresh a context entry with real LRU eviction (delete + set). */
+export function touchContextTimes(times, key, time) {
+  if (typeof key !== 'string' || key === '') return
+  if (times.has(key)) times.delete(key)
+  times.set(key, time)
+  while (times.size > MAX_CONTEXT_TIMES) times.delete(times.keys().next().value)
+}
+
+/** Stable per-(turn, step) key for the pricing-time context of a request. */
+export function contextTimeKey(turn, step) {
+  const safeTurn = Number.isSafeInteger(turn) && turn >= 0 ? turn : null
+  const safeStep = Number.isSafeInteger(step) && step >= 0 ? step : null
+  if (safeTurn !== null && safeStep !== null) return 'context:' + safeTurn + ':' + safeStep
+  return 'context:__latest__'
+}
+
+/**
+ * Pick the billing instant for a usage event: the request/context time that
+ * matches the same turn/step wins (parallel requests stay per-step), otherwise
+ * the usage event time itself is the auditable fallback.
+ */
+export function pickPricingTime(contextTimes, eventTime, turn, step) {
+  if (contextTimes instanceof Map && validEventTime(eventTime)) {
+    const exact = contextTimes.get(contextTimeKey(turn, step))
+    const candidate = exact !== undefined ? exact : contextTimes.get(contextTimeKey(null, null))
+    if (Number.isFinite(candidate) && candidate <= eventTime) {
+      return { time: candidate, source: 'request-context' }
+    }
+  }
+  return { time: Number.isFinite(eventTime) && eventTime >= 0 ? eventTime : null, source: 'usage-event' }
+}
+
+/** Replace one logical sample; stale lower-seq replays are ignored. */
+/** Event sequence contract: -1 (missing) or a non-negative safe integer. */
+export function normalizeEventSeq(value) {
+  return Number.isSafeInteger(value) && value >= 0 ? value : -1
+}
+
+export function upsertUsageSample(samples, sample) {
+  if (!(samples instanceof Map) || !isRecord(sample) || typeof sample.key !== 'string' || sample.key === '') return { accepted: false, reason: 'invalid-sample', previous: undefined, next: undefined }
+  const previous = samples.get(sample.key)
+  const seq = normalizeEventSeq(sample.seq)
+  const previousSeq = normalizeEventSeq(previous === undefined ? -1 : previous.seq)
+  if (previous !== undefined && seq >= 0 && previousSeq > seq) return { accepted: false, reason: 'stale-sample', key: sample.key, previous, next: previous }
+  const next = { ...sample, seq }
+  samples.set(sample.key, next)
+  return { accepted: true, replaced: previous !== undefined, key: sample.key, previous, next }
+}
+
+export { TOKEN_FIELDS }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-all-usage",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "DeepSeek Harness usage dashboard with model, provider, workspace, cache, balance, and CSV insights",
   "repository": {
     "type": "git",
@@ -8,8 +8,16 @@
   },
   "homepage": "https://github.com/ParticleLight/dsh-all-usage#readme",
   "type": "module",
+  "engines": {
+    "node": ">=22 <25"
+  },
   "scripts": {
-    "test": "node --test"
+    "build:client": "node scripts/build-client.mjs",
+    "test": "node --test",
+    "fixture:check": "node scripts/replay-fixture.mjs fixtures/usage-events.json",
+    "test:runtime": "node --test test/dsh-runtime.test.js",
+    "check:pack": "node scripts/check-package.mjs",
+    "prepack": "npm run build:client"
   },
   "main": "lib/index.js",
   "exports": {
@@ -22,6 +30,10 @@
     "./package.json": "./package.json"
   },
   "dsh": {
+    "compatibility": {
+      "runtime": ">=0.1.1-rc.1 <0.1.2",
+      "verified": ["0.1.1-rc.2", "0.1.1-rc.1"]
+    },
     "bundle": {
       "patch": "./cordis.patch.yml"
     },
@@ -36,11 +48,21 @@
   },
   "files": [
     "lib/index.js",
+    "lib/plugin.js",
+    "lib/aggregation.js",
+    "lib/ledger.js",
+    "lib/session-sync.js",
+    "lib/pricing-runtime.js",
+    "lib/balance.js",
+    "lib/http.js",
     "lib/client.js",
     "lib/pricing.js",
+    "lib/usage-core.js",
     "CHANGELOG.md",
     "cordis.patch.yml",
     "screenshots.json",
+    "fixtures/usage-events.json",
+    "scripts/replay-fixture.mjs",
     "assets"
   ],
   "keywords": [
@@ -53,5 +75,8 @@
     "tokens",
     "balance"
   ],
-  "license": "MIT"
+  "license": "MIT",
+  "devDependencies": {
+    "terser": "5.51.2"
+  }
 }

package/scripts/replay-fixture.mjs

@@ -0,0 +1,155 @@
+import assert from 'node:assert/strict'
+import { readFile } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { apply } from '../lib/index.js'
+
+const PACKAGE_ROOT = fileURLToPath(new URL('..', import.meta.url))
+
+function makeResponse() {
+  let body = ''
+  const headers = {}
+  return {
+    res: {
+      statusCode: 200,
+      setHeader(name, value) {
+        headers[String(name).toLowerCase()] = value
+      },
+      end(value = '') {
+        body += String(value)
+      },
+    },
+    body: () => body,
+  }
+}
+
+function makeRequest(url) {
+  return {
+    method: 'GET',
+    url,
+    headers: { host: '127.0.0.1:3080' },
+    socket: { remoteAddress: '127.0.0.1' },
+    on(event, callback) {
+      if (event === 'end') callback()
+      return this
+    },
+  }
+}
+
+function createHarness(fixture) {
+  const routes = new Map()
+  const listeners = new Map()
+  const cleanups = []
+  const webServer = {
+    register(route) {
+      routes.set(route.path, route.handler)
+      return () => routes.delete(route.path)
+    },
+  }
+  const ctx = {
+    sessionQuery: {
+      async listSessions() {
+        return fixture.sessions
+      },
+      async readSession(sessionId) {
+        return { events: fixture.events[sessionId] || [] }
+      },
+    },
+    workspaceRegistry: {
+      list() {
+        return fixture.workspaces
+      },
+    },
+    async timeout() {},
+    on(name, handler) {
+      const current = listeners.get(name) || []
+      current.push(handler)
+      listeners.set(name, current)
+    },
+    effect(factory) {
+      const cleanup = factory()
+      if (typeof cleanup === 'function') cleanups.push(cleanup)
+      return cleanup
+    },
+    get(name) {
+      return name === 'webServer' ? webServer : undefined
+    },
+  }
+  return { ctx, routes, cleanups, listeners }
+}
+
+async function invoke(harness, url) {
+  const pathname = new URL(url || '/', 'http://fixture.local').pathname
+  const handler = harness.routes.get(pathname)
+  assert.equal(typeof handler, 'function', 'fixture route should be registered: ' + pathname)
+  const response = makeResponse()
+  await handler(makeRequest(url), response.res)
+  return { status: response.res.statusCode, body: JSON.parse(response.body()) }
+}
+
+function projectModel(row) {
+  return {
+    provider: row.provider,
+    requestedModel: row.requestedModel,
+    actualModel: row.actualModel,
+    calls: row.calls,
+    input: row.input,
+    output: row.output,
+    cacheRead: row.cacheRead,
+    cacheWrite: row.cacheWrite,
+    reasoning: row.reasoning,
+  }
+}
+
+function assertExpected(fixture, snapshot, records) {
+  const expected = fixture.expected
+  const totals = snapshot.totals
+  assert.deepEqual({
+    turns: totals.turns,
+    sessions: totals.sessions,
+    input: totals.input,
+    output: totals.output,
+    cacheRead: totals.cacheRead,
+    cacheWrite: totals.cacheWrite,
+    reasoning: totals.reasoning,
+  }, expected.totals)
+  assert.equal(records.items.length, expected.records)
+  assert.deepEqual(snapshot.perModel.map(projectModel).sort((left, right) => String(left.provider).localeCompare(String(right.provider))), expected.models)
+  assert.equal(totals.cost.unpricedCalls + totals.cost.ambiguousCalls + totals.cost.unsupportedCalls + totals.cost.pricedCalls, expected.records)
+}
+
+export async function runFixture(fixture) {
+  assert.equal(fixture.schemaVersion, 1)
+  const harness = createHarness(fixture)
+  apply(harness.ctx)
+  try {
+    let snapshot = null
+    for (let attempt = 0; attempt < 200; attempt += 1) {
+      snapshot = await invoke(harness, '/api/all-usage')
+      if (snapshot.status === 200 && snapshot.body.scan.done === true) break
+      await new Promise((resolvePromise) => setImmediate(resolvePromise))
+    }
+    assert.ok(snapshot && snapshot.body && snapshot.body.scan.done === true, 'fixture scan did not complete')
+    const records = await invoke(harness, '/api/all-usage/records?start=' + fixture.query.start + '&end=' + fixture.query.end + '&utc=' + fixture.query.utc + '&limit=200')
+    assert.equal(records.status, 200)
+    assertExpected(fixture, snapshot.body, records.body)
+    return {
+      fixture: fixture.name,
+      totals: snapshot.body.totals,
+      models: snapshot.body.perModel.map(projectModel),
+      records: records.body.items.length,
+    }
+  } finally {
+    for (const cleanup of harness.cleanups.slice().reverse()) await cleanup()
+  }
+}
+
+async function main() {
+  const fixturePath = process.argv[2] === undefined ? join(PACKAGE_ROOT, 'fixtures', 'usage-events.json') : resolve(process.argv[2])
+  const fixture = JSON.parse(await readFile(fixturePath, 'utf8'))
+  const result = await runFixture(fixture)
+  console.log(JSON.stringify(result, null, 2))
+}
+
+const invokedPath = process.argv[1] === undefined ? null : pathToFileURL(resolve(process.argv[1])).href
+if (invokedPath === import.meta.url) await main()