Skip to content

Self-improving AI Employees for everyone

docs(chat): add the chat wire protocol, handoff fixtures and json-render

trohitg1d710cea1883
diff --git a/bun.lock b/bun.lock
index e81bf262..d172e75e 100644
--- a/bun.lock
+++ b/bun.lock
@@ -18,6 +18,8 @@
"@eslint/js": "^10.0.1",
"@fontsource-variable/geist": "^5.2.8",
"@hookform/resolvers": "^5.2.2",
+ "@json-render/core": "0.21.0",
+ "@json-render/react": "0.21.0",
"@lobehub/icons": "^2.48.0",
"@lukemorales/query-key-factory": "^1.3.4",
"@tailwindcss/typography": "^0.5.19",
@@ -415,6 +417,10 @@
"@jridgewell/trace-mapping": ["@jridgewell/[email protected]", "", { "dependencies": { "@jridgewell/resolve-uri": "3.1.2", "@jridgewell/sourcemap-codec": "1.5.5" } }, "sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw=="],
+ "@json-render/core": ["@json-render/[email protected]", "", { "dependencies": { "zod": "^4.3.6" } }, "sha512-vysEbTjO1y8mEgAsp0tztRyaWCkNsBrG8MhAqbndGK3qmMXjMRdCNtk21+AQRNKdRelFGVAwBgtUNW8tfjQlsw=="],
+
+ "@json-render/react": ["@json-render/[email protected]", "", { "dependencies": { "@json-render/core": "0.21.0" }, "peerDependencies": { "react": "^19.2.3" } }, "sha512-z/fZg0L8fJe2dnnQjWkmMw409iBclSWcOqdjoBy8eLHeBr/7F7VipzkY1CfgA2Fa5uW+zxZ54OvWMtdDcsp/yg=="],
+
"@lit-labs/ssr-dom-shim": ["@lit-labs/[email protected]", "", {}, "sha512-Aou5UdlSpr5whQe8AA/bZG0jMj96CoJIWbGfZ91qieWu5AWUMKw8VR/pAkQkJYvBNhmCcWnZlyyk5oze8JIqYA=="],
"@lit/reactive-element": ["@lit/[email protected]", "", { "dependencies": { "@lit-labs/ssr-dom-shim": "1.5.1" } }, "sha512-pbCDiVMnne1lYUIaYNN5wrwQXDtHaYtg7YEFPeW+hws6U47WeFvISGUWekPGKWOP1ygrs0ef0o1VJMk1exos5A=="],
diff --git a/client/package.json b/client/package.json
index 4f53579f..59e8e0a8 100644
--- a/client/package.json
+++ b/client/package.json
@@ -20,6 +20,8 @@
"@eslint/js": "^10.0.1",
"@fontsource-variable/geist": "^5.2.8",
"@hookform/resolvers": "^5.2.2",
+ "@json-render/core": "0.21.0",
+ "@json-render/react": "0.21.0",
"@lobehub/icons": "^2.48.0",
"@lukemorales/query-key-factory": "^1.3.4",
"@tailwindcss/typography": "^0.5.19",
diff --git a/client/src/features/chat/__fixtures__/reminders.patches.jsonl b/client/src/features/chat/__fixtures__/reminders.patches.jsonl
new file mode 100644
index 00000000..8edfae8b
--- /dev/null
+++ b/client/src/features/chat/__fixtures__/reminders.patches.jsonl
@@ -0,0 +1,12 @@
+{"op":"add","path":"/root","value":"root"}
+{"op":"add","path":"/state","value":{"tom":true,"sara":true,"priya":true,"mo":false,"at":"6pm"}}
+{"op":"add","path":"/elements/root","value":{"type":"Stack","props":{"gap":"md"},"children":["who","acts"]}}
+{"op":"add","path":"/elements/who","value":{"type":"Card","props":{"title":"Who gets a reminder","description":"Tomorrow, Saturday 28 Sep"},"children":["t1","t2","t3","t4","moNote","when"]}}
+{"op":"add","path":"/elements/t1","value":{"type":"Toggle","props":{"label":"Tom Hale","hint":"10:00 · Cut","checked":{"$bindState":"/tom"}}}}
+{"op":"add","path":"/elements/t2","value":{"type":"Toggle","props":{"label":"Sara Lin","hint":"11:30 · Cut & blow-dry","checked":{"$bindState":"/sara"}}}}
+{"op":"add","path":"/elements/t3","value":{"type":"Toggle","props":{"label":"Priya Shah","hint":"14:30 · Colour","checked":{"$bindState":"/priya"}}}}
+{"op":"add","path":"/elements/t4","value":{"type":"Toggle","props":{"label":"Mo Reid","hint":"16:45 · Beard trim","checked":{"$bindState":"/mo"}}}}
+{"op":"add","path":"/elements/moNote","value":{"type":"Text","props":{"text":"Mo has confirmed on his own for his last 6 visits."},"visible":{"$state":"/mo","not":true}}}
+{"op":"add","path":"/elements/when","value":{"type":"Select","props":{"label":"Send at","value":{"$bindState":"/at"},"options":["9am","12pm","6pm"]}}}
+{"op":"add","path":"/elements/acts","value":{"type":"Row","children":["go"]}}
+{"op":"add","path":"/elements/go","value":{"type":"Button","props":{"label":"Schedule reminders","variant":"primary"},"on":{"press":{"action":"scheduleReminders","params":{"at":{"$state":"/at"}}}}}}
diff --git a/client/src/features/chat/__fixtures__/reminders.spec.json b/client/src/features/chat/__fixtures__/reminders.spec.json
new file mode 100644
index 00000000..862cfa95
--- /dev/null
+++ b/client/src/features/chat/__fixtures__/reminders.spec.json
@@ -0,0 +1,124 @@
+{
+ "root": "root",
+ "state": {
+ "tom": true,
+ "sara": true,
+ "priya": true,
+ "mo": false,
+ "at": "6pm"
+ },
+ "elements": {
+ "root": {
+ "type": "Stack",
+ "props": {
+ "gap": "md"
+ },
+ "children": [
+ "who",
+ "acts"
+ ]
+ },
+ "who": {
+ "type": "Card",
+ "props": {
+ "title": "Who gets a reminder",
+ "description": "Tomorrow, Saturday 28 Sep"
+ },
+ "children": [
+ "t1",
+ "t2",
+ "t3",
+ "t4",
+ "moNote",
+ "when"
+ ]
+ },
+ "t1": {
+ "type": "Toggle",
+ "props": {
+ "label": "Tom Hale",
+ "hint": "10:00 · Cut",
+ "checked": {
+ "$bindState": "/tom"
+ }
+ }
+ },
+ "t2": {
+ "type": "Toggle",
+ "props": {
+ "label": "Sara Lin",
+ "hint": "11:30 · Cut & blow-dry",
+ "checked": {
+ "$bindState": "/sara"
+ }
+ }
+ },
+ "t3": {
+ "type": "Toggle",
+ "props": {
+ "label": "Priya Shah",
+ "hint": "14:30 · Colour",
+ "checked": {
+ "$bindState": "/priya"
+ }
+ }
+ },
+ "t4": {
+ "type": "Toggle",
+ "props": {
+ "label": "Mo Reid",
+ "hint": "16:45 · Beard trim",
+ "checked": {
+ "$bindState": "/mo"
+ }
+ }
+ },
+ "moNote": {
+ "type": "Text",
+ "props": {
+ "text": "Mo has confirmed on his own for his last 6 visits."
+ },
+ "visible": {
+ "$state": "/mo",
+ "not": true
+ }
+ },
+ "when": {
+ "type": "Select",
+ "props": {
+ "label": "Send at",
+ "value": {
+ "$bindState": "/at"
+ },
+ "options": [
+ "9am",
+ "12pm",
+ "6pm"
+ ]
+ }
+ },
+ "acts": {
+ "type": "Row",
+ "children": [
+ "go"
+ ]
+ },
+ "go": {
+ "type": "Button",
+ "props": {
+ "label": "Schedule reminders",
+ "variant": "primary"
+ },
+ "on": {
+ "press": {
+ "action": "scheduleReminders",
+ "params": {
+ "at": {
+ "$state": "/at"
+ }
+ }
+ }
+ }
+ }
+ }
+}
diff --git a/client/src/features/chat/__fixtures__/reply-insights.patches.jsonl b/client/src/features/chat/__fixtures__/reply-insights.patches.jsonl
new file mode 100644
index 00000000..8c4114b1
--- /dev/null
+++ b/client/src/features/chat/__fixtures__/reply-insights.patches.jsonl
@@ -0,0 +1,6 @@
+{"op":"add","path":"/root","value":"root"}
+{"op":"add","path":"/state","value":{"range":"30 days"}}
+{"op":"add","path":"/elements/root","value":{"type":"Stack","props":{"gap":"md"},"children":["stats","bars","note"]}}
+{"op":"add","path":"/elements/stats","value":{"type":"StatGrid","props":{"items":[{"label":"Questions this month","value":"184","delta":"+12% vs August","tone":"up"},{"label":"Booked after reply","value":"61%","delta":"+8 pts with two options","tone":"up"},{"label":"Avg reply time","value":"38s","delta":"4s faster","tone":"up"}]}}}
+{"op":"add","path":"/elements/bars","value":{"type":"BarChart","props":{"title":"What customers ask most","bars":[{"label":"Prices","value":42},{"label":"Availability","value":35},{"label":"Colour options","value":19},{"label":"Parking","value":8}]}}}
+{"op":"add","path":"/elements/note","value":{"type":"Callout","props":{"tone":"info","text":"Based on 184 WhatsApp conversations since 1 September."}}}
diff --git a/client/src/features/chat/__fixtures__/reply-insights.spec.json b/client/src/features/chat/__fixtures__/reply-insights.spec.json
new file mode 100644
index 00000000..243b145f
--- /dev/null
+++ b/client/src/features/chat/__fixtures__/reply-insights.spec.json
@@ -0,0 +1,75 @@
+{
+ "root": "root",
+ "state": {
+ "range": "30 days"
+ },
+ "elements": {
+ "root": {
+ "type": "Stack",
+ "props": {
+ "gap": "md"
+ },
+ "children": [
+ "stats",
+ "bars",
+ "note"
+ ]
+ },
+ "stats": {
+ "type": "StatGrid",
+ "props": {
+ "items": [
+ {
+ "label": "Questions this month",
+ "value": "184",
+ "delta": "+12% vs August",
+ "tone": "up"
+ },
+ {
+ "label": "Booked after reply",
+ "value": "61%",
+ "delta": "+8 pts with two options",
+ "tone": "up"
+ },
+ {
+ "label": "Avg reply time",
+ "value": "38s",
+ "delta": "4s faster",
+ "tone": "up"
+ }
+ ]
+ }
+ },
+ "bars": {
+ "type": "BarChart",
+ "props": {
+ "title": "What customers ask most",
+ "bars": [
+ {
+ "label": "Prices",
+ "value": 42
+ },
+ {
+ "label": "Availability",
+ "value": 35
+ },
+ {
+ "label": "Colour options",
+ "value": 19
+ },
+ {
+ "label": "Parking",
+ "value": 8
+ }
+ ]
+ }
+ },
+ "note": {
+ "type": "Callout",
+ "props": {
+ "tone": "info",
+ "text": "Based on 184 WhatsApp conversations since 1 September."
+ }
+ }
+ }
+}
diff --git a/client/src/features/chat/__fixtures__/saturday-booking.events.json b/client/src/features/chat/__fixtures__/saturday-booking.events.json
new file mode 100644
index 00000000..e5422a24
--- /dev/null
+++ b/client/src/features/chat/__fixtures__/saturday-booking.events.json
@@ -0,0 +1,1009 @@
+[
+ {
+ "type": "chat_run_event",
+ "data": {
+ "specversion": "1.0",
+ "id": "r_8f2a1c:1",
+ "source": "opencompany://services/chat",
+ "type": "com.opencompany.chat.run.started",
+ "subject": "r_8f2a1c",
+ "time": "2026-09-27T14:02:01.000Z",
+ "datacontenttype": "application/json",
+ "data": {
+ "workflow_id": "wf_salon",
+ "session_id": "wf_salon",
+ "run_id": "r_8f2a1c",
+ "seq": 1,
+ "hub_epoch": "e_fixture",
+ "kind": "message",
+ "user_message_id": "m_owner_1",
+ "reply_message_id": "a_r_8f2a1c",
+ "started_at": "2026-09-27T14:02:00.000Z"
+ }
+ }
+ },
+ {
+ "type": "chat_run_event",
+ "data": {
+ "specversion": "1.0",
+ "id": "r_8f2a1c:2",
+ "source": "opencompany://services/chat",
+ "type": "com.opencompany.chat.run.step.started",
+ "subject": "r_8f2a1c",
+ "time": "2026-09-27T14:02:02.000Z",
+ "datacontenttype": "application/json",
+ "data": {
+ "workflow_id": "wf_salon",
+ "session_id": "wf_salon",
+ "run_id": "r_8f2a1c",
+ "seq": 2,
+ "hub_epoch": "e_fixture",
+ "step_id": "step_1",
+ "step_name": "Checked Google Calendar",
+ "agent_node_id": "wf_salon:aiAgent:1",
+ "attempt": 1
+ }
+ }
+ },
+ {
+ "type": "chat_run_event",
+ "data": {
+ "specversion": "1.0",
+ "id": "r_8f2a1c:3",
+ "source": "opencompany://services/chat",
+ "type": "com.opencompany.chat.run.step.finished",
+ "subject": "r_8f2a1c",
+ "time": "2026-09-27T14:02:03.000Z",
+ "datacontenttype": "application/json",
+ "data": {
+ "workflow_id": "wf_salon",
+ "session_id": "wf_salon",
+ "run_id": "r_8f2a1c",
+ "seq": 3,
+ "hub_epoch": "e_fixture",
+ "step_id": "step_1",
+ "step_name": "Checked Google Calendar",
+ "state": "done",
+ "duration_ms": 640
+ }
+ }
+ },
+ {
+ "type": "chat_run_event",
+ "data": {
+ "specversion": "1.0",
+ "id": "r_8f2a1c:4",
+ "source": "opencompany://services/chat",
+ "type": "com.opencompany.chat.run.step.started",
+ "subject": "r_8f2a1c",
+ "time": "2026-09-27T14:02:04.000Z",
+ "datacontenttype": "application/json",
+ "data": {
+ "workflow_id": "wf_salon",
+ "session_id": "wf_salon",
+ "run_id": "r_8f2a1c",
+ "seq": 4,
+ "hub_epoch": "e_fixture",
+ "step_id": "step_2",
+ "step_name": "Read the WhatsApp thread with Priya",
+ "agent_node_id": "wf_salon:aiAgent:1",
+ "attempt": 1
+ }
+ }
+ },
+ {
+ "type": "chat_run_event",
+ "data": {
+ "specversion": "1.0",
+ "id": "r_8f2a1c:5",
+ "source": "opencompany://services/chat",
+ "type": "com.opencompany.chat.run.step.finished",
+ "subject": "r_8f2a1c",
+ "time": "2026-09-27T14:02:05.000Z",
+ "datacontenttype": "application/json",
+ "data": {
+ "workflow_id": "wf_salon",
+ "session_id": "wf_salon",
+ "run_id": "r_8f2a1c",
+ "seq": 5,
+ "hub_epoch": "e_fixture",
+ "step_id": "step_2",
+ "step_name": "Read the WhatsApp thread with Priya",
+ "state": "done",
+ "duration_ms": 640
+ }
+ }
+ },
+ {
+ "type": "chat_run_event",
+ "data": {
+ "specversion": "1.0",
+ "id": "r_8f2a1c:6",
+ "source": "opencompany://services/chat",
+ "type": "com.opencompany.chat.run.step.started",
+ "subject": "r_8f2a1c",
+ "time": "2026-09-27T14:02:06.000Z",
+ "datacontenttype": "application/json",
+ "data": {
+ "workflow_id": "wf_salon",
+ "session_id": "wf_salon",
+ "run_id": "r_8f2a1c",
+ "seq": 6,
+ "hub_epoch": "e_fixture",
+ "step_id": "step_3",
+ "step_name": "Compared stylist availability",
+ "agent_node_id": "wf_salon:aiAgent:1",
+ "attempt": 1
+ }
+ }
+ },
+ {
+ "type": "chat_run_event",
+ "data": {
+ "specversion": "1.0",
+ "id": "r_8f2a1c:7",
+ "source": "opencompany://services/chat",
+ "type": "com.opencompany.chat.run.step.finished",
+ "subject": "r_8f2a1c",
+ "time": "2026-09-27T14:02:07.000Z",
+ "datacontenttype": "application/json",
+ "data": {
+ "workflow_id": "wf_salon",
+ "session_id": "wf_salon",
+ "run_id": "r_8f2a1c",
+ "seq": 7,
+ "hub_epoch": "e_fixture",
+ "step_id": "step_3",
+ "step_name": "Compared stylist availability",
+ "state": "done",
+ "duration_ms": 640
+ }
+ }
+ },
+ {
+ "type": "chat_run_event",
+ "data": {
+ "specversion": "1.0",
+ "id": "r_8f2a1c:8",
+ "source": "opencompany://services/chat",
+ "type": "com.opencompany.chat.run.text.started",
+ "subject": "r_8f2a1c",
+ "time": "2026-09-27T14:02:08.000Z",
+ "datacontenttype": "application/json",
+ "data": {
+ "workflow_id": "wf_salon",
+ "session_id": "wf_salon",
+ "run_id": "r_8f2a1c",
+ "seq": 8,
+ "hub_epoch": "e_fixture",
+ "message_id": "r_8f2a1c.1.1",
+ "role": "assistant",
+ "agent_node_id": "wf_salon:aiAgent:1"
+ }
+ }
+ },
+ {
+ "type": "chat_run_event",
+ "data": {
+ "specversion": "1.0",
+ "id": "r_8f2a1c:9",
+ "source": "opencompany://services/chat",
+ "type": "com.opencompany.chat.run.text.content",
+ "subject": "r_8f2a1c",
+ "time": "2026-09-27T14:02:09.000Z",
+ "datacontenttype": "application/json",
+ "data": {
+ "workflow_id": "wf_salon",
+ "session_id": "wf_salon",
+ "run_id": "r_8f2a1c",
+ "seq": 9,
+ "hub_epoch": "e_fixture",
+ "message_id": "r_8f2a1c.1.1",
+ "delta": "Saturday is fairly full, but there’s a clean 2h 15m gap with Ana from 2:30pm."
+ }
+ }
+ },
+ {
+ "type": "chat_run_event",
+ "data": {
+ "specversion": "1.0",
+ "id": "r_8f2a1c:10",
+ "source": "opencompany://services/chat",
+ "type": "com.opencompany.chat.run.text.ended",
+ "subject": "r_8f2a1c",
+ "time": "2026-09-27T14:02:10.000Z",
+ "datacontenttype": "application/json",
+ "data": {
+ "workflow_id": "wf_salon",
+ "session_id": "wf_salon",
+ "run_id": "r_8f2a1c",
+ "seq": 10,
+ "hub_epoch": "e_fixture",
+ "message_id": "r_8f2a1c.1.1",
+ "final": true,
+ "reply_message_id": "a_r_8f2a1c"
+ }
+ }
+ },
+ {
+ "type": "chat_run_event",
+ "data": {
+ "specversion": "1.0",
+ "id": "r_8f2a1c:11",
+ "source": "opencompany://services/chat",
+ "type": "com.opencompany.chat.run.activity.snapshot",
+ "subject": "r_8f2a1c",
+ "time": "2026-09-27T14:02:11.000Z",
+ "datacontenttype": "application/json",
+ "data": {
+ "workflow_id": "wf_salon",
+ "session_id": "wf_salon",
+ "run_id": "r_8f2a1c",
+ "seq": 11,
+ "hub_epoch": "e_fixture",
+ "message_id": "p_ui_1",
+ "activity_type": "json_render",
+ "content": {
+ "root": "",
+ "state": {},
+ "elements": {}
+ },
+ "replace": true
+ }
+ }
+ },
+ {
+ "type": "chat_run_event",
+ "data": {
+ "specversion": "1.0",
+ "id": "r_8f2a1c:12",
+ "source": "opencompany://services/chat",
+ "type": "com.opencompany.chat.run.activity.delta",
+ "subject": "r_8f2a1c",
+ "time": "2026-09-27T14:02:12.000Z",
+ "datacontenttype": "application/json",
+ "data": {
+ "workflow_id": "wf_salon",
+ "session_id": "wf_salon",
+ "run_id": "r_8f2a1c",
+ "seq": 12,
+ "hub_epoch": "e_fixture",
+ "message_id": "p_ui_1",
+ "activity_type": "json_render",
+ "patch": [
+ {
+ "op": "add",
+ "path": "/root",
+ "value": "root"
+ }
+ ]
+ }
+ }
+ },
+ {
+ "type": "chat_run_event",
+ "data": {
+ "specversion": "1.0",
+ "id": "r_8f2a1c:13",
+ "source": "opencompany://services/chat",
+ "type": "com.opencompany.chat.run.activity.delta",
+ "subject": "r_8f2a1c",
+ "time": "2026-09-27T14:02:13.000Z",
+ "datacontenttype": "application/json",
+ "data": {
+ "workflow_id": "wf_salon",
+ "session_id": "wf_salon",
+ "run_id": "r_8f2a1c",
+ "seq": 13,
+ "hub_epoch": "e_fixture",
+ "message_id": "p_ui_1",
+ "activity_type": "json_render",
+ "patch": [
+ {
+ "op": "add",
+ "path": "/state",
+ "value": {
+ "slot": "s2",
+ "service": "Colour",
+ "remind": true,
+ "note": ""
+ }
+ }
+ ]
+ }
+ }
+ },
+ {
+ "type": "chat_run_event",
+ "data": {
+ "specversion": "1.0",
+ "id": "r_8f2a1c:14",
+ "source": "opencompany://services/chat",
+ "type": "com.opencompany.chat.run.activity.delta",
+ "subject": "r_8f2a1c",
+ "time": "2026-09-27T14:02:14.000Z",
+ "datacontenttype": "application/json",
+ "data": {
+ "workflow_id": "wf_salon",
+ "session_id": "wf_salon",
+ "run_id": "r_8f2a1c",
+ "seq": 14,
+ "hub_epoch": "e_fixture",
+ "message_id": "p_ui_1",
+ "activity_type": "json_render",
+ "patch": [
+ {
+ "op": "add",
+ "path": "/elements/root",
+ "value": {
+ "type": "Stack",
+ "props": {
+ "gap": "md"
+ },
+ "children": [
+ "slots",
+ "tooLong",
+ "details",
+ "acts"
+ ]
+ }
+ }
+ ]
+ }
+ }
+ },
+ {
+ "type": "chat_run_event",
+ "data": {
+ "specversion": "1.0",
+ "id": "r_8f2a1c:15",
+ "source": "opencompany://services/chat",
+ "type": "com.opencompany.chat.run.activity.delta",
+ "subject": "r_8f2a1c",
+ "time": "2026-09-27T14:02:15.000Z",
+ "datacontenttype": "application/json",
+ "data": {
+ "workflow_id": "wf_salon",
+ "session_id": "wf_salon",
+ "run_id": "r_8f2a1c",
+ "seq": 15,
+ "hub_epoch": "e_fixture",
+ "message_id": "p_ui_1",
+ "activity_type": "json_render",
+ "patch": [
+ {
+ "op": "add",
+ "path": "/elements/slots",
+ "value": {
+ "type": "SlotPicker",
+ "props": {
+ "label": "Saturday 28 Sep",
+ "hint": "Free 2-hour slots",
+ "value": {
+ "$bindState": "/slot"
+ },
+ "options": [
+ {
+ "id": "s1",
+ "time": "12:00",
+ "detail": "Jordan"
+ },
+ {
+ "id": "s2",
+ "time": "14:30",
+ "detail": "Ana",
+ "recommended": true
+ },
+ {
+ "id": "s3",
+ "time": "16:30",
+ "detail": "Ana",
+ "unavailable": true,
+ "note": "Only 1h free"
+ },
+ {
+ "id": "s4",
+ "time": "17:00",
+ "detail": "Jordan"
+ }
+ ]
+ }
+ }
+ }
+ ]
+ }
+ }
+ },
+ {
+ "type": "chat_run_event",
+ "data": {
+ "specversion": "1.0",
+ "id": "r_8f2a1c:16",
+ "source": "opencompany://services/chat",
+ "type": "com.opencompany.chat.run.activity.delta",
+ "subject": "r_8f2a1c",
+ "time": "2026-09-27T14:02:16.000Z",
+ "datacontenttype": "application/json",
+ "data": {
+ "workflow_id": "wf_salon",
+ "session_id": "wf_salon",
+ "run_id": "r_8f2a1c",
+ "seq": 16,
+ "hub_epoch": "e_fixture",
+ "message_id": "p_ui_1",
+ "activity_type": "json_render",
+ "patch": [
+ {
+ "op": "add",
+ "path": "/elements/tooLong",
+ "value": {
+ "type": "Callout",
+ "props": {
+ "tone": "warning",
+ "text": "Highlights take about 3 hours. Only the 12:00 slot with Jordan is long enough."
+ },
+ "visible": {
+ "$state": "/service",
+ "eq": "Highlights"
+ }
+ }
+ }
+ ]
+ }
+ }
+ },
+ {
+ "type": "chat_run_event",
+ "data": {
+ "specversion": "1.0",
+ "id": "r_8f2a1c:17",
+ "source": "opencompany://services/chat",
+ "type": "com.opencompany.chat.run.activity.delta",
+ "subject": "r_8f2a1c",
+ "time": "2026-09-27T14:02:17.000Z",
+ "datacontenttype": "application/json",
+ "data": {
+ "workflow_id": "wf_salon",
+ "session_id": "wf_salon",
+ "run_id": "r_8f2a1c",
+ "seq": 17,
+ "hub_epoch": "e_fixture",
+ "message_id": "p_ui_1",
+ "activity_type": "json_render",
+ "patch": [
+ {
+ "op": "add",
+ "path": "/elements/details",
+ "value": {
+ "type": "Card",
+ "props": {
+ "title": "Booking details",
+ "description": "The WhatsApp draft below updates as you change these."
+ },
+ "children": [
+ "svc",
+ "rem",
+ "remWhen",
+ "note"
+ ]
+ }
+ }
+ ]
+ }
+ }
+ },
+ {
+ "type": "chat_run_event",
+ "data": {
+ "specversion": "1.0",
+ "id": "r_8f2a1c:18",
+ "source": "opencompany://services/chat",
+ "type": "com.opencompany.chat.run.activity.delta",
+ "subject": "r_8f2a1c",
+ "time": "2026-09-27T14:02:18.000Z",
+ "datacontenttype": "application/json",
+ "data": {
+ "workflow_id": "wf_salon",
+ "session_id": "wf_salon",
+ "run_id": "r_8f2a1c",
+ "seq": 18,
+ "hub_epoch": "e_fixture",
+ "message_id": "p_ui_1",
+ "activity_type": "json_render",
+ "patch": [
+ {
+ "op": "add",
+ "path": "/elements/svc",
+ "value": {
+ "type": "Select",
+ "props": {
+ "label": "Service",
+ "value": {
+ "$bindState": "/service"
+ },
+ "options": [
+ "Colour",
+ "Colour & cut",
+ "Highlights"
+ ]
+ }
+ }
+ }
+ ]
+ }
+ }
+ },
+ {
+ "type": "chat_run_event",
+ "data": {
+ "specversion": "1.0",
+ "id": "r_8f2a1c:19",
+ "source": "opencompany://services/chat",
+ "type": "com.opencompany.chat.run.activity.delta",
+ "subject": "r_8f2a1c",
+ "time": "2026-09-27T14:02:19.000Z",
+ "datacontenttype": "application/json",
+ "data": {
+ "workflow_id": "wf_salon",
+ "session_id": "wf_salon",
+ "run_id": "r_8f2a1c",
+ "seq": 19,
+ "hub_epoch": "e_fixture",
+ "message_id": "p_ui_1",
+ "activity_type": "json_render",
+ "patch": [
+ {
+ "op": "add",
+ "path": "/elements/rem",
+ "value": {
+ "type": "Toggle",
+ "props": {
+ "label": "Remind her the day before",
+ "checked": {
+ "$bindState": "/remind"
+ }
+ }
+ }
+ }
+ ]
+ }
+ }
+ },
+ {
+ "type": "chat_run_event",
+ "data": {
+ "specversion": "1.0",
+ "id": "r_8f2a1c:20",
+ "source": "opencompany://services/chat",
+ "type": "com.opencompany.chat.run.activity.delta",
+ "subject": "r_8f2a1c",
+ "time": "2026-09-27T14:02:20.000Z",
+ "datacontenttype": "application/json",
+ "data": {
+ "workflow_id": "wf_salon",
+ "session_id": "wf_salon",
+ "run_id": "r_8f2a1c",
+ "seq": 20,
+ "hub_epoch": "e_fixture",
+ "message_id": "p_ui_1",
+ "activity_type": "json_render",
+ "patch": [
+ {
+ "op": "add",
+ "path": "/elements/remWhen",
+ "value": {
+ "type": "Text",
+ "props": {
+ "text": "Goes out on WhatsApp at 6pm on Friday."
+ },
+ "visible": {
+ "$state": "/remind"
+ }
+ }
+ }
+ ]
+ }
+ }
+ },
+ {
+ "type": "chat_run_event",
+ "data": {
+ "specversion": "1.0",
+ "id": "r_8f2a1c:21",
+ "source": "opencompany://services/chat",
+ "type": "com.opencompany.chat.run.activity.delta",
+ "subject": "r_8f2a1c",
+ "time": "2026-09-27T14:02:21.000Z",
+ "datacontenttype": "application/json",
+ "data": {
+ "workflow_id": "wf_salon",
+ "session_id": "wf_salon",
+ "run_id": "r_8f2a1c",
+ "seq": 21,
+ "hub_epoch": "e_fixture",
+ "message_id": "p_ui_1",
+ "activity_type": "json_render",
+ "patch": [
+ {
+ "op": "add",
+ "path": "/elements/note",
+ "value": {
+ "type": "TextField",
+ "props": {
+ "label": "Note for the stylist",
+ "value": {
+ "$bindState": "/note"
+ },
+ "placeholder": "e.g. patch test done in June"
+ }
+ }
+ }
+ ]
+ }
+ }
+ },
+ {
+ "type": "chat_run_event",
+ "data": {
+ "specversion": "1.0",
+ "id": "r_8f2a1c:22",
+ "source": "opencompany://services/chat",
+ "type": "com.opencompany.chat.run.activity.delta",
+ "subject": "r_8f2a1c",
+ "time": "2026-09-27T14:02:22.000Z",
+ "datacontenttype": "application/json",
+ "data": {
+ "workflow_id": "wf_salon",
+ "session_id": "wf_salon",
+ "run_id": "r_8f2a1c",
+ "seq": 22,
+ "hub_epoch": "e_fixture",
+ "message_id": "p_ui_1",
+ "activity_type": "json_render",
+ "patch": [
+ {
+ "op": "add",
+ "path": "/elements/acts",
+ "value": {
+ "type": "Row",
+ "props": {
+ "gap": "sm"
+ },
+ "children": [
+ "hold",
+ "sun"
+ ]
+ }
+ }
+ ]
+ }
+ }
+ },
+ {
+ "type": "chat_run_event",
+ "data": {
+ "specversion": "1.0",
+ "id": "r_8f2a1c:23",
+ "source": "opencompany://services/chat",
+ "type": "com.opencompany.chat.run.activity.delta",
+ "subject": "r_8f2a1c",
+ "time": "2026-09-27T14:02:23.000Z",
+ "datacontenttype": "application/json",
+ "data": {
+ "workflow_id": "wf_salon",
+ "session_id": "wf_salon",
+ "run_id": "r_8f2a1c",
+ "seq": 23,
+ "hub_epoch": "e_fixture",
+ "message_id": "p_ui_1",
+ "activity_type": "json_render",
+ "patch": [
+ {
+ "op": "add",
+ "path": "/elements/hold",
+ "value": {
+ "type": "Button",
+ "props": {
+ "label": "Hold this slot for 15 min",
+ "variant": "primary"
+ },
+ "on": {
+ "press": {
+ "action": "holdSlot",
+ "params": {
+ "slot": {
+ "$state": "/slot"
+ }
+ }
+ }
+ }
+ }
+ }
+ ]
+ }
+ }
+ },
+ {
+ "type": "chat_run_event",
+ "data": {
+ "specversion": "1.0",
+ "id": "r_8f2a1c:24",
+ "source": "opencompany://services/chat",
+ "type": "com.opencompany.chat.run.activity.delta",
+ "subject": "r_8f2a1c",
+ "time": "2026-09-27T14:02:24.000Z",
+ "datacontenttype": "application/json",
+ "data": {
+ "workflow_id": "wf_salon",
+ "session_id": "wf_salon",
+ "run_id": "r_8f2a1c",
+ "seq": 24,
+ "hub_epoch": "e_fixture",
+ "message_id": "p_ui_1",
+ "activity_type": "json_render",
+ "patch": [
+ {
+ "op": "add",
+ "path": "/elements/sun",
+ "value": {
+ "type": "Button",
+ "props": {
+ "label": "Show Sunday instead"
+ },
+ "on": {
+ "press": {
+ "action": "ask",
+ "params": {
+ "text": "What does Sunday look like?"
+ }
+ }
+ }
+ }
+ }
+ ]
+ }
+ }
+ },
+ {
+ "type": "chat_run_event",
+ "data": {
+ "specversion": "1.0",
+ "id": "r_8f2a1c:25",
+ "source": "opencompany://services/chat",
+ "type": "com.opencompany.chat.run.tool_call.started",
+ "subject": "r_8f2a1c",
+ "time": "2026-09-27T14:02:25.000Z",
+ "datacontenttype": "application/json",
+ "data": {
+ "workflow_id": "wf_salon",
+ "session_id": "wf_salon",
+ "run_id": "r_8f2a1c",
+ "seq": 25,
+ "hub_epoch": "e_fixture",
+ "tool_call_id": "call_8f2a1c",
+ "tool_call_name": "whatsapp_send",
+ "parent_message_id": "a_r_8f2a1c",
+ "label": "WhatsApp"
+ }
+ }
+ },
+ {
+ "type": "chat_run_event",
+ "data": {
+ "specversion": "1.0",
+ "id": "r_8f2a1c:26",
+ "source": "opencompany://services/chat",
+ "type": "com.opencompany.chat.run.tool_call.args",
+ "subject": "r_8f2a1c",
+ "time": "2026-09-27T14:02:26.000Z",
+ "datacontenttype": "application/json",
+ "data": {
+ "workflow_id": "wf_salon",
+ "session_id": "wf_salon",
+ "run_id": "r_8f2a1c",
+ "seq": 26,
+ "hub_epoch": "e_fixture",
+ "tool_call_id": "call_8f2a1c",
+ "delta": "{\"phone\": \"Priya Shah\", \"message\": \"Hi Priya! Saturday at 14:30 is free for a colour with Ana (about 2 hours). Shall I book you in? I’ll send you a reminder the day before.\"}"
+ }
+ }
+ },
+ {
+ "type": "chat_run_event",
+ "data": {
+ "specversion": "1.0",
+ "id": "r_8f2a1c:27",
+ "source": "opencompany://services/chat",
+ "type": "com.opencompany.chat.run.tool_call.ended",
+ "subject": "r_8f2a1c",
+ "time": "2026-09-27T14:02:27.000Z",
+ "datacontenttype": "application/json",
+ "data": {
+ "workflow_id": "wf_salon",
+ "session_id": "wf_salon",
+ "run_id": "r_8f2a1c",
+ "seq": 27,
+ "hub_epoch": "e_fixture",
+ "tool_call_id": "call_8f2a1c"
+ }
+ }
+ },
+ {
+ "type": "chat_run_event",
+ "data": {
+ "specversion": "1.0",
+ "id": "r_8f2a1c:28",
+ "source": "opencompany://services/chat",
+ "type": "com.opencompany.chat.run.activity.snapshot",
+ "subject": "r_8f2a1c",
+ "time": "2026-09-27T14:02:28.000Z",
+ "datacontenttype": "application/json",
+ "data": {
+ "workflow_id": "wf_salon",
+ "session_id": "wf_salon",
+ "run_id": "r_8f2a1c",
+ "seq": 28,
+ "hub_epoch": "e_fixture",
+ "message_id": "p_approval_1",
+ "activity_type": "approval",
+ "content": {
+ "approval_id": "ap_1",
+ "tool_call_id": "call_8f2a1c",
+ "status": "pending"
+ },
+ "replace": true
+ }
+ }
+ },
+ {
+ "type": "chat_run_event",
+ "data": {
+ "specversion": "1.0",
+ "id": "r_8f2a1c:29",
+ "source": "opencompany://services/chat",
+ "type": "com.opencompany.chat.run.finished",
+ "subject": "r_8f2a1c",
+ "time": "2026-09-27T14:02:29.000Z",
+ "datacontenttype": "application/json",
+ "data": {
+ "workflow_id": "wf_salon",
+ "session_id": "wf_salon",
+ "run_id": "r_8f2a1c",
+ "seq": 29,
+ "hub_epoch": "e_fixture",
+ "outcome": {
+ "type": "interrupt",
+ "interrupts": [
+ {
+ "id": "ap_1",
+ "reason": "tool_call",
+ "message": "Maya wants to send a message",
+ "tool_call_id": "call_8f2a1c",
+ "response_schema": {
+ "type": "object",
+ "properties": {
+ "approved": {
+ "type": "boolean"
+ },
+ "edited_args": {
+ "type": "object"
+ }
+ },
+ "required": [
+ "approved"
+ ]
+ },
+ "expires_at": "2026-10-04T14:02:00.000Z"
+ }
+ ]
+ },
+ "result": {
+ "reply_message_id": "a_r_8f2a1c"
+ },
+ "duration_ms": 9000,
+ "step_count": 3
+ }
+ }
+ },
+ {
+ "type": "chat_run_event",
+ "data": {
+ "specversion": "1.0",
+ "id": "r_9b3d2e:1",
+ "source": "opencompany://services/chat",
+ "type": "com.opencompany.chat.run.started",
+ "subject": "r_9b3d2e",
+ "time": "2026-09-27T14:02:30.000Z",
+ "datacontenttype": "application/json",
+ "data": {
+ "workflow_id": "wf_salon",
+ "session_id": "wf_salon",
+ "run_id": "r_9b3d2e",
+ "seq": 1,
+ "hub_epoch": "e_fixture",
+ "kind": "resume",
+ "parent_run_id": "r_8f2a1c",
+ "reply_message_id": "a_r_8f2a1c",
+ "started_at": "2026-09-27T14:03:10.000Z"
+ }
+ }
+ },
+ {
+ "type": "chat_run_event",
+ "data": {
+ "specversion": "1.0",
+ "id": "r_9b3d2e:2",
+ "source": "opencompany://services/chat",
+ "type": "com.opencompany.chat.run.tool_call.result",
+ "subject": "r_9b3d2e",
+ "time": "2026-09-27T14:02:31.000Z",
+ "datacontenttype": "application/json",
+ "data": {
+ "workflow_id": "wf_salon",
+ "session_id": "wf_salon",
+ "run_id": "r_9b3d2e",
+ "seq": 2,
+ "hub_epoch": "e_fixture",
+ "message_id": "t_call_8f2a1c",
+ "tool_call_id": "call_8f2a1c",
+ "content": "{\"status\": \"sent\", \"approved_by\": \"user\"}",
+ "role": "tool"
+ }
+ }
+ },
+ {
+ "type": "chat_run_event",
+ "data": {
+ "specversion": "1.0",
+ "id": "r_9b3d2e:3",
+ "source": "opencompany://services/chat",
+ "type": "com.opencompany.chat.run.activity.delta",
+ "subject": "r_9b3d2e",
+ "time": "2026-09-27T14:02:32.000Z",
+ "datacontenttype": "application/json",
+ "data": {
+ "workflow_id": "wf_salon",
+ "session_id": "wf_salon",
+ "run_id": "r_9b3d2e",
+ "seq": 3,
+ "hub_epoch": "e_fixture",
+ "message_id": "p_approval_1",
+ "activity_type": "approval",
+ "patch": [
+ {
+ "op": "replace",
+ "path": "/status",
+ "value": "sent"
+ }
+ ]
+ }
+ }
+ },
+ {
+ "type": "chat_run_event",
+ "data": {
+ "specversion": "1.0",
+ "id": "r_9b3d2e:4",
+ "source": "opencompany://services/chat",
+ "type": "com.opencompany.chat.run.finished",
+ "subject": "r_9b3d2e",
+ "time": "2026-09-27T14:02:33.000Z",
+ "datacontenttype": "application/json",
+ "data": {
+ "workflow_id": "wf_salon",
+ "session_id": "wf_salon",
+ "run_id": "r_9b3d2e",
+ "seq": 4,
+ "hub_epoch": "e_fixture",
+ "outcome": {
+ "type": "success"
+ },
+ "result": {
+ "reply_message_id": "a_r_8f2a1c"
+ },
+ "duration_ms": 5200,
+ "step_count": 0
+ }
+ }
+ }
+]
diff --git a/client/src/features/chat/__fixtures__/saturday-booking.patches.jsonl b/client/src/features/chat/__fixtures__/saturday-booking.patches.jsonl
new file mode 100644
index 00000000..10491dcc
--- /dev/null
+++ b/client/src/features/chat/__fixtures__/saturday-booking.patches.jsonl
@@ -0,0 +1,13 @@
+{"op":"add","path":"/root","value":"root"}
+{"op":"add","path":"/state","value":{"slot":"s2","service":"Colour","remind":true,"note":""}}
+{"op":"add","path":"/elements/root","value":{"type":"Stack","props":{"gap":"md"},"children":["slots","tooLong","details","acts"]}}
+{"op":"add","path":"/elements/slots","value":{"type":"SlotPicker","props":{"label":"Saturday 28 Sep","hint":"Free 2-hour slots","value":{"$bindState":"/slot"},"options":[{"id":"s1","time":"12:00","detail":"Jordan"},{"id":"s2","time":"14:30","detail":"Ana","recommended":true},{"id":"s3","time":"16:30","detail":"Ana","unavailable":true,"note":"Only 1h free"},{"id":"s4","time":"17:00","detail":"Jordan"}]}}}
+{"op":"add","path":"/elements/tooLong","value":{"type":"Callout","props":{"tone":"warning","text":"Highlights take about 3 hours. Only the 12:00 slot with Jordan is long enough."},"visible":{"$state":"/service","eq":"Highlights"}}}
+{"op":"add","path":"/elements/details","value":{"type":"Card","props":{"title":"Booking details","description":"The WhatsApp draft below updates as you change these."},"children":["svc","rem","remWhen","note"]}}
+{"op":"add","path":"/elements/svc","value":{"type":"Select","props":{"label":"Service","value":{"$bindState":"/service"},"options":["Colour","Colour & cut","Highlights"]}}}
+{"op":"add","path":"/elements/rem","value":{"type":"Toggle","props":{"label":"Remind her the day before","checked":{"$bindState":"/remind"}}}}
+{"op":"add","path":"/elements/remWhen","value":{"type":"Text","props":{"text":"Goes out on WhatsApp at 6pm on Friday."},"visible":{"$state":"/remind"}}}
+{"op":"add","path":"/elements/note","value":{"type":"TextField","props":{"label":"Note for the stylist","value":{"$bindState":"/note"},"placeholder":"e.g. patch test done in June"}}}
+{"op":"add","path":"/elements/acts","value":{"type":"Row","props":{"gap":"sm"},"children":["hold","sun"]}}
+{"op":"add","path":"/elements/hold","value":{"type":"Button","props":{"label":"Hold this slot for 15 min","variant":"primary"},"on":{"press":{"action":"holdSlot","params":{"slot":{"$state":"/slot"}}}}}}
+{"op":"add","path":"/elements/sun","value":{"type":"Button","props":{"label":"Show Sunday instead"},"on":{"press":{"action":"ask","params":{"text":"What does Sunday look like?"}}}}}
diff --git a/client/src/features/chat/__fixtures__/saturday-booking.spec.json b/client/src/features/chat/__fixtures__/saturday-booking.spec.json
new file mode 100644
index 00000000..e506624b
--- /dev/null
+++ b/client/src/features/chat/__fixtures__/saturday-booking.spec.json
@@ -0,0 +1,165 @@
+{
+ "root": "root",
+ "state": {
+ "slot": "s2",
+ "service": "Colour",
+ "remind": true,
+ "note": ""
+ },
+ "elements": {
+ "root": {
+ "type": "Stack",
+ "props": {
+ "gap": "md"
+ },
+ "children": [
+ "slots",
+ "tooLong",
+ "details",
+ "acts"
+ ]
+ },
+ "slots": {
+ "type": "SlotPicker",
+ "props": {
+ "label": "Saturday 28 Sep",
+ "hint": "Free 2-hour slots",
+ "value": {
+ "$bindState": "/slot"
+ },
+ "options": [
+ {
+ "id": "s1",
+ "time": "12:00",
+ "detail": "Jordan"
+ },
+ {
+ "id": "s2",
+ "time": "14:30",
+ "detail": "Ana",
+ "recommended": true
+ },
+ {
+ "id": "s3",
+ "time": "16:30",
+ "detail": "Ana",
+ "unavailable": true,
+ "note": "Only 1h free"
+ },
+ {
+ "id": "s4",
+ "time": "17:00",
+ "detail": "Jordan"
+ }
+ ]
+ }
+ },
+ "tooLong": {
+ "type": "Callout",
+ "props": {
+ "tone": "warning",
+ "text": "Highlights take about 3 hours. Only the 12:00 slot with Jordan is long enough."
+ },
+ "visible": {
+ "$state": "/service",
+ "eq": "Highlights"
+ }
+ },
+ "details": {
+ "type": "Card",
+ "props": {
+ "title": "Booking details",
+ "description": "The WhatsApp draft below updates as you change these."
+ },
+ "children": [
+ "svc",
+ "rem",
+ "remWhen",
+ "note"
+ ]
+ },
+ "svc": {
+ "type": "Select",
+ "props": {
+ "label": "Service",
+ "value": {
+ "$bindState": "/service"
+ },
+ "options": [
+ "Colour",
+ "Colour & cut",
+ "Highlights"
+ ]
+ }
+ },
+ "rem": {
+ "type": "Toggle",
+ "props": {
+ "label": "Remind her the day before",
+ "checked": {
+ "$bindState": "/remind"
+ }
+ }
+ },
+ "remWhen": {
+ "type": "Text",
+ "props": {
+ "text": "Goes out on WhatsApp at 6pm on Friday."
+ },
+ "visible": {
+ "$state": "/remind"
+ }
+ },
+ "note": {
+ "type": "TextField",
+ "props": {
+ "label": "Note for the stylist",
+ "value": {
+ "$bindState": "/note"
+ },
+ "placeholder": "e.g. patch test done in June"
+ }
+ },
+ "acts": {
+ "type": "Row",
+ "props": {
+ "gap": "sm"
+ },
+ "children": [
+ "hold",
+ "sun"
+ ]
+ },
+ "hold": {
+ "type": "Button",
+ "props": {
+ "label": "Hold this slot for 15 min",
+ "variant": "primary"
+ },
+ "on": {
+ "press": {
+ "action": "holdSlot",
+ "params": {
+ "slot": {
+ "$state": "/slot"
+ }
+ }
+ }
+ }
+ },
+ "sun": {
+ "type": "Button",
+ "props": {
+ "label": "Show Sunday instead"
+ },
+ "on": {
+ "press": {
+ "action": "ask",
+ "params": {
+ "text": "What does Sunday look like?"
+ }
+ }
+ }
+ }
+ }
+}
diff --git a/docs-internal/chat_protocol.md b/docs-internal/chat_protocol.md
new file mode 100644
index 00000000..a9a2fb56
--- /dev/null
+++ b/docs-internal/chat_protocol.md
@@ -0,0 +1,231 @@
+# Chat protocol (v1)
+
+The wire contract between the server's chat runtime (`server/services/chat/`) and the shared chat UI
+(`client/src/features/chat/`). Home's employee page and Dev's console Chat pane both speak it. It follows AG-UI's
+event model and ordering ([events](https://docs.ag-ui.com/concepts/events),
+[interrupts](https://docs.ag-ui.com/concepts/interrupts.md),
+[activity events](https://docs.ag-ui.com/spec/1.0/events/activity.md)), carried on the existing WebSocket with
+snake_case fields in the repo's CloudEvents envelope (`services/events/envelope.py`), never as literal camelCase
+AG-UI JSON.
+
+Status: being built on `feature/chat-genui`; the design and the owner's decisions are in the plan recorded at
+`~/.claude/plans/analyze-the-new-generative-zazzy-cosmos.md`. Change this document in the same commit as any change
+to the shapes below, and bump `protocol_version` when an existing field changes meaning.
+
+## Concepts
+
+| Term | Meaning |
+|---|---|
+| Session | One conversation. Its id is the workflow id (`"default"` with no workflow open). |
+| Run | One answer the employee works on: an owner message, an edit, a regenerate, or a button press in generated UI (kinds `message`, `edit`, `regenerate`, `action`). Approved sends execute as runs of kind `resume`. |
+| Lane | At most one non-terminal run per session, `resume` runs excepted. A second send is refused with `run_in_progress`; the composer shows Stop instead of Send while a run is live. |
+| Message tree | Messages link to their parent. Owner messages that share a parent are branches; replies under the same owner message are versions. The session's active leaf picks the path shown. |
+| Part | Structured content attached to a reply: steps, generated UI, artifacts, approvals, sources, follow-ups. |
+| Generation | The deployment generation a message was written in (`run_key`). A Reset clears the thread. |
+
+## Delivery
+
+Run events never ride `StatusBroadcaster.broadcast` (which reaches every socket). A socket receives a session's run
+events only after `chat_subscribe` succeeds. That handler applies the same checks as the canvas handlers: refuse the
+internal socket, load the workflow, and compare its owner with the socket's execution principal.
+
+```json
+{"type": "chat_run_event",
+ "data": {"specversion": "1.0", "id": "r_7f3c…:12", "source": "opencompany://services/chat",
+ "type": "com.opencompany.chat.run.text.content", "subject": "r_7f3c…",
+ "time": "2026-10-03T21:40:12.512Z", "datacontenttype": "application/json",
+ "data": {"workflow_id": "…", "session_id": "…", "run_id": "r_7f3c…", "seq": 12,
+ "hub_epoch": "e_91ab…", "message_id": "r_7f3c….0.1", "delta": "Saturday is "}}}
+```
+
+- Scope fields (`workflow_id`, `session_id`, `run_id`) live inside `data`, never as top-level CloudEvents extension
+ attributes.
+- `seq` increases by one per run. The client drops duplicates `(run_id, seq)` and asks for a snapshot on a gap.
+- `hub_epoch` changes when the server process restarts. A changed epoch means the client must resync.
+- Each subscriber has a bounded queue. Under pressure the hub merges consecutive text deltas of one segment, never
+ drops lifecycle events, and finally sends `custom` `opencompany.resync`.
+- `chat.updated` remains an identity-only broadcast (`{workflow_id, session_id, role}`) that tells every open thread
+ to refetch `get_chat_messages`.
+
+## Events
+
+Every event's `data` carries `{workflow_id, session_id, run_id, seq, hub_epoch}` plus the fields below. The CloudEvents
+`type` is `com.opencompany.chat.run.<suffix>`; `subject` is the run id; `id` is `<run_id>:<seq>`.
+
+| AG-UI event | Suffix | Fields |
+|---|---|---|
+| RUN_STARTED | `started` | `kind`, `parent_run_id?`, `user_message_id?`, `reply_message_id`, `started_at` |
+| RUN_FINISHED | `finished` | `outcome` (below), `result {reply_message_id?, no_reply?}`, `duration_ms`, `step_count` |
+| RUN_ERROR | `failed` | `message` (safe to show, at most 500 chars), `code`, `hint?`, `requires_user_action?` |
+| STEP_STARTED | `step.started` | `step_id`, `step_name`, `icon?`, `agent_node_id`, `tool_node_id?`, `attempt` |
+| STEP_FINISHED | `step.finished` | `step_id`, `step_name` (the done label), `state` (`done`, `failed`, `skipped`), `detail?`, `duration_ms`, `narration?` |
+| TEXT_MESSAGE_START | `text.started` | `message_id` (segment id `{run_id}.{iteration}.{attempt}`), `role: "assistant"`, `agent_node_id` |
+| TEXT_MESSAGE_CONTENT | `text.content` | `message_id`, `delta` (never empty) |
+| TEXT_MESSAGE_END | `text.ended` | `message_id`, `final` (bool), `reply_message_id?`, `output_tokens?` |
+| TOOL_CALL_START | `tool_call.started` | `tool_call_id`, `tool_call_name`, `parent_message_id?`, `label` (sending tools only) |
+| TOOL_CALL_ARGS | `tool_call.args` | `tool_call_id`, `delta` |
+| TOOL_CALL_END | `tool_call.ended` | `tool_call_id` |
+| TOOL_CALL_RESULT | `tool_call.result` | `message_id`, `tool_call_id`, `content` (a JSON string), `role: "tool"` |
+| ACTIVITY_SNAPSHOT | `activity.snapshot` | `message_id` (the part id), `activity_type`, `content` (an object), `replace` |
+| ACTIVITY_DELTA | `activity.delta` | `message_id`, `activity_type`, `patch` (RFC 6902 operations on `content`) |
+| REASONING_START / END | `reasoning.started` / `reasoning.ended` | `message_id`; lifecycle only, no reasoning text |
+| CUSTOM | `custom` | `name`, `value` |
+
+`activity_type` values: `json_render`, `approval`, `sources`, `followups`, `artifact`.
+
+`custom` names: `opencompany.segment_discarded` (`{message_id}`: a retried LLM attempt replaces this segment),
+`opencompany.retrying` (`{retry_after?, attempt}`), `opencompany.stopping`, `opencompany.resync`.
+
+**Text segments.** Only the agent that answers the owner streams text. A segment that ends with `final: false`
+accompanied a tool call: the client folds it into the steps as narration. The segment with `final: true` is the
+reply. Text that could still turn out to be `NO_REPLY` or a `<followups>` block is held back on the server and never
+streamed.
+
+**Outcomes** (`run.finished`):
+
+| `outcome.type` | Meaning |
+|---|---|
+| `success` | The run ended. `result.reply_message_id` names the saved reply, or `result.no_reply` is true. |
+| `interrupt` | Drafts wait for the owner. `outcome.interrupts: [{id, reason: "tool_call", message, tool_call_id, response_schema, expires_at}]`; `id` is the approval id. |
+| `stopped` | The owner pressed Stop. OpenCompany extension; AG-UI defines only `success` and `interrupt`. |
+
+Never-picked-up runs end with `run.failed` code `not_delivered`; a Reset ends live runs with code `reset`.
+
+## Handlers
+
+All are WebSocket request/response handlers with snake_case payloads. Failures answer
+`{success: false, error: "<code>", …}`.
+
+### Chat (`server/services/chat/handlers.py`)
+
+| Handler | Request | Response |
+|---|---|---|
+| `send_chat_message` | `{session_id, message, role: "user", timestamp?, client_message_id?, attachments?: FileRef[], options?: {web?}, ui_event?: {part_id, element_id, action, params}}` | `{success, message_id, run_id, delivery: "now" \| "queued", timestamp}` |
+| `get_chat_messages` | `{session_id, limit?, all_generations?}` | `{success, messages, thread: {active_leaf_id, revision}, active_runs}` |
+| `chat_subscribe` / `chat_unsubscribe` | `{session_id}` | `{success, hub_epoch, active_runs: [RunSnapshot]}` |
+| `get_chat_run` | `{run_id}` | `{success, run: RunSnapshot}` |
+| `stop_chat_run` | `{run_id}` or `{session_id}` | `{success, run_id, state}` |
+| `edit_chat_message` | `{message_id, text, attachments?, expected_revision}` | `{success, message_id, run_id}` |
+| `regenerate_chat_reply` | `{message_id, expected_revision}` | `{success, run_id}` |
+| `switch_chat_branch` | `{message_id, target_id, expected_revision}` | `{success, thread}` |
+| `set_chat_feedback` | `{message_id, rating: "good" \| "bad" \| null, comment?}` | `{success, reaches: ["next_reply", "memory"?]}` |
+| `get_chat_context` | `{session_id}` | `{success, commands, suggestions, capabilities, genui_catalog, limits, ask_first: {value, editable, replies_gated}}` |
+| `clear_chat_messages` | `{session_id}` | `{success}`; also clears runs, parts, snapshots, notes and feedback, and makes the employee forget the conversation |
+
+`send_chat_message` with the same `client_message_id` returns the run the first call created.
+
+**RunSnapshot** is the state the client reducer would hold after replaying the run's events:
+`{run_id, kind, state, seq, steps, segments: [{message_id, text, final}], activities, interrupts, started_at}`.
+
+### Approvals (`server/services/approvals/handlers.py`)
+
+| Handler | Request | Response |
+|---|---|---|
+| `list_approvals` | `{workflow_id?, status?: str \| [str] \| "open" \| "recent", run_id?, kind?, limit?}` | `{success, approvals, counts, server_time}` |
+| `get_approvals` | `{approval_ids}` (at most 50) | `{success, approvals, server_time}` |
+| `decide_approval` | `{approval_id, decision: "send" \| "discard" \| "undo" \| "restore" \| "retry", decision_key, edited_args?, text?, subject?, expected_revision?, confirm?}` | `{success, approval, will_send_on_resume, execution}` |
+| `resolve_interrupt` | `{interrupt_id, status: "resolved" \| "cancelled", payload: {approved, edited_args?}, decision_key}` | as `decide_approval` |
+| `set_ask_first` | `{workflow_id, ask_first, expected_revision?}` | `{success, ask_first, revision, replies_gated, needs_apply}` |
+
+`edited_args` replaces the call's arguments in full and may differ from them only in the editable keys. The approval
+summary adds `kind` (`gate` or `tool_call`), `node_type`, `tool_name`, `tool_call_id`, `run_id`, `args`, `editable`,
+`body_field`, `subject_field`, `approved_by` (`user` or `auto`), `undo_until`, `restore_until` and
+`outcome {certainty: "sent" | "not_sent" | "unknown", error?, at}`.
+
+### Plugins
+
+| Handler | Owner | Request | Response |
+|---|---|---|---|
+| `chat_ui_state` | `nodes/chat/chat_ui` | `{workflow_id, part_id, delta: [{op: "replace" \| "add", path, value}], base_revision}` | `{success, state_revision}` or `stale` |
+| `canvas_versions` | `nodes/tool/canvas` | `{workflow_id, node_id, item_id}` | `{success, versions: [{version, title, created_at, source, size_bytes}], latest}` |
+| `canvas_version` | `nodes/tool/canvas` | `{workflow_id, node_id, item_id, version}` | `{success, item_id, version, title, content, language, created_at, filename}` |
+| `transcribe_audio` | `nodes/speech` | `{workflow_id, audio: FileRef, language?}` | `{success, text, provider, model, duration_seconds}` |
+
+## Messages
+
+`get_chat_messages` returns the active path, oldest first:
+
+```
+{id, legacy_id, role, kind, text, message, timestamp, run_key, run_id, parent_id, status, attachments,
+ parts, feedback, siblings: {index, count, ids}, editable}
+```
+
+- `message` equals `text`; it is kept for older readers.
+- `kind`: `text`, `report` (Post to Talk: no parent, not editable), `action` (a button press), `notice`.
+- `status`: `complete`, `stopped`, `error`.
+- `siblings` are branches for owner messages and versions for replies.
+
+Parts render in this order, whatever order they were produced in: steps, text, generated UI, artifacts, approvals,
+sources, follow-ups.
+
+```
+parts: {
+ steps?: {duration_ms, items: [{step_id, name, state, detail?, duration_ms?}]},
+ ui?: [{part_id, ui_id, title?, spec, state, state_revision, elements}],
+ artifacts?: [{workflow_id, canvas_node_id, item_id, version, title, format}],
+ approvals?: [{approval_id, tool_call_id?}],
+ sources?: [{n, display, label, detail?, url?, kind, cited}],
+ followups?: [string],
+ stopped?: true
+}
+```
+
+Approvals are joined live from the approvals store; the part only names them.
+
+## Generated UI
+
+- **Source.** The employee calls the `show_ui` tool (`chatUi` plugin) with a json-render flat spec
+ `{root, state, elements}`. The server validates it against `server/config/chat_genui_catalog.json`, the single
+ source of truth for the client catalog, and streams it as `activity.snapshot` (empty spec) followed by one
+ `activity.delta` per patch: `add /root`, `add /state`, then `add /elements/<id>` in depth-first order.
+- **Owner edits.** `$bindState` writes stay in the message's local state and are sent with `chat_ui_state`; the last
+ write per path wins, and the client flushes after 300 ms idle, on blur, before an action and when the page hides.
+ The employee sees the state on its next turn as a `[ui-state]` note.
+- **Buttons.** A press resolves `$state` params at click time. `ask` sends its text as the owner's message only when
+ it equals the button's label; otherwise the text goes into the composer for review. Any other action becomes
+ `send_chat_message{ui_event}`; the server checks it against the saved spec and starts a run of kind `action`
+ whose turn carries `[ui-event]{…}[/ui-event]`.
+- **Sanitising.** json-render 0.21 does not guard state paths (`setByPath` descends into `__proto__`), does not
+ validate props against the catalog, and supports `watch` (actions fired by state changes), `repeat`, `$computed`
+ and `confirm`. Both sides therefore:
+ - refuse `__proto__`, `constructor` and `prototype` path segments everywhere (`$state`, `$bindState`, `$template`,
+ `visible`, action params, patch paths);
+ - strip `watch`, `repeat`, `slots`, `$computed` and `confirm`;
+ - validate every element's props (the client degrades one bad prop at a time with forgiving zod schemas);
+ - drop unknown component types before rendering.
+
+ json-render renders each element inside its own error boundary, so one failing element renders nothing instead of
+ breaking the reply.
+
+## Notes to the employee
+
+Things the employee should learn on its next turn are queued in `chat_notes` and prepended to that turn's user
+message in brackets: `[updates]` (approval outcomes), `[ui-state]`, `[feedback]`. The agent's system prompt says that
+bracketed lines come from OpenCompany, not from the owner. Notes are claimed when the next run's payload is prepared
+and marked delivered when its conversation is saved, so a failed run offers them again.
+
+## Fixtures
+
+`client/src/features/chat/__fixtures__/` holds the design handoff's examples in this protocol's shapes, for client
+and server tests alike:
+
+- `<name>.spec.json` and `<name>.patches.jsonl` (`saturday-booking`, `reply-insights`, `reminders`): json-render
+ specs and the depth-first patch stream for each. SlotPicker options use the catalog's generic keys (`time`,
+ `detail`, `recommended`, `unavailable`, `note`) instead of the handoff's salon ones.
+- `saturday-booking.events.json`: the handoff's AG-UI run as `chat_run_event` frames — steps, text, a generated UI
+ streamed as `activity.delta` patches, a held WhatsApp send ending the run with an `interrupt` outcome, and the
+ `resume` run that sends it once the owner presses Send.
+
+## Error codes
+
+| Code | Where | Meaning |
+|---|---|---|
+| `run_in_progress` | send, edit, regenerate, switch | A run is live in this session; `run_id` names it. |
+| `save_failed` | send | The message could not be saved; nothing was dispatched. |
+| `not_running` | send | The employee is not running and cannot queue messages. |
+| `conflict` | edit, regenerate, switch, set_ask_first | `expected_revision` is stale. |
+| `not_editable` | edit, regenerate, decide | The message belongs to an older generation, its prefix was compacted, or an edited argument is not editable. |
+| `ui_event_rejected` | send | The element or action does not match the saved spec. |
+| `access_denied` | all | The socket's principal does not own the workflow. |
+| `too_late` | decide | The Undo or Restore window has passed. |
+| `speech_unavailable` | transcribe_audio | No dictation provider has a stored key. |