@ai-matrx/agents 0.7.1 → 0.9.0

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

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ComponentType, ReactNode, Ref } from 'react';
+import { ComponentType, ReactNode, Ref, SVGProps } from 'react';
 
 /**
  * `@ai-matrx/agents/catalog` — the row shape and the per-consumer view state.
@@ -42,6 +42,39 @@ type AgentCatalogAgentType = "user" | "builtin";
  * itself rather than being coerced into a wrong one.
  */
 type AgentAccessLevel = "owner" | "admin" | "editor" | "viewer" | "system" | (string & {});
+/**
+ * Present on a catalog row ONLY when that agent is an **Orchestra** — a
+ * conductor that delegates to member agents at run time. Choosing one for a
+ * step, a chat or a workflow node runs the whole ensemble, so a person has to
+ * be able to SEE that before choosing, not discover it from the run.
+ *
+ * The DB decides. `agx_get_list_full` / `agx_get_list` / `agx_search` build
+ * this from `platform.associations` (the conductor self-edge plus its member
+ * edges) in one `agx_orchestra_badges()` join — never a second fetch, and
+ * never a per-row read. `null` for every ordinary agent.
+ *
+ * History: the badge lived only in the Python `GET /agents` route, so every
+ * client lost it when the pickers moved to the RPC. It is a ROW FIELD now, in
+ * the one read every client shares.
+ */
+interface OrchestraBadge {
+    /** How the ensemble runs: `supervisor` | `sequential` | `parallel` | `dag`, or a future mode verbatim. */
+    mode: string;
+    /** The composition's one-line description, when its author wrote one. */
+    tagline: string | null;
+    /**
+     * The per-composition delegation-depth budget AS DECLARED, or `null` when
+     * the composition declares none. Deliberately NOT defaulted here: the
+     * platform's fallback ceiling is enforced by the server that runs the
+     * ensemble, and a badge that invented a number would be reporting a promise
+     * nobody made.
+     */
+    depthBudget: number | null;
+    /** Member edges. From the ROW count, so an unlabelled ensemble still counts. */
+    memberCount: number;
+    /** Only REAL role titles — an ensemble with unlabelled edges yields `[]`. */
+    memberTitles: string[];
+}
 /**
  * One `agx_get_list_full()` row, camelCased. Nineteen columns, no more:
  * anything richer needs a different read and is a different type.
@@ -66,6 +99,12 @@ interface AgentSummary {
     isOwner: boolean | null;
     accessLevel: AgentAccessLevel | null;
     sharedByEmail: string | null;
+    /**
+     * The Orchestra badge, or `null` for an ordinary agent. Strict: every row
+     * carries the key, so a surface reads `agent.orchestra` and never has to ask
+     * whether the column existed.
+     */
+    orchestra: OrchestraBadge | 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.
@@ -73,6 +112,21 @@ interface AgentSummary {
     mandateKey?: string;
 }
 type AgentSortOption = "updated-desc" | "created-desc" | "name-asc" | "name-desc" | "category-asc";
+/**
+ * The sort choices a picker offers, in order. PURE DATA, so it lives in the
+ * pure entry: a server-reachable manifest reads it at module scope, and
+ * importing it from the client-stamped `./catalog/react` bundle dragged React
+ * into a server graph for the sake of five string pairs. `./catalog/react`
+ * re-exports it unchanged, so no consumer has to move.
+ *
+ * (Written "client-stamped", never with the literal directive: this comment is
+ * emitted into `dist/catalog/index.d.ts`, and the tarball canary rightly
+ * refuses that directive anywhere in a PURE entry.)
+ */
+declare const SORT_OPTIONS: {
+    value: AgentSortOption;
+    label: string;
+}[];
 /** Which ownership tab is active in the agent list. */
 type AgentTab = "mine" | "shared" | "all" | "system";
 /** Favorite filter. */
@@ -259,6 +313,18 @@ interface AgentCatalogSchemaReport {
     answered: string[];
     /** True when `agent.definition.is_favorite` is writable by this caller. */
     favoriteWritable: boolean | null;
+    /**
+     * Whether `agx_get_list_full` carries the `orchestra` badge column (added to
+     * the platform 2026-09-08).
+     *
+     * NOT a violation when absent — the picker degrades to no conductor marker,
+     * which is honest — but it is never SILENT either: a `false` here is the one
+     * signal that tells a host "this database predates the badge" instead of
+     * leaving someone to wonder why their Orchestra looks like a plain agent.
+     * `null` means the probe could not tell (the caller can see no agents at
+     * all), never "fine".
+     */
+    orchestraColumn: boolean | null;
 }
 interface AssertAgentCatalogSchemaOptions {
     /**
@@ -352,10 +418,23 @@ interface AgentCatalog {
 }
 
 /**
- * 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`.
+ * The anchor a row renders for cmd/ctrl-click. DEFAULT (web): 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`. On React Native the
+ * default is a pressable `Text` that routes through `navigate`.
+ */
+/**
+ * What a row's link handler receives. A DOM `React.MouseEvent` satisfies this
+ * structurally, and the native default link supplies the two methods itself —
+ * so a shared component can call `preventDefault()` on either platform
+ * without a platform check.
  */
+interface AgentCatalogLinkClickEvent {
+    metaKey?: boolean;
+    ctrlKey?: boolean;
+    preventDefault(): void;
+    stopPropagation(): void;
+}
 type AgentCatalogLinkComponent = ComponentType<{
     href: string;
     className?: string;
@@ -363,7 +442,7 @@ type AgentCatalogLinkComponent = ComponentType<{
     rel?: string;
     title?: string;
     "aria-label"?: string;
-    onClick?: (e: React.MouseEvent<HTMLAnchorElement>) => void;
+    onClick?: (e: AgentCatalogLinkClickEvent) => void;
     children: ReactNode;
 }>;
 /** Render a model id as whatever door the host has. DEFAULT: plain text. */
@@ -372,9 +451,9 @@ type AgentCatalogRenderModelRef = (args: {
     className?: string;
 }) => ReactNode;
 interface AgentCatalogUiPorts {
-    /** DEFAULT: `window.location.assign`. */
+    /** DEFAULT (web): `window.location.assign`. DEFAULT (native): a reporting no-op. */
     navigate?: AgentCatalogNavigate;
-    /** DEFAULT: a plain `<a>`. */
+    /** DEFAULT: a plain `<a>` (web) / a pressable `Text` (native). */
     LinkComponent?: AgentCatalogLinkComponent;
     /** DEFAULT: the model id as plain text. */
     renderModelRef?: AgentCatalogRenderModelRef;
@@ -383,14 +462,10 @@ interface AgentCatalogUiPorts {
     /**
      * Portal container for the desktop popover, when the picker is mounted
      * inside a dialog. DEFAULT: the document body (Radix's own default).
+     * Web only — the native entry ignores it.
      */
     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. */
@@ -408,6 +483,30 @@ declare function useAgentCatalogState<T>(select: (state: AgentCatalogState) => T
 /** Every row currently in the catalogue, as one stable array. */
 declare function useAgentCatalogRows(): AgentSummary[];
 
+interface AgentCatalogProviderProps extends AgentCatalogUiPorts {
+    catalog: AgentCatalog;
+    children: ReactNode;
+}
+declare function AgentCatalogProvider({ catalog, children, ...ports }: AgentCatalogProviderProps): react.JSX.Element;
+
+/**
+ * catalog/shared/useAgentConsumer.ts — VERBATIM port of matrx-frontend
+ * `features/agents/hooks/useAgentConsumer.ts`.
+ *
+ * Wraps a single consumer slot identified by `consumerId`. Registers the slot
+ * on mount, optionally unregisters on unmount, and returns every filter/sort/
+ * pagination value plus stable write helpers.
+ *
+ * Two seams inverted, nothing else:
+ *   - `useAppSelector`/`useAppDispatch` → `useAgentCatalog()` + the store's
+ *     own methods.
+ *   - `useServerAgentSearch` (a separate frontend hook) is folded IN, because
+ *     it was already wired here and nowhere else: EVERY agent surface that
+ *     uses a consumer searches the full server-side set. A local-only search
+ *     over a paginated list reports "no results" for agents that were merely
+ *     never fetched — a wrong answer, not a missing feature.
+ */
+
 interface UseAgentConsumerReturn {
     tab: AgentTab;
     sortBy: AgentSortOption;
@@ -464,26 +563,17 @@ declare function useAgentConsumer(consumerId: string, options?: {
     initialTab?: AgentTab;
 }): UseAgentConsumerReturn;
 
+/**
+ * The four ownership counts a tab strip prints. Declared HERE, beside the code
+ * that computes them, so both the web tab strip and the native one name the
+ * same shape (0.9.0 — it used to live in the web-only `AgentListTabs`).
+ */
 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;
@@ -641,16 +731,26 @@ interface AgentListInlinePickerProps {
 }
 declare function AgentListInlinePicker({ consumerId, onSelect, activeAgentId, className, autoFocusSearch, initialTab, includeSystemInAll, visibleTabs, systemTabLabel, resolveAgentHref, showPinnedAgent, excludeAgentIds, defaultMandateKey, }: AgentListInlinePickerProps): react.JSX.Element;
 
+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;
+
 /**
  * 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.
@@ -816,4 +916,43 @@ declare function SidePanelHeader({ title, onClose, }: {
     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 };
+type IconProps = SVGProps<SVGSVGElement> & {
+    className?: string;
+};
+/**
+ * The Orchestra marker (Lucide `music-4`): the glyph the Workflow Studio's
+ * picker used for a conductor, kept identical so the same agent wears the same
+ * mark in every client.
+ */
+declare const Music4Icon: (props: IconProps) => react.JSX.Element;
+
+/**
+ * catalog/orchestra.ts — @ai-matrx/agents/catalog
+ *
+ * Creator words for an Orchestra badge. A VERBATIM port of the helpers the
+ * Workflow Studio's hand-rolled picker carried (`apps/workflow-studio/src/
+ * hooks/use-agents.ts` before `c0f958b43`), lifted here so every client says
+ * the same sentence about the same ensemble.
+ *
+ * Pure — no React, no DOM. The row shape is `OrchestraBadge` in `./types`.
+ */
+
+declare function orchestraModeLabel(mode: string): string;
+/** Human label for a badge: "Orchestra · supervisor · 3 members" (singular-safe). */
+declare function orchestraLabel(badge: OrchestraBadge): string;
+/**
+ * The member-call ceiling in Creator language ("Team members can call helpers
+ * up to 2 levels deep"), or `null` when the composition declared none. A badge
+ * never invents the platform default: the server that runs the ensemble owns
+ * that number, and printing a promise nobody made is worse than printing
+ * nothing.
+ */
+declare function orchestraDepthLine(badge: OrchestraBadge): string | null;
+/**
+ * One visible line naming who the Orchestra delegates to, collapsing past
+ * `limit` into "+N more". `null` when no member carries a real role title —
+ * "Member, Member, Member" is noise that reads like data.
+ */
+declare function orchestraDelegatesLine(badge: OrchestraBadge, limit?: number): string | null;
+
+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, type IconProps, LIST_MAX_HEIGHT, Music4Icon, OptionRow, type OrchestraBadge, PANEL_HEIGHT, type RightPanel, SORT_OPTIONS, SearchInput, SidePanelHeader, type UseAgentConsumerReturn, coerceVisibleTab, orchestraDelegatesLine, orchestraDepthLine, orchestraLabel, orchestraModeLabel, useAgentCatalog, useAgentCatalogRows, useAgentCatalogState, useAgentCatalogUiPorts, useAgentConsumer, useAgentListCore };

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

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ComponentType, ReactNode, Ref } from 'react';
+import { ComponentType, ReactNode, Ref, SVGProps } from 'react';
 
 /**
  * `@ai-matrx/agents/catalog` — the row shape and the per-consumer view state.
@@ -42,6 +42,39 @@ type AgentCatalogAgentType = "user" | "builtin";
  * itself rather than being coerced into a wrong one.
  */
 type AgentAccessLevel = "owner" | "admin" | "editor" | "viewer" | "system" | (string & {});
+/**
+ * Present on a catalog row ONLY when that agent is an **Orchestra** — a
+ * conductor that delegates to member agents at run time. Choosing one for a
+ * step, a chat or a workflow node runs the whole ensemble, so a person has to
+ * be able to SEE that before choosing, not discover it from the run.
+ *
+ * The DB decides. `agx_get_list_full` / `agx_get_list` / `agx_search` build
+ * this from `platform.associations` (the conductor self-edge plus its member
+ * edges) in one `agx_orchestra_badges()` join — never a second fetch, and
+ * never a per-row read. `null` for every ordinary agent.
+ *
+ * History: the badge lived only in the Python `GET /agents` route, so every
+ * client lost it when the pickers moved to the RPC. It is a ROW FIELD now, in
+ * the one read every client shares.
+ */
+interface OrchestraBadge {
+    /** How the ensemble runs: `supervisor` | `sequential` | `parallel` | `dag`, or a future mode verbatim. */
+    mode: string;
+    /** The composition's one-line description, when its author wrote one. */
+    tagline: string | null;
+    /**
+     * The per-composition delegation-depth budget AS DECLARED, or `null` when
+     * the composition declares none. Deliberately NOT defaulted here: the
+     * platform's fallback ceiling is enforced by the server that runs the
+     * ensemble, and a badge that invented a number would be reporting a promise
+     * nobody made.
+     */
+    depthBudget: number | null;
+    /** Member edges. From the ROW count, so an unlabelled ensemble still counts. */
+    memberCount: number;
+    /** Only REAL role titles — an ensemble with unlabelled edges yields `[]`. */
+    memberTitles: string[];
+}
 /**
  * One `agx_get_list_full()` row, camelCased. Nineteen columns, no more:
  * anything richer needs a different read and is a different type.
@@ -66,6 +99,12 @@ interface AgentSummary {
     isOwner: boolean | null;
     accessLevel: AgentAccessLevel | null;
     sharedByEmail: string | null;
+    /**
+     * The Orchestra badge, or `null` for an ordinary agent. Strict: every row
+     * carries the key, so a surface reads `agent.orchestra` and never has to ask
+     * whether the column existed.
+     */
+    orchestra: OrchestraBadge | 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.
@@ -73,6 +112,21 @@ interface AgentSummary {
     mandateKey?: string;
 }
 type AgentSortOption = "updated-desc" | "created-desc" | "name-asc" | "name-desc" | "category-asc";
+/**
+ * The sort choices a picker offers, in order. PURE DATA, so it lives in the
+ * pure entry: a server-reachable manifest reads it at module scope, and
+ * importing it from the client-stamped `./catalog/react` bundle dragged React
+ * into a server graph for the sake of five string pairs. `./catalog/react`
+ * re-exports it unchanged, so no consumer has to move.
+ *
+ * (Written "client-stamped", never with the literal directive: this comment is
+ * emitted into `dist/catalog/index.d.ts`, and the tarball canary rightly
+ * refuses that directive anywhere in a PURE entry.)
+ */
+declare const SORT_OPTIONS: {
+    value: AgentSortOption;
+    label: string;
+}[];
 /** Which ownership tab is active in the agent list. */
 type AgentTab = "mine" | "shared" | "all" | "system";
 /** Favorite filter. */
@@ -259,6 +313,18 @@ interface AgentCatalogSchemaReport {
     answered: string[];
     /** True when `agent.definition.is_favorite` is writable by this caller. */
     favoriteWritable: boolean | null;
+    /**
+     * Whether `agx_get_list_full` carries the `orchestra` badge column (added to
+     * the platform 2026-09-08).
+     *
+     * NOT a violation when absent — the picker degrades to no conductor marker,
+     * which is honest — but it is never SILENT either: a `false` here is the one
+     * signal that tells a host "this database predates the badge" instead of
+     * leaving someone to wonder why their Orchestra looks like a plain agent.
+     * `null` means the probe could not tell (the caller can see no agents at
+     * all), never "fine".
+     */
+    orchestraColumn: boolean | null;
 }
 interface AssertAgentCatalogSchemaOptions {
     /**
@@ -352,10 +418,23 @@ interface AgentCatalog {
 }
 
 /**
- * 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`.
+ * The anchor a row renders for cmd/ctrl-click. DEFAULT (web): 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`. On React Native the
+ * default is a pressable `Text` that routes through `navigate`.
+ */
+/**
+ * What a row's link handler receives. A DOM `React.MouseEvent` satisfies this
+ * structurally, and the native default link supplies the two methods itself —
+ * so a shared component can call `preventDefault()` on either platform
+ * without a platform check.
  */
+interface AgentCatalogLinkClickEvent {
+    metaKey?: boolean;
+    ctrlKey?: boolean;
+    preventDefault(): void;
+    stopPropagation(): void;
+}
 type AgentCatalogLinkComponent = ComponentType<{
     href: string;
     className?: string;
@@ -363,7 +442,7 @@ type AgentCatalogLinkComponent = ComponentType<{
     rel?: string;
     title?: string;
     "aria-label"?: string;
-    onClick?: (e: React.MouseEvent<HTMLAnchorElement>) => void;
+    onClick?: (e: AgentCatalogLinkClickEvent) => void;
     children: ReactNode;
 }>;
 /** Render a model id as whatever door the host has. DEFAULT: plain text. */
@@ -372,9 +451,9 @@ type AgentCatalogRenderModelRef = (args: {
     className?: string;
 }) => ReactNode;
 interface AgentCatalogUiPorts {
-    /** DEFAULT: `window.location.assign`. */
+    /** DEFAULT (web): `window.location.assign`. DEFAULT (native): a reporting no-op. */
     navigate?: AgentCatalogNavigate;
-    /** DEFAULT: a plain `<a>`. */
+    /** DEFAULT: a plain `<a>` (web) / a pressable `Text` (native). */
     LinkComponent?: AgentCatalogLinkComponent;
     /** DEFAULT: the model id as plain text. */
     renderModelRef?: AgentCatalogRenderModelRef;
@@ -383,14 +462,10 @@ interface AgentCatalogUiPorts {
     /**
      * Portal container for the desktop popover, when the picker is mounted
      * inside a dialog. DEFAULT: the document body (Radix's own default).
+     * Web only — the native entry ignores it.
      */
     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. */
@@ -408,6 +483,30 @@ declare function useAgentCatalogState<T>(select: (state: AgentCatalogState) => T
 /** Every row currently in the catalogue, as one stable array. */
 declare function useAgentCatalogRows(): AgentSummary[];
 
+interface AgentCatalogProviderProps extends AgentCatalogUiPorts {
+    catalog: AgentCatalog;
+    children: ReactNode;
+}
+declare function AgentCatalogProvider({ catalog, children, ...ports }: AgentCatalogProviderProps): react.JSX.Element;
+
+/**
+ * catalog/shared/useAgentConsumer.ts — VERBATIM port of matrx-frontend
+ * `features/agents/hooks/useAgentConsumer.ts`.
+ *
+ * Wraps a single consumer slot identified by `consumerId`. Registers the slot
+ * on mount, optionally unregisters on unmount, and returns every filter/sort/
+ * pagination value plus stable write helpers.
+ *
+ * Two seams inverted, nothing else:
+ *   - `useAppSelector`/`useAppDispatch` → `useAgentCatalog()` + the store's
+ *     own methods.
+ *   - `useServerAgentSearch` (a separate frontend hook) is folded IN, because
+ *     it was already wired here and nowhere else: EVERY agent surface that
+ *     uses a consumer searches the full server-side set. A local-only search
+ *     over a paginated list reports "no results" for agents that were merely
+ *     never fetched — a wrong answer, not a missing feature.
+ */
+
 interface UseAgentConsumerReturn {
     tab: AgentTab;
     sortBy: AgentSortOption;
@@ -464,26 +563,17 @@ declare function useAgentConsumer(consumerId: string, options?: {
     initialTab?: AgentTab;
 }): UseAgentConsumerReturn;
 
+/**
+ * The four ownership counts a tab strip prints. Declared HERE, beside the code
+ * that computes them, so both the web tab strip and the native one name the
+ * same shape (0.9.0 — it used to live in the web-only `AgentListTabs`).
+ */
 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;
@@ -641,16 +731,26 @@ interface AgentListInlinePickerProps {
 }
 declare function AgentListInlinePicker({ consumerId, onSelect, activeAgentId, className, autoFocusSearch, initialTab, includeSystemInAll, visibleTabs, systemTabLabel, resolveAgentHref, showPinnedAgent, excludeAgentIds, defaultMandateKey, }: AgentListInlinePickerProps): react.JSX.Element;
 
+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;
+
 /**
  * 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.
@@ -816,4 +916,43 @@ declare function SidePanelHeader({ title, onClose, }: {
     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 };
+type IconProps = SVGProps<SVGSVGElement> & {
+    className?: string;
+};
+/**
+ * The Orchestra marker (Lucide `music-4`): the glyph the Workflow Studio's
+ * picker used for a conductor, kept identical so the same agent wears the same
+ * mark in every client.
+ */
+declare const Music4Icon: (props: IconProps) => react.JSX.Element;
+
+/**
+ * catalog/orchestra.ts — @ai-matrx/agents/catalog
+ *
+ * Creator words for an Orchestra badge. A VERBATIM port of the helpers the
+ * Workflow Studio's hand-rolled picker carried (`apps/workflow-studio/src/
+ * hooks/use-agents.ts` before `c0f958b43`), lifted here so every client says
+ * the same sentence about the same ensemble.
+ *
+ * Pure — no React, no DOM. The row shape is `OrchestraBadge` in `./types`.
+ */
+
+declare function orchestraModeLabel(mode: string): string;
+/** Human label for a badge: "Orchestra · supervisor · 3 members" (singular-safe). */
+declare function orchestraLabel(badge: OrchestraBadge): string;
+/**
+ * The member-call ceiling in Creator language ("Team members can call helpers
+ * up to 2 levels deep"), or `null` when the composition declared none. A badge
+ * never invents the platform default: the server that runs the ensemble owns
+ * that number, and printing a promise nobody made is worse than printing
+ * nothing.
+ */
+declare function orchestraDepthLine(badge: OrchestraBadge): string | null;
+/**
+ * One visible line naming who the Orchestra delegates to, collapsing past
+ * `limit` into "+N more". `null` when no member carries a real role title —
+ * "Member, Member, Member" is noise that reads like data.
+ */
+declare function orchestraDelegatesLine(badge: OrchestraBadge, limit?: number): string | null;
+
+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, type IconProps, LIST_MAX_HEIGHT, Music4Icon, OptionRow, type OrchestraBadge, PANEL_HEIGHT, type RightPanel, SORT_OPTIONS, SearchInput, SidePanelHeader, type UseAgentConsumerReturn, coerceVisibleTab, orchestraDelegatesLine, orchestraDepthLine, orchestraLabel, orchestraModeLabel, useAgentCatalog, useAgentCatalogRows, useAgentCatalogState, useAgentCatalogUiPorts, useAgentConsumer, useAgentListCore };