WHCandCursor
5538ed3412
Move Qt/Tauri/full Web SPA under archive/, ship hermit as CLI/TUI plus libcstcore and cst-webui/1 HTTP+SSE (turn lifecycle hooks, capabilities). Co-authored-by: Cursor <cursoragent@cursor.com>
67 lines
2.2 KiB
Markdown
67 lines
2.2 KiB
Markdown
# 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`).
|