@happyvertical/smrt-chat 0.56.0 → 0.56.2

package/dist/smrt-knowledge.json

@@ -3,13 +3,13 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-chat",
-  "packageVersion": "0.56.0",
+  "packageVersion": "0.56.2",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "3efffe7554e94afc6894f89b2ee0ea7da865389eeaee742064fe697da93c2bd6",
-    "packageJson": "029020d3855fa363c2e26fedd2f23fe5f1371bd28740ccfc9fa01c56c5750c73",
-    "agents": "c2bea26402fa1df8659a408887c603ae1ee56b95fe48210bf1923cb6d6fbd4cc",
+    "manifest": "b9b7036624c4e86ca2f147c3b347807b2d525ef409df1442e9392dd6e52decc0",
+    "packageJson": "eb5da27259c829f10d97d919768ab2976fe844fb79523f7ea8dc6f8c0a6d625c",
+    "agents": "74a05bfffe21c3f63bc4289112d25054b0351f411a9de8079fc871b66caad27c",
     "moduleDoc:agents/dev-workbench.md": "f07a428519e8cca4a46371da0a3b33b9c8d3102f1d9056e4c8efba3c0b702048",
     "moduleDoc:agents/overview-tools.md": "752a4afb6b57a2e9224f3c65a98b0deb23cda87371f01ac0566f0887e9bb12da",
     "moduleDoc:agents/token-streaming.md": "e92a28a8702d111a3751a86b8cdff30cb5146cc115fed86c227402bef1c683fd",
@@ -167,46 +167,6 @@
         }
       ],
       "surfaces": [
-        {
-          "kind": "api",
-          "name": "agentsessions.findActiveByParticipant",
-          "operation": "findActiveByParticipant",
-          "objectName": "@happyvertical/smrt-chat:AgentSessionCollection",
-          "path": "/agentsessions/findActiveByParticipant",
-          "method": "POST"
-        },
-        {
-          "kind": "api",
-          "name": "agentsessions.findActiveSession",
-          "operation": "findActiveSession",
-          "objectName": "@happyvertical/smrt-chat:AgentSessionCollection",
-          "path": "/agentsessions/findActiveSession",
-          "method": "POST"
-        },
-        {
-          "kind": "api",
-          "name": "agentsessions.findOrCreate",
-          "operation": "findOrCreate",
-          "objectName": "@happyvertical/smrt-chat:AgentSessionCollection",
-          "path": "/agentsessions/findOrCreate",
-          "method": "POST"
-        },
-        {
-          "kind": "api",
-          "name": "agentsessions.findByAgent",
-          "operation": "findByAgent",
-          "objectName": "@happyvertical/smrt-chat:AgentSessionCollection",
-          "path": "/agentsessions/findByAgent",
-          "method": "POST"
-        },
-        {
-          "kind": "api",
-          "name": "agentsessions.expireStale",
-          "operation": "expireStale",
-          "objectName": "@happyvertical/smrt-chat:AgentSessionCollection",
-          "path": "/agentsessions/expireStale",
-          "method": "POST"
-        },
         {
           "kind": "cli",
           "name": "agentsessioncollection_findActiveByParticipant",
@@ -236,35 +196,42 @@
           "name": "agentsessioncollection_expireStale",
           "operation": "expireStale",
           "objectName": "@happyvertical/smrt-chat:AgentSessionCollection"
-        },
+        }
+      ],
+      "withheldSurfaces": [
         {
-          "kind": "mcp",
-          "name": "agentsessioncollection_findactivebyparticipant",
-          "operation": "findActiveByParticipant",
+          "kind": "api",
+          "operation": "expireStale",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-chat:AgentSessionCollection"
         },
         {
-          "kind": "mcp",
-          "name": "agentsessioncollection_findactivesession",
-          "operation": "findActiveSession",
+          "kind": "api",
+          "operation": "findActiveByParticipant",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-chat:AgentSessionCollection"
         },
         {
-          "kind": "mcp",
-          "name": "agentsessioncollection_findorcreate",
-          "operation": "findOrCreate",
+          "kind": "api",
+          "operation": "findActiveSession",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-chat:AgentSessionCollection"
         },
         {
-          "kind": "mcp",
-          "name": "agentsessioncollection_findbyagent",
+          "kind": "api",
           "operation": "findByAgent",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-chat:AgentSessionCollection"
         },
         {
-          "kind": "mcp",
-          "name": "agentsessioncollection_expirestale",
-          "operation": "expireStale",
+          "kind": "api",
+          "operation": "findOrCreate",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-chat:AgentSessionCollection"
         }
       ],
@@ -349,46 +316,6 @@
         }
       ],
       "surfaces": [
-        {
-          "kind": "api",
-          "name": "chatmessages.getByRoom",
-          "operation": "getByRoom",
-          "objectName": "@happyvertical/smrt-chat:ChatMessageCollection",
-          "path": "/chatmessages/getByRoom",
-          "method": "POST"
-        },
-        {
-          "kind": "api",
-          "name": "chatmessages.getByThread",
-          "operation": "getByThread",
-          "objectName": "@happyvertical/smrt-chat:ChatMessageCollection",
-          "path": "/chatmessages/getByThread",
-          "method": "POST"
-        },
-        {
-          "kind": "api",
-          "name": "chatmessages.getByAgentSession",
-          "operation": "getByAgentSession",
-          "objectName": "@happyvertical/smrt-chat:ChatMessageCollection",
-          "path": "/chatmessages/getByAgentSession",
-          "method": "POST"
-        },
-        {
-          "kind": "api",
-          "name": "chatmessages.getUnreadCount",
-          "operation": "getUnreadCount",
-          "objectName": "@happyvertical/smrt-chat:ChatMessageCollection",
-          "path": "/chatmessages/getUnreadCount",
-          "method": "POST"
-        },
-        {
-          "kind": "api",
-          "name": "chatmessages.getLatestPerRoom",
-          "operation": "getLatestPerRoom",
-          "objectName": "@happyvertical/smrt-chat:ChatMessageCollection",
-          "path": "/chatmessages/getLatestPerRoom",
-          "method": "POST"
-        },
         {
           "kind": "cli",
           "name": "chatmessagecollection_getByRoom",
@@ -424,50 +351,49 @@
           "name": "chatmessagecollection_getLatestPerRoom",
           "operation": "getLatestPerRoom",
           "objectName": "@happyvertical/smrt-chat:ChatMessageCollection"
-        },
+        }
+      ],
+      "withheldSurfaces": [
         {
-          "kind": "mcp",
-          "name": "chatmessagecollection_getbyroom",
-          "operation": "getByRoom",
+          "kind": "api",
+          "operation": "getByAgentSession",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-chat:ChatMessageCollection"
         },
         {
-          "kind": "mcp",
-          "name": "chatmessagecollection_getbythread",
-          "operation": "getByThread",
+          "kind": "api",
+          "operation": "getByRoom",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-chat:ChatMessageCollection"
         },
         {
-          "kind": "mcp",
-          "name": "chatmessagecollection_getbyagentsession",
-          "operation": "getByAgentSession",
+          "kind": "api",
+          "operation": "getByThread",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-chat:ChatMessageCollection"
         },
         {
-          "kind": "mcp",
-          "name": "chatmessagecollection_search",
-          "operation": "search",
+          "kind": "api",
+          "operation": "getLatestPerRoom",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-chat:ChatMessageCollection"
         },
         {
-          "kind": "mcp",
-          "name": "chatmessagecollection_getunreadcount",
+          "kind": "api",
           "operation": "getUnreadCount",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-chat:ChatMessageCollection"
         },
-        {
-          "kind": "mcp",
-          "name": "chatmessagecollection_getlatestperroom",
-          "operation": "getLatestPerRoom",
-          "objectName": "@happyvertical/smrt-chat:ChatMessageCollection"
-        }
-      ],
-      "withheldSurfaces": [
         {
           "kind": "api",
           "operation": "search",
-          "code": "not-wireable",
-          "reason": "not routed: the declared type of `filters` could not be resolved by the scanner",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-chat:ChatMessageCollection"
         }
       ],
@@ -569,70 +495,6 @@
         }
       ],
       "surfaces": [
-        {
-          "kind": "api",
-          "name": "chatparticipants.getByRoom",
-          "operation": "getByRoom",
-          "objectName": "@happyvertical/smrt-chat:ChatParticipantCollection",
-          "path": "/chatparticipants/getByRoom",
-          "method": "POST"
-        },
-        {
-          "kind": "api",
-          "name": "chatparticipants.getByProfile",
-          "operation": "getByProfile",
-          "objectName": "@happyvertical/smrt-chat:ChatParticipantCollection",
-          "path": "/chatparticipants/getByProfile",
-          "method": "POST"
-        },
-        {
-          "kind": "api",
-          "name": "chatparticipants.findMembership",
-          "operation": "findMembership",
-          "objectName": "@happyvertical/smrt-chat:ChatParticipantCollection",
-          "path": "/chatparticipants/findMembership",
-          "method": "POST"
-        },
-        {
-          "kind": "api",
-          "name": "chatparticipants.findActiveMembership",
-          "operation": "findActiveMembership",
-          "objectName": "@happyvertical/smrt-chat:ChatParticipantCollection",
-          "path": "/chatparticipants/findActiveMembership",
-          "method": "POST"
-        },
-        {
-          "kind": "api",
-          "name": "chatparticipants.isActiveMember",
-          "operation": "isActiveMember",
-          "objectName": "@happyvertical/smrt-chat:ChatParticipantCollection",
-          "path": "/chatparticipants/isActiveMember",
-          "method": "POST"
-        },
-        {
-          "kind": "api",
-          "name": "chatparticipants.getOnlineInRoom",
-          "operation": "getOnlineInRoom",
-          "objectName": "@happyvertical/smrt-chat:ChatParticipantCollection",
-          "path": "/chatparticipants/getOnlineInRoom",
-          "method": "POST"
-        },
-        {
-          "kind": "api",
-          "name": "chatparticipants.getAdminsInRoom",
-          "operation": "getAdminsInRoom",
-          "objectName": "@happyvertical/smrt-chat:ChatParticipantCollection",
-          "path": "/chatparticipants/getAdminsInRoom",
-          "method": "POST"
-        },
-        {
-          "kind": "api",
-          "name": "chatparticipants.countInRoom",
-          "operation": "countInRoom",
-          "objectName": "@happyvertical/smrt-chat:ChatParticipantCollection",
-          "path": "/chatparticipants/countInRoom",
-          "method": "POST"
-        },
         {
           "kind": "cli",
           "name": "chatparticipantcollection_getByRoom",
@@ -680,53 +542,63 @@
           "name": "chatparticipantcollection_countInRoom",
           "operation": "countInRoom",
           "objectName": "@happyvertical/smrt-chat:ChatParticipantCollection"
-        },
+        }
+      ],
+      "withheldSurfaces": [
         {
-          "kind": "mcp",
-          "name": "chatparticipantcollection_getbyroom",
-          "operation": "getByRoom",
+          "kind": "api",
+          "operation": "countInRoom",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-chat:ChatParticipantCollection"
         },
         {
-          "kind": "mcp",
-          "name": "chatparticipantcollection_getbyprofile",
-          "operation": "getByProfile",
+          "kind": "api",
+          "operation": "findActiveMembership",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-chat:ChatParticipantCollection"
         },
         {
-          "kind": "mcp",
-          "name": "chatparticipantcollection_findmembership",
+          "kind": "api",
           "operation": "findMembership",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-chat:ChatParticipantCollection"
         },
         {
-          "kind": "mcp",
-          "name": "chatparticipantcollection_findactivemembership",
-          "operation": "findActiveMembership",
+          "kind": "api",
+          "operation": "getAdminsInRoom",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-chat:ChatParticipantCollection"
         },
         {
-          "kind": "mcp",
-          "name": "chatparticipantcollection_isactivemember",
-          "operation": "isActiveMember",
+          "kind": "api",
+          "operation": "getByProfile",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-chat:ChatParticipantCollection"
         },
         {
-          "kind": "mcp",
-          "name": "chatparticipantcollection_getonlineinroom",
-          "operation": "getOnlineInRoom",
+          "kind": "api",
+          "operation": "getByRoom",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-chat:ChatParticipantCollection"
         },
         {
-          "kind": "mcp",
-          "name": "chatparticipantcollection_getadminsinroom",
-          "operation": "getAdminsInRoom",
+          "kind": "api",
+          "operation": "getOnlineInRoom",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-chat:ChatParticipantCollection"
         },
         {
-          "kind": "mcp",
-          "name": "chatparticipantcollection_countinroom",
-          "operation": "countInRoom",
+          "kind": "api",
+          "operation": "isActiveMember",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-chat:ChatParticipantCollection"
         }
       ],
@@ -779,47 +651,27 @@
           "returns": "Promise<object>"
         }
       ],
-      "surfaces": [
-        {
-          "kind": "api",
-          "name": "chatreactions.getByMessage",
-          "operation": "getByMessage",
-          "objectName": "@happyvertical/smrt-chat:ChatReactionCollection",
-          "path": "/chatreactions/getByMessage",
-          "method": "POST"
-        },
-        {
-          "kind": "api",
-          "name": "chatreactions.getReactionCounts",
-          "operation": "getReactionCounts",
-          "objectName": "@happyvertical/smrt-chat:ChatReactionCollection",
-          "path": "/chatreactions/getReactionCounts",
-          "method": "POST"
-        },
+      "surfaces": [],
+      "withheldSurfaces": [
         {
           "kind": "api",
-          "name": "chatreactions.toggle",
-          "operation": "toggle",
-          "objectName": "@happyvertical/smrt-chat:ChatReactionCollection",
-          "path": "/chatreactions/toggle",
-          "method": "POST"
-        },
-        {
-          "kind": "mcp",
-          "name": "chatreactioncollection_getbymessage",
           "operation": "getByMessage",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-chat:ChatReactionCollection"
         },
         {
-          "kind": "mcp",
-          "name": "chatreactioncollection_getreactioncounts",
+          "kind": "api",
           "operation": "getReactionCounts",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-chat:ChatReactionCollection"
         },
         {
-          "kind": "mcp",
-          "name": "chatreactioncollection_toggle",
+          "kind": "api",
           "operation": "toggle",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-chat:ChatReactionCollection"
         }
       ],
@@ -892,46 +744,6 @@
         }
       ],
       "surfaces": [
-        {
-          "kind": "api",
-          "name": "chatrooms.findByType",
-          "operation": "findByType",
-          "objectName": "@happyvertical/smrt-chat:ChatRoomCollection",
-          "path": "/chatrooms/findByType",
-          "method": "POST"
-        },
-        {
-          "kind": "api",
-          "name": "chatrooms.findPublic",
-          "operation": "findPublic",
-          "objectName": "@happyvertical/smrt-chat:ChatRoomCollection",
-          "path": "/chatrooms/findPublic",
-          "method": "POST"
-        },
-        {
-          "kind": "api",
-          "name": "chatrooms.findDMs",
-          "operation": "findDMs",
-          "objectName": "@happyvertical/smrt-chat:ChatRoomCollection",
-          "path": "/chatrooms/findDMs",
-          "method": "POST"
-        },
-        {
-          "kind": "api",
-          "name": "chatrooms.findAgentRooms",
-          "operation": "findAgentRooms",
-          "objectName": "@happyvertical/smrt-chat:ChatRoomCollection",
-          "path": "/chatrooms/findAgentRooms",
-          "method": "POST"
-        },
-        {
-          "kind": "api",
-          "name": "chatrooms.search",
-          "operation": "search",
-          "objectName": "@happyvertical/smrt-chat:ChatRoomCollection",
-          "path": "/chatrooms/search",
-          "method": "POST"
-        },
         {
           "kind": "cli",
           "name": "chatroomcollection_findByType",
@@ -967,50 +779,49 @@
           "name": "chatroomcollection_findOrCreateDM",
           "operation": "findOrCreateDM",
           "objectName": "@happyvertical/smrt-chat:ChatRoomCollection"
-        },
+        }
+      ],
+      "withheldSurfaces": [
         {
-          "kind": "mcp",
-          "name": "chatroomcollection_findbytype",
-          "operation": "findByType",
+          "kind": "api",
+          "operation": "findAgentRooms",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-chat:ChatRoomCollection"
         },
         {
-          "kind": "mcp",
-          "name": "chatroomcollection_findpublic",
-          "operation": "findPublic",
+          "kind": "api",
+          "operation": "findByType",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-chat:ChatRoomCollection"
         },
         {
-          "kind": "mcp",
-          "name": "chatroomcollection_finddms",
+          "kind": "api",
           "operation": "findDMs",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-chat:ChatRoomCollection"
         },
         {
-          "kind": "mcp",
-          "name": "chatroomcollection_findagentrooms",
-          "operation": "findAgentRooms",
+          "kind": "api",
+          "operation": "findOrCreateDM",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-chat:ChatRoomCollection"
         },
         {
-          "kind": "mcp",
-          "name": "chatroomcollection_search",
-          "operation": "search",
+          "kind": "api",
+          "operation": "findPublic",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-chat:ChatRoomCollection"
         },
-        {
-          "kind": "mcp",
-          "name": "chatroomcollection_findorcreatedm",
-          "operation": "findOrCreateDM",
-          "objectName": "@happyvertical/smrt-chat:ChatRoomCollection"
-        }
-      ],
-      "withheldSurfaces": [
         {
           "kind": "api",
-          "operation": "findOrCreateDM",
-          "code": "not-wireable",
-          "reason": "not routed: parameter `participants`: `ChatParticipantCollection` is a model class instance, not JSON data",
+          "operation": "search",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-chat:ChatRoomCollection"
         }
       ],
@@ -1058,30 +869,6 @@
         }
       ],
       "surfaces": [
-        {
-          "kind": "api",
-          "name": "chatthreads.getByRoom",
-          "operation": "getByRoom",
-          "objectName": "@happyvertical/smrt-chat:ChatThreadCollection",
-          "path": "/chatthreads/getByRoom",
-          "method": "POST"
-        },
-        {
-          "kind": "api",
-          "name": "chatthreads.getActive",
-          "operation": "getActive",
-          "objectName": "@happyvertical/smrt-chat:ChatThreadCollection",
-          "path": "/chatthreads/getActive",
-          "method": "POST"
-        },
-        {
-          "kind": "api",
-          "name": "chatthreads.getUnresolved",
-          "operation": "getUnresolved",
-          "objectName": "@happyvertical/smrt-chat:ChatThreadCollection",
-          "path": "/chatthreads/getUnresolved",
-          "method": "POST"
-        },
         {
           "kind": "cli",
           "name": "chatthreadcollection_getByRoom",
@@ -1099,23 +886,28 @@
           "name": "chatthreadcollection_getUnresolved",
           "operation": "getUnresolved",
           "objectName": "@happyvertical/smrt-chat:ChatThreadCollection"
-        },
+        }
+      ],
+      "withheldSurfaces": [
         {
-          "kind": "mcp",
-          "name": "chatthreadcollection_getbyroom",
-          "operation": "getByRoom",
+          "kind": "api",
+          "operation": "getActive",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-chat:ChatThreadCollection"
         },
         {
-          "kind": "mcp",
-          "name": "chatthreadcollection_getactive",
-          "operation": "getActive",
+          "kind": "api",
+          "operation": "getByRoom",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-chat:ChatThreadCollection"
         },
         {
-          "kind": "mcp",
-          "name": "chatthreadcollection_getunresolved",
+          "kind": "api",
           "operation": "getUnresolved",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-chat:ChatThreadCollection"
         }
       ],
@@ -1147,19 +939,13 @@
           "returns": "Promise<VoiceGatewayTurn>"
         }
       ],
-      "surfaces": [
+      "surfaces": [],
+      "withheldSurfaces": [
         {
           "kind": "api",
-          "name": "voicegatewayturns.reserveTurn",
-          "operation": "reserveTurn",
-          "objectName": "@happyvertical/smrt-chat:VoiceGatewayTurnCollection",
-          "path": "/voicegatewayturns/reserveTurn",
-          "method": "POST"
-        },
-        {
-          "kind": "mcp",
-          "name": "voicegatewayturncollection_reserveturn",
           "operation": "reserveTurn",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-chat:VoiceGatewayTurnCollection"
         }
       ],
@@ -1203,22 +989,6 @@
         }
       ],
       "surfaces": [
-        {
-          "kind": "api",
-          "name": "voicesessions.getActiveById",
-          "operation": "getActiveById",
-          "objectName": "@happyvertical/smrt-chat:VoiceSessionCollection",
-          "path": "/voicesessions/getActiveById",
-          "method": "POST"
-        },
-        {
-          "kind": "api",
-          "name": "voicesessions.expireStale",
-          "operation": "expireStale",
-          "objectName": "@happyvertical/smrt-chat:VoiceSessionCollection",
-          "path": "/voicesessions/expireStale",
-          "method": "POST"
-        },
         {
           "kind": "cli",
           "name": "voicesessioncollection_getActiveById",
@@ -1230,17 +1000,21 @@
           "name": "voicesessioncollection_expireStale",
           "operation": "expireStale",
           "objectName": "@happyvertical/smrt-chat:VoiceSessionCollection"
-        },
+        }
+      ],
+      "withheldSurfaces": [
         {
-          "kind": "mcp",
-          "name": "voicesessioncollection_getactivebyid",
-          "operation": "getActiveById",
+          "kind": "api",
+          "operation": "expireStale",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-chat:VoiceSessionCollection"
         },
         {
-          "kind": "mcp",
-          "name": "voicesessioncollection_expirestale",
-          "operation": "expireStale",
+          "kind": "api",
+          "operation": "getActiveById",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-chat:VoiceSessionCollection"
         }
       ],
@@ -3834,46 +3608,6 @@
     }
   ],
   "surfaces": [
-    {
-      "kind": "api",
-      "name": "agentsessions.findActiveByParticipant",
-      "operation": "findActiveByParticipant",
-      "objectName": "@happyvertical/smrt-chat:AgentSessionCollection",
-      "path": "/agentsessions/findActiveByParticipant",
-      "method": "POST"
-    },
-    {
-      "kind": "api",
-      "name": "agentsessions.findActiveSession",
-      "operation": "findActiveSession",
-      "objectName": "@happyvertical/smrt-chat:AgentSessionCollection",
-      "path": "/agentsessions/findActiveSession",
-      "method": "POST"
-    },
-    {
-      "kind": "api",
-      "name": "agentsessions.findOrCreate",
-      "operation": "findOrCreate",
-      "objectName": "@happyvertical/smrt-chat:AgentSessionCollection",
-      "path": "/agentsessions/findOrCreate",
-      "method": "POST"
-    },
-    {
-      "kind": "api",
-      "name": "agentsessions.findByAgent",
-      "operation": "findByAgent",
-      "objectName": "@happyvertical/smrt-chat:AgentSessionCollection",
-      "path": "/agentsessions/findByAgent",
-      "method": "POST"
-    },
-    {
-      "kind": "api",
-      "name": "agentsessions.expireStale",
-      "operation": "expireStale",
-      "objectName": "@happyvertical/smrt-chat:AgentSessionCollection",
-      "path": "/agentsessions/expireStale",
-      "method": "POST"
-    },
     {
       "kind": "cli",
       "name": "agentsessioncollection_findActiveByParticipant",
@@ -3904,76 +3638,6 @@
       "operation": "expireStale",
       "objectName": "@happyvertical/smrt-chat:AgentSessionCollection"
     },
-    {
-      "kind": "mcp",
-      "name": "agentsessioncollection_findactivebyparticipant",
-      "operation": "findActiveByParticipant",
-      "objectName": "@happyvertical/smrt-chat:AgentSessionCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "agentsessioncollection_findactivesession",
-      "operation": "findActiveSession",
-      "objectName": "@happyvertical/smrt-chat:AgentSessionCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "agentsessioncollection_findorcreate",
-      "operation": "findOrCreate",
-      "objectName": "@happyvertical/smrt-chat:AgentSessionCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "agentsessioncollection_findbyagent",
-      "operation": "findByAgent",
-      "objectName": "@happyvertical/smrt-chat:AgentSessionCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "agentsessioncollection_expirestale",
-      "operation": "expireStale",
-      "objectName": "@happyvertical/smrt-chat:AgentSessionCollection"
-    },
-    {
-      "kind": "api",
-      "name": "chatmessages.getByRoom",
-      "operation": "getByRoom",
-      "objectName": "@happyvertical/smrt-chat:ChatMessageCollection",
-      "path": "/chatmessages/getByRoom",
-      "method": "POST"
-    },
-    {
-      "kind": "api",
-      "name": "chatmessages.getByThread",
-      "operation": "getByThread",
-      "objectName": "@happyvertical/smrt-chat:ChatMessageCollection",
-      "path": "/chatmessages/getByThread",
-      "method": "POST"
-    },
-    {
-      "kind": "api",
-      "name": "chatmessages.getByAgentSession",
-      "operation": "getByAgentSession",
-      "objectName": "@happyvertical/smrt-chat:ChatMessageCollection",
-      "path": "/chatmessages/getByAgentSession",
-      "method": "POST"
-    },
-    {
-      "kind": "api",
-      "name": "chatmessages.getUnreadCount",
-      "operation": "getUnreadCount",
-      "objectName": "@happyvertical/smrt-chat:ChatMessageCollection",
-      "path": "/chatmessages/getUnreadCount",
-      "method": "POST"
-    },
-    {
-      "kind": "api",
-      "name": "chatmessages.getLatestPerRoom",
-      "operation": "getLatestPerRoom",
-      "objectName": "@happyvertical/smrt-chat:ChatMessageCollection",
-      "path": "/chatmessages/getLatestPerRoom",
-      "method": "POST"
-    },
     {
       "kind": "cli",
       "name": "chatmessagecollection_getByRoom",
@@ -4010,106 +3674,6 @@
       "operation": "getLatestPerRoom",
       "objectName": "@happyvertical/smrt-chat:ChatMessageCollection"
     },
-    {
-      "kind": "mcp",
-      "name": "chatmessagecollection_getbyroom",
-      "operation": "getByRoom",
-      "objectName": "@happyvertical/smrt-chat:ChatMessageCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "chatmessagecollection_getbythread",
-      "operation": "getByThread",
-      "objectName": "@happyvertical/smrt-chat:ChatMessageCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "chatmessagecollection_getbyagentsession",
-      "operation": "getByAgentSession",
-      "objectName": "@happyvertical/smrt-chat:ChatMessageCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "chatmessagecollection_search",
-      "operation": "search",
-      "objectName": "@happyvertical/smrt-chat:ChatMessageCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "chatmessagecollection_getunreadcount",
-      "operation": "getUnreadCount",
-      "objectName": "@happyvertical/smrt-chat:ChatMessageCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "chatmessagecollection_getlatestperroom",
-      "operation": "getLatestPerRoom",
-      "objectName": "@happyvertical/smrt-chat:ChatMessageCollection"
-    },
-    {
-      "kind": "api",
-      "name": "chatparticipants.getByRoom",
-      "operation": "getByRoom",
-      "objectName": "@happyvertical/smrt-chat:ChatParticipantCollection",
-      "path": "/chatparticipants/getByRoom",
-      "method": "POST"
-    },
-    {
-      "kind": "api",
-      "name": "chatparticipants.getByProfile",
-      "operation": "getByProfile",
-      "objectName": "@happyvertical/smrt-chat:ChatParticipantCollection",
-      "path": "/chatparticipants/getByProfile",
-      "method": "POST"
-    },
-    {
-      "kind": "api",
-      "name": "chatparticipants.findMembership",
-      "operation": "findMembership",
-      "objectName": "@happyvertical/smrt-chat:ChatParticipantCollection",
-      "path": "/chatparticipants/findMembership",
-      "method": "POST"
-    },
-    {
-      "kind": "api",
-      "name": "chatparticipants.findActiveMembership",
-      "operation": "findActiveMembership",
-      "objectName": "@happyvertical/smrt-chat:ChatParticipantCollection",
-      "path": "/chatparticipants/findActiveMembership",
-      "method": "POST"
-    },
-    {
-      "kind": "api",
-      "name": "chatparticipants.isActiveMember",
-      "operation": "isActiveMember",
-      "objectName": "@happyvertical/smrt-chat:ChatParticipantCollection",
-      "path": "/chatparticipants/isActiveMember",
-      "method": "POST"
-    },
-    {
-      "kind": "api",
-      "name": "chatparticipants.getOnlineInRoom",
-      "operation": "getOnlineInRoom",
-      "objectName": "@happyvertical/smrt-chat:ChatParticipantCollection",
-      "path": "/chatparticipants/getOnlineInRoom",
-      "method": "POST"
-    },
-    {
-      "kind": "api",
-      "name": "chatparticipants.getAdminsInRoom",
-      "operation": "getAdminsInRoom",
-      "objectName": "@happyvertical/smrt-chat:ChatParticipantCollection",
-      "path": "/chatparticipants/getAdminsInRoom",
-      "method": "POST"
-    },
-    {
-      "kind": "api",
-      "name": "chatparticipants.countInRoom",
-      "operation": "countInRoom",
-      "objectName": "@happyvertical/smrt-chat:ChatParticipantCollection",
-      "path": "/chatparticipants/countInRoom",
-      "method": "POST"
-    },
     {
       "kind": "cli",
       "name": "chatparticipantcollection_getByRoom",
@@ -4158,136 +3722,6 @@
       "operation": "countInRoom",
       "objectName": "@happyvertical/smrt-chat:ChatParticipantCollection"
     },
-    {
-      "kind": "mcp",
-      "name": "chatparticipantcollection_getbyroom",
-      "operation": "getByRoom",
-      "objectName": "@happyvertical/smrt-chat:ChatParticipantCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "chatparticipantcollection_getbyprofile",
-      "operation": "getByProfile",
-      "objectName": "@happyvertical/smrt-chat:ChatParticipantCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "chatparticipantcollection_findmembership",
-      "operation": "findMembership",
-      "objectName": "@happyvertical/smrt-chat:ChatParticipantCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "chatparticipantcollection_findactivemembership",
-      "operation": "findActiveMembership",
-      "objectName": "@happyvertical/smrt-chat:ChatParticipantCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "chatparticipantcollection_isactivemember",
-      "operation": "isActiveMember",
-      "objectName": "@happyvertical/smrt-chat:ChatParticipantCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "chatparticipantcollection_getonlineinroom",
-      "operation": "getOnlineInRoom",
-      "objectName": "@happyvertical/smrt-chat:ChatParticipantCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "chatparticipantcollection_getadminsinroom",
-      "operation": "getAdminsInRoom",
-      "objectName": "@happyvertical/smrt-chat:ChatParticipantCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "chatparticipantcollection_countinroom",
-      "operation": "countInRoom",
-      "objectName": "@happyvertical/smrt-chat:ChatParticipantCollection"
-    },
-    {
-      "kind": "api",
-      "name": "chatreactions.getByMessage",
-      "operation": "getByMessage",
-      "objectName": "@happyvertical/smrt-chat:ChatReactionCollection",
-      "path": "/chatreactions/getByMessage",
-      "method": "POST"
-    },
-    {
-      "kind": "api",
-      "name": "chatreactions.getReactionCounts",
-      "operation": "getReactionCounts",
-      "objectName": "@happyvertical/smrt-chat:ChatReactionCollection",
-      "path": "/chatreactions/getReactionCounts",
-      "method": "POST"
-    },
-    {
-      "kind": "api",
-      "name": "chatreactions.toggle",
-      "operation": "toggle",
-      "objectName": "@happyvertical/smrt-chat:ChatReactionCollection",
-      "path": "/chatreactions/toggle",
-      "method": "POST"
-    },
-    {
-      "kind": "mcp",
-      "name": "chatreactioncollection_getbymessage",
-      "operation": "getByMessage",
-      "objectName": "@happyvertical/smrt-chat:ChatReactionCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "chatreactioncollection_getreactioncounts",
-      "operation": "getReactionCounts",
-      "objectName": "@happyvertical/smrt-chat:ChatReactionCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "chatreactioncollection_toggle",
-      "operation": "toggle",
-      "objectName": "@happyvertical/smrt-chat:ChatReactionCollection"
-    },
-    {
-      "kind": "api",
-      "name": "chatrooms.findByType",
-      "operation": "findByType",
-      "objectName": "@happyvertical/smrt-chat:ChatRoomCollection",
-      "path": "/chatrooms/findByType",
-      "method": "POST"
-    },
-    {
-      "kind": "api",
-      "name": "chatrooms.findPublic",
-      "operation": "findPublic",
-      "objectName": "@happyvertical/smrt-chat:ChatRoomCollection",
-      "path": "/chatrooms/findPublic",
-      "method": "POST"
-    },
-    {
-      "kind": "api",
-      "name": "chatrooms.findDMs",
-      "operation": "findDMs",
-      "objectName": "@happyvertical/smrt-chat:ChatRoomCollection",
-      "path": "/chatrooms/findDMs",
-      "method": "POST"
-    },
-    {
-      "kind": "api",
-      "name": "chatrooms.findAgentRooms",
-      "operation": "findAgentRooms",
-      "objectName": "@happyvertical/smrt-chat:ChatRoomCollection",
-      "path": "/chatrooms/findAgentRooms",
-      "method": "POST"
-    },
-    {
-      "kind": "api",
-      "name": "chatrooms.search",
-      "operation": "search",
-      "objectName": "@happyvertical/smrt-chat:ChatRoomCollection",
-      "path": "/chatrooms/search",
-      "method": "POST"
-    },
     {
       "kind": "cli",
       "name": "chatroomcollection_findByType",
@@ -4324,66 +3758,6 @@
       "operation": "findOrCreateDM",
       "objectName": "@happyvertical/smrt-chat:ChatRoomCollection"
     },
-    {
-      "kind": "mcp",
-      "name": "chatroomcollection_findbytype",
-      "operation": "findByType",
-      "objectName": "@happyvertical/smrt-chat:ChatRoomCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "chatroomcollection_findpublic",
-      "operation": "findPublic",
-      "objectName": "@happyvertical/smrt-chat:ChatRoomCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "chatroomcollection_finddms",
-      "operation": "findDMs",
-      "objectName": "@happyvertical/smrt-chat:ChatRoomCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "chatroomcollection_findagentrooms",
-      "operation": "findAgentRooms",
-      "objectName": "@happyvertical/smrt-chat:ChatRoomCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "chatroomcollection_search",
-      "operation": "search",
-      "objectName": "@happyvertical/smrt-chat:ChatRoomCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "chatroomcollection_findorcreatedm",
-      "operation": "findOrCreateDM",
-      "objectName": "@happyvertical/smrt-chat:ChatRoomCollection"
-    },
-    {
-      "kind": "api",
-      "name": "chatthreads.getByRoom",
-      "operation": "getByRoom",
-      "objectName": "@happyvertical/smrt-chat:ChatThreadCollection",
-      "path": "/chatthreads/getByRoom",
-      "method": "POST"
-    },
-    {
-      "kind": "api",
-      "name": "chatthreads.getActive",
-      "operation": "getActive",
-      "objectName": "@happyvertical/smrt-chat:ChatThreadCollection",
-      "path": "/chatthreads/getActive",
-      "method": "POST"
-    },
-    {
-      "kind": "api",
-      "name": "chatthreads.getUnresolved",
-      "operation": "getUnresolved",
-      "objectName": "@happyvertical/smrt-chat:ChatThreadCollection",
-      "path": "/chatthreads/getUnresolved",
-      "method": "POST"
-    },
     {
       "kind": "cli",
       "name": "chatthreadcollection_getByRoom",
@@ -4402,54 +3776,6 @@
       "operation": "getUnresolved",
       "objectName": "@happyvertical/smrt-chat:ChatThreadCollection"
     },
-    {
-      "kind": "mcp",
-      "name": "chatthreadcollection_getbyroom",
-      "operation": "getByRoom",
-      "objectName": "@happyvertical/smrt-chat:ChatThreadCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "chatthreadcollection_getactive",
-      "operation": "getActive",
-      "objectName": "@happyvertical/smrt-chat:ChatThreadCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "chatthreadcollection_getunresolved",
-      "operation": "getUnresolved",
-      "objectName": "@happyvertical/smrt-chat:ChatThreadCollection"
-    },
-    {
-      "kind": "api",
-      "name": "voicegatewayturns.reserveTurn",
-      "operation": "reserveTurn",
-      "objectName": "@happyvertical/smrt-chat:VoiceGatewayTurnCollection",
-      "path": "/voicegatewayturns/reserveTurn",
-      "method": "POST"
-    },
-    {
-      "kind": "mcp",
-      "name": "voicegatewayturncollection_reserveturn",
-      "operation": "reserveTurn",
-      "objectName": "@happyvertical/smrt-chat:VoiceGatewayTurnCollection"
-    },
-    {
-      "kind": "api",
-      "name": "voicesessions.getActiveById",
-      "operation": "getActiveById",
-      "objectName": "@happyvertical/smrt-chat:VoiceSessionCollection",
-      "path": "/voicesessions/getActiveById",
-      "method": "POST"
-    },
-    {
-      "kind": "api",
-      "name": "voicesessions.expireStale",
-      "operation": "expireStale",
-      "objectName": "@happyvertical/smrt-chat:VoiceSessionCollection",
-      "path": "/voicesessions/expireStale",
-      "method": "POST"
-    },
     {
       "kind": "cli",
       "name": "voicesessioncollection_getActiveById",
@@ -4462,18 +3788,6 @@
       "operation": "expireStale",
       "objectName": "@happyvertical/smrt-chat:VoiceSessionCollection"
     },
-    {
-      "kind": "mcp",
-      "name": "voicesessioncollection_getactivebyid",
-      "operation": "getActiveById",
-      "objectName": "@happyvertical/smrt-chat:VoiceSessionCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "voicesessioncollection_expirestale",
-      "operation": "expireStale",
-      "objectName": "@happyvertical/smrt-chat:VoiceSessionCollection"
-    },
     {
       "kind": "api",
       "name": "agentsessions.list",
@@ -5198,7 +4512,7 @@
     "polymorphicAssociations": 0,
     "uuidColumns": 78
   },
-  "agentDoc": "# @happyvertical/smrt-chat\n\nChat rooms, threads, and agent sessions with app-controlled tool whitelisting.\n\n## Dev Server\n\n`pnpm --dir packages/chat dev` runs a package-local SvelteKit workbench. The root\nroute separates **Character setup** and **Chat dev** into tabs; switching tabs\nretains the current character rig and chat state. The chat tab is an interactive\nsurface with a dev-only `/api/dev-chat` endpoint:\nit uses `@happyvertical/ai` when local provider credentials are present and\nfalls back to a deterministic local assistant otherwise. `/api/dev-chat-stream`\nis its SSE companion (#1936) — the same provider/local-fallback resolution wired\nthrough `createChatStreamHandler` in plain mode, so an embedded `SmrtChatBackend`\nclient can exercise token streaming locally. `/previews` hosts the shared\ncomponent playground entries from `src/svelte/playground.ts`.\n\nThe root route also drives the **browser inference path**\n(`@happyvertical/smrt-web/ai`: bitgpu, WebLLM, and route backends composed by\n`createInferencePath`) and an **agent-addressable draft form** (`useViewIntent`\nover `src/routes/chat-dev.intents.ts`, #2588). Their dev-config dependencies\n(static optional-peer imports, `workspace-aliases.js` prefix rules, the theme\nstylesheet import) and the stage→apply tool-call gotchas are in\n[agents/dev-workbench.md](agents/dev-workbench.md).\n\nDev-only voice and opt-in local character persistence are documented in\n[agents/dev-workbench.md](agents/dev-workbench.md#voice-and-local-character-persistence).\nThese endpoints are loopback-only demos; production hosts supply authenticated\nprincipals, tenancy, and authorization to the owning services.\n\n## Models\n\nAll seven models expose only generated REST/MCP `list`/`get`; structural tests\ncheck the registry for accidental mutating operations. Writes go through\nmembership/owner-checked `ChatService` or the binding-checked voice adapter.\n\n`ChatService` is a closed facade. Its collections and security-sensitive\nhelpers use ES `#private` fields/methods (TypeScript `private` is erased).\nCollection classes are not exported from the package index. The agent-reply\nbridge is a Symbol-keyed static accessible through a non-exported symbol held\nby the module-local `sendAgentReply` function.\n\n- **ChatRoom**: `roomType` (public/private/dm/agent), `status`, `topic`, `maxParticipants`, `lastMessageAt`. Tenant-scoped (required).\n- **ChatMessage**: shared by users + agents. `role` (user/assistant/system/tool), `messageType` (text/system/action/file/tool_call/tool_result), `toolCallData` JSON. Unified model — no separate agent message type. Tenant-scoped (required).\n- **ChatParticipant**: `role` (owner/admin/member/viewer), `onlineStatus`, `lastReadMessageId`, `isMuted`. Tenant-scoped (required).\n- **ChatThread**: `rootMessageId`, `isResolved`, `messageCount`. Created via `ChatService.startThread()` (member-checked). Tenant-scoped (required).\n- **ChatReaction**: `messageId`, `profileId`, `emoji`. Added/removed via `ChatService.addReaction()`/`removeReaction()` (member-checked, self-keyed). Tenant-scoped (required).\n- **AgentSession**: `agentId` (application slug, string ref, not FK), `agentProfileId` (nullable `crossPackageRef` to `Profile` — the `bot` profile the agent AUTHORS as, #2995), `allowedTools` (JSON string array), `sessionContext` (JSON, sensitive), `systemPrompt`, limits (`maxTokens`/`maxMessages`/`expiresAt`). Optional tenancy.\n- **VoiceSession**: short-lived voice-gateway binding over `(tenant, actorProfileId, personaId, room/thread/agentSession)` plus a persona snapshot, gateway `session_id`, expiry, replay tracking, and metadata. Tenant-scoped (required). Generated surface is read-only; creation and turns go through `createVoiceChatSession()` / `handleVoiceGatewayTurn()`.\n\n## ChatService\n\nPublic writes take server-supplied `actorProfileId`; never trust a request's\n`senderProfileId`, `role`, owner id, or participant id as authority.\n\n| Operation | Authorization and behavior |\n|---|---|\n| `sendMessage()` | Room member; authors as actor with `role: 'user'`; no public membership bypass |\n| `createRoom()` | Actor becomes owner |\n| `startThread()` | Member; optional root message bound to room and tenant |\n| `addParticipant()` / `removeParticipant()` | Owner/admin; self-leave allowed |\n| `updateRoom()` | Owner/admin |\n| `addReaction()` / `removeReaction()` | Member; self-keyed |\n| `getOrCreateDM()` | Actor must be a DM participant |\n| `createAgentSession()` | Actor becomes session participant; existing-session lookup tenant-bound; optional `sessionKey` isolates conversation subjects |\n| `updateAgentSessionConfig()` | Owner; mandatory tenant-bound lookup |\n| `sendAgentUserMessage()` | Actor must be session participant; authored as participant |\n\nRead facade: `getAgentSession({agentSessionId, tenantId})`,\n`findActiveAgentSessions({tenantId, agentId, participantProfileId})`, and\n`getThread({threadId, tenantId})` are tenant-bound; consumers still check\nownership/context. `listRoomThreads({roomId, actorProfileId, tenantId})`,\n`getThreadMessages({threadId, actorProfileId, tenantId, limit?})` (chronological),\n`getRoomMessages({roomId, actorProfileId, tenantId})`, and\n`getRoomForMember(roomId, actorProfileId, tenantId)` additionally require\nmembership of the server-supplied actor, not a caller-selected subject.\n\nTrusted agent runtime imports `sendAgentReply(service, params)` only from\n`@happyvertical/smrt-chat/internal/agent-runtime`. It is not a `ChatService`\nmethod or package-index export. It authors as `session.agentProfileId` — the\nagent's resolved `bot` Profile, NEVER the `agentId` slug (#2995) — accepts a\nsame-room/tenant thread, and enforces `allowedTools` fail-closed.\n\nPrivate `#writeMessage` alone can select arbitrary authors/roles or bypass\nmembership. It binds every supplied `threadId`, `agentSessionId`, and\n`replyToMessageId` to the same room **and** tenant. Internal enrollment supports\nautomatically created rooms, sessions, and participants.\n\n## Agent Tool Whitelisting\n\n`allowedTools` is a JSON array controlled by the consuming app. Fail-closed: an empty/unparseable whitelist permits NO tools. The internal `sendAgentReply(service, params)` function enforces the whitelist before emitting any `tool`/`tool_call` message; a caller cannot supply a `senderProfileId`/`role` to post as the agent, and the function is not reachable from the package index.\n\nPrincipal-bound data discovery and reads are available as `PrincipalTool[]` via\n`createDataSurfaceTools()` (re-exported by the chat package). Pass the tools as\n`extraTools` to the persona conversation/tool loop. They use the same\nfail-closed `allowedTools` offer/execution gates; RBAC, tenant, redaction,\nbounded query results, and audit authority remain in the authenticated\n`PrincipalRun` supplied by `@happyvertical/smrt-agents`.\n\n## Runtime report tools (#3711)\n\n`createRuntimeReportTools()` (`runtime-report-tools.ts`) returns four\n`PrincipalTool`s for the persona `extraTools` seam: `reports.runtime.sources`,\n`reports.runtime.define` (`preview` / `apply`), `reports.runtime.list`, and\n`reports.runtime.run`. The model supplies only a declarative\n`RuntimeReportSpec` from `@happyvertical/smrt-reports`; sources are a\nserver-owned allow-list gated by `run.assertOperation(collection, 'read')`, and\nfield policy, `readPermission`, and tenancy are enforced by the compiler against\nthe live run on every compile and every stored-report run. `apply` needs the\n`specHash` of the previewed spec plus an app-owned `confirmation` host that\nresolves only after a human approved that exact spec; with no host apply returns an `awaiting_confirmation` proposal for the\nsame-origin browser confirm route and stores nothing and a model-supplied `confirmed` flag is ignored. Saving also needs\n`create` on the `RuntimeReport` collection, and `list`/`run` need `read`; the\ndefault `reportsCollection` is the `RuntimeReport` class itself, which resolves\nto the catalog slug. A string `collection`/`reportsCollection` is used verbatim\nas a catalog slug (never a class name); tests must run the tools under the real\n`assertOperationPermission` guard so a wrong slug fails. A stored report is\nwritten only by this confirmed `apply`: the model layer refuses every other\ninsert/spec change, and the generic manifest tools (`buildManifestToolCatalog`,\n`invokeManifestTool`) never offer or run a `RuntimeReport` write. Stored-report\nreads/saves run under the principal's tenant (`withPrincipalTenant`), refuse a\nmismatching ambient tenant (checked before `confirmSave`), and filter by the principal tenant explicitly. Contract and authority model:\n[`packages/reports/agents/runtime-reports.md`](../reports/agents/runtime-reports.md).\n\n## Overview tools (#3727)\n\n`createOverviewTools({ host })` (`overview-tools.ts`) returns\n`overviews.describe`, `overviews.apply` (an atomic batch of structured widget\noperations) and `overviews.undo` (single step, keyed by tenant, user and page).\nThe host opens a page per `PrincipalRun` (smrt-svelte's\n`createOverviewAssistantSurface`, typed structurally here); validation and\n`canCustomize` are the surface's. Contract:\n[agents/overview-tools.md](agents/overview-tools.md).\n\n## Conversational Harness (L3, #1891)\n\nThe `AgentSession` runtime depends on personas, agents, and users. Keep those\nedges acyclic: none of those packages may depend back on chat.\n\n- **`runToolLoop(options)`** (`tool-loop.ts`) — a bounded `tool_call → observe → respond` loop. Tools are **manifest operations** of installed packages: `buildManifestToolCatalog({ allowedTools })` reads the `PermissionCatalogService` catalog and keeps only the `(collection, action)` entries named in the persona's allow-list (the **offer gate**; absent/empty ⇒ NO tools). The loop runs inside one `executeAsPrincipal` context, and `invokeManifestTool` executes each op **in-process (\"side door\")** against `run.context.database` (the RLS tx when Postgres RLS is on), after re-asserting the fail-closed allow-list (`run.assertToolAllowed`) AND the catalog permission (`run.assertOperation`) — the **execution gate**. Bounded by a max-steps ceiling (`DEFAULT_MAX_STEPS = 8`): on the ceiling it disables tools for one final completion so the turn always terminates with text. A thrown tool error is classified (`classifyToolError`): permission denials and 401/403 are `not_permitted`; a `ValidationError` or 400/404/409/422 is `invalid_request` (observation: actionable message, `publicMessage` first, `code`, fix-and-retry hint); else (incl. 429) `execution_error`.\n- **`runPersonaConversationTurn(options)`** (`persona-conversation.ts`) — binds a conversation to an `AgentPersona`/`ResolvedPersona`: runs as its principal (`runAsUserId`), offers only its `allowedTools`, speaks its instructions (`resolvePersonaInstructions`, layering approved learned directives), and injects its **recalled learning memory** (`personaLearningMemory`, isolated per `memoryScope`) into the system prompt. `bindPersonaToSession()` mirrors the persona's `allowedTools`/instructions onto the `AgentSession` so the chat authoring gate agrees with the loop's offer gate. Authors the reply (and each executed tool) via the internal `sendAgentReply` bridge. Tools run with the run-as user's **live** permissions unless the host passes a `permissions` snapshot (#2978), which `runToolLoop` forwards to `executeAsPrincipal` so a narrowed principal (e.g. a shared station) cannot reach grants — such as `readPermission`-gated data-surface fields — beyond that snapshot, including through `agents.invoke` delegation (the snapshot becomes the worker's permission ceiling).\n- **Agent orchestration** (L3, #1892) — the loop accepts non-manifest **`extraTools`** (`PrincipalTool[]`, from `@happyvertical/smrt-agents`), gated by the *same* fail-closed allow-list. The standard **`invoke-agent`** tool (`createInvokeAgentTool`, slug `agents.invoke`) lets a conversational agent delegate to a **worker agent under its own principal** — the worker runs via `executeAsPrincipal` as the originating user (never its own authority), the principal is immutable along the chain, and its completion is surfaced back into the conversation. `runPersonaConversationTurn` filters `extraTools` by the persona's `allowedTools` (offer gate); the tool's `execute` re-asserts `assertToolAllowed` (execution gate). See `@happyvertical/smrt-agents` for the delegation envelope + transports.\n- **Chat feedback capture** (`chat-feedback.ts`) — `captureChatFeedback()` + `acceptAppliedChange`/`rejectAppliedChange`/`correctResponse`/`rateResponse`/`thumbsUp`/`thumbsDown` write a `Feedback` row (personas) carrying the conversation's **correlation-id**, and (by default) reinforce the persona's learning memory (`reinforceFromFeedback`). So an in-chat reject decays a strategy below the reuse floor and it stops being recalled; a correction supersedes its stored value.\n\n## Voice Gateway Turns (#1910)\n\nVoice is an input mode for the existing persona chat harness, not a separate chat runtime. `createVoiceChatSession()` creates a short-lived `VoiceSession` for an authenticated actor/profile, binding tenant, persona, agent session, room, and optional thread. `handleVoiceGatewayTurn()` resolves that binding from `metadata.voiceSessionId`, checks the gateway's `session_id` and any supplied tenant/profile/persona/session/thread metadata against the server-side binding, persists the transcript through `ChatService.sendAgentUserMessage()`, runs `runPersonaConversationTurn()`, stamps voice/correlation metadata onto the persisted user/assistant/tool messages, records the gateway `turn_id`, and returns the gateway response contract. The Fetch-compatible `createVoiceGatewayTurnHandler()` adds the coarse gateway bearer-token check.\n\nThe gateway bearer token proves only \"this request came from the gateway\"; it never authorizes the end user. The short-lived `VoiceSession` binding is the user/session proof, and untrusted gateway metadata must be validated against that binding before any chat write or tool loop. Tool execution remains fail-closed through the persona allow-list mirrored onto `AgentSession` by `bindPersonaToSession()`.\n\n## Token streaming\n\n`chat-stream.ts` serves browser-safe SSE through `./client`. The host's\n`authorize(request, body)` is the sole trust boundary: resolve identity, tenant,\ncapabilities, and generation limits server-side; never authorize from request\nsession metadata. Persona turns reuse the principal and fail-closed tool gates.\nThe engine and browser-safe `SmrtChatBackend` keep custom-tool resolution\nserver-side. See [agents/token-streaming.md](agents/token-streaming.md) for the\nevent contract, CORS policy, and streaming behavior.\n\n## Streamed assistant turns with browser tools (#2908)\n\n`runAssistantTurn()` (`assistant-turn.ts`) is the host-route engine for the\nAssistantDock: one turn over `runToolLoop` with server tools (offer-gated by\n`principal.allowedTools`), browser tools (validated by\n`sanitizeClientToolDeclarations` + a server allow-list), `maxSteps`, `signal`,\nand `onUsage`. A browser tool call SUSPENDS the turn (`stoppedReason:\n'client_tools'`); the transcript waits in an `AssistantContinuationStore`\n(single-use, 15-minute TTL; `createSessionContinuationStore` keeps it in the\nAgentSession's `sessionContext`) and the browser resumes it with results,\nwhich reach the model wrapped `untrusted`. `createAssistantTurnResponse`\nserves the events as SSE; `assistant-turn-events.ts` is the browser-safe wire\ncontract (`./assistant-turn` subpath, also a vite library entry because the\nSvelte dock imports it). The dock decides whether a browser call runs or waits\nfor the user from the page registry, never the server's echo; destructive\nalways waits. Details: [`docs/assistant-dock.md`](../../docs/assistant-dock.md).\n\n## AssistantDock (#2904)\n\n`AssistantDock` (`svelte/components/assistant/`, exported from `./svelte`)\nuses a host `DataSurfaceRegistry`'s mounted descriptors (none: plain chat).\nActions: `normalizeDataSurfaceActionRequest` → `AssistantActionClient`\n(preview/apply over a server `DataSurfaceActionAdapter`, not the\n`data-surface-bridge.ts` channel). Generated `ChatThread`/`ChatMessage`\n`list`/`get` are tenant- not member-scoped; the dock never calls them.\n\n**Server routes (#3368).** `./sveltekit` `mountAssistantRoutes()` serves the\ndock from one `[...path]` route; `createAssistantHttp{Transport,ActionClient}`\n(`./svelte`) are its browser half. Principal from `event.locals` or\n`resolvePrincipal`; threads only from the actor's keyed session room in that\ntenant (else 404). `allowedTools` is fail-closed; without `tools` it offers\nthose manifest ops (an unprovided name is an error, #3414). `ai` defaults to\nthe config `ai` block. Pass `runtime`: a turn never keeps the RLS request tx\n(own `runAsPrincipal` tx). `clientRequestId` makes the row id a UUIDv5\n(`clientRequestMessageId`): the PK is the retry reservation. See\n[docs](../../docs/assistant-dock.md).\n\n## Recipes (#3719)\n\n`src/recipes.ts` declares `chat.assistant` (the AssistantDock as a `header.end`\nshell widget, an `llm` provider, runtime `both`; help in\n`src/assistant.recipe.md`). Keep each recipe class self-contained. Details:\n[agents/recipes.md](agents/recipes.md).\n\n## Gotchas\n\n- **sessionContext, not context**: `context` is reserved for slug scoping. Use `getSessionContext()`/`updateSessionContext()` for agent memory.\n- **Agent rooms auto-created**: `roomType: 'agent'`, `maxParticipants` defaults to 2; the agent is enrolled as a member so its replies pass the membership check. `createAgentSession()` re-enrolls the participant AND the agent on the existing-session path, so legacy sessions created before the agent was enrolled self-heal.\n- **The agent's author is a Profile, not `agentId` (#2995)**: `senderProfileId`/`profileId` are `crossPackageRef`s to `Profile` and therefore uuid columns on PostgreSQL, so the slug fails the cast (`22P02`) and no agent reply can persist. `createAgentSession()` resolves the agent's `bot` Profile through `resolveAgentProfile()` in `@happyvertical/smrt-profiles` (created on first use, tenant-bound) and records it as `AgentSession.agentProfileId`; both enrolment and `sendAgentReply` use that uuid. A consumer whose agent already has an acting identity passes `agentProfileId` to skip resolution — the voice path does this with the persona's `actsAsProfileId`, so persona replies stay attributed to the configured acting profile. Like `actorProfileId`, `agentProfileId` is SERVER-supplied, never request input: it selects the author of every later assistant message. It is validated (`#requireAgentProfile`) to exist and be visible in the tenant and to differ from the acting participant, and it can never re-point a session that already resolved one — only a pre-#2995 session with none is backfilled. **Migration**: `agent_profile_id` is an ordinary additive manifest field, so a consumer adopts it the same way as any other — `smrt db:migrate` generates and applies the column from the manifest, and `db:status --parity` verifies it; the framework never creates application schema at runtime. It is nullable and needs no offline DATA backfill — a session created before #2995 resolves and persists its `agentProfileId`, and re-enrols the agent, on its first agent turn after the upgrade. Two pre-#2995 cohorts: a session whose `agentId` is an ordinary slug never committed an author on PostgreSQL (the cast failed), so there is nothing to repair there, while SQLite/DuckDB may hold `chat_messages`/`chat_participants` rows whose id column holds the slug — readable, but not joinable to `profiles`. A session whose `agentId` is already a Profile uuid (the voice path used to collapse a persona's `actsAsProfileId` into it) DID commit on PostgreSQL; that profile is ADOPTED as the author, tenant-checked and never the participant, so the conversation's author does not change and the two-seat room gains no third identity. Known one-time effect: because `voice.ts` no longer derives `agentId` from `actsAsProfileId`, a keyless `createVoiceChatSession()` for such a persona opens a new session and room instead of reusing the legacy one; the old room and its messages stay intact and readable, and resuming with an explicit `agentSessionId` is unaffected.\n- **Only SQLite-backed tests would miss this class of bug**: uuid columns accept any text on SQLite. `src/__tests__/agent-reply-postgres.test.ts` (`pnpm --filter @happyvertical/smrt-chat test:postgres`) pins the agent-reply path against real PostgreSQL. That suite runs in `postgres-tests.yml` on every same-repository PR and merge group (#2659); keep a cheap SQLite assertion alongside it anyway, since the default lane is SQLite-only (`chat-service.test.ts` asserts the author is the profile uuid, not the slug).\n- **Per-subject sessions need `sessionKey`**: `createAgentSession()` reuses ANY active session for the same `(agentId, participantProfileId, tenantId)`. Callers that open separate conversations per subject (e.g. one content-editor session per content id) MUST pass a stable `sessionKey` (stored in `sessionContext.__sessionKey`, read via `AgentSession.getSessionKey()`); otherwise a session opened for one subject is reused and its context overwritten for another, surfacing the wrong room/threads (S5 #1392). A keyed create never reuses a keyless/legacy session.\n- **Session expiry**: check `isActive()` before allowing messages (expiresAt or limit-based)\n- **DM identity**: derived from the deterministic per-tenant `canonicalDmRoomId()` and the authoritative `chat_participants` join, not client metadata; concurrent creates upsert onto one row.\n- **Tenant-bound lookups**: membership/session/DM lookups REQUIRE `tenantId` and always bind it into the WHERE clause (`findActiveMembership`/`isActiveMember`/`findActiveSession` take a required `tenantId`; AgentSession's `null` tenant is an explicit bound scope, not \"any tenant\") so they can never resolve a row from another tenant.\n",
+  "agentDoc": "# @happyvertical/smrt-chat\n\nChat rooms, threads, and agent sessions with app-controlled tool whitelisting.\n\n## Dev Server\n\n`pnpm --dir packages/chat dev` runs a package-local SvelteKit workbench. The root\nroute separates **Character setup** and **Chat dev** into tabs; switching tabs\nretains the current character rig and chat state. The chat tab is an interactive\nsurface with a dev-only `/api/dev-chat` endpoint:\nit uses `@happyvertical/ai` when local provider credentials are present and\nfalls back to a deterministic local assistant otherwise. `/api/dev-chat-stream`\nis its SSE companion (#1936) — the same provider/local-fallback resolution wired\nthrough `createChatStreamHandler` in plain mode, so an embedded `SmrtChatBackend`\nclient can exercise token streaming locally. `/previews` hosts the shared\ncomponent playground entries from `src/svelte/playground.ts`.\n\nThe root route also drives the **browser inference path**\n(`@happyvertical/smrt-web/ai`: bitgpu, WebLLM, and route backends composed by\n`createInferencePath`) and an **agent-addressable draft form** (`useViewIntent`\nover `src/routes/chat-dev.intents.ts`, #2588). Their dev-config dependencies\n(static optional-peer imports, `workspace-aliases.js` prefix rules, the theme\nstylesheet import) and the stage→apply tool-call gotchas are in\n[agents/dev-workbench.md](agents/dev-workbench.md).\n\nDev-only voice and opt-in local character persistence are documented in\n[agents/dev-workbench.md](agents/dev-workbench.md#voice-and-local-character-persistence).\nThese endpoints are loopback-only demos; production hosts supply authenticated\nprincipals, tenancy, and authorization to the owning services.\n\n## Models\n\nAll seven models expose only generated REST/MCP `list`/`get`; structural tests\ncheck the registry for accidental mutating operations. Writes go through\nmembership/owner-checked `ChatService` or the binding-checked voice adapter.\n\n`ChatService` is a closed facade. Its collections and security-sensitive\nhelpers use ES `#private` fields/methods (TypeScript `private` is erased).\nCollection classes are not exported from the package index. The agent-reply\nbridge is a Symbol-keyed static accessible through a non-exported symbol held\nby the module-local `sendAgentReply` function.\n\n- **ChatRoom**: `roomType` (public/private/dm/agent), `status`, `topic`, `maxParticipants`, `lastMessageAt`. Tenant-scoped (required).\n- **ChatMessage**: shared by users + agents. `role` (user/assistant/system/tool), `messageType` (text/system/action/file/tool_call/tool_result), `toolCallData` JSON. Unified model — no separate agent message type. Tenant-scoped (required).\n- **ChatParticipant**: `role` (owner/admin/member/viewer), `onlineStatus`, `lastReadMessageId`, `isMuted`. Tenant-scoped (required).\n- **ChatThread**: `rootMessageId`, `isResolved`, `messageCount`. Created via `ChatService.startThread()` (member-checked). Tenant-scoped (required).\n- **ChatReaction**: `messageId`, `profileId`, `emoji`. Added/removed via `ChatService.addReaction()`/`removeReaction()` (member-checked, self-keyed). Tenant-scoped (required).\n- **AgentSession**: `agentId` (application slug, string ref, not FK), `agentProfileId` (nullable `crossPackageRef` to `Profile` — the `bot` profile the agent AUTHORS as, #2995), `allowedTools` (JSON string array), `sessionContext` (JSON, sensitive), `systemPrompt`, limits (`maxTokens`/`maxMessages`/`expiresAt`). Optional tenancy.\n- **VoiceSession**: short-lived voice-gateway binding over `(tenant, actorProfileId, personaId, room/thread/agentSession)` plus a persona snapshot, gateway `session_id`, expiry, replay tracking, and metadata. Tenant-scoped (required). Generated surface is read-only; creation and turns go through `createVoiceChatSession()` / `handleVoiceGatewayTurn()`.\n\n## ChatService\n\nPublic writes take server-supplied `actorProfileId`; never trust a request's\n`senderProfileId`, `role`, owner id, or participant id as authority.\n\n| Operation | Authorization and behavior |\n|---|---|\n| `sendMessage()` | Room member; authors as actor with `role: 'user'`; no public membership bypass |\n| `createRoom()` | Actor becomes owner |\n| `startThread()` | Member; optional root message bound to room and tenant |\n| `addParticipant()` / `removeParticipant()` | Owner/admin; self-leave allowed |\n| `updateRoom()` | Owner/admin |\n| `addReaction()` / `removeReaction()` | Member; self-keyed |\n| `getOrCreateDM()` | Actor must be a DM participant |\n| `createAgentSession()` | Actor becomes session participant; existing-session lookup tenant-bound; optional `sessionKey` isolates conversation subjects |\n| `updateAgentSessionConfig()` | Owner; mandatory tenant-bound lookup |\n| `sendAgentUserMessage()` | Actor must be session participant; authored as participant |\n\nRead facade: `getAgentSession({agentSessionId, tenantId})`,\n`findActiveAgentSessions({tenantId, agentId, participantProfileId})`, and\n`getThread({threadId, tenantId})` are tenant-bound; consumers still check\nownership/context. `listRoomThreads({roomId, actorProfileId, tenantId})`,\n`getThreadMessages({threadId, actorProfileId, tenantId, limit?})` (chronological),\n`getRoomMessages({roomId, actorProfileId, tenantId})`, and\n`getRoomForMember(roomId, actorProfileId, tenantId)` additionally require\nmembership of the server-supplied actor, not a caller-selected subject.\n\nTrusted agent runtime imports `sendAgentReply(service, params)` only from\n`@happyvertical/smrt-chat/internal/agent-runtime`. It is not a `ChatService`\nmethod or package-index export. It authors as `session.agentProfileId` — the\nagent's resolved `bot` Profile, NEVER the `agentId` slug (#2995) — accepts a\nsame-room/tenant thread, and enforces `allowedTools` fail-closed.\n\nPrivate `#writeMessage` alone can select arbitrary authors/roles or bypass\nmembership. It binds every supplied `threadId`, `agentSessionId`, and\n`replyToMessageId` to the same room **and** tenant. Internal enrollment supports\nautomatically created rooms, sessions, and participants.\n\n## Agent Tool Whitelisting\n\n`allowedTools` is a JSON array controlled by the consuming app. Fail-closed: an empty/unparseable whitelist permits NO tools. The internal `sendAgentReply(service, params)` function enforces the whitelist before emitting any `tool`/`tool_call` message; a caller cannot supply a `senderProfileId`/`role` to post as the agent, and the function is not reachable from the package index.\n\nPrincipal-bound data discovery and reads are available as `PrincipalTool[]` via\n`createDataSurfaceTools()` (re-exported by the chat package). Pass the tools as\n`extraTools` to the persona conversation/tool loop. They use the same\nfail-closed `allowedTools` offer/execution gates; RBAC, tenant, redaction,\nbounded query results, and audit authority remain in the authenticated\n`PrincipalRun` supplied by `@happyvertical/smrt-agents`.\n\n## Commerce money tools (#3937)\n\nHosts that offer invoice money work must explicitly register\n`createCommerceMoneyTools()` from `@happyvertical/smrt-commerce` in\ntheir authenticated assistant route's `extraTools` (for example, `extraTools: () => createCommerceMoneyTools()`) and\nadd only the desired `commerce.*` slugs to the persona's `allowedTools`.\nThey are not generic manifest CRUD tools: tax codes are selected by code,\npreview is calculator-only, and line writes run through the document-money\ncoordinator. Each execution reasserts the principal allow-list and required\n`Invoice`, `InvoiceLineItem`, `DocumentTax`, and `TaxCode` operations. The\ngenerated MCP invoice `get` serializer remains commerce-owned; use its\nstored-facts integration when that serializer exposes `DocumentTax` rows.\n\n## Runtime report tools (#3711)\n\n`createRuntimeReportTools()` (`runtime-report-tools.ts`) returns four\n`PrincipalTool`s for the persona `extraTools` seam: `reports.runtime.sources`,\n`reports.runtime.define` (`preview` / `apply`), `reports.runtime.list`, and\n`reports.runtime.run`. The model supplies only a declarative\n`RuntimeReportSpec` from `@happyvertical/smrt-reports`; sources are a\nserver-owned allow-list gated by `run.assertOperation(collection, 'read')`, and\nfield policy, `readPermission`, and tenancy are enforced by the compiler against\nthe live run on every compile and every stored-report run. `apply` needs the\n`specHash` of the previewed spec plus an app-owned `confirmation` host that\nresolves only after a human approved that exact spec; with no host apply returns an `awaiting_confirmation` proposal for the\nsame-origin browser confirm route and stores nothing and a model-supplied `confirmed` flag is ignored. Saving also needs\n`create` on the `RuntimeReport` collection, and `list`/`run` need `read`; the\ndefault `reportsCollection` is the `RuntimeReport` class itself, which resolves\nto the catalog slug. A string `collection`/`reportsCollection` is used verbatim\nas a catalog slug (never a class name); tests must run the tools under the real\n`assertOperationPermission` guard so a wrong slug fails. A stored report is\nwritten only by this confirmed `apply`: the model layer refuses every other\ninsert/spec change, and the generic manifest tools (`buildManifestToolCatalog`,\n`invokeManifestTool`) never offer or run a `RuntimeReport` write. Stored-report\nreads/saves run under the principal's tenant (`withPrincipalTenant`), refuse a\nmismatching ambient tenant (checked before `confirmSave`), and filter by the principal tenant explicitly. Contract and authority model:\n[`packages/reports/agents/runtime-reports.md`](../reports/agents/runtime-reports.md).\n\n## Overview tools (#3727)\n\n`createOverviewTools({ host })` (`overview-tools.ts`) returns\n`overviews.describe`, `overviews.apply` (an atomic batch of structured widget\noperations) and `overviews.undo` (single step, keyed by tenant, user and page).\nThe host opens a page per `PrincipalRun` (smrt-svelte's\n`createOverviewAssistantSurface`, typed structurally here); validation and\n`canCustomize` are the surface's. Contract:\n[agents/overview-tools.md](agents/overview-tools.md).\n\n## Conversational Harness (L3, #1891)\n\nThe `AgentSession` runtime depends on personas, agents, and users. Keep those\nedges acyclic: none of those packages may depend back on chat.\n\n- **`runToolLoop(options)`** (`tool-loop.ts`) — a bounded `tool_call → observe → respond` loop. Tools are **manifest operations** of installed packages: `buildManifestToolCatalog({ allowedTools })` reads the `PermissionCatalogService` catalog and keeps only the `(collection, action)` entries named in the persona's allow-list (the **offer gate**; absent/empty ⇒ NO tools). The loop runs inside one `executeAsPrincipal` context, and `invokeManifestTool` executes each op **in-process (\"side door\")** against `run.context.database` (the RLS tx when Postgres RLS is on), after re-asserting the fail-closed allow-list (`run.assertToolAllowed`) AND the catalog permission (`run.assertOperation`) — the **execution gate**. Bounded by a max-steps ceiling (`DEFAULT_MAX_STEPS = 8`): on the ceiling it disables tools for one final completion so the turn always terminates with text. A thrown tool error is classified (`classifyToolError`): permission denials and 401/403 are `not_permitted`; a `ValidationError` or 400/404/409/422 is `invalid_request` (observation: actionable message, `publicMessage` first, `code`, fix-and-retry hint); else (incl. 429) `execution_error`.\n- **`runPersonaConversationTurn(options)`** (`persona-conversation.ts`) — binds a conversation to an `AgentPersona`/`ResolvedPersona`: runs as its principal (`runAsUserId`), offers only its `allowedTools`, speaks its instructions (`resolvePersonaInstructions`, layering approved learned directives), and injects its **recalled learning memory** (`personaLearningMemory`, isolated per `memoryScope`) into the system prompt. `bindPersonaToSession()` mirrors the persona's `allowedTools`/instructions onto the `AgentSession` so the chat authoring gate agrees with the loop's offer gate. Authors the reply (and each executed tool) via the internal `sendAgentReply` bridge. Tools run with the run-as user's **live** permissions unless the host passes a `permissions` snapshot (#2978), which `runToolLoop` forwards to `executeAsPrincipal` so a narrowed principal (e.g. a shared station) cannot reach grants — such as `readPermission`-gated data-surface fields — beyond that snapshot, including through `agents.invoke` delegation (the snapshot becomes the worker's permission ceiling).\n- **Agent orchestration** (L3, #1892) — the loop accepts non-manifest **`extraTools`** (`PrincipalTool[]`, from `@happyvertical/smrt-agents`), gated by the *same* fail-closed allow-list. The standard **`invoke-agent`** tool (`createInvokeAgentTool`, slug `agents.invoke`) lets a conversational agent delegate to a **worker agent under its own principal** — the worker runs via `executeAsPrincipal` as the originating user (never its own authority), the principal is immutable along the chain, and its completion is surfaced back into the conversation. `runPersonaConversationTurn` filters `extraTools` by the persona's `allowedTools` (offer gate); the tool's `execute` re-asserts `assertToolAllowed` (execution gate). See `@happyvertical/smrt-agents` for the delegation envelope + transports.\n- **Chat feedback capture** (`chat-feedback.ts`) — `captureChatFeedback()` + `acceptAppliedChange`/`rejectAppliedChange`/`correctResponse`/`rateResponse`/`thumbsUp`/`thumbsDown` write a `Feedback` row (personas) carrying the conversation's **correlation-id**, and (by default) reinforce the persona's learning memory (`reinforceFromFeedback`). So an in-chat reject decays a strategy below the reuse floor and it stops being recalled; a correction supersedes its stored value.\n\n## Voice Gateway Turns (#1910)\n\nVoice is an input mode for the existing persona chat harness, not a separate chat runtime. `createVoiceChatSession()` creates a short-lived `VoiceSession` for an authenticated actor/profile, binding tenant, persona, agent session, room, and optional thread. `handleVoiceGatewayTurn()` resolves that binding from `metadata.voiceSessionId`, checks the gateway's `session_id` and any supplied tenant/profile/persona/session/thread metadata against the server-side binding, persists the transcript through `ChatService.sendAgentUserMessage()`, runs `runPersonaConversationTurn()`, stamps voice/correlation metadata onto the persisted user/assistant/tool messages, records the gateway `turn_id`, and returns the gateway response contract. The Fetch-compatible `createVoiceGatewayTurnHandler()` adds the coarse gateway bearer-token check.\n\nThe gateway bearer token proves only \"this request came from the gateway\"; it never authorizes the end user. The short-lived `VoiceSession` binding is the user/session proof, and untrusted gateway metadata must be validated against that binding before any chat write or tool loop. Tool execution remains fail-closed through the persona allow-list mirrored onto `AgentSession` by `bindPersonaToSession()`.\n\n## Token streaming\n\n`chat-stream.ts` serves browser-safe SSE through `./client`. The host's\n`authorize(request, body)` is the sole trust boundary: resolve identity, tenant,\ncapabilities, and generation limits server-side; never authorize from request\nsession metadata. Persona turns reuse the principal and fail-closed tool gates.\nThe engine and browser-safe `SmrtChatBackend` keep custom-tool resolution\nserver-side. See [agents/token-streaming.md](agents/token-streaming.md) for the\nevent contract, CORS policy, and streaming behavior.\n\n## Streamed assistant turns with browser tools (#2908)\n\n`runAssistantTurn()` (`assistant-turn.ts`) is the host-route engine for the\nAssistantDock: one turn over `runToolLoop` with server tools (offer-gated by\n`principal.allowedTools`), browser tools (validated by\n`sanitizeClientToolDeclarations` + a server allow-list), `maxSteps`, `signal`,\nand `onUsage`. A browser tool call SUSPENDS the turn (`stoppedReason:\n'client_tools'`); the transcript waits in an `AssistantContinuationStore`\n(single-use, 15-minute TTL; `createSessionContinuationStore` keeps it in the\nAgentSession's `sessionContext`) and the browser resumes it with results,\nwhich reach the model wrapped `untrusted`. `createAssistantTurnResponse`\nserves the events as SSE; `assistant-turn-events.ts` is the browser-safe wire\ncontract (`./assistant-turn` subpath, also a vite library entry because the\nSvelte dock imports it). The dock decides whether a browser call runs or waits\nfor the user from the page registry, never the server's echo; destructive\nalways waits. Details: [`docs/assistant-dock.md`](../../docs/assistant-dock.md).\n\n## AssistantDock (#2904)\n\n`AssistantDock` (`svelte/components/assistant/`, exported from `./svelte`)\nuses a host `DataSurfaceRegistry`'s mounted descriptors (none: plain chat).\nActions: `normalizeDataSurfaceActionRequest` → `AssistantActionClient`\n(preview/apply over a server `DataSurfaceActionAdapter`, not the\n`data-surface-bridge.ts` channel). Generated `ChatThread`/`ChatMessage`\n`list`/`get` are tenant- not member-scoped; the dock never calls them.\n\n**Server routes (#3368).** `./sveltekit` `mountAssistantRoutes()` serves the\ndock from one `[...path]` route; `createAssistantHttp{Transport,ActionClient}`\n(`./svelte`) are its browser half. Principal from `event.locals` or\n`resolvePrincipal`; threads only from the actor's keyed session room in that\ntenant (else 404). `allowedTools` is fail-closed; without `tools` it offers\nthose manifest ops (an unprovided name is an error, #3414). `ai` defaults to\nthe config `ai` block. Pass `runtime`: a turn never keeps the RLS request tx\n(own `runAsPrincipal` tx). `clientRequestId` makes the row id a UUIDv5\n(`clientRequestMessageId`): the PK is the retry reservation. See\n[docs](../../docs/assistant-dock.md).\n\n## Recipes (#3719)\n\n`src/recipes.ts` declares `chat.assistant` (the AssistantDock as a `header.end`\nshell widget, an `llm` provider, runtime `both`; help in\n`src/assistant.recipe.md`). Keep each recipe class self-contained. Details:\n[agents/recipes.md](agents/recipes.md).\n\n## Gotchas\n\n- **sessionContext, not context**: `context` is reserved for slug scoping. Use `getSessionContext()`/`updateSessionContext()` for agent memory.\n- **Agent rooms auto-created**: `roomType: 'agent'`, `maxParticipants` defaults to 2; the agent is enrolled as a member so its replies pass the membership check. `createAgentSession()` re-enrolls the participant AND the agent on the existing-session path, so legacy sessions created before the agent was enrolled self-heal.\n- **The agent's author is a Profile, not `agentId` (#2995)**: `senderProfileId`/`profileId` are `crossPackageRef`s to `Profile` and therefore uuid columns on PostgreSQL, so the slug fails the cast (`22P02`) and no agent reply can persist. `createAgentSession()` resolves the agent's `bot` Profile through `resolveAgentProfile()` in `@happyvertical/smrt-profiles` (created on first use, tenant-bound) and records it as `AgentSession.agentProfileId`; both enrolment and `sendAgentReply` use that uuid. A consumer whose agent already has an acting identity passes `agentProfileId` to skip resolution — the voice path does this with the persona's `actsAsProfileId`, so persona replies stay attributed to the configured acting profile. Like `actorProfileId`, `agentProfileId` is SERVER-supplied, never request input: it selects the author of every later assistant message. It is validated (`#requireAgentProfile`) to exist and be visible in the tenant and to differ from the acting participant, and it can never re-point a session that already resolved one — only a pre-#2995 session with none is backfilled. **Migration**: `agent_profile_id` is an ordinary additive manifest field, so a consumer adopts it the same way as any other — `smrt db:migrate` generates and applies the column from the manifest, and `db:status --parity` verifies it; the framework never creates application schema at runtime. It is nullable and needs no offline DATA backfill — a session created before #2995 resolves and persists its `agentProfileId`, and re-enrols the agent, on its first agent turn after the upgrade. Two pre-#2995 cohorts: a session whose `agentId` is an ordinary slug never committed an author on PostgreSQL (the cast failed), so there is nothing to repair there, while SQLite/DuckDB may hold `chat_messages`/`chat_participants` rows whose id column holds the slug — readable, but not joinable to `profiles`. A session whose `agentId` is already a Profile uuid (the voice path used to collapse a persona's `actsAsProfileId` into it) DID commit on PostgreSQL; that profile is ADOPTED as the author, tenant-checked and never the participant, so the conversation's author does not change and the two-seat room gains no third identity. Known one-time effect: because `voice.ts` no longer derives `agentId` from `actsAsProfileId`, a keyless `createVoiceChatSession()` for such a persona opens a new session and room instead of reusing the legacy one; the old room and its messages stay intact and readable, and resuming with an explicit `agentSessionId` is unaffected.\n- **Only SQLite-backed tests would miss this class of bug**: uuid columns accept any text on SQLite. `src/__tests__/agent-reply-postgres.test.ts` (`pnpm --filter @happyvertical/smrt-chat test:postgres`) pins the agent-reply path against real PostgreSQL. That suite runs in `postgres-tests.yml` on every same-repository PR and merge group (#2659); keep a cheap SQLite assertion alongside it anyway, since the default lane is SQLite-only (`chat-service.test.ts` asserts the author is the profile uuid, not the slug).\n- **Per-subject sessions need `sessionKey`**: `createAgentSession()` reuses ANY active session for the same `(agentId, participantProfileId, tenantId)`. Callers that open separate conversations per subject (e.g. one content-editor session per content id) MUST pass a stable `sessionKey` (stored in `sessionContext.__sessionKey`, read via `AgentSession.getSessionKey()`); otherwise a session opened for one subject is reused and its context overwritten for another, surfacing the wrong room/threads (S5 #1392). A keyed create never reuses a keyless/legacy session.\n- **Session expiry**: check `isActive()` before allowing messages (expiresAt or limit-based)\n- **DM identity**: derived from the deterministic per-tenant `canonicalDmRoomId()` and the authoritative `chat_participants` join, not client metadata; concurrent creates upsert onto one row.\n- **Tenant-bound lookups**: membership/session/DM lookups REQUIRE `tenantId` and always bind it into the WHERE clause (`findActiveMembership`/`isActiveMember`/`findActiveSession` take a required `tenantId`; AgentSession's `null` tenant is an explicit bound scope, not \"any tenant\") so they can never resolve a row from another tenant.\n",
   "moduleDocs": [
     {
       "path": "agents/dev-workbench.md",