@ai-matrx/agents 0.6.2 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,239 @@
 # Changelog
 
+## 0.7.1 — 2026-09-08
+
+**0.7.0's two catalog entries did not typecheck together.** `./catalog` and
+`./catalog/react` are emitted by two separate tsup passes (only the react group
+carries the `"use client"` banner), so each `.d.ts` holds its own copy of the
+shared declarations. `AgentId` was branded with a `unique symbol`, which is
+NOMINAL — the two copies were unrelated types, and the wiring the 0.7.0
+`Consumer action` prescribes:
+
+```tsx
+<AgentCatalogProvider catalog={createAgentCatalog({ client, identity })}>
+```
+
+failed with *"Two different types with this name exist, but they are
+unrelated"* in every consumer. Every runtime canary was green; only a `tsc` in
+a real host caught it (matrx-extend, on its first compile of the adoption).
+
+### Consumer action (C28)
+
+Update to 0.7.1 and the documented wiring compiles. No source change is needed
+in a host — if you worked around this with a cast, DELETE the cast.
+
+### The fix, and the guard
+
+- `AgentId` is now branded with a string literal
+  (`string & { readonly __agentId: "ai-matrx.agent-id" }`). A literal brand is
+  structural, so the two emitted copies unify; a bare `string` still cannot be
+  passed where an `AgentId` is required, so the branding is not weakened. Any
+  future brand in this package follows the same rule — the reason is recorded
+  at the declaration.
+- `scripts/verify-tarball.mjs` grew THE TWO-ENTRY TYPE-IDENTITY CANARY: it
+  installs the packed tarball into a scratch consumer with `strict`,
+  `exactOptionalPropertyTypes`, `noUncheckedIndexedAccess` and
+  `skipLibCheck: false`, then compiles the real provider wiring plus reads that
+  cross the seam in both directions. Proven RED against the 0.7.0 brand
+  (the same "two different types" error, from the packed types) and GREEN
+  after the fix. It runs inside `pnpm check:package`, which the publish
+  workflow gates on.
+
+
+## 0.7.0 — 2026-09-08
+
+**THE ONE AGENT PICKER moves into the package.** Two new entries — `./catalog`
+(pure) and `./catalog/react` (client-stamped) — carry the whole of
+matrx-frontend's canonical agent picker: the complete-list read, filter / sort /
+search / tabs / counts, the favourite write, the mandate-resolved default row
+with its drift screamer, and both picker shells. Owner ruling (Arman,
+2026-09-08): the picker and ALL its logic live in the package; an app provides
+identity and a Supabase client and nothing else, and the host's only contract
+is `onSelect(agentId)`.
+
+Every existing entry is untouched. This release is purely additive.
+
+### Consumer action (C28)
+
+1. **Install nothing new.** `@ai-matrx/design-system` is now an ordinary
+   dependency of this package (`"latest"`, per THE LATEST LAW).
+
+2. **Create the catalog ONCE and mount the provider ONCE:**
+
+   ```ts
+   // lib/agents/catalog.ts
+   import { createAgentCatalog } from "@ai-matrx/agents/catalog";
+
+   export const agentCatalog = createAgentCatalog({
+     client: supabase,                                   // REQUIRED
+     identity: { requireUserId: () => requireUserId() }, // REQUIRED (throws when signed out)
+     transport,        // REQUIRED only if a picker passes `defaultMandateKey`
+     errorSink,        // optional — default: a tagged console.error naming the remedy
+     notifier,         // optional — the drift banner is the primary scream either way
+     storage,          // optional — default: localStorage when it answers, else memory
+     labels,           // optional — every user-visible string
+   });
+   ```
+
+   ```tsx
+   // app providers
+   import "@ai-matrx/agents/catalog/styles.css";
+   import { AgentCatalogProvider } from "@ai-matrx/agents/catalog/react";
+
+   <AgentCatalogProvider
+     catalog={agentCatalog}
+     LinkComponent={Link}            // optional — default: a plain <a> (cmd-click works)
+     navigate={router.push}          // optional — default: window.location.assign
+     renderModelRef={renderModelRef} // optional — default: the model id as text
+     openPeek={openSneakPeek}        // ABSENT → the peek affordance is hidden, never dead
+     popoverContainer={dialogContainer}
+   >
+     {children}
+   </AgentCatalogProvider>
+   ```
+
+3. **Register this package's build with your Tailwind source scan**, exactly as
+   you already do for `@ai-matrx/design-system` — the picker's layout uses
+   ordinary utilities and your Tailwind only generates what it can see:
+
+   ```css
+   @import "tailwindcss";
+   @source "../node_modules/@ai-matrx/agents/dist";
+   ```
+
+4. **Swap the imports; the prop surface is unchanged.** `AgentListDropdown`
+   and `AgentListInlinePicker` keep every prop they had (`onSelect`,
+   `navigateTo`, `activeAgentId`, `contentSide`, `consumerId`, `initialTab`,
+   `includeSystemInAll`, `visibleTabs`, `systemTabLabel`, `resolveAgentHref`,
+   `showPinnedAgent`, `excludeAgentIds`, `triggerSlot`, `noBorder`, `compact`)
+   and gain `defaultMandateKey`.
+
+5. **Files a host can DELETE once it adopts** (matrx-frontend paths; the same
+   shapes exist in matrx-extend and matrx-local):
+   - `features/agents/redux/agent-consumers/slice.ts`
+   - `features/agents/redux/agent-consumers/selectors.ts`
+   - `features/agents/search/score.ts`
+   - `features/agents/constants/agent-list-labels.ts`
+   - `features/agents/hooks/useAgentConsumer.ts`
+   - `features/agents/hooks/useServerAgentSearch.ts`
+   - `features/agents/components/agent-listings/AgentListDropdown.tsx`
+   - `features/agents/components/agent-listings/AgentListInlinePicker.tsx`
+   - `features/agents/components/agent-listings/useAgentListCore.ts`
+   - `features/agents/components/agent-listings/core/*` (AgentListContent,
+     AgentListTabs, AgentFilterBar, AgentRow, AgentDetailCard, AgentSortPanel,
+     AgentCategoriesPanel, AgentTagsPanel, AgentMobileSubView, primitives, types)
+   - `features/agents/components/agent-listings/FavoriteAgentButton.tsx`
+   - the `agentConsumers` reducer registration in the store
+   - matrx-extend `PilotAgentPicker`, `AgentPicker`, `scope.ts`, the Settings
+     default-agent `PillSelect`; matrx-local `AgentPicker.tsx` and its
+     `fetchCloudAgents` sort — plus every hardcoded default-agent NAME.
+
+### `@ai-matrx/agents/catalog` — the headless kernel (pure, no banner)
+
+- `createAgentCatalog(config)` — required ports `client` (a structural subset
+  of `SupabaseClient`: `rpc`, `schema().from()`) and `identity.requireUserId()`;
+  a missing one throws `AgentCatalogConfigError` with a remedy. Optional
+  `errorSink`, `notifier`, `storage`, `transport`, `labels`, `catalogId`, each
+  with a working default and a documented degradation.
+- The complete-list read (`agx_get_list_full`), the tier-2 server search
+  (`agx_search`), the single-agent name read (`agx_resolve_agent_address`), and
+  the ONE write (`agent.definition.is_favorite`, optimistic with rollback).
+- Per-consumer view state keyed by `consumerId` (tabs, sort, search, favourite
+  / archive / access filters, category and tag inclusion, paging, server-search
+  results) plus every selector: `filterUserTypeAgents`,
+  `filterBuiltinTypeAgents`, `sortFilteredAgents`, `applyAgentSortComparator`,
+  `makeSelectFilteredAgents`, the five count selectors, the four split
+  category/tag option selectors, `AGENT_NONE_SENTINEL`, and the scorer.
+- `assertAgentCatalogSchema(client)` — the demanded-schema probe, with a
+  `selfTest` leg that refuses a probe which cannot fail.
+- Branded `AgentId`; strict types throughout (`exactOptionalPropertyTypes`,
+  `noUncheckedIndexedAccess`, zero `any`).
+- No module-level mutable state: the catalog registry, the in-flight list
+  promise, the freshness stamp and the default-row cache live on `globalThis`
+  under `Symbol.for("ai-matrx.agents.catalog")`.
+
+### `@ai-matrx/agents/catalog/react` — the picker (client-stamped)
+
+`AgentCatalogProvider`, `useAgentCatalog`, `useAgentConsumer`,
+`useAgentListCore`, `AgentListDropdown`, `AgentListInlinePicker`,
+`AgentListContent`, `AgentListTabs`, `AgentFilterBar`, `AgentRow`,
+`AgentDetailCard`, `AgentSortPanel`, `AgentCategoriesPanel`, `AgentTagsPanel`,
+`AgentMobileSubView`, `FavoriteAgentButton`, the primitives, and
+`./catalog/styles.css` (structural CSS + a default token sheet; no hardcoded
+colour in any component). React stays an optional peer; the ~20 Lucide glyphs
+are inlined SVGs (C19 — no icon dependency).
+
+### The default row, and THE DRIFT SCREAM (design D3)
+
+A picker instance may pass `defaultMandateKey`. The catalog resolves the
+Holder through the aidream door `GET /mandates/{mandate_key}/resolution`
+(verified against `aidream/api/routers/mandate_bindings.py`
+`get_mandate_resolution`, mounted at prefix `/mandates`) using the injected
+`transport` — 🚨 clients NEVER walk the mandate ladder themselves (D-R1), so a
+`defaultMandateKey` with no transport throws a typed config error. The row
+renders the Holder's REAL name and description; its id stays
+`mandate:<key>`, byte-identical to the ref shape matrx-extend and matrx-local
+already hand their hosts. The last resolution is cached for first paint, and
+whenever cached and live disagree on holder id or holder name the picker shows
+a PERSISTENT in-picker banner and calls the `notifier` — never console-only.
+This kills the class that made matrx-local's row say "Matrx Desktop Agent"
+while `local.cloud_chat` resolved to General Chat.
+
+### Behavioural deltas from the matrx-frontend original (recorded, never silent)
+
+1. **The list read is now COMPLETE OR LOUD.** `fetchAgentsListFull` issued a
+   bare `.rpc("agx_get_list_full")`, which PostgREST silently caps at
+   `db-max-rows` (1000). The package reads through `@ai-matrx/data`'s
+   `readAllRows` with `{ count: "exact" }` and a stable `.order("id")`, so a
+   truncated catalogue is an `IncompleteReadError`, not a short picker. Row
+   ORDER from the DB was already irrelevant — every row is re-sorted client
+   side.
+2. **"Clear (n)" now clears n.** `AgentCategoriesPanel`, `AgentTagsPanel` and
+   `AgentMobileSubView` ran `includedCats.forEach(toggleCategory)`; each toggle
+   computes its next array from the same render's snapshot, so three toggles in
+   one tick removed exactly ONE category. matrx-frontend's own
+   `useAgentConsumer` documents the hazard and names `setIncludedCats` as the
+   fix; the call sites never adopted it. They do here.
+3. **`AGENT_PUBLIC_BADGE_LABEL` was dead.** The frontend declared it as the
+   builtin row's badge label ("Public") and `AgentRow` rendered the literal
+   `system`; nothing ever read the constant. The badge is now the
+   `labels.systemBadge` port, defaulting to `"system"` — the string that
+   actually shipped.
+4. **No app-wide "active agent" store.** By ruling D1 that is host state, so
+   the pinned row comes from the `activeAgentId` prop alone; the frontend's
+   fallback to a Redux `activeAgentId` has no package twin.
+5. **A click never goes nowhere.** A call site passing neither `onSelect` nor
+   `navigateTo` used to `dispatch(setActiveAgentId(...))`; here it reports to
+   the `errorSink` instead of silently doing nothing.
+6. **`isVersion` filtering is structural, not conditional.** The frontend's
+   `selectLiveAgents` strips version snapshots out of a store that also holds
+   them; this catalog only ever holds list rows, so the filter is a no-op and
+   is not ported. Every ordering, tie-break and count is unchanged.
+7. **Three class names are package-owned.** `scrollbar-none`,
+   `animate-in fade-in-0` and `animate-spin` came from the host's own globals
+   or a Tailwind plugin; a package never invents a class name and expects the
+   consumer to generate it, so they ship here as `matrx-agent-scrollbar-none`,
+   `matrx-agent-fade-in` and `matrx-agent-spin`. The amber favourite star and
+   the drift banner are `--matrx-agent-*` tokens with default values.
+8. **Server search is folded into `useAgentConsumer`.** The frontend's separate
+   `useServerAgentSearch` hook was wired in exactly one place — here — so it
+   is one hook, with the same debounce (250ms), the same 2-character floor and
+   the same stale-response guard.
+
+### Parity proof
+
+`matrx-frontend/scripts/agent-picker-parity-fixture.ts` runs THE ORIGINAL
+matrx-frontend selectors over 66 realistic `agx_get_list_full` rows (owned,
+directly-shared, org-shared, builtin, favourites, archived, null names, null
+categories, untagged rows, unicode, duplicate names, colliding timestamps)
+across a 295-case matrix — every tab × every sort × favoritesFirst × favourite
+filter × archive filter × access filter × category and tag inclusion including
+the none-sentinel × ten search queries × server-matched ids × the admin blended
+"All" — and writes the expected ordered id lists, counts and option lists to
+`catalog/__tests__/parity-expected.json`. `catalog/__tests__/parity.test.ts`
+asserts the ported selectors reproduce all of it exactly, and carries a
+falsifiability leg that requires a perturbed row to turn the matrix red.
+
 ## 0.6.2
 
 Automatic changed-only republish (docs/metadata drift since the last tag — see

package/README.md

@@ -1,9 +1,9 @@
 # @ai-matrx/agents
 
 Portable client-side primitives for AI Matrx agent applications. The package
-standardizes the stream wire, pure request/workflow projection, and safe
-Creator-facing result boundaries without importing React, Redux, Next.js, or
-application code.
+standardizes the stream wire, pure request/workflow projection, safe
+Creator-facing result boundaries, and THE agent picker — without importing
+Redux, Next.js, or application code.
 
 **This package talks to the fully assembled AI Dream brain. It does not run the
 provider/tool loop locally; use `@ai-matrx/agent-engine` when you need to run a
@@ -146,12 +146,72 @@ const { phase, projection, start, cancel } = useAgentRun({ transport });
 `useFollowRuntimeOperation({ transport, executionId, onEvent })` is the
 reconnect follower as a hook — production stall/retry/cursor policy built in.
 
+## THE agent picker (`./catalog` + `./catalog/react`)
+
+There is ONE agent picker on this platform and it ships here. An app provides a
+Supabase client and who the user is; the picker's contract back is
+`onSelect(agentId)`.
+
+```ts
+// once, anywhere
+import { createAgentCatalog } from "@ai-matrx/agents/catalog";
+
+export const agentCatalog = createAgentCatalog({
+  client: supabase,                                   // REQUIRED
+  identity: { requireUserId: () => requireUserId() }, // REQUIRED
+  transport,   // only when a picker passes `defaultMandateKey`
+});
+```
+
+```tsx
+// once, at the top of your tree
+import "@ai-matrx/agents/catalog/styles.css";
+import { AgentCatalogProvider, AgentListDropdown } from "@ai-matrx/agents/catalog/react";
+
+<AgentCatalogProvider catalog={agentCatalog} LinkComponent={Link}>
+  <AgentListDropdown activeAgentId={agentId} onSelect={setAgentId} />
+</AgentCatalogProvider>
+```
+
+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,
+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.
+
+Register this package's build with your Tailwind source scan so the picker's
+utilities are generated:
+
+```css
+@import "tailwindcss";
+@source "../node_modules/@ai-matrx/agents/dist";
+```
+
+**The default row.** Pass `defaultMandateKey` and the picker offers the
+platform default for that Mandate, resolved LIVE through the server and
+labelled with the Holder's real name — no client ever hardcodes an agent name
+again. Its id is `mandate:<key>`. If the cached name and the live one disagree,
+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),
+`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.
+
 ## Runtime support
 
 The package targets modern browsers, browser-based desktop shells,
 extensions, Next.js client or server modules, and Node 20+. Its one runtime
-dependency is `@ai-matrx/data` (the shared net-resilience + credentials
-layer); `react >= 18` is an optional peer needed only by `./react`. No entry
+dependencies are `@ai-matrx/data` (the shared net-resilience + credentials
+layer) and `@ai-matrx/design-system` (the picker's primitives); `react >= 18`
+is an optional peer needed only by `./react` and `./catalog/react`. No entry
 point performs work at import time.
 
 ## Development