# Agents Collection and Analytics UI

**Status:** Approved target-state baseline  
**First realization:** I1 basic active-agent visibility; full analytics/observability I4.  
**Purpose:** Answer which agents are running, what they are doing, where they are running, which model/account they use, and whether any agent needs attention.

## Target State

`Agents` is a global operational collection over canonical `AgentRun` / `Attempt` / `Workspace` state. It is not a second agent lifecycle database.

Primary questions:

```text
Which agents are active right now?
What Project / Plan / Task / FactoryRun owns each one?
Where is it running?
Which provider / model / account / effort is resolved for the Attempt?
What is its state and latest meaningful progress?
What is waiting/failing and why?
How are agent usage/error patterns changing over time?
```

## Primary Users / Jobs

- owner/operator: find active/waiting/error agents and determine whether any need intervention;
- engineering/delivery lead: understand concurrency, provider/model/account usage and failure patterns across Projects;
- developer/reviewer: jump from an AgentRun to its exact Task/Factory/Attempt/work output.

## Entry / Exit

Entry points:

- `EXECUTION -> Agents` global navigation;
- Project/Plan/Factory summaries;
- Work/Attention links;
- search/command palette.

Selecting a row/card opens the canonical Agent detail route while preserving collection filters when navigating back. Other exits include Project, Task, FactoryRun, Machine/Cluster and evidence/Incident contexts.

## User Journeys

### J1 — Find an active agent

```text
open Agents
 -> scan active/waiting/error summary
 -> filter by Project/state/model/account/Machine
 -> identify Task/FactoryRun + latest progress
 -> open Agent detail
 -> return with filters/time window preserved
```

### J2 — Diagnose an agent wait/failure

```text
waiting/error row
 -> read reason + since + owner + latest progress + next
 -> inspect Attempt/provider/account/Workspace context
 -> open canonical Factory/Incident/Connection source
 -> retry/cancel/resolve only if policy allows
 -> collection updates from authoritative run state
```

### J3 — Inspect trends without confusing telemetry with truth

```text
select time window
 -> inspect concurrency/token/error/fallback trends
 -> filter by Project/provider/model
 -> drill to contributing AgentRuns
 -> current operational status remains sourced from AgentRun state
```

## Information Architecture

```text
Agents
  summary
    Active / Waiting / Error
    utilization trend
    token/model usage summary
    provider/account health hints

  active collection
    Agent / status
    Project / Task
    FactoryRun
    Attempt
    model + account + effort
    Machine / Workspace
    started / elapsed
    latest progress
    next / waiting reason

  analytics
    active agents over time
    token usage by model/provider/project
    failure/error rate
    retries/fallbacks
    duration / throughput where meaningful

  history
    completed / failed / cancelled runs
```

## Default Collection

Desktop table/list is the default for operational density. A card view may exist only if it improves a specific compact use case.

Columns must remain human-readable and clickable:

```text
Agent / Run
State
Project / Task
FactoryRun
Model
Account
Machine
Started / elapsed
Last meaningful activity
Attention / next
```

Raw provider IDs are secondary evidence.

## States

Use product language:

```text
Working
Idle / waiting for provider/tool/user/dependency
Retrying
Interrupted / recovering
Needs attention
Failed
Completed
Cancelled
```

Every waiting/error state explains reason, since-when, current owner, latest progress and next expected action.

## Analytics

Target time windows include at least:

```text
24h
3d
7d
14d
30d
```

Target views include:

- active/concurrent agents over time;
- token usage by model/provider/account where available;
- error/failure/retry rate;
- provider/model fallback frequency;
- average/percentile run duration where useful;
- project-level filtering.

Charts use the canonical AWP Chart.js substrate and always expose accessible table/text equivalents. Analytics may be delayed/stale without changing authoritative current run state.

## Data Truth

Current lifecycle state comes from AWP `AgentRun` / `Attempt` / `Workspace` read models. Machine placement comes from `Workload`/`Machine` projection. Provider/account/model comes from immutable Attempt provenance. Historical metrics may use OTel/metric backends, but telemetry never overrides lifecycle truth.

## Actions

Primary action is contextual, not globally `Start agent` because agents normally begin through Plan/Task/Factory lifecycle.

Allowed contextual actions may include:

```text
Open Agent
Open FactoryRun / Task / Project
Steer / communicate when provider supports it and policy permits
Cancel / retry protected by policy
Inspect evidence/logs/files
```

Destructive or authority-changing actions are separated and live-evaluated.

## Authorization / Mutation Safety

Collection visibility follows Principal/Project access. Steer, cancel and retry require current Agent/Factory capability and policy; the collection does not broaden authority. Mutations acknowledge immediately, use revision/idempotency protection, expose the durable AgentRun/Attempt operation and disable duplicate submit. Unsafe mutations are disabled while current state is stale/disconnected.

## Filters / Search / URL Truth

Support at least:

```text
state
Project
FactoryRun
model
account
provider
Machine
attention
started range
```

Search/filter/sort/group/time-window state is URL-restorable where practical.

## Complete UI States

### Loading

Reserve table/chart geometry with skeletons; do not flash `0 agents`.

### Empty

Explain whether there are no active agents or no matches. Link to Work/Projects rather than inventing an agent outside a Task/Factory context.

### Error

If analytics fails but live run collection works, keep operations available and mark analytics unavailable. If current-state read fails, show stale last-known state with timestamp and disable unsafe mutations.

### Stale / Disconnected

Show freshness timestamp. Reading cached state is allowed. Cancel/retry/steer requires live authoritative connection.

## Responsive Behavior

Wide screens keep operational table plus summary/analytics. Medium screens collapse secondary analytics. Small screens use a compact list with drill-in; model/account/machine remain discoverable in row detail rather than disappearing.

## Accessibility

- sortable headers expose semantics;
- status is not color-only;
- charts have textual/table equivalents;
- keyboard row navigation and Enter-to-open;
- live state changes use restrained async announcements without constant screen-reader chatter.

## Invariants From Day 1

- current status comes from AgentRun/Attempt state, never analytics inference;
- every agent row is traceable to Project/Task/Factory/Attempt/Workspace;
- provider/model/account provenance is immutable per Attempt;
- charts never become the only representation of critical data;
- waiting/error rows explain why and next action;
- collection actions cannot bypass Factory/Policy gates.

## Increment Realization

| Increment | Agents UI |
|---|---|
| I1 | active AgentRun/Attempt status, Project/Task/Factory/model/account/Machine, failure/retry provenance. |
| I4 | rich live activity, tools/files/diff links, analytics and historical exploration. |
| I5–I8 | CI/delivery/incident correlations deepen without changing agent identity. |
| I9 | tenant/cost/governance views if productized. |

## Current Implementation State

Target page spec only. I1 high-fi may include the minimum operational agent summary inside U2/U3; a full standalone Agents high-fi is required before its dedicated collection implementation.

## Deferred Realization

Sophisticated cost optimization, billing analytics and cross-tenant dashboards are not dogfood requirements.

## Temporary Dogfood Behavior

I1 may render only active/recent runs with basic statistics while retaining the final route/data model. Do not create a temporary provider-specific process monitor.

## Related Specs

- `../domains/agents.md`
- `../domains/accounts-models-providers.md`
- `../domains/cluster.md`
- `factory-run.md`
- `agent.md`
- `INDEX.md`

## Decisions / ADRs

The page inherits provider/account/Attempt identity, K3s placement and telemetry-vs-product-state decisions from the corresponding domains/architecture. A material change to those authority boundaries requires the relevant Decision/spec amendment.

## Visual Mockup Authority

No standalone Agents high-fi is approved yet. I1 may show the minimal operational collection state only if covered by approved U2/U3 composition; the full I4 Agents analytics frame requires separate approval before implementation.

## Acceptance

From one page the user can identify every active agent, its exact owning work/context, model/account/Machine, latest progress and reason for waiting/failure, then navigate directly to the AgentRun/Factory/Task without searching IDs.