@ai-matrx/agents 0.8.0 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,248 @@
 # Changelog
 
+## 0.9.1 — 2026-09-08
+
+**TWO SCREENS TOLD THE SAME USER TWO DIFFERENT TRUTHS. BOTH ARE FIXED HERE, IN
+THE PACKAGE, AT THE CLASS.**
+
+Independent final verification of the picker unification (2026-09-08, same
+account signed in on both surfaces) found the tab strip, the counts, the
+Mine/Shared/All order, the five sort options, the tri-state favourites control,
+the 42 categories, the 871 tags and four tag-only searches identical between
+`aimatrx.com/chat/new` and `workflows.aimatrx.com`. Two things were not.
+
+### Consumer action: none
+
+No export was removed, renamed or re-signed. Three symbols were ADDED —
+`compareAgentIds`, `agentMatchesArchiveFilter`, `selectAgentTabCounts` — and the
+web `AgentRow` gained a `data-testid` matching the native row's `testID`.
+Every host adopts this by taking `latest`; there is nothing to change.
+
+### Behavioural deltas (both deliberate, both were defects)
+
+**F1 — every sort is now a TOTAL order, ending on `id` ASC.**
+
+The Public tab diverged at index 10. 17 rows tied on
+`updated_at = 2026-09-08T06:52:46.430326+00:00`, and the two hosts fetch the
+same RPC through different transports:
+
+| host | request | order of tied rows |
+|---|---|---|
+| matrx-frontend | `POST /rpc/agx_get_list_full` (one shot) | the RPC's own |
+| workflow-studio | `…?order=id.asc&offset=0&limit=1000` (`readAllRows`) | id ASC |
+
+Neither client was wrong about the ROWS. The sort was not total: each
+comparator branch returned `0` for tied rows, so `Array.prototype.sort` left
+them wherever the transport had put them. `sortFilteredAgents` and
+`applyAgentSortComparator` now end on the same final key the database itself
+ends on — `public.agx_get_list` is
+`ORDER BY is_favorite DESC, updated_at DESC, id` — giving:
+
+    searching:     score DESC -> server rank ASC -> sort key -> id ASC
+    not searching: favourites first (when asked) -> sort key -> id ASC
+
+Comparison is a codepoint `<`/`>`, never `localeCompare`: Postgres orders
+`uuid` by its raw bytes and a collator is free to fold case or ignore the
+dashes, which would diverge from the server on exactly these ties. A sort key
+that yields `NaN` (an unparseable timestamp) now collapses to the id key
+instead of defeating it.
+
+*What the frontend used to do on ties: whatever order the RPC page came back
+in.* That was never a decision — it was the absence of one, and it happened to
+look stable only until a second host fetched the same rows a different way. The
+order is now DEFINED, is the server's own, and is a function of the rows alone.
+
+**F5 — a tab badge counts exactly what the tab renders.**
+
+The Mine badge said 416 while the list rendered 412 rows and the footer said
+"412 agents": 4 owned and 2 shared ARCHIVED agents were counted by the badge
+and (correctly) hidden by the list. One screen, three numbers, one of them
+untrue about agents the user cannot see or reach from there. This is "a screen
+never lies", so it is a fix and not a knob.
+
+`selectAgentTabCounts(rows, archFilter)` is the new consumer-aware badge
+source used by `useAgentListCore`, and the four plain aggregate counts
+(`selectTotalUserAgentsCount`, `…Owned…`, `…Shared…`, `…Favorite…`) now honour
+the same archive rule the list uses. Flip the archive filter and the badges
+follow the list into the archive. `selectTotalBuiltinAgentsCount` is
+deliberately unchanged: `filterBuiltinTypeAgents` applies no archive filter
+(a builtin belongs to the platform and is never the user's to archive), so it
+already counted exactly what it rendered.
+
+### The proof
+
+`catalog/__tests__/parity.test.ts`'s 66-row fixture had NO ties, which is why
+293 green cases never saw F1. The new fixture does:
+`catalog/__tests__/total-order-fixture.json` — 42 rows, every one on that exact
+live `updated_at`, 26 of them also tied on `created_at`, with name and category
+tie groups on top, ids deliberately uncorrelated with emission order.
+
+`total-order-expected.json` is generated **from the RULE** by
+`scripts/generate-total-order-fixture.mjs` — favourites -> key -> id ASC,
+written out independently and importing nothing from `catalog/selectors.ts`.
+Regenerating it by running the shipped comparator would have made the test a
+mirror of the code; it measures the specification instead.
+
+720 cases (tab x sort x favouritesFirst x archive x favourite x access) are
+asserted three times over — kernel (`catalog/__tests__/total-order.test.ts`),
+web shell (`catalog/react/total-order.test.tsx`) and native shell
+(`catalog/native/__tests__/total-order.test.tsx`) — each reading the RENDERED
+row ids, not the selector's return value.
+
+Falsifiability, on every leg:
+
+- the same rows are fed in four different input orders (identity, two seeded
+  shuffles, reversed) and the answer must be byte-identical — this is the live
+  defect, reproduced as a test;
+- both shells mount the picker twice with the row array reversed and compare
+  screen to screen;
+- deleting the id tiebreaker turns 4 of the 10 kernel tests red (verified
+  before shipping), and a key-only sort of the same fixture is asserted to
+  disagree with itself under reversal;
+- the F5 legs assert the OLD counting rule produces a DIFFERENT number on this
+  fixture, so "badge == rows" cannot pass vacuously.
+
+`parity.test.ts`'s count assertion now states the F5 delta explicitly — the
+recorded matrx-frontend number minus the archived rows the list hides — rather
+than reproducing a screen that lies. Its 293-case ordering matrix and the
+native shell's 293-case matrix are UNCHANGED and still green: the old fixture
+had no ties, so F1 moved nothing that was already defined.
+
+## 0.9.0 — 2026-09-08
+
+**THE ONE PICKER NOW RENDERS ON REACT NATIVE — `@ai-matrx/agents/catalog/native`.**
+
+Matrx Mobile (Expo 54 / RN 0.81) was the last client still hand-rolling its
+agent list. Its sheet showed four HARDCODED agents plus a Supabase read of a
+`prompts` table that **does not exist in the platform database** — a read whose
+PostgREST error was swallowed into an empty array, so the list silently never
+had anything but the four constants. Three of those four constants named the
+WRONG agent: the ids behind "General Chat", "Deep Research" and "Code Helper"
+resolve in `agent.definition` to *Agent Ledger*, *Knowledge Search Test* and
+*Balanced News Analysis*. A label lying on screen, with nothing anywhere that
+could notice — the same class the mandate default row was built to end.
+
+React Native could not adopt the picker before this release for two concrete
+reasons, and both are fixed here rather than worked around in the app.
+
+### Consumer action (C28)
+
+**Web hosts: none.** `@ai-matrx/agents/catalog` and `/catalog/react` keep every
+export, every name and every behaviour. The provider, the store subscription
+and the two list hooks moved to `catalog/shared/*` so both platforms run one
+implementation; `catalog/react` re-exports all of them unchanged, and the
+`"use client"` banner is still stamped on the react build and still absent from
+the pure ones (the tarball canary now judges eight artefacts instead of four).
+
+**React Native hosts:**
+
+```tsx
+import AsyncStorage from "@react-native-async-storage/async-storage";
+import { createAgentCatalog } from "@ai-matrx/agents/catalog";
+import { AgentCatalogProvider, AgentListSheet } from "@ai-matrx/agents/catalog/native";
+
+const catalog = createAgentCatalog({
+  client: supabase,
+  identity: { requireUserId: () => requireUserId() },
+  storage: AsyncStorage,          // NEW — the async storage seam
+  transport,                      // only when a picker passes defaultMandateKey
+  errorSink: reportToDiagnostics,
+});
+
+<AgentCatalogProvider catalog={catalog} navigate={(href) => router.push(href)}>
+  <AgentListSheet consumerId="chat" onSelect={setAgentId} activeAgentId={agentId} />
+</AgentCatalogProvider>
+```
+
+- `react-native` and `react-native-svg` are OPTIONAL peers. Install
+  `react-native-svg` (`npx expo install react-native-svg`) for the real glyphs;
+  without it the icons fall back to text glyphs and **say so once** through the
+  `errorSink`, with the remedy. Nothing goes blank and nothing goes quiet.
+- Bind `navigate` if your rows should be able to open an agent. Unbound, the
+  default is a no-op that REPORTS through the `errorSink` — never a control
+  that silently does nothing.
+- `@ai-matrx/agents/catalog/styles.css` is a WEB artefact; the native entry
+  needs no stylesheet.
+
+### What is new
+
+- **`@ai-matrx/agents/catalog/native`** — the picker in React Native
+  primitives over the SAME headless kernel and the SAME hooks:
+  `AgentCatalogProvider`, `AgentListSheet` (the body of a bottom sheet — the
+  host keeps its own sheet chrome, so no gesture library is forced on anyone),
+  `AgentListInlinePicker`, and every part beneath them (`AgentListContent`,
+  `AgentListTabs`, `AgentFilterBar`, `AgentRow`, `AgentDetailCard`,
+  `AgentSubView`, `FavoriteAgentButton`, the five primitives, `AgentIcon`).
+  The shells take the web shells' prop surface name for name: `onSelect`,
+  `activeAgentId`, `consumerId`, `initialTab`, `includeSystemInAll`,
+  `visibleTabs`, `systemTabLabel`, `showPinnedAgent`, `excludeAgentIds`,
+  `defaultMandateKey`, `compact`.
+- **The async storage seam** — `AgentCatalogAsyncStorage` /
+  `AgentCatalogStorageLike`, plus `readCachedDefaultRowAsync` and
+  `writeCachedDefaultRowAsync`. `createAgentCatalog({ storage })` now accepts an
+  `AsyncStorage`-shaped store verbatim. React Native has no `localStorage`, so
+  before this a native host could only hand the catalog a store that answered
+  `null` synchronously (a lie) or lose the default row's first paint entirely.
+  **The web path is unchanged**: `AgentCatalogStorage` is still synchronous,
+  `readCachedDefaultRow`/`writeCachedDefaultRow` still have their synchronous
+  signatures, `defaultStorage()` still prefers `localStorage`, and the async
+  helpers over a synchronous store produce byte-identical cache payloads
+  (proven in `catalog/__tests__/storage-seam.test.ts`).
+- **`AgentCatalogNativeTheme`** (C26 on a platform with no CSS) — the native
+  twin of the `--matrx-agent-*` sheet: every token ships a DEFAULT VALUE so the
+  picker renders correctly unthemed, and a host re-brands by passing `theme` to
+  the provider. `DEFAULT_AGENT_CATALOG_NATIVE_THEME` (dark) and
+  `LIGHT_AGENT_CATALOG_NATIVE_THEME` ship; `resolveAgentCatalogNativeTheme`
+  merges an override and keeps every value it omits. No native component
+  contains a colour literal.
+- **`catalog/shared/icon-paths.ts`** — the glyph geometry, once. The web icons
+  now read it too, so a shape can never differ between the two platforms; the
+  native entry draws the same paths through `react-native-svg` (C19: still no
+  icon-library dependency, on either platform).
+- **`AgentListTabCounts` moved** to `catalog/shared/useAgentListCore` beside the
+  code that computes it. `catalog/react/AgentListTabs` re-exports it unchanged.
+
+### Behavioural deltas on native, recorded rather than hidden
+
+1. **No hover preview.** The web picker's side panel opens on hover; a touch
+   screen has no hover, so the detail card is reached by the row's chevron —
+   the same three-view stack (`list → detail → sort/categories/tags`) the web
+   `AgentListInlinePicker` already used on mobile widths.
+2. **No cmd-click link.** `AgentRow`'s anchor exists on the web so a person can
+   open an agent in a new tab. React Native has neither, so the row is an
+   ordinary `Pressable`; the `LinkComponent` port still exists and still ships
+   a working native default.
+3. **`autoFocusSearch` defaults to `false`** (the web inline picker defaults to
+   `true`): a keyboard that opens with the sheet covers the list it was meant
+   to filter.
+
+### Proof
+
+- **The 293-case ordering matrix, re-measured through the RENDERED native
+  list** (`catalog/native/__tests__/parity.test.tsx`): every case's ids, in
+  order, read back out of the mounted native tree — not out of the selectors a
+  second time. Sharing a kernel is an architecture claim; this is the
+  measurement. It carries a falsifiability leg.
+- **The tarball canary imports AND requires `./catalog/native`**, checks every
+  documented export, proves the theme override merges over the PACKED build,
+  proves the icon degradation announces exactly once with its remedy, and
+  compiles a native usage (including an `AsyncStorage`-shaped `storage`) against
+  the packed types under `exactOptionalPropertyTypes` + `noUncheckedIndexedAccess`.
+- **The banner canary now judges eight artefacts**: the `"use client"` prologue
+  must be present on both `catalog/react` builds and ABSENT from all four
+  `catalog/index.*` and all four `catalog/native/index.*` files.
+
+### Known limits, stated plainly
+
+There is still **no React Native canary harness** in this workspace (campaign
+decision C7 schedules it for Phase 2), and the real `react-native` package
+cannot be loaded by vitest — it ships Flow-typed source only Metro parses. The
+native tests therefore render against a minimal RN stand-in
+(`catalog/native/__tests__/react-native.stub.tsx`) that maps RN primitives onto
+DOM nodes. That proves rows, order, labels, counts, handlers and every
+announced degradation. It does **not** prove pixel layout, gestures or Hermes —
+those are proven by the consuming Expo app's own build and device smoke.
+
 ## 0.8.0 — 2026-09-08
 
 **THE ORCHESTRA BADGE IS BACK, in every client at once.**

package/dist/catalog/index.cjs

@@ -34,10 +34,12 @@ __export(catalog_exports, {
   _resetCatalogGlobalState: () => _resetCatalogGlobalState,
   agentConsumerHasActiveFilters: () => agentConsumerHasActiveFilters,
   agentListEmptyLabel: () => agentListEmptyLabel,
+  agentMatchesArchiveFilter: () => agentMatchesArchiveFilter,
   agentMatchesSearch: () => agentMatchesSearch,
   applyAgentSortComparator: () => applyAgentSortComparator,
   asAgentId: () => asAgentId,
   assertAgentCatalogSchema: () => assertAgentCatalogSchema,
+  compareAgentIds: () => compareAgentIds,
   computeAgentSearchScore: () => computeAgentSearchScore,
   createAgentCatalog: () => createAgentCatalog,
   createMemoryStorage: () => createMemoryStorage,
@@ -69,9 +71,11 @@ __export(catalog_exports, {
   parseMandateResolution: () => parseMandateResolution,
   readAgentCatalogRows: () => readAgentCatalogRows,
   readCachedDefaultRow: () => readCachedDefaultRow,
+  readCachedDefaultRowAsync: () => readCachedDefaultRowAsync,
   readSingleAgentRow: () => readSingleAgentRow,
   resolveDefaultRow: () => resolveDefaultRow,
   searchAgentsOnServer: () => searchAgentsOnServer,
+  selectAgentTabCounts: () => selectAgentTabCounts,
   selectAllAgentCategories: () => selectAllAgentCategories,
   selectAllAgentTags: () => selectAllAgentTags,
   selectAllSystemAgentCategories: () => selectAllSystemAgentCategories,
@@ -87,7 +91,8 @@ __export(catalog_exports, {
   sortFilteredAgents: () => sortFilteredAgents,
   toAgentSummary: () => toAgentSummary,
   writeAgentFavorite: () => writeAgentFavorite,
-  writeCachedDefaultRow: () => writeCachedDefaultRow
+  writeCachedDefaultRow: () => writeCachedDefaultRow,
+  writeCachedDefaultRowAsync: () => writeCachedDefaultRowAsync
 });
 module.exports = __toCommonJS(catalog_exports);
 
@@ -312,8 +317,8 @@ async function readSingleAgentRow(client, agentId) {
   }
   return null;
 }
-async function writeAgentFavorite(client, agentId, isFavorite) {
-  const { error } = await client.schema("agent").from("definition").update({ is_favorite: isFavorite }).eq("id", agentId);
+async function writeAgentFavorite(client, agentId, isFavorite2) {
+  const { error } = await client.schema("agent").from("definition").update({ is_favorite: isFavorite2 }).eq("id", agentId);
   if (error) {
     throw new AgentCatalogReadError(
       "agent.definition.is_favorite",
@@ -430,6 +435,51 @@ function writeCachedDefaultRow(storage, resolved) {
   } catch {
   }
 }
+function parseCachedDefaultRow(mandateKey, raw) {
+  try {
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    if (!isRecord2(parsed)) return null;
+    const holderId = parsed["holderId"];
+    const holderName = parsed["holderName"];
+    if (typeof holderId !== "string" || typeof holderName !== "string") {
+      return null;
+    }
+    const description = parsed["holderDescription"];
+    const provenance = parsed["provenance"];
+    const at = parsed["at"];
+    return {
+      mandateKey,
+      holderId,
+      holderName,
+      holderDescription: typeof description === "string" ? description : null,
+      provenance: typeof provenance === "string" ? provenance : "system",
+      at: typeof at === "number" ? at : 0
+    };
+  } catch {
+    return null;
+  }
+}
+async function readCachedDefaultRowAsync(storage, mandateKey) {
+  let raw;
+  try {
+    raw = await storage.getItem(
+      CACHE_PREFIX + mandateKey
+    );
+  } catch {
+    return null;
+  }
+  return parseCachedDefaultRow(mandateKey, raw);
+}
+async function writeCachedDefaultRowAsync(storage, resolved) {
+  try {
+    await storage.setItem(
+      CACHE_PREFIX + resolved.mandateKey,
+      JSON.stringify(resolved)
+    );
+  } catch {
+  }
+}
 function defaultRowFromResolution(resolved) {
   return {
     id: mandateAgentId(resolved.mandateKey),
@@ -469,7 +519,7 @@ function detectDefaultRowDrift(cached, live) {
 }
 async function resolveDefaultRow(args) {
   const { mandateKey, transport, client, storage, lookupRow } = args;
-  const cached = readCachedDefaultRow(storage, mandateKey);
+  const cached = await readCachedDefaultRowAsync(storage, mandateKey);
   const verdict = await askTheServer(transport, mandateKey);
   if (verdict.holderType !== "agent") {
     throw new MandateDefaultRowError({
@@ -506,7 +556,7 @@ async function resolveDefaultRow(args) {
     at: Date.now()
   };
   const drift = detectDefaultRowDrift(cached, resolved);
-  writeCachedDefaultRow(storage, resolved);
+  await writeCachedDefaultRowAsync(storage, resolved);
   return { resolved, row: defaultRowFromResolution(resolved), drift };
 }
 
@@ -846,7 +896,7 @@ function createAgentCatalog(config) {
     mergeRows(result.rows);
     return result.ids;
   }
-  async function setFavorite(agentId, isFavorite) {
+  async function setFavorite(agentId, isFavorite2) {
     const existing = state.byId[agentId];
     if (!existing) {
       errorSink({
@@ -855,15 +905,15 @@ function createAgentCatalog(config) {
       });
       return;
     }
-    mergeRows([{ ...existing, isFavorite }]);
+    mergeRows([{ ...existing, isFavorite: isFavorite2 }]);
     try {
-      await writeAgentFavorite(client, agentId, isFavorite);
+      await writeAgentFavorite(client, agentId, isFavorite2);
     } catch (e) {
       mergeRows([existing]);
       errorSink({
         code: "favorite_write_failed",
         message: `the favorite could not be saved: ${errorMessage(e)}`,
-        context: { agentId, isFavorite }
+        context: { agentId, isFavorite: isFavorite2 }
       });
       notifier?.({
         level: "error",
@@ -1142,7 +1192,19 @@ function memoize3(fn) {
     return last;
   };
 }
+function compareAgentIds(a, b) {
+  const idA = a.id ?? "";
+  const idB = b.id ?? "";
+  if (idA < idB) return -1;
+  if (idA > idB) return 1;
+  return 0;
+}
 function applyAgentSortComparator(a, b, sortBy) {
+  const primary = compareAgentSortKey(a, b, sortBy);
+  if (!Number.isFinite(primary) || primary === 0) return compareAgentIds(a, b);
+  return primary;
+}
+function compareAgentSortKey(a, b, sortBy) {
   switch (sortBy) {
     case "name-asc":
       return (a.name ?? "").localeCompare(b.name ?? "");
@@ -1390,21 +1452,45 @@ var makeSelectFilteredBuiltinAgentsCount = () => {
 function agentConsumerHasActiveFilters(consumer, defaults) {
   return consumer.tab !== defaults.tab || consumer.sortBy !== defaults.sortBy || consumer.searchTerm !== "" || consumer.includedCats.length > 0 || consumer.includedTags.length > 0 || consumer.favFilter !== defaults.favFilter || consumer.archFilter !== defaults.archFilter || consumer.accessFilter !== defaults.accessFilter || consumer.favoritesFirst !== defaults.favoritesFirst;
 }
+function agentMatchesArchiveFilter(agent, archFilter) {
+  if (archFilter === "active") return !agent.isArchived;
+  if (archFilter === "archived") return Boolean(agent.isArchived);
+  return true;
+}
+function countUserRows(agents, archFilter, predicate) {
+  let n = 0;
+  for (const a of agents) {
+    if (a.agentType !== "user") continue;
+    if (!agentMatchesArchiveFilter(a, archFilter)) continue;
+    if (predicate(a)) n += 1;
+  }
+  return n;
+}
+var isOwned = (a) => a.isOwner === true;
+var isShared = (a) => a.isOwner === false && a.accessLevel != null;
+var isAny = () => true;
+var isFavorite = (a) => Boolean(a.isFavorite);
+var selectAgentTabCounts = memoize2(
+  (agents, archFilter) => ({
+    mine: countUserRows(agents, archFilter, isOwned),
+    shared: countUserRows(agents, archFilter, isShared),
+    all: countUserRows(agents, archFilter, isAny),
+    system: selectBuiltinTypeAgents(agents).length
+  })
+);
 var selectTotalUserAgentsCount = memoize1(
-  (agents) => selectUserTypeAgents(agents).length
+  (agents) => countUserRows(agents, "active", isAny)
 );
 var selectTotalOwnedAgentsCount = memoize1(
-  (agents) => selectUserTypeAgents(agents).filter((a) => a.isOwner === true).length
+  (agents) => countUserRows(agents, "active", isOwned)
 );
 var selectTotalSharedAgentsCount = memoize1(
-  (agents) => selectUserTypeAgents(agents).filter(
-    (a) => a.isOwner === false && a.accessLevel != null
-  ).length
+  (agents) => countUserRows(agents, "active", isShared)
 );
 var selectTotalBuiltinAgentsCount = memoize1(
   (agents) => selectBuiltinTypeAgents(agents).length
 );
 var selectTotalFavoriteAgentsCount = memoize1(
-  (agents) => selectUserTypeAgents(agents).filter((a) => a.isFavorite).length
+  (agents) => countUserRows(agents, "active", isFavorite)
 );
 //# sourceMappingURL=index.cjs.map