@ai-matrx/agents 0.7.1 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,230 @@
 # 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.**
+
+An **Orchestra** is a conductor agent that delegates to member agents at run
+time: choosing one for a step, a chat or a workflow node runs the whole
+ensemble. The Workflow Studio's old hand-rolled picker showed that — a
+conductor marker, the member count, the run mode, the tagline and the member
+titles — because the Python route `GET /agents` stamped it from
+`platform.associations`.
+
+Every picker on the platform now reads the RPC `agx_get_list_full`, and that
+RPC had no such column. So the day the pickers unified, EVERY client lost the
+badge at once, and an Orchestra became indistinguishable from an ordinary
+agent in the one place where the difference decides what happens next.
+
+The fix is in the read every client shares, not in any client.
+
+### Consumer action (C28)
+
+**None for the badge — it appears by itself.** The column is served by the
+platform RPC, this package parses it, and the picker renders it. Update to
+`0.8.0` (hosts on `"latest"` get it on their next install) and any Orchestra in
+the list wears its marker.
+
+**One import path changed, compatibly:** `SORT_OPTIONS` now lives in the pure
+`@ai-matrx/agents/catalog` entry. `@ai-matrx/agents/catalog/react` re-exports
+it unchanged, so nothing breaks — but a server-reachable module that only wants
+the five sort labels should import it from `./catalog` and stop dragging the
+`"use client"` bundle into a server graph.
+
+**Rendering your own summary of a chosen agent?** Use the exported `Music4Icon`
+and `orchestraLabel` / `orchestraDelegatesLine` / `orchestraDepthLine` rather
+than writing a second vocabulary for the same badge.
+
+### What is new
+
+- **`AgentSummary.orchestra: OrchestraBadge | null`** — strict, on every row.
+  `{ mode, tagline, depthBudget, memberCount, memberTitles }`, camelCased from
+  the new nullable `orchestra jsonb` column.
+- **`AgentRow`** carries the conductor marker: the Orchestra glyph plus the
+  member count, titled with the delegates line. Absent on an ordinary agent —
+  never a dead or empty chip.
+- **`AgentDetailCard`** leads with the Orchestra block — "Orchestra · supervisor
+  · 4 members", the tagline, "Delegates to: …" (collapsing past three into
+  "+N more") and the declared delegation depth. It sits ABOVE the description
+  because it changes what selecting this agent MEANS.
+- **`orchestraLabel` / `orchestraModeLabel` / `orchestraDelegatesLine` /
+  `orchestraDepthLine`** — the Creator words, ported verbatim from the studio
+  picker, exported from both entries.
+- **`Music4Icon`** — inlined SVG (C19), the same glyph the studio used.
+- **`assertAgentCatalogSchema`** reports `orchestraColumn: boolean | null`: a
+  database that predates the column is VISIBLE, not silently badge-less.
+
+### The platform side
+
+Migration `matrx-frontend/migrations/agx_list_orchestra_badge_column.sql` adds
+a trailing nullable `orchestra jsonb` to `agx_get_list`, `agx_get_list_full`
+and `agx_search`, built by ONE new helper `public.agx_orchestra_badges()` —
+the conductor self-edge (`source_type='agent'`, `source_id=target_id`,
+`role='orchestra'`) for mode/tagline/depth_budget, its `role='member'` edges
+for the count and the non-empty labels. Membership, `ORDER BY`, `SECURITY
+DEFINER`, `search_path` and every grant are unchanged; the page is cut BEFORE
+the badge join so `LIMIT`/`OFFSET` still bite on exactly the rows they did.
+
+### Deliberate deltas, said out loud
+
+- **`depthBudget` is what the composition DECLARED, and `null` when it declared
+  nothing.** The old studio badge printed the EFFECTIVE ceiling, defaulting to
+  the platform constant `PROJECTED_AGENT_MAX_RECURSION_DEPTH`. That constant
+  lives in the Python that enforces it; copying it into SQL and again into
+  TypeScript would be three places to drift. So a composition with no declared
+  budget shows no depth line at all, rather than a number nobody wrote.
+- **The literal token "orchestra" is not searchable.** The studio's picker let
+  an author type the word and see only ensembles. The canonical scorer this
+  package ports (from matrx-frontend) never had that, and adding it would
+  change the 295-case parity matrix. Not ported; recorded here rather than lost.
+
+### Proof
+
+`catalog/__tests__/orchestra.test.ts` layers conductor rows onto the SAME
+66-row parity fixture and asserts the badge survives the parser, every sort,
+the user/builtin split and a real filtered-search selector, pinned to literal
+expectations (comparing output to input passes trivially when both are null —
+which is the regression it exists to catch). `catalog/react/picker.test.tsx`
+renders a conductor beside an ordinary agent and asserts the marker, its count,
+its hover text and its ABSENCE on the ordinary row. Both proven RED on a
+deliberate perturbation and GREEN restored.
+
+
 ## 0.7.1 — 2026-09-08
 
 **0.7.0's two catalog entries did not typecheck together.** `./catalog` and

package/dist/catalog/index.cjs

@@ -30,6 +30,7 @@ __export(catalog_exports, {
   DEFAULT_AGENT_CATALOG_LABELS: () => DEFAULT_AGENT_CATALOG_LABELS,
   DEFAULT_AGENT_CONSUMER_STATE: () => DEFAULT_AGENT_CONSUMER_STATE,
   MandateDefaultRowError: () => MandateDefaultRowError,
+  SORT_OPTIONS: () => SORT_OPTIONS,
   _resetCatalogGlobalState: () => _resetCatalogGlobalState,
   agentConsumerHasActiveFilters: () => agentConsumerHasActiveFilters,
   agentListEmptyLabel: () => agentListEmptyLabel,
@@ -61,9 +62,14 @@ __export(catalog_exports, {
   memoize1: () => memoize1,
   memoize2: () => memoize2,
   memoize3: () => memoize3,
+  orchestraDelegatesLine: () => orchestraDelegatesLine,
+  orchestraDepthLine: () => orchestraDepthLine,
+  orchestraLabel: () => orchestraLabel,
+  orchestraModeLabel: () => orchestraModeLabel,
   parseMandateResolution: () => parseMandateResolution,
   readAgentCatalogRows: () => readAgentCatalogRows,
   readCachedDefaultRow: () => readCachedDefaultRow,
+  readCachedDefaultRowAsync: () => readCachedDefaultRowAsync,
   readSingleAgentRow: () => readSingleAgentRow,
   resolveDefaultRow: () => resolveDefaultRow,
   searchAgentsOnServer: () => searchAgentsOnServer,
@@ -82,7 +88,8 @@ __export(catalog_exports, {
   sortFilteredAgents: () => sortFilteredAgents,
   toAgentSummary: () => toAgentSummary,
   writeAgentFavorite: () => writeAgentFavorite,
-  writeCachedDefaultRow: () => writeCachedDefaultRow
+  writeCachedDefaultRow: () => writeCachedDefaultRow,
+  writeCachedDefaultRowAsync: () => writeCachedDefaultRowAsync
 });
 module.exports = __toCommonJS(catalog_exports);
 
@@ -96,6 +103,13 @@ function mandateAgentId(mandateKey) {
 function isMandateAgentId(id) {
   return id.startsWith("mandate:");
 }
+var SORT_OPTIONS = [
+  { value: "updated-desc", label: "Recent" },
+  { value: "created-desc", label: "Created" },
+  { value: "name-asc", label: "A \u2192 Z" },
+  { value: "name-desc", label: "Z \u2192 A" },
+  { value: "category-asc", label: "Category" }
+];
 var AGENT_NONE_SENTINEL = "__none__";
 var DEFAULT_AGENT_CONSUMER_STATE = {
   tab: "mine",
@@ -165,6 +179,18 @@ function stringArray(value) {
 function agentType(value) {
   return value === "builtin" ? "builtin" : "user";
 }
+function orchestraBadge(value) {
+  if (!isRecord(value)) return null;
+  const depth = value["depth_budget"];
+  const count = value["member_count"];
+  return {
+    mode: str(value["mode"]) ?? "supervisor",
+    tagline: str(value["tagline"]),
+    depthBudget: typeof depth === "number" && Number.isFinite(depth) && depth > 0 ? depth : null,
+    memberCount: typeof count === "number" && Number.isFinite(count) && count >= 0 ? count : 0,
+    memberTitles: stringArray(value["member_titles"])
+  };
+}
 function toAgentSummary(raw) {
   if (!isRecord(raw)) return null;
   const id = str(raw["id"]);
@@ -188,7 +214,8 @@ function toAgentSummary(raw) {
     updatedAt: str(raw["updated_at"]),
     isOwner: boolOrNull(raw["is_owner"]),
     accessLevel: str(raw["access_level"]),
-    sharedByEmail: str(raw["shared_by_email"])
+    sharedByEmail: str(raw["shared_by_email"]),
+    orchestra: orchestraBadge(raw["orchestra"])
   };
 }
 
@@ -405,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),
@@ -426,6 +498,9 @@ function defaultRowFromResolution(resolved) {
     isOwner: null,
     accessLevel: null,
     sharedByEmail: null,
+    // A mandate default row is a live reference to whichever agent the mandate
+    // resolves to; the badge belongs to the RESOLVED agent's own catalog row.
+    orchestra: null,
     mandateKey: resolved.mandateKey
   };
 }
@@ -441,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({
@@ -478,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 };
 }
 
@@ -530,10 +605,14 @@ async function assertAgentCatalogSchema(client, options = {}) {
   const missing = [];
   const unreachable = [];
   const answered = [];
+  let orchestraColumn = null;
   for (const fn of names) {
     const args = DEMANDED_RPCS[fn] ?? {};
     try {
-      const { error } = await client.rpc(fn, args);
+      const { data, error } = await client.rpc(fn, args);
+      if (fn === "agx_get_list_full" && error == null) {
+        orchestraColumn = readsOrchestraColumn(data);
+      }
       if (error == null) answered.push(fn);
       else if (isMissingFunctionError(error)) missing.push(fn);
       else answered.push(fn);
@@ -573,7 +652,8 @@ async function assertAgentCatalogSchema(client, options = {}) {
     missing,
     unreachable,
     answered,
-    favoriteWritable
+    favoriteWritable,
+    orchestraColumn
   };
   if (!ok && throwOnViolation) {
     const parts = [];
@@ -591,6 +671,12 @@ async function assertAgentCatalogSchema(client, options = {}) {
   }
   return report;
 }
+function readsOrchestraColumn(data) {
+  if (!Array.isArray(data) || data.length === 0) return null;
+  return data.some(
+    (row) => typeof row === "object" && row !== null && Object.prototype.hasOwnProperty.call(row, "orchestra")
+  );
+}
 function isPermissionRefusal(error) {
   if (!error) return false;
   const code = error.code;
@@ -964,6 +1050,33 @@ function getRegisteredAgentCatalog(catalogId = "default") {
   return found;
 }
 
+// catalog/orchestra.ts
+var ORCHESTRA_MODE_LABEL = {
+  supervisor: "supervisor",
+  sequential: "in order",
+  parallel: "together",
+  dag: "custom flow"
+};
+function orchestraModeLabel(mode) {
+  return ORCHESTRA_MODE_LABEL[mode] ?? mode;
+}
+function orchestraLabel(badge) {
+  const n = badge.memberCount;
+  return `Orchestra \xB7 ${orchestraModeLabel(badge.mode)} \xB7 ${n} ${n === 1 ? "member" : "members"}`;
+}
+function orchestraDepthLine(badge) {
+  const n = badge.depthBudget;
+  if (typeof n !== "number" || n <= 0) return null;
+  return `Team members can call helpers up to ${n} ${n === 1 ? "level" : "levels"} deep`;
+}
+function orchestraDelegatesLine(badge, limit = 3) {
+  const titles = badge.memberTitles;
+  if (titles.length === 0) return null;
+  const shown = titles.slice(0, limit);
+  const extra = titles.length - shown.length;
+  return `Delegates to: ${shown.join(", ")}${extra > 0 ? ` +${extra} more` : ""}`;
+}
+
 // catalog/labels.ts
 function agentListEmptyLabel(tab, labels) {
   switch (tab) {