@ai-matrx/agents 0.59.274 → 0.59.276

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/README.md

@@ -0,0 +1,20 @@
+# `@ai-matrx/agents/generated` — the server's client contract
+
+Every file here is GENERATED from the aidream server source. Never edit one by hand.
+
+- `uv run python scripts/generate_types.py` (from the aidream root) writes the stream events,
+  LLM enums/params, source attribution, workflow events and canvas chat files.
+- `uv run python scripts/generate_types.py api --direct` writes `openapi.json`
+  through `../scripts/typegen/write-api-types.mjs`: contract pin, then the drop guard over every
+  client checkout beside aidream, then normalization. A refusal writes
+  nothing (DD-128). `scripts/generate_types.py --check` runs
+  `../scripts/typegen/check-api-types-fresh.mjs`: a hand-edited `openapi.json`
+  fails it (release health `frontend-type-snapshots`).
+- `scripts/mandates_generate.py` writes `provision-offers.ts`.
+- `hr-contracts.api-types.ts`: `node apps/shared/matrx-agents/scripts/typegen/gen-hr-contracts.mjs`.
+
+The TypeScript view of the contract is `@ai-matrx/api/types` (`components`, `paths`), generated by the api package from `api-contract/`.
+
+Clients import `@ai-matrx/agents/generated/<name>` and keep NO copy (chat package
+independence P15, 2026-10-02). A server change and its types land in the same aidream commit;
+the publish train ships them.