@ai-matrx/agents 0.6.2 → 0.7.1

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

@@ -0,0 +1,819 @@
+import * as react from 'react';
+import { ComponentType, ReactNode, Ref } from 'react';
+
+/**
+ * `@ai-matrx/agents/catalog` — the row shape and the per-consumer view state.
+ *
+ * `AgentSummary` is the 19-column row `agx_get_list_full()` returns, camelCased.
+ * It is deliberately NOT the editable agent record: dirty tracking, undo,
+ * messages, tools and `_fetchStatus` stay in whichever host owns the editor.
+ * A list row is a list row.
+ *
+ * The view-state types are a VERBATIM port of matrx-frontend
+ * `features/agents/redux/agent-consumers/slice.ts` — only the coupling seam
+ * inverts (Redux reducers become store actions in `./store`).
+ */
+/**
+ * A branded agent id. Every id that reaches `onSelect` is one of these:
+ * either a `agent.definition` UUID, or the `mandate:<key>` reference a
+ * default row carries (byte-identical to the ref shape matrx-extend
+ * `src/lib/mandates.ts` and matrx-local `desktop/src/lib/mandates.ts`
+ * already hand back to their hosts).
+ *
+ * 🚨 The brand is a STRING LITERAL, never `unique symbol`. This package emits
+ * `./catalog` and `./catalog/react` as two separate bundles, so each `.d.ts`
+ * carries its own copy of these declarations. A `unique symbol` brand is
+ * NOMINAL: two copies of it are unrelated types, so `createAgentCatalog()`
+ * from `./catalog` was not assignable to `<AgentCatalogProvider catalog=…>`
+ * from `./catalog/react` — the exact two-import wiring the README, the
+ * CHANGELOG and every consumer use. A literal brand is structural, so the two
+ * copies unify, while a bare `string` still cannot be passed where an
+ * `AgentId` is required (which is the whole point of branding). Any future
+ * brand in this package follows the same rule.
+ */
+type AgentId = string & {
+    readonly __agentId: "ai-matrx.agent-id";
+};
+/** `agent_type` verbatim. Only `builtin` changes how a row is grouped. */
+type AgentCatalogAgentType = "user" | "builtin";
+/**
+ * `access_level` verbatim from `agx_get_list_full`. Widened over the raw
+ * string because it is a DB-owned vocabulary: an unknown level renders as
+ * itself rather than being coerced into a wrong one.
+ */
+type AgentAccessLevel = "owner" | "admin" | "editor" | "viewer" | "system" | (string & {});
+/**
+ * One `agx_get_list_full()` row, camelCased. Nineteen columns, no more:
+ * anything richer needs a different read and is a different type.
+ */
+interface AgentSummary {
+    id: AgentId;
+    name: string | null;
+    description: string | null;
+    category: string | null;
+    tags: string[];
+    agentType: AgentCatalogAgentType;
+    modelId: string | null;
+    isActive: boolean;
+    isArchived: boolean;
+    isFavorite: boolean;
+    createdBy: string | null;
+    organizationId: string | null;
+    taskId: string | null;
+    sourceAgentId: string | null;
+    createdAt: string | null;
+    updatedAt: string | null;
+    isOwner: boolean | null;
+    accessLevel: AgentAccessLevel | null;
+    sharedByEmail: string | null;
+    /**
+     * Set only on a mandate default row — the key it resolved through, so a
+     * host can tell "the default" from a stored agent without parsing the id.
+     */
+    mandateKey?: string;
+}
+type AgentSortOption = "updated-desc" | "created-desc" | "name-asc" | "name-desc" | "category-asc";
+/** Which ownership tab is active in the agent list. */
+type AgentTab = "mine" | "shared" | "all" | "system";
+/** Favorite filter. */
+type AgentFavFilter = "all" | "yes" | "no";
+/** Archive filter. */
+type AgentArchFilter = "active" | "archived" | "both";
+/**
+ * Access level filter.
+ * 'any'    = no restriction (default).
+ * 'owned'  = only agents the user owns (isOwner = true).
+ * 'shared' = only agents shared with the user (isOwner = false).
+ * 'editable' = owner + admin + editor.
+ */
+type AgentAccessFilter = "any" | "owned" | "shared" | "editable";
+interface AgentConsumerState {
+    tab: AgentTab;
+    sortBy: AgentSortOption;
+    searchTerm: string;
+    /** INCLUSION model: empty = show all; non-empty = only matching. */
+    includedCats: string[];
+    /** INCLUSION model: empty = show all; non-empty = only matching. */
+    includedTags: string[];
+    favFilter: AgentFavFilter;
+    archFilter: AgentArchFilter;
+    accessFilter: AgentAccessFilter;
+    favoritesFirst: boolean;
+    /** Current page for owned-agent list items (after the card section). */
+    listPage: number;
+    /** Current page for shared-agent list items. */
+    sharedPage: number;
+    /**
+     * Ids returned by the last server-side search (`agx_search`), in server rank
+     * order. Additive: an agent in this list survives the search filter even
+     * when the local scorer gives it 0.
+     *
+     * That is load-bearing for tier 2. A deep search matches an agent's prompt
+     * content, which the client never loads — so the local scorer cannot see it.
+     * Without this list the server would return prompt matches and the UI would
+     * immediately filter them back out.
+     *
+     * Server-only matches sort BELOW every locally-scored match, in server rank
+     * order, so obvious matches always come first.
+     */
+    serverMatchedIds: string[];
+    /** True while a server search is in flight — drives the search spinner. */
+    isServerSearching: boolean;
+    /** Tier 2: also search agent prompt content. Opt-in, per consumer. */
+    deepSearch: boolean;
+}
+/** 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 catalogue — 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.
+ *
+ * Two are required (`client`, `identity`); every other one ships a working
+ * default with a DOCUMENTED degradation, per THE ALL-INCLUSIVE LAW. A host
+ * injects identity and a Supabase client and nothing else; the picker's only
+ * contract back to the host is `onSelect(agentId)`.
+ *
+ * React appears nowhere in this file — it is import-inert and legal in any
+ * graph, server components included.
+ */
+
+/**
+ * Every degraded path, every failed read, every drift detection reports here.
+ * DEFAULT: a tagged `console.error` that announces ONCE that no sink is bound
+ * and names the remedy.
+ */
+type AgentCatalogErrorSink = (event: {
+    code: string;
+    message: string;
+    context?: object;
+}) => void;
+/**
+ * The drift scream's second channel. DEFAULT: none — and that is safe
+ * ONLY because the in-picker persistent banner is the primary scream and
+ * always renders. A drift is never console-only.
+ */
+type AgentCatalogNotifier = (event: {
+    level: "warning" | "error";
+    title: string;
+    message: string;
+}) => void;
+/** Every user-visible string the picker renders, overridable per host. */
+interface AgentCatalogLabels {
+    /** User-facing label for the `system` ownership tab. */
+    publicTab: string;
+    /**
+     * Badge label on a builtin row. Default `"system"` — the string
+     * `AgentRow` actually rendered in matrx-frontend. (The frontend also
+     * declared `AGENT_PUBLIC_BADGE_LABEL = "Public"` for this badge and NOTHING
+     * ever read it — a constant that named the badge without being the badge.
+     * Recorded in the CHANGELOG and dropped rather than ported.)
+     */
+    systemBadge: string;
+    searchPlaceholder: string;
+    currentAgentHeading: string;
+    emptyDefault: string;
+    emptyShared: string;
+    emptySystem: string;
+    loading: string;
+    triggerFallback: string;
+    triggerResolving: string;
+    triggerUnnameable: string;
+    hoverHint: string;
+}
+/**
+ * Where a row's href goes when someone cmd-clicks it, and where `navigateTo`
+ * lands. DEFAULT: `window.location.assign` (so cmd-click and ordinary
+ * navigation both work with no host wiring at all).
+ */
+type AgentCatalogNavigate = (href: string) => void;
+/**
+ * The sneak-peek affordance. Absent → the affordance is HIDDEN, never a dead
+ * button (nothing fails silently, and nothing looks alive when it is not).
+ */
+type AgentCatalogOpenPeek = (agent: AgentSummary) => void;
+
+/**
+ * catalog/schema.ts — @ai-matrx/agents/catalog
+ *
+ * THE DEMANDED SCHEMA PROBE (the `@ai-matrx/associations` `assertDemandedSchema`
+ * precedent). It proves that the database a host pointed this catalog at can
+ * actually answer the three functions the picker demands.
+ *
+ * 🚨 IT MUST BE ABLE TO FAIL. A probe whose green result is unconditional
+ * proves nothing, so `selfTest: true` also probes a fabricated function name
+ * and REQUIRES it to come back missing. `catalog/__tests__/schema.test.ts`
+ * runs the whole probe against a client whose `rpc` answers PostgreSQL 42883
+ * (`undefined_function`, which PostgREST surfaces as PGRST202) and asserts the
+ * loud error.
+ */
+
+interface AgentCatalogSchemaReport {
+    ok: boolean;
+    /** Demanded functions the database cannot answer. */
+    missing: string[];
+    /** Functions the probe could not reach (transport/unknown failure). */
+    unreachable: {
+        fn: string;
+        error: unknown;
+    }[];
+    /** Functions that answered (success or any non-missing refusal). */
+    answered: string[];
+    /** True when `agent.definition.is_favorite` is writable by this caller. */
+    favoriteWritable: boolean | null;
+}
+interface AssertAgentCatalogSchemaOptions {
+    /**
+     * Also probe a fabricated function name and REQUIRE it to come back
+     * missing — proves this probe can fail.
+     */
+    selfTest?: boolean;
+    /** Return the report instead of throwing. The self-test failure ALWAYS throws. */
+    throwOnViolation?: boolean;
+    /**
+     * Also probe the ONE write (`agent.definition.is_favorite`) against an
+     * impossible id, so a 42501/permission refusal is seen at boot rather than
+     * on a user's first click. Default: on.
+     */
+    probeWrite?: boolean;
+}
+
+/**
+ * catalog/store.ts — @ai-matrx/agents/catalog
+ *
+ * `createAgentCatalog(config)` — the headless kernel. Everything the picker
+ * knows lives here: the row registry, the complete-list read with its
+ * session-shared in-flight dedupe and freshness window, the tier-2 server
+ * search, the per-consumer view state, the ONE write, and the mandate default
+ * row with its drift screamer.
+ *
+ * The host injects a Supabase client and who the user is. Nothing else.
+ *
+ * The consumer reducers below are a VERBATIM port of matrx-frontend
+ * `features/agents/redux/agent-consumers/slice.ts`; only the seam inverts
+ * (a Redux reducer becomes a store method, and Immer's draft mutation becomes
+ * an explicit copy so the store can publish a new reference).
+ */
+
+type AgentCatalogStatus = "idle" | "loading" | "succeeded" | "failed";
+interface AgentCatalogState {
+    /** Every row, one stable array reference per change (memoization depends on it). */
+    rows: AgentSummary[];
+    byId: Record<string, AgentSummary>;
+    status: AgentCatalogStatus;
+    error: string | null;
+    consumers: Record<string, AgentConsumerState>;
+    /** Keyed by mandate key. */
+    defaultRows: Record<string, DefaultRowState>;
+}
+interface AgentCatalog {
+    readonly catalogId: string;
+    readonly labels: AgentCatalogLabels;
+    readonly errorSink: AgentCatalogErrorSink;
+    readonly notifier: AgentCatalogNotifier | undefined;
+    /** True when this catalog was given a transport and can resolve mandates. */
+    readonly canResolveMandates: boolean;
+    getState(): AgentCatalogState;
+    subscribe(listener: () => void): () => void;
+    getAgent(agentId: string): AgentSummary | undefined;
+    /**
+     * The signed-in user id, or `null` when there is no session. The ONE place
+     * `identity.requireUserId()`'s throw is caught — a signed-out visitor
+     * legitimately lands on the public catalogue — and it is reported to the
+     * errorSink the first time so it is never silent.
+     */
+    getUserIdOrNull(): string | null;
+    /** Load the catalogue if it is not fresh. Safe to call on every mount. */
+    ensureLoaded(options?: {
+        force?: boolean;
+    }): 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). */
+    isStale(): boolean;
+    getConsumer(consumerId: string): AgentConsumerState;
+    registerConsumer(consumerId: string, initial?: AgentConsumerPatch): void;
+    unregisterConsumer(consumerId: string): void;
+    setConsumerFilter(consumerId: string, patch: AgentConsumerPatch): void;
+    setConsumerPage(consumerId: string, which: "list" | "shared", page: number): void;
+    setConsumerServerSearch(consumerId: string, args: {
+        matchedIds?: string[];
+        isSearching?: boolean;
+    }): void;
+    resetConsumerFilters(consumerId: string): void;
+    /** Tier-2 search. Purely additive; merges rows into the registry. */
+    searchServer(query: string, deep?: boolean): Promise<string[]>;
+    /** THE ONE WRITE. Optimistic, rolled back on failure, loud either way. */
+    setFavorite(agentId: string, isFavorite: boolean): Promise<void>;
+    /** Resolve (once) the default row for a mandate key. Idempotent. */
+    ensureDefaultRow(mandateKey: string): void;
+    getDefaultRow(mandateKey: string): DefaultRowState | undefined;
+    /** A person acknowledged the drift banner. The notifier already fired. */
+    dismissDefaultRowDrift(mandateKey: string): void;
+    assertSchema(options?: AssertAgentCatalogSchemaOptions): Promise<AgentCatalogSchemaReport>;
+}
+
+/**
+ * The anchor a row renders for cmd/ctrl-click. DEFAULT: a plain `<a>` — which
+ * is a REAL, working link in every framework. A Next.js host passes
+ * `next/link`; a TanStack host passes its own `Link`.
+ */
+type AgentCatalogLinkComponent = ComponentType<{
+    href: string;
+    className?: string;
+    target?: string;
+    rel?: string;
+    title?: string;
+    "aria-label"?: string;
+    onClick?: (e: React.MouseEvent<HTMLAnchorElement>) => void;
+    children: ReactNode;
+}>;
+/** Render a model id as whatever door the host has. DEFAULT: plain text. */
+type AgentCatalogRenderModelRef = (args: {
+    modelId: string;
+    className?: string;
+}) => ReactNode;
+interface AgentCatalogUiPorts {
+    /** DEFAULT: `window.location.assign`. */
+    navigate?: AgentCatalogNavigate;
+    /** DEFAULT: a plain `<a>`. */
+    LinkComponent?: AgentCatalogLinkComponent;
+    /** DEFAULT: the model id as plain text. */
+    renderModelRef?: AgentCatalogRenderModelRef;
+    /** ABSENT: the sneak-peek affordance is HIDDEN — never a dead button. */
+    openPeek?: AgentCatalogOpenPeek;
+    /**
+     * Portal container for the desktop popover, when the picker is mounted
+     * inside a dialog. DEFAULT: the document body (Radix's own default).
+     */
+    popoverContainer?: HTMLElement | null;
+}
+interface AgentCatalogProviderProps extends AgentCatalogUiPorts {
+    catalog: AgentCatalog;
+    children: ReactNode;
+}
+declare function AgentCatalogProvider({ catalog, children, ...ports }: AgentCatalogProviderProps): react.JSX.Element;
+/** The headless catalog this tree is bound to. Throws with no provider. */
+declare function useAgentCatalog(): AgentCatalog;
+/** The UI ports this tree is bound to, with every default already applied. */
+declare function useAgentCatalogUiPorts(): Required<Pick<AgentCatalogUiPorts, "navigate" | "LinkComponent" | "renderModelRef">> & {
+    openPeek: AgentCatalogOpenPeek | undefined;
+    popoverContainer: HTMLElement | null | undefined;
+};
+/**
+ * Subscribe to a slice of catalog state. `useSyncExternalStore` because the
+ * catalog is an external store and React 18/19 concurrency must not tear it.
+ * `select` MUST return a stable reference for unchanged state — every
+ * selector in `../selectors` does.
+ */
+declare function useAgentCatalogState<T>(select: (state: AgentCatalogState) => T): T;
+/** Every row currently in the catalogue, as one stable array. */
+declare function useAgentCatalogRows(): AgentSummary[];
+
+interface UseAgentConsumerReturn {
+    tab: AgentTab;
+    sortBy: AgentSortOption;
+    searchTerm: string;
+    includedCats: string[];
+    includedTags: string[];
+    favFilter: AgentFavFilter;
+    archFilter: AgentArchFilter;
+    accessFilter: AgentAccessFilter;
+    favoritesFirst: boolean;
+    listPage: number;
+    sharedPage: number;
+    /** The whole slot, for the selectors that take a consumer state. */
+    state: AgentConsumerState;
+    /** True if any filter differs from its default value. */
+    hasActiveFilters: boolean;
+    /** Tier 2 search — also match against agent prompt content. */
+    deepSearch: boolean;
+    /** True while a server-side search is in flight. */
+    isServerSearching: boolean;
+    setSearchTerm: (value: string) => void;
+    setDeepSearch: (value: boolean) => void;
+    setSortBy: (value: AgentSortOption) => void;
+    setTab: (value: AgentTab) => void;
+    setFavFilter: (value: AgentFavFilter) => void;
+    setArchFilter: (value: AgentArchFilter) => void;
+    setAccessFilter: (value: AgentAccessFilter) => void;
+    /** Add category to inclusion set; if already present, remove (toggle). */
+    toggleCategory: (cat: string) => void;
+    /** Add tag to inclusion set; if already present, remove (toggle). */
+    toggleTag: (tag: string) => void;
+    /**
+     * Replace the WHOLE category inclusion set in one write.
+     *
+     * Prefer this over looping `toggleCategory` whenever more than one value
+     * changes. Each `toggleCategory` call computes its next array from the
+     * `includedCats` captured in the CURRENT render, so two toggles fired in the
+     * same tick both start from the same snapshot and the second one's patch
+     * overwrites the first — a "Clear filter" click with three categories active
+     * removes only one. One write of the final set cannot drift that way.
+     */
+    setIncludedCats: (next: string[]) => void;
+    /** Replace the WHOLE tag inclusion set in one write. See setIncludedCats. */
+    setIncludedTags: (next: string[]) => void;
+    toggleFavoritesFirst: () => void;
+    loadMoreList: () => void;
+    loadMoreShared: () => void;
+    resetFilters: () => void;
+}
+declare function useAgentConsumer(consumerId: string, options?: {
+    /** Delete the slot on unmount. Default false — persistent consumers keep state. */
+    unregisterOnUnmount?: boolean;
+    /** Applied only when the consumer is first registered (idempotent). */
+    initialTab?: AgentTab;
+}): UseAgentConsumerReturn;
+
+interface AgentListTabCounts {
+    mine: number;
+    shared: number;
+    all: number;
+    system: number;
+}
+interface AgentListTabsProps {
+    consumer: UseAgentConsumerReturn;
+    tabCounts: AgentListTabCounts;
+    /** Limit the ownership tabs for constrained pickers. */
+    visibleTabs?: readonly AgentTab[] | undefined;
+    /**
+     * Label for the builtin-agent tab. Users see "Public" (that is what a
+     * platform agent is to them); ADMIN surfaces pass "System", because there
+     * these are the agents they own and maintain.
+     */
+    systemTabLabel?: string | undefined;
+}
+declare function AgentListTabs({ consumer, tabCounts, systemTabLabel, visibleTabs, }: AgentListTabsProps): react.JSX.Element;
+
+interface AgentListCoreOptions {
+    consumerId: string;
+    onSelect?: (agentId: string) => void;
+    navigateTo?: string;
+    /** Route-scoped agent id (chat/builder headers). `undefined` = nothing pinned. */
+    activeAgentIdOverride?: string | null;
+    /**
+     * Tab this surface opens on, applied once on first mount. Admin surfaces
+     * that manage system agents pass `"system"`. When omitted the normal
+     * user heuristic applies (a user with no agents of their own lands on the
+     * public/system catalogue).
+     */
+    initialTab?: AgentTab;
+    /**
+     * ADMIN reading of the "All" tab: blend system agents into it instead of
+     * keeping them to their own tab. See `makeSelectFilteredAgents`.
+     */
+    includeSystemInAll?: boolean;
+    /**
+     * 🚨 THE OWNERSHIP TABS THIS CALL SITE MAY REACH — a HARD restriction, not a
+     * default.
+     *
+     * `AgentListTabs` already hides the buttons this list omits, but hiding a
+     * button never emptied the list behind it: the active tab lives in the
+     * consumer's REMEMBERED state, and `initialTab` is applied exactly once per
+     * mount (`defaultTabAppliedRef`). So a person who had been on "Mine" and
+     * then moved a control that narrows the picker got the personal catalogue
+     * with the tab bar removed — the forbidden list, and no way to see that it
+     * was forbidden. That is the defect Arman named on the mandate binding
+     * screen's global rung (VISION-RECONCILIATION D2, 2026-08-31: the picker
+     * opened on "Mine · 40").
+     *
+     * Given here, the tab is COERCED into the allowed set on every change of it,
+     * not just at mount — so a restriction that arrives later is enforced later.
+     */
+    visibleTabs?: readonly AgentTab[];
+    /** Hide records that are invalid for this call site. */
+    excludeAgentIds?: readonly string[];
+    /**
+     * Show the platform DEFAULT agent for this mandate key at the top of the
+     * list, resolved live through the server (never a hardcoded name). Requires
+     * the catalog to have been built with a `transport`.
+     */
+    defaultMandateKey?: string;
+}
+/**
+ * How long the hover-preview detail panel stays open after the cursor leaves
+ * an agent row (or the panel itself) before it closes. Generous on purpose:
+ * the panel renders to the side of the list, so the user needs ample time to
+ * travel the cursor across the gap to reach it without it vanishing. Paired
+ * with a reserved, non-resizing popover width so the target never moves.
+ */
+declare const HOVER_GRACE_MS = 900;
+/**
+ * THE RULE, ALONE AND TESTABLE: which tab a restricted picker must land on.
+ *
+ * Returns `null` when the current tab is already allowed (nothing to do), and
+ * otherwise the tab to switch to — `initialTab` when that is itself allowed,
+ * else the first allowed tab.
+ */
+declare function coerceVisibleTab(current: AgentTab, allowed: readonly AgentTab[], initialTab?: AgentTab): AgentTab | null;
+declare function useAgentListCore({ consumerId, onSelect, navigateTo, activeAgentIdOverride, initialTab, includeSystemInAll, visibleTabs, excludeAgentIds, defaultMandateKey, }: AgentListCoreOptions): {
+    agents: AgentSummary[];
+    isLoading: boolean;
+    activeAgentId: string | null;
+    pinnedAgent: AgentSummary | null;
+    defaultRow: DefaultRowState | null;
+    allCategories: string[];
+    allTags: string[];
+    consumer: UseAgentConsumerReturn;
+    tabCounts: AgentListTabCounts;
+    activeFilterCount: number;
+    hoveredAgent: AgentSummary | null;
+    setHoveredAgent: react.Dispatch<react.SetStateAction<AgentSummary | null>>;
+    ensureLoaded: () => void;
+    handleSelectAgent: (agent: AgentSummary) => void;
+    handleAgentHover: (agent: AgentSummary, panelOpen: boolean) => void;
+    handleAgentHoverEnd: (agent: AgentSummary, onClear: () => void) => void;
+    handleDetailPanelMouseEnter: () => void;
+    handleDetailPanelMouseLeave: (onClear: () => void) => void;
+};
+
+interface AgentListDropdownProps {
+    onSelect?: (agentId: string) => void;
+    navigateTo?: string;
+    className?: string;
+    label?: string;
+    /** Custom trigger element — replaces the default text button. */
+    triggerSlot?: React.ReactNode;
+    /** Remove the border from the default trigger button. */
+    noBorder?: boolean;
+    /** Use a compact (h-5) trigger instead of the default h-7. */
+    compact?: boolean;
+    /** Route-scoped agent id — highlights + pins the current agent in the list. */
+    activeAgentId?: string | null;
+    /**
+     * Which side the desktop popover opens toward. Defaults to Radix's "bottom".
+     * Pass "right" when the trigger lives in a narrow vertical rail so the panel
+     * opens beside the rail instead of covering it. Ignored on mobile (Drawer).
+     */
+    contentSide?: "top" | "right" | "bottom" | "left";
+    /**
+     * Isolate this dropdown's filter/tab state under its own consumer id.
+     * Defaults to the shared `agent-list-dropdown` consumer so ordinary chat
+     * triggers keep one remembered set of filters across the app.
+     */
+    consumerId?: string;
+    /** Tab to open on. Admin surfaces managing system agents pass `"system"`. */
+    initialTab?: AgentTab;
+    /** ADMIN variant: blend system agents into the "All" tab. */
+    includeSystemInAll?: boolean;
+    /** Restrict which ownership tabs are available for domain-constrained pickers. */
+    visibleTabs?: readonly AgentTab[];
+    /** Label override for the builtin-agent tab. Admin surfaces use "System". */
+    systemTabLabel?: string;
+    /** Resolve the route used by each named agent door. */
+    resolveAgentHref?: (agent: AgentSummary) => string;
+    /** Show the active agent above the filtered list. Default true. */
+    showPinnedAgent?: boolean;
+    /** Hide records that are invalid for this call site. */
+    excludeAgentIds?: readonly string[];
+    /**
+     * Offer the platform DEFAULT agent for this mandate key at the top of the
+     * list, named LIVE from the mandate's real Holder. `onSelect` receives
+     * `mandate:<key>` for that row — the ref shape every client already speaks.
+     */
+    defaultMandateKey?: string;
+}
+declare function AgentListDropdown({ onSelect, navigateTo, className, label, triggerSlot, noBorder, compact, activeAgentId: activeAgentIdProp, contentSide, consumerId, initialTab, includeSystemInAll, visibleTabs, systemTabLabel, resolveAgentHref: resolveAgentHrefProp, showPinnedAgent, excludeAgentIds, defaultMandateKey, }: AgentListDropdownProps): react.JSX.Element;
+
+interface AgentListInlinePickerProps {
+    /** Unique consumer id for filter/tab state (see `useAgentConsumer`). */
+    consumerId: string;
+    onSelect: (agentId: string) => void;
+    activeAgentId?: string | null;
+    className?: string;
+    /** Auto-focus the search field on mount. Default true. */
+    autoFocusSearch?: boolean;
+    /** Tab to open on. Admin surfaces that manage system agents pass `"system"`. */
+    initialTab?: AgentTab;
+    /** ADMIN variant: blend system agents into the "All" tab. */
+    includeSystemInAll?: boolean;
+    /** Restrict which ownership tabs are available for domain-constrained pickers. */
+    visibleTabs?: readonly AgentTab[];
+    /** Label override for the builtin-agent tab. Admin surfaces use "System". */
+    systemTabLabel?: string;
+    /** Resolve the route used by each named agent door. */
+    resolveAgentHref?: (agent: AgentSummary) => string;
+    /** Show the globally active agent above the filtered list. Default true. */
+    showPinnedAgent?: boolean;
+    /** Hide records that are invalid for this call site. */
+    excludeAgentIds?: readonly string[];
+    /** Offer the mandate's live-resolved default agent at the top of the list. */
+    defaultMandateKey?: string;
+}
+declare function AgentListInlinePicker({ consumerId, onSelect, activeAgentId, className, autoFocusSearch, initialTab, includeSystemInAll, visibleTabs, systemTabLabel, resolveAgentHref, showPinnedAgent, excludeAgentIds, defaultMandateKey, }: AgentListInlinePickerProps): react.JSX.Element;
+
+/**
+ * catalog/react/types.ts — VERBATIM port of matrx-frontend
+ * `features/agents/components/agent-listings/core/types.ts`.
+ */
+
+type RightPanel = "detail" | "sort" | "categories" | "tags" | null;
+declare const SORT_OPTIONS: {
+    value: AgentSortOption;
+    label: string;
+}[];
+declare const PANEL_HEIGHT = "528px";
+/**
+ * 🚨 THE PANEL NEVER OUTGROWS THE SPACE IT HAS.
+ *
+ * The popover reserves a FIXED footprint on purpose (a resizing panel in a
+ * narrow rail gets collision-shifted out from under the cursor). But a flat
+ * 528px is taller than the room above a trigger sitting mid-page on a laptop,
+ * and Radix cannot shift what does not fit either way — so the top of the
+ * panel, which is the SEARCH BOX, was rendered off-screen. Measured 2026-09-08
+ * on the mandate Holder screen at 1280x900: the popover sat at `top: -76`.
+ *
+ * Clamping to Radix's own measurement keeps the footprint fixed whenever there
+ * IS room and merely shortens the list when there is not — the panel still
+ * never resizes while open, because the available height does not change while
+ * the popover is open.
+ */
+declare const LIST_MAX_HEIGHT = "min(528px, var(--radix-popper-available-height, 528px))";
+
+interface AgentListContentProps {
+    agents: AgentSummary[];
+    isLoading: boolean;
+    consumer: UseAgentConsumerReturn;
+    activeAgentId: string | null;
+    allCategories: string[];
+    allTags: string[];
+    inputRef: React.RefObject<HTMLInputElement | null>;
+    onSelectAgent: (a: AgentSummary) => void;
+    /** Per-row href for cmd/ctrl+click. Defaults to `/agents/go/[id]`. */
+    resolveAgentHref?: ((agent: AgentSummary) => string) | undefined;
+    onReset: () => void;
+    activeFilterCount: number;
+    isMobile: boolean;
+    hoveredAgent: AgentSummary | null;
+    onAgentHover: (a: AgentSummary) => void;
+    onAgentHoverEnd: (a: AgentSummary) => void;
+    onDetailPress: (a: AgentSummary) => void;
+    onFilterChipClick: (panel: "sort" | "categories" | "tags") => void;
+    rightPanel: RightPanel;
+    tabCounts: AgentListTabCounts;
+    /** Limit the ownership tabs shown by this picker. */
+    visibleTabs?: readonly AgentTab[] | undefined;
+    /** Label override for the builtin tab — admin surfaces pass "System". */
+    systemTabLabel?: string | undefined;
+    /** Resolved current agent — pinned at the top when the list opens. */
+    pinnedAgent?: AgentSummary | null | undefined;
+    /** The mandate default row, when this picker was given a `defaultMandateKey`. */
+    defaultRow?: DefaultRowState | null | undefined;
+    /** When true, scroll the list to the pinned row (top). */
+    listOpen?: boolean | 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, }: AgentListContentProps): react.JSX.Element;
+
+interface AgentFilterBarProps {
+    consumer: UseAgentConsumerReturn;
+    allCategories: string[];
+    allTags: string[];
+    activeFilterCount: number;
+    isMobile: boolean;
+    rightPanel: RightPanel;
+    onFilterChipClick: (panel: "sort" | "categories" | "tags") => void;
+    onReset: () => void;
+}
+/**
+ * The filter bar is IDENTICAL on every tab, system included. A tab that offers
+ * fewer controls than its neighbour is the half-built shape this list exists
+ * to prevent — the system tab's category/tag options simply come from the
+ * builtin population (see `selectAllSystemAgentCategories`).
+ */
+declare function AgentFilterBar({ consumer, allCategories, allTags, activeFilterCount, isMobile, rightPanel, onFilterChipClick, onReset, }: AgentFilterBarProps): react.JSX.Element;
+
+interface AgentRowProps {
+    agent: AgentSummary;
+    isActive: boolean;
+    isHovered: boolean;
+    isMobile: boolean;
+    /** Row href. Defaults to `/agents/go/[id]`. */
+    href?: string | undefined;
+    onClick: () => void;
+    onHover: () => void;
+    onHoverEnd: () => void;
+    onDetailPress: () => void;
+}
+declare function AgentRow({ agent, isActive, isHovered, isMobile, href, onClick, onHover, onHoverEnd, onDetailPress, }: AgentRowProps): react.JSX.Element;
+
+interface AgentDetailCardProps {
+    agent: AgentSummary;
+    onSelect: () => void;
+}
+declare function AgentDetailCard({ agent, onSelect }: AgentDetailCardProps): react.JSX.Element;
+
+interface AgentSortPanelProps {
+    consumer: UseAgentConsumerReturn;
+    onClose: () => void;
+}
+declare function AgentSortPanel({ consumer, onClose }: AgentSortPanelProps): react.JSX.Element;
+
+interface AgentCategoriesPanelProps {
+    consumer: UseAgentConsumerReturn;
+    allCategories: string[];
+    search: string;
+    setSearch: (v: string) => void;
+    onClose: () => void;
+}
+declare function AgentCategoriesPanel({ consumer, allCategories, search, setSearch, onClose, }: AgentCategoriesPanelProps): react.JSX.Element;
+
+interface AgentTagsPanelProps {
+    consumer: UseAgentConsumerReturn;
+    allTags: string[];
+    search: string;
+    setSearch: (v: string) => void;
+    onClose: () => void;
+}
+declare function AgentTagsPanel({ consumer, allTags, search, setSearch, onClose, }: AgentTagsPanelProps): react.JSX.Element;
+
+interface AgentMobileSubViewProps {
+    view: "sort" | "categories" | "tags";
+    consumer: UseAgentConsumerReturn;
+    allCategories: string[];
+    allTags: string[];
+    catSearch: string;
+    setCatSearch: (v: string) => void;
+    tagSearch: string;
+    setTagSearch: (v: string) => void;
+    onBack: () => void;
+}
+declare function AgentMobileSubView({ view, consumer, allCategories, allTags, catSearch, setCatSearch, tagSearch, setTagSearch, onBack, }: AgentMobileSubViewProps): react.JSX.Element;
+
+interface FavoriteAgentButtonProps {
+    id: string;
+    /** "card" = absolute-positioned corner star, "list" = inline icon button */
+    variant?: "card" | "list";
+    disabled?: boolean;
+}
+declare function FavoriteAgentButton({ id, variant, disabled, }: FavoriteAgentButtonProps): react.JSX.Element;
+
+declare const SearchInput: ({ ref, value, onChange, placeholder, }: {
+    ref?: Ref<HTMLInputElement>;
+    value: string;
+    onChange: (v: string) => void;
+    placeholder: string;
+}) => react.JSX.Element;
+declare function FilterChip({ icon: Icon, label, active, focused, onClick, }: {
+    icon: ComponentType<{
+        className?: string;
+    }>;
+    label: string;
+    active: boolean;
+    focused?: boolean;
+    onClick: () => void;
+}): react.JSX.Element;
+declare function OptionRow({ label, selected, onClick, }: {
+    label: string;
+    selected: boolean;
+    onClick: () => void;
+}): react.JSX.Element;
+declare function CheckRow({ label, checked, onClick, }: {
+    label: string;
+    checked: boolean;
+    onClick: () => void;
+}): react.JSX.Element;
+declare function SidePanelHeader({ title, onClose, }: {
+    title: string;
+    onClose: () => void;
+}): react.JSX.Element;
+
+export { type AgentCatalogLinkComponent, AgentCatalogProvider, type AgentCatalogProviderProps, type AgentCatalogRenderModelRef, type AgentCatalogUiPorts, AgentCategoriesPanel, type AgentCategoriesPanelProps, AgentDetailCard, type AgentDetailCardProps, AgentFilterBar, type AgentFilterBarProps, AgentListContent, type AgentListContentProps, type AgentListCoreOptions, AgentListDropdown, type AgentListDropdownProps, AgentListInlinePicker, type AgentListInlinePickerProps, type AgentListTabCounts, AgentListTabs, AgentMobileSubView, type AgentMobileSubViewProps, AgentRow, type AgentRowProps, AgentSortPanel, type AgentSortPanelProps, AgentTagsPanel, type AgentTagsPanelProps, CheckRow, FavoriteAgentButton, FilterChip, HOVER_GRACE_MS, LIST_MAX_HEIGHT, OptionRow, PANEL_HEIGHT, type RightPanel, SORT_OPTIONS, SearchInput, SidePanelHeader, type UseAgentConsumerReturn, coerceVisibleTab, useAgentCatalog, useAgentCatalogRows, useAgentCatalogState, useAgentCatalogUiPorts, useAgentConsumer, useAgentListCore };