@ai-matrx/agents 0.59.263 → 0.59.265

package/dist/catalog/native/index.cjs

@@ -263,7 +263,7 @@ function AgentCatalogProvider({
 var import_react_native12 = require("react-native");
 
 // catalog/native/AgentPickerBody.tsx
-var import_react6 = require("react");
+var import_react7 = require("react");
 var import_react_native11 = require("react-native");
 
 // catalog/shared/useAgentListCore-react.ts
@@ -841,6 +841,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,
@@ -870,19 +878,60 @@ function useAgentListCore({
   const allRows = useAgentCatalogRows();
   const rows = (0, import_react4.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_react4.useState)(null);
+  const activeAgentFilter = agentFilter && setAsideLabel !== agentFilter.label ? agentFilter : null;
+  const [facetsWanted, setFacetsWanted] = (0, import_react4.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_react4.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_react4.useCallback)((state) => state.byId, []);
+  const byId = useAgentCatalogState(selectById);
+  const pageRows = (0, import_react4.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_react4.useMemo)(
     () => makeSelectFilteredAgents(includeSystemInAll),
     [includeSystemInAll]
   );
-  const filteredAgents = selectFiltered(rows, consumer.state);
+  const searchPool = (0, import_react4.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_react4.useMemo)(
     () => new Set(excludeAgentIds),
     [excludeAgentIds]
   );
-  const [setAsideLabel, setSetAsideLabel] = (0, import_react4.useState)(null);
-  const activeAgentFilter = agentFilter && setAsideLabel !== agentFilter.label ? agentFilter : null;
   const filterTest = activeAgentFilter?.test;
   const applyExcludes = (0, import_react4.useCallback)(
     (list) => excludedAgentIds.size === 0 && !filterTest ? list : list.filter(
@@ -905,23 +954,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_react4.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_react4.useCallback)(() => {
     if (!hasFetchedRef.current) {
       hasFetchedRef.current = true;
-      void catalog.ensureLoaded().catch(() => {
-      });
+      setEngaged(true);
     }
-  }, [catalog]);
+  }, []);
+  const pageQueryRef = (0, import_react4.useRef)(pageQuery);
+  pageQueryRef.current = pageQuery;
+  (0, import_react4.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_react4.useCallback)(() => {
+    if (!paged) return;
+    void catalog.loadMorePickerPage(pageQueryRef.current).catch(() => void 0);
+  }, [paged, catalog]);
+  const ensureFullCatalog = (0, import_react4.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_react4.useEffect)(() => {
+    if (!engaged || !pinnedMissing || !activeAgentId) return;
+    void catalog.ensureAgentRows([activeAgentId]).catch(() => void 0);
+  }, [engaged, pinnedMissing, activeAgentId, catalog]);
   const selectDefaultRow = (0, import_react4.useCallback)(
     (state) => defaultMandateKey ? state.defaultRows[defaultMandateKey] : void 0,
     [defaultMandateKey]
@@ -998,13 +1068,14 @@ function useAgentListCore({
   const handleAgentHover = (0, import_react4.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_react4.useCallback)(
     (agent, onClear) => {
@@ -1035,8 +1106,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
   });
@@ -1060,6 +1133,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,
@@ -1079,6 +1160,7 @@ var EMPTY_EXCLUDES = [];
 var selectStatus = (state) => state.status;
 
 // catalog/native/AgentDetailCard.tsx
+var import_react6 = require("react");
 var import_react_native4 = require("react-native");
 
 // catalog/orchestra.ts
@@ -1406,8 +1488,14 @@ function formatDate(value) {
     year: "numeric"
   });
 }
-function AgentDetailCard({ agent, onSelect }) {
-  const { errorSink } = useAgentCatalog();
+function AgentDetailCard({ agent: given, onSelect }) {
+  const catalog = useAgentCatalog();
+  const { errorSink } = catalog;
+  const held = (0, import_react6.useSyncExternalStore)(catalog.subscribe, () => catalog.getState().byId[given.id], () => catalog.getState().byId[given.id]);
+  const agent = held && !held.isThin ? held : given;
+  (0, import_react6.useEffect)(() => {
+    if (given.isThin && !(held && !held.isThin)) void catalog.ensureAgentRows([given.id]).catch(() => void 0);
+  }, [catalog, given.id, given.isThin, held]);
   const { renderModelRef, openPeek } = useAgentCatalogUiPorts();
   const theme = useAgentCatalogNativeTheme();
   const isDefaultRow = isMandateAgentId(agent.id);
@@ -2455,7 +2543,9 @@ function AgentListContent({
   pinnedAgent = null,
   defaultRow = null,
   autoFocusSearch = false,
-  archivedHiddenCount = 0
+  archivedHiddenCount = 0,
+  onReachEnd,
+  totalCount
 }) {
   const catalog = useAgentCatalog();
   const theme = useAgentCatalogNativeTheme();
@@ -2640,6 +2730,7 @@ function AgentListContent({
         data: items,
         keyExtractor: (item) => item.key,
         keyboardShouldPersistTaps: "handled",
+        ...onReachEnd ? { onEndReached: onReachEnd, onEndReachedThreshold: 0.5 } : {},
         renderItem: ({ item }) => {
           if (item.kind === "divider") return /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(import_react_native9.View, { style: hairline });
           if (item.kind === "label") {
@@ -2693,7 +2784,7 @@ function AgentListContent({
             fontVariant: ["tabular-nums"]
           },
           children: agentListFooterLabel({
-            count: agents.length,
+            count: totalCount ?? agents.length,
             archFilter: consumer.archFilter,
             archivedHiddenCount
           })
@@ -2858,9 +2949,9 @@ function AgentPickerBody({
   compact = false,
   onAfterSelect
 }) {
-  const [detailAgent, setDetailAgent] = (0, import_react6.useState)(null);
-  const [subView, setSubView] = (0, import_react6.useState)(null);
-  const [panelSearch, setPanelSearch] = (0, import_react6.useState)("");
+  const [detailAgent, setDetailAgent] = (0, import_react7.useState)(null);
+  const [subView, setSubView] = (0, import_react7.useState)(null);
+  const [panelSearch, setPanelSearch] = (0, import_react7.useState)("");
   const {
     agents,
     archivedHiddenCount,
@@ -2873,6 +2964,9 @@ function AgentPickerBody({
     pinnedAgent,
     defaultRow,
     ensureLoaded,
+    loadMore,
+    totalCount,
+    ensureFullCatalog,
     handleSelectAgent: coreSelectAgent
   } = useAgentListCore({
     consumerId,
@@ -2885,7 +2979,7 @@ function AgentPickerBody({
     ...excludeAgentIds ? { excludeAgentIds } : {},
     ...defaultMandateKey ? { defaultMandateKey } : {}
   });
-  (0, import_react6.useEffect)(() => {
+  (0, import_react7.useEffect)(() => {
     ensureLoaded();
   }, [ensureLoaded]);
   const selectAgent = (agent) => {
@@ -2931,11 +3025,16 @@ function AgentPickerBody({
       allTags,
       onSelectAgent: selectAgent,
       onDetailPress: setDetailAgent,
-      onFilterChipPress: setSubView,
+      onFilterChipPress: (panel) => {
+        if (panel !== "sort") ensureFullCatalog();
+        setSubView(panel);
+      },
       onReset: consumer.resetFilters,
       activeFilterCount,
       tabCounts,
       archivedHiddenCount,
+      onReachEnd: loadMore,
+      totalCount,
       ...visibleTabs ? { visibleTabs } : {},
       ...systemTabLabel ?? (includeSystemInAll ? "System" : void 0) ? {
         systemTabLabel: systemTabLabel ?? (includeSystemInAll ? "System" : void 0)

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

@@ -1,45 +1,6 @@
 import * as react from 'react';
 import { ComponentType, ReactNode } from 'react';
-import { A as AgentSummary, a as AgentConsumerState, b as AgentConsumerPatch, c as AgentTab, d as AgentSortOption, e as AgentFavFilter, f as AgentArchFilter, g as AgentAccessFilter, O as OrchestraBadge } from '../../types-DZhDqrVE.cjs';
-
-/**
- * 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;
-}
+import { A as AgentSummary, a as AgentConsumerState, b as AgentConsumerPatch, c as AgentTab, d as AgentSortOption, e as AgentFavFilter, f as AgentArchFilter, g as AgentAccessFilter, O as OrchestraBadge } from '../../types-5pX8AZBM.cjs';
 
 /**
  * `@ai-matrx/agents/catalog` — THE PORTS.
@@ -116,6 +77,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
  *
@@ -184,6 +240,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[];
@@ -199,6 +269,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;
@@ -207,6 +279,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
@@ -245,6 +319,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). */
@@ -587,6 +683,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;
@@ -732,8 +836,12 @@ interface AgentListContentProps {
      * `useAgentListCore`. The footer names them, exactly as on the web.
      */
     archivedHiddenCount?: number | undefined;
+    /** FW-014 paging: asked for the next page when the list nears its end. */
+    onReachEnd?: (() => void) | undefined;
+    /** The tab's total for the footer (server count when paged). */
+    totalCount?: number | undefined;
 }
-declare function AgentListContent({ agents, isLoading, consumer, activeAgentId, allCategories, allTags, onSelectAgent, onDetailPress, onFilterChipPress, onReset, activeFilterCount, tabCounts, visibleTabs, systemTabLabel, pinnedAgent, defaultRow, autoFocusSearch, archivedHiddenCount, }: AgentListContentProps): react.JSX.Element;
+declare function AgentListContent({ agents, isLoading, consumer, activeAgentId, allCategories, allTags, onSelectAgent, onDetailPress, onFilterChipPress, onReset, activeFilterCount, tabCounts, visibleTabs, systemTabLabel, pinnedAgent, defaultRow, autoFocusSearch, archivedHiddenCount, onReachEnd, totalCount, }: AgentListContentProps): react.JSX.Element;
 
 interface AgentListTabsProps {
     consumer: UseAgentConsumerReturn;
@@ -766,7 +874,7 @@ interface AgentDetailCardProps {
     agent: AgentSummary;
     onSelect: () => void;
 }
-declare function AgentDetailCard({ agent, onSelect }: AgentDetailCardProps): react.JSX.Element;
+declare function AgentDetailCard({ agent: given, onSelect }: AgentDetailCardProps): react.JSX.Element;
 
 type AgentSubViewName = "sort" | "categories" | "tags";
 interface AgentSubViewProps {