@ai-matrx/agents 0.9.0 → 0.9.2

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

@@ -131,7 +131,25 @@ declare const SORT_OPTIONS: {
 type AgentTab = "mine" | "shared" | "all" | "system";
 /** Favorite filter. */
 type AgentFavFilter = "all" | "yes" | "no";
-/** Archive filter. */
+/**
+ * The archive filter — THE ARCHIVED-ITEMS LAW's ONE control, in this
+ * package's existing vocabulary.
+ *
+ * > "everything should have an archive filter, and the default should always
+ * > hide archived, but seeing archived items should be one or two clicks
+ * > away." — Arman, 2026-09-09 (`common-docs/policies/archived-items.md`)
+ *
+ * Three states and no more, identical for every entity on the platform:
+ *
+ * | value      | the platform's words | what the list shows      |
+ * |------------|----------------------|--------------------------|
+ * | `active`   | hide archived        | only un-archived rows    |
+ * | `both`     | show all             | every row                |
+ * | `archived` | archived only        | only archived rows       |
+ *
+ * `active` is the platform default, and it is a KNOB — see
+ * `AgentCatalogConfig.defaults.archiveFilter`.
+ */
 type AgentArchFilter = "active" | "archived" | "both";
 /**
  * Access level filter.
@@ -377,6 +395,14 @@ interface AgentCatalog {
     readonly notifier: AgentCatalogNotifier | undefined;
     /** True when this catalog was given a transport and can resolve mandates. */
     readonly canResolveMandates: boolean;
+    /**
+     * The consumer state a brand-new consumer starts from, AFTER the host's
+     * `defaults` knob is applied. Read it instead of
+     * `DEFAULT_AGENT_CONSUMER_STATE` whenever the question is "is this filter at
+     * its default?" — a host that legitimately defaults the archive filter to
+     * "show all" must not have every control render as though it were modified.
+     */
+    readonly consumerDefaults: AgentConsumerState;
     getState(): AgentCatalogState;
     subscribe(listener: () => void): () => void;
     getAgent(agentId: string): AgentSummary | undefined;
@@ -515,6 +541,13 @@ interface UseAgentConsumerReturn {
     includedTags: string[];
     favFilter: AgentFavFilter;
     archFilter: AgentArchFilter;
+    /**
+     * The archive-filter state this catalog starts consumers in — the platform
+     * default `"active"` unless the host set the knob. What "not the default
+     * state" means on this surface, so the control and the footer can both say
+     * it honestly.
+     */
+    archFilterDefault: AgentArchFilter;
     accessFilter: AgentAccessFilter;
     favoritesFirst: boolean;
     listPage: number;
@@ -561,12 +594,23 @@ declare function useAgentConsumer(consumerId: string, options?: {
     unregisterOnUnmount?: boolean;
     /** Applied only when the consumer is first registered (idempotent). */
     initialTab?: AgentTab;
+    /**
+     * THE ARCHIVED-ITEMS LAW's per-consumer override of the catalog-wide
+     * `defaults.archiveFilter` knob. Applied only at first registration — the
+     * state belongs to the person after that.
+     */
+    initialArchFilter?: AgentArchFilter;
 }): 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`).
+ *
+ * 🚨 These are the numbers on the BADGES, and since 0.9.1 they count exactly
+ * the rows the tab renders under the consumer's own archive filter. A badge
+ * that counted rows the list hid was the screen telling the user something
+ * untrue about her own agents.
  */
 interface AgentListTabCounts {
     mine: number;
@@ -610,6 +654,13 @@ interface AgentListCoreOptions {
      * not just at mount — so a restriction that arrives later is enforced later.
      */
     visibleTabs?: readonly AgentTab[];
+    /**
+     * THE ARCHIVED-ITEMS LAW's per-consumer override of the catalog-wide
+     * `defaults.archiveFilter` knob, applied once at first registration. Almost
+     * nothing should pass it: the platform answer is "hide archived", and the
+     * person reveals the archive from the control on the filter bar.
+     */
+    initialArchFilter?: AgentArchFilter;
     /** Hide records that are invalid for this call site. */
     excludeAgentIds?: readonly string[];
     /**
@@ -635,8 +686,10 @@ declare const HOVER_GRACE_MS = 900;
  * 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): {
+declare function useAgentListCore({ consumerId, onSelect, navigateTo, activeAgentIdOverride, initialTab, includeSystemInAll, visibleTabs, initialArchFilter, excludeAgentIds, defaultMandateKey, }: AgentListCoreOptions): {
     agents: AgentSummary[];
+    archivedHiddenCount: number;
+    footerLabel: string;
     isLoading: boolean;
     activeAgentId: string | null;
     pinnedAgent: AgentSummary | null;
@@ -800,8 +853,16 @@ interface AgentListContentProps {
     defaultRow?: DefaultRowState | null | undefined;
     /** When true, scroll the list to the pinned row (top). */
     listOpen?: boolean | undefined;
+    /**
+     * Rows the ARCHIVE FILTER is currently keeping off this screen — from
+     * `useAgentListCore`. The footer names them (clause 2 of THE ARCHIVED-ITEMS
+     * LAW: a screen never implies the list is everything). 0 means "nothing
+     * archived is hidden behind this view", which is also what a host that
+     * mounts this component directly and passes nothing gets.
+     */
+    archivedHiddenCount?: number | undefined;
 }
-declare function AgentListContent({ agents, isLoading, consumer, activeAgentId, allCategories, allTags, inputRef, onSelectAgent, resolveAgentHref, onReset, activeFilterCount, isMobile, hoveredAgent, onAgentHover, onAgentHoverEnd, onDetailPress, onFilterChipClick, rightPanel, tabCounts, visibleTabs, systemTabLabel, pinnedAgent, defaultRow, listOpen, }: AgentListContentProps): react.JSX.Element;
+declare function AgentListContent({ agents, isLoading, consumer, activeAgentId, allCategories, allTags, inputRef, onSelectAgent, resolveAgentHref, onReset, activeFilterCount, isMobile, hoveredAgent, onAgentHover, onAgentHoverEnd, onDetailPress, onFilterChipClick, rightPanel, tabCounts, visibleTabs, systemTabLabel, pinnedAgent, defaultRow, listOpen, archivedHiddenCount, }: AgentListContentProps): react.JSX.Element;
 
 interface AgentFilterBarProps {
     consumer: UseAgentConsumerReturn;
@@ -818,6 +879,14 @@ interface AgentFilterBarProps {
  * 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`).
+ *
+ * 🚨 THE ARCHIVE CONTROL IS NOT OPTIONAL (0.9.2). It renders here, on every
+ * tab, for every consumer — including one whose `visibleTabs` removes the tab
+ * strip above it, since this bar is mounted unconditionally by
+ * `AgentListContent`. THE ARCHIVED-ITEMS LAW clause 3: revealing archived
+ * items is one or two clicks away, "on the surface itself — never zero
+ * (impossible) and never buried in another page". One click of this chip
+ * shows all; a second shows archived only; a third hides them again.
  */
 declare function AgentFilterBar({ consumer, allCategories, allTags, activeFilterCount, isMobile, rightPanel, onFilterChipClick, onReset, }: AgentFilterBarProps): react.JSX.Element;
 
@@ -892,7 +961,7 @@ declare const SearchInput: ({ ref, value, onChange, placeholder, }: {
     onChange: (v: string) => void;
     placeholder: string;
 }) => react.JSX.Element;
-declare function FilterChip({ icon: Icon, label, active, focused, onClick, }: {
+declare function FilterChip({ icon: Icon, label, active, focused, onClick, ariaLabel, testId, }: {
     icon: ComponentType<{
         className?: string;
     }>;
@@ -900,6 +969,10 @@ declare function FilterChip({ icon: Icon, label, active, focused, onClick, }: {
     active: boolean;
     focused?: boolean;
     onClick: () => void;
+    /** Accessible name when the visible label alone would not say the state. */
+    ariaLabel?: string;
+    /** Stable hook so a shell test can measure the control, not a class name. */
+    testId?: string;
 }): react.JSX.Element;
 declare function OptionRow({ label, selected, onClick, }: {
     label: string;

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

@@ -131,7 +131,25 @@ declare const SORT_OPTIONS: {
 type AgentTab = "mine" | "shared" | "all" | "system";
 /** Favorite filter. */
 type AgentFavFilter = "all" | "yes" | "no";
-/** Archive filter. */
+/**
+ * The archive filter — THE ARCHIVED-ITEMS LAW's ONE control, in this
+ * package's existing vocabulary.
+ *
+ * > "everything should have an archive filter, and the default should always
+ * > hide archived, but seeing archived items should be one or two clicks
+ * > away." — Arman, 2026-09-09 (`common-docs/policies/archived-items.md`)
+ *
+ * Three states and no more, identical for every entity on the platform:
+ *
+ * | value      | the platform's words | what the list shows      |
+ * |------------|----------------------|--------------------------|
+ * | `active`   | hide archived        | only un-archived rows    |
+ * | `both`     | show all             | every row                |
+ * | `archived` | archived only        | only archived rows       |
+ *
+ * `active` is the platform default, and it is a KNOB — see
+ * `AgentCatalogConfig.defaults.archiveFilter`.
+ */
 type AgentArchFilter = "active" | "archived" | "both";
 /**
  * Access level filter.
@@ -377,6 +395,14 @@ interface AgentCatalog {
     readonly notifier: AgentCatalogNotifier | undefined;
     /** True when this catalog was given a transport and can resolve mandates. */
     readonly canResolveMandates: boolean;
+    /**
+     * The consumer state a brand-new consumer starts from, AFTER the host's
+     * `defaults` knob is applied. Read it instead of
+     * `DEFAULT_AGENT_CONSUMER_STATE` whenever the question is "is this filter at
+     * its default?" — a host that legitimately defaults the archive filter to
+     * "show all" must not have every control render as though it were modified.
+     */
+    readonly consumerDefaults: AgentConsumerState;
     getState(): AgentCatalogState;
     subscribe(listener: () => void): () => void;
     getAgent(agentId: string): AgentSummary | undefined;
@@ -515,6 +541,13 @@ interface UseAgentConsumerReturn {
     includedTags: string[];
     favFilter: AgentFavFilter;
     archFilter: AgentArchFilter;
+    /**
+     * The archive-filter state this catalog starts consumers in — the platform
+     * default `"active"` unless the host set the knob. What "not the default
+     * state" means on this surface, so the control and the footer can both say
+     * it honestly.
+     */
+    archFilterDefault: AgentArchFilter;
     accessFilter: AgentAccessFilter;
     favoritesFirst: boolean;
     listPage: number;
@@ -561,12 +594,23 @@ declare function useAgentConsumer(consumerId: string, options?: {
     unregisterOnUnmount?: boolean;
     /** Applied only when the consumer is first registered (idempotent). */
     initialTab?: AgentTab;
+    /**
+     * THE ARCHIVED-ITEMS LAW's per-consumer override of the catalog-wide
+     * `defaults.archiveFilter` knob. Applied only at first registration — the
+     * state belongs to the person after that.
+     */
+    initialArchFilter?: AgentArchFilter;
 }): 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`).
+ *
+ * 🚨 These are the numbers on the BADGES, and since 0.9.1 they count exactly
+ * the rows the tab renders under the consumer's own archive filter. A badge
+ * that counted rows the list hid was the screen telling the user something
+ * untrue about her own agents.
  */
 interface AgentListTabCounts {
     mine: number;
@@ -610,6 +654,13 @@ interface AgentListCoreOptions {
      * not just at mount — so a restriction that arrives later is enforced later.
      */
     visibleTabs?: readonly AgentTab[];
+    /**
+     * THE ARCHIVED-ITEMS LAW's per-consumer override of the catalog-wide
+     * `defaults.archiveFilter` knob, applied once at first registration. Almost
+     * nothing should pass it: the platform answer is "hide archived", and the
+     * person reveals the archive from the control on the filter bar.
+     */
+    initialArchFilter?: AgentArchFilter;
     /** Hide records that are invalid for this call site. */
     excludeAgentIds?: readonly string[];
     /**
@@ -635,8 +686,10 @@ declare const HOVER_GRACE_MS = 900;
  * 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): {
+declare function useAgentListCore({ consumerId, onSelect, navigateTo, activeAgentIdOverride, initialTab, includeSystemInAll, visibleTabs, initialArchFilter, excludeAgentIds, defaultMandateKey, }: AgentListCoreOptions): {
     agents: AgentSummary[];
+    archivedHiddenCount: number;
+    footerLabel: string;
     isLoading: boolean;
     activeAgentId: string | null;
     pinnedAgent: AgentSummary | null;
@@ -800,8 +853,16 @@ interface AgentListContentProps {
     defaultRow?: DefaultRowState | null | undefined;
     /** When true, scroll the list to the pinned row (top). */
     listOpen?: boolean | undefined;
+    /**
+     * Rows the ARCHIVE FILTER is currently keeping off this screen — from
+     * `useAgentListCore`. The footer names them (clause 2 of THE ARCHIVED-ITEMS
+     * LAW: a screen never implies the list is everything). 0 means "nothing
+     * archived is hidden behind this view", which is also what a host that
+     * mounts this component directly and passes nothing gets.
+     */
+    archivedHiddenCount?: number | undefined;
 }
-declare function AgentListContent({ agents, isLoading, consumer, activeAgentId, allCategories, allTags, inputRef, onSelectAgent, resolveAgentHref, onReset, activeFilterCount, isMobile, hoveredAgent, onAgentHover, onAgentHoverEnd, onDetailPress, onFilterChipClick, rightPanel, tabCounts, visibleTabs, systemTabLabel, pinnedAgent, defaultRow, listOpen, }: AgentListContentProps): react.JSX.Element;
+declare function AgentListContent({ agents, isLoading, consumer, activeAgentId, allCategories, allTags, inputRef, onSelectAgent, resolveAgentHref, onReset, activeFilterCount, isMobile, hoveredAgent, onAgentHover, onAgentHoverEnd, onDetailPress, onFilterChipClick, rightPanel, tabCounts, visibleTabs, systemTabLabel, pinnedAgent, defaultRow, listOpen, archivedHiddenCount, }: AgentListContentProps): react.JSX.Element;
 
 interface AgentFilterBarProps {
     consumer: UseAgentConsumerReturn;
@@ -818,6 +879,14 @@ interface AgentFilterBarProps {
  * 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`).
+ *
+ * 🚨 THE ARCHIVE CONTROL IS NOT OPTIONAL (0.9.2). It renders here, on every
+ * tab, for every consumer — including one whose `visibleTabs` removes the tab
+ * strip above it, since this bar is mounted unconditionally by
+ * `AgentListContent`. THE ARCHIVED-ITEMS LAW clause 3: revealing archived
+ * items is one or two clicks away, "on the surface itself — never zero
+ * (impossible) and never buried in another page". One click of this chip
+ * shows all; a second shows archived only; a third hides them again.
  */
 declare function AgentFilterBar({ consumer, allCategories, allTags, activeFilterCount, isMobile, rightPanel, onFilterChipClick, onReset, }: AgentFilterBarProps): react.JSX.Element;
 
@@ -892,7 +961,7 @@ declare const SearchInput: ({ ref, value, onChange, placeholder, }: {
     onChange: (v: string) => void;
     placeholder: string;
 }) => react.JSX.Element;
-declare function FilterChip({ icon: Icon, label, active, focused, onClick, }: {
+declare function FilterChip({ icon: Icon, label, active, focused, onClick, ariaLabel, testId, }: {
     icon: ComponentType<{
         className?: string;
     }>;
@@ -900,6 +969,10 @@ declare function FilterChip({ icon: Icon, label, active, focused, onClick, }: {
     active: boolean;
     focused?: boolean;
     onClick: () => void;
+    /** Accessible name when the visible label alone would not say the state. */
+    ariaLabel?: string;
+    /** Stable hook so a shell test can measure the control, not a class name. */
+    testId?: string;
 }): react.JSX.Element;
 declare function OptionRow({ label, selected, onClick, }: {
     label: string;