@linxin666/dsh-usage 0.3.23 → 0.4.0

package/src/client/foot-card-mount.tsx

@@ -0,0 +1,112 @@
+/**
+ * Sidebar foot card mounting.
+ *
+ * The foot's only slot (sidebar.footer.action) stacks ABOVE the Settings row
+ * and cannot host a block, so the card container is inserted into the shell's
+ * foot area directly above the Settings seat — keeping Settings the foot's
+ * terminal row instead of hanging a card off the sidebar floor. It self-heals
+ * with the page-wide body-mutation hub: a React re-render that displaces the
+ * container re-seats it on the next frame, and a whole-pane rebuild is noticed
+ * by the same body-level watcher the family entry rows use.
+ *
+ * The container is a plain div carrying its own React root, so it can never
+ * disturb the shell's reconciliation.
+ * @module @linxin666/dsh-usage/client/foot-card-mount
+ */
+
+import { createElement } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { subscribeBodyInvalidations } from './body-mutations.ts'
+import { UsageFootCard, type UsageFootCardProps } from './UsageFootCard.tsx'
+
+/** Stable data attribute identifying the injected card container. */
+export const FOOT_CARD_SELECTOR = '[data-dsh-usage-foot-card]'
+
+/** The shell sidebar's foot area (footer actions + the Settings row), when mounted. */
+function footArea(): HTMLElement | undefined {
+  const column = document.querySelector<HTMLElement>('[data-pane="sidebar"], [class*="sidebarCol"]')
+  return column?.querySelector<HTMLElement>('[class*="footArea"]') ?? undefined
+}
+
+/**
+ * Open the settings panel on the usage section. The shell owns the panel's
+ * open state and exposes no service for it, so the card replays the user's
+ * own path: activate the sidebar Settings trigger, then pick the nav row
+ * carrying the section's (localized) label. Every step degrades silently —
+ * with the panel already open only the nav pick runs, and a missing row
+ * leaves the panel on its default section.
+ * @param label - the usage section's nav label in the active locale.
+ */
+export function openUsageSettings(label: () => string): void {
+  /** Click the nav row carrying the usage label inside the open panel. */
+  const pick = (panel: Element): void => {
+    const wanted = label()
+    for (const row of panel.querySelectorAll<HTMLButtonElement>('nav button')) {
+      if (row.textContent !== null && row.textContent.includes(wanted)) {
+        row.click()
+        return
+      }
+    }
+    // Panel open but the usage row is gone (plugin toggled off): stay put.
+  }
+  // A panel that is already open must never be toggled shut by the trigger;
+  // only the nav pick runs.
+  const open = document.querySelector('[role="dialog"]')
+  if (open !== null) {
+    pick(open)
+    return
+  }
+  const column = document.querySelector<HTMLElement>('[data-pane="sidebar"], [class*="sidebarCol"]')
+  const trigger = column?.querySelector<HTMLButtonElement>('[class*="settingsArea"] button')
+  trigger?.click()
+  let tries = 0
+  const attempt = (): void => {
+    const panel = document.querySelector('[role="dialog"]')
+    if (panel !== null) {
+      pick(panel)
+      return
+    }
+    tries += 1
+    // The panel mounts on the shell's next frames; wait briefly, then give up.
+    if (tries <= 20) window.setTimeout(attempt, 50)
+  }
+  window.setTimeout(attempt, 0)
+}
+
+/**
+ * Mount the sidebar foot card directly above the Settings row.
+ * @param props - the store/poll/settings/open inputs of the apply body.
+ * @returns disposer removing the container and its observers.
+ */
+export function mountUsageFootCard(props: UsageFootCardProps): () => void {
+  // DOM-level idempotency: whatever path mounted a card before this call (a
+  // duplicated apply, an HMR re-injection), never mount a second one.
+  if (typeof document !== 'undefined' && document.querySelector(FOOT_CARD_SELECTOR) !== null) {
+    return () => {}
+  }
+  const container = document.createElement('div')
+  container.setAttribute('data-dsh-usage-foot-card', '')
+  const root: Root = createRoot(container)
+  root.render(createElement(UsageFootCard, props))
+
+  /** Keep the container directly above the Settings seat inside the foot area. */
+  const place = (): void => {
+    const foot = footArea()
+    if (foot === undefined) return
+    const settings = foot.querySelector<HTMLElement>('[class*="settingsArea"]')
+    if (settings !== null) {
+      if (container.nextElementSibling !== settings) foot.insertBefore(container, settings)
+      return
+    }
+    // No Settings seat to anchor against (shell change): fall back to the tail.
+    if (foot.lastElementChild !== container) foot.append(container)
+  }
+  place()
+  const unsubscribeBody = subscribeBodyInvalidations(place)
+
+  return () => {
+    unsubscribeBody()
+    root.unmount()
+    container.remove()
+  }
+}

package/src/client/index.ts

@@ -1,24 +1,26 @@
 /**
  * dsh-usage browser half — seats the first-level 使用统计 settings section
- * (below the Workshop entry) and polls the host overview only while the
- * section is open. All provider probing and credential handling happens in
- * the host half; this bundle only renders the overview document.
+ * (below the Workshop entry) plus the compact usage glance card below the
+ * sidebar's Settings row. The section polls the host overview only while it
+ * is open; the foot card runs its own relaxed loop because the sidebar foot
+ * is permanently mounted. All provider probing and credential handling
+ * happens in the host half; this bundle only renders the overview document.
  * @module @linxin666/dsh-usage/client
  */
 
 import type { Context as ClientContext } from '@deepseek-ai/cordis'
-import type { SettingsScope, SettingsScopeSpec } from '@deepseek-ai/dsh-client-ui-settings/client'
+import type { ConfigForm } from '@deepseek-ai/dsh-client-ui-settings/client'
 // Type-only: pulls the locale plugin's Context merge (ctx.locale).
 import type {} from '@deepseek-ai/dsh-client-locale/client'
-// Type-only: pulls the settings-surface Context merge (ctx.settingsScope).
+// Type-only: pulls the shared-forms Context merge (ctx.configForms).
 import type {} from '@deepseek-ai/dsh-client-ui-settings/client'
 import type {} from '@deepseek-ai/dsh-client-ui-slots'
 // Type-only: pulls the ctx.slots merge (the renderer owns the slot registry since 0.1.2).
 import type {} from '@deepseek-ai/dsh-client-ui-renderer/client'
-import { createElement } from 'react'
 import { createUsageStore, type UsageStoreInstance } from './usage-store.ts'
 import { UsageSectionCard, type UsageSectionFace, type UsageSettings } from './UsageSectionCard.tsx'
-import { NS, en, zh } from './locales.ts'
+import { mountUsageFootCard, openUsageSettings } from './foot-card-mount.tsx'
+import { NS, en, zh, t } from './locales.ts'
 import type { UsageOverviewView } from '../core/types.ts'
 
 /** The host usage API as the browser sees it (same-origin JSON endpoints). */
@@ -44,27 +46,39 @@ const usageApi: UsageHttpApi = {
   refresh: () => usageFetch('/api/dsh-usage/refresh', 'POST'),
 }
 
-/** Settings namespace the section edits (the host plugin registers it). */
+/** Settings namespace the section edits (dsh-web-settings maps it onto this row's profile entry id). */
 const USAGE_SETTINGS_NS = 'dsh-usage'
 
 /** First-level nav position: directly below the Workshop section (order 150). */
 const SECTION_ORDER = 151
 
 /** Required services. */
-export const inject = ['slots', 'locale', 'connection', 'settingsScope', 'remote']
+export const inject = ['slots', 'locale', 'connection', 'configForms', 'remote']
 
 export type { UsageSectionProps, UsageSectionFace } from './UsageSectionCard.tsx'
 export type { UsageUiState } from './usage-store.ts'
 export type { UsageSettings }
 
+/**
+ * One settings namespace a family card binds. The 0.1.7 client exports no spec
+ * type (the form controller takes it privately), so the binder's input shape is
+ * restated here.
+ */
+export interface UsageSettingsBindSpec<T> {
+  /** Settings namespace registered by the owning host plugin. */
+  namespace: string
+  /** Narrow one wire section; undefined keeps the last accepted value. */
+  decode?: (section: unknown) => T | undefined
+}
+
 declare module '@deepseek-ai/cordis' {
   interface Context {
     /**
-     * Optional rc.6 compatibility binder provided by dsh-web-settings;
-     * absent when that group plugin is not installed, so callers fall back to
-     * the official settings scope.
+     * Optional family settings binder provided by dsh-web-settings; absent when
+     * that group plugin is not installed, so callers fall back to the native
+     * per-entry forms (`ctx.configForms`).
      */
-    webUiSettings?: { bind<S>(spec: SettingsScopeSpec<S>): SettingsScope<S> }
+    webUiSettings?: { bind<S>(spec: UsageSettingsBindSpec<S>): ConfigForm<S> }
   }
 }
 
@@ -83,8 +97,16 @@ export function apply(ctx: ClientContext): void {
     }
   }, 'dsh-usage: dictionaries')
 
-  const binder = ctx.get('webUiSettings') ?? ctx.settingsScope
-  const settingsScope = binder.bind<UsageSettings>({ namespace: USAGE_SETTINGS_NS })
+  // The family binder is what maps this namespace onto the row's profile entry
+  // id and hands back the native form. Without the group plugin the client can
+  // only address an entry id it already knows: the namespace itself is one when
+  // the profile keeps the family spelling. Any other entry id leaves the form
+  // unavailable, which renders the row's controls disabled — the Host's own
+  // generated page for the row still edits the same Config.
+  const binder = ctx.get('webUiSettings')
+  const settingsForm = binder !== undefined
+    ? binder.bind<UsageSettings>({ namespace: USAGE_SETTINGS_NS })
+    : ctx.configForms.get<UsageSettings>(USAGE_SETTINGS_NS)
 
   // One store instance per apply body; the section mounts and unmounts with
   // the settings page, and the store survives between visits so the last
@@ -121,7 +143,26 @@ export function apply(ctx: ClientContext): void {
     })
   }
 
-  const face = (): UsageSectionFace => ({ store, poll, refresh, settings: settingsScope })
+  const face = (): UsageSectionFace => ({ store, poll, refresh, settings: settingsForm })
+
+  // Sidebar foot card: the compact usage glance seated below the shell's
+  // Settings row. It shares the section's store and poll path (the sequence
+  // guard absorbs interleaved calls), runs its own relaxed poll loop, and
+  // opens the settings panel on the usage section when clicked.
+  const disposeFootCard = mountUsageFootCard({
+    store,
+    poll,
+    settings: settingsForm,
+    onOpen: () => { openUsageSettings(() => t('usage.title')) },
+    locale: ctx.locale,
+  })
+  ctx.effect(() => () => {
+    try {
+      disposeFootCard()
+    } catch {
+      // Card container already gone (teardown race).
+    }
+  }, 'dsh-usage: sidebar foot card')
 
   ctx.slots.inject('settings.section', () => {
     try {

package/src/client/locales.ts

@@ -48,10 +48,7 @@ export const zh = {
   'usage.config.title': '设置',
   'usage.config.enabled': '启用插件',
   'usage.config.pollIntervalSec': '轮询间隔（秒）',
-  'usage.config.bubbleMode': '宠物气泡',
-  'usage.config.bubbleMode.always': '常驻显示',
-  'usage.config.bubbleMode.change': '仅变化时',
-  'usage.config.bubbleMode.off': '关闭',
+  'usage.config.saveFailed': '保存失败：设置未被接受。',
   'usage.bank.title': '鲸元券',
   'usage.bank.hint': '官方 API 每消耗 100 万 tokens 铸造 1 鲸元；保存或分享这张票券。',
   'usage.bank.noUsage': '暂无 DeepSeek 官方用量数据（统计自插件启用起）',
@@ -62,6 +59,11 @@ export const zh = {
   'usage.bank.save': '保存图片',
   'usage.bank.share': '分享',
   'usage.bank.drawError': '票券生成失败：{error}',
+  'usage.foot.cost': '今日消费',
+  'usage.foot.noData': '今日暂无用量',
+  'usage.foot.open': '打开使用统计设置',
+  'usage.foot.collapse': '收起用量卡片',
+  'usage.foot.expand': '展开用量卡片',
 }
 
 /** English mirror; every zh key present. */
@@ -105,10 +107,7 @@ export const en: Record<UsageKey, string> = {
   'usage.config.title': 'Settings',
   'usage.config.enabled': 'Enable plugin',
   'usage.config.pollIntervalSec': 'Poll interval (seconds)',
-  'usage.config.bubbleMode': 'Pet bubble',
-  'usage.config.bubbleMode.always': 'Always visible',
-  'usage.config.bubbleMode.change': 'On change',
-  'usage.config.bubbleMode.off': 'Off',
+  'usage.config.saveFailed': 'Save failed: the deployment did not accept the setting.',
   'usage.bank.title': 'Whale-yuan voucher',
   'usage.bank.hint': 'Every 1,000,000 tokens spent on the official API mint one whale yuan; save or share the note.',
   'usage.bank.noUsage': 'No official DeepSeek usage yet (counting starts when the plugin is enabled)',
@@ -119,6 +118,11 @@ export const en: Record<UsageKey, string> = {
   'usage.bank.save': 'Save image',
   'usage.bank.share': 'Share',
   'usage.bank.drawError': 'Failed to render the voucher: {error}',
+  'usage.foot.cost': 'Today spend',
+  'usage.foot.noData': 'No usage yet today',
+  'usage.foot.open': 'Open usage statistics settings',
+  'usage.foot.collapse': 'Collapse the usage card',
+  'usage.foot.expand': 'Expand the usage card',
 }
 
 export type UsageKey = keyof typeof zh

package/src/client/usage.module.css

@@ -381,3 +381,191 @@
   outline: none;
   box-shadow: 0 0 0 2px color-mix(in srgb, currentColor 45%, transparent);
 }
+
+
+/* ---------------------------------------------------------------------------
+   Sidebar foot card: the compact usage glance the mount seats as the shell
+   foot area's last child, directly below the Settings row. The chrome is an
+   outer div; the content is one transparent main button (the whole card opens
+   the usage settings section) with a sibling corner chevron toggling the
+   collapsed strip — sibling buttons, since nesting buttons is invalid HTML.
+   Quiet card on the same currentColor mixes as the section cards; hidden in
+   the 56px rail (the frame carries data-sidebar-collapsed).
+   --------------------------------------------------------------------------- */
+
+/* Seated above the Settings row as a native sidebar row: the shell's row
+   radius and hover fill, with none of the card chrome that made it read as a
+   pill pasted onto the foot. Only the expanded body keeps a faint surface to
+   hold its four lines together; the collapsed strip is a plain 36px row. */
+.footCard {
+  position: relative;
+  box-sizing: border-box;
+  width: 100%;
+  margin: 2px 0 4px;
+  border: none;
+  border-radius: 12px;
+  background: color-mix(in srgb, currentColor 4%, transparent);
+  color: inherit;
+  transition: background-color 120ms ease;
+}
+
+.footCard:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+.footCardCollapsed {
+  background: transparent;
+}
+
+.footMain {
+  appearance: none;
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  width: 100%;
+  padding: 8px;
+  border: none;
+  border-radius: 12px;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  text-align: left;
+  cursor: pointer;
+}
+
+.footMain:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 2px color-mix(in srgb, currentColor 45%, transparent);
+}
+
+.footToggle {
+  appearance: none;
+  position: absolute;
+  top: 6px;
+  right: 6px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 20px;
+  height: 20px;
+  padding: 0;
+  border: none;
+  border-radius: 6px;
+  background: transparent;
+  color: inherit;
+  cursor: pointer;
+  opacity: 0.55;
+  transition: opacity 120ms ease, background-color 120ms ease;
+}
+
+.footCard:hover .footToggle {
+  opacity: 0.8;
+}
+
+.footToggle:hover {
+  opacity: 1;
+  background: color-mix(in srgb, currentColor 10%, transparent);
+}
+
+.footToggle:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 2px color-mix(in srgb, currentColor 45%, transparent);
+}
+
+.footToggle svg {
+  display: block;
+}
+
+.footHead {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 8px;
+}
+
+.footTitle {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  min-width: 0;
+  font-size: 12px;
+  opacity: 0.65;
+  white-space: nowrap;
+}
+
+.footTitle svg {
+  display: block;
+  flex: none;
+}
+
+/* The headline value leaves room for the corner toggle. */
+.footValue {
+  margin-right: 18px;
+  font-size: 15px;
+  font-weight: 600;
+  font-variant-numeric: tabular-nums;
+  white-space: nowrap;
+}
+
+.footLine {
+  font-size: 11px;
+  opacity: 0.7;
+  font-variant-numeric: tabular-nums;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.footMeta {
+  font-size: 10px;
+  opacity: 0.5;
+  font-variant-numeric: tabular-nums;
+}
+
+/* Collapsed strip: tighter chrome, one horizontal line, room for the toggle. */
+.footCardCollapsed .footMain {
+  min-height: 36px;
+  padding: 7px 8px;
+}
+
+.footStrip {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding-right: 20px;
+  font-size: 12px;
+  white-space: nowrap;
+  overflow: hidden;
+}
+
+.footStrip svg {
+  display: block;
+  flex: none;
+  opacity: 0.65;
+}
+
+.footStripProvider {
+  flex: none;
+  max-width: 45%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  font-weight: 500;
+}
+
+.footStripLabel {
+  opacity: 0.65;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.footStripValue {
+  margin-left: auto;
+  font-weight: 600;
+  font-variant-numeric: tabular-nums;
+}
+
+:global([data-dsh-frame][data-sidebar-collapsed]) .footCard,
+:global([data-sidebar-collapsed]) .footCard {
+  display: none;
+}

package/src/core/adapters.ts

@@ -67,6 +67,11 @@ function str(value: unknown): string | undefined {
   return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined
 }
 
+/** Clamp a provider percentage into the renderable 0-100 band. */
+function clampPercent(value: number): number {
+  return Math.max(0, Math.min(100, value))
+}
+
 /** Format a number to a fixed 2-decimal display string. */
 function money(value: number): string {
   return value.toFixed(2)
@@ -190,7 +195,26 @@ const KIMI_CODING: ProviderAdapter = {
   },
 }
 
-/** GLM Coding Plan quota; auth is the RAW key without a Bearer prefix. */
+/**
+ * GLM Coding Plan quota windows, keyed by the provider's own `unit` code
+ * rather than by row position so an added or reordered limit cannot shift a
+ * window's meaning: 3 = the rolling 5-hour window, 6 = the weekly window,
+ * 5 = the monthly one. Two row kinds carry quota — `TOKENS_LIMIT` (token
+ * plans) and `CREDIT_LIMIT` (credit plans, whose exact ratio is
+ * `currentValue` / `usage`) — while `TIME_LIMIT` is the MCP request cap and
+ * is not a plan window at all. Auth is the RAW key without a Bearer prefix.
+ */
+const GLM_UNIT_KEYS: Readonly<Record<number, string>> = { 3: '5h', 5: 'month', 6: 'week' }
+
+/** Percent from a credit row's exact ratio, else the provider's own percentage. */
+function glmCreditPercent(row: Record<string, unknown>): number | undefined {
+  const used = toNum(row.currentValue)
+  const limit = toNum(row.usage)
+  if (used !== undefined && limit !== undefined && limit > 0) return clampPercent((used / limit) * 100)
+  const percentage = toNum(row.percentage)
+  return percentage === undefined ? undefined : clampPercent(percentage)
+}
+
 function glmPlan(host: string, ids: readonly string[]): ProviderAdapter {
   return {
     ids,
@@ -212,11 +236,21 @@ function glmPlan(host: string, ids: readonly string[]): ProviderAdapter {
         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)
+          const kind = str(row.type)
+          // The MCP request cap is a per-minute request budget, not a plan window.
+          if (kind === 'TIME_LIMIT') continue
+          const key = GLM_UNIT_KEYS[toNum(row.unit) ?? Number.NaN]
+          // Unknown units fall through: rendering them would invent a window.
+          if (key === undefined) continue
+          if (kind !== 'TOKENS_LIMIT' && kind !== 'CREDIT_LIMIT') continue
           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)),
+            key,
+            percent: kind === 'CREDIT_LIMIT'
+              ? glmCreditPercent(row)
+              : (() => {
+                  const percentage = toNum(row.percentage)
+                  return percentage === undefined ? undefined : clampPercent(percentage)
+                })(),
             resetsAt: toIso(row.nextResetTime),
           })
         }
@@ -409,7 +443,7 @@ export const PROVIDER_ADAPTERS: readonly ProviderAdapter[] = [
   moonshotBalance('api.moonshot.ai', 'USD', ['moonshotai']),
   KIMI_CODING,
   glmPlan('open.bigmodel.cn', ['zai-coding-cn']),
-  glmPlan('api.z.ai', ['zai-coding']),
+  glmPlan('api.z.ai', ['zai', 'zai-coding']),
   OPENCODE_GO,
   minimaxPlan('api.minimaxi.com', ['minimax-cn']),
   minimaxPlan('api.minimax.io', ['minimax']),

package/src/core/provider-routes.ts

@@ -0,0 +1,37 @@
+/**
+ * Alias folding for the enumerated provider routes. Kept in core because the
+ * rule is pure — the host enumerates routes and this decides which of two
+ * routes serving one adapter family survives.
+ * @module @linxin666/dsh-usage/core/provider-routes
+ */
+
+import { adapterFor } from './adapters.ts'
+
+/** The facts alias folding needs about one enumerated provider route. */
+export interface FoldableRoute {
+  /** Provider route key (`deepseek`, `deepseek-official`, custom routes, ...). */
+  id: string
+  /** Whether the LLM runtime serves requests on this route; a catalog-only entry is dormant. */
+  live: boolean
+}
+
+/**
+ * Drop dormant catalog aliases that shadow a live route of the same adapter
+ * family. The pi-ai catalog ships route keys the runtime serves nothing on
+ * until a profile declares them: for DeepSeek the catalog entry `deepseek`
+ * sits beside the llm-deepseek runtime route `deepseek-official`, and both
+ * resolve the same credential (the family's `apiKeyEnv` fallback), so probing
+ * and rendering both turns one account into two identical balance rows.
+ *
+ * A family keeps every live route it has — two configured profiles are two
+ * real accounts, not aliases. A route with no adapter, or one whose family
+ * has no live route at all, is returned untouched.
+ */
+export function foldAliasRoutes<T extends FoldableRoute>(routes: readonly T[]): T[] {
+  return routes.filter((route) => {
+    if (route.live) return true
+    const family = adapterFor(route.id)
+    if (family === undefined) return true
+    return !routes.some((other) => other.live && adapterFor(other.id) === family)
+  })
+}

package/src/core/types.ts

@@ -140,12 +140,25 @@ export interface ProviderSnapshotView {
 export interface UsageOverviewView {
   updatedAt: number
   providers: ProviderSnapshotView[]
-  /** The provider the pet bubble and the header highlight; `source` says how it was picked. */
+  /** The provider the collapsed sidebar strip 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'
+    /**
+     * Resolved display name (snapshot first, route-derived otherwise), so the
+     * strip needs no name-resolution of its own. Optional so an older host
+     * document still renders.
+     */
+    displayName?: string
+    /**
+     * Today's ledger totals for the provider's adapter family (the route
+     * itself when adapter-less), carrying tokens, calls, and the priced cost.
+     * Absent on a day without usage; optional for the same older-host
+     * tolerance as displayName.
+     */
+    today?: UsageTokenTotals
   }
   usage: {
     today: { date: string; totals: UsageTokenTotals; providers: UsageProviderSummary[] }

package/src/host/access.ts

@@ -0,0 +1,21 @@
+/**
+ * Usage trust fence (issue #1592): loopback (the desktop) always passes, and a
+ * live paired-device cookie is an additional allow path when remote-web-ui is
+ * loaded — the same family fence the skill center uses. Without that service
+ * the fence stays loopback-only, so an unpaired LAN browser keeps its 403.
+ * The decision logic lives in the generated pair-access.ts copy (shared by
+ * git-graph / pet / skill-explorer).
+ */
+import type { IncomingMessage } from 'node:http'
+import type { Context } from '@deepseek-ai/cordis'
+import { isPairedOrLoopbackAllowed } from './pair-access.ts'
+
+/**
+ * Whether this request may read the usage overview or trigger a refresh.
+ * @param ctx - host context; may expose remoteWebUiPairing.
+ * @param request - the incoming HTTP request.
+ * @returns true for loopback, or a live paired-device cookie.
+ */
+export function isUsageAllowed(ctx: Context, request: IncomingMessage): boolean {
+  return isPairedOrLoopbackAllowed(ctx, request)
+}

package/src/host/http.ts

@@ -2,7 +2,9 @@
 /**
  * Shared JSON body/response helpers for the host route families: one strict
  * bounded body reader, one lenient bounded body reader, one JSON object
- * narrow, and one JSON writer. Previously these were copy-pasted across the
+ * narrow, one JSON writer, and the outbound request-init helper that keeps a
+ * host fetch body decodable (withIdentityEncoding). Previously the readers
+ * were copy-pasted across the
  * package route files (routes.ts, update-routes.ts, mobile-api.ts, and each
  * family's route module) with drifting contracts: body caps ranging 4 KiB to
  * 1 MiB and four distinct overflow behaviors (reject, undefined, null, throw).
@@ -88,6 +90,26 @@ export function asJsonObject(value: unknown): Record<string, unknown> | undefine
   return isJsonObject(value) ? value : undefined
 }
 
+/**
+ * Request init that asks a remote origin for an uncompressed body.
+ *
+ * The DSH host boots `@deepseek-ai/dsh-http-proxy`, whose top-level import of
+ * the npm `undici` copy replaces the legacy `undici.globalDispatcher.1` slot
+ * Node's built-in `fetch()` reads. That cross-major wrapper drops the
+ * `content-encoding` header and automatic decompression, so a plain fetch
+ * resolves to raw gzip/brotli/zstd bytes — compressed noise no JSON or text
+ * consumer can read. Every host fetch that parses a remote body must request
+ * identity encoding. Caller headers survive; `accept-encoding` is forced to
+ * `identity` because a caller value has no decoder behind it in this host.
+ * @param init - the caller's request init (signal, headers, method, ...).
+ * @returns a copy with `accept-encoding: identity` merged in.
+ */
+export function withIdentityEncoding(init: RequestInit = {}): RequestInit {
+  const headers = new Headers(init.headers)
+  headers.set('accept-encoding', 'identity')
+  return { ...init, headers }
+}
+
 /**
  * Write one JSON response. Default headers are the family defaults
  * (content-type and referrer-policy); caller headers are appended or