@happyvertical/smrt-chat

中文文档
0.62.1发布于 2026/11/17MITTypeScriptES Module近 30 天下载 1.8万

Chat rooms, DMs, threads, and agent conversations for the SMRT framework

原始使用文档
文档目录22 节
  1. Installation
  2. Assistant turn drivers
  3. Data-surface bridge security
  4. Usage
  5. Team Chat recipe
  6. Local dev server
  7. Rooms and messages
  8. Agent sessions with tool whitelisting
  9. Commerce money assistant tools
  10. Voice gateway turns
  11. Direct messages
  12. Assistant dock and supervised runs
  13. Recipes
  14. API
  15. Models
  16. Internal collections
  17. Services
  18. Types
  19. Constants
  20. Dependencies
  21. Contributor guide
  22. Durable approvals for server tools

@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

ExportDescription
ChatRoomRoom with type (public/private/dm/agent), status, topic, and metadata
ChatMessageMessage with role (user/assistant/system/tool), messageType (text/system/action/file/tool_call/tool_result), optional thread and reply references
ChatParticipantRoom member with role (owner/admin/member/viewer), online status, read tracking
ChatThreadThreaded conversation linked to a root message, with resolve/reopen lifecycle
ChatReactionEmoji reaction on a message
AgentSessionAI agent session with allowedTools (JSON string array), sessionContext for multi-turn memory, systemPrompt, and usage limits (maxTokens/maxMessages/expiresAt)
VoiceSessionShort-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 classDescription
ChatRoomCollectionRoom queries, findOrCreateDM()
ChatMessageCollectionMessage queries and search filters
ChatParticipantCollectionParticipant queries, findMembership()
ChatThreadCollectionThread queries
ChatReactionCollectionReaction queries
AgentSessionCollectionSession queries, findActiveSession(), findOrCreate()
VoiceSessionCollectionVoice session binding queries and stale-expiry helper

Services

ExportDescription
ChatServiceFacade: 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.

版本与发布记录

@happyvertical/smrt-chat 共发布 366 个版本,首次发布于 2026/06/23;过去 12 个月发布了 366 个版本。

版本发布日期距今
0.62.1latest2026/11/17今天
0.62.02026/11/17今天
0.61.62026/11/161 天前
0.61.52026/11/161 天前
0.61.42026/11/161 天前
0.61.32026/11/152 天前

关于 @happyvertical/smrt-chat 的常见问题

@happyvertical/smrt-chat 是什么?

Chat rooms, DMs, threads, and agent conversations for the SMRT framework

如何安装 @happyvertical/smrt-chat?

在项目目录运行 npm install @happyvertical/smrt-chat,或使用 pnpm add / yarn add / bun add。

@happyvertical/smrt-chat 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@happyvertical/smrt-chat 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@happyvertical/smrt-chat 可以商用吗?

@happyvertical/smrt-chat 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@happyvertical/smrt-chat 的下载量有多少?

根据 npm 官方下载统计,@happyvertical/smrt-chat 在 2026/10/17 – 2026/11/15 这 30 天内被下载 18,134 次,日均约 604 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@happyvertical/smrt-chat 还在维护吗?

最新版本 0.62.1 发布于 2026/11/17(今天);至今共发布 366 个版本,其中过去 12 个月发布了 366 个;首次发布于 2026/06/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。