agui-author

# Authoring generative UI over AG-UI

CAO exposes an **AG-UI** stream (`GET /agui/v1/stream`) that any dashboard —
CopilotKit, the AG-UI Dojo, or a plain `EventSource` — renders
without CAO-specific code. As an agent you can push a **declarative UI intent**
onto that stream with the `emit_ui` MCP tool. The operator sees a rendered card,
not raw text — and because every provider's intents render uniformly, they can't
tell (and don't need to) which CLI agent produced which card.

The surface must be enabled on the server (`CAO_AGUI_ENABLED=true` or
`CAO_MCP_APPS_ENABLED=true` — the two surfaces share one event source). When it
is disabled, `emit_ui` returns `{"ok": false, "reason": "AG-UI surface disabled…"}`
— treat that as a no-op, not an error.

## Safety model (why this is always safe to call)

You may emit **only** a closed allow-list of named components with JSON props.
There is **no HTML, no script, no `eval`, no iframe**. The intent is validated
**server-side** against the allow-list before it reaches the stream:

- An **off-list** component (e.g. `iframe`, `script`) is **refused** — the tool
  raises a `ValueError`; nothing is rendered.
- `props` must be **JSON-serializable** and are **bounded to 8 KB** — an oversized
  or non-serializable payload is **rejected** at the `emit_ui` boundary (HTTP 400,
  the tool raises a `ValueError`), so a bad payload never reaches the bus.
- If the AG-UI surface is disabled on the server, the tool **degrades gracefully**
  (no error) — so calling it is never fatal.
- The AG-UI stream is **metadata-only by contract**: never put message bodies,
  credentials, or file contents in props. Reference paths, not contents.

## The tool

```
emit_ui(component: str, props: dict) -> {"ok", "event_id", "component"}
```

`component` must be one of: `approval_card`, `choice_prompt`, `diff_summary`,
`progress`, `metric`, `agent_card`.

## When to use which component

Props below are what a conformant client renderer will display; unknown extra keys
are ignored, not refused.

| Component | Use it when… | Props |
|---|---|---|
| `approval_card` | you need a human to approve/reject a risky action before you proceed | `title` (str), `detail` (str, optional), `risk` (`"low"`/`"medium"`/`"high"`, optional) |
| `choice_prompt` | you want the operator to pick among options | `question` (str), `choices` (list of `{"label", "value"}` or plain strings) |
| `diff_summary` | you changed files and want a compact review | `title` (str), `files` (list of `{"path", "additions", "deletions"}`) |
| `progress` | a long step is running | `label` (str), `value` (0.0–1.0; omit for an indeterminate bar) |
| `metric` | you want to surface a single number | `label` (str), `value` (str/number), `unit` (str, optional) |
| `agent_card` | you want to advertise your identity/status in the fleet view | `name` (str), `provider` (str), `status` (str, optional) |

## Examples

```python
# Gate a risky action on human approval.
emit_ui("approval_card", {
    "title": "Deploy to production?",
    "detail": "3 files changed, 1 DB migration",
    "risk": "high",
})

# Ask the operator to choose.
emit_ui("choice_prompt", {
    "question": "Which base branch?",
    "choices": [{"label": "main", "value": "main"},
                {"label": "release", "value": "release"}],
})

# Summarize a change set.
emit_ui("diff_summary", {
    "title": "Refactor auth",
    "files": [{"path": "security/auth.py", "additions": 74, "deletions": 3}],
})

# Show progress / a metric / your identity.
emit_ui("progress", {"label": "Indexing repository", "value": 0.42})
emit_ui("metric", {"label": "tokens used", "value": 12840, "unit": "tok"})
emit_ui("agent_card", {"name": "reviewer", "provider": "claude_code", "status": "working"})
```

## L2 constructs (Phase 2)

The AG-UI surface also exposes **L2 constructs** — higher-level projections that
fold the raw event stream into structured views. As an agent you don't author L2
constructs, but you should know they exist because your `emit_ui` intents feed
them:

- **`SupervisorDashboardStream`** — folds `STATE_SNAPSHOT`/`STATE_DELTA` + your
  `agent_card` emits into a live fleet hierarchy view.
- **`MultiAgentSessionTimeline`** — reconstructs delegation/message timeline
  from `TOOL_CALL` lifecycle events.
- **`AgentHandoffWithApproval`** — the full interrupt lifecycle: provider prompt
  → reason classification → interrupt → approve/deny/edit → delivery.
- **`CrossProviderStateSync`** — convergence proof across providers.

The **run plane** (`POST /agui/v1/run`) streams these as stock AG-UI wire frames.
Interrupts (approval prompts) route through `POST /agui/v1/interrupts/{id}/resume`.

For details: [references/l2-constructs.md](references/l2-constructs.md) and
[references/run-plane.md](references/run-plane.md).

## Gotchas

1. **Emitting to a disabled surface** — if `CAO_AGUI_ENABLED` is unset, `emit_ui`
   returns `{"ok": false}` gracefully. Don't treat this as an error or retry — it's
   a no-op by design. The fix: always check `ok` in the return but never fail on it.

2. **Props over 8 KB are rejected** — the tool raises a `ValueError` and nothing
   renders. The fix: reference file paths instead of embedding content. Keep props
   to metadata (paths, counts, labels).

3. **No HTML sink exists** — strings in props render as plain text. Attempting to
   smuggle markup through props (e.g. `<script>`, `<iframe>`) won't render and
   looks broken. The fix: use structured props, not markup.

4. **One intent per meaningful moment** — emitting a `progress` card on every
   token or tool call floods the stream and degrades client rendering. The fix:
   emit at milestones (start, 25%, 50%, 75%, done) or once per logical phase.

5. **`approval_card` is display-only today** — it gives the operator an
   approve/reject affordance in the dashboard, but the action routes to the
   dashboard's command surface, not back to you. The fix: pair it with your
   provider's own wait-for-input mech