@linxin666/dsh-usage 0.3.7

package/src/host/usage-service.ts

@@ -0,0 +1,530 @@
+/**
+ * The dsh-usage host service: folds live session usage into the persistent
+ * ledger, probes each configured provider's balance/coding-plan endpoint on
+ * a poll cycle, and announces the current provider's status to the pet
+ * bubble. Secrets stay in the host process; the browser only ever sees the
+ * overview document.
+ * @module @linxin666/dsh-usage/host/usage-service
+ */
+
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import type { Context } from '@deepseek-ai/cordis'
+import { credentialKey, credentialRef } from '@deepseek-ai/dsh-credentials'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import type { TokenUsage } from '@deepseek-ai/dsh-llm'
+import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+import { dshHome } from '../dsh-home.ts'
+import { adapterFor, providerErrorMessage } from '../core/adapters.ts'
+import type { BalanceParse, PlanParse } from '../core/adapters.ts'
+import { createLedgerDocument, deserializeLedger, foldUsage, ledgerDayKeys, localDateKey, pruneLedger, totalTokens } from '../core/ledger.ts'
+import type { BalanceView, CredentialKind, PlanView, ProviderSnapshotView, UsageLedgerDocument, UsageOverviewView, UsageTokenTotals } from '../core/types.ts'
+import { emptyTotals } from '../core/types.ts'
+
+/** Source tag the plugin stamps onto pet announcements. */
+export const USAGE_ANNOUNCE_SOURCE = 'dsh-usage'
+
+/** Per-route credential fact the probes run against. */
+interface ResolvedCredential {
+  kind: CredentialKind
+  key?: string
+}
+
+/** One live LLM provider route the service knows about. */
+interface ProviderRoute {
+  id: string
+  displayName: string
+}
+
+/** Poll-loop and announce options; re-applied live on settings change. */
+export interface UsageServiceOptions {
+  pollIntervalSec: number
+  bubbleMode: 'always' | 'change' | 'off'
+  retainDays: number
+}
+
+/** Probe timeout per HTTP call. */
+const PROBE_TIMEOUT_MS = 10_000
+
+/** Ledger flush debounce. */
+const FLUSH_DEBOUNCE_MS = 3_000
+
+/** How many trend days the overview serves. */
+const TREND_DAYS = 30
+
+/** Currency symbols the bubble and section render inline; other codes render as `12.00 EUR`. */
+const CURRENCY_SYMBOLS: Readonly<Record<string, string>> = { CNY: '¥', USD: '$', EUR: '€', GBP: '£' }
+
+/** Format a balance for display: symbol prefix when known, code suffix otherwise. */
+export function formatMoney(currency: string, totalBalance: string): string {
+  const symbol = CURRENCY_SYMBOLS[currency.toUpperCase()]
+  if (symbol !== undefined) return symbol + totalBalance
+  return `${totalBalance} ${currency.toUpperCase()}`
+}
+
+/** Map a used percent to the announcement tone. */
+export function planTone(percent: number): 'ok' | 'warn' | 'low' {
+  if (percent >= 90) return 'low'
+  if (percent >= 70) return 'warn'
+  return 'ok'
+}
+
+/** Best-effort typed service read: absent services resolve to undefined at runtime. */
+function service<T>(ctx: Context, name: string): T | undefined {
+  try {
+    return (ctx as unknown as { get(name: string): unknown }).get(name) as T | undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** Atomic JSON write through a temp file + rename. */
+async function writeJsonAtomic(path: string, value: unknown): Promise<void> {
+  const temp = path + '.tmp'
+  await writeFile(temp, JSON.stringify(value, null, 1), 'utf8')
+  await rename(temp, path)
+}
+
+/**
+ * Read a foreign settings namespace's resolved value (the llm adapter
+ * profiles, the agent default model). Unregistered namespaces read as
+ * undefined; nothing here throws into the poll loop.
+ */
+function readNamespace(ctx: Context, ns: string): unknown {
+  try {
+    const settings = service<{ get(ns: unknown): unknown }>(ctx, 'settings')
+    if (settings === undefined) return undefined
+    return settings.get(settingsNamespace(ns))
+  } catch {
+    return undefined
+  }
+}
+
+export class UsageService {
+  private readonly ctx: Context
+  private options: UsageServiceOptions
+  private readonly persistDir: string
+  private readonly ledgerPath: string
+  private readonly snapshotsPath: string
+
+  private ledger: UsageLedgerDocument = createLedgerDocument()
+  private readonly snapshots = new Map<string, ProviderSnapshotView>()
+  /** Per-live-session route attribution (WeakMap: disposed sessions age out). */
+  private readonly sessionRoutes = new WeakMap<Session, { provider: string; model: string }>()
+  /** The most recent route seen this boot; the pet bubble follows it. */
+  private current: { provider?: string; model?: string; source: 'live' | 'default' } = { source: 'default' }
+
+  private sessionListenerDisposer: (() => void) | undefined
+  private pollTimer: ReturnType<typeof setTimeout> | undefined
+  private flushTimer: ReturnType<typeof setTimeout> | undefined
+  private pollInFlight = false
+  private disposed = false
+  private lastSignature: string | undefined
+
+  constructor(ctx: Context, options: UsageServiceOptions) {
+    this.ctx = ctx
+    this.options = options
+    this.persistDir = join(dshHome(), 'dsh-usage')
+    this.ledgerPath = join(this.persistDir, 'usage-ledger.json')
+    this.snapshotsPath = join(this.persistDir, 'provider-snapshots.json')
+  }
+
+  /** Start the listeners, load persisted state, and arm the first poll. */
+  start(): void {
+    this.sessionListenerDisposer = this.ctx.on('session/event', (session, event) => this.onSessionEvent(session, event))
+    void this.loadPersisted()
+    this.rearmPoll(2_000)
+  }
+
+  /** Stop timers and flush pending ledger writes. */
+  stop(): void {
+    this.disposed = true
+    if (this.pollTimer !== undefined) clearTimeout(this.pollTimer)
+    if (this.flushTimer !== undefined) clearTimeout(this.flushTimer)
+    this.sessionListenerDisposer?.()
+    void this.flushLedger()
+  }
+
+  /** Re-apply options live (settings change); the poll cycle picks them up. */
+  applyOptions(options: UsageServiceOptions): void {
+    this.options = options
+  }
+
+  /** Force one poll now (manual refresh route). */
+  async refresh(): Promise<void> {
+    await this.pollNow()
+  }
+
+  /** Assemble the overview document the browser section renders. */
+  overview(): UsageOverviewView {
+    const todayKey = localDateKey(Date.now())
+    const routes = this.listProviderRoutes()
+    const providers: ProviderSnapshotView[] = []
+    for (const route of routes) {
+      const adapter = adapterFor(route.id)
+      const snapshot = this.snapshots.get(route.id)
+      providers.push({
+        provider: route.id,
+        displayName: route.displayName || adapter?.displayName || route.id,
+        credential: snapshot?.credential ?? 'none',
+        supported: adapter !== undefined && (adapter.balance !== undefined || adapter.plan !== undefined),
+        ...(snapshot?.balance !== undefined ? { balance: snapshot.balance } : {}),
+        ...(snapshot?.plan !== undefined ? { plan: snapshot.plan } : {}),
+        ...(snapshot?.error !== undefined ? { error: snapshot.error } : {}),
+        ...(snapshot?.updatedAt !== undefined ? { updatedAt: snapshot.updatedAt } : {}),
+      })
+    }
+    providers.sort((a, b) => Number(b.supported) - Number(a.supported) || a.displayName.localeCompare(b.displayName))
+    const days = ledgerDayKeys(this.ledger).slice(-TREND_DAYS)
+    return {
+      updatedAt: Date.now(),
+      providers,
+      current: { ...this.current },
+      usage: {
+        today: this.daySummary(todayKey),
+        days: days.map((date) => {
+          const summary = this.daySummary(date)
+          return { date, totals: summary.totals }
+        }),
+      },
+    }
+  }
+
+  /** One local day aggregated per provider. */
+  private daySummary(dateKey: string): UsageOverviewView['usage']['today'] {
+    const day = this.ledger.days[dateKey] ?? {}
+    const providers = Object.entries(day).map(([provider, models]) => {
+      const totals = emptyTotals()
+      const modelRows = Object.entries(models).map(([model, modelTotals]) => ({ model, totals: modelTotals }))
+      for (const row of modelRows) {
+        totals.inputTokens += row.totals.inputTokens
+        totals.outputTokens += row.totals.outputTokens
+        totals.cacheReadTokens += row.totals.cacheReadTokens
+        totals.cacheWriteTokens += row.totals.cacheWriteTokens
+        totals.reasoningTokens += row.totals.reasoningTokens
+        totals.calls += row.totals.calls
+      }
+      modelRows.sort((a, b) => totalTokens(b.totals) - totalTokens(a.totals))
+      return { provider, totals, models: modelRows.slice(0, 12) }
+    })
+    providers.sort((a, b) => totalTokens(b.totals) - totalTokens(a.totals))
+    const totals = emptyTotals()
+    for (const row of providers) {
+      totals.inputTokens += row.totals.inputTokens
+      totals.outputTokens += row.totals.outputTokens
+      totals.cacheReadTokens += row.totals.cacheReadTokens
+      totals.cacheWriteTokens += row.totals.cacheWriteTokens
+      totals.reasoningTokens += row.totals.reasoningTokens
+      totals.calls += row.totals.calls
+    }
+    return { date: dateKey, totals, providers }
+  }
+
+  // ------------------------------------------------------------------
+  // Session usage fold
+  // ------------------------------------------------------------------
+
+  private onSessionEvent(session: Session, event: SessionEvent): void {
+    try {
+      if (event.type === 'request/header') {
+        const config = (event.data as { header?: { config?: { provider?: string; model?: string } } }).header?.config
+        if (config?.provider !== undefined) {
+          this.sessionRoutes.set(session, { provider: config.provider, model: config.model ?? '' })
+          this.current = { provider: config.provider, model: config.model, source: 'live' }
+        }
+      } else if (event.type === 'request/context') {
+        const data = event.data as { provider?: string; model?: string }
+        if (data.provider !== undefined) {
+          this.sessionRoutes.set(session, { provider: data.provider, model: data.model ?? '' })
+          this.current = { provider: data.provider, model: data.model, source: 'live' }
+        }
+      } else if (event.type === 'assistant/message') {
+        const usage = (event.data as { usage?: TokenUsage }).usage
+        if (usage === undefined) return
+        const route = this.sessionRoutes.get(session)
+        if (route === undefined || route.provider === '') return
+        foldUsage(this.ledger, Date.now(), route.provider, route.model || 'unknown', this.totalsFrom(usage))
+        this.scheduleFlush()
+      }
+    } catch {
+      // A malformed event must never break the session loop.
+    }
+  }
+
+  /** Normalize a provider TokenUsage into the ledger bucket (one call). */
+  private totalsFrom(usage: TokenUsage): UsageTokenTotals {
+    const totals = emptyTotals()
+    totals.inputTokens = usage.inputTokens
+    totals.outputTokens = usage.outputTokens
+    totals.cacheReadTokens = usage.cacheReadTokens ?? 0
+    totals.cacheWriteTokens = usage.cacheWriteTokens ?? 0
+    totals.reasoningTokens = usage.reasoningTokens ?? 0
+    totals.calls = 1
+    return totals
+  }
+
+  // ------------------------------------------------------------------
+  // Persistence
+  // ------------------------------------------------------------------
+
+  private async loadPersisted(): Promise<void> {
+    try {
+      const [rawLedger, rawSnapshots] = await Promise.all([
+        readFile(this.ledgerPath, 'utf8').catch(() => undefined),
+        readFile(this.snapshotsPath, 'utf8').catch(() => undefined),
+      ])
+      if (rawLedger !== undefined) {
+        this.ledger = deserializeLedger(JSON.parse(rawLedger))
+        pruneLedger(this.ledger, localDateKey(Date.now()), this.options.retainDays)
+      }
+      if (rawSnapshots !== undefined) {
+        const parsed = JSON.parse(rawSnapshots) as { providers?: Record<string, ProviderSnapshotView> }
+        if (typeof parsed === 'object' && parsed !== null && typeof parsed.providers === 'object' && parsed.providers !== null) {
+          for (const [provider, snapshot] of Object.entries(parsed.providers)) {
+            if (typeof snapshot === 'object' && snapshot !== null && typeof snapshot.provider === 'string') {
+              this.snapshots.set(provider, snapshot)
+            }
+          }
+        }
+      }
+    } catch {
+      // Corrupt or unreadable state starts fresh; the next flush rewrites it.
+    }
+  }
+
+  private scheduleFlush(): void {
+    if (this.flushTimer !== undefined || this.disposed) return
+    this.flushTimer = setTimeout(() => {
+      this.flushTimer = undefined
+      void this.flushLedger()
+    }, FLUSH_DEBOUNCE_MS)
+  }
+
+  private async flushLedger(): Promise<void> {
+    try {
+      await mkdir(dirname(this.ledgerPath), { recursive: true })
+      await writeJsonAtomic(this.ledgerPath, this.ledger)
+    } catch {
+      // Persistence failures degrade silently; the in-memory ledger keeps counting.
+    }
+  }
+
+  private async persistSnapshots(): Promise<void> {
+    try {
+      await mkdir(dirname(this.snapshotsPath), { recursive: true })
+      await writeJsonAtomic(this.snapshotsPath, { version: 1, providers: Object.fromEntries(this.snapshots) })
+    } catch {
+      // Same silent degradation as the ledger.
+    }
+  }
+
+  // ------------------------------------------------------------------
+  // Poll loop
+  // ------------------------------------------------------------------
+
+  private rearmPoll(delayMs: number): void {
+    if (this.disposed) return
+    if (this.pollTimer !== undefined) clearTimeout(this.pollTimer)
+    this.pollTimer = setTimeout(() => {
+      this.pollTimer = undefined
+      void this.pollNow().finally(() => this.rearmPoll(Math.max(30, this.options.pollIntervalSec) * 1000))
+    }, delayMs)
+  }
+
+  /** One poll cycle: enumerate routes, resolve credentials, probe, announce. */
+  async pollNow(): Promise<void> {
+    if (this.pollInFlight || this.disposed) return
+    this.pollInFlight = true
+    try {
+      const routes = this.listProviderRoutes()
+      const seen = new Set<string>()
+      for (const route of routes) {
+        seen.add(route.id)
+        const adapter = adapterFor(route.id)
+        if (adapter === undefined || (adapter.balance === undefined && adapter.plan === undefined)) continue
+        await this.probeRoute(route, adapter)
+      }
+      for (const id of [...this.snapshots.keys()]) {
+        if (!seen.has(id)) this.snapshots.delete(id)
+      }
+      await this.persistSnapshots()
+      this.announceCurrent()
+    } finally {
+      this.pollInFlight = false
+    }
+  }
+
+  private listProviderRoutes(): ProviderRoute[] {
+    const routes = new Map<string, string>()
+    const runtime = service<{ listProviders(): Array<{ id: string; name: string }>; listConfigurableProviders(): Array<{ provider: string; displayName: string }> }>(this.ctx, 'llm')
+    if (runtime !== undefined) {
+      try {
+        for (const provider of runtime.listProviders()) {
+          if (provider.id !== '') routes.set(provider.id, provider.name)
+        }
+        for (const provider of runtime.listConfigurableProviders()) {
+          if (!routes.has(provider.provider)) routes.set(provider.provider, provider.displayName)
+        }
+      } catch {
+        // Registry hiccups degrade to an empty list; the next poll retries.
+      }
+    }
+    return [...routes].map(([id, displayName]) => ({ id, displayName }))
+  }
+
+  private async probeRoute(route: ProviderRoute, adapter: NonNullable<ReturnType<typeof adapterFor>>): Promise<void> {
+    const credential = await this.resolveCredential(route.id)
+    const previous = this.snapshots.get(route.id)
+    const snapshot: ProviderSnapshotView = {
+      provider: route.id,
+      displayName: route.displayName || adapter.displayName,
+      credential: credential.kind,
+      supported: true,
+      ...(previous?.balance !== undefined ? { balance: previous.balance } : {}),
+      ...(previous?.plan !== undefined ? { plan: previous.plan } : {}),
+      updatedAt: Date.now(),
+    }
+    if (credential.key === undefined) {
+      // Nothing to probe with (oauth grant, no credential): keep any previous
+      // facts visible and stay quiet about it.
+      snapshot.error = undefined
+      this.snapshots.set(route.id, snapshot)
+      return
+    }
+    let probed = false
+    const runProbe = async (kind: 'balance' | 'plan'): Promise<BalanceView | PlanView | undefined> => {
+      const half = adapter[kind]
+      if (half === undefined) return undefined
+      try {
+        const spec = half.build({ apiKey: credential.key as string })
+        const response = await fetch(spec.url, { headers: spec.headers, signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) })
+        const body: unknown = await response.json().catch(() => undefined)
+        if (!response.ok) throw new Error(providerErrorMessage(response.status, body))
+        const parsed = half.parse(response.status, body)
+        if (parsed === undefined) throw new Error('unrecognized response shape')
+        probed = true
+        const updatedAt = Date.now()
+        if (kind === 'balance') {
+          const fact = parsed as BalanceParse
+          return { currency: fact.currency, totalBalance: fact.totalBalance, updatedAt }
+        }
+        const plan = parsed as PlanParse
+        return { planName: plan.planName, windows: plan.windows, updatedAt }
+      } catch (error) {
+        snapshot.error = error instanceof Error ? error.message.slice(0, 200) : String(error)
+        return undefined
+      }
+    }
+    const balance = await runProbe('balance')
+    // A failed probe keeps the previous fact visible (stale but useful), with
+    // the error line explaining why it is stale.
+    if (balance !== undefined) snapshot.balance = balance as BalanceView
+    const plan = await runProbe('plan')
+    if (plan !== undefined) snapshot.plan = plan as PlanView
+    if (probed) snapshot.error = undefined
+    if (snapshot.balance === undefined && snapshot.plan === undefined && snapshot.error === undefined) {
+      snapshot.error = 'no credential configured'
+    }
+    this.snapshots.set(route.id, snapshot)
+  }
+
+  /**
+   * Resolve the credential backing one route: pi-ai credential records
+   * first, then the profile's apiKeyEnv reference, then the DeepSeek
+   * official adapter's env reference. OAuth grants resolve to a kind with
+   * no key (this plugin does not spend third-party OAuth budgets).
+   */
+  private async resolveCredential(provider: string): Promise<ResolvedCredential> {
+    const credentials = service<{
+      readRecord(key: unknown): Promise<{ kind: string; key?: string; env?: Record<string, string> } | undefined>
+      resolve(ref: unknown): Promise<{ value: string } | undefined>
+    }>(this.ctx, 'credentials')
+    if (credentials === undefined) return { kind: 'none' }
+    try {
+      const record = await credentials.readRecord(credentialKey('llm-pi-ai', provider))
+      if (record?.kind === 'api-key' && typeof record.key === 'string' && record.key !== '') {
+        return { kind: 'api-key', key: record.key }
+      }
+      if (record?.kind === 'grant') return { kind: 'oauth' }
+    } catch {
+      // Invalid record ids read as absent.
+    }
+    try {
+      const profile = this.piAiProfile(provider)
+      const envName = profile?.apiKeyEnv ?? (provider === 'deepseek' ? this.deepseekApiKeyEnv() : undefined)
+      if (typeof envName === 'string' && envName !== '') {
+        const resolved = await credentials.resolve(credentialRef(envName))
+        if (resolved?.value !== undefined && resolved.value !== '') return { kind: 'env', key: resolved.value }
+      }
+    } catch {
+      // Malformed references read as absent.
+    }
+    return { kind: 'none' }
+  }
+
+  /** The llm-pi-ai profile object for one provider route, when configured. */
+  private piAiProfile(provider: string): { apiKeyEnv?: string; baseURL?: string } | undefined {
+    const section = readNamespace(this.ctx, 'llm-pi-ai') as { providers?: Record<string, { apiKeyEnv?: string; baseURL?: string }> } | undefined
+    return section?.providers?.[provider]
+  }
+
+  /** The DeepSeek official adapter's credential reference name. */
+  private deepseekApiKeyEnv(): string {
+    const section = readNamespace(this.ctx, 'llm-deepseek') as { apiKeyEnv?: string } | undefined
+    return section?.apiKeyEnv ?? 'DEEPSEEK_API_KEY'
+  }
+
+  // ------------------------------------------------------------------
+  // Pet bubble
+  // ------------------------------------------------------------------
+
+  /**
+   * Announce the current provider's balance or plan usage to the pet. In
+   * `change` mode only meaningful value changes re-announce; `off` skips.
+   */
+  private announceCurrent(): void {
+    if (this.options.bubbleMode === 'off') return
+    let provider = this.current.provider
+    if (provider === undefined) {
+      const fallback = readNamespace(this.ctx, 'agent-default-model') as { provider?: string; model?: string } | undefined
+      if (fallback?.provider !== undefined) {
+        provider = fallback.provider
+        this.current = { provider: fallback.provider, model: fallback.model, source: 'default' }
+      } else {
+        return
+      }
+    }
+    const snapshot = this.snapshots.get(provider)
+    if (snapshot === undefined) return
+    let announcement: Record<string, unknown> | undefined
+    if (snapshot.balance !== undefined) {
+      announcement = {
+        kind: 'balance',
+        title: snapshot.displayName,
+        amount: formatMoney(snapshot.balance.currency, snapshot.balance.totalBalance),
+        tone: 'ok',
+      }
+    } else if (snapshot.plan !== undefined && snapshot.plan.windows.length > 0) {
+      const window = [...snapshot.plan.windows].sort((a, b) => (b.percent ?? 0) - (a.percent ?? 0))[0]
+      announcement = {
+        kind: 'plan',
+        title: snapshot.displayName,
+        ...(window.percent !== undefined ? { percent: window.percent } : {}),
+        ...(window.resetsAt !== undefined ? { resetAt: window.resetsAt } : {}),
+        ...(snapshot.plan.planName !== undefined ? { note: snapshot.plan.planName } : {}),
+        tone: window.percent !== undefined ? planTone(window.percent) : 'ok',
+      }
+    } else {
+      return
+    }
+    const signature = JSON.stringify(announcement)
+    if (this.options.bubbleMode === 'change' && signature === this.lastSignature) return
+    this.lastSignature = signature
+    const pet = service<{ announce(input: Record<string, unknown>): void }>(this.ctx, 'pet')
+    try {
+      pet?.announce({ source: USAGE_ANNOUNCE_SOURCE, ttlMs: undefined, ...announcement })
+    } catch {
+      // A missing or failing pet service must never break the poll loop.
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,90 @@
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-host-webserver'
+import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings'
+import z from 'schemastery'
+import { mountOnce } from './mount-once.ts'
+import { UsageService, type UsageServiceOptions } from './host/usage-service.ts'
+import { makeUsageOverviewRoute, makeUsageRefreshRoute } from './host/routes.ts'
+
+export const name = 'dsh-usage'
+export const inject = ['webServer']
+export const USAGE_SETTINGS_NAMESPACE = settingsNamespace('dsh-usage')
+
+export interface Config {
+  enabled?: boolean
+  /** Provider probe cycle in seconds; 30-3600. */
+  pollIntervalSec?: number
+  /** Pet bubble mode: always (refreshes each poll), change (only on value change), off. */
+  bubbleMode?: string
+  /** Ledger retention in local days. */
+  retainDays?: number
+}
+
+export const Config: z<Config> = z.object({
+  enabled: z.boolean().default(true),
+  pollIntervalSec: z.number().min(30).max(3600).default(60),
+  bubbleMode: z.string().default('always'),
+  retainDays: z.number().min(7).max(730).default(180),
+})
+
+export interface ResolvedConfig extends UsageServiceOptions {
+  enabled: boolean
+}
+
+export function resolveConfig(config?: Config): ResolvedConfig {
+  const bubbleMode = config?.bubbleMode === 'change' || config?.bubbleMode === 'off' ? config.bubbleMode : 'always'
+  return {
+    enabled: config?.enabled ?? true,
+    pollIntervalSec: typeof config?.pollIntervalSec === 'number' ? config.pollIntervalSec : 60,
+    bubbleMode,
+    retainDays: typeof config?.retainDays === 'number' ? config.retainDays : 180,
+  }
+}
+
+export const apply = mountOnce('@linxin666/dsh-usage', (ctx: Context, config?: Config): void => {
+  let source: () => Config = () => config ?? {}
+  let service: UsageService | undefined
+  let disposeRoutes: (() => void) | undefined
+
+  const rearm = (): void => {
+    const value = resolveConfig(source())
+    if (!value.enabled) {
+      service?.stop()
+      service = undefined
+      disposeRoutes?.()
+      disposeRoutes = undefined
+      return
+    }
+    if (service === undefined) {
+      service = new UsageService(ctx, value)
+      service.start()
+      const disposers = [makeUsageOverviewRoute(service), makeUsageRefreshRoute(service)]
+        .map((route) => ctx.webServer.register(route))
+      disposeRoutes = () => {
+        for (const dispose of disposers) {
+          try {
+            dispose()
+          } catch {
+            // Route fiber already gone during shutdown.
+          }
+        }
+      }
+    } else {
+      service.applyOptions(value)
+    }
+  }
+
+  installSettingsSection(ctx, USAGE_SETTINGS_NAMESPACE, Config, config ?? {}, {
+    setSource: (next) => { source = next; rearm() },
+    onChange: rearm,
+  })
+
+  ctx.effect(() => {
+    rearm()
+    return () => {
+      disposeRoutes?.()
+      service?.stop()
+      service = undefined
+    }
+  }, 'dsh-usage: runtime')
+})

package/src/mount-once.ts

@@ -0,0 +1,48 @@
+// Generated by scripts/sync-shared.mjs from shared/host/mount-once.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * Host single-instance guard shared by the plugin family. The family bundle
+ * (dsh-web-all / dsh-skins) namespaces every child row id (web-ui-*), so
+ * the loader accepts a standalone install of the same package side by side;
+ * without this guard the second instance would still re-register the same
+ * webserver routes, tools, settings namespaces, and system-prompt sections
+ * and fail the boot. mountOnce makes the second host apply a no-op for the
+ * lifetime of the first instance (the browser half is already deduped by
+ * package name in the client module host).
+ *
+ * The registry rides a global symbol so two module instances of the same
+ * package (npm copy vs repository link) still share one verdict. cordis
+ * `ctx.effect` runs its callback immediately and treats the callback's
+ * return value as the fiber disposer, so the unmarker is returned, not run.
+ */
+
+const MOUNTED = Symbol.for('dsh-web.mounted-plugins')
+
+interface MountRegistry {
+  [MOUNTED]?: Set<string>
+}
+
+function mountedSet(): Set<string> {
+  const registry = globalThis as MountRegistry
+  return (registry[MOUNTED] ??= new Set())
+}
+
+/**
+ * Wrap a cordis plugin apply so the package runs at most once per process.
+ * The first mount registers normally and unmarks when its fiber disposes;
+ * any later mount of the same package name is a no-op.
+ * @param packageName - npm package identity shared by every install source.
+ * @param fn - the original plugin apply.
+ * @returns an apply of the same shape.
+ */
+export function mountOnce<T extends (...args: any[]) => unknown>(packageName: string, fn: T): T {
+  return ((...args: unknown[]) => {
+    const mounted = mountedSet()
+    if (mounted.has(packageName)) return
+    mounted.add(packageName)
+    const ctx = args[0] as { effect?: (effect: () => unknown) => unknown } | undefined
+    ctx?.effect?.(() => () => {
+      mounted.delete(packageName)
+    })
+    return fn(...args)
+  }) as T
+}