@iislee/opencodex 2.11.0 → 2.35.0

package/src/usage/user-cost-overlay-reconciler.ts

@@ -0,0 +1,313 @@
+/**
+ * Cross-process reconciliation for user cost overlays.
+ *
+ * `refreshUserCostOverlays` is process-local by design: `ocx config set`
+ * executes `saveConfig()` in the CLI process, and a direct `config.json` edit
+ * runs no in-process code at all. A running proxy therefore keeps its previous
+ * `activeUserCostOverlays()`/version until restart or another in-process
+ * refresh.
+ *
+ * This module gives the long-lived server a lightweight stat-based poller:
+ * when `config.json` changes on disk, it re-reads the persisted config, mirrors
+ * the disk `modelCosts` rows into the live provider rows (so a later in-process
+ * save cannot erase the external edit), and refreshes the overlay registry so
+ * Logs/Usage estimates follow the edit without a restart.
+ *
+ * The reconciler is owner-scoped: every `startServer` acquires its own lease
+ * (with its own live config), and the shared timer is torn down only when the
+ * LAST owner stops. This mirrors `acquireServerBackgroundLifecycle` so stopping
+ * one of several servers cannot kill reconciliation for the others.
+ */
+import { statSync } from "node:fs";
+
+import { getConfigPath, readConfigDiagnostics } from "../config";
+import type { OcxConfig, OcxProviderConfig } from "../types";
+import {
+  refreshPreservedProviderOwner,
+  refreshUserCostOverlays,
+  registerPreservedProviderOwner,
+  setPreservedDiskOnlyProviders,
+  unregisterPreservedProviderOwner,
+} from "./user-cost-overlays";
+
+/** Default poll cadence for external config edits. */
+export const USER_COST_OVERLAY_RECONCILE_INTERVAL_MS = 5_000;
+
+let reconcileTimer: ReturnType<typeof setInterval> | null = null;
+let reconcileTimerMs = 0;
+const owners = new Map<symbol, OcxConfig | null>();
+const ownerIntervals = new Map<symbol, number>();
+let lastStamp: { mtimeMs: number; size: number; ctimeMs: number; ino: number } | null = null;
+let invalidReconcileCount = 0;
+
+function configStamp(): { mtimeMs: number; size: number; ctimeMs: number; ino: number } | null {
+  try {
+    const stat = statSync(getConfigPath());
+    return {
+      mtimeMs: stat.mtimeMs,
+      size: stat.size,
+      ctimeMs: stat.ctimeMs,
+      ino: Number(stat.ino),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** Registered live configs plus an optional one-shot config, deduped by object identity. */
+function liveConfigsForPreservation(extra?: OcxConfig | null): OcxConfig[] {
+  const liveConfigs: OcxConfig[] = [];
+  const seen = new Set<OcxConfig>();
+  if (extra) {
+    seen.add(extra);
+    liveConfigs.push(extra);
+  }
+  for (const config of owners.values()) {
+    if (!config || seen.has(config)) continue;
+    seen.add(config);
+    liveConfigs.push(config);
+  }
+  return liveConfigs;
+}
+
+/**
+ * Mirror disk `modelCosts` rows into provider rows the live config already
+ * knows. Providers added by the external edit are left out of the live config
+ * (they would change the routing surface); their overlays still become active
+ * because the registry below is refreshed from the disk config.
+ */
+function adoptDiskModelCosts(live: OcxConfig, disk: OcxConfig): void {
+  if (!live.providers || !disk.providers) return;
+  for (const [name, diskProvider] of Object.entries(disk.providers)) {
+    const liveProvider = live.providers[name];
+    if (!liveProvider) continue;
+    if (diskProvider?.modelCosts === undefined) {
+      delete liveProvider.modelCosts;
+    } else {
+      liveProvider.modelCosts = structuredClone(diskProvider.modelCosts);
+    }
+  }
+}
+
+/**
+ * Remember provider rows present on disk that at least one live routing
+ * config does NOT own. They stay out of the live configs that lack them
+ * (adding them would change the routing surface), but
+ * `persistConfigUnlocked` merges them back at serialization so ANY owner's
+ * unrelated save preserves a provider row that another active owner owns.
+ *
+ * A row is preserved when it is missing from at least one live config: the
+ * writer that lacks it would otherwise erase it. Rows every live config owns
+ * need no protection because every writer carries them from its own config.
+ */
+function rememberDiskOnlyProviders(liveConfigs: readonly OcxConfig[], disk: OcxConfig): void {
+  const preserved: Record<string, OcxProviderConfig> = {};
+  if (disk.providers && liveConfigs.length > 0) {
+    for (const [name, provider] of Object.entries(disk.providers)) {
+      if (!provider) continue;
+      const ownedByAll = liveConfigs.every(live => Object.hasOwn(live.providers ?? {}, name));
+      if (!ownedByAll) preserved[name] = structuredClone(provider);
+    }
+  }
+  setPreservedDiskOnlyProviders(Object.keys(preserved).length > 0 ? preserved : null);
+  // Update only registered server owners. One-shot callers without a lease do
+  // not become deletion authorities merely by asking for a reconciliation.
+  for (const live of liveConfigs) refreshPreservedProviderOwner(live, disk);
+}
+
+/**
+ * Re-read the persisted config and recompute the disk-only provider
+ * preservation registry against the CURRENT owner set. Used when an owner
+ * stops but others remain: a newer owner may have owned a provider that an
+ * older owner still treats as disk-only, and the registry must reflect the
+ * remaining owners rather than the stale pre-stop snapshot.
+ *
+ * A missing or transiently invalid file leaves the registry untouched so a
+ * bad write cannot erase preservation state.
+ */
+function recomputePreservedDiskOnlyProviders(): void {
+  const diagnostics = readConfigDiagnostics();
+  if (diagnostics.source !== "file") return;
+  const liveConfigs = liveConfigsForPreservation();
+  if (liveConfigs.length > 0) {
+    rememberDiskOnlyProviders(liveConfigs, diagnostics.config);
+  } else {
+    // No live routing configuration remains to protect disk-only providers;
+    // clear the cache so a later save cannot resurrect externally deleted rows.
+    setPreservedDiskOnlyProviders(null);
+  }
+}
+
+/**
+ * Re-read the persisted config and make external overlay edits live.
+ *
+ * Returns `false` (and leaves the registry untouched) when the file is missing
+ * or invalid, so a transient bad write cannot wipe display-only prices.
+ */
+export function reconcileUserCostOverlaysFromDisk(liveConfig?: OcxConfig | null): boolean {
+  const diagnostics = readConfigDiagnostics();
+  if (diagnostics.source !== "file") return false;
+  const disk = diagnostics.config;
+  if (liveConfig) {
+    adoptDiskModelCosts(liveConfig, disk);
+    // A one-shot caller is not the whole process. Existing server owners still
+    // participate in global preservation or this call can drop protection for
+    // a provider absent from an older live projection.
+    rememberDiskOnlyProviders(liveConfigsForPreservation(liveConfig), disk);
+  } else {
+    // No live routing config was supplied: mirror the owners path so a stale
+    // preservation registry cannot resurrect externally deleted providers on
+    // the next saveConfig. Registered owners still protect disk-only rows;
+    // without any, preservation is cleared.
+    const liveConfigs = liveConfigsForPreservation();
+    if (liveConfigs.length > 0) {
+      for (const live of liveConfigs) adoptDiskModelCosts(live, disk);
+      rememberDiskOnlyProviders(liveConfigs, disk);
+    } else {
+      setPreservedDiskOnlyProviders(null);
+    }
+  }
+  // Refresh from the DISK config: overlays for providers only added by the
+  // external edit are display-only and must still resolve for historical rows.
+  refreshUserCostOverlays(disk);
+  return true;
+}
+
+function reconcileForOwners(): void {
+  const diagnostics = readConfigDiagnostics();
+  if (diagnostics.source !== "file") {
+    if (diagnostics.source === "fallback") invalidReconcileCount += 1;
+    return;
+  }
+  const disk = diagnostics.config;
+  const liveConfigs = liveConfigsForPreservation();
+  if (liveConfigs.length > 0) {
+    for (const live of liveConfigs) adoptDiskModelCosts(live, disk);
+    rememberDiskOnlyProviders(liveConfigs, disk);
+  } else {
+    // Overlay-only refresh with no live routing configuration: do not treat
+    // every disk provider as protected, and do not let a stale preservation
+    // cache resurrect providers that were intentionally removed.
+    setPreservedDiskOnlyProviders(null);
+  }
+  refreshUserCostOverlays(disk);
+}
+
+/** Test-only observation that proves the timer actually read an invalid config fallback. */
+export function userCostOverlayInvalidReconcileCountForTests(): number {
+  return invalidReconcileCount;
+}
+
+/** Smallest poll interval across all active owners (the effective cadence). */
+function effectiveIntervalMs(): number {
+  let min = Number.POSITIVE_INFINITY;
+  for (const interval of ownerIntervals.values()) {
+    if (interval < min) min = interval;
+  }
+  return min === Number.POSITIVE_INFINITY ? USER_COST_OVERLAY_RECONCILE_INTERVAL_MS : min;
+}
+
+/**
+ * Keep the shared timer on the effective minimum cadence across owners. A
+ * later owner may request a smaller interval, which restarts the timer; when
+ * an owner stops, the cadence relaxes back up to the smallest still-active
+ * owner's request. The timer therefore never outlives or ignores an owner's
+ * faster polling need, and never polls faster than the active set requires.
+ */
+function syncReconcileTimer(): void {
+  const intervalMs = effectiveIntervalMs();
+  if (reconcileTimer && reconcileTimerMs === intervalMs) return;
+  if (reconcileTimer) clearInterval(reconcileTimer);
+  reconcileTimer = setInterval(() => {
+    const stamp = configStamp();
+    if (!stamp) return;
+    if (
+      lastStamp
+      && lastStamp.mtimeMs === stamp.mtimeMs
+      && lastStamp.size === stamp.size
+      && lastStamp.ctimeMs === stamp.ctimeMs
+      && lastStamp.ino === stamp.ino
+    ) return;
+    lastStamp = stamp;
+    try {
+      reconcileForOwners();
+    } catch {
+      // Display-only reconciliation must never take the proxy down.
+    }
+  }, intervalMs);
+  reconcileTimer.unref?.();
+  reconcileTimerMs = intervalMs;
+}
+
+/**
+ * Start the stat-based reconciler. Each call registers an owner lease; the
+ * shared timer starts with the first owner and stops when the last owner's
+ * `stop()` releases it.
+ */
+export function startUserCostOverlayReconciler(
+  options: { intervalMs?: number; liveConfig?: OcxConfig | null } = {},
+): { stop(): void } {
+  const token = Symbol("user-cost-overlay-reconciler");
+  const liveConfig = options.liveConfig ?? null;
+  owners.set(token, liveConfig);
+  ownerIntervals.set(token, options.intervalMs ?? USER_COST_OVERLAY_RECONCILE_INTERVAL_MS);
+  if (liveConfig) registerPreservedProviderOwner(liveConfig);
+  syncReconcileTimer();
+  return {
+    stop() {
+      const ownedConfig = owners.get(token) ?? null;
+      owners.delete(token);
+      ownerIntervals.delete(token);
+      if (ownedConfig) unregisterPreservedProviderOwner(ownedConfig);
+      if (owners.size === 0) {
+        if (reconcileTimer) clearInterval(reconcileTimer);
+        reconcileTimer = null;
+        reconcileTimerMs = 0;
+        lastStamp = null;
+        // No live routing config remains, so nothing can keep disk-only
+        // providers alive: clear the cache to prevent a later save from
+        // resurrecting an externally deleted provider.
+        setPreservedDiskOnlyProviders(null);
+        return;
+      }
+      syncReconcileTimer();
+      // Other owners remain: recompute preservation against their live
+      // configs. A newer owner may have owned providers that an older owner
+      // still sees as disk-only; without this recompute the older owner's next
+      // unrelated save could erase them.
+      try {
+        recomputePreservedDiskOnlyProviders();
+      } catch {
+        // Preservation is display-only; a failed recompute must not break stop.
+      }
+    },
+  };
+}
+
+/**
+ * Process-wide stop: releases EVERY owner's lease and the shared timer.
+ * Intended for tests and full process teardown. A per-server shutdown must
+ * call its own owner-scoped `stop()` handle instead — this function would
+ * otherwise tear down reconciliation (and disk-only preservation) for every
+ * other server still running in the same process.
+ */
+export function stopUserCostOverlayReconciler(): void {
+  for (const config of owners.values()) {
+    if (config) unregisterPreservedProviderOwner(config);
+  }
+  owners.clear();
+  ownerIntervals.clear();
+  if (reconcileTimer) clearInterval(reconcileTimer);
+  reconcileTimer = null;
+  reconcileTimerMs = 0;
+  lastStamp = null;
+  // No live routing config remains; drop preservation so a later save cannot
+  // resurrect externally deleted providers.
+  setPreservedDiskOnlyProviders(null);
+}
+
+/** Test-only reset for module-global reconciler state. */
+export function resetUserCostOverlayReconcilerForTests(): void {
+  stopUserCostOverlayReconciler();
+  invalidReconcileCount = 0;
+}

package/src/usage/user-cost-overlays.ts

@@ -0,0 +1,314 @@
+/**
+ * Runtime registry for user-configured provider cost overlays
+ * (`providers.<name>.modelCosts` in config.json — per-model prices in ocx's
+ * flat `modelXxx` convention, mirroring opencode's per-model pricing).
+ *
+ * The usage cost estimator stays pure: it receives overlays as parameters and
+ * defaults to this registry, which is refreshed at the config chokepoints
+ * (loadConfig and every persist path). A refresh that actually changes the
+ * rows replaces the active array with a NEW identity and bumps a version
+ * counter, so the estimator's memo and the /api/usage summary cache skip stale
+ * rows without cross-module invalidation. Refreshes with byte-identical rows
+ * are no-ops: config is reloaded at many chokepoints and an unchanged reload
+ * must not churn the version (see refreshUserCostOverlays). The configured
+ * provider-name set is part of the change identity: adding or removing a
+ * provider changes which names may collapse to a label base in the resolver,
+ * so it bumps the version even when no overlay row changed.
+ *
+ * Display-time estimation only — these rows never affect billing.
+ */
+import type { OcxConfig, OcxProviderConfig, ProviderCostOverlay } from "../types";
+import { MAX_COST4_RATE, type ExpectedPriceOverlay } from "./expected-prices";
+import { redactSecretString } from "../lib/redact";
+
+const EMPTY: readonly ExpectedPriceOverlay[] = [];
+
+let active: readonly ExpectedPriceOverlay[] = EMPTY;
+let activeSignature = "";
+let activeConfigured = new Set<string>();
+let version = 0;
+let preservedDiskOnlyProviders: Record<string, OcxProviderConfig> | null = null;
+
+/**
+ * Preservation owner metadata rides through the shallow config projections in
+ * config.ts via an enumerable SYMBOL key. JSON.stringify ignores symbol keys,
+ * so the tag is process-local only and can never reach config.json or a DTO.
+ */
+const PRESERVATION_OWNER_STATE = Symbol("opencodex.user-cost-overlay-preservation-owner");
+const PERSISTED_PROVIDER_DELETIONS = Symbol("opencodex.persisted-provider-deletions");
+
+type PreservationOwnerState = {
+  refs: number;
+  config: OcxConfig;
+  ownedProviders: Set<string>;
+};
+
+type PreservationTaggedConfig = OcxConfig & {
+  [PRESERVATION_OWNER_STATE]?: PreservationOwnerState;
+  [PERSISTED_PROVIDER_DELETIONS]?: readonly string[];
+};
+
+const preservationOwnerStates = new Set<PreservationOwnerState>();
+
+function providerNames(config: OcxConfig): Set<string> {
+  return new Set(Object.keys(config.providers ?? {}));
+}
+
+/** Register one active live-config owner. Multiple server leases may share one config object. */
+export function registerPreservedProviderOwner(config: OcxConfig): void {
+  const tagged = config as PreservationTaggedConfig;
+  const existing = tagged[PRESERVATION_OWNER_STATE];
+  if (existing && preservationOwnerStates.has(existing)) {
+    existing.refs += 1;
+    existing.ownedProviders = providerNames(config);
+    return;
+  }
+  const state: PreservationOwnerState = {
+    refs: 1,
+    config,
+    ownedProviders: providerNames(config),
+  };
+  // Enumerable is deliberate: projectCustomModelCatalogMigration and the live
+  // binding guard use object spread, which must carry this process-local tag to
+  // the serialization view. Symbol keys are still omitted by JSON.stringify.
+  Object.defineProperty(tagged, PRESERVATION_OWNER_STATE, {
+    value: state,
+    enumerable: true,
+    configurable: true,
+  });
+  preservationOwnerStates.add(state);
+}
+
+/**
+ * Refresh a registered owner's provider snapshot from a successful disk read.
+ *
+ * A provider still present on disk remains owned even if the live object
+ * temporarily omits it: management DELETE has an async-import gap between
+ * mutating the live config and committing the write, and a reconciler tick in
+ * that gap must not erase the deletion authority. Conversely, providers that
+ * disappeared from disk are no longer considered owned, and newly present
+ * providers are adopted only when this live config actually has the row.
+ */
+export function refreshPreservedProviderOwner(config: OcxConfig, disk: OcxConfig): void {
+  const state = (config as PreservationTaggedConfig)[PRESERVATION_OWNER_STATE];
+  if (!state || !preservationOwnerStates.has(state)) return;
+  const diskNames = providerNames(disk);
+  for (const name of [...state.ownedProviders]) {
+    if (!diskNames.has(name)) state.ownedProviders.delete(name);
+  }
+  for (const name of Object.keys(config.providers ?? {})) {
+    if (diskNames.has(name)) state.ownedProviders.add(name);
+  }
+}
+
+/** Release one active live-config owner lease. */
+export function unregisterPreservedProviderOwner(config: OcxConfig): void {
+  const tagged = config as PreservationTaggedConfig;
+  const state = tagged[PRESERVATION_OWNER_STATE];
+  if (!state || !preservationOwnerStates.has(state)) return;
+  state.refs -= 1;
+  if (state.refs > 0) return;
+  preservationOwnerStates.delete(state);
+  if (tagged[PRESERVATION_OWNER_STATE] === state) {
+    delete tagged[PRESERVATION_OWNER_STATE];
+  }
+}
+
+/**
+ * Remember provider rows that exist on disk but are intentionally absent from
+ * the live routing config (added by an external editor after the proxy booted).
+ * They are merged back at the config serialization boundary so an unrelated
+ * in-process save cannot erase the external provider and its overlay.
+ */
+export function setPreservedDiskOnlyProviders(
+  providers: Record<string, OcxProviderConfig> | null,
+): void {
+  preservedDiskOnlyProviders = providers;
+}
+
+/**
+ * Commit an explicit provider deletion only after the persisted serialization
+ * view has been accepted by the config write path. This clears the stale
+ * preservation row and removes the provider from every active live projection,
+ * so a second owner cannot resurrect it on a later unrelated save.
+ */
+function commitPersistedProviderDeletions(config: OcxConfig): void {
+  const tagged = config as PreservationTaggedConfig;
+  const deletions = tagged[PERSISTED_PROVIDER_DELETIONS];
+  if (!deletions || deletions.length === 0) return;
+
+  const deleted = new Set(deletions);
+  if (preservedDiskOnlyProviders) {
+    const next = { ...preservedDiskOnlyProviders };
+    for (const name of deleted) delete next[name];
+    preservedDiskOnlyProviders = Object.keys(next).length > 0 ? next : null;
+  }
+
+  for (const state of preservationOwnerStates) {
+    for (const name of deleted) {
+      state.ownedProviders.delete(name);
+      if (state.config.providers) delete state.config.providers[name];
+    }
+  }
+  delete tagged[PERSISTED_PROVIDER_DELETIONS];
+}
+
+/**
+ * A serialization view of `config` that keeps externally added providers on
+ * disk without adding them to live routing state. Live providers win when a
+ * name exists in both maps.
+ *
+ * A registered owner also carries the provider names it previously owned. If
+ * that owner now omits one of those providers, the omission is an intentional
+ * in-process deletion rather than an old projection that never knew the row.
+ * Suppress only those names from preservation for this write. The suppression
+ * is committed globally only after refreshUserCostOverlays receives the
+ * successfully persisted view, so a failed atomic write cannot destroy the
+ * preservation safety net.
+ */
+export function withPreservedDiskOnlyProviders(config: OcxConfig): OcxConfig {
+  const tagged = config as PreservationTaggedConfig;
+  const owner = tagged[PRESERVATION_OWNER_STATE];
+  const deletedProviders = owner && preservationOwnerStates.has(owner)
+    ? [...owner.ownedProviders].filter(name => !Object.hasOwn(config.providers ?? {}, name))
+    : [];
+  const deletedSet = new Set(deletedProviders);
+
+  let preserved: Record<string, OcxProviderConfig> | null = null;
+  if (preservedDiskOnlyProviders) {
+    const filtered = Object.entries(preservedDiskOnlyProviders)
+      .filter(([name]) => !deletedSet.has(name));
+    if (filtered.length > 0) preserved = Object.fromEntries(filtered);
+  }
+
+  let persisted: OcxConfig;
+  if (preserved && Object.keys(preserved).length > 0) {
+    persisted = {
+      ...config,
+      providers: {
+        ...preserved,
+        ...config.providers,
+      },
+    };
+  } else if (deletedProviders.length > 0) {
+    // Return a distinct object so the persisted-deletion marker remains scoped
+    // to this serialization attempt rather than the long-lived live config.
+    persisted = { ...config };
+  } else {
+    return config;
+  }
+
+  if (deletedProviders.length > 0) {
+    Object.defineProperty(persisted as PreservationTaggedConfig, PERSISTED_PROVIDER_DELETIONS, {
+      value: deletedProviders,
+      enumerable: false,
+      configurable: true,
+    });
+  }
+  return persisted;
+}
+
+/** Test-only reset for the preserved disk-only provider registry. */
+export function resetPreservedDiskOnlyProvidersForTests(): void {
+  preservedDiskOnlyProviders = null;
+  preservationOwnerStates.clear();
+}
+
+/** Exact four fields accepted for a user-configured cost tuple. */
+export const COST4_RATE_KEYS = ["input", "output", "cacheRead", "cacheWrite"] as const;
+
+/** Shared per-rate predicate used by config validation, display sanitization, and runtime lifting. */
+export function isValidCost4Rate(rate: unknown): rate is number {
+  return typeof rate === "number"
+    && Number.isFinite(rate)
+    && rate >= 0
+    && rate <= MAX_COST4_RATE;
+}
+
+/** True when `value` is a complete cost entry: all four rates are non-negative finite numbers. */
+function validCost4(value: unknown): value is ProviderCostOverlay {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const entry = value as Record<string, unknown>;
+  return COST4_RATE_KEYS.every(key => isValidCost4Rate(entry[key]));
+}
+
+/**
+ * Rebuild the active user-overlay rows from the current config. Malformed rows
+ * are skipped (config validation reports them separately); a provider with no
+ * overlay contributes nothing.
+ */
+export function refreshUserCostOverlays(config: OcxConfig): void {
+  // Only persisted serialization views carry PERSISTED_PROVIDER_DELETIONS.
+  // Committing here means changed writes update owner state only after the
+  // atomic write succeeds, while byte-identical successful saves also converge.
+  commitPersistedProviderDeletions(config);
+
+  const rows: ExpectedPriceOverlay[] = [];
+  const providers = config.providers;
+  if (providers) {
+    for (const [providerName, provider] of Object.entries(providers)) {
+      const costs = provider?.modelCosts;
+      if (!costs || typeof costs !== "object" || Array.isArray(costs)) continue;
+      for (const [modelId, cost4] of Object.entries(costs)) {
+        if (!modelId.trim() || !validCost4(cost4)) continue;
+        rows.push({
+          provider: providerName,
+          modelId,
+          // Copy ONLY the four validated rate fields: a hand-edited row may
+          // carry extra properties (e.g. a misplaced apiKey) that must never
+          // reach display estimates or /api/logs through the registry.
+          cost4: {
+            input: cost4.input,
+            output: cost4.output,
+            cacheRead: cost4.cacheRead,
+            cacheWrite: cost4.cacheWrite,
+          },
+          // Display provenance only: redact token-shaped provider/model ids so
+          // the source string can never echo a pasted key. Matching still uses
+          // the raw fields, and the change-detection signature below MUST keep
+          // them raw — distinct ids would otherwise collapse to "[REDACTED]"
+          // and skip the version bump.
+          source: `config:providers.${redactSecretString(providerName)}.modelCosts[${redactSecretString(modelId)}]`,
+          verifiedAt: "user-configured",
+          status: "verified",
+        });
+      }
+    }
+  }
+  // Config is re-loaded at many chokepoints (server start, migrations, persist
+  // paths). Bumping the version on every load — even when nothing changed —
+  // would invalidate the /api/usage summary cache on unrelated reloads and
+  // churn the cost memo. Only a real overlay change bumps the version, so the
+  // cache survives reloads of an unchanged config.
+  // The signature MUST compare the raw matching fields: two different
+  // secret-shaped ids would both redact to "[REDACTED]" and falsely look
+  // unchanged, skipping the version bump and serving stale estimates. The
+  // signature is process-local state and is never serialized to a response;
+  // only the display `source` above is redacted.
+  // The configured provider-name set is part of the identity too: adding or
+  // removing a provider (even one without an overlay) changes which names are
+  // allowed to collapse to a label base, so the resolver memo and the
+  // /api/usage summary cache must be invalidated on that change as well.
+  const configuredNames = Object.keys(providers ?? {}).sort();
+  const signature = `${JSON.stringify(configuredNames)}\u0000${JSON.stringify(rows)}`;
+  if (signature === activeSignature) return;
+  activeSignature = signature;
+  active = rows;
+  activeConfigured = new Set(configuredNames);
+  version++;
+}
+
+/** Active user-configured overlay rows (stable identity until the next refresh). */
+export function activeUserCostOverlays(): readonly ExpectedPriceOverlay[] {
+  return active;
+}
+
+/** Monotonic version bumped on every refresh; used by the estimator memo key. */
+export function userCostOverlayVersion(): number {
+  return version;
+}
+
+/** Configured provider names from the last refresh (pricing-namespace identity). */
+export function activeConfiguredProviders(): ReadonlySet<string> {
+  return activeConfigured;
+}

package/src/vision/anthropic-describe.ts

@@ -3,7 +3,7 @@ import { CLAUDE_CODE_HEADERS, claudeCodeSessionId } from "../adapters/client-fin
 import { signalWithTimeout, cancelBodyOnAbort } from "../lib/abort";
 import { sidecarEnter } from "../lib/sidecar-tracker";
 import { fetchWithResetRetry } from "../lib/upstream-retry";
-import { getValidAccessToken } from "../oauth";
+import { getValidAccessToken, publicOAuthAuthenticationErrorMessage } from "../oauth";
 import { ANTHROPIC_OAUTH_BETA, CLAUDE_CODE_SYSTEM_INSTRUCTION } from "../oauth/anthropic";
 import type { DescribeOutcome, VisionSettings } from "./describe";
 
@@ -67,8 +67,8 @@ export async function parseAnthropicVisionSSE(res: Response): Promise<DescribeOu
       const delta = isRecord(data.delta) ? data.delta : {};
       if (delta.type === "text_delta" && typeof delta.text === "string") text += delta.text;
     } else if (data.type === "error") {
-      const error = isRecord(data.error) ? data.error : {};
-      terminalError = typeof error.message === "string" ? error.message : "anthropic vision sidecar stream error";
+      // Provider-authored stream errors can contain credentials, paths, or response bodies.
+      terminalError = "anthropic vision sidecar stream error";
     }
   };
 
@@ -116,7 +116,7 @@ export async function describeImageAnthropic(
   try {
     token = await getValidAccessToken(providerName);
   } catch (error) {
-    return { text: "", error: `anthropic vision sidecar auth failed: ${error instanceof Error ? error.message : String(error)}` };
+    return { text: "", error: `anthropic vision sidecar auth failed: ${publicOAuthAuthenticationErrorMessage(error)}` };
   }
 
   const headers: Record<string, string> = {
@@ -166,7 +166,11 @@ export async function describeImageAnthropic(
     if (!res.ok) {
       const responseText = await res.text().catch(() => "");
       console.warn(`[vision] anthropic sidecar HTTP ${res.status} (${Date.now() - startedAt}ms)`);
-      return { text: "", error: `anthropic vision sidecar HTTP ${res.status}: ${responseText.slice(0, 200)}` };
+      if (res.status === 401) {
+        return { text: "", error: `anthropic vision sidecar auth failed: ${publicOAuthAuthenticationErrorMessage(new Error(responseText))}` };
+      }
+      // Upstream bodies are untrusted and may contain credentials, paths, or provider diagnostics.
+      return { text: "", error: `anthropic vision sidecar HTTP ${res.status}` };
     }
     const detachBodyGuard = cancelBodyOnAbort(res.body, linkedSignal.signal);
     try {
@@ -177,7 +181,7 @@ export async function describeImageAnthropic(
   } catch (error) {
     const kind = error instanceof Error && error.name === "TimeoutError" ? "timeout" : "connect_error";
     console.warn(`[vision] anthropic sidecar ${kind} (${Date.now() - startedAt}ms)`);
-    return { text: "", error: error instanceof Error ? error.message : String(error) };
+    return { text: "", error: `anthropic vision sidecar ${kind}` };
   } finally {
     sidecarExit();
     linkedSignal.cleanup();