@things-factory/board-ai 10.0.0 → 10.0.2

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

@@ -14,7 +14,7 @@ import { In } from 'typeorm'
 
 import { ChatSession } from './chat-session/chat-session.js'
 import { anchorColumns, anchorWhere } from './chat-session/session-anchor.js'
-import { buildInbox, activityPatch } from './chat-session/session-inbox.js'
+import { buildInbox, applyHidden, activityPatch, searchInbox, INBOX_SCAN_CAP } from './chat-session/session-inbox.js'
 import { publishSessionActivity } from './chat-session/session-activity-publish.js'
 import { ChatMessage } from './chat-message/chat-message.js'
 import { ChatSessionParticipant } from './chat-session-participant/chat-session-participant.js'
@@ -56,6 +56,15 @@ class ChatSessionInboxEntry {
 
   @Field({ description: 'Whether this viewer is a participant of the session (non-participants get no unread state).' })
   participant!: boolean
+
+  /* 삭제는 되돌릴 수 없으므로 **만든 사람**만 한다 — 클라이언트가 버튼을 보일지 판단하는 근거.
+   * (권한 판정은 서버가 다시 한다. 이 값은 UI 힌트일 뿐이다.) */
+  @Field({ description: 'Whether this viewer created the session — only the creator may delete it.' })
+  mine!: boolean
+
+  /* 숨김은 나에게만 적용되고 되돌릴 수 있다 — 필터를 켠 사용자가 무엇이 숨겨진 것인지 알아야 한다. */
+  @Field({ nullable: true, description: 'Whether this viewer hid the session from their own list (only returned when showHidden is on).' })
+  hidden?: boolean
 }
 
 @Resolver()
@@ -118,23 +127,190 @@ export class ChatSessionResolver {
    */
   @Query(() => [ChatSessionInboxEntry], {
     description:
-      "List sessions anchored to a target with this viewer's unread state, ordered by recent activity. Uses the denormalized last-activity timestamp compared against the viewer's read point — no per-session aggregation."
+      "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: "board-ai", privilege: "query")')
   async chatSessionInbox(
+    @Arg('anchorType') anchorType: string,
+    @Arg('anchorId') anchorId: string,
+    @Ctx() context: ResolverContext,
+    /* 숨긴 대화 보기 — 숨김이 한 번 넣으면 못 꺼내는 함정이 되지 않도록 필터를 준다. */
+    @Arg('showHidden', { nullable: true }) showHidden?: boolean,
+    /* 대량 목록 대응 — 검색·소유 필터·페이지. 목록 UI 는 처음부터 이걸 갖고 있어야 한다. */
+    @Arg('search', { nullable: true }) search?: string,
+    @Arg('mineOnly', { nullable: true }) mineOnly?: boolean,
+    @Arg('limit', () => Int, { nullable: true }) limit?: number,
+    @Arg('offset', () => Int, { nullable: true }) offset?: number
+  ): Promise<ChatSessionInboxEntry[]> {
+    const filtered = await this._inboxFiltered(anchorType, anchorId, context, { showHidden, search, mineOnly })
+    const from = Math.max(0, offset ?? 0)
+    const size = Math.min(Math.max(1, limit ?? 50), 200)
+    return filtered.slice(from, from + size) as any
+  }
+
+  /**
+   * 필터를 통과한 **전체 개수** — "더 보기" 가 남았는지, 검색 결과가 몇 건인지.
+   *
+   * 목록과 같은 요청에 담아 가져가므로 왕복은 늘지 않는다. 개수를 모르면 사용자는 목록의 끝이
+   * 페이지의 끝인지 자료의 끝인지 구별할 수 없다.
+   */
+  @Query(() => Int, {
+    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: "board-ai", privilege: "query")')
+  async chatSessionInboxTotal(
+    @Arg('anchorType') anchorType: string,
+    @Arg('anchorId') anchorId: string,
+    @Ctx() context: ResolverContext,
+    @Arg('showHidden', { nullable: true }) showHidden?: boolean,
+    @Arg('search', { nullable: true }) search?: string,
+    @Arg('mineOnly', { nullable: true }) mineOnly?: boolean
+  ): Promise<number> {
+    return (await this._inboxFiltered(anchorType, anchorId, context, { showHidden, search, mineOnly })).length
+  }
+
+  /** 필터 적용(페이지 전) — 목록·개수가 **같은 규칙**을 쓰도록 한 곳에 둔다(어긋나면 "더 보기" 가 거짓말이 된다). */
+  private async _inboxFiltered(
+    anchorType: string,
+    anchorId: string,
+    context: ResolverContext,
+    opts: { showHidden?: boolean; search?: string; mineOnly?: boolean }
+  ): Promise<ChatSessionInboxEntry[]> {
+    const all = await this._inboxEntries(anchorType, anchorId, context)
+    let entries = opts.showHidden ? all : all.filter(e => !e.hidden)
+    if (opts.mineOnly) entries = entries.filter(e => (e as any).mine)
+    return searchInbox(entries as any, opts.search) as any
+  }
+
+  /**
+   * 내가 숨긴 대화 수 — 필터에 "몇 개가 접혀 있는지" 를 보여주기 위한 값.
+   *
+   * 숨긴 것이 몇 개인지 모르면 필터를 눌러 볼 이유가 생기지 않는다(숨긴 사실 자체를 잊는다).
+   * 목록 조회와 **같은 요청**에 담아 가져갈 수 있으므로 왕복은 늘지 않는다.
+   */
+  @Query(() => Int, {
+    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: "board-ai", privilege: "query")')
+  async hiddenSessionCount(
     @Arg('anchorType') anchorType: string,
     @Arg('anchorId') anchorId: string,
     @Ctx() context: ResolverContext
+  ): Promise<number> {
+    const all = await this._inboxEntries(anchorType, anchorId, context)
+    return all.filter(e => e.hidden).length
+  }
+
+  /** 목록 조립 — 숨김 표시까지 붙인 **전체**. 목록·개수 두 진입점이 같은 규칙을 쓰도록 한 곳에 둔다. */
+  private async _inboxEntries(
+    anchorType: string,
+    anchorId: string,
+    context: ResolverContext
   ): Promise<ChatSessionInboxEntry[]> {
     const { domain, user } = context.state
+    /* 조회 상한 — 한 앵커의 대화가 아무리 늘어도 한 번에 이만큼만 훑는다. 최근 활동순으로 자른다
+     * (오래된 대화가 잘리는 것이 최근 대화가 잘리는 것보다 낫다). 정렬·검색·페이지는 순수 로직이 한다. */
     const sessions = await getRepository(ChatSession).find({
-      where: anchorWhere(domain.id, anchorType, anchorId)
+      where: anchorWhere(domain.id, anchorType, anchorId),
+      order: { lastMessageAt: 'DESC' },
+      take: INBOX_SCAN_CAP
     })
     if (sessions.length === 0) return []
-    const mine = await getRepository(ChatSessionParticipant).find({
+    const rows = await getRepository(ChatSessionParticipant).find({
       where: { domain: { id: domain.id } as any, user: { id: user.id } as any, session: { id: In(sessions.map(s => s.id!)) } as any }
     })
-    return buildInbox(sessions as any, mine as any) as any
+    /* 'viewer' 는 대화에 낀 사람이 아니다 — 숨김을 기록하려고 만든 행이므로 읽음·안 읽음 판정에서 뺀다.
+     * (참여자가 아닌 사람에게 남의 협의 배지를 띄우지 않는다.) */
+    const participations = rows.filter(r => r.role !== 'viewer')
+    const hiddenAt = new Map(rows.map(r => [(r as any).sessionId as string, r.hiddenAt]))
+    /* 내가 만든 대화인지 표시 — 삭제 버튼을 보일지 결정하는 UI 힌트(권한은 서버가 다시 판정한다). */
+    const createdByMe = new Set(sessions.filter(s => (s as any).creatorId === user?.id).map(s => s.id))
+    const entries = buildInbox(sessions as any, participations as any).map(entry => ({
+      ...entry,
+      mine: createdByMe.has(entry.id)
+    }))
+    /* showHidden=true 로 불러 **전체**를 얻는다 — 숨김 여부 판정을 두 곳에 복제하지 않기 위함. */
+    return applyHidden(entries as any, hiddenAt, true) as any
+  }
+
+  /**
+   * 세션 삭제 — **만든 사람만.**
+   *
+   * 협의는 여럿의 기록이고 삭제는 화면에서 되돌릴 수 없다. 그래서 권한을 좁힌다(이름 변경은 되돌릴 수
+   * 있어서 누구나 할 수 있는 것과 대비). 권한이 없는 사람에게는 `hideAISession`(내 목록에서만 숨김)이
+   * 있다 — 남의 기록을 지우지 않고 자기 목록을 정리하는 길.
+   *
+   * 소프트 삭제(deletedAt)다 — 메시지·패치는 세션을 통해서만 도달하므로 함께 사라지고, 잘못 지운 경우
+   * 데이터로는 남아 있다. 다른 참여자 목록에서도 사라져야 하므로 meta 활동으로 방송한다.
+   */
+  @Mutation(() => Boolean, {
+    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: "board-ai", privilege: "mutation")')
+  async deleteAISession(@Arg('sessionId') sessionId: string, @Ctx() context: ResolverContext): Promise<boolean> {
+    const { domain, user } = context.state
+    const repo = getRepository(ChatSession)
+    const session = await repo.findOneBy({ id: sessionId, domain: { id: domain.id } as any })
+    if (!session) return false
+    if (!user?.id || (session as any).creatorId !== user.id) {
+      /* 조용한 무동작이 아니라 명시 실패 — 지워진 줄 알고 넘어가면 안 된다. */
+      throw new Error('Only the user who created this session may delete it. Hide it from your own list instead.')
+    }
+    await repo.softDelete(sessionId)
+    publishSessionActivity({
+      domainId: domain.id,
+      sessionId,
+      kind: 'meta',
+      anchorType: (session as any).anchorType,
+      anchorId: (session as any).anchorId,
+      actorId: user?.id
+    })
+    return true
+  }
+
+  /**
+   * 내 목록에서 숨기기·되돌리기 — **나에게만** 적용된다(대화·다른 참여자 목록은 그대로).
+   *
+   * 참여자가 아니어도 숨길 수 있어야 한다 — 목록에는 같은 공간의 남의 협의도 보이고, 그것을 정리하는
+   * 것은 남에게 아무 영향이 없다. 그 경우 'viewer' 역할로 기록만 남긴다(참여자 명부·배지에는 들지 않는다).
+   */
+  @Mutation(() => Boolean, {
+    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: "board-ai", privilege: "mutation")')
+  async hideAISession(
+    @Arg('sessionId') sessionId: string,
+    @Ctx() context: ResolverContext,
+    @Arg('hidden', { nullable: true }) hidden?: boolean
+  ): Promise<boolean> {
+    const { domain, user } = context.state
+    if (!user?.id) return false
+    const session = await getRepository(ChatSession).findOneBy({ id: sessionId, domain: { id: domain.id } as any })
+    if (!session) return false
+    const repo = getRepository(ChatSessionParticipant)
+    const existing = await repo.findOne({
+      where: { domain: { id: domain.id } as any, session: { id: sessionId } as any, user: { id: user.id } as any }
+    })
+    const hiddenAt = hidden === false ? null : new Date()
+    if (existing) {
+      await repo.update(existing.id!, { hiddenAt, updater: user } as any)
+    } else {
+      if (hidden === false) return true // 숨긴 적이 없으면 되돌릴 것도 없다
+      await repo.save({
+        domain: { id: domain.id } as any,
+        session: { id: sessionId } as any,
+        user: { id: user.id } as any,
+        role: 'viewer', // 대화에 낀 것이 아니라 숨김만 기록한다
+        hiddenAt,
+        creator: user,
+        updater: user
+      } as any)
+    }
+    return true
   }
 
   /**
@@ -407,6 +583,122 @@ export class ChatSessionResolver {
     return true
   }
 
+  @Directive('@transaction')
+  @Mutation(() => Boolean, {
+    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: "board-ai", privilege: "mutation")')
+  async appendSessionNote(
+    @Arg('sessionId') sessionId: string,
+    @Arg('content') content: string,
+    @Ctx() context: ResolverContext
+  ): Promise<boolean> {
+    const { domain, user, tx } = 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 body = (content ?? '').trim().slice(0, 4000)
+    if (!body) return false
+
+    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: body,
+      creator: user,
+      updater: user,
+      parentMessage: previousLast ? ({ id: previousLast.id } as any) : undefined
+    } as any)
+
+    /* 활동 갱신 + 방송 — 다른 참여자 목록·안 읽음과 열려 있는 화면의 transcript 일관성. best-effort. */
+    try {
+      await getRepository(ChatSession, tx).update(session.id!, activityPatch(body) as any)
+    } catch {
+      /* 기록 자체를 막지 않는다 */
+    }
+    publishSessionActivity({
+      domainId: domain.id,
+      sessionId: session.id!,
+      kind: 'message',
+      anchorType: (session as any).anchorType,
+      anchorId: (session as any).anchorId,
+      preview: body,
+      actorId: user?.id
+    })
+    publishChatMessage({ domainId: domain.id, sessionId: session.id, message: sysMsg })
+    return true
+  }
+
+  @Directive('@transaction')
+  @Mutation(() => Boolean, {
+    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: "board-ai", privilege: "mutation")')
+  async appendSessionTurns(
+    @Arg('sessionId') sessionId: string,
+    @Arg('turns', () => GraphQLJSON) turns: { role?: string; content?: string }[],
+    @Ctx() context: ResolverContext
+  ): Promise<boolean> {
+    const { domain, user, tx } = 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 rows = (Array.isArray(turns) ? turns : [])
+      .map(t => ({
+        role: t?.role === 'ai' || t?.role === 'assistant' ? 'assistant' : t?.role === 'user' ? 'user' : 'system',
+        content: (t?.content ?? '').trim().slice(0, 4000)
+      }))
+      .filter(t => t.content)
+      .slice(-40)
+    if (!rows.length) return false
+
+    let previous = await getRepository(ChatMessage, tx).findOne({
+      where: { session: { id: session.id } as any },
+      order: { createdAt: 'DESC' }
+    })
+    const saved: ChatMessage[] = []
+    for (const row of rows) {
+      previous = await getRepository(ChatMessage, tx).save({
+        session: { id: session.id } as any,
+        role: row.role,
+        content: row.content,
+        creator: user,
+        updater: user,
+        parentMessage: previous ? ({ id: previous.id } as any) : undefined
+      } as any)
+      saved.push(previous!)
+    }
+
+    /* 활동은 마지막 발언 기준 한 번만 — 옮긴 줄마다 목록을 흔들 이유가 없다. */
+    const last = rows[rows.length - 1]
+    try {
+      await getRepository(ChatSession, tx).update(session.id!, activityPatch(last.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: last.content,
+      actorId: user?.id
+    })
+    for (const message of saved) {
+      publishChatMessage({ domainId: domain.id, sessionId: session.id, message })
+    }
+    return true
+  }
+
   @Directive('@transaction')
   @Mutation(() => PatchEntry, {
     description: 'Record a patch from user direct edit. Adds a system message so AI sees the change next turn.'

package/server/service/grounding.test.ts

@@ -0,0 +1,55 @@
+/*
+ * 근거집합의 정의 검증 — 무엇을 "모델이 받은 것" 으로 볼 것인가.
+ *
+ * 판정 규칙(식별자 대조·소음 제거)은 ai-client-base 가 소유하고 그쪽에서 검증한다.
+ * 여기서 지키는 것은 **하나도 빠뜨리지 않는 것**이다 — 근거를 빠뜨리면 정상 답에 경고가 붙고,
+ * 그 오탐이 반복되면 사용자는 경고를 무시한다(가드가 죽는다).
+ */
+import { buildGroundedCorpus, checkReplyGrounding } from './grounding'
+
+describe('buildGroundedCorpus', () => {
+  it('네 갈래를 모두 담는다 — 프롬프트·보드 문맥·이력·도구 결과', () => {
+    const corpus = buildGroundedCorpus({
+      systemPrompt: 'types: dock-door',
+      boardContext: '{"components":[{"id":"gauge-1"}]}',
+      messages: ['aisle-2 상태 알려줘'],
+      toolResults: ['{"nodes":[{"id":"rack-9"}]}']
+    })
+    for (const id of ['dock-door', 'gauge-1', 'aisle-2', 'rack-9']) {
+      expect(corpus).toContain(id)
+    }
+  })
+
+  it('빈 갈래는 건너뛴다 — 근거 없는 대화(즉석 질문)도 성립한다', () => {
+    expect(buildGroundedCorpus({})).toBe('')
+  })
+})
+
+describe('checkReplyGrounding', () => {
+  const sources = {
+    systemPrompt: 'creatable types: dock-door, twin-node',
+    boardContext: '{"components":[{"id":"dock-1","name":"입고 도크"}]}',
+    messages: ['지금 상태 어때?'],
+    toolResults: ['{"instances":[{"instanceId":"hatiolab-wms"}],"nodes":[{"id":"dock-1"}]}']
+  }
+
+  it('도구가 돌려준 대상으로 답하면 경고가 없다', () => {
+    expect(checkReplyGrounding('hatiolab-wms 의 dock-1 은 여유롭습니다.', sources)).toEqual([])
+  })
+
+  it('프롬프트의 타입 이름을 말하는 것은 근거 있는 것이다 — 오탐 방지', () => {
+    expect(checkReplyGrounding('dock-door 컴포넌트를 추가했습니다.', sources)).toEqual([])
+  })
+
+  it('근거 밖의 대상을 지목하면 경고한다', () => {
+    expect(checkReplyGrounding('dock-5 에 적체가 있습니다.', sources)).toEqual(['dock-5'])
+  })
+
+  it('도구를 부르지 않았으면 도구 결과가 근거에 없다 — 그때 언급한 대상은 경고 대상', () => {
+    expect(checkReplyGrounding('rack-3 이 포화입니다.', { ...sources, toolResults: [] })).toEqual(['rack-3'])
+  })
+
+  it('빈 답은 검사하지 않는다', () => {
+    expect(checkReplyGrounding('', sources)).toEqual([])
+  })
+})

package/server/service/grounding.ts

@@ -0,0 +1,53 @@
+/*
+ * 접지 검사 — 이 대화면의 답이 **모델이 실제로 받은 것** 안에서 말했는지.
+ *
+ * ── 왜 board-ai 에 필요한가 ─────────────────────────────────────────────────
+ * 협의 도크(operato-twin)는 board-ai 위에 서 있고, 여기서 사람들이 운영 상태를 묻는다.
+ * 헤더 경로(twin-ai)에는 접지 가드가 있었지만 도크 경로에는 없었다 — 같은 질문에 대해
+ * 한쪽은 검증되고 한쪽은 검증되지 않는 상태였다. 판정 규칙은 공용 모듈이 소유하고
+ * (`@things-factory/ai-client-base` 의 grounding), 이 파일은 **무엇을 근거로 볼 것인가**만 정한다.
+ *
+ * ── 근거집합의 정의 ─────────────────────────────────────────────────────────
+ * 모델이 이 턴에 받은 전부다. 하나라도 빼면 정상 답이 경고를 받는다(오탐):
+ *   · systemPrompt  — 생성 가능한 컴포넌트 타입 목록 등. 여기 있는 이름을 말하는 건 정상이다.
+ *   · boardContext  — 현재 보드 요약(컴포넌트 id·이름). 보드를 두고 말하는 근거.
+ *   · messages      — 사용자·이력 텍스트. 사용자가 말한 식별자를 되받는 건 정상이다.
+ *   · toolResults   — 도구가 돌려준 원문(압축 전). 운영 상태 답의 유일한 사실 근거.
+ *
+ * ── 사정거리 ────────────────────────────────────────────────────────────────
+ * 식별자만 본다. "지게차들이 바쁘게 움직인다" 처럼 **식별자 없이 지어낸 서술**은 잡지 못한다 —
+ * 그건 도구를 부르지 않고 답한 경우이고, 도구 호출을 강제하는 별도 레버의 몫이다.
+ */
+import { groundingWarnings } 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 function checkReplyGrounding(reply: string, sources: GroundingSources): string[] {
+  if (!reply) return []
+  return groundingWarnings(reply, buildGroundedCorpus(sources))
+}

package/server/service/types.ts

@@ -27,6 +27,15 @@ export interface ChatOptions {
    * 되돌릴 수 있는 편집이 한 대화에 섞이지 않게 한다.
    */
   boardTools?: boolean
+  /**
+   * **첫 턴에 도구 호출을 강제**한다. 라이브 상태를 다루는 대화면(운영 협의)에서 켠다.
+   *
+   * 접지 가드는 답이 지어낸 **식별자**를 잡지만, 식별자 없이 지어낸 **상황 서술**은 잡지 못한다
+   * ("지게차들이 바쁘게 움직이고 있다" — 실제로 나온 답이다). 그건 도구를 아예 부르지 않고 답한
+   * 경우여서 사후 검사로 막을 수 없다. 첫 턴에 무엇이든 조회하게 만들면 근거 없이 상태를 단언할
+   * 길이 없어진다. 켜고 끄는 판단은 대화면이 한다 — 서버가 질문 내용을 눈치로 분류하지 않는다.
+   */
+  requireGroundingTools?: boolean
   /**
    * 호스트(대화면)가 실어 보내는 **문맥** — 도구가 ctx.state.host 로 읽는다.
    *
@@ -133,6 +142,13 @@ export interface ChatResponse {
   followUp?: string
   /** AI 가 응답 만드는 과정에서 호출한 도구들 (시간순). UI fold-able 박스용. */
   toolUsages?: ToolUsage[]
+  /**
+   * 접지 경고 — 답이 언급했으나 모델이 받은 근거(프롬프트·보드 문맥·이력·도구 결과)에 없는 식별자.
+   *
+   * 있으면 그 대상은 **만들어 낸 것일 수 있다**. 답을 막거나 고치지 않고 사용자에게 표시한다 —
+   * 판정 규칙·사정거리는 ./grounding 참조. 비면(undefined) 접지 정상.
+   */
+  groundingWarnings?: string[]
 }
 
 export interface BoardEditPatch {

package/translations/en.json

@@ -45,5 +45,7 @@
   "board-ai.text.copied": "Copied",
   "board-ai.text.mention-not-found": "#{token} not found",
   "board-ai.text.session-tab-label": "Session {n}",
-  "board-ai.text.tools-used": "Tools used"
+  "board-ai.text.tools-used": "Tools used",
+  "board-ai.text.ungrounded-mention": "Mentions an unverified target — not present in the actual data:",
+  "board-ai.text.toggle-system-note": "click to expand"
 }

package/translations/ja.json

@@ -44,5 +44,7 @@
   "board-ai.text.copied": "コピーしました",
   "board-ai.text.mention-not-found": "#{token} が見つかりません",
   "board-ai.text.session-tab-label": "セッション {n}",
-  "board-ai.text.tools-used": "使用したツール"
+  "board-ai.text.tools-used": "使用したツール",
+  "board-ai.text.ungrounded-mention": "確認できない対象に言及しています — 実データにありません:",
+  "board-ai.text.toggle-system-note": "クリックで展開"
 }

package/translations/ko.json

@@ -23,6 +23,8 @@
   "board-ai.text.failed-to-load-history": "이력 로드 실패",
   "board-ai.text.empty-response": "응답이 비어있습니다.",
   "board-ai.text.tools-used": "도구 사용",
+  "board-ai.text.ungrounded-mention": "확인되지 않은 대상을 언급했습니다 — 실제 데이터에 없습니다:",
+  "board-ai.text.toggle-system-note": "눌러서 펼치기",
 
   "board-ai.example.create-monitoring-dashboard": "가동률·온도·압력 3개 게이지와 24시간 라인 차트로 모니터링 대시보드",
   "board-ai.example.create-welcome-screen": "큰 'OPERATO' 제목과 시계, 부제로 환영 화면",

package/translations/ms.json

@@ -44,5 +44,7 @@
   "board-ai.text.copied": "Disalin",
   "board-ai.text.mention-not-found": "#{token} tidak dijumpai",
   "board-ai.text.session-tab-label": "Sesi {n}",
-  "board-ai.text.tools-used": "Alat yang digunakan"
+  "board-ai.text.tools-used": "Alat yang digunakan",
+  "board-ai.text.ungrounded-mention": "Menyebut sasaran yang tidak disahkan — tiada dalam data sebenar:",
+  "board-ai.text.toggle-system-note": "klik untuk kembangkan"
 }

package/translations/zh.json

@@ -44,5 +44,7 @@
   "board-ai.text.copied": "已复制",
   "board-ai.text.mention-not-found": "未找到 #{token}",
   "board-ai.text.session-tab-label": "会话 {n}",
-  "board-ai.text.tools-used": "使用的工具"
+  "board-ai.text.tools-used": "使用的工具",
+  "board-ai.text.ungrounded-mention": "提到了未经确认的对象 — 实际数据中不存在:",
+  "board-ai.text.toggle-system-note": "点击展开"
 }