# Agent UI Protocol

## Summary

`agent-ui@1` is the experimental frontend protocol for Agent-driven UI. The
Agent never returns executable frontend code. It invokes trusted opencode tools;
the service maps those tool calls to `UIEnvelope` payloads; the frontend validates
and renders known components, charts, and map actions.

## SSE Event

```text
event: ui_envelope
data: {
  "session_id": "session-id",
  "envelope_id": "env-id",
  "created_at": 1710000000000,
  "envelope": {}
}
```

## Envelope Types

Current `agent-ui@1` support is intentionally limited to three trusted shapes:

- `registered_component` for frontend-registered business panels.
- `chart` for the `echarts-safe-subset` chart grammar.
- `map_action` for the WebGIS map adapter.

The Agent must not return executable JS, JSX, HTML, CSS, or arbitrary component
source. The frontend renders only allowlisted components, chart specs, and map
actions.

```ts
type UISurface = "chat_inline" | "side_panel" | "canvas" | "map_overlay";

type UIEnvelope =
  | {
      kind: "registered_component";
      schemaVersion: "agent-ui@1";
      component: string;
      surface: UISurface;
      props: unknown;
      data?: unknown;
      fallbackText?: string;
    }
  | {
      kind: "chart";
      schemaVersion: "agent-ui@1";
      grammar: "echarts-safe-subset";
      surface: "chat_inline" | "side_panel" | "canvas";
      spec: unknown;
      data: unknown;
      fallbackText?: string;
    }
  | {
      kind: "map_action";
      schemaVersion: "agent-ui@1";
      action: string;
      surface: "map_overlay";
      params: unknown;
      fallbackText?: string;
    };
```

## Registry

```text
GET /api/v1/agent/chat/ui-registry
```

The registry returns the allowed chart grammar, registered components, and map
actions. Unknown components/actions should be rejected by the frontend.

`map_action` is a WebGIS-specific extension, not a general command channel. It
is valid only on `map_overlay`; every action and parameter set must be validated
by the frontend before it can affect MapLibre state. Invalid map actions should
fall back to `fallbackText`.

Initial mappings:

- `show_chart` -> `chart`
- `locate_features` -> `map_action`
- `zoom_to_map` -> `map_action`
- `render_junctions` -> `map_action`
- `apply_layer_style` -> `map_action`
- `view_history` -> `registered_component: HistoryPanel`
- `view_scada` -> `registered_component: ScadaPanel`

`view_history` parameters must include `start_time` and `end_time` ISO8601
timestamps with `start_time < end_time`. When the Agent needs historical
monitoring values for analysis or a chart, it should call
`query_monitoring_readings` first, then use `view_history` only to open the
frontend panel.

`render_junctions` accepts only a `render_ref`. The frontend must resolve the
full payload through:

```text
GET /api/v1/agent/chat/render-ref/:render_ref?session_id=:session_id
```

## State Persistence

Assistant messages may contain:

```ts
uiEnvelopes?: Array<{
  envelopeId: string;
  createdAt: number;
  envelope: UIEnvelope;
  renderStatus: "pending" | "rendered" | "fallback" | "error";
  error?: string;
}>;
```

`tool_call` and `artifacts` remain deprecated compatibility/debug surfaces. New
frontends should consume `ui_envelope` and `uiEnvelopes`.