# Agent Page UI

**Status:** Approved target-state behavior  
**Basic provenance:** I1  
**Dedicated rich UI activation:** I4.

## Page Job

Provide a familiar AI coding-agent conversation surface with structured tool/use/change observability, tied clearly to AWP delivery context.

```text
Who/what is this agent working on?
Which provider/model/account/Attempt?
What has it said/done?
Which tools/files changed?
What diff/WIP/checkpoint exists?
Is it running/waiting/error/idle?
Where is it running?
```

## Header

AgentRun role/status, Task/FactoryRun breadcrumbs, current Attempt number, provider/model/effort/account label, node/workspace, elapsed time and allowed action (cancel/steer only if capability/policy supports it).

## Chat / Tool UX

Use a normal readable chat pattern (Astryx AI chat as source/reference) rather than raw event JSON. Tool uses are compact structured cards/rows:

```text
Tool: edit_file
path: packages/domain/...
result: changed 3 lines
[View diff]
```

Expandable technical detail/log is secondary.

## Diff / Files / Context

Desktop can use a context panel/drawer for current diff, files, checkpoints, task/plan instructions and Attempt provenance. Clicking file opens diff/source viewer without losing chat scroll position.

## Attempts

Retry/fallback history is explicit:

```text
Attempt 1  Spark low / account A   rate exhausted
Attempt 2  Spark low / account B   process interrupted
Attempt 3  DeepSeek free           active
```

Selecting historical Attempt switches read-only chat/tool/checkpoint context. No blending messages across attempts without labels.

## Status / Waiting

Differentiate agent actively reasoning/tooling, waiting for tool/provider, human/policy wait, model capacity/rate limit, workspace issue, completed, cancelled and disconnected observation.

## Token / Cost / Model Metrics

I4 shows token/cost/latency where provider exposes reliable data, but these are secondary to task progress and cannot be fabricated when unavailable.

## Security

Never expose raw provider tokens/secrets. Tool logs redact secrets and sensitive values. Agent's actual capability set is inspectable.

## States

- provisioning;
- active chat/tool use;
- idle/waiting;
- failure/retryable;
- completed;
- cancelled;
- stale/disconnected realtime.

Loading keeps AgentRun/Attempt header and message placeholders.

## Responsive / Accessibility

On narrow screens chat dominates; diff/files/tool details are drawers. Tool cards use semantic headings/buttons; focus returns correctly after drawer/file navigation; live token/tool updates do not spam screen readers.

## URL Truth

Stable AgentRun route plus selected Attempt/file/diff state where useful. Deep links from Factory/Plan restore context.

## Increment Realization

I1 may show basic Agent provenance/status within FactoryRun rather than dedicated rich page. I4 activates full page; I8 resolver agents use same core interaction with incident context.

## High-Fidelity Requirements

Before I4: realistic long conversation with tool cards, diff drawer, multi-attempt fallback, waiting/error and narrow mobile state.

## Target State

Agent detail is the human-readable observation/interaction view of one logical AgentRun and its immutable Attempts. It presents chat, tools, files, diffs, WIP and provenance without making provider conversation logs or a browser session the lifecycle authority.

## Primary Users / Jobs

- engineer/operator: understand what the agent is doing and what it changed;
- reviewer/debugger: inspect tool/file/diff evidence and Attempt history;
- authorized owner/lead: steer/cancel when provider capability and AWP policy permit.

## Entry / Exit Points

Entry: FactoryRun node/row, Agents collection, Plan/Task context, Incident resolver context, search. Exit: Task/Plan, FactoryRun, selected file/diff/checkpoint, ChangeSet/Review, Workspace/Machine context and provider-native raw log only as secondary debugging evidence.

## User Journeys

### J1 — Inspect live coding work

```text
open Agent
 -> orient on Task/Factory/Attempt/model/account/Machine
 -> read conversation + structured tool activity
 -> open changed file/diff in context drawer
 -> return to chat at same scroll point
 -> follow resulting ChangeSet when produced
```

### J2 — Understand fallback/retry

```text
current Attempt fails/waits
 -> read classified reason
 -> inspect immutable Attempt history
 -> see provider/account/model changes on new Attempt
 -> compare checkpoints/WIP provenance
 -> continue observing current Attempt without blended history
```

### J3 — Steer or cancel safely

```text
authorized contextual action
 -> inspect capability/policy consequence
 -> submit steer/cancel once
 -> immediate acknowledgement + durable AgentRun/Attempt state
 -> current activity updates or cancellation enters terminal/recovery path
```

### J4 — Inspect resolver agent

```text
Incident resolver AgentRun
 -> Incident breadcrumb/context
 -> inspect diagnosis/tools/change proposal
 -> proposed fix enters normal ChangeSet/Review/Verification
 -> agent page remains execution evidence, not approval authority
```

## Data / Source of Truth

AgentRun lifecycle and Attempt provenance come from the Agents domain; Workspace/checkpoint from Workspace; Task/Factory relationships from Work/Factory. Messages/tool events/files/diffs are attributable execution evidence. Provider token/cost/latency values are observations and may be unavailable. Raw provider session IDs never replace AWP identity.

## Actions / Authorization

Readability follows Project/Run visibility. `Steer` requires supported provider capability and configured AgentRun/Policy authority; `Cancel` uses Factory/Agent cancellation policy. A displayed agent cannot grant itself additional tools/capabilities. Secret-bearing log detail remains redacted by policy.

## Async / Duplicate-Mutation Safety

Steer/cancel commands use durable command identity/revision protection, acknowledge immediately and suppress duplicate submit. Disconnect does not imply cancellation. Historical Attempts are read-only. Unsafe mutation is disabled until current state is refreshed after stale/disconnected observation.

## Invariants From Day 1

- logical AgentRun and Attempt are never conflated;
- provider/model/account are immutable for an Attempt;
- historical Attempt content is clearly read-only;
- no raw secret is rendered in chat/tool/diff metadata;
- diff/file navigation preserves conversational context;
- raw provider logs remain secondary evidence;
- chat cannot become an alternate Decision/Approval source of truth.

## Current Implementation State

Target page only. I1 captures enough provenance/status to support FactoryRun; dedicated rich page waits for I4.

## Deferred Realization

I4 activates full chat/tool/diff/files/cost observability; I8 reuses the same page model for resolver agents with Incident context. Billing/tenant analytics are later productization concerns.

## Temporary Dogfood Behavior

I1 may deep-link to a minimal read-only Agent detail if useful, but must not create a provider-specific temporary chat app. Final AgentRun/Attempt routes and provenance are preserved.

## Related Contracts / Decisions

- [`../domains/agents.md`](../domains/agents.md)
- [`../domains/factory.md`](../domains/factory.md)
- [`../workflows/factory-execution.md`](../workflows/factory-execution.md)
- [`factory-run.md`](factory-run.md), [`agents.md`](agents.md), [`review.md`](review.md)
- Astryx AI chat is a visual/interaction source, not domain authority.

## Visual Mockup Authority

No rich Agent high-fi is approved yet. The I4 mockup set must demonstrate realistic long conversation, tool cards, diff/file context, Attempt switching, waiting/failure and narrow layout before implementation.

## Acceptance

An engineer can inspect an agent like a modern coding-agent chat, understand every important tool/change without reading raw logs, and trace it to Task/Factory/Attempt/Workspace.