@hanzo/usage 0.1.0

package/src/providers/hanzo.ts

@@ -0,0 +1,203 @@
+// Copyright (c) 2026 Hanzo AI Inc. MIT License.
+// Hanzo provider — two lanes:
+//  1. hanzo.cloud  — commerce billing usage (`GET {base}/v1/billing/usage`),
+//     the same source of truth console and chat bill against.
+//  2. hanzo.dev    — local probe of Hanzo Dev CLI rollouts
+//     ($HANZO_HOME|$CODEX_HOME|~/.hanzo|~/.codex sessions/YYYY/MM/DD/*.jsonl):
+//     the last persisted token_count event carries token totals and the
+//     latest rate-limit snapshot, exactly what the dev app-server replays.
+
+import type {
+  ProviderDescriptor,
+  ProviderFetchContext,
+  ProviderFetchResult,
+  ProviderFetchStrategy,
+} from '../provider.js'
+import { forMode } from '../provider.js'
+import type { RateWindow, UsageSnapshot } from '../types.js'
+import { expandHome } from '../host.js'
+
+// ---- cloud (commerce ledger) ----
+
+const num = (v: unknown): number => (typeof v === 'number' && Number.isFinite(v) ? v : 0)
+
+const cloudStrategy: ProviderFetchStrategy = {
+  id: 'hanzo.cloud',
+  kind: 'apiToken',
+  async isAvailable(ctx) {
+    return Boolean(ctx.settings?.getToken || ctx.settings?.apiKey)
+  },
+  async fetch(ctx): Promise<ProviderFetchResult> {
+    const base = ctx.settings?.baseUrl ?? 'https://api.hanzo.ai'
+    const token = (await ctx.settings?.getToken?.()) ?? ctx.settings?.apiKey
+    if (!token) throw new Error('hanzo: no token for cloud usage')
+    const res = await ctx.host.http({
+      url: `${base}/v1/billing/usage`,
+      headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
+      timeoutMs: 30_000,
+    })
+    if (res.status !== 200) throw new Error(`hanzo billing usage HTTP ${res.status}`)
+    const body = JSON.parse(res.text) as Record<string, unknown>
+    // Defensive roll-up: accept either precomputed totals or a ledger of entries.
+    const entries = Array.isArray(body.usage)
+      ? (body.usage as Array<Record<string, unknown>>)
+      : Array.isArray(body.data)
+        ? (body.data as Array<Record<string, unknown>>)
+        : []
+    let tokens = num(body.total_tokens ?? body.totalTokens)
+    let spendCents = num(body.spend_cents ?? body.spendCents)
+    let requests = num(body.total_requests ?? body.requests)
+    for (const e of entries) {
+      tokens += num(e.total_tokens ?? e.totalTokens ?? e.tokens)
+      spendCents += num(e.spend_cents ?? e.spendCents ?? e.cost_cents)
+      requests += num(e.requests ?? e.request_count ?? 1) - (e.requests === undefined && e.request_count === undefined ? 1 : 0)
+    }
+    const now = ctx.host.now().toISOString()
+    const usage: UsageSnapshot = {
+      providerId: 'hanzo',
+      identity: { providerId: 'hanzo', loginMethod: 'iam' },
+      providerCost: {
+        used: spendCents / 100,
+        currencyCode: 'USD',
+        period: 'monthly',
+        updatedAt: now,
+      },
+      totals: { tokens, requests },
+      dataConfidence: 'exact',
+      updatedAt: now,
+    }
+    return {
+      usage,
+      sourceLabel: 'Hanzo Cloud',
+      strategyId: this.id,
+      strategyKind: this.kind,
+    }
+  },
+}
+
+// ---- local dev CLI probe ----
+
+interface TokenCountRateLimitWindow {
+  used_percent?: number
+  window_minutes?: number
+  resets_in_seconds?: number
+}
+
+interface TokenCountPayload {
+  type?: string
+  info?: {
+    total_token_usage?: {
+      input_tokens?: number
+      cached_input_tokens?: number
+      output_tokens?: number
+      total_tokens?: number
+    }
+  }
+  rate_limits?: {
+    primary?: TokenCountRateLimitWindow
+    secondary?: TokenCountRateLimitWindow
+  }
+}
+
+const devHome = async (ctx: ProviderFetchContext): Promise<string | undefined> => {
+  const candidates = [
+    ctx.host.env('HANZO_HOME'),
+    ctx.host.env('CODEX_HOME'),
+    expandHome(ctx.host, '~/.hanzo'),
+    expandHome(ctx.host, '~/.codex'),
+  ].filter((c): c is string => Boolean(c))
+  for (const dir of candidates) {
+    if ((await ctx.host.listDir(`${dir}/sessions`)).length > 0) return dir
+  }
+  return undefined
+}
+
+/** Newest entry of a directory listing of numeric names (years, months, days). */
+const newest = (names: string[]): string | undefined =>
+  names.filter((n) => /^\d+$/.test(n)).sort().at(-1)
+
+const toRateWindow = (
+  w: TokenCountRateLimitWindow | undefined,
+  now: Date,
+): RateWindow | undefined => {
+  if (!w || typeof w.used_percent !== 'number') return undefined
+  return {
+    usedPercent: w.used_percent,
+    windowMinutes: w.window_minutes,
+    resetsAt:
+      typeof w.resets_in_seconds === 'number'
+        ? new Date(now.getTime() + w.resets_in_seconds * 1000).toISOString()
+        : undefined,
+  }
+}
+
+const devStrategy: ProviderFetchStrategy = {
+  id: 'hanzo.dev',
+  kind: 'localProbe',
+  async isAvailable(ctx) {
+    return Boolean(await devHome(ctx))
+  },
+  async fetch(ctx): Promise<ProviderFetchResult> {
+    const home = await devHome(ctx)
+    if (!home) throw new Error('hanzo: no dev CLI home with sessions')
+    const sessions = `${home}/sessions`
+    const year = newest(await ctx.host.listDir(sessions))
+    const month = year && newest(await ctx.host.listDir(`${sessions}/${year}`))
+    const day = month && newest(await ctx.host.listDir(`${sessions}/${year}/${month}`))
+    if (!day) throw new Error('hanzo: no dev sessions found')
+    const dayDir = `${sessions}/${year}/${month}/${day}`
+    const rollouts = (await ctx.host.listDir(dayDir))
+      .filter((f) => f.endsWith('.jsonl'))
+      .sort()
+    const latest = rollouts.at(-1)
+    if (!latest) throw new Error('hanzo: no rollout files today')
+    const text = (await ctx.host.readTextFile(`${dayDir}/${latest}`)) ?? ''
+    let payload: TokenCountPayload | undefined
+    for (const line of text.split('\n')) {
+      if (!line.includes('"token_count"')) continue
+      try {
+        const item = JSON.parse(line) as { payload?: TokenCountPayload }
+        if (item.payload?.type === 'token_count') payload = item.payload
+      } catch {
+        // tolerate partial trailing lines
+      }
+    }
+    const now = ctx.host.now()
+    const totals = payload?.info?.total_token_usage
+    const usage: UsageSnapshot = {
+      providerId: 'hanzo',
+      primary: toRateWindow(payload?.rate_limits?.primary, now),
+      secondary: toRateWindow(payload?.rate_limits?.secondary, now),
+      identity: { providerId: 'hanzo', loginMethod: 'dev-cli' },
+      totals: totals
+        ? {
+            tokens: totals.total_tokens ?? 0,
+            inputTokens: totals.input_tokens ?? 0,
+            outputTokens: totals.output_tokens ?? 0,
+            cachedInputTokens: totals.cached_input_tokens ?? 0,
+          }
+        : undefined,
+      dataConfidence: totals ? 'exact' : 'unknown',
+      updatedAt: now.toISOString(),
+    }
+    return {
+      usage,
+      sourceLabel: 'Hanzo Dev CLI',
+      strategyId: this.id,
+      strategyKind: this.kind,
+    }
+  },
+}
+
+export const hanzoProvider: ProviderDescriptor = {
+  id: 'hanzo',
+  metadata: {
+    displayName: 'Hanzo',
+    sessionLabel: '5h limit',
+    weeklyLabel: 'Weekly limit',
+    defaultEnabled: true,
+    dashboardUrl: 'https://console.hanzo.ai/billing/usage',
+    color: '#ff2d55',
+  },
+  strategies: (mode) => forMode([cloudStrategy, devStrategy], mode),
+}

package/src/react.ts

@@ -0,0 +1,12 @@
+// Copyright (c) 2026 Hanzo AI Inc. MIT License.
+// React binding — one hook, no extra state library.
+
+import { useSyncExternalStore } from 'react'
+import type { UsageStore, UsageStoreState } from './store.js'
+
+export const useUsage = (store: UsageStore): UsageStoreState =>
+  useSyncExternalStore(
+    (onChange) => store.subscribe(onChange),
+    () => store.getState(),
+    () => store.getState(),
+  )

package/src/store.ts

@@ -0,0 +1,209 @@
+// Copyright (c) 2026 Hanzo AI Inc. MIT License.
+// UsageStore — port of CodexBar's UsageStore + AdaptiveRefreshPolicy: central
+// observable state, concurrent refresh across providers, poll timer, and
+// plan-utilization history capture (schema-compatible with the Swift app).
+
+import type {
+  PlanUtilizationHistoryFile,
+  PlanUtilizationSeriesHistory,
+  CreditsSnapshot,
+  UsageSnapshot,
+} from './types.js'
+import type {
+  ProviderDescriptor,
+  ProviderFetchAttempt,
+  ProviderFetchContext,
+  ProviderSettings,
+  ProviderSourceMode,
+} from './provider.js'
+import { runPipeline } from './provider.js'
+import type { UsageHost } from './host.js'
+
+export interface ProviderState {
+  snapshot?: UsageSnapshot
+  credits?: CreditsSnapshot
+  error?: string
+  sourceLabel?: string
+  attempts?: ProviderFetchAttempt[]
+  refreshing: boolean
+}
+
+export interface UsageStoreState {
+  providers: Record<string, ProviderState>
+  refreshing: boolean
+  lastRefreshAt?: string
+}
+
+export interface UsageStoreOptions {
+  host: UsageHost
+  providers: ProviderDescriptor[]
+  sourceMode?: ProviderSourceMode
+  settings?: Record<string, ProviderSettings>
+  /** Poll interval in ms; default 5 minutes (CodexBar's default). */
+  intervalMs?: number
+  /** Directory for history JSON files; omit to keep history in memory only. */
+  historyDir?: string
+}
+
+type Listener = () => void
+
+const HISTORY_MAX_ENTRIES = 2000
+
+export class UsageStore {
+  private readonly opts: UsageStoreOptions
+  private state: UsageStoreState = { providers: {}, refreshing: false }
+  private listeners = new Set<Listener>()
+  private timer: ReturnType<typeof setInterval> | undefined
+  private history = new Map<string, PlanUtilizationSeriesHistory[]>()
+
+  constructor(opts: UsageStoreOptions) {
+    this.opts = opts
+    for (const p of opts.providers) {
+      this.state.providers[p.id] = { refreshing: false }
+    }
+  }
+
+  getState(): UsageStoreState {
+    return this.state
+  }
+
+  subscribe(listener: Listener): () => void {
+    this.listeners.add(listener)
+    return () => this.listeners.delete(listener)
+  }
+
+  private emit(next: Partial<UsageStoreState>): void {
+    this.state = { ...this.state, ...next }
+    for (const l of this.listeners) l()
+  }
+
+  private setProvider(id: string, patch: Partial<ProviderState>): void {
+    this.emit({
+      providers: {
+        ...this.state.providers,
+        [id]: { ...this.state.providers[id], refreshing: false, ...patch },
+      },
+    })
+  }
+
+  async refresh(providerId?: string): Promise<void> {
+    const targets = this.opts.providers.filter((p) => !providerId || p.id === providerId)
+    this.emit({ refreshing: true })
+    await Promise.all(targets.map((p) => this.refreshProvider(p)))
+    this.emit({ refreshing: false, lastRefreshAt: this.opts.host.now().toISOString() })
+  }
+
+  private async refreshProvider(descriptor: ProviderDescriptor): Promise<void> {
+    this.setProvider(descriptor.id, { refreshing: true })
+    const ctx: ProviderFetchContext = {
+      host: this.opts.host,
+      sourceMode: this.opts.sourceMode ?? 'auto',
+      settings: this.opts.settings?.[descriptor.id],
+    }
+    const outcome = await runPipeline(descriptor, ctx)
+    if (outcome.result) {
+      this.setProvider(descriptor.id, {
+        snapshot: outcome.result.usage,
+        credits: outcome.result.credits,
+        sourceLabel: outcome.result.sourceLabel,
+        attempts: outcome.attempts,
+        error: undefined,
+      })
+      await this.captureHistory(outcome.result.usage)
+    } else {
+      // Keep stale data over flapping — errors annotate, they don't erase.
+      this.setProvider(descriptor.id, {
+        error:
+          outcome.error instanceof Error ? outcome.error.message : String(outcome.error),
+        attempts: outcome.attempts,
+      })
+    }
+  }
+
+  start(): void {
+    if (this.timer) return
+    const interval = this.opts.intervalMs ?? 5 * 60 * 1000
+    this.timer = setInterval(() => void this.refresh(), interval)
+    void this.refresh()
+  }
+
+  stop(): void {
+    if (this.timer) clearInterval(this.timer)
+    this.timer = undefined
+  }
+
+  // ---- plan-utilization history (sparkline data) ----
+
+  getHistory(providerId: string): PlanUtilizationSeriesHistory[] {
+    return this.history.get(providerId) ?? []
+  }
+
+  private async captureHistory(snapshot: UsageSnapshot): Promise<void> {
+    const lanes: Array<{ name: string; windowMinutes: number; usedPercent?: number; resetsAt?: string }> = [
+      {
+        name: 'session',
+        windowMinutes: snapshot.primary?.windowMinutes ?? 300,
+        usedPercent: snapshot.primary?.usedPercent,
+        resetsAt: snapshot.primary?.resetsAt,
+      },
+      {
+        name: 'weekly',
+        windowMinutes: snapshot.secondary?.windowMinutes ?? 10_080,
+        usedPercent: snapshot.secondary?.usedPercent,
+        resetsAt: snapshot.secondary?.resetsAt,
+      },
+    ]
+    let series = this.history.get(snapshot.providerId)
+    if (!series) {
+      series = await this.loadHistory(snapshot.providerId)
+      this.history.set(snapshot.providerId, series)
+    }
+    const capturedAt = snapshot.updatedAt
+    // Hour-bucketed dedup, as the Swift store does.
+    const bucket = capturedAt.slice(0, 13)
+    for (const lane of lanes) {
+      if (typeof lane.usedPercent !== 'number') continue
+      let s = series.find((x) => x.name === lane.name)
+      if (!s) {
+        s = { name: lane.name, windowMinutes: lane.windowMinutes, entries: [] }
+        series.push(s)
+      }
+      const last = s.entries.at(-1)
+      if (last && last.capturedAt.slice(0, 13) === bucket) {
+        last.usedPercent = lane.usedPercent
+        last.resetsAt = lane.resetsAt
+      } else {
+        s.entries.push({ capturedAt, usedPercent: lane.usedPercent, resetsAt: lane.resetsAt })
+        if (s.entries.length > HISTORY_MAX_ENTRIES) s.entries.splice(0, s.entries.length - HISTORY_MAX_ENTRIES)
+      }
+    }
+    await this.persistHistory(snapshot.providerId, series)
+  }
+
+  private historyPath(providerId: string): string | undefined {
+    return this.opts.historyDir ? `${this.opts.historyDir}/${providerId}.json` : undefined
+  }
+
+  private async loadHistory(providerId: string): Promise<PlanUtilizationSeriesHistory[]> {
+    const path = this.historyPath(providerId)
+    if (!path) return []
+    const text = await this.opts.host.readTextFile(path)
+    if (!text) return []
+    try {
+      const file = JSON.parse(text) as PlanUtilizationHistoryFile
+      return file.version === 1 ? file.unscoped : []
+    } catch {
+      return []
+    }
+  }
+
+  private async persistHistory(
+    providerId: string,
+    series: PlanUtilizationSeriesHistory[],
+  ): Promise<void> {
+    const path = this.historyPath(providerId)
+    if (!path) return
+    const file: PlanUtilizationHistoryFile = { version: 1, unscoped: series }
+    await this.opts.host.writeTextFile(path, JSON.stringify(file))
+  }
+}

package/src/types.ts

@@ -0,0 +1,160 @@
+// Copyright (c) 2026 Hanzo AI Inc. MIT License.
+// TypeScript port of CodexBarCore's data model (UsageFetcher.swift, CreditsModels.swift,
+// CostUsageModels.swift). Wire-compatible JSON where the Swift app persists snapshots.
+
+/** Universal quota unit — one rate-limit window (session/5h, weekly, …). */
+export interface RateWindow {
+  /** 0–100 percent used. */
+  usedPercent: number
+  /** Window length in minutes (300 = 5h, 10080 = weekly). */
+  windowMinutes?: number
+  /** Absolute reset time, ISO 8601. */
+  resetsAt?: string
+  /** Textual reset description when only scraped text is available. */
+  resetDescription?: string
+  /** Rolling-recovery providers: percent that regenerates next. */
+  nextRegenPercent?: number
+  /** True when a lane was fabricated (e.g. provider returned null for it). */
+  isSyntheticPlaceholder?: boolean
+}
+
+export const remainingPercent = (w: RateWindow): number =>
+  Math.max(0, 100 - w.usedPercent)
+
+export interface NamedRateWindow {
+  id: string
+  title: string
+  window: RateWindow
+  usageKnown: boolean
+}
+
+export type UsageDataConfidence = 'exact' | 'estimated' | 'percentOnly' | 'unknown'
+
+export interface ProviderIdentity {
+  providerId: string
+  accountEmail?: string
+  accountOrganization?: string
+  loginMethod?: string
+  plan?: string
+}
+
+/** Per-provider fetch result — the central value of the system. */
+export interface UsageSnapshot {
+  providerId: string
+  /** Session / 5h lane. */
+  primary?: RateWindow
+  /** Weekly lane. */
+  secondary?: RateWindow
+  tertiary?: RateWindow
+  /** Model-specific or auxiliary windows. */
+  extraRateWindows?: NamedRateWindow[]
+  identity?: ProviderIdentity
+  dataConfidence: UsageDataConfidence
+  subscriptionExpiresAt?: string
+  subscriptionRenewsAt?: string
+  providerCost?: ProviderCostSnapshot
+  /** Absolute token totals when the source reports them (exact confidence). */
+  totals?: UsageTotals
+  updatedAt: string
+}
+
+export interface UsageTotals {
+  tokens: number
+  inputTokens?: number
+  outputTokens?: number
+  cachedInputTokens?: number
+  requests?: number
+}
+
+export interface CreditEvent {
+  id: string
+  date: string
+  service: string
+  creditsUsed: number
+}
+
+export interface CreditsSnapshot {
+  remaining: number
+  unlimited?: boolean
+  events?: CreditEvent[]
+  updatedAt: string
+}
+
+/** Generic spend/budget meter used by API providers. */
+export interface ProviderCostSnapshot {
+  used: number
+  limit?: number
+  currencyCode: string
+  period?: string
+  resetsAt?: string
+  updatedAt: string
+}
+
+// ---- Cost usage (offline JSONL session-log scanning, à la ccusage) ----
+
+export interface ModelBreakdown {
+  modelName: string
+  costUSD: number
+  totalTokens: number
+  requestCount: number
+}
+
+export interface CostUsageDailyEntry {
+  /** "YYYY-MM-DD" */
+  date: string
+  inputTokens: number
+  cacheReadTokens: number
+  cacheCreationTokens: number
+  outputTokens: number
+  totalTokens: number
+  requestCount: number
+  costUSD: number
+  modelsUsed: string[]
+  modelBreakdowns?: ModelBreakdown[]
+}
+
+export interface CostUsageTokenSnapshot {
+  providerId: string
+  sessionTokens: number
+  sessionCostUSD: number
+  sessionRequests: number
+  last30DaysTokens: number
+  last30DaysCostUSD: number
+  last30DaysRequests: number
+  currencyCode: string
+  historyDays: number
+  daily: CostUsageDailyEntry[]
+  updatedAt: string
+}
+
+// ---- History (sparklines) — schema-compatible with PlanUtilizationHistoryStore v1 ----
+
+export interface PlanUtilizationEntry {
+  capturedAt: string
+  usedPercent: number
+  resetsAt?: string
+}
+
+export interface PlanUtilizationSeriesHistory {
+  /** "session" | "weekly" | named lane */
+  name: string
+  windowMinutes: number
+  entries: PlanUtilizationEntry[]
+}
+
+export interface PlanUtilizationHistoryFile {
+  version: 1
+  preferredAccountKey?: string
+  unscoped: PlanUtilizationSeriesHistory[]
+  accounts?: Record<string, PlanUtilizationSeriesHistory[]>
+}
+
+// ---- Provider status (statuspage.io etc.) ----
+
+export type StatusIndicator = 'none' | 'minor' | 'major' | 'critical' | 'unknown'
+
+export interface ProviderStatus {
+  indicator: StatusIndicator
+  description?: string
+  updatedAt: string
+}