@ai-matrx/agents 0.59.270 → 0.59.271

package/CHANGELOG.md

@@ -1,10 +1,15 @@
 # Changelog
 
-## 0.59.270
+## 0.59.271
 
 UNVERIFIED: this release has no Unreleased entry and the source comparison could not be made (the caller supplied no source comparison). Whether source changed is unknown; consumer action is unknown.
 Check the package's gitHead on npm against this version's gitHead: `git diff <previous gitHead> <this gitHead> -- apps/shared/matrx-agents/src`.
 
+## 0.59.270
+
+Automatic changed-only republish (docs/metadata drift since the last published version; verified: `git diff 4c08cba6c4 8a4ed656ea -- apps/shared/matrx-agents/src`
+has no shipped-source changes outside tests, fixtures and docs). No consumer action required.
+
 ## 0.59.269
 
 Automatic changed-only republish (docs/metadata drift since the last published version; verified: `git diff 5b7c48a99c 4c08cba6c4 -- apps/shared/matrx-agents/src`

package/dist/models/index.cjs

@@ -74,6 +74,7 @@ __export(models_exports, {
   fitsNeed: () => fitsNeed,
   fitsThisComputer: () => fitsThisComputer,
   followModelCatalogChanges: () => followModelCatalogChanges,
+  followModelCatalogVisibility: () => followModelCatalogVisibility,
   formatMemoryBytes: () => formatMemoryBytes,
   fromDiscovery: () => fromDiscovery,
   ggufEngine: () => ggufEngine,
@@ -122,6 +123,7 @@ __export(models_exports, {
   readDeviceModelFiles: () => readDeviceModelFiles,
   readGgufHeader: () => readGgufHeader,
   readModelCatalog: () => readModelCatalog,
+  readModelCatalogStamp: () => readModelCatalogStamp,
   readModelIdentities: () => readModelIdentities,
   readPublicModel: () => readPublicModel,
   reconcileModelFavoriteIds: () => reconcileModelFavoriteIds,
@@ -937,42 +939,6 @@ 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;
@@ -1564,6 +1530,102 @@ async function readPublicModel(client, key) {
   if (error) return { row: null, error: error.message };
   return { row: data ?? null, error: null };
 }
+async function readModelCatalogStamp(client) {
+  const q = client.schema("ai").from("model_definition").select("updated_at").order("updated_at", { ascending: false, nullsFirst: false });
+  if (!q.limit) throw new Error("readModelCatalogStamp: the client has no .limit() (a supabase-js client does)");
+  const { data, error } = await q.limit(1).maybeSingle();
+  if (error) throw new Error(error.message);
+  const stamp = data?.updated_at;
+  return typeof stamp === "string" ? stamp : null;
+}
+
+// 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 ?? {}));
+}
+function followModelCatalogVisibility(options) {
+  const page = options.page ?? (typeof document !== "undefined" && typeof window !== "undefined" ? { document, window } : null);
+  if (!page) return () => {
+  };
+  const minIntervalMs = options.minIntervalMs ?? 2e4;
+  const now = options.now ?? (() => Date.now());
+  const sink = options.errorSink ?? ((e) => {
+    console.error(`[@ai-matrx/agents/models] ${e.code}: ${e.message}`);
+  });
+  let baseline;
+  let inFlight = null;
+  let lastShownRead = -Infinity;
+  const stamp = () => inFlight ??= readModelCatalogStamp(options.client).finally(() => {
+    inFlight = null;
+  });
+  const fail = (err) => sink({ code: "model-catalog-stamp-failed", message: err instanceof Error ? err.message : String(err) });
+  const learnBaseline = () => {
+    if (baseline !== void 0) return;
+    void stamp().then((s4) => {
+      if (baseline === void 0) baseline = s4;
+    }, fail);
+  };
+  const onHidden = () => {
+    if (page.document.visibilityState === "hidden") learnBaseline();
+  };
+  const onShown = () => {
+    if (page.document.visibilityState === "hidden") return;
+    const t = now();
+    if (t - lastShownRead < minIntervalMs) return;
+    lastShownRead = t;
+    const known = baseline;
+    if (known === void 0) return learnBaseline();
+    void stamp().then((s4) => {
+      if (s4 === known) return;
+      baseline = s4;
+      announceModelCatalogChanged({ catalog: "models", change: "catch_up_visible" });
+    }, fail);
+  };
+  const offChanges = onModelCatalogChanged(() => {
+    baseline = void 0;
+    if (page.document.visibilityState === "hidden") learnBaseline();
+  });
+  const onVisibility = () => page.document.visibilityState === "hidden" ? onHidden() : onShown();
+  page.document.addEventListener("visibilitychange", onVisibility);
+  page.window.addEventListener("focus", onShown);
+  if (page.document.visibilityState === "hidden") learnBaseline();
+  return () => {
+    offChanges();
+    page.document.removeEventListener("visibilitychange", onVisibility);
+    page.window.removeEventListener("focus", onShown);
+  };
+}
 
 // models/catalog/store.ts
 var IDLE = { status: "idle", models: [], error: null, loadedAt: null };

package/dist/models/index.d.cts

@@ -641,6 +641,8 @@ interface RecordsQuery extends PromiseLike<PgResult> {
         nullsFirst?: boolean;
     }): RecordsQuery;
     maybeSingle(): PromiseLike<PgResult>;
+    /** Only the catalog stamp (`readModelCatalogStamp`) uses it. */
+    limit?(count: number): RecordsQuery;
 }
 interface ModelRecordsClient {
     schema(name: string): {
@@ -791,6 +793,12 @@ declare function readPublicModel(client: PublicModelClient, key: string): Promis
     } | null;
     error: string | null;
 }>;
+/**
+ * THE catalog stamp: the newest `ai.model_definition.updated_at` (one row, one column) — the cheap read a
+ * tab makes to learn whether the catalog changed while it was not listening (catalog/changes.ts
+ * `followModelCatalogVisibility`). Null when the catalog is empty. Throws the database's error.
+ */
+declare function readModelCatalogStamp(client: ModelRecordsClient): Promise<string | null>;
 
 /**
  * `@ai-matrx/agents/models` — `createModelCatalog`: the headless model catalog store.
@@ -2032,7 +2040,12 @@ declare function modelDisplayLabel(row: ModelLabelSource | null | undefined): st
  * `@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 tab that is not listening (the bus room not joined yet, or asleep) catches up when it comes to the
+ * front: `followModelCatalogVisibility({ client })` reads the catalog stamp when the tab hides and again
+ * when it shows or takes focus (throttled), and announces a change when the stamp moved.
  */
+
 /** 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`). */
@@ -2047,6 +2060,32 @@ declare function modelCatalogRevision(): number;
 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;
+interface ModelCatalogVisibilityOptions {
+    /** The client the stamp is read with (supabase-js fits as is). */
+    client: ModelRecordsClient;
+    /** At most one stamp read per this many ms when the tab shows / takes focus. Default 20 s. */
+    minIntervalMs?: number;
+    /** The page (tests pass a double); defaults to the global `document` / `window`. */
+    page?: {
+        document: Pick<Document, "visibilityState" | "addEventListener" | "removeEventListener">;
+        window: Pick<Window, "addEventListener" | "removeEventListener">;
+    };
+    /** Where a failed stamp read is said. Default: console.error, tagged. */
+    errorSink?: (event: {
+        code: string;
+        message: string;
+    }) => void;
+    now?: () => number;
+}
+/**
+ * When the tab shows or takes focus, read the catalog stamp (one row) and, when it moved since the tab
+ * last knew it, announce a model catalog change through the SAME door as the bus (every catalog re-reads
+ * what it read; every reader following `onModelCatalogChanged` re-reads). The baseline is taken when the
+ * tab hides (or at bind when it starts hidden), and refreshed by every announced change. Reads already in
+ * flight are joined; shows/focuses within `minIntervalMs` share the last read. Returns the unbind. No-op
+ * where there is no document (a server render, a worker).
+ */
+declare function followModelCatalogVisibility(options: ModelCatalogVisibilityOptions): () => void;
 
-export { CHAT_DEFAULT_MODEL_KNOB, CONTENT_TYPES, DEFAULT_CAPABILITIES, DEVICE_FILE_USABLE_STATES, DEVICE_OWN_FILE_USABLE_STATES, DEVICE_RULE_TWIN_FIXTURE, DEVICE_SERVED_SETTINGS_KEY, DEVICE_SERVED_VIA, DeviceModelUnavailableError, EMPTY_MODEL_RECORDS, EXCLUDED_REVIEW_STATES, FEATURE_BUCKETS, FEATURE_BUCKET_ORDER, FEATURE_KEYS, FILE_TYPE_QUANT, GgufError, INPUT_MODALITIES, INTERACTION_MODES, MAX_SUCCESSION_HOPS, MODEL_CATALOG_KINDS, MODEL_FAVORITE_ENTITY_TYPE, NEW_AGENT_DEFAULT_MODEL_KNOB, OUTPUT_MODALITIES, SERVICE_LABEL, SERVICE_LABEL_PLURAL, TOP_TIER_COST_RATING, TOP_TIER_LOCKED_TITLE, acceptsTextInstructions, announceModelCatalogChanged, availableOnDevices, 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, readDeviceModelFiles, readGgufHeader, readModelCatalog, readModelIdentities, readPublicModel, reconcileModelFavoriteIds, reportModelDiagnostic, requireCanonicalCapabilities, requiredArtifactIds, requiredArtifacts, resetSuccessionLogForTests, resolveDeviceModel, 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, toDeviceModelFile, validateModelSet, variantVerdict, withModelClass };
-export type { AdminOffering, AdminPricingBand, ArtifactUse, AuditCapabilitiesRecord, AvailabilityVariant, CapabilitiesParseContext, CatalogKeyColumn, CatalogKindInput, CatalogModel, CatalogTier, CheapestAdequateOptions, CompatStatus, ContentType, CuratedCatalogClient, CuratedModel, CuratedPresentation, CuratedRows, CuratedVariant, DecidedBy, DeviceAvailability, DeviceGraphics, DeviceHardware, DeviceModelFile, DeviceModelResolution, DeviceServedSettings, DiscoveryAmbiguity, DiscoveryArtifact, DiscoveryMedia, DiscoveryResult, DiscoveryRuntime, DiscoverySource, DiscoveryVariant, FeatureBucket, FeatureBucketMeta, FeatureKey, FitCapabilities, GgufHeader, GgufRead, GgufTensor, GroupedFeatures, HardwareClass, HardwareClasses, HeaderFlag, HeaderJudgement, HeaderRefusal, Interaction, InteractionMode, LocalArtifact, LocalCatalogClient, LocalCatalogQuery, LocalCompatRow, LocalModel, LocalModelCatalog, LocalPresentation, LocalRuntime, LocalRuntimeBuild, LocalVariant, Modality, ModelCapabilities, ModelCatalog, ModelCatalogChangePayload, ModelCatalogClient, ModelCatalogConfig, ModelCatalogDirectiveSubscribe, ModelCatalogErrorSink, ModelCatalogPgError, ModelCatalogPgResult, ModelCatalogQuery, ModelCatalogState, ModelCatalogVariant, ModelCatalogVariantState, ModelClassConfig, ModelClassEntry, ModelClassIndex, ModelDiagnosticEntry, ModelDiagnosticsSink, ModelFavorites, ModelFavoritesCache, ModelFavoritesClient, ModelFavoritesConfig, ModelFavoritesErrorSink, ModelFavoritesState, ModelFetchScope, ModelFileHandle, ModelFit, ModelIdentityRow, ModelJson, ModelLabelSource, ModelNeed, ModelOfferingRow, ModelOption, ModelOptionWithLifecycle, ModelRecord, ModelRecordFetchType, ModelRecords, ModelRecordsClient, ModelRecordsConfig, ModelRecordsState, ModelSelectionPurpose, ModelSetEnv, ModelSetFacts, ModelSetValidation, NewAgentModel, NoSelection, OrderedLike, PreferredModelChoice, PreferredModelChoicePorts, PriceTier, PricedCatalogModel, PublicModelClient, RankOptions, RankedVariant, ReadModelCatalogOptions, SelectDevice, Selection, ShardName, SuccessionClient, SuccessionIndex, SuccessionNode, VariantDiscovery, VariantVerdict, Want };
+export { CHAT_DEFAULT_MODEL_KNOB, CONTENT_TYPES, DEFAULT_CAPABILITIES, DEVICE_FILE_USABLE_STATES, DEVICE_OWN_FILE_USABLE_STATES, DEVICE_RULE_TWIN_FIXTURE, DEVICE_SERVED_SETTINGS_KEY, DEVICE_SERVED_VIA, DeviceModelUnavailableError, EMPTY_MODEL_RECORDS, EXCLUDED_REVIEW_STATES, FEATURE_BUCKETS, FEATURE_BUCKET_ORDER, FEATURE_KEYS, FILE_TYPE_QUANT, GgufError, INPUT_MODALITIES, INTERACTION_MODES, MAX_SUCCESSION_HOPS, MODEL_CATALOG_KINDS, MODEL_FAVORITE_ENTITY_TYPE, NEW_AGENT_DEFAULT_MODEL_KNOB, OUTPUT_MODALITIES, SERVICE_LABEL, SERVICE_LABEL_PLURAL, TOP_TIER_COST_RATING, TOP_TIER_LOCKED_TITLE, acceptsTextInstructions, announceModelCatalogChanged, availableOnDevices, blendedPrice, buildModelClassIndex, buildSuccessionIndex, catalogFingerprint, catalogForApp, catalogKeyColumn, catalogKindOf, cheapestAdequateModel, classConfigKey, collapseTiersByClass, costRatingTier, costRatingWord, createModelCatalog, createModelFavorites, createModelRecords, curatedList, displayOrderOf, favoriteIdsEqual, fetchCuratedModels, findNonCanonicalCapabilityValues, fitsMemory, fitsNeed, fitsThisComputer, followModelCatalogChanges, followModelCatalogVisibility, 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, readDeviceModelFiles, readGgufHeader, readModelCatalog, readModelCatalogStamp, readModelIdentities, readPublicModel, reconcileModelFavoriteIds, reportModelDiagnostic, requireCanonicalCapabilities, requiredArtifactIds, requiredArtifacts, resetSuccessionLogForTests, resolveDeviceModel, 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, toDeviceModelFile, validateModelSet, variantVerdict, withModelClass };
+export type { AdminOffering, AdminPricingBand, ArtifactUse, AuditCapabilitiesRecord, AvailabilityVariant, CapabilitiesParseContext, CatalogKeyColumn, CatalogKindInput, CatalogModel, CatalogTier, CheapestAdequateOptions, CompatStatus, ContentType, CuratedCatalogClient, CuratedModel, CuratedPresentation, CuratedRows, CuratedVariant, DecidedBy, DeviceAvailability, DeviceGraphics, DeviceHardware, DeviceModelFile, DeviceModelResolution, DeviceServedSettings, DiscoveryAmbiguity, DiscoveryArtifact, DiscoveryMedia, DiscoveryResult, DiscoveryRuntime, DiscoverySource, DiscoveryVariant, FeatureBucket, FeatureBucketMeta, FeatureKey, FitCapabilities, GgufHeader, GgufRead, GgufTensor, GroupedFeatures, HardwareClass, HardwareClasses, HeaderFlag, HeaderJudgement, HeaderRefusal, Interaction, InteractionMode, LocalArtifact, LocalCatalogClient, LocalCatalogQuery, LocalCompatRow, LocalModel, LocalModelCatalog, LocalPresentation, LocalRuntime, LocalRuntimeBuild, LocalVariant, Modality, ModelCapabilities, ModelCatalog, ModelCatalogChangePayload, ModelCatalogClient, ModelCatalogConfig, ModelCatalogDirectiveSubscribe, ModelCatalogErrorSink, ModelCatalogPgError, ModelCatalogPgResult, ModelCatalogQuery, ModelCatalogState, ModelCatalogVariant, ModelCatalogVariantState, ModelCatalogVisibilityOptions, ModelClassConfig, ModelClassEntry, ModelClassIndex, ModelDiagnosticEntry, ModelDiagnosticsSink, ModelFavorites, ModelFavoritesCache, ModelFavoritesClient, ModelFavoritesConfig, ModelFavoritesErrorSink, ModelFavoritesState, ModelFetchScope, ModelFileHandle, ModelFit, ModelIdentityRow, ModelJson, ModelLabelSource, ModelNeed, ModelOfferingRow, ModelOption, ModelOptionWithLifecycle, ModelRecord, ModelRecordFetchType, ModelRecords, ModelRecordsClient, ModelRecordsConfig, ModelRecordsState, ModelSelectionPurpose, ModelSetEnv, ModelSetFacts, ModelSetValidation, NewAgentModel, NoSelection, OrderedLike, PreferredModelChoice, PreferredModelChoicePorts, PriceTier, PricedCatalogModel, PublicModelClient, RankOptions, RankedVariant, ReadModelCatalogOptions, SelectDevice, Selection, ShardName, SuccessionClient, SuccessionIndex, SuccessionNode, VariantDiscovery, VariantVerdict, Want };

package/dist/models/index.d.ts

@@ -641,6 +641,8 @@ interface RecordsQuery extends PromiseLike<PgResult> {
         nullsFirst?: boolean;
     }): RecordsQuery;
     maybeSingle(): PromiseLike<PgResult>;
+    /** Only the catalog stamp (`readModelCatalogStamp`) uses it. */
+    limit?(count: number): RecordsQuery;
 }
 interface ModelRecordsClient {
     schema(name: string): {
@@ -791,6 +793,12 @@ declare function readPublicModel(client: PublicModelClient, key: string): Promis
     } | null;
     error: string | null;
 }>;
+/**
+ * THE catalog stamp: the newest `ai.model_definition.updated_at` (one row, one column) — the cheap read a
+ * tab makes to learn whether the catalog changed while it was not listening (catalog/changes.ts
+ * `followModelCatalogVisibility`). Null when the catalog is empty. Throws the database's error.
+ */
+declare function readModelCatalogStamp(client: ModelRecordsClient): Promise<string | null>;
 
 /**
  * `@ai-matrx/agents/models` — `createModelCatalog`: the headless model catalog store.
@@ -2032,7 +2040,12 @@ declare function modelDisplayLabel(row: ModelLabelSource | null | undefined): st
  * `@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 tab that is not listening (the bus room not joined yet, or asleep) catches up when it comes to the
+ * front: `followModelCatalogVisibility({ client })` reads the catalog stamp when the tab hides and again
+ * when it shows or takes focus (throttled), and announces a change when the stamp moved.
  */
+
 /** 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`). */
@@ -2047,6 +2060,32 @@ declare function modelCatalogRevision(): number;
 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;
+interface ModelCatalogVisibilityOptions {
+    /** The client the stamp is read with (supabase-js fits as is). */
+    client: ModelRecordsClient;
+    /** At most one stamp read per this many ms when the tab shows / takes focus. Default 20 s. */
+    minIntervalMs?: number;
+    /** The page (tests pass a double); defaults to the global `document` / `window`. */
+    page?: {
+        document: Pick<Document, "visibilityState" | "addEventListener" | "removeEventListener">;
+        window: Pick<Window, "addEventListener" | "removeEventListener">;
+    };
+    /** Where a failed stamp read is said. Default: console.error, tagged. */
+    errorSink?: (event: {
+        code: string;
+        message: string;
+    }) => void;
+    now?: () => number;
+}
+/**
+ * When the tab shows or takes focus, read the catalog stamp (one row) and, when it moved since the tab
+ * last knew it, announce a model catalog change through the SAME door as the bus (every catalog re-reads
+ * what it read; every reader following `onModelCatalogChanged` re-reads). The baseline is taken when the
+ * tab hides (or at bind when it starts hidden), and refreshed by every announced change. Reads already in
+ * flight are joined; shows/focuses within `minIntervalMs` share the last read. Returns the unbind. No-op
+ * where there is no document (a server render, a worker).
+ */
+declare function followModelCatalogVisibility(options: ModelCatalogVisibilityOptions): () => void;
 
-export { CHAT_DEFAULT_MODEL_KNOB, CONTENT_TYPES, DEFAULT_CAPABILITIES, DEVICE_FILE_USABLE_STATES, DEVICE_OWN_FILE_USABLE_STATES, DEVICE_RULE_TWIN_FIXTURE, DEVICE_SERVED_SETTINGS_KEY, DEVICE_SERVED_VIA, DeviceModelUnavailableError, EMPTY_MODEL_RECORDS, EXCLUDED_REVIEW_STATES, FEATURE_BUCKETS, FEATURE_BUCKET_ORDER, FEATURE_KEYS, FILE_TYPE_QUANT, GgufError, INPUT_MODALITIES, INTERACTION_MODES, MAX_SUCCESSION_HOPS, MODEL_CATALOG_KINDS, MODEL_FAVORITE_ENTITY_TYPE, NEW_AGENT_DEFAULT_MODEL_KNOB, OUTPUT_MODALITIES, SERVICE_LABEL, SERVICE_LABEL_PLURAL, TOP_TIER_COST_RATING, TOP_TIER_LOCKED_TITLE, acceptsTextInstructions, announceModelCatalogChanged, availableOnDevices, 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, readDeviceModelFiles, readGgufHeader, readModelCatalog, readModelIdentities, readPublicModel, reconcileModelFavoriteIds, reportModelDiagnostic, requireCanonicalCapabilities, requiredArtifactIds, requiredArtifacts, resetSuccessionLogForTests, resolveDeviceModel, 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, toDeviceModelFile, validateModelSet, variantVerdict, withModelClass };
-export type { AdminOffering, AdminPricingBand, ArtifactUse, AuditCapabilitiesRecord, AvailabilityVariant, CapabilitiesParseContext, CatalogKeyColumn, CatalogKindInput, CatalogModel, CatalogTier, CheapestAdequateOptions, CompatStatus, ContentType, CuratedCatalogClient, CuratedModel, CuratedPresentation, CuratedRows, CuratedVariant, DecidedBy, DeviceAvailability, DeviceGraphics, DeviceHardware, DeviceModelFile, DeviceModelResolution, DeviceServedSettings, DiscoveryAmbiguity, DiscoveryArtifact, DiscoveryMedia, DiscoveryResult, DiscoveryRuntime, DiscoverySource, DiscoveryVariant, FeatureBucket, FeatureBucketMeta, FeatureKey, FitCapabilities, GgufHeader, GgufRead, GgufTensor, GroupedFeatures, HardwareClass, HardwareClasses, HeaderFlag, HeaderJudgement, HeaderRefusal, Interaction, InteractionMode, LocalArtifact, LocalCatalogClient, LocalCatalogQuery, LocalCompatRow, LocalModel, LocalModelCatalog, LocalPresentation, LocalRuntime, LocalRuntimeBuild, LocalVariant, Modality, ModelCapabilities, ModelCatalog, ModelCatalogChangePayload, ModelCatalogClient, ModelCatalogConfig, ModelCatalogDirectiveSubscribe, ModelCatalogErrorSink, ModelCatalogPgError, ModelCatalogPgResult, ModelCatalogQuery, ModelCatalogState, ModelCatalogVariant, ModelCatalogVariantState, ModelClassConfig, ModelClassEntry, ModelClassIndex, ModelDiagnosticEntry, ModelDiagnosticsSink, ModelFavorites, ModelFavoritesCache, ModelFavoritesClient, ModelFavoritesConfig, ModelFavoritesErrorSink, ModelFavoritesState, ModelFetchScope, ModelFileHandle, ModelFit, ModelIdentityRow, ModelJson, ModelLabelSource, ModelNeed, ModelOfferingRow, ModelOption, ModelOptionWithLifecycle, ModelRecord, ModelRecordFetchType, ModelRecords, ModelRecordsClient, ModelRecordsConfig, ModelRecordsState, ModelSelectionPurpose, ModelSetEnv, ModelSetFacts, ModelSetValidation, NewAgentModel, NoSelection, OrderedLike, PreferredModelChoice, PreferredModelChoicePorts, PriceTier, PricedCatalogModel, PublicModelClient, RankOptions, RankedVariant, ReadModelCatalogOptions, SelectDevice, Selection, ShardName, SuccessionClient, SuccessionIndex, SuccessionNode, VariantDiscovery, VariantVerdict, Want };
+export { CHAT_DEFAULT_MODEL_KNOB, CONTENT_TYPES, DEFAULT_CAPABILITIES, DEVICE_FILE_USABLE_STATES, DEVICE_OWN_FILE_USABLE_STATES, DEVICE_RULE_TWIN_FIXTURE, DEVICE_SERVED_SETTINGS_KEY, DEVICE_SERVED_VIA, DeviceModelUnavailableError, EMPTY_MODEL_RECORDS, EXCLUDED_REVIEW_STATES, FEATURE_BUCKETS, FEATURE_BUCKET_ORDER, FEATURE_KEYS, FILE_TYPE_QUANT, GgufError, INPUT_MODALITIES, INTERACTION_MODES, MAX_SUCCESSION_HOPS, MODEL_CATALOG_KINDS, MODEL_FAVORITE_ENTITY_TYPE, NEW_AGENT_DEFAULT_MODEL_KNOB, OUTPUT_MODALITIES, SERVICE_LABEL, SERVICE_LABEL_PLURAL, TOP_TIER_COST_RATING, TOP_TIER_LOCKED_TITLE, acceptsTextInstructions, announceModelCatalogChanged, availableOnDevices, blendedPrice, buildModelClassIndex, buildSuccessionIndex, catalogFingerprint, catalogForApp, catalogKeyColumn, catalogKindOf, cheapestAdequateModel, classConfigKey, collapseTiersByClass, costRatingTier, costRatingWord, createModelCatalog, createModelFavorites, createModelRecords, curatedList, displayOrderOf, favoriteIdsEqual, fetchCuratedModels, findNonCanonicalCapabilityValues, fitsMemory, fitsNeed, fitsThisComputer, followModelCatalogChanges, followModelCatalogVisibility, 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, readDeviceModelFiles, readGgufHeader, readModelCatalog, readModelCatalogStamp, readModelIdentities, readPublicModel, reconcileModelFavoriteIds, reportModelDiagnostic, requireCanonicalCapabilities, requiredArtifactIds, requiredArtifacts, resetSuccessionLogForTests, resolveDeviceModel, 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, toDeviceModelFile, validateModelSet, variantVerdict, withModelClass };
+export type { AdminOffering, AdminPricingBand, ArtifactUse, AuditCapabilitiesRecord, AvailabilityVariant, CapabilitiesParseContext, CatalogKeyColumn, CatalogKindInput, CatalogModel, CatalogTier, CheapestAdequateOptions, CompatStatus, ContentType, CuratedCatalogClient, CuratedModel, CuratedPresentation, CuratedRows, CuratedVariant, DecidedBy, DeviceAvailability, DeviceGraphics, DeviceHardware, DeviceModelFile, DeviceModelResolution, DeviceServedSettings, DiscoveryAmbiguity, DiscoveryArtifact, DiscoveryMedia, DiscoveryResult, DiscoveryRuntime, DiscoverySource, DiscoveryVariant, FeatureBucket, FeatureBucketMeta, FeatureKey, FitCapabilities, GgufHeader, GgufRead, GgufTensor, GroupedFeatures, HardwareClass, HardwareClasses, HeaderFlag, HeaderJudgement, HeaderRefusal, Interaction, InteractionMode, LocalArtifact, LocalCatalogClient, LocalCatalogQuery, LocalCompatRow, LocalModel, LocalModelCatalog, LocalPresentation, LocalRuntime, LocalRuntimeBuild, LocalVariant, Modality, ModelCapabilities, ModelCatalog, ModelCatalogChangePayload, ModelCatalogClient, ModelCatalogConfig, ModelCatalogDirectiveSubscribe, ModelCatalogErrorSink, ModelCatalogPgError, ModelCatalogPgResult, ModelCatalogQuery, ModelCatalogState, ModelCatalogVariant, ModelCatalogVariantState, ModelCatalogVisibilityOptions, ModelClassConfig, ModelClassEntry, ModelClassIndex, ModelDiagnosticEntry, ModelDiagnosticsSink, ModelFavorites, ModelFavoritesCache, ModelFavoritesClient, ModelFavoritesConfig, ModelFavoritesErrorSink, ModelFavoritesState, ModelFetchScope, ModelFileHandle, ModelFit, ModelIdentityRow, ModelJson, ModelLabelSource, ModelNeed, ModelOfferingRow, ModelOption, ModelOptionWithLifecycle, ModelRecord, ModelRecordFetchType, ModelRecords, ModelRecordsClient, ModelRecordsConfig, ModelRecordsState, ModelSelectionPurpose, ModelSetEnv, ModelSetFacts, ModelSetValidation, NewAgentModel, NoSelection, OrderedLike, PreferredModelChoice, PreferredModelChoicePorts, PriceTier, PricedCatalogModel, PublicModelClient, RankOptions, RankedVariant, ReadModelCatalogOptions, SelectDevice, Selection, ShardName, SuccessionClient, SuccessionIndex, SuccessionNode, VariantDiscovery, VariantVerdict, Want };

package/dist/models/index.js

@@ -759,42 +759,6 @@ 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;
@@ -1386,6 +1350,102 @@ async function readPublicModel(client, key) {
   if (error) return { row: null, error: error.message };
   return { row: data ?? null, error: null };
 }
+async function readModelCatalogStamp(client) {
+  const q = client.schema("ai").from("model_definition").select("updated_at").order("updated_at", { ascending: false, nullsFirst: false });
+  if (!q.limit) throw new Error("readModelCatalogStamp: the client has no .limit() (a supabase-js client does)");
+  const { data, error } = await q.limit(1).maybeSingle();
+  if (error) throw new Error(error.message);
+  const stamp = data?.updated_at;
+  return typeof stamp === "string" ? stamp : null;
+}
+
+// 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 ?? {}));
+}
+function followModelCatalogVisibility(options) {
+  const page = options.page ?? (typeof document !== "undefined" && typeof window !== "undefined" ? { document, window } : null);
+  if (!page) return () => {
+  };
+  const minIntervalMs = options.minIntervalMs ?? 2e4;
+  const now = options.now ?? (() => Date.now());
+  const sink = options.errorSink ?? ((e) => {
+    console.error(`[@ai-matrx/agents/models] ${e.code}: ${e.message}`);
+  });
+  let baseline;
+  let inFlight = null;
+  let lastShownRead = -Infinity;
+  const stamp = () => inFlight ??= readModelCatalogStamp(options.client).finally(() => {
+    inFlight = null;
+  });
+  const fail = (err) => sink({ code: "model-catalog-stamp-failed", message: err instanceof Error ? err.message : String(err) });
+  const learnBaseline = () => {
+    if (baseline !== void 0) return;
+    void stamp().then((s4) => {
+      if (baseline === void 0) baseline = s4;
+    }, fail);
+  };
+  const onHidden = () => {
+    if (page.document.visibilityState === "hidden") learnBaseline();
+  };
+  const onShown = () => {
+    if (page.document.visibilityState === "hidden") return;
+    const t = now();
+    if (t - lastShownRead < minIntervalMs) return;
+    lastShownRead = t;
+    const known = baseline;
+    if (known === void 0) return learnBaseline();
+    void stamp().then((s4) => {
+      if (s4 === known) return;
+      baseline = s4;
+      announceModelCatalogChanged({ catalog: "models", change: "catch_up_visible" });
+    }, fail);
+  };
+  const offChanges = onModelCatalogChanged(() => {
+    baseline = void 0;
+    if (page.document.visibilityState === "hidden") learnBaseline();
+  });
+  const onVisibility = () => page.document.visibilityState === "hidden" ? onHidden() : onShown();
+  page.document.addEventListener("visibilitychange", onVisibility);
+  page.window.addEventListener("focus", onShown);
+  if (page.document.visibilityState === "hidden") learnBaseline();
+  return () => {
+    offChanges();
+    page.document.removeEventListener("visibilitychange", onVisibility);
+    page.window.removeEventListener("focus", onShown);
+  };
+}
 
 // models/catalog/store.ts
 var IDLE = { status: "idle", models: [], error: null, loadedAt: null };
@@ -3031,6 +3091,7 @@ export {
   fitsNeed,
   fitsThisComputer,
   followModelCatalogChanges,
+  followModelCatalogVisibility,
   formatMemoryBytes,
   fromDiscovery,
   ggufEngine,
@@ -3079,6 +3140,7 @@ export {
   readDeviceModelFiles,
   readGgufHeader,
   readModelCatalog,
+  readModelCatalogStamp,
   readModelIdentities,
   readPublicModel,
   reconcileModelFavoriteIds,

package/dist/models/react/index.d.cts

@@ -675,7 +675,12 @@ declare function ModelListDropdown({ value: savedValue, localModels: localModels
  * `@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 tab that is not listening (the bus room not joined yet, or asleep) catches up when it comes to the
+ * front: `followModelCatalogVisibility({ client })` reads the catalog stamp when the tab hides and again
+ * when it shows or takes focus (throttled), and announces a change when the stamp moved.
  */
+
 /** A `catalog_changed` payload: `{ catalog?: "models" | ..., change?, model_id? }`. */
 type ModelCatalogChangePayload = Record<string, unknown>;
 

package/dist/models/react/index.d.ts

@@ -675,7 +675,12 @@ declare function ModelListDropdown({ value: savedValue, localModels: localModels
  * `@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 tab that is not listening (the bus room not joined yet, or asleep) catches up when it comes to the
+ * front: `followModelCatalogVisibility({ client })` reads the catalog stamp when the tab hides and again
+ * when it shows or takes focus (throttled), and announces a change when the stamp moved.
  */
+
 /** A `catalog_changed` payload: `{ catalog?: "models" | ..., change?, model_id? }`. */
 type ModelCatalogChangePayload = Record<string, unknown>;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/agents",
-  "version": "0.59.270",
+  "version": "0.59.271",
   "description": "Portable AI Matrx agent stream protocol, event projection, and safe result-presentation primitives.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -518,5 +518,5 @@
       "optional": true
     }
   },
-  "gitHead": "8a4ed656ea91ae1934870745a5c95f91f24da863"
+  "gitHead": "2c48e6413332bdf7ea9f92366e3ad0e4129ddd52"
 }