@happyvertical/smrt-chat 0.38.24 → 0.38.26

package/dist/smrt-knowledge.json

@@ -1,14 +1,14 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-07-09T22:58:30.681Z",
+  "generatedAt": "2026-07-10T12:54:56.500Z",
   "packageName": "@happyvertical/smrt-chat",
-  "packageVersion": "0.38.24",
+  "packageVersion": "0.38.26",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "c8199af419d2152049dfba55bd5633e85c1ef7d93fe559172de33967a6463343",
-    "packageJson": "c0a5849e26b143fd1dae016e0b34ddfd151b13137668d603fa94e1c2e5f192bc",
-    "agents": "c1cee4d26a176b177856ebcceaa3c7ea0bf6dc108c779036a4532cde7eea96e7"
+    "manifest": "66abcc6e33b44cc9b2f94aa592c89a4d913fc79a599c853e492340fdfa9d0ad9",
+    "packageJson": "d3cbae82592618c9e03bb44885e6078fd61c04fc61270b851f3d9cbba2eee506",
+    "agents": "6cd3406a8954dd51b7c3354115a022333c96f125c9e2ac1ede272951da2a1f10"
   },
   "exports": [
     ".",
@@ -29,8 +29,10 @@
     "@happyvertical/smrt-ui": "workspace:*",
     "@happyvertical/smrt-users": "workspace:*",
     "@happyvertical/sql": "catalog:",
+    "@happyvertical/smrt-playground": "workspace:*",
     "@happyvertical/smrt-profiles": "workspace:*",
     "@happyvertical/smrt-vitest": "workspace:*",
+    "@sveltejs/kit": "^2.69.1",
     "@sveltejs/package": "^2.5.8",
     "@sveltejs/vite-plugin-svelte": "^7.1.2",
     "@types/node": "24.13.2",
@@ -45,6 +47,7 @@
     "@happyvertical/smrt-agents",
     "@happyvertical/smrt-core",
     "@happyvertical/smrt-personas",
+    "@happyvertical/smrt-playground",
     "@happyvertical/smrt-profiles",
     "@happyvertical/smrt-tenancy",
     "@happyvertical/smrt-types",
@@ -59,6 +62,184 @@
   "tags": [],
   "risks": [],
   "objects": [
+    {
+      "name": "AgentSessionCollection",
+      "qualifiedName": "@happyvertical/smrt-chat:AgentSessionCollection",
+      "collection": "agentsessions",
+      "tableName": "agent_sessions",
+      "packageName": "@happyvertical/smrt-chat",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "expireStale",
+        "findActiveByParticipant",
+        "findActiveSession",
+        "findByAgent",
+        "findOrCreate"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "ChatMessageCollection",
+      "qualifiedName": "@happyvertical/smrt-chat:ChatMessageCollection",
+      "collection": "chatmessages",
+      "tableName": "chat_messages",
+      "packageName": "@happyvertical/smrt-chat",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "getByAgentSession",
+        "getByRoom",
+        "getByThread",
+        "getLatestPerRoom",
+        "getUnreadCount",
+        "search"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "ChatParticipantCollection",
+      "qualifiedName": "@happyvertical/smrt-chat:ChatParticipantCollection",
+      "collection": "chatparticipants",
+      "tableName": "chat_participants",
+      "packageName": "@happyvertical/smrt-chat",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "countInRoom",
+        "findActiveMembership",
+        "findMembership",
+        "getAdminsInRoom",
+        "getByProfile",
+        "getByRoom",
+        "getOnlineInRoom",
+        "isActiveMember"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "ChatReactionCollection",
+      "qualifiedName": "@happyvertical/smrt-chat:ChatReactionCollection",
+      "collection": "chatreactions",
+      "tableName": "chat_reactions",
+      "packageName": "@happyvertical/smrt-chat",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "getByMessage",
+        "getReactionCounts",
+        "toggle"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "ChatRoomCollection",
+      "qualifiedName": "@happyvertical/smrt-chat:ChatRoomCollection",
+      "collection": "chatrooms",
+      "tableName": "chat_rooms",
+      "packageName": "@happyvertical/smrt-chat",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "findAgentRooms",
+        "findByType",
+        "findDMs",
+        "findOrCreateDM",
+        "findPublic",
+        "search"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "ChatThreadCollection",
+      "qualifiedName": "@happyvertical/smrt-chat:ChatThreadCollection",
+      "collection": "chatthreads",
+      "tableName": "chat_threads",
+      "packageName": "@happyvertical/smrt-chat",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "getActive",
+        "getByRoom",
+        "getUnresolved"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "VoiceGatewayTurnCollection",
+      "qualifiedName": "@happyvertical/smrt-chat:VoiceGatewayTurnCollection",
+      "collection": "voicegatewayturns",
+      "tableName": "voice_gateway_turns",
+      "packageName": "@happyvertical/smrt-chat",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "reserveTurn"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "VoiceSessionCollection",
+      "qualifiedName": "@happyvertical/smrt-chat:VoiceSessionCollection",
+      "collection": "voicesessions",
+      "tableName": "voice_sessions",
+      "packageName": "@happyvertical/smrt-chat",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "expireStale",
+        "getActiveById"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "AgentSession",
       "qualifiedName": "@happyvertical/smrt-chat:AgentSession",
@@ -1058,139 +1239,344 @@
       "risks": []
     },
     {
-      "name": "AgentSessionCollection",
-      "qualifiedName": "@happyvertical/smrt-chat:AgentSessionCollection",
-      "collection": "agentsessions",
-      "tableName": "agent_sessions",
+      "name": "VoiceGatewayTurn",
+      "qualifiedName": "@happyvertical/smrt-chat:VoiceGatewayTurn",
+      "collection": "voicegatewayturns",
+      "tableName": "voice_gateway_turns",
       "packageName": "@happyvertical/smrt-chat",
-      "extends": "SmrtCollection",
-      "fields": [],
-      "relationships": [],
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "voiceSessionId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "VoiceSession",
+          "columnType": "UUID"
+        },
+        {
+          "name": "gatewaySessionId",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "gatewayTurnId",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "target",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "status",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "completedAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "failedAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "voiceSessionId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "VoiceSession",
+          "columnType": "UUID"
+        }
+      ],
       "methods": [
-        "expireStale",
-        "findActiveByParticipant",
-        "findActiveSession",
-        "findByAgent",
-        "findOrCreate"
+        "complete",
+        "fail"
+      ],
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "voicegatewayturns.list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-chat:VoiceGatewayTurn",
+          "path": "/voicegatewayturns",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "voicegatewayturns.get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-chat:VoiceGatewayTurn",
+          "path": "/voicegatewayturns/[id]",
+          "method": "GET"
+        },
+        {
+          "kind": "mcp",
+          "name": "voicegatewayturn_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-chat:VoiceGatewayTurn"
+        },
+        {
+          "kind": "mcp",
+          "name": "voicegatewayturn_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-chat:VoiceGatewayTurn"
+        }
       ],
-      "surfaces": [],
       "relationshipFeatures": [
+        "foreignKey",
         "uuidColumns"
       ],
       "tags": [],
       "risks": []
     },
     {
-      "name": "ChatMessageCollection",
-      "qualifiedName": "@happyvertical/smrt-chat:ChatMessageCollection",
-      "collection": "chatmessages",
-      "tableName": "chat_messages",
-      "packageName": "@happyvertical/smrt-chat",
-      "extends": "SmrtCollection",
-      "fields": [],
-      "relationships": [],
-      "methods": [
-        "getByAgentSession",
-        "getByRoom",
-        "getByThread",
-        "getLatestPerRoom",
-        "getUnreadCount",
-        "search"
-      ],
-      "surfaces": [],
-      "relationshipFeatures": [
-        "uuidColumns"
-      ],
-      "tags": [],
-      "risks": []
-    },
-    {
-      "name": "ChatParticipantCollection",
-      "qualifiedName": "@happyvertical/smrt-chat:ChatParticipantCollection",
-      "collection": "chatparticipants",
-      "tableName": "chat_participants",
-      "packageName": "@happyvertical/smrt-chat",
-      "extends": "SmrtCollection",
-      "fields": [],
-      "relationships": [],
-      "methods": [
-        "countInRoom",
-        "findActiveMembership",
-        "findMembership",
-        "getAdminsInRoom",
-        "getByProfile",
-        "getByRoom",
-        "getOnlineInRoom",
-        "isActiveMember"
-      ],
-      "surfaces": [],
-      "relationshipFeatures": [
-        "uuidColumns"
-      ],
-      "tags": [],
-      "risks": []
-    },
-    {
-      "name": "ChatReactionCollection",
-      "qualifiedName": "@happyvertical/smrt-chat:ChatReactionCollection",
-      "collection": "chatreactions",
-      "tableName": "chat_reactions",
+      "name": "VoiceSession",
+      "qualifiedName": "@happyvertical/smrt-chat:VoiceSession",
+      "collection": "voicesessions",
+      "tableName": "voice_sessions",
       "packageName": "@happyvertical/smrt-chat",
-      "extends": "SmrtCollection",
-      "fields": [],
-      "relationships": [],
-      "methods": [
-        "getByMessage",
-        "getReactionCounts",
-        "toggle"
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "gatewaySessionId",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "actorProfileId",
+          "type": "crossPackageRef",
+          "required": true,
+          "related": "@happyvertical/smrt-profiles:Profile",
+          "columnType": "UUID"
+        },
+        {
+          "name": "actorUserId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-users:User",
+          "columnType": "UUID"
+        },
+        {
+          "name": "personaId",
+          "type": "crossPackageRef",
+          "required": true,
+          "related": "@happyvertical/smrt-personas:AgentPersona",
+          "columnType": "UUID"
+        },
+        {
+          "name": "agentSessionId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "AgentSession",
+          "columnType": "UUID"
+        },
+        {
+          "name": "chatRoomId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "ChatRoom",
+          "columnType": "UUID"
+        },
+        {
+          "name": "threadId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "ChatThread",
+          "columnType": "UUID"
+        },
+        {
+          "name": "target",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "status",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "expiresAt",
+          "type": "datetime",
+          "required": true,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "lastTurnAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "lastGatewayTurnId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "personaSnapshot",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "metadata",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "processedTurnIds",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
       ],
-      "surfaces": [],
-      "relationshipFeatures": [
-        "uuidColumns"
+      "relationships": [
+        {
+          "name": "actorProfileId",
+          "type": "crossPackageRef",
+          "required": true,
+          "related": "@happyvertical/smrt-profiles:Profile",
+          "columnType": "UUID"
+        },
+        {
+          "name": "actorUserId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-users:User",
+          "columnType": "UUID"
+        },
+        {
+          "name": "personaId",
+          "type": "crossPackageRef",
+          "required": true,
+          "related": "@happyvertical/smrt-personas:AgentPersona",
+          "columnType": "UUID"
+        },
+        {
+          "name": "agentSessionId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "AgentSession",
+          "columnType": "UUID"
+        },
+        {
+          "name": "chatRoomId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "ChatRoom",
+          "columnType": "UUID"
+        },
+        {
+          "name": "threadId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "ChatThread",
+          "columnType": "UUID"
+        }
       ],
-      "tags": [],
-      "risks": []
-    },
-    {
-      "name": "ChatRoomCollection",
-      "qualifiedName": "@happyvertical/smrt-chat:ChatRoomCollection",
-      "collection": "chatrooms",
-      "tableName": "chat_rooms",
-      "packageName": "@happyvertical/smrt-chat",
-      "extends": "SmrtCollection",
-      "fields": [],
-      "relationships": [],
       "methods": [
-        "findAgentRooms",
-        "findByType",
-        "findDMs",
-        "findOrCreateDM",
-        "findPublic",
-        "search"
-      ],
-      "surfaces": [],
-      "relationshipFeatures": [
-        "uuidColumns"
+        "expire",
+        "getMetadata",
+        "getPersonaSnapshot",
+        "getProcessedTurnIds",
+        "hasProcessedTurn",
+        "isActive",
+        "isExpired",
+        "recordGatewayTurn",
+        "revoke",
+        "setMetadata",
+        "setPersonaSnapshot"
       ],
-      "tags": [],
-      "risks": []
-    },
-    {
-      "name": "ChatThreadCollection",
-      "qualifiedName": "@happyvertical/smrt-chat:ChatThreadCollection",
-      "collection": "chatthreads",
-      "tableName": "chat_threads",
-      "packageName": "@happyvertical/smrt-chat",
-      "extends": "SmrtCollection",
-      "fields": [],
-      "relationships": [],
-      "methods": [
-        "getActive",
-        "getByRoom",
-        "getUnresolved"
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "voicesessions.list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-chat:VoiceSession",
+          "path": "/voicesessions",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "voicesessions.get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-chat:VoiceSession",
+          "path": "/voicesessions/[id]",
+          "method": "GET"
+        },
+        {
+          "kind": "cli",
+          "name": "voicesession_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-chat:VoiceSession"
+        },
+        {
+          "kind": "cli",
+          "name": "voicesession_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-chat:VoiceSession"
+        },
+        {
+          "kind": "cli",
+          "name": "voicesession_create",
+          "operation": "create",
+          "objectName": "@happyvertical/smrt-chat:VoiceSession"
+        },
+        {
+          "kind": "cli",
+          "name": "voicesession_update",
+          "operation": "update",
+          "objectName": "@happyvertical/smrt-chat:VoiceSession"
+        },
+        {
+          "kind": "cli",
+          "name": "voicesession_delete",
+          "operation": "delete",
+          "objectName": "@happyvertical/smrt-chat:VoiceSession"
+        },
+        {
+          "kind": "mcp",
+          "name": "voicesession_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-chat:VoiceSession"
+        },
+        {
+          "kind": "mcp",
+          "name": "voicesession_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-chat:VoiceSession"
+        }
       ],
-      "surfaces": [],
       "relationshipFeatures": [
+        "crossPackageRef",
+        "foreignKey",
         "uuidColumns"
       ],
       "tags": [],
@@ -1501,16 +1887,102 @@
       "name": "chatthread_get",
       "operation": "get",
       "objectName": "@happyvertical/smrt-chat:ChatThread"
+    },
+    {
+      "kind": "api",
+      "name": "voicegatewayturns.list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-chat:VoiceGatewayTurn",
+      "path": "/voicegatewayturns",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "voicegatewayturns.get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-chat:VoiceGatewayTurn",
+      "path": "/voicegatewayturns/[id]",
+      "method": "GET"
+    },
+    {
+      "kind": "mcp",
+      "name": "voicegatewayturn_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-chat:VoiceGatewayTurn"
+    },
+    {
+      "kind": "mcp",
+      "name": "voicegatewayturn_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-chat:VoiceGatewayTurn"
+    },
+    {
+      "kind": "api",
+      "name": "voicesessions.list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-chat:VoiceSession",
+      "path": "/voicesessions",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "voicesessions.get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-chat:VoiceSession",
+      "path": "/voicesessions/[id]",
+      "method": "GET"
+    },
+    {
+      "kind": "cli",
+      "name": "voicesession_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-chat:VoiceSession"
+    },
+    {
+      "kind": "cli",
+      "name": "voicesession_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-chat:VoiceSession"
+    },
+    {
+      "kind": "cli",
+      "name": "voicesession_create",
+      "operation": "create",
+      "objectName": "@happyvertical/smrt-chat:VoiceSession"
+    },
+    {
+      "kind": "cli",
+      "name": "voicesession_update",
+      "operation": "update",
+      "objectName": "@happyvertical/smrt-chat:VoiceSession"
+    },
+    {
+      "kind": "cli",
+      "name": "voicesession_delete",
+      "operation": "delete",
+      "objectName": "@happyvertical/smrt-chat:VoiceSession"
+    },
+    {
+      "kind": "mcp",
+      "name": "voicesession_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-chat:VoiceSession"
+    },
+    {
+      "kind": "mcp",
+      "name": "voicesession_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-chat:VoiceSession"
     }
   ],
   "prompts": [],
   "relationshipsV2": {
-    "foreignKeyFields": 10,
-    "crossPackageRefFields": 5,
+    "foreignKeyFields": 14,
+    "crossPackageRefFields": 8,
     "junctionCollections": 0,
     "hierarchicalObjects": 0,
     "polymorphicAssociations": 0,
-    "uuidColumns": 33
+    "uuidColumns": 46
   },
-  "agentDoc": "# @happyvertical/smrt-chat\n\nChat rooms, threads, and agent sessions with app-controlled tool whitelisting.\n\n## Models\n\nInternal models — all mutations go through the membership/owner-checked `ChatService` (S5 #1392). EVERY `@smrt()` model in this package (ChatRoom, ChatMessage, ChatParticipant, ChatThread, ChatReaction, AgentSession) has a READ-ONLY generated REST/MCP surface (`list`/`get` only); `create`/`update`/`delete` are intentionally NOT generated so the raw collection routes cannot skip the service-layer authorization. A structural regression test enumerates the registry to assert no chat model exposes a mutating op.\n\n`ChatService` is a CLOSED FACADE (S5 #1392). The raw collections (`rooms`, `messages`, `participants`, `threads`, `agentSessions`, `reactions`) are ES `#private` fields — they are NOT on the public `ChatService` type and the package index does NOT export the collection classes, so a consumer cannot do `chat.messages.create({senderProfileId, role})` / `new ChatParticipantCollection(...)` to mutate around the authorization. The security-sensitive internals (`#writeMessage`, `#emitAgentReply`, `#enrollParticipant`, `#loadActiveSession`, `#requireActiveMembership`, `#requireRoomAdmin`, `#extractToolName`) are ES `#private` too, so they are unreachable at runtime — TypeScript `private` alone is erased and would leave them callable on the prototype. The agent-reply bridge is a `Symbol`-keyed static (not the old enumerable `_runAgentReply`), reachable only by the module-local `sendAgentReply` that holds the non-exported symbol.\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` (string ref, not FK), `allowedTools` (JSON string array), `sessionContext` (JSON), `systemPrompt`, limits (`maxTokens`/`maxMessages`/`expiresAt`). Optional tenancy.\n\n## ChatService\n\nEvery public write takes an explicit server-supplied `actorProfileId` (the authenticated principal the route injects) — never a caller-controlled `senderProfileId`/`role` (S5 #1392).\n\nFacade: `sendMessage()` (authors as the actor with `role: 'user'`; room-membership-checked; no caller-supplied sender/role and no public membership-skip), `createRoom()` (acting actor becomes owner — no caller-supplied `createdByProfileId`), `startThread()` (member-checked; optional `rootMessageId` bound to the same room+tenant), `addParticipant()`/`removeParticipant()` (owner/admin-checked; self-leave allowed), `updateRoom()` (owner/admin-checked), `addReaction()`/`removeReaction()` (member-checked, self-keyed), `getOrCreateDM()` (actor must be a DM participant), `createAgentSession()` (acting actor becomes the session participant — no caller-supplied `participantProfileId`; the existing-session room lookup is tenant-bound; optional `sessionKey` scopes session identity to a conversation subject so distinct keys get distinct sessions/rooms and a session opened for one subject is never reused/rewritten for another). Tenant-bound read facade (replaces raw-collection reach-ins; consumers apply their own ownership/context checks on the returned rows): `getAgentSession({agentSessionId, tenantId})`, `findActiveAgentSessions({tenantId, agentId, participantProfileId})`, `getThread({threadId, tenantId})`, `listRoomThreads({roomId, actorProfileId, tenantId})` (membership-gated), `getThreadMessages({threadId, actorProfileId, tenantId, limit?})` (membership-gated, chronological), `getRoomMessages({roomId, actorProfileId, tenantId})`/`getRoomForMember(roomId, actorProfileId, tenantId)` (membership-checked reads gated on the server-supplied `actorProfileId`, never a caller-controlled subject id — confused-deputy avoidance; `tenantId` required), `updateAgentSessionConfig()` (owner-checked; `tenantId` mandatory and bound into the lookup). Agent session messaging is split by authority: `sendAgentUserMessage()` (caller `actorProfileId` must be the session participant; always authored as the participant). The agent-authored reply path `sendAgentReply(service, params)` is an exported **function — NOT a `ChatService` method and NOT on the package index**; it is reachable only via the dedicated `@happyvertical/smrt-chat/internal/agent-runtime` subpath (S5 #1392), so only trusted in-process agent-runtime code that explicitly opts into that subpath can author as the agent. It authors as `session.agentId`, accepts an optional same-room/tenant `threadId`, and gates tool calls fail-closed against `allowedTools`. The shared internal persistence path (`writeMessage`) is private — it alone may author an arbitrary profile/role or skip the membership check, and is unreachable from any route; it also validates every supplied `threadId`/`agentSessionId`/`replyToMessageId` belongs to the SAME room AND tenant (tenant/room-bound lookups) before use, rejecting cross-room/cross-tenant references. Auto-creates rooms/sessions/participants via an internal `enrollParticipant`.\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\n## Conversational Harness (L3, #1891)\n\nThe \"chat with your learning agent\" surface — the real agentic runtime for `AgentSession` (the only shipping chat runtime before this was a single-shot completion). This is the new **acyclic `chat → personas` / `chat → agents` / `chat → users` edge**; keep it that way (personas/agents/users never 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.\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.\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## 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- **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 is an interactive chat surface 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. `/previews` hosts the\nshared component playground entries from `src/svelte/playground.ts`.\n\nThe root workbench also has a dev-only voice conversation mode. It reads voice\ngateway connection details through `/api/dev-voice/config`, streams browser mic\naudio to `WS /ws/voice` as PCM16 mono, appends gateway transcripts/responses to\nthe chat, and plays returned TTS audio. Exposing\n`SMRT_CHAT_DEV_VOICE_GATEWAY_TOKEN` to the browser requires\n`SMRT_CHAT_DEV_VOICE_GATEWAY_EXPOSE_TOKEN=true`; keep that local-only.\n\n## Models\n\nInternal models — all mutations go through the membership/owner-checked `ChatService` (S5 #1392) or the voice adapter's binding-checked flow. EVERY `@smrt()` model in this package (ChatRoom, ChatMessage, ChatParticipant, ChatThread, ChatReaction, AgentSession, VoiceSession) has a READ-ONLY generated REST/MCP surface (`list`/`get` only); `create`/`update`/`delete` are intentionally NOT generated so the raw collection routes cannot skip the service-layer authorization. A structural regression test enumerates the registry to assert no chat model exposes a mutating op.\n\n`ChatService` is a CLOSED FACADE (S5 #1392). The raw collections (`rooms`, `messages`, `participants`, `threads`, `agentSessions`, `reactions`, `voiceSessions`) are ES `#private` fields — they are NOT on the public `ChatService` type and the package index does NOT export the collection classes, so a consumer cannot do `chat.messages.create({senderProfileId, role})` / `new ChatParticipantCollection(...)` to mutate around the authorization. The security-sensitive internals (`#writeMessage`, `#emitAgentReply`, `#enrollParticipant`, `#loadActiveSession`, `#requireActiveMembership`, `#requireRoomAdmin`, `#extractToolName`) are ES `#private` too, so they are unreachable at runtime — TypeScript `private` alone is erased and would leave them callable on the prototype. The agent-reply bridge is a `Symbol`-keyed static (not the old enumerable `_runAgentReply`), reachable only by the module-local `sendAgentReply` that holds the non-exported symbol.\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` (string ref, not FK), `allowedTools` (JSON string array), `sessionContext` (JSON), `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\nEvery public write takes an explicit server-supplied `actorProfileId` (the authenticated principal the route injects) — never a caller-controlled `senderProfileId`/`role` (S5 #1392).\n\nFacade: `sendMessage()` (authors as the actor with `role: 'user'`; room-membership-checked; no caller-supplied sender/role and no public membership-skip), `createRoom()` (acting actor becomes owner — no caller-supplied `createdByProfileId`), `startThread()` (member-checked; optional `rootMessageId` bound to the same room+tenant), `addParticipant()`/`removeParticipant()` (owner/admin-checked; self-leave allowed), `updateRoom()` (owner/admin-checked), `addReaction()`/`removeReaction()` (member-checked, self-keyed), `getOrCreateDM()` (actor must be a DM participant), `createAgentSession()` (acting actor becomes the session participant — no caller-supplied `participantProfileId`; the existing-session room lookup is tenant-bound; optional `sessionKey` scopes session identity to a conversation subject so distinct keys get distinct sessions/rooms and a session opened for one subject is never reused/rewritten for another). Tenant-bound read facade (replaces raw-collection reach-ins; consumers apply their own ownership/context checks on the returned rows): `getAgentSession({agentSessionId, tenantId})`, `findActiveAgentSessions({tenantId, agentId, participantProfileId})`, `getThread({threadId, tenantId})`, `listRoomThreads({roomId, actorProfileId, tenantId})` (membership-gated), `getThreadMessages({threadId, actorProfileId, tenantId, limit?})` (membership-gated, chronological), `getRoomMessages({roomId, actorProfileId, tenantId})`/`getRoomForMember(roomId, actorProfileId, tenantId)` (membership-checked reads gated on the server-supplied `actorProfileId`, never a caller-controlled subject id — confused-deputy avoidance; `tenantId` required), `updateAgentSessionConfig()` (owner-checked; `tenantId` mandatory and bound into the lookup). Agent session messaging is split by authority: `sendAgentUserMessage()` (caller `actorProfileId` must be the session participant; always authored as the participant). The agent-authored reply path `sendAgentReply(service, params)` is an exported **function — NOT a `ChatService` method and NOT on the package index**; it is reachable only via the dedicated `@happyvertical/smrt-chat/internal/agent-runtime` subpath (S5 #1392), so only trusted in-process agent-runtime code that explicitly opts into that subpath can author as the agent. It authors as `session.agentId`, accepts an optional same-room/tenant `threadId`, and gates tool calls fail-closed against `allowedTools`. The shared internal persistence path (`writeMessage`) is private — it alone may author an arbitrary profile/role or skip the membership check, and is unreachable from any route; it also validates every supplied `threadId`/`agentSessionId`/`replyToMessageId` belongs to the SAME room AND tenant (tenant/room-bound lookups) before use, rejecting cross-room/cross-tenant references. Auto-creates rooms/sessions/participants via an internal `enrollParticipant`.\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\n## Conversational Harness (L3, #1891)\n\nThe \"chat with your learning agent\" surface — the real agentic runtime for `AgentSession` (the only shipping chat runtime before this was a single-shot completion). This is the new **acyclic `chat → personas` / `chat → agents` / `chat → users` edge**; keep it that way (personas/agents/users never 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.\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.\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## 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- **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"
 }