@things-factory/board-ai 10.0.1 → 10.0.3

package/client/components/chat-echo-dedup.test.ts

@@ -154,9 +154,24 @@ describe('내 발신 에코 흡수 (대기 중 중복 렌더 방지)', () => {
     expect(r.lines[2]).toMatchObject({ id: 'S9', senderEmail: 'other@x.com' })
   })
 
-  it('assistant 방송은 흡수 대상이 아니다(append)', () => {
-    const r = receiveRemoteMessage(pending(), new Set(), { id: 'S2', role: 'assistant', content: '답' })!
-    expect(r.lines).toHaveLength(3)
+  /* 이 테스트는 예전에 "assistant 방송은 흡수하지 않고 붙인다" 를 규칙으로 굳혀 두고 있었다.
+   * 그것이 실제 결함이었다 — 붙이면 뒤이은 mutation 응답이 대기 줄을 지우고, 그 줄에만 있던
+   * **영속되지 않는 응답 데이터**(조치 제안 카드·접지 경고)가 함께 사라진다. 규칙을 바로잡는다. */
+  it('assistant 방송도 대기 중인 AI 줄에 흡수한다 — 붙이면 제안 카드가 사라진다', () => {
+    const lines = [
+      { _localId: 'L1', role: 'user', content: '질문', senderEmail: 'me@x.com' },
+      { _localId: 'L2', role: 'assistant', content: '', pending: true }
+    ]
+    const r = receiveRemoteMessage(lines as any, new Set(), { id: 'S2', role: 'assistant', content: '답' })!
+    expect(r.lines).toHaveLength(2)
+    expect(r.lines[1]).toMatchObject({ id: 'S2', content: '답', pending: false })
+  })
+
+  it('대기 중인 AI 줄이 없으면 붙인다 — 다른 참여자가 부른 답변', () => {
+    const settled = [{ id: 'S0', role: 'user', content: '질문' }]
+    const r = receiveRemoteMessage(settled as any, new Set(), { id: 'S2', role: 'assistant', content: '답' })!
+    expect(r.lines).toHaveLength(2)
+    expect(r.lines[1].id).toBe('S2')
   })
 
   it('흡수한 뒤 mutation 응답 reconcile 은 그 줄을 지우지 않고 patch 를 병합한다', () => {
@@ -172,3 +187,44 @@ describe('내 발신 에코 흡수 (대기 중 중복 렌더 방지)', () => {
     expect(after.lines[0]._localId).toBeUndefined()
   })
 })
+
+describe('AI 답변 에코 흡수 — 영속되지 않는 응답 데이터를 잃지 않기', () => {
+  /* 실제 사고: 방송이 mutation 응답보다 먼저 와서 assistant 줄이 새로 붙고, 뒤이어 응답이 대기 줄을
+   * 지웠다. 대기 줄에만 있던 **조치 제안 카드**가 그때 사라졌다(도구는 분명히 호출됐는데도). */
+  const pendingAi = () => [
+    { id: 'u1', role: 'user', content: '지게차 한 대 추가해줘' },
+    { _localId: 'L2', role: 'assistant', content: '', pending: true, proposals: [{ command: 'resource.add' }] }
+  ]
+
+  it('대기 중인 AI 줄에 흡수한다 — 새 줄로 붙이지 않는다', () => {
+    const r = receiveRemoteMessage(pendingAi() as any, new Set(), {
+      id: 'a1',
+      role: 'assistant',
+      content: '제안해 두었습니다.'
+    })!
+    expect(r.lines).toHaveLength(2)
+    expect(r.lines[1].id).toBe('a1')
+    expect(r.lines[1].content).toBe('제안해 두었습니다.')
+  })
+
+  it('제안 카드를 유지한다 — 영속되지 않는 값이라 잃으면 화면에서 버튼이 사라진다', () => {
+    const r = receiveRemoteMessage(pendingAi() as any, new Set(), {
+      id: 'a1',
+      role: 'assistant',
+      content: '제안해 두었습니다.'
+    })!
+    expect(r.lines[1].proposals).toEqual([{ command: 'resource.add' }])
+  })
+
+  it('대기 표시를 푼다 — 방송이 먼저 오면 답이 더 빨리 보인다', () => {
+    const r = receiveRemoteMessage(pendingAi() as any, new Set(), { id: 'a1', role: 'assistant', content: '답' })!
+    expect(r.lines[1].pending).toBe(false)
+  })
+
+  it('대기 줄이 없으면(다른 참여자가 부른 AI 답변) 새 줄로 붙인다', () => {
+    const lines = [{ id: 'u1', role: 'user', content: '질문' }]
+    const r = receiveRemoteMessage(lines as any, new Set(), { id: 'a9', role: 'assistant', content: '답' })!
+    expect(r.lines).toHaveLength(2)
+    expect(r.lines[1].id).toBe('a9')
+  })
+})

package/client/components/chat-echo-dedup.ts

@@ -27,6 +27,8 @@ export interface RemoteMessage {
   content: string
   relatedPatchId?: string
   toolUsagesJson?: any
+  /** 접지 경고(영속) — 답이 언급했으나 근거에 없던 식별자. 나중에 읽는 사람도 같은 주의를 봐야 한다. */
+  groundingWarningsJson?: any
   /** 발신자 — 표시용 name + **자기 여부 판정용 email**(내부 관리키 id 는 쓰지 않는다). */
   creator?: { name?: string; email?: string } | null
 }
@@ -39,6 +41,7 @@ export function remoteMessageToLine(m: RemoteMessage): DedupLine {
     content: m.content,
     patchId: m.relatedPatchId ?? undefined,
     toolUsages: Array.isArray(m.toolUsagesJson) ? m.toolUsagesJson : undefined,
+    groundingWarnings: Array.isArray(m.groundingWarningsJson) ? m.groundingWarningsJson : undefined,
     senderEmail: m.creator?.email ?? undefined,
     senderName: m.creator?.name ?? undefined
   }
@@ -69,6 +72,35 @@ export function receiveRemoteMessage(
   /* 내 발신 에코 흡수 — `_localId` 가 있는 줄은 이 클라이언트가 만든 것뿐이다.
    * 발신자 판정: 양쪽 email 이 있으면 같아야 하고, 방송에 발신자 email 이 없으면(단일 사용자·구형)
    * 내 것으로 본다. 다른 사용자의 메시지가 내 대기 줄을 삼키지 않도록 email 이 다르면 흡수하지 않는다. */
+  /* AI 답변 에코 흡수 — 사용자 발화와 **같은 이유**로 붙이지 않고 대기 줄에 흡수한다.
+   *
+   * 왜 필요한가(실제 사고): 방송은 mutation 응답보다 먼저 도착할 수 있다. 예전에는 assistant 방송을
+   * 새 줄로 붙였고, 뒤이어 mutation 응답이 "같은 서버 id 를 가진 다른 줄이 있다" 며 **대기 줄을 지웠다**.
+   * 그런데 대기 줄에만 있는 것이 있다 — **영속되지 않는 응답 데이터**(조치 제안 카드·접지 경고).
+   * 그래서 화면에서 실행 버튼이 사라졌다(제안 도구는 분명히 호출됐는데도).
+   *
+   * 흡수하면 서버가 보낸 본문(멘션 마커 포함)을 그 줄에 입히면서 대기 표시를 풀 수 있어, 답이 더
+   * 빨리 보이는 효과도 있다. */
+  if (m.role === 'assistant') {
+    const idx = lines.findIndex(l => l.role === 'assistant' && !l.id && !!l._localId)
+    if (idx >= 0) {
+      const nextLines = [...lines]
+      nextLines[idx] = {
+        ...nextLines[idx],
+        id: m.id,
+        /* 본문·영속 데이터는 서버 것으로 갱신하고, 이 줄이 들고 있던 값(제안 등)은 유지한다. */
+        content: m.content,
+        patchId: m.relatedPatchId ?? nextLines[idx].patchId,
+        toolUsages: Array.isArray(m.toolUsagesJson) ? m.toolUsagesJson : nextLines[idx].toolUsages,
+        groundingWarnings: Array.isArray(m.groundingWarningsJson)
+          ? m.groundingWarningsJson
+          : nextLines[idx].groundingWarnings,
+        pending: false
+      }
+      return { lines: nextLines, seen: nextSeen }
+    }
+  }
+
   if (m.role === 'user') {
     const echoEmail = m.creator?.email
     const idx = lines.findIndex(

package/client/components/chat-input-builder.ts

@@ -21,6 +21,11 @@ export interface ChatMutationInputArgs {
   toolCategories?: string[]
   /** 코어 보드 편집 도구(addComponent·스타일링·씬 조작) 사용 여부. 기본 true. */
   boardTools?: boolean
+  /**
+   * 첫 턴에 도구 호출을 강제할지 — 라이브 상태를 다루는 대화면에서 켠다.
+   * 근거 없이 상태를 단언하는 답(도구를 아예 부르지 않은 답)을 원천에서 막는다.
+   */
+  requireGroundingTools?: boolean
   knownTypes?: string[]
   categories?: string[]
   componentSchemas?: any
@@ -54,6 +59,7 @@ export function buildChatMutationInput(args: ChatMutationInputArgs): Record<stri
     /* 미지정은 서버 기본(전부 허용)에 맡긴다 — null 을 보내 굳이 덮어쓰지 않는다. */
     ...(args.toolCategories ? { toolCategories: args.toolCategories } : {}),
     ...(args.boardTools === false ? { boardTools: false } : {}),
+    ...(args.requireGroundingTools ? { requireGroundingTools: true } : {}),
     knownTypes: args.knownTypes,
     categories: args.categories,
     componentSchemas: args.componentSchemas,

package/dist-client/client/components/board-ai-chat.d.ts

@@ -100,6 +100,13 @@ export declare class OxBoardAIChat extends LitElement {
     hostContext?: any;
     /** 코어 보드 편집 도구 사용 여부. 기본 true. 보드를 고칠 이유가 없는 면에서 false. */
     boardTools: boolean;
+    /**
+     * 라이브 상태를 다루는 대화면인가 — true 면 **첫 턴에 도구 호출을 강제**한다.
+     *
+     * 접지 가드는 지어낸 식별자를 잡지만 식별자 없는 상황 서술("바쁘게 움직이고 있다")은 잡지 못한다.
+     * 그건 도구를 부르지 않고 답한 경우이므로, 조회를 먼저 하게 만들어 원천을 막는다.
+     */
+    requireGroundingTools: boolean;
     /** board-import registry scopes. */
     scopes?: string[];
     knownTypes?: string[];
@@ -128,6 +135,18 @@ export declare class OxBoardAIChat extends LitElement {
     private toastMessage?;
     /** 복사 confirmation feedback (메시지 idx → 짧은 시간 동안 ✓ 표시) */
     private copiedIdx?;
+    /** 원본 JSON 을 펼친 단계(라인:단계) — 목록은 한 줄 요약으로 훑고 필요한 것만 펼친다. */
+    private openToolSteps;
+    /** 이미 실행을 요청한 제안 키 — 같은 카드를 두 번 눌러 되돌릴 수 없는 명령이 두 번 나가지 않게. */
+    private sentProposals;
+    /**
+     * 이 대화가 길어져 앞부분이 프롬프트에서 접혔다는 **사실**(서버 보고). 주제 이탈을 판정한 것이
+     * 아니다 — 판정하면 오탐이 생기고, 오탐이 생기면 사용자는 안내 자체를 무시한다.
+     * 사실만 알리고 "새 대화로 시작할지" 는 사용자가 정한다.
+     */
+    private historyFolded?;
+    /** 안내를 닫았는가 — 한 번 닫으면 이 세션에서는 다시 띄우지 않는다(잔소리 금지). */
+    private foldNoticeDismissed;
     private busy;
     private errorMessage?;
     /** C4 presence/roster — 세션 참여자 목록. lastSeenAt 으로 online 판정. */
@@ -261,6 +280,50 @@ export declare class OxBoardAIChat extends LitElement {
      *   system    : 없음
      */
     private renderMessageActions;
+    /**
+     * "대화가 길어졌습니다" 안내 — **사실만** 알리고 결정은 사용자에게 맡긴다.
+     *
+     * 주제가 바뀌었는지 판정하지 않는다: 판정하면 오탐이 생기고, 오탐이 생기면 사용자는 안내 자체를
+     * 무시한다(접지 경고에서 배운 것과 같다). 근거는 "앞부분이 프롬프트에서 접혔다" 는 객관적 사실뿐이다.
+     *
+     * 왜 알려야 하는가: 한 대화에 주제가 여럿 섞이면 (1) 옛 맥락이 새 답을 오염시키고 (2) 요약이
+     * 뭉개지고 (3) 목록의 대화 이름이 거짓말이 된다. 그걸 아는 사람은 사용자뿐이다.
+     */
+    private renderFoldNotice;
+    /**
+     * 새 대화로 — **맥락을 옮기지 않는다.** 주제를 바꾸려고 새로 시작하는 것이므로, 옮기면 그 이유가
+     * 사라진다(승격은 이어가려는 것이고 이건 끊으려는 것이다). 세션 생성은 호스트의 몫이다.
+     */
+    private startNewFromNotice;
+    /**
+     * 조치 제안 카드 — AI 는 제안까지, **실행은 사용자**.
+     *
+     * 왜 카드인가: 되돌릴 수 없는 현장 명령을 문장 속 링크로 흘리면 실수로 눌린다. 무엇을·왜 하는지
+     * 한 줄로 보이고 실행이 **분명한 한 번의 행동**이어야 한다.
+     * 실행 결과는 호스트가 **대화에 기록**한다 — 누가 무엇을 실행했는지가 협의 이력에 남아야 한다.
+     */
+    private renderProposals;
+    /**
+     * 제안 식별 키 — 같은 조치를 두 번 실행하지 않도록 **효과**(명령·대상·인자)로만 만든다.
+     *
+     * 인자는 **키 순서를 정렬**해 직렬화한다: 같은 인자를 다른 순서로 받았을 뿐인데 키가 달라지면
+     * 한 카드를 실행한 뒤에도 다른 카드가 살아 있어 **같은 명령이 두 번 나간다**(실제로 그랬다).
+     * 설명 문구(label·reason)는 키에 넣지 않는다 — 문구가 달라도 같은 조치다.
+     */
+    private proposalKey;
+    /**
+     * 실행은 호스트가 한다 — 이 컴포넌트는 도메인(트윈 명령 채널)을 모른다.
+     * 확인 대화·명령 전송·결과 기록은 호스트의 몫이고, 여기서는 중복 클릭만 막는다.
+     */
+    private executeProposal;
+    /**
+     * 접지 경고 — 답이 언급했지만 **근거에 없던** 대상을 알린다.
+     *
+     * 왜 답을 지우지 않는가: 판정은 식별자 대조라 확정이 아니다(예: 사용자가 화면에서 본 이름을
+     * 대화 밖에서 알고 말한 경우). 그래서 답은 그대로 보여주고, 검증되지 않았다는 사실만 붙인다 —
+     * 사용자가 그 대상을 실제 작업의 근거로 삼기 전에 알아야 하는 정보다.
+     */
+    private renderGroundingWarning;
     /**
      * "AI 가 이런 도구를 사용했습니다" fold-able 박스.
      *
@@ -269,6 +332,23 @@ export declare class OxBoardAIChat extends LitElement {
      * - 디버그 / 신뢰도 향상용 — 사용자가 "왜 이렇게 답했지" 의문 가질 때 즉시 검증.
      */
     private renderToolUsages;
+    /** 시스템 기록 펼치기/접기 — 곁줄이 길어도 대화가 가려지지 않게. */
+    private toggleSystemNote;
+    /**
+     * 판단 과정의 한 단계 — 턴 구분 · 도구 · 배지 · **한 줄 요약**.
+     *
+     * 원본 JSON 을 처음부터 펼쳐 두면 눈이 흐려져 정작 중요한 것(무엇이 거절됐는지, 무엇이 접혔는지)이
+     * 안 보인다. 한 줄로 줄이고 원본은 항목별로 눌러서 본다.
+     */
+    private renderToolStep;
+    /** 배지 문구 — 코드가 아니라 사람 말로. */
+    private outcomeLabel;
+    /**
+     * 결과 한 줄 — 무엇을 얻었는지/왜 막혔는지만. 목록에서 훑어 읽을 수 있어야 한다.
+     * 거절이면 사유를, 조회면 대표적인 개수를, 제안이면 무엇을 제안했는지.
+     */
+    private stepSummary;
+    private toggleToolStep;
     private toggleToolUsages;
     private formatJson;
     private copyMessage;