Skip to content

Self-improving AI Employees for everyone

feat(chat): employees can show an interface in a chat reply

trohitg8d9093d784c6
diff --git a/server/config/chat_genui_catalog.json b/server/config/chat_genui_catalog.json
new file mode 100644
index 00000000..d2c5da26
--- /dev/null
+++ b/server/config/chat_genui_catalog.json
@@ -0,0 +1,239 @@
+{
+ "_comment": "What an employee may show inside a chat reply with the show_ui tool (server/nodes/chat/chat_ui). The tool's description and its validation (server/services/genui/spec.py) are built from this file, and the client's chat catalog (client/src/features/chat/genui/catalog.ts) must list the same components, roles, children, bound props, events and limits: tests on both sides read the other side. A component's props are JSON Schema for the literal values a model writes; any prop may instead hold an expression ({\"$state\": \"/path\"}, {\"$template\": \"... ${/path} ...\"}, {\"$cond\": condition, \"$then\": value, \"$else\": value}), and the prop named in `bind` may hold {\"$bindState\": \"/path\"}, which the control reads and writes. SlotPicker options use generic keys (time, detail, recommended, unavailable, note) rather than the design handoff's salon ones.",
+ "spec_version": 1,
+ "limits": {
+ "max_elements": 24,
+ "max_depth": 6,
+ "max_bytes": 16384,
+ "max_children": 12,
+ "max_id_length": 40,
+ "max_path_segments": 6
+ },
+ "components": {
+ "Stack": {
+ "role": "layout",
+ "description": "A column of elements, top to bottom. Use it as the root.",
+ "children": "any",
+ "props": {
+ "type": "object",
+ "properties": {
+ "gap": {"enum": ["sm", "md"]}
+ }
+ }
+ },
+ "Row": {
+ "role": "layout",
+ "description": "Buttons side by side.",
+ "children": ["Button"],
+ "props": {
+ "type": "object",
+ "properties": {
+ "gap": {"enum": ["sm", "md"]}
+ }
+ }
+ },
+ "Card": {
+ "role": "layout",
+ "description": "A titled panel of fields and text.",
+ "children": ["Select", "Toggle", "TextField", "Text"],
+ "props": {
+ "type": "object",
+ "required": ["title"],
+ "properties": {
+ "title": {"type": "string", "minLength": 1, "maxLength": 80},
+ "description": {"type": "string", "maxLength": 240}
+ }
+ }
+ },
+ "SlotPicker": {
+ "role": "input",
+ "description": "Pick one of a few times; its value is the picked option's id.",
+ "bind": "value",
+ "props": {
+ "type": "object",
+ "required": ["label", "options"],
+ "properties": {
+ "label": {"type": "string", "minLength": 1, "maxLength": 80},
+ "hint": {"type": "string", "maxLength": 120},
+ "value": {"type": "string", "maxLength": 40},
+ "options": {
+ "type": "array",
+ "minItems": 1,
+ "maxItems": 8,
+ "items": {
+ "type": "object",
+ "required": ["id", "time"],
+ "properties": {
+ "id": {"type": "string", "minLength": 1, "maxLength": 40},
+ "time": {"type": "string", "minLength": 1, "maxLength": 40},
+ "detail": {"type": "string", "maxLength": 60},
+ "recommended": {"type": "boolean"},
+ "unavailable": {"type": "boolean"},
+ "note": {"type": "string", "maxLength": 80}
+ },
+ "additionalProperties": false
+ }
+ }
+ }
+ }
+ },
+ "Select": {
+ "role": "input",
+ "description": "Pick one of two to six short options.",
+ "bind": "value",
+ "props": {
+ "type": "object",
+ "required": ["label", "options"],
+ "properties": {
+ "label": {"type": "string", "minLength": 1, "maxLength": 80},
+ "value": {"type": "string", "maxLength": 40},
+ "options": {
+ "type": "array",
+ "minItems": 2,
+ "maxItems": 6,
+ "items": {"type": "string", "minLength": 1, "maxLength": 40}
+ }
+ }
+ }
+ },
+ "Toggle": {
+ "role": "input",
+ "description": "An on/off choice.",
+ "bind": "checked",
+ "props": {
+ "type": "object",
+ "required": ["label"],
+ "properties": {
+ "label": {"type": "string", "minLength": 1, "maxLength": 80},
+ "hint": {"type": "string", "maxLength": 120},
+ "checked": {"type": "boolean"}
+ }
+ }
+ },
+ "TextField": {
+ "role": "input",
+ "description": "A short line of text the owner types.",
+ "bind": "value",
+ "props": {
+ "type": "object",
+ "required": ["label"],
+ "properties": {
+ "label": {"type": "string", "minLength": 1, "maxLength": 80},
+ "placeholder": {"type": "string", "maxLength": 80},
+ "value": {"type": "string", "maxLength": 400}
+ }
+ }
+ },
+ "Text": {
+ "role": "display",
+ "description": "A sentence or short paragraph.",
+ "props": {
+ "type": "object",
+ "required": ["text"],
+ "properties": {
+ "text": {"type": "string", "minLength": 1, "maxLength": 600}
+ }
+ }
+ },
+ "StatGrid": {
+ "role": "display",
+ "description": "A few numbers side by side, each with an optional change.",
+ "props": {
+ "type": "object",
+ "required": ["items"],
+ "properties": {
+ "items": {
+ "type": "array",
+ "minItems": 1,
+ "maxItems": 6,
+ "items": {
+ "type": "object",
+ "required": ["label", "value"],
+ "properties": {
+ "label": {"type": "string", "minLength": 1, "maxLength": 40},
+ "value": {"type": ["string", "number"]},
+ "delta": {"type": "string", "maxLength": 40},
+ "tone": {"enum": ["up", "down"]}
+ },
+ "additionalProperties": false
+ }
+ }
+ }
+ }
+ },
+ "BarChart": {
+ "role": "display",
+ "description": "Horizontal bars comparing a few values.",
+ "props": {
+ "type": "object",
+ "required": ["title", "bars"],
+ "properties": {
+ "title": {"type": "string", "minLength": 1, "maxLength": 80},
+ "bars": {
+ "type": "array",
+ "minItems": 1,
+ "maxItems": 12,
+ "items": {
+ "type": "object",
+ "required": ["label", "value"],
+ "properties": {
+ "label": {"type": "string", "minLength": 1, "maxLength": 40},
+ "value": {"type": "number", "minimum": 0}
+ },
+ "additionalProperties": false
+ }
+ }
+ }
+ }
+ },
+ "Callout": {
+ "role": "display",
+ "description": "A highlighted note: info, warning, danger or success.",
+ "props": {
+ "type": "object",
+ "required": ["tone", "text"],
+ "properties": {
+ "tone": {"enum": ["info", "warning", "danger", "success"]},
+ "text": {"type": "string", "minLength": 1, "maxLength": 400}
+ }
+ }
+ },
+ "Button": {
+ "role": "action",
+ "description": "Runs the action in its \"on\": {\"press\": {\"action\", \"params\"}}.",
+ "events": ["press"],
+ "props": {
+ "type": "object",
+ "required": ["label"],
+ "properties": {
+ "label": {"type": "string", "minLength": 1, "maxLength": 40},
+ "variant": {"enum": ["primary", "secondary"]}
+ }
+ }
+ }
+ },
+ "actions": {
+ "ask": {
+ "description": "Sends params.text as the owner's next message. It is sent at once only when it is the button's label; otherwise it goes into the message box for the owner to send.",
+ "params": {
+ "type": "object",
+ "required": ["text"],
+ "properties": {
+ "text": {"type": "string", "minLength": 1, "maxLength": 300}
+ }
+ }
+ },
+ "setState": {
+ "description": "Sets params.statePath to params.value in this UI's state, without telling you.",
+ "params": {
+ "type": "object",
+ "required": ["statePath"],
+ "properties": {
+ "statePath": {"type": "string", "minLength": 2, "maxLength": 120},
+ "value": {}
+ }
+ }
+ }
+ },
+ "custom_actions": "Any other action name (a letter, then letters, digits or _) comes back to you as the owner's next turn, [ui-event]{...}[/ui-event], naming the element, the action and its params with $state values read at the press."
+}
diff --git a/server/config/node_allowlist.json b/server/config/node_allowlist.json
index 4a3f4801..b59eb3d5 100644
--- a/server/config/node_allowlist.json
+++ b/server/config/node_allowlist.json
@@ -4,6 +4,7 @@
"start",
"chatTrigger",
"chatReply",
+ "chatUi",
"taskTrigger",
"console",
diff --git a/server/nodes/chat/chat_ui/__init__.py b/server/nodes/chat/chat_ui/__init__.py
new file mode 100644
index 00000000..ea8a5cb8
--- /dev/null
+++ b/server/nodes/chat/chat_ui/__init__.py
@@ -0,0 +1,118 @@
+"""Show UI: the tool an employee uses to put a small interface in its chat
+reply (docs-internal/chat_protocol.md, "Generated UI").
+
+The employee calls ``show_ui`` with a json-render spec. ``services/genui/
+spec.py`` checks it against ``config/chat_genui_catalog.json``: a spec that
+breaks a rule fails the call with every reason, so the model writes it again.
+``services/chat/parts.py`` then shows it: the spec is saved on the chat run as
+a part and streamed to the chat as patches, and when the run ends it is
+sealed into the reply message, where a reload finds it.
+
+Only the agent answering the owner's chat message can show UI. Anywhere else
+(a canvas Run, a delegated agent, a schedule) the call says nothing was
+shown. The tool takes no working step of its own: the UI is what shows.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from services.genui.spec import SpecError, check_spec, describe_catalog
+from services.plugin import NodeContext, NodeUserError, Operation, TaskQueue, ToolNode
+
+
+# Flat on purpose: this IS the LLM tool schema. The spec's shape is in the
+# tool description, generated from the catalog.
+class ChatUiParams(BaseModel):
+ spec: Dict[str, Any] = Field(
+ ...,
+ description='The interface as json-render\'s flat spec: {"root": "<id>", "state": {...}, "elements": {...}}.',
+ )
+
+ model_config = ConfigDict(extra="ignore")
+
+ @field_validator("spec", mode="before")
+ @classmethod
+ def _coerce_spec(cls, value: Any) -> Any:
+ """Some providers send an object argument as a JSON string."""
+ if isinstance(value, str):
+ try:
+ parsed = json.loads(value)
+ except ValueError:
+ return value
+ return parsed
+ return value
+
+
+class ChatUiOutput(BaseModel):
+ """What the model reads back: whether it showed, and what changed."""
+
+ shown: bool = False
+ ui_id: Optional[str] = None
+ elements: Optional[int] = None
+ dropped: Optional[List[Dict[str, str]]] = None
+ notes: Optional[List[str]] = None
+ message: Optional[str] = None
+
+ model_config = ConfigDict(extra="allow")
+
+
+class ChatUiNode(ToolNode):
+ type = "chatUi"
+ display_name = "Show UI"
+ subtitle = "Interface in a reply"
+ group = ("chat", "tool")
+ description = (
+ "Lets an employee show a small interface inside its chat reply: choices, a short form, numbers, "
+ "a chart, buttons."
+ )
+ component_kind = "tool"
+ tool_name = "show_ui"
+ # The description is generated from the catalog; pin it against stale
+ # persisted ToolSchema rows.
+ tool_schema_locked = True
+ tool_description = describe_catalog()
+ handles = ({"name": "output-tool", "kind": "output", "position": "top", "label": "Tool", "role": "tools"},)
+ ui_hints = {"hideRunButton": True}
+ annotations = {"destructive": False, "readonly": False, "open_world": False}
+ task_queue = TaskQueue.DEFAULT
+ chat_step_hidden = True
+
+ Params = ChatUiParams
+ Output = ChatUiOutput
+
+ @Operation("show")
+ async def show(self, ctx: NodeContext, params: ChatUiParams) -> ChatUiOutput:
+ from services.chat.parts import show_ui
+ from services.plugin.deps import get_database
+
+ try:
+ checked = check_spec(params.spec)
+ except SpecError as error:
+ raise NodeUserError(
+ "The interface was not shown. Fix these and call show_ui again: " + "; ".join(error.problems)
+ ) from None
+ stream = ctx.raw.get("chat_stream") if isinstance(ctx.raw, dict) else None
+ tool_call_id = ctx.raw.get("tool_call_id") if isinstance(ctx.raw, dict) else None
+ dropped = checked.dropped or None
+ notes = checked.notes or None
+ if not isinstance(stream, dict) or not isinstance(tool_call_id, str) or not tool_call_id:
+ return ChatUiOutput(
+ shown=False,
+ elements=checked.element_count,
+ dropped=dropped,
+ notes=notes,
+ message="Nothing was shown: an interface shows only in your reply to the owner's chat message.",
+ )
+ ui_id = await show_ui(get_database(), stream, tool_call_id=tool_call_id, spec=checked.spec)
+ return ChatUiOutput(
+ shown=True,
+ ui_id=ui_id,
+ elements=checked.element_count,
+ dropped=dropped,
+ notes=notes,
+ message="Shown under your reply; your text need not repeat what it shows.",
+ )
diff --git a/server/nodes/chat/chat_ui/meta.json b/server/nodes/chat/chat_ui/meta.json
new file mode 100644
index 00000000..339affc0
--- /dev/null
+++ b/server/nodes/chat/chat_ui/meta.json
@@ -0,0 +1,4 @@
+{
+ "color": "#8be9fd",
+ "icon": "lucide:LayoutDashboard"
+}
diff --git a/server/pyproject.toml b/server/pyproject.toml
index 35a9765b..61411d76 100644
--- a/server/pyproject.toml
+++ b/server/pyproject.toml
@@ -55,6 +55,10 @@ dependencies = [
# transitively via mcp; declared explicitly so it survives that
# dependency changing.
"python-multipart>=0.0.20",
+ # Checks the generated UI an employee shows in a chat reply against its
+ # catalog (services/genui/spec.py). Already present transitively via mcp;
+ # declared explicitly for the same reason.
+ "jsonschema>=4.23.0",
# Auth
"bcrypt>=4.2.0",
diff --git a/server/services/chat/handlers.py b/server/services/chat/handlers.py
index adf17d31..6933abc0 100644
--- a/server/services/chat/handlers.py
+++ b/server/services/chat/handlers.py
@@ -138,12 +138,41 @@ async def _answers_session(database: Any, control: Any, session_id: str) -> bool
return False
+async def _ui_event(database: Any, session_id: str, raw: Any) -> Dict[str, Any]:
+ """A button press, checked against the interface it came from. Returns
+ ``{label, meta, prompt}``; raises ``ValueError`` saying why not."""
+ from services.chat import parts
+
+ if not isinstance(raw, dict):
+ raise ValueError("ui_event is {part_id, element_id, action, params}")
+ part_id = raw.get("part_id")
+ part = await parts.find_ui_part(database, session_id, part_id) if isinstance(part_id, str) and part_id else None
+ if part is None:
+ raise ValueError("this chat has no such interface")
+ try:
+ pressed = parts.check_ui_event(part, raw.get("element_id"), raw.get("action"), raw.get("params"))
+ except parts.UiRefused as exc:
+ raise ValueError(str(exc)) from None
+ event = {"part_id": part_id, "element_id": raw["element_id"], "action": raw["action"], "params": pressed["params"]}
+ label = pressed["label"] or str(raw["action"])
+ return {
+ "label": label,
+ "meta": {"ui_event": event},
+ "prompt": parts.ui_event_message(label=label, **event),
+ }
+
+
@ws_handler("message")
async def handle_send_chat_message(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
"""Save the owner's message, start its run, and dispatch it. Answers
``{message_id, run_id, delivery, timestamp}``; ``run_in_progress`` (with
- the live ``run_id``), ``not_running``, ``save_failed``, ``access_denied``
- or ``invalid_request`` otherwise."""
+ the live ``run_id``), ``not_running``, ``save_failed``, ``access_denied``,
+ ``invalid_request`` or ``ui_event_rejected`` otherwise.
+
+ With ``ui_event`` the message is a button pressed in an interface the
+ employee showed: checked against that interface, saved as the owner's
+ message reading the button's label (kind ``action``), and sent to the
+ employee as a ``[ui-event]`` line naming the press."""
message = data.get("message")
if not isinstance(message, str) or not message.strip():
return {"success": False, "error": "invalid_request", "detail": "message must be text"}
@@ -157,6 +186,14 @@ async def handle_send_chat_message(data: Dict[str, Any], websocket: WebSocket) -
except ChatAccessDenied:
return dict(_DENIED)
+ press: Optional[Dict[str, Any]] = None
+ if data.get("ui_event") is not None:
+ try:
+ press = await _ui_event(database, session_id, data["ui_event"])
+ except ValueError as exc:
+ return {"success": False, "error": "ui_event_rejected", "detail": str(exc)}
+ message = press["label"]
+
# The scope rides the envelope's ``workflow_id``, so ``dispatch.emit``
# signals only this workflow's listeners (without it one workflow's chat
# fired every deployed chat trigger). The editor's "default" session
@@ -179,7 +216,10 @@ async def handle_send_chat_message(data: Dict[str, Any], websocket: WebSocket) -
text=message,
track=track,
state="queued" if delivery == "queued" else "pending",
+ kind="action" if press is not None else "message",
+ message_kind="action" if press is not None else "text",
client_message_id=data.get("client_message_id"),
+ meta=press["meta"] if press is not None else None,
)
except ledger.RunInProgress as exc:
return {"success": False, "error": "run_in_progress", "run_id": exc.run.run_id}
@@ -193,7 +233,7 @@ async def handle_send_chat_message(data: Dict[str, Any], websocket: WebSocket) -
if admission.created:
await announce_chat_updated(session_id, "user")
event_data: Dict[str, Any] = {
- "message": message,
+ "message": press["prompt"] if press is not None else message,
"timestamp": timestamp,
"session_id": session_id,
"message_id": row["uid"],
@@ -329,6 +369,31 @@ async def handle_stop_chat_run(data: Dict[str, Any], websocket: WebSocket) -> Di
return {"success": True, "run_id": run.run_id, "state": run.state}
+@ws_handler("part_id")
+async def handle_chat_ui_state(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
+ """What the owner set in an interface the employee showed
+ (``changes: [{path, value}]``, the last value per path winning). Kept on
+ the reply (``parts.ui[].state``), so a reload shows it. Answers the
+ state's new ``state_revision``; ``not_found`` when the session has no
+ such interface, ``invalid_request`` for a change that does not fit."""
+ from services.chat import parts
+
+ session_id = session_id_of(data)
+ database = container.database()
+ try:
+ await authorize_session(database, websocket, session_id)
+ except ChatAccessDenied:
+ return dict(_DENIED)
+ part_id = str(data["part_id"])
+ try:
+ updated = await parts.update_ui_state(database, session_id, part_id, data.get("changes"))
+ except parts.UiRefused as exc:
+ return {"success": False, "error": "invalid_request", "detail": str(exc)}
+ if updated is None:
+ return {"success": False, "error": "not_found"}
+ return {"success": True, "part_id": part_id, "state_revision": updated["state_revision"]}
+
+
@ws_handler()
async def handle_clear_chat_messages(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
"""Clear a session's chat, every generation of it, with its runs. For a
@@ -367,6 +432,7 @@ WS_HANDLERS = {
"chat_unsubscribe": handle_chat_unsubscribe,
"get_chat_run": handle_get_chat_run,
"stop_chat_run": handle_stop_chat_run,
+ "chat_ui_state": handle_chat_ui_state,
"clear_chat_messages": handle_clear_chat_messages,
"save_chat_message": handle_save_chat_message,
}
diff --git a/server/services/chat/ledger.py b/server/services/chat/ledger.py
index 5cecdf89..dd1d02e7 100644
--- a/server/services/chat/ledger.py
+++ b/server/services/chat/ledger.py
@@ -36,7 +36,9 @@ run finishes with outcome ``stopped``. A run still stopping
ended by the watchdog, which also cancels its workflow.
**Steps** (``record_step``) are saved on the run as they finish, so a reload
-can say how long it worked and what it did.
+can say how long it worked and what it did. **Parts** (what its tools
+showed, such as generated UI) are sealed into its reply as it ends
+(``services/chat/parts.py``), before the end is published.
Every transition commits before its event is published, so a client that
reads the run after an event never sees an older state than the event.
@@ -191,14 +193,18 @@ async def admit_message(
client_message_id: Optional[str] = None,
options: Optional[Dict[str, Any]] = None,
attachments: Optional[List[Dict[str, Any]]] = None,
+ meta: Optional[Dict[str, Any]] = None,
) -> Admission:
"""Save the owner's message and, when ``track``, the run that will answer
it. Raises :class:`RunInProgress` when the lane is held, ``ValueError``
- for a malformed ``client_message_id``."""
+ for a malformed ``client_message_id``. ``meta`` goes on the message (a
+ button press keeps its ``ui_event`` there)."""
if state not in ("pending", "queued"):
raise ValueError(f"a run is admitted pending or queued, not {state!r}")
uid = client_message_uid(session_id, client_message_id) if client_message_id is not None else None
- meta = {"client_message_id": client_message_id} if client_message_id is not None else {}
+ meta = dict(meta or {})
+ if client_message_id is not None:
+ meta["client_message_id"] = client_message_id
async with database.reserved_session() as session:
if uid is not None:
found = (await session.execute(select(ChatMessage).where(ChatMessage.uid == uid))).scalar_one_or_none()
@@ -288,6 +294,15 @@ async def post_reply(
uid = f"{uid}.{len(replies) + 1}"
current = await session.get(ChatRun, run.run_id)
stopped = current is not None and current.state in ("stopping", "stopped")
+ # What the run's tools showed so far goes on its first reply, so the
+ # thread never draws the reply without it; the end seals the rest.
+ parts = None
+ if not replies:
+ from models.chat import ChatRunPart
+ from services.chat.parts import grouped_parts
+
+ found = await session.execute(select(ChatRunPart).where(ChatRunPart.run_id == run.run_id).order_by(ChatRunPart.id))
+ parts = grouped_parts(list(found.scalars().all())) or None
row = await database.append_chat_row(
session,
session_id=run.session_id,
@@ -297,6 +312,7 @@ async def post_reply(
uid=uid,
run_id=run.run_id,
status="stopped" if stopped else "complete",
+ parts=parts,
meta={"node_id": node_id},
)
await session.commit()
@@ -420,6 +436,16 @@ async def _settle(database: Any, run: ChatRun, values: Dict[str, Any]) -> Option
return settled
+async def _seal(database: Any, run: ChatRun) -> None:
+ """Put what the run's tools showed on its reply (``services/chat/
+ parts.py``), and tell open threads when that changed the thread."""
+ from services.chat.parts import seal_parts
+ from services.chat_thread import announce_chat_updated
+
+ if await seal_parts(database, run):
+ await announce_chat_updated(run.session_id, "assistant")
+
+
async def _success_values(database: Any, run: ChatRun, outcome: str) -> Dict[str, Any]:
if await _message_exists(database, run.reply_message_uid):
result: Dict[str, Any] = {"reply_message_id": run.reply_message_uid}
@@ -451,6 +477,7 @@ async def finish_run(
return run
if run.state not in ("running", "stopping"):
return None
+ await _seal(database, run)
if run.state == "stopping":
values = await _success_values(database, run, "stopped")
elif success:
@@ -594,6 +621,7 @@ async def _sweep_stopping(
await temporal_cancel(run.temporal_workflow_id, run.temporal_run_id)
except Exception: # noqa: BLE001 - the run ends either way
logger.warning("Could not cancel a stopped run's workflow", run_id=run.run_id, exc_info=True)
+ await _seal(database, run)
return await _settle(database, run, await _success_values(database, run, "stopped"))
@@ -632,6 +660,7 @@ async def _sweep_one(
current = await get_run(database, run.run_id)
if current is None or current.state not in ("running", "stopping"):
return None
+ await _seal(database, current)
if await _message_exists(database, current.reply_message_uid):
return await _settle(database, current, await _success_values(database, current, "stopped" if current.state == "stopping" else "success"))
return await fail_run(database, current, code="interrupted", message="The run ended before it answered.")
diff --git a/server/services/chat/parts.py b/server/services/chat/parts.py
new file mode 100644
index 00000000..a9c77588
--- /dev/null
+++ b/server/services/chat/parts.py
@@ -0,0 +1,364 @@
+"""What a chat run's tools add to its reply (docs-internal/chat_protocol.md,
+"Messages" and "Generated UI").
+
+A tool of the agent answering a run records a **part** on the run
+(``record_part``, keyed so an activity retry writes the same row again) and
+shows it live through the run's ``activity.*`` events. Generated UI is the
+first kind: ``show_ui`` saves the checked spec and publishes it as an empty
+``activity.snapshot`` followed by one ``activity.delta`` per patch
+(``services/genui/patches.py``); the client paces what arrives.
+
+When the run ends, ``seal_parts`` copies its parts into the reply message's
+``parts`` (``{"ui": [...]}``), creating an empty reply when the run showed
+something but wrote nothing, so a reload draws what the run showed. Every
+write here is best effort for the run: a part that cannot be saved is
+logged, and the run goes on.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from collections import OrderedDict
+from typing import Any, Dict, List, Mapping, Optional
+
+from sqlalchemy.exc import IntegrityError
+from sqlmodel import select
+
+from core.logging import get_logger
+from models.chat import ChatRun, ChatRunPart
+from models.database import ChatMessage
+
+logger = get_logger(__name__)
+
+#: The ``activity_type`` of a generated UI's events.
+JSON_RENDER = "json_render"
+#: The kinds of part a reply's ``parts`` holds, in the order they render.
+PART_KINDS = ("ui",)
+
+
+def ui_part_id(run_id: str, tool_call_id: str) -> str:
+ """A UI's id: stable across retries of the call that showed it."""
+ digest = hashlib.sha256(f"{run_id}\x00{tool_call_id}".encode()).hexdigest()[:16]
+ return f"ui_{digest}"
+
+
+async def record_part(database: Any, run_id: str, *, kind: str, key: str, payload: Dict[str, Any]) -> None:
+ """Save a part on its run, replacing an earlier save under the same key."""
+ async with database.reserved_session() as session:
+ result = await session.execute(select(ChatRunPart).where(ChatRunPart.run_id == run_id, ChatRunPart.key == key))
+ part = result.scalar_one_or_none()
+ if part is None:
+ part = ChatRunPart(run_id=run_id, kind=kind, key=key, payload=dict(payload))
+ else:
+ part.kind = kind
+ part.payload = dict(payload)
+ session.add(part)
+ try:
+ await session.commit()
+ except IntegrityError:
+ await session.rollback()
+ raise
+
+
+async def run_parts(database: Any, run_id: str) -> List[ChatRunPart]:
+ """A run's parts, in the order they were first saved."""
+ async with database.get_session() as session:
+ result = await session.execute(select(ChatRunPart).where(ChatRunPart.run_id == run_id).order_by(ChatRunPart.id))
+ return list(result.scalars().all())
+
+
+def _publish(stream: Mapping[str, Any], suffix: str, fields: Dict[str, Any], event_key: str) -> None:
+ try:
+ from services.chat.hub import get_chat_hub
+
+ workflow_id = stream.get("workflow_id")
+ get_chat_hub().publish(
+ run_id=stream["run_id"],
+ session_id=stream["session_id"],
+ workflow_id=workflow_id if isinstance(workflow_id, str) else None,
+ suffix=suffix,
+ fields=fields,
+ event_key=event_key,
+ )
+ except Exception: # noqa: BLE001 - the part is saved; the live view is a courtesy
+ logger.warning("Chat part event could not be published", run_id=stream.get("run_id"), exc_info=True)
+
+
+async def show_ui(database: Any, stream: Mapping[str, Any], *, tool_call_id: str, spec: Dict[str, Any]) -> str:
+ """Save a checked spec on the run and stream it to the chat. Returns the
+ UI's id."""
+ from services.genui.patches import spec_to_patches
+
+ run_id = stream["run_id"]
+ part_id = ui_part_id(run_id, tool_call_id)
+ payload = {
+ "part_id": part_id,
+ "spec": spec,
+ "state": dict(spec.get("state") or {}),
+ "state_revision": 0,
+ "elements": len(spec.get("elements") or {}),
+ }
+ await record_part(database, run_id, kind="ui", key=f"ui:{part_id}", payload=payload)
+ _publish(
+ stream,
+ "activity.snapshot",
+ {
+ "message_id": part_id,
+ "activity_type": JSON_RENDER,
+ "content": {"root": "", "state": {}, "elements": {}},
+ "replace": True,
+ },
+ f"{part_id}:snapshot",
+ )
+ for index, patch in enumerate(spec_to_patches(spec)):
+ _publish(
+ stream,
+ "activity.delta",
+ {"message_id": part_id, "activity_type": JSON_RENDER, "patch": [patch]},
+ f"{part_id}:{index}",
+ )
+ return part_id
+
+
+#: What names one item of each kind, for merging a run's parts into a reply.
+_ITEM_KEYS = {"ui": "part_id"}
+
+
+def grouped_parts(parts: List[ChatRunPart]) -> Dict[str, List[Dict[str, Any]]]:
+ """A run's parts as a reply's ``parts`` holds them: ``{kind: [payload]}``."""
+ grouped: "OrderedDict[str, List[Dict[str, Any]]]" = OrderedDict()
+ for part in parts:
+ if part.kind in PART_KINDS:
+ grouped.setdefault(part.kind, []).append(dict(part.payload or {}))
+ return dict(grouped)
+
+
+def _merged(kind: str, existing: List[Any], incoming: List[Dict[str, Any]]) -> List[Any]:
+ """The reply's items of a kind with the run's new ones added. An item the
+ reply already holds stays as it is there: the owner may have changed it
+ since (an interface's state), and the run's copy is older."""
+ key = _ITEM_KEYS.get(kind)
+ if key is None:
+ return incoming
+ held = {item.get(key) for item in existing if isinstance(item, dict)}
+ return [*existing, *[item for item in incoming if item.get(key) not in held]]
+
+
+async def seal_parts(database: Any, run: ChatRun) -> bool:
+ """Put the run's parts on its reply message (creating an empty reply
+ when it wrote none). Returns whether the thread changed."""
+ try:
+ grouped = grouped_parts(await run_parts(database, run.run_id))
+ if not grouped:
+ return False
+ uid = run.reply_message_uid
+ async with database.reserved_session() as session:
+ reply: Optional[ChatMessage] = None
+ if uid:
+ found = await session.execute(select(ChatMessage).where(ChatMessage.uid == uid))
+ reply = found.scalar_one_or_none()
+ if reply is not None:
+ current = dict(reply.parts or {})
+ merged = {kind: _merged(kind, list(current.get(kind) or []), items) for kind, items in grouped.items()}
+ if all(current.get(kind) == items for kind, items in merged.items()):
+ return False
+ reply.parts = {**current, **merged}
+ session.add(reply)
+ else:
+ current = await session.get(ChatRun, run.run_id)
+ stopped = current is not None and current.state in ("stopping", "stopped")
+ await database.append_chat_row(
+ session,
+ session_id=run.session_id,
+ role="assistant",
+ message="",
+ execution_id=run.run_key,
+ uid=uid,
+ run_id=run.run_id,
+ status="stopped" if stopped else "complete",
+ parts=grouped,
+ meta={"sealed": True},
+ )
+ await session.commit()
+ return True
+ except Exception: # noqa: BLE001 - the run ends either way
+ logger.warning("Chat run parts could not be sealed into the reply", run_id=run.run_id, exc_info=True)
+ return False
+
+
+# ----- an interface the owner uses -------------------------------------------
+
+#: Assistant messages searched for an interface, newest first.
+_SEARCH_MESSAGES = 200
+#: The most a press or a state change may carry.
+_MAX_EVENT_BYTES = 4096
+_MAX_STATE_BYTES = 16384
+_MAX_CHANGES = 32
+
+
+class UiRefused(ValueError):
+ """A press or a state change that does not fit the interface."""
+
+
+def _state_path(path: Any) -> List[str]:
+ from services.genui.spec import canonical_path, load_catalog
+
+ canonical = canonical_path(path, int(load_catalog()["limits"]["max_path_segments"]))
+ if canonical is None:
+ raise UiRefused(f"{path!r} is not a usable state path")
+ return [part.replace("~1", "/").replace("~0", "~") for part in canonical[1:].split("/")]
+
+
+def _set_path(state: Any, segments: List[str], value: Any) -> Any:
+ """``state`` with ``value`` at ``segments``, copied along the way (the
+ client's ``writePath``): missing objects are made, an array index may
+ reach one past the end."""
+ key, rest = segments[0], segments[1:]
+ if isinstance(state, list):
+ if not key.isdigit() or int(key) > len(state):
+ raise UiRefused("a state path points past the end of a list")
+ at = int(key)
+ out = list(state)
+ current = state[at] if at < len(state) else None
+ item = _set_path(current, rest, value) if rest else value
+ if at == len(out):
+ out.append(item)
+ else:
+ out[at] = item
+ return out
+ base = dict(state) if isinstance(state, dict) else {}
+ base[key] = _set_path(base.get(key), rest, value) if rest else value
+ return base
+
+
+def _size(value: Any) -> int:
+ import json
+
+ return len(json.dumps(value, ensure_ascii=False, default=str).encode("utf-8"))
+
+
+async def find_ui_part(database: Any, session_id: str, part_id: str) -> Optional[Dict[str, Any]]:
+ """The interface ``part_id`` in this session: on a saved reply, or on a
+ run whose reply is not saved yet. None when this session has none."""
+ async with database.get_session() as session:
+ result = await session.execute(
+ select(ChatMessage)
+ .where(ChatMessage.session_id == session_id, ChatMessage.role == "assistant")
+ .order_by(ChatMessage.id.desc())
+ .limit(_SEARCH_MESSAGES)
+ )
+ for message in result.scalars().all():
+ for item in (message.parts or {}).get("ui") or []:
+ if isinstance(item, dict) and item.get("part_id") == part_id:
+ return dict(item)
+ result = await session.execute(
+ select(ChatRunPart, ChatRun)
+ .join(ChatRun, ChatRun.run_id == ChatRunPart.run_id)
+ .where(ChatRunPart.key == f"ui:{part_id}", ChatRun.session_id == session_id)
+ )
+ found = result.first()
+ return dict(found[0].payload or {}) if found is not None else None
+
+
+def check_ui_event(part: Mapping[str, Any], element_id: Any, action: Any, params: Any) -> Dict[str, Any]:
+ """A button press, checked against the interface it came from: the
+ element is a Button whose press runs ``action``, and the params name only
+ what its binding declares. Returns ``{label, params}``."""
+ elements = (part.get("spec") or {}).get("elements") or {}
+ element = elements.get(element_id) if isinstance(element_id, str) else None
+ if not isinstance(element, dict) or element.get("type") != "Button":
+ raise UiRefused("the interface has no such button")
+ binding = ((element.get("on") or {}).get("press")) or {}
+ if not isinstance(binding, dict) or binding.get("action") != action:
+ raise UiRefused("that button does not run that action")
+ if params is None:
+ params = {}
+ if not isinstance(params, dict) or _size(params) > _MAX_EVENT_BYTES:
+ raise UiRefused("the press carries more than its button declares")
+ declared = set((binding.get("params") or {}).keys())
+ extra = sorted(set(params) - declared)
+ if extra:
+ raise UiRefused(f"the button does not send {', '.join(extra)}")
+ label = (element.get("props") or {}).get("label")
+ return {"label": label if isinstance(label, str) else "", "params": dict(params)}
+
+
+def ui_event_message(*, part_id: str, element_id: str, label: str, action: str, params: Mapping[str, Any]) -> str:
+ """What the employee reads for a button press: one bracketed line, so the
+ agent's prompt can say such lines come from OpenCompany, not the owner."""
+ import json
+
+ payload = {"ui_id": part_id, "element": element_id, "label": label, "action": action, "params": dict(params)}
+ return f"[ui-event]{json.dumps(payload, ensure_ascii=False, separators=(', ', ': '))}[/ui-event]"
+
+
+async def update_ui_state(database: Any, session_id: str, part_id: str, changes: Any) -> Optional[Dict[str, Any]]:
+ """Apply what the owner set (``[{path, value}]``, the last value per path
+ winning) to the interface's saved state. Returns ``{state,
+ state_revision}``; :class:`UiRefused` for a change that does not fit, or
+ None when the session has no such interface."""
+ if not isinstance(changes, list) or not changes or len(changes) > _MAX_CHANGES:
+ raise UiRefused(f"changes is a list of 1 to {_MAX_CHANGES} {{path, value}}")
+ parsed = []
+ for change in changes:
+ if not isinstance(change, dict) or "path" not in change:
+ raise UiRefused("each change is {path, value}")
+ if _size(change.get("value")) > _MAX_EVENT_BYTES:
+ raise UiRefused("a value is too large")
+ parsed.append((_state_path(change["path"]), change.get("value")))
+
+ def applied(item: Mapping[str, Any]) -> Dict[str, Any]:
+ state = item.get("state") if isinstance(item.get("state"), dict) else dict((item.get("spec") or {}).get("state") or {})
+ for segments, value in parsed:
+ state = _set_path(state, segments, value)
+ if _size(state) > _MAX_STATE_BYTES:
+ raise UiRefused("the interface's state is too large")
+ return {**item, "state": state, "state_revision": int(item.get("state_revision") or 0) + 1}
+
+ async with database.reserved_session() as session:
+ result = await session.execute(
+ select(ChatMessage)
+ .where(ChatMessage.session_id == session_id, ChatMessage.role == "assistant")
+ .order_by(ChatMessage.id.desc())
+ .limit(_SEARCH_MESSAGES)
+ )
+ for message in result.scalars().all():
+ items = (message.parts or {}).get("ui") or []
+ for index, item in enumerate(items):
+ if isinstance(item, dict) and item.get("part_id") == part_id:
+ updated = applied(item)
+ ui = [*items[:index], updated, *items[index + 1:]]
+ message.parts = {**(message.parts or {}), "ui": ui}
+ session.add(message)
+ await session.commit()
+ return {"state": updated["state"], "state_revision": updated["state_revision"]}
+ result = await session.execute(
+ select(ChatRunPart)
+ .join(ChatRun, ChatRun.run_id == ChatRunPart.run_id)
+ .where(ChatRunPart.key == f"ui:{part_id}", ChatRun.session_id == session_id)
+ )
+ part = result.scalar_one_or_none()
+ if part is None:
+ return None
+ updated = applied(part.payload or {})
+ part.payload = updated
+ session.add(part)
+ await session.commit()
+ return {"state": updated["state"], "state_revision": updated["state_revision"]}
+
+
+__all__ = [
+ "JSON_RENDER",
+ "PART_KINDS",
+ "UiRefused",
+ "check_ui_event",
+ "find_ui_part",
+ "grouped_parts",
+ "record_part",
+ "run_parts",
+ "seal_parts",
+ "show_ui",
+ "ui_event_message",
+ "ui_part_id",
+ "update_ui_state",
+]
diff --git a/server/services/chat/reducer.py b/server/services/chat/reducer.py
index a431907e..95c0b937 100644
--- a/server/services/chat/reducer.py
+++ b/server/services/chat/reducer.py
@@ -6,9 +6,10 @@ that subscribes mid-run starts from the same state the events before would
have built. The hub keeps one live snapshot per run it publishes for
(``services/chat/hub.py``); ``merge_snapshot`` lays it over the stored row.
-Lifecycle, step and text events are folded. Activity events (generated UI,
-approvals, sources) are not yet: nothing publishes them before generated UI
-lands, and folding them needs the RFC 6902 patch code that comes with it.
+Lifecycle, step, text and activity events are folded: an activity (a part
+the run is building, such as a generated UI) keeps its content, replaced by
+``activity.snapshot`` and patched by ``activity.delta``
+(``services/genui/patches.py``).
"""
from __future__ import annotations
@@ -118,6 +119,15 @@ def _segment(snapshot: Dict[str, Any], message_id: str) -> Dict[str, Any]:
return segment
+def _activity(snapshot: Dict[str, Any], message_id: str, activity_type: str) -> Dict[str, Any]:
+ for activity in snapshot["activities"]:
+ if activity.get("message_id") == message_id:
+ return activity
+ activity: Dict[str, Any] = {"message_id": message_id, "activity_type": activity_type, "content": None, "patches": 0}
+ snapshot["activities"].append(activity)
+ return activity
+
+
def apply_event(snapshot: Mapping[str, Any], event: Mapping[str, Any]) -> Dict[str, Any]:
"""Fold one ``chat_run_event`` envelope (as a dict) into ``snapshot``.
@@ -168,6 +178,19 @@ def apply_event(snapshot: Mapping[str, Any], event: Mapping[str, Any]) -> Dict[s
elif suffix == "text.ended":
segment = _segment(out, str(data.get("message_id")))
segment["final"] = bool(data.get("final"))
+ elif suffix == "activity.snapshot":
+ activity = _activity(out, str(data.get("message_id")), str(data.get("activity_type") or ""))
+ if data.get("replace", True) or activity.get("content") is None:
+ activity.update(
+ {"activity_type": data.get("activity_type"), "content": deepcopy(data.get("content")), "patches": 0}
+ )
+ elif suffix == "activity.delta":
+ from services.genui.patches import apply_patch
+
+ activity = _activity(out, str(data.get("message_id")), str(data.get("activity_type") or ""))
+ patch = data.get("patch") if isinstance(data.get("patch"), list) else []
+ activity["content"] = apply_patch(activity.get("content"), patch)
+ activity["patches"] = int(activity.get("patches") or 0) + len(patch)
elif suffix == "custom":
name = data.get("name")
value = data.get("value") or {}
diff --git a/server/services/genui/__init__.py b/server/services/genui/__init__.py
new file mode 100644
index 00000000..36bd709f
--- /dev/null
+++ b/server/services/genui/__init__.py
@@ -0,0 +1,7 @@
+"""Generated UI shown inside chat replies (docs-internal/chat_protocol.md,
+"Generated UI"): checking a spec against ``config/chat_genui_catalog.json``
+(``spec.py``) and streaming it as JSON patches (``patches.py``).
+
+Core, so it never imports ``nodes/``; the ``show_ui`` tool
+(``nodes/chat/chat_ui``) is its one producer.
+"""
diff --git a/server/services/genui/patches.py b/server/services/genui/patches.py
new file mode 100644
index 00000000..446c906e
--- /dev/null
+++ b/server/services/genui/patches.py
@@ -0,0 +1,147 @@
+"""A generated UI as a stream of JSON patches, and applying them.
+
+A reply's UI reaches the chat as RFC 6902 patches on an empty spec
+(docs-internal/chat_protocol.md, "Generated UI"): ``add /root``, ``add
+/state``, then one ``add /elements/<id>`` per element, depth first from the
+root, each id escaped as RFC 6901 says. ``spec_to_patches`` writes that
+stream; the design handoff's examples hold it line for line
+(``client/src/features/chat/__fixtures__/*.patches.jsonl``), and the client
+writes the same one (``client/src/lib/jsonRender/reveal.ts``).
+
+``apply_patch`` folds patches into an activity's content for the run
+snapshot (``services/chat/reducer.py``): ``add``, ``replace`` and ``remove``
+only, a copy each time, nothing through ``__proto__``, ``constructor`` or
+``prototype``, and an operation that does not apply is skipped. The client
+applies them the same way (``client/src/lib/agui/patch.ts``).
+"""
+
+from __future__ import annotations
+
+import copy
+from typing import Any, Dict, Iterable, List, Mapping, Optional
+
+FORBIDDEN_SEGMENTS = frozenset({"__proto__", "constructor", "prototype"})
+
+
+def escape_pointer(token: str) -> str:
+ return token.replace("~", "~0").replace("/", "~1")
+
+
+def unescape_pointer(token: str) -> str:
+ return token.replace("~1", "/").replace("~0", "~")
+
+
+def spec_to_patches(spec: Mapping[str, Any]) -> List[Dict[str, Any]]:
+ """The patch stream that builds ``spec`` from ``{root: "", state: {},
+ elements: {}}``: root, state, then every element the root reaches,
+ depth first, each once."""
+ elements: Mapping[str, Any] = spec.get("elements") or {}
+ patches: List[Dict[str, Any]] = [
+ {"op": "add", "path": "/root", "value": spec.get("root")},
+ {"op": "add", "path": "/state", "value": spec.get("state") or {}},
+ ]
+ seen = set()
+
+ def walk(element_id: str) -> None:
+ element = elements.get(element_id)
+ if element is None or element_id in seen:
+ return
+ seen.add(element_id)
+ patches.append({"op": "add", "path": f"/elements/{escape_pointer(element_id)}", "value": element})
+ for child in element.get("children") or []:
+ walk(child)
+
+ root = spec.get("root")
+ if isinstance(root, str):
+ walk(root)
+ return patches
+
+
+def _segments(path: Any) -> Optional[List[str]]:
+ if not isinstance(path, str):
+ return None
+ if path == "":
+ return []
+ if not path.startswith("/"):
+ return None
+ segments = [unescape_pointer(part) for part in path[1:].split("/")]
+ if any(part in FORBIDDEN_SEGMENTS for part in segments):
+ return None
+ return segments
+
+
+class _Refused(Exception):
+ pass
+
+
+def _write(node: Any, segments: List[str], index: int, op: str, value: Any) -> Any:
+ key = segments[index]
+ last = index == len(segments) - 1
+ if isinstance(node, list):
+ if key == "-":
+ if op != "add" or not last:
+ raise _Refused
+ at = len(node)
+ else:
+ try:
+ at = int(key)
+ except ValueError:
+ raise _Refused from None
+ if at < 0 or at > len(node) or (not key.isdigit()):
+ raise _Refused
+ out = list(node)
+ if not last:
+ if at >= len(node):
+ raise _Refused
+ out[at] = _write(node[at], segments, index + 1, op, value)
+ return out
+ if op == "add":
+ out.insert(at, copy.deepcopy(value))
+ elif at >= len(node):
+ raise _Refused
+ elif op == "replace":
+ out[at] = copy.deepcopy(value)
+ else:
+ del out[at]
+ return out
+ if not isinstance(node, dict):
+ raise _Refused
+ if not last:
+ if key not in node:
+ raise _Refused
+ return {**node, key: _write(node[key], segments, index + 1, op, value)}
+ if op == "remove":
+ if key not in node:
+ raise _Refused
+ return {name: item for name, item in node.items() if name != key}
+ if op == "replace" and key not in node:
+ raise _Refused
+ return {**node, key: copy.deepcopy(value)}
+
+
+def apply_patch_op(content: Any, op: Mapping[str, Any]) -> Any:
+ """``content`` with one operation applied; ``content`` itself when the
+ operation does not apply."""
+ kind = op.get("op") if isinstance(op, Mapping) else None
+ if kind not in ("add", "replace", "remove"):
+ return content
+ segments = _segments(op.get("path"))
+ if segments is None:
+ return content
+ if not segments:
+ return content if kind == "remove" else copy.deepcopy(op.get("value"))
+ try:
+ return _write(content, segments, 0, kind, op.get("value"))
+ except _Refused:
+ return content
+
+
+def apply_patch(content: Any, ops: Iterable[Mapping[str, Any]]) -> Any:
+ """``content`` with every operation applied in order, skipping the ones
+ that do not apply."""
+ for op in ops:
+ content = apply_patch_op(content, op)
+ return content
+
+
+__all__ = ["apply_patch", "apply_patch_op", "escape_pointer", "spec_to_patches", "unescape_pointer"]
diff --git a/server/services/genui/spec.py b/server/services/genui/spec.py
new file mode 100644
index 00000000..182173c1
--- /dev/null
+++ b/server/services/genui/spec.py
@@ -0,0 +1,570 @@
+"""Generated UI in a chat reply: checking the spec an employee writes.
+
+The ``show_ui`` tool (``nodes/chat/chat_ui``) hands the model's spec here. It
+is json-render's flat shape, ``{root, state, elements}``, checked against the
+catalog in ``config/chat_genui_catalog.json`` (docs-internal/chat_protocol.md,
+"Generated UI"):
+
+- **Refused** (:class:`SpecError`, every problem listed, so the tool fails and
+ the model writes it again): a spec that is not an object; a root that is not
+ an element; more elements, more depth or more bytes than the limits allow; a
+ child that is not an element, or not one its parent may hold; a cycle; a
+ prop its component's schema refuses; a state path through ``__proto__``,
+ ``constructor`` or ``prototype``; an action the chat keeps for itself.
+- **Dropped**, and reported back (``dropped``, ``notes``): elements of a type
+ the catalog does not have, elements the root cannot reach, element fields
+ json-render must not see (``watch``, ``repeat``, ...), props a component
+ does not declare, and expressions that only ``repeat`` gives meaning to.
+
+What comes back is the spec as it will be drawn, in canonical form: every
+state path written ``/a/b``, every element keeping only ``type``, ``props``,
+``children``, ``visible`` and ``on``, the elements the root reaches only. The
+client sanitizes again before rendering (``client/src/lib/jsonRender``); this
+side's job is to tell the model before anything is shown.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Dict, List, Mapping, Optional, Tuple
+
+CATALOG_PATH = Path(__file__).resolve().parents[2] / "config" / "chat_genui_catalog.json"
+
+FORBIDDEN_SEGMENTS = frozenset({"__proto__", "constructor", "prototype"})
+#: Element ids json-render can key on (client/src/lib/jsonRender/sanitize.ts).
+_ID = re.compile(r"^[A-Za-z0-9_.:-]+$")
+#: Action and event names.
+_NAME = re.compile(r"^[A-Za-z][A-Za-z0-9_]{0,63}$")
+#: Fields an element keeps; anything else is dropped.
+_ELEMENT_FIELDS = ("type", "props", "children", "visible", "on")
+#: Expressions that only mean something inside ``repeat`` or call app code.
+_DROPPED_EXPRESSIONS = ("$computed", "$item", "$index", "$bindItem")
+_EXPRESSIONS = ("$state", "$bindState", "$cond", "$template", *_DROPPED_EXPRESSIONS)
+#: Actions json-render runs itself that a reply may not use.
+_RESERVED_ACTIONS = frozenset({"pushState", "removeState", "push", "pop", "validateForm"})
+_COMPARISONS = ("eq", "neq")
+_ORDERINGS = ("gt", "gte", "lt", "lte")
+_TEMPLATE = re.compile(r"\$\{([^}]+)\}")
+
+
+class SpecError(ValueError):
+ """The spec cannot be shown; ``problems`` says every reason found."""
+
+ def __init__(self, problems: List[str]) -> None:
+ self.problems = list(problems)
+ super().__init__("; ".join(self.problems))
+
+
+@dataclass(frozen=True)
+class CheckedSpec:
+ #: ``{root, state, elements}`` as it will be drawn.
+ spec: Dict[str, Any]
+ #: ``[{id, reason}]`` for each element left out.
+ dropped: List[Dict[str, str]] = field(default_factory=list)
+ #: Everything else changed on the way, in words.
+ notes: List[str] = field(default_factory=list)
+
+ @property
+ def element_count(self) -> int:
+ return len(self.spec["elements"])
+
+
+@lru_cache(maxsize=1)
+def load_catalog() -> Mapping[str, Any]:
+ return json.loads(CATALOG_PATH.read_text(encoding="utf-8"))
+
+
+# ----- paths -----------------------------------------------------------------
+
+
+def _unescape(token: str) -> str:
+ return token.replace("~1", "/").replace("~0", "~")
+
+
+def _escape(token: str) -> str:
+ return token.replace("~", "~0").replace("/", "~1")
+
+
+def canonical_path(path: Any, max_segments: int) -> Optional[str]:
+ """A usable state path as ``/a/b``, or None (the same rule as the
+ client's ``paths.ts``: empty segments skipped, prototype keys refused)."""
+ if not isinstance(path, str):
+ return None
+ segments = [_unescape(part) for part in path.split("/") if part]
+ if not segments or len(segments) > max_segments or any(part in FORBIDDEN_SEGMENTS for part in segments):
+ return None
+ return "/" + "/".join(_escape(part) for part in segments)
+
+
+# ----- the checker -----------------------------------------------------------
+
+
+def _is_record(value: Any) -> bool:
+ return isinstance(value, dict)
+
+
+def _expression_key(value: Any) -> Optional[str]:
+ if not _is_record(value):
+ return None
+ for key in _EXPRESSIONS:
+ if key in value:
+ return key
+ return None
+
+
+def _describe(error: Any) -> str:
+ where = "/".join(str(part) for part in error.absolute_path)
+ return f"{where}: {error.message}" if where else error.message
+
+
+class _Checker:
+ def __init__(self, catalog: Mapping[str, Any]) -> None:
+ self.catalog = catalog
+ self.components: Mapping[str, Any] = catalog["components"]
+ self.actions: Mapping[str, Any] = catalog.get("actions") or {}
+ limits = catalog["limits"]
+ self.max_elements = int(limits["max_elements"])
+ self.max_depth = int(limits["max_depth"])
+ self.max_bytes = int(limits["max_bytes"])
+ self.max_children = int(limits["max_children"])
+ self.max_id = int(limits["max_id_length"])
+ self.max_segments = int(limits["max_path_segments"])
+ self.problems: List[str] = []
+ self.notes: List[str] = []
+ self.dropped: List[Dict[str, str]] = []
+
+ # -- helpers ------------------------------------------------------------
+
+ def refuse(self, message: str) -> None:
+ self.problems.append(message)
+
+ def path(self, raw: Any, where: str) -> Optional[str]:
+ path = canonical_path(raw, self.max_segments)
+ if path is None:
+ self.refuse(
+ f"{where}: {raw!r} is not a usable state path (\"/name\", at most {self.max_segments} "
+ "parts, no __proto__, constructor or prototype)"
+ )
+ return path
+
+ def usable_id(self, value: Any) -> bool:
+ return (
+ isinstance(value, str)
+ and 0 < len(value) <= self.max_id
+ and bool(_ID.match(value))
+ and value not in FORBIDDEN_SEGMENTS
+ )
+
+ def json_value(self, value: Any, where: str, depth: int = 0) -> Any:
+ """Plain JSON with prototype keys refused."""
+ if depth > 8:
+ self.refuse(f"{where}: nested too deep")
+ return None
+ if isinstance(value, dict):
+ out: Dict[str, Any] = {}
+ for key, item in value.items():
+ if not isinstance(key, str) or key in FORBIDDEN_SEGMENTS:
+ self.refuse(f"{where}: the key {key!r} is not allowed")
+ continue
+ out[key] = self.json_value(item, f"{where}/{key}", depth + 1)
+ return out
+ if isinstance(value, list):
+ return [self.json_value(item, f"{where}/{index}", depth + 1) for index, item in enumerate(value)]
+ if isinstance(value, float) and value != value: # NaN
+ self.refuse(f"{where}: not a number")
+ return None
+ return value
+
+ # -- expressions and conditions -----------------------------------------
+
+ def expression(self, value: Dict[str, Any], where: str, *, bind_prop: bool) -> Tuple[bool, Any]:
+ """``(keep, cleaned)`` for an expression-valued prop or param."""
+ key = _expression_key(value)
+ if key in _DROPPED_EXPRESSIONS:
+ self.notes.append(f"{where}: dropped {key}, which only works inside repeat")
+ return False, None
+ if key == "$bindState":
+ if not bind_prop:
+ self.refuse(f"{where}: only an input's bound prop may use $bindState; read the state with $state")
+ return False, None
+ path = self.path(value["$bindState"], where)
+ return path is not None, {"$bindState": path}
+ if key == "$state":
+ path = self.path(value["$state"], where)
+ return path is not None, {"$state": path}
+ if key == "$template":
+ template = value["$template"]
+ if not isinstance(template, str):
+ self.refuse(f"{where}: $template must be a string")
+ return False, None
+
+ def placeholder(match: "re.Match[str]") -> str:
+ path = self.path(match.group(1).strip(), where)
+ return "${" + path + "}" if path else ""
+
+ return True, {"$template": _TEMPLATE.sub(placeholder, template)}
+ # $cond
+ condition = self.condition(value.get("$cond"), where)
+ branches = {}
+ for branch in ("$then", "$else"):
+ raw = value.get(branch)
+ if _expression_key(raw):
+ keep, cleaned = self.expression(raw, f"{where}{branch}", bind_prop=False)
+ branches[branch] = cleaned if keep else None
+ else:
+ branches[branch] = self.json_value(raw, f"{where}{branch}")
+ return True, {"$cond": condition, **branches}
+
+ def condition(self, condition: Any, where: str) -> Any:
+ if condition is None or isinstance(condition, bool):
+ return condition if condition is not None else True
+ if isinstance(condition, list):
+ return {"$and": [self.condition(item, where) for item in condition]}
+ if not _is_record(condition):
+ self.refuse(f"{where}: a condition is true, false, a list, or {{\"$state\": \"/path\", ...}}")
+ return False
+ for joined in ("$and", "$or"):
+ if joined in condition:
+ items = condition[joined]
+ if not isinstance(items, list):
+ self.refuse(f"{where}: {joined} takes a list")
+ return False
+ return {joined: [self.condition(item, where) for item in items]}
+ if "$state" not in condition:
+ self.refuse(f"{where}: a condition reads the state with {{\"$state\": \"/path\"}}")
+ return False
+ path = self.path(condition["$state"], where)
+ out: Dict[str, Any] = {"$state": path}
+ for op in _COMPARISONS:
+ if op in condition:
+ operand = condition[op]
+ if _is_record(operand) and "$state" in operand:
+ out[op] = {"$state": self.path(operand["$state"], where)}
+ else:
+ out[op] = self.json_value(operand, f"{where}.{op}")
+ for op in _ORDERINGS:
+ if op in condition:
+ operand = condition[op]
+ if isinstance(operand, (int, float)) and not isinstance(operand, bool):
+ out[op] = operand
+ elif _is_record(operand) and "$state" in operand:
+ out[op] = {"$state": self.path(operand["$state"], where)}
+ else:
+ self.refuse(f"{where}: {op} compares with a number")
+ if condition.get("not"):
+ out["not"] = True
+ unknown = sorted(set(condition) - {"$state", "not", *_COMPARISONS, *_ORDERINGS})
+ if unknown:
+ self.notes.append(f"{where}: ignored {', '.join(unknown)} in a condition")
+ return out
+
+ # -- one element --------------------------------------------------------
+
+ def props(self, element_id: str, type_name: str, raw: Any) -> Dict[str, Any]:
+ from jsonschema import Draft202012Validator
+
+ component = self.components[type_name]
+ schema = component["props"]
+ declared: Mapping[str, Any] = schema.get("properties") or {}
+ bind = component.get("bind")
+ where = f"element {element_id!r} ({type_name})"
+ if raw is None:
+ raw = {}
+ if not _is_record(raw):
+ self.refuse(f"{where}: props must be an object")
+ return {}
+ literal: Dict[str, Any] = {}
+ dynamic: Dict[str, Any] = {}
+ for key, value in raw.items():
+ if key not in declared:
+ self.notes.append(f"{where}: dropped the prop {key!r}, which {type_name} does not have")
+ continue
+ if _expression_key(value):
+ keep, cleaned = self.expression(value, f"{where}.{key}", bind_prop=key == bind)
+ if keep:
+ dynamic[key] = cleaned
+ continue
+ literal[key] = self.json_value(value, f"{where}.{key}")
+ required = [name for name in schema.get("required") or [] if name not in dynamic]
+ checked = {**schema, "required": required}
+ for error in sorted(Draft202012Validator(checked).iter_errors(literal), key=lambda item: list(item.absolute_path)):
+ self.refuse(f"{where}: {_describe(error)}")
+ return {**literal, **dynamic}
+
+ def binding(self, element_id: str, raw: Any) -> Optional[Dict[str, Any]]:
+ from jsonschema import Draft202012Validator
+
+ where = f"element {element_id!r} on.press"
+ if not _is_record(raw):
+ self.refuse(f"{where}: an action binding is {{\"action\": \"name\", \"params\": {{...}}}}")
+ return None
+ action = raw.get("action")
+ if not isinstance(action, str) or not _NAME.match(action) or action in FORBIDDEN_SEGMENTS:
+ self.refuse(f"{where}: {action!r} is not an action name (a letter, then letters, digits or _)")
+ return None
+ if action in _RESERVED_ACTIONS:
+ self.refuse(f"{where}: {action} is not available in a reply")
+ return None
+ params = raw.get("params", {})
+ if params is None:
+ params = {}
+ if not _is_record(params):
+ self.refuse(f"{where}: params must be an object")
+ return None
+ literal: Dict[str, Any] = {}
+ dynamic: Dict[str, Any] = {}
+ for key, value in params.items():
+ if not isinstance(key, str) or key in FORBIDDEN_SEGMENTS or key.startswith("__"):
+ self.refuse(f"{where}: the param {key!r} is not allowed")
+ continue
+ if _expression_key(value):
+ keep, cleaned = self.expression(value, f"{where}.params.{key}", bind_prop=False)
+ if keep:
+ dynamic[key] = cleaned
+ continue
+ literal[key] = self.json_value(value, f"{where}.params.{key}")
+ declared = self.actions.get(action)
+ if declared is not None:
+ schema = declared.get("params") or {"type": "object"}
+ required = [name for name in schema.get("required") or [] if name not in dynamic]
+ for error in Draft202012Validator({**schema, "required": required}).iter_errors(literal):
+ self.refuse(f"{where} ({action}): {_describe(error)}")
+ if action == "setState" and "statePath" in literal:
+ literal["statePath"] = self.path(literal["statePath"], f"{where}.params.statePath")
+ unknown = sorted(set(raw) - {"action", "params"})
+ if unknown:
+ self.notes.append(f"{where}: dropped {', '.join(unknown)} from the action binding")
+ binding: Dict[str, Any] = {"action": action}
+ if literal or dynamic:
+ binding["params"] = {**literal, **dynamic}
+ return binding
+
+ def element(self, element_id: str, raw: Any) -> Optional[Dict[str, Any]]:
+ if not _is_record(raw):
+ self.refuse(f"element {element_id!r}: an element is {{\"type\": ..., \"props\": {{...}}}}")
+ return None
+ type_name = raw.get("type")
+ if type_name not in self.components:
+ self.dropped.append({"id": element_id, "reason": f"unknown type {type_name!r}"})
+ return None
+ component = self.components[type_name]
+ extra = sorted(set(raw) - set(_ELEMENT_FIELDS))
+ if extra:
+ self.notes.append(f"element {element_id!r}: dropped {', '.join(extra)}")
+ element: Dict[str, Any] = {"type": type_name, "props": self.props(element_id, type_name, raw.get("props"))}
+
+ children = raw.get("children")
+ if children not in (None, []):
+ if not component.get("children"):
+ self.refuse(f"element {element_id!r} ({type_name}) cannot hold children")
+ elif not isinstance(children, list) or not all(isinstance(child, str) for child in children):
+ self.refuse(f"element {element_id!r}: children is a list of element ids")
+ elif len(children) > self.max_children:
+ self.refuse(f"element {element_id!r}: more than {self.max_children} children")
+ elif len(set(children)) != len(children):
+ self.refuse(f"element {element_id!r}: a child is listed twice")
+ else:
+ element["children"] = list(children)
+ elif component.get("children"):
+ element["children"] = []
+
+ if "visible" in raw:
+ element["visible"] = self.condition(raw["visible"], f"element {element_id!r} visible")
+
+ on = raw.get("on")
+ if on is not None:
+ events = component.get("events") or []
+ if not _is_record(on):
+ self.refuse(f"element {element_id!r}: on maps an event to an action binding")
+ else:
+ kept = {}
+ for event, binding in on.items():
+ if event not in events:
+ self.notes.append(f"element {element_id!r}: dropped the event {event!r}, which {type_name} does not have")
+ continue
+ cleaned = self.binding(element_id, binding)
+ if cleaned is not None:
+ kept[event] = cleaned
+ if kept:
+ element["on"] = kept
+ return element
+
+ # -- the whole spec -----------------------------------------------------
+
+ def check(self, raw: Any) -> CheckedSpec:
+ if not _is_record(raw):
+ raise SpecError(["the spec is an object: {\"root\": \"<id>\", \"state\": {...}, \"elements\": {...}}"])
+ size = len(json.dumps(raw, ensure_ascii=False, default=str).encode("utf-8"))
+ if size > self.max_bytes:
+ raise SpecError([f"the spec is {size} bytes; at most {self.max_bytes}"])
+ elements_raw = raw.get("elements")
+ if not _is_record(elements_raw) or not elements_raw:
+ raise SpecError(["elements must map element ids to elements"])
+ root = raw.get("root")
+ if not self.usable_id(root):
+ raise SpecError([f"root must name an element (letters, digits and _.:-, at most {self.max_id})"])
+
+ state_raw = raw.get("state", {})
+ if state_raw is None:
+ state_raw = {}
+ if not _is_record(state_raw):
+ self.refuse("state must be an object")
+ state_raw = {}
+ state = self.json_value(state_raw, "state")
+
+ elements: Dict[str, Dict[str, Any]] = {}
+ for element_id, element_raw in elements_raw.items():
+ if not self.usable_id(element_id):
+ self.refuse(f"{element_id!r} is not a usable element id (letters, digits and _.:-, at most {self.max_id})")
+ continue
+ element = self.element(element_id, element_raw)
+ if element is not None:
+ elements[element_id] = element
+
+ dropped_ids = {item["id"] for item in self.dropped}
+ if root not in elements:
+ self.refuse(f"the root {root!r} is not an element" + (" of a known type" if root in dropped_ids else ""))
+ raise SpecError(self.problems)
+
+ # Reach the tree from the root: every child an element it may hold,
+ # no cycles, not too deep.
+ reached: List[str] = []
+ visiting: set = set()
+
+ def walk(element_id: str, depth: int, parent: Optional[str]) -> None:
+ if element_id in visiting:
+ self.refuse(f"element {element_id!r} contains itself")
+ return
+ if element_id in reached:
+ self.refuse(f"element {element_id!r} has two parents")
+ return
+ if depth > self.max_depth:
+ self.refuse(f"the UI is nested more than {self.max_depth} deep at {element_id!r}")
+ return
+ reached.append(element_id)
+ visiting.add(element_id)
+ element = elements[element_id]
+ allowed = self.components[element["type"]].get("children")
+ kept_children = []
+ for child in element.get("children", []):
+ if child in dropped_ids:
+ self.notes.append(f"element {element_id!r}: left out the child {child!r} (unknown type)")
+ continue
+ if child not in elements:
+ self.refuse(f"element {element_id!r}: the child {child!r} is not an element")
+ continue
+ child_type = elements[child]["type"]
+ if allowed != "any" and child_type not in allowed:
+ self.refuse(f"element {element_id!r} ({element['type']}) cannot hold {child_type} {child!r}; it holds {', '.join(allowed)}")
+ continue
+ kept_children.append(child)
+ walk(child, depth + 1, element_id)
+ if "children" in element:
+ element["children"] = kept_children
+ visiting.discard(element_id)
+
+ walk(root, 1, None)
+ if len(reached) > self.max_elements:
+ self.refuse(f"the UI has {len(reached)} elements; at most {self.max_elements}")
+ for element_id in elements:
+ if element_id not in reached:
+ self.dropped.append({"id": element_id, "reason": "not reachable from the root"})
+ if self.problems:
+ raise SpecError(self.problems)
+ spec = {"root": root, "state": state, "elements": {element_id: elements[element_id] for element_id in reached}}
+ return CheckedSpec(spec=spec, dropped=list(self.dropped), notes=list(self.notes))
+
+
+def check_spec(raw: Any, catalog: Optional[Mapping[str, Any]] = None) -> CheckedSpec:
+ """The spec as it will be drawn, or :class:`SpecError` saying why not."""
+ return _Checker(catalog or load_catalog()).check(raw)
+
+
+# ----- the tool description --------------------------------------------------
+
+
+def _type_text(schema: Mapping[str, Any]) -> str:
+ if "enum" in schema:
+ return "|".join(json.dumps(value) for value in schema["enum"])
+ kind = schema.get("type")
+ if isinstance(kind, list):
+ return "|".join(kind)
+ if kind == "array":
+ items = schema.get("items") or {}
+ if items.get("type") == "object":
+ return f"[{_object_text(items)}]"
+ return f"[{_type_text(items)}]"
+ if kind == "object":
+ return _object_text(schema)
+ return str(kind or "any")
+
+
+def _object_text(schema: Mapping[str, Any]) -> str:
+ required = set(schema.get("required") or [])
+ parts = []
+ for name, prop in (schema.get("properties") or {}).items():
+ mark = "" if name in required else "?"
+ parts.append(f"{name}{mark}: {_type_text(prop)}")
+ return "{" + ", ".join(parts) + "}"
+
+
+def describe_catalog(catalog: Optional[Mapping[str, Any]] = None) -> str:
+ """The show_ui tool's description, from the catalog. The same catalog
+ always gives the same text, byte for byte."""
+ catalog = catalog or load_catalog()
+ limits = catalog["limits"]
+ lines = [
+ "Show the owner a small interface inside your reply: a choice to make, a short form, numbers, a chart, "
+ "buttons. Use it when that says it better than words; otherwise just answer. Write your reply as usual: "
+ "the interface shows under it.",
+ "",
+ "The spec is json-render's flat shape: {\"root\": \"<id>\", \"state\": {...}, \"elements\": {\"<id>\": "
+ "{\"type\": \"<Component>\", \"props\": {...}, \"children\": [\"<id>\", ...], \"visible\": <condition>, "
+ "\"on\": {\"press\": {\"action\": \"<name>\", \"params\": {...}}}}}}. Element ids are letters, digits and _.:-.",
+ "",
+ "Components:",
+ ]
+ for name, component in catalog["components"].items():
+ role = component["role"]
+ children = component.get("children")
+ held = ""
+ if children == "any":
+ held = "; holds any components"
+ elif children:
+ held = "; holds " + ", ".join(children)
+ bind = f"; binds {component['bind']}" if component.get("bind") else ""
+ lines.append(f"- {name} ({role}{held}{bind}): {component['description']} Props: {_object_text(component['props'])}.")
+ lines += [
+ "",
+ "State: an input reads and writes its bound prop with {\"$bindState\": \"/path\"}; any prop may read the "
+ "state with {\"$state\": \"/path\"} or {\"$template\": \"Hi ${/name}\"}. Put each bound value in \"state\" "
+ "first. visible: {\"$state\": \"/path\"} (truthy), with \"eq\"/\"neq\": value, or \"not\": true; a list "
+ "means all of them.",
+ "",
+ "Actions (on.press of a Button; params may read the state with {\"$state\": \"/path\"}, read at the press):",
+ ]
+ for name, action in (catalog.get("actions") or {}).items():
+ lines.append(f"- {name} {_object_text(action.get('params') or {})}: {action['description']}")
+ lines += [
+ f"- {catalog['custom_actions']}",
+ "",
+ f"Limits: at most {limits['max_elements']} elements, nested at most {limits['max_depth']} deep, "
+ f"{limits['max_children']} children each, {limits['max_bytes']} bytes. A spec that breaks a rule is refused "
+ "with every reason; write it again.",
+ ]
+ return "\n".join(lines)
+
+
+__all__ = [
+ "CATALOG_PATH",
+ "CheckedSpec",
+ "SpecError",
+ "canonical_path",
+ "check_spec",
+ "describe_catalog",
+ "load_catalog",
+]
diff --git a/server/services/plugin/base.py b/server/services/plugin/base.py
index 4c43c2a1..ca073031 100644
--- a/server/services/plugin/base.py
+++ b/server/services/plugin/base.py
@@ -1187,6 +1187,10 @@ class BaseNode:
# The chat run this run answers (MachinaWorkflow sets it
# for a run the owner's chat message started).
"run_scope",
+ # A tool call of the agent answering a chat run: where
+ # what it shows goes (show_ui, services/chat/parts.py).
+ "chat_stream",
+ "chat_run_id",
):
if key in context:
extras[key] = context[key]
diff --git a/server/tests/nodes/test_chat_ui.py b/server/tests/nodes/test_chat_ui.py
new file mode 100644
index 00000000..979d9489
--- /dev/null
+++ b/server/tests/nodes/test_chat_ui.py
@@ -0,0 +1,102 @@
+"""Show UI (nodes/chat/chat_ui): the employee's tool for an interface in its
+chat reply. A spec that breaks a rule fails the call with every reason, a
+call outside a chat reply shows nothing and says so, a call of the agent
+answering the owner shows it, and the tool's schema and description are the
+catalog's, pinned and flat."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from nodes.chat.chat_ui import ChatUiNode, ChatUiParams
+from services.genui.spec import describe_catalog
+from services.plugin import NodeContext, NodeUserError
+
+FIXTURES = Path(__file__).resolve().parents[3] / "client" / "src" / "features" / "chat" / "__fixtures__"
+STREAM = {"run_id": "r_1", "session_id": "wf", "workflow_id": "wf", "reply_message_id": "a_r_1"}
+
+
+def booking():
+ return json.loads((FIXTURES / "saturday-booking.spec.json").read_text(encoding="utf-8"))
+
+
+def ctx(raw=None) -> NodeContext:
+ return NodeContext(node_id="wf:chatUi:1", node_type="chatUi", workflow_id="wf", raw=raw or {})
+
+
+def shown(monkeypatch):
+ calls = []
+
+ async def show_ui(database, stream, *, tool_call_id, spec):
+ calls.append({"stream": stream, "tool_call_id": tool_call_id, "spec": spec})
+ return "ui_1234"
+
+ monkeypatch.setattr("services.chat.parts.show_ui", show_ui)
+ monkeypatch.setattr("services.plugin.deps.get_database", lambda: "db")
+ return calls
+
+
+async def test_the_agent_answering_the_owner_shows_it(shown):
+ result = await ChatUiNode().show(ctx({"chat_stream": STREAM, "tool_call_id": "call_1"}), ChatUiParams(spec=booking()))
+ assert (result.shown, result.ui_id, result.elements) == (True, "ui_1234", 11)
+ assert result.dropped is None and result.notes is None
+ [call] = shown
+ assert call["stream"] == STREAM and call["tool_call_id"] == "call_1"
+ assert set(call["spec"]["elements"]) == set(booking()["elements"])
+
+
+async def test_outside_a_chat_reply_nothing_shows(shown):
+ for raw in ({}, {"chat_stream": STREAM}, {"tool_call_id": "call_1"}):
+ result = await ChatUiNode().show(ctx(raw), ChatUiParams(spec=booking()))
+ assert result.shown is False and "only in your reply" in result.message
+ assert shown == []
+
+
+async def test_a_spec_that_breaks_a_rule_is_refused_with_every_reason(shown):
+ bad = booking()
+ bad["elements"]["svc"]["props"]["options"] = ["Only one"]
+ bad["elements"]["hold"]["on"]["press"]["action"] = "pop"
+ with pytest.raises(NodeUserError) as error:
+ await ChatUiNode().show(ctx({"chat_stream": STREAM, "tool_call_id": "call_1"}), ChatUiParams(spec=bad))
+ message = str(error.value)
+ assert "call show_ui again" in message and "options" in message and "pop is not available" in message
+ assert shown == []
+
+
+async def test_what_was_left_out_is_reported(shown):
+ spec = booking()
+ spec["elements"]["ghost"] = {"type": "Marquee", "props": {}}
+ result = await ChatUiNode().show(ctx({"chat_stream": STREAM, "tool_call_id": "call_1"}), ChatUiParams(spec=spec))
+ assert result.dropped == [{"id": "ghost", "reason": "unknown type 'Marquee'"}]
+
+
+def test_a_spec_sent_as_a_json_string_is_read():
+ assert ChatUiParams(spec=json.dumps(booking())).spec == booking()
+
+
+def test_the_tool_is_the_catalogs_pinned_and_flat():
+ schema = ChatUiNode.as_tool_schema()
+ assert schema["name"] == "show_ui"
+ assert ChatUiNode.tool_schema_locked is True
+ assert ChatUiNode.tool_description == describe_catalog()
+ assert ChatUiNode.chat_step_hidden is True
+
+ def no_refs(value):
+ if isinstance(value, dict):
+ assert "$defs" not in value and "$ref" not in value
+ for child in value.values():
+ no_refs(child)
+ elif isinstance(value, list):
+ for child in value:
+ no_refs(child)
+
+ no_refs(schema)
+
+
+def test_the_tool_is_allowed_for_hires():
+ allowlist = json.loads((Path(__file__).resolve().parents[2] / "config" / "node_allowlist.json").read_text(encoding="utf-8"))
+ assert "chatUi" in allowlist["enabled_nodes"]
diff --git a/server/tests/services/chat/test_parts.py b/server/tests/services/chat/test_parts.py
new file mode 100644
index 00000000..3c64c906
--- /dev/null
+++ b/server/tests/services/chat/test_parts.py
@@ -0,0 +1,217 @@
+"""What a chat run's tools show in its reply (services/chat/parts.py): a UI
+is saved on the run and streamed as patches; the reply carries it once
+saved, also when the run wrote nothing; snapshots fold the stream; a button
+press is checked against the UI it came from and reaches the employee as a
+[ui-event] line; what the owner sets is kept on the reply."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from pathlib import Path
+
+import pytest
+
+from services.chat import ledger, parts, reducer
+from services.genui.spec import check_spec
+from tests.services.chat._helpers import FakeSocket, talking
+
+FIXTURES = Path(__file__).resolve().parents[4] / "client" / "src" / "features" / "chat" / "__fixtures__"
+CLAIM = dict(temporal_workflow_id="tw-1", temporal_run_id="tr-1")
+
+
+def booking():
+ raw = json.loads((FIXTURES / "saturday-booking.spec.json").read_text(encoding="utf-8"))
+ return check_spec(raw).spec
+
+
+async def running(database, session_id="wf"):
+ admission = await ledger.admit_message(
+ database, session_id=session_id, workflow_id=session_id, execution_id="gen-1", text="Book Saturday", track=True
+ )
+ return await ledger.start_run(database, run_id=admission.run.run_id, **CLAIM)
+
+
+def stream_of(run):
+ return {"run_id": run.run_id, "session_id": run.session_id, "workflow_id": run.workflow_id, "reply_message_id": run.reply_message_uid}
+
+
+def roomy_hub():
+ """A hub whose sockets hold a whole UI's patches."""
+ from services.chat.hub import ChatRunHub, reset_chat_hub_for_tests
+
+ fresh = ChatRunHub(queue_size=64)
+ previous = reset_chat_hub_for_tests(fresh)
+ try:
+ yield fresh
+ finally:
+ reset_chat_hub_for_tests(previous)
+
+
+async def test_a_ui_is_saved_on_the_run_and_streamed_as_patches(database, roomy_hub):
+ hub = roomy_hub
+ socket = FakeSocket()
+ hub.subscribe(socket, "wf")
+ run = await running(database)
+ spec = booking()
+ part_id = await parts.show_ui(database, stream_of(run), tool_call_id="call_1", spec=spec)
+ assert part_id == parts.ui_part_id(run.run_id, "call_1") and part_id.startswith("ui_")
+ # A retried call saves the same part again, not a second one, and says nothing new.
+ assert await parts.show_ui(database, stream_of(run), tool_call_id="call_1", spec=spec) == part_id
+ [saved] = await parts.run_parts(database, run.run_id)
+ assert (saved.kind, saved.key) == ("ui", f"ui:{part_id}")
+ assert saved.payload["spec"] == spec and saved.payload["state"] == spec["state"] and saved.payload["state_revision"] == 0
+
+ await asyncio.sleep(0)
+ events = [event for event in socket.events() if event["type"].startswith("com.opencompany.chat.run.activity")]
+ snapshot, *deltas = events
+ assert snapshot["data"]["content"] == {"root": "", "state": {}, "elements": {}}
+ assert {event["data"]["message_id"] for event in events} == {part_id}
+ assert len(deltas) == 2 + len(spec["elements"])
+ # The run's snapshot folds the stream into the spec.
+ live = hub.live_snapshot(run.run_id)
+ [activity] = live["activities"]
+ assert (activity["activity_type"], activity["content"], activity["patches"]) == ("json_render", spec, len(deltas))
+
+
+async def test_the_reply_carries_the_ui_from_the_moment_it_is_saved(database, hub):
+ run = await running(database)
+ part_id = await parts.show_ui(database, stream_of(run), tool_call_id="call_1", spec=booking())
+ reply = await ledger.post_reply(database, run=run, node_id="wf:chatReply:1", text="Here are Saturday's slots.", execution_id="gen-1")
+ assert [item["part_id"] for item in reply["parts"]["ui"]] == [part_id]
+ finished = await ledger.finish_run(database, run_id=run.run_id, success=True, **CLAIM)
+ assert finished.result == {"reply_message_id": run.reply_message_uid}
+ [_, saved] = await database.get_chat_messages("wf")
+ assert saved["parts"]["ui"][0]["part_id"] == part_id
+
+
+async def test_a_run_that_only_showed_a_ui_gets_a_reply_holding_it(database, hub, frames):
+ run = await running(database)
+ part_id = await parts.show_ui(database, stream_of(run), tool_call_id="call_1", spec=booking())
+ finished = await ledger.finish_run(database, run_id=run.run_id, success=True, **CLAIM)
+ assert finished.result == {"reply_message_id": run.reply_message_uid}
+ [_, reply] = await database.get_chat_messages("wf")
+ assert (reply["role"], reply["message"], reply["uid"]) == ("assistant", "", run.reply_message_uid)
+ assert reply["parts"]["ui"][0]["part_id"] == part_id
+ # Open threads were told to read it.
+ assert any(frame["type"] == "chat.updated" for frame in frames)
+
+
+async def test_the_end_keeps_what_the_owner_set_after_the_reply_was_saved(database, hub):
+ run = await running(database)
+ first = await parts.show_ui(database, stream_of(run), tool_call_id="call_1", spec=booking())
+ await ledger.post_reply(database, run=run, node_id="n", text="Pick one.", execution_id="gen-1")
+ await parts.update_ui_state(database, "wf", first, [{"path": "/slot", "value": "s4"}])
+ # A second interface after the reply was saved is added at the end.
+ second = await parts.show_ui(database, stream_of(run), tool_call_id="call_2", spec=booking())
+ await ledger.finish_run(database, run_id=run.run_id, success=True, **CLAIM)
+ [_, reply] = await database.get_chat_messages("wf")
+ assert [item["part_id"] for item in reply["parts"]["ui"]] == [first, second]
+ assert reply["parts"]["ui"][0]["state"]["slot"] == "s4"
+
+
+async def test_sealing_twice_changes_nothing_and_no_parts_seals_nothing(database, hub):
+ run = await running(database)
+ assert await parts.seal_parts(database, run) is False
+ await parts.show_ui(database, stream_of(run), tool_call_id="call_1", spec=booking())
+ assert await parts.seal_parts(database, run) is True
+ assert await parts.seal_parts(database, run) is False
+
+
+async def test_a_press_is_checked_against_its_ui(database, hub):
+ run = await running(database)
+ part_id = await parts.show_ui(database, stream_of(run), tool_call_id="call_1", spec=booking())
+ part = await parts.find_ui_part(database, "wf", part_id)
+ assert part is not None and part["part_id"] == part_id
+ assert await parts.find_ui_part(database, "other", part_id) is None
+
+ pressed = parts.check_ui_event(part, "hold", "holdSlot", {"slot": "s3"})
+ assert pressed == {"label": "Hold this slot for 15 min", "params": {"slot": "s3"}}
+ with pytest.raises(parts.UiRefused):
+ parts.check_ui_event(part, "svc", "holdSlot", {})
+ with pytest.raises(parts.UiRefused):
+ parts.check_ui_event(part, "hold", "deleteEverything", {})
+ with pytest.raises(parts.UiRefused):
+ parts.check_ui_event(part, "hold", "holdSlot", {"slot": "s3", "extra": 1})
+ line = parts.ui_event_message(part_id=part_id, element_id="hold", label="Hold this slot for 15 min", action="holdSlot", params={"slot": "s3"})
+ assert line.startswith("[ui-event]{") and line.endswith("}[/ui-event]")
+ assert json.loads(line[len("[ui-event]"):-len("[/ui-event]")]) == {
+ "ui_id": part_id, "element": "hold", "label": "Hold this slot for 15 min", "action": "holdSlot", "params": {"slot": "s3"},
+ }
+
+
+async def test_what_the_owner_sets_is_kept_on_the_ui(database, hub):
+ run = await running(database)
+ part_id = await parts.show_ui(database, stream_of(run), tool_call_id="call_1", spec=booking())
+ # Before the reply is saved, on the run.
+ first = await parts.update_ui_state(database, "wf", part_id, [{"path": "/slot", "value": "s4"}])
+ assert first == {"state": {**booking()["state"], "slot": "s4"}, "state_revision": 1}
+ await ledger.post_reply(database, run=run, node_id="n", text="Pick one.", execution_id="gen-1")
+ # After, on the reply.
+ second = await parts.update_ui_state(database, "wf", part_id, [{"path": "/note", "value": "Patch test done"}, {"path": "/a/b", "value": 1}])
+ assert second["state_revision"] == 2 and second["state"]["note"] == "Patch test done" and second["state"]["a"] == {"b": 1}
+ [_, reply] = await database.get_chat_messages("wf")
+ assert reply["parts"]["ui"][0]["state"]["slot"] == "s4"
+
+ with pytest.raises(parts.UiRefused):
+ await parts.update_ui_state(database, "wf", part_id, [{"path": "/__proto__/x", "value": 1}])
+ with pytest.raises(parts.UiRefused):
+ await parts.update_ui_state(database, "wf", part_id, [])
+ with pytest.raises(parts.UiRefused):
+ await parts.update_ui_state(database, "wf", part_id, [{"path": "/big", "value": "x" * 5000}])
+ assert await parts.update_ui_state(database, "wf", "ui_nope", [{"path": "/x", "value": 1}]) is None
+
+
+def test_the_reducer_folds_activity_events():
+ snapshot = reducer.empty_snapshot("r_1")
+
+ def event(seq, suffix, **data):
+ return {"type": f"com.opencompany.chat.run.{suffix}", "data": {"seq": seq, **data}}
+
+ snapshot = reducer.apply_event(snapshot, event(1, "activity.snapshot", message_id="ui_1", activity_type="json_render", content={"root": "", "state": {}, "elements": {}}, replace=True))
+ snapshot = reducer.apply_event(snapshot, event(2, "activity.delta", message_id="ui_1", activity_type="json_render", patch=[{"op": "add", "path": "/root", "value": "a"}]))
+ snapshot = reducer.apply_event(snapshot, event(3, "activity.delta", message_id="ui_1", activity_type="json_render", patch=[{"op": "add", "path": "/__proto__/x", "value": 1}]))
+ [activity] = snapshot["activities"]
+ assert activity == {"message_id": "ui_1", "activity_type": "json_render", "content": {"root": "a", "state": {}, "elements": {}}, "patches": 2}
+
+
+# ----- the commands -----
+
+
+async def test_a_press_goes_to_the_employee_as_a_ui_event(chat):
+ await talking(chat.database)
+ first = await chat.handlers.handle_send_chat_message({"message": "Book Saturday", "session_id": "wf"}, None)
+ run = await ledger.start_run(chat.database, run_id=first["run_id"], **CLAIM)
+ part_id = await parts.show_ui(chat.database, stream_of(run), tool_call_id="call_1", spec=booking())
+ await ledger.post_reply(chat.database, run=run, node_id="n", text="Pick a slot.", execution_id="gen-1")
+ await ledger.finish_run(chat.database, run_id=run.run_id, success=True, **CLAIM)
+
+ press = {"part_id": part_id, "element_id": "hold", "action": "holdSlot", "params": {"slot": "s2"}}
+ sent = await chat.handlers.handle_send_chat_message({"message": "anything", "session_id": "wf", "ui_event": press}, None)
+ assert sent["success"] is True
+ pressed_run = await ledger.get_run(chat.database, sent["run_id"])
+ assert pressed_run.kind == "action"
+ rows = await chat.database.get_chat_messages("wf")
+ owner = rows[-1]
+ # The owner's message reads the button's label, whatever the client sent.
+ assert (owner["message"], owner["kind"], owner["meta"]["ui_event"]) == ("Hold this slot for 15 min", "action", press)
+ dispatched = chat.dispatched[-1]["data"]["message"]
+ assert dispatched.startswith("[ui-event]") and '"action": "holdSlot"' in dispatched
+
+ bad = await chat.handlers.handle_send_chat_message(
+ {"message": "x", "session_id": "wf", "ui_event": {**press, "action": "somethingElse"}}, None
+ )
+ assert bad["error"] == "ui_event_rejected"
+
+
+async def test_the_ui_state_command(chat):
+ await talking(chat.database)
+ first = await chat.handlers.handle_send_chat_message({"message": "Book Saturday", "session_id": "wf"}, None)
+ run = await ledger.start_run(chat.database, run_id=first["run_id"], **CLAIM)
+ part_id = await parts.show_ui(chat.database, stream_of(run), tool_call_id="call_1", spec=booking())
+ saved = await chat.handlers.handle_chat_ui_state({"session_id": "wf", "part_id": part_id, "changes": [{"path": "/slot", "value": "s1"}]}, None)
+ assert saved == {"success": True, "part_id": part_id, "state_revision": 1}
+ assert (await chat.handlers.handle_chat_ui_state({"session_id": "wf", "part_id": "ui_x", "changes": [{"path": "/a", "value": 1}]}, None))["error"] == "not_found"
+ bad = await chat.handlers.handle_chat_ui_state({"session_id": "wf", "part_id": part_id, "changes": "nope"}, None)
+ assert bad["error"] == "invalid_request"
diff --git a/server/tests/services/genui/__init__.py b/server/tests/services/genui/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/server/tests/services/genui/test_catalog_sync.py b/server/tests/services/genui/test_catalog_sync.py
new file mode 100644
index 00000000..e08331c3
--- /dev/null
+++ b/server/tests/services/genui/test_catalog_sync.py
@@ -0,0 +1,62 @@
+"""The chat's generated-UI vocabulary on both sides: the manifest the server
+checks every spec against (config/chat_genui_catalog.json) and the client's
+catalogue (client/src/features/chat/genui/catalog.ts). A component the
+server accepts but the client cannot draw would show as nothing; one the
+client knows but the server refuses is dead code. This reads the TypeScript
+off disk; the client's own test reads the manifest the same way."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import pytest
+
+from services.genui.spec import load_catalog
+
+CATALOG_TS = Path(__file__).resolve().parents[4] / "client" / "src" / "features" / "chat" / "genui" / "catalog.ts"
+
+
[email protected](scope="module")
+def catalog_ts() -> str:
+ if not CATALOG_TS.exists():
+ pytest.skip(f"client source not present: {CATALOG_TS}")
+ return CATALOG_TS.read_text(encoding="utf-8")
+
+
+def _block(source: str, name: str) -> str:
+ match = re.search(rf"export const {name}\b[^=]*= (\[.*?\]|\{{.*?\}}) (?:as const|satisfies)", source, re.DOTALL)
+ assert match, f"could not find {name}"
+ return match.group(1)
+
+
+def test_the_same_components_in_the_same_order(catalog_ts):
+ assert re.findall(r"'([^']*)'", _block(catalog_ts, "CHAT_COMPONENT_TYPES")) == list(load_catalog()["components"])
+
+
+def test_roles_bound_props_and_children(catalog_ts):
+ components = load_catalog()["components"]
+ roles = dict(re.findall(r"(\w+): '(\w+)'", _block(catalog_ts, "COMPONENT_ROLES")))
+ assert roles == {name: component["role"] for name, component in components.items()}
+ binds = dict(re.findall(r"(\w+): '(\w+)'", _block(catalog_ts, "BIND_PROPS")))
+ assert binds == {name: component["bind"] for name, component in components.items() if component.get("bind")}
+ children_block = _block(catalog_ts, "COMPONENT_CHILDREN")
+ children = {}
+ for name, value in re.findall(r"(\w+): ('any'|\[[^\]]*\])", children_block):
+ children[name] = "any" if value == "'any'" else re.findall(r"'([^']*)'", value)
+ assert children == {name: component["children"] for name, component in components.items() if component.get("children")}
+
+
+def test_actions_and_limits(catalog_ts):
+ catalog = load_catalog()
+ assert sorted(re.findall(r"'([^']*)'", _block(catalog_ts, "CHAT_ACTIONS"))) == sorted(catalog["actions"])
+ limits = {key: int(value) for key, value in re.findall(r"(\w+): (\d+)", _block(catalog_ts, "CHAT_LIMITS"))}
+ names = {
+ "maxElements": "max_elements",
+ "maxDepth": "max_depth",
+ "maxBytes": "max_bytes",
+ "maxChildren": "max_children",
+ "maxIdLength": "max_id_length",
+ "maxPathSegments": "max_path_segments",
+ }
+ assert {names[key]: value for key, value in limits.items()} == catalog["limits"]
diff --git a/server/tests/services/genui/test_patches.py b/server/tests/services/genui/test_patches.py
new file mode 100644
index 00000000..45ed24fe
--- /dev/null
+++ b/server/tests/services/genui/test_patches.py
@@ -0,0 +1,68 @@
+"""A generated UI as JSON patches (services/genui/patches.py): the stream
+matches the design handoff's examples line for line, folding it back builds
+the spec, and applying patches never reaches a prototype, never changes its
+input, and skips what does not apply."""
+
+from __future__ import annotations
+
+import copy
+import json
+from pathlib import Path
+
+import pytest
+
+from services.genui.patches import apply_patch, apply_patch_op, escape_pointer, spec_to_patches, unescape_pointer
+
+FIXTURES = Path(__file__).resolve().parents[4] / "client" / "src" / "features" / "chat" / "__fixtures__"
+EMPTY = {"root": "", "state": {}, "elements": {}}
+
+
[email protected]("name", ["saturday-booking", "reply-insights", "reminders"])
+def test_the_stream_matches_the_handoff_line_for_line(name):
+ spec = json.loads((FIXTURES / f"{name}.spec.json").read_text(encoding="utf-8"))
+ golden = [json.loads(line) for line in (FIXTURES / f"{name}.patches.jsonl").read_text(encoding="utf-8").splitlines() if line.strip()]
+ assert spec_to_patches(spec) == golden
+ assert apply_patch(copy.deepcopy(EMPTY), golden) == {"root": spec["root"], "state": spec["state"], "elements": spec["elements"]}
+
+
+def test_ids_are_escaped_and_unreachable_elements_left_out():
+ spec = {
+ "root": "a/b",
+ "state": {},
+ "elements": {"a/b": {"type": "Stack", "children": ["x~y"]}, "x~y": {"type": "Text"}, "lost": {"type": "Text"}},
+ }
+ paths = [patch["path"] for patch in spec_to_patches(spec)]
+ assert paths == ["/root", "/state", "/elements/a~1b", "/elements/x~0y"]
+ assert unescape_pointer(escape_pointer("a/~b")) == "a/~b"
+
+
+def test_add_replace_remove():
+ content = {"a": {"b": [1, 2]}}
+ assert apply_patch_op(content, {"op": "add", "path": "/a/c", "value": 3}) == {"a": {"b": [1, 2], "c": 3}}
+ assert apply_patch_op(content, {"op": "add", "path": "/a/b/1", "value": 9}) == {"a": {"b": [1, 9, 2]}}
+ assert apply_patch_op(content, {"op": "add", "path": "/a/b/-", "value": 9}) == {"a": {"b": [1, 2, 9]}}
+ assert apply_patch_op(content, {"op": "replace", "path": "/a/b/0", "value": 7}) == {"a": {"b": [7, 2]}}
+ assert apply_patch_op(content, {"op": "remove", "path": "/a/b/0"}) == {"a": {"b": [2]}}
+ assert apply_patch_op(content, {"op": "remove", "path": "/a"}) == {}
+ assert apply_patch_op(content, {"op": "replace", "path": "", "value": {"new": 1}}) == {"new": 1}
+ assert content == {"a": {"b": [1, 2]}}, "the input changed"
+
+
+ "op",
+ [
+ {"op": "add", "path": "/__proto__/polluted", "value": True},
+ {"op": "add", "path": "/a/constructor", "value": 1},
+ {"op": "replace", "path": "/missing", "value": 1},
+ {"op": "remove", "path": "/missing"},
+ {"op": "add", "path": "/a/x/y", "value": 1},
+ {"op": "add", "path": "/a/b/5", "value": 1},
+ {"op": "replace", "path": "/a/b/-", "value": 1},
+ {"op": "move", "from": "/a", "path": "/b"},
+ {"op": "add", "path": "no-slash", "value": 1},
+ {"op": "add", "path": "/a/b/x", "value": 1},
+ ],
+)
+def test_what_does_not_apply_is_skipped(op):
+ content = {"a": {"b": [1, 2]}}
+ assert apply_patch_op(content, op) is content
diff --git a/server/tests/services/genui/test_spec.py b/server/tests/services/genui/test_spec.py
new file mode 100644
index 00000000..ef696cf0
--- /dev/null
+++ b/server/tests/services/genui/test_spec.py
@@ -0,0 +1,211 @@
+"""Checking the interface an employee shows in a chat reply
+(services/genui/spec.py): the design handoff's examples pass as written;
+structural problems are refused with every reason; unknown types, unreachable
+elements, stray fields and props are left out and reported; expressions and
+paths come back canonical; and the tool description is the catalog's,
+stable byte for byte."""
+
+from __future__ import annotations
+
+import copy
+import json
+from pathlib import Path
+
+import pytest
+
+from services.genui.spec import SpecError, canonical_path, check_spec, describe_catalog, load_catalog
+
+FIXTURES = Path(__file__).resolve().parents[4] / "client" / "src" / "features" / "chat" / "__fixtures__"
+EXAMPLES = ("saturday-booking", "reply-insights", "reminders")
+
+
+def fixture(name: str):
+ return json.loads((FIXTURES / f"{name}.spec.json").read_text(encoding="utf-8"))
+
+
+def spec(**elements):
+ return {"root": "root", "state": {}, "elements": {"root": {"type": "Stack", "children": list(elements)}, **elements}}
+
+
+def refused(raw) -> list:
+ with pytest.raises(SpecError) as error:
+ check_spec(raw)
+ return error.value.problems
+
+
[email protected]("name", EXAMPLES)
+def test_the_handoff_examples_pass_as_written(name):
+ raw = fixture(name)
+ checked = check_spec(raw)
+ assert checked.dropped == [] and checked.notes == []
+ for element_id, element in raw["elements"].items():
+ assert checked.spec["elements"][element_id] == {"props": {}, **element}
+ assert checked.spec["root"] == raw["root"] and checked.spec["state"] == raw.get("state", {})
+
+
+# ----- refused -----
+
+
+def test_a_spec_that_is_not_one_is_refused():
+ assert refused("not a spec")
+ assert refused({"root": "root"})
+ assert refused({"root": "root", "elements": {}})
+ assert refused({"root": "../x", "elements": {"x": {"type": "Text", "props": {"text": "hi"}}}})
+
+
+def test_a_root_that_is_not_an_element_is_refused():
+ problems = refused({"root": "missing", "elements": {"a": {"type": "Text", "props": {"text": "hi"}}}})
+ assert any("root 'missing'" in problem for problem in problems)
+ problems = refused({"root": "a", "elements": {"a": {"type": "Marquee", "props": {}}}})
+ assert any("known type" in problem for problem in problems)
+
+
+def test_every_problem_is_listed_at_once():
+ raw = spec(
+ pick={"type": "Select", "props": {"label": "Service", "options": ["Only one"]}},
+ note={"type": "Text", "props": {}},
+ go={"type": "Button", "props": {"label": "Go"}, "on": {"press": {"action": "push"}}},
+ )
+ problems = refused(raw)
+ assert any("'pick' (Select)" in problem and "options" in problem for problem in problems)
+ assert any("'note' (Text)" in problem and "text" in problem for problem in problems)
+ assert any("push is not available" in problem for problem in problems)
+
+
+def test_children_must_be_elements_the_parent_may_hold():
+ assert any("is not an element" in problem for problem in refused(spec(row={"type": "Row", "children": ["ghost"]})))
+ raw = spec(card={"type": "Card", "props": {"title": "Details"}, "children": ["go"]}, go={"type": "Button", "props": {"label": "Go"}})
+ raw["elements"]["root"]["children"] = ["card"]
+ assert any("cannot hold Button" in problem for problem in refused(raw))
+ assert any("cannot hold children" in problem for problem in refused(spec(t={"type": "Text", "props": {"text": "x"}, "children": ["root"]})))
+
+
+def test_cycles_and_shared_children_are_refused():
+ raw = {
+ "root": "a",
+ "elements": {"a": {"type": "Stack", "children": ["b"]}, "b": {"type": "Stack", "children": ["a"]}},
+ }
+ assert any("contains itself" in problem for problem in refused(raw))
+ shared = spec(s1={"type": "Stack", "children": ["t"]}, s2={"type": "Stack", "children": ["t"]}, t={"type": "Text", "props": {"text": "x"}})
+ shared["elements"]["root"]["children"] = ["s1", "s2"]
+ assert any("two parents" in problem for problem in refused(shared))
+
+
+def test_limits_are_refused():
+ limits = load_catalog()["limits"]
+ deep = {"root": "s0", "elements": {}}
+ for depth in range(limits["max_depth"] + 1):
+ deep["elements"][f"s{depth}"] = {"type": "Stack", "children": [f"s{depth + 1}"] if depth < limits["max_depth"] else []}
+ assert any("nested more than" in problem for problem in refused(deep))
+
+ many = {f"t{n}": {"type": "Text", "props": {"text": "x"}} for n in range(limits["max_elements"])}
+ wide = {"root": "root", "elements": {"root": {"type": "Stack", "children": []}, **many}}
+ # More children than one element may hold.
+ wide["elements"]["root"]["children"] = list(many)
+ assert any("children" in problem for problem in refused(wide))
+
+ big = spec(t={"type": "Text", "props": {"text": "x" * (limits["max_bytes"] + 1)}})
+ assert any("bytes" in problem for problem in refused(big))
+
+
+def test_prototype_paths_and_reserved_names_are_refused():
+ raw = spec(f={"type": "TextField", "props": {"label": "Name", "value": {"$bindState": "/__proto__/x"}}})
+ assert any("not a usable state path" in problem for problem in refused(raw))
+ raw = spec(t={"type": "Text", "props": {"text": {"$state": "/a/constructor"}}})
+ assert refused(raw)
+ raw = spec(t={"type": "Text", "props": {"text": "hi"}, "visible": {"$state": "/prototype"}})
+ assert refused(raw)
+ raw = spec(go={"type": "Button", "props": {"label": "Go"}, "on": {"press": {"action": "hold", "params": {"__oc_element": "x"}}}})
+ assert any("not allowed" in problem for problem in refused(raw))
+ raw = spec(go={"type": "Button", "props": {"label": "Go"}, "on": {"press": {"action": "9lives"}}})
+ assert any("not an action name" in problem for problem in refused(raw))
+ raw = {"root": "root", "state": {"__proto__": {"x": 1}}, "elements": spec()["elements"]}
+ assert any("not allowed" in problem for problem in refused(raw))
+
+
+def test_only_a_bound_prop_binds_state():
+ raw = spec(pick={"type": "Select", "props": {"label": {"$bindState": "/x"}, "options": ["a", "b"]}})
+ assert any("only an input's bound prop" in problem for problem in refused(raw))
+
+
+def test_ask_needs_its_text():
+ raw = spec(go={"type": "Button", "props": {"label": "Ask"}, "on": {"press": {"action": "ask"}}})
+ assert any("(ask)" in problem and "text" in problem for problem in refused(raw))
+ # A text read from the state at the press counts.
+ raw = spec(go={"type": "Button", "props": {"label": "Ask"}, "on": {"press": {"action": "ask", "params": {"text": {"$state": "/q"}}}}})
+ assert check_spec(raw).spec["elements"]["go"]["on"]["press"]["params"] == {"text": {"$state": "/q"}}
+
+
+# ----- dropped and reported -----
+
+
+def test_unknown_types_and_unreachable_elements_are_left_out():
+ raw = spec(t={"type": "Text", "props": {"text": "hi"}}, marquee={"type": "Marquee", "props": {}})
+ raw["elements"]["orphan"] = {"type": "Text", "props": {"text": "nobody holds me"}}
+ checked = check_spec(raw)
+ assert set(checked.spec["elements"]) == {"root", "t"}
+ assert checked.spec["elements"]["root"]["children"] == ["t"]
+ assert {item["id"]: item["reason"] for item in checked.dropped} == {
+ "marquee": "unknown type 'Marquee'",
+ "orphan": "not reachable from the root",
+ }
+
+
+def test_stray_fields_props_and_repeat_expressions_are_dropped_with_a_note():
+ raw = spec(
+ t={
+ "type": "Text",
+ "props": {"text": "hi", "color": "red"},
+ "watch": {"/x": {"action": "ask"}},
+ "repeat": {"statePath": "/items"},
+ },
+ f={"type": "TextField", "props": {"label": "Name", "placeholder": {"$item": "name"}}},
+ )
+ checked = check_spec(raw)
+ assert checked.spec["elements"]["t"] == {"type": "Text", "props": {"text": "hi"}}
+ assert checked.spec["elements"]["f"]["props"] == {"label": "Name"}
+ notes = " | ".join(checked.notes)
+ assert "'color'" in notes and "repeat, watch" in notes and "$item" in notes
+
+
+def test_expressions_and_paths_come_back_canonical():
+ raw = spec(
+ t={"type": "Text", "props": {"text": {"$template": "Hi ${ name/first }"}}, "visible": [{"$state": "remind"}, {"$state": "/count", "gt": 2}]},
+ f={"type": "Toggle", "props": {"label": "Remind", "checked": {"$bindState": "remind//"}}},
+ c={"type": "Text", "props": {"text": {"$cond": {"$state": "/a", "eq": "x"}, "$then": "yes", "$else": {"$state": "b"}}}},
+ )
+ checked = check_spec(raw).spec["elements"]
+ assert checked["t"]["props"]["text"] == {"$template": "Hi ${/name/first}"}
+ assert checked["t"]["visible"] == {"$and": [{"$state": "/remind"}, {"$state": "/count", "gt": 2}]}
+ assert checked["f"]["props"]["checked"] == {"$bindState": "/remind"}
+ assert checked["c"]["props"]["text"] == {"$cond": {"$state": "/a", "eq": "x"}, "$then": "yes", "$else": {"$state": "/b"}}
+
+
+def test_the_input_is_not_changed():
+ raw = fixture("saturday-booking")
+ before = copy.deepcopy(raw)
+ check_spec(raw)
+ assert raw == before
+
+
+def test_paths():
+ assert canonical_path("/a/b", 6) == "/a/b"
+ assert canonical_path("a//b/", 6) == "/a/b"
+ assert canonical_path("/a~1b", 6) == "/a~1b"
+ assert canonical_path("", 6) is None
+ assert canonical_path("/__proto__", 6) is None
+ assert canonical_path("/a/b/c", 2) is None
+ assert canonical_path(7, 6) is None
+
+
+# ----- the tool description -----
+
+
+def test_the_description_is_the_catalogs_and_stable():
+ text = describe_catalog()
+ assert text == describe_catalog()
+ for name in load_catalog()["components"]:
+ assert f"- {name} (" in text
+ assert "SlotPicker (input; binds value)" in text
+ assert "Card (layout; holds Select, Toggle, TextField, Text)" in text
+ assert "[ui-event]" in text
diff --git a/server/uv.lock b/server/uv.lock
index e04b3c6d..ea097867 100644
--- a/server/uv.lock
+++ b/server/uv.lock
@@ -1904,6 +1904,7 @@ dependencies = [
{ name = "greenlet" },
{ name = "html2text" },
{ name = "httpx" },
+ { name = "jsonschema" },
{ name = "lmstudio" },
{ name = "markdown-it-py" },
{ name = "mcp" },
@@ -1990,6 +1991,7 @@ requires-dist = [
{ name = "greenlet", specifier = ">=3.0.0" },
{ name = "html2text", specifier = ">=2024.2.26" },
{ name = "httpx", specifier = ">=0.28.0" },
+ { name = "jsonschema", specifier = ">=4.23.0" },
{ name = "keyring", marker = "extra == 'keyring'", specifier = ">=25.0.0" },
{ name = "lmstudio", specifier = ">=1.5.0" },
{ name = "markdown-it-py", specifier = ">=3.0.0" },