@ai-matrx/agents 0.9.1 → 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,6 +594,12 @@ 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;
 
 /**
@@ -615,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[];
     /**
@@ -640,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;
@@ -805,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;
@@ -823,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;
 
@@ -897,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;
     }>;
@@ -905,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,6 +594,12 @@ 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;
 
 /**
@@ -615,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[];
     /**
@@ -640,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;
@@ -805,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;
@@ -823,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;
 
@@ -897,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;
     }>;
@@ -905,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.js

@@ -117,53 +117,27 @@ function AgentCatalogProvider({
 
 // catalog/shared/useAgentConsumer.ts
 import { useCallback as useCallback2, useEffect, useRef, useState } from "react";
-
-// catalog/types.ts
-function isMandateAgentId(id) {
-  return id.startsWith("mandate:");
-}
-var SORT_OPTIONS = [
-  { value: "updated-desc", label: "Recent" },
-  { value: "created-desc", label: "Created" },
-  { value: "name-asc", label: "A \u2192 Z" },
-  { value: "name-desc", label: "Z \u2192 A" },
-  { value: "category-asc", label: "Category" }
-];
-var AGENT_NONE_SENTINEL = "__none__";
-var DEFAULT_AGENT_CONSUMER_STATE = {
-  tab: "mine",
-  sortBy: "updated-desc",
-  searchTerm: "",
-  includedCats: [],
-  includedTags: [],
-  favFilter: "all",
-  archFilter: "active",
-  accessFilter: "any",
-  favoritesFirst: true,
-  listPage: 1,
-  sharedPage: 1,
-  serverMatchedIds: [],
-  isServerSearching: false,
-  deepSearch: false
-};
-
-// catalog/shared/useAgentConsumer.ts
 var DEBOUNCE_MS = 250;
 var MIN_QUERY_LENGTH = 2;
 function useAgentConsumer(consumerId, options) {
   const catalog = useAgentCatalog();
+  const defaults = catalog.consumerDefaults;
   const selectConsumer = useCallback2(
-    (state) => state.consumers[consumerId] ?? DEFAULT_AGENT_CONSUMER_STATE,
-    [consumerId]
+    (state) => state.consumers[consumerId] ?? defaults,
+    [consumerId, defaults]
   );
   const consumer = useAgentCatalogState(selectConsumer);
   const optionsRef = useRef(options);
   optionsRef.current = options;
   useEffect(() => {
     const opts = optionsRef.current;
+    const initial = {
+      ...opts?.initialTab ? { tab: opts.initialTab } : {},
+      ...opts?.initialArchFilter ? { archFilter: opts.initialArchFilter } : {}
+    };
     catalog.registerConsumer(
       consumerId,
-      opts?.initialTab ? { tab: opts.initialTab } : void 0
+      Object.keys(initial).length > 0 ? initial : void 0
     );
     return () => {
       if (optionsRef.current?.unregisterOnUnmount) {
@@ -286,7 +260,10 @@ function useAgentConsumer(consumerId, options) {
       isSearching
     });
   }, [consumerId, catalog, matchedIds, isSearching]);
-  const hasActiveFilters = consumer.searchTerm !== "" || consumer.includedCats.length > 0 || consumer.includedTags.length > 0 || consumer.favFilter !== "all" || consumer.archFilter !== "active" || consumer.accessFilter !== "any" || !consumer.favoritesFirst;
+  const hasActiveFilters = consumer.searchTerm !== "" || consumer.includedCats.length > 0 || consumer.includedTags.length > 0 || consumer.favFilter !== "all" || // The archive filter is compared to THIS CATALOG'S default, not to the
+  // hardcoded platform one: a host that legitimately defaults to "show all"
+  // must not have the reset control permanently lit.
+  consumer.archFilter !== defaults.archFilter || consumer.accessFilter !== "any" || !consumer.favoritesFirst;
   return {
     tab: consumer.tab,
     sortBy: consumer.sortBy,
@@ -295,6 +272,7 @@ function useAgentConsumer(consumerId, options) {
     includedTags: consumer.includedTags,
     favFilter: consumer.favFilter,
     archFilter: consumer.archFilter,
+    archFilterDefault: defaults.archFilter,
     accessFilter: consumer.accessFilter,
     favoritesFirst: consumer.favoritesFirst,
     listPage: consumer.listPage,
@@ -330,6 +308,34 @@ import {
   useState as useState2
 } from "react";
 
+// catalog/types.ts
+function isMandateAgentId(id) {
+  return id.startsWith("mandate:");
+}
+var SORT_OPTIONS = [
+  { value: "updated-desc", label: "Recent" },
+  { value: "created-desc", label: "Created" },
+  { value: "name-asc", label: "A \u2192 Z" },
+  { value: "name-desc", label: "Z \u2192 A" },
+  { value: "category-asc", label: "Category" }
+];
+var ARCHIVE_FILTER_ORDER = [
+  "active",
+  "both",
+  "archived"
+];
+var ARCHIVE_FILTER_OPTIONS = [
+  { value: "active", label: "Hide archived", chip: "Archive" },
+  { value: "both", label: "Show all", chip: "All + archived" },
+  { value: "archived", label: "Archived only", chip: "Archived only" }
+];
+function nextArchFilter(current) {
+  const index = ARCHIVE_FILTER_ORDER.indexOf(current);
+  if (index < 0) return ARCHIVE_FILTER_ORDER[0];
+  return ARCHIVE_FILTER_ORDER[(index + 1) % ARCHIVE_FILTER_ORDER.length];
+}
+var AGENT_NONE_SENTINEL = "__none__";
+
 // catalog/labels.ts
 function agentListEmptyLabel(tab, labels) {
   switch (tab) {
@@ -346,6 +352,26 @@ function shouldDefaultAgentListToPublicTab(args) {
   if (!args.agentsLoaded) return false;
   return args.ownedCount === 0;
 }
+function agentArchiveFilterChipLabel(archFilter) {
+  return ARCHIVE_FILTER_OPTIONS.find((o) => o.value === archFilter)?.chip ?? "Archive";
+}
+function agentArchiveFilterStateLabel(archFilter) {
+  return ARCHIVE_FILTER_OPTIONS.find((o) => o.value === archFilter)?.label ?? "Hide archived";
+}
+function agentArchiveFilterControlLabel(archFilter) {
+  return `Archive filter: ${agentArchiveFilterStateLabel(
+    archFilter
+  ).toLowerCase()}. Click for ${agentArchiveFilterStateLabel(
+    nextArchFilter(archFilter)
+  ).toLowerCase()}`;
+}
+function agentListFooterLabel(args) {
+  const { count, archFilter, archivedHiddenCount } = args;
+  if (archFilter === "archived") return `${count} archived shown`;
+  const base = `${count} agent${count !== 1 ? "s" : ""}`;
+  if (archFilter === "both") return `${base} \xB7 archived shown`;
+  return archivedHiddenCount > 0 ? `${base} \xB7 ${archivedHiddenCount} archived hidden` : base;
+}
 
 // catalog/score.ts
 function computeAgentSearchScore(agent, query) {
@@ -536,8 +562,7 @@ function filterUserTypeAgents(agents, consumer) {
     if (tab === "mine" && agent.isOwner !== true) return false;
     if (tab === "shared" && !(agent.isOwner === false && agent.accessLevel != null))
       return false;
-    if (archFilter === "active" && agent.isArchived) return false;
-    if (archFilter === "archived" && !agent.isArchived) return false;
+    if (!agentMatchesArchiveFilter(agent, archFilter)) return false;
     if (favFilter === "yes" && !agent.isFavorite) return false;
     if (favFilter === "no" && agent.isFavorite) return false;
     if (accessFilter === "owned" && agent.isOwner !== true) return false;
@@ -567,9 +592,10 @@ function filterUserTypeAgents(agents, consumer) {
   return sortFilteredAgents(filtered, consumer);
 }
 function filterBuiltinTypeAgents(agents, consumer) {
-  const { searchTerm, favFilter, includedCats, includedTags } = consumer;
+  const { searchTerm, favFilter, archFilter, includedCats, includedTags } = consumer;
   const serverMatched = new Set(consumer.serverMatchedIds);
   const filtered = agents.filter((agent) => {
+    if (!agentMatchesArchiveFilter(agent, archFilter)) return false;
     if (favFilter === "yes" && !agent.isFavorite) return false;
     if (favFilter === "no" && agent.isFavorite) return false;
     if (includedCats.length > 0) {
@@ -615,6 +641,15 @@ function agentMatchesArchiveFilter(agent, archFilter) {
   if (archFilter === "archived") return Boolean(agent.isArchived);
   return true;
 }
+function countBuiltinRows(agents, archFilter) {
+  let n = 0;
+  for (const a of agents) {
+    if (a.agentType !== "builtin") continue;
+    if (!agentMatchesArchiveFilter(a, archFilter)) continue;
+    n += 1;
+  }
+  return n;
+}
 function countUserRows(agents, archFilter, predicate) {
   let n = 0;
   for (const a of agents) {
@@ -633,7 +668,7 @@ var selectAgentTabCounts = memoize2(
     mine: countUserRows(agents, archFilter, isOwned),
     shared: countUserRows(agents, archFilter, isShared),
     all: countUserRows(agents, archFilter, isAny),
-    system: selectBuiltinTypeAgents(agents).length
+    system: countBuiltinRows(agents, archFilter)
   })
 );
 var selectTotalUserAgentsCount = memoize1(
@@ -646,7 +681,7 @@ var selectTotalSharedAgentsCount = memoize1(
   (agents) => countUserRows(agents, "active", isShared)
 );
 var selectTotalBuiltinAgentsCount = memoize1(
-  (agents) => selectBuiltinTypeAgents(agents).length
+  (agents) => countBuiltinRows(agents, "active")
 );
 var selectTotalFavoriteAgentsCount = memoize1(
   (agents) => countUserRows(agents, "active", isFavorite)
@@ -668,6 +703,7 @@ function useAgentListCore({
   initialTab,
   includeSystemInAll = false,
   visibleTabs,
+  initialArchFilter,
   excludeAgentIds = EMPTY_EXCLUDES,
   defaultMandateKey
 }) {
@@ -677,7 +713,10 @@ function useAgentListCore({
   const [hoveredAgent, setHoveredAgent] = useState2(null);
   const hoverLeaveTimerRef = useRef2(null);
   const defaultTabAppliedRef = useRef2(false);
-  const consumer = useAgentConsumer(consumerId, { unregisterOnUnmount: true });
+  const consumer = useAgentConsumer(consumerId, {
+    unregisterOnUnmount: true,
+    ...initialArchFilter ? { initialArchFilter } : {}
+  });
   const rows = useAgentCatalogRows();
   const userId = catalog.getUserIdOrNull();
   const tabCountsForFilter = selectAgentTabCounts(rows, consumer.state.archFilter);
@@ -691,7 +730,20 @@ function useAgentListCore({
     () => new Set(excludeAgentIds),
     [excludeAgentIds]
   );
-  const agents = excludedAgentIds.size === 0 ? filteredAgents : filteredAgents.filter((agent) => !excludedAgentIds.has(agent.id));
+  const applyExcludes = useCallback3(
+    (list) => excludedAgentIds.size === 0 ? list : list.filter((agent) => !excludedAgentIds.has(agent.id)),
+    [excludedAgentIds]
+  );
+  const agents = applyExcludes(filteredAgents);
+  const selectArchivedProbe = useMemo3(
+    () => makeSelectFilteredAgents(includeSystemInAll),
+    [includeSystemInAll]
+  );
+  const archiveProbeState = useMemo3(
+    () => ({ ...consumer.state, archFilter: "archived" }),
+    [consumer.state]
+  );
+  const archivedHiddenCount = consumer.archFilter === "active" ? applyExcludes(selectArchivedProbe(rows, archiveProbeState)).length : 0;
   const status = useAgentCatalogState(selectStatus);
   const activeAgentId = activeAgentIdOverride ?? null;
   const pinnedAgent = activeAgentId ? catalog.getAgent(activeAgentId) : void 0;
@@ -778,7 +830,9 @@ function useAgentListCore({
     },
     [onSelect, navigateTo, navigate, catalog, consumerId]
   );
-  const activeFilterCount = (consumer.sortBy !== "updated-desc" ? 1 : 0) + (consumer.includedCats.length > 0 ? 1 : 0) + (consumer.includedTags.length > 0 ? 1 : 0) + (consumer.favFilter !== "all" ? 1 : 0);
+  const activeFilterCount = (consumer.sortBy !== "updated-desc" ? 1 : 0) + (consumer.includedCats.length > 0 ? 1 : 0) + (consumer.includedTags.length > 0 ? 1 : 0) + (consumer.favFilter !== "all" ? 1 : 0) + // The archive filter counts like every other filter, so a list showing
+  // archived rows offers the reset control that puts them away again.
+  (consumer.archFilter !== consumer.archFilterDefault ? 1 : 0);
   const handleAgentHover = useCallback3(
     (agent, panelOpen) => {
       if (panelOpen) return;
@@ -819,8 +873,15 @@ function useAgentListCore({
     },
     []
   );
+  const footerLabel = agentListFooterLabel({
+    count: agents.length,
+    archFilter: consumer.archFilter,
+    archivedHiddenCount
+  });
   return {
     agents,
+    archivedHiddenCount,
+    footerLabel,
     isLoading,
     activeAgentId,
     pinnedAgent: pinnedAgent ?? null,
@@ -950,6 +1011,18 @@ var SHAPES = {
       "M12 15v5s3.03-.55 4-2c1.08-1.62 0-5 0-5"
     ]
   },
+  /**
+   * THE ARCHIVE GLYPH (Lucide `archive`) — the ONE mark of the platform
+   * archive filter, drawn identically in every Matrx client so the control a
+   * person learns on one surface is recognisable on all of them.
+   */
+  archive: {
+    paths: [
+      "M3 3h18a1 1 0 0 1 1 1v3a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1z",
+      "M4 8v11a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8",
+      "M10 12h4"
+    ]
+  },
   circleCheck: {
     paths: ["m9 12 2 2 4-4"],
     circles: [{ cx: 12, cy: 12, r: 10 }]
@@ -1020,6 +1093,7 @@ var ArrowUpDownIcon = makeIcon("arrowUpDown");
 var FolderIcon = makeIcon("folder");
 var TagIcon = makeIcon("tag");
 var RotateCcwIcon = makeIcon("rotateCcw");
+var ArchiveIcon = makeIcon("archive");
 var LoaderIcon = makeIcon("loader");
 var UsersIcon = makeIcon("users");
 var ClockIcon = makeIcon("clock");
@@ -1077,13 +1151,17 @@ function FilterChip({
   label,
   active,
   focused,
-  onClick
+  onClick,
+  ariaLabel,
+  testId
 }) {
   return /* @__PURE__ */ jsxs2(
     "button",
     {
       type: "button",
       onClick,
+      ...ariaLabel ? { "aria-label": ariaLabel } : {},
+      ...testId ? { "data-testid": testId } : {},
       className: cn(
         "inline-flex items-center gap-1 h-6 px-1.5 rounded text-[11px] font-medium shrink-0 transition-colors",
         focused ? "bg-primary/15 text-primary border border-primary/30 ring-1 ring-primary/20" : active ? "bg-primary/10 text-primary border border-primary/20" : "text-muted-foreground hover:text-foreground hover:bg-muted/50 border border-transparent"
@@ -1506,6 +1584,17 @@ function AgentFilterBar({
         }
       }
     ),
+    /* @__PURE__ */ jsx8(
+      FilterChip,
+      {
+        icon: ArchiveIcon,
+        label: agentArchiveFilterChipLabel(consumer.archFilter),
+        active: consumer.archFilter !== consumer.archFilterDefault,
+        ariaLabel: agentArchiveFilterControlLabel(consumer.archFilter),
+        testId: "agent-archive-filter",
+        onClick: () => consumer.setArchFilter(nextArchFilter(consumer.archFilter))
+      }
+    ),
     allCategories.length > 0 && /* @__PURE__ */ jsx8(
       FilterChip,
       {
@@ -1705,7 +1794,8 @@ function AgentListContent({
   systemTabLabel,
   pinnedAgent = null,
   defaultRow = null,
-  listOpen = false
+  listOpen = false,
+  archivedHiddenCount = 0
 }) {
   const catalog = useAgentCatalog();
   const listScrollRef = useRef3(null);
@@ -1843,11 +1933,18 @@ function AgentListContent({
     ] }) }),
     /* @__PURE__ */ jsx11("div", { className: "h-px bg-border shrink-0" }),
     /* @__PURE__ */ jsxs8("div", { className: "flex items-center justify-between px-2.5 py-1.5 shrink-0", children: [
-      /* @__PURE__ */ jsxs8("span", { className: "text-[10px] text-muted-foreground tabular-nums", children: [
-        agents.length,
-        " agent",
-        agents.length !== 1 ? "s" : ""
-      ] }),
+      /* @__PURE__ */ jsx11(
+        "span",
+        {
+          "data-testid": "agent-list-footer",
+          className: "text-[10px] text-muted-foreground tabular-nums",
+          children: agentListFooterLabel({
+            count: agents.length,
+            archFilter: consumer.archFilter,
+            archivedHiddenCount
+          })
+        }
+      ),
       consumer.searchTerm && /* @__PURE__ */ jsx11(
         "button",
         {
@@ -2070,6 +2167,7 @@ function AgentListDropdown({
   const inputRef = useRef4(null);
   const {
     agents,
+    archivedHiddenCount,
     isLoading,
     activeAgentId,
     pinnedAgent,
@@ -2205,6 +2303,7 @@ function AgentListDropdown({
       onFilterChipClick: handleFilterChipClick,
       rightPanel,
       tabCounts,
+      archivedHiddenCount,
       ...visibleTabs ? { visibleTabs } : {},
       ...systemTabLabel ?? (includeSystemInAll ? "System" : void 0) ? {
         systemTabLabel: systemTabLabel ?? (includeSystemInAll ? "System" : void 0)
@@ -2361,6 +2460,7 @@ function AgentListInlinePicker({
   const [mobileSubView, setMobileSubView] = useState4(null);
   const {
     agents,
+    archivedHiddenCount,
     isLoading,
     allCategories,
     allTags,
@@ -2467,6 +2567,7 @@ function AgentListInlinePicker({
       onFilterChipClick: handleFilterChipClick,
       rightPanel: null,
       tabCounts,
+      archivedHiddenCount,
       ...visibleTabs ? { visibleTabs } : {},
       ...systemTabLabel ?? (includeSystemInAll ? "System" : void 0) ? {
         systemTabLabel: systemTabLabel ?? (includeSystemInAll ? "System" : void 0)