The A2A filter control provides a multi-dimension Popover-triggered filter panel for narrowing down agent-to-agent conversations by Agent, Task, Status, and Date range. It replaces the previous free-text search + status toggle and applies different filter rules to the Switchboard (org-chart pairs) and Conversation List (message feeds) views per the design spec's per-view rules.
**Key principle:** The same filter state manages both views, but which dimensions apply depends on the active view—Switchboard pairs only narrow by Agent (since they may have no conversation), while the Conversation List applies all four dimensions.
-`filters` — The current filter state (see `A2AFilters` below).
-`onFiltersChange` — Callback fired on any filter change; receives the entire updated filter object.
-`agentOptions` — Distinct agent slugs to display in the Agent checkbox list, already deduped and sorted. Derive this via `distinctA2AAgents(conversations, pairs)` in the parent component.
-`view` — The active view mode. When `"switchboard"`, an inline note reminds that Task/Status/Date only apply to the List view.
**Rendered output:**
- **Collapsed (no filters):** A compact trigger button labeled `Filters` with a funnel icon.
- **With active filters:** The trigger shows a count badge (`Filters · N`).
- **Expanded:** A `Popover` displaying all four filter dimensions stacked vertically, plus an inline note if in Switchboard view.
- **Chip row:** Below the header, a wrapping row of `Badge` chips—one per active filter value—with individual remove `X` buttons and a shared `Clear all` button. Only rendered when >=1 filter is active.
**Empty state:**`EMPTY_A2A_FILTERS` = all fields empty or falsy.
## Filter Dimensions
Each dimension narrows the loaded conversations or pairs via a pure matcher function in `a2a-filter-utils.ts`.
### 1. Agent (applies to both views)
- **Source:** `agent_a` and `agent_b` fields on `AdminConversationSummary` / `AdminPairSummary`.
- **Match logic:** A conversation/pair matches if **either** participant is in the selected `agents` array.
- **Widget:** Checkbox list in the Popover, with a `Clear` button when >=1 agent is selected.
- **Empty behavior:** If `agents.length === 0`, all items pass (no agent filter applied).
```typescript
// Example: agents = ["be-dev-1"]
// Match: conversation with agent_a="be-dev-1" agent_b="be-qa" ✓
// Match: conversation with agent_a="ux-dev-1" agent_b="be-dev-1" ✓
// No match: conversation with agent_a="ux-dev-1" agent_b="ux-qa" ✗
```
**Switchboard only:** Pairs are narrowed by Agent alone (design doc §1 "Per-view applicability").
### 2. Task (List view only)
Combines two controls for maximum flexibility:
- **Task ID fragment input:** Free-text match against the full `task_id` (case-insensitive). Displayed as a single chip labeled `Task: <fragment>` when set.
- **"No linked task" toggle:** Matches conversations with `task_id === null`. Displayed as a separate chip when active.
**Match logic:**
```
IF (fragment is empty AND noLinkedTask is false)
PASS (no task filter)
ELSE
PASS if (fragment matches task_id) OR (noLinkedTask is true AND task_id is null)
```
In other words: **if both controls are empty, no filtering; if one or both are set, match conversations that satisfy either condition (OR logic).**
```typescript
// Example 1: taskIdFragment="abcdef", noLinkedTask=false
// Match: task_id="abcdef01-0000-..." ✓
// No match: task_id="ffffffff-0000-..." ✗
// No match: task_id=null ✗
// Example 2: taskIdFragment="", noLinkedTask=true
// No match: task_id="abcdef01-0000-..." ✗
// Match: task_id=null ✓
// Example 3: taskIdFragment="abcdef", noLinkedTask=true
// Match: task_id="abcdef01-0000-..." ✓
// No match: task_id="ffffffff-0000-..." ✗
// Match: task_id=null ✓
```
**Switchboard:** This dimension does not apply (pairs may have no conversation to check a task against).
### 3. Status (List view only)
- **Source:** `status` field on `AdminConversationSummary` (values: `"active"` | `"archived"`).
- **Widget:** Two toggle buttons (Active / Archived) with `aria-pressed`.
- **Match logic:** A conversation matches if its `status` is in the selected `statuses` array.
- **Empty behavior:** If `statuses.length === 0`, all items pass (no status filter applied).
```typescript
// Example: statuses = ["active"]
// Match: conversation with status="active" ✓
// No match: conversation with status="archived" ✗
```
**Switchboard:** This dimension does not apply.
### 4. Date range (List view only)
- **Source:** `last_message_at` field on `AdminConversationSummary`, falling back to `created_at` if null (same fallback the list already uses for display).
- **Widget:** Two native `<input type="date">` fields (From / To), in the viewer's local timezone.
- **Match logic:** Both dates are compared at day granularity. A conversation matches if:
```
IF (dateFrom is empty AND dateTo is empty)
PASS (no date filter)
ELSE IF (timestamp is null/empty)
FAIL
ELSE
PASS if (timestamp >= dateFrom) AND (timestamp <= dateTo)
```
- **Rendered chips:** One chip per set date (`From <date>` / `To <date>`), independently removable.
**`filterConversations(conversations, filters): AdminConversationSummary[]`** Applies all four dimensions (Agent, Task, Status, Date) to narrow the conversation list.
**`distinctA2AAgents(conversations, pairs): string[]`** Derives the checkbox option set by scanning all loaded pairs and conversations, deduping agent slugs, and sorting alphabetically. Call this in a `useMemo` in the parent whenever pairs/conversations change.
**`activeA2AFilterCount(filters): number`** Returns the count of active filter values (one per chip). Drives the trigger's count badge. An empty fragment/date counts as 0; a set date counts as 1 per date.
| Task | ✗ (N/A—pairs may have no conversation) | ✓ |
| Status | ✗ | ✓ |
| Date | ✗ | ✓ |
**Switchboard hint:** When the view is `"switchboard"`, the Popover displays an inline note: *"Task, Status, and Date filters apply to the Conversation List view."* This prepares the user if they set those filters before switching to List.
## Design Notes
### Client-Side Filtering
**Important limitation:** Filtering currently runs client-side over the already-fetched page of conversations/pairs (capped at `limit=100` from the backend). There are **no backend query params** for these dimensions yet.
**Implication:** If the loaded data doesn't contain a matching item, the filter won't find it. This is acceptable for the current conversation volume and is explicitly noted in the design spec as "Future work."
**Future task:** A later PR will add backend query params (`agent`, `task_id`, `status`, `from`, `to`) to `GET /a2a/chat/admin/conversations` so filtering can work server-side without this limitation.
### Persistence
Filter state is **local to the page component** (`useState`), not persisted to localStorage or the URL. Reloading the page resets filters to empty. This is intentional and consistent with the page's existing behavior (no search persistence today).
### Debouncing
The Task ID fragment input does **not** debounce; it updates the filter state on every keystroke. For a small dataset (100 conversations) this is fine. If performance becomes an issue with larger datasets, add a 300ms debounce in the parent using `useCallback` + `useRef` on the `onFiltersChange` callback.
**Q: Why doesn't the fragment search the topic field anymore?** A: The design spec replaced free-text search with four discrete dimensions. Task ID fragment and Agent are the most common filters; if you need to search topics, that would be a fifth dimension—raise it in design review if needed.
**Q: Can I make filters persist across page reloads?** A: Not in this version. To add localStorage persistence, wrap `setFilters` in the parent with `useEffect` to sync to localStorage and restore on mount. This would be a follow-up task.
**Q: What happens to filtered state when new conversations arrive via WebSocket?** A: Filters remain active. The `filterConversations` function is re-run against the refreshed list on every data update, so incoming messages are immediately re-evaluated against the current filters.
**Q: Can filters be set via URL query params?** A: Not currently. The state is ephemeral. To support deep-linking (e.g., `?agents=be-dev-1&status=active`), add a URL param sync layer in the parent using `useSearchParams` / `useRouter` from Next.js. This would be a follow-up task.
