dsh-tokenlens 1.0.9 → 1.2.0

package/index.js

@@ -71,7 +71,7 @@ export const inject = []
 export const PLUGIN_NAME = 'dsh-tokenlens'
 
 /** Plugin version; mirrors package.json (kept here so diagnostics need no fs read). */
-export const PLUGIN_VERSION = '1.0.9'
+export const PLUGIN_VERSION = '1.2.0'
 
 /** Documented defaults; every field of the raw row config is optional. */
 const DEFAULTS = {
@@ -926,6 +926,49 @@ export function apply(ctx, rawConfig) {
       }
       provider = { ...provider, accessKeyId: accessValue, secretAccessKey: secretValue }
       keyInfo = { ref: accessRef, source: access.source, detail: access.detail }
+    } else if (adapterId === 'open-design') {
+      const workspaceId =
+        String(provider.workspaceId ?? '').trim() || String(process.env.OPENDESIGN_WORKSPACE_ID ?? '').trim()
+      const refs = []
+      for (const ref of [provider.controlKeyRef, 'OPENDESIGN_CONTROL_KEY', 'VELA_CONTROL_KEY']) {
+        if (typeof ref === 'string' && ref.trim() !== '' && !refs.includes(ref.trim())) refs.push(ref.trim())
+      }
+      // The management page's per-provider key field holds the Control Key here
+      // (the inference API key cannot query billing).
+      let controlKey = typeof provider.apiKey === 'string' ? provider.apiKey.trim() : ''
+      let controlRef = refs[0] ?? 'OPENDESIGN_CONTROL_KEY'
+      let controlSource = controlKey === '' ? 'none' : 'config'
+      let controlDetail = controlKey === '' ? 'no OpenDesign control key found' : 'plugin config'
+      if (controlKey === '') {
+        for (const ref of refs) {
+          const resolved = await resolveApiKey({
+            config: { apiKeyRef: ref },
+            credentials: ctx.get('credentials'),
+            env: process.env,
+          })
+          const value = typeof resolved.value === 'string' ? resolved.value.trim() : ''
+          if (value === '') continue
+          controlKey = value
+          controlRef = resolved.ref ?? ref
+          controlSource = resolved.source
+          controlDetail = resolved.detail
+          break
+        }
+      }
+      if (workspaceId === '') {
+        throw new UsageError(
+          'missing-key',
+          'OpenDesign quota needs a workspace id (providers.open-design.workspaceId or OPENDESIGN_WORKSPACE_ID)',
+          { retryable: false },
+        )
+      }
+      if (controlKey === '') {
+        throw new UsageError('missing-key', `OpenDesign quota needs a Control Key (${refs.join(' / ')})`, {
+          retryable: false,
+        })
+      }
+      provider = { ...provider, workspaceId, controlKey }
+      keyInfo = { ref: controlRef, source: controlSource, detail: controlDetail }
     } else if (typeof provider.apiKeyRef === 'string' && provider.apiKeyRef.trim() !== '') {
       const key = await resolveApiKey({
         config: { apiKeyRef: provider.apiKeyRef, apiKey: provider.apiKey ?? '' },

package/lib/providers.mjs

@@ -236,12 +236,16 @@ export const PROVIDER_DEFAULTS = {
     consoleUrl: 'https://agnes.ai',
   },
   'open-design': {
-    kind: 'balance',
+    kind: 'windows',
     label: 'Open Design',
     shortLabel: 'OD',
-    baseURL: 'https://api.open-design.ai',
-    apiKeyRef: 'OPEN_DESIGN_API_KEY',
-    consoleUrl: 'https://open-design.ai',
+    baseURL: 'https://amr-api.open-design.ai',
+    // The read-only billing API is scoped to one workspace and authenticated
+    // with a Control Key (not the inference API key used for model calls).
+    workspaceId: '',
+    controlKeyRef: 'OPENDESIGN_CONTROL_KEY',
+    apiKeyRef: 'OPENDESIGN_CONTROL_KEY',
+    consoleUrl: 'https://open-design.ai/cloud/dashboard',
   },
   hunyuan: {
     kind: 'balance',
@@ -753,6 +757,119 @@ export function parseVolcenginePlan(payload, now = Date.now()) {
   return { windows, plan: tier === null ? null : { id: tier, label: tier } }
 }
 
+/**
+ * OpenDesign Design Plan window seconds → the canonical window id.
+ *
+ * Design Plan allowances are independent simultaneous limits; Go has both a
+ * 5-hour and a 7-day window, while Plus/Pro/Max only have the 7-day one. Any
+ * other duration is not one of the plugin's canonical windows.
+ */
+const OPEN_DESIGN_WINDOW_SECONDS = {
+  18000: 'rolling',
+  604800: 'weekly',
+  2592000: 'monthly',
+}
+
+/** A non-negative integer credit amount serialized as a decimal string. */
+function openDesignCredits(value) {
+  return typeof value === 'string' && /^\d{1,40}$/.test(value) ? BigInt(value) : null
+}
+
+/**
+ * Parse the OpenDesign `billing/coding-plan-usage` document.
+ *
+ * Shape (v1, verified against the official Vela billing adapter):
+ * `{ workspaceId, workspaceMemberId?, eligible, windows: [{ policyId,
+ *    durationSeconds, usedCredits, remainingCredits, limitCredits, resetsAt }] }`
+ * where the credits are decimal strings and `resetsAt` is ISO (or null).
+ * A window's percentage is `used / limit`, capped at 100%; unknown durations
+ * and repeated durations keep only the first canonical window.
+ */
+export function parseOpenDesignUsage(payload, workspaceId, now = Date.now()) {
+  const document = payload !== null && typeof payload === 'object' && !Array.isArray(payload) ? payload : null
+  if (document === null) throw new UsageError('parse', 'the OpenDesign quota response is not an object')
+  const expected = String(workspaceId ?? '').trim()
+  if (typeof document.workspaceId !== 'string' || document.workspaceId !== expected) {
+    throw new UsageError('parse', 'the OpenDesign quota response belongs to a different workspace')
+  }
+  if (typeof document.eligible !== 'boolean') {
+    throw new UsageError('parse', 'the OpenDesign quota response has no eligibility flag')
+  }
+  if (!Array.isArray(document.windows) || document.windows.length > 32) {
+    throw new UsageError('parse', 'the OpenDesign quota response has an invalid windows array')
+  }
+  const inputs = {}
+  const seenPolicies = new Set()
+  for (const row of document.windows) {
+    if (row === null || typeof row !== 'object') {
+      throw new UsageError('parse', 'the OpenDesign quota response has a malformed window')
+    }
+    if (typeof row.policyId !== 'string' || row.policyId === '' || seenPolicies.has(row.policyId)) {
+      throw new UsageError('parse', 'the OpenDesign quota response has an empty or duplicate policy id')
+    }
+    seenPolicies.add(row.policyId)
+    if (!Number.isSafeInteger(row.durationSeconds) || row.durationSeconds <= 0) {
+      throw new UsageError('parse', 'the OpenDesign quota window has no duration')
+    }
+    const used = openDesignCredits(row.usedCredits)
+    const limit = openDesignCredits(row.limitCredits)
+    const remaining = openDesignCredits(row.remainingCredits)
+    if (used === null || limit === null || remaining === null) {
+      throw new UsageError('parse', 'the OpenDesign quota window has invalid credit amounts')
+    }
+    const id = OPEN_DESIGN_WINDOW_SECONDS[row.durationSeconds]
+    if (id === undefined || inputs[id] !== undefined) continue
+    if (limit <= 0n) continue
+    const cappedUsed = used > limit ? limit : used
+    const percent = (Number(cappedUsed) / Number(limit)) * 100
+    inputs[id] = {
+      percent,
+      status: 'ok',
+      resetsAt:
+        typeof row.resetsAt === 'string' || typeof row.resetsAt === 'number' ? row.resetsAt : undefined,
+    }
+  }
+  const windows = windowSet(inputs, now)
+  const usable = WINDOW_IDS.some((id) => windows[id] !== null)
+  if (document.eligible === false) {
+    if (usable) throw new UsageError('parse', 'the OpenDesign quota response reports an ineligible plan with windows')
+    return { windows: windowSet({}, now), plan: null }
+  }
+  if (!usable) throw new UsageError('parse', 'the OpenDesign quota response has no usable allowance windows')
+  return { windows, plan: null }
+}
+
+/**
+ * Parse the OpenDesign `wallet/balance` document.
+ *
+ * Shape (v2): `{ billingScopeVersion: 2, workspaceId, workspaceMemberId,
+ * balanceUsd }` where `balanceUsd` is a decimal string (negative = debt).
+ */
+export function parseOpenDesignWallet(payload, workspaceId) {
+  const document = payload !== null && typeof payload === 'object' && !Array.isArray(payload) ? payload : null
+  if (document === null) throw new UsageError('parse', 'the OpenDesign wallet response is not an object')
+  if (document.billingScopeVersion !== 2) {
+    throw new UsageError('parse', 'the OpenDesign wallet response has an unsupported scope version')
+  }
+  const expected = String(workspaceId ?? '').trim()
+  if (typeof document.workspaceId !== 'string' || document.workspaceId !== expected) {
+    throw new UsageError('parse', 'the OpenDesign wallet response belongs to a different workspace')
+  }
+  if (typeof document.workspaceMemberId !== 'string' || document.workspaceMemberId === '') {
+    throw new UsageError('parse', 'the OpenDesign wallet response has no member identity')
+  }
+  const raw = typeof document.balanceUsd === 'string' && /^-?\d+(?:\.\d+)?$/.test(document.balanceUsd)
+    ? Number(document.balanceUsd)
+    : null
+  if (raw === null || !Number.isFinite(raw)) {
+    throw new UsageError('parse', 'the OpenDesign wallet response has no usable balance')
+  }
+  return {
+    balance: { amount: raw, currency: 'USD' },
+    workspaceMemberId: document.workspaceMemberId,
+  }
+}
+
 /**
  * The provider adapter table. `read()` performs the required network reads and
  * returns the normalized result; optional reads (subscription/whoami) are
@@ -791,6 +908,49 @@ export const ADAPTERS = {
       return { kind: 'windows', ...parseVolcenginePlan(payload, now) }
     },
   },
+  'open-design': {
+    kind: 'windows',
+    async read({ providerId = 'open-design', provider, httpJson, now }) {
+      const config = providerConfig(providerId, provider)
+      const workspaceId = String(config.workspaceId ?? '').trim()
+      if (workspaceId === '') {
+        throw new UsageError(
+          'missing-key',
+          'OpenDesign quota needs a workspace id (providers.open-design.workspaceId or OPENDESIGN_WORKSPACE_ID)',
+          { retryable: false },
+        )
+      }
+      const controlKey = typeof provider.controlKey === 'string' ? provider.controlKey : ''
+      if (controlKey === '') {
+        throw new UsageError('missing-key', 'OpenDesign quota needs a Control Key (OPENDESIGN_CONTROL_KEY or VELA_CONTROL_KEY)', {
+          retryable: false,
+        })
+      }
+      const workspaceBase = joinUrl(config.baseURL, `/api/v1/workspaces/${encodeURIComponent(workspaceId)}`)
+      const headers = {
+        accept: 'application/json',
+        authorization: `Bearer ${controlKey}`,
+        'x-vela-workspace-id': workspaceId,
+      }
+      const usage = await httpJson(`${workspaceBase}/billing/coding-plan-usage`, { method: 'GET', headers })
+      const parsed = parseOpenDesignUsage(usage, workspaceId, now)
+      const wallet = await httpJson(`${workspaceBase}/wallet/balance`, { method: 'GET', headers })
+      const usageMember =
+        usage !== null && typeof usage === 'object' && typeof usage.workspaceMemberId === 'string'
+          ? usage.workspaceMemberId
+          : undefined
+      const walletParsed = parseOpenDesignWallet(wallet, workspaceId)
+      if (usageMember !== undefined && usageMember !== walletParsed.workspaceMemberId) {
+        throw new UsageError('parse', 'the OpenDesign wallet and quota responses name different workspace members')
+      }
+      return {
+        kind: 'windows',
+        windows: parsed.windows,
+        plan: parsed.plan,
+        balance: walletParsed.balance,
+      }
+    },
+  },
   'zhipu-cn': {
     kind: 'windows',
     async read({ providerId = 'zhipu-cn', provider, fetchJson, now }) {

package/lib/usage-jsonl.mjs

@@ -33,7 +33,7 @@
 import { readdirSync, readFileSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 import { homedir } from 'node:os'
-import { localDayKey } from './usage-zcode.mjs'
+import { localDayKey, localHour } from './usage-zcode.mjs'
 
 const num = (value) => (typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : 0)
 
@@ -81,11 +81,12 @@ export function jsonlTreeSignature(root) {
     .join('|')
 }
 
-/** Merge one row into a day/provider/model group map. */
-function addGroup(groups, { day, providerId, modelId, input, output, cacheRead, cacheWrite, total }) {
-  const key = `${day}\u0000${providerId}\u0000${modelId}`
+/** Merge one row into a (day, hour, provider, model) group map. */
+function addGroup(groups, { day, hour, providerId, modelId, input, output, cacheRead, cacheWrite, total }) {
+  const key = `${day}\u0000${hour}\u0000${providerId}\u0000${modelId}`
   const group = groups.get(key) ?? {
     day,
+    hour,
     providerId,
     modelId,
     bucket: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0, messages: 0 },
@@ -171,6 +172,7 @@ export function readWorkbuddyUsage(input = {}) {
     const model = String(providerData.model ?? providerData.requestModelId ?? 'unknown')
     addGroup(groups, {
       day: localDayKey(time),
+      hour: localHour(time),
       providerId: 'workbuddy',
       modelId: model,
       // prompt_tokens includes the cached prefix.
@@ -181,7 +183,7 @@ export function readWorkbuddyUsage(input = {}) {
       total,
     })
   })
-  const list = [...groups.values()].sort((a, b) => a.day.localeCompare(b.day))
+  const list = [...groups.values()].sort((a, b) => a.day.localeCompare(b.day) || a.hour - b.hour)
   return { harness: 'workbuddy', label: 'WorkBuddy', root, groups: list, rows: list.length, requests, skippedZero, durationMs: Date.now() - started }
 }
 
@@ -263,6 +265,7 @@ export function readQoderUsage(input = {}) {
     const modelId = custom !== null ? rawModel : rawModel
     addGroup(groups, {
       day: localDayKey(time),
+      hour: localHour(time),
       providerId,
       modelId,
       // Qoder's input_tokens include the cached prompt.
@@ -273,6 +276,6 @@ export function readQoderUsage(input = {}) {
       total,
     })
   })
-  const list = [...groups.values()].sort((a, b) => a.day.localeCompare(b.day))
+  const list = [...groups.values()].sort((a, b) => a.day.localeCompare(b.day) || a.hour - b.hour)
   return { harness: 'qoder', label: 'Qoder', root, groups: list, rows: list.length, requests, durationMs: Date.now() - started }
 }

package/lib/usage-opencode.mjs

@@ -24,7 +24,7 @@
 import { statSync } from 'node:fs'
 import { join } from 'node:path'
 import { homedir } from 'node:os'
-import { localDayKey } from './usage-zcode.mjs'
+import { localDayKey, localHour } from './usage-zcode.mjs'
 
 /** The default OpenCode CLI database location. */
 export function defaultOpencodeDbPath(env = process.env, home = homedir()) {
@@ -52,7 +52,7 @@ export function opencodeDbSignature(dbPath) {
  *
  * @param input.dbPath - database file (read-only).
  * @param input.openDatabase - test seam: `(path) => DatabaseSync`-like handle.
- * @returns `{ groups: [{day, providerId, modelId, bucket}], rows, durationMs, dbPath }`.
+ * @returns `{ groups: [{day, hour, providerId, modelId, bucket}], rows, durationMs, dbPath }`.
  */
 export function readOpencodeUsage(input = {}) {
   const dbPath =
@@ -91,12 +91,16 @@ export function readOpencodeUsage(input = {}) {
       const time = typeof row.timeCreated === 'number' ? row.timeCreated : null
       if (time === null) continue
       const day = localDayKey(time)
+      // Local clock hour: the chart's hourly drill-down bucket (DST fold hours
+      // collapse into one slot, like `getHours()`).
+      const hour = localHour(time)
       const providerId =
         typeof message.providerID === 'string' && message.providerID !== '' ? message.providerID : 'unknown'
       const modelId = typeof message.modelID === 'string' && message.modelID !== '' ? message.modelID : 'unknown'
-      const key = `${day}\u0000${providerId}\u0000${modelId}`
+      const key = `${day}\u0000${hour}\u0000${providerId}\u0000${modelId}`
       const group = groups.get(key) ?? {
         day,
+        hour,
         providerId,
         modelId,
         bucket: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0, messages: 0 },
@@ -110,7 +114,9 @@ export function readOpencodeUsage(input = {}) {
       group.bucket.messages += 1
       groups.set(key, group)
     }
-    const list = [...groups.values()].sort((a, b) => a.day.localeCompare(b.day))
+    // Day-ascending then hour-ascending keeps the groups deterministic for tests
+    // and for the daily merge.
+    const list = [...groups.values()].sort((a, b) => a.day.localeCompare(b.day) || a.hour - b.hour)
     return {
       harness: 'opencode',
       label: 'OpenCode',

package/lib/usage-stats.mjs

@@ -200,6 +200,34 @@ export function cloneBucket(from) {
   return addBucket(emptyBucket(), from)
 }
 
+/** An all-zero 24-slot local-hour token series. */
+export function emptyHourSeries() {
+  return new Array(24).fill(0)
+}
+
+/** Add one local-hour token amount into a 24-slot series; invalid slots are ignored. */
+export function addHourTokens(series, hour, tokens) {
+  if (!Array.isArray(series) || !Number.isInteger(hour) || hour < 0 || hour > 23) return series
+  if (typeof tokens !== 'number' || !Number.isFinite(tokens) || tokens <= 0) return series
+  series[hour] += tokens
+  return series
+}
+
+/** Accumulate one 24-slot series onto another (in place); false when `from` is not one. */
+export function addHourSeries(target, from) {
+  if (!Array.isArray(target) || !Array.isArray(from)) return false
+  for (let hour = 0; hour < 24; hour += 1) {
+    const value = from[hour]
+    if (typeof value === 'number' && Number.isFinite(value)) target[hour] += value
+  }
+  return true
+}
+
+/** A 24-slot series as wire integers (hourly token bars are rounded). */
+export function roundHourSeries(series) {
+  return series.map((value) => (typeof value === 'number' && Number.isFinite(value) ? Math.round(value) : 0))
+}
+
 /** Fold one decoded session into per-day / per-provider / per-model buckets. */
 export function foldSession(records) {
   const days = Object.create(null)
@@ -477,8 +505,8 @@ export function createUsageStats(input) {
     const daysAggregate = Object.create(null)
     const providersAggregate = Object.create(null)
     const modelsAggregate = Object.create(null)
-  const hoursAggregate = Object.create(null)
-  const workspacesAggregate = Object.create(null)
+    const hoursAggregate = Object.create(null)
+    const workspacesAggregate = Object.create(null)
     for (const entry of Object.values(cache.files)) {
       for (const [day, dayBucket] of Object.entries(entry.days ?? {})) {
         const target = (daysAggregate[day] ??= { providers: Object.create(null) })
@@ -516,6 +544,23 @@ export function createUsageStats(input) {
         }
       }
     }
+    // Local-hour series per day, folded from the epoch-hour buckets the session
+    // folds already carry: the chart mode drills into one day's 24 bars. Values
+    // stay raw here; `daily` rounds them once at the wire boundary.
+    const dayHoursAggregate = Object.create(null)
+    for (const [epochHour, bucket] of Object.entries(hoursAggregate)) {
+      const hourStart = Number(epochHour) * 3600_000
+      const date = new Date(hourStart)
+      if (!Number.isFinite(date.getTime())) continue
+      const slot = date.getHours()
+      const dayEntry = (dayHoursAggregate[dayKey(hourStart)] ??= { total: emptyHourSeries(), providers: Object.create(null) })
+      for (const [provider, providerBucket] of Object.entries(bucket.providers ?? {})) {
+        const tokens = providerBucket?.total
+        if (typeof tokens !== 'number' || !Number.isFinite(tokens) || tokens <= 0) continue
+        dayEntry.total[slot] += tokens
+        addHourTokens((dayEntry.providers[provider] ??= emptyHourSeries()), slot, tokens)
+      }
+    }
 
     const allTime = emptyBucket()
     for (const bucket of Object.values(providersAggregate)) addBucket(allTime, bucket)
@@ -627,7 +672,10 @@ export function createUsageStats(input) {
       })
       .sort((a, b) => b.allTime.total - a.allTime.total)
 
-    // Compact daily series (bounded) for the client chart view.
+    // Compact daily series (bounded) for the client chart view. `hours` is only
+    // present for a day with real local-hour data: a very old session's hour
+    // buckets are pruned by the fold, and a non-drillable day must not pretend
+    // to have an all-zero hour series.
     const daily = Object.entries(daysAggregate)
       .sort(([left], [right]) => left.localeCompare(right))
       .slice(-120)
@@ -638,7 +686,19 @@ export function createUsageStats(input) {
           providers[providerId] = { total: providerBucket.total ?? 0, messages: providerBucket.messages ?? 0 }
           addBucket(totals, providerBucket)
         }
-        return { day, total: { total: totals.total, messages: totals.messages }, providers }
+        const dayHours = dayHoursAggregate[day]
+        if (dayHours !== undefined) {
+          for (const [providerId, providerHours] of Object.entries(dayHours.providers)) {
+            // Only a provider already present in the day bucket gets a series.
+            if (providers[providerId] !== undefined) providers[providerId].hours = roundHourSeries(providerHours)
+          }
+        }
+        return {
+          day,
+          total: { total: totals.total, messages: totals.messages },
+          ...(dayHours === undefined ? {} : { hours: roundHourSeries(dayHours.total) }),
+          providers,
+        }
       })
 
     return {
@@ -789,7 +849,7 @@ export function createUsageStats(input) {
     try {
       const value = readZcodeUsage({ dbPath: zcodeDbPath })
       zcodeMemo = { sig, at: now, value, error: null }
-      log.info(`ZCode usage: ${value.rows} grouped day/provider/model rows in ${value.durationMs} ms`)
+      log.info(`ZCode usage: ${value.rows} grouped day/hour/provider/model rows in ${value.durationMs} ms`)
       return { enabled: true, dbPath: zcodeDbPath, value, error: null, cached: false }
     } catch (error) {
       const wire = {
@@ -921,7 +981,7 @@ export function createUsageStats(input) {
     try {
       const value = def.read()
       def.setMemo({ sig, at: now, value, error: null })
-      log.info(def.label + ' usage: ' + value.rows + ' grouped day/provider/model rows in ' + value.durationMs + ' ms')
+      log.info(def.label + ' usage: ' + value.rows + ' grouped day/hour/provider/model rows in ' + value.durationMs + ' ms')
       return { enabled: true, dbPath: def.dbPath, value, error: null, cached: false, installed: true }
     } catch (error) {
       const wire = {
@@ -1142,15 +1202,26 @@ export function createUsageStats(input) {
       for (const entry of unmapped) unmappedRows.push({ harnessId: def.id, harnessLabel: def.label, ...entry })
     }
 
-    // Daily series (last 120 days) for the chart view.
+    // Daily series (last 120 days) for the chart view. Each day keeps a bucket
+    // per canonical provider plus a 24-slot local-hour series; `hours` is only
+    // emitted for a day where at least one harness reported an hour, so the
+    // client never has to invent an all-zero drill-down.
     const dailyMap = new Map()
     for (const entry of dsh.daily ?? []) {
-      const dayEntry = dailyMap.get(entry.day) ?? { total: emptyBucket(), providers: new Map() }
+      const dayEntry = dailyMap.get(entry.day) ?? { total: emptyBucket(), providers: new Map(), hours: null }
       addBucket(dayEntry.total, entry.total)
+      if (Array.isArray(entry.hours)) {
+        dayEntry.hours ??= emptyHourSeries()
+        addHourSeries(dayEntry.hours, entry.hours)
+      }
       for (const [providerId, totals] of Object.entries(entry.providers ?? {})) {
-        const bucket = dayEntry.providers.get(providerId) ?? emptyBucket()
-        addBucket(bucket, totals)
-        dayEntry.providers.set(providerId, bucket)
+        const slot = dayEntry.providers.get(providerId) ?? { bucket: emptyBucket(), hours: null }
+        addBucket(slot.bucket, totals)
+        if (Array.isArray(totals?.hours)) {
+          slot.hours ??= emptyHourSeries()
+          addHourSeries(slot.hours, totals.hours)
+        }
+        dayEntry.providers.set(providerId, slot)
       }
       dailyMap.set(entry.day, dayEntry)
     }
@@ -1160,28 +1231,40 @@ export function createUsageStats(input) {
       if (slice.value === null) continue
       for (const group of slice.value.groups) {
         const mapped = mapHarnessProvider(group.providerId, group.modelId, def.aliases, catalog)
+        // Unmapped usage stays out of `daily` (it never had a provider row);
+        // its tokens only feed the all-harness buckets.
         if (mapped === null) continue
-        const dayEntry = dailyMap.get(group.day) ?? { total: emptyBucket(), providers: new Map() }
+        const dayEntry = dailyMap.get(group.day) ?? { total: emptyBucket(), providers: new Map(), hours: null }
         addBucket(dayEntry.total, group.bucket)
-        const bucket = dayEntry.providers.get(mapped.providerId) ?? emptyBucket()
-        addBucket(bucket, group.bucket)
-        dayEntry.providers.set(mapped.providerId, bucket)
+        if (Number.isInteger(group.hour)) {
+          addHourTokens((dayEntry.hours ??= emptyHourSeries()), group.hour, group.bucket.total)
+        }
+        const slot = dayEntry.providers.get(mapped.providerId) ?? { bucket: emptyBucket(), hours: null }
+        addBucket(slot.bucket, group.bucket)
+        if (Number.isInteger(group.hour)) {
+          addHourTokens((slot.hours ??= emptyHourSeries()), group.hour, group.bucket.total)
+        }
+        dayEntry.providers.set(mapped.providerId, slot)
         dailyMap.set(group.day, dayEntry)
       }
     }
     const daily = [...dailyMap.entries()]
       .sort(([left], [right]) => left.localeCompare(right))
       .slice(-120)
-      .map(([day, entry]) => ({
-        day,
-        total: { total: entry.total.total, messages: entry.total.messages },
-        providers: Object.fromEntries(
-          [...entry.providers.entries()].map(([providerId, bucket]) => [
-            providerId,
-            { total: bucket.total, messages: bucket.messages },
-          ]),
-        ),
-      }))
+      .map(([day, entry]) => {
+        const providers = Object.create(null)
+        for (const [providerId, slot] of entry.providers) {
+          const row = { total: slot.bucket.total, messages: slot.bucket.messages }
+          if (slot.hours !== null) row.hours = roundHourSeries(slot.hours)
+          providers[providerId] = row
+        }
+        return {
+          day,
+          total: { total: entry.total.total, messages: entry.total.messages },
+          ...(entry.hours === null ? {} : { hours: roundHourSeries(entry.hours) }),
+          providers,
+        }
+      })
 
     // Earliest record per provider across every contributing harness. This is
     // the local "effective date" used for the 最近X天 provider window.

package/lib/usage-zcode.mjs

@@ -20,13 +20,13 @@
  *   cacheWrite = cache_creation_input_tokens
  *   total      = computed_total_tokens (= input + output, cache included)
  *
- * Only token counters, provider/model ids and the completion day are read: no
+ * Only token counters, provider/model ids and the completion time are read: no
  * prompt or message content. The database is opened read-only.
  *
- * The result is a flat `groups` list (local day + ZCode provider id + model id +
- * bucket). Mapping a ZCode provider onto a canonical DSH provider (e.g.
- * `opencode-go-chat` -> `opencode-go`) is the caller's job, because the mapping
- * needs the Harness model catalog.
+ * The result is a flat `groups` list (local day + local hour + ZCode provider id
+ * + model id + bucket). Mapping a ZCode provider onto a canonical DSH provider
+ * (e.g. `opencode-go-chat` -> `opencode-go`) is the caller's job, because the
+ * mapping needs the Harness model catalog.
  */
 import { statSync } from 'node:fs'
 import { join } from 'node:path'
@@ -73,12 +73,23 @@ export function localDayKey(ms) {
   return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`
 }
 
+/**
+ * The local clock hour (0..23) of an epoch-ms instant.
+ *
+ * A DST fall-back day repeats one wall-clock hour, so both instants collapse
+ * into the same slot — which is exactly how the chart's 24 bars are defined.
+ */
+export function localHour(ms) {
+  const hour = new Date(ms).getHours()
+  return Number.isInteger(hour) && hour >= 0 && hour <= 23 ? hour : 0
+}
+
 /**
  * Read ZCode usage groups.
  *
  * @param input.dbPath - database file (read-only).
  * @param input.openDatabase - test seam: `(path) => DatabaseSync`-like handle.
- * @returns `{ groups: [{day, providerId, modelId, bucket}], rows, durationMs, dbPath }`.
+ * @returns `{ groups: [{day, hour, providerId, modelId, bucket}], rows, durationMs, dbPath }`.
  */
 export function readZcodeUsage(input = {}) {
   const dbPath = typeof input.dbPath === 'string' && input.dbPath !== '' ? input.dbPath : defaultZcodeDbPath()
@@ -89,6 +100,7 @@ export function readZcodeUsage(input = {}) {
     const rows = db
       .prepare(
         `SELECT date(completed_at / 1000, 'unixepoch', 'localtime') AS day,
+                CAST(strftime('%H', completed_at / 1000, 'unixepoch', 'localtime') AS INTEGER) AS hour,
                 provider_id AS providerId,
                 model_id AS modelId,
                 COUNT(*) AS messages,
@@ -99,8 +111,8 @@ export function readZcodeUsage(input = {}) {
                 SUM(computed_total_tokens) AS total
            FROM model_usage
           WHERE computed_total_tokens > 0 AND completed_at IS NOT NULL
-          GROUP BY day, provider_id, model_id
-          ORDER BY day`,
+          GROUP BY day, hour, provider_id, model_id
+          ORDER BY day, hour`,
       )
       .all()
     const groups = rows
@@ -108,8 +120,11 @@ export function readZcodeUsage(input = {}) {
       .map((row) => {
         const input = Math.max(0, Number(row.input ?? 0))
         const cacheRead = Math.max(0, Number(row.cacheRead ?? 0))
+        const hour = Number(row.hour)
         return {
           day: row.day,
+          // SQLite yields '00'..'23'; keep the wire field an integer.
+          hour: Number.isInteger(hour) && hour >= 0 && hour <= 23 ? hour : 0,
           providerId: typeof row.providerId === 'string' && row.providerId !== '' ? row.providerId : 'unknown',
           modelId: typeof row.modelId === 'string' && row.modelId !== '' ? row.modelId : 'unknown',
           bucket: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-tokenlens",
-  "version": "1.0.9",
+  "version": "1.2.0",
   "type": "module",
   "description": "dsh-TokenLens (词元透镜) — provider-aware plan capacity plus local token statistics (today/7d/30d/all-time, by harness/provider/model/workspace) for DSH.",
   "license": "MIT",