@ai-matrx/agents 0.59.261 → 0.59.263

package/CHANGELOG.md

@@ -1,6 +1,22 @@
 # Changelog
 
+## 0.59.263
+### no second star read after a catalog or search read (FW-014)
+
+- `ensureLoaded()` and `searchServer()` no longer follow each read with `ues_get_bulk('agent', every id)`.
+  Every catalog read (`agx_get_list_full`, `agx_search`, `agent.agx_get_by_ids`) already returns
+  `is_favorite` computed server-side from `platform.user_entity_state` (`platform.my_favorite`), so
+  `toAgentSummary` now reads it. Saves one sequential request uploading every agent id (673 ids for an
+  ordinary account, 1,478 for admin) on every picker load and search.
+- Removed: `overlayAgentFavorites` (internal) and the `favorite_read_failed` error code. The favorites
+  port's `getBulk` is no longer called by the catalog. Consumer action: none.
+
 ## 0.59.261
+
+Automatic changed-only republish (docs/metadata drift since the last published version; verified: `git diff 9a4fd3053c c006aa4394 -- apps/shared/matrx-agents/src`
+has no shipped-source changes outside tests, fixtures and docs). No consumer action required.
+
+## 0.59.260
 ### the pinned read asks the server for those agents only (FW-015)
 
 - `ensureFavoriteRows()` / `readFavoriteAgentRows` now read the starred agents through
@@ -10,6 +26,16 @@
 - The narrow read needs a client with `schema()` (supabase-js has it); without one the store falls back to the
   whole catalog and reports `pinned_read_unsupported`, as before. Consumer action: none.
 
+## 0.59.259
+
+Automatic changed-only republish (docs/metadata drift since the last published version; verified: `git diff 48dc0c53e7 c3bd77d32a -- apps/shared/matrx-agents/src`
+has no shipped-source changes outside tests, fixtures and docs). No consumer action required.
+
+## 0.59.258
+
+Automatic changed-only republish (docs/metadata drift since the last published version; verified: `git diff 0a2b8c9356 48dc0c53e7 -- apps/shared/matrx-agents/src`
+has no shipped-source changes outside tests, fixtures and docs). No consumer action required.
+
 ## 0.59.257
 
 Automatic changed-only republish (docs/metadata drift since the last published version; verified: `git diff 76b41cb76b 0a2b8c9356 -- apps/shared/matrx-agents/src`

package/dist/catalog/index.cjs

@@ -239,9 +239,11 @@ function toAgentSummary(raw) {
     modelId: str(raw["model_id"]),
     isActive: bool(raw["is_active"]),
     isArchived: bool(raw["is_archived"]),
-    // Stars are per-person (platform.user_entity_state) and are overlaid by
-    // `overlayAgentFavorites` — a list row never carries the caller's star.
-    isFavorite: false,
+    // The caller's star. Every read this module maps (agx_get_list_full,
+    // agx_search, agent.agx_get_by_ids) computes it server-side with
+    // platform.my_favorite — platform.user_entity_state for auth.uid(), the
+    // same table the favorites port reads — so no second read is needed (FW-014).
+    isFavorite: bool(raw["is_favorite"]),
     createdBy: str(raw["created_by"]),
     organizationId: str(raw["organization_id"]),
     taskId: str(raw["task_id"]),
@@ -354,29 +356,6 @@ async function readSingleAgentRow(client, agentId) {
   return null;
 }
 var AGENT_FAVORITE_ENTITY_TYPE = "agent";
-async function overlayAgentFavorites(favorites, rows, onError) {
-  if (rows.length === 0) return rows;
-  let starred = null;
-  try {
-    const result = await favorites.getBulk(
-      AGENT_FAVORITE_ENTITY_TYPE,
-      rows.map((r) => r.id)
-    );
-    if (result.ok) {
-      starred = new Set(
-        result.data.items.filter((s) => s.isFavorite).map((s) => s.entityId)
-      );
-    } else {
-      onError(result.error.message);
-    }
-  } catch (e) {
-    onError(e instanceof Error ? e.message : String(e));
-  }
-  return rows.map((r) => {
-    const isFavorite2 = starred?.has(r.id) ?? false;
-    return r.isFavorite === isFavorite2 ? r : { ...r, isFavorite: isFavorite2 };
-  });
-}
 async function writeAgentFavorite(favorites, agentId, isFavorite2) {
   const result = await favorites.setFavorite(
     AGENT_FAVORITE_ENTITY_TYPE,
@@ -832,13 +811,6 @@ function createAgentCatalog(config) {
     identity,
     errorSink
   }).favorites;
-  function reportFavoriteReadFailure(message) {
-    errorSink({
-      code: "favorite_read_failed",
-      message: `your starred agents could not be read (${message}); every star is shown unset until the next catalog load`,
-      context: { catalogId }
-    });
-  }
   const labels = {
     ...DEFAULT_AGENT_CATALOG_LABELS,
     ...config.labels ?? {}
@@ -910,11 +882,7 @@ function createAgentCatalog(config) {
     }
     publish({ ...state, status: "loading", error: null });
     try {
-      const rows = await overlayAgentFavorites(
-        favorites,
-        await readAgentCatalogRows(client),
-        reportFavoriteReadFailure
-      );
+      const rows = await readAgentCatalogRows(client);
       replaceRows(rows);
       publish({ ...state, status: "succeeded", error: null, favoriteRowsStatus: "succeeded" });
       globalState.listFetchedAt.set(catalogId, Date.now());
@@ -1064,13 +1032,7 @@ function createAgentCatalog(config) {
   }
   async function searchServer(query, deep = false) {
     const result = await searchAgentsOnServer(client, { query, deep });
-    mergeRows(
-      await overlayAgentFavorites(
-        favorites,
-        result.rows,
-        reportFavoriteReadFailure
-      )
-    );
+    mergeRows(result.rows);
     return result.ids;
   }
   async function setFavorite(agentId, isFavorite2) {

package/dist/catalog/index.d.cts

@@ -809,9 +809,10 @@ declare function getRegisteredAgentCatalog(catalogId?: string): AgentCatalog | u
  *   2. `agx_search(p_query, p_deep, p_limit, p_offset)` — tier-2 server search.
  *   3. `agx_resolve_agent_address(p_ids)` — the single-agent name read, used
  *      when a mandate's Holder is not in the caller's own catalog.
- *   4. The caller's stars: `ues_get_bulk('agent', ids)` through the
- *      favorites port (`platform.user_entity_state`), overlaid on every row
- *      set this module returns to the store.
+ *   4. The caller's stars arrive ON the rows: every read above computes
+ *      `is_favorite` server-side from `platform.user_entity_state`
+ *      (`platform.my_favorite`). There is no second star read (FW-014; the
+ *      `ues_get_bulk` overlay over every id was retired 2026-10-23).
  *   5. ONE write: the caller's star, `ues_set` through the same port. The
  *      retired `agent.definition.is_favorite` column is never read or written.
  *   6. THE PINNED READ (2026-10-09; by-ids 2026-10-23): the caller's starred

package/dist/catalog/index.d.ts

@@ -809,9 +809,10 @@ declare function getRegisteredAgentCatalog(catalogId?: string): AgentCatalog | u
  *   2. `agx_search(p_query, p_deep, p_limit, p_offset)` — tier-2 server search.
  *   3. `agx_resolve_agent_address(p_ids)` — the single-agent name read, used
  *      when a mandate's Holder is not in the caller's own catalog.
- *   4. The caller's stars: `ues_get_bulk('agent', ids)` through the
- *      favorites port (`platform.user_entity_state`), overlaid on every row
- *      set this module returns to the store.
+ *   4. The caller's stars arrive ON the rows: every read above computes
+ *      `is_favorite` server-side from `platform.user_entity_state`
+ *      (`platform.my_favorite`). There is no second star read (FW-014; the
+ *      `ues_get_bulk` overlay over every id was retired 2026-10-23).
  *   5. ONE write: the caller's star, `ues_set` through the same port. The
  *      retired `agent.definition.is_favorite` column is never read or written.
  *   6. THE PINNED READ (2026-10-09; by-ids 2026-10-23): the caller's starred

package/dist/catalog/index.js

@@ -133,9 +133,11 @@ function toAgentSummary(raw) {
     modelId: str(raw["model_id"]),
     isActive: bool(raw["is_active"]),
     isArchived: bool(raw["is_archived"]),
-    // Stars are per-person (platform.user_entity_state) and are overlaid by
-    // `overlayAgentFavorites` — a list row never carries the caller's star.
-    isFavorite: false,
+    // The caller's star. Every read this module maps (agx_get_list_full,
+    // agx_search, agent.agx_get_by_ids) computes it server-side with
+    // platform.my_favorite — platform.user_entity_state for auth.uid(), the
+    // same table the favorites port reads — so no second read is needed (FW-014).
+    isFavorite: bool(raw["is_favorite"]),
     createdBy: str(raw["created_by"]),
     organizationId: str(raw["organization_id"]),
     taskId: str(raw["task_id"]),
@@ -248,29 +250,6 @@ async function readSingleAgentRow(client, agentId) {
   return null;
 }
 var AGENT_FAVORITE_ENTITY_TYPE = "agent";
-async function overlayAgentFavorites(favorites, rows, onError) {
-  if (rows.length === 0) return rows;
-  let starred = null;
-  try {
-    const result = await favorites.getBulk(
-      AGENT_FAVORITE_ENTITY_TYPE,
-      rows.map((r) => r.id)
-    );
-    if (result.ok) {
-      starred = new Set(
-        result.data.items.filter((s) => s.isFavorite).map((s) => s.entityId)
-      );
-    } else {
-      onError(result.error.message);
-    }
-  } catch (e) {
-    onError(e instanceof Error ? e.message : String(e));
-  }
-  return rows.map((r) => {
-    const isFavorite2 = starred?.has(r.id) ?? false;
-    return r.isFavorite === isFavorite2 ? r : { ...r, isFavorite: isFavorite2 };
-  });
-}
 async function writeAgentFavorite(favorites, agentId, isFavorite2) {
   const result = await favorites.setFavorite(
     AGENT_FAVORITE_ENTITY_TYPE,
@@ -726,13 +705,6 @@ function createAgentCatalog(config) {
     identity,
     errorSink
   }).favorites;
-  function reportFavoriteReadFailure(message) {
-    errorSink({
-      code: "favorite_read_failed",
-      message: `your starred agents could not be read (${message}); every star is shown unset until the next catalog load`,
-      context: { catalogId }
-    });
-  }
   const labels = {
     ...DEFAULT_AGENT_CATALOG_LABELS,
     ...config.labels ?? {}
@@ -804,11 +776,7 @@ function createAgentCatalog(config) {
     }
     publish({ ...state, status: "loading", error: null });
     try {
-      const rows = await overlayAgentFavorites(
-        favorites,
-        await readAgentCatalogRows(client),
-        reportFavoriteReadFailure
-      );
+      const rows = await readAgentCatalogRows(client);
       replaceRows(rows);
       publish({ ...state, status: "succeeded", error: null, favoriteRowsStatus: "succeeded" });
       globalState.listFetchedAt.set(catalogId, Date.now());
@@ -958,13 +926,7 @@ function createAgentCatalog(config) {
   }
   async function searchServer(query, deep = false) {
     const result = await searchAgentsOnServer(client, { query, deep });
-    mergeRows(
-      await overlayAgentFavorites(
-        favorites,
-        result.rows,
-        reportFavoriteReadFailure
-      )
-    );
+    mergeRows(result.rows);
     return result.ids;
   }
   async function setFavorite(agentId, isFavorite2) {

package/dist/context/index.cjs

@@ -470,7 +470,9 @@ function receiptRowToResolved(row, blocks) {
     surfaceKey: row.surface_key,
     origin,
     value: void 0,
-    chars: row.delivered && isServerAuthoritativeKey(row.key) ? row.delivered.chars + attached.reduce((n, b) => n + b.delivered.chars, 0) : row.chars,
+    // The server's own count of the text it sent (the text View opens); the value's
+    // size on the page is only the fallback for a receipt that states none.
+    chars: row.delivered && isServerAuthoritativeKey(row.key) ? row.delivered.chars + attached.reduce((n, b) => n + b.delivered.chars, 0) : row.delivered?.chars ?? row.on_request?.chars ?? row.chars,
     userRule: normalizeUserRule(row.user_rule),
     include: row.include,
     max_inline_chars: row.max_inline_chars,

package/dist/context/index.js

@@ -407,7 +407,9 @@ function receiptRowToResolved(row, blocks) {
     surfaceKey: row.surface_key,
     origin,
     value: void 0,
-    chars: row.delivered && isServerAuthoritativeKey(row.key) ? row.delivered.chars + attached.reduce((n, b) => n + b.delivered.chars, 0) : row.chars,
+    // The server's own count of the text it sent (the text View opens); the value's
+    // size on the page is only the fallback for a receipt that states none.
+    chars: row.delivered && isServerAuthoritativeKey(row.key) ? row.delivered.chars + attached.reduce((n, b) => n + b.delivered.chars, 0) : row.delivered?.chars ?? row.on_request?.chars ?? row.chars,
     userRule: normalizeUserRule(row.user_rule),
     include: row.include,
     max_inline_chars: row.max_inline_chars,

package/dist/context/react/index.cjs

@@ -205,6 +205,20 @@ function buildContextLevels(rows, hierarchy) {
   for (const level of out) level.groups = stableSort(level.groups, (g) => g.ref);
   return stableSort(out, (level) => level.ref);
 }
+function mergeLevels(a, b) {
+  const groups = a.groups.map((g) => ({ ref: g.ref, rows: [...g.rows] }));
+  for (const g of b.groups) {
+    const hit = groups.find((x) => x.ref.id === g.ref.id);
+    if (hit) hit.rows.push(...g.rows);
+    else groups.push({ ref: g.ref, rows: [...g.rows] });
+  }
+  return {
+    ref: { ...a.ref, order: Math.min(a.ref.order ?? 0, b.ref.order ?? 0) },
+    rows: [...a.rows, ...b.rows],
+    groups,
+    master: a.master ?? b.master
+  };
+}
 function buildContextTree(levels) {
   const roots = [];
   const byId = /* @__PURE__ */ new Map();
@@ -228,7 +242,7 @@ function buildContextTree(levels) {
       last = hit;
       siblings = hit.children;
     }
-    if (last) last.level = level;
+    if (last) last.level = last.level ? mergeLevels(last.level, level) : level;
   }
   const sort = (list) => {
     const sorted = stableSort(list, (n) => ({ order: rank.get(n) ?? 0 }));
@@ -857,7 +871,7 @@ var import_controls = require("@ai-matrx/design-system/controls");
 var import_design_system4 = require("@ai-matrx/design-system");
 var import_icons7 = require("@ai-matrx/design-system/icons");
 var import_jsx_runtime4 = require("react/jsx-runtime");
-var BLIND_TOOLTIP = "This model can't read these values";
+var BLIND_TOOLTIP = "Not sent to this model";
 var BLIND_LABEL = "Not read";
 function IconButton({
   label,
@@ -1107,11 +1121,8 @@ function DeliveredSection({
           });
       },
       (error) => {
-        if (live)
-          setLoaded({
-            state: "error",
-            message: error instanceof Error && error.message ? error.message : "Couldn't load"
-          });
+        void error;
+        if (live) setLoaded({ state: "error" });
       }
     );
     return () => {
@@ -1139,18 +1150,21 @@ function DeliveredSection({
         }
       ) : null
     ] }),
-    unavailable ? null : !load ? /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("span", { className: "text-xs text-muted-foreground", children: "\u2014" }) : loaded.state === "loading" ? /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(import_design_system5.Skeleton, { "data-testid": "context-delivered-loading", className: "h-16 w-full" }) : loaded.state === "error" ? /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)(import_design_system5.ErrorBox, { as: "div", message: loaded.message, className: "flex items-center gap-2 text-xs text-destructive", children: [
-      /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("span", { className: "min-w-0 truncate", title: loaded.message, children: loaded.message }),
-      /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(
-        "button",
-        {
-          type: "button",
-          onClick: () => setAttempt((n) => n + 1),
-          className: "shrink-0 rounded px-1.5 py-0.5 text-foreground hover:bg-accent",
-          children: "Retry"
-        }
-      )
-    ] }) : loaded.text === "" ? /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("span", { "data-testid": "context-delivered-empty", className: "text-xs text-muted-foreground", children: "None" }) : /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(
+    unavailable ? null : !load ? /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("span", { className: "text-xs text-muted-foreground", children: "\u2014" }) : loaded.state === "loading" ? /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(import_design_system5.Skeleton, { "data-testid": "context-delivered-loading", className: "h-16 w-full" }) : loaded.state === "error" ? (
+      // Calm and one line: the server's words never reach the person (the host's loader files the error).
+      /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("span", { "data-testid": "context-delivered-unavailable", className: "flex items-center gap-2 text-xs text-muted-foreground", children: [
+        /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("span", { className: "min-w-0 truncate", children: "Text not kept for this message" }),
+        /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(
+          "button",
+          {
+            type: "button",
+            onClick: () => setAttempt((n) => n + 1),
+            className: "shrink-0 rounded px-1.5 py-0.5 text-foreground hover:bg-accent",
+            children: "Try again"
+          }
+        )
+      ] })
+    ) : loaded.text === "" ? /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("span", { "data-testid": "context-delivered-empty", className: "text-xs text-muted-foreground", children: "None" }) : /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(
       "pre",
       {
         "data-testid": "context-delivered-text",

package/dist/context/react/index.js

@@ -167,6 +167,20 @@ function buildContextLevels(rows, hierarchy) {
   for (const level of out) level.groups = stableSort(level.groups, (g) => g.ref);
   return stableSort(out, (level) => level.ref);
 }
+function mergeLevels(a, b) {
+  const groups = a.groups.map((g) => ({ ref: g.ref, rows: [...g.rows] }));
+  for (const g of b.groups) {
+    const hit = groups.find((x) => x.ref.id === g.ref.id);
+    if (hit) hit.rows.push(...g.rows);
+    else groups.push({ ref: g.ref, rows: [...g.rows] });
+  }
+  return {
+    ref: { ...a.ref, order: Math.min(a.ref.order ?? 0, b.ref.order ?? 0) },
+    rows: [...a.rows, ...b.rows],
+    groups,
+    master: a.master ?? b.master
+  };
+}
 function buildContextTree(levels) {
   const roots = [];
   const byId = /* @__PURE__ */ new Map();
@@ -190,7 +204,7 @@ function buildContextTree(levels) {
       last = hit;
       siblings = hit.children;
     }
-    if (last) last.level = level;
+    if (last) last.level = last.level ? mergeLevels(last.level, level) : level;
   }
   const sort = (list) => {
     const sorted = stableSort(list, (n) => ({ order: rank.get(n) ?? 0 }));
@@ -836,7 +850,7 @@ import {
 } from "@ai-matrx/design-system";
 import { EyeOffIcon, PanelRightIcon } from "@ai-matrx/design-system/icons";
 import { jsx as jsx4, jsxs as jsxs4 } from "react/jsx-runtime";
-var BLIND_TOOLTIP = "This model can't read these values";
+var BLIND_TOOLTIP = "Not sent to this model";
 var BLIND_LABEL = "Not read";
 function IconButton({
   label,
@@ -1012,7 +1026,7 @@ import { ChevronLeftIcon, SearchIcon } from "@ai-matrx/design-system/icons";
 
 // context/react/ContextDeliveredValue.tsx
 import * as React4 from "react";
-import { ErrorBox, Skeleton, cn as cn5 } from "@ai-matrx/design-system";
+import { Skeleton, cn as cn5 } from "@ai-matrx/design-system";
 import { jsx as jsx5, jsxs as jsxs5 } from "react/jsx-runtime";
 function ContextDeliveredValue({
   row,
@@ -1091,11 +1105,8 @@ function DeliveredSection({
           });
       },
       (error) => {
-        if (live)
-          setLoaded({
-            state: "error",
-            message: error instanceof Error && error.message ? error.message : "Couldn't load"
-          });
+        void error;
+        if (live) setLoaded({ state: "error" });
       }
     );
     return () => {
@@ -1123,18 +1134,21 @@ function DeliveredSection({
         }
       ) : null
     ] }),
-    unavailable ? null : !load ? /* @__PURE__ */ jsx5("span", { className: "text-xs text-muted-foreground", children: "\u2014" }) : loaded.state === "loading" ? /* @__PURE__ */ jsx5(Skeleton, { "data-testid": "context-delivered-loading", className: "h-16 w-full" }) : loaded.state === "error" ? /* @__PURE__ */ jsxs5(ErrorBox, { as: "div", message: loaded.message, className: "flex items-center gap-2 text-xs text-destructive", children: [
-      /* @__PURE__ */ jsx5("span", { className: "min-w-0 truncate", title: loaded.message, children: loaded.message }),
-      /* @__PURE__ */ jsx5(
-        "button",
-        {
-          type: "button",
-          onClick: () => setAttempt((n) => n + 1),
-          className: "shrink-0 rounded px-1.5 py-0.5 text-foreground hover:bg-accent",
-          children: "Retry"
-        }
-      )
-    ] }) : loaded.text === "" ? /* @__PURE__ */ jsx5("span", { "data-testid": "context-delivered-empty", className: "text-xs text-muted-foreground", children: "None" }) : /* @__PURE__ */ jsx5(
+    unavailable ? null : !load ? /* @__PURE__ */ jsx5("span", { className: "text-xs text-muted-foreground", children: "\u2014" }) : loaded.state === "loading" ? /* @__PURE__ */ jsx5(Skeleton, { "data-testid": "context-delivered-loading", className: "h-16 w-full" }) : loaded.state === "error" ? (
+      // Calm and one line: the server's words never reach the person (the host's loader files the error).
+      /* @__PURE__ */ jsxs5("span", { "data-testid": "context-delivered-unavailable", className: "flex items-center gap-2 text-xs text-muted-foreground", children: [
+        /* @__PURE__ */ jsx5("span", { className: "min-w-0 truncate", children: "Text not kept for this message" }),
+        /* @__PURE__ */ jsx5(
+          "button",
+          {
+            type: "button",
+            onClick: () => setAttempt((n) => n + 1),
+            className: "shrink-0 rounded px-1.5 py-0.5 text-foreground hover:bg-accent",
+            children: "Try again"
+          }
+        )
+      ] })
+    ) : loaded.text === "" ? /* @__PURE__ */ jsx5("span", { "data-testid": "context-delivered-empty", className: "text-xs text-muted-foreground", children: "None" }) : /* @__PURE__ */ jsx5(
       "pre",
       {
         "data-testid": "context-delivered-text",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/agents",
-  "version": "0.59.261",
+  "version": "0.59.263",
   "description": "Portable AI Matrx agent stream protocol, event projection, and safe result-presentation primitives.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -562,5 +562,5 @@
     "verify:tarball": "node ./scripts/verify-tarball.mjs",
     "typegen:self-test": "node scripts/typegen/drop-guard.self-test.mjs && node scripts/typegen/check-api-types-fresh.mjs --self-test"
   },
-  "gitHead": "c006aa4394ac233c23c923f57d06b49f769037ab"
+  "gitHead": "6201da503daf423d01eadb1c5ff2efa5bc846bc0"
 }