@ai-matrx/agents 0.59.272 → 0.59.274

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.59.274
+
+- `./models`: a burst of `catalog_changed` is ONE re-read. New `coalesceModelCatalogChanges(deliver, options?)`:
+  a `requestId` already delivered (60 s) is dropped; the first envelope of a burst is delivered at once; copies
+  with the same payload inside 1.5 s are dropped; a different payload inside the window is delivered once when
+  it closes. `followModelCatalogChanges(subscribe, options?)` uses it, and the subscribe handler may pass a
+  second `meta` argument (`{ requestId }`). Live 2026-10-24: one edit reached every open app as 8 + 8
+  envelopes. Consumer action: none for the web; Matrx 2's main-process follower adopts the coalescer.
+
+## 0.59.273
+
+Automatic changed-only republish (docs/metadata drift since the last published version; verified: `git diff 467bc8f112 757401d3d2 -- apps/shared/matrx-agents/src`
+has no shipped-source changes outside tests, fixtures and docs). No consumer action required.
+
 ## 0.59.272
 
 - New export `./context/rules-corpus.json` (shipped in `files`): the context-rules parity corpus, so a consumer test (chat) reads it through the dependency instead of a path into this package. Additive; no consumer action required.

package/dist/models/index.cjs

@@ -62,6 +62,7 @@ __export(models_exports, {
   catalogKindVerdict: () => catalogKindVerdict,
   cheapestAdequateModel: () => cheapestAdequateModel,
   classConfigKey: () => classConfigKey,
+  coalesceModelCatalogChanges: () => coalesceModelCatalogChanges,
   collapseTiersByClass: () => collapseTiersByClass,
   costRatingTier: () => costRatingTier,
   costRatingWord: () => costRatingWord,
@@ -1574,8 +1575,64 @@ function announceModelCatalogChanged(payload = {}) {
     }
   }
 }
-function followModelCatalogChanges(subscribe) {
-  return subscribe("catalog_changed", (payload) => announceModelCatalogChanged(payload ?? {}));
+var contentKey = (payload) => JSON.stringify(
+  Object.keys({ catalog: "models", ...payload }).sort().map((k) => [k, k === "catalog" ? payload[k] ?? "models" : payload[k] ?? null]).filter(([, v]) => v !== null)
+);
+function coalesceModelCatalogChanges(deliver, options = {}) {
+  const windowMs = options.windowMs ?? 1500;
+  const rememberMs = options.rememberMs ?? 6e4;
+  const now = options.now ?? (() => Date.now());
+  const setTimer = options.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+  const clearTimer = options.clearTimer ?? ((h) => clearTimeout(h));
+  const seenIds = /* @__PURE__ */ new Map();
+  let windowStart = -Infinity;
+  let windowKeys = /* @__PURE__ */ new Set();
+  let pending = null;
+  let timer = null;
+  const open = (payload, at) => {
+    windowStart = at;
+    windowKeys = /* @__PURE__ */ new Set([contentKey(payload)]);
+    deliver(payload);
+  };
+  const feed = (payload, meta) => {
+    const p = payload ?? {};
+    const t = now();
+    for (const [id2, at] of seenIds) if (t - at > rememberMs) seenIds.delete(id2);
+    const id = typeof meta?.requestId === "string" && meta.requestId ? meta.requestId : null;
+    if (id !== null) {
+      if (seenIds.has(id)) return;
+      seenIds.set(id, t);
+    }
+    if (t - windowStart >= windowMs) return open(p, t);
+    const key = contentKey(p);
+    if (windowKeys.has(key)) return;
+    windowKeys.add(key);
+    pending = p;
+    timer ??= setTimer(() => {
+      timer = null;
+      const next = pending;
+      pending = null;
+      if (next) open(next, now());
+    }, Math.max(0, windowStart + windowMs - t));
+  };
+  return Object.assign(feed, {
+    stop() {
+      if (timer !== null) clearTimer(timer);
+      timer = null;
+      pending = null;
+    }
+  });
+}
+function followModelCatalogChanges(subscribe, options) {
+  const feed = coalesceModelCatalogChanges((payload) => announceModelCatalogChanged(payload), options);
+  const off = subscribe("catalog_changed", (payload, meta) => {
+    if (!isModelCatalogChange(payload ?? {})) return;
+    feed(payload ?? {}, meta);
+  });
+  return () => {
+    feed.stop();
+    off();
+  };
 }
 function followModelCatalogVisibility(options) {
   const page = options.page ?? (typeof document !== "undefined" && typeof window !== "undefined" ? { document, window } : null);
@@ -2831,7 +2888,8 @@ function toDeviceModelFile(r) {
     sha256: sn2(r.sha256),
     artifact_id: sn2(r.artifact_id),
     state: s2(r.state),
-    organization_id: sn2(r.organization_id)
+    organization_id: sn2(r.organization_id),
+    model_key: sn2(r.metadata?.model_key)
   };
 }
 async function readDeviceModelFiles(client, opts = {}) {

package/dist/models/index.d.cts

@@ -1764,6 +1764,11 @@ interface DeviceModelFile {
     artifact_id: string | null;
     state: string;
     organization_id: string | null;
+    /**
+     * The key the computer runs this file under (`metadata.model_key`, published by Matrx 2): for a person's own
+     * file it is the run key the device's model service names it by. Null when not reported yet.
+     */
+    model_key: string | null;
 }
 declare function toDeviceModelFile(r: Row$1): DeviceModelFile;
 /**
@@ -2061,8 +2066,12 @@ declare function modelDisplayLabel(row: ModelLabelSource | null | undefined): st
 
 /** A `catalog_changed` payload: `{ catalog?: "models" | ..., change?, model_id? }`. */
 type ModelCatalogChangePayload = Record<string, unknown>;
+/** What the bus knew about one envelope besides its payload: its `requestId` (the server names one burst once). */
+type ModelCatalogChangeMeta = {
+    requestId?: string | null;
+} | null | undefined;
 /** The bus client's subscribe call: `(action, handler) => unsubscribe` (the web's `registerDirectiveHandler`). */
-type ModelCatalogDirectiveSubscribe = (action: "catalog_changed", handler: (payload: ModelCatalogChangePayload) => void) => () => void;
+type ModelCatalogDirectiveSubscribe = (action: "catalog_changed", handler: (payload: ModelCatalogChangePayload, meta?: ModelCatalogChangeMeta) => void) => () => void;
 /** Is this notice about the MODEL catalog? (`catalog` absent or `"models"`; the tool catalog shares the action.) */
 declare function isModelCatalogChange(payload: ModelCatalogChangePayload | null | undefined): boolean;
 /** Listen for model catalog changes. Returns the unsubscribe. */
@@ -2071,8 +2080,32 @@ declare function onModelCatalogChanged(listener: (payload: ModelCatalogChangePay
 declare function modelCatalogRevision(): number;
 /** Announce a model catalog change to every listener (a notice that is not about models is ignored). */
 declare function announceModelCatalogChanged(payload?: ModelCatalogChangePayload): void;
-/** Bind the host's bus client: every `catalog_changed` it delivers reaches every model reader. Returns the unbind. */
-declare function followModelCatalogChanges(subscribe: ModelCatalogDirectiveSubscribe): () => void;
+interface ModelCatalogCoalesceOptions {
+    /** Envelopes within this many ms of the last delivery are the same burst. Default 1500. */
+    windowMs?: number;
+    /** How long a delivered `requestId` is remembered (a late replica's copy is dropped). Default 60 s. */
+    rememberMs?: number;
+    now?: () => number;
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+}
+/**
+ * Fold a burst of `catalog_changed` envelopes into ONE delivery. The server's replicas (and, before
+ * 2026-10-24, a second relay ~4 s later) can put the same change on the bus several times; every copy used to
+ * cost every open app a re-read. Rules: an envelope whose `requestId` was delivered within `rememberMs` is
+ * dropped; the first envelope of a burst is delivered at once; within `windowMs` of that delivery a copy with
+ * the same payload is dropped, and a DIFFERENT payload (another model, another kind of edit) is delivered
+ * once when the window closes, so a real second change is never lost. Returns the feed; `feed.stop()` drops
+ * a pending delivery.
+ */
+declare function coalesceModelCatalogChanges(deliver: (payload: ModelCatalogChangePayload) => void, options?: ModelCatalogCoalesceOptions): ((payload: ModelCatalogChangePayload, meta?: ModelCatalogChangeMeta) => void) & {
+    stop(): void;
+};
+/**
+ * Bind the host's bus client: every `catalog_changed` it delivers reaches every model reader, a burst of
+ * copies as ONE change (`coalesceModelCatalogChanges`). Returns the unbind.
+ */
+declare function followModelCatalogChanges(subscribe: ModelCatalogDirectiveSubscribe, options?: ModelCatalogCoalesceOptions): () => void;
 interface ModelCatalogVisibilityOptions {
     /** The client the stamp is read with (supabase-js fits as is). */
     client: ModelRecordsClient;
@@ -2100,5 +2133,5 @@ interface ModelCatalogVisibilityOptions {
  */
 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, 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 };
+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, coalesceModelCatalogChanges, 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, ModelCatalogChangeMeta, ModelCatalogChangePayload, ModelCatalogClient, ModelCatalogCoalesceOptions, 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

@@ -1764,6 +1764,11 @@ interface DeviceModelFile {
     artifact_id: string | null;
     state: string;
     organization_id: string | null;
+    /**
+     * The key the computer runs this file under (`metadata.model_key`, published by Matrx 2): for a person's own
+     * file it is the run key the device's model service names it by. Null when not reported yet.
+     */
+    model_key: string | null;
 }
 declare function toDeviceModelFile(r: Row$1): DeviceModelFile;
 /**
@@ -2061,8 +2066,12 @@ declare function modelDisplayLabel(row: ModelLabelSource | null | undefined): st
 
 /** A `catalog_changed` payload: `{ catalog?: "models" | ..., change?, model_id? }`. */
 type ModelCatalogChangePayload = Record<string, unknown>;
+/** What the bus knew about one envelope besides its payload: its `requestId` (the server names one burst once). */
+type ModelCatalogChangeMeta = {
+    requestId?: string | null;
+} | null | undefined;
 /** The bus client's subscribe call: `(action, handler) => unsubscribe` (the web's `registerDirectiveHandler`). */
-type ModelCatalogDirectiveSubscribe = (action: "catalog_changed", handler: (payload: ModelCatalogChangePayload) => void) => () => void;
+type ModelCatalogDirectiveSubscribe = (action: "catalog_changed", handler: (payload: ModelCatalogChangePayload, meta?: ModelCatalogChangeMeta) => void) => () => void;
 /** Is this notice about the MODEL catalog? (`catalog` absent or `"models"`; the tool catalog shares the action.) */
 declare function isModelCatalogChange(payload: ModelCatalogChangePayload | null | undefined): boolean;
 /** Listen for model catalog changes. Returns the unsubscribe. */
@@ -2071,8 +2080,32 @@ declare function onModelCatalogChanged(listener: (payload: ModelCatalogChangePay
 declare function modelCatalogRevision(): number;
 /** Announce a model catalog change to every listener (a notice that is not about models is ignored). */
 declare function announceModelCatalogChanged(payload?: ModelCatalogChangePayload): void;
-/** Bind the host's bus client: every `catalog_changed` it delivers reaches every model reader. Returns the unbind. */
-declare function followModelCatalogChanges(subscribe: ModelCatalogDirectiveSubscribe): () => void;
+interface ModelCatalogCoalesceOptions {
+    /** Envelopes within this many ms of the last delivery are the same burst. Default 1500. */
+    windowMs?: number;
+    /** How long a delivered `requestId` is remembered (a late replica's copy is dropped). Default 60 s. */
+    rememberMs?: number;
+    now?: () => number;
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+}
+/**
+ * Fold a burst of `catalog_changed` envelopes into ONE delivery. The server's replicas (and, before
+ * 2026-10-24, a second relay ~4 s later) can put the same change on the bus several times; every copy used to
+ * cost every open app a re-read. Rules: an envelope whose `requestId` was delivered within `rememberMs` is
+ * dropped; the first envelope of a burst is delivered at once; within `windowMs` of that delivery a copy with
+ * the same payload is dropped, and a DIFFERENT payload (another model, another kind of edit) is delivered
+ * once when the window closes, so a real second change is never lost. Returns the feed; `feed.stop()` drops
+ * a pending delivery.
+ */
+declare function coalesceModelCatalogChanges(deliver: (payload: ModelCatalogChangePayload) => void, options?: ModelCatalogCoalesceOptions): ((payload: ModelCatalogChangePayload, meta?: ModelCatalogChangeMeta) => void) & {
+    stop(): void;
+};
+/**
+ * Bind the host's bus client: every `catalog_changed` it delivers reaches every model reader, a burst of
+ * copies as ONE change (`coalesceModelCatalogChanges`). Returns the unbind.
+ */
+declare function followModelCatalogChanges(subscribe: ModelCatalogDirectiveSubscribe, options?: ModelCatalogCoalesceOptions): () => void;
 interface ModelCatalogVisibilityOptions {
     /** The client the stamp is read with (supabase-js fits as is). */
     client: ModelRecordsClient;
@@ -2100,5 +2133,5 @@ interface ModelCatalogVisibilityOptions {
  */
 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, 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 };
+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, coalesceModelCatalogChanges, 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, ModelCatalogChangeMeta, ModelCatalogChangePayload, ModelCatalogClient, ModelCatalogCoalesceOptions, 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

@@ -1391,8 +1391,64 @@ function announceModelCatalogChanged(payload = {}) {
     }
   }
 }
-function followModelCatalogChanges(subscribe) {
-  return subscribe("catalog_changed", (payload) => announceModelCatalogChanged(payload ?? {}));
+var contentKey = (payload) => JSON.stringify(
+  Object.keys({ catalog: "models", ...payload }).sort().map((k) => [k, k === "catalog" ? payload[k] ?? "models" : payload[k] ?? null]).filter(([, v]) => v !== null)
+);
+function coalesceModelCatalogChanges(deliver, options = {}) {
+  const windowMs = options.windowMs ?? 1500;
+  const rememberMs = options.rememberMs ?? 6e4;
+  const now = options.now ?? (() => Date.now());
+  const setTimer = options.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+  const clearTimer = options.clearTimer ?? ((h) => clearTimeout(h));
+  const seenIds = /* @__PURE__ */ new Map();
+  let windowStart = -Infinity;
+  let windowKeys = /* @__PURE__ */ new Set();
+  let pending = null;
+  let timer = null;
+  const open = (payload, at) => {
+    windowStart = at;
+    windowKeys = /* @__PURE__ */ new Set([contentKey(payload)]);
+    deliver(payload);
+  };
+  const feed = (payload, meta) => {
+    const p = payload ?? {};
+    const t = now();
+    for (const [id2, at] of seenIds) if (t - at > rememberMs) seenIds.delete(id2);
+    const id = typeof meta?.requestId === "string" && meta.requestId ? meta.requestId : null;
+    if (id !== null) {
+      if (seenIds.has(id)) return;
+      seenIds.set(id, t);
+    }
+    if (t - windowStart >= windowMs) return open(p, t);
+    const key = contentKey(p);
+    if (windowKeys.has(key)) return;
+    windowKeys.add(key);
+    pending = p;
+    timer ??= setTimer(() => {
+      timer = null;
+      const next = pending;
+      pending = null;
+      if (next) open(next, now());
+    }, Math.max(0, windowStart + windowMs - t));
+  };
+  return Object.assign(feed, {
+    stop() {
+      if (timer !== null) clearTimer(timer);
+      timer = null;
+      pending = null;
+    }
+  });
+}
+function followModelCatalogChanges(subscribe, options) {
+  const feed = coalesceModelCatalogChanges((payload) => announceModelCatalogChanged(payload), options);
+  const off = subscribe("catalog_changed", (payload, meta) => {
+    if (!isModelCatalogChange(payload ?? {})) return;
+    feed(payload ?? {}, meta);
+  });
+  return () => {
+    feed.stop();
+    off();
+  };
 }
 function followModelCatalogVisibility(options) {
   const page = options.page ?? (typeof document !== "undefined" && typeof window !== "undefined" ? { document, window } : null);
@@ -2648,7 +2704,8 @@ function toDeviceModelFile(r) {
     sha256: sn2(r.sha256),
     artifact_id: sn2(r.artifact_id),
     state: s2(r.state),
-    organization_id: sn2(r.organization_id)
+    organization_id: sn2(r.organization_id),
+    model_key: sn2(r.metadata?.model_key)
   };
 }
 async function readDeviceModelFiles(client, opts = {}) {
@@ -3094,6 +3151,7 @@ export {
   catalogKindVerdict,
   cheapestAdequateModel,
   classConfigKey,
+  coalesceModelCatalogChanges,
   collapseTiersByClass,
   costRatingTier,
   costRatingWord,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/agents",
-  "version": "0.59.272",
+  "version": "0.59.274",
   "description": "Portable AI Matrx agent stream protocol, event projection, and safe result-presentation primitives.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -520,5 +520,5 @@
       "optional": true
     }
   },
-  "gitHead": "467bc8f11239e00d4bcd8d27c85861b0165cd0bd"
+  "gitHead": "6393a0ff9a690870c61c5c757c4ffe0b066e73df"
 }