@ai-matrx/agents 0.59.256 → 0.59.258

package/dist/models/index.cjs

@@ -42,6 +42,7 @@ __export(models_exports, {
   TOP_TIER_COST_RATING: () => TOP_TIER_COST_RATING,
   TOP_TIER_LOCKED_TITLE: () => TOP_TIER_LOCKED_TITLE,
   acceptsTextInstructions: () => acceptsTextInstructions,
+  announceModelCatalogChanged: () => announceModelCatalogChanged,
   blendedPrice: () => blendedPrice,
   buildModelClassIndex: () => buildModelClassIndex,
   buildSuccessionIndex: () => buildSuccessionIndex,
@@ -65,6 +66,7 @@ __export(models_exports, {
   fitsMemory: () => fitsMemory,
   fitsNeed: () => fitsNeed,
   fitsThisComputer: () => fitsThisComputer,
+  followModelCatalogChanges: () => followModelCatalogChanges,
   formatMemoryBytes: () => formatMemoryBytes,
   fromDiscovery: () => fromDiscovery,
   ggufEngine: () => ggufEngine,
@@ -82,21 +84,25 @@ __export(models_exports, {
   isListedVariant: () => isListedVariant,
   isLocalModelCatalog: () => isLocalModelCatalog,
   isManagedAgentModelCapability: () => isManagedAgentModelCapability,
+  isModelCatalogChange: () => isModelCatalogChange,
   isProjectorName: () => isProjectorName,
   isSupersedable: () => isSupersedable,
   isTopTierRating: () => isTopTierRating,
   judgeHeaderFacts: () => judgeHeaderFacts,
   mergeAuditRecordIntoCapabilities: () => mergeAuditRecordIntoCapabilities,
   missingShards: () => missingShards,
+  modelCatalogRevision: () => modelCatalogRevision,
   modelClassKnobFor: () => modelClassKnobFor,
   modelClassName: () => modelClassName,
   modelClassPinOf: () => modelClassPinOf,
+  modelDisplayLabel: () => modelDisplayLabel,
   modelsForSelectionPurpose: () => modelsForSelectionPurpose,
   normalizeArch: () => normalizeArch,
   normalizeModel: () => normalizeModel,
   normalizeModels: () => normalizeModels,
   normalizeOs: () => normalizeOs,
   normalizePromptSettings: () => normalizePromptSettings,
+  onModelCatalogChanged: () => onModelCatalogChanged,
   orderCatalogGroups: () => orderCatalogGroups,
   orderCatalogModels: () => orderCatalogModels,
   outputFormatControlKey: () => outputFormatControlKey,
@@ -108,6 +114,8 @@ __export(models_exports, {
   readCuratedRows: () => readCuratedRows,
   readGgufHeader: () => readGgufHeader,
   readModelCatalog: () => readModelCatalog,
+  readModelIdentities: () => readModelIdentities,
+  readPublicModel: () => readPublicModel,
   reconcileModelFavoriteIds: () => reconcileModelFavoriteIds,
   reportModelDiagnostic: () => reportModelDiagnostic,
   requireCanonicalCapabilities: () => requireCanonicalCapabilities,
@@ -918,6 +926,48 @@ var OUTPUT_MODALITIES = [
   "decision"
 ];
 
+// models/catalog/changes.ts
+var KEY2 = /* @__PURE__ */ Symbol.for("ai-matrx.agents.model-catalog-changes");
+function hub() {
+  const g = globalThis;
+  return g[KEY2] ??= { listeners: /* @__PURE__ */ new Set(), revision: 0 };
+}
+function isModelCatalogChange(payload) {
+  const catalog = payload?.["catalog"];
+  return catalog === void 0 || catalog === null || catalog === "models";
+}
+function onModelCatalogChanged(listener) {
+  const h = hub();
+  h.listeners.add(listener);
+  return () => {
+    h.listeners.delete(listener);
+  };
+}
+function modelCatalogRevision() {
+  return hub().revision;
+}
+function announceModelCatalogChanged(payload = {}) {
+  if (!isModelCatalogChange(payload)) return;
+  const h = hub();
+  h.revision += 1;
+  for (const l of [...h.listeners]) {
+    try {
+      l(payload);
+    } catch (err) {
+      console.error("[@ai-matrx/agents/models] a catalog_changed listener threw", err);
+    }
+  }
+}
+function followModelCatalogChanges(subscribe) {
+  return subscribe("catalog_changed", (payload) => announceModelCatalogChanged(payload ?? {}));
+}
+
+// models/label.ts
+function modelDisplayLabel(row) {
+  if (!row) return void 0;
+  return row.common_name || row.name || void 0;
+}
+
 // models/catalog/records.ts
 var classConfigKey = (modelId, offeringId) => `${modelId}:${offeringId}`;
 var EMPTY_MODEL_RECORDS = Object.freeze({
@@ -986,7 +1036,7 @@ function withIdLists(state2) {
   const active = [];
   const deprecated = [];
   for (const [id, record] of Object.entries(state2.entities)) (record.is_deprecated === true ? deprecated : active).push(id);
-  const label = (id) => state2.entities[id]?.common_name ?? state2.entities[id]?.name ?? "";
+  const label = (id) => modelDisplayLabel(state2.entities[id]) ?? "";
   const sort = (ids) => ids.sort((a, b) => label(a).localeCompare(label(b)));
   return { ...state2, activeIds: sort(active), deprecatedIds: sort(deprecated) };
 }
@@ -1407,13 +1457,13 @@ function selectDeprecatedModels(s3) {
 var allOf = memo((entities) => Object.values(entities));
 var selectAllModels = (s3) => allOf(s3.entities);
 var optionsOf = memo(
-  (models) => models.map((m) => ({ value: m.id, label: m.common_name || m.name || m.id, maker: m.maker, costRating: m.cost_rating, speedRating: m.speed_rating }))
+  (models) => models.map((m) => ({ value: m.id, label: modelDisplayLabel(m) || m.id, maker: m.maker, costRating: m.cost_rating, speedRating: m.speed_rating }))
 );
 var selectModelOptions = (s3) => optionsOf(selectActiveModels(s3));
 var allOptionsOf = memo(
   (entities) => Object.values(entities).map((m) => ({
     value: m.id,
-    label: m.common_name || m.name || m.id,
+    label: modelDisplayLabel(m) || m.id,
     maker: m.maker,
     isDeprecated: m.is_deprecated ?? false,
     isRetired: m.retired_at != null,
@@ -1426,7 +1476,7 @@ function selectModelLabelById(s3, modelId) {
   if (!modelId) return void 0;
   const m = s3.entities[modelId];
   const identity = s3.identityById[modelId];
-  return m?.common_name || m?.name || identity?.common_name || identity?.name || void 0;
+  return modelDisplayLabel(m) || modelDisplayLabel(identity);
 }
 var selectModelNameById = (s3, modelId) => modelId ? s3.entities[modelId]?.name : void 0;
 var selectModelClassName = (s3, modelId, offeringId) => modelClassName(s3.modelClassIndex, modelId, offeringId);
@@ -1444,6 +1494,18 @@ var selectDeprecatedModelsReady = (s3) => (s3.fetchScope === "deprecated" || s3.
 var selectAllModelsReady = (s3) => s3.fetchScope === "all";
 var selectModelIdentityById = (s3, modelId) => s3.identityById[modelId];
 var selectModelIdentityLookupStatus = (s3, modelId) => s3.identityStatusById[modelId] ?? "idle";
+async function readModelIdentities(client, modelIds) {
+  const ids = [...new Set(modelIds.filter(Boolean))];
+  if (ids.length === 0) return [];
+  const { data, error } = await client.schema("ai").from("model_definition").select("id, name, common_name, is_deprecated").in("id", ids);
+  if (error) throw new Error(error.message);
+  return Array.isArray(data) ? data : [];
+}
+async function readPublicModel(client, key) {
+  const { data, error } = await client.schema("ai").from("model_public").select("id, name").eq(catalogKeyColumn(key), key.trim()).maybeSingle();
+  if (error) return { row: null, error: error.message };
+  return { row: data ?? null, error: null };
+}
 
 // models/catalog/store.ts
 var IDLE = { status: "idle", models: [], error: null, loadedAt: null };
@@ -1713,8 +1775,16 @@ function createModelCatalog(config) {
     errorSink,
     ...config.isSignedIn ? { isSignedIn: config.isSignedIn } : {}
   });
+  const refresh = async () => {
+    const variants = Object.keys(state2).filter((v) => state2[v].status !== "idle");
+    await Promise.all([records.refresh(), ...variants.map((v) => run(v))]);
+  };
+  const stopFollowing = config.followChanges === false ? () => {
+  } : onModelCatalogChanged(() => void refresh());
   return {
     records,
+    refresh,
+    dispose: stopFollowing,
     getState: () => state2,
     subscribe(listener) {
       listeners.add(listener);

package/dist/models/index.d.cts

@@ -750,6 +750,41 @@ declare const selectDeprecatedModelsReady: (s: ModelRecordsState) => boolean;
 declare const selectAllModelsReady: (s: ModelRecordsState) => boolean;
 declare const selectModelIdentityById: (s: ModelRecordsState, modelId: string) => ModelIdentityRow | undefined;
 declare const selectModelIdentityLookupStatus: (s: ModelRecordsState, modelId: string) => "loading" | "succeeded" | "failed" | "idle";
+/**
+ * The durable identities (id, name, common_name, is_deprecated) of these models, read from
+ * `ai.model_definition` — the same read `records.loadIdentity` makes. For a process with no records
+ * store that stamps a name ONCE (a sync snapshot); a screen names models through the records hooks.
+ * Rows the database does not return are absent. Throws the database's error.
+ */
+declare function readModelIdentities(client: ModelRecordsClient, modelIds: readonly string[]): Promise<ModelIdentityRow[]>;
+/** The structural read `readPublicModel` needs (a supabase-js client fits it as is). */
+interface PublicModelClient {
+    schema(name: "ai"): {
+        from(table: "model_public"): {
+            select(columns: string): {
+                eq(column: string, value: string): {
+                    maybeSingle(): PromiseLike<{
+                        data: unknown;
+                        error: {
+                            message: string;
+                        } | null;
+                    }>;
+                };
+            };
+        };
+    };
+}
+/**
+ * One `ai.model_public` row (id + canonical name) by id or name, read fresh — for a value sent on the wire at
+ * the moment it is used (a voice session's transcription model), never for a label on screen.
+ */
+declare function readPublicModel(client: PublicModelClient, key: string): Promise<{
+    row: {
+        id?: unknown;
+        name?: unknown;
+    } | null;
+    error: string | null;
+}>;
 
 /**
  * `@ai-matrx/agents/models` — `createModelCatalog`: the headless model catalog store.
@@ -802,6 +837,8 @@ type ModelCatalogErrorSink = (event: {
     context?: object;
 }) => void;
 interface ModelCatalogConfig {
+    /** Re-read on every model catalog change notice (catalog/changes.ts). Default true. */
+    followChanges?: boolean;
     client: ModelCatalogClient;
     /** OPTIONAL — DEFAULT: a tagged `console.error` (the in-picker error banner always renders too). */
     errorSink?: ModelCatalogErrorSink;
@@ -828,6 +865,14 @@ interface ModelCatalog {
     load(variant: ModelCatalogVariant): Promise<void>;
     /** Re-read the variant now (rows stay visible while it runs). Never throws. */
     reload(variant: ModelCatalogVariant): Promise<void>;
+    /**
+     * The catalog changed upstream (`catalog_changed`): re-read every picker variant already read and every
+     * record already read (`records.refresh()`). Called by itself on every `announceModelCatalogChanged`
+     * (catalog/changes.ts) unless `followChanges: false`. Never throws.
+     */
+    refresh(): Promise<void>;
+    /** Stop following `catalog_changed` (a test, or a catalog a host discards). */
+    dispose(): void;
     /**
      * The RECORDS part (agent core B3): options list, full records with resolved controls, class
      * configs, the class index and identities — what chat's retired `modelRegistry` slice held.
@@ -1818,4 +1863,49 @@ catalog?: SuccessionClient): Promise<NewAgentModel>;
  */
 declare function resolveModelMapKnob(value: unknown, catalog: SuccessionClient): Promise<Record<string, string>>;
 
-export { type AdminOffering, type AdminPricingBand, type ArtifactUse, type AuditCapabilitiesRecord, CHAT_DEFAULT_MODEL_KNOB, CONTENT_TYPES, type CapabilitiesParseContext, type CatalogKeyColumn, type CatalogKindInput, type CatalogModel, type CatalogTier, type CheapestAdequateOptions, type CompatStatus, type ContentType, type CuratedCatalogClient, type CuratedModel, type CuratedPresentation, type CuratedRows, type CuratedVariant, DEFAULT_CAPABILITIES, type DecidedBy, type DeviceGraphics, type DeviceHardware, type DiscoveryAmbiguity, type DiscoveryArtifact, type DiscoveryMedia, type DiscoveryResult, type DiscoveryRuntime, type DiscoverySource, type DiscoveryVariant, EMPTY_MODEL_RECORDS, EXCLUDED_REVIEW_STATES, FEATURE_BUCKETS, FEATURE_BUCKET_ORDER, FEATURE_KEYS, FILE_TYPE_QUANT, type FeatureBucket, type FeatureBucketMeta, type FeatureKey, type FitCapabilities, GgufError, type GgufHeader, type GgufRead, type GgufTensor, type GroupedFeatures, type HardwareClass, type HardwareClasses, type HeaderFlag, type HeaderJudgement, type HeaderRefusal, INPUT_MODALITIES, INTERACTION_MODES, type Interaction, type InteractionMode, type LocalArtifact, type LocalCatalogClient, type LocalCatalogQuery, type LocalCompatRow, type LocalModel, type LocalModelCatalog, type LocalPresentation, type LocalRuntime, type LocalRuntimeBuild, type LocalVariant, MAX_SUCCESSION_HOPS, MODEL_CATALOG_KINDS, MODEL_FAVORITE_ENTITY_TYPE, type Modality, type ModelCapabilities, type ModelCatalog, type ModelCatalogClient, type ModelCatalogConfig, type ModelCatalogErrorSink, type ModelCatalogPgError, type ModelCatalogPgResult, type ModelCatalogQuery, type ModelCatalogState, type ModelCatalogVariant, type ModelCatalogVariantState, type ModelClassConfig, type ModelClassEntry, type ModelClassIndex, type ModelDiagnosticEntry, type ModelDiagnosticsSink, type ModelFavorites, type ModelFavoritesCache, type ModelFavoritesClient, type ModelFavoritesConfig, type ModelFavoritesErrorSink, type ModelFavoritesState, type ModelFetchScope, type ModelFileHandle, type ModelFit, type ModelIdentityRow, type ModelJson, type ModelNeed, type ModelOfferingRow, type ModelOption, type ModelOptionWithLifecycle, type ModelRecord, type ModelRecordFetchType, type ModelRecords, type ModelRecordsClient, type ModelRecordsConfig, type ModelRecordsState, type ModelSelectionPurpose, type ModelSetEnv, type ModelSetFacts, type ModelSetValidation, NEW_AGENT_DEFAULT_MODEL_KNOB, type NewAgentModel, type NoSelection, OUTPUT_MODALITIES, type OrderedLike, type PreferredModelChoice, type PreferredModelChoicePorts, type PriceTier, type PricedCatalogModel, type RankOptions, type RankedVariant, type ReadModelCatalogOptions, SERVICE_LABEL, SERVICE_LABEL_PLURAL, type SelectDevice, type Selection, type ShardName, type SuccessionClient, type SuccessionIndex, type SuccessionNode, TOP_TIER_COST_RATING, TOP_TIER_LOCKED_TITLE, type VariantDiscovery, type VariantVerdict, type Want, acceptsTextInstructions, blendedPrice, buildModelClassIndex, buildSuccessionIndex, catalogFingerprint, catalogForApp, catalogKeyColumn, catalogKindOf, cheapestAdequateModel, classConfigKey, collapseTiersByClass, costRatingTier, costRatingWord, createModelCatalog, createModelFavorites, createModelRecords, curatedList, displayOrderOf, favoriteIdsEqual, fetchCuratedModels, findNonCanonicalCapabilityValues, fitsMemory, fitsNeed, fitsThisComputer, formatMemoryBytes, fromDiscovery, ggufEngine, ggufFacts, groupFeatures, hardwareClassesOf, hasCompatibleDecisionInteraction, isChatModelCapability, isContentType, isConversationalModelCapability, isDecisionModelCapability, isFeatureKey, isHelperGguf, isInteractionMode, isListedVariant, isLocalModelCatalog, isManagedAgentModelCapability, isProjectorName, isSupersedable, isTopTierRating, judgeHeaderFacts, mergeAuditRecordIntoCapabilities, missingShards, modelClassKnobFor, modelClassName, modelClassPinOf, modelsForSelectionPurpose, normalizeArch, normalizeModel, normalizeModels, normalizeOs, normalizePromptSettings, orderCatalogGroups, orderCatalogModels, outputFormatControlKey, parseCapabilities, pickProjector, priceTierRating, quantFromName, rankVariants, readCuratedRows, readGgufHeader, readModelCatalog, reconcileModelFavoriteIds, reportModelDiagnostic, requireCanonicalCapabilities, requiredArtifacts, resetSuccessionLogForTests, resolveLiveModelId, resolveModelMapKnob, resolveNewAgentModelId, resolvePreferredModelChoice, resolveSuccessor, runtimesOnEngine, seesImages, selectActiveModels, selectActiveModelsReady, selectAllModelOptions, selectAllModels, selectAllModelsReady, selectDeprecatedModels, selectDeprecatedModelsReady, selectModelById, selectModelClassConfig, selectModelClassName, selectModelControls, selectModelDetailError, selectModelFetchType, selectModelFullyLoaded, selectModelIdentityById, selectModelIdentityLookupStatus, selectModelLabelById, selectModelLabelWithClass, selectModelNameById, selectModelOptions, selectVariant, serviceCountLabel, setModelDiagnosticsSink, shapeCuratedModels, shardFileName, shardName, speedRatingLabel, speedRatingWord, splitSetProblems, takesInput, toAuditRecord, validateModelSet, variantVerdict, withModelClass };
+/**
+ * `@ai-matrx/agents/models` — THE model label formula. Every surface that names a model computes the
+ * name here: the person-facing `common_name`, else the canonical `name`. An empty `common_name` counts
+ * as absent. Pure; the row it is handed must come from the subscribed catalog (records / readModelCatalog),
+ * so a `catalog_changed` notice re-renders it. Guard: `scripts/check-model-catalog-reads.mjs`.
+ */
+/** The two columns a model label is made from (cloud records, identities, local catalog rows). */
+interface ModelLabelSource {
+    common_name?: string | null;
+    name?: string | null;
+}
+/** A row that always has a canonical name always has a label. */
+declare function modelDisplayLabel(row: {
+    common_name?: string | null;
+    name: string;
+}): string;
+declare function modelDisplayLabel(row: ModelLabelSource | null | undefined): string | undefined;
+
+/**
+ * `@ai-matrx/agents/models` — the ONE subscription to `catalog_changed`.
+ *
+ * The server publishes `catalog_changed` on the platform bus for every admin edit and direct SQL write to
+ * the model catalog. A host binds its bus client ONCE with `followModelCatalogChanges(subscribe)` (the web's
+ * directive registry, Matrx 2's IPC forward of the main-process bus); every model catalog
+ * (`createModelCatalog`: picker rows + records) re-reads itself on the notice, and any other reader
+ * subscribes here (`onModelCatalogChanged`, or `useModelCatalogRevision` / `useOnModelCatalogChanged` in
+ * `@ai-matrx/agents/models/react`). No surface keeps a model cache that misses the event.
+ *
+ * The hub lives on `globalThis` so two bundled copies of this module share one set of listeners.
+ */
+/** A `catalog_changed` payload: `{ catalog?: "models" | ..., change?, model_id? }`. */
+type ModelCatalogChangePayload = Record<string, unknown>;
+/** The bus client's subscribe call: `(action, handler) => unsubscribe` (the web's `registerDirectiveHandler`). */
+type ModelCatalogDirectiveSubscribe = (action: "catalog_changed", handler: (payload: ModelCatalogChangePayload) => void) => () => void;
+/** Is this notice about the MODEL catalog? (`catalog` absent or `"models"`; the tool catalog shares the action.) */
+declare function isModelCatalogChange(payload: ModelCatalogChangePayload | null | undefined): boolean;
+/** Listen for model catalog changes. Returns the unsubscribe. */
+declare function onModelCatalogChanged(listener: (payload: ModelCatalogChangePayload) => void): () => void;
+/** How many model catalog changes this page has seen (a React key / effect dependency). */
+declare function modelCatalogRevision(): number;
+/** Announce a model catalog change to every listener (a notice that is not about models is ignored). */
+declare function announceModelCatalogChanged(payload?: ModelCatalogChangePayload): void;
+/** Bind the host's bus client: every `catalog_changed` it delivers reaches every model reader. Returns the unbind. */
+declare function followModelCatalogChanges(subscribe: ModelCatalogDirectiveSubscribe): () => void;
+
+export { type AdminOffering, type AdminPricingBand, type ArtifactUse, type AuditCapabilitiesRecord, CHAT_DEFAULT_MODEL_KNOB, CONTENT_TYPES, type CapabilitiesParseContext, type CatalogKeyColumn, type CatalogKindInput, type CatalogModel, type CatalogTier, type CheapestAdequateOptions, type CompatStatus, type ContentType, type CuratedCatalogClient, type CuratedModel, type CuratedPresentation, type CuratedRows, type CuratedVariant, DEFAULT_CAPABILITIES, type DecidedBy, type DeviceGraphics, type DeviceHardware, type DiscoveryAmbiguity, type DiscoveryArtifact, type DiscoveryMedia, type DiscoveryResult, type DiscoveryRuntime, type DiscoverySource, type DiscoveryVariant, EMPTY_MODEL_RECORDS, EXCLUDED_REVIEW_STATES, FEATURE_BUCKETS, FEATURE_BUCKET_ORDER, FEATURE_KEYS, FILE_TYPE_QUANT, type FeatureBucket, type FeatureBucketMeta, type FeatureKey, type FitCapabilities, GgufError, type GgufHeader, type GgufRead, type GgufTensor, type GroupedFeatures, type HardwareClass, type HardwareClasses, type HeaderFlag, type HeaderJudgement, type HeaderRefusal, INPUT_MODALITIES, INTERACTION_MODES, type Interaction, type InteractionMode, type LocalArtifact, type LocalCatalogClient, type LocalCatalogQuery, type LocalCompatRow, type LocalModel, type LocalModelCatalog, type LocalPresentation, type LocalRuntime, type LocalRuntimeBuild, type LocalVariant, MAX_SUCCESSION_HOPS, MODEL_CATALOG_KINDS, MODEL_FAVORITE_ENTITY_TYPE, type Modality, type ModelCapabilities, type ModelCatalog, type ModelCatalogChangePayload, type ModelCatalogClient, type ModelCatalogConfig, type ModelCatalogDirectiveSubscribe, type ModelCatalogErrorSink, type ModelCatalogPgError, type ModelCatalogPgResult, type ModelCatalogQuery, type ModelCatalogState, type ModelCatalogVariant, type ModelCatalogVariantState, type ModelClassConfig, type ModelClassEntry, type ModelClassIndex, type ModelDiagnosticEntry, type ModelDiagnosticsSink, type ModelFavorites, type ModelFavoritesCache, type ModelFavoritesClient, type ModelFavoritesConfig, type ModelFavoritesErrorSink, type ModelFavoritesState, type ModelFetchScope, type ModelFileHandle, type ModelFit, type ModelIdentityRow, type ModelJson, type ModelLabelSource, type ModelNeed, type ModelOfferingRow, type ModelOption, type ModelOptionWithLifecycle, type ModelRecord, type ModelRecordFetchType, type ModelRecords, type ModelRecordsClient, type ModelRecordsConfig, type ModelRecordsState, type ModelSelectionPurpose, type ModelSetEnv, type ModelSetFacts, type ModelSetValidation, NEW_AGENT_DEFAULT_MODEL_KNOB, type NewAgentModel, type NoSelection, OUTPUT_MODALITIES, type OrderedLike, type PreferredModelChoice, type PreferredModelChoicePorts, type PriceTier, type PricedCatalogModel, type PublicModelClient, type RankOptions, type RankedVariant, type ReadModelCatalogOptions, SERVICE_LABEL, SERVICE_LABEL_PLURAL, type SelectDevice, type Selection, type ShardName, type SuccessionClient, type SuccessionIndex, type SuccessionNode, TOP_TIER_COST_RATING, TOP_TIER_LOCKED_TITLE, type VariantDiscovery, type VariantVerdict, type Want, acceptsTextInstructions, announceModelCatalogChanged, blendedPrice, buildModelClassIndex, buildSuccessionIndex, catalogFingerprint, catalogForApp, catalogKeyColumn, catalogKindOf, cheapestAdequateModel, classConfigKey, collapseTiersByClass, costRatingTier, costRatingWord, createModelCatalog, createModelFavorites, createModelRecords, curatedList, displayOrderOf, favoriteIdsEqual, fetchCuratedModels, findNonCanonicalCapabilityValues, fitsMemory, fitsNeed, fitsThisComputer, followModelCatalogChanges, formatMemoryBytes, fromDiscovery, ggufEngine, ggufFacts, groupFeatures, hardwareClassesOf, hasCompatibleDecisionInteraction, isChatModelCapability, isContentType, isConversationalModelCapability, isDecisionModelCapability, isFeatureKey, isHelperGguf, isInteractionMode, isListedVariant, isLocalModelCatalog, isManagedAgentModelCapability, isModelCatalogChange, isProjectorName, isSupersedable, isTopTierRating, judgeHeaderFacts, mergeAuditRecordIntoCapabilities, missingShards, modelCatalogRevision, modelClassKnobFor, modelClassName, modelClassPinOf, modelDisplayLabel, modelsForSelectionPurpose, normalizeArch, normalizeModel, normalizeModels, normalizeOs, normalizePromptSettings, onModelCatalogChanged, orderCatalogGroups, orderCatalogModels, outputFormatControlKey, parseCapabilities, pickProjector, priceTierRating, quantFromName, rankVariants, readCuratedRows, readGgufHeader, readModelCatalog, readModelIdentities, readPublicModel, reconcileModelFavoriteIds, reportModelDiagnostic, requireCanonicalCapabilities, requiredArtifacts, resetSuccessionLogForTests, resolveLiveModelId, resolveModelMapKnob, resolveNewAgentModelId, resolvePreferredModelChoice, resolveSuccessor, runtimesOnEngine, seesImages, selectActiveModels, selectActiveModelsReady, selectAllModelOptions, selectAllModels, selectAllModelsReady, selectDeprecatedModels, selectDeprecatedModelsReady, selectModelById, selectModelClassConfig, selectModelClassName, selectModelControls, selectModelDetailError, selectModelFetchType, selectModelFullyLoaded, selectModelIdentityById, selectModelIdentityLookupStatus, selectModelLabelById, selectModelLabelWithClass, selectModelNameById, selectModelOptions, selectVariant, serviceCountLabel, setModelDiagnosticsSink, shapeCuratedModels, shardFileName, shardName, speedRatingLabel, speedRatingWord, splitSetProblems, takesInput, toAuditRecord, validateModelSet, variantVerdict, withModelClass };

package/dist/models/index.d.ts

@@ -750,6 +750,41 @@ declare const selectDeprecatedModelsReady: (s: ModelRecordsState) => boolean;
 declare const selectAllModelsReady: (s: ModelRecordsState) => boolean;
 declare const selectModelIdentityById: (s: ModelRecordsState, modelId: string) => ModelIdentityRow | undefined;
 declare const selectModelIdentityLookupStatus: (s: ModelRecordsState, modelId: string) => "loading" | "succeeded" | "failed" | "idle";
+/**
+ * The durable identities (id, name, common_name, is_deprecated) of these models, read from
+ * `ai.model_definition` — the same read `records.loadIdentity` makes. For a process with no records
+ * store that stamps a name ONCE (a sync snapshot); a screen names models through the records hooks.
+ * Rows the database does not return are absent. Throws the database's error.
+ */
+declare function readModelIdentities(client: ModelRecordsClient, modelIds: readonly string[]): Promise<ModelIdentityRow[]>;
+/** The structural read `readPublicModel` needs (a supabase-js client fits it as is). */
+interface PublicModelClient {
+    schema(name: "ai"): {
+        from(table: "model_public"): {
+            select(columns: string): {
+                eq(column: string, value: string): {
+                    maybeSingle(): PromiseLike<{
+                        data: unknown;
+                        error: {
+                            message: string;
+                        } | null;
+                    }>;
+                };
+            };
+        };
+    };
+}
+/**
+ * One `ai.model_public` row (id + canonical name) by id or name, read fresh — for a value sent on the wire at
+ * the moment it is used (a voice session's transcription model), never for a label on screen.
+ */
+declare function readPublicModel(client: PublicModelClient, key: string): Promise<{
+    row: {
+        id?: unknown;
+        name?: unknown;
+    } | null;
+    error: string | null;
+}>;
 
 /**
  * `@ai-matrx/agents/models` — `createModelCatalog`: the headless model catalog store.
@@ -802,6 +837,8 @@ type ModelCatalogErrorSink = (event: {
     context?: object;
 }) => void;
 interface ModelCatalogConfig {
+    /** Re-read on every model catalog change notice (catalog/changes.ts). Default true. */
+    followChanges?: boolean;
     client: ModelCatalogClient;
     /** OPTIONAL — DEFAULT: a tagged `console.error` (the in-picker error banner always renders too). */
     errorSink?: ModelCatalogErrorSink;
@@ -828,6 +865,14 @@ interface ModelCatalog {
     load(variant: ModelCatalogVariant): Promise<void>;
     /** Re-read the variant now (rows stay visible while it runs). Never throws. */
     reload(variant: ModelCatalogVariant): Promise<void>;
+    /**
+     * The catalog changed upstream (`catalog_changed`): re-read every picker variant already read and every
+     * record already read (`records.refresh()`). Called by itself on every `announceModelCatalogChanged`
+     * (catalog/changes.ts) unless `followChanges: false`. Never throws.
+     */
+    refresh(): Promise<void>;
+    /** Stop following `catalog_changed` (a test, or a catalog a host discards). */
+    dispose(): void;
     /**
      * The RECORDS part (agent core B3): options list, full records with resolved controls, class
      * configs, the class index and identities — what chat's retired `modelRegistry` slice held.
@@ -1818,4 +1863,49 @@ catalog?: SuccessionClient): Promise<NewAgentModel>;
  */
 declare function resolveModelMapKnob(value: unknown, catalog: SuccessionClient): Promise<Record<string, string>>;
 
-export { type AdminOffering, type AdminPricingBand, type ArtifactUse, type AuditCapabilitiesRecord, CHAT_DEFAULT_MODEL_KNOB, CONTENT_TYPES, type CapabilitiesParseContext, type CatalogKeyColumn, type CatalogKindInput, type CatalogModel, type CatalogTier, type CheapestAdequateOptions, type CompatStatus, type ContentType, type CuratedCatalogClient, type CuratedModel, type CuratedPresentation, type CuratedRows, type CuratedVariant, DEFAULT_CAPABILITIES, type DecidedBy, type DeviceGraphics, type DeviceHardware, type DiscoveryAmbiguity, type DiscoveryArtifact, type DiscoveryMedia, type DiscoveryResult, type DiscoveryRuntime, type DiscoverySource, type DiscoveryVariant, EMPTY_MODEL_RECORDS, EXCLUDED_REVIEW_STATES, FEATURE_BUCKETS, FEATURE_BUCKET_ORDER, FEATURE_KEYS, FILE_TYPE_QUANT, type FeatureBucket, type FeatureBucketMeta, type FeatureKey, type FitCapabilities, GgufError, type GgufHeader, type GgufRead, type GgufTensor, type GroupedFeatures, type HardwareClass, type HardwareClasses, type HeaderFlag, type HeaderJudgement, type HeaderRefusal, INPUT_MODALITIES, INTERACTION_MODES, type Interaction, type InteractionMode, type LocalArtifact, type LocalCatalogClient, type LocalCatalogQuery, type LocalCompatRow, type LocalModel, type LocalModelCatalog, type LocalPresentation, type LocalRuntime, type LocalRuntimeBuild, type LocalVariant, MAX_SUCCESSION_HOPS, MODEL_CATALOG_KINDS, MODEL_FAVORITE_ENTITY_TYPE, type Modality, type ModelCapabilities, type ModelCatalog, type ModelCatalogClient, type ModelCatalogConfig, type ModelCatalogErrorSink, type ModelCatalogPgError, type ModelCatalogPgResult, type ModelCatalogQuery, type ModelCatalogState, type ModelCatalogVariant, type ModelCatalogVariantState, type ModelClassConfig, type ModelClassEntry, type ModelClassIndex, type ModelDiagnosticEntry, type ModelDiagnosticsSink, type ModelFavorites, type ModelFavoritesCache, type ModelFavoritesClient, type ModelFavoritesConfig, type ModelFavoritesErrorSink, type ModelFavoritesState, type ModelFetchScope, type ModelFileHandle, type ModelFit, type ModelIdentityRow, type ModelJson, type ModelNeed, type ModelOfferingRow, type ModelOption, type ModelOptionWithLifecycle, type ModelRecord, type ModelRecordFetchType, type ModelRecords, type ModelRecordsClient, type ModelRecordsConfig, type ModelRecordsState, type ModelSelectionPurpose, type ModelSetEnv, type ModelSetFacts, type ModelSetValidation, NEW_AGENT_DEFAULT_MODEL_KNOB, type NewAgentModel, type NoSelection, OUTPUT_MODALITIES, type OrderedLike, type PreferredModelChoice, type PreferredModelChoicePorts, type PriceTier, type PricedCatalogModel, type RankOptions, type RankedVariant, type ReadModelCatalogOptions, SERVICE_LABEL, SERVICE_LABEL_PLURAL, type SelectDevice, type Selection, type ShardName, type SuccessionClient, type SuccessionIndex, type SuccessionNode, TOP_TIER_COST_RATING, TOP_TIER_LOCKED_TITLE, type VariantDiscovery, type VariantVerdict, type Want, acceptsTextInstructions, blendedPrice, buildModelClassIndex, buildSuccessionIndex, catalogFingerprint, catalogForApp, catalogKeyColumn, catalogKindOf, cheapestAdequateModel, classConfigKey, collapseTiersByClass, costRatingTier, costRatingWord, createModelCatalog, createModelFavorites, createModelRecords, curatedList, displayOrderOf, favoriteIdsEqual, fetchCuratedModels, findNonCanonicalCapabilityValues, fitsMemory, fitsNeed, fitsThisComputer, formatMemoryBytes, fromDiscovery, ggufEngine, ggufFacts, groupFeatures, hardwareClassesOf, hasCompatibleDecisionInteraction, isChatModelCapability, isContentType, isConversationalModelCapability, isDecisionModelCapability, isFeatureKey, isHelperGguf, isInteractionMode, isListedVariant, isLocalModelCatalog, isManagedAgentModelCapability, isProjectorName, isSupersedable, isTopTierRating, judgeHeaderFacts, mergeAuditRecordIntoCapabilities, missingShards, modelClassKnobFor, modelClassName, modelClassPinOf, modelsForSelectionPurpose, normalizeArch, normalizeModel, normalizeModels, normalizeOs, normalizePromptSettings, orderCatalogGroups, orderCatalogModels, outputFormatControlKey, parseCapabilities, pickProjector, priceTierRating, quantFromName, rankVariants, readCuratedRows, readGgufHeader, readModelCatalog, reconcileModelFavoriteIds, reportModelDiagnostic, requireCanonicalCapabilities, requiredArtifacts, resetSuccessionLogForTests, resolveLiveModelId, resolveModelMapKnob, resolveNewAgentModelId, resolvePreferredModelChoice, resolveSuccessor, runtimesOnEngine, seesImages, selectActiveModels, selectActiveModelsReady, selectAllModelOptions, selectAllModels, selectAllModelsReady, selectDeprecatedModels, selectDeprecatedModelsReady, selectModelById, selectModelClassConfig, selectModelClassName, selectModelControls, selectModelDetailError, selectModelFetchType, selectModelFullyLoaded, selectModelIdentityById, selectModelIdentityLookupStatus, selectModelLabelById, selectModelLabelWithClass, selectModelNameById, selectModelOptions, selectVariant, serviceCountLabel, setModelDiagnosticsSink, shapeCuratedModels, shardFileName, shardName, speedRatingLabel, speedRatingWord, splitSetProblems, takesInput, toAuditRecord, validateModelSet, variantVerdict, withModelClass };
+/**
+ * `@ai-matrx/agents/models` — THE model label formula. Every surface that names a model computes the
+ * name here: the person-facing `common_name`, else the canonical `name`. An empty `common_name` counts
+ * as absent. Pure; the row it is handed must come from the subscribed catalog (records / readModelCatalog),
+ * so a `catalog_changed` notice re-renders it. Guard: `scripts/check-model-catalog-reads.mjs`.
+ */
+/** The two columns a model label is made from (cloud records, identities, local catalog rows). */
+interface ModelLabelSource {
+    common_name?: string | null;
+    name?: string | null;
+}
+/** A row that always has a canonical name always has a label. */
+declare function modelDisplayLabel(row: {
+    common_name?: string | null;
+    name: string;
+}): string;
+declare function modelDisplayLabel(row: ModelLabelSource | null | undefined): string | undefined;
+
+/**
+ * `@ai-matrx/agents/models` — the ONE subscription to `catalog_changed`.
+ *
+ * The server publishes `catalog_changed` on the platform bus for every admin edit and direct SQL write to
+ * the model catalog. A host binds its bus client ONCE with `followModelCatalogChanges(subscribe)` (the web's
+ * directive registry, Matrx 2's IPC forward of the main-process bus); every model catalog
+ * (`createModelCatalog`: picker rows + records) re-reads itself on the notice, and any other reader
+ * subscribes here (`onModelCatalogChanged`, or `useModelCatalogRevision` / `useOnModelCatalogChanged` in
+ * `@ai-matrx/agents/models/react`). No surface keeps a model cache that misses the event.
+ *
+ * The hub lives on `globalThis` so two bundled copies of this module share one set of listeners.
+ */
+/** A `catalog_changed` payload: `{ catalog?: "models" | ..., change?, model_id? }`. */
+type ModelCatalogChangePayload = Record<string, unknown>;
+/** The bus client's subscribe call: `(action, handler) => unsubscribe` (the web's `registerDirectiveHandler`). */
+type ModelCatalogDirectiveSubscribe = (action: "catalog_changed", handler: (payload: ModelCatalogChangePayload) => void) => () => void;
+/** Is this notice about the MODEL catalog? (`catalog` absent or `"models"`; the tool catalog shares the action.) */
+declare function isModelCatalogChange(payload: ModelCatalogChangePayload | null | undefined): boolean;
+/** Listen for model catalog changes. Returns the unsubscribe. */
+declare function onModelCatalogChanged(listener: (payload: ModelCatalogChangePayload) => void): () => void;
+/** How many model catalog changes this page has seen (a React key / effect dependency). */
+declare function modelCatalogRevision(): number;
+/** Announce a model catalog change to every listener (a notice that is not about models is ignored). */
+declare function announceModelCatalogChanged(payload?: ModelCatalogChangePayload): void;
+/** Bind the host's bus client: every `catalog_changed` it delivers reaches every model reader. Returns the unbind. */
+declare function followModelCatalogChanges(subscribe: ModelCatalogDirectiveSubscribe): () => void;
+
+export { type AdminOffering, type AdminPricingBand, type ArtifactUse, type AuditCapabilitiesRecord, CHAT_DEFAULT_MODEL_KNOB, CONTENT_TYPES, type CapabilitiesParseContext, type CatalogKeyColumn, type CatalogKindInput, type CatalogModel, type CatalogTier, type CheapestAdequateOptions, type CompatStatus, type ContentType, type CuratedCatalogClient, type CuratedModel, type CuratedPresentation, type CuratedRows, type CuratedVariant, DEFAULT_CAPABILITIES, type DecidedBy, type DeviceGraphics, type DeviceHardware, type DiscoveryAmbiguity, type DiscoveryArtifact, type DiscoveryMedia, type DiscoveryResult, type DiscoveryRuntime, type DiscoverySource, type DiscoveryVariant, EMPTY_MODEL_RECORDS, EXCLUDED_REVIEW_STATES, FEATURE_BUCKETS, FEATURE_BUCKET_ORDER, FEATURE_KEYS, FILE_TYPE_QUANT, type FeatureBucket, type FeatureBucketMeta, type FeatureKey, type FitCapabilities, GgufError, type GgufHeader, type GgufRead, type GgufTensor, type GroupedFeatures, type HardwareClass, type HardwareClasses, type HeaderFlag, type HeaderJudgement, type HeaderRefusal, INPUT_MODALITIES, INTERACTION_MODES, type Interaction, type InteractionMode, type LocalArtifact, type LocalCatalogClient, type LocalCatalogQuery, type LocalCompatRow, type LocalModel, type LocalModelCatalog, type LocalPresentation, type LocalRuntime, type LocalRuntimeBuild, type LocalVariant, MAX_SUCCESSION_HOPS, MODEL_CATALOG_KINDS, MODEL_FAVORITE_ENTITY_TYPE, type Modality, type ModelCapabilities, type ModelCatalog, type ModelCatalogChangePayload, type ModelCatalogClient, type ModelCatalogConfig, type ModelCatalogDirectiveSubscribe, type ModelCatalogErrorSink, type ModelCatalogPgError, type ModelCatalogPgResult, type ModelCatalogQuery, type ModelCatalogState, type ModelCatalogVariant, type ModelCatalogVariantState, type ModelClassConfig, type ModelClassEntry, type ModelClassIndex, type ModelDiagnosticEntry, type ModelDiagnosticsSink, type ModelFavorites, type ModelFavoritesCache, type ModelFavoritesClient, type ModelFavoritesConfig, type ModelFavoritesErrorSink, type ModelFavoritesState, type ModelFetchScope, type ModelFileHandle, type ModelFit, type ModelIdentityRow, type ModelJson, type ModelLabelSource, type ModelNeed, type ModelOfferingRow, type ModelOption, type ModelOptionWithLifecycle, type ModelRecord, type ModelRecordFetchType, type ModelRecords, type ModelRecordsClient, type ModelRecordsConfig, type ModelRecordsState, type ModelSelectionPurpose, type ModelSetEnv, type ModelSetFacts, type ModelSetValidation, NEW_AGENT_DEFAULT_MODEL_KNOB, type NewAgentModel, type NoSelection, OUTPUT_MODALITIES, type OrderedLike, type PreferredModelChoice, type PreferredModelChoicePorts, type PriceTier, type PricedCatalogModel, type PublicModelClient, type RankOptions, type RankedVariant, type ReadModelCatalogOptions, SERVICE_LABEL, SERVICE_LABEL_PLURAL, type SelectDevice, type Selection, type ShardName, type SuccessionClient, type SuccessionIndex, type SuccessionNode, TOP_TIER_COST_RATING, TOP_TIER_LOCKED_TITLE, type VariantDiscovery, type VariantVerdict, type Want, acceptsTextInstructions, announceModelCatalogChanged, blendedPrice, buildModelClassIndex, buildSuccessionIndex, catalogFingerprint, catalogForApp, catalogKeyColumn, catalogKindOf, cheapestAdequateModel, classConfigKey, collapseTiersByClass, costRatingTier, costRatingWord, createModelCatalog, createModelFavorites, createModelRecords, curatedList, displayOrderOf, favoriteIdsEqual, fetchCuratedModels, findNonCanonicalCapabilityValues, fitsMemory, fitsNeed, fitsThisComputer, followModelCatalogChanges, formatMemoryBytes, fromDiscovery, ggufEngine, ggufFacts, groupFeatures, hardwareClassesOf, hasCompatibleDecisionInteraction, isChatModelCapability, isContentType, isConversationalModelCapability, isDecisionModelCapability, isFeatureKey, isHelperGguf, isInteractionMode, isListedVariant, isLocalModelCatalog, isManagedAgentModelCapability, isModelCatalogChange, isProjectorName, isSupersedable, isTopTierRating, judgeHeaderFacts, mergeAuditRecordIntoCapabilities, missingShards, modelCatalogRevision, modelClassKnobFor, modelClassName, modelClassPinOf, modelDisplayLabel, modelsForSelectionPurpose, normalizeArch, normalizeModel, normalizeModels, normalizeOs, normalizePromptSettings, onModelCatalogChanged, orderCatalogGroups, orderCatalogModels, outputFormatControlKey, parseCapabilities, pickProjector, priceTierRating, quantFromName, rankVariants, readCuratedRows, readGgufHeader, readModelCatalog, readModelIdentities, readPublicModel, reconcileModelFavoriteIds, reportModelDiagnostic, requireCanonicalCapabilities, requiredArtifacts, resetSuccessionLogForTests, resolveLiveModelId, resolveModelMapKnob, resolveNewAgentModelId, resolvePreferredModelChoice, resolveSuccessor, runtimesOnEngine, seesImages, selectActiveModels, selectActiveModelsReady, selectAllModelOptions, selectAllModels, selectAllModelsReady, selectDeprecatedModels, selectDeprecatedModelsReady, selectModelById, selectModelClassConfig, selectModelClassName, selectModelControls, selectModelDetailError, selectModelFetchType, selectModelFullyLoaded, selectModelIdentityById, selectModelIdentityLookupStatus, selectModelLabelById, selectModelLabelWithClass, selectModelNameById, selectModelOptions, selectVariant, serviceCountLabel, setModelDiagnosticsSink, shapeCuratedModels, shardFileName, shardName, speedRatingLabel, speedRatingWord, splitSetProblems, takesInput, toAuditRecord, validateModelSet, variantVerdict, withModelClass };

package/dist/models/index.js

@@ -759,6 +759,48 @@ var OUTPUT_MODALITIES = [
   "decision"
 ];
 
+// models/catalog/changes.ts
+var KEY2 = /* @__PURE__ */ Symbol.for("ai-matrx.agents.model-catalog-changes");
+function hub() {
+  const g = globalThis;
+  return g[KEY2] ??= { listeners: /* @__PURE__ */ new Set(), revision: 0 };
+}
+function isModelCatalogChange(payload) {
+  const catalog = payload?.["catalog"];
+  return catalog === void 0 || catalog === null || catalog === "models";
+}
+function onModelCatalogChanged(listener) {
+  const h = hub();
+  h.listeners.add(listener);
+  return () => {
+    h.listeners.delete(listener);
+  };
+}
+function modelCatalogRevision() {
+  return hub().revision;
+}
+function announceModelCatalogChanged(payload = {}) {
+  if (!isModelCatalogChange(payload)) return;
+  const h = hub();
+  h.revision += 1;
+  for (const l of [...h.listeners]) {
+    try {
+      l(payload);
+    } catch (err) {
+      console.error("[@ai-matrx/agents/models] a catalog_changed listener threw", err);
+    }
+  }
+}
+function followModelCatalogChanges(subscribe) {
+  return subscribe("catalog_changed", (payload) => announceModelCatalogChanged(payload ?? {}));
+}
+
+// models/label.ts
+function modelDisplayLabel(row) {
+  if (!row) return void 0;
+  return row.common_name || row.name || void 0;
+}
+
 // models/catalog/records.ts
 var classConfigKey = (modelId, offeringId) => `${modelId}:${offeringId}`;
 var EMPTY_MODEL_RECORDS = Object.freeze({
@@ -827,7 +869,7 @@ function withIdLists(state2) {
   const active = [];
   const deprecated = [];
   for (const [id, record] of Object.entries(state2.entities)) (record.is_deprecated === true ? deprecated : active).push(id);
-  const label = (id) => state2.entities[id]?.common_name ?? state2.entities[id]?.name ?? "";
+  const label = (id) => modelDisplayLabel(state2.entities[id]) ?? "";
   const sort = (ids) => ids.sort((a, b) => label(a).localeCompare(label(b)));
   return { ...state2, activeIds: sort(active), deprecatedIds: sort(deprecated) };
 }
@@ -1248,13 +1290,13 @@ function selectDeprecatedModels(s3) {
 var allOf = memo((entities) => Object.values(entities));
 var selectAllModels = (s3) => allOf(s3.entities);
 var optionsOf = memo(
-  (models) => models.map((m) => ({ value: m.id, label: m.common_name || m.name || m.id, maker: m.maker, costRating: m.cost_rating, speedRating: m.speed_rating }))
+  (models) => models.map((m) => ({ value: m.id, label: modelDisplayLabel(m) || m.id, maker: m.maker, costRating: m.cost_rating, speedRating: m.speed_rating }))
 );
 var selectModelOptions = (s3) => optionsOf(selectActiveModels(s3));
 var allOptionsOf = memo(
   (entities) => Object.values(entities).map((m) => ({
     value: m.id,
-    label: m.common_name || m.name || m.id,
+    label: modelDisplayLabel(m) || m.id,
     maker: m.maker,
     isDeprecated: m.is_deprecated ?? false,
     isRetired: m.retired_at != null,
@@ -1267,7 +1309,7 @@ function selectModelLabelById(s3, modelId) {
   if (!modelId) return void 0;
   const m = s3.entities[modelId];
   const identity = s3.identityById[modelId];
-  return m?.common_name || m?.name || identity?.common_name || identity?.name || void 0;
+  return modelDisplayLabel(m) || modelDisplayLabel(identity);
 }
 var selectModelNameById = (s3, modelId) => modelId ? s3.entities[modelId]?.name : void 0;
 var selectModelClassName = (s3, modelId, offeringId) => modelClassName(s3.modelClassIndex, modelId, offeringId);
@@ -1285,6 +1327,18 @@ var selectDeprecatedModelsReady = (s3) => (s3.fetchScope === "deprecated" || s3.
 var selectAllModelsReady = (s3) => s3.fetchScope === "all";
 var selectModelIdentityById = (s3, modelId) => s3.identityById[modelId];
 var selectModelIdentityLookupStatus = (s3, modelId) => s3.identityStatusById[modelId] ?? "idle";
+async function readModelIdentities(client, modelIds) {
+  const ids = [...new Set(modelIds.filter(Boolean))];
+  if (ids.length === 0) return [];
+  const { data, error } = await client.schema("ai").from("model_definition").select("id, name, common_name, is_deprecated").in("id", ids);
+  if (error) throw new Error(error.message);
+  return Array.isArray(data) ? data : [];
+}
+async function readPublicModel(client, key) {
+  const { data, error } = await client.schema("ai").from("model_public").select("id, name").eq(catalogKeyColumn(key), key.trim()).maybeSingle();
+  if (error) return { row: null, error: error.message };
+  return { row: data ?? null, error: null };
+}
 
 // models/catalog/store.ts
 var IDLE = { status: "idle", models: [], error: null, loadedAt: null };
@@ -1554,8 +1608,16 @@ function createModelCatalog(config) {
     errorSink,
     ...config.isSignedIn ? { isSignedIn: config.isSignedIn } : {}
   });
+  const refresh = async () => {
+    const variants = Object.keys(state2).filter((v) => state2[v].status !== "idle");
+    await Promise.all([records.refresh(), ...variants.map((v) => run(v))]);
+  };
+  const stopFollowing = config.followChanges === false ? () => {
+  } : onModelCatalogChanged(() => void refresh());
   return {
     records,
+    refresh,
+    dispose: stopFollowing,
     getState: () => state2,
     subscribe(listener) {
       listeners.add(listener);
@@ -2771,6 +2833,7 @@ export {
   TOP_TIER_COST_RATING,
   TOP_TIER_LOCKED_TITLE,
   acceptsTextInstructions,
+  announceModelCatalogChanged,
   blendedPrice,
   buildModelClassIndex,
   buildSuccessionIndex,
@@ -2794,6 +2857,7 @@ export {
   fitsMemory,
   fitsNeed,
   fitsThisComputer,
+  followModelCatalogChanges,
   formatMemoryBytes,
   fromDiscovery,
   ggufEngine,
@@ -2811,21 +2875,25 @@ export {
   isListedVariant,
   isLocalModelCatalog,
   isManagedAgentModelCapability,
+  isModelCatalogChange,
   isProjectorName,
   isSupersedable,
   isTopTierRating,
   judgeHeaderFacts,
   mergeAuditRecordIntoCapabilities,
   missingShards,
+  modelCatalogRevision,
   modelClassKnobFor,
   modelClassName,
   modelClassPinOf,
+  modelDisplayLabel,
   modelsForSelectionPurpose,
   normalizeArch,
   normalizeModel,
   normalizeModels,
   normalizeOs,
   normalizePromptSettings,
+  onModelCatalogChanged,
   orderCatalogGroups,
   orderCatalogModels,
   outputFormatControlKey,
@@ -2837,6 +2905,8 @@ export {
   readCuratedRows,
   readGgufHeader,
   readModelCatalog,
+  readModelIdentities,
+  readPublicModel,
   reconcileModelFavoriteIds,
   reportModelDiagnostic,
   requireCanonicalCapabilities,

package/dist/models/react/index.cjs

@@ -29,10 +29,12 @@ __export(react_exports, {
   useLocalModels: () => useLocalModels,
   useModelAccess: () => useModelAccess,
   useModelCatalog: () => useModelCatalog,
+  useModelCatalogRevision: () => useModelCatalogRevision,
   useModelCatalogStore: () => useModelCatalogStore,
   useModelCatalogUiPorts: () => useModelCatalogUiPorts,
   useModelFavorites: () => useModelFavorites,
-  useModelRecordsSelector: () => useModelRecordsSelector
+  useModelRecordsSelector: () => useModelRecordsSelector,
+  useOnModelCatalogChanged: () => useOnModelCatalogChanged
 });
 module.exports = __toCommonJS(react_exports);
 
@@ -2289,6 +2291,25 @@ function ModelListDropdown({
 
 // models/react/records.ts
 var import_react3 = require("react");
+
+// models/catalog/changes.ts
+var KEY = /* @__PURE__ */ Symbol.for("ai-matrx.agents.model-catalog-changes");
+function hub() {
+  const g = globalThis;
+  return g[KEY] ??= { listeners: /* @__PURE__ */ new Set(), revision: 0 };
+}
+function onModelCatalogChanged(listener) {
+  const h = hub();
+  h.listeners.add(listener);
+  return () => {
+    h.listeners.delete(listener);
+  };
+}
+function modelCatalogRevision() {
+  return hub().revision;
+}
+
+// models/react/records.ts
 function useModelRecordsSelector(records, select) {
   return (0, import_react3.useSyncExternalStore)(
     records.subscribe,
@@ -2296,6 +2317,15 @@ function useModelRecordsSelector(records, select) {
     () => select(records.getState())
   );
 }
+var subscribeRevision = (listener) => onModelCatalogChanged(() => listener());
+function useModelCatalogRevision() {
+  return (0, import_react3.useSyncExternalStore)(subscribeRevision, modelCatalogRevision, modelCatalogRevision);
+}
+function useOnModelCatalogChanged(onChange) {
+  const latest = (0, import_react3.useRef)(onChange);
+  latest.current = onChange;
+  (0, import_react3.useEffect)(() => onModelCatalogChanged((payload) => latest.current(payload)), []);
+}
 
 // models/react/ModelDiscovery.tsx
 var import_format3 = require("@ai-matrx/kit/format");