@ai-matrx/agents 0.59.270 → 0.59.272

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.
@@ -1101,7 +1109,7 @@ interface LocalModel {
     /** Matrx 2's 1.48 id for a model seeded from its old list (metadata.desktop_id). */
     desktop_id?: string | null;
     maker_logo_file_id?: string | null;
-    /** The admin Catalogs kind (`catalogKindOf`): llm_model, whisper_model, tts_model_file, image_gen_model, video_gen_model, ner_model, wake_word_model, lora. */
+    /** The admin Catalogs kind (`catalogKindOf`): llm_model, whisper_model, tts_model_file, image_gen_model, video_gen_model, ner_model, wake_word_model, lora, embedding_model, or unknown (no rule places it; `catalogKindVerdict` says why). */
     kind?: string;
     /** At least one variant is offered (Matrx 2 lists it). */
     offered?: boolean;
@@ -1837,8 +1845,12 @@ interface ReadModelCatalogOptions {
         appInstanceIds?: readonly string[];
     };
 }
+/** The kind of a model the catalog cannot place by its capabilities: shown loudly, never offered to a chat. */
+declare const UNKNOWN_MODEL_KIND: "unknown";
 /** The catalog kinds whose rows live in the unified catalog (ai.*): the admin Catalogs page's model kinds. */
 declare const MODEL_CATALOG_KINDS: ReadonlySet<string>;
+/** The interactions a text-in, text-out model answers a person in: only these make an llm_model. */
+declare const LLM_INTERACTIONS: ReadonlySet<string>;
 /** What `catalogKindOf` reads from a model (a CuratedModel or a LocalModel from `readModelCatalog` both fit). */
 interface CatalogKindInput {
     readonly variants: ReadonlyArray<{
@@ -1853,11 +1865,20 @@ interface CatalogKindInput {
         readonly shelf?: string | null;
     } | null;
 }
+/** A model's admin kind and, when it is `unknown`, why (one line, said on the admin page and in reader warnings). */
+interface CatalogKindVerdict {
+    kind: string;
+    reason: string | null;
+}
 /**
- * THE admin Catalogs kind of a unified model: the kind of the old public.catalog_entries rows its variants
- * carry (the list migration stamps them), when that is a model kind; else placed by what it does.
- * `kindOfEntry` maps catalog_entries.id → kind.
+ * THE admin Catalogs kind of a unified model, with the reason when it cannot be placed: the kind of the
+ * old public.catalog_entries rows its variants carry (the list migration stamps them), when that is a
+ * model kind; else placed by what it does (capabilities, never a name list). There is NO default: a model
+ * is an llm_model only when it takes text, gives text and answers in a chat-like interaction
+ * (LLM_INTERACTIONS); anything the rules cannot place is `unknown`, with the reason.
  */
+declare function catalogKindVerdict(m: CatalogKindInput, kindOfEntry: ReadonlyMap<string, string>): CatalogKindVerdict;
+/** THE admin Catalogs kind of a unified model (`catalogKindVerdict(...).kind`); `unknown` when it cannot be placed. */
 declare function catalogKindOf(m: CatalogKindInput, kindOfEntry: ReadonlyMap<string, string>): string;
 /** sha256 (hex) of the catalog's canonical JSON, its own `catalog_fingerprint` left out. Isomorphic (pure JS). */
 declare function catalogFingerprint(catalog: LocalModelCatalog): string;
@@ -2032,7 +2053,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 +2073,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, LLM_INTERACTIONS, 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, UNKNOWN_MODEL_KIND, acceptsTextInstructions, announceModelCatalogChanged, availableOnDevices, blendedPrice, buildModelClassIndex, buildSuccessionIndex, catalogFingerprint, catalogForApp, catalogKeyColumn, catalogKindOf, catalogKindVerdict, 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, CatalogKindVerdict, 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.
@@ -1101,7 +1109,7 @@ interface LocalModel {
     /** Matrx 2's 1.48 id for a model seeded from its old list (metadata.desktop_id). */
     desktop_id?: string | null;
     maker_logo_file_id?: string | null;
-    /** The admin Catalogs kind (`catalogKindOf`): llm_model, whisper_model, tts_model_file, image_gen_model, video_gen_model, ner_model, wake_word_model, lora. */
+    /** The admin Catalogs kind (`catalogKindOf`): llm_model, whisper_model, tts_model_file, image_gen_model, video_gen_model, ner_model, wake_word_model, lora, embedding_model, or unknown (no rule places it; `catalogKindVerdict` says why). */
     kind?: string;
     /** At least one variant is offered (Matrx 2 lists it). */
     offered?: boolean;
@@ -1837,8 +1845,12 @@ interface ReadModelCatalogOptions {
         appInstanceIds?: readonly string[];
     };
 }
+/** The kind of a model the catalog cannot place by its capabilities: shown loudly, never offered to a chat. */
+declare const UNKNOWN_MODEL_KIND: "unknown";
 /** The catalog kinds whose rows live in the unified catalog (ai.*): the admin Catalogs page's model kinds. */
 declare const MODEL_CATALOG_KINDS: ReadonlySet<string>;
+/** The interactions a text-in, text-out model answers a person in: only these make an llm_model. */
+declare const LLM_INTERACTIONS: ReadonlySet<string>;
 /** What `catalogKindOf` reads from a model (a CuratedModel or a LocalModel from `readModelCatalog` both fit). */
 interface CatalogKindInput {
     readonly variants: ReadonlyArray<{
@@ -1853,11 +1865,20 @@ interface CatalogKindInput {
         readonly shelf?: string | null;
     } | null;
 }
+/** A model's admin kind and, when it is `unknown`, why (one line, said on the admin page and in reader warnings). */
+interface CatalogKindVerdict {
+    kind: string;
+    reason: string | null;
+}
 /**
- * THE admin Catalogs kind of a unified model: the kind of the old public.catalog_entries rows its variants
- * carry (the list migration stamps them), when that is a model kind; else placed by what it does.
- * `kindOfEntry` maps catalog_entries.id → kind.
+ * THE admin Catalogs kind of a unified model, with the reason when it cannot be placed: the kind of the
+ * old public.catalog_entries rows its variants carry (the list migration stamps them), when that is a
+ * model kind; else placed by what it does (capabilities, never a name list). There is NO default: a model
+ * is an llm_model only when it takes text, gives text and answers in a chat-like interaction
+ * (LLM_INTERACTIONS); anything the rules cannot place is `unknown`, with the reason.
  */
+declare function catalogKindVerdict(m: CatalogKindInput, kindOfEntry: ReadonlyMap<string, string>): CatalogKindVerdict;
+/** THE admin Catalogs kind of a unified model (`catalogKindVerdict(...).kind`); `unknown` when it cannot be placed. */
 declare function catalogKindOf(m: CatalogKindInput, kindOfEntry: ReadonlyMap<string, string>): string;
 /** sha256 (hex) of the catalog's canonical JSON, its own `catalog_fingerprint` left out. Isomorphic (pure JS). */
 declare function catalogFingerprint(catalog: LocalModelCatalog): string;
@@ -2032,7 +2053,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 +2073,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, LLM_INTERACTIONS, 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, UNKNOWN_MODEL_KIND, acceptsTextInstructions, announceModelCatalogChanged, availableOnDevices, blendedPrice, buildModelClassIndex, buildSuccessionIndex, catalogFingerprint, catalogForApp, catalogKeyColumn, catalogKindOf, catalogKindVerdict, 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, CatalogKindVerdict, 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 };
@@ -2641,6 +2701,7 @@ var DeviceModelUnavailableError = class extends Error {
 };
 
 // models/catalog-reader.ts
+var UNKNOWN_MODEL_KIND = "unknown";
 var MODEL_CATALOG_KINDS = /* @__PURE__ */ new Set([
   "llm_model",
   "whisper_model",
@@ -2649,23 +2710,35 @@ var MODEL_CATALOG_KINDS = /* @__PURE__ */ new Set([
   "video_gen_model",
   "ner_model",
   "wake_word_model",
-  "lora"
+  "lora",
+  "embedding_model",
+  UNKNOWN_MODEL_KIND
 ]);
-function catalogKindOf(m, kindOfEntry) {
+var LLM_INTERACTIONS = /* @__PURE__ */ new Set(["turn", "single", "agent"]);
+function catalogKindVerdict(m, kindOfEntry) {
   for (const v of m.variants)
     for (const id of v.catalog_entry_ids ?? []) {
       const k = kindOfEntry.get(id);
-      if (k && MODEL_CATALOG_KINDS.has(k)) return k;
+      if (k && k !== UNKNOWN_MODEL_KIND && MODEL_CATALOG_KINDS.has(k)) return { kind: k, reason: null };
     }
   const out = m.capabilities.output ?? [];
   const inp = m.capabilities.input ?? [];
-  if (m.presentation?.shelf === "loras") return "lora";
-  if (out.includes("video")) return "video_gen_model";
-  if (out.includes("image")) return "image_gen_model";
-  if (out.includes("audio")) return "tts_model_file";
-  if (inp.includes("audio")) return "whisper_model";
-  if (m.capabilities.interaction === "extraction") return "ner_model";
-  return "llm_model";
+  const interaction = m.capabilities.interaction ?? "";
+  const placed = (kind) => ({ kind, reason: null });
+  if (m.presentation?.shelf === "loras" || interaction === "adapter") return placed("lora");
+  if (out.includes("video")) return placed("video_gen_model");
+  if (out.includes("image")) return placed("image_gen_model");
+  if (out.includes("embedding")) return placed("embedding_model");
+  if (out.includes("audio")) return placed("tts_model_file");
+  if (inp.includes("audio") && (out.includes("decision") || interaction === "detection")) return placed("wake_word_model");
+  if (inp.includes("audio") && out.includes("text")) return placed("whisper_model");
+  if (interaction === "extraction") return placed("ner_model");
+  if (inp.includes("text") && out.includes("text") && LLM_INTERACTIONS.has(interaction)) return placed("llm_model");
+  const shape = `input [${inp.join(", ")}], output [${out.join(", ")}], interaction ${interaction || "(none)"}`;
+  return { kind: UNKNOWN_MODEL_KIND, reason: `no kind rule places ${shape}` };
+}
+function catalogKindOf(m, kindOfEntry) {
+  return catalogKindVerdict(m, kindOfEntry).kind;
 }
 function canonicalJson(value) {
   if (value === void 0) return "null";
@@ -2744,6 +2817,8 @@ async function readCatalogWith(client, opts, preread) {
     const p = presentationOf.get(c.id);
     stamp(p);
     const maker = providerById.get(s3(m.provider_id));
+    const verdict = catalogKindVerdict(c, kindOfEntry);
+    if (verdict.reason) warnings.push(`${s3(m.name)}: kind unknown: ${verdict.reason}`);
     return [
       {
         id: s3(m.id),
@@ -2754,7 +2829,7 @@ async function readCatalogWith(client, opts, preread) {
         maker_logo_file_id: sn3(maker?.logo_file_id),
         description: sn3(m.description),
         capabilities: m.capabilities ?? {},
-        kind: catalogKindOf(c, kindOfEntry),
+        kind: verdict.kind,
         offered: c.offered,
         updated_at: c.updated_at,
         presentation: p ? {
@@ -2995,6 +3070,7 @@ export {
   GgufError,
   INPUT_MODALITIES,
   INTERACTION_MODES,
+  LLM_INTERACTIONS,
   MAX_SUCCESSION_HOPS,
   MODEL_CATALOG_KINDS,
   MODEL_FAVORITE_ENTITY_TYPE,
@@ -3004,6 +3080,7 @@ export {
   SERVICE_LABEL_PLURAL,
   TOP_TIER_COST_RATING,
   TOP_TIER_LOCKED_TITLE,
+  UNKNOWN_MODEL_KIND,
   acceptsTextInstructions,
   announceModelCatalogChanged,
   availableOnDevices,
@@ -3014,6 +3091,7 @@ export {
   catalogForApp,
   catalogKeyColumn,
   catalogKindOf,
+  catalogKindVerdict,
   cheapestAdequateModel,
   classConfigKey,
   collapseTiersByClass,
@@ -3031,6 +3109,7 @@ export {
   fitsNeed,
   fitsThisComputer,
   followModelCatalogChanges,
+  followModelCatalogVisibility,
   formatMemoryBytes,
   fromDiscovery,
   ggufEngine,
@@ -3079,6 +3158,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>;
 
@@ -799,7 +804,7 @@ interface LocalModel {
     /** Matrx 2's 1.48 id for a model seeded from its old list (metadata.desktop_id). */
     desktop_id?: string | null;
     maker_logo_file_id?: string | null;
-    /** The admin Catalogs kind (`catalogKindOf`): llm_model, whisper_model, tts_model_file, image_gen_model, video_gen_model, ner_model, wake_word_model, lora. */
+    /** The admin Catalogs kind (`catalogKindOf`): llm_model, whisper_model, tts_model_file, image_gen_model, video_gen_model, ner_model, wake_word_model, lora, embedding_model, or unknown (no rule places it; `catalogKindVerdict` says why). */
     kind?: string;
     /** At least one variant is offered (Matrx 2 lists it). */
     offered?: boolean;

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>;
 
@@ -799,7 +804,7 @@ interface LocalModel {
     /** Matrx 2's 1.48 id for a model seeded from its old list (metadata.desktop_id). */
     desktop_id?: string | null;
     maker_logo_file_id?: string | null;
-    /** The admin Catalogs kind (`catalogKindOf`): llm_model, whisper_model, tts_model_file, image_gen_model, video_gen_model, ner_model, wake_word_model, lora. */
+    /** The admin Catalogs kind (`catalogKindOf`): llm_model, whisper_model, tts_model_file, image_gen_model, video_gen_model, ner_model, wake_word_model, lora, embedding_model, or unknown (no rule places it; `catalogKindVerdict` says why). */
     kind?: string;
     /** At least one variant is offered (Matrx 2 lists it). */
     offered?: boolean;

package/dist/settings/index.cjs

@@ -25,6 +25,7 @@ __export(settings_exports, {
   CATALOGUE_KEYS: () => CATALOGUE_KEYS,
   EMPTY_UI_GATES: () => EMPTY_UI_GATES,
   ENUM_OFF_VALUE: () => ENUM_OFF_VALUE,
+  NEVER_IMPLICIT_AUTO_KEYS: () => NEVER_IMPLICIT_AUTO_KEYS,
   PARAM_ALIASES: () => PARAM_ALIASES,
   SETTINGS_CATALOGUE: () => SETTINGS_CATALOGUE,
   UI_GATE_EDITABLE_KEYS: () => UI_GATE_EDITABLE_KEYS,
@@ -39,6 +40,7 @@ __export(settings_exports, {
   extractModelDefaults: () => extractModelDefaults,
   gateEnabled: () => gateEnabled,
   getActionForMode: () => getActionForMode,
+  isNeverImplicitChoice: () => isNeverImplicitChoice,
   isOffValue: () => isOffValue,
   isUiGateKey: () => isUiGateKey,
   isUnsetChoice: () => isUnsetChoice,
@@ -1032,13 +1034,19 @@ function withSettingState(settings, key, state, control, value) {
 // settings/auto-means-unset.ts
 var AUTO_VALUE = "auto";
 var AUTO_MEANS_UNSET_KEYS = /* @__PURE__ */ new Set([
-  "reasoning_effort",
   "visualization"
 ]);
+var NEVER_IMPLICIT_AUTO_KEYS = /* @__PURE__ */ new Set([
+  "reasoning_effort"
+]);
 function isUnsetChoice(key, value) {
   if (value === void 0 || value === null) return true;
   return value === AUTO_VALUE && AUTO_MEANS_UNSET_KEYS.has(key);
 }
+function isNeverImplicitChoice(key, value) {
+  if (isUnsetChoice(key, value)) return true;
+  return value === AUTO_VALUE && NEVER_IMPLICIT_AUTO_KEYS.has(key);
+}
 
 // settings/starting-value.ts
 function startingValueFor(key, control) {
@@ -1056,8 +1064,8 @@ function startingValueFor(key, control) {
       value = [];
     }
   }
-  if (isUnsetChoice(key, value) && control.type === "enum" && control.enum?.length) {
-    value = control.enum.find((choice) => !isUnsetChoice(key, choice));
+  if (isNeverImplicitChoice(key, value) && control.type === "enum" && control.enum?.length) {
+    value = control.enum.find((choice) => !isNeverImplicitChoice(key, choice));
   }
   if (key === "response_format" && typeof value === "string") {
     value = value === "" ? void 0 : { type: value };