@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
Assistant turn drivers
The assistant uses its existing model/tool loop by default. Supply an ai
client or per-request factory for a model adapter, or a turnDriver for an
external agent that owns its loop:
import { mountAssistantRoutes } from '@happyvertical/smrt-chat/sveltekit';
export const { GET, POST } = mountAssistantRoutes({
turnDriver: {
async run(context, progress) {
// A host adapter forwards the agent's callbacks and AbortSignal.
context.signal.throwIfAborted();
progress.text('Hello from your agent.');
progress.done({ text: 'Hello from your agent.' });
},
},
allowedTools: [],
});
resolveTurnDriver(ctx) selects a driver per authenticated request/user.
Chat keeps thread/message persistence, tool allow-lists, the dock's streaming
format and stop behavior. Drivers receive history, the new user message,
system guidance, thread identity, principal, offered server tools and an abort
signal. Await tool-call/result callbacks to author their transcript. The
approvalNeeded callback and waitForApproval host hook reserve the durable
owner-approval integration; without a hook approval is denied. Durable approval
storage and UI are not implemented by this seam.
See turn-driver contracts and callback example, including MCP authorization responsibilities, engine status, and browser continuation limits.
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
Team Chat recipe
ChatRoomsRecipe declares the chat.rooms unit for app navigation and
generated read-only room, message, membership, thread, and reaction views.
It places the Chat Rooms entry in the Team section under the Team collaboration
card, using the shell's users icon.
Hosts can mount its exported ChatLayout at /chat/rooms; the recipe also
points demo hosts at the browser-safe static chat fixture from ./playground.
Its user help describes how to find rooms and
follow conversations. The package playground previews use static mock fixtures;
they do not connect to a live chat service.
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
}
Commerce money assistant tools
An authenticated AssistantDock host can register the draft-invoice tools through
the same extraTools seam. Include only the tools the persona may use in its
server-controlled allowedTools; the tools repeat both the allow-list and
operation checks when invoked.
import { createCommerceMoneyTools } from '@happyvertical/smrt-commerce';
import { mountAssistantRoutes } from '@happyvertical/smrt-chat/sveltekit';
const routes = mountAssistantRoutes({
// The authenticated host resolves allowedTools for each principal.
extraTools: () => createCommerceMoneyTools(),
allowedTools: () => [
'commerce.taxCodes.list',
'commerce.invoice.preview',
'commerce.invoice.line.add',
'commerce.invoice.line.update',
],
// ...the host's principal, database, and AI bindings
});
These tools select tax codes by code and use the commerce calculator and document-money coordinator. They do not expose raw amount, tax amount, or numeric tax-rate writes.
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',
});
Assistant dock and supervised runs
AssistantDock / createAssistantDockController (@happyvertical/smrt-chat/svelte)
is an in-page assistant over a host transport; runAssistantTurn is its
server engine (model tools, browser tools that suspend and resume, budgets
maxSteps / maxTurnTokens / maxTurnMs). For "watch it work" hosts the
controller keeps a supervised run (goal, current step, running | paused | waiting | done | failed | cancelled), with pauseRun / continueRun,
holdForUser for choices the person makes, a clientToolFilter, and a
settle hook so the step after a navigation sees the new page's tools.
threadList={false} omits the Conversations list for a single-conversation dock
(the host then opens a thread via oncontroller). matchesToolAllowList is exported browser-safe. Full guide:
docs/assistant-dock.md.
Pass conversations="single" to AssistantDock for an app where people should not see separate conversations: it reuses the newest thread (or creates one), opens the focused composer, and offers an icon-only clear action.
The server side mounts in one route file. The principal comes from
event.locals (@happyvertical/smrt-users/sveltekit); threads are scoped to
the caller's own assistant session in the active tenant; tools are
fail-closed (allowedTools, absent means none) and, without tools, are the
manifest operations allowedTools names. ai defaults to the smrt.config
ai block. Pass the application runtime: each request then uses its own
database (runtime.databaseConfig()), and under database-rls a streamed
turn, which outlives the request's transaction, runs in a transaction of its
own for the same principal (runtime.runAsPrincipal):
// src/routes/api/assistant/[...path]/+server.ts
import { mountAssistantRoutes } from '@happyvertical/smrt-chat/sveltekit';
import { runtime } from '$lib/server/smrt';
export const { GET, POST } = mountAssistantRoutes({
allowedTools: ['notes.read', 'notes.create'],
runtime,
});
In the page, createAssistantHttpTransport({ endpoint: '/api/assistant' })
is the dock's transport, and createAssistantHttpActionClient its
actionClient when the route is given actions: { adapter }.
Recipes
AssistantRecipe (chat.assistant) declares the assistant dock for app and
agent catalogs: a shell widget in header.end that mounts AssistantDock
from @happyvertical/smrt-chat/svelte, an llm provider (hosted keys
OPENAI_API_KEY, ANTHROPIC_API_KEY or GEMINI_API_KEY, or a browser model
with no key), and user-facing help. See agents/recipes.md.
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.
Durable approvals for server tools
mountAssistantRoutes holds destructive server calls by default (delete/remove/
destroy/purge/drop/truncate, including extra tools). A built-in turn persists a
pending approval in its thread, streams approval_needed, and ends with
stoppedReason: 'approval'. It makes no further model call. Approve executes the
saved tool with its original principal and arguments after live permission and
offering checks, then authors the result. Deny authors a refusal. Model-supplied
approved values have no effect on this gate.
The default authority uses app-runtime's SQLite envelope adapter over the existing
smrt-approvals ledger; include its models in normal database migrations. Supply
approvals for another store/host authority. approvalPolicy.tools and
approvalPolicy.operations explicitly override the default per tool or canonical
operation; e.g. { tools: { 'invoices.update': true } } also holds updates.
Direct runAssistantTurn callers supply createAssistantApprovalBridge; a
protected call without one fails closed. This does not change low-level
runToolLoop or persona conversation policy, which remain host integration APIs.
Owner-only routes: GET approvals (tenant-wide pending summaries), GET threads/:threadId/approvals and
POST approvals/:id/decide with { approve: boolean }, under the same mount.
Thread reads keep their ownership checks; owner decision uses the saved requester's thread binding and cannot read arbitrary thread history. Tenant and mutation-origin checks match the
other routes. They return only the public approval projection. The default owner
check requires the active user's active direct membership in the canonical system
owner role. A second decision is 409. A failed consumed effect cannot be replayed.
createAssistantHttpTransport supplies the approval methods; AssistantDock
automatically renders AssistantApprovalCard for persisted holds, with translated,
keyboard-accessible Approve/Deny controls and persisted outcomes. External drivers
use their existing approvalNeeded callback: chat creates the canonical request,
persists/streams it, and waits for the same authority before returning approval.
Drivers must honor denial and execute through the original principal's live,
permission-bound host/MCP adapter. See approval details.
Runtime cookbook gating is opt-in through smrt-core runtime exposure. Generated manifest operations keep their AOT declarations, but live offerings and calls must also pass the current tenant's cookbook and host preference gate.
Saved manifest calls recheck runtime exposure when approved. A disabled or unreadable model gate records a terminal refused result without running the tool; approval lists retain only the original public hold summary.