Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
docs(chat): add the chat wire protocol, handoff fixtures and json-render
trohitg1d710cea1883
diff --git a/bun.lock b/bun.lockindex 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.jsonindex 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.jsonlnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonlnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonlnew file mode 100644index 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.jsonnew file mode 100644index 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.mdnew file mode 100644index 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. |