@linxin666/dsh-usage 0.3.7

package/src/core/adapters.ts

@@ -0,0 +1,370 @@
+/**
+ * Provider adapters: one entry per provider family this plugin can query for
+ * a pay-as-you-go balance or a coding-plan quota. Adapters are pure — they
+ * build an HTTP probe from a resolved credential and parse the response — so
+ * the service stays transport-only and every endpoint detail lives here.
+ *
+ * All probes run host-side (Node fetch); API keys never reach the browser.
+ * @module @linxin666/dsh-usage/core/adapters
+ */
+
+import type { PlanWindowView } from './types.ts'
+
+/** One HTTP probe the service executes verbatim. */
+export interface ProbeSpec {
+  url: string
+  headers: Record<string, string>
+}
+
+/** Inputs an adapter may use to build a probe. */
+export interface AdapterProbeContext {
+  /** Resolved credential value (the raw key; env refs are resolved upstream). */
+  apiKey: string
+}
+
+/** A parsed balance fact. */
+export interface BalanceParse {
+  currency: string
+  totalBalance: string
+}
+
+/** A parsed plan-quota fact. */
+export interface PlanParse {
+  planName?: string
+  windows: PlanWindowView[]
+}
+
+/** One provider family's probing capability. */
+export interface ProviderAdapter {
+  /** Provider route keys this adapter serves. */
+  ids: readonly string[]
+  /** Fallback display name when the LLM runtime has none. */
+  displayName: string
+  balance?: {
+    build(context: AdapterProbeContext): ProbeSpec
+    parse(status: number, body: unknown): BalanceParse | undefined
+  }
+  plan?: {
+    build(context: AdapterProbeContext): ProbeSpec
+    parse(status: number, body: unknown): PlanParse | undefined
+  }
+}
+
+/** Parse a string/number into a finite number, else undefined. */
+function toNum(value: unknown): number | undefined {
+  if (typeof value === 'number') return Number.isFinite(value) ? value : undefined
+  if (typeof value === 'string' && value.trim() !== '') {
+    const parsed = Number(value)
+    return Number.isFinite(parsed) ? parsed : undefined
+  }
+  return undefined
+}
+
+/** Read a string field that must be a non-empty string. */
+function str(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined
+}
+
+/** Format a number to a fixed 2-decimal display string. */
+function money(value: number): string {
+  return value.toFixed(2)
+}
+
+/** Millisecond epoch or ISO string → normalized ISO 8601, else undefined. */
+function toIso(value: unknown): string | undefined {
+  if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
+    const ms = value < 1e12 ? value * 1000 : value
+    const date = new Date(ms)
+    return Number.isNaN(date.getTime()) ? undefined : date.toISOString()
+  }
+  const text = str(value)
+  if (text === undefined) return undefined
+  const date = new Date(text)
+  return Number.isNaN(date.getTime()) ? text : date.toISOString()
+}
+
+/** Used-percent helper guarding zero/absent limits. */
+function usedPercent(used: unknown, limit: unknown): number | undefined {
+  const usedNum = toNum(used)
+  const limitNum = toNum(limit)
+  if (usedNum === undefined || limitNum === undefined || limitNum <= 0) return undefined
+  return Math.max(0, Math.min(100, (usedNum / limitNum) * 100))
+}
+
+function bearer(apiKey: string): Record<string, string> {
+  return { authorization: `Bearer ${apiKey}` }
+}
+
+const DEEPSEEK: ProviderAdapter = {
+  ids: ['deepseek'],
+  displayName: 'DeepSeek',
+  balance: {
+    build: ({ apiKey }) => ({ url: 'https://api.deepseek.com/user/balance', headers: bearer(apiKey) }),
+    parse: (status, body) => {
+      if (status !== 200 || typeof body !== 'object' || body === null) return undefined
+      const infos = (body as Record<string, unknown>).balance_infos
+      if (!Array.isArray(infos) || infos.length === 0) return undefined
+      const first = infos[0]
+      if (typeof first !== 'object' || first === null) return undefined
+      const currency = str((first as Record<string, unknown>).currency)
+      const total = str((first as Record<string, unknown>).total_balance)
+      if (currency === undefined || total === undefined) return undefined
+      return { currency, totalBalance: total }
+    },
+  },
+}
+
+/** Moonshot pay-as-you-go balance; CN bills in CNY, international in USD. */
+function moonshotBalance(host: string, currency: string, ids: readonly string[]): ProviderAdapter {
+  return {
+    ids,
+    displayName: 'Moonshot AI',
+    balance: {
+      build: ({ apiKey }) => ({ url: `https://${host}/v1/users/me/balance`, headers: bearer(apiKey) }),
+      parse: (status, body) => {
+        if (status !== 200 || typeof body !== 'object' || body === null) return undefined
+        const data = (body as Record<string, unknown>).data
+        if (typeof data !== 'object' || data === null) return undefined
+        const available = toNum((data as Record<string, unknown>).available_balance)
+        if (available === undefined) return undefined
+        return { currency, totalBalance: money(available) }
+      },
+    },
+  }
+}
+
+/** Kimi For Coding quota: top-level `usage` is the weekly summary, `limits[]` the per-window rows. */
+const KIMI_CODING: ProviderAdapter = {
+  ids: ['kimi-coding'],
+  displayName: 'Kimi For Coding',
+  plan: {
+    build: ({ apiKey }) => ({ url: 'https://api.kimi.com/coding/v1/usages', headers: bearer(apiKey) }),
+    parse: (status, body) => {
+      if (status !== 200 || typeof body !== 'object' || body === null) return undefined
+      const root = body as Record<string, unknown>
+      const windows: PlanWindowView[] = []
+      const limits = root.limits
+      if (Array.isArray(limits)) {
+        for (const entry of limits) {
+          if (typeof entry !== 'object' || entry === null) continue
+          const detail = (entry as Record<string, unknown>).detail
+          const window = (entry as Record<string, unknown>).window
+          if (typeof detail !== 'object' || detail === null) continue
+          const row = detail as Record<string, unknown>
+          const duration = typeof window === 'object' && window !== null ? toNum((window as Record<string, unknown>).duration) : undefined
+          const unit = typeof window === 'object' && window !== null ? str((window as Record<string, unknown>).timeUnit) : undefined
+          const key = duration === 300 && unit === 'TIME_UNIT_MINUTE' ? '5h' : duration !== undefined ? `w-${duration}` : 'window'
+          const percent = usedPercent(row.used, row.limit)
+          windows.push({ key, name: str(row.name), percent, resetsAt: toIso(row.resetTime) })
+        }
+      }
+      const usage = root.usage
+      if (typeof usage === 'object' && usage !== null) {
+        const weekly = usage as Record<string, unknown>
+        windows.push({
+          key: 'week',
+          name: 'Weekly',
+          percent: usedPercent(weekly.used, weekly.limit),
+          resetsAt: toIso(weekly.resetTime),
+        })
+      }
+      if (windows.length === 0) return undefined
+      const user = root.user
+      const membership = typeof user === 'object' && user !== null ? (user as Record<string, unknown>).membership : undefined
+      const planName = typeof membership === 'object' && membership !== null ? str((membership as Record<string, unknown>).level) : undefined
+      return { planName, windows }
+    },
+  },
+}
+
+/** GLM Coding Plan quota; auth is the RAW key without a Bearer prefix. */
+function glmPlan(host: string, ids: readonly string[]): ProviderAdapter {
+  return {
+    ids,
+    displayName: 'GLM Coding Plan',
+    plan: {
+      build: ({ apiKey }) => ({
+        url: `https://${host}/api/monitor/usage/quota/limit`,
+        headers: { authorization: apiKey, 'accept-language': 'en-US,en' },
+      }),
+      parse: (status, body) => {
+        if (status !== 200 || typeof body !== 'object' || body === null) return undefined
+        const root = body as Record<string, unknown>
+        if (root.success !== true) return undefined
+        const data = root.data
+        if (typeof data !== 'object' || data === null) return undefined
+        const limits = (data as Record<string, unknown>).limits
+        if (!Array.isArray(limits)) return undefined
+        const windows: PlanWindowView[] = []
+        for (const entry of limits) {
+          if (typeof entry !== 'object' || entry === null) continue
+          const row = entry as Record<string, unknown>
+          const unit = toNum(row.unit)
+          const percent = toNum(row.percentage)
+          windows.push({
+            key: unit === 3 ? '5h' : unit === 6 ? 'week' : unit !== undefined ? `unit-${unit}` : 'window',
+            percent: percent === undefined ? undefined : Math.max(0, Math.min(100, percent)),
+            resetsAt: toIso(row.nextResetTime),
+          })
+        }
+        if (windows.length === 0) return undefined
+        return { planName: str((data as Record<string, unknown>).level), windows }
+      },
+    },
+  }
+}
+
+/** OpenCode Go quota: percent-only rolling/weekly/monthly windows. */
+const OPENCODE_GO: ProviderAdapter = {
+  ids: ['opencode-go'],
+  displayName: 'OpenCode Go',
+  plan: {
+    build: ({ apiKey }) => ({ url: 'https://opencode.ai/zen/go/v1/usage', headers: bearer(apiKey) }),
+    parse: (status, body) => {
+      if (status !== 200 || typeof body !== 'object' || body === null) return undefined
+      const usage = (body as Record<string, unknown>).usage
+      if (typeof usage !== 'object' || usage === null) return undefined
+      const windows: PlanWindowView[] = []
+      const keys: Array<[string, string]> = [['rolling', '5h'], ['weekly', 'week'], ['monthly', 'month']]
+      for (const [field, key] of keys) {
+        const entry = (usage as Record<string, unknown>)[field]
+        if (typeof entry !== 'object' || entry === null) continue
+        const row = entry as Record<string, unknown>
+        const percent = toNum(row.percent)
+        windows.push({
+          key,
+          percent: percent === undefined ? undefined : Math.max(0, Math.min(100, percent)),
+          // percent 0 resetsAt is a placeholder (now + window); drop it.
+          resetsAt: percent === 0 ? undefined : toIso(row.resetsAt),
+        })
+      }
+      if (windows.length === 0) return undefined
+      return { windows }
+    },
+  },
+}
+
+/** MiniMax coding-plan remains: remaining-percent semantics, `general` model entry. */
+function minimaxPlan(host: string, ids: readonly string[]): ProviderAdapter {
+  return {
+    ids,
+    displayName: 'MiniMax Coding Plan',
+    plan: {
+      build: ({ apiKey }) => ({ url: `https://${host}/v1/api/openplatform/coding_plan/remains`, headers: bearer(apiKey) }),
+      parse: (status, body) => {
+        if (status !== 200 || typeof body !== 'object' || body === null) return undefined
+        const remains = (body as Record<string, unknown>).model_remains
+        if (!Array.isArray(remains)) return undefined
+        const general = remains.find((entry) => typeof entry === 'object' && entry !== null
+          && (entry as Record<string, unknown>).model_name === 'general')
+        if (typeof general !== 'object' || general === null) return undefined
+        const row = general as Record<string, unknown>
+        const windows: PlanWindowView[] = []
+        const intervalRemaining = toNum(row.current_interval_remaining_percent)
+        if (intervalRemaining !== undefined) {
+          windows.push({ key: '5h', percent: Math.max(0, Math.min(100, 100 - intervalRemaining)), resetsAt: toIso(row.end_time) })
+        }
+        if (row.current_weekly_status === 1) {
+          const weeklyRemaining = toNum(row.current_weekly_remaining_percent)
+          if (weeklyRemaining !== undefined) {
+            windows.push({ key: 'week', percent: Math.max(0, Math.min(100, 100 - weeklyRemaining)), resetsAt: toIso(row.weekly_end_time) })
+          }
+        }
+        if (windows.length === 0) return undefined
+        return { windows }
+      },
+    },
+  }
+}
+
+const OPENROUTER: ProviderAdapter = {
+  ids: ['openrouter'],
+  displayName: 'OpenRouter',
+  balance: {
+    build: ({ apiKey }) => ({ url: 'https://openrouter.ai/api/v1/credits', headers: bearer(apiKey) }),
+    parse: (status, body) => {
+      if (status !== 200 || typeof body !== 'object' || body === null) return undefined
+      const data = (body as Record<string, unknown>).data
+      if (typeof data !== 'object' || data === null) return undefined
+      const credits = toNum((data as Record<string, unknown>).total_credits)
+      const used = toNum((data as Record<string, unknown>).total_usage) ?? 0
+      if (credits === undefined) return undefined
+      return { currency: 'USD', totalBalance: money(credits - used) }
+    },
+  },
+}
+
+function siliconFlow(host: string, ids: readonly string[], currency: string): ProviderAdapter {
+  return {
+    ids,
+    displayName: 'SiliconFlow',
+    balance: {
+      build: ({ apiKey }) => ({ url: `https://${host}/v1/user/info`, headers: bearer(apiKey) }),
+      parse: (status, body) => {
+        if (status !== 200 || typeof body !== 'object' || body === null) return undefined
+        const data = (body as Record<string, unknown>).data
+        if (typeof data !== 'object' || data === null) return undefined
+        const total = str((data as Record<string, unknown>).totalBalance)
+        if (total === undefined) return undefined
+        return { currency, totalBalance: total }
+      },
+    },
+  }
+}
+
+const ZENMUX: ProviderAdapter = {
+  ids: ['zenmux'],
+  displayName: 'ZenMux',
+  balance: {
+    build: ({ apiKey }) => ({ url: 'https://zenmux.ai/api/v1/management/payg/balance', headers: bearer(apiKey) }),
+    parse: (status, body) => {
+      if (status !== 200 || typeof body !== 'object' || body === null) return undefined
+      const data = (body as Record<string, unknown>).data
+      if (typeof data !== 'object' || data === null) return undefined
+      const credits = toNum((data as Record<string, unknown>).total_credits)
+      if (credits === undefined) return undefined
+      return { currency: 'USD', totalBalance: money(credits) }
+    },
+  },
+}
+
+/**
+ * The adapter registry, in no particular order. Route keys come from the
+ * pi-ai provider catalog plus the routes this deployment observed in user
+ * configuration (`zenmux`).
+ */
+export const PROVIDER_ADAPTERS: readonly ProviderAdapter[] = [
+  DEEPSEEK,
+  moonshotBalance('api.moonshot.cn', 'CNY', ['moonshotai-cn']),
+  moonshotBalance('api.moonshot.ai', 'USD', ['moonshotai']),
+  KIMI_CODING,
+  glmPlan('open.bigmodel.cn', ['zai-coding-cn']),
+  glmPlan('api.z.ai', ['zai-coding']),
+  OPENCODE_GO,
+  minimaxPlan('api.minimaxi.com', ['minimax-cn']),
+  minimaxPlan('api.minimax.io', ['minimax']),
+  OPENROUTER,
+  siliconFlow('api.siliconflow.cn', ['siliconflow', 'siliconflow-cn'], 'CNY'),
+  siliconFlow('api.siliconflow.com', ['siliconflow-intl'], 'USD'),
+  ZENMUX,
+]
+
+/** Find the adapter serving a provider route key, if any. */
+export function adapterFor(provider: string): ProviderAdapter | undefined {
+  return PROVIDER_ADAPTERS.find((adapter) => adapter.ids.includes(provider))
+}
+
+/**
+ * Best-effort human message from a provider error body, for the per-provider
+ * error line. Never throws; truncated to one short sentence.
+ */
+export function providerErrorMessage(status: number, body: unknown): string {
+  let message: string | undefined
+  if (typeof body === 'object' && body !== null) {
+    const root = body as Record<string, unknown>
+    const nested = typeof root.error === 'object' && root.error !== null ? (root.error as Record<string, unknown>) : undefined
+    message = str(root.message) ?? str(root.msg) ?? (nested !== undefined ? str(nested.message) : undefined)
+  }
+  const detail = message === undefined ? '' : `: ${message.slice(0, 120)}`
+  return `HTTP ${status}${detail}`
+}

package/src/core/ledger.ts

@@ -0,0 +1,108 @@
+/**
+ * The usage ledger: a pure fold from session usage facts into a per-day,
+ * per-provider, per-model totals document, plus its JSON serialization.
+ * Host-side state lives only in the document; the service owns persistence.
+ * @module @linxin666/dsh-usage/core/ledger
+ */
+
+import { addTotals, emptyTotals, type UsageLedgerDocument, type UsageTokenTotals } from './types.ts'
+
+/** Local-date key (`YYYY-MM-DD`) for an epoch ms timestamp. */
+export function localDateKey(ms: number): string {
+  const date = new Date(ms)
+  const month = String(date.getMonth() + 1).padStart(2, '0')
+  const day = String(date.getDate()).padStart(2, '0')
+  return `${date.getFullYear()}-${month}-${day}`
+}
+
+/** An empty ledger document. */
+export function createLedgerDocument(): UsageLedgerDocument {
+  return { version: 1, days: {} }
+}
+
+/**
+ * Fold one usage report into the ledger in place. `provider` is the route key
+ * and `model` the provider-owned model id the step ran under.
+ */
+export function foldUsage(
+  doc: UsageLedgerDocument,
+  atMs: number,
+  provider: string,
+  model: string,
+  usage: Readonly<UsageTokenTotals>,
+): void {
+  if (usage.calls <= 0 && usage.inputTokens + usage.outputTokens + usage.cacheReadTokens + usage.cacheWriteTokens <= 0) return
+  const dayKey = localDateKey(atMs)
+  const day = doc.days[dayKey] ?? {}
+  const models = day[provider] ?? {}
+  const totals = models[model] ?? emptyTotals()
+  addTotals(totals, usage)
+  models[model] = totals
+  day[provider] = models
+  doc.days[dayKey] = day
+}
+
+/** Total tokens of a bucket (billed input + output; reasoning is inside output). */
+export function totalTokens(totals: Readonly<UsageTokenTotals>): number {
+  return totals.inputTokens + totals.cacheReadTokens + totals.cacheWriteTokens + totals.outputTokens
+}
+
+/** All local-date keys in the ledger, ascending. */
+export function ledgerDayKeys(doc: Readonly<UsageLedgerDocument>): string[] {
+  return Object.keys(doc.days).sort()
+}
+
+/**
+ * Drop every day older than `retainDays` local days before `todayKey`, in
+ * place. Returns the number of pruned days.
+ */
+export function pruneLedger(doc: UsageLedgerDocument, todayKey: string, retainDays: number): number {
+  const cutoff = new Date(todayKey + 'T00:00:00')
+  cutoff.setDate(cutoff.getDate() - retainDays)
+  const cutoffKey = localDateKey(cutoff.getTime())
+  let pruned = 0
+  for (const key of Object.keys(doc.days)) {
+    if (key < cutoffKey) {
+      delete doc.days[key]
+      pruned += 1
+    }
+  }
+  return pruned
+}
+
+function reviveTotals(value: unknown): UsageTokenTotals | undefined {
+  if (typeof value !== 'object' || value === null) return undefined
+  const source = value as Record<string, unknown>
+  const num = (key: string): number => typeof source[key] === 'number' && Number.isFinite(source[key]) ? source[key] : 0
+  return {
+    inputTokens: num('inputTokens'),
+    outputTokens: num('outputTokens'),
+    cacheReadTokens: num('cacheReadTokens'),
+    cacheWriteTokens: num('cacheWriteTokens'),
+    reasoningTokens: num('reasoningTokens'),
+    calls: num('calls'),
+  }
+}
+
+/**
+ * Parse a ledger document from untrusted JSON: unknown shapes resolve to an
+ * empty document, malformed entries are dropped, numbers are coerced to
+ * finite values. Never throws.
+ */
+export function deserializeLedger(value: unknown): UsageLedgerDocument {
+  const doc = createLedgerDocument()
+  if (typeof value !== 'object' || value === null) return doc
+  const days = (value as Record<string, unknown>).days
+  if (typeof days !== 'object' || days === null) return doc
+  for (const [dateKey, providers] of Object.entries(days as Record<string, unknown>)) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(dateKey) || typeof providers !== 'object' || providers === null) continue
+    for (const [provider, models] of Object.entries(providers as Record<string, unknown>)) {
+      if (typeof models !== 'object' || models === null) continue
+      for (const [model, totals] of Object.entries(models as Record<string, unknown>)) {
+        const revived = reviveTotals(totals)
+        if (revived !== undefined) foldUsage(doc, new Date(dateKey + 'T12:00:00').getTime(), provider, model, revived)
+      }
+    }
+  }
+  return doc
+}

package/src/core/types.ts

@@ -0,0 +1,127 @@
+/**
+ * Wire-facing view types shared by the dsh-usage host service, its HTTP
+ * routes, and the browser section. Everything here crosses the wire as JSON
+ * and must stay provider-agnostic: provider quirks are normalized inside the
+ * core adapters, never here.
+ * @module @linxin666/dsh-usage/core/types
+ */
+
+/** One disjoint token bucket total, aggregated over calls (billed input = input + cacheRead + cacheWrite). */
+export interface UsageTokenTotals {
+  /** Uncached input tokens. */
+  inputTokens: number
+  /** Output tokens (reasoning included). */
+  outputTokens: number
+  /** Cache read tokens. */
+  cacheReadTokens: number
+  /** Cache write tokens. */
+  cacheWriteTokens: number
+  /** Reasoning tokens, when the provider reported them. */
+  reasoningTokens: number
+  /** Provider calls that reported usage. */
+  calls: number
+}
+
+/** A zeroed totals bucket. */
+export function emptyTotals(): UsageTokenTotals {
+  return { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, reasoningTokens: 0, calls: 0 }
+}
+
+/** Add `right` into `left` in place. */
+export function addTotals(left: UsageTokenTotals, right: Readonly<UsageTokenTotals>): UsageTokenTotals {
+  left.inputTokens += right.inputTokens
+  left.outputTokens += right.outputTokens
+  left.cacheReadTokens += right.cacheReadTokens
+  left.cacheWriteTokens += right.cacheWriteTokens
+  left.reasoningTokens += right.reasoningTokens
+  left.calls += right.calls
+  return left
+}
+
+/** On-disk usage ledger: per local day, per provider route, per model. */
+export interface UsageLedgerDocument {
+  version: 1
+  /** Local-date key `YYYY-MM-DD` → per-provider per-model totals. */
+  days: Record<string, Record<string, Record<string, UsageTokenTotals>>>
+}
+
+/** One provider row of the day summary the overview serves. */
+export interface UsageProviderSummary {
+  provider: string
+  totals: UsageTokenTotals
+  /** Per-model breakdown, heaviest by total tokens first, capped by the route. */
+  models: Array<{ model: string; totals: UsageTokenTotals }>
+}
+
+/** One day row of the trend the overview serves. */
+export interface UsageDaySummary {
+  date: string
+  totals: UsageTokenTotals
+}
+
+/** A balance fact normalized from a provider probe. */
+export interface BalanceView {
+  /** ISO 4217 code the provider bills in (`CNY`, `USD`, ...). */
+  currency: string
+  /** Spendable total formatted for display (no currency symbol). */
+  totalBalance: string
+  /** Epoch ms of the successful probe. */
+  updatedAt: number
+}
+
+/** One quota window of a coding plan. */
+export interface PlanWindowView {
+  /** Stable window key the UI localizes (`5h`, `week`, `month`, provider strings otherwise). */
+  key: string
+  /** Provider-supplied window name, when it sends one. */
+  name?: string
+  /** Used percent 0-100, when computable. */
+  percent?: number
+  /** ISO 8601 reset instant, when the provider reports one. */
+  resetsAt?: string
+}
+
+/** A coding-plan quota fact normalized from a provider probe. */
+export interface PlanView {
+  /** Plan tier name, when the provider reports one. */
+  planName?: string
+  windows: PlanWindowView[]
+  updatedAt: number
+}
+
+/** How the credential backing one provider route was resolved. */
+export type CredentialKind = 'api-key' | 'env' | 'oauth' | 'none'
+
+/** One provider row of the overview snapshot. */
+export interface ProviderSnapshotView {
+  /** Provider route key (`deepseek`, `kimi-coding`, custom routes, ...). */
+  provider: string
+  /** Display name from the LLM runtime, else the adapter's, else the route key. */
+  displayName: string
+  credential: CredentialKind
+  /** Whether a balance/plan adapter exists for this route. */
+  supported: boolean
+  balance?: BalanceView
+  plan?: PlanView
+  /** Last probe failure, cleared on the next success. */
+  error?: string
+  updatedAt?: number
+}
+
+/** The overview the browser section renders. */
+export interface UsageOverviewView {
+  updatedAt: number
+  providers: ProviderSnapshotView[]
+  /** The provider the pet bubble and the header highlight; `source` says how it was picked. */
+  current: {
+    provider?: string
+    model?: string
+    /** `live` — last request seen this boot; `default` — the agent default model. */
+    source: 'live' | 'default'
+  }
+  usage: {
+    today: { date: string; totals: UsageTokenTotals; providers: UsageProviderSummary[] }
+    /** Last N local days ascending, including today. */
+    days: UsageDaySummary[]
+  }
+}

package/src/dsh-home.ts

@@ -0,0 +1,42 @@
+// Generated by scripts/sync-shared.mjs from shared/host/dsh-home.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * DSH_HOME resolution shared by the plugin family's Host halves: the
+ * environment override wins, the platform home fallback follows. Mirrors
+ * what dsh-pet and dsh-liangshen each used to implement locally.
+ */
+
+import { homedir } from 'node:os'
+import { isAbsolute, join } from 'node:path'
+import { isAbsolute as posixIsAbsolute, join as posixJoin } from 'node:path/posix'
+
+/** Expand a leading ~ (or ~user) in a path, platform-style. */
+export function expandHome(path: string, home: string = homedir()): string {
+  const isPosix = home.startsWith('/')
+  const j = isPosix ? posixJoin : join
+  if (path === '~') return home
+  if (path.startsWith('~/') || path.startsWith('~\\')) return j(home, path.slice(2))
+  return path
+}
+
+/**
+ * Resolve the DSH home directory.
+ * @param env - process environment to read DSH_HOME from.
+ * @param home - platform home directory fallback (test seam).
+ * @returns the absolute DSH home path.
+ */
+export function resolveDshHome(env: NodeJS.ProcessEnv = process.env, home: string = homedir()): string {
+  const isPosix = home.startsWith('/')
+  const j = isPosix ? posixJoin : join
+  const isAbs = isPosix ? posixIsAbsolute : isAbsolute
+  const raw = env.DSH_HOME
+  if (raw !== undefined && raw.trim() !== '') {
+    const expanded = expandHome(raw.trim(), home)
+    return isAbs(expanded) ? expanded : j(process.cwd(), expanded)
+  }
+  return j(home, '.dsh')
+}
+
+/** Resolve the DSH home directory from the live environment. */
+export function dshHome(): string {
+  return resolveDshHome()
+}