@pellux/goodvibes-agent 0.1.0

package/src/runtime/ui/model-picker/health-enrichment.ts

@@ -0,0 +1,228 @@
+/**
+ * Health enrichment for model picker entries.
+ *
+ * Joins ModelDefinition records from the provider registry with health
+ * telemetry from ProviderHealthDomainState to produce enriched
+ * ModelPickerEntry objects ready for UI consumption.
+ */
+import type { ModelDefinition } from '@pellux/goodvibes-sdk/platform/providers';
+import type { ProviderRegistry } from '@pellux/goodvibes-sdk/platform/providers';
+import type { BenchmarkStore } from '@pellux/goodvibes-sdk/platform/providers';
+import type { ProviderHealthDomainState, ProviderHealthRecord } from '@/runtime/index.ts';
+import type { ModelDomainState } from '@/runtime/index.ts';
+import { detectFamily, tierToCategoryFilter } from '../../../input/model-picker.ts';
+import { getQualityTier, getQualityTierFromScore, compositeScore } from '@pellux/goodvibes-sdk/platform/providers';
+import type {
+  ModelPickerEntry,
+  ModelPickerGroup,
+  ProviderHealthContext,
+  CapabilityFlags,
+  ProviderLatencyStats,
+} from '@/runtime/index.ts';
+
+/** Status sort priority (lower = shown first). */
+const STATUS_ORDER: Record<string, number> = {
+  healthy: 0,
+  unknown: 1,
+  degraded: 2,
+  rate_limited: 3,
+  auth_error: 4,
+  unavailable: 5,
+};
+
+/**
+ * Derive ProviderHealthContext from a ProviderHealthRecord.
+ * Returns a safe default when the record is absent (provider not yet observed).
+ */
+function buildHealthContext(record: ProviderHealthRecord | undefined): ProviderHealthContext {
+  if (!record) {
+    return {
+      status: 'unknown',
+      isConfigured: false,
+    };
+  }
+
+  let latency: ProviderLatencyStats | undefined;
+  if (record.stats.totalCalls > 0) {
+    latency = {
+      avgMs: record.stats.avgLatencyMs,
+      p95Ms: record.stats.maxLatencyMs,
+      minMs: record.stats.minLatencyMs,
+    };
+  }
+
+  return {
+    status: record.status,
+    latency,
+    cacheHitRate: record.cacheMetrics?.hitRate,
+    isConfigured: record.isConfigured,
+    rateLimitResetAt: record.rateLimitResetAt,
+  };
+}
+
+/**
+ * Derive CapabilityFlags from a ModelDefinition.
+ */
+function buildCapabilityFlags(model: ModelDefinition): CapabilityFlags {
+  return {
+    reasoning: model.capabilities?.reasoning ?? false,
+    caching: false, // caching capability is provider-level; enriched separately if needed
+    toolCalling: model.capabilities?.toolCalling ?? false,
+    multimodal: model.capabilities?.multimodal ?? false,
+    codeEditing: model.capabilities?.codeEditing ?? false,
+  };
+}
+
+/**
+ * Derive quality tier and benchmark score for a model.
+ * Handles synthetic models (catalog-backed composite scores) and standard models.
+ */
+function buildQualityInfo(
+  model: ModelDefinition,
+  benchmarkStore: Pick<BenchmarkStore, 'getBenchmarks'>,
+  providerRegistry: Pick<ProviderRegistry, 'getSyntheticModelInfoFromCatalog'>,
+): { qualityTier?: string; benchmarkScore?: number } {
+  if (model.provider === 'synthetic') {
+    const info = providerRegistry.getSyntheticModelInfoFromCatalog(model.id);
+    if (info?.bestCompositeScore != null) {
+      return {
+        qualityTier: getQualityTierFromScore(info.bestCompositeScore),
+        benchmarkScore: info.bestCompositeScore,
+      };
+    }
+    return {};
+  }
+
+  const benchmarks = benchmarkStore.getBenchmarks(model.id) ?? benchmarkStore.getBenchmarks(model.displayName);
+  if (!benchmarks) return {};
+
+  return {
+    qualityTier: getQualityTier(benchmarks.benchmarks),
+    benchmarkScore: compositeScore(benchmarks.benchmarks) ?? undefined,
+  };
+}
+
+/**
+ * Build the set of model IDs in the current fallback chain.
+ * Returns a Map from modelId to its position (0 = primary).
+ */
+function buildFallbackPositionMap(modelState: ModelDomainState): Map<string, number> {
+  const map = new Map<string, number>();
+  // Position 0 is always the primary active model
+  map.set(modelState.activeModelId, 0);
+  for (let i = 0; i < modelState.fallbackChain.length; i++) {
+    const entry = modelState.fallbackChain[i];
+    if (!map.has(entry.modelId)) {
+      map.set(entry.modelId, i + 1);
+    }
+  }
+  return map;
+}
+
+/**
+ * Enrich a flat list of ModelDefinitions with health and state data.
+ *
+ * @param models - All selectable models from the registry.
+ * @param healthState - Current provider health domain state.
+ * @param modelState - Current model domain state.
+ * @param pinnedIds - Set of pinned/favorited model IDs.
+ * @returns Sorted, enriched ModelPickerEntry array.
+ */
+export function enrichModelEntries(
+  models: readonly ModelDefinition[],
+  healthState: ProviderHealthDomainState,
+  modelState: ModelDomainState,
+  pinnedIds: ReadonlySet<string>,
+  benchmarkStore: Pick<BenchmarkStore, 'getBenchmarks'>,
+  providerRegistry: Pick<ProviderRegistry, 'getSyntheticModelInfoFromCatalog' | 'getContextWindowForModel'>,
+): ModelPickerEntry[] {
+  const fallbackPositions = buildFallbackPositionMap(modelState);
+
+  const entries: ModelPickerEntry[] = models.map((model) => {
+    const record = healthState.providers.get(model.provider);
+    const health = buildHealthContext(record);
+    const { qualityTier, benchmarkScore } = buildQualityInfo(model, benchmarkStore, providerRegistry);
+    const isProviderDegraded =
+      health.status === 'degraded' || health.status === 'rate_limited';
+    const isProviderUnavailable =
+      health.status === 'unavailable' || health.status === 'auth_error';
+
+    const fallbackPosition = fallbackPositions.get(model.id);
+
+    // Resolve effective context window and determine display source label.
+    const effectiveContextWindow = providerRegistry.getContextWindowForModel(model);
+    // Determine source: custom/local providers carry provenance on ModelDefinition;
+    // for catalog models, if getContextWindowForModel returned more than the
+    // static contextWindow it came from OpenRouter, else it's the registry value.
+    let contextWindowSource: ModelPickerEntry['contextWindowSource'];
+    if (model.contextWindowProvenance) {
+      contextWindowSource = model.contextWindowProvenance;
+    } else if (effectiveContextWindow !== model.contextWindow) {
+      contextWindowSource = 'openrouter';
+    } else {
+      contextWindowSource = 'registry';
+    }
+
+    return {
+      modelId: model.id,
+      providerId: model.provider,
+      displayName: model.displayName,
+      family: detectFamily(model),
+      pricingTier: tierToCategoryFilter(model.tier),
+      qualityTier,
+      benchmarkScore,
+      capabilities: buildCapabilityFlags(model),
+      health,
+      contextWindow: effectiveContextWindow,
+      contextWindowSource,
+      isPinned: pinnedIds.has(model.id),
+      isActive: model.id === modelState.activeModelId,
+      isProviderDegraded,
+      isProviderUnavailable,
+      isInFallbackChain: fallbackPosition !== undefined,
+      fallbackPosition,
+    };
+  });
+
+  // Sort: healthy providers first, then degraded, then unavailable.
+  // Within each status bucket: pinned first, then active, then by display name.
+  entries.sort((a, b) => {
+    const statusDiff =
+      (STATUS_ORDER[a.health.status] ?? 1) - (STATUS_ORDER[b.health.status] ?? 1);
+    if (statusDiff !== 0) return statusDiff;
+
+    // Pinned before unpinned
+    if (a.isPinned !== b.isPinned) return a.isPinned ? -1 : 1;
+    // Active before inactive
+    if (a.isActive !== b.isActive) return a.isActive ? -1 : 1;
+
+    return a.displayName.localeCompare(b.displayName);
+  });
+
+  return entries;
+}
+
+/**
+ * Group a sorted list of ModelPickerEntry records by their provider ID.
+ * Preserves the sort order of entries within each group.
+ *
+ * @param entries - Pre-sorted enriched entries.
+ * @returns Groups ordered by first appearance of each provider in entries.
+ */
+export function groupEntriesByProvider(entries: readonly ModelPickerEntry[]): ModelPickerGroup[] {
+  const groupMap = new Map<string, ModelPickerEntry[]>();
+  const groupOrder: string[] = [];
+
+  for (const entry of entries) {
+    if (!groupMap.has(entry.providerId)) {
+      groupMap.set(entry.providerId, []);
+      groupOrder.push(entry.providerId);
+    }
+    groupMap.get(entry.providerId)!.push(entry);
+  }
+
+  return groupOrder.map((providerId) => ({
+    label: providerId,
+    entries: groupMap.get(providerId)!,
+  }));
+}

package/src/runtime/ui/model-picker/index.ts

@@ -0,0 +1,59 @@
+/**
+ * Model picker UI data surface barrel.
+ *
+ * Re-exports all types and the ModelPickerDataProvider class.
+ * Also provides the createModelPickerData() factory for one-shot snapshots.
+ */
+export type {
+  CapabilityFlags,
+  ProviderLatencyStats,
+  ProviderHealthContext,
+  ModelPickerEntry,
+  ModelPickerGroup,
+  ModelPickerData,
+} from '@/runtime/index.ts';
+// ProviderStatus re-exported from types for convenience
+export type { ProviderStatus } from '@/runtime/index.ts';
+
+export { ModelPickerDataProvider } from '@/runtime/index.ts';
+export type { ModelPickerDataProviderOptions } from '@/runtime/index.ts';
+
+import type { ModelDefinition } from '@pellux/goodvibes-sdk/platform/providers';
+import type { ProviderRegistry } from '@pellux/goodvibes-sdk/platform/providers';
+import type { BenchmarkStore } from '@pellux/goodvibes-sdk/platform/providers';
+import type { ProviderHealthDomainState } from '@/runtime/index.ts';
+import type { ModelDomainState } from '@/runtime/index.ts';
+import type { ModelPickerData } from '@/runtime/index.ts';
+import { ModelPickerDataProvider } from '@/runtime/index.ts';
+
+/**
+ * Produce a one-shot ModelPickerData snapshot without creating a long-lived provider.
+ *
+ * Use this when you need a single render pass and do not require change subscriptions.
+ * For reactive/subscription-based UIs, prefer ModelPickerDataProvider.
+ *
+ * @param models - All selectable models from the registry.
+ * @param healthState - Current provider health domain state.
+ * @param modelState - Current model domain state.
+ * @param pinnedIds - Set of pinned/favorited model IDs.
+ * @returns Immutable ModelPickerData snapshot.
+ */
+export function createModelPickerData(
+  models: readonly ModelDefinition[],
+  healthState: ProviderHealthDomainState,
+  modelState: ModelDomainState,
+  benchmarkStore: Pick<BenchmarkStore, 'getBenchmarks'>,
+  providerRegistry: Pick<ProviderRegistry, 'getSyntheticModelInfoFromCatalog' | 'getContextWindowForModel'>,
+  pinnedIds: ReadonlySet<string> = new Set(),
+): ModelPickerData {
+  // Delegate to the data provider for consistent derivation logic,
+  // then dispose immediately since no subscriptions are needed.
+  const dp = new ModelPickerDataProvider(models, healthState, modelState, {
+    pinnedIds,
+    benchmarkStore,
+    providerRegistry,
+  });
+  const snapshot = dp.getSnapshot();
+  dp.dispose();
+  return snapshot;
+}

package/src/runtime/ui/model-picker/types.ts

@@ -0,0 +1,149 @@
+/**
+ * Model picker UI data types.
+ *
+ * Purely data-oriented — no rendering logic. These types are produced by
+ * ModelPickerDataProvider and consumed by renderers/components.
+ */
+import type { ProviderStatus } from '@/runtime/index.ts';
+import type { ModelFamily, CategoryFilter } from '../../../input/model-picker.ts';
+
+// Re-export for convenience
+export type { ProviderStatus };
+
+/**
+ * Capability flags indicating what a model can do.
+ */
+export interface CapabilityFlags {
+  /** Model supports extended reasoning / chain-of-thought. */
+  readonly reasoning: boolean;
+  /** Model supports prompt caching. */
+  readonly caching: boolean;
+  /** Model supports tool/function calling. */
+  readonly toolCalling: boolean;
+  /** Model supports vision/multimodal inputs. */
+  readonly multimodal: boolean;
+  /** Model supports code editing operations. */
+  readonly codeEditing: boolean;
+}
+
+/**
+ * Latency statistics for a provider, derived from health telemetry.
+ */
+export interface ProviderLatencyStats {
+  /** Moving average latency in ms (last N calls). */
+  readonly avgMs: number;
+  /** Approximate 95th-percentile latency in ms (max of recent observations). */
+  readonly p95Ms: number;
+  /** Minimum observed latency in ms. */
+  readonly minMs: number;
+}
+
+/**
+ * Health context for a single provider, enriched into model picker entries.
+ */
+export interface ProviderHealthContext {
+  /** Current health status of the provider. */
+  readonly status: ProviderStatus;
+  /** Latency stats. Present only when the provider has call history. */
+  readonly latency?: ProviderLatencyStats;
+  /** Cache hit rate (0–1). Present only when cache metrics are available. */
+  readonly cacheHitRate?: number;
+  /** True when the provider is configured with a valid API key. */
+  readonly isConfigured: boolean;
+  /** Rate limit reset time (epoch ms), if the provider is currently rate-limited. */
+  readonly rateLimitResetAt?: number;
+}
+
+/**
+ * A single entry in the model picker list, enriched with health and benchmark data.
+ */
+export interface ModelPickerEntry {
+  // ── Identity ──────────────────────────────────────────────────────────────
+  /** Unique model identifier. */
+  readonly modelId: string;
+  /** Provider identifier. */
+  readonly providerId: string;
+  /** Human-readable display name. */
+  readonly displayName: string;
+  /** Model family (GPT, Claude, Gemini, …). */
+  readonly family: ModelFamily;
+  /** Pricing tier bucket. */
+  readonly pricingTier: CategoryFilter;
+
+  // ── Quality ───────────────────────────────────────────────────────────────
+  /** Quality tier badge (S/A/B/C), derived from benchmark composite score. */
+  readonly qualityTier?: string;
+  /** Benchmark composite score (0–1). */
+  readonly benchmarkScore?: number;
+
+  // ── Capabilities ──────────────────────────────────────────────────────────
+  /** Capability flags for this model. */
+  readonly capabilities: CapabilityFlags;
+
+  // ── Health ────────────────────────────────────────────────────────────────
+  /** Health context for the model's provider. */
+  readonly health: ProviderHealthContext;
+
+  // ── Context window ─────────────────────────────────────────────────────
+  /**
+   * Effective context window in tokens.
+   * Use this for display and budgeting — it is the authoritative value.
+   */
+  readonly contextWindow: number;
+  /**
+   * How `contextWindow` was determined.
+   * - `provider_api`   — reported by the provider's /v1/models endpoint
+   * - `configured_cap` — set explicitly in the provider config file
+   * - `fallback`       — default constant (no config or API source)
+   * - `openrouter`     — sourced from OpenRouter model data (built-in catalog models)
+   * - `registry`       — static value in the built-in model registry
+   */
+  readonly contextWindowSource:
+    | 'provider_api'
+    | 'configured_cap'
+    | 'fallback'
+    | 'openrouter'
+    | 'registry';
+
+  // ── Display state ─────────────────────────────────────────────────────────
+  /** True if this model is in the user's favorites/pinned list. */
+  readonly isPinned: boolean;
+  /** True if this is the currently active model. */
+  readonly isActive: boolean;
+  /** True when the provider is currently in a degraded or critical state. */
+  readonly isProviderDegraded: boolean;
+  /** True when the provider is unavailable or in auth error. */
+  readonly isProviderUnavailable: boolean;
+  /** True if this model is part of the current fallback chain. */
+  readonly isInFallbackChain: boolean;
+  /** Position in the fallback chain (0 = primary, 1+ = fallback index). */
+  readonly fallbackPosition?: number;
+}
+
+/**
+ * A visual group in the model picker list.
+ */
+export interface ModelPickerGroup {
+  /** Group label (e.g. provider name, family name, quality tier). */
+  readonly label: string;
+  /** Entries belonging to this group, sorted by health then favorites. */
+  readonly entries: readonly ModelPickerEntry[];
+}
+
+/**
+ * Complete data snapshot produced by ModelPickerDataProvider.
+ */
+export interface ModelPickerData {
+  /** All enriched model entries (flat, pre-sorted). */
+  readonly entries: readonly ModelPickerEntry[];
+  /** Grouped view for rendering with section headers. */
+  readonly groups: readonly ModelPickerGroup[];
+  /** IDs of providers that are currently degraded. */
+  readonly degradedProviderIds: readonly string[];
+  /** IDs of providers that are currently unavailable. */
+  readonly unavailableProviderIds: readonly string[];
+  /** Model ID currently at the head of the fallback chain (active model). */
+  readonly activeModelId: string;
+  /** Epoch ms when this snapshot was produced. */
+  readonly snapshotAt: number;
+}

package/src/runtime/ui/provider-health/data-provider.ts

@@ -0,0 +1,244 @@
+/**
+ * ProviderHealthDataProvider — enriched provider health data surface.
+ *
+ * Combines ProviderHealthDomainState and ModelDomainState into a single,
+ * sorted ProviderHealthData snapshot for UI consumption.
+ *
+ * This class is a data provider only — it contains no rendering logic.
+ * Subscribe to change notifications and call getSnapshot() to render.
+ */
+import type { ProviderHealthDomainState, ProviderHealthRecord } from '@/runtime/index.ts';
+import type { ModelDomainState } from '@/runtime/index.ts';
+import { buildFallbackChainData } from '@/runtime/index.ts';
+import type {
+  ProviderHealthData,
+  ProviderHealthEntry,
+  HealthTimeline,
+  HealthTimelinePoint,
+} from '@/runtime/index.ts';
+
+/**
+ * Number of timeline points retained per provider.
+ * Each point represents a snapshot at the time of a state update.
+ */
+const TIMELINE_MAX_POINTS = 60;
+
+/** Status sort priority (lower = shown first in list). */
+const STATUS_ORDER: Record<string, number> = {
+  degraded: 0,
+  rate_limited: 1,
+  auth_error: 2,
+  unavailable: 3,
+  unknown: 4,
+  healthy: 5,
+};
+
+/**
+ * Internal mutable timeline buffer for a provider.
+ */
+interface TimelineBuffer {
+  readonly points: HealthTimelinePoint[];
+}
+
+/**
+ * ProviderHealthDataProvider produces enriched provider health data snapshots.
+ *
+ * Usage:
+ * ```ts
+ * const provider = new ProviderHealthDataProvider(healthState, modelState);
+ * const unsub = provider.subscribe(() => {
+ *   const data = provider.getSnapshot();
+ *   // render data.entries, data.fallbackChain, etc.
+ * });
+ * // When state changes:
+ * provider.updateHealthState(newHealthState);
+ * provider.updateModelState(newModelState);
+ * // Cleanup:
+ * unsub();
+ * provider.dispose();
+ * ```
+ */
+export class ProviderHealthDataProvider {
+  private _healthState: ProviderHealthDomainState;
+  private _modelState: ModelDomainState;
+  private _snapshot: ProviderHealthData;
+  private readonly _subscribers = new Set<() => void>();
+  /** Per-provider timeline buffers, keyed by providerId. */
+  private readonly _timelines = new Map<string, TimelineBuffer>();
+
+  constructor(healthState: ProviderHealthDomainState, modelState: ModelDomainState) {
+    this._healthState = healthState;
+    this._modelState = modelState;
+    this._seedTimelines(healthState);
+    this._snapshot = this._buildSnapshot();
+  }
+
+  /**
+   * Return the current enriched provider health data snapshot.
+   * Updated synchronously when state changes via update methods.
+   */
+  public getSnapshot(): ProviderHealthData {
+    return this._snapshot;
+  }
+
+  /**
+   * Register a callback invoked whenever the snapshot changes.
+   * @returns An unsubscribe function.
+   */
+  public subscribe(callback: () => void): () => void {
+    this._subscribers.add(callback);
+    return () => this._subscribers.delete(callback);
+  }
+
+  /**
+   * Update provider health state and rebuild the snapshot.
+   * Appends a new timeline point for each provider.
+   */
+  public updateHealthState(healthState: ProviderHealthDomainState): void {
+    this._healthState = healthState;
+    this._appendTimelinePoints(healthState);
+    this._rebuild();
+  }
+
+  /**
+   * Update model domain state (e.g. active model or fallback chain change).
+   * Triggers a snapshot rebuild.
+   */
+  public updateModelState(modelState: ModelDomainState): void {
+    this._modelState = modelState;
+    this._rebuild();
+  }
+
+  /**
+   * Release all subscriber references.
+   * Does not clear internal state — getSnapshot() remains usable after disposal.
+   */
+  public dispose(): void {
+    this._subscribers.clear();
+  }
+
+  // ── Private ────────────────────────────────────────────────────────────────
+
+  /**
+   * Seed timeline buffers from the initial health state.
+   * Appends one point per known provider to initialize the timeline.
+   */
+  private _seedTimelines(healthState: ProviderHealthDomainState): void {
+    for (const [id, record] of healthState.providers) {
+      const buffer: TimelineBuffer = { points: [] };
+      this._timelines.set(id, buffer);
+      this._appendPoint(buffer, record);
+    }
+  }
+
+  /**
+   * Append a new timeline point for every provider in the updated state.
+   * Creates a new buffer for providers seen for the first time.
+   */
+  private _appendTimelinePoints(healthState: ProviderHealthDomainState): void {
+    for (const [id, record] of healthState.providers) {
+      if (!this._timelines.has(id)) {
+        this._timelines.set(id, { points: [] });
+      }
+      this._appendPoint(this._timelines.get(id)!, record);
+    }
+  }
+
+  /** Append a single timeline point to a buffer, capping at TIMELINE_MAX_POINTS. */
+  private _appendPoint(buffer: TimelineBuffer, record: ProviderHealthRecord): void {
+    const total = record.stats.totalCalls;
+    const successRate = total > 0 ? record.stats.successCalls / total : 1;
+    const errorRate = total > 0 ? record.stats.errorCalls / total : 0;
+
+    buffer.points.push({
+      ts: Date.now(),
+      successRate,
+      avgLatencyMs: record.stats.avgLatencyMs,
+      errorRate,
+    });
+
+    if (buffer.points.length > TIMELINE_MAX_POINTS) {
+      // Array.shift() is O(n) but acceptable: TIMELINE_MAX_POINTS is capped at 60,
+      // so the cost is negligible and the simplicity outweighs a ring-buffer implementation.
+      buffer.points.shift();
+    }
+  }
+
+  /** Build a HealthTimeline from a buffer for a given provider. */
+  private _buildTimeline(providerId: string): HealthTimeline {
+    const buffer = this._timelines.get(providerId);
+    const points: readonly HealthTimelinePoint[] = buffer ? [...buffer.points] : [];
+    return {
+      providerId,
+      points,
+      length: points.length,
+    };
+  }
+
+  private _rebuild(): void {
+    this._snapshot = this._buildSnapshot();
+    this._notify();
+  }
+
+  private _buildSnapshot(): ProviderHealthData {
+    const entries: ProviderHealthEntry[] = [];
+
+    for (const [id, record] of this._healthState.providers) {
+      const total = record.stats.totalCalls;
+      const successRate = total > 0 ? record.stats.successCalls / total : 1;
+      const errorRate = total > 0 ? record.stats.errorCalls / total : 0;
+
+      entries.push({
+        providerId: id,
+        displayName: record.displayName,
+        status: record.status,
+        isActive: record.isActive,
+        isConfigured: record.isConfigured,
+        successRate,
+        errorRate,
+        p95LatencyMs: record.stats.maxLatencyMs,
+        avgLatencyMs: record.stats.avgLatencyMs,
+        totalCalls: total,
+        // cacheHitRate is populated only when cache-capability is wired to the provider record.
+        // Until then this will always be undefined — intentionally unsupported at this stage.
+        cacheHitRate: record.cacheMetrics?.hitRate,
+        cacheReadTokens: record.cacheMetrics?.cacheReadTokens,
+        cacheWriteTokens: record.cacheMetrics?.cacheWriteTokens,
+        lastSuccessAt: record.stats.lastSuccessAt,
+        lastErrorAt: record.stats.lastErrorAt,
+        lastErrorMessage: record.stats.lastErrorMessage,
+        lastCheckedAt: record.lastCheckedAt,
+        rateLimitResetAt: record.rateLimitResetAt,
+        timeline: this._buildTimeline(id),
+      });
+    }
+
+    // Sort: degraded/unavailable first (needs attention), then healthy, then unknown
+    entries.sort((a, b) => {
+      const diff = (STATUS_ORDER[a.status] ?? 4) - (STATUS_ORDER[b.status] ?? 4);
+      return diff !== 0 ? diff : a.displayName.localeCompare(b.displayName);
+    });
+
+    const fallbackChain = buildFallbackChainData(this._modelState, this._healthState);
+
+    return {
+      entries,
+      compositeStatus: this._healthState.compositeStatus,
+      degradedCount: this._healthState.degradedCount,
+      unavailableCount: this._healthState.unavailableCount,
+      fallbackChain,
+      warnings: this._healthState.warnings,
+      snapshotAt: Date.now(),
+    };
+  }
+
+  private _notify(): void {
+    for (const cb of this._subscribers) {
+      try {
+        cb();
+      } catch {
+        // Non-fatal: subscriber errors must not crash the provider
+      }
+    }
+  }
+}