478a7f18e9
14 files in docs/wireframes/v2/ addressing 13 UX gaps from v1: - Theme spec with indigo brand, status tokens, terminal/diff tokens, dark mode, Geist typography, 6px radius, layered shadows - Wireframes for all pages with loading/error/empty states - Shared component specs (SaveIndicator, EmptyState, ErrorState, CommandPalette, ThemeToggle)
290 lines
13 KiB
Markdown
290 lines
13 KiB
Markdown
# Agents Page (v2)
|
|
|
|
### Route: `/agents`
|
|
### Source: `packages/web/src/routes/agents.tsx`
|
|
|
|
---
|
|
|
|
## v1 -> v2 Changes
|
|
|
|
| Aspect | v1 | v2 |
|
|
|--------|----|----|
|
|
| Provider filter | None | Dropdown: All / Claude / Codex / Gemini / etc. |
|
|
| Mode filter | None | Dropdown: All / discuss / plan / detail / execute / verify / etc. |
|
|
| Search | None | Text input filtering agent name |
|
|
| Agent card context | Name + status + provider + mode + time only | Added context row: "Task: ..." or "Initiative: ..." with link |
|
|
| Loading state | 5 skeleton cards (basic) | 5 skeleton cards with shimmer animation |
|
|
| Error state | AlertCircle + retry (exists) | Same (unchanged) |
|
|
| Empty (filtered) | "No agents match this filter" | "No matching agents" + `[Clear filters]` link |
|
|
| Empty (zero agents) | None | Centered empty state with description |
|
|
|
|
---
|
|
|
|
## Default State (with agents)
|
|
|
|
```
|
|
+=============================================================================+
|
|
| [CW] Initiatives [*Agents*] *3 Inbox (2) Settings [cmd-k] [sun] * |
|
|
+=============================================================================+
|
|
| |
|
|
| Agents (7) [ Refresh ] |
|
|
| [search___________] [All providers v] [All modes v] |
|
|
| |
|
|
| Agent List 320px | Agent Output |
|
|
| -------------------------+-------------------------------------------------|
|
|
| +----------------------+ | |
|
|
| | * blue-fox-7 [...] | | Session 1 |
|
|
| | claude . execute | | > Analyzing codebase structure... |
|
|
| | Task: PKCE flow | | > Found 12 files matching pattern |
|
|
| | 2m ago | | > Creating src/auth/pkce.ts |
|
|
| +----------------------+ | > Writing test file... |
|
|
| | |
|
|
| +----------------------+ | |
|
|
| | - red-elk-3 [...] | | |
|
|
| | claude . plan | | |
|
|
| | Init: Auth Overhaul | | |
|
|
| | 1h ago | | |
|
|
| +----------------------+ | |
|
|
| | |
|
|
| +----------------------+ | |
|
|
| | ? green-bear-1 [...] | | |
|
|
| | codex . detail | | |
|
|
| | Task: DB schema | | |
|
|
| | 5m ago | | |
|
|
| +----------------------+ | |
|
|
+=============================================================================+
|
|
```
|
|
|
|
---
|
|
|
|
## Search + Filter Controls
|
|
|
|
```
|
|
[search___________] [All providers v] [All modes v]
|
|
```
|
|
|
|
### Search input
|
|
- Placeholder: "Search agents..."
|
|
- Client-side filter on `agent.name` (case-insensitive substring match)
|
|
- Debounced 150ms
|
|
- Clear button `[x]` appears when non-empty
|
|
|
|
### Provider filter dropdown `[All providers v]`
|
|
|
|
```
|
|
[All providers v]
|
|
+-----------------+
|
|
| All |
|
|
| claude |
|
|
| codex |
|
|
| gemini |
|
|
| ... |
|
|
+-----------------+
|
|
```
|
|
|
|
Populated dynamically from `listProviderNames` tRPC query. Only shows providers
|
|
that have at least one registered account.
|
|
|
|
### Mode filter dropdown `[All modes v]`
|
|
|
|
```
|
|
[All modes v]
|
|
+-----------------+
|
|
| All |
|
|
| discuss |
|
|
| plan |
|
|
| detail |
|
|
| execute |
|
|
| verify |
|
|
| refine |
|
|
| research |
|
|
| merge |
|
|
| review |
|
|
+-----------------+
|
|
```
|
|
|
|
Static list of all task category values.
|
|
|
|
---
|
|
|
|
## Agent Card Anatomy (v2)
|
|
|
|
### Running agent with task context
|
|
|
|
```
|
|
+------------------------------+
|
|
| * blue-fox-7 [...] |
|
|
| claude . execute |
|
|
| Task: PKCE flow | <-- clickable link to task/initiative
|
|
| 2m ago |
|
|
+------------------------------+
|
|
```
|
|
|
|
### Running agent with initiative context (no specific task)
|
|
|
|
```
|
|
+------------------------------+
|
|
| * blue-fox-7 [...] |
|
|
| claude . plan |
|
|
| Init: Auth Overhaul | <-- clickable link to initiative
|
|
| 2m ago |
|
|
+------------------------------+
|
|
```
|
|
|
|
### Waiting for input
|
|
|
|
```
|
|
+------------------------------+
|
|
| ? green-bear-1 [...] |
|
|
| codex . detail |
|
|
| Task: DB schema |
|
|
| 5m ago |
|
|
| Answer questions -> | <-- link to /inbox
|
|
+------------------------------+
|
|
```
|
|
|
|
### Exited
|
|
|
|
```
|
|
+------------------------------+
|
|
| - red-elk-3 [...] |
|
|
| claude . plan |
|
|
| Init: Auth Overhaul |
|
|
| 1h ago |
|
|
+------------------------------+
|
|
```
|
|
|
|
### Context row rules
|
|
- If agent has a `taskId`: show "Task: <task name>" linking to the initiative detail (Execution tab)
|
|
- Else if agent has an `initiativeId`: show "Init: <initiative name>" linking to the initiative detail
|
|
- Else: omit the context row entirely
|
|
- Context text: `text-xs text-muted-foreground`, clickable portion gets `hover:underline cursor-pointer`
|
|
|
|
### Status dot legend
|
|
- `*` green/active = `running`
|
|
- `?` orange/waiting = `waiting_for_input`
|
|
- `-` grey/exited = `stopped`, `crashed`, `idle`, `completed`
|
|
|
|
---
|
|
|
|
## Loading State (5 skeleton cards with shimmer)
|
|
|
|
```
|
|
+=============================================================================+
|
|
| |
|
|
| Agents [ Refresh ] |
|
|
| [search___________] [All providers v] [All modes v] |
|
|
| |
|
|
| Agent List 320px | Agent Output |
|
|
| -------------------------+-------------------------------------------------|
|
|
| +----------------------+ | |
|
|
| | [.] ░░░░░░░░░░░░ | | |
|
|
| | ░░░░░ . ░░░░░░ | | |
|
|
| | ░░░░░░░░░░░░░ | | |
|
|
| +----------------------+ | Select an agent |
|
|
| +----------------------+ | to view output |
|
|
| | [.] ░░░░░░░░░░░░ | | |
|
|
| | ░░░░░ . ░░░░░░ | | |
|
|
| | ░░░░░░░░░░░░░ | | |
|
|
| +----------------------+ | |
|
|
| +----------------------+ | |
|
|
| | [.] ░░░░░░░░░░░░ | | |
|
|
| | ░░░░░ . ░░░░░░ | | |
|
|
| | ░░░░░░░░░░░░░ | | |
|
|
| +----------------------+ | |
|
|
| +----------------------+ | |
|
|
| | [.] ░░░░░░░░░░░░ | | |
|
|
| | ░░░░░ . ░░░░░░ | | |
|
|
| | ░░░░░░░░░░░░░ | | |
|
|
| +----------------------+ | |
|
|
| +----------------------+ | |
|
|
| | [.] ░░░░░░░░░░░░ | | |
|
|
| | ░░░░░ . ░░░░░░ | | |
|
|
| | ░░░░░░░░░░░░░ | | |
|
|
| +----------------------+ | |
|
|
+=============================================================================+
|
|
```
|
|
|
|
Skeleton cards mirror card anatomy: status dot placeholder, name line, provider/mode line,
|
|
context line. Shimmer animation sweeps left-to-right on a 1.5s loop.
|
|
|
|
---
|
|
|
|
## Error State
|
|
|
|
```
|
|
+=============================================================================+
|
|
| |
|
|
| Agents [ Refresh ] |
|
|
| |
|
|
| |
|
|
| [AlertCircle] |
|
|
| Failed to load agents |
|
|
| |
|
|
| [ Retry ] |
|
|
| |
|
|
+=============================================================================+
|
|
```
|
|
|
|
- `[AlertCircle]` icon: `h-8 w-8 text-destructive`
|
|
- Error message: `text-sm text-destructive`
|
|
- `[ Retry ]` button: `variant="outline" size="sm"`, calls `agentsQuery.refetch()`
|
|
|
|
---
|
|
|
|
## Empty State -- No Agents
|
|
|
|
```
|
|
+=============================================================================+
|
|
| |
|
|
| Agents [ Refresh ] |
|
|
| [search___________] [All providers v] [All modes v] |
|
|
| |
|
|
| +-----------------------------------------------------------------------+ |
|
|
| | | |
|
|
| | [bot] | |
|
|
| | No agents yet | |
|
|
| | Agents appear here when dispatched from initiatives. | |
|
|
| | | |
|
|
| +-----------------------------------------------------------------------+ |
|
|
| |
|
|
+=============================================================================+
|
|
```
|
|
|
|
- `[bot]` icon: `Bot` from Lucide, `h-8 w-8 text-muted-foreground`
|
|
- Shown when the `listAgents` query returns an empty array and no filters are active
|
|
|
|
---
|
|
|
|
## Empty State -- Filters Active, No Match
|
|
|
|
```
|
|
+=============================================================================+
|
|
| |
|
|
| Agents [ Refresh ] |
|
|
| [codex_____________] [claude v] [execute v] |
|
|
| |
|
|
| +-----------------------------------------------------------------------+ |
|
|
| | | |
|
|
| | No matching agents | |
|
|
| | Try a different search or filter. | |
|
|
| | | |
|
|
| | [Clear filters] | |
|
|
| | | |
|
|
| +-----------------------------------------------------------------------+ |
|
|
| |
|
|
+=============================================================================+
|
|
```
|
|
|
|
- "Clear filters" is a text link (`text-primary hover:underline cursor-pointer`)
|
|
- Resets search input to empty, provider filter to "All", mode filter to "All"
|
|
|
|
---
|
|
|
|
## Source
|
|
|
|
- `packages/web/src/routes/agents.tsx`
|
|
- `packages/web/src/components/AgentOutputViewer.tsx`
|
|
- `packages/web/src/components/AgentActions.tsx`
|
|
- `packages/web/src/components/StatusDot.tsx`
|