@ai-matrx/agents 0.15.1 → 0.16.18

package/CHANGELOG.md

@@ -1,5 +1,149 @@
 # Changelog
 
+## 0.16.18
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/matrx-agents/v0.15.1..npm/matrx-agents/v0.16.18 -- apps/shared/matrx-agents`).
+No source changes intended and no consumer action required.
+
+## 0.16.17
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/matrx-agents/v0.15.1..npm/matrx-agents/v0.16.17 -- apps/shared/matrx-agents`).
+No source changes intended and no consumer action required.
+
+## 0.16.16
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/matrx-agents/v0.15.1..npm/matrx-agents/v0.16.16 -- apps/shared/matrx-agents`).
+No source changes intended and no consumer action required.
+
+## 0.16.15
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/matrx-agents/v0.15.1..npm/matrx-agents/v0.16.15 -- apps/shared/matrx-agents`).
+No source changes intended and no consumer action required.
+
+## 0.16.14
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/matrx-agents/v0.15.1..npm/matrx-agents/v0.16.14 -- apps/shared/matrx-agents`).
+No source changes intended and no consumer action required.
+
+## 0.16.13
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/matrx-agents/v0.15.1..npm/matrx-agents/v0.16.13 -- apps/shared/matrx-agents`).
+No source changes intended and no consumer action required.
+
+## 0.16.12
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/matrx-agents/v0.15.1..npm/matrx-agents/v0.16.12 -- apps/shared/matrx-agents`).
+No source changes intended and no consumer action required.
+
+## 0.16.11
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/matrx-agents/v0.15.1..npm/matrx-agents/v0.16.11 -- apps/shared/matrx-agents`).
+No source changes intended and no consumer action required.
+
+## 0.16.10
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/matrx-agents/v0.15.1..npm/matrx-agents/v0.16.10 -- apps/shared/matrx-agents`).
+No source changes intended and no consumer action required.
+
+## 0.16.9
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/matrx-agents/v0.15.1..npm/matrx-agents/v0.16.9 -- apps/shared/matrx-agents`).
+No source changes intended and no consumer action required.
+
+## 0.16.8
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/matrx-agents/v0.15.1..npm/matrx-agents/v0.16.8 -- apps/shared/matrx-agents`).
+No source changes intended and no consumer action required.
+
+## 0.16.7
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/matrx-agents/v0.15.1..npm/matrx-agents/v0.16.7 -- apps/shared/matrx-agents`).
+No source changes intended and no consumer action required.
+
+## 0.16.6
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/matrx-agents/v0.15.1..npm/matrx-agents/v0.16.6 -- apps/shared/matrx-agents`).
+No source changes intended and no consumer action required.
+
+## 0.16.5
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/matrx-agents/v0.15.1..npm/matrx-agents/v0.16.5 -- apps/shared/matrx-agents`).
+No source changes intended and no consumer action required.
+
+## 0.16.4
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/matrx-agents/v0.15.1..npm/matrx-agents/v0.16.4 -- apps/shared/matrx-agents`).
+No source changes intended and no consumer action required.
+
+## 0.16.3
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/matrx-agents/v0.15.1..npm/matrx-agents/v0.16.3 -- apps/shared/matrx-agents`).
+No source changes intended and no consumer action required.
+
+## 0.16.2
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/matrx-agents/v0.15.1..npm/matrx-agents/v0.16.2 -- apps/shared/matrx-agents`).
+No source changes intended and no consumer action required.
+
+## 0.16.1
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/matrx-agents/v0.15.1..npm/matrx-agents/v0.16.1 -- apps/shared/matrx-agents`).
+No source changes intended and no consumer action required.
+
+## 0.16.0
+
+### Changed (breaking)
+
+- **Agent stars live in `platform.user_entity_state`.** A star is per-person
+  state; the catalog no longer reads or writes the retired
+  `agent.definition.is_favorite` column (a flag on the OWNER's row, which made a
+  shared agent unstarrable and let the classic grid, the picker, Pinned Agents,
+  the /agents list and the Knowledge hub disagree). Every list load and every
+  server-search hit overlays the caller's stars from ONE `ues_get_bulk('agent',
+  ids)`; `setFavorite` writes `ues_set`. Both go through the platform's one
+  `ues_*` chokepoint, `@ai-matrx/associations/core` (new dependency). A failed
+  star read never blocks the catalogue: it reports `favorite_read_failed` and
+  renders every star unset.
+- `AgentCatalogClient` is `rpc()` only — `schema().from().update()` and the
+  `AgentCatalogTableQuery` port are gone (the column write was their only use).
+- `FavoriteAgentButton` (web and native) no longer refuses non-owned rows:
+  "Shared — cannot favorite" existed only because of the owner-row column.
+- `assertAgentCatalogSchema` demands `ues_get_bulk` and no longer probes a
+  column write; `favoriteWritable` and `probeWrite` are removed.
+- A mandate default row whose Holder is being fetched by an in-flight list read
+  waits for that read instead of issuing a second single-row read.
+
+### Added
+
+- `AgentCatalogConfig.favorites` (`AgentCatalogFavorites`) — optional; pass the
+  host's existing favorites service so there is exactly one instance. Default:
+  `createAssociationsStore({ dataSource: client, identity, errorSink }).favorites`.
+
+### Consumer action
+
+- None required: a host passing a supabase-js client keeps working. A host that
+  already holds `@ai-matrx/associations`' favorites service (matrx-frontend's
+  `favoritesService`) should pass it as `favorites`. Remove any host code that
+  reads `favoriteWritable` or passes `probeWrite`.
+
 ## 0.15.1
 
 ### Added

package/README.md

@@ -175,7 +175,8 @@ import { AgentCatalogProvider, AgentListDropdown } from "@ai-matrx/agents/catalo
 
 You get, on every surface and in every app: the complete catalogue read (owned
 + shared + org-shared + platform agents), Mine / Shared / All / Public tabs
-with live counts, sort, favourites (with the write), category and tag filters,
+with live counts, sort, favourites (the caller's own stars, read and written in
+`platform.user_entity_state`), category and tag filters,
 local relevance scoring plus server-side search, the current agent pinned on
 top, per-row origin badges, a hover detail panel, a mobile drawer, and a footer
 count. `AgentListInlinePicker` is the same core without the popover shell.
@@ -197,20 +198,23 @@ the picker shows a persistent banner and calls your `notifier`.
 **Ports.** `client` and `identity` are required and throw when absent. Every
 other port ships a working default: `errorSink` (tagged console), `notifier`
 (the banner is the primary channel), `storage` (localStorage, else memory),
+`favorites` (the `@ai-matrx/associations` `ues_*` chokepoint built on your
+client — pass your own instance if you hold one),
 `labels`, `navigate` (`window.location.assign`), `LinkComponent` (a plain
 `<a>`), `renderModelRef` (plain text) and `openPeek` (absent → the affordance
 is hidden, never dead).
 
 `assertAgentCatalogSchema(client)` proves at boot that the database can answer
-`agx_get_list_full`, `agx_search`, `agx_resolve_agent_address` and the
-favourite write.
+`agx_get_list_full`, `agx_search`, `agx_resolve_agent_address` and
+`ues_get_bulk` (the star read).
 
 ## Runtime support
 
 The package targets modern browsers, browser-based desktop shells,
 extensions, Next.js client or server modules, and Node 20+. Its one runtime
 dependencies are `@ai-matrx/data` (the shared net-resilience + credentials
-layer) and `@ai-matrx/design-system` (the picker's primitives); `react >= 18`
+layer), `@ai-matrx/design-system` (the picker's primitives) and
+`@ai-matrx/associations` (the per-user star chokepoint); `react >= 18`
 is an optional peer needed only by `./react` and `./catalog/react`. No entry
 point performs work at import time.
 

package/dist/catalog/index.cjs

@@ -186,6 +186,9 @@ var DEFAULT_AGENT_CATALOG_LABELS = {
   hoverHint: "Hover an agent to preview its details, or click to select."
 };
 
+// catalog/store.ts
+var import_core = require("@ai-matrx/associations/core");
+
 // catalog/data.ts
 var import_db = require("@ai-matrx/data/db");
 
@@ -235,7 +238,9 @@ function toAgentSummary(raw) {
     modelId: str(raw["model_id"]),
     isActive: bool(raw["is_active"]),
     isArchived: bool(raw["is_archived"]),
-    isFavorite: bool(raw["is_favorite"]),
+    // Stars are per-person (platform.user_entity_state) and are overlaid by
+    // `overlayAgentFavorites` — a list row never carries the caller's star.
+    isFavorite: false,
     createdBy: str(raw["created_by"]),
     organizationId: str(raw["organization_id"]),
     taskId: str(raw["task_id"]),
@@ -344,12 +349,40 @@ async function readSingleAgentRow(client, agentId) {
   }
   return null;
 }
-async function writeAgentFavorite(client, agentId, isFavorite2) {
-  const { error } = await client.schema("agent").from("definition").update({ is_favorite: isFavorite2 }).eq("id", agentId);
-  if (error) {
+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,
+    agentId,
+    isFavorite2
+  );
+  if (!result.ok) {
     throw new AgentCatalogReadError(
-      "agent.definition.is_favorite",
-      pgDetail(error)
+      "user_entity_state (ues_set)",
+      result.error.code ? `${result.error.message} (${result.error.code})` : result.error.message
     );
   }
 }
@@ -563,7 +596,7 @@ async function resolveDefaultRow(args) {
       remedy: `bind the ${verdict.provenance} rung to an agent`
     });
   }
-  let holder = lookupRow(holderId);
+  let holder = await lookupRow(holderId);
   if (!holder) {
     holder = await readSingleAgentRow(client, holderId) ?? void 0;
   }
@@ -617,7 +650,9 @@ var SELF_TEST_MISSING_RPC = "agx_this_function_does_not_exist_probe";
 var DEMANDED_RPCS = {
   agx_get_list_full: {},
   agx_search: { p_query: "__probe__", p_deep: false, p_limit: 1, p_offset: 0 },
-  agx_resolve_agent_address: { p_ids: [BAD_UUID] }
+  agx_resolve_agent_address: { p_ids: [BAD_UUID] },
+  // The caller's stars. Read-only, and an impossible id touches no row.
+  ues_get_bulk: { p_entity_type: "agent", p_entity_ids: [BAD_UUID] }
 };
 function isMissingFunctionError(error) {
   if (!error || typeof error !== "object") return false;
@@ -625,11 +660,7 @@ function isMissingFunctionError(error) {
   return code === "PGRST202" || code === "42883";
 }
 async function assertAgentCatalogSchema(client, options = {}) {
-  const {
-    selfTest = false,
-    throwOnViolation = true,
-    probeWrite = true
-  } = options;
+  const { selfTest = false, throwOnViolation = true } = options;
   const names = Object.keys(DEMANDED_RPCS);
   if (selfTest) names.push(SELF_TEST_MISSING_RPC);
   const missing = [];
@@ -662,41 +693,22 @@ async function assertAgentCatalogSchema(client, options = {}) {
       );
     }
   }
-  let favoriteWritable = null;
-  if (probeWrite) {
-    try {
-      const { error } = await client.schema("agent").from("definition").update({ is_favorite: false }).eq("id", BAD_UUID);
-      favoriteWritable = !isPermissionRefusal(error);
-    } catch (e) {
-      unreachable.push({ fn: "agent.definition.is_favorite", error: e });
-    }
-  }
   if (unreachable.length > 0) {
     throw new Error(
       `assertAgentCatalogSchema could not complete: ${unreachable.length} probe call(s) failed to reach the database (${unreachable.map((u) => u.fn).join(", ")}). This is NOT a schema verdict \u2014 fix connectivity and re-run.`
     );
   }
-  const ok = missing.length === 0 && favoriteWritable !== false;
+  const ok = missing.length === 0;
   const report = {
     ok,
     missing,
     unreachable,
     answered,
-    favoriteWritable,
     orchestraColumn
   };
   if (!ok && throwOnViolation) {
-    const parts = [];
-    if (missing.length > 0) {
-      parts.push(
-        `cannot answer ${missing.length} demanded function(s): ${missing.join(", ")}`
-      );
-    }
-    if (favoriteWritable === false) {
-      parts.push("refuses a write to agent.definition.is_favorite");
-    }
     throw new Error(
-      `DEMANDED SCHEMA VIOLATION: the database this client points at ${parts.join("; and ")}. @ai-matrx/agents/catalog cannot render a correct picker against it \u2014 point the client at Matrx Main, or apply the agx_* migrations.`
+      `DEMANDED SCHEMA VIOLATION: the database this client points at cannot answer ${missing.length} demanded function(s): ${missing.join(", ")}. @ai-matrx/agents/catalog cannot render a correct picker against it \u2014 point the client at Matrx Main, or apply the agx_* migrations.`
     );
   }
   return report;
@@ -707,11 +719,6 @@ function readsOrchestraColumn(data) {
     (row) => typeof row === "object" && row !== null && Object.prototype.hasOwnProperty.call(row, "orchestra")
   );
 }
-function isPermissionRefusal(error) {
-  if (!error) return false;
-  const code = error.code;
-  return code === "42501" || code === "42P01" || code === "PGRST205";
-}
 
 // catalog/store.ts
 var LIST_TTL_MS = 15 * 60 * 1e3;
@@ -748,13 +755,6 @@ function createAgentCatalog(config) {
       remedy: "pass `client` (a supabase-js client, or anything with rpc() and schema().from())"
     });
   }
-  if (typeof config.client.schema !== "function") {
-    throw new AgentCatalogConfigError({
-      code: "client_cannot_write",
-      message: "the client passed to createAgentCatalog has no schema() \u2014 the favorite write has nowhere to go",
-      remedy: "pass a full supabase-js client"
-    });
-  }
   if (!config.identity || typeof config.identity.requireUserId !== "function") {
     throw new AgentCatalogConfigError({
       code: "missing_identity",
@@ -781,6 +781,21 @@ function createAgentCatalog(config) {
   const notifier = config.notifier;
   const storage = config.storage ?? defaultStorage();
   const transport = config.transport;
+  const favorites = config.favorites ?? (0, import_core.createAssociationsStore)({
+    // The catalog's client IS a supabase-js client; the associations
+    // data-source port is the same `rpc(fn, args)` shape, typed over its
+    // own demanded-RPC names.
+    dataSource: client,
+    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 catalogue load`,
+      context: { catalogId }
+    });
+  }
   const labels = {
     ...DEFAULT_AGENT_CATALOG_LABELS,
     ...config.labels ?? {}
@@ -845,7 +860,11 @@ function createAgentCatalog(config) {
   async function load() {
     publish({ ...state, status: "loading", error: null });
     try {
-      const rows = await readAgentCatalogRows(client);
+      const rows = await overlayAgentFavorites(
+        favorites,
+        await readAgentCatalogRows(client),
+        reportFavoriteReadFailure
+      );
       replaceRows(rows);
       publish({ ...state, status: "succeeded", error: null });
       globalState.listFetchedAt.set(catalogId, Date.now());
@@ -928,7 +947,13 @@ function createAgentCatalog(config) {
   }
   async function searchServer(query, deep = false) {
     const result = await searchAgentsOnServer(client, { query, deep });
-    mergeRows(result.rows);
+    mergeRows(
+      await overlayAgentFavorites(
+        favorites,
+        result.rows,
+        reportFavoriteReadFailure
+      )
+    );
     return result.ids;
   }
   async function setFavorite(agentId, isFavorite2) {
@@ -942,7 +967,7 @@ function createAgentCatalog(config) {
     }
     mergeRows([{ ...existing, isFavorite: isFavorite2 }]);
     try {
-      await writeAgentFavorite(client, agentId, isFavorite2);
+      await writeAgentFavorite(favorites, agentId, isFavorite2);
     } catch (e) {
       mergeRows([existing]);
       errorSink({
@@ -994,7 +1019,14 @@ function createAgentCatalog(config) {
           client,
           storage,
           errorSink,
-          lookupRow: (id) => state.byId[id]
+          lookupRow: async (id) => {
+            const hit = state.byId[id];
+            if (hit) return hit;
+            const inFlight = globalState.listInFlight.get(catalogId);
+            if (!inFlight) return void 0;
+            await inFlight.catch(() => void 0);
+            return state.byId[id];
+          }
         });
         getCatalogGlobalState().defaultRows.set(
           `${catalogId}::${mandateKey}`,