@things-factory/board-ai 10.0.1 → 10.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/board-ai",
-  "version": "10.0.1",
+  "version": "10.0.2",
   "main": "dist-server/index.js",
   "browser": "dist-client/client/index.js",
   "things-factory": true,
@@ -30,9 +30,9 @@
     "@operato/graphql": "^10.0.0",
     "@operato/i18n": "^10.0.0",
     "@operato/styles": "^10.0.0",
-    "@things-factory/ai-client-base": "^10.0.0",
+    "@things-factory/ai-client-base": "^10.0.2",
     "@things-factory/auth-base": "^10.0.0",
-    "@things-factory/board-import": "^10.0.1",
+    "@things-factory/board-import": "^10.0.2",
     "@things-factory/env": "^10.0.0",
     "@things-factory/shell": "^10.0.0",
     "dompurify": "^3.0.0",
@@ -44,5 +44,5 @@
     "copyfiles": "^2.4.1",
     "rimraf": "^5.0.0"
   },
-  "gitHead": "6dd5b25ed1fe863415793bd156c3411ffe1ce47d"
+  "gitHead": "a69c3592a44e27bfa8212bc06268bff6140afc9a"
 }

package/server/service/agentic-loop.test.ts

@@ -703,3 +703,66 @@ describe('runAgenticLoop — currentBoard / selectedRefids 전달', () => {
     expect(receivedComponents).toEqual([{ refid: 7 }])
   })
 })
+
+describe('runAgenticLoop — 접지 근거 수집', () => {
+  test('도구 결과 원문을 groundedTexts 에 담는다 — 압축본(toolUsages.result)이 아니라 원문이어야 한다', async () => {
+    let callCount = 0
+    const input = mkInput(
+      {
+        chat: async () => {
+          callCount++
+          return callCount === 1 ? okResult(undefined, [TC('getTwinStructure', {})]) : okResult('done')
+        }
+      },
+      {
+        isReadTool: () => true,
+        executeReadTool: () => ({ nodes: [{ id: 'dock-1' }, { id: 'dock-2' }] }),
+        /* 표시용 압축이 식별자를 잘라내도 근거는 온전해야 한다. */
+        summarizeToolResult: () => ({ nodes: '…(생략)' })
+      }
+    )
+    const r = await runAgenticLoop(input)
+    expect(r.groundedTexts).toEqual([JSON.stringify({ nodes: [{ id: 'dock-1' }, { id: 'dock-2' }] })])
+    expect(r.toolUsages[0].result).toEqual({ nodes: '…(생략)' })
+  })
+
+  test('도구를 부르지 않으면 근거가 비어 있다 — 그 답은 접지될 수 없다', async () => {
+    const r = await runAgenticLoop(mkInput({ chat: async () => okResult('바쁘게 움직이고 있습니다') }))
+    expect(r.groundedTexts).toEqual([])
+  })
+})
+
+describe('runAgenticLoop — 첫 턴 도구 강제(근거 없는 단언 차단)', () => {
+  /** 각 iteration 의 toolChoice 를 기록하는 mock. */
+  const recordChoices = (turns: number) => {
+    const choices: any[] = []
+    let i = 0
+    return {
+      choices,
+      chat: async (_m: any, _t: any, opts: any) => {
+        choices.push(opts.toolChoice)
+        i++
+        return i < turns ? okResult(undefined, [TC('getSelection', {})]) : okResult('done')
+      }
+    }
+  }
+
+  test('켜면 첫 턴만 required, 두 번째부터 auto — 조회 결과를 받고도 또 부르지 않게', async () => {
+    const rec = recordChoices(2)
+    await runAgenticLoop(
+      mkInput(
+        { chat: rec.chat, options: { systemPrompt: 'x', requireToolOnFirstTurn: true } },
+        { isReadTool: () => true, executeReadTool: () => ({ ok: 1 }) }
+      )
+    )
+    expect(rec.choices).toEqual(['required', 'auto'])
+  })
+
+  test('끄면 기존 그대로 auto — 라이브 상태를 다루지 않는 대화면은 강제하지 않는다', async () => {
+    const rec = recordChoices(2)
+    await runAgenticLoop(
+      mkInput({ chat: rec.chat }, { isReadTool: () => true, executeReadTool: () => ({ ok: 1 }) })
+    )
+    expect(rec.choices).toEqual(['auto', 'auto'])
+  })
+})

package/server/service/agentic-loop.ts

@@ -64,6 +64,17 @@ export interface AgenticLoopOptions {
    * LLM 이 같은 잘못을 무한 반복하는 경우 방어.
    */
   repeatedFailureLimit?: number
+  /**
+   * **첫 턴에 도구 호출을 강제**한다(toolChoice: 'required'). 두 번째 턴부터는 자유(auto).
+   *
+   * 왜: 접지 가드는 답이 지어낸 **식별자**를 잡지만, 식별자 없이 지어낸 **상황 서술**은 잡지 못한다
+   * ("지게차들이 바쁘게 움직이고 있다" — 실제로 이 답이 나왔다). 그건 도구를 아예 부르지 않고 답한
+   * 경우이고, 사후 검사로는 막을 수 없다. 첫 턴에 무엇이든 조회하게 만들면 근거 없이 상태를 단언할
+   * 길이 없어진다 — 개념·사용법 질문도 문서 조회 도구로 답하므로 막히지 않는다.
+   *
+   * 대화면이 정한다(라이브 상태를 다루는 면에서만 켠다) — 여기서 질문 내용을 눈치로 분류하지 않는다.
+   */
+  requireToolOnFirstTurn?: boolean
 }
 
 export interface AgenticLoopInput {
@@ -86,6 +97,13 @@ export interface AgenticLoopResult {
   accumulatedWriteCalls: AIToolCall[]
   accumulatedActions: BoardActionOp[]
   toolUsages: ToolUsage[]
+  /**
+   * LLM 에게 실제로 회신된 도구 결과 문자열(시간순) — **접지 판정의 근거집합**.
+   *
+   * `toolUsages[].result` 를 쓰면 안 된다: 그건 UI 표시용으로 압축된(잘린) 값이라 근거로 삼으면
+   * 잘려 나간 식별자를 "근거 없음" 으로 오판한다. 여기 담기는 것은 tool_result 로 보낸 원문 그대로다.
+   */
+  groundedTexts: string[]
   /** LLM 마지막 응답의 stopReason. provider-specific 문자열. */
   stopReason: string
   /**
@@ -132,6 +150,8 @@ export async function runAgenticLoop(
   const accumulatedWriteCalls: AIToolCall[] = []
   const accumulatedActions: BoardActionOp[] = []
   const toolUsages: ToolUsage[] = []
+  /* 접지 근거 — tool_result 로 LLM 에 보낸 원문(압축 전). 호출부가 답의 접지를 검사한다. */
+  const groundedTexts: string[] = []
   let lastText: string | undefined
   let stopReason: string = 'end_turn'
   let abortReason: AgenticLoopResult['abortReason']
@@ -158,7 +178,8 @@ export async function runAgenticLoop(
         model: options.model,
         temperature: options.temperature,
         maxTokens: options.maxTokens,
-        toolChoice: 'auto',
+        /* 첫 턴만 강제 — 이후는 자유. 계속 강제하면 조회 결과를 받아 놓고도 답을 못 쓰고 도구를 또 부른다. */
+        toolChoice: iter === 0 && options.requireToolOnFirstTurn ? 'required' : 'auto',
         allowParallelToolCalls: true,
         signal
       })
@@ -206,6 +227,11 @@ export async function runAgenticLoop(
       toolUsages
     )
 
+    /* 접지 근거 누적 — 모델이 tool_result 로 받은 원문 그대로. 압축 전 값이어야 한다(위 필드 주석). */
+    for (const part of toolResultParts) {
+      if (typeof part?.content === 'string') groundedTexts.push(part.content)
+    }
+
     // (4) 같은 tool 의 validation 실패 연속 감지 — LLM 이 같은 잘못 반복 시 abort
     const newUsages = toolUsages.slice(beforeUsages)
     const repeatedFailureAbort = detectRepeatedValidationFailure(
@@ -264,6 +290,7 @@ export async function runAgenticLoop(
     accumulatedWriteCalls,
     accumulatedActions,
     toolUsages,
+    groundedTexts,
     stopReason,
     abortReason
   }

package/server/service/assistant.ts

@@ -34,6 +34,7 @@ import { resolveCatalogMentions } from './catalog-resolver'
 // 직접 import 안 함 — 신규 styling tool 추가 시 registry 에만 spec 추가하면 됨.
 import { buildComponentStyleSummary } from './styling/read-tools'
 import { runAgenticLoop, type AgenticLoopResult } from './agentic-loop'
+import { checkReplyGrounding } from './grounding'
 import { collectAllComponents, findComponentByRefid } from './component-tree'
 import {
   isStylingTool,
@@ -222,7 +223,9 @@ export class DefaultBoardAIAssistant implements BoardAIAssistant {
         systemPrompt,
         model: options.model,
         temperature: options.temperature,
-        maxTokens: options.maxTokens
+        maxTokens: options.maxTokens,
+        /* 라이브 상태를 다루는 대화면은 첫 턴에 조회를 강제한다 — 근거 없이 상태를 단언할 길을 막는다. */
+        requireToolOnFirstTurn: options.requireGroundingTools
       },
       chat: (msgs, tools, opts) => this.base.chatWithTools!(msgs, tools, opts),
       dispatch: {
@@ -267,12 +270,22 @@ export class DefaultBoardAIAssistant implements BoardAIAssistant {
       }
     }
 
+    /* 접지 검사 — 답이 **모델이 받은 것** 밖의 식별자를 지목했는지. 답은 고치지 않고 경고만 낸다.
+     * 근거집합의 정의와 사정거리는 ./grounding 머리말 참조(식별자 없는 창작 서술은 잡지 못한다). */
+    const warnings = checkReplyGrounding(baseReply, {
+      systemPrompt,
+      boardContext,
+      messages: messages.map(m => (typeof m.content === 'string' ? m.content : '')),
+      toolResults: loopResult.groundedTexts
+    })
+
     return {
       reply,
       patch,
       followUp: undefined,
       toolUsages: toolUsages.length > 0 ? toolUsages : undefined,
-      actions: accumulatedActions.length > 0 ? accumulatedActions : undefined
+      actions: accumulatedActions.length > 0 ? accumulatedActions : undefined,
+      groundingWarnings: warnings.length > 0 ? warnings : undefined
     }
   }
 

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

@@ -105,6 +105,13 @@ class BoardAIChatInput {
   })
   boardTools?: boolean
 
+  @Field({
+    nullable: true,
+    description:
+      'Force a tool call on the first turn (toolChoice: required). Turn this on for surfaces that discuss live state: the grounding guard catches invented identifiers but not an invented situation stated without any, which only happens when the model answers without querying at all. Concept / how-to questions are unaffected — they are answered through a documentation tool.'
+  })
+  requireGroundingTools?: boolean
+
   @Field(() => [String], {
     nullable: true,
     description: 'Component types the LLM is allowed to emit (e.g. ["rect", "label"]). Constrains generation to the current solution.'
@@ -196,6 +203,13 @@ class BoardAIChatOutput {
       'Ephemeral scene actions (selection/view/mode) — sequence of BoardActionOp. Applied via board-action-execute event on the host. Distinct from `patch` which carries persistent model changes.'
   })
   actions?: any
+
+  @Field(() => GraphQLJSON, {
+    nullable: true,
+    description:
+      'Ungrounded identifiers mentioned by the reply — present in the answer but absent from everything the model received (prompt, board context, history, tool results). Hallucination candidates surfaced to the user; the reply itself is not altered. Null when the answer is grounded.'
+  })
+  groundingWarnings?: any
 }
 
 @Resolver()
@@ -341,6 +355,7 @@ export class BoardAIChatResolver {
       /* 대화면별 도구 노출 — 미지정이면 현행(전부 허용) 그대로. */
       toolCategories: input.toolCategories ?? undefined,
       boardTools: input.boardTools ?? undefined,
+      requireGroundingTools: input.requireGroundingTools ?? undefined,
       knownTypes: input.knownTypes,
       categories: input.categories as ComponentCategory[] | undefined,
       selectedRefids: input.selectedRefids,
@@ -385,6 +400,12 @@ export class BoardAIChatResolver {
         content: enrichedReply,
         relatedPatchId: patchEntry?.id,
         toolUsages: r.toolUsages && r.toolUsages.length > 0 ? JSON.stringify(r.toolUsages) : undefined,
+        /* 접지 경고를 함께 영속 — 나중에 읽는 참여자도 같은 주의를 봐야 한다(재계산 불가: 근거 원문이 남지 않는다).
+         * 컬럼 길이(1024) 안에 들도록 앞 20개까지만 — 그 이상이면 목록이 아니라 답 자체가 문제다. */
+        groundingWarnings:
+          r.groundingWarnings && r.groundingWarnings.length > 0
+            ? JSON.stringify(r.groundingWarnings.slice(0, 20))
+            : undefined,
         // assistant 메시지의 creator = 이 응답을 트리거한 user (= 직전 user 메시지의 작성자).
         // 같은 turn 으로 묶임 → 향후 사용자별 필터에서 user/assistant 가 함께 따라옴.
         creator: user,
@@ -426,7 +447,8 @@ export class BoardAIChatResolver {
       assistantMessageId,
       patchId,
       toolUsages: r.toolUsages ?? null,
-      actions: r.actions && r.actions.length > 0 ? r.actions : null
+      actions: r.actions && r.actions.length > 0 ? r.actions : null,
+      groundingWarnings: r.groundingWarnings && r.groundingWarnings.length > 0 ? r.groundingWarnings : null
     }
   }
 

package/server/service/chat-message/chat-message.ts

@@ -107,6 +107,32 @@ export class ChatMessage {
     }
   }
 
+  /**
+   * 접지 경고 — 이 답이 언급했으나 근거(프롬프트·보드 문맥·이력·도구 결과)에 없던 식별자 목록.
+   *
+   * **왜 영속하는가**: 도크의 협의는 여러 사람이 며칠에 걸쳐 읽는다. 경고가 그 자리에서만
+   * 보이고 새로 고치면 사라지면, 나중에 읽는 사람은 검증되지 않은 문장을 검증된 것으로 읽는다.
+   * 다시 계산할 수도 없다 — 근거였던 도구 결과 원문은 남지 않고 압축본만 남기 때문이다.
+   *
+   * 형태: string[] 를 JSON-stringify. 비었으면 null(= 접지 정상).
+   */
+  @Column({ type: 'varchar', length: 1024, nullable: true })
+  groundingWarnings?: string
+
+  /** GraphQL 노출용 — 식별자 배열로 parse. */
+  @Field(() => GraphQLJSON, {
+    nullable: true,
+    description: 'Ungrounded identifiers mentioned by this reply (hallucination candidates). Null when grounded.'
+  })
+  get groundingWarningsJson(): any {
+    if (!this.groundingWarnings) return null
+    try {
+      return JSON.parse(this.groundingWarnings)
+    } catch {
+      return null
+    }
+  }
+
   /**
    * 메시지를 일으킨 사용자.
    *   - role='user' → 보낸 사용자

package/server/service/chat-session/session-inbox.test.ts

@@ -11,7 +11,7 @@
  *
  * 집계 쿼리를 쓰지 않는 설계라(5개 DB 드라이버) 판정이 전부 값 비교로 끝난다 — 그래서 순수 테스트가 된다.
  */
-import { buildInbox, countUnreadSessions, activityPatch } from './session-inbox'
+import { buildInbox, countUnreadSessions, activityPatch, applyHidden, searchInbox } from './session-inbox'
 
 const t = (iso: string) => new Date(iso)
 
@@ -115,3 +115,71 @@ describe('활동 갱신 값', () => {
     expect(activityPatch('').lastMessagePreview).toBe('')
   })
 })
+
+describe('applyHidden — 내 목록에서만 숨기기', () => {
+  const entry = (id: string, lastMessageAt?: string): any => ({
+    id,
+    lastMessageAt,
+    unread: false,
+    participant: true
+  })
+
+  it('숨긴 대화는 기본 목록에서 빠진다', () => {
+    const out = applyHidden([entry('a', '2026-07-30T01:00:00Z'), entry('b')], new Map([['a', '2026-07-30T02:00:00Z']]))
+    expect(out.map(e => e.id)).toEqual(['b'])
+  })
+
+  it('숨긴 뒤 새 활동이 생기면 다시 보인다 — 참여 중인 대화에서 조용히 잘려 나가지 않게', () => {
+    const out = applyHidden([entry('a', '2026-07-30T03:00:00Z')], new Map([['a', '2026-07-30T02:00:00Z']]))
+    expect(out.map(e => e.id)).toEqual(['a'])
+    expect(out[0].hidden).toBeUndefined()
+  })
+
+  it('필터를 켜면 숨긴 것도 표시와 함께 돌려준다 — 되돌릴 수 있어야 한다', () => {
+    const out = applyHidden(
+      [entry('a', '2026-07-30T01:00:00Z'), entry('b')],
+      new Map([['a', '2026-07-30T02:00:00Z']]),
+      true
+    )
+    expect(out.map(e => e.id)).toEqual(['a', 'b'])
+    expect(out[0].hidden).toBe(true)
+    expect(out[1].hidden).toBeUndefined()
+  })
+
+  it('숨김 기록이 없으면 아무것도 바꾸지 않는다', () => {
+    const entries = [entry('a'), entry('b')]
+    expect(applyHidden(entries, new Map())).toEqual(entries)
+  })
+})
+
+describe('searchInbox — 대량 목록의 풀텍스트 필터', () => {
+  const rows: any[] = [
+    { id: 'a', name: 'A-DC 포화 원인', lastMessagePreview: '점유율이 92% 입니다', unread: false, participant: true },
+    { id: 'b', name: 'Dock 배치 검토', lastMessagePreview: '입고 도크를 늘리면', unread: false, participant: true },
+    { id: 'c', lastMessagePreview: '이름 없는 대화', unread: false, participant: true }
+  ]
+
+  it('이름으로 찾는다', () => {
+    expect(searchInbox(rows, '포화').map(e => e.id)).toEqual(['a'])
+  })
+
+  it('미리보기 본문으로도 찾는다 — 제목만으로는 돌아갈 대화를 못 찾는다', () => {
+    expect(searchInbox(rows, '입고').map(e => e.id)).toEqual(['b'])
+  })
+
+  it('대소문자를 무시한다', () => {
+    expect(searchInbox(rows, 'dock').map(e => e.id)).toEqual(['b'])
+  })
+
+  it('이름이 없는 대화도 미리보기로 걸린다', () => {
+    expect(searchInbox(rows, '이름 없는').map(e => e.id)).toEqual(['c'])
+  })
+
+  it('빈 검색어는 전체를 그대로 돌려준다(필터 없음)', () => {
+    expect(searchInbox(rows, '   ')).toBe(rows)
+  })
+
+  it('맞는 것이 없으면 빈 목록 — 조용히 전체를 보여주지 않는다', () => {
+    expect(searchInbox(rows, 'zzz')).toEqual([])
+  })
+})

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

@@ -31,6 +31,8 @@ export interface InboxSessionRow {
 export interface MyParticipation {
   sessionId?: string
   lastReadAt?: Date | string | null
+  /** 내 목록에서 숨긴 시각 — 이후 새 활동이 생기면 다시 보인다. */
+  hiddenAt?: Date | string | null
 }
 
 export interface InboxEntry extends InboxSessionRow {
@@ -38,6 +40,8 @@ export interface InboxEntry extends InboxSessionRow {
   unread: boolean
   /** 내가 참여자인가 — 아니면 열어볼 수는 있어도 읽음 상태를 갖지 않는다. */
   participant: boolean
+  /** 내가 숨긴 대화인가 — 목록에서 빠지지만 필터로 볼 수 있다(되돌리기 가능). */
+  hidden?: boolean
 }
 
 function time(v: Date | string | null | undefined): number {
@@ -83,6 +87,47 @@ export function buildInbox(sessions: InboxSessionRow[], mine: MyParticipation[])
   )
 }
 
+/**
+ * 숨김 표시·필터.
+ *
+ * 숨김은 **나에게만** 적용되고 되돌릴 수 있다. 숨긴 **뒤에 새 활동이 생기면 다시 보인다** —
+ * 아직 참여 중인 대화에서 조용히 잘려 나가는 것이 목록 한 줄보다 나쁘다.
+ *
+ * `showHidden` 이면 숨긴 것도 함께 돌려주되 표시(hidden)를 남긴다 — 필터를 켠 사용자가 무엇이
+ * 숨겨진 것인지 알아야 되돌릴 수 있다.
+ */
+export function applyHidden(entries: InboxEntry[], hiddenAt: Map<string, Date | string | null | undefined>, showHidden = false): InboxEntry[] {
+  const out: InboxEntry[] = []
+  for (const entry of entries) {
+    const at = hiddenAt.get(entry.id ?? '')
+    /* 숨긴 시각보다 **뒤에** 활동이 있으면 숨김은 풀린 것으로 본다. */
+    const hidden = !!at && time(entry.lastMessageAt) <= time(at)
+    if (hidden && !showHidden) continue
+    out.push(hidden ? { ...entry, hidden: true } : entry)
+  }
+  return out
+}
+
+/**
+ * 검색 — 이름과 마지막 미리보기에 대한 대소문자 무시 부분일치.
+ *
+ * **왜 메모리에서 하는가**: 이 프레임워크는 5개 DB 드라이버를 지원한다. 대소문자 무시 검색은
+ * 드라이버마다 표기가 갈리고(ILIKE=pg 전용, LOWER()+LIKE 는 되지만 정렬·NULL 취급이 또 갈린다),
+ * 목록 경로에 드라이버별 SQL 을 두는 것은 이 프로젝트의 규율에 반한다. 그래서 조회는 앵커로
+ * **상한을 두고** 가져오고(아래 INBOX_SCAN_CAP) 걸러내기·정렬·페이지는 여기서 한다.
+ * 상한을 넘으면 잘렸다는 사실을 그대로 알린다(조용히 일부만 보여주지 않는다).
+ */
+export function searchInbox(entries: InboxEntry[], search?: string): InboxEntry[] {
+  const q = (search ?? '').trim().toLowerCase()
+  if (!q) return entries
+  return entries.filter(e =>
+    `${e.name ?? ''}\n${e.lastMessagePreview ?? ''}`.toLowerCase().includes(q)
+  )
+}
+
+/** 한 번에 훑는 세션 상한 — 이보다 많으면 잘렸다고 알린다(정직). */
+export const INBOX_SCAN_CAP = 500
+
 /** 안 읽은 세션 수 — 도크 버튼 배지(개수가 아니라 **세션 수**). */
 export function countUnreadSessions(entries: InboxEntry[]): number {
   return entries.filter(e => e.unread).length

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

@@ -93,6 +93,20 @@ export class ChatSessionParticipant {
   @Field({ nullable: true, description: 'Point up to which this participant has read the session. Distinct from lastSeenAt (presence): a window can be open without being read, and the read point survives disconnection. Null means nothing read yet.' })
   lastReadAt?: Date
 
+  /**
+   * 이 사용자가 **자기 목록에서 숨긴 시각**. 숨김은 **나에게만** 적용된다 — 남의 목록·대화 내용은 그대로다.
+   *
+   * 왜 삭제와 나누는가: 협의는 여럿의 기록이므로 지우는 것은 **만든 사람**만 할 수 있다(되돌릴 수 없다).
+   * 그 권한이 없는 사람에게도 "내 목록을 정리할" 방법은 있어야 하고, 그것이 숨김이다.
+   *
+   * 숨긴 **뒤에 새 활동이 생기면 다시 나타난다** — 아직 참여자인 대화에서 조용히 잘려 나가는 것이
+   * 목록이 한 줄 늘어나는 것보다 나쁘다. 완전히 빠지려면 대화에서 나가야 한다(별개 기능).
+   * nullable — 값이 없으면 숨기지 않은 상태.
+   */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'When this user hid the session from their own list. Per-user only; the session and other participants are unaffected. Activity newer than this timestamp makes it reappear.' })
+  hiddenAt?: Date
+
   @ManyToOne(type => User)
   @Field(type => User, { nullable: true, description: 'User who created this participant record (typically session owner who invited).' })
   creator?: User