# 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`.

There are currently no Agent tool mappings for charts, components, or map
actions. The protocol types remain documented for compatibility and future
allowlisted actions.

Historical monitoring values for analysis come from the project `source/`
directory.

## 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`.