@ai-matrx/agents 0.59.275 → 0.59.277

package/CHANGELOG.md

@@ -1,10 +1,27 @@
 # Changelog
 
-## 0.59.275
+## 0.59.277
 
 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.276
+
+- `./models`: one catalog edit costs a page at most two requests, however many model labels are mounted.
+  `records.refresh(listed?)` re-reads full records in ONE `in (...)` read, identities in ONE `in (...)`
+  read of only the ids no list row covers, and model class slices in ONE read; `createModelCatalog().refresh()`
+  passes its picker list's fresh `model_public` + `model_offering` rows (`ModelCatalogListRows`), which answer
+  the records' options list, identities and class index, so an edit is that one list read. `loadIdentity`
+  calls for ids in the same tick (N labels mounting) coalesce into one `in (...)` read, shared with
+  `loadIdentities`; a name-shaped key still reads alone. Live 2026-10-24 (web f8dc2956): one rename cost the
+  chat page a list read plus one single-id `model_definition` read per label. Guard:
+  `models/react/catalog-changed-request-count.test.tsx`. Consumer action: none (the argument is optional).
+
+## 0.59.275
+
+Automatic changed-only republish (docs/metadata drift since the last published version; verified: `git diff 6393a0ff9a cf96f35563 -- apps/shared/matrx-agents/src`
+has no shipped-source changes outside tests, fixtures and docs). No consumer action required.
+
 ## 0.59.274
 
 - `./models`: a burst of `catalog_changed` is ONE re-read. New `coalesceModelCatalogChanges(deliver, options?)`:

package/dist/models/index.cjs

@@ -1021,6 +1021,9 @@ function withIdLists(state2) {
   const sort = (ids) => ids.sort((a, b) => label(a).localeCompare(label(b)));
   return { ...state2, activeIds: sort(active), deprecatedIds: sort(deprecated) };
 }
+var IDENTITY_COLUMNS = "id, name, common_name, is_deprecated";
+var OPTION_COLUMN_LIST = ["id", "name", "common_name", "maker", "cost_rating", "speed_rating", "is_primary", "capabilities", "is_deprecated", "retired_at", "successor_id"];
+var OPTION_COLUMNS = OPTION_COLUMN_LIST.join(", ");
 var MODEL_CONFIG_COLUMNS = "id, name, common_name, maker, cost_rating, speed_rating, is_premium, is_primary, context_window, max_tokens, capabilities, controls, constraints, is_deprecated, retired_at, successor_id";
 function createModelRecords(config) {
   if (!config?.client) throw new Error("createModelRecords: `client` (a Supabase client) is required.");
@@ -1045,13 +1048,10 @@ function createModelRecords(config) {
     inFlight.set(key, p);
     return p;
   };
-  async function readFullModel(modelId) {
-    const relation = await isSignedIn() ? "model_config" : "model_public";
-    const { data, error } = await ai().from(relation).select(MODEL_CONFIG_COLUMNS).eq(catalogKeyColumn(modelId), modelId).maybeSingle();
-    if (error) throw error;
-    const row = data;
-    if (!row) throw new Error(`AI model ${modelId} is not available (ai.${relation} has no such row)`);
-    if (!row.id || !row.name) throw new Error(`ai.${relation} returned a row without id/name for model ${modelId}`);
+  function toFullRecord(raw, relation, asked) {
+    const row = raw;
+    if (!row) throw new Error(`AI model ${asked} is not available (ai.${relation} has no such row)`);
+    if (!row.id || !row.name) throw new Error(`ai.${relation} returned a row without id/name for model ${asked}`);
     const read = {
       ...row,
       id: row.id,
@@ -1061,74 +1061,146 @@ function createModelRecords(config) {
     };
     return normalizeModel(read);
   }
-  async function readOfferings(modelId) {
+  async function readFullModel(modelId) {
+    const relation = await isSignedIn() ? "model_config" : "model_public";
+    const { data, error } = await ai().from(relation).select(MODEL_CONFIG_COLUMNS).eq(catalogKeyColumn(modelId), modelId).maybeSingle();
+    if (error) throw error;
+    return toFullRecord(data, relation, modelId);
+  }
+  async function readOfferings(modelIds) {
     const q = ai().from("model_offering").select("model_id, offering_id, served_via, served_via_endpoint_id, priority");
-    const { data, error } = await (modelId ? q.eq("model_id", modelId) : q);
+    const { data, error } = await (modelIds ? modelIds.length === 1 ? q.eq("model_id", modelIds[0]) : q.in("model_id", modelIds) : q);
     if (error) throw error;
     return data ?? [];
   }
-  async function rereadKnown() {
+  const mergeClassSlice = (rows3) => update((s4) => {
+    if (s4.modelClassStatus === "succeeded") return s4;
+    const slice = buildModelClassIndex(rows3);
+    const base = s4.modelClassIndex ?? { classesByModelId: {}, classOfOffering: {} };
+    return { ...s4, modelClassIndex: { classesByModelId: { ...base.classesByModelId, ...slice.classesByModelId }, classOfOffering: { ...base.classOfOffering, ...slice.classOfOffering } } };
+  });
+  let identityTick = null;
+  async function readIdentitiesNow(wanted) {
+    try {
+      const { data, error } = await ai().from("model_definition").select(IDENTITY_COLUMNS).in("id", wanted);
+      if (error) throw error;
+      const rows3 = Array.isArray(data) ? data : [];
+      const got = new Set(rows3.map((r) => r.id));
+      const missing = wanted.filter((id) => !got.has(id));
+      if (missing.length > 0) errorSink({ code: "model-records-identity-failed", message: `AI model ${missing.join(", ")} is not available (ai.model_definition has no such row)`, context: { modelIds: missing } });
+      update((s4) => ({
+        ...s4,
+        identityById: { ...s4.identityById, ...Object.fromEntries(rows3.map((r) => [r.id, r])) },
+        identityStatusById: { ...s4.identityStatusById, ...Object.fromEntries(wanted.map((id) => [id, got.has(id) ? "succeeded" : "failed"])) }
+      }));
+    } catch (err) {
+      errorSink({ code: "model-records-identity-failed", message: messageOf(err), context: { modelIds: wanted } });
+      update((s4) => ({ ...s4, identityStatusById: { ...s4.identityStatusById, ...Object.fromEntries(wanted.map((id) => [id, "failed"])) } }));
+    }
+  }
+  function queueIdentity(id) {
+    if (!identityTick) {
+      const ids = /* @__PURE__ */ new Set();
+      const done = Promise.resolve().then(() => {
+        identityTick = null;
+        return readIdentitiesNow([...ids]);
+      });
+      identityTick = { ids, done };
+      void done.finally(() => {
+        for (const queued of ids) if (inFlight.get(`identity:${queued}`) === done) inFlight.delete(`identity:${queued}`);
+      });
+    }
+    identityTick.ids.add(id);
+    inFlight.set(`identity:${id}`, identityTick.done);
+    update((s4) => ({ ...s4, identityStatusById: { ...s4.identityStatusById, [id]: "loading" } }));
+    return identityTick.done;
+  }
+  async function rereadKnown(listed) {
     const known = state2;
     const jobs = [];
     const fail = (code, message, context) => errorSink({ code, message: `Catalog refresh: ${message}`, ...context ? { context } : {} });
-    if (known.fetchScope === "active" || known.fetchScope === "all") {
-      jobs.push(
-        readOptions().then(
-          (rows3) => update((s4) => {
+    const fed = listed ? listed.then((f) => f, () => null) : Promise.resolve(null);
+    const optionsWereRead = known.fetchScope === "active" || known.fetchScope === "all";
+    const freshOptions = optionsWereRead ? fed.then((f) => f ? optionRowsOf(f.publicRows, f.offeringRows) : readOptions()) : Promise.resolve(null);
+    jobs.push(
+      freshOptions.then(
+        (rows3) => {
+          if (!rows3) return;
+          update((s4) => {
             const entities = { ...s4.entities };
             for (const row of rows3) {
               const existing = entities[row.id];
               entities[row.id] = { ...emptyRecord(), ...existing, ...row, _fetchType: existing?._fetchType === "full" ? "full" : "options" };
             }
             return withIdLists({ ...s4, entities, lastFetched: Date.now(), error: null });
-          }),
-          (err) => fail("model-records-refresh-options-failed", messageOf(err))
-        )
-      );
-    }
-    for (const [id, record] of Object.entries(known.entities)) {
-      if (record._fetchType !== "full") continue;
+          });
+        },
+        (err) => fail("model-records-refresh-options-failed", messageOf(err))
+      )
+    );
+    const fullIds = Object.entries(known.entities).filter(([, r]) => r._fetchType === "full").map(([id]) => id);
+    if (fullIds.length > 0) {
       jobs.push(
-        readFullModel(id).then(
-          (fresh) => update((s4) => {
-            const existing = s4.entities[fresh.id];
-            return withIdLists({ ...s4, entities: { ...s4.entities, [fresh.id]: { ...emptyRecord(), ...existing, ...fresh, maker: fresh.maker ?? existing?.maker ?? null, _fetchType: "full" } } });
-          }),
-          (err) => fail("model-records-refresh-model-failed", `${id}: ${messageOf(err)}`, { modelId: id })
-        )
+        (async () => {
+          const relation = await isSignedIn() ? "model_config" : "model_public";
+          const { data, error } = await ai().from(relation).select(MODEL_CONFIG_COLUMNS).in("id", fullIds);
+          if (error) throw error;
+          const byId2 = new Map((Array.isArray(data) ? data : []).map((r) => [r.id, r]));
+          for (const id of fullIds) {
+            try {
+              const fresh = toFullRecord(byId2.get(id) ?? null, relation, id);
+              update((s4) => {
+                const existing = s4.entities[fresh.id];
+                return withIdLists({ ...s4, entities: { ...s4.entities, [fresh.id]: { ...emptyRecord(), ...existing, ...fresh, maker: fresh.maker ?? existing?.maker ?? null, _fetchType: "full" } } });
+              });
+            } catch (err) {
+              fail("model-records-refresh-model-failed", `${id}: ${messageOf(err)}`, { modelId: id });
+            }
+          }
+        })().catch((err) => fail("model-records-refresh-model-failed", `${fullIds.join(", ")}: ${messageOf(err)}`, { modelIds: fullIds }))
       );
     }
-    for (const id of Object.keys(known.identityById)) {
+    const identityKeys = Object.entries(known.identityById);
+    if (identityKeys.length > 0) {
       jobs.push(
-        Promise.resolve(ai().from("model_definition").select("id, name, common_name, is_deprecated").eq(catalogKeyColumn(id), id).maybeSingle()).then(
-          ({ data, error }) => {
+        (async () => {
+          const [f, opts] = await Promise.all([fed, freshOptions.catch(() => null)]);
+          const covered = /* @__PURE__ */ new Map();
+          for (const r of [...f?.publicRows ?? [], ...opts ?? []]) {
+            if (typeof r.id === "string" && typeof r.name === "string") {
+              covered.set(r.id, { id: r.id, name: r.name, common_name: r.common_name ?? null, is_deprecated: r.is_deprecated ?? null });
+            }
+          }
+          const wanted = [...new Set(identityKeys.map(([, row]) => row.id))].filter((id) => !covered.has(id) && known.entities[id]?._fetchType !== "full");
+          if (wanted.length > 0) {
+            const { data, error } = await ai().from("model_definition").select(IDENTITY_COLUMNS).in("id", wanted);
             if (error) throw error;
-            if (data) update((s4) => ({ ...s4, identityById: { ...s4.identityById, [id]: data } }));
+            for (const row of Array.isArray(data) ? data : []) covered.set(row.id, row);
+          }
+          const next = {};
+          for (const [key, row] of identityKeys) {
+            const fresh = covered.get(row.id);
+            if (fresh) next[key] = fresh;
           }
-        ).catch((err) => fail("model-records-refresh-identity-failed", `${id}: ${messageOf(err)}`, { modelId: id }))
+          if (Object.keys(next).length > 0) update((s4) => ({ ...s4, identityById: { ...s4.identityById, ...next } }));
+        })().catch((err) => fail("model-records-refresh-identity-failed", messageOf(err)))
       );
     }
     if (known.modelClassStatus === "succeeded") {
       jobs.push(
-        readOfferings().then(
+        fed.then((f) => f?.offeringRows ?? readOfferings()).then(
           (rows3) => update((s4) => ({ ...s4, modelClassIndex: buildModelClassIndex(rows3) })),
           (err) => fail("model-records-refresh-classes-failed", messageOf(err))
         )
       );
-    } else {
-      for (const id of classesReadFor) {
-        jobs.push(
-          readOfferings(id).then(
-            (rows3) => update((s4) => {
-              if (s4.modelClassStatus === "succeeded") return s4;
-              const slice = buildModelClassIndex(rows3);
-              const base = s4.modelClassIndex ?? { classesByModelId: {}, classOfOffering: {} };
-              return { ...s4, modelClassIndex: { classesByModelId: { ...base.classesByModelId, ...slice.classesByModelId }, classOfOffering: { ...base.classOfOffering, ...slice.classOfOffering } } };
-            }),
-            (err) => fail("model-records-refresh-classes-failed", `${id}: ${messageOf(err)}`, { modelId: id })
-          )
-        );
-      }
+    } else if (classesReadFor.size > 0) {
+      const ids = [...classesReadFor];
+      jobs.push(
+        fed.then((f) => f ? f.offeringRows.filter((o) => o.model_id !== null && classesReadFor.has(o.model_id)) : readOfferings(ids)).then(
+          (rows3) => mergeClassSlice(rows3),
+          (err) => fail("model-records-refresh-classes-failed", `${ids.join(", ")}: ${messageOf(err)}`, { modelIds: ids })
+        )
+      );
     }
     for (const [key, cfg] of Object.entries(known.classConfigByOffering)) {
       const offeringId = key.slice(cfg.modelId.length + 1);
@@ -1146,16 +1218,29 @@ function createModelRecords(config) {
   }
   let refreshing = null;
   let refreshAgain = null;
-  function refreshAll() {
+  function refreshAll(listed) {
     if (refreshing) return refreshAgain ??= refreshing.then(() => {
       refreshAgain = null;
       return refreshAll();
     });
-    refreshing = rereadKnown().finally(() => {
+    refreshing = rereadKnown(listed).finally(() => {
       refreshing = null;
     });
     return refreshing;
   }
+  function optionRowsOf(publicRows, offeringRows) {
+    const routable = new Set(offeringRows.map((r) => r.model_id).filter((id) => typeof id === "string" && id.length > 0));
+    return publicRows.filter((r) => typeof r.id === "string" && typeof r.name === "string" && routable.has(r.id)).map((r) => {
+      const picked = {};
+      for (const c of OPTION_COLUMN_LIST) if (c in r) picked[c] = r[c];
+      return {
+        ...picked,
+        id: r.id,
+        name: r.name,
+        capabilities: requireCanonicalCapabilities(r.capabilities, { modelId: r.id, modelName: r.name })
+      };
+    });
+  }
   async function readOptions() {
     const { data: offeringRows, error: offeringError } = await ai().from("model_offering").select("model_id");
     if (offeringError) throw offeringError;
@@ -1165,12 +1250,9 @@ function createModelRecords(config) {
       )
     ];
     if (routableIds.length === 0) return [];
-    const { data, error } = await ai().from("model_public").select("id, name, common_name, maker, cost_rating, speed_rating, is_primary, capabilities, is_deprecated, retired_at, successor_id").in("id", routableIds).order("common_name", { ascending: true, nullsFirst: false });
+    const { data, error } = await ai().from("model_public").select(OPTION_COLUMNS).in("id", routableIds).order("common_name", { ascending: true, nullsFirst: false });
     if (error) throw error;
-    return (data ?? []).filter((r) => typeof r.id === "string" && typeof r.name === "string").map((r) => ({
-      ...r,
-      capabilities: requireCanonicalCapabilities(r.capabilities, { modelId: r.id, modelName: r.name })
-    }));
+    return optionRowsOf(data ?? [], routableIds.map((model_id) => ({ model_id })));
   }
   const api = {
     getState: () => state2,
@@ -1327,10 +1409,11 @@ function createModelRecords(config) {
       if (!modelId || state2.entities[modelId] || state2.identityById[modelId] || status === "loading" || status === "succeeded" || status === "failed") {
         return inFlight.get(`identity:${modelId}`) ?? Promise.resolve();
       }
+      if (catalogKeyColumn(modelId) === "id") return queueIdentity(modelId);
       return once(`identity:${modelId}`, async () => {
         update((s4) => ({ ...s4, identityStatusById: { ...s4.identityStatusById, [modelId]: "loading" } }));
         try {
-          const { data, error } = await ai().from("model_definition").select("id, name, common_name, is_deprecated").eq(catalogKeyColumn(modelId), modelId).maybeSingle();
+          const { data, error } = await ai().from("model_definition").select(IDENTITY_COLUMNS).eq(catalogKeyColumn(modelId), modelId).maybeSingle();
           if (error) throw error;
           if (!data) throw new Error(`AI model ${modelId} is not available (ai.model_definition has no such row)`);
           const row = data;
@@ -1346,52 +1429,10 @@ function createModelRecords(config) {
       });
     },
     loadIdentities(modelIds) {
-      const asked = (id) => {
-        const status = state2.identityStatusById[id];
-        return Boolean(state2.entities[id] || state2.identityById[id] || status === "loading" || status === "succeeded" || status === "failed");
-      };
       const ids = [...new Set(modelIds.filter((id) => Boolean(id)))];
-      const waits = [];
-      const wanted = [];
-      for (const id of ids) {
-        if (catalogKeyColumn(id) !== "id") waits.push(api.loadIdentity(id));
-        else if (asked(id)) waits.push(inFlight.get(`identity:${id}`) ?? Promise.resolve());
-        else wanted.push(id);
-      }
-      if (wanted.length > 0) {
-        const marked = Object.fromEntries(wanted.map((id) => [id, "loading"]));
-        update((s4) => ({ ...s4, identityStatusById: { ...s4.identityStatusById, ...marked } }));
-        const run = (async () => {
-          try {
-            const { data, error } = await ai().from("model_definition").select("id, name, common_name, is_deprecated").in("id", wanted);
-            if (error) throw error;
-            const rows3 = Array.isArray(data) ? data : [];
-            const got = new Set(rows3.map((r) => r.id));
-            update((s4) => ({
-              ...s4,
-              identityById: { ...s4.identityById, ...Object.fromEntries(rows3.map((r) => [r.id, r])) },
-              identityStatusById: {
-                ...s4.identityStatusById,
-                ...Object.fromEntries(wanted.map((id) => [id, got.has(id) ? "succeeded" : "failed"]))
-              }
-            }));
-          } catch (err) {
-            errorSink({ code: "model-records-identity-failed", message: messageOf(err), context: { modelIds: wanted } });
-            update((s4) => ({
-              ...s4,
-              identityStatusById: { ...s4.identityStatusById, ...Object.fromEntries(wanted.map((id) => [id, "failed"])) }
-            }));
-          }
-        })();
-        for (const id of wanted) inFlight.set(`identity:${id}`, run);
-        void run.finally(() => {
-          for (const id of wanted) if (inFlight.get(`identity:${id}`) === run) inFlight.delete(`identity:${id}`);
-        });
-        waits.push(run);
-      }
-      return Promise.all(waits).then(() => void 0);
+      return Promise.all(ids.map((id) => api.loadIdentity(id))).then(() => void 0);
     },
-    refresh: () => refreshAll(),
+    refresh: (listed) => refreshAll(listed),
     seedModel({ modelId, config: config2, offerings }) {
       if (!modelId) return;
       if (!classesReadFor.has(modelId) && state2.modelClassStatus !== "succeeded") {
@@ -1840,7 +1881,7 @@ function aiRpc(client, fn) {
   if (!scope.rpc) throw new Error(`The model catalog client's schema("ai") has no rpc(), so ${fn} cannot be called.`);
   return scope.rpc(fn);
 }
-async function readCatalog(client, variant) {
+async function readCatalog(client, variant, onListRows) {
   if (variant === "admin") {
     const [rpcRes, offeringsRes] = await Promise.all([
       aiRpc(client, "admin_model_catalog"),
@@ -1891,6 +1932,7 @@ async function readCatalog(client, variant) {
   ]);
   if (publicRes.error) throw publicRes.error;
   if (offeringRes.error) throw offeringRes.error;
+  onListRows?.({ publicRows: rows(publicRes.data), offeringRows: rows(offeringRes.data) });
   const tiersByModel = /* @__PURE__ */ new Map();
   for (const r of rows(offeringRes.data)) {
     const modelId = str(r.model_id);
@@ -1930,14 +1972,14 @@ function createModelCatalog(config) {
     state2 = { ...state2, [variant]: next };
     for (const l of [...listeners]) l();
   };
-  const run = (variant) => {
+  const run = (variant, onListRows) => {
     const pending = inFlight[variant];
     if (pending) return pending;
     const prior = state2[variant];
     if (prior.status === "idle" || prior.status === "error") set(variant, { ...prior, status: "loading", error: null });
     const job = (async () => {
       try {
-        const models = await readCatalog(client, variant);
+        const models = await readCatalog(client, variant, onListRows);
         set(variant, { status: "ready", models, error: null, loadedAt: Date.now() });
       } catch (err) {
         const message = messageOf2(err);
@@ -1957,7 +1999,15 @@ function createModelCatalog(config) {
   });
   const refresh = async () => {
     const variants = Object.keys(state2).filter((v) => state2[v].status !== "idle");
-    await Promise.all([records.refresh(), ...variants.map((v) => run(v))]);
+    let listed;
+    const runs = variants.map((v) => {
+      if (v !== "user" || inFlight.user) return run(v);
+      let give = () => {
+      };
+      listed = new Promise((resolve) => give = resolve);
+      return run("user", (rows3) => give(rows3)).finally(() => give(null));
+    });
+    await Promise.all([records.refresh(listed), ...runs]);
   };
   const stopFollowing = config.followChanges === false ? () => {
   } : onModelCatalogChanged(() => void refresh());

package/dist/models/index.d.cts

@@ -600,6 +600,15 @@ interface ModelRecord {
     published_to_web_by: string | null;
 }
 type ModelIdentityRow = Pick<ModelRecord, "id" | "name" | "common_name" | "is_deprecated">;
+/**
+ * What the picker list's read of the catalog returned, raw: every `ai.model_public` row (with at least the
+ * options columns) and every `ai.model_offering` row (`ModelOfferingRow` columns). `records.refresh(listed)`
+ * answers the options list, the identities and the class index from it instead of reading them again.
+ */
+interface ModelCatalogListRows {
+    publicRows: Array<Record<string, unknown>>;
+    offeringRows: ModelOfferingRow[];
+}
 type ModelClassConfig = {
     modelId: string;
     controls: ModelJson | null;
@@ -693,8 +702,14 @@ interface ModelRecords {
      * the class index and slices, every pinned class's controls — and swap each in when it answers. The old
      * rows stay on screen until then (no blank pill, no flicker); a failed re-read keeps them and reports
      * through the error sink. Reads nothing that was never read. Never throws.
+     *
+     * Few requests, however many labels are mounted: full records are ONE `in (...)` read, identities are
+     * ONE `in (...)` read of only the ids no list row covers, model class slices are ONE read. `listed` is
+     * the picker list's own fresh re-read of `ai.model_public` + `ai.model_offering` (the catalog passes it,
+     * `createModelCatalog().refresh()`): when given, the options list, the identities it covers and the class
+     * index are answered from it, so one edit costs the page that one list read.
      */
-    refresh(): Promise<void>;
+    refresh(listed?: Promise<ModelCatalogListRows | null>): Promise<void>;
     /**
      * Answer `loadModel` + `loadModelClasses` for one model from rows a batched
      * route read already returned (`chat.route_seed`): its `ai.model_config` row
@@ -2134,4 +2149,4 @@ 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, 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 };
+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, ModelCatalogListRows, 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

@@ -600,6 +600,15 @@ interface ModelRecord {
     published_to_web_by: string | null;
 }
 type ModelIdentityRow = Pick<ModelRecord, "id" | "name" | "common_name" | "is_deprecated">;
+/**
+ * What the picker list's read of the catalog returned, raw: every `ai.model_public` row (with at least the
+ * options columns) and every `ai.model_offering` row (`ModelOfferingRow` columns). `records.refresh(listed)`
+ * answers the options list, the identities and the class index from it instead of reading them again.
+ */
+interface ModelCatalogListRows {
+    publicRows: Array<Record<string, unknown>>;
+    offeringRows: ModelOfferingRow[];
+}
 type ModelClassConfig = {
     modelId: string;
     controls: ModelJson | null;
@@ -693,8 +702,14 @@ interface ModelRecords {
      * the class index and slices, every pinned class's controls — and swap each in when it answers. The old
      * rows stay on screen until then (no blank pill, no flicker); a failed re-read keeps them and reports
      * through the error sink. Reads nothing that was never read. Never throws.
+     *
+     * Few requests, however many labels are mounted: full records are ONE `in (...)` read, identities are
+     * ONE `in (...)` read of only the ids no list row covers, model class slices are ONE read. `listed` is
+     * the picker list's own fresh re-read of `ai.model_public` + `ai.model_offering` (the catalog passes it,
+     * `createModelCatalog().refresh()`): when given, the options list, the identities it covers and the class
+     * index are answered from it, so one edit costs the page that one list read.
      */
-    refresh(): Promise<void>;
+    refresh(listed?: Promise<ModelCatalogListRows | null>): Promise<void>;
     /**
      * Answer `loadModel` + `loadModelClasses` for one model from rows a batched
      * route read already returned (`chat.route_seed`): its `ai.model_config` row
@@ -2134,4 +2149,4 @@ 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, 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 };
+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, ModelCatalogListRows, 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

@@ -837,6 +837,9 @@ function withIdLists(state2) {
   const sort = (ids) => ids.sort((a, b) => label(a).localeCompare(label(b)));
   return { ...state2, activeIds: sort(active), deprecatedIds: sort(deprecated) };
 }
+var IDENTITY_COLUMNS = "id, name, common_name, is_deprecated";
+var OPTION_COLUMN_LIST = ["id", "name", "common_name", "maker", "cost_rating", "speed_rating", "is_primary", "capabilities", "is_deprecated", "retired_at", "successor_id"];
+var OPTION_COLUMNS = OPTION_COLUMN_LIST.join(", ");
 var MODEL_CONFIG_COLUMNS = "id, name, common_name, maker, cost_rating, speed_rating, is_premium, is_primary, context_window, max_tokens, capabilities, controls, constraints, is_deprecated, retired_at, successor_id";
 function createModelRecords(config) {
   if (!config?.client) throw new Error("createModelRecords: `client` (a Supabase client) is required.");
@@ -861,13 +864,10 @@ function createModelRecords(config) {
     inFlight.set(key, p);
     return p;
   };
-  async function readFullModel(modelId) {
-    const relation = await isSignedIn() ? "model_config" : "model_public";
-    const { data, error } = await ai().from(relation).select(MODEL_CONFIG_COLUMNS).eq(catalogKeyColumn(modelId), modelId).maybeSingle();
-    if (error) throw error;
-    const row = data;
-    if (!row) throw new Error(`AI model ${modelId} is not available (ai.${relation} has no such row)`);
-    if (!row.id || !row.name) throw new Error(`ai.${relation} returned a row without id/name for model ${modelId}`);
+  function toFullRecord(raw, relation, asked) {
+    const row = raw;
+    if (!row) throw new Error(`AI model ${asked} is not available (ai.${relation} has no such row)`);
+    if (!row.id || !row.name) throw new Error(`ai.${relation} returned a row without id/name for model ${asked}`);
     const read = {
       ...row,
       id: row.id,
@@ -877,74 +877,146 @@ function createModelRecords(config) {
     };
     return normalizeModel(read);
   }
-  async function readOfferings(modelId) {
+  async function readFullModel(modelId) {
+    const relation = await isSignedIn() ? "model_config" : "model_public";
+    const { data, error } = await ai().from(relation).select(MODEL_CONFIG_COLUMNS).eq(catalogKeyColumn(modelId), modelId).maybeSingle();
+    if (error) throw error;
+    return toFullRecord(data, relation, modelId);
+  }
+  async function readOfferings(modelIds) {
     const q = ai().from("model_offering").select("model_id, offering_id, served_via, served_via_endpoint_id, priority");
-    const { data, error } = await (modelId ? q.eq("model_id", modelId) : q);
+    const { data, error } = await (modelIds ? modelIds.length === 1 ? q.eq("model_id", modelIds[0]) : q.in("model_id", modelIds) : q);
     if (error) throw error;
     return data ?? [];
   }
-  async function rereadKnown() {
+  const mergeClassSlice = (rows3) => update((s4) => {
+    if (s4.modelClassStatus === "succeeded") return s4;
+    const slice = buildModelClassIndex(rows3);
+    const base = s4.modelClassIndex ?? { classesByModelId: {}, classOfOffering: {} };
+    return { ...s4, modelClassIndex: { classesByModelId: { ...base.classesByModelId, ...slice.classesByModelId }, classOfOffering: { ...base.classOfOffering, ...slice.classOfOffering } } };
+  });
+  let identityTick = null;
+  async function readIdentitiesNow(wanted) {
+    try {
+      const { data, error } = await ai().from("model_definition").select(IDENTITY_COLUMNS).in("id", wanted);
+      if (error) throw error;
+      const rows3 = Array.isArray(data) ? data : [];
+      const got = new Set(rows3.map((r) => r.id));
+      const missing = wanted.filter((id) => !got.has(id));
+      if (missing.length > 0) errorSink({ code: "model-records-identity-failed", message: `AI model ${missing.join(", ")} is not available (ai.model_definition has no such row)`, context: { modelIds: missing } });
+      update((s4) => ({
+        ...s4,
+        identityById: { ...s4.identityById, ...Object.fromEntries(rows3.map((r) => [r.id, r])) },
+        identityStatusById: { ...s4.identityStatusById, ...Object.fromEntries(wanted.map((id) => [id, got.has(id) ? "succeeded" : "failed"])) }
+      }));
+    } catch (err) {
+      errorSink({ code: "model-records-identity-failed", message: messageOf(err), context: { modelIds: wanted } });
+      update((s4) => ({ ...s4, identityStatusById: { ...s4.identityStatusById, ...Object.fromEntries(wanted.map((id) => [id, "failed"])) } }));
+    }
+  }
+  function queueIdentity(id) {
+    if (!identityTick) {
+      const ids = /* @__PURE__ */ new Set();
+      const done = Promise.resolve().then(() => {
+        identityTick = null;
+        return readIdentitiesNow([...ids]);
+      });
+      identityTick = { ids, done };
+      void done.finally(() => {
+        for (const queued of ids) if (inFlight.get(`identity:${queued}`) === done) inFlight.delete(`identity:${queued}`);
+      });
+    }
+    identityTick.ids.add(id);
+    inFlight.set(`identity:${id}`, identityTick.done);
+    update((s4) => ({ ...s4, identityStatusById: { ...s4.identityStatusById, [id]: "loading" } }));
+    return identityTick.done;
+  }
+  async function rereadKnown(listed) {
     const known = state2;
     const jobs = [];
     const fail = (code, message, context) => errorSink({ code, message: `Catalog refresh: ${message}`, ...context ? { context } : {} });
-    if (known.fetchScope === "active" || known.fetchScope === "all") {
-      jobs.push(
-        readOptions().then(
-          (rows3) => update((s4) => {
+    const fed = listed ? listed.then((f) => f, () => null) : Promise.resolve(null);
+    const optionsWereRead = known.fetchScope === "active" || known.fetchScope === "all";
+    const freshOptions = optionsWereRead ? fed.then((f) => f ? optionRowsOf(f.publicRows, f.offeringRows) : readOptions()) : Promise.resolve(null);
+    jobs.push(
+      freshOptions.then(
+        (rows3) => {
+          if (!rows3) return;
+          update((s4) => {
             const entities = { ...s4.entities };
             for (const row of rows3) {
               const existing = entities[row.id];
               entities[row.id] = { ...emptyRecord(), ...existing, ...row, _fetchType: existing?._fetchType === "full" ? "full" : "options" };
             }
             return withIdLists({ ...s4, entities, lastFetched: Date.now(), error: null });
-          }),
-          (err) => fail("model-records-refresh-options-failed", messageOf(err))
-        )
-      );
-    }
-    for (const [id, record] of Object.entries(known.entities)) {
-      if (record._fetchType !== "full") continue;
+          });
+        },
+        (err) => fail("model-records-refresh-options-failed", messageOf(err))
+      )
+    );
+    const fullIds = Object.entries(known.entities).filter(([, r]) => r._fetchType === "full").map(([id]) => id);
+    if (fullIds.length > 0) {
       jobs.push(
-        readFullModel(id).then(
-          (fresh) => update((s4) => {
-            const existing = s4.entities[fresh.id];
-            return withIdLists({ ...s4, entities: { ...s4.entities, [fresh.id]: { ...emptyRecord(), ...existing, ...fresh, maker: fresh.maker ?? existing?.maker ?? null, _fetchType: "full" } } });
-          }),
-          (err) => fail("model-records-refresh-model-failed", `${id}: ${messageOf(err)}`, { modelId: id })
-        )
+        (async () => {
+          const relation = await isSignedIn() ? "model_config" : "model_public";
+          const { data, error } = await ai().from(relation).select(MODEL_CONFIG_COLUMNS).in("id", fullIds);
+          if (error) throw error;
+          const byId2 = new Map((Array.isArray(data) ? data : []).map((r) => [r.id, r]));
+          for (const id of fullIds) {
+            try {
+              const fresh = toFullRecord(byId2.get(id) ?? null, relation, id);
+              update((s4) => {
+                const existing = s4.entities[fresh.id];
+                return withIdLists({ ...s4, entities: { ...s4.entities, [fresh.id]: { ...emptyRecord(), ...existing, ...fresh, maker: fresh.maker ?? existing?.maker ?? null, _fetchType: "full" } } });
+              });
+            } catch (err) {
+              fail("model-records-refresh-model-failed", `${id}: ${messageOf(err)}`, { modelId: id });
+            }
+          }
+        })().catch((err) => fail("model-records-refresh-model-failed", `${fullIds.join(", ")}: ${messageOf(err)}`, { modelIds: fullIds }))
       );
     }
-    for (const id of Object.keys(known.identityById)) {
+    const identityKeys = Object.entries(known.identityById);
+    if (identityKeys.length > 0) {
       jobs.push(
-        Promise.resolve(ai().from("model_definition").select("id, name, common_name, is_deprecated").eq(catalogKeyColumn(id), id).maybeSingle()).then(
-          ({ data, error }) => {
+        (async () => {
+          const [f, opts] = await Promise.all([fed, freshOptions.catch(() => null)]);
+          const covered = /* @__PURE__ */ new Map();
+          for (const r of [...f?.publicRows ?? [], ...opts ?? []]) {
+            if (typeof r.id === "string" && typeof r.name === "string") {
+              covered.set(r.id, { id: r.id, name: r.name, common_name: r.common_name ?? null, is_deprecated: r.is_deprecated ?? null });
+            }
+          }
+          const wanted = [...new Set(identityKeys.map(([, row]) => row.id))].filter((id) => !covered.has(id) && known.entities[id]?._fetchType !== "full");
+          if (wanted.length > 0) {
+            const { data, error } = await ai().from("model_definition").select(IDENTITY_COLUMNS).in("id", wanted);
             if (error) throw error;
-            if (data) update((s4) => ({ ...s4, identityById: { ...s4.identityById, [id]: data } }));
+            for (const row of Array.isArray(data) ? data : []) covered.set(row.id, row);
+          }
+          const next = {};
+          for (const [key, row] of identityKeys) {
+            const fresh = covered.get(row.id);
+            if (fresh) next[key] = fresh;
           }
-        ).catch((err) => fail("model-records-refresh-identity-failed", `${id}: ${messageOf(err)}`, { modelId: id }))
+          if (Object.keys(next).length > 0) update((s4) => ({ ...s4, identityById: { ...s4.identityById, ...next } }));
+        })().catch((err) => fail("model-records-refresh-identity-failed", messageOf(err)))
       );
     }
     if (known.modelClassStatus === "succeeded") {
       jobs.push(
-        readOfferings().then(
+        fed.then((f) => f?.offeringRows ?? readOfferings()).then(
           (rows3) => update((s4) => ({ ...s4, modelClassIndex: buildModelClassIndex(rows3) })),
           (err) => fail("model-records-refresh-classes-failed", messageOf(err))
         )
       );
-    } else {
-      for (const id of classesReadFor) {
-        jobs.push(
-          readOfferings(id).then(
-            (rows3) => update((s4) => {
-              if (s4.modelClassStatus === "succeeded") return s4;
-              const slice = buildModelClassIndex(rows3);
-              const base = s4.modelClassIndex ?? { classesByModelId: {}, classOfOffering: {} };
-              return { ...s4, modelClassIndex: { classesByModelId: { ...base.classesByModelId, ...slice.classesByModelId }, classOfOffering: { ...base.classOfOffering, ...slice.classOfOffering } } };
-            }),
-            (err) => fail("model-records-refresh-classes-failed", `${id}: ${messageOf(err)}`, { modelId: id })
-          )
-        );
-      }
+    } else if (classesReadFor.size > 0) {
+      const ids = [...classesReadFor];
+      jobs.push(
+        fed.then((f) => f ? f.offeringRows.filter((o) => o.model_id !== null && classesReadFor.has(o.model_id)) : readOfferings(ids)).then(
+          (rows3) => mergeClassSlice(rows3),
+          (err) => fail("model-records-refresh-classes-failed", `${ids.join(", ")}: ${messageOf(err)}`, { modelIds: ids })
+        )
+      );
     }
     for (const [key, cfg] of Object.entries(known.classConfigByOffering)) {
       const offeringId = key.slice(cfg.modelId.length + 1);
@@ -962,16 +1034,29 @@ function createModelRecords(config) {
   }
   let refreshing = null;
   let refreshAgain = null;
-  function refreshAll() {
+  function refreshAll(listed) {
     if (refreshing) return refreshAgain ??= refreshing.then(() => {
       refreshAgain = null;
       return refreshAll();
     });
-    refreshing = rereadKnown().finally(() => {
+    refreshing = rereadKnown(listed).finally(() => {
       refreshing = null;
     });
     return refreshing;
   }
+  function optionRowsOf(publicRows, offeringRows) {
+    const routable = new Set(offeringRows.map((r) => r.model_id).filter((id) => typeof id === "string" && id.length > 0));
+    return publicRows.filter((r) => typeof r.id === "string" && typeof r.name === "string" && routable.has(r.id)).map((r) => {
+      const picked = {};
+      for (const c of OPTION_COLUMN_LIST) if (c in r) picked[c] = r[c];
+      return {
+        ...picked,
+        id: r.id,
+        name: r.name,
+        capabilities: requireCanonicalCapabilities(r.capabilities, { modelId: r.id, modelName: r.name })
+      };
+    });
+  }
   async function readOptions() {
     const { data: offeringRows, error: offeringError } = await ai().from("model_offering").select("model_id");
     if (offeringError) throw offeringError;
@@ -981,12 +1066,9 @@ function createModelRecords(config) {
       )
     ];
     if (routableIds.length === 0) return [];
-    const { data, error } = await ai().from("model_public").select("id, name, common_name, maker, cost_rating, speed_rating, is_primary, capabilities, is_deprecated, retired_at, successor_id").in("id", routableIds).order("common_name", { ascending: true, nullsFirst: false });
+    const { data, error } = await ai().from("model_public").select(OPTION_COLUMNS).in("id", routableIds).order("common_name", { ascending: true, nullsFirst: false });
     if (error) throw error;
-    return (data ?? []).filter((r) => typeof r.id === "string" && typeof r.name === "string").map((r) => ({
-      ...r,
-      capabilities: requireCanonicalCapabilities(r.capabilities, { modelId: r.id, modelName: r.name })
-    }));
+    return optionRowsOf(data ?? [], routableIds.map((model_id) => ({ model_id })));
   }
   const api = {
     getState: () => state2,
@@ -1143,10 +1225,11 @@ function createModelRecords(config) {
       if (!modelId || state2.entities[modelId] || state2.identityById[modelId] || status === "loading" || status === "succeeded" || status === "failed") {
         return inFlight.get(`identity:${modelId}`) ?? Promise.resolve();
       }
+      if (catalogKeyColumn(modelId) === "id") return queueIdentity(modelId);
       return once(`identity:${modelId}`, async () => {
         update((s4) => ({ ...s4, identityStatusById: { ...s4.identityStatusById, [modelId]: "loading" } }));
         try {
-          const { data, error } = await ai().from("model_definition").select("id, name, common_name, is_deprecated").eq(catalogKeyColumn(modelId), modelId).maybeSingle();
+          const { data, error } = await ai().from("model_definition").select(IDENTITY_COLUMNS).eq(catalogKeyColumn(modelId), modelId).maybeSingle();
           if (error) throw error;
           if (!data) throw new Error(`AI model ${modelId} is not available (ai.model_definition has no such row)`);
           const row = data;
@@ -1162,52 +1245,10 @@ function createModelRecords(config) {
       });
     },
     loadIdentities(modelIds) {
-      const asked = (id) => {
-        const status = state2.identityStatusById[id];
-        return Boolean(state2.entities[id] || state2.identityById[id] || status === "loading" || status === "succeeded" || status === "failed");
-      };
       const ids = [...new Set(modelIds.filter((id) => Boolean(id)))];
-      const waits = [];
-      const wanted = [];
-      for (const id of ids) {
-        if (catalogKeyColumn(id) !== "id") waits.push(api.loadIdentity(id));
-        else if (asked(id)) waits.push(inFlight.get(`identity:${id}`) ?? Promise.resolve());
-        else wanted.push(id);
-      }
-      if (wanted.length > 0) {
-        const marked = Object.fromEntries(wanted.map((id) => [id, "loading"]));
-        update((s4) => ({ ...s4, identityStatusById: { ...s4.identityStatusById, ...marked } }));
-        const run = (async () => {
-          try {
-            const { data, error } = await ai().from("model_definition").select("id, name, common_name, is_deprecated").in("id", wanted);
-            if (error) throw error;
-            const rows3 = Array.isArray(data) ? data : [];
-            const got = new Set(rows3.map((r) => r.id));
-            update((s4) => ({
-              ...s4,
-              identityById: { ...s4.identityById, ...Object.fromEntries(rows3.map((r) => [r.id, r])) },
-              identityStatusById: {
-                ...s4.identityStatusById,
-                ...Object.fromEntries(wanted.map((id) => [id, got.has(id) ? "succeeded" : "failed"]))
-              }
-            }));
-          } catch (err) {
-            errorSink({ code: "model-records-identity-failed", message: messageOf(err), context: { modelIds: wanted } });
-            update((s4) => ({
-              ...s4,
-              identityStatusById: { ...s4.identityStatusById, ...Object.fromEntries(wanted.map((id) => [id, "failed"])) }
-            }));
-          }
-        })();
-        for (const id of wanted) inFlight.set(`identity:${id}`, run);
-        void run.finally(() => {
-          for (const id of wanted) if (inFlight.get(`identity:${id}`) === run) inFlight.delete(`identity:${id}`);
-        });
-        waits.push(run);
-      }
-      return Promise.all(waits).then(() => void 0);
+      return Promise.all(ids.map((id) => api.loadIdentity(id))).then(() => void 0);
     },
-    refresh: () => refreshAll(),
+    refresh: (listed) => refreshAll(listed),
     seedModel({ modelId, config: config2, offerings }) {
       if (!modelId) return;
       if (!classesReadFor.has(modelId) && state2.modelClassStatus !== "succeeded") {
@@ -1656,7 +1697,7 @@ function aiRpc(client, fn) {
   if (!scope.rpc) throw new Error(`The model catalog client's schema("ai") has no rpc(), so ${fn} cannot be called.`);
   return scope.rpc(fn);
 }
-async function readCatalog(client, variant) {
+async function readCatalog(client, variant, onListRows) {
   if (variant === "admin") {
     const [rpcRes, offeringsRes] = await Promise.all([
       aiRpc(client, "admin_model_catalog"),
@@ -1707,6 +1748,7 @@ async function readCatalog(client, variant) {
   ]);
   if (publicRes.error) throw publicRes.error;
   if (offeringRes.error) throw offeringRes.error;
+  onListRows?.({ publicRows: rows(publicRes.data), offeringRows: rows(offeringRes.data) });
   const tiersByModel = /* @__PURE__ */ new Map();
   for (const r of rows(offeringRes.data)) {
     const modelId = str(r.model_id);
@@ -1746,14 +1788,14 @@ function createModelCatalog(config) {
     state2 = { ...state2, [variant]: next };
     for (const l of [...listeners]) l();
   };
-  const run = (variant) => {
+  const run = (variant, onListRows) => {
     const pending = inFlight[variant];
     if (pending) return pending;
     const prior = state2[variant];
     if (prior.status === "idle" || prior.status === "error") set(variant, { ...prior, status: "loading", error: null });
     const job = (async () => {
       try {
-        const models = await readCatalog(client, variant);
+        const models = await readCatalog(client, variant, onListRows);
         set(variant, { status: "ready", models, error: null, loadedAt: Date.now() });
       } catch (err) {
         const message = messageOf2(err);
@@ -1773,7 +1815,15 @@ function createModelCatalog(config) {
   });
   const refresh = async () => {
     const variants = Object.keys(state2).filter((v) => state2[v].status !== "idle");
-    await Promise.all([records.refresh(), ...variants.map((v) => run(v))]);
+    let listed;
+    const runs = variants.map((v) => {
+      if (v !== "user" || inFlight.user) return run(v);
+      let give = () => {
+      };
+      listed = new Promise((resolve) => give = resolve);
+      return run("user", (rows3) => give(rows3)).finally(() => give(null));
+    });
+    await Promise.all([records.refresh(listed), ...runs]);
   };
   const stopFollowing = config.followChanges === false ? () => {
   } : onModelCatalogChanged(() => void refresh());

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

@@ -288,6 +288,15 @@ interface ModelRecord {
     published_to_web_by: string | null;
 }
 type ModelIdentityRow = Pick<ModelRecord, "id" | "name" | "common_name" | "is_deprecated">;
+/**
+ * What the picker list's read of the catalog returned, raw: every `ai.model_public` row (with at least the
+ * options columns) and every `ai.model_offering` row (`ModelOfferingRow` columns). `records.refresh(listed)`
+ * answers the options list, the identities and the class index from it instead of reading them again.
+ */
+interface ModelCatalogListRows {
+    publicRows: Array<Record<string, unknown>>;
+    offeringRows: ModelOfferingRow[];
+}
 type ModelClassConfig = {
     modelId: string;
     controls: ModelJson | null;
@@ -343,8 +352,14 @@ interface ModelRecords {
      * the class index and slices, every pinned class's controls — and swap each in when it answers. The old
      * rows stay on screen until then (no blank pill, no flicker); a failed re-read keeps them and reports
      * through the error sink. Reads nothing that was never read. Never throws.
+     *
+     * Few requests, however many labels are mounted: full records are ONE `in (...)` read, identities are
+     * ONE `in (...)` read of only the ids no list row covers, model class slices are ONE read. `listed` is
+     * the picker list's own fresh re-read of `ai.model_public` + `ai.model_offering` (the catalog passes it,
+     * `createModelCatalog().refresh()`): when given, the options list, the identities it covers and the class
+     * index are answered from it, so one edit costs the page that one list read.
      */
-    refresh(): Promise<void>;
+    refresh(listed?: Promise<ModelCatalogListRows | null>): Promise<void>;
     /**
      * Answer `loadModel` + `loadModelClasses` for one model from rows a batched
      * route read already returned (`chat.route_seed`): its `ai.model_config` row

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

@@ -288,6 +288,15 @@ interface ModelRecord {
     published_to_web_by: string | null;
 }
 type ModelIdentityRow = Pick<ModelRecord, "id" | "name" | "common_name" | "is_deprecated">;
+/**
+ * What the picker list's read of the catalog returned, raw: every `ai.model_public` row (with at least the
+ * options columns) and every `ai.model_offering` row (`ModelOfferingRow` columns). `records.refresh(listed)`
+ * answers the options list, the identities and the class index from it instead of reading them again.
+ */
+interface ModelCatalogListRows {
+    publicRows: Array<Record<string, unknown>>;
+    offeringRows: ModelOfferingRow[];
+}
 type ModelClassConfig = {
     modelId: string;
     controls: ModelJson | null;
@@ -343,8 +352,14 @@ interface ModelRecords {
      * the class index and slices, every pinned class's controls — and swap each in when it answers. The old
      * rows stay on screen until then (no blank pill, no flicker); a failed re-read keeps them and reports
      * through the error sink. Reads nothing that was never read. Never throws.
+     *
+     * Few requests, however many labels are mounted: full records are ONE `in (...)` read, identities are
+     * ONE `in (...)` read of only the ids no list row covers, model class slices are ONE read. `listed` is
+     * the picker list's own fresh re-read of `ai.model_public` + `ai.model_offering` (the catalog passes it,
+     * `createModelCatalog().refresh()`): when given, the options list, the identities it covers and the class
+     * index are answered from it, so one edit costs the page that one list read.
      */
-    refresh(): Promise<void>;
+    refresh(listed?: Promise<ModelCatalogListRows | null>): Promise<void>;
     /**
      * Answer `loadModel` + `loadModelClasses` for one model from rows a batched
      * route read already returned (`chat.route_seed`): its `ai.model_config` row

package/dist/versions/react/index.cjs

@@ -1107,6 +1107,7 @@ var import_design_system10 = require("@ai-matrx/design-system");
 var import_data_table = require("@ai-matrx/design-system/data-table");
 var import_design_system11 = require("@ai-matrx/design-system");
 var import_text_case4 = require("@ai-matrx/kit/text-case");
+var import_error_sentence = require("@ai-matrx/design-system/error-sentence");
 var import_jsx_runtime14 = require("react/jsx-runtime");
 var SILENT = { success: () => {
 }, error: () => {
@@ -1275,7 +1276,7 @@ function ContractBreak({ version, ports }) {
       await ports.onDeclare(version.version_number, kind);
     } catch (error) {
       setDeclared(previous);
-      ports.notify.error(`Couldn't record the contract break: ${error instanceof Error ? error.message : String(error)}`);
+      ports.notify.error("Break not recorded", { description: (0, import_error_sentence.peopleErrorSentence)(error, null, { card: true }) });
       return;
     }
     {

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

@@ -97,7 +97,10 @@ interface VersionHistoryLoad {
 /** Where the timeline says a result: the host's toasts (sonner on the web). */
 interface VersionTimelineNotify {
     success: (message: string) => void;
-    error: (message: string) => void;
+    /** A card: a short title and an optional line (design-system NOTICE_TEXT_BUDGET). */
+    error: (message: string, options?: {
+        description?: string;
+    }) => void;
 }
 interface VersionHistoryTimelineProps {
     agentId: string;

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

@@ -97,7 +97,10 @@ interface VersionHistoryLoad {
 /** Where the timeline says a result: the host's toasts (sonner on the web). */
 interface VersionTimelineNotify {
     success: (message: string) => void;
-    error: (message: string) => void;
+    /** A card: a short title and an optional line (design-system NOTICE_TEXT_BUDGET). */
+    error: (message: string, options?: {
+        description?: string;
+    }) => void;
 }
 interface VersionHistoryTimelineProps {
     agentId: string;

package/dist/versions/react/index.js

@@ -1111,6 +1111,7 @@ import {
 } from "@ai-matrx/design-system/data-table";
 import { RecordId } from "@ai-matrx/design-system";
 import { humanizeIdentifier as humanizeIdentifier4 } from "@ai-matrx/kit/text-case";
+import { peopleErrorSentence } from "@ai-matrx/design-system/error-sentence";
 import { jsx as jsx14, jsxs as jsxs12 } from "react/jsx-runtime";
 var SILENT = { success: () => {
 }, error: () => {
@@ -1279,7 +1280,7 @@ function ContractBreak({ version, ports }) {
       await ports.onDeclare(version.version_number, kind);
     } catch (error) {
       setDeclared(previous);
-      ports.notify.error(`Couldn't record the contract break: ${error instanceof Error ? error.message : String(error)}`);
+      ports.notify.error("Break not recorded", { description: peopleErrorSentence(error, null, { card: true }) });
       return;
     }
     {

package/generated/llm-params.schema.json

@@ -947,6 +947,18 @@
       ],
       "default": null
     },
+    "conversation_instructions": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Conversation Instructions"
+    },
     "max_output_tokens": {
       "anyOf": [
         {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/agents",
-  "version": "0.59.275",
+  "version": "0.59.277",
   "description": "Portable AI Matrx agent stream protocol, event projection, and safe result-presentation primitives.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -522,5 +522,5 @@
       "optional": true
     }
   },
-  "gitHead": "cf96f355636de937738b2161490614a412f9e775"
+  "gitHead": "9798073998e5fa0c03b673a38fda129a2bc7d19d"
 }