@pellux/goodvibes-agent 0.1.0

package/src/runtime/store/state.ts

@@ -0,0 +1,145 @@
+/**
+ * RuntimeState — the canonical top-level state shape for the goodvibes-agent
+ * runtime store. All domain slices are defined here.
+ *
+ * Each domain includes revision, lastUpdatedAt, and source metadata fields.
+ * These are defined per-domain in the domain files.
+ */
+
+import type { SessionDomainState } from '@/runtime/index.ts';
+import type { ModelDomainState } from '@/runtime/index.ts';
+import type { ConversationDomainState } from '@/runtime/index.ts';
+import type { OverlayDomainState } from '@/runtime/index.ts';
+import type { PanelDomainState } from './domains/panels.ts';
+import type { PermissionDomainState } from '@/runtime/index.ts';
+import type { TaskDomainState } from '@/runtime/index.ts';
+import type { AgentDomainState } from '@/runtime/index.ts';
+import type { OrchestrationDomainState } from '@/runtime/index.ts';
+import type { CommunicationDomainState } from '@/runtime/index.ts';
+import type { ProviderHealthDomainState } from '@/runtime/index.ts';
+import type { McpDomainState } from '@/runtime/index.ts';
+import type { PluginDomainState } from '@/runtime/index.ts';
+import type { DaemonDomainState } from '@/runtime/index.ts';
+import type { AutomationDomainState } from '@/runtime/index.ts';
+import type { AcpDomainState } from '@/runtime/index.ts';
+import type { RoutesDomainState } from '@/runtime/index.ts';
+import type { ControlPlaneDomainState } from '@/runtime/index.ts';
+import type { DeliveryDomainState } from '@/runtime/index.ts';
+import type { WatcherDomainState } from '@/runtime/index.ts';
+import type { SurfaceDomainState } from '@/runtime/index.ts';
+import type { IntegrationDomainState } from '@/runtime/index.ts';
+import type { TelemetryDomainState } from '@/runtime/index.ts';
+import type { GitDomainState } from '@/runtime/index.ts';
+import type { DiscoveryDomainState } from '@/runtime/index.ts';
+import type { IntelligenceDomainState } from '@/runtime/index.ts';
+import type { UiPerfDomainState } from './domains/ui-perf.ts';
+// UiPerfDomainState is structurally identical to SDK's SurfacePerfDomainState.
+// Export as SurfacePerfDomainState alias for SDK compatibility.
+export type { UiPerfDomainState };
+
+import { createInitialSessionState } from '@/runtime/index.ts';
+import { createInitialModelState } from '@/runtime/index.ts';
+import { createInitialConversationState } from '@/runtime/index.ts';
+import { createInitialOverlaysState } from '@/runtime/index.ts';
+import { createInitialPanelsState } from './domains/panels.ts';
+import { createInitialPermissionsState } from '@/runtime/index.ts';
+import { createInitialTasksState } from '@/runtime/index.ts';
+import { createInitialAgentsState } from '@/runtime/index.ts';
+import { createInitialOrchestrationState } from '@/runtime/index.ts';
+import { createInitialCommunicationState } from '@/runtime/index.ts';
+import { createInitialProviderHealthState } from '@/runtime/index.ts';
+import { createInitialMcpState } from '@/runtime/index.ts';
+import { createInitialPluginsState } from '@/runtime/index.ts';
+import { createInitialDaemonState } from '@/runtime/index.ts';
+import { createInitialAutomationState } from '@/runtime/index.ts';
+import { createInitialAcpState } from '@/runtime/index.ts';
+import { createInitialRoutesState } from '@/runtime/index.ts';
+import { createInitialControlPlaneState } from '@/runtime/index.ts';
+import { createInitialDeliveryState } from '@/runtime/index.ts';
+import { createInitialWatcherState } from '@/runtime/index.ts';
+import { createInitialSurfaceState } from '@/runtime/index.ts';
+import { createInitialIntegrationsState } from '@/runtime/index.ts';
+import { createInitialTelemetryState } from '@/runtime/index.ts';
+import { createInitialGitState } from '@/runtime/index.ts';
+import { createInitialDiscoveryState } from '@/runtime/index.ts';
+import { createInitialIntelligenceState } from '@/runtime/index.ts';
+import { createInitialUiPerfState } from './domains/ui-perf.ts';
+
+/**
+ * RuntimeState — the complete state shape managed by the runtime store.
+ *
+ * Domain slices, each with revision/lastUpdatedAt/source metadata.
+ * All mutations must go through typed domain dispatch APIs.
+ */
+export interface RuntimeState {
+  session: SessionDomainState;
+  model: ModelDomainState;
+  conversation: ConversationDomainState;
+  overlays: OverlayDomainState;
+  /**
+   * TUI panel state. Typed as Record<string,unknown> for SDK RuntimeState
+   * compatibility. Use selectPanels() which casts to PanelDomainState.
+   */
+  panels: Record<string, unknown>;
+  permissions: PermissionDomainState;
+  tasks: TaskDomainState;
+  agents: AgentDomainState;
+  orchestration: OrchestrationDomainState;
+  communication: CommunicationDomainState;
+  providerHealth: ProviderHealthDomainState;
+  mcp: McpDomainState;
+  plugins: PluginDomainState;
+  daemon: DaemonDomainState;
+  automation: AutomationDomainState;
+  routes: RoutesDomainState;
+  controlPlane: ControlPlaneDomainState;
+  deliveries: DeliveryDomainState;
+  watchers: WatcherDomainState;
+  surfaces: SurfaceDomainState;
+  acp: AcpDomainState;
+  integrations: IntegrationDomainState;
+  telemetry: TelemetryDomainState;
+  git: GitDomainState;
+  discovery: DiscoveryDomainState;
+  intelligence: IntelligenceDomainState;
+  /** Surface/UI performance metrics. SDK-compatible field name. */
+  surfacePerf: UiPerfDomainState;
+}
+
+/**
+ * Creates and returns a fully initialized RuntimeState with all domains
+ * set to their default initial values.
+ *
+ * This is the factory used by `createRuntimeStore()` and test harnesses.
+ */
+export function createInitialRuntimeState(): RuntimeState {
+  return {
+    session: createInitialSessionState(),
+    model: createInitialModelState(),
+    conversation: createInitialConversationState(),
+    overlays: createInitialOverlaysState(),
+    panels: createInitialPanelsState() as unknown as Record<string, unknown>,
+    permissions: createInitialPermissionsState(),
+    tasks: createInitialTasksState(),
+    agents: createInitialAgentsState(),
+    orchestration: createInitialOrchestrationState(),
+    communication: createInitialCommunicationState(),
+    providerHealth: createInitialProviderHealthState(),
+    mcp: createInitialMcpState(),
+    plugins: createInitialPluginsState(),
+    daemon: createInitialDaemonState(),
+    automation: createInitialAutomationState(),
+    routes: createInitialRoutesState(),
+    controlPlane: createInitialControlPlaneState(),
+    deliveries: createInitialDeliveryState(),
+    watchers: createInitialWatcherState(),
+    surfaces: createInitialSurfaceState(),
+    acp: createInitialAcpState(),
+    integrations: createInitialIntegrationsState(),
+    telemetry: createInitialTelemetryState(),
+    git: createInitialGitState(),
+    discovery: createInitialDiscoveryState(),
+    intelligence: createInitialIntelligenceState(),
+    surfacePerf: createInitialUiPerfState(),
+  };
+}

package/src/runtime/surface-feature-flags.ts

@@ -0,0 +1,65 @@
+import type { ConfigKey, ConfigManager, PersistedFlagState } from '../config/index.ts';
+import { surfaceFeatureGateId } from '@/runtime/index.ts';
+
+export const CONTROL_PLANE_FEATURE_FLAG = 'control-plane-gateway';
+export const ROUTE_BINDING_FEATURE_FLAG = 'route-binding';
+export const DELIVERY_ENGINE_FEATURE_FLAG = 'delivery-engine';
+export const SERVICE_MANAGEMENT_FEATURE_FLAG = 'service-management';
+
+const CORE_CHANNEL_FEATURE_FLAGS = [
+  CONTROL_PLANE_FEATURE_FLAG,
+  ROUTE_BINDING_FEATURE_FLAG,
+  DELIVERY_ENGINE_FEATURE_FLAG,
+] as const;
+
+export type FeatureFlagConfigKey = 'featureFlags' | `featureFlags.${string}`;
+
+export function getSurfaceFeatureFlag(surfaceId: string): string | null {
+  return surfaceFeatureGateId(surfaceId);
+}
+
+export function getServerSurfaceFeatureFlags(options: {
+  readonly serverBacked?: boolean;
+  readonly web?: boolean;
+  readonly externalSurfaces?: readonly string[];
+}): readonly string[] {
+  const flags = new Set<string>();
+  const hasExternalSurfaces = (options.externalSurfaces?.length ?? 0) > 0;
+
+  if (options.serverBacked || options.web || hasExternalSurfaces) {
+    flags.add(CONTROL_PLANE_FEATURE_FLAG);
+    flags.add(SERVICE_MANAGEMENT_FEATURE_FLAG);
+  }
+  if (options.web) {
+    const webFlag = getSurfaceFeatureFlag('web');
+    if (webFlag) flags.add(webFlag);
+  }
+
+  if (hasExternalSurfaces) {
+    for (const flag of CORE_CHANNEL_FEATURE_FLAGS) flags.add(flag);
+    for (const surfaceId of options.externalSurfaces ?? []) {
+      const surfaceFlag = getSurfaceFeatureFlag(surfaceId);
+      if (surfaceFlag) flags.add(surfaceFlag);
+    }
+  }
+
+  return [...flags].sort((left, right) => left.localeCompare(right));
+}
+
+export function isFeatureFlagEnabled(config: Pick<ConfigManager, 'getCategory'>, flagId: string): boolean {
+  const flags = (config.getCategory('featureFlags') as Record<string, PersistedFlagState | undefined>) ?? {};
+  return flags[flagId] === 'enabled';
+}
+
+export function getMissingSurfaceFeatureFlags(config: Pick<ConfigManager, 'getCategory'>, surfaceId: string): readonly string[] {
+  const required = surfaceId === 'web'
+    ? getServerSurfaceFeatureFlags({ web: true })
+    : getServerSurfaceFeatureFlags({ externalSurfaces: [surfaceId] });
+  return required.filter((flagId) => !isFeatureFlagEnabled(config, flagId));
+}
+
+export function enableFeatureFlags(config: Pick<ConfigManager, 'setDynamic'>, flagIds: readonly string[]): void {
+  for (const flagId of flagIds) {
+    config.setDynamic(`featureFlags.${flagId}` as ConfigKey, 'enabled');
+  }
+}

package/src/runtime/terminal-output-guard.ts

@@ -0,0 +1,228 @@
+import { format } from 'node:util';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils';
+
+type WritableStreamLike = {
+  write: {
+    (buffer: string | Uint8Array, cb?: (error?: Error | null) => void): boolean;
+    (buffer: string | Uint8Array, encoding?: BufferEncoding, cb?: (error?: Error | null) => void): boolean;
+  };
+};
+
+export type TerminalOutputInterceptSource =
+  | 'stdout'
+  | 'stderr'
+  | 'console.debug'
+  | 'console.error'
+  | 'console.info'
+  | 'console.log'
+  | 'console.warn';
+
+export type TerminalOutputIntercept = {
+  readonly source: TerminalOutputInterceptSource;
+  readonly text: string;
+  readonly preview: string;
+};
+
+export type TerminalOutputGuard = {
+  setActive(active: boolean): void;
+  allowTerminalWrite<T>(fn: () => T): T;
+  dispose(): void;
+};
+
+export type TerminalOutputGuardOptions = {
+  readonly stdout: WritableStreamLike;
+  readonly stderr?: WritableStreamLike;
+  readonly active?: boolean;
+  readonly onIntercept?: (event: TerminalOutputIntercept) => void;
+};
+
+export type TuiTerminalOutputGuardOptions = {
+  readonly stdout: WritableStreamLike;
+  readonly stderr?: WritableStreamLike;
+  readonly active?: boolean;
+  readonly notify: (message: string) => void;
+};
+
+const MAX_LOG_TEXT = 4_000;
+const MAX_PREVIEW_TEXT = 180;
+const ANSI_RE = /\x1b\[[0-?]*[ -/]*[@-~]/g;
+
+let currentGuard: TerminalOutputGuard | null = null;
+
+function writeCallback(args: unknown[]): ((error?: Error | null) => void) | undefined {
+  const maybeCallback = args[args.length - 1];
+  return typeof maybeCallback === 'function'
+    ? maybeCallback as (error?: Error | null) => void
+    : undefined;
+}
+
+function chunkToText(chunk: unknown): string {
+  if (typeof chunk === 'string') return chunk;
+  if (chunk instanceof Uint8Array) return Buffer.from(chunk).toString('utf8');
+  return String(chunk);
+}
+
+function normalizeText(text: string): string {
+  return text.replace(ANSI_RE, '').replace(/\r/g, '').trim();
+}
+
+function previewText(text: string): string {
+  const singleLine = normalizeText(text).replace(/\s+/g, ' ');
+  if (singleLine.length <= MAX_PREVIEW_TEXT) return singleLine;
+  return `${singleLine.slice(0, MAX_PREVIEW_TEXT - 1)}...`;
+}
+
+function truncateForLog(text: string): string {
+  if (text.length <= MAX_LOG_TEXT) return text;
+  return `${text.slice(0, MAX_LOG_TEXT)}\n[truncated ${text.length - MAX_LOG_TEXT} byte(s)]`;
+}
+
+function invokeSuppressedCallback(args: unknown[]): void {
+  const callback = writeCallback(args);
+  if (callback) {
+    queueMicrotask(() => callback(null));
+  }
+}
+
+export function allowTerminalWrite<T>(fn: () => T): T {
+  return currentGuard ? currentGuard.allowTerminalWrite(fn) : fn();
+}
+
+export function installTerminalOutputGuard(options: TerminalOutputGuardOptions): TerminalOutputGuard {
+  const stdout = options.stdout;
+  const stderr = options.stderr ?? process.stderr;
+  const originalStdoutWriteMethod = stdout.write;
+  const originalStderrWriteMethod = stderr.write;
+  const originalStdoutWrite = (...args: unknown[]): boolean =>
+    Reflect.apply(originalStdoutWriteMethod, stdout, args) as boolean;
+  const originalStderrWrite = (...args: unknown[]): boolean =>
+    Reflect.apply(originalStderrWriteMethod, stderr, args) as boolean;
+  const originalConsole = {
+    debug: console.debug.bind(console),
+    error: console.error.bind(console),
+    info: console.info.bind(console),
+    log: console.log.bind(console),
+    warn: console.warn.bind(console),
+  };
+
+  let active = options.active ?? true;
+  let disposed = false;
+  let allowDepth = 0;
+  let captureDepth = 0;
+
+  const record = (source: TerminalOutputInterceptSource, text: string): void => {
+    if (disposed || !active) return;
+    const normalized = normalizeText(text);
+    if (!normalized) return;
+    if (normalized.startsWith('[ActivityLogger]')) return;
+    if (captureDepth > 0) return;
+
+    captureDepth++;
+    try {
+      const event: TerminalOutputIntercept = {
+        source,
+        text: truncateForLog(normalized),
+        preview: previewText(normalized),
+      };
+      logger.warn('Intercepted terminal output while TUI renderer was active', {
+        source: event.source,
+        text: event.text,
+      });
+      options.onIntercept?.(event);
+    } finally {
+      captureDepth--;
+    }
+  };
+
+  const shouldPassThrough = (): boolean => !active || allowDepth > 0 || disposed;
+
+  stdout.write = ((...args: unknown[]) => {
+    if (shouldPassThrough()) {
+      return originalStdoutWrite(...args);
+    }
+    record('stdout', chunkToText(args[0]));
+    invokeSuppressedCallback(args);
+    return true;
+  }) as WritableStreamLike['write'];
+
+  stderr.write = ((...args: unknown[]) => {
+    if (shouldPassThrough()) {
+      return originalStderrWrite(...args);
+    }
+    record('stderr', chunkToText(args[0]));
+    invokeSuppressedCallback(args);
+    return true;
+  }) as WritableStreamLike['write'];
+
+  console.debug = (...args: unknown[]) => {
+    if (!active || disposed) return originalConsole.debug(...args);
+    record('console.debug', format(...args));
+  };
+  console.error = (...args: unknown[]) => {
+    if (!active || disposed) return originalConsole.error(...args);
+    record('console.error', format(...args));
+  };
+  console.info = (...args: unknown[]) => {
+    if (!active || disposed) return originalConsole.info(...args);
+    record('console.info', format(...args));
+  };
+  console.log = (...args: unknown[]) => {
+    if (!active || disposed) return originalConsole.log(...args);
+    record('console.log', format(...args));
+  };
+  console.warn = (...args: unknown[]) => {
+    if (!active || disposed) return originalConsole.warn(...args);
+    record('console.warn', format(...args));
+  };
+
+  const guard: TerminalOutputGuard = {
+    setActive(nextActive) {
+      active = nextActive;
+    },
+    allowTerminalWrite<T>(fn: () => T): T {
+      allowDepth++;
+      try {
+        return fn();
+      } finally {
+        allowDepth--;
+      }
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      stdout.write = originalStdoutWriteMethod;
+      stderr.write = originalStderrWriteMethod;
+      console.debug = originalConsole.debug;
+      console.error = originalConsole.error;
+      console.info = originalConsole.info;
+      console.log = originalConsole.log;
+      console.warn = originalConsole.warn;
+      if (currentGuard === guard) {
+        currentGuard = null;
+      }
+    },
+  };
+
+  currentGuard = guard;
+  return guard;
+}
+
+export function installTuiTerminalOutputGuard(options: TuiTerminalOutputGuardOptions): TerminalOutputGuard {
+  let capturedWriteCount = 0;
+  let lastNoticeAt = 0;
+  return installTerminalOutputGuard({
+    stdout: options.stdout,
+    stderr: options.stderr,
+    active: options.active,
+    onIntercept: (event) => {
+      capturedWriteCount++;
+      const now = Date.now();
+      if (now - lastNoticeAt < 5_000) return;
+      const count = capturedWriteCount;
+      capturedWriteCount = 0;
+      lastNoticeAt = now;
+      const plural = count === 1 ? '' : 's';
+      options.notify(`[Terminal] Captured ${count} direct ${event.source} write${plural} that would have corrupted the TUI: ${event.preview}`);
+    },
+  });
+}

package/src/runtime/ui/index.ts

@@ -0,0 +1,39 @@
+/**
+ * Runtime UI data surface barrel.
+ *
+ * Exports enriched data providers and one-shot factory functions for
+ * the model picker and provider health surfaces.
+ *
+ * These modules produce structured data for renderers — no UI rendering
+ * logic lives here.
+ */
+
+// ── Model picker ──────────────────────────────────────────────────────────────
+export type {
+  CapabilityFlags,
+  ProviderLatencyStats,
+  ProviderHealthContext,
+  ModelPickerEntry,
+  ModelPickerGroup,
+  ModelPickerData,
+} from '@/runtime/index.ts';
+export type { ProviderStatus as ModelPickerProviderStatus } from '@/runtime/index.ts';
+export { ModelPickerDataProvider, createModelPickerData } from '@/runtime/index.ts';
+export type { ModelPickerDataProviderOptions } from '@/runtime/index.ts';
+
+// ── Provider health ───────────────────────────────────────────────────────────
+export type {
+  HealthTimelinePoint,
+  HealthTimeline,
+  ProviderHealthEntry,
+  FallbackChainNode,
+  FallbackChainData,
+  ProviderHealthData,
+  CompositeHealthStatus,
+} from '@/runtime/index.ts';
+export type { ProviderStatus } from '@/runtime/index.ts';
+export {
+  ProviderHealthDataProvider,
+  buildFallbackChainData,
+  createProviderHealthData,
+} from '@/runtime/index.ts';

package/src/runtime/ui/model-picker/data-provider.ts

@@ -0,0 +1,182 @@
+/**
+ * ModelPickerDataProvider — enriched model picker data surface.
+ *
+ * Combines ModelDefinition records from the provider registry with
+ * ProviderHealthDomainState and ModelDomainState to produce a single,
+ * sorted, health-enriched ModelPickerData 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 { 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 { enrichModelEntries, groupEntriesByProvider } from '@/runtime/index.ts';
+import type { ModelPickerData, ModelPickerEntry } from '@/runtime/index.ts';
+
+/** Options for constructing a ModelPickerDataProvider. */
+export interface ModelPickerDataProviderOptions {
+  /**
+   * Initial set of pinned model IDs.
+   * Call updatePinnedIds() to update at runtime.
+   */
+  readonly pinnedIds?: ReadonlySet<string>;
+  readonly benchmarkStore: Pick<BenchmarkStore, 'getBenchmarks'>;
+  readonly providerRegistry: Pick<ProviderRegistry, 'getSyntheticModelInfoFromCatalog' | 'getContextWindowForModel'>;
+}
+
+/**
+ * ModelPickerDataProvider produces enriched model picker data snapshots.
+ *
+ * Usage:
+ * ```ts
+ * const provider = new ModelPickerDataProvider(models, healthState, modelState);
+ * const unsub = provider.subscribe(() => {
+ *   const data = provider.getSnapshot();
+ *   // render data.entries or data.groups
+ * });
+ * // When health or model state changes:
+ * provider.updateHealthState(newHealthState);
+ * provider.updateModelState(newModelState);
+ * // Cleanup:
+ * unsub();
+ * provider.dispose();
+ * ```
+ */
+export class ModelPickerDataProvider {
+  private _models: readonly ModelDefinition[];
+  private _healthState: ProviderHealthDomainState;
+  private _modelState: ModelDomainState;
+  private _pinnedIds: ReadonlySet<string>;
+  private _snapshot: ModelPickerData;
+  private readonly benchmarkStore: Pick<BenchmarkStore, 'getBenchmarks'>;
+  private readonly providerRegistry: Pick<ProviderRegistry, 'getSyntheticModelInfoFromCatalog' | 'getContextWindowForModel'>;
+  private readonly _subscribers = new Set<() => void>();
+
+  constructor(
+    models: readonly ModelDefinition[],
+    healthState: ProviderHealthDomainState,
+    modelState: ModelDomainState,
+    options: ModelPickerDataProviderOptions,
+  ) {
+    this._models = models;
+    this._healthState = healthState;
+    this._modelState = modelState;
+    this._pinnedIds = options.pinnedIds ?? new Set();
+    this.benchmarkStore = options.benchmarkStore;
+    this.providerRegistry = options.providerRegistry;
+    this._snapshot = this._buildSnapshot();
+  }
+
+  /**
+   * Return the current enriched model picker data snapshot.
+   * This is updated synchronously when state changes via update methods.
+   */
+  public getSnapshot(): ModelPickerData {
+    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 the model list (e.g. after registry reload).
+   * Triggers a snapshot rebuild and notifies subscribers.
+   */
+  public updateModels(models: readonly ModelDefinition[]): void {
+    this._models = models;
+    this._rebuild();
+  }
+
+  /**
+   * Update health state (e.g. on ProviderHealthDomainState change).
+   * Triggers a snapshot rebuild and notifies subscribers.
+   */
+  public updateHealthState(healthState: ProviderHealthDomainState): void {
+    this._healthState = healthState;
+    this._rebuild();
+  }
+
+  /**
+   * Update model domain state (e.g. on active model or fallback change).
+   * Triggers a snapshot rebuild and notifies subscribers.
+   */
+  public updateModelState(modelState: ModelDomainState): void {
+    this._modelState = modelState;
+    this._rebuild();
+  }
+
+  /**
+   * Update the pinned/favorites model ID set.
+   * Triggers a snapshot rebuild and notifies subscribers.
+   */
+  public updatePinnedIds(pinnedIds: ReadonlySet<string>): void {
+    this._pinnedIds = pinnedIds;
+    this._rebuild();
+  }
+
+  /**
+   * Release all subscriber references.
+   * Does not clear internal state — getSnapshot() remains usable after disposal.
+   */
+  public dispose(): void {
+    this._subscribers.clear();
+  }
+
+  // ── Private ────────────────────────────────────────────────────────────────
+
+  private _rebuild(): void {
+    this._snapshot = this._buildSnapshot();
+    this._notify();
+  }
+
+  private _buildSnapshot(): ModelPickerData {
+    const entries: readonly ModelPickerEntry[] = enrichModelEntries(
+      this._models,
+      this._healthState,
+      this._modelState,
+      this._pinnedIds,
+      this.benchmarkStore,
+      this.providerRegistry,
+    );
+
+    const groups = groupEntriesByProvider(entries);
+
+    const degradedProviderIds: string[] = [];
+    const unavailableProviderIds: string[] = [];
+    for (const [id, record] of this._healthState.providers) {
+      if (record.status === 'degraded' || record.status === 'rate_limited') {
+        degradedProviderIds.push(id);
+      } else if (record.status === 'unavailable' || record.status === 'auth_error') {
+        unavailableProviderIds.push(id);
+      }
+    }
+
+    return {
+      entries,
+      groups,
+      degradedProviderIds,
+      unavailableProviderIds,
+      activeModelId: this._modelState.activeModelId,
+      snapshotAt: Date.now(),
+    };
+  }
+
+  private _notify(): void {
+    for (const cb of this._subscribers) {
+      try {
+        cb();
+      } catch {
+        // Non-fatal: subscriber errors must not crash the provider
+      }
+    }
+  }
+}