@ai-matrx/agents 0.59.263 → 0.59.265

package/dist/catalog/react/index.cjs

@@ -198,12 +198,14 @@ function useAgentSummary(catalog, agentId) {
     () => catalog && agentId ? catalog.getState().byId[agentId] : void 0,
     () => catalog && agentId ? catalog.getState().byId[agentId] : void 0
   );
-  const present = row !== void 0;
+  const present = row !== void 0 && !row.isThin;
   (0, import_react3.useEffect)(() => {
     if (!catalog || !agentId || present) return;
     let cancelled = false;
-    void catalog.ensureLoaded().then(() => {
-      if (cancelled || catalog.getState().byId[agentId]) return;
+    void catalog.ensureAgentRows([agentId]).catch(() => catalog.ensureLoaded()).then(() => {
+      const held = catalog.getState().byId[agentId];
+      if (cancelled || held && !held.isThin) return;
+      if (held) return;
       return lookUpAgentOnce(catalog, agentId);
     }).catch(() => void 0);
     return () => {
@@ -788,6 +790,14 @@ function agentListFooterLabel(args) {
   return archivedHiddenCount > 0 ? `${base} \xB7 ${archivedHiddenCount} archived hidden` : base;
 }
 
+// catalog/store.ts
+var import_core = require("@ai-matrx/associations/core");
+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" : "-"}`;
+}
+
 // catalog/shared/useAgentListCore-react.ts
 function useAgentListCore({
   consumerId,
@@ -817,19 +827,60 @@ function useAgentListCore({
   const allRows = useAgentCatalogRows();
   const rows = (0, import_react5.useMemo)(() => includeQuickAgents ? allRows : withoutQuickAgents(allRows), [allRows, includeQuickAgents]);
   const userId = catalog.getUserIdOrNull();
-  const tabCountsForFilter = selectAgentTabCounts(rows, consumer.state.archFilter);
+  const status = useAgentCatalogState(selectStatus);
+  const [setAsideLabel, setSetAsideLabel] = (0, import_react5.useState)(null);
+  const activeAgentFilter = agentFilter && setAsideLabel !== agentFilter.label ? agentFilter : null;
+  const [facetsWanted, setFacetsWanted] = (0, import_react5.useState)(false);
+  const needsFullCatalog = facetsWanted || activeAgentFilter !== null || consumer.state.includedCats.length > 0 || consumer.state.includedTags.length > 0 || consumer.state.favFilter !== "all" || consumer.state.accessFilter !== "any" || !consumer.state.favoritesFirst || consumer.state.sortBy !== "updated-desc";
+  const fullCatalogReady = status === "succeeded" && catalog.isFresh();
+  const pageQuery = {
+    tab: includeSystemInAll && consumer.state.tab === "all" ? "all_system" : consumer.state.tab,
+    archive: consumer.state.archFilter,
+    includeQuick: includeQuickAgents
+  };
+  const pageKey = agentPickerPageKey(pageQuery);
+  const selectPage = (0, import_react5.useCallback)((state) => state.pickerPages[pageKey], [pageKey]);
+  const pageState = useAgentCatalogState(selectPage);
+  const pageUnsupported = pageState?.error === "unsupported";
+  const paged = catalog.pickerReads === "page" && !needsFullCatalog && !fullCatalogReady && !pageUnsupported;
+  const selectById = (0, import_react5.useCallback)((state) => state.byId, []);
+  const byId = useAgentCatalogState(selectById);
+  const pageRows = (0, import_react5.useMemo)(() => {
+    if (!pageState) return [];
+    const out = [];
+    for (const id of pageState.ids) {
+      const row = byId[id];
+      if (row) out.push(row);
+    }
+    return out;
+  }, [pageState, byId]);
+  const tabCountsForFilter = paged ? {
+    mine: pageState?.counts?.mine ?? 0,
+    shared: pageState?.counts?.shared ?? 0,
+    all: (pageState?.counts?.all ?? 0) + (includeSystemInAll ? pageState?.counts?.system ?? 0 : 0),
+    system: pageState?.counts?.system ?? 0
+  } : selectAgentTabCounts(rows, consumer.state.archFilter);
   const ownedCount = tabCountsForFilter.mine;
   const selectFiltered = (0, import_react5.useMemo)(
     () => makeSelectFilteredAgents(includeSystemInAll),
     [includeSystemInAll]
   );
-  const filteredAgents = selectFiltered(rows, consumer.state);
+  const searchPool = (0, import_react5.useMemo)(() => {
+    if (!paged || !consumer.state.searchTerm) return null;
+    const pool = /* @__PURE__ */ new Map();
+    for (const row of pageRows) pool.set(row.id, row);
+    for (const id of consumer.state.serverMatchedIds) {
+      const row = byId[id];
+      if (row) pool.set(id, row);
+    }
+    const list = [...pool.values()];
+    return includeQuickAgents ? list : withoutQuickAgents(list);
+  }, [paged, consumer.state.searchTerm, consumer.state.serverMatchedIds, pageRows, byId, includeQuickAgents]);
+  const filteredAgents = paged ? searchPool ? selectFiltered(searchPool, consumer.state) : pageRows : selectFiltered(rows, consumer.state);
   const excludedAgentIds = (0, import_react5.useMemo)(
     () => new Set(excludeAgentIds),
     [excludeAgentIds]
   );
-  const [setAsideLabel, setSetAsideLabel] = (0, import_react5.useState)(null);
-  const activeAgentFilter = agentFilter && setAsideLabel !== agentFilter.label ? agentFilter : null;
   const filterTest = activeAgentFilter?.test;
   const applyExcludes = (0, import_react5.useCallback)(
     (list) => excludedAgentIds.size === 0 && !filterTest ? list : list.filter(
@@ -852,23 +903,44 @@ function useAgentListCore({
     () => ({ ...consumer.state, archFilter: "archived" }),
     [consumer.state]
   );
-  const archivedHiddenCount = consumer.archFilter === "active" ? applyExcludes(selectArchivedProbe(rows, archiveProbeState)).length : 0;
-  const status = useAgentCatalogState(selectStatus);
+  const archivedHiddenCount = consumer.archFilter !== "active" || paged && consumer.state.searchTerm ? 0 : paged ? pageState?.counts?.archivedHidden ?? 0 : applyExcludes(selectArchivedProbe(rows, archiveProbeState)).length;
   const activeAgentId = activeAgentIdOverride ?? null;
-  const pinnedAgent = activeAgentId ? catalog.getAgent(activeAgentId) : void 0;
+  const pinnedAgent = activeAgentId ? byId[activeAgentId] : void 0;
   const onSystemTab = consumer.tab === "system";
   const allCategories = onSystemTab ? selectAllSystemAgentCategories(rows) : selectAllAgentCategories(rows);
   const allTags = onSystemTab ? selectAllSystemAgentTags(rows) : selectAllAgentTags(rows);
   const tabCounts = tabCountsForFilter;
-  const isLoading = status === "loading";
-  const agentsLoaded = status === "succeeded" || status === "failed";
+  const [engaged, setEngaged] = (0, import_react5.useState)(false);
+  const pageStatus = pageState?.status ?? "idle";
+  const isLoading = paged ? (pageStatus === "loading" || pageStatus === "idle") && pageRows.length === 0 && engaged : status === "loading";
+  const agentsLoaded = paged ? pageStatus === "succeeded" || pageStatus === "failed" : status === "succeeded" || status === "failed";
   const ensureLoaded = (0, import_react5.useCallback)(() => {
     if (!hasFetchedRef.current) {
       hasFetchedRef.current = true;
-      void catalog.ensureLoaded().catch(() => {
-      });
+      setEngaged(true);
     }
-  }, [catalog]);
+  }, []);
+  const pageQueryRef = (0, import_react5.useRef)(pageQuery);
+  pageQueryRef.current = pageQuery;
+  (0, import_react5.useEffect)(() => {
+    if (!engaged) return;
+    if (paged) void catalog.ensurePickerPage(pageQueryRef.current).catch(() => void 0);
+    else void catalog.ensureLoaded().catch(() => void 0);
+  }, [engaged, paged, pageKey, catalog]);
+  const loadMore = (0, import_react5.useCallback)(() => {
+    if (!paged) return;
+    void catalog.loadMorePickerPage(pageQueryRef.current).catch(() => void 0);
+  }, [paged, catalog]);
+  const ensureFullCatalog = (0, import_react5.useCallback)(() => {
+    setFacetsWanted(true);
+  }, []);
+  const hasMore = paged && pageStatus === "succeeded" && pageState?.done === false;
+  const loadingMore = paged && pageState?.loadingMore === true;
+  const pinnedMissing = Boolean(activeAgentId) && pinnedAgent === void 0;
+  (0, import_react5.useEffect)(() => {
+    if (!engaged || !pinnedMissing || !activeAgentId) return;
+    void catalog.ensureAgentRows([activeAgentId]).catch(() => void 0);
+  }, [engaged, pinnedMissing, activeAgentId, catalog]);
   const selectDefaultRow = (0, import_react5.useCallback)(
     (state) => defaultMandateKey ? state.defaultRows[defaultMandateKey] : void 0,
     [defaultMandateKey]
@@ -945,13 +1017,14 @@ function useAgentListCore({
   const handleAgentHover = (0, import_react5.useCallback)(
     (agent, panelOpen) => {
       if (panelOpen) return;
+      if (agent.isThin) void catalog.ensureAgentRows([agent.id]).catch(() => void 0);
       if (hoverLeaveTimerRef.current) {
         clearTimeout(hoverLeaveTimerRef.current);
         hoverLeaveTimerRef.current = null;
       }
       setHoveredAgent(agent);
     },
-    []
+    [catalog]
   );
   const handleAgentHoverEnd = (0, import_react5.useCallback)(
     (agent, onClear) => {
@@ -982,8 +1055,10 @@ function useAgentListCore({
     },
     []
   );
+  const tabTotal = consumer.state.tab === "mine" ? tabCountsForFilter.mine : consumer.state.tab === "shared" ? tabCountsForFilter.shared : consumer.state.tab === "system" ? tabCountsForFilter.system : tabCountsForFilter.all;
+  const totalCount = paged && !consumer.state.searchTerm && excludedAgentIds.size === 0 ? Math.max(tabTotal, agents.length) : agents.length;
   const footerLabel = agentListFooterLabel({
-    count: agents.length,
+    count: totalCount,
     archFilter: consumer.archFilter,
     archivedHiddenCount
   });
@@ -1007,6 +1082,14 @@ function useAgentListCore({
     hoveredAgent,
     setHoveredAgent,
     ensureLoaded,
+    /** FW-014: the list reads a page at a time; true while the slice has more. */
+    paged,
+    hasMore,
+    loadingMore,
+    loadMore,
+    /** The tab's total (server count when paged) — the footer's number. */
+    totalCount,
+    ensureFullCatalog,
     handleSelectAgent,
     handleAgentHover,
     handleAgentHoverEnd,
@@ -1488,7 +1571,8 @@ function AgentDetailCard({ agent, onSelect, duplicate, onHoldChange }) {
   const select = (0, import_react6.useCallback)((state) => state.byId[agent.id], [agent.id]);
   const row = useAgentCatalogState(select);
   const on = row?.isFavorite ?? agent.isFavorite ?? false;
-  const record = agentPeekRecord(agent, {
+  const live = row && !row.isThin ? row : agent;
+  const record = agentPeekRecord(live, {
     favorite: {
       on,
       onToggle: () => {
@@ -1785,6 +1869,7 @@ var AGENT_ROW_HEIGHT = 36;
 var UNMEASURED_VIEWPORT = 480;
 var ROW_OVERSCAN = 8;
 var WINDOW_ABOVE = 50;
+var REACH_END_ROWS = 10;
 function AgentListContent({
   agents,
   isLoading,
@@ -1812,7 +1897,11 @@ function AgentListContent({
   listOpen = false,
   archivedHiddenCount = 0,
   agentFilterLabel = null,
-  onClearAgentFilter
+  onClearAgentFilter,
+  hasMore = false,
+  onReachEnd,
+  loadingMore = false,
+  totalCount
 }) {
   const catalog = useAgentCatalog();
   const listScrollRef = (0, import_react7.useRef)(null);
@@ -1861,6 +1950,12 @@ function AgentListContent({
     scroller.scrollTo({ top });
     setScrollTop(top);
   }, [listOpen, pinnedAgent?.id, activeAgentId, isLoading]);
+  (0, import_react7.useEffect)(() => {
+    if (!hasMore || !onReachEnd || isLoading) return;
+    const view = viewport > 0 ? viewport : UNMEASURED_VIEWPORT;
+    const listBottom = listStart + agents.length * AGENT_ROW_HEIGHT;
+    if (scrollTop + view >= listBottom - REACH_END_ROWS * AGENT_ROW_HEIGHT) onReachEnd();
+  }, [hasMore, onReachEnd, isLoading, scrollTop, viewport, listStart, agents.length]);
   const win = agents.length <= WINDOW_ABOVE ? { start: 0, end: agents.length, padStart: 0, padEnd: 0 } : (0, import_virtual_window.computeWindow)({
     count: agents.length,
     itemSize: AGENT_ROW_HEIGHT,
@@ -2117,6 +2212,14 @@ function AgentListContent({
               ]
             }
           ),
+          loadingMore && /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(
+            "div",
+            {
+              "data-testid": "agent-list-loading-more",
+              className: "flex items-center justify-center py-2 text-muted-foreground",
+              children: /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(LoaderIcon, { className: "w-3.5 h-3.5 matrx-agent-spin" })
+            }
+          ),
           agents.length === 0 && (pinnedAgent || defaultAgent) && /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("div", { className: "flex flex-col items-center py-4 text-muted-foreground", children: /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("span", { className: "text-xs", children: emptyLabel }) })
         ] })
       }
@@ -2129,7 +2232,7 @@ function AgentListContent({
           "data-testid": "agent-list-footer",
           className: "text-[10px] text-muted-foreground tabular-nums",
           children: agentListFooterLabel({
-            count: agents.length,
+            count: totalCount ?? agents.length,
             archFilter: consumer.archFilter,
             archivedHiddenCount
           })
@@ -2363,6 +2466,11 @@ function AgentListPanelBody({
     hoveredAgent,
     setHoveredAgent,
     ensureLoaded,
+    hasMore,
+    loadMore,
+    loadingMore,
+    totalCount,
+    ensureFullCatalog,
     handleSelectAgent: coreSelectAgent,
     handleAgentHover: coreAgentHover,
     handleAgentHoverEnd: coreAgentHoverEnd,
@@ -2390,6 +2498,7 @@ function AgentListPanelBody({
     onAfterSelect?.(agent);
   };
   const handleFilterChipClick = (panel) => {
+    if (panel !== "sort") ensureFullCatalog();
     if (isMobile) {
       setMobileSubView(panel);
     } else {
@@ -2462,6 +2571,10 @@ function AgentListPanelBody({
       defaultRow,
       agentFilterLabel,
       onClearAgentFilter: clearAgentFilter,
+      hasMore,
+      onReachEnd: loadMore,
+      loadingMore,
+      totalCount,
       listOpen: true
     }
   );
@@ -2801,6 +2914,11 @@ function AgentListInlinePicker({
     agentFilterLabel,
     clearAgentFilter,
     ensureLoaded,
+    hasMore,
+    loadMore,
+    loadingMore,
+    totalCount,
+    ensureFullCatalog,
     handleSelectAgent: coreSelectAgent,
     handleAgentHover,
     handleAgentHoverEnd
@@ -2830,6 +2948,7 @@ function AgentListInlinePicker({
     setMobileSubView(null);
   };
   const handleFilterChipClick = (panel) => {
+    if (panel !== "sort") ensureFullCatalog();
     setMobileSubView(panel);
   };
   const isMobile = true;
@@ -2908,6 +3027,10 @@ function AgentListInlinePicker({
       defaultRow,
       agentFilterLabel,
       onClearAgentFilter: clearAgentFilter,
+      hasMore,
+      onReachEnd: loadMore,
+      loadingMore,
+      totalCount,
       listOpen: true
     }
   ) });

package/dist/catalog/react/index.d.cts

@@ -125,6 +125,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";
 /**
@@ -212,45 +222,6 @@ interface AgentConsumerState {
 /** The subset of consumer state a caller may patch (paging is derived). */
 type AgentConsumerPatch = Partial<Omit<AgentConsumerState, "listPage" | "sharedPage">>;
 
-/**
- * catalog/default-row-types.ts — @ai-matrx/agents/catalog
- *
- * Split out of `default-row.ts` so `global-state.ts` can name the cached
- * shape without importing the resolver (and its transport work) — the same
- * split-out reflex C8 asks for, at module scale.
- */
-
-/** A resolved default row, cached for first paint and compared for drift. */
-interface ResolvedDefaultRow {
-    mandateKey: string;
-    /** The `agent.definition` id the mandate resolved to. */
-    holderId: string;
-    /** The holder's REAL name, read from the catalog — never hardcoded. */
-    holderName: string;
-    holderDescription: string | null;
-    provenance: string;
-    /** Epoch ms of this resolution. */
-    at: number;
-}
-/** What the picker renders and what it screams, together. */
-interface DefaultRowState {
-    mandateKey: string;
-    /** The row to render at the top of the list. `null` until resolved. */
-    row: AgentSummary | null;
-    /** The last live resolution, or the cached one before the live answer lands. */
-    resolved: ResolvedDefaultRow | null;
-    /** True while the resolution is in flight. */
-    loading: boolean;
-    /**
-     * 🚨 THE DRIFT SCREAM. Set when the cached first-paint row and the LIVE
-     * resolution disagree on holder id or holder name. Rendered as a persistent
-     * in-picker banner AND sent to the `notifier` port — never console-only.
-     */
-    drift: string | null;
-    /** Set when the mandate could not be resolved at all. Loud, with a remedy. */
-    error: string | null;
-}
-
 /**
  * `@ai-matrx/agents/catalog` — THE PORTS.
  *
@@ -326,6 +297,101 @@ type AgentCatalogNavigate = (href: string) => void;
  */
 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`.
+ */
+
+/** 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
+ *
+ * Split out of `default-row.ts` so `global-state.ts` can name the cached
+ * shape without importing the resolver (and its transport work) — the same
+ * split-out reflex C8 asks for, at module scale.
+ */
+
+/** A resolved default row, cached for first paint and compared for drift. */
+interface ResolvedDefaultRow {
+    mandateKey: string;
+    /** The `agent.definition` id the mandate resolved to. */
+    holderId: string;
+    /** The holder's REAL name, read from the catalog — never hardcoded. */
+    holderName: string;
+    holderDescription: string | null;
+    provenance: string;
+    /** Epoch ms of this resolution. */
+    at: number;
+}
+/** What the picker renders and what it screams, together. */
+interface DefaultRowState {
+    mandateKey: string;
+    /** The row to render at the top of the list. `null` until resolved. */
+    row: AgentSummary | null;
+    /** The last live resolution, or the cached one before the live answer lands. */
+    resolved: ResolvedDefaultRow | null;
+    /** True while the resolution is in flight. */
+    loading: boolean;
+    /**
+     * 🚨 THE DRIFT SCREAM. Set when the cached first-paint row and the LIVE
+     * resolution disagree on holder id or holder name. Rendered as a persistent
+     * in-picker banner AND sent to the `notifier` port — never console-only.
+     */
+    drift: string | null;
+    /** Set when the mandate could not be resolved at all. Loud, with a remedy. */
+    error: string | null;
+}
+
 /**
  * catalog/schema.ts — @ai-matrx/agents/catalog
  *
@@ -394,6 +460,20 @@ interface AssertAgentCatalogSchemaOptions {
  */
 
 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[];
@@ -409,6 +489,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;
@@ -417,6 +499,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
@@ -455,6 +539,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). */
@@ -563,10 +669,11 @@ declare function AgentCatalogProvider({ catalog, children, ...ports }: AgentCata
 declare function lookUpAgentOnce(catalog: AgentCatalog, agentId: string): Promise<void>;
 /**
  * ONE agent's catalog row — name, description, category, tags, star, access — read straight from
- * the catalog store (the ONE holder of agent identity; no host mirror). When the row is missing the
- * catalog is loaded (its own TTL and in-flight dedupe make this safe on every mount); an id the
- * list does not carry is looked up by server search, which merges it into the catalog — once per
- * id per catalog (the Board's remount law: a woken or remounted tile asks nothing again).
+ * the catalog store (the ONE holder of agent identity; no host mirror). When the row is missing (or
+ * only a thin picker row) that ONE row is read by id (`ensureAgentRows`, deduped) — never the whole
+ * catalog (FW-014); an id that read does not return is looked up by server search, which merges it
+ * into the catalog — once per id per catalog (the Board's remount law: a woken or remounted tile
+ * asks nothing again).
  *
  * Takes the catalog explicitly so a host without `AgentCatalogProvider` (chat, workers) binds it.
  */
@@ -661,6 +768,14 @@ declare function useAgentListCore({ consumerId, onSelect, navigateTo, activeAgen
     hoveredAgent: AgentSummary | null;
     setHoveredAgent: react.Dispatch<react.SetStateAction<AgentSummary | null>>;
     ensureLoaded: () => void;
+    /** FW-014: the list reads a page at a time; true while the slice has more. */
+    paged: boolean;
+    hasMore: boolean;
+    loadingMore: boolean;
+    loadMore: () => void;
+    /** The tab's total (server count when paged) — the footer's number. */
+    totalCount: number;
+    ensureFullCatalog: () => void;
     handleSelectAgent: (agent: AgentSummary) => void;
     handleAgentHover: (agent: AgentSummary, panelOpen: boolean) => void;
     handleAgentHoverEnd: (agent: AgentSummary, onClear: () => void) => void;
@@ -1052,8 +1167,19 @@ interface AgentListContentProps {
     agentFilterLabel?: string | null | undefined;
     /** "Show all" on the host-filter chip. */
     onClearAgentFilter?: (() => void) | undefined;
+    /**
+     * FW-014 paging: true while the list has more rows on the server. The list
+     * asks `onReachEnd` for the next page when the scroll nears the end (or when
+     * the rows do not fill the viewport yet).
+     */
+    hasMore?: boolean | undefined;
+    onReachEnd?: (() => void) | undefined;
+    /** True while the next page is in flight — a spinner row closes the list. */
+    loadingMore?: boolean | undefined;
+    /** The tab's total for the footer (server count when paged); defaults to the rendered rows. */
+    totalCount?: number | undefined;
 }
-declare function AgentListContent({ agents, isLoading, consumer, activeAgentId, allCategories, allTags, inputRef, onSelectAgent, resolveAgentHref, onReset, activeFilterCount, isMobile, hoveredAgent, onAgentHover, onAgentHoverEnd, onDetailPress, onFilterChipClick, rightPanel, tabCounts, visibleTabs, systemTabLabel, pinnedAgent, defaultRow, listOpen, archivedHiddenCount, agentFilterLabel, onClearAgentFilter, }: AgentListContentProps): react.JSX.Element;
+declare function AgentListContent({ agents, isLoading, consumer, activeAgentId, allCategories, allTags, inputRef, onSelectAgent, resolveAgentHref, onReset, activeFilterCount, isMobile, hoveredAgent, onAgentHover, onAgentHoverEnd, onDetailPress, onFilterChipClick, rightPanel, tabCounts, visibleTabs, systemTabLabel, pinnedAgent, defaultRow, listOpen, archivedHiddenCount, agentFilterLabel, onClearAgentFilter, hasMore, onReachEnd, loadingMore, totalCount, }: AgentListContentProps): react.JSX.Element;
 
 interface AgentFilterBarProps {
     consumer: UseAgentConsumerReturn;