@ai-matrx/agents 0.59.263 → 0.59.265

package/CHANGELOG.md

@@ -1,7 +1,57 @@
 # Changelog
 
+<!-- matrx-auto-git-docs-resolution-needed-delete-this-when-resolved — two versions follow: LOCAL first, then GITHUB. (LOCAL latest 2026-10-23 13:10; GITHUB latest 2026-10-23 13:07; LOCAL lacks 3 of GITHUB's 5 new lines; GITHUB lacks 26 of LOCAL's 26 new lines; recover: git show c3687a0589:'apps/shared/matrx-agents/CHANGELOG.md' / f84d7bf4e5:'apps/shared/matrx-agents/CHANGELOG.md') Delete these three marker lines when resolved. -->
+
+## 0.59.265
+### tagged rows without the catalog (FW-014, composer)
+
+- `ensureTaggedRows(tags)` + `readAgentTaggedRows` (`agent.agx_picker_tagged`, live 2026-10-23, reach verified
+  against `agx_get_list_full`): the caller's live agents carrying any tag, never the whole catalog.
+  Consumer action: none.
+
+### the agent menu opens on one thin page, never the catalog (FW-014)
+
+- Every picker (`AgentListDropdown`, `AgentListPanel`, `AgentListInlinePicker`, native `AgentPickerBody`)
+  now opens on ONE page of `agent.agx_picker_page` — favorites, then the agents the person used most
+  recently, then name; 50 rows; only the columns a row renders; the tab counts on page 1 — and reads the
+  next page on scroll. Typing still searches `agx_search`. Measured in SQL: page 1 3.4 KB (ordinary account)
+  / 32 KB (admin) in ~0.2–0.4 s, where opening the menu used to read 673 / 1,476 full rows (~340 KB, 2.6 s).
+  The whole catalog is read only when the person opens the category/tag facets, picks another sort, a
+  favorites/access filter, or the host passes `agentFilter` — or when another surface already holds it fresh.
+- New on the catalog: `ensurePickerPage(query)`, `loadMorePickerPage(query)`, `ensureAgentRows(ids)` (full
+  rows by id through `agent.agx_get_by_ids`), `state.pickerPages`, `agentPickerPageKey`, `pickerReads`.
+  New data doors: `readAgentPickerPage`, `readAgentRowsByIds`, `PICKER_PAGE_SIZE`. `AgentSummary` gains
+  `isThin` (a page row: no description/model/offering/task/source/sharer) and `lastUsedAt`.
+- A thin row never replaces a full one; hovering a thin row reads that one row (web and native detail
+  cards render the full row when it lands); the pinned current agent is read by id when it is not on page 1.
+- `useAgentSummary` reads the one row by id (`ensureAgentRows`) instead of loading the whole catalog;
+  server search remains the fallback for an id that read does not return.
+- `useAgentListCore` returns `paged`, `hasMore`, `loadingMore`, `loadMore`, `totalCount`,
+  `ensureFullCatalog`; `AgentListContent` (web) takes `hasMore` / `onReachEnd` / `loadingMore` /
+  `totalCount`, native takes `onReachEnd` / `totalCount`.
+- Knob: `createAgentCatalog({ pickerReads: "catalog" })` restores the read-everything-on-open behavior (a
+  host whose client cannot reach the `agent` schema; tests of the full-list rules). Default `"page"`.
+- Consumer action: none for hosts using supabase-js (needs `agent.agx_picker_page`, live since
+  2026-10-23). A host that reads `catalog.getState().rows` expecting the whole catalog after a picker
+  opened must call `ensureLoaded()` itself — the picker no longer loads it. A host component that
+  renders a hovered agent's description from the picker's object should read the store row
+  (`getAgent(id)`), which `ensureAgentRows` fills.
+
+### no second star read after a catalog or search read (FW-014)
+<!-- matrx-auto-git-docs-resolution-needed-delete-this-when-resolved — GITHUB version below -->
+## 0.59.264
+
+Automatic changed-only republish (docs/metadata drift since the last published version; verified: `git diff 6201da503d aa81498da0 -- apps/shared/matrx-agents/src`
+has no shipped-source changes outside tests, fixtures and docs). No consumer action required.
+
 ## 0.59.263
+
+Automatic changed-only republish (docs/metadata drift since the last published version; verified: `git diff de2b958734 6201da503d -- apps/shared/matrx-agents/src`
+has no shipped-source changes outside tests, fixtures and docs). No consumer action required.
+
+## 0.59.262
 ### no second star read after a catalog or search read (FW-014)
+<!-- matrx-auto-git-docs-resolution-needed-delete-this-when-resolved — end of both versions -->
 
 - `ensureLoaded()` and `searchServer()` no longer follow each read with `ues_get_bulk('agent', every id)`.
   Every catalog read (`agx_get_list_full`, `agx_search`, `agent.agx_get_by_ids`) already returns

package/dist/catalog/index.cjs

@@ -256,7 +256,8 @@ function toAgentSummary(raw) {
     orchestra: orchestraBadge(raw["orchestra"]),
     // Present only when the read carries the column: absent ≠ "no pin".
     ..."offering_id" in raw ? { offeringId: str(raw["offering_id"]) } : {},
-    ..."organization_name" in raw ? { organizationName: str(raw["organization_name"]) } : {}
+    ..."organization_name" in raw ? { organizationName: str(raw["organization_name"]) } : {},
+    ..."last_used_at" in raw ? { lastUsedAt: str(raw["last_used_at"]) } : {}
   };
 }
 
@@ -395,20 +396,77 @@ async function readFavoriteAgentRows(client, favorites) {
     )
   );
   if (ids.length === 0) return [];
+  const rows = await readAgentRowsByIds(client, ids, "agent.agx_get_by_ids (pinned)");
+  return rows.map((summary) => summary.isFavorite ? summary : { ...summary, isFavorite: true });
+}
+async function readAgentRowsByIds(client, agentIds, label = "agent.agx_get_by_ids") {
+  if (typeof client.schema !== "function") {
+    throw new AgentPinnedReadUnsupported("the client has no schema()");
+  }
+  const ids = Array.from(new Set(agentIds.filter((id) => typeof id === "string" && id.length > 0)));
   const rows = [];
   for (let at = 0; at < ids.length; at += PINNED_ID_CHUNK) {
     const chunk = ids.slice(at, at + PINNED_ID_CHUNK);
     const { data, error } = await client.schema("agent").rpc("agx_get_by_ids", { p_ids: chunk });
     if (error) {
-      throw new AgentCatalogReadError("agent.agx_get_by_ids (pinned)", pgDetail(error));
+      throw new AgentCatalogReadError(label, pgDetail(error));
     }
     for (const item of Array.isArray(data) ? data : []) {
       const summary = toAgentSummary(item);
-      if (summary) rows.push(summary.isFavorite ? summary : { ...summary, isFavorite: true });
+      if (summary) rows.push(summary);
     }
   }
   return rows;
 }
+var PICKER_PAGE_SIZE = 50;
+function countOf(record, key) {
+  const value = record[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+async function readAgentPickerPage(client, query, cursor = null, limit = PICKER_PAGE_SIZE) {
+  if (typeof client.schema !== "function") {
+    throw new AgentPinnedReadUnsupported("the client has no schema()");
+  }
+  const { data, error } = await client.schema("agent").rpc("agx_picker_page", {
+    p_tab: query.tab,
+    p_archive: query.archive,
+    p_include_quick: query.includeQuick,
+    p_cursor: cursor ?? null,
+    p_limit: limit
+  });
+  if (error) throw new AgentCatalogReadError("agent.agx_picker_page", pgDetail(error));
+  const record = typeof data === "object" && data !== null && !Array.isArray(data) ? data : null;
+  if (!record) {
+    throw new AgentCatalogReadError("agent.agx_picker_page", "the page came back without a body");
+  }
+  const rows = [];
+  for (const item of Array.isArray(record["rows"]) ? record["rows"] : []) {
+    const summary = toAgentSummary(item);
+    if (summary) rows.push({ ...summary, isThin: true });
+  }
+  const rawCounts = record["counts"];
+  const counts = typeof rawCounts === "object" && rawCounts !== null && !Array.isArray(rawCounts) ? {
+    mine: countOf(rawCounts, "mine"),
+    shared: countOf(rawCounts, "shared"),
+    all: countOf(rawCounts, "all"),
+    system: countOf(rawCounts, "system"),
+    archivedHidden: countOf(rawCounts, "archived_hidden")
+  } : null;
+  return { rows, nextCursor: record["next_cursor"] ?? null, counts };
+}
+async function readAgentTaggedRows(client, tags) {
+  if (typeof client.schema !== "function") {
+    throw new AgentPinnedReadUnsupported("the client has no schema()");
+  }
+  const { data, error } = await client.schema("agent").rpc("agx_picker_tagged", { p_tags: [...tags] });
+  if (error) throw new AgentCatalogReadError("agent.agx_picker_tagged", pgDetail(error));
+  const rows = [];
+  for (const item of Array.isArray(data) ? data : []) {
+    const summary = toAgentSummary(item);
+    if (summary) rows.push({ ...summary, isThin: true });
+  }
+  return rows;
+}
 
 // catalog/default-row.ts
 var CACHE_PREFIX = "ai-matrx.agents.catalog.default-row:";
@@ -746,6 +804,9 @@ function readsOrchestraColumn(data) {
 // catalog/store.ts
 var LIST_TTL_MS = 15 * 60 * 1e3;
 var LIST_STALE_MS = 4 * 60 * 60 * 1e3;
+function agentPickerPageKey(query) {
+  return `${query.tab}|${query.archive}|${query.includeQuick ? "q" : "-"}`;
+}
 function createDefaultErrorSink() {
   let announced = false;
   return (event) => {
@@ -829,7 +890,8 @@ function createAgentCatalog(config) {
     error: null,
     consumers: {},
     defaultRows: {},
-    favoriteRowsStatus: "idle"
+    favoriteRowsStatus: "idle",
+    pickerPages: {}
   };
   const listeners = /* @__PURE__ */ new Set();
   function publish(next) {
@@ -839,7 +901,10 @@ function createAgentCatalog(config) {
   function mergeRows(incoming) {
     if (incoming.length === 0) return;
     const byId = { ...state.byId };
-    for (const row of incoming) byId[row.id] = row;
+    for (const row of incoming) {
+      const held = byId[row.id];
+      byId[row.id] = row.isThin && held && !held.isThin ? { ...held, isFavorite: row.isFavorite, ...row.lastUsedAt !== void 0 ? { lastUsedAt: row.lastUsedAt } : {} } : row;
+    }
     publish({ ...state, byId, rows: Object.values(byId) });
   }
   function replaceRows(incoming) {
@@ -977,6 +1042,164 @@ function createAgentCatalog(config) {
     favoriteRowsInFlight = run;
     return run;
   }
+  const pickerInFlight = /* @__PURE__ */ new Map();
+  function writePickerPage(key, next) {
+    publish({ ...state, pickerPages: { ...state.pickerPages, [key]: next } });
+  }
+  async function readPickerPage(query, first) {
+    const key = agentPickerPageKey(query);
+    const prior = state.pickerPages[key];
+    if (getUserIdOrNull() === null) {
+      writePickerPage(key, { ids: [], nextCursor: null, done: true, status: "succeeded", loadingMore: false, error: null, counts: { mine: 0, shared: 0, all: 0, system: 0, archivedHidden: 0 }, fetchedAt: Date.now() });
+      return;
+    }
+    const base = {
+      ids: [],
+      nextCursor: null,
+      done: false,
+      status: "loading",
+      loadingMore: false,
+      error: null,
+      counts: null,
+      fetchedAt: 0
+    };
+    if (first) {
+      if (!prior || prior.status === "failed") writePickerPage(key, { ...prior ?? base, status: "loading", error: null });
+    } else if (prior) {
+      writePickerPage(key, { ...prior, loadingMore: true, error: null });
+    }
+    try {
+      const page = await readAgentPickerPage(client, query, first ? null : prior?.nextCursor ?? null);
+      mergeRows(page.rows);
+      const current = state.pickerPages[key];
+      const keptIds = first ? [] : current?.ids ?? [];
+      const seen = new Set(keptIds);
+      const ids = [...keptIds];
+      for (const row of page.rows) if (!seen.has(row.id)) {
+        seen.add(row.id);
+        ids.push(row.id);
+      }
+      writePickerPage(key, {
+        ids,
+        nextCursor: page.nextCursor,
+        done: page.nextCursor === null || page.nextCursor === void 0,
+        status: "succeeded",
+        loadingMore: false,
+        error: null,
+        counts: page.counts ?? current?.counts ?? null,
+        fetchedAt: first ? Date.now() : current?.fetchedAt ?? Date.now()
+      });
+    } catch (e) {
+      if (e instanceof AgentPinnedReadUnsupported) {
+        errorSink({
+          code: "picker_page_unsupported",
+          message: `the agent picker fell back to the whole catalog (${e.message}); pass a supabase-js client`,
+          context: { catalogId }
+        });
+        const current2 = state.pickerPages[key];
+        writePickerPage(key, { ...current2 ?? base, status: "failed", loadingMore: false, error: "unsupported" });
+        await ensureLoaded();
+        return;
+      }
+      const message = errorMessage(e);
+      const current = state.pickerPages[key];
+      writePickerPage(key, { ...current ?? base, status: "failed", loadingMore: false, error: message });
+      errorSink({
+        code: "picker_page_failed",
+        message: `the agent list could not be read: ${message}`,
+        context: { catalogId, query }
+      });
+      throw e;
+    }
+  }
+  function runPicker(key, run) {
+    const existing = pickerInFlight.get(key);
+    if (existing) return existing;
+    const promise = run().finally(() => {
+      if (pickerInFlight.get(key) === promise) pickerInFlight.delete(key);
+    });
+    pickerInFlight.set(key, promise);
+    return promise;
+  }
+  function ensurePickerPage(query) {
+    const key = agentPickerPageKey(query);
+    const held = state.pickerPages[key];
+    if (held && held.status === "succeeded" && Date.now() - held.fetchedAt < LIST_TTL_MS) {
+      return Promise.resolve();
+    }
+    return runPicker(key, () => readPickerPage(query, true));
+  }
+  function loadMorePickerPage(query) {
+    const key = agentPickerPageKey(query);
+    const held = state.pickerPages[key];
+    if (!held || held.done || held.status !== "succeeded" || held.loadingMore) return Promise.resolve();
+    return runPicker(key, () => readPickerPage(query, false));
+  }
+  const rowsInFlight = /* @__PURE__ */ new Map();
+  async function ensureAgentRows(agentIds) {
+    if (getUserIdOrNull() === null) return;
+    const waits = [];
+    const wanted = [];
+    for (const id of agentIds) {
+      if (!id || id.startsWith("mandate:")) continue;
+      const held = state.byId[id];
+      if (held && !held.isThin) continue;
+      const flying = rowsInFlight.get(id);
+      if (flying) waits.push(flying);
+      else wanted.push(id);
+    }
+    if (wanted.length > 0) {
+      const run = (async () => {
+        try {
+          mergeRows(await readAgentRowsByIds(client, wanted));
+        } catch (e) {
+          errorSink({
+            code: "agent_rows_read_failed",
+            message: `agent details could not be read: ${errorMessage(e)}`,
+            context: { catalogId, count: wanted.length }
+          });
+          throw e;
+        }
+      })();
+      const settled = run.finally(() => {
+        for (const id of wanted) if (rowsInFlight.get(id) === settled) rowsInFlight.delete(id);
+      });
+      for (const id of wanted) rowsInFlight.set(id, settled);
+      waits.push(settled);
+    }
+    await Promise.all(waits);
+  }
+  const taggedAt = /* @__PURE__ */ new Map();
+  const taggedInFlight = /* @__PURE__ */ new Map();
+  function ensureTaggedRows(tags) {
+    if (tags.length === 0 || isFresh() || getUserIdOrNull() === null) return Promise.resolve();
+    const key = [...tags].sort().join("|");
+    const at = taggedAt.get(key);
+    if (at !== void 0 && Date.now() - at < LIST_TTL_MS) return Promise.resolve();
+    const flying = taggedInFlight.get(key);
+    if (flying) return flying;
+    const run = (async () => {
+      try {
+        mergeRows(await readAgentTaggedRows(client, tags));
+        taggedAt.set(key, Date.now());
+      } catch (e) {
+        if (e instanceof AgentPinnedReadUnsupported) {
+          await ensureLoaded();
+          return;
+        }
+        errorSink({
+          code: "tagged_rows_read_failed",
+          message: `agents tagged ${key} could not be read: ${errorMessage(e)}`,
+          context: { catalogId, tags }
+        });
+        throw e;
+      }
+    })().finally(() => {
+      if (taggedInFlight.get(key) === run) taggedInFlight.delete(key);
+    });
+    taggedInFlight.set(key, run);
+    return run;
+  }
   function getConsumer(consumerId) {
     return state.consumers[consumerId] ?? consumerDefaults;
   }
@@ -1171,6 +1394,7 @@ function createAgentCatalog(config) {
     errorSink,
     notifier,
     canResolveMandates: transport !== void 0,
+    pickerReads: config.pickerReads === "catalog" ? "catalog" : "page",
     consumerDefaults,
     getState: () => state,
     subscribe: (listener) => {
@@ -1184,6 +1408,10 @@ function createAgentCatalog(config) {
     ensureLoaded,
     ensureFavoriteRows,
     seedFavoriteRows,
+    ensurePickerPage,
+    loadMorePickerPage,
+    ensureAgentRows,
+    ensureTaggedRows,
     isFresh,
     isStale,
     getConsumer,

package/dist/catalog/index.d.cts

@@ -128,6 +128,16 @@ interface AgentSummary {
      * host can tell "the default" from a stored agent without parsing the id.
      */
     mandateKey?: string;
+    /**
+     * THE THIN ROW (FW-014). `true` when this row came from the picker's page
+     * read (`agent.agx_picker_page`), which carries only what a picker row
+     * renders: no description, model, offering, task, source or sharer. A
+     * consumer that needs those asks `catalog.ensureAgentRows([id])` (hover,
+     * open), which replaces it with the full row. Absent = a full row.
+     */
+    isThin?: boolean;
+    /** When the caller last used this agent (their latest conversation with it). Page reads only. */
+    lastUsedAt?: string | null;
 }
 type AgentSortOption = "updated-desc" | "created-desc" | "name-asc" | "name-desc" | "category-asc";
 /**
@@ -528,6 +538,15 @@ interface AgentCatalogConfig {
     transport?: AgentCatalogTransport;
     /** OPTIONAL — label overrides. */
     labels?: Partial<AgentCatalogLabels>;
+    /**
+     * How a picker reads its list (FW-014). DEFAULT `"page"`: the menu opens on
+     * one server page (`agent.agx_picker_page`, ~50 thin rows + counts) and pages
+     * on scroll; the whole catalog is read only when the person narrows by
+     * category/tag/sort/filter. `"catalog"`: every picker reads the whole catalog
+     * on open (the pre-2026-10-23 behavior) — for a host whose client cannot
+     * reach the `agent` schema, and for tests of the full-list rules.
+     */
+    pickerReads?: "page" | "catalog";
     /**
      * OPTIONAL — the host's starting values for per-consumer view state.
      * See `AgentCatalogDefaults`.
@@ -579,6 +598,111 @@ type AgentCatalogResolveHref = (agent: AgentSummary) => string;
  */
 type AgentCatalogOpenPeek = (agent: AgentSummary) => void;
 
+/**
+ * catalog/data.ts — @ai-matrx/agents/catalog
+ *
+ * Every database call the catalog makes, and nothing else. Five of them:
+ *
+ *   1. `agx_get_list_full()` — the complete catalog (owned + directly-shared
+ *      + org-shared user agents, unioned with active builtins).
+ *   2. `agx_search(p_query, p_deep, p_limit, p_offset)` — tier-2 server search.
+ *   3. `agx_resolve_agent_address(p_ids)` — the single-agent name read, used
+ *      when a mandate's Holder is not in the caller's own catalog.
+ *   4. The caller's stars arrive ON the rows: every read above computes
+ *      `is_favorite` server-side from `platform.user_entity_state`
+ *      (`platform.my_favorite`). There is no second star read (FW-014; the
+ *      `ues_get_bulk` overlay over every id was retired 2026-10-23).
+ *   5. ONE write: the caller's star, `ues_set` through the same port. The
+ *      retired `agent.definition.is_favorite` column is never read or written.
+ *   6. THE PINNED READ (2026-10-09; by-ids 2026-10-23): the caller's starred
+ *      ids (`ues_list` through the favorites port), then
+ *      `agent.agx_get_by_ids(p_ids)` for exactly those ids. A sidebar's Pinned
+ *      section shows a handful of rows; it never pays for the whole catalog,
+ *      in the browser or on the server, to find them.
+ *   7. THE PICKER PAGE (FW-014, 2026-10-23): `agent.agx_picker_page` — the
+ *      menu opens with ~50 thin rows (favorites, recently used, name) and the
+ *      tab counts; scrolling reads the next keyset page. `agent.agx_get_by_ids`
+ *      fills in a full row on hover/open. The whole-catalog read above remains
+ *      for surfaces that genuinely list everything, and for a picker whose
+ *      person narrows by category or tag (the facets need every row).
+ *
+ * 🚨 THE LIST READ IS COMPLETE OR IT THROWS. PostgREST caps every response at
+ * `db-max-rows` (1000 on Matrx Main) and reports success — matrx-frontend's
+ * `fetchAgentsListFull` issued a bare `.rpc()` and would silently have
+ * returned 1000 rows of a larger catalog (the ~400-builtin truncation
+ * incident is the near-miss). Here the read goes through `readAllRows` with
+ * `{ count: "exact" }` and a stable `.order("id")`, so a truncation is a
+ * loud `IncompleteReadError` instead of a confidently short picker.
+ * The DB's own favourites-first/`updated_at` order is irrelevant: every row
+ * is re-sorted client-side by `sortFilteredAgents`.
+ */
+
+/** Server search page size — the frontend's `AGENT_SEARCH_LIMIT`. */
+declare const AGENT_SEARCH_LIMIT = 50;
+declare class AgentCatalogReadError extends Error {
+    readonly name = "AgentCatalogReadError";
+    readonly source: string;
+    constructor(source: string, detail: string);
+}
+/**
+ * Read the WHOLE agent catalog. Throws rather than returning a partial
+ * list — see the file header.
+ */
+declare function readAgentCatalogRows(client: AgentCatalogClient): Promise<AgentSummary[]>;
+interface AgentServerSearchResult {
+    /** Matched ids in SERVER RANK ORDER. */
+    ids: string[];
+    /** Full rows for every hit — merged additively into the registry. */
+    rows: AgentSummary[];
+}
+/**
+ * Tier-2 server search. Purely ADDITIVE: it widens what the local filter
+ * admits and never removes a row the local scorer already matched.
+ */
+declare function searchAgentsOnServer(client: AgentCatalogClient, args: {
+    query: string;
+    deep?: boolean;
+    limit?: number;
+}): Promise<AgentServerSearchResult>;
+/**
+ * The single-agent read, used when a mandate's resolved Holder is not in the
+ * caller's own catalog (a platform agent nobody has shared, most often).
+ *
+ * Two existing doors, in order — never a new RPC:
+ *   1. `agx_search` with the id as the query. The scorer awards an exact id
+ *      match 100000, so the row comes back first, and it is the FULL 19-column
+ *      row (name AND description AND category AND tags).
+ *   2. `agx_resolve_agent_address([id])` — the frontend's own name resolver.
+ *      Name and type only, so the row renders with an honest name and no
+ *      description rather than a fabricated one.
+ *
+ * Returns `null` when neither door can name the agent. The caller SCREAMS;
+ * it never invents a label.
+ */
+declare function readSingleAgentRow(client: AgentCatalogClient, agentId: string): Promise<AgentSummary | null>;
+/**
+ * THE ONE WRITE: the caller's star on one agent, in
+ * `platform.user_entity_state` through the favorites port. Throws an
+ * `AgentCatalogReadError` carrying the refusal in words.
+ */
+declare function writeAgentFavorite(favorites: AgentCatalogFavorites, agentId: string, isFavorite: boolean): Promise<void>;
+/** Which slice of the caller's catalog a picker page reads. */
+interface AgentPickerPageQuery {
+    /** `all_system` = the admin "All" tab that blends system agents in. */
+    tab: "mine" | "shared" | "all" | "all_system" | "system";
+    archive: "active" | "archived" | "both";
+    includeQuick: boolean;
+}
+/** The tab badges, counted server-side over the same reach as the rows. */
+interface AgentPickerCounts {
+    mine: number;
+    shared: number;
+    all: number;
+    system: number;
+    /** Archived rows the active filter hides behind THIS tab (0 unless archive = active). */
+    archivedHidden: number;
+}
+
 /**
  * catalog/default-row-types.ts — @ai-matrx/agents/catalog
  *
@@ -704,6 +828,20 @@ declare function assertAgentCatalogSchema(client: AgentCatalogClient, options?:
  */
 
 type AgentCatalogStatus = "idle" | "loading" | "succeeded" | "failed";
+/** One picker slice (tab × archive × quick) read a page at a time (FW-014). */
+interface AgentPickerPageState {
+    /** Row ids in server order across every page read so far. */
+    ids: string[];
+    /** Keyset position of the next page; `null` once the last page is in. */
+    nextCursor: unknown;
+    done: boolean;
+    status: AgentCatalogStatus;
+    /** True while a next page (not the first) is in flight. */
+    loadingMore: boolean;
+    error: string | null;
+    counts: AgentPickerCounts | null;
+    fetchedAt: number;
+}
 interface AgentCatalogState {
     /** Every row, one stable array reference per change (memoization depends on it). */
     rows: AgentSummary[];
@@ -719,6 +857,8 @@ interface AgentCatalogState {
      * or by a complete catalog load, whichever came first.
      */
     favoriteRowsStatus: AgentCatalogStatus;
+    /** The picker's paged slices, keyed by `agentPickerPageKey` (FW-014). */
+    pickerPages: Record<string, AgentPickerPageState>;
 }
 interface AgentCatalog {
     readonly catalogId: string;
@@ -727,6 +867,8 @@ interface AgentCatalog {
     readonly notifier: AgentCatalogNotifier | undefined;
     /** True when this catalog was given a transport and can resolve mandates. */
     readonly canResolveMandates: boolean;
+    /** `AgentCatalogConfig.pickerReads`, resolved (default `"page"`). */
+    readonly pickerReads: "page" | "catalog";
     /**
      * The consumer state a brand-new consumer starts from, AFTER the host's
      * `defaults` knob is applied. Read it instead of
@@ -765,6 +907,28 @@ interface AgentCatalog {
      * makes no request. Rows that do not parse are skipped.
      */
     seedFavoriteRows(rawRows: unknown[]): void;
+    /**
+     * THE PICKER'S OPEN (FW-014): the first page (~50 thin rows) of one slice,
+     * plus its tab counts — never the whole catalog. Fresh for the list's TTL;
+     * deduped in flight; safe on every open.
+     */
+    ensurePickerPage(query: AgentPickerPageQuery): Promise<void>;
+    /** The next page of a slice (scroll). No-op when the slice is done or already loading. */
+    loadMorePickerPage(query: AgentPickerPageQuery): Promise<void>;
+    /**
+     * FULL rows for these ids (`agent.agx_get_by_ids`), merged into the registry:
+     * a hover card's details, the pinned current agent, a name for an id that is
+     * not on page 1. Ids already held as full rows are not asked again; deduped
+     * in flight.
+     */
+    ensureAgentRows(agentIds: readonly string[]): Promise<void>;
+    /**
+     * The caller's live agents carrying any of these tags, merged into the
+     * registry (`agent.agx_picker_tagged`) — the composer's quick agents and
+     * presets, never the catalog. Fresh for the list's TTL; deduped in flight;
+     * answered at once when the whole catalog is already fresh.
+     */
+    ensureTaggedRows(tags: readonly string[]): Promise<void>;
     /** True when the last load is inside the 15-minute TTL. */
     isFresh(): boolean;
     /** True when the last load is older than 4 hours (tab-restore threshold). */
@@ -799,89 +963,6 @@ declare function createAgentCatalog(config: AgentCatalogConfig): AgentCatalog;
  */
 declare function getRegisteredAgentCatalog(catalogId?: string): AgentCatalog | undefined;
 
-/**
- * catalog/data.ts — @ai-matrx/agents/catalog
- *
- * Every database call the catalog makes, and nothing else. Five of them:
- *
- *   1. `agx_get_list_full()` — the complete catalog (owned + directly-shared
- *      + org-shared user agents, unioned with active builtins).
- *   2. `agx_search(p_query, p_deep, p_limit, p_offset)` — tier-2 server search.
- *   3. `agx_resolve_agent_address(p_ids)` — the single-agent name read, used
- *      when a mandate's Holder is not in the caller's own catalog.
- *   4. The caller's stars arrive ON the rows: every read above computes
- *      `is_favorite` server-side from `platform.user_entity_state`
- *      (`platform.my_favorite`). There is no second star read (FW-014; the
- *      `ues_get_bulk` overlay over every id was retired 2026-10-23).
- *   5. ONE write: the caller's star, `ues_set` through the same port. The
- *      retired `agent.definition.is_favorite` column is never read or written.
- *   6. THE PINNED READ (2026-10-09; by-ids 2026-10-23): the caller's starred
- *      ids (`ues_list` through the favorites port), then
- *      `agent.agx_get_by_ids(p_ids)` for exactly those ids. A sidebar's Pinned
- *      section shows a handful of rows; it never pays for the whole catalog,
- *      in the browser or on the server, to find them.
- *
- * 🚨 THE LIST READ IS COMPLETE OR IT THROWS. PostgREST caps every response at
- * `db-max-rows` (1000 on Matrx Main) and reports success — matrx-frontend's
- * `fetchAgentsListFull` issued a bare `.rpc()` and would silently have
- * returned 1000 rows of a larger catalog (the ~400-builtin truncation
- * incident is the near-miss). Here the read goes through `readAllRows` with
- * `{ count: "exact" }` and a stable `.order("id")`, so a truncation is a
- * loud `IncompleteReadError` instead of a confidently short picker.
- * The DB's own favourites-first/`updated_at` order is irrelevant: every row
- * is re-sorted client-side by `sortFilteredAgents`.
- */
-
-/** Server search page size — the frontend's `AGENT_SEARCH_LIMIT`. */
-declare const AGENT_SEARCH_LIMIT = 50;
-declare class AgentCatalogReadError extends Error {
-    readonly name = "AgentCatalogReadError";
-    readonly source: string;
-    constructor(source: string, detail: string);
-}
-/**
- * Read the WHOLE agent catalog. Throws rather than returning a partial
- * list — see the file header.
- */
-declare function readAgentCatalogRows(client: AgentCatalogClient): Promise<AgentSummary[]>;
-interface AgentServerSearchResult {
-    /** Matched ids in SERVER RANK ORDER. */
-    ids: string[];
-    /** Full rows for every hit — merged additively into the registry. */
-    rows: AgentSummary[];
-}
-/**
- * Tier-2 server search. Purely ADDITIVE: it widens what the local filter
- * admits and never removes a row the local scorer already matched.
- */
-declare function searchAgentsOnServer(client: AgentCatalogClient, args: {
-    query: string;
-    deep?: boolean;
-    limit?: number;
-}): Promise<AgentServerSearchResult>;
-/**
- * The single-agent read, used when a mandate's resolved Holder is not in the
- * caller's own catalog (a platform agent nobody has shared, most often).
- *
- * Two existing doors, in order — never a new RPC:
- *   1. `agx_search` with the id as the query. The scorer awards an exact id
- *      match 100000, so the row comes back first, and it is the FULL 19-column
- *      row (name AND description AND category AND tags).
- *   2. `agx_resolve_agent_address([id])` — the frontend's own name resolver.
- *      Name and type only, so the row renders with an honest name and no
- *      description rather than a fabricated one.
- *
- * Returns `null` when neither door can name the agent. The caller SCREAMS;
- * it never invents a label.
- */
-declare function readSingleAgentRow(client: AgentCatalogClient, agentId: string): Promise<AgentSummary | null>;
-/**
- * THE ONE WRITE: the caller's star on one agent, in
- * `platform.user_entity_state` through the favorites port. Throws an
- * `AgentCatalogReadError` carrying the refusal in words.
- */
-declare function writeAgentFavorite(favorites: AgentCatalogFavorites, agentId: string, isFavorite: boolean): Promise<void>;
-
 /**
  * catalog/rows.ts — @ai-matrx/agents/catalog
  *