# Agents Domain

**Status:** Approved target-state baseline  
**First realization:** I1.

## Target State

AWP distinguishes an `Agent` definition/identity, a logical `AgentRun`, and immutable concrete `Attempt` executions.

```text
Task
 -> AgentRun (logical assignment)
     -> Attempt 1
          AgentProvider / Account / Model / effort
          Workspace / ExecutionProfile
     -> Attempt 2 (retry/fallback)
```

Agent providers may use ACP or native APIs. AWP owns run/attempt provenance, policy and lifecycle.

## Agent

An Agent describes a role/capability/provider-compatible execution identity or template: coder, reviewer, resolver, planner, etc. It does not imply a long-lived process.

## AgentRun

One logical assignment linked to Task/FactoryRun/role and expected outcome. Retry/fallback remains the same logical run where intent is unchanged.

## Attempt

Concrete immutable execution inputs:

```text
attemptId
agentRunId
provider
account
model
reason for selection/fallback
effort/profile/tool permissions
workspaceId/executionProfile
start/end/result
checkpoint/change provenance
provider native references
```

Provider/account/model never silently switch mid-Attempt.

## Invariants From Day 1

- agent role is not merge/deployment authority;
- every Attempt has explicit provider/account/model provenance;
- fallback/rate exhaustion creates new Attempt;
- workspace/tool permissions are capability-scoped;
- reusable Git/control credentials never mounted;
- agent messages/tool activity are observable but not authoritative lifecycle state;
- cancellation/retry preserves WIP/checkpoints before destructive cleanup;
- reviewer/coder independence is policy-visible.

## Live Dogfood Model Policy

Test-purpose aliases resolve dynamically:

```text
factory-throwaway
  Codex / gpt-5.3-codex-spark / low effort
  rotate authorized Spark-capable accounts between Attempts

factory-free-useful
  OpenCode Zen / deepseek-v4-flash-free

factory-free-fallback
  OpenCode + OpenRouter / cohere/north-mini-code:free
```

Free availability is probed immediately before execution. OpenCode harness is preferred for coding-agent E2E; raw OpenRouter tests provider connectivity only unless AWP owns equivalent tool-using harness.

## Lifecycle

```text
AgentRun: planned -> queued -> active -> waiting -> completed/cancelled/failed
Attempt: created -> provisioning -> running -> checkpointing -> terminal
```

Reason/status includes model capacity, tool wait, human wait, workspace failure, provider outage, policy denial and cancellation.

## Tool Activity / Chat

Agent output is structured into messages, tool-use records, files/diffs/checkpoints and token/cost telemetry where available. Rich dedicated Agent UI activates I4 but I1 captures event/provenance fields needed later.

## Increment Realization

| Increment | Agent realization |
|---|---|
| I1 | coder/reviewer AgentRuns, Attempts, model/account selection, retries/fallback and basic status. |
| I2 | Planning can choose/infer execution defaults. |
| I4 | dedicated chat/tool/diff/files/cost UX. |
| I8 | resolver agent roles. |
| I9 | customer-configurable provider/catalog governance. |

## Current Implementation State

Target spec. Live testing policy is canonical dogfood behavior, not production model preference.

## Deferred Realization

Advanced cost routing/health scoring/model marketplaces are later policy/provider work.

## Temporary Dogfood Behavior

Spark looping/low-value output is acceptable when pass condition is lifecycle plumbing. Do not spend high-value models on tests that do not depend on answer quality.

## Failure / Recovery

Rate exhaustion/provider unavailability preserves WIP and starts a new Attempt with explicit selection reason. Process/pod crash resumes from checkpoint or starts new Attempt from latest durable state.

## UI Implications

Agent page resembles normal AI chat, with human-readable tool-use log, diffs/files and context links to Task/FactoryRun/model/account/node. No raw event JSON dump as primary UX.

## Decisions / ADRs

Attempt immutability and execution-plane isolation are binding architecture seams.