@things-factory/board-ai 10.1.5 → 10.1.6

package/server/service/grounding.ts

@@ -1,47 +1,28 @@
 /*
  * 접지 검사 — 이 대화면의 답이 **모델이 실제로 받은 것** 안에서 말했는지.
  *
- * ── 왜 board-ai 에 필요한가 ─────────────────────────────────────────────────
- * 협의 도크(operato-twin)는 board-ai 위에 서 있고, 여기서 사람들이 운영 상태를 묻는다.
- * 헤더 경로(twin-ai)에는 접지 가드가 있었지만 도크 경로에는 없었다 — 같은 질문에 대해
- * 한쪽은 검증되고 한쪽은 검증되지 않는 상태였다. 판정 규칙은 공용 모듈이 소유하고
- * (`@things-factory/ai-client-base` 의 grounding), 이 파일은 **무엇을 근거로 볼 것인가**만 정한다.
+ * ── 이 파일에 무엇이 남았나 (2026-09-10) ────────────────────────────────────
+ * 판정 규칙은 처음부터 `@things-factory/ai-client-base` 에 있었고, **근거집합의 모양**은 여기
+ * 있었다. 그래서 보드가 없는 제품은 규칙만 있고 쓸 길이 없었다 — 접지 검사를 하려면 보드
+ * 편집기를 지나야 했다. 자리는 있고 길이 없는 쪽이다.
  *
- * ── 근거집합의 정의 ─────────────────────────────────────────────────────────
- * 모델이 이 턴에 받은 전부다. 하나라도 빼면 정상 답이 경고를 받는다(오탐):
- *   · systemPrompt  — 생성 가능한 컴포넌트 타입 목록 등. 여기 있는 이름을 말하는 건 정상이다.
- *   · boardContext  — 현재 보드 요약(컴포넌트 id·이름). 보드를 두고 말하는 근거.
- *   · messages      — 사용자·이력 텍스트. 사용자가 말한 식별자를 되받는 건 정상이다.
- *   · toolResults   — 도구가 돌려준 원문(압축 전). 운영 상태 답의 유일한 사실 근거.
+ * 그 모양(`GroundingSources` · `buildGroundedCorpus`)을 공용 패키지로 옮겼다. 칸 하나가
+ * 바뀌었다: `boardContext` → `hostContext`. 근거는 보드일 수도, 공장 현황일 수도, 저작 중인
+ * 자산일 수도 있고, 그것을 아는 것은 호스트뿐이다.
+ *
+ * **베끼지 않고 옮겼다** — 같은 글이 두 곳에 있으면 한쪽만 고쳐진다. 여기 남은 것은 이 패키지의
+ * 소비처(9개 앱이 이 패키지를 지난다)가 이름을 그대로 쓰게 하는 재수출 하나다.
  *
  * ── 사정거리 ────────────────────────────────────────────────────────────────
  * 식별자만 본다. "지게차들이 바쁘게 움직인다" 처럼 **식별자 없이 지어낸 서술**은 잡지 못한다 —
  * 그건 도구를 부르지 않고 답한 경우이고, 도구 호출을 강제하는 별도 레버의 몫이다.
+ *
+ * 그리고 식별자 관례가 **소문자**다(`ID_TOKEN`). 대문자 식별자를 쓰는 제품(plant 의 `WO-…`,
+ * 트윈의 `TAG-FUNC-…`)에는 이 가드가 닿지 않는다 — 공용 패키지 쪽 판단이 필요한 별 건이다.
  */
-import { groundingWarnings } from '@things-factory/ai-client-base'
+import { buildGroundedCorpus, groundingWarnings, type GroundingSources } from '@things-factory/ai-client-base'
 
-export interface GroundingSources {
-  /** 시스템 프롬프트(타입 목록·규칙). */
-  systemPrompt?: string
-  /** 보드 상태 요약 등 대화 앞에 붙인 문맥. */
-  boardContext?: string
-  /** 사용자·어시스턴트 이력 텍스트. */
-  messages?: string[]
-  /** tool_result 로 회신된 원문(시간순). */
-  toolResults?: string[]
-}
-
-/** 근거집합을 한 덩어리 문자열로. (id 토큰 대조만 하므로 구분자는 개행으로 충분하다.) */
-export function buildGroundedCorpus(sources: GroundingSources): string {
-  return [
-    sources.systemPrompt ?? '',
-    sources.boardContext ?? '',
-    ...(sources.messages ?? []),
-    ...(sources.toolResults ?? [])
-  ]
-    .filter(Boolean)
-    .join('\n')
-}
+export { buildGroundedCorpus, type GroundingSources }
 
 /**
  * 답이 근거 밖의 식별자를 지목했으면 그 목록. 비면 접지 정상.

package/server/service/index.ts

@@ -1,11 +1,17 @@
+/*
+ * 대화 기계는 **`@things-factory/ai-assistant` 로 나갔다** (2026-09-10).
+ *
+ * 세션·메시지·참가자·인박스·구독은 보드가 없는 제품에도 뜻이 있다. 여기 남은 것은 보드 저작이다.
+ * 아래 재수출은 이 패키지를 지나는 소비처(아홉 앱)가 이름을 그대로 쓰게 한다 — 베낀 것이 아니라
+ * 가리키는 것이다.
+ *
+ * 자르는 선과 이유는 `things-factory/docs/design/ai-modules.md`.
+ */
+export * from '@things-factory/ai-assistant'
+
 import { BoardAIChatResolver } from './board-ai-resolver.js'
-import { ChatSessionResolver } from './chat-session-resolver.js'
-import { MySessionActivitySubscription } from './chat-session/session-activity-subscription.js'
+import { BoardSessionResolver } from './board-session-resolver.js'
 import { BoardPatchSubscription } from './patch-entry/board-patch-subscription.js'
-import { BoardChatMessageSubscription } from './chat-message/chat-message-subscription.js'
-import { entities as ChatSessionEntities } from './chat-session/index.js'
-import { entities as ChatMessageEntities } from './chat-message/index.js'
-import { entities as ChatSessionParticipantEntities } from './chat-session-participant/index.js'
 import { entities as PatchEntryEntities } from './patch-entry/index.js'
 
 export * from './types.js'
@@ -15,28 +21,16 @@ export * from './prefab-registry.js'
 export * from './mention-resolver.js'
 export * from './catalog-resolver.js'
 export * from './board-ai-resolver.js'
-export * from './chat-session-resolver.js'
-/* 세션 앵커 순수 로직 — 호스트가 앵커 종류를 참조할 수 있게 공개(리졸버는 데코레이터 때문에 무거움). */
-export * from './chat-session/session-anchor.js'
-export * from './chat-session/index.js'
-export * from './chat-message/index.js'
-export * from './chat-session-participant/index.js'
 export * from './patch-entry/index.js'
 
-export const entities = [
-  ...ChatSessionEntities,
-  ...ChatMessageEntities,
-  ...ChatSessionParticipantEntities,
-  ...PatchEntryEntities
-]
+/* 세션 계열 엔티티는 `ai-assistant` 가 낸다 — 프레임워크가 의존을 타고 재귀로 모은다. */
+export const entities = [...PatchEntryEntities]
 
 export const schema = {
   resolverClasses: [
     BoardAIChatResolver,
-    ChatSessionResolver,
+    /* 보드에 매인 op 여섯 — 중립 세션 op 과 갈랐다(2026-09-10). */
+    BoardSessionResolver,
     BoardPatchSubscription,
-    BoardChatMessageSubscription,
-    /* 내가 참여한 모든 세션의 활동 — 창을 닫아 둔 표면이 배지·목록을 갱신할 수 있게. */
-    MySessionActivitySubscription
   ]
 }

package/server/service/patch-entry/board-patch-subscription.ts

@@ -12,7 +12,7 @@ import { filter, pipe } from 'graphql-yoga'
 import { pubsub } from '@things-factory/shell'
 import { PatchEntry } from './patch-entry.js'
 import { BOARD_PATCH_TOPIC, boardPatchFilter, type BoardPatchPayload } from './board-patch-broadcast.js'
-import { assertDomainSubscribeAllowed } from '../subscribe-auth.js'
+import { assertDomainSubscribeAllowed } from '@things-factory/ai-assistant'
 
 export { BOARD_PATCH_TOPIC, boardPatchFilter } from './board-patch-broadcast.js'
 export type { BoardPatchPayload } from './board-patch-broadcast.js'

package/server/service/patch-entry/patch-entry.ts

@@ -23,7 +23,7 @@ import { GraphQLJSON } from 'graphql-scalars'
 
 import { config } from '@things-factory/env'
 
-import { ChatSession } from '../chat-session/chat-session.js'
+import { ChatSession } from '@things-factory/ai-assistant'
 
 const ORMCONFIG = config.get('ormconfig', {})
 const DATABASE_TYPE = ORMCONFIG.type
@@ -36,7 +36,8 @@ export class PatchEntry {
   @Field(type => ID, { nullable: true })
   readonly id?: string
 
-  @ManyToOne(type => ChatSession, session => session.patches, { onDelete: 'CASCADE' })
+  /* 역방향(`ChatSession.patches`)을 두지 않는다 — 세션은 중립이고 보드 패치를 몰라야 한다. */
+  @ManyToOne(type => ChatSession, { onDelete: 'CASCADE' })
   session?: ChatSession
 
   @RelationId((patch: PatchEntry) => patch.session)

package/server/service/registry-tool-loop.test.ts

@@ -62,6 +62,7 @@ function toolResultsSeen(seen: any[][]): any[] {
 /* 외부 도메인 패키지를 흉내낸 카테고리 — read 는 **async**(DB 조회 대역), write 는 op 생성. */
 const CATEGORY: ToolCategory = {
   name: 'test-domain',
+  guidance: '- fixture guidance for test-domain',
   specs: [
     {
       kind: 'read',

package/server/service/tool-exposure.test.ts

@@ -27,6 +27,7 @@ import {
 /* 두 개의 가짜 외부 카테고리 — 하나는 보드 저작 계열, 하나는 운영 계열. */
 const AUTHORING: ToolCategory = {
   name: 'test-authoring',
+  guidance: '- fixture guidance for test-authoring',
   specs: [
     {
       kind: 'write',
@@ -39,6 +40,7 @@ const AUTHORING: ToolCategory = {
 }
 const OPS: ToolCategory = {
   name: 'test-ops',
+  guidance: '- fixture guidance for test-ops',
   specs: [
     {
       kind: 'read',

package/server/service/types.ts

@@ -9,10 +9,9 @@
  */
 import type { BoardComponent, BoardModel } from '@things-factory/board-import'
 
-export interface LLMMessage {
-  role: 'user' | 'assistant'
-  content: string
-}
+/* 대화 한 줄은 도메인을 모른다 — 정의는 `@things-factory/ai-assistant` 에 있다(2026-09-10). */
+import type { LLMMessage } from '@things-factory/ai-assistant'
+export type { LLMMessage }
 
 export interface ChatOptions {
   /**

package/client/components/board-ai-chat.test.ts

@@ -1,149 +0,0 @@
-/**
- * board-ai-chat.ts 의 pure helper 회귀 방지.
- *
- * 핵심 보호:
- *  - GraphQL mutation input 에 selectedRefids 가 항상 포함되는지 — 누락이 사용자
- *    보고된 "AI 가 선택된 컴포넌트를 모른다" 의 root cause 였다.
- *  - 식별자 정책 — refid (universal numeric) 가 selection 채널의 표준. id 는 데이터
- *    바인딩 이름이며 unique 가 아니라 selection 에 부적합.
- */
-import { buildChatMutationInput } from './chat-input-builder'
-
-describe('buildChatMutationInput — mutation input 회귀 방지', () => {
-  test('selectedRefids 가 input 에 반드시 포함된다 (root cause regression)', () => {
-    const input = buildChatMutationInput({
-      sessionId: 'session-1',
-      history: [{ role: 'user', content: 'hi' }],
-      liveBoard: { width: 1000, height: 600, components: [] },
-      selectedRefids: [35]
-    })
-    expect(input).toHaveProperty('selectedRefids', [35])
-  })
-
-  test('selectedRefids 빈 배열도 누락 없이 포함', () => {
-    const input = buildChatMutationInput({
-      history: [],
-      liveBoard: null,
-      selectedRefids: []
-    })
-    expect(input.selectedRefids).toEqual([])
-  })
-
-  test('모든 expected 필드 존재', () => {
-    const input = buildChatMutationInput({
-      sessionId: 's1',
-      history: [{ role: 'user', content: 'hi' }],
-      liveBoard: { components: [] },
-      scopes: ['fmsim'],
-      knownTypes: ['rect'],
-      categories: ['equipment'],
-      componentSchemas: [{ type: 'rect' }],
-      selectedRefids: [1, 2]
-    })
-    expect(Object.keys(input).sort()).toEqual([
-      'categories',
-      'componentSchemas',
-      'currentBoard',
-      'knownTypes',
-      'messages',
-      'scopes',
-      'selectedRefids',
-      'sessionId'
-    ])
-  })
-
-  test('sessionId 누락 → null 정규화', () => {
-    const input = buildChatMutationInput({
-      history: [],
-      liveBoard: null,
-      selectedRefids: []
-    })
-    expect(input.sessionId).toBeNull()
-  })
-
-  test('liveBoard 누락 → null 정규화', () => {
-    const input = buildChatMutationInput({
-      history: [],
-      liveBoard: undefined,
-      selectedRefids: []
-    })
-    expect(input.currentBoard).toBeNull()
-  })
-
-  test('messages 가 history 그대로', () => {
-    const history = [
-      { role: 'user' as const, content: 'msg1' },
-      { role: 'assistant' as const, content: 'reply1' }
-    ]
-    const input = buildChatMutationInput({
-      history,
-      liveBoard: null,
-      selectedRefids: []
-    })
-    expect(input.messages).toBe(history)
-  })
-
-  test('liveBoard 가 그대로 currentBoard 로 매핑', () => {
-    const board = {
-      width: 1920,
-      height: 1080,
-      components: [{ refid: 1, type: 'rect' }]
-    }
-    const input = buildChatMutationInput({
-      history: [],
-      liveBoard: board,
-      selectedRefids: []
-    })
-    expect(input.currentBoard).toBe(board)
-  })
-
-  test('scopes / knownTypes / categories 누락 시 undefined', () => {
-    const input = buildChatMutationInput({
-      history: [],
-      liveBoard: null,
-      selectedRefids: []
-    })
-    expect(input.scopes).toBeUndefined()
-    expect(input.knownTypes).toBeUndefined()
-    expect(input.categories).toBeUndefined()
-    expect(input.componentSchemas).toBeUndefined()
-  })
-
-  test('selectedRefids 다중 항목 (number 배열, stringify 없음)', () => {
-    const input = buildChatMutationInput({
-      history: [],
-      liveBoard: null,
-      selectedRefids: [35, 127, 4096]
-    })
-    expect(input.selectedRefids).toEqual([35, 127, 4096])
-  })
-
-  test('mentions (popup picks) — 빈 배열은 input 에 안 들어감 (server 부담 X)', () => {
-    const input = buildChatMutationInput({
-      history: [],
-      liveBoard: null,
-      selectedRefids: [],
-      mentions: []
-    })
-    expect(input.mentions).toBeUndefined()
-  })
-
-  test('mentions — 항목 있으면 input 에 그대로 통과', () => {
-    const input = buildChatMutationInput({
-      history: [{ role: 'user', content: '#경광등1 빨갛게' }],
-      liveBoard: null,
-      selectedRefids: [],
-      mentions: [{ token: '경광등1', refid: 35 }]
-    })
-    expect(input.mentions).toEqual([{ token: '경광등1', refid: 35 }])
-  })
-
-  test('mentions 미지정 시 input 에 키 자체가 없음 (backwards compat)', () => {
-    const input = buildChatMutationInput({
-      history: [],
-      liveBoard: null,
-      selectedRefids: []
-    })
-    expect('mentions' in input).toBe(false)
-  })
-})