--- name: agui-author description: Author live dashboard UI from an agent via the `emit_ui` MCP tool. Emit one of six allow-listed components (approval_card, choice_prompt, diff_summary, progress, metric, agent_card) with JSON props and it renders in any AG-UI client watching the fleet. Use when you want the operator to see a decision, a diff, or a status readout instead of scrolling terminal text. Arbitrary HTML/markup is refused. --- # 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. `