# AWP Control Surfaces Architecture

**Status:** Approved target-state baseline  
**First realization:** I0 API/application seams; I1 minimum CLI/operator path; richer MCP/CLI grows with consuming increments.  
**Purpose:** Ensure Web UI, HTTP API, `aw*` CLI and MCP are different interfaces to one AWP application/domain authority rather than independent automation stacks.

## Target State

AWP exposes multiple control surfaces over the same commands, queries, IDs, authorization, policy, audit and lifecycle semantics:

```text
Web UI
HTTP/API
aw* CLI
MCP
   \ | /
application commands / queries
        ↓
domain + policy + authorization
        ↓
provider adapters / durable workflows
```

No surface is privileged merely because it is local or agent-oriented.

## Invariants From Day 1

- UI, API, CLI and MCP call the same application use cases rather than reimplementing lifecycle logic;
- stable AWP primitive IDs are accepted/returned consistently across surfaces;
- final authorization occurs in the control plane;
- every state-changing command carries attributable `Principal`, correlation/idempotency context and audit;
- MCP cannot bypass Approval, autonomy, capability, connection or merge/deployment gates;
- CLI cannot become a hidden workstation-control backdoor;
- high-risk command semantics are identical regardless of transport;
- transport/provider errors are normalized through stable AWP error contracts;
- long-running commands return durable operation/run identity rather than holding a fragile process as authority;
- commands are idempotent where retry is plausible;
- output has a structured machine-readable form and useful human form where CLI-facing;
- no separate daemon or state database exists solely for CLI/MCP.

## `aw*` CLI Family

AWP reorganizes product-operable commands under an `aw*` namespace/family. Exact binary packaging can be decided during I0 implementation without changing this contract.

Examples of intended command identity:

```text
awctl                  general control/query entry point
awproject              Project operations where a focused alias improves use
awplan                  Plan/Planning operations
awrun                   Factory/Agent run operations
awci                    CI queries/actions when I5 activates
awship                  release/deployment operations when I6 activates
```

The design goal is discoverable product commands, not preserving hundreds of accidental Overdeck command names.

Aliases/wrappers are allowed when they reduce friction, but canonical semantics live in AWP application commands.

## CLI Contract

Every command declares:

```text
command/use-case identity
required principal/capability
input schema
accepted primitive IDs/selectors
idempotency semantics
sync vs durable async result
human output
structured output (JSON where appropriate)
error codes/recovery hints
links/IDs for continued inspection
```

CLI must support scripting without requiring parsing decorative text.

A CLI operation that starts long-running work returns the durable AWP object:

```text
awrun start ...
  -> FactoryRunId / AgentRunId / operation state
```

not a PID whose death loses ownership.

## MCP Contract

Use the **official TypeScript MCP SDK** matching the selected protocol generation. Do not custom-build MCP framing, transport or protocol parsing.

MCP tools/resources are thin projections of AWP commands/queries. They expose domain concepts in agent-friendly form while preserving the same policy gates.

Example mapping:

```text
Project query              -> MCP resource/tool -> GetProject
Start approved execution   -> MCP tool          -> StartPlan/FactoryRun command
Inspect run/evidence       -> MCP resource      -> canonical read model
Request decision/approval  -> MCP tool          -> domain request command
```

Do not expose provider credentials, Kubernetes raw authority or trusted publication credentials through generic MCP merely because an agent asks for them.

MCP capability advertisement must reflect the authenticated Principal and Project binding rather than listing unusable privileged tools as if available.

## HTTP / API

Hono owns transport mechanics only. API DTOs/events live in runtime-neutral contracts. Public/internal transport cannot import provider-native domain meanings.

Stable externally consumed contracts use the R4 compatibility policy and OpenAPI/oasdiff when the consumer boundary becomes stable.

## UI

The web UI is not a privileged semantic path. It consumes the same commands/queries and adds presentation, optimistic/immediate feedback, navigation and safe interaction patterns.

High-risk actions such as Merge, production Deployment, credential/security changes and destructive cleanup require live authoritative connectivity; they are never queued offline merely because a client UI can cache state.

## Authentication and Principal Mapping

```text
human browser/session -> Human Principal
CLI credential/session -> Human/System Principal according to configured identity
MCP client/session     -> Agent/Human/System Principal according to connection
internal automation    -> System Principal
```

Transport authentication does not decide final capability. The control plane resolves authorization and policy.

## Agent/Automation Boundary

Normal coding/reviewer agents may receive only the AWP tools allowed for their role/context. An agent can request publication/merge but does not receive reusable forge credentials or direct merge authority.

A tool exposed to an agent must state whether it is:

```text
read-only
workspace mutation
control-plane request
protected action requiring Approval/policy
```

## Observability

Every state-changing invocation records at least:

```text
principal
surface: ui | api | cli | mcp | internal
command
project/scope
correlation/causation
result / durable operation ID
policy/approval decision where applicable
```

Do not create separate audit semantics per surface.

## Increment Realization

| Increment | Control-surface realization |
|---|---|
| I0 | shared application command/query seams; authentication/Principal mapping; minimal operator CLI needed for bootstrap. |
| I1 | CLI/API/UI can inspect/start the first dogfood lifecycle through the same semantics. MCP may expose only capabilities required by agents/operators. |
| I2 | Planning/project commands and Planning MCP resources/tools where useful. |
| I3 | generic Decision/Approval/autonomy commands. |
| I4–I8 | Factory, CI, delivery, cluster and incident command families activate with their domains. |
| I9 | stable public API/adapter SDK commitments and compatibility guarantees. |

## Current Implementation State

Target contract only. Existing Overdeck CLI tools are harvest sources, not AWP's command architecture.

## Deferred Realization

Exact binary split, shell completion implementation, public SDK generation and remote customer API guarantees are implementation/productization choices behind this seam.

## Temporary Dogfood Behavior

I0/I1 may expose a smaller `awctl` command set before ergonomic focused aliases exist. It must still use final commands/IDs/auth/audit rather than throwaway scripts that mutate AWP state directly.

## FOSS / Harvest Requirements

Before CLI/MCP implementation:

- inspect relevant Overdeck CLI tools for proven behavior/error handling, then disposition them through the harvest plan;
- use official MCP TypeScript SDK rather than implementing protocol wire behavior;
- reuse verified Platform auth/config/logger/CLI helpers when they fit;
- do not migrate Botmaster as AWP's core CLI; Botmaster remains external/personal tooling.

## Failure / Recovery

Transport disconnect does not cancel durable work unless the command explicitly requested cancellation. Duplicate client retry uses idempotency key/command semantics. Authorization changes are re-evaluated for protected actions rather than trusting stale client capability.

## Acceptance

A representative lifecycle can be started/inspected through more than one surface and yields the same canonical object IDs, state transitions, policy outcomes and audit history; no surface can bypass a gate that another surface must obey.