# cst-webui/1 — event & state schema

Machine-oriented summary of the HTTP/SSE engine API. Narrative + security:
[webui.md](webui.md). Peer/device sockets are separate: [parliament.md](parliament.md).

Protocol string: `GET /api/state` → `"protocol": "cst-webui/1"`.

## Capabilities

`GET /api/state` includes `"capabilities": [ ... ]` listing SSE `type` values this
build emits. Clients should probe this array rather than hard-coding.

Current set:

| type | Mirrors hook | Notes |
|------|--------------|--------|
| `assistant_delta` | `on_assistant_delta` | streaming text |
| `think_delta` | `on_think_delta` | reasoning stream |
| `assistant_html` | (web md) | sanitized HTML chunks |
| `status` | `on_status` | `{ "message": "..." }` |
| `tool` | `on_tool_event` | phase + call |
| `tool_result` | `on_tool_result` | output + exit |
| `todo` | `on_todo` | task list text |
| `permission` | `on_permission` | wait for `POST /api/permission` |
| `ask_user` | `on_ask_user` | wait for `POST /api/ask` |
| `state` | — | full snapshot (same shape as `/api/state`) |
| `turn_begin` | `on_turn_begin` | `{ "text": "<user prompt>" }` |
| `turn_end` | `on_turn_end` | `{ "rc": 0\|N, "error": "" }` |
| `error` | `on_error` | `{ "kind": "turn\|cancel\|…", "message": "…" }` |

## SSE framing

```
GET /api/events?since=<seq>
```

- `id: <seq>` + `data: {"type":…,"seq":…, …}`
- Comment heartbeat: `: ping`

## Primary control endpoints

| Method | Path | Role |
|--------|------|------|
| GET | `/api/state` | snapshot + `capabilities` |
| GET | `/api/events` | SSE stream |
| POST | `/api/turn` | `{ "text": "..." }` start turn |
| POST | `/api/cancel` | cancel in-flight turn |
| POST | `/api/permission` | answer permission prompt |
| POST | `/api/ask` | answer ask_user |
| POST | `/api/quit` | shut down server |

Full route list: [webui.md](webui.md).

## Embedded hooks (same semantics)

```c
cst_agent_hooks_t {
  on_status, on_assistant_delta, on_think_delta,
  on_tool_event, on_tool_result, on_tool_images,
  on_permission, on_ask_user, on_todo,
  on_turn_begin, on_turn_end, on_error,
  userdata
};
```

Archived FFI mirror: `archive/desktop-tauri/src-tauri/src/ffi_bridge.h` (`hermit_hooks_t`).