@happyvertical/smrt-chat

Chat rooms, DMs, threads, and agent conversations for the s-m-r-t framework. Supports public, private, DM, and agent-type rooms with threaded messages, reactions, and agent sessions with tool whitelisting.

Installation

pnpm add @happyvertical/smrt-chat

Data-surface bridge security

The ./data-surface-bridge entry point is the server half of the browser data- surface protocol. Supply a transport adapter whose subscribe callback provides peer metadata derived from authenticated connection state (such as a bound WebSocket session or origin-checked postMessage peer). Never copy sessionId or source from an untrusted message into that metadata, and route send only to the authenticated peer.

The bridge validates and bounds every command, acknowledgement, and event before it crosses the server boundary, using the shared identifier limit from @happyvertical/smrt-ui/data-surface. authorize remains the application’s responsibility and must fail closed. Commands are scoped to the configured session/source, expire by TTL, and are idempotent by command ID plus command signature; replay retention is bounded and capacity exhaustion returns an explicit replay_capacity_exceeded outcome. Invalid, stale, disconnected, or transport-failed work resolves with a protocol failure reason rather than trusting browser data or throwing raw transport errors.

Usage

Local dev server

Run the chat package workbench directly:

pnpm --dir packages/chat dev

The root route opens an interactive chat surface backed by src/routes/api/dev-chat/+server.ts. If SMRT_CHAT_DEV_PROVIDER / SMRT_CHAT_DEV_API_KEY or standard provider credentials such as OPENAI_API_KEY, ANTHROPIC_API_KEY, or GEMINI_API_KEY are available, the assistant turn goes through @happyvertical/ai; otherwise it uses a deterministic local fallback. Component previews are available at /previews.

The workbench also has a local-only voice conversation mode. It reads SMRT_CHAT_DEV_VOICE_GATEWAY_HTTP_URL and SMRT_CHAT_DEV_VOICE_GATEWAY_WS_URL, fetches gateway targets from /api/dev-voice/config, streams browser microphone audio to WS /ws/voice as PCM16 mono at 16 kHz, appends gateway transcripts/responses to the chat, and plays returned TTS audio. If the gateway requires a bearer token, set SMRT_CHAT_DEV_VOICE_GATEWAY_TOKEN; browser WebSocket testing also requires SMRT_CHAT_DEV_VOICE_GATEWAY_EXPOSE_TOKEN=true, so use this only for local dev.

Rooms and messages

import { ChatService } from '@happyvertical/smrt-chat';

const chat = await ChatService.create({
  db: { type: 'sqlite', 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

// 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
}

Voice gateway turns

smrt-chat can expose a gateway-facing turn target for browser voice input. The browser receives only a short-lived s-m-r-t voice session binding; the gateway-to-s-m-r-t service bearer token stays server-side.

import {
  createVoiceChatSession,
  createVoiceGatewayTurnHandler,
} from '@happyvertical/smrt-chat';

// Authenticated app route: bind the speaking profile to a persona and an
// existing or newly-created agent session.
const voice = await createVoiceChatSession({
  chatService: chat,
  db,
  tenantId: locals.tenantId,
  actorProfileId: locals.profileId,
  actorUserId: locals.userId,
  persona: resolvedPersona,
  agentSessionId: session.id, // omit to create/reuse an agent session
  ttlSeconds: 600,
});

// Return voice.gatewaySessionId + voice.metadata to the browser/gateway. Do not
// return the gateway service token.

// Gateway target route: configure the deployed voice gateway HTTP target to
// POST here with Authorization: Bearer <SMRT_VOICE_GATEWAY_TOKEN>.
export const POST = ({ request }) =>
  createVoiceGatewayTurnHandler({
    chatService: chat,
    db,
    ai,
    gatewayToken: process.env.SMRT_VOICE_GATEWAY_TOKEN ?? '',
  })(request);

The gateway sends the transcribed text turn:

{
  "session_id": "gateway-or-smrt-stable-session-id",
  "turn_id": "gateway-generated-turn-id",
  "target": "smrt:chat",
  "actor": "optional-display-name",
  "text": "transcribed user utterance",
  "metadata": {
    "tenantId": "tenant uuid",
    "actorProfileId": "profile id",
    "chatRoomId": "room id",
    "threadId": "optional thread id",
    "agentSessionId": "agent session id",
    "personaId": "persona id",
    "voiceSessionId": "SMRT-issued voice session id",
    "source": "voice-gateway"
  }
}

s-m-r-t validates metadata.voiceSessionId against its server-side binding, then checks any supplied tenant/profile/persona/session/thread ids against that binding instead of trusting the gateway metadata. A valid turn is persisted as a normal user chat message, routed through runPersonaConversationTurn(), and the assistant reply is persisted as a normal assistant message. The response is:

{
  "session_id": "same session_id",
  "turn_id": "same turn_id",
  "text": "assistant response text",
  "metadata": {
    "tenantId": "tenant id",
    "chatRoomId": "room id",
    "threadId": null,
    "agentSessionId": "agent session id",
    "userMessageId": "persisted transcript message id",
    "assistantMessageId": "persisted assistant message id",
    "personaId": "persona id",
    "correlationId": "feedback correlation id",
    "voiceSessionId": "SMRT-issued voice session id",
    "source": "voice-gateway"
  }
}

Direct messages

// 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) | | VoiceSession | Short-lived voice gateway binding over a tenant, actor profile, persona, and agent session |

Internal collections

Raw collection classes are not exported from the package index. They are listed here as implementation details; application code should use ChatService and the voice helpers.

| Internal class | 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() | | VoiceSessionCollection | Voice session binding queries and stale-expiry helper |

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). | | createVoiceChatSession() | Creates a short-lived voice binding for an authenticated actor and persona, optionally against an existing agent session | | handleVoiceGatewayTurn() | Lower-level gateway turn adapter for non-Fetch hosts | | createVoiceGatewayTurnHandler() | Fetch-compatible HTTP handler for the gateway target endpoint |

Types

ChatRoomType, ChatRoomStatus, ChatRoomOptions, ChatMessageType, ChatMessageRole, ChatMessageOptions, ChatMessageSearchFilters, ChatParticipantRole, ChatParticipantStatus, ChatParticipantOptions, OnlineStatus, ChatThreadOptions, ChatReactionOptions, AgentSessionStatus, AgentSessionOptions, VoiceSessionStatus, VoiceSessionOptions, VoiceGatewayTurnPayload, VoiceGatewayTurnResponse

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

Contributor guide

See AGENTS.md for package architecture, invariants, validation, and contributor guidance.