@things-factory/ai-assistant 10.1.6 → 10.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/ai-assistant",
-  "version": "10.1.6",
+  "version": "10.1.7",
   "main": "dist-server/index.js",
   "things-factory": true,
   "author": "heartyoh",
@@ -29,10 +29,10 @@
     "@operato/graphql": "^10.0.0",
     "@operato/i18n": "^10.0.0",
     "@operato/styles": "^10.0.0",
-    "@things-factory/ai-client-base": "^10.1.6",
-    "@things-factory/auth-base": "^10.1.6",
+    "@things-factory/ai-client-base": "^10.1.7",
+    "@things-factory/auth-base": "^10.1.7",
     "@things-factory/env": "^10.1.3",
-    "@things-factory/shell": "^10.1.4",
+    "@things-factory/shell": "^10.1.7",
     "dompurify": "^3.0.0",
     "graphql-scalars": "^1.22.0",
     "graphql-tag": "^2.12.6",
@@ -44,5 +44,5 @@
     "copyfiles": "^2.4.1",
     "rimraf": "^5.0.0"
   },
-  "gitHead": "963aeb9ac470be5aea05bb5842a0a92afcab6036"
+  "gitHead": "9a036f83f5751f9e4af9180e9a0018f716a4ba27"
 }

package/server/service/assistant-chat-resolver.ts

@@ -0,0 +1,326 @@
+/*
+ * The neutral door into a conversation.
+ *
+ * ── Why this exists (2026-09-11) ───────────────────────────────────────────────
+ * The chat component moved here from `board-ai`, but the only mutation it could call stayed
+ * behind. operato-figure mounted the dock, registered four tools, and got
+ * `Cannot query field "boardAIChat" on type "Mutation"` — it does not load board-ai. The twin has
+ * the same shape and it does not show: its space deliberation runs through board-ai's door purely
+ * because the board authoring half of the same product already loaded that package.
+ *
+ * ── Why the board resolver was not moved ───────────────────────────────────────
+ * `board-ai-resolver.ts` is 692 lines and the larger part of it is board authoring itself:
+ * `currentBoard` as a BoardModel, PatchEntry, board patch broadcasts, refid injection for
+ * component mentions. Moving that here would teach this package the board document, which is the
+ * dependency we just cut, pointing the other way.
+ *
+ * So the door moved and the editor did not. `boardAIChat` stays in board-ai for board authoring;
+ * this one is for a surface that asks questions and runs registered tools.
+ *
+ * ── What this is not ───────────────────────────────────────────────────────────
+ * It has no document, so it takes no document and returns no patch. Tools that write to a
+ * document are not offered here — `registryAssistantChat` enforces that, and it decides what may
+ * be dispatched from the same list it offers, so the two cannot drift apart.
+ */
+import { Arg, Ctx, Directive, Field, InputType, Mutation, ObjectType, Resolver } from 'type-graphql'
+import { GraphQLJSON } from 'graphql-scalars'
+import '@things-factory/auth-base'
+
+import { config } from '@things-factory/env'
+import { getRepository } from '@things-factory/shell'
+import { createAIClient, getDefaultAIClient, registryAssistantChat, type AIClient } from '@things-factory/ai-client-base'
+
+import { ChatSession } from './chat-session/chat-session.js'
+import { ChatMessage } from './chat-message/chat-message.js'
+import { buildLlmHistory } from './chat-message/llm-history.js'
+import { publishChatMessage } from './chat-message/chat-message-publish.js'
+import { publishSessionActivity } from './chat-session/session-activity-publish.js'
+import { activityPatch, autoSessionName } from './chat-session/session-inbox.js'
+
+/**
+ * How many stored messages reach the model.
+ *
+ * A deliberation runs for days. Without a cap the prompt grows without bound and the oldest turns
+ * bury the recent ones. Kept the same as the board conversation's cap so the two surfaces of one
+ * product do not remember differently.
+ */
+const LLM_HISTORY_MAX_TURNS = 40
+
+@InputType()
+class AssistantMessageInput {
+  @Field({ description: "Role: 'user' or 'assistant'" })
+  role: string
+
+  @Field({ description: 'Message content' })
+  content: string
+}
+
+@InputType({ description: 'One turn of a conversation that has no document of its own.' })
+class AssistantChatInput {
+  @Field({
+    nullable: true,
+    description: 'ChatSession id. Omit for a one-off question with no persistence.'
+  })
+  sessionId?: string
+
+  @Field(() => [AssistantMessageInput], {
+    description:
+      'Conversation, newest last. For a persisted session only the last user message is appended; the rest is read from storage.'
+  })
+  messages: AssistantMessageInput[]
+
+  @Field({
+    description:
+      'Who the assistant is on this surface, in the words of the product that owns the screen. The rules for using each tool come from whoever registered it and are appended by the server.'
+  })
+  systemPrompt: string
+
+  @Field(() => [String], {
+    nullable: true,
+    description:
+      'Registered tool categories this conversation may use (registerToolCategory names, e.g. ["figure-authoring"]). Omit to allow every registered category. An empty list allows none — a plain conversation.'
+  })
+  toolCategories?: string[]
+
+  @Field(() => GraphQLJSON, {
+    nullable: true,
+    description:
+      'What this surface is looking at (e.g. { figureId } while modelling). Tools read it so the model never has to ask the user for identifiers. Client-supplied — never used for authorization; a tool verifies the scope belongs to the caller tenant.'
+  })
+  hostContext?: any
+
+  @Field({
+    nullable: true,
+    description:
+      'Last message to keep from the stored history. The client keeps its own truncation when a user edits a message, so pass the last kept id to hide the retracted span from the model.'
+  })
+  truncateAfterMessageId?: string
+
+  @Field({
+    nullable: true,
+    description:
+      'Require a tool call before the model may answer. For surfaces that report live state, where an unchecked assertion reads the same as a checked one.'
+  })
+  requireGroundingTools?: boolean
+
+  @Field({ nullable: true, description: 'Model identifier override. Falls back to the configured default.' })
+  model?: string
+
+  @Field({ nullable: true, description: 'Sampling temperature override.' })
+  temperature?: number
+
+  @Field({ nullable: true, description: 'Max output tokens per call.' })
+  maxTokens?: number
+}
+
+@ObjectType()
+class AssistantChatOutput {
+  @Field({ description: 'The reply, including the notice when the loop stopped early.' })
+  reply: string
+
+  @Field({ description: 'AI client identifier (provider:model).' })
+  clientId: string
+
+  @Field({ nullable: true, description: 'Echo of the session id, when persisted.' })
+  sessionId?: string
+
+  @Field({ nullable: true, description: 'Stored ChatMessage id of the user input.' })
+  userMessageId?: string
+
+  @Field({ nullable: true, description: 'Stored ChatMessage id of the reply.' })
+  assistantMessageId?: string
+
+  @Field(() => GraphQLJSON, {
+    nullable: true,
+    description: 'Tool usages during the turn — {name, arguments, result, kind}. The surface shows them foldably.'
+  })
+  toolUsages?: any
+
+  @Field(() => [String], {
+    nullable: true,
+    description:
+      'Tool names offered to the model this turn. A surface that expected a category and sees it missing here knows the registration did not happen, rather than reading a vague answer as a refusal.'
+  })
+  offeredTools?: string[]
+
+  @Field(() => GraphQLJSON, {
+    nullable: true,
+    description:
+      'Actions a tool recorded without executing — each carries what the tool returned alongside `proposed: true`. The surface renders a confirm button; executing is the user\'s act.'
+  })
+  proposals?: any
+
+  @Field(() => GraphQLJSON, {
+    nullable: true,
+    description:
+      'Identifiers in the reply that appear in nothing the model received. Hallucination candidates surfaced to the user; the reply itself is not altered. Null when the answer is grounded.'
+  })
+  groundingWarnings?: any
+}
+
+function resolveAIClient(): AIClient | undefined {
+  const existing = getDefaultAIClient()
+  if (existing) return existing
+  const cfg = config.get('aiClient', null) as any
+  if (cfg && cfg.provider) return createAIClient(cfg)
+  return undefined
+}
+
+@Resolver()
+export class AssistantChatResolver {
+  /*
+   * No `@transaction`, for the same reason the board conversation has none: a model call takes
+   * seconds to tens of seconds, and holding a write lock for that long collides with everything
+   * else on SQLite. Writes are short and around the call. For a conversation, a partly stored
+   * history is safer than a lost one.
+   */
+  @Mutation(() => AssistantChatOutput, {
+    description:
+      'Ask the assistant a question on a surface that has no document of its own. Tools come from the registry; with a sessionId the conversation is persisted.'
+  })
+  /*
+   * `ai-assistant:mutation` — the same door as the board conversation's, which moved here on
+   * 2026-09-10. No `legacy` alias: this operation is new, so no one was ever passing under an old
+   * name, and declaring an alias would open a second name that nothing needs.
+   */
+  @Directive('@privilege(category: "ai-assistant", privilege: "mutation")')
+  async assistantChat(@Arg('input') input: AssistantChatInput, @Ctx() context: any): Promise<AssistantChatOutput> {
+    const client = resolveAIClient()
+    if (!client) {
+      throw new Error(
+        'No AI client configured. Set config.aiClient = { provider, model, apiKey } or call setDefaultAIClient(...).'
+      )
+    }
+
+    const { domain, user } = context.state
+    const sessionRepo = getRepository(ChatSession)
+    const messageRepo = getRepository(ChatMessage)
+
+    let session: ChatSession | undefined
+    if (input.sessionId) {
+      const found = await sessionRepo.findOneBy({ id: input.sessionId, domain: { id: domain.id } as any })
+      if (!found) throw new Error(`ChatSession ${input.sessionId} not found`)
+      session = found
+    }
+
+    const lastUserMessage = input.messages[input.messages.length - 1]
+    let userMessageId: string | undefined
+
+    if (session && lastUserMessage?.role === 'user') {
+      const previousLast = await messageRepo.findOne({
+        where: { session: { id: session.id } as any },
+        order: { createdAt: 'DESC' }
+      })
+      const saved = await messageRepo.save({
+        session: { id: session.id } as any,
+        role: 'user',
+        content: lastUserMessage.content,
+        creator: user,
+        updater: user,
+        parentMessage: previousLast ? ({ id: previousLast.id } as any) : undefined
+      })
+      userMessageId = saved.id
+
+      /*
+       * Session activity is denormalised for the list: most-recent ordering and another
+       * participant's unread badge read it. Best effort — a conversation must not fail because a
+       * list sorts one position late.
+       */
+      try {
+        const patch: any = activityPatch(lastUserMessage.content)
+        if (!session.name) patch.name = autoSessionName(lastUserMessage.content)
+        await sessionRepo.update(session.id!, patch)
+      } catch {
+        /* noop */
+      }
+
+      publishChatMessage({ domainId: domain.id, sessionId: session.id, message: saved } as any)
+      publishSessionActivity({
+        domainId: domain.id,
+        sessionId: session.id!,
+        kind: 'message',
+        anchorType: (session as any).anchorType,
+        anchorId: (session as any).anchorId,
+        preview: lastUserMessage.content,
+        actorId: user?.id
+      })
+    }
+
+    const conversation = session
+      ? buildLlmHistory(
+          await messageRepo.find({
+            where: { session: { id: session.id } as any },
+            order: { createdAt: 'ASC' },
+            relations: ['creator']
+          }),
+          {
+            maxTurns: LLM_HISTORY_MAX_TURNS,
+            truncateAfterMessageId: input.truncateAfterMessageId,
+            /* The message just stored is this turn's question — truncation must never drop it. */
+            keepMessageIds: userMessageId ? [userMessageId] : undefined,
+            summary: (session as any).lastSummary
+              ? { text: (session as any).lastSummary, upToMessageId: (session as any).summaryUpToMessageId }
+              : undefined
+          }
+        )
+      : input.messages.map(message => ({ role: message.role as any, content: message.content }))
+
+    const result = await registryAssistantChat({
+      client,
+      messages: conversation as any,
+      systemPrompt: input.systemPrompt,
+      toolCategories: input.toolCategories,
+      hostContext: input.hostContext,
+      state: context.state,
+      model: input.model,
+      temperature: input.temperature,
+      maxTokens: input.maxTokens,
+      requireToolOnFirstTurn: input.requireGroundingTools
+    })
+
+    let assistantMessageId: string | undefined
+    if (session) {
+      const stored = await messageRepo.save({
+        session: { id: session.id } as any,
+        role: 'assistant',
+        content: result.reply,
+        toolUsages: result.loop.toolUsages?.length ? JSON.stringify(result.loop.toolUsages) : undefined,
+        groundingWarnings: result.groundingWarnings?.length ? JSON.stringify(result.groundingWarnings) : undefined,
+        creator: user,
+        updater: user,
+        parentMessage: userMessageId ? ({ id: userMessageId } as any) : undefined
+      })
+      assistantMessageId = stored.id
+
+      publishChatMessage({ domainId: domain.id, sessionId: session.id, message: stored } as any)
+      /* The reply is session activity too. Leaving it out shows other participants "nothing new". */
+      publishSessionActivity({
+        domainId: domain.id,
+        sessionId: session.id!,
+        kind: 'message',
+        anchorType: (session as any).anchorType,
+        anchorId: (session as any).anchorId,
+        preview: result.reply,
+        actorId: user?.id
+      })
+
+      await sessionRepo.update(session.id!, {
+        aiClientId: client.id,
+        updater: user,
+        ...activityPatch(result.reply)
+      } as any)
+    }
+
+    return {
+      reply: result.reply,
+      clientId: client.id,
+      sessionId: session?.id,
+      userMessageId,
+      assistantMessageId,
+      toolUsages: result.loop.toolUsages?.length ? result.loop.toolUsages : null,
+      offeredTools: result.offeredTools,
+      proposals: result.loop.proposals?.length ? result.loop.proposals : null,
+      groundingWarnings: result.groundingWarnings?.length ? result.groundingWarnings : null
+    }
+  }
+}

package/server/service/chat-session-resolver.ts

@@ -68,7 +68,7 @@ class ChatSessionInboxEntry {
 @Resolver()
 export class ChatSessionResolver {
   @Query(() => ChatSession, { nullable: true, description: 'Get AI chat session by id.' })
-  @Directive('@privilege(category: "ai-assistant", privilege: "query", legacy: "board-ai")')
+  @Directive('@privilege(category: "ai-assistant", privilege: "query")')
   async chatSession(
     @Arg('id') id: string,
     @Ctx() context: ResolverContext
@@ -81,7 +81,7 @@ export class ChatSessionResolver {
     description:
       'List AI chat sessions anchored to a target (oldest first). Anchor decides the nature and the history boundary of the conversation: board = authoring, space = the site and the twins running there. Board anchor also matches legacy rows that only have boardId.'
   })
-  @Directive('@privilege(category: "ai-assistant", privilege: "query", legacy: "board-ai")')
+  @Directive('@privilege(category: "ai-assistant", privilege: "query")')
   async chatSessionsByAnchor(
     @Arg('anchorType') anchorType: string,
     @Arg('anchorId') anchorId: string,
@@ -103,7 +103,7 @@ export class ChatSessionResolver {
     description:
       "List sessions anchored to a target with this viewer's unread state, most recent activity first. Supports free-text search over name and last preview, a mine-only filter, hidden inclusion, and paging. Uses the denormalized last-activity timestamp compared against the viewer's read point — no per-session aggregation."
   })
-  @Directive('@privilege(category: "ai-assistant", privilege: "query", legacy: "board-ai")')
+  @Directive('@privilege(category: "ai-assistant", privilege: "query")')
   async chatSessionInbox(
     @Arg('anchorType') anchorType: string,
     @Arg('anchorId') anchorId: string,
@@ -132,7 +132,7 @@ export class ChatSessionResolver {
     description:
       'Total number of sessions matching the same filters as chatSessionInbox (before paging). Request it alongside the list so the UI can tell "end of page" from "end of data".'
   })
-  @Directive('@privilege(category: "ai-assistant", privilege: "query", legacy: "board-ai")')
+  @Directive('@privilege(category: "ai-assistant", privilege: "query")')
   async chatSessionInboxTotal(
     @Arg('anchorType') anchorType: string,
     @Arg('anchorId') anchorId: string,
@@ -167,7 +167,7 @@ export class ChatSessionResolver {
     description:
       "Number of sessions on this anchor that the caller has hidden and that have had no activity since. Meant to be requested alongside chatSessionInbox in the same operation so the filter can say how many are folded away."
   })
-  @Directive('@privilege(category: "ai-assistant", privilege: "query", legacy: "board-ai")')
+  @Directive('@privilege(category: "ai-assistant", privilege: "query")')
   async hiddenSessionCount(
     @Arg('anchorType') anchorType: string,
     @Arg('anchorId') anchorId: string,
@@ -223,7 +223,7 @@ export class ChatSessionResolver {
     description:
       'Delete a chat session — creator only, since a shared deliberation cannot be un-deleted from the UI. Participants who are not the creator can hide it from their own list instead (hideAISession). Soft delete; broadcast as meta activity so every list drops it.'
   })
-  @Directive('@privilege(category: "ai-assistant", privilege: "mutation", legacy: "board-ai")')
+  @Directive('@privilege(category: "ai-assistant", privilege: "mutation")')
   async deleteAISession(@Arg('sessionId') sessionId: string, @Ctx() context: ResolverContext): Promise<boolean> {
     const { domain, user } = context.state
     const repo = getRepository(ChatSession)
@@ -255,7 +255,7 @@ export class ChatSessionResolver {
     description:
       'Hide (or unhide) a session from the calling user\'s own list. Per-user and reversible — the session and other participants are unaffected. Activity newer than the hide makes it reappear; the inbox filter (showHidden) reveals hidden ones.'
   })
-  @Directive('@privilege(category: "ai-assistant", privilege: "mutation", legacy: "board-ai")')
+  @Directive('@privilege(category: "ai-assistant", privilege: "mutation")')
   async hideAISession(
     @Arg('sessionId') sessionId: string,
     @Ctx() context: ResolverContext,
@@ -301,7 +301,7 @@ export class ChatSessionResolver {
     description:
       'Rename a chat session. Any participant may rename it — the name is the topic label of a shared deliberation and the change is reversible. Broadcast as meta activity so every participant sees it without raising unread badges.'
   })
-  @Directive('@privilege(category: "ai-assistant", privilege: "mutation", legacy: "board-ai")')
+  @Directive('@privilege(category: "ai-assistant", privilege: "mutation")')
   async renameAISession(
     @Arg('sessionId') sessionId: string,
     @Arg('name') name: string,
@@ -336,7 +336,7 @@ export class ChatSessionResolver {
     description:
       "Mark a session as read up to now for the current user. Idempotent. Distinct from presence (lastSeenAt) — a window can be open without being read."
   })
-  @Directive('@privilege(category: "ai-assistant", privilege: "mutation", legacy: "board-ai")')
+  @Directive('@privilege(category: "ai-assistant", privilege: "mutation")')
   async markSessionRead(
     @Arg('sessionId') sessionId: string,
     @Ctx() context: ResolverContext
@@ -356,7 +356,7 @@ export class ChatSessionResolver {
     description:
       'List users in the current domain for `@` mention popup. board-ai 권한이면 누구나 멘션용 검색 가능 (관리자 전용 users() 와 별도).'
   })
-  @Directive('@privilege(category: "ai-assistant", privilege: "query", legacy: "board-ai")')
+  @Directive('@privilege(category: "ai-assistant", privilege: "query")')
   async domainUsersForMention(
     @Arg('query', { nullable: true, description: 'Substring to match against name/email (case-insensitive). Empty → all.' }) query: string | undefined,
     @Arg('limit', () => Int, { nullable: true, defaultValue: 50 }) limit: number,
@@ -375,7 +375,7 @@ export class ChatSessionResolver {
   @Query(() => [ChatSessionParticipant], {
     description: 'List participants of a ChatSession (members / owner).'
   })
-  @Directive('@privilege(category: "ai-assistant", privilege: "query", legacy: "board-ai")')
+  @Directive('@privilege(category: "ai-assistant", privilege: "query")')
   async chatSessionParticipants(
     @Arg('sessionId') sessionId: string,
     @Ctx() context: ResolverContext
@@ -395,7 +395,7 @@ export class ChatSessionResolver {
   @Mutation(() => Boolean, {
     description: 'Presence heartbeat — bump current user\'s lastSeenAt in the session (online indicator).'
   })
-  @Directive('@privilege(category: "ai-assistant", privilege: "mutation", legacy: "board-ai")')
+  @Directive('@privilege(category: "ai-assistant", privilege: "mutation")')
   async touchPresence(@Arg('sessionId') sessionId: string, @Ctx() context: ResolverContext): Promise<boolean> {
     const { domain, user } = context.state
     const repo = getRepository(ChatSessionParticipant)
@@ -408,7 +408,7 @@ export class ChatSessionResolver {
   }
 
   @Query(() => [ChatMessage], { description: 'List chat messages of a session, oldest first.' })
-  @Directive('@privilege(category: "ai-assistant", privilege: "query", legacy: "board-ai")')
+  @Directive('@privilege(category: "ai-assistant", privilege: "query")')
   async chatMessages(
     @Arg('sessionId') sessionId: string,
     @Arg('limit', () => Int, { nullable: true, defaultValue: 100 }) limit: number,
@@ -436,7 +436,7 @@ export class ChatSessionResolver {
     description:
       'Start (or get existing) AI chat session anchored to a target. Idempotent — returns first existing or creates one. Use anchorType board for board authoring, space for a site (its co-located twins).'
   })
-  @Directive('@privilege(category: "ai-assistant", privilege: "mutation", legacy: "board-ai")')
+  @Directive('@privilege(category: "ai-assistant", privilege: "mutation")')
   async startAISession(
     @Arg('anchorType') anchorType: string,
     @Arg('anchorId') anchorId: string,
@@ -471,7 +471,7 @@ export class ChatSessionResolver {
     description:
       'Always create a new AI chat session anchored to a target (no idempotent reuse). For multi-session UX — 새 탭 열기.'
   })
-  @Directive('@privilege(category: "ai-assistant", privilege: "mutation", legacy: "board-ai")')
+  @Directive('@privilege(category: "ai-assistant", privilege: "mutation")')
   async createAISession(
     @Arg('anchorType') anchorType: string,
     @Arg('anchorId') anchorId: string,
@@ -511,7 +511,7 @@ export class ChatSessionResolver {
   @Mutation(() => Boolean, {
     description: 'Rename a ChatSession (tab label).'
   })
-  @Directive('@privilege(category: "ai-assistant", privilege: "mutation", legacy: "board-ai")')
+  @Directive('@privilege(category: "ai-assistant", privilege: "mutation")')
   async renameChatSession(
     @Arg('sessionId') sessionId: string,
     @Arg('name') name: string,
@@ -530,7 +530,7 @@ export class ChatSessionResolver {
     description:
       'Append a system note to a session — context that did not come from a participant typing (e.g. a conversation carried over from another surface, an external state change). The AI sees it as part of the shared history.'
   })
-  @Directive('@privilege(category: "ai-assistant", privilege: "mutation", legacy: "board-ai")')
+  @Directive('@privilege(category: "ai-assistant", privilege: "mutation")')
   async appendSessionNote(
     @Arg('sessionId') sessionId: string,
     @Arg('content') content: string,
@@ -580,7 +580,7 @@ export class ChatSessionResolver {
     description:
       'Carry a conversation from another surface into this session as its own turns (user / assistant), preserving order. Use when a lightweight exchange is promoted into a persistent discussion — the participants should read it as the conversation continuing, not as a machine dump.'
   })
-  @Directive('@privilege(category: "ai-assistant", privilege: "mutation", legacy: "board-ai")')
+  @Directive('@privilege(category: "ai-assistant", privilege: "mutation")')
   async appendSessionTurns(
     @Arg('sessionId') sessionId: string,
     @Arg('turns', () => GraphQLJSON) turns: { role?: string; content?: string }[],

package/server/service/index.ts

@@ -1,4 +1,5 @@
 import { ChatSessionResolver } from './chat-session-resolver.js'
+import { AssistantChatResolver } from './assistant-chat-resolver.js'
 import { MySessionActivitySubscription } from './chat-session/session-activity-subscription.js'
 import { ChatMessageSubscription } from './chat-message/chat-message-subscription.js'
 import { entities as ChatSessionEntities } from './chat-session/index.js'
@@ -7,6 +8,7 @@ import { entities as ChatSessionParticipantEntities } from './chat-session-parti
 
 export * from './types.js'
 export * from './chat-session-resolver.js'
+export * from './assistant-chat-resolver.js'
 export * from './subscribe-auth.js'
 /* 앵커 순수 로직 — 호스트가 앵커 종류를 참조한다(리졸버는 데코레이터 때문에 무겁다). */
 export * from './chat-session/session-anchor.js'
@@ -30,6 +32,8 @@ export const entities = [...ChatSessionEntities, ...ChatMessageEntities, ...Chat
 export const schema = {
   resolverClasses: [
     ChatSessionResolver,
+    /* 문서를 갖지 않은 표면의 대화 — board 를 안 싣는 제품이 물어볼 수 있는 자리. */
+    AssistantChatResolver,
     ChatMessageSubscription,
     /* 내가 참여한 모든 세션의 활동 — 창을 닫아 둔 표면이 배지·목록을 갱신할 수 있게. */
     MySessionActivitySubscription

package/test/translations.test.ts

@@ -0,0 +1,79 @@
+/*
+ * What this holds: **the chat's words live in the same package as the chat.**
+ *
+ * The chat component moved from `board-ai` to this package on 2026-09-10, but its translation
+ * files stayed behind. In an app that loads board-ai the strings still resolved, so nothing looked
+ * wrong. In an app that does not — operato-figure was the first — the dock opened with twelve raw
+ * keys on screen (`board-ai.text.triggers-heading`, ...). No build error, no console error.
+ *
+ * The keys are strings, so neither tsc nor eslint can see a key that has no entry. These tests are
+ * the only thing that can.
+ */
+import { readFileSync, readdirSync } from 'fs'
+import { join } from 'path'
+
+const PACKAGE_ROOT = join(__dirname, '..')
+const CLIENT_DIR = join(PACKAGE_ROOT, 'client')
+const TRANSLATIONS_DIR = join(PACKAGE_ROOT, 'translations')
+
+const KEY_IN_SOURCE = /'(ai-assistant\.[a-z0-9.-]+)'/g
+
+function sourceFiles(dir: string): string[] {
+  return readdirSync(dir, { withFileTypes: true }).flatMap(entry => {
+    const path = join(dir, entry.name)
+    if (entry.isDirectory()) return sourceFiles(path)
+    return /\.tsx?$/.test(entry.name) ? [path] : []
+  })
+}
+
+const files = sourceFiles(CLIENT_DIR)
+const usedKeys = new Set<string>(
+  files.flatMap(file => [...readFileSync(file, 'utf8').matchAll(KEY_IN_SOURCE)].map(match => match[1]))
+)
+
+function locale(name: string): Record<string, string> {
+  return JSON.parse(readFileSync(join(TRANSLATIONS_DIR, `${name}.json`), 'utf8'))
+}
+
+/*
+ * An absence test passes for free once it stops finding anything to look at — a renamed directory,
+ * a changed key prefix, a moved component. So state the floor: this suite only means something
+ * while it is still reading the real client source and the real translation files.
+ */
+describe('the suite examined something', () => {
+  it('reads the client source of this package', () => {
+    expect(files.length).toBeGreaterThanOrEqual(5)
+    expect(usedKeys.size).toBeGreaterThanOrEqual(30)
+  })
+
+  it('reads the translation files of this package', () => {
+    const locales = readdirSync(TRANSLATIONS_DIR).filter(name => name.endsWith('.json'))
+    expect(locales).toEqual(expect.arrayContaining(['en.json', 'ko.json']))
+  })
+})
+
+describe('every key the chat asks for has an entry', () => {
+  it('★ english — a missing entry renders the key itself on screen', () => {
+    const entries = locale('en')
+    const missing = [...usedKeys].filter(key => !(key in entries))
+    expect(missing).toEqual([])
+  })
+
+  it('★ korean — the same, for the language most of these screens run in', () => {
+    const entries = locale('ko')
+    const missing = [...usedKeys].filter(key => !(key in entries))
+    expect(missing).toEqual([])
+  })
+})
+
+describe('the keys belong to this package', () => {
+  it('★ no key still carries the board-ai prefix — the component is not in board-ai any more', () => {
+    const stale = files.filter(file => /'board-ai\.[a-z0-9.-]+'/.test(readFileSync(file, 'utf8')))
+    expect(stale).toEqual([])
+  })
+
+  it('every entry in en.json is an ai-assistant key', () => {
+    const wrongPrefix = Object.keys(locale('en')).filter(key => !key.startsWith('ai-assistant.'))
+    expect(wrongPrefix).toEqual([])
+  })
+})