@ai-matrx/agents 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,140 @@
 # Changelog
 
+## 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

@@ -69,6 +69,7 @@ __export(catalog_exports, {
   parseMandateResolution: () => parseMandateResolution,
   readAgentCatalogRows: () => readAgentCatalogRows,
   readCachedDefaultRow: () => readCachedDefaultRow,
+  readCachedDefaultRowAsync: () => readCachedDefaultRowAsync,
   readSingleAgentRow: () => readSingleAgentRow,
   resolveDefaultRow: () => resolveDefaultRow,
   searchAgentsOnServer: () => searchAgentsOnServer,
@@ -87,7 +88,8 @@ __export(catalog_exports, {
   sortFilteredAgents: () => sortFilteredAgents,
   toAgentSummary: () => toAgentSummary,
   writeAgentFavorite: () => writeAgentFavorite,
-  writeCachedDefaultRow: () => writeCachedDefaultRow
+  writeCachedDefaultRow: () => writeCachedDefaultRow,
+  writeCachedDefaultRowAsync: () => writeCachedDefaultRowAsync
 });
 module.exports = __toCommonJS(catalog_exports);
 
@@ -430,6 +432,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 +516,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 +553,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 };
 }