CST-agent/docs/webui-schema.md

cst-webui/1 — event & state schema

Machine-oriented summary of the HTTP/SSE engine API. Narrative + security: webui.md. Peer/device sockets are separate: 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.

Embedded hooks (same semantics)

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).