@ai-matrx/agents 0.59.192 → 0.59.193

package/CHANGELOG.md

@@ -1,6 +1,16 @@
 # Changelog
 
+## 0.59.193
+
+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.192
+
+Automatic changed-only republish (docs/metadata drift since the last published version; verified: `git diff 89bae1f6f7 7829f4d91a -- apps/shared/matrx-agents/src`
+has no shipped-source changes outside tests, fixtures and docs). No consumer action required.
+
+## 0.59.191
 ### THE model-settings panel (2026-10-21)
 
 - Added `./settings/react` `ModelSettingsPanel`, `ExtraSettingRow`, `SettingRowFrame`, `SettingsGroupSection`, `SettingRowLabel`, `formatSettingValue`; `./settings` `SettingsWriteTarget` / `CapabilitiesWriteTarget` / `SettingRowRead`, `isOffValue` / `offValueFor` / `settingStateOf` / `withSettingState` / `ENUM_OFF_VALUE`, `isUnsetChoice` / `AUTO_VALUE` / `AUTO_MEANS_UNSET_KEYS`, `startingValueFor`.

package/dist/content-transfer/index.cjs

@@ -703,7 +703,7 @@ var MANDATE_KEYS = {
    */
   brand_discovery__offering_roles: "brand_discovery.offering_roles",
   /**
-   * @deprecated retiring since 0.59.192 — no longer declared in
+   * @deprecated retiring since 0.59.193 — no longer declared in
    * aidream. It leaves this union once no snapshot within the last
    * 3 published versions still carries it as active.
    */

package/dist/content-transfer/index.js

@@ -680,7 +680,7 @@ var MANDATE_KEYS = {
    */
   brand_discovery__offering_roles: "brand_discovery.offering_roles",
   /**
-   * @deprecated retiring since 0.59.192 — no longer declared in
+   * @deprecated retiring since 0.59.193 — no longer declared in
    * aidream. It leaves this union once no snapshot within the last
    * 3 published versions still carries it as active.
    */

package/dist/content-transfer/react/index.cjs

@@ -656,7 +656,7 @@ var MANDATE_KEYS = {
    */
   brand_discovery__offering_roles: "brand_discovery.offering_roles",
   /**
-   * @deprecated retiring since 0.59.192 — no longer declared in
+   * @deprecated retiring since 0.59.193 — no longer declared in
    * aidream. It leaves this union once no snapshot within the last
    * 3 published versions still carries it as active.
    */

package/dist/content-transfer/react/index.js

@@ -628,7 +628,7 @@ var MANDATE_KEYS = {
    */
   brand_discovery__offering_roles: "brand_discovery.offering_roles",
   /**
-   * @deprecated retiring since 0.59.192 — no longer declared in
+   * @deprecated retiring since 0.59.193 — no longer declared in
    * aidream. It leaves this union once no snapshot within the last
    * 3 published versions still carries it as active.
    */

package/dist/mandates/index.cjs

@@ -47,9 +47,9 @@ module.exports = __toCommonJS(mandates_exports);
 
 // mandates/keys.generated.ts
 var MANDATE_KEYS_META = {
-  aidreamRevision: "7829f4d91a8aa88811a634c9fe02aa66cf4b2e5c",
+  aidreamRevision: "3165453310fa6d42f3b90249a12d956eeebe7636",
   generatorVersion: "1.0.0",
-  packageVersion: "0.59.192",
+  packageVersion: "0.59.193",
   retireWindow: 3
 };
 var MANDATE_KEYS = {
@@ -666,7 +666,7 @@ var MANDATE_KEYS = {
    */
   brand_discovery__offering_roles: "brand_discovery.offering_roles",
   /**
-   * @deprecated retiring since 0.59.192 — no longer declared in
+   * @deprecated retiring since 0.59.193 — no longer declared in
    * aidream. It leaves this union once no snapshot within the last
    * 3 published versions still carries it as active.
    */
@@ -693,7 +693,7 @@ var MANDATE_KEYS = {
 var ALL_MANDATE_KEYS = Object.values(MANDATE_KEYS);
 var RETIRING_MANDATE_KEYS = {
   "brand_discovery.offering_roles": "0.59.0",
-  "coding_session.managed_translation_reference": "0.59.192",
+  "coding_session.managed_translation_reference": "0.59.193",
   "pdf.content_cleaner": "0.59.0",
   "sms.owner_beta": "0.59.0",
   "voice.owner_beta": "0.59.0"

package/dist/mandates/index.d.cts

@@ -6,9 +6,9 @@
  * from the IN-PROCESS mandate declarations — the same `declared_mandates()` the
  * boot sync writes to the database from. There is no hand list anywhere.
  *
- * aidream revision:   7829f4d91a8aa88811a634c9fe02aa66cf4b2e5c
+ * aidream revision:   3165453310fa6d42f3b90249a12d956eeebe7636
  * generator version:  1.0.0
- * package version:    0.59.192
+ * package version:    0.59.193
  * active keys:        606
  * retiring keys:      5
  *
@@ -19,9 +19,9 @@
  */
 /** Where this module came from — surfaced so a report can name the exact build. */
 declare const MANDATE_KEYS_META: {
-    readonly aidreamRevision: "7829f4d91a8aa88811a634c9fe02aa66cf4b2e5c";
+    readonly aidreamRevision: "3165453310fa6d42f3b90249a12d956eeebe7636";
     readonly generatorVersion: "1.0.0";
-    readonly packageVersion: "0.59.192";
+    readonly packageVersion: "0.59.193";
     readonly retireWindow: 3;
 };
 /** Every declared mandate key, by THE IDENTIFIER RULE. */
@@ -639,7 +639,7 @@ declare const MANDATE_KEYS: {
      */
     readonly brand_discovery__offering_roles: "brand_discovery.offering_roles";
     /**
-     * @deprecated retiring since 0.59.192 — no longer declared in
+     * @deprecated retiring since 0.59.193 — no longer declared in
      * aidream. It leaves this union once no snapshot within the last
      * 3 published versions still carries it as active.
      */
@@ -670,7 +670,7 @@ declare const ALL_MANDATE_KEYS: readonly MandateKey[];
 /** Keys still in the union but no longer declared (two-phase retire, phase 1). */
 declare const RETIRING_MANDATE_KEYS: {
     readonly "brand_discovery.offering_roles": "0.59.0";
-    readonly "coding_session.managed_translation_reference": "0.59.192";
+    readonly "coding_session.managed_translation_reference": "0.59.193";
     readonly "pdf.content_cleaner": "0.59.0";
     readonly "sms.owner_beta": "0.59.0";
     readonly "voice.owner_beta": "0.59.0";

package/dist/mandates/index.d.ts

@@ -6,9 +6,9 @@
  * from the IN-PROCESS mandate declarations — the same `declared_mandates()` the
  * boot sync writes to the database from. There is no hand list anywhere.
  *
- * aidream revision:   7829f4d91a8aa88811a634c9fe02aa66cf4b2e5c
+ * aidream revision:   3165453310fa6d42f3b90249a12d956eeebe7636
  * generator version:  1.0.0
- * package version:    0.59.192
+ * package version:    0.59.193
  * active keys:        606
  * retiring keys:      5
  *
@@ -19,9 +19,9 @@
  */
 /** Where this module came from — surfaced so a report can name the exact build. */
 declare const MANDATE_KEYS_META: {
-    readonly aidreamRevision: "7829f4d91a8aa88811a634c9fe02aa66cf4b2e5c";
+    readonly aidreamRevision: "3165453310fa6d42f3b90249a12d956eeebe7636";
     readonly generatorVersion: "1.0.0";
-    readonly packageVersion: "0.59.192";
+    readonly packageVersion: "0.59.193";
     readonly retireWindow: 3;
 };
 /** Every declared mandate key, by THE IDENTIFIER RULE. */
@@ -639,7 +639,7 @@ declare const MANDATE_KEYS: {
      */
     readonly brand_discovery__offering_roles: "brand_discovery.offering_roles";
     /**
-     * @deprecated retiring since 0.59.192 — no longer declared in
+     * @deprecated retiring since 0.59.193 — no longer declared in
      * aidream. It leaves this union once no snapshot within the last
      * 3 published versions still carries it as active.
      */
@@ -670,7 +670,7 @@ declare const ALL_MANDATE_KEYS: readonly MandateKey[];
 /** Keys still in the union but no longer declared (two-phase retire, phase 1). */
 declare const RETIRING_MANDATE_KEYS: {
     readonly "brand_discovery.offering_roles": "0.59.0";
-    readonly "coding_session.managed_translation_reference": "0.59.192";
+    readonly "coding_session.managed_translation_reference": "0.59.193";
     readonly "pdf.content_cleaner": "0.59.0";
     readonly "sms.owner_beta": "0.59.0";
     readonly "voice.owner_beta": "0.59.0";

package/dist/mandates/index.js

@@ -1,8 +1,8 @@
 // mandates/keys.generated.ts
 var MANDATE_KEYS_META = {
-  aidreamRevision: "7829f4d91a8aa88811a634c9fe02aa66cf4b2e5c",
+  aidreamRevision: "3165453310fa6d42f3b90249a12d956eeebe7636",
   generatorVersion: "1.0.0",
-  packageVersion: "0.59.192",
+  packageVersion: "0.59.193",
   retireWindow: 3
 };
 var MANDATE_KEYS = {
@@ -619,7 +619,7 @@ var MANDATE_KEYS = {
    */
   brand_discovery__offering_roles: "brand_discovery.offering_roles",
   /**
-   * @deprecated retiring since 0.59.192 — no longer declared in
+   * @deprecated retiring since 0.59.193 — no longer declared in
    * aidream. It leaves this union once no snapshot within the last
    * 3 published versions still carries it as active.
    */
@@ -646,7 +646,7 @@ var MANDATE_KEYS = {
 var ALL_MANDATE_KEYS = Object.values(MANDATE_KEYS);
 var RETIRING_MANDATE_KEYS = {
   "brand_discovery.offering_roles": "0.59.0",
-  "coding_session.managed_translation_reference": "0.59.192",
+  "coding_session.managed_translation_reference": "0.59.193",
   "pdf.content_cleaner": "0.59.0",
   "sms.owner_beta": "0.59.0",
   "voice.owner_beta": "0.59.0"

package/dist/models/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // models/index.ts
 var models_exports = {};
 __export(models_exports, {
+  AGENT_AUTHORING_DEFAULT_MODEL_KNOB: () => AGENT_AUTHORING_DEFAULT_MODEL_KNOB,
   CHAT_DEFAULT_MODEL_KNOB: () => CHAT_DEFAULT_MODEL_KNOB,
   CONTENT_TYPES: () => CONTENT_TYPES,
   DEFAULT_CAPABILITIES: () => DEFAULT_CAPABILITIES,
@@ -41,11 +42,13 @@ __export(models_exports, {
   TOP_TIER_COST_RATING: () => TOP_TIER_COST_RATING,
   TOP_TIER_LOCKED_TITLE: () => TOP_TIER_LOCKED_TITLE,
   acceptsTextInstructions: () => acceptsTextInstructions,
+  blendedPrice: () => blendedPrice,
   buildModelClassIndex: () => buildModelClassIndex,
   buildSuccessionIndex: () => buildSuccessionIndex,
   catalogFingerprint: () => catalogFingerprint,
   catalogForApp: () => catalogForApp,
   catalogKindOf: () => catalogKindOf,
+  cheapestAdequateModel: () => cheapestAdequateModel,
   classConfigKey: () => classConfigKey,
   collapseTiersByClass: () => collapseTiersByClass,
   costRatingTier: () => costRatingTier,
@@ -59,6 +62,7 @@ __export(models_exports, {
   fetchCuratedModels: () => fetchCuratedModels,
   findNonCanonicalCapabilityValues: () => findNonCanonicalCapabilityValues,
   fitsMemory: () => fitsMemory,
+  fitsNeed: () => fitsNeed,
   fitsThisComputer: () => fitsThisComputer,
   formatMemoryBytes: () => formatMemoryBytes,
   fromDiscovery: () => fromDiscovery,
@@ -67,6 +71,7 @@ __export(models_exports, {
   groupFeatures: () => groupFeatures,
   hardwareClassesOf: () => hardwareClassesOf,
   hasCompatibleDecisionInteraction: () => hasCompatibleDecisionInteraction,
+  isChatModelCapability: () => isChatModelCapability,
   isContentType: () => isContentType,
   isConversationalModelCapability: () => isConversationalModelCapability,
   isDecisionModelCapability: () => isDecisionModelCapability,
@@ -86,6 +91,7 @@ __export(models_exports, {
   modelClassName: () => modelClassName,
   modelClassPinOf: () => modelClassPinOf,
   modelsForSelectionPurpose: () => modelsForSelectionPurpose,
+  newAgentModelStandInCount: () => newAgentModelStandInCount,
   normalizeArch: () => normalizeArch,
   normalizeModel: () => normalizeModel,
   normalizeModels: () => normalizeModels,
@@ -108,8 +114,10 @@ __export(models_exports, {
   requiredArtifacts: () => requiredArtifacts,
   resetSuccessionLogForTests: () => resetSuccessionLogForTests,
   resolveLiveModelId: () => resolveLiveModelId,
+  resolveNewAgentModelId: () => resolveNewAgentModelId,
   resolvePreferredModelChoice: () => resolvePreferredModelChoice,
   resolveSuccessor: () => resolveSuccessor,
+  seesImages: () => seesImages,
   selectActiveModels: () => selectActiveModels,
   selectActiveModelsReady: () => selectActiveModelsReady,
   selectAllModelOptions: () => selectAllModelOptions,
@@ -139,6 +147,7 @@ __export(models_exports, {
   speedRatingLabel: () => speedRatingLabel,
   speedRatingWord: () => speedRatingWord,
   splitSetProblems: () => splitSetProblems,
+  takesInput: () => takesInput,
   toAuditRecord: () => toAuditRecord,
   validateModelSet: () => validateModelSet,
   withModelClass: () => withModelClass
@@ -2672,3 +2681,77 @@ async function readModelCatalog(client, opts = {}) {
   out.catalog_fingerprint = catalogFingerprint(out);
   return out;
 }
+
+// models/fit.ts
+var featuresOf = (c) => {
+  const f = c.features;
+  if (!f) return [];
+  return Array.isArray(f) ? f : f.raw ?? [];
+};
+function seesImages(c) {
+  return (c.input ?? []).includes("image") || featuresOf(c).includes("vision");
+}
+function takesInput(c, modality) {
+  if (modality === "image") return seesImages(c);
+  return (c.input ?? []).includes(modality);
+}
+var MEDIA_GENERATION_FEATURES = /* @__PURE__ */ new Set(["image_generation", "video_generation", "audio_generation", "music_generation"]);
+function isChatModelCapability(c) {
+  if (c.interaction !== "turn") return false;
+  if (!(c.input ?? []).includes("text")) return false;
+  if (!(c.output ?? []).includes("text")) return false;
+  return !featuresOf(c).some((f) => MEDIA_GENERATION_FEATURES.has(f));
+}
+function fitsNeed(c, need) {
+  for (const m of need.inputs ?? []) if (!takesInput(c, m)) return false;
+  for (const m of need.outputs ?? []) if (!(c.output ?? []).includes(m)) return false;
+  const features = featuresOf(c);
+  for (const f of need.features ?? []) if (!features.includes(f)) return false;
+  if (need.interaction && c.interaction !== need.interaction) return false;
+  if (need.minContextWindow != null && (c.contextWindow ?? 0) < need.minContextWindow) return false;
+  return true;
+}
+function blendedPrice(m, outputWeight = 3) {
+  const i = m.pointsInput;
+  const o = m.pointsOutput;
+  if (i == null && o == null) return null;
+  return ((i ?? o ?? 0) + (o ?? i ?? 0) * outputWeight) / (1 + outputWeight);
+}
+function cheapestAdequateModel(catalog, need, options = {}) {
+  const w = options.outputWeight ?? 3;
+  const fits = catalog.filter((m) => !m.retiredAt && (options.includeDeprecated || !m.isDeprecated) && fitsNeed(m, need));
+  if (fits.length === 0) return null;
+  const rank = (m) => blendedPrice(m, w);
+  return [...fits].sort((a, b) => {
+    const pa = rank(a);
+    const pb = rank(b);
+    if (pa != null && pb != null && pa !== pb) return pa - pb;
+    if (pa != null && pb == null) return -1;
+    if (pa == null && pb != null) return 1;
+    const ca = a.costRating ?? Number.MAX_SAFE_INTEGER;
+    const cb = b.costRating ?? Number.MAX_SAFE_INTEGER;
+    if (ca !== cb) return ca - cb;
+    return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+  })[0];
+}
+
+// models/default-model.ts
+var AGENT_AUTHORING_DEFAULT_MODEL_KNOB = "agents.model_prefs.agent_authoring_default_model";
+var PENDING_KNOB_ROW_MODEL_ID = "617abdcd-79e2-4a4b-be76-4a9960cdffa1";
+var standInCount = 0;
+var newAgentModelStandInCount = () => standInCount;
+async function resolveNewAgentModelId(resolveKnob) {
+  let why;
+  try {
+    const value = await resolveKnob(AGENT_AUTHORING_DEFAULT_MODEL_KNOB);
+    if (typeof value === "string" && value.trim() !== "") return { modelId: value.trim(), standIn: false };
+    why = "has no value (its platform default row is pending)";
+  } catch (error) {
+    why = `could not be read (${error instanceof Error ? error.message : String(error)})`;
+  }
+  standInCount += 1;
+  console.error(
+    `[newAgentModel] STAND-IN: ${AGENT_AUTHORING_DEFAULT_MODEL_KNOB} ${why} \u2014 this new agent starts on ${PENDING_KNOB_ROW_MODEL_ID} (today's model). Set the knob's default to remove this stand-in.`
+  );
+  return { modelId: PENDING_KNOB_ROW_MODEL_ID, standIn: true };
+}

package/dist/models/index.d.cts

@@ -1659,4 +1659,109 @@ declare function catalogFingerprint(catalog: LocalModelCatalog): string;
  */
 declare function readModelCatalog(client: CuratedCatalogClient, opts?: ReadModelCatalogOptions): Promise<LocalModelCatalog>;
 
-export { type AdminOffering, type AdminPricingBand, type ArtifactUse, type AuditCapabilitiesRecord, CHAT_DEFAULT_MODEL_KNOB, CONTENT_TYPES, type CapabilitiesParseContext, type CatalogKindInput, type CatalogModel, type CatalogTier, type CompatStatus, type ContentType, type CuratedCatalogClient, type CuratedModel, type CuratedPresentation, type CuratedRows, type CuratedVariant, DEFAULT_CAPABILITIES, type DecidedBy, type DeviceGraphics, type DeviceHardware, type DiscoveryAmbiguity, type DiscoveryArtifact, type DiscoveryMedia, type DiscoveryResult, type DiscoveryRuntime, type DiscoverySource, type DiscoveryVariant, EMPTY_MODEL_RECORDS, EXCLUDED_REVIEW_STATES, FEATURE_BUCKETS, FEATURE_BUCKET_ORDER, FEATURE_KEYS, FILE_TYPE_QUANT, type FeatureBucket, type FeatureBucketMeta, type FeatureKey, GgufError, type GgufHeader, type GgufRead, type GgufTensor, type GroupedFeatures, type HardwareClass, type HardwareClasses, type HeaderFlag, type HeaderJudgement, type HeaderRefusal, INPUT_MODALITIES, INTERACTION_MODES, type Interaction, type InteractionMode, type LocalArtifact, type LocalCatalogClient, type LocalCatalogQuery, type LocalCompatRow, type LocalModel, type LocalModelCatalog, type LocalPresentation, type LocalRuntime, type LocalRuntimeBuild, type LocalVariant, MAX_SUCCESSION_HOPS, MODEL_CATALOG_KINDS, MODEL_FAVORITE_ENTITY_TYPE, type Modality, type ModelCapabilities, type ModelCatalog, type ModelCatalogClient, type ModelCatalogConfig, type ModelCatalogErrorSink, type ModelCatalogPgError, type ModelCatalogPgResult, type ModelCatalogQuery, type ModelCatalogState, type ModelCatalogVariant, type ModelCatalogVariantState, type ModelClassConfig, type ModelClassEntry, type ModelClassIndex, type ModelDiagnosticEntry, type ModelDiagnosticsSink, type ModelFavorites, type ModelFavoritesCache, type ModelFavoritesClient, type ModelFavoritesConfig, type ModelFavoritesErrorSink, type ModelFavoritesState, type ModelFetchScope, type ModelFileHandle, type ModelFit, type ModelIdentityRow, type ModelJson, type ModelOfferingRow, type ModelOption, type ModelOptionWithLifecycle, type ModelRecord, type ModelRecordFetchType, type ModelRecords, type ModelRecordsClient, type ModelRecordsConfig, type ModelRecordsState, type ModelSelectionPurpose, type ModelSetEnv, type ModelSetFacts, type ModelSetValidation, type NoSelection, OUTPUT_MODALITIES, type OrderedLike, type PreferredModelChoice, type PreferredModelChoicePorts, type PriceTier, type RankedVariant, type ReadModelCatalogOptions, SERVICE_LABEL, SERVICE_LABEL_PLURAL, type SelectDevice, type Selection, type ShardName, type SuccessionClient, type SuccessionIndex, type SuccessionNode, TOP_TIER_COST_RATING, TOP_TIER_LOCKED_TITLE, type VariantDiscovery, type Want, acceptsTextInstructions, buildModelClassIndex, buildSuccessionIndex, catalogFingerprint, catalogForApp, catalogKindOf, classConfigKey, collapseTiersByClass, costRatingTier, costRatingWord, createModelCatalog, createModelFavorites, createModelRecords, curatedList, displayOrderOf, favoriteIdsEqual, fetchCuratedModels, findNonCanonicalCapabilityValues, fitsMemory, fitsThisComputer, formatMemoryBytes, fromDiscovery, ggufEngine, ggufFacts, groupFeatures, hardwareClassesOf, hasCompatibleDecisionInteraction, isContentType, isConversationalModelCapability, isDecisionModelCapability, isFeatureKey, isHelperGguf, isInteractionMode, isListedVariant, isLocalModelCatalog, isManagedAgentModelCapability, isProjectorName, isSupersedable, isTopTierRating, judgeHeaderFacts, mergeAuditRecordIntoCapabilities, missingShards, modelClassKnobFor, modelClassName, modelClassPinOf, modelsForSelectionPurpose, normalizeArch, normalizeModel, normalizeModels, normalizeOs, normalizePromptSettings, orderCatalogGroups, orderCatalogModels, outputFormatControlKey, parseCapabilities, pickProjector, priceTierRating, quantFromName, rankVariants, readCuratedRows, readGgufHeader, readModelCatalog, reconcileModelFavoriteIds, reportModelDiagnostic, requireCanonicalCapabilities, requiredArtifacts, resetSuccessionLogForTests, resolveLiveModelId, resolvePreferredModelChoice, resolveSuccessor, 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, toAuditRecord, validateModelSet, withModelClass };
+/**
+ * `@ai-matrx/agents/models` — THE fit rules: what a model can do for a purpose, read from the
+ * capability data the catalog holds (`capabilities.input / output / features / interaction`), never
+ * from a placement (a presentation shelf, a page) and never from a list of names.
+ *
+ * One capability can live in two shapes in the data: "sees images" is `input` containing `image`
+ * OR the `vision` feature (the audit projection `toAuditRecord` already reads it that way). Every
+ * filter that asks "does it see images" asks `seesImages`, so a model carrying only one of the two
+ * shapes is never dropped by one surface and kept by another.
+ *
+ * Every picker, every scope chip and every knob that names "the cheapest model that can do X"
+ * (`cheapestAdequateModel`) goes through these, so the web, Matrx 2 and the server-side knobs agree.
+ */
+
+/** The capability fields a fit rule reads. A CatalogModel, a ModelCapabilities and a LocalModel's `capabilities` all fit. */
+interface FitCapabilities {
+    readonly input?: readonly string[];
+    readonly output?: readonly string[];
+    /** Raw feature keys, or the picker's grouped features (its `raw` keeps every key). */
+    readonly features?: readonly string[] | Pick<GroupedFeatures, "raw">;
+    readonly interaction?: string;
+}
+/** Sees images: `image` input OR the `vision` feature (both shapes the data uses). */
+declare function seesImages(c: FitCapabilities): boolean;
+/** Takes this modality as input. `image` reads both shapes (`seesImages`). */
+declare function takesInput(c: FitCapabilities, modality: string): boolean;
+/**
+ * Fit for a CHAT turn: an ordinary turn model that takes text in and gives text out, whose job is not
+ * making media (a music or image generator that also returns a caption is not a chat model). Speech-to-text,
+ * embedding, extraction, realtime voice, decision holders and provider-managed agents are out.
+ */
+declare function isChatModelCapability(c: FitCapabilities): boolean;
+/** What a job needs from a model. Every listed item is required. */
+interface ModelNeed {
+    /** Input modalities it must take (`image` = sees images, both shapes). */
+    readonly inputs?: readonly string[];
+    /** Output modalities it must give. */
+    readonly outputs?: readonly string[];
+    /** Raw feature keys it must carry (e.g. `function_calling`, `structured_output`). */
+    readonly features?: readonly string[];
+    /** Required interaction mode (e.g. `turn`). Absent = any. */
+    readonly interaction?: string;
+    /** Minimum context window in tokens. */
+    readonly minContextWindow?: number;
+}
+/** Does the model meet every item of the need? */
+declare function fitsNeed(c: FitCapabilities & {
+    readonly contextWindow?: number | null;
+}, need: ModelNeed): boolean;
+/** The catalog fields `cheapestAdequateModel` reads (a picker `CatalogModel` fits as-is). */
+interface PricedCatalogModel extends FitCapabilities {
+    readonly id: string;
+    readonly name: string;
+    readonly contextWindow?: number | null;
+    /** Points per 1M input tokens (the catalog's price). */
+    readonly pointsInput?: number | null;
+    /** Points per 1M output tokens (the catalog's price). */
+    readonly pointsOutput?: number | null;
+    /** Curated 1-6 cost rating: the tie-break, and the price when no points are set. */
+    readonly costRating?: number | null;
+    readonly isDeprecated?: boolean;
+    readonly retiredAt?: string | null;
+}
+interface CheapestAdequateOptions {
+    /** Weight of output price against input price (output tokens usually dominate). Default 3 (1 in : 3 out). */
+    readonly outputWeight?: number;
+    /** Allow deprecated models. Default false (retired models are never chosen). */
+    readonly includeDeprecated?: boolean;
+}
+/** The blended price a model is ranked by, or null when the catalog holds no price for it. */
+declare function blendedPrice(m: PricedCatalogModel, outputWeight?: number): number | null;
+/**
+ * THE cheapest model in a catalog that meets `need`, by the catalog's own prices (points per 1M
+ * tokens, output weighted). A model with no price ranks after every priced one, by cost rating; ties
+ * break on cost rating then name (stable). Retired models never; deprecated only when asked. Null when
+ * nothing fits — the caller says so; there is no built-in fallback.
+ */
+declare function cheapestAdequateModel<T extends PricedCatalogModel>(catalog: readonly T[], need: ModelNeed, options?: CheapestAdequateOptions): T | null;
+
+/**
+ * `@ai-matrx/agents/models` — THE model a new agent starts on comes from a knob, never a constant:
+ * `agents.model_prefs.agent_authoring_default_model` (organization → person → device ladder, through the
+ * host's knob port). Every "make me an agent" path (blank agent, quick agent, templates, the web's manual
+ * create and system-agent create) asks `resolveNewAgentModelId`.
+ *
+ * KNOB ROW PENDING (2026-10-21): the register row exists with `default_value = null`. Until its default is
+ * set to today's model (the SQL is with the owner), an unset knob answers the stand-in below — LOUDLY, every
+ * time, naming the knob — so creating an agent keeps working exactly as before. When the row lands the stand-in
+ * never fires; delete it then. This file is the ONE place a model id literal may appear in shared runtime code
+ * (guard: apps/shared/scripts/check-no-model-literals.mjs).
+ */
+declare const AGENT_AUTHORING_DEFAULT_MODEL_KNOB = "agents.model_prefs.agent_authoring_default_model";
+interface NewAgentModel {
+    modelId: string;
+    /** True when the knob held no value and the pending-row stand-in answered (it screamed). */
+    standIn: boolean;
+}
+/** How many times the stand-in answered in this process (tests, diagnostics). */
+declare const newAgentModelStandInCount: () => number;
+/**
+ * The model a new agent starts on. `resolveKnob(fullKey)` is the host's effective-knob read. A knob value
+ * that is a non-empty string wins; an unset knob, or a knob read that fails, answers the stand-in and says so.
+ */
+declare function resolveNewAgentModelId(resolveKnob: (fullKey: string) => Promise<unknown>): Promise<NewAgentModel>;
+
+export { AGENT_AUTHORING_DEFAULT_MODEL_KNOB, type AdminOffering, type AdminPricingBand, type ArtifactUse, type AuditCapabilitiesRecord, CHAT_DEFAULT_MODEL_KNOB, CONTENT_TYPES, type CapabilitiesParseContext, type CatalogKindInput, type CatalogModel, type CatalogTier, type CheapestAdequateOptions, type CompatStatus, type ContentType, type CuratedCatalogClient, type CuratedModel, type CuratedPresentation, type CuratedRows, type CuratedVariant, DEFAULT_CAPABILITIES, type DecidedBy, type DeviceGraphics, type DeviceHardware, type DiscoveryAmbiguity, type DiscoveryArtifact, type DiscoveryMedia, type DiscoveryResult, type DiscoveryRuntime, type DiscoverySource, type DiscoveryVariant, EMPTY_MODEL_RECORDS, EXCLUDED_REVIEW_STATES, FEATURE_BUCKETS, FEATURE_BUCKET_ORDER, FEATURE_KEYS, FILE_TYPE_QUANT, type FeatureBucket, type FeatureBucketMeta, type FeatureKey, type FitCapabilities, GgufError, type GgufHeader, type GgufRead, type GgufTensor, type GroupedFeatures, type HardwareClass, type HardwareClasses, type HeaderFlag, type HeaderJudgement, type HeaderRefusal, INPUT_MODALITIES, INTERACTION_MODES, type Interaction, type InteractionMode, type LocalArtifact, type LocalCatalogClient, type LocalCatalogQuery, type LocalCompatRow, type LocalModel, type LocalModelCatalog, type LocalPresentation, type LocalRuntime, type LocalRuntimeBuild, type LocalVariant, MAX_SUCCESSION_HOPS, MODEL_CATALOG_KINDS, MODEL_FAVORITE_ENTITY_TYPE, type Modality, type ModelCapabilities, type ModelCatalog, type ModelCatalogClient, type ModelCatalogConfig, type ModelCatalogErrorSink, type ModelCatalogPgError, type ModelCatalogPgResult, type ModelCatalogQuery, type ModelCatalogState, type ModelCatalogVariant, type ModelCatalogVariantState, type ModelClassConfig, type ModelClassEntry, type ModelClassIndex, type ModelDiagnosticEntry, type ModelDiagnosticsSink, type ModelFavorites, type ModelFavoritesCache, type ModelFavoritesClient, type ModelFavoritesConfig, type ModelFavoritesErrorSink, type ModelFavoritesState, type ModelFetchScope, type ModelFileHandle, type ModelFit, type ModelIdentityRow, type ModelJson, type ModelNeed, type ModelOfferingRow, type ModelOption, type ModelOptionWithLifecycle, type ModelRecord, type ModelRecordFetchType, type ModelRecords, type ModelRecordsClient, type ModelRecordsConfig, type ModelRecordsState, type ModelSelectionPurpose, type ModelSetEnv, type ModelSetFacts, type ModelSetValidation, type NewAgentModel, type NoSelection, OUTPUT_MODALITIES, type OrderedLike, type PreferredModelChoice, type PreferredModelChoicePorts, type PriceTier, type PricedCatalogModel, type RankedVariant, type ReadModelCatalogOptions, SERVICE_LABEL, SERVICE_LABEL_PLURAL, type SelectDevice, type Selection, type ShardName, type SuccessionClient, type SuccessionIndex, type SuccessionNode, TOP_TIER_COST_RATING, TOP_TIER_LOCKED_TITLE, type VariantDiscovery, type Want, acceptsTextInstructions, blendedPrice, buildModelClassIndex, buildSuccessionIndex, catalogFingerprint, catalogForApp, catalogKindOf, cheapestAdequateModel, classConfigKey, collapseTiersByClass, costRatingTier, costRatingWord, createModelCatalog, createModelFavorites, createModelRecords, curatedList, displayOrderOf, favoriteIdsEqual, fetchCuratedModels, findNonCanonicalCapabilityValues, fitsMemory, fitsNeed, fitsThisComputer, formatMemoryBytes, fromDiscovery, ggufEngine, ggufFacts, groupFeatures, hardwareClassesOf, hasCompatibleDecisionInteraction, isChatModelCapability, isContentType, isConversationalModelCapability, isDecisionModelCapability, isFeatureKey, isHelperGguf, isInteractionMode, isListedVariant, isLocalModelCatalog, isManagedAgentModelCapability, isProjectorName, isSupersedable, isTopTierRating, judgeHeaderFacts, mergeAuditRecordIntoCapabilities, missingShards, modelClassKnobFor, modelClassName, modelClassPinOf, modelsForSelectionPurpose, newAgentModelStandInCount, normalizeArch, normalizeModel, normalizeModels, normalizeOs, normalizePromptSettings, orderCatalogGroups, orderCatalogModels, outputFormatControlKey, parseCapabilities, pickProjector, priceTierRating, quantFromName, rankVariants, readCuratedRows, readGgufHeader, readModelCatalog, reconcileModelFavoriteIds, reportModelDiagnostic, requireCanonicalCapabilities, requiredArtifacts, resetSuccessionLogForTests, resolveLiveModelId, resolveNewAgentModelId, resolvePreferredModelChoice, resolveSuccessor, seesImages, selectActiveModels, selectActiveModelsReady, selectAllModelOptions, selectAllModels, selectAllModelsReady, selectDeprecatedModels, selectDeprecatedModelsReady, selectModelById, selectModelClassConfig, selectModelClassName, selectModelControls, selectModelDetailError, selectModelFetchType, selectModelFullyLoaded, selectModelIdentityById, selectModelIdentityLookupStatus, selectModelLabelById, selectModelLabelWithClass, selectModelNameById, selectModelOptions, selectVariant, serviceCountLabel, setModelDiagnosticsSink, shapeCuratedModels, shardFileName, shardName, speedRatingLabel, speedRatingWord, splitSetProblems, takesInput, toAuditRecord, validateModelSet, withModelClass };

package/dist/models/index.d.ts

@@ -1659,4 +1659,109 @@ declare function catalogFingerprint(catalog: LocalModelCatalog): string;
  */
 declare function readModelCatalog(client: CuratedCatalogClient, opts?: ReadModelCatalogOptions): Promise<LocalModelCatalog>;
 
-export { type AdminOffering, type AdminPricingBand, type ArtifactUse, type AuditCapabilitiesRecord, CHAT_DEFAULT_MODEL_KNOB, CONTENT_TYPES, type CapabilitiesParseContext, type CatalogKindInput, type CatalogModel, type CatalogTier, type CompatStatus, type ContentType, type CuratedCatalogClient, type CuratedModel, type CuratedPresentation, type CuratedRows, type CuratedVariant, DEFAULT_CAPABILITIES, type DecidedBy, type DeviceGraphics, type DeviceHardware, type DiscoveryAmbiguity, type DiscoveryArtifact, type DiscoveryMedia, type DiscoveryResult, type DiscoveryRuntime, type DiscoverySource, type DiscoveryVariant, EMPTY_MODEL_RECORDS, EXCLUDED_REVIEW_STATES, FEATURE_BUCKETS, FEATURE_BUCKET_ORDER, FEATURE_KEYS, FILE_TYPE_QUANT, type FeatureBucket, type FeatureBucketMeta, type FeatureKey, GgufError, type GgufHeader, type GgufRead, type GgufTensor, type GroupedFeatures, type HardwareClass, type HardwareClasses, type HeaderFlag, type HeaderJudgement, type HeaderRefusal, INPUT_MODALITIES, INTERACTION_MODES, type Interaction, type InteractionMode, type LocalArtifact, type LocalCatalogClient, type LocalCatalogQuery, type LocalCompatRow, type LocalModel, type LocalModelCatalog, type LocalPresentation, type LocalRuntime, type LocalRuntimeBuild, type LocalVariant, MAX_SUCCESSION_HOPS, MODEL_CATALOG_KINDS, MODEL_FAVORITE_ENTITY_TYPE, type Modality, type ModelCapabilities, type ModelCatalog, type ModelCatalogClient, type ModelCatalogConfig, type ModelCatalogErrorSink, type ModelCatalogPgError, type ModelCatalogPgResult, type ModelCatalogQuery, type ModelCatalogState, type ModelCatalogVariant, type ModelCatalogVariantState, type ModelClassConfig, type ModelClassEntry, type ModelClassIndex, type ModelDiagnosticEntry, type ModelDiagnosticsSink, type ModelFavorites, type ModelFavoritesCache, type ModelFavoritesClient, type ModelFavoritesConfig, type ModelFavoritesErrorSink, type ModelFavoritesState, type ModelFetchScope, type ModelFileHandle, type ModelFit, type ModelIdentityRow, type ModelJson, type ModelOfferingRow, type ModelOption, type ModelOptionWithLifecycle, type ModelRecord, type ModelRecordFetchType, type ModelRecords, type ModelRecordsClient, type ModelRecordsConfig, type ModelRecordsState, type ModelSelectionPurpose, type ModelSetEnv, type ModelSetFacts, type ModelSetValidation, type NoSelection, OUTPUT_MODALITIES, type OrderedLike, type PreferredModelChoice, type PreferredModelChoicePorts, type PriceTier, type RankedVariant, type ReadModelCatalogOptions, SERVICE_LABEL, SERVICE_LABEL_PLURAL, type SelectDevice, type Selection, type ShardName, type SuccessionClient, type SuccessionIndex, type SuccessionNode, TOP_TIER_COST_RATING, TOP_TIER_LOCKED_TITLE, type VariantDiscovery, type Want, acceptsTextInstructions, buildModelClassIndex, buildSuccessionIndex, catalogFingerprint, catalogForApp, catalogKindOf, classConfigKey, collapseTiersByClass, costRatingTier, costRatingWord, createModelCatalog, createModelFavorites, createModelRecords, curatedList, displayOrderOf, favoriteIdsEqual, fetchCuratedModels, findNonCanonicalCapabilityValues, fitsMemory, fitsThisComputer, formatMemoryBytes, fromDiscovery, ggufEngine, ggufFacts, groupFeatures, hardwareClassesOf, hasCompatibleDecisionInteraction, isContentType, isConversationalModelCapability, isDecisionModelCapability, isFeatureKey, isHelperGguf, isInteractionMode, isListedVariant, isLocalModelCatalog, isManagedAgentModelCapability, isProjectorName, isSupersedable, isTopTierRating, judgeHeaderFacts, mergeAuditRecordIntoCapabilities, missingShards, modelClassKnobFor, modelClassName, modelClassPinOf, modelsForSelectionPurpose, normalizeArch, normalizeModel, normalizeModels, normalizeOs, normalizePromptSettings, orderCatalogGroups, orderCatalogModels, outputFormatControlKey, parseCapabilities, pickProjector, priceTierRating, quantFromName, rankVariants, readCuratedRows, readGgufHeader, readModelCatalog, reconcileModelFavoriteIds, reportModelDiagnostic, requireCanonicalCapabilities, requiredArtifacts, resetSuccessionLogForTests, resolveLiveModelId, resolvePreferredModelChoice, resolveSuccessor, 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, toAuditRecord, validateModelSet, withModelClass };
+/**
+ * `@ai-matrx/agents/models` — THE fit rules: what a model can do for a purpose, read from the
+ * capability data the catalog holds (`capabilities.input / output / features / interaction`), never
+ * from a placement (a presentation shelf, a page) and never from a list of names.
+ *
+ * One capability can live in two shapes in the data: "sees images" is `input` containing `image`
+ * OR the `vision` feature (the audit projection `toAuditRecord` already reads it that way). Every
+ * filter that asks "does it see images" asks `seesImages`, so a model carrying only one of the two
+ * shapes is never dropped by one surface and kept by another.
+ *
+ * Every picker, every scope chip and every knob that names "the cheapest model that can do X"
+ * (`cheapestAdequateModel`) goes through these, so the web, Matrx 2 and the server-side knobs agree.
+ */
+
+/** The capability fields a fit rule reads. A CatalogModel, a ModelCapabilities and a LocalModel's `capabilities` all fit. */
+interface FitCapabilities {
+    readonly input?: readonly string[];
+    readonly output?: readonly string[];
+    /** Raw feature keys, or the picker's grouped features (its `raw` keeps every key). */
+    readonly features?: readonly string[] | Pick<GroupedFeatures, "raw">;
+    readonly interaction?: string;
+}
+/** Sees images: `image` input OR the `vision` feature (both shapes the data uses). */
+declare function seesImages(c: FitCapabilities): boolean;
+/** Takes this modality as input. `image` reads both shapes (`seesImages`). */
+declare function takesInput(c: FitCapabilities, modality: string): boolean;
+/**
+ * Fit for a CHAT turn: an ordinary turn model that takes text in and gives text out, whose job is not
+ * making media (a music or image generator that also returns a caption is not a chat model). Speech-to-text,
+ * embedding, extraction, realtime voice, decision holders and provider-managed agents are out.
+ */
+declare function isChatModelCapability(c: FitCapabilities): boolean;
+/** What a job needs from a model. Every listed item is required. */
+interface ModelNeed {
+    /** Input modalities it must take (`image` = sees images, both shapes). */
+    readonly inputs?: readonly string[];
+    /** Output modalities it must give. */
+    readonly outputs?: readonly string[];
+    /** Raw feature keys it must carry (e.g. `function_calling`, `structured_output`). */
+    readonly features?: readonly string[];
+    /** Required interaction mode (e.g. `turn`). Absent = any. */
+    readonly interaction?: string;
+    /** Minimum context window in tokens. */
+    readonly minContextWindow?: number;
+}
+/** Does the model meet every item of the need? */
+declare function fitsNeed(c: FitCapabilities & {
+    readonly contextWindow?: number | null;
+}, need: ModelNeed): boolean;
+/** The catalog fields `cheapestAdequateModel` reads (a picker `CatalogModel` fits as-is). */
+interface PricedCatalogModel extends FitCapabilities {
+    readonly id: string;
+    readonly name: string;
+    readonly contextWindow?: number | null;
+    /** Points per 1M input tokens (the catalog's price). */
+    readonly pointsInput?: number | null;
+    /** Points per 1M output tokens (the catalog's price). */
+    readonly pointsOutput?: number | null;
+    /** Curated 1-6 cost rating: the tie-break, and the price when no points are set. */
+    readonly costRating?: number | null;
+    readonly isDeprecated?: boolean;
+    readonly retiredAt?: string | null;
+}
+interface CheapestAdequateOptions {
+    /** Weight of output price against input price (output tokens usually dominate). Default 3 (1 in : 3 out). */
+    readonly outputWeight?: number;
+    /** Allow deprecated models. Default false (retired models are never chosen). */
+    readonly includeDeprecated?: boolean;
+}
+/** The blended price a model is ranked by, or null when the catalog holds no price for it. */
+declare function blendedPrice(m: PricedCatalogModel, outputWeight?: number): number | null;
+/**
+ * THE cheapest model in a catalog that meets `need`, by the catalog's own prices (points per 1M
+ * tokens, output weighted). A model with no price ranks after every priced one, by cost rating; ties
+ * break on cost rating then name (stable). Retired models never; deprecated only when asked. Null when
+ * nothing fits — the caller says so; there is no built-in fallback.
+ */
+declare function cheapestAdequateModel<T extends PricedCatalogModel>(catalog: readonly T[], need: ModelNeed, options?: CheapestAdequateOptions): T | null;
+
+/**
+ * `@ai-matrx/agents/models` — THE model a new agent starts on comes from a knob, never a constant:
+ * `agents.model_prefs.agent_authoring_default_model` (organization → person → device ladder, through the
+ * host's knob port). Every "make me an agent" path (blank agent, quick agent, templates, the web's manual
+ * create and system-agent create) asks `resolveNewAgentModelId`.
+ *
+ * KNOB ROW PENDING (2026-10-21): the register row exists with `default_value = null`. Until its default is
+ * set to today's model (the SQL is with the owner), an unset knob answers the stand-in below — LOUDLY, every
+ * time, naming the knob — so creating an agent keeps working exactly as before. When the row lands the stand-in
+ * never fires; delete it then. This file is the ONE place a model id literal may appear in shared runtime code
+ * (guard: apps/shared/scripts/check-no-model-literals.mjs).
+ */
+declare const AGENT_AUTHORING_DEFAULT_MODEL_KNOB = "agents.model_prefs.agent_authoring_default_model";
+interface NewAgentModel {
+    modelId: string;
+    /** True when the knob held no value and the pending-row stand-in answered (it screamed). */
+    standIn: boolean;
+}
+/** How many times the stand-in answered in this process (tests, diagnostics). */
+declare const newAgentModelStandInCount: () => number;
+/**
+ * The model a new agent starts on. `resolveKnob(fullKey)` is the host's effective-knob read. A knob value
+ * that is a non-empty string wins; an unset knob, or a knob read that fails, answers the stand-in and says so.
+ */
+declare function resolveNewAgentModelId(resolveKnob: (fullKey: string) => Promise<unknown>): Promise<NewAgentModel>;
+
+export { AGENT_AUTHORING_DEFAULT_MODEL_KNOB, type AdminOffering, type AdminPricingBand, type ArtifactUse, type AuditCapabilitiesRecord, CHAT_DEFAULT_MODEL_KNOB, CONTENT_TYPES, type CapabilitiesParseContext, type CatalogKindInput, type CatalogModel, type CatalogTier, type CheapestAdequateOptions, type CompatStatus, type ContentType, type CuratedCatalogClient, type CuratedModel, type CuratedPresentation, type CuratedRows, type CuratedVariant, DEFAULT_CAPABILITIES, type DecidedBy, type DeviceGraphics, type DeviceHardware, type DiscoveryAmbiguity, type DiscoveryArtifact, type DiscoveryMedia, type DiscoveryResult, type DiscoveryRuntime, type DiscoverySource, type DiscoveryVariant, EMPTY_MODEL_RECORDS, EXCLUDED_REVIEW_STATES, FEATURE_BUCKETS, FEATURE_BUCKET_ORDER, FEATURE_KEYS, FILE_TYPE_QUANT, type FeatureBucket, type FeatureBucketMeta, type FeatureKey, type FitCapabilities, GgufError, type GgufHeader, type GgufRead, type GgufTensor, type GroupedFeatures, type HardwareClass, type HardwareClasses, type HeaderFlag, type HeaderJudgement, type HeaderRefusal, INPUT_MODALITIES, INTERACTION_MODES, type Interaction, type InteractionMode, type LocalArtifact, type LocalCatalogClient, type LocalCatalogQuery, type LocalCompatRow, type LocalModel, type LocalModelCatalog, type LocalPresentation, type LocalRuntime, type LocalRuntimeBuild, type LocalVariant, MAX_SUCCESSION_HOPS, MODEL_CATALOG_KINDS, MODEL_FAVORITE_ENTITY_TYPE, type Modality, type ModelCapabilities, type ModelCatalog, type ModelCatalogClient, type ModelCatalogConfig, type ModelCatalogErrorSink, type ModelCatalogPgError, type ModelCatalogPgResult, type ModelCatalogQuery, type ModelCatalogState, type ModelCatalogVariant, type ModelCatalogVariantState, type ModelClassConfig, type ModelClassEntry, type ModelClassIndex, type ModelDiagnosticEntry, type ModelDiagnosticsSink, type ModelFavorites, type ModelFavoritesCache, type ModelFavoritesClient, type ModelFavoritesConfig, type ModelFavoritesErrorSink, type ModelFavoritesState, type ModelFetchScope, type ModelFileHandle, type ModelFit, type ModelIdentityRow, type ModelJson, type ModelNeed, type ModelOfferingRow, type ModelOption, type ModelOptionWithLifecycle, type ModelRecord, type ModelRecordFetchType, type ModelRecords, type ModelRecordsClient, type ModelRecordsConfig, type ModelRecordsState, type ModelSelectionPurpose, type ModelSetEnv, type ModelSetFacts, type ModelSetValidation, type NewAgentModel, type NoSelection, OUTPUT_MODALITIES, type OrderedLike, type PreferredModelChoice, type PreferredModelChoicePorts, type PriceTier, type PricedCatalogModel, type RankedVariant, type ReadModelCatalogOptions, SERVICE_LABEL, SERVICE_LABEL_PLURAL, type SelectDevice, type Selection, type ShardName, type SuccessionClient, type SuccessionIndex, type SuccessionNode, TOP_TIER_COST_RATING, TOP_TIER_LOCKED_TITLE, type VariantDiscovery, type Want, acceptsTextInstructions, blendedPrice, buildModelClassIndex, buildSuccessionIndex, catalogFingerprint, catalogForApp, catalogKindOf, cheapestAdequateModel, classConfigKey, collapseTiersByClass, costRatingTier, costRatingWord, createModelCatalog, createModelFavorites, createModelRecords, curatedList, displayOrderOf, favoriteIdsEqual, fetchCuratedModels, findNonCanonicalCapabilityValues, fitsMemory, fitsNeed, fitsThisComputer, formatMemoryBytes, fromDiscovery, ggufEngine, ggufFacts, groupFeatures, hardwareClassesOf, hasCompatibleDecisionInteraction, isChatModelCapability, isContentType, isConversationalModelCapability, isDecisionModelCapability, isFeatureKey, isHelperGguf, isInteractionMode, isListedVariant, isLocalModelCatalog, isManagedAgentModelCapability, isProjectorName, isSupersedable, isTopTierRating, judgeHeaderFacts, mergeAuditRecordIntoCapabilities, missingShards, modelClassKnobFor, modelClassName, modelClassPinOf, modelsForSelectionPurpose, newAgentModelStandInCount, normalizeArch, normalizeModel, normalizeModels, normalizeOs, normalizePromptSettings, orderCatalogGroups, orderCatalogModels, outputFormatControlKey, parseCapabilities, pickProjector, priceTierRating, quantFromName, rankVariants, readCuratedRows, readGgufHeader, readModelCatalog, reconcileModelFavoriteIds, reportModelDiagnostic, requireCanonicalCapabilities, requiredArtifacts, resetSuccessionLogForTests, resolveLiveModelId, resolveNewAgentModelId, resolvePreferredModelChoice, resolveSuccessor, seesImages, selectActiveModels, selectActiveModelsReady, selectAllModelOptions, selectAllModels, selectAllModelsReady, selectDeprecatedModels, selectDeprecatedModelsReady, selectModelById, selectModelClassConfig, selectModelClassName, selectModelControls, selectModelDetailError, selectModelFetchType, selectModelFullyLoaded, selectModelIdentityById, selectModelIdentityLookupStatus, selectModelLabelById, selectModelLabelWithClass, selectModelNameById, selectModelOptions, selectVariant, serviceCountLabel, setModelDiagnosticsSink, shapeCuratedModels, shardFileName, shardName, speedRatingLabel, speedRatingWord, splitSetProblems, takesInput, toAuditRecord, validateModelSet, withModelClass };

package/dist/models/index.js

@@ -2525,7 +2525,82 @@ async function readModelCatalog(client, opts = {}) {
   out.catalog_fingerprint = catalogFingerprint(out);
   return out;
 }
+
+// models/fit.ts
+var featuresOf = (c) => {
+  const f = c.features;
+  if (!f) return [];
+  return Array.isArray(f) ? f : f.raw ?? [];
+};
+function seesImages(c) {
+  return (c.input ?? []).includes("image") || featuresOf(c).includes("vision");
+}
+function takesInput(c, modality) {
+  if (modality === "image") return seesImages(c);
+  return (c.input ?? []).includes(modality);
+}
+var MEDIA_GENERATION_FEATURES = /* @__PURE__ */ new Set(["image_generation", "video_generation", "audio_generation", "music_generation"]);
+function isChatModelCapability(c) {
+  if (c.interaction !== "turn") return false;
+  if (!(c.input ?? []).includes("text")) return false;
+  if (!(c.output ?? []).includes("text")) return false;
+  return !featuresOf(c).some((f) => MEDIA_GENERATION_FEATURES.has(f));
+}
+function fitsNeed(c, need) {
+  for (const m of need.inputs ?? []) if (!takesInput(c, m)) return false;
+  for (const m of need.outputs ?? []) if (!(c.output ?? []).includes(m)) return false;
+  const features = featuresOf(c);
+  for (const f of need.features ?? []) if (!features.includes(f)) return false;
+  if (need.interaction && c.interaction !== need.interaction) return false;
+  if (need.minContextWindow != null && (c.contextWindow ?? 0) < need.minContextWindow) return false;
+  return true;
+}
+function blendedPrice(m, outputWeight = 3) {
+  const i = m.pointsInput;
+  const o = m.pointsOutput;
+  if (i == null && o == null) return null;
+  return ((i ?? o ?? 0) + (o ?? i ?? 0) * outputWeight) / (1 + outputWeight);
+}
+function cheapestAdequateModel(catalog, need, options = {}) {
+  const w = options.outputWeight ?? 3;
+  const fits = catalog.filter((m) => !m.retiredAt && (options.includeDeprecated || !m.isDeprecated) && fitsNeed(m, need));
+  if (fits.length === 0) return null;
+  const rank = (m) => blendedPrice(m, w);
+  return [...fits].sort((a, b) => {
+    const pa = rank(a);
+    const pb = rank(b);
+    if (pa != null && pb != null && pa !== pb) return pa - pb;
+    if (pa != null && pb == null) return -1;
+    if (pa == null && pb != null) return 1;
+    const ca = a.costRating ?? Number.MAX_SAFE_INTEGER;
+    const cb = b.costRating ?? Number.MAX_SAFE_INTEGER;
+    if (ca !== cb) return ca - cb;
+    return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+  })[0];
+}
+
+// models/default-model.ts
+var AGENT_AUTHORING_DEFAULT_MODEL_KNOB = "agents.model_prefs.agent_authoring_default_model";
+var PENDING_KNOB_ROW_MODEL_ID = "617abdcd-79e2-4a4b-be76-4a9960cdffa1";
+var standInCount = 0;
+var newAgentModelStandInCount = () => standInCount;
+async function resolveNewAgentModelId(resolveKnob) {
+  let why;
+  try {
+    const value = await resolveKnob(AGENT_AUTHORING_DEFAULT_MODEL_KNOB);
+    if (typeof value === "string" && value.trim() !== "") return { modelId: value.trim(), standIn: false };
+    why = "has no value (its platform default row is pending)";
+  } catch (error) {
+    why = `could not be read (${error instanceof Error ? error.message : String(error)})`;
+  }
+  standInCount += 1;
+  console.error(
+    `[newAgentModel] STAND-IN: ${AGENT_AUTHORING_DEFAULT_MODEL_KNOB} ${why} \u2014 this new agent starts on ${PENDING_KNOB_ROW_MODEL_ID} (today's model). Set the knob's default to remove this stand-in.`
+  );
+  return { modelId: PENDING_KNOB_ROW_MODEL_ID, standIn: true };
+}
 export {
+  AGENT_AUTHORING_DEFAULT_MODEL_KNOB,
   CHAT_DEFAULT_MODEL_KNOB,
   CONTENT_TYPES,
   DEFAULT_CAPABILITIES,
@@ -2547,11 +2622,13 @@ export {
   TOP_TIER_COST_RATING,
   TOP_TIER_LOCKED_TITLE,
   acceptsTextInstructions,
+  blendedPrice,
   buildModelClassIndex,
   buildSuccessionIndex,
   catalogFingerprint,
   catalogForApp,
   catalogKindOf,
+  cheapestAdequateModel,
   classConfigKey,
   collapseTiersByClass,
   costRatingTier,
@@ -2565,6 +2642,7 @@ export {
   fetchCuratedModels,
   findNonCanonicalCapabilityValues,
   fitsMemory,
+  fitsNeed,
   fitsThisComputer,
   formatMemoryBytes,
   fromDiscovery,
@@ -2573,6 +2651,7 @@ export {
   groupFeatures,
   hardwareClassesOf,
   hasCompatibleDecisionInteraction,
+  isChatModelCapability,
   isContentType,
   isConversationalModelCapability,
   isDecisionModelCapability,
@@ -2592,6 +2671,7 @@ export {
   modelClassName,
   modelClassPinOf,
   modelsForSelectionPurpose,
+  newAgentModelStandInCount,
   normalizeArch,
   normalizeModel,
   normalizeModels,
@@ -2614,8 +2694,10 @@ export {
   requiredArtifacts,
   resetSuccessionLogForTests,
   resolveLiveModelId,
+  resolveNewAgentModelId,
   resolvePreferredModelChoice,
   resolveSuccessor,
+  seesImages,
   selectActiveModels,
   selectActiveModelsReady,
   selectAllModelOptions,
@@ -2645,6 +2727,7 @@ export {
   speedRatingLabel,
   speedRatingWord,
   splitSetProblems,
+  takesInput,
   toAuditRecord,
   validateModelSet,
   withModelClass

package/dist/models/react/index.cjs

@@ -446,6 +446,27 @@ function resolveSuccessor(modelId, index) {
   return modelId;
 }
 
+// models/fit.ts
+var featuresOf = (c) => {
+  const f = c.features;
+  if (!f) return [];
+  return Array.isArray(f) ? f : f.raw ?? [];
+};
+function seesImages(c) {
+  return (c.input ?? []).includes("image") || featuresOf(c).includes("vision");
+}
+function takesInput(c, modality) {
+  if (modality === "image") return seesImages(c);
+  return (c.input ?? []).includes(modality);
+}
+var MEDIA_GENERATION_FEATURES = /* @__PURE__ */ new Set(["image_generation", "video_generation", "audio_generation", "music_generation"]);
+function isChatModelCapability(c) {
+  if (c.interaction !== "turn") return false;
+  if (!(c.input ?? []).includes("text")) return false;
+  if (!(c.output ?? []).includes("text")) return false;
+  return !featuresOf(c).some((f) => MEDIA_GENERATION_FEATURES.has(f));
+}
+
 // models/catalog/types.ts
 var INPUT_MODALITIES = ["text", "image", "audio", "video"];
 var OUTPUT_MODALITIES = [
@@ -1635,6 +1656,7 @@ function ModelListDropdown({
     ].sort((a, b) => a.localeCompare(b)),
     [eligibleModels]
   );
+  const chatFitApplies = effectiveSelectionPurpose === "chat" && !(outputModalities ?? []).some((o) => o !== "text");
   const filtered = (0, import_react2.useMemo)(() => {
     const q = query.trim().toLowerCase();
     const hasAvailable = (m) => (m.admin?.offerings ?? []).some((o) => o.isAvailable);
@@ -1646,6 +1668,7 @@ function ModelListDropdown({
         return false;
       if (effectiveSelectionPurpose === "chat" && isManagedAgentModelCapability(m))
         return false;
+      if (chatFitApplies && !isChatModelCapability(m)) return false;
       if (tab === "favorites" && !favoriteSet.has(m.id)) return false;
       const haystack = [
         m.name,
@@ -1685,7 +1708,7 @@ function ModelListDropdown({
       if (filters.premium !== "any") {
         if (filters.premium === "yes" !== m.isPremium) return false;
       }
-      for (const m2 of filters.input) if (!m.input.includes(m2)) return false;
+      for (const m2 of filters.input) if (!takesInput(m, m2)) return false;
       const outputSatisfied = (want) => m.output.includes(want) || effectiveSelectionPurpose === "agent" && isDecision && want === "text";
       for (const m2 of filters.output) if (!outputSatisfied(m2)) return false;
       for (const b of filters.features)
@@ -1751,6 +1774,7 @@ function ModelListDropdown({
     variant,
     priorityModelSet,
     effectiveSelectionPurpose,
+    chatFitApplies,
     hiddenModelIds,
     value,
     successionIndex

package/dist/models/react/index.js

@@ -428,6 +428,27 @@ function resolveSuccessor(modelId, index) {
   return modelId;
 }
 
+// models/fit.ts
+var featuresOf = (c) => {
+  const f = c.features;
+  if (!f) return [];
+  return Array.isArray(f) ? f : f.raw ?? [];
+};
+function seesImages(c) {
+  return (c.input ?? []).includes("image") || featuresOf(c).includes("vision");
+}
+function takesInput(c, modality) {
+  if (modality === "image") return seesImages(c);
+  return (c.input ?? []).includes(modality);
+}
+var MEDIA_GENERATION_FEATURES = /* @__PURE__ */ new Set(["image_generation", "video_generation", "audio_generation", "music_generation"]);
+function isChatModelCapability(c) {
+  if (c.interaction !== "turn") return false;
+  if (!(c.input ?? []).includes("text")) return false;
+  if (!(c.output ?? []).includes("text")) return false;
+  return !featuresOf(c).some((f) => MEDIA_GENERATION_FEATURES.has(f));
+}
+
 // models/catalog/types.ts
 var INPUT_MODALITIES = ["text", "image", "audio", "video"];
 var OUTPUT_MODALITIES = [
@@ -1617,6 +1638,7 @@ function ModelListDropdown({
     ].sort((a, b) => a.localeCompare(b)),
     [eligibleModels]
   );
+  const chatFitApplies = effectiveSelectionPurpose === "chat" && !(outputModalities ?? []).some((o) => o !== "text");
   const filtered = useMemo2(() => {
     const q = query.trim().toLowerCase();
     const hasAvailable = (m) => (m.admin?.offerings ?? []).some((o) => o.isAvailable);
@@ -1628,6 +1650,7 @@ function ModelListDropdown({
         return false;
       if (effectiveSelectionPurpose === "chat" && isManagedAgentModelCapability(m))
         return false;
+      if (chatFitApplies && !isChatModelCapability(m)) return false;
       if (tab === "favorites" && !favoriteSet.has(m.id)) return false;
       const haystack = [
         m.name,
@@ -1667,7 +1690,7 @@ function ModelListDropdown({
       if (filters.premium !== "any") {
         if (filters.premium === "yes" !== m.isPremium) return false;
       }
-      for (const m2 of filters.input) if (!m.input.includes(m2)) return false;
+      for (const m2 of filters.input) if (!takesInput(m, m2)) return false;
       const outputSatisfied = (want) => m.output.includes(want) || effectiveSelectionPurpose === "agent" && isDecision && want === "text";
       for (const m2 of filters.output) if (!outputSatisfied(m2)) return false;
       for (const b of filters.features)
@@ -1733,6 +1756,7 @@ function ModelListDropdown({
     variant,
     priorityModelSet,
     effectiveSelectionPurpose,
+    chatFitApplies,
     hiddenModelIds,
     value,
     successionIndex

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/agents",
-  "version": "0.59.192",
+  "version": "0.59.193",
   "description": "Portable AI Matrx agent stream protocol, event projection, and safe result-presentation primitives.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -514,8 +514,8 @@
     "@ai-matrx/content-ir": "latest",
     "@ai-matrx/data": "latest",
     "@ai-matrx/design-system": "latest",
-    "@ai-matrx/icons": "latest",
     "@ai-matrx/diff": "latest",
+    "@ai-matrx/icons": "latest",
     "@ai-matrx/kit": "latest"
   },
   "peerDependencies": {
@@ -555,11 +555,11 @@
   "scripts": {
     "build": "pnpm clean && node ./scripts/build-parts.mjs && node ../scripts/check-node-env-not-inlined.mjs",
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
-    "check:package": "node ./scripts/check-catalog-reader-columns.mjs && node ./scripts/check-catalog-reader-columns.mjs --self-test && node ../scripts/check-agents-below-chat.mjs && node ../scripts/check-agents-below-chat.mjs --self-test && pnpm build && node ../scripts/check-exports-agreement.mjs && publint && pnpm verify:tarball && node ../scripts/check-tarball-relative-imports.mjs --self-test && node ../scripts/check-tarball-relative-imports.mjs --pack . && node ../scripts/check-package-rules.mjs --self-test && node ../scripts/check-package-rules.mjs .",
+    "check:package": "node ./scripts/check-catalog-reader-columns.mjs && node ./scripts/check-catalog-reader-columns.mjs --self-test && node ../scripts/check-no-model-literals.mjs && node ../scripts/check-no-model-literals.mjs --self-test && node ../scripts/check-agents-below-chat.mjs && node ../scripts/check-agents-below-chat.mjs --self-test && pnpm build && node ../scripts/check-exports-agreement.mjs && publint && pnpm verify:tarball && node ../scripts/check-tarball-relative-imports.mjs --self-test && node ../scripts/check-tarball-relative-imports.mjs --pack . && node ../scripts/check-package-rules.mjs --self-test && node ../scripts/check-package-rules.mjs .",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "verify:tarball": "node ./scripts/verify-tarball.mjs",
     "typegen:self-test": "node scripts/typegen/drop-guard.self-test.mjs && node scripts/typegen/check-api-types-fresh.mjs --self-test"
   },
-  "gitHead": "7829f4d91a8aa88811a634c9fe02aa66cf4b2e5c"
+  "gitHead": "3165453310fa6d42f3b90249a12d956eeebe7636"
 }