@qadanm/opencode-smart-router 0.0.0-stage → 0.4.0

package/src/core/quota/reconcile.ts

@@ -0,0 +1,155 @@
+import { OPENDESIGN_MODELS } from "../providers/opendesign-models.js"
+import { creditMultiplierFor } from "../providers/opendesign-credits.js"
+import type { UsageReading } from "../plan-page.js"
+
+/**
+ * Check the router's cost model against what the account was actually charged.
+ *
+ * This is the whole reason a usage paste beats an allowance paste. A percentage
+ * tells you how much allowance is left; a usage table tells you whether the
+ * arithmetic that predicted it was right in the first place.
+ *
+ * For one model, charged credits divided by the published base price gives the
+ * multiplier that was actually applied. Compare that to the multiplier the
+ * catalog believes, and the disagreement — if any — is measured rather than
+ * assumed. Ten wrong prices were found exactly this way, by comparing numbers
+ * instead of trusting comments.
+ *
+ * Nothing here writes anything. A disagreement is reported for a human to
+ * decide on, because a usage page is one window of one account and a catalog is
+ * meant to describe everyone.
+ */
+
+export interface ReconcileRow {
+  readonly modelName: string
+  readonly modelID?: string
+  /** Credits charged, as USD-equivalent. */
+  readonly chargedUsd: number
+  /** What the router's prices say that usage should have cost, before multiplier. */
+  readonly baseUsd?: number
+  /** chargedUsd / baseUsd — the multiplier the account actually applied. */
+  readonly impliedMultiplier?: number
+  /** The multiplier the catalog believes. */
+  readonly catalogMultiplier?: number
+  readonly verdict: "agrees" | "differs" | "unmatched" | "no-price"
+  /** For a differing row, how far apart in relative terms. */
+  readonly driftPct?: number
+}
+
+export interface ReconcileResult {
+  readonly rows: ReadonlyArray<ReconcileRow>
+  readonly agree: number
+  readonly differ: number
+  readonly unmatched: number
+  /** One sentence for the panel. */
+  readonly summary: string
+}
+
+/** Normalise a display name for matching: "DeepSeek V4.1 Flash" -> "deepseekv41flash". */
+const normaliseName = (value: string): string =>
+  value.toLowerCase().replace(/\(.*?\)/g, "").replace(/[^a-z0-9]/g, "")
+
+const byNormalisedName = new Map(OPENDESIGN_MODELS.map((model) => [normaliseName(model.name), model]))
+
+/** Names the console may use that differ from our label. */
+const ALIASES: Readonly<Record<string, string>> = {
+  deepseekv41flash: "deepseek-v4.1-flash",
+  deepseekv4flash: "deepseek-v4-flash",
+  deepseekv4pro: "deepseek-v4-pro",
+  glm53flash: "glm-5.3-flash",
+  glm53flashx: "glm-5.3-flashx",
+  claudehaiku55: "claude-haiku-5.5",
+  gpt6luna: "gpt-6-luna",
+  mimo26flash: "mimo-v2.6-flash",
+  mimo26pro: "mimo-v2.6-pro",
+  kimik27code: "kimi-k2.7-code",
+}
+
+const resolveModel = (name: string) => {
+  const key = normaliseName(name)
+  const direct = byNormalisedName.get(key)
+  if (direct) return direct
+  const aliasID = ALIASES[key as keyof typeof ALIASES]
+  if (aliasID) return OPENDESIGN_MODELS.find((model) => model.modelID === aliasID)
+  return undefined
+}
+
+/** Within this much, a rounding difference is not a finding. */
+const TOLERANCE_PCT = 5
+
+export const reconcileUsage = (reading: UsageReading): ReconcileResult => {
+  const rows: ReconcileRow[] = []
+
+  for (const row of reading.rows) {
+    if (row.chargedUsd === undefined || !row.modelName) continue
+    const model = resolveModel(row.modelName)
+    if (!model) {
+      rows.push({
+        modelName: row.modelName,
+        chargedUsd: row.chargedUsd,
+        verdict: "unmatched",
+      })
+      continue
+    }
+
+    const tier = model.cost[0]
+    if (!tier) {
+      rows.push({
+        modelName: row.modelName,
+        modelID: model.modelID,
+        chargedUsd: row.chargedUsd,
+        verdict: "no-price",
+      })
+      continue
+    }
+
+    const input = row.inputTokens ?? 0
+    const output = row.outputTokens ?? 0
+    const cacheRead = row.cacheReadTokens ?? 0
+    // Tokens absent means the base cost cannot be reconstructed; the row still
+    // proves a charge happened, which is why it is kept rather than dropped.
+    const baseUsd =
+      input + output + cacheRead === 0
+        ? undefined
+        : (tier.input * input + tier.output * output + (tier.cache?.read ?? 0) * cacheRead) / 1_000_000
+
+    if (baseUsd === undefined || baseUsd <= 0) {
+      rows.push({
+        modelName: row.modelName,
+        modelID: model.modelID,
+        chargedUsd: row.chargedUsd,
+        verdict: "no-price",
+      })
+      continue
+    }
+
+    const impliedMultiplier = row.chargedUsd / baseUsd
+    const catalogMultiplier = creditMultiplierFor(model.modelID).multiplier
+    const driftPct = catalogMultiplier === 0 ? undefined : ((impliedMultiplier - catalogMultiplier) / catalogMultiplier) * 100
+    const agrees = driftPct !== undefined && Math.abs(driftPct) <= TOLERANCE_PCT
+
+    rows.push({
+      modelName: row.modelName,
+      modelID: model.modelID,
+      chargedUsd: row.chargedUsd,
+      baseUsd,
+      impliedMultiplier,
+      catalogMultiplier,
+      verdict: agrees ? "agrees" : "differs",
+      ...(driftPct !== undefined ? { driftPct } : {}),
+    })
+  }
+
+  const agree = rows.filter((row) => row.verdict === "agrees").length
+  const differ = rows.filter((row) => row.verdict === "differs").length
+  const unmatched = rows.filter((row) => row.verdict !== "agrees" && row.verdict !== "differs").length
+
+  const summary =
+    rows.length === 0
+      ? "No charged amounts on that page, so the cost model cannot be checked from it."
+      : differ === 0
+        ? `The cost model matches what was charged for ${agree} of ${rows.length} model${rows.length === 1 ? "" : "s"}.`
+        : `The cost model disagrees with what was charged for ${differ} of ${rows.length} model${rows.length === 1 ? "" : "s"}. That is a catalog problem, not a routing one.`
+
+  return { rows, agree, differ, unmatched, summary }
+}

package/src/core/quota/report.ts

@@ -0,0 +1,261 @@
+/**
+ * Usage aggregation and forecasting.
+ *
+ * The earlier ledger kept a flat, capped array of events, so a heavy afternoon
+ * erased the start of the week and no weekly or monthly projection was
+ * possible. The ledger now folds aged events into hourly buckets; this module
+ * turns those into the windows a plan actually meters, and projects
+ * consumption against the window that will reset first.
+ *
+ * Everything here is an estimate unless a provider snapshot supplied the
+ * numbers, and each figure says which it is.
+ */
+
+import type { UsageEvent } from "../types.js"
+
+const FIVE_HOURS_MS = 5 * 60 * 60 * 1000
+const WEEK_MS = 7 * 24 * 60 * 60 * 1000
+const DAY_MS = 24 * 60 * 60 * 1000
+
+export interface WindowTotals {
+  readonly since: number
+  readonly until: number
+  readonly requests: number
+  readonly input: number
+  readonly output: number
+  readonly cacheRead: number
+  readonly cacheWrite: number
+  readonly usd: number
+  readonly failures: number
+  readonly latencyMsTotal: number
+  readonly latencySamples: number
+}
+
+export interface Forecast {
+  /** Credits or dollars projected over the full window at the current rate. */
+  readonly projectedUsd: number
+  /** Hours of representative data the projection is based on. */
+  readonly basisHours: number
+  /** When the allowance would run out at the current rate, if it would. */
+  readonly exhaustsAt?: number
+  /** True when the projection exceeds the remaining allowance. */
+  readonly willExhaust: boolean
+  /** Short, plain-language explanation for a dashboard. */
+  readonly explanation: string
+}
+
+export interface UsageSource {
+  aggregate(input: { providerID?: string; modelID?: string; since: number; until?: number }): WindowTotals
+  usageByModel(input: { since: number; until?: number }): Array<{
+    providerID: string
+    modelID: string
+    requests: number
+    input: number
+    output: number
+    cacheRead: number
+    cacheWrite: number
+    usd: number
+  }>
+  readonly usageEvents: ReadonlyArray<UsageEvent>
+}
+
+/**
+ * Project consumption from a representative recent window.
+ *
+ * The basis is capped so a long quiet stretch cannot dilute a burst, and
+ * floored so a burst of a few minutes is not extrapolated into a month. Both
+ * bounds are stated in the explanation rather than hidden.
+ */
+export const forecast = (input: {
+  windowMs: number
+  now: number
+  spendInWindowUsd: number
+  /** Earliest instant with representative activity, if known. */
+  activityStart?: number
+  remainingUsd?: number
+  label: string
+}): Forecast => {
+  const windowStart = input.now - input.windowMs
+  const earliest = Math.max(windowStart, input.activityStart ?? windowStart)
+  // A representative basis: at least one hour, at most the full window.
+  const basisMs = Math.min(
+    input.windowMs,
+    Math.max(60 * 60 * 1000, input.now - earliest),
+  )
+  const basisHours = basisMs / (60 * 60 * 1000)
+  const windowHours = input.windowMs / (60 * 60 * 1000)
+  const perHour = input.spendInWindowUsd / Math.max(0.001, basisHours)
+  const projectedUsd = perHour * windowHours
+  const remaining = input.remainingUsd
+  const willExhaust = remaining !== undefined && projectedUsd > remaining
+  const exhaustsAt =
+    willExhaust && perHour > 0
+      ? input.now + (Math.max(0, remaining ?? 0) / perHour) * 60 * 60 * 1000
+      : undefined
+  const explanation = willExhaust
+    ? `At the current rate the ${input.label} allowance runs out about ${formatRelative(exhaustsAt ?? input.now, input.now)}.`
+    : `At the current rate the ${input.label} allowance covers the full window.`
+  return {
+    projectedUsd,
+    basisHours,
+    ...(exhaustsAt !== undefined ? { exhaustsAt } : {}),
+    willExhaust,
+    explanation,
+  }
+}
+
+export const formatRelative = (at: number, now: number): string => {
+  const delta = at - now
+  if (delta <= 0) return "now"
+  const hours = delta / (60 * 60 * 1000)
+  if (hours < 1) return `${Math.round(delta / 60_000)} minutes from now`
+  if (hours < 48) return `${hours.toFixed(1)} hours from now`
+  return `${(hours / 24).toFixed(1)} days from now`
+}
+
+export interface ProviderUsageReport {
+  readonly providerID: string
+  readonly label: string
+  readonly plan: string
+  readonly source: "provider" | "estimate" | "unknown"
+  readonly quotaState?: string
+  readonly fiveHour: WindowTotals
+  readonly weekly: WindowTotals
+  readonly monthly: WindowTotals
+  readonly cacheSharePct: number
+  readonly byModel: Array<{
+    providerID: string
+    modelID: string
+    requests: number
+    input: number
+    output: number
+    cacheRead: number
+    cacheWrite: number
+    usd: number
+  }>
+  readonly forecasts: ReadonlyArray<{ window: string; forecast: Forecast }>
+  readonly notes: ReadonlyArray<string>
+}
+
+/**
+ * Build a per-provider report from durable aggregates.
+ *
+ * A plan with no five-hour window reports `fiveHour` with zero requests rather
+ * than pretending a limit exists, so a dashboard can tell "unused" apart from
+ * "not applicable".
+ */
+export const buildProviderUsageReport = (input: {
+  providerID: string
+  label: string
+  plan: string
+  source: "provider" | "estimate" | "unknown"
+  quotaState?: string
+  now: number
+  source_: UsageSource
+  hasFiveHourWindow: boolean
+  hasWeeklyWindow: boolean
+  remainingMonthlyUsd?: number
+  notes: ReadonlyArray<string>
+}): ProviderUsageReport => {
+  const { now, source_ } = input
+  const monthStart = now - 30 * DAY_MS
+  const fiveHour = input.hasFiveHourWindow
+    ? source_.aggregate({ providerID: input.providerID, since: now - FIVE_HOURS_MS, until: now })
+    : emptyTotals(now - FIVE_HOURS_MS, now)
+  const weekly = input.hasWeeklyWindow
+    ? source_.aggregate({ providerID: input.providerID, since: now - WEEK_MS, until: now })
+    : emptyTotals(now - WEEK_MS, now)
+  const monthly = source_.aggregate({ providerID: input.providerID, since: monthStart, until: now })
+  const byModel = source_.usageByModel({ since: monthStart, until: now })
+    .filter((entry) => entry.providerID === input.providerID)
+
+  const totalInput = monthly.input + monthly.cacheRead + monthly.cacheWrite
+  const cacheSharePct = totalInput > 0 ? (monthly.cacheRead / totalInput) * 100 : 0
+
+  const activityStart = earliestActivity(source_.usageEvents, input.providerID)
+  const forecasts = [
+    ...(input.hasFiveHourWindow
+      ? [{
+          window: "5-hour",
+          forecast: forecast({
+            windowMs: FIVE_HOURS_MS,
+            now,
+            spendInWindowUsd: fiveHour.usd,
+            ...(activityStart !== undefined ? { activityStart } : {}),
+            label: `${input.label} five-hour`,
+          }),
+        }]
+      : []),
+    ...(input.hasWeeklyWindow
+      ? [{
+          window: "7-day",
+          forecast: forecast({
+            windowMs: WEEK_MS,
+            now,
+            spendInWindowUsd: weekly.usd,
+            ...(activityStart !== undefined ? { activityStart } : {}),
+            label: `${input.label} seven-day`,
+          }),
+        }]
+      : []),
+    {
+      window: "monthly",
+      forecast: forecast({
+        windowMs: 30 * DAY_MS,
+        now,
+        spendInWindowUsd: monthly.usd,
+        ...(activityStart !== undefined ? { activityStart } : {}),
+        ...(input.remainingMonthlyUsd !== undefined
+          ? { remainingUsd: input.remainingMonthlyUsd }
+          : {}),
+        label: `${input.label} monthly`,
+      }),
+    },
+  ]
+
+  return {
+    providerID: input.providerID,
+    label: input.label,
+    plan: input.plan,
+    source: input.source,
+    ...(input.quotaState ? { quotaState: input.quotaState } : {}),
+    fiveHour,
+    weekly,
+    monthly,
+    cacheSharePct,
+    byModel,
+    forecasts,
+    notes: [
+      ...input.notes,
+      input.hasFiveHourWindow
+        ? "This plan meters a five-hour window."
+        : "This plan has no five-hour window; that row is not a limit being ignored.",
+    ],
+  }
+}
+
+const emptyTotals = (since: number, until: number): WindowTotals => ({
+  since,
+  until,
+  requests: 0,
+  input: 0,
+  output: 0,
+  cacheRead: 0,
+  cacheWrite: 0,
+  usd: 0,
+  failures: 0,
+  latencyMsTotal: 0,
+  latencySamples: 0,
+})
+
+const earliestActivity = (
+  events: ReadonlyArray<UsageEvent>,
+  providerID: string,
+): number | undefined => {
+  let earliest: number | undefined
+  for (const event of events) {
+    if (event.providerID !== providerID) continue
+    if (earliest === undefined || event.at < earliest) earliest = event.at
+  }
+  return earliest
+}

package/src/core/quota/service.ts

@@ -0,0 +1,273 @@
+import type { ProviderQuotaSnapshot, ProviderSettings, QuotaWindow, UsageEvent } from "../types.js"
+import { probeCommandCodeQuota, type FetchLike } from "./commandcode.js"
+import { probeOpenCodeGoQuota } from "./opencode-go.js"
+import { probeOpenDesignQuota, OPENDESIGN_MONTH_MS } from "./opendesign.js"
+
+export interface QuotaCredentials {
+  readonly goAccessToken?: string
+  readonly commandCodeIntegrationKey?: string
+  readonly commandCodeProviderKey?: string
+  /** OpenDesign inference key. It cannot read quota. */
+  readonly openDesignApiKey?: string
+  /** OpenDesign account-control key. Only used when explicitly configured. */
+  readonly openDesignControlKey?: string
+}
+
+export interface QuotaServiceOptions {
+  readonly getSettings: () => Readonly<Record<string, ProviderSettings>>
+  readonly getCredentials: () => Promise<QuotaCredentials>
+  readonly probeIntervalMinutes: number
+  readonly fetchImpl?: FetchLike
+  readonly now?: () => number
+  readonly onSnapshot?: (snapshot: ProviderQuotaSnapshot) => void
+  readonly initial?: ReadonlyArray<ProviderQuotaSnapshot>
+  /**
+   * Local usage events, used by providers whose quota must be modelled.
+   *
+   * The argument is the window the probe needs, not a hint. A provider that
+   * models a 30-day allowance cannot be handed fewer than 30 days of history:
+   * history that has aged out of the raw event array has been folded into
+   * hourly buckets, and a caller that ignores the window returns the raw array
+   * alone and under-reports spend exactly when the account is busiest.
+   */
+  readonly getUsageEvents?: (window?: { since: number; until?: number }) => ReadonlyArray<UsageEvent>
+}
+
+/** Providers the router can probe. Order does not imply preference. */
+export const QUOTA_PROVIDER_IDS = ["opencode-go", "commandcode", "opendesign"] as const
+
+export type QuotaProviderID = (typeof QUOTA_PROVIDER_IDS)[number]
+
+interface ProviderState {
+  snapshot?: ProviderQuotaSnapshot
+  lastAttempt: number
+  nextAllowed: number
+  failures: number
+  inFlight?: Promise<ProviderQuotaSnapshot>
+}
+
+const unknownWindow: QuotaWindow = { usedPct: 0, remainingPct: 100, source: "unknown" }
+
+const unknownSnapshot = (
+  providerID: string,
+  label: string,
+  plan: string,
+  now: number,
+  error: string,
+): ProviderQuotaSnapshot => ({
+  providerID,
+  label,
+  plan,
+  source: "unknown",
+  fetchedAt: now,
+  stale: false,
+  rolling: unknownWindow,
+  weekly: unknownWindow,
+  monthly: unknownWindow,
+  models: {},
+  notes: [],
+  error,
+  quotaState: "unknown",
+})
+
+const withStale = (snapshot: ProviderQuotaSnapshot, now: number, intervalMs: number): ProviderQuotaSnapshot => ({
+  ...snapshot,
+  stale: now - snapshot.fetchedAt > Math.max(intervalMs * 2, 60_000),
+  ...(snapshot.quotaState && snapshot.quotaState !== "unknown" && snapshot.quotaState !== "unavailable"
+    ? { quotaState: now - snapshot.fetchedAt > Math.max(intervalMs * 2, 60_000) ? ("stale" as const) : snapshot.quotaState }
+    : {}),
+})
+
+const backoffFor = (failures: number) => {
+  const steps = [30_000, 2 * 60_000, 5 * 60_000, 15 * 60_000]
+  return steps[Math.min(Math.max(failures, 1) - 1, steps.length - 1)] ?? 15 * 60_000
+}
+
+/**
+ * Caches provider-reported quota, probes on a conservative interval, and backs
+ * off independently per provider. Snapshots are read-only and contain no
+ * credentials.
+ */
+export class QuotaService {
+  private readonly options: QuotaServiceOptions
+  private readonly state: Record<string, ProviderState> = {
+    "opencode-go": { lastAttempt: 0, nextAllowed: 0, failures: 0 },
+    commandcode: { lastAttempt: 0, nextAllowed: 0, failures: 0 },
+    opendesign: { lastAttempt: 0, nextAllowed: 0, failures: 0 },
+  }
+
+  constructor(options: QuotaServiceOptions) {
+    this.options = options
+    const now = options.now?.() ?? Date.now()
+    for (const snapshot of options.initial ?? []) {
+      const state = this.state[snapshot.providerID]
+      if (!state) continue
+      state.snapshot = { ...snapshot, stale: true }
+      state.lastAttempt = snapshot.fetchedAt
+    }
+    void now
+  }
+
+  private intervalMs() {
+    return Math.max(1, this.options.probeIntervalMinutes) * 60_000
+  }
+
+  private now() {
+    return this.options.now?.() ?? Date.now()
+  }
+
+  getCached(): ProviderQuotaSnapshot[] {
+    const now = this.now()
+    const interval = this.intervalMs()
+    return Object.values(this.state)
+      .map((state) => state.snapshot)
+      .filter((snapshot): snapshot is ProviderQuotaSnapshot => Boolean(snapshot))
+      .map((snapshot) => withStale(snapshot, now, interval))
+  }
+
+  /**
+   * Return the freshest available snapshots without making a prompt wait on a
+   * slow provider. Stale data is refreshed in the background.
+   */
+  read(): ProviderQuotaSnapshot[] {
+    const now = this.now()
+    const interval = this.intervalMs()
+    const settings = this.options.getSettings()
+    for (const providerID of QUOTA_PROVIDER_IDS) {
+      const providerSettings = settings[providerID]
+      if (!providerSettings?.enabled || !providerSettings.probeUsage) continue
+      const state = this.state[providerID]
+      if (!state) continue
+      if ((!state.snapshot || now - state.lastAttempt > interval) && now >= state.nextAllowed && !state.inFlight) {
+        void this.refresh(providerID).catch(() => undefined)
+      }
+    }
+    return this.getCached()
+  }
+
+  /**
+   * Drop every cached snapshot.
+   *
+   * Called when settings change underneath the service — a pasted baseline is the
+   * case that matters. The cache holds snapshots computed from the *previous*
+   * settings, and a stale one is served with `stale: true` while a fresh probe is
+   * still pending. Without this the panel can show a percentage that predates the
+   * reading it was given, which reads as "my paste did nothing" even though it was
+   * applied.
+   */
+  invalidate(): void {
+    for (const state of Object.values(this.state)) {
+      state.snapshot = undefined
+      state.lastAttempt = 0
+      state.nextAllowed = 0
+    }
+  }
+
+  async refresh(providerID: QuotaProviderID | string, force = false): Promise<ProviderQuotaSnapshot> {
+    const settings = this.options.getSettings()[providerID]
+    const state = this.state[providerID]
+    if (!settings || !state) {
+      return unknownSnapshot(providerID, providerID, settings?.plan ?? "unknown", this.now(), "Unknown provider")
+    }
+    if (!settings.enabled || !settings.probeUsage) {
+      return (
+        state.snapshot ??
+        unknownSnapshot(providerID, providerID, settings.plan, this.now(), "Quota probing is disabled for this provider")
+      )
+    }
+    if (state.inFlight) return state.inFlight
+    const now = this.now()
+    if (!force && now < state.nextAllowed) {
+      return state.snapshot ?? unknownSnapshot(providerID, providerID, settings.plan, now, "Quota probe is cooling down")
+    }
+
+    state.lastAttempt = now
+    const task = this.probe(providerID, settings)
+      .then((snapshot) => {
+        state.snapshot = snapshot
+        state.failures = snapshot.error ? state.failures + 1 : 0
+        const retryAfter = snapshot.retryAfterMs === undefined
+          ? undefined
+          : Math.min(Math.max(0, snapshot.retryAfterMs), 15 * 60_000)
+        state.nextAllowed = snapshot.error
+          ? this.now() + (retryAfter ?? backoffFor(state.failures))
+          : 0
+        this.options.onSnapshot?.(snapshot)
+        return snapshot
+      })
+      .catch((error) => {
+        state.failures += 1
+        state.nextAllowed = this.now() + backoffFor(state.failures)
+        const snapshot = unknownSnapshot(
+          providerID,
+          providerID,
+          settings.plan,
+          this.now(),
+          error instanceof Error ? error.message : String(error),
+        )
+        state.snapshot = snapshot
+        this.options.onSnapshot?.(snapshot)
+        return snapshot
+      })
+      .finally(() => {
+        state.inFlight = undefined
+      })
+
+    state.inFlight = task
+    return task
+  }
+
+  private async probe(providerID: string, settings: ProviderSettings) {
+    const credentials = await this.options.getCredentials()
+    if (providerID === "opencode-go") {
+      const result = await probeOpenCodeGoQuota({
+        accessToken: credentials.goAccessToken ?? "",
+        settings,
+        fetchImpl: this.options.fetchImpl,
+        now: this.options.now,
+      })
+      return result.snapshot
+    }
+    if (providerID === "opendesign") {
+      // Ask for the widest window the model uses. Without it the estimator
+      // receives only the raw event array, and every hour of history that has
+      // been folded into a bucket stops counting.
+      const now = this.options.now?.() ?? Date.now()
+      const result = await probeOpenDesignQuota({
+        settings,
+        apiKey: credentials.openDesignApiKey,
+        controlKey: credentials.openDesignControlKey,
+        usage: this.options.getUsageEvents?.({ since: now - OPENDESIGN_MONTH_MS, until: now }) ?? [],
+        fetchImpl: this.options.fetchImpl,
+        now: this.options.now,
+        ...(settings.controlBaseURL ? { controlBaseURL: settings.controlBaseURL } : {}),
+        ...(settings.creditsPerUsd !== undefined ? { creditsPerUsd: settings.creditsPerUsd } : {}),
+        ...(settings.uncertaintyMarginPct !== undefined ? { uncertaintyMarginPct: settings.uncertaintyMarginPct } : {}),
+        ...(settings.multiplierOverrides ? { multiplierOverrides: settings.multiplierOverrides } : {}),
+      })
+      return { ...result.snapshot, quotaState: result.state }
+    }
+    const result = await probeCommandCodeQuota({
+      settings,
+      openCodeIntegrationKey: credentials.commandCodeIntegrationKey,
+      providerSettingsKey: credentials.commandCodeProviderKey,
+      fetchImpl: this.options.fetchImpl,
+      now: this.options.now,
+    })
+    return result.snapshot
+  }
+
+  async initialize(): Promise<ProviderQuotaSnapshot[]> {
+    const settings = this.options.getSettings()
+    const tasks: Array<Promise<ProviderQuotaSnapshot>> = []
+    for (const providerID of QUOTA_PROVIDER_IDS) {
+      const providerSettings = settings[providerID]
+      if (providerSettings?.enabled && providerSettings.probeUsage) tasks.push(this.refresh(providerID, true))
+    }
+    if (tasks.length === 0) return this.getCached()
+    await Promise.allSettled(tasks)
+    return this.getCached()
+  }
+}
+
+export const __quotaInternals = { backoffFor, withStale }