# 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

生成接口为 `POST /api/v1/responses`。下方示例是会话状态订阅中的 UIEnvelope；Responses 生成流将同一业务数据放入 `tjwater.ui_envelope` 事件的 `data` 中，并携带 `response_id` 和 `sequence_number`。

运行中追加文本使用同一生成地址，`stream=false`，携带 `conversation`、`tjwater.delivery="steer" | "queue"` 和稳定的 `tjwater.input_id`。HTTP 202 的 `tjwater.response_input` 收件回执不是新的 Response 或处理成功证明。当前 Responses SSE 保持连接，用 `tjwater.user_input` 的 `pending` / `delivered` 状态同步输入，`delivered` 表示原生收件箱已取走而非任务完成。`GET /api/v1/session/:session_id/inputs` 返回待处理消息；PATCH 其 `/:input_id` 的 `delivery` 可在处理前切换模式，处理后返回409。恢复会话流使用同样的 `user_input` 业务事件和原生待处理列表。

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

Analysis evidence must come from validated request context or allowlisted
tools. This service does not bundle a local historical business dataset.

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