@things-factory/board-ai 10.1.4 → 10.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/board-ai",
-  "version": "10.1.4",
+  "version": "10.1.6",
   "main": "dist-server/index.js",
   "browser": "dist-client/client/index.js",
   "things-factory": true,
@@ -31,9 +31,10 @@
     "@operato/graphql": "^10.0.0",
     "@operato/i18n": "^10.0.0",
     "@operato/styles": "^10.0.0",
-    "@things-factory/ai-client-base": "^10.1.3",
-    "@things-factory/auth-base": "^10.1.4",
-    "@things-factory/board-import": "^10.1.4",
+    "@things-factory/ai-assistant": "^10.1.6",
+    "@things-factory/ai-client-base": "^10.1.6",
+    "@things-factory/auth-base": "^10.1.6",
+    "@things-factory/board-import": "^10.1.6",
     "@things-factory/env": "^10.1.3",
     "@things-factory/shell": "^10.1.4",
     "dompurify": "^3.0.0",
@@ -45,5 +46,5 @@
     "copyfiles": "^2.4.1",
     "rimraf": "^5.0.0"
   },
-  "gitHead": "c653a2967daa76b3828f1eb7f4eb18934263d4b8"
+  "gitHead": "963aeb9ac470be5aea05bb5842a0a92afcab6036"
 }

package/server/service/apply-patch-drift.test.ts

@@ -14,7 +14,9 @@
 import * as serverModule from './apply-patch'
 // 테스트 환경은 jest node — client 측 module 도 plain TS 라서 직접 import 가능
 // (Lit / @material/web 같은 ESM 의존 없음)
-import * as clientModule from '../../client/utils/board-edit-patch'
+/* 클라이언트 쪽 구현은  로 옮겼다(2026-09-10). 이 시험은 두 구현이
+ * 어긋나는 것을 잡는 것이므로, 옮긴 자리를 그대로 가리킨다. */
+import * as clientModule from '../../../ai-assistant/client/utils/board-edit-patch'
 
 describe('apply-patch drift 자동 검증 — server / client 사본 동기 보장', () => {
   test('주요 함수 export 모두 양쪽에 존재', () => {

package/server/service/assistant.ts

@@ -40,7 +40,15 @@ import { buildComponentStyleSummary } from './styling/read-tools'
  *
  * board 의 것(문서·선택 refid·편집 op)은 타입 매개변수로 넘긴다 — 루프는 그 모양을 모른다.
  */
-import { runAgenticLoop, type AgenticLoopResult } from '@things-factory/ai-client-base'
+import {
+  runAgenticLoop,
+  formatAbortNotice,
+  summarizeToolResult,
+  registryToolGate,
+  extendToolGate,
+  type ToolGate as NeutralToolGate,
+  type AgenticLoopResult
+} from '@things-factory/ai-client-base'
 import type { BoardActionOp } from './types.js'
 
 /** 이 대화면의 도구가 알아야 하는 것 — 루프는 나르기만 한다. */
@@ -296,7 +304,8 @@ export class DefaultBoardAIAssistant implements BoardAIAssistant {
      * 근거집합의 정의와 사정거리는 ./grounding 머리말 참조(식별자 없는 창작 서술은 잡지 못한다). */
     const warnings = checkReplyGrounding(baseReply, {
       systemPrompt,
-      boardContext,
+      /* 근거집합의 칸 이름은 공용 패키지의 것이다 — 이 값이 보드 문맥이라는 것은 이 파일만 안다. */
+      hostContext: boardContext,
       messages: messages.map(m => (typeof m.content === 'string' ? m.content : '')),
       toolResults: loopResult.groundedTexts
     })
@@ -1990,64 +1999,20 @@ export function listLayoutTemplateNames(): string[] {
   return Object.keys(LAYOUT_TEMPLATES.templates)
 }
 
-/**
- * agentic loop 의 비정상 종료 사유 → 사용자 메시지에 부기할 한국어 한 줄.
+/*
+ * 중단 통지 · 도구 결과 요약 — **공용 패키지로 옮겼다** (2026-09-10).
  *
- * 정상 종료 (abortReason undefined) 면 빈 문자열 — concat 해도 무해.
- * 사용자에게 "왜 중간에 멈췄는지" 단서 제공이 목적 — 침묵 종료 금지.
- */
-export function formatAbortNotice(
-  abortReason: AgenticLoopResult['abortReason']
-): string {
-  if (!abortReason) return ''
-  switch (abortReason.type) {
-    case 'aborted':
-      return '\n\n_(요청이 중단되어 일부만 처리됐어요.)_'
-    case 'provider_error':
-      /* 남의 말(SDK 원문)을 사용자에게 보여주지 않는다 — "Error fetching from undefined: [503 …]" 은
-       * 사용자가 할 수 있는 일을 알려주지 않는다. 일시 장애는 이미 몇 번 다시 시도한 뒤이므로,
-       * 지금 필요한 안내는 "잠시 후 다시" 하나다. 원문은 서버 로그에 남는다. */
-      return isTransientAIError({ message: abortReason.message })
-        ? '\n\n_(AI 서비스가 일시적으로 응답하지 않았어요. 잠시 후 다시 시도해 주세요.)_'
-        : '\n\n_(처리 중 오류가 발생했어요. 같은 요청이 계속 실패하면 관리자에게 알려 주세요.)_'
-    case 'max_iterations':
-      return `\n\n_(작업이 너무 길어 ${abortReason.iter}회에서 중단했어요. 더 작게 나눠 요청해보세요.)_`
-    case 'repeated_validation_failure':
-      return `\n\n_(\`${abortReason.toolName}\` 호출이 ${abortReason.consecutive}회 연속 실패해 중단했어요. 요청을 다시 표현해보세요.)_`
-  }
-}
-
-/**
- * tool 결과를 UI fold-able 박스에 보여줄 만한 크기로 요약.
+ * 둘 다 보드를 모르는 함수였다. 옮긴 이유는 중복이 아니라 **한쪽만 갖고 있었던 것**이다:
+ * `twin-ai` 는 `summarizeToolResult: v => v` 로 요약을 아예 안 하고 있었다. 한 제품은 압축해서
+ * 영속하고 다른 제품은 원본을 영속했고, 그렇게 갈린 이유가 어디에도 없었다.
+ *
+ * 중단 통지는 더 무겁다 — 안 붙이면 **잘린 답이 완결된 답과 똑같이 보인다.** 그 보장을 제품마다
+ * 기억해야 하는 것으로 두면 언젠가 한 제품이 잊는다.
  *
- * 원본 그대로면 findComponents 50개 / getAtmosphereGuide 같은 큰 객체가 ChatMessage
- * 영속까지 부담 — 핵심 모양만 유지하고 나머지는 marker.
+ * 여기 남은 것은 재수출이다. 이 패키지를 지나는 소비처가 이름을 그대로 쓰게 한다.
  */
-export function summarizeToolResult(value: any, depth = 0): any {
-  if (value === null || value === undefined) return value
-  if (typeof value === 'string') {
-    return value.length > 200 ? `${value.slice(0, 200)}…[+${value.length - 200} chars]` : value
-  }
-  if (typeof value === 'number' || typeof value === 'boolean') return value
-  if (Array.isArray(value)) {
-    if (depth >= 2) return `[Array(${value.length})]`
-    const out = value.slice(0, 5).map(v => summarizeToolResult(v, depth + 1))
-    if (value.length > 5) out.push(`…[+${value.length - 5} items]`)
-    return out
-  }
-  if (typeof value === 'object') {
-    if (depth >= 3) {
-      const keys = Object.keys(value).slice(0, 6).join(',')
-      return `{${keys}${Object.keys(value).length > 6 ? ',…' : ''}}`
-    }
-    const out: any = {}
-    for (const key of Object.keys(value)) {
-      out[key] = summarizeToolResult(value[key], depth + 1)
-    }
-    return out
-  }
-  return undefined
-}
+export { formatAbortNotice, summarizeToolResult }
+
 
 export function isWriteTool(name: string): boolean {
   if (WRITE_TOOL_NAMES.has(name)) return true
@@ -2079,27 +2044,36 @@ export interface ToolExposure {
   toolCategories?: ToolCategoryFilter
 }
 
-export interface ToolGate {
+/**
+ * 보드의 게이트 — 공용 게이트 + 이 패키지가 가진 코어 도구 이름집합.
+ *
+ * `coreOn` 이 여기 있는 이유: 「코어 보드 편집 도구」라는 것이 board-ai 에만 있는 개념이다.
+ * 공용 게이트는 레지스트리만 안다.
+ */
+export interface ToolGate extends NeutralToolGate {
   coreOn: boolean
-  filter: ToolCategoryFilter
-  isRead(name: string): boolean
-  isWrite(name: string): boolean
-  isAction(name: string): boolean
-  spec(name: string): ToolSpec | undefined
 }
 
+/**
+ * ── 레지스트리 판정을 공용으로 옮겼다 (2026-09-10) ─────────────────────────
+ * 이 함수가 두 출처에 답하고 있었다 — **도구 레지스트리**(등록된 카테고리의 kind·spec)와
+ * **이 패키지의 코어 이름집합**. 앞엣것은 중립이다: 「이 이름이 어느 종류이고 이 대화가 볼 수
+ * 있나」는 호스트가 누구든 같은 답이다.
+ *
+ * 그래서 앞엣것은 `registryToolGate` 로 내려갔고, 여기서 뒤엣것을 **더한다**. 이 갈이가 없으면
+ * 보드 없는 제품이 같은 dispatch 규율을 받으려고 자기 게이트를 써야 하고, 그러면 접지 가드가
+ * 갈렸던 것과 같은 일이 게이트에서 난다.
+ *
+ * 더하는 것이지 덮는 것이 아니다 — 덮으면 코어 이름집합에 없는 등록 도구가 조용히 잠긴다.
+ */
 export function buildToolGate(exposure: ToolExposure = {}): ToolGate {
   const coreOn = exposure.boardTools !== false
-  const filter = exposure.toolCategories
-  const kind = (name: string) => getToolKind(name, filter)
-  return {
-    coreOn,
-    filter,
-    isRead: name => (coreOn && READ_TOOL_NAMES.has(name)) || kind(name) === 'read' || kind(name) === 'external',
-    isWrite: name => (coreOn && WRITE_TOOL_NAMES.has(name)) || kind(name) === 'write',
-    isAction: name => (coreOn && ACTION_TOOL_NAMES.has(name)) || kind(name) === 'action',
-    spec: name => findToolSpec(name, filter)
-  }
+  const gate = extendToolGate(registryToolGate(exposure.toolCategories), {
+    isRead: name => coreOn && READ_TOOL_NAMES.has(name),
+    isWrite: name => coreOn && WRITE_TOOL_NAMES.has(name),
+    isAction: name => coreOn && ACTION_TOOL_NAMES.has(name)
+  })
+  return { ...gate, coreOn }
 }
 
 /**

package/server/service/board-ai-resolver.ts

@@ -15,12 +15,13 @@ import { createAIClient, getDefaultAIClient, type AIClient } from '@things-facto
 import type { ComponentCategory } from '@things-factory/board-import'
 
 import { DefaultBoardAIAssistant } from './assistant.js'
+import { effectiveBoardTools } from './board-tool-rights.js'
 import type { LLMMessage } from './types.js'
-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 { splitByCap, summaryInstruction } from './chat-message/history-summary.js'
-import { foldHistorySummary } from './chat-message/fold-history.js'
+import { ChatSession } from '@things-factory/ai-assistant'
+import { ChatMessage } from '@things-factory/ai-assistant'
+import { buildLlmHistory } from '@things-factory/ai-assistant'
+import { splitByCap, summaryInstruction } from '@things-factory/ai-assistant'
+import { foldHistorySummary } from '@things-factory/ai-assistant'
 
 /**
  * 모델에 넘길 최근 메시지 수 상한.
@@ -38,13 +39,13 @@ const LLM_HISTORY_MAX_TURNS = 40
  * 상한을 넘긴 뒤 매 턴 요약을 만들면 대화마다 LLM 호출이 두 번씩 붙는다. 10 개씩 모아 접는다.
  */
 const LLM_SUMMARY_THRESHOLD = 10
-import { activityPatch, autoSessionName } from './chat-session/session-inbox.js'
-import { publishSessionActivity } from './chat-session/session-activity-publish.js'
-import { publishChatMessage } from './chat-message/chat-message-publish.js'
+import { activityPatch, autoSessionName } from '@things-factory/ai-assistant'
+import { publishSessionActivity } from '@things-factory/ai-assistant'
+import { publishChatMessage } from '@things-factory/ai-assistant'
 import { PatchEntry } from './patch-entry/patch-entry.js'
 import { publishBoardPatch } from './patch-entry/board-patch-subscription.js'
-import { ChatSessionParticipant } from './chat-session-participant/chat-session-participant.js'
-import { buildInviteNotification } from './chat-session-participant/invite-notification.js'
+import { ChatSessionParticipant } from '@things-factory/ai-assistant'
+import { buildInviteNotification } from '@things-factory/ai-assistant'
 import {
   injectMentionRefids,
   injectAiMentionRefids,
@@ -258,7 +259,16 @@ export class BoardAIChatResolver {
   @Mutation(() => BoardAIChatOutput, {
     description: 'AI 주도 보드 모델링 — 자연어 채팅으로 보드 생성·구조편집·스타일링. sessionId 로 영속 컨텍스트.'
   })
-  @Directive('@privilege(category: "board-ai", privilege: "mutation")')
+  /*
+   * ── 이 문은 「묻는 것」이지 「보드를 고치는 것」이 아니다 (2026-09-10) ──────────
+   * 공장 현황을 묻는 화면이 **보드 편집 권한**을 요구하던 것이 이 분리의 시작이었다. 대화는
+   * `ai-assistant:mutation`, 보드 편집은 `board-ai:mutation` — 둘은 다른 능력이다.
+   *
+   * ⚠ 문만 바꾸면 **거꾸로 넓어진다.** 코어 보드 편집 도구가 기본으로 켜져 있으므로, 대화 권한만
+   * 가진 사람이 이 문으로 보드를 고치게 된다. 그래서 아래에서 **보드 편집 권한을 따로 보고**
+   * 없으면 그 도구를 끈다(§`effectiveBoardTools`).
+   */
+  @Directive('@privilege(category: "ai-assistant", privilege: "mutation", legacy: "board-ai")')
   async boardAIChat(
     @Arg('input') input: BoardAIChatInput,
     @Ctx() context: ResolverContext
@@ -401,7 +411,7 @@ export class BoardAIChatResolver {
       hostContext: input.hostContext ?? undefined,
       /* 대화면별 도구 노출 — 미지정이면 현행(전부 허용) 그대로. */
       toolCategories: input.toolCategories ?? undefined,
-      boardTools: input.boardTools ?? undefined,
+      boardTools: await effectiveBoardTools(input.boardTools, context),
       requireGroundingTools: input.requireGroundingTools ?? undefined,
       knownTypes: input.knownTypes,
       categories: input.categories as ComponentCategory[] | undefined,

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

@@ -0,0 +1,183 @@
+/*
+ * 보드에 매인 대화 op — **보드 편집기의 것이라 여기 남는다.**
+ *
+ * ── 왜 갈랐나 (2026-09-10) ──────────────────────────────────────────────────
+ * `chat-session-resolver.ts` 에 스물넷이 함께 있었다. 그 중 열여덟은 대화 자체의 일(세션·참가자·
+ * 인박스·메시지)이라 보드가 없는 제품에도 뜻이 있고, 여섯은 보드의 일이다. 한 파일에 있는 동안은
+ * 앞엣것을 중립 패키지로 옮길 수 없다 — 옮기면 `ai-assistant → board-ai` 의존이 생긴다.
+ *
+ * 그래서 **여섯을 이쪽으로 뗐다.** 남은 열여덟이 옮겨질 수 있는 상태가 되는 것이 이 갈이의 목적이다.
+ *
+ * ── 왜 여섯인가 ─────────────────────────────────────────────────────────────
+ *   chatSessionByBoard · chatSessionsByBoard   보드 id 로 찾는다 — 보드를 아는 질의
+ *   startBoardAISession                        보드 앵커로 시작하는 얇은 래퍼
+ *   chatPatches · recordDirectPatch · revertPatch   PatchEntry — 보드 편집 이력
+ *
+ * ── 위임을 `this` 로 하지 않는다 ────────────────────────────────────────────
+ * 앞의 셋은 원래 `this.startAISession(...)` 처럼 같은 클래스의 중립 메서드를 불렀다. 이제 클래스가
+ * 둘이므로 중립 리졸버 인스턴스에 위임한다. 리졸버는 상태가 없다(전부 `context.state` 에서 읽는다).
+ *
+ * **로직을 베끼지 않는다** — 같은 글이 두 곳에 있으면 한쪽만 고쳐진다.
+ */
+import { Resolver, Query, Mutation, Arg, Ctx, Directive, Int } from 'type-graphql'
+import { GraphQLJSON } from 'graphql-scalars'
+
+import { getRepository } from '@things-factory/shell'
+
+import { ChatSession } from '@things-factory/ai-assistant'
+import { activityPatch } from '@things-factory/ai-assistant'
+import { publishSessionActivity } from '@things-factory/ai-assistant'
+import { ChatMessage } from '@things-factory/ai-assistant'
+import { publishChatMessage } from '@things-factory/ai-assistant'
+import { ChatSessionResolver } from '@things-factory/ai-assistant'
+import { PatchEntry } from './patch-entry/patch-entry.js'
+import { publishBoardPatch } from './patch-entry/board-patch-subscription.js'
+
+/** 중립 op 로의 위임 대상. 리졸버는 상태가 없으므로 하나면 된다. */
+const sessions = new ChatSessionResolver()
+
+@Resolver()
+export class BoardSessionResolver {
+  @Query(() => ChatSession, { nullable: true, description: 'Get AI chat session by board id (returns first match — backward compat single-session lookup).' })
+  @Directive('@privilege(category: "ai-assistant", privilege: "query", legacy: "board-ai")')
+  async chatSessionByBoard(
+    @Arg('boardId') boardId: string,
+    @Ctx() context: ResolverContext
+  ): Promise<ChatSession | null> {
+    const { domain } = context.state
+    return (
+      (await getRepository(ChatSession).findOneBy({ boardId, domain: { id: domain.id } })) ?? null
+    )
+  }
+
+  /** 보드 전용 진입점 — 앵커 조회의 얇은 래퍼(기존 소비자 무변경). */
+  @Query(() => [ChatSession], {
+    description: 'List all AI chat sessions for a board (oldest first). Thin wrapper over chatSessionsByAnchor(board).'
+  })
+  @Directive('@privilege(category: "ai-assistant", privilege: "query", legacy: "board-ai")')
+  async chatSessionsByBoard(
+    @Arg('boardId') boardId: string,
+    @Ctx() context: ResolverContext
+  ): Promise<ChatSession[]> {
+    return await sessions.chatSessionsByAnchor('board', boardId, context)
+  }
+
+  @Query(() => [PatchEntry], { description: 'List patch entries of a session, newest first.' })
+  /*
+   * ⚠ 이 셋은 **보드 편집기의 것**이라 `board-ai` 에 남는다 (2026-09-10).
+   *
+   * 나머지 스물둘을 `ai-assistant` 로 옮길 때 이것들도 함께 갔다가, 도는 스키마를 확인하면서
+   * 되돌렸다 — `revertPatch` 가 `ai-assistant:mutation` 으로 떠 있었다. 즉 **대화 권한만 가진
+   * 사람이 보드 패치를 되돌릴 수 있었다.** 좁히려던 변경이 넓히는 변경이 된 자리다.
+   *
+   * 가르는 물음: **이것이 보드를 바꾸나.** 패치는 바꾼다. 세션 조회는 안 바꾼다.
+   */
+  @Directive('@privilege(category: "board-ai", privilege: "query")')
+  async chatPatches(
+    @Arg('sessionId') sessionId: string,
+    @Arg('limit', () => Int, { nullable: true, defaultValue: 100 }) limit: number,
+    @Ctx() context: ResolverContext
+  ): Promise<PatchEntry[]> {
+    const { domain } = context.state
+    const session = await getRepository(ChatSession).findOneBy({
+      id: sessionId,
+      domain: { id: domain.id }
+    })
+    if (!session) return []
+    return await getRepository(PatchEntry).find({
+      where: { session: { id: sessionId } as any },
+      order: { createdAt: 'DESC' },
+      take: limit
+    })
+  }
+
+  /** 보드 전용 진입점 — 앵커 시작의 얇은 래퍼(기존 소비자 무변경). */
+  @Mutation(() => ChatSession, {
+    description: 'Start (or get existing) AI chat session for a board. Thin wrapper over startAISession(board).'
+  })
+  @Directive('@privilege(category: "ai-assistant", privilege: "mutation", legacy: "board-ai")')
+  async startBoardAISession(
+    @Arg('boardId') boardId: string,
+    @Ctx() context: ResolverContext
+  ): Promise<ChatSession> {
+    return await sessions.startAISession('board', boardId, context)
+  }
+
+  @Directive('@transaction')
+  @Mutation(() => PatchEntry, {
+    description: 'Record a patch from user direct edit. Adds a system message so AI sees the change next turn.'
+  })
+  @Directive('@privilege(category: "board-ai", privilege: "mutation")')
+  async recordDirectPatch(
+    @Arg('sessionId') sessionId: string,
+    @Arg('ops', () => GraphQLJSON) ops: any[],
+    @Arg('summary', { nullable: true }) summary: string | undefined,
+    @Ctx() context: ResolverContext
+  ): Promise<PatchEntry> {
+    const { domain, tx, user } = context.state
+    const session = await getRepository(ChatSession, tx).findOneBy({
+      id: sessionId,
+      domain: { id: domain.id }
+    })
+    if (!session) throw new Error(`ChatSession ${sessionId} not found`)
+
+    const entry = await getRepository(PatchEntry, tx).save({
+      session: { id: session.id } as any,
+      source: 'user-direct',
+      ops: JSON.stringify(ops || []),
+      summary,
+      reverted: false
+    } as any)
+
+    // AI 컨텍스트 흐름 — system 메시지 자동 추가. creator = 직접 편집한 사용자.
+    // parentMessage = 직전 in-session 메시지 (timeline 연속성 유지 — system 도 chain 에 합류).
+    const previousLast = await getRepository(ChatMessage, tx).findOne({
+      where: { session: { id: session.id } as any },
+      order: { createdAt: 'DESC' }
+    })
+    const sysMsg = await getRepository(ChatMessage, tx).save({
+      session: { id: session.id } as any,
+      role: 'system',
+      content: `User directly edited the board: ${summary ?? `${(ops || []).length} op(s)`}`,
+      relatedPatchId: entry.id,
+      creator: user,
+      updater: user,
+      parentMessage: previousLast ? ({ id: previousLast.id } as any) : undefined
+    } as any)
+
+    /* 세션 활동 갱신 — 직접 편집도 다른 참여자에게는 새 소식이다(목록 정렬·안 읽음 판정). */
+    try {
+      await getRepository(ChatSession, tx).update(session.id!, activityPatch(sysMsg.content) as any)
+    } catch {
+      /* best-effort — 편집 기록을 막지 않는다 */
+    }
+    publishSessionActivity({
+      domainId: domain.id,
+      sessionId: session.id!,
+      kind: 'message',
+      anchorType: (session as any).anchorType,
+      anchorId: (session as any).anchorId,
+      preview: sysMsg.content,
+      actorId: user?.id
+    })
+
+    // C1: user-direct 편집도 같은 board 구독자에게 방송 (AI·타참여자 실시간 반영). best-effort.
+    publishBoardPatch({ domainId: domain.id, boardId: session.boardId, patch: entry })
+    // C4: 직접편집 system 메시지를 같은 세션 구독자에게 방송 (transcript 실시간 일관성). best-effort.
+    publishChatMessage({ domainId: domain.id, sessionId: session.id, message: sysMsg })
+
+    return entry
+  }
+
+  @Directive('@transaction')
+  @Mutation(() => Boolean, { description: 'Mark a patch as reverted (does not undo, only flags).' })
+  @Directive('@privilege(category: "board-ai", privilege: "mutation")')
+  async revertPatch(
+    @Arg('patchId') patchId: string,
+    @Ctx() context: ResolverContext
+  ): Promise<boolean> {
+    const { tx } = context.state
+    await getRepository(PatchEntry, tx).update(patchId, { reverted: true })
+    return true
+  }
+}

package/server/service/board-tool-rights.test.ts

@@ -0,0 +1,96 @@
+/*
+ * 무엇을 지키는가: **권한을 좁히려던 변경이 권한을 넓히지 않는 것.**
+ *
+ * `boardAIChat` 의 문이 `board-ai:mutation` 에서 `ai-assistant:mutation` 으로 옮겨졌다. 코어 보드
+ * 편집 도구는 기본이 켜짐이므로, 그 한 줄만 바꾸면 **대화 권한만 가진 사람이 같은 문으로 보드를
+ * 고치게 된다.** 시작한 문제(공장 질문이 보드 편집 권한을 요구한다)를 뒤집어 놓는 것이다.
+ *
+ * 여기 있는 시험들은 그 뒤집힘이 다시 생기면 실패한다.
+ */
+const mockCheckPermission = jest.fn()
+const mockWarn = jest.fn()
+
+jest.mock('@things-factory/auth-base', () => ({ checkPermission: (...a: any[]) => mockCheckPermission(...a) }))
+jest.mock('@things-factory/env', () => ({ logger: { warn: (...a: any[]) => mockWarn(...a) } }))
+
+import { effectiveBoardTools } from './board-tool-rights'
+
+const context = (over: any = {}) => ({
+  state: {
+    domain: { id: 'dom-1', subdomain: 'miratek-gunsan' },
+    user: { id: 'u-1', email: 'a@b.c' },
+    unsafeIP: false,
+    prohibitedPrivileges: [],
+    ...over
+  }
+})
+
+beforeEach(() => {
+  mockCheckPermission.mockReset()
+  mockWarn.mockReset()
+})
+
+describe('보드 편집 권한이 없으면 편집 도구가 켜지지 않는다', () => {
+  it('★ 권한이 없으면 기본값(미지정)이 켜짐으로 남지 않는다', async () => {
+    mockCheckPermission.mockResolvedValue(false)
+    expect(await effectiveBoardTools(undefined, context())).toBe(false)
+  })
+
+  it('권한이 있으면 미지정은 미지정 그대로다 — 기본 거동을 이 파일이 바꾸지 않는다', async () => {
+    mockCheckPermission.mockResolvedValue(true)
+    expect(await effectiveBoardTools(undefined, context())).toBeUndefined()
+  })
+
+  it('권한이 있고 켜 달라고 하면 켠다', async () => {
+    mockCheckPermission.mockResolvedValue(true)
+    expect(await effectiveBoardTools(true, context())).toBe(true)
+  })
+
+  it('권한이 없는데 켜 달라고 하면 끄고, 그 사실을 남긴다', async () => {
+    mockCheckPermission.mockResolvedValue(false)
+    expect(await effectiveBoardTools(true, context())).toBe(false)
+    expect(mockWarn).toHaveBeenCalledTimes(1)
+    expect(String(mockWarn.mock.calls[0][0])).toMatch(/board-ai:mutation/)
+  })
+
+  it('안 물어본 좁힘은 로그를 남기지 않는다 — 매 질문마다 한 줄이면 로그가 소음이 된다', async () => {
+    mockCheckPermission.mockResolvedValue(false)
+    await effectiveBoardTools(undefined, context())
+    expect(mockWarn).not.toHaveBeenCalled()
+  })
+})
+
+describe('끄겠다고 한 것을 되살리지 않는다', () => {
+  it('false 는 권한이 있어도 false 다 — 보드 없는 대화면이 이 값을 준다', async () => {
+    mockCheckPermission.mockResolvedValue(true)
+    expect(await effectiveBoardTools(false, context())).toBe(false)
+  })
+
+  it('false 면 권한을 묻지도 않는다 — 물을 이유가 없다', async () => {
+    await effectiveBoardTools(false, context())
+    expect(mockCheckPermission).not.toHaveBeenCalled()
+  })
+})
+
+describe('묻는 방식', () => {
+  it('board-ai:mutation 을 묻는다', async () => {
+    mockCheckPermission.mockResolvedValue(true)
+    await effectiveBoardTools(undefined, context())
+    expect(mockCheckPermission.mock.calls[0][0]).toEqual({ category: 'board-ai', privilege: 'mutation' })
+  })
+
+  it('★ 소유자·슈퍼유저 우회를 새로 주지 않는다 — 좁히는 변경이 우회를 늘리면 안 된다', async () => {
+    mockCheckPermission.mockResolvedValue(true)
+    await effectiveBoardTools(undefined, context())
+    const asked = mockCheckPermission.mock.calls[0][0]
+    expect(asked.owner).toBeUndefined()
+    expect(asked.super).toBeUndefined()
+  })
+
+  it('금지 목록을 그대로 넘긴다 — 여기서 관리자의 금지를 무력화하지 않는다', async () => {
+    mockCheckPermission.mockResolvedValue(true)
+    const prohibited = [{ category: 'board-ai', privilege: 'mutation' }]
+    await effectiveBoardTools(undefined, context({ prohibitedPrivileges: prohibited }))
+    expect(mockCheckPermission.mock.calls[0][4]).toBe(prohibited)
+  })
+})

package/server/service/board-tool-rights.ts

@@ -0,0 +1,73 @@
+/*
+ * 이 대화가 보드를 고칠 수 있나 — **문을 지난 것과 별개로** 묻는다.
+ *
+ * ── 왜 나뉘어야 하나 (2026-09-10) ───────────────────────────────────────────
+ * `boardAIChat` 의 문이 `board-ai:mutation` 이었다. 그래서 공장 현황을 묻는 화면이 보드 편집
+ * 권한을 요구했고, 그것이 이 분리의 시작이었다.
+ *
+ * 문만 `ai-assistant:mutation` 으로 바꾸면 **거꾸로 넓어진다.** 코어 보드 편집 도구는 기본으로
+ * 켜져 있으므로, 대화 권한만 가진 사람이 같은 문으로 보드를 고치게 된다. 권한을 좁히려던 변경이
+ * 권한을 넓히는 변경이 되는 것이다.
+ *
+ * 그래서 둘로 본다.
+ *
+ *   묻는다        ai-assistant:mutation   문이 본다
+ *   보드를 고친다  board-ai:mutation       이 파일이 본다
+ *
+ * ── 왜 게이트가 아니라 능력으로 두나 ────────────────────────────────────────
+ * 권한이 없다고 요청을 거절하면, 보드 편집 권한이 없는 사람은 **보드가 열린 화면에서 아무것도
+ * 물을 수 없게** 된다. 그건 과하다 — 읽고 묻는 것은 편집이 아니다. 그래서 거절하지 않고 **편집
+ * 도구만 끈다.** 모델은 그 도구를 아예 못 보고, 고쳐 달라는 말에는 할 수 없다고 답한다.
+ *
+ * 도구를 숨기는 것만으로 충분하지 않다는 것은 이미 판정돼 있다 — 정의를 숨겨도 이름을 짐작하거나
+ * 옛 대화가 재생되면 호출된다. 그래서 이 값은 `buildToolGate` 로 내려가 **정의 조립과 dispatch
+ * 판정 양쪽**에 쓰인다(`assistant.ts`).
+ */
+import { checkPermission } from '@things-factory/auth-base'
+import { logger } from '@things-factory/env'
+
+/**
+ * 이 요청에 코어 보드 편집 도구를 켤 것인가.
+ *
+ * @param requested 대화면이 보낸 값. `false` 는 「끄고 싶다」는 뜻이고 그대로 존중한다.
+ *                  `undefined` 는 「기본대로」이고, 기본은 켜짐이었다 — 이제 권한이 그것을 정한다.
+ */
+export async function effectiveBoardTools(
+  requested: boolean | undefined,
+  context: any
+): Promise<boolean | undefined> {
+  /* 끄겠다고 한 것을 권한으로 되살리지 않는다. plant 처럼 애초에 보드가 없는 대화면이 이 값을 준다. */
+  if (requested === false) return false
+
+  const { domain, user, unsafeIP, prohibitedPrivileges } = context?.state ?? {}
+
+  /*
+   * 소유자·슈퍼유저 우회를 주지 않는다 — 옮기기 전 이 리졸버의 지시자에도 없었다. 여기서 새로
+   * 주면 권한을 좁히는 변경이 우회를 하나 늘리는 변경이 된다.
+   */
+  const mayEdit = await checkPermission(
+    { category: 'board-ai', privilege: 'mutation' },
+    user,
+    domain,
+    unsafeIP,
+    prohibitedPrivileges
+  )
+
+  if (mayEdit) return requested
+
+  /*
+   * **달라고 했는데 못 준 경우에만 남긴다.**
+   *
+   * 안 물어본 좁힘(=`undefined`)까지 매번 적으면, 보드가 없는 대화면이 질문을 던질 때마다 한 줄씩
+   * 쌓여 로그가 소음이 된다. 소음이 되면 사람이 로그를 안 본다. 반대로 **명시로 켜 달라고 한 것을
+   * 조용히 끄면** 대화면 쪽에서 원인을 찾을 길이 없다 — 그 경우만 적는다.
+   */
+  if (requested === true) {
+    logger.warn(
+      `[board-ai] board edit tools were requested but withheld — ` +
+        `${user?.email || user?.id} has no board-ai:mutation in ${domain?.subdomain || domain?.id}`
+    )
+  }
+
+  return false
+}

package/server/service/dock-contract.test.ts

@@ -44,6 +44,8 @@ function registerFakeTwinTools(seen: { host?: any; args?: any }) {
   registerToolCategory({
     name: 'twin-ops-fake',
     description: 'fake ops tools for contract test',
+    /* 지침 — 지침 없는 카테고리는 등록이 거절된다(2026-09-10). */
+    guidance: '- fixture guidance for twin-ops-fake',
     specs: [
       {
         kind: 'read',
@@ -101,6 +103,7 @@ describe('도크 계약 — 대화면 문맥(hostContext)', () => {
     registerToolCategory({
       name: 'twin-ops-fake',
       description: 'x',
+      guidance: '- fixture guidance for twin-ops-fake',
       specs: [
         {
           kind: 'read',

package/server/service/grounding.test.ts

@@ -8,10 +8,10 @@
 import { buildGroundedCorpus, checkReplyGrounding } from './grounding'
 
 describe('buildGroundedCorpus', () => {
-  it('네 갈래를 모두 담는다 — 프롬프트·보드 문맥·이력·도구 결과', () => {
+  it('네 갈래를 모두 담는다 — 프롬프트·호스트 문맥·이력·도구 결과', () => {
     const corpus = buildGroundedCorpus({
       systemPrompt: 'types: dock-door',
-      boardContext: '{"components":[{"id":"gauge-1"}]}',
+      hostContext: '{"components":[{"id":"gauge-1"}]}',
       messages: ['aisle-2 상태 알려줘'],
       toolResults: ['{"nodes":[{"id":"rack-9"}]}']
     })
@@ -28,7 +28,7 @@ describe('buildGroundedCorpus', () => {
 describe('checkReplyGrounding', () => {
   const sources = {
     systemPrompt: 'creatable types: dock-door, twin-node',
-    boardContext: '{"components":[{"id":"dock-1","name":"입고 도크"}]}',
+    hostContext: '{"components":[{"id":"dock-1","name":"입고 도크"}]}',
     messages: ['지금 상태 어때?'],
     toolResults: ['{"instances":[{"instanceId":"hatiolab-wms"}],"nodes":[{"id":"dock-1"}]}']
   }