@happyvertical/smrt-chat 0.30.0

package/AGENTS.md

@@ -0,0 +1,35 @@
+# @happyvertical/smrt-chat
+
+Chat rooms, threads, and agent sessions with app-controlled tool whitelisting.
+
+## Models
+
+Internal 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.
+
+`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.
+
+- **ChatRoom**: `roomType` (public/private/dm/agent), `status`, `topic`, `maxParticipants`, `lastMessageAt`. Tenant-scoped (required).
+- **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).
+- **ChatParticipant**: `role` (owner/admin/member/viewer), `onlineStatus`, `lastReadMessageId`, `isMuted`. Tenant-scoped (required).
+- **ChatThread**: `rootMessageId`, `isResolved`, `messageCount`. Created via `ChatService.startThread()` (member-checked). Tenant-scoped (required).
+- **ChatReaction**: `messageId`, `profileId`, `emoji`. Added/removed via `ChatService.addReaction()`/`removeReaction()` (member-checked, self-keyed). Tenant-scoped (required).
+- **AgentSession**: `agentId` (string ref, not FK), `allowedTools` (JSON string array), `sessionContext` (JSON), `systemPrompt`, limits (`maxTokens`/`maxMessages`/`expiresAt`). Optional tenancy.
+
+## ChatService
+
+Every public write takes an explicit server-supplied `actorProfileId` (the authenticated principal the route injects) — never a caller-controlled `senderProfileId`/`role` (S5 #1392).
+
+Facade: `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`.
+
+## Agent Tool Whitelisting
+
+`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.
+
+## Gotchas
+
+- **sessionContext, not context**: `context` is reserved for slug scoping. Use `getSessionContext()`/`updateSessionContext()` for agent memory.
+- **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.
+- **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.
+- **Session expiry**: check `isActive()` before allowing messages (expiresAt or limit-based)
+- **DM identity**: derived from the deterministic per-tenant `canonicalDmRoomId()` and the authoritative `chat_participants` join, not client metadata; concurrent creates upsert onto one row.
+- **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.

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,163 @@
+# @happyvertical/smrt-chat
+
+Chat rooms, DMs, threads, and agent conversations for the SMRT framework. Supports public, private, DM, and agent-type rooms with threaded messages, reactions, and agent sessions with tool whitelisting.
+
+## Installation
+
+```bash
+pnpm add @happyvertical/smrt-chat
+```
+
+## Usage
+
+### Rooms and messages
+
+```typescript
+import { ChatService } from '@happyvertical/smrt-chat';
+
+const chat = await ChatService.create({
+  persistence: { type: 'sql', url: 'chat.db' },
+});
+
+// `actorProfileId` is the authenticated principal the route injects. Every
+// write takes it explicitly; the caller never supplies a `senderProfileId`,
+// `role`, or `createdByProfileId` (S5 #1392).
+
+// Create a public room (the acting actor becomes the owner)
+const room = await chat.createRoom({
+  tenantId: 'tenant-1',
+  name: 'General',
+  roomType: 'public',
+  actorProfileId: 'profile-1',
+});
+
+// Send a message (always authored as the actor with role 'user')
+const message = await chat.sendMessage({
+  tenantId: 'tenant-1',
+  roomId: room.id,
+  actorProfileId: 'profile-1',
+  content: 'Hello, world!',
+});
+
+// Start a threaded conversation from a message (member-checked)
+const thread = await chat.startThread({
+  tenantId: 'tenant-1',
+  roomId: room.id,
+  actorProfileId: 'profile-1',
+  rootMessageId: message.id,
+  title: 'Follow-up discussion',
+});
+
+// Reply within the thread. The thread (and any reply-to message) must belong
+// to the same room and tenant, or the write is rejected.
+await chat.sendMessage({
+  tenantId: 'tenant-1',
+  roomId: room.id,
+  actorProfileId: 'profile-2',
+  content: 'Great point!',
+  threadId: thread.id,
+});
+```
+
+### Agent sessions with tool whitelisting
+
+```typescript
+// Create an agent session (auto-creates an agent-type room). The acting actor
+// becomes the owning participant; the caller cannot open a session for someone
+// else by supplying a participant id.
+const { session, room } = await chat.createAgentSession({
+  tenantId: 'tenant-1',
+  agentId: 'agent-summarizer',
+  actorProfileId: 'profile-1',
+  allowedTools: ['web-search', 'summarize'],
+  systemPrompt: 'You are a research assistant.',
+  maxMessages: 100,
+});
+
+// Send a USER message within the agent session. The caller must be the
+// session participant; the message is always authored as that participant.
+await chat.sendAgentUserMessage({
+  tenantId: 'tenant-1',
+  agentSessionId: session.id,
+  actorProfileId: 'profile-1',
+  content: 'Summarize the latest news',
+});
+
+// Emit the agent's reply. This is the INTERNAL trusted authority that authors
+// a message AS the agent, so it is intentionally NOT a public ChatService
+// method and NOT on the package index. It is reachable only via the dedicated
+// `./internal/agent-runtime` subpath, which a normal route/consumer importing
+// from '@happyvertical/smrt-chat' cannot reach. Opting into this subpath
+// signals the importer IS the trusted in-process agent runtime. Tool calls are
+// gated fail-closed against the session's allowedTools.
+import { sendAgentReply } from '@happyvertical/smrt-chat/internal/agent-runtime';
+await sendAgentReply(chat, {
+  tenantId: 'tenant-1',
+  agentSessionId: session.id,
+  content: 'Here is the summary...',
+  kind: 'assistant',
+});
+
+// Check session limits before allowing more messages
+if (session.isActive()) {
+  // Session has not expired or hit token/message limits
+}
+```
+
+### Direct messages
+
+```typescript
+// Get or create a DM room between two profiles. The acting actor must be one
+// of the two DM participants.
+const dmRoom = await chat.getOrCreateDM({
+  tenantId: 'tenant-1',
+  actorProfileId: 'profile-1',
+  profileId1: 'profile-1',
+  profileId2: 'profile-2',
+});
+```
+
+## API
+
+### Models
+
+| Export | Description |
+|--------|------------|
+| `ChatRoom` | Room with type (`public`/`private`/`dm`/`agent`), status, topic, and metadata |
+| `ChatMessage` | Message with `role` (user/assistant/system/tool), `messageType` (text/system/action/file/tool_call/tool_result), optional thread and reply references |
+| `ChatParticipant` | Room member with `role` (owner/admin/member/viewer), online status, read tracking |
+| `ChatThread` | Threaded conversation linked to a root message, with resolve/reopen lifecycle |
+| `ChatReaction` | Emoji reaction on a message |
+| `AgentSession` | AI agent session with `allowedTools` (JSON string array), `sessionContext` for multi-turn memory, `systemPrompt`, and usage limits (`maxTokens`/`maxMessages`/`expiresAt`) |
+
+### Collections
+
+| Export | Description |
+|--------|------------|
+| `ChatRoomCollection` | Room queries, `findOrCreateDM()` |
+| `ChatMessageCollection` | Message queries and search filters |
+| `ChatParticipantCollection` | Participant queries, `findMembership()` |
+| `ChatThreadCollection` | Thread queries |
+| `ChatReactionCollection` | Reaction queries |
+| `AgentSessionCollection` | Session queries, `findActiveSession()`, `findOrCreate()` |
+
+### Services
+
+| Export | Description |
+|--------|------------|
+| `ChatService` | Facade: `createRoom()`, `sendMessage()`, `startThread()`, `addParticipant()`, `removeParticipant()`, `updateRoom()`, `addReaction()`, `removeReaction()`, `getOrCreateDM()`, `createAgentSession()`, `sendAgentUserMessage()`, `getRoomMessages()`, `getRoomForMember()`, `updateAgentSessionConfig()`. Every write takes a server-supplied `actorProfileId`. The agent-authored reply path (`sendAgentReply`) is intentionally NOT on this facade or the package index — it is an internal function in `services/ChatService.ts` for the trusted in-process agent runtime only (S5 #1392). |
+
+### Types
+
+`ChatRoomType`, `ChatRoomStatus`, `ChatRoomOptions`, `ChatMessageType`, `ChatMessageRole`, `ChatMessageOptions`, `ChatMessageSearchFilters`, `ChatParticipantRole`, `ChatParticipantStatus`, `ChatParticipantOptions`, `OnlineStatus`, `ChatThreadOptions`, `ChatReactionOptions`, `AgentSessionStatus`, `AgentSessionOptions`
+
+### Constants
+
+`CHAT_MODULE_META`, `CHAT_UI_SLOTS`
+
+## Dependencies
+
+- `@happyvertical/smrt-core` -- ORM and code generation
+- `@happyvertical/smrt-tenancy` -- multi-tenant scoping
+- `@happyvertical/smrt-types` -- shared type definitions
+- Peer (optional): `@happyvertical/smrt-agents`, `@happyvertical/smrt-profiles`, `@happyvertical/smrt-svelte`

package/dist/__smrt-register__.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=__smrt-register__.d.ts.map

package/dist/__smrt-register__.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"__smrt-register__.d.ts","sourceRoot":"","sources":["../src/__smrt-register__.ts"],"names":[],"mappings":""}