@things-factory/board-ai 10.0.0 → 10.0.2

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

@@ -70,6 +70,13 @@ interface ChatLine {
   toolUsages?: Array<{ name: string; arguments: any; result: any; kind: 'read' | 'write' | 'unknown' }>
   /** UI 상태: tool usage 박스 펼침 여부 (assistant 메시지마다 독립). */
   toolUsagesOpen?: boolean
+  /** UI 상태: 접힌 시스템 기록을 펼쳤는가(곁줄이 대화를 가리지 않게 기본은 3줄 접기). */
+  systemOpen?: boolean
+  /**
+   * 접지 경고 — 이 답이 언급했으나 모델이 받은 근거(프롬프트·보드 문맥·이력·도구 결과)에 없던 식별자.
+   * 있으면 그 대상은 만들어 낸 것일 수 있다는 주의를 답 아래에 표시한다(답 자체는 그대로 보여준다).
+   */
+  groundingWarnings?: string[]
 }
 
 const BOARD_AI_CHAT_MUTATION = gql`
@@ -85,6 +92,7 @@ const BOARD_AI_CHAT_MUTATION = gql`
       patchId
       toolUsages
       actions
+      groundingWarnings
     }
   }
 `
@@ -97,6 +105,7 @@ const CHAT_MESSAGES_QUERY = gql`
       content
       relatedPatchId
       toolUsagesJson
+      groundingWarningsJson
       createdAt
       creator {
         name
@@ -116,6 +125,7 @@ const CHAT_MESSAGE_SUBSCRIPTION = gql`
       content
       relatedPatchId
       toolUsagesJson
+      groundingWarningsJson
       createdAt
       creator {
         name
@@ -253,6 +263,15 @@ export class OxBoardAIChat extends LitElement {
   @property({ type: Boolean, attribute: 'board-tools' })
   boardTools = true
 
+  /**
+   * 라이브 상태를 다루는 대화면인가 — true 면 **첫 턴에 도구 호출을 강제**한다.
+   *
+   * 접지 가드는 지어낸 식별자를 잡지만 식별자 없는 상황 서술("바쁘게 움직이고 있다")은 잡지 못한다.
+   * 그건 도구를 부르지 않고 답한 경우이므로, 조회를 먼저 하게 만들어 원천을 막는다.
+   */
+  @property({ type: Boolean, attribute: 'require-grounding-tools' })
+  requireGroundingTools = false
+
   /** board-import registry scopes. */
   @property({ type: Array })
   scopes?: string[]
@@ -951,6 +970,21 @@ export class OxBoardAIChat extends LitElement {
       margin: 0;
       border: 0;
     }
+    /* 시스템 기록은 **곁줄**이다 — 길면 화면을 잡아먹어 대화가 안 보인다(옮겨온 대화를 한 덩어리로
+       넣었을 때 실제로 그랬다). 세 줄로 접고 눌러서 펼친다. */
+    .msg.system .sys-text {
+      display: -webkit-box;
+      -webkit-box-orient: vertical;
+      -webkit-line-clamp: 3;
+      overflow: hidden;
+      white-space: pre-wrap;
+      cursor: pointer;
+    }
+    .msg.system.open .sys-text {
+      display: block;
+      -webkit-line-clamp: unset;
+      overflow: visible;
+    }
 
     .msg.pending {
       opacity: 0.5;
@@ -1039,6 +1073,30 @@ export class OxBoardAIChat extends LitElement {
       line-height: 1.45;
     }
 
+    /* ── 접지 경고 — 근거에 없는 대상을 지목한 답 ───── */
+    .grounding-warning {
+      display: flex;
+      align-items: flex-start;
+      gap: 6px;
+      margin-top: 4px;
+      padding: 5px 8px;
+      border-radius: 6px;
+      border: 1px solid var(--md-sys-color-error, #dc2626);
+      background: var(--md-sys-color-error-container, #fef2f2);
+      color: var(--md-sys-color-on-error-container, #7f1d1d);
+      font-size: 10.5px;
+      line-height: 1.45;
+    }
+    .grounding-warning md-icon {
+      --md-icon-size: 14px;
+      flex-shrink: 0;
+    }
+    .grounding-warning .ids {
+      font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+      font-weight: 600;
+      word-break: break-all;
+    }
+
     /* ── Tool usages fold-able 박스 — AI 도구 호출 trace ───── */
     .tool-usages {
       margin-top: 4px;
@@ -1645,12 +1703,22 @@ export class OxBoardAIChat extends LitElement {
                 ? html`<div class="msg-label sender">${line.senderName || i18next.t('board-ai.label.participant')}</div>`
                 : nothing}
             <div class="msg-wrap ${line.role} ${isOther ? 'other' : ''}">
-              <div class="msg ${line.role} ${isOther ? 'other' : ''} ${line.pending ? 'pending' : ''}">
+              <div
+                class="msg ${line.role} ${isOther ? 'other' : ''} ${line.pending ? 'pending' : ''} ${line.systemOpen
+                  ? 'open'
+                  : ''}">
                 ${line.pending
                   ? html`<span class="typing-dots"><span></span><span></span><span></span></span>`
                   : isMarkdown
                     ? html`<div class="md-body">${unsafeHTML(renderMarkdown(content))}</div>`
-                    : content}
+                    : line.role === 'system'
+                      ? html`<span
+                          class="sys-text"
+                          title=${i18next.t('board-ai.text.toggle-system-note', { defaultValue: '눌러서 펼치기' })}
+                          @click=${() => this.toggleSystemNote(idx)}
+                          >${content}</span
+                        >`
+                      : content}
                 ${line.patchId
                   ? html`
                       <div class="summary ${this.revertedPatchIds.has(line.patchId) ? 'reverted' : ''}">
@@ -1672,6 +1740,9 @@ export class OxBoardAIChat extends LitElement {
                 ${line.followUp
                   ? html`<div class="followup">${unsafeHTML(renderMarkdown(line.followUp.trim()))}</div>`
                   : nothing}
+                ${line.groundingWarnings && line.groundingWarnings.length > 0
+                  ? this.renderGroundingWarning(line)
+                  : nothing}
                 ${line.toolUsages && line.toolUsages.length > 0
                   ? this.renderToolUsages(idx, line)
                   : nothing}
@@ -2327,6 +2398,29 @@ export class OxBoardAIChat extends LitElement {
     `
   }
 
+  /**
+   * 접지 경고 — 답이 언급했지만 **근거에 없던** 대상을 알린다.
+   *
+   * 왜 답을 지우지 않는가: 판정은 식별자 대조라 확정이 아니다(예: 사용자가 화면에서 본 이름을
+   * 대화 밖에서 알고 말한 경우). 그래서 답은 그대로 보여주고, 검증되지 않았다는 사실만 붙인다 —
+   * 사용자가 그 대상을 실제 작업의 근거로 삼기 전에 알아야 하는 정보다.
+   */
+  private renderGroundingWarning(line: ChatLine) {
+    const ids = line.groundingWarnings ?? []
+    if (ids.length === 0) return nothing
+    return html`
+      <div class="grounding-warning" role="note">
+        <md-icon>report</md-icon>
+        <span>
+          ${i18next.t('board-ai.text.ungrounded-mention', {
+            defaultValue: '확인되지 않은 대상을 언급했습니다 — 실제 데이터에 없습니다:'
+          })}
+          <span class="ids">${ids.join(', ')}</span>
+        </span>
+      </div>
+    `
+  }
+
   /**
    * "AI 가 이런 도구를 사용했습니다" fold-able 박스.
    *
@@ -2379,6 +2473,15 @@ export class OxBoardAIChat extends LitElement {
     `
   }
 
+  /** 시스템 기록 펼치기/접기 — 곁줄이 길어도 대화가 가려지지 않게. */
+  private toggleSystemNote(idx: number) {
+    const next = [...this.lines]
+    const line = next[idx]
+    if (!line) return
+    next[idx] = { ...line, systemOpen: !line.systemOpen }
+    this.lines = next
+  }
+
   private toggleToolUsages(idx: number) {
     const next = [...this.lines]
     const line = next[idx]
@@ -2534,6 +2637,7 @@ export class OxBoardAIChat extends LitElement {
             hostContext: this.hostContext,
             toolCategories: this.toolCategories,
             boardTools: this.boardTools,
+            requireGroundingTools: this.requireGroundingTools,
             knownTypes: this.knownTypes,
             categories: this.categories,
             componentSchemas: this.componentSchemas,
@@ -2560,6 +2664,7 @@ export class OxBoardAIChat extends LitElement {
         followUp: out.followUp || undefined,
         patchId: out.patchId || undefined,
         toolUsages: Array.isArray(out.toolUsages) ? out.toolUsages : undefined,
+        groundingWarnings: Array.isArray(out.groundingWarnings) ? out.groundingWarnings : undefined,
         pending: false
       })
 

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
   }

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[];
@@ -261,6 +268,14 @@ export declare class OxBoardAIChat extends LitElement {
      *   system    : 없음
      */
     private renderMessageActions;
+    /**
+     * 접지 경고 — 답이 언급했지만 **근거에 없던** 대상을 알린다.
+     *
+     * 왜 답을 지우지 않는가: 판정은 식별자 대조라 확정이 아니다(예: 사용자가 화면에서 본 이름을
+     * 대화 밖에서 알고 말한 경우). 그래서 답은 그대로 보여주고, 검증되지 않았다는 사실만 붙인다 —
+     * 사용자가 그 대상을 실제 작업의 근거로 삼기 전에 알아야 하는 정보다.
+     */
+    private renderGroundingWarning;
     /**
      * "AI 가 이런 도구를 사용했습니다" fold-able 박스.
      *
@@ -269,6 +284,8 @@ export declare class OxBoardAIChat extends LitElement {
      * - 디버그 / 신뢰도 향상용 — 사용자가 "왜 이렇게 답했지" 의문 가질 때 즉시 검증.
      */
     private renderToolUsages;
+    /** 시스템 기록 펼치기/접기 — 곁줄이 길어도 대화가 가려지지 않게. */
+    private toggleSystemNote;
     private toggleToolUsages;
     private formatJson;
     private copyMessage;

package/dist-client/client/components/board-ai-chat.js

@@ -44,6 +44,7 @@ const BOARD_AI_CHAT_MUTATION = gql `
       patchId
       toolUsages
       actions
+      groundingWarnings
     }
   }
 `;
@@ -55,6 +56,7 @@ const CHAT_MESSAGES_QUERY = gql `
       content
       relatedPatchId
       toolUsagesJson
+      groundingWarningsJson
       createdAt
       creator {
         name
@@ -73,6 +75,7 @@ const CHAT_MESSAGE_SUBSCRIPTION = gql `
       content
       relatedPatchId
       toolUsagesJson
+      groundingWarningsJson
       createdAt
       creator {
         name
@@ -136,6 +139,13 @@ let OxBoardAIChat = class OxBoardAIChat extends LitElement {
         this.selectedRefids = [];
         /** 코어 보드 편집 도구 사용 여부. 기본 true. 보드를 고칠 이유가 없는 면에서 false. */
         this.boardTools = true;
+        /**
+         * 라이브 상태를 다루는 대화면인가 — true 면 **첫 턴에 도구 호출을 강제**한다.
+         *
+         * 접지 가드는 지어낸 식별자를 잡지만 식별자 없는 상황 서술("바쁘게 움직이고 있다")은 잡지 못한다.
+         * 그건 도구를 부르지 않고 답한 경우이므로, 조회를 먼저 하게 만들어 원천을 막는다.
+         */
+        this.requireGroundingTools = false;
         this.placeholder = '자연어로 명령하세요 (Shift+Enter 줄바꿈, Enter 전송)';
         this.lines = [];
         this.input = '';
@@ -789,6 +799,21 @@ let OxBoardAIChat = class OxBoardAIChat extends LitElement {
       margin: 0;
       border: 0;
     }
+    /* 시스템 기록은 **곁줄**이다 — 길면 화면을 잡아먹어 대화가 안 보인다(옮겨온 대화를 한 덩어리로
+       넣었을 때 실제로 그랬다). 세 줄로 접고 눌러서 펼친다. */
+    .msg.system .sys-text {
+      display: -webkit-box;
+      -webkit-box-orient: vertical;
+      -webkit-line-clamp: 3;
+      overflow: hidden;
+      white-space: pre-wrap;
+      cursor: pointer;
+    }
+    .msg.system.open .sys-text {
+      display: block;
+      -webkit-line-clamp: unset;
+      overflow: visible;
+    }
 
     .msg.pending {
       opacity: 0.5;
@@ -877,6 +902,30 @@ let OxBoardAIChat = class OxBoardAIChat extends LitElement {
       line-height: 1.45;
     }
 
+    /* ── 접지 경고 — 근거에 없는 대상을 지목한 답 ───── */
+    .grounding-warning {
+      display: flex;
+      align-items: flex-start;
+      gap: 6px;
+      margin-top: 4px;
+      padding: 5px 8px;
+      border-radius: 6px;
+      border: 1px solid var(--md-sys-color-error, #dc2626);
+      background: var(--md-sys-color-error-container, #fef2f2);
+      color: var(--md-sys-color-on-error-container, #7f1d1d);
+      font-size: 10.5px;
+      line-height: 1.45;
+    }
+    .grounding-warning md-icon {
+      --md-icon-size: 14px;
+      flex-shrink: 0;
+    }
+    .grounding-warning .ids {
+      font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+      font-weight: 600;
+      word-break: break-all;
+    }
+
     /* ── Tool usages fold-able 박스 — AI 도구 호출 trace ───── */
     .tool-usages {
       margin-top: 4px;
@@ -1482,12 +1531,22 @@ let OxBoardAIChat = class OxBoardAIChat extends LitElement {
                         ? html `<div class="msg-label sender">${line.senderName || i18next.t('board-ai.label.participant')}</div>`
                         : nothing}
             <div class="msg-wrap ${line.role} ${isOther ? 'other' : ''}">
-              <div class="msg ${line.role} ${isOther ? 'other' : ''} ${line.pending ? 'pending' : ''}">
+              <div
+                class="msg ${line.role} ${isOther ? 'other' : ''} ${line.pending ? 'pending' : ''} ${line.systemOpen
+                    ? 'open'
+                    : ''}">
                 ${line.pending
                     ? html `<span class="typing-dots"><span></span><span></span><span></span></span>`
                     : isMarkdown
                         ? html `<div class="md-body">${unsafeHTML(renderMarkdown(content))}</div>`
-                        : content}
+                        : line.role === 'system'
+                            ? html `<span
+                          class="sys-text"
+                          title=${i18next.t('board-ai.text.toggle-system-note', { defaultValue: '눌러서 펼치기' })}
+                          @click=${() => this.toggleSystemNote(idx)}
+                          >${content}</span
+                        >`
+                            : content}
                 ${line.patchId
                     ? html `
                       <div class="summary ${this.revertedPatchIds.has(line.patchId) ? 'reverted' : ''}">
@@ -1509,6 +1568,9 @@ let OxBoardAIChat = class OxBoardAIChat extends LitElement {
                 ${line.followUp
                     ? html `<div class="followup">${unsafeHTML(renderMarkdown(line.followUp.trim()))}</div>`
                     : nothing}
+                ${line.groundingWarnings && line.groundingWarnings.length > 0
+                    ? this.renderGroundingWarning(line)
+                    : nothing}
                 ${line.toolUsages && line.toolUsages.length > 0
                     ? this.renderToolUsages(idx, line)
                     : nothing}
@@ -2086,6 +2148,29 @@ let OxBoardAIChat = class OxBoardAIChat extends LitElement {
       </div>
     `;
     }
+    /**
+     * 접지 경고 — 답이 언급했지만 **근거에 없던** 대상을 알린다.
+     *
+     * 왜 답을 지우지 않는가: 판정은 식별자 대조라 확정이 아니다(예: 사용자가 화면에서 본 이름을
+     * 대화 밖에서 알고 말한 경우). 그래서 답은 그대로 보여주고, 검증되지 않았다는 사실만 붙인다 —
+     * 사용자가 그 대상을 실제 작업의 근거로 삼기 전에 알아야 하는 정보다.
+     */
+    renderGroundingWarning(line) {
+        const ids = line.groundingWarnings ?? [];
+        if (ids.length === 0)
+            return nothing;
+        return html `
+      <div class="grounding-warning" role="note">
+        <md-icon>report</md-icon>
+        <span>
+          ${i18next.t('board-ai.text.ungrounded-mention', {
+            defaultValue: '확인되지 않은 대상을 언급했습니다 — 실제 데이터에 없습니다:'
+        })}
+          <span class="ids">${ids.join(', ')}</span>
+        </span>
+      </div>
+    `;
+    }
     /**
      * "AI 가 이런 도구를 사용했습니다" fold-able 박스.
      *
@@ -2136,6 +2221,15 @@ let OxBoardAIChat = class OxBoardAIChat extends LitElement {
       </div>
     `;
     }
+    /** 시스템 기록 펼치기/접기 — 곁줄이 길어도 대화가 가려지지 않게. */
+    toggleSystemNote(idx) {
+        const next = [...this.lines];
+        const line = next[idx];
+        if (!line)
+            return;
+        next[idx] = { ...line, systemOpen: !line.systemOpen };
+        this.lines = next;
+    }
     toggleToolUsages(idx) {
         const next = [...this.lines];
         const line = next[idx];
@@ -2277,6 +2371,7 @@ let OxBoardAIChat = class OxBoardAIChat extends LitElement {
                         hostContext: this.hostContext,
                         toolCategories: this.toolCategories,
                         boardTools: this.boardTools,
+                        requireGroundingTools: this.requireGroundingTools,
                         knownTypes: this.knownTypes,
                         categories: this.categories,
                         componentSchemas: this.componentSchemas,
@@ -2301,6 +2396,7 @@ let OxBoardAIChat = class OxBoardAIChat extends LitElement {
                 followUp: out.followUp || undefined,
                 patchId: out.patchId || undefined,
                 toolUsages: Array.isArray(out.toolUsages) ? out.toolUsages : undefined,
+                groundingWarnings: Array.isArray(out.groundingWarnings) ? out.groundingWarnings : undefined,
                 pending: false
             });
             // 호스트로 patch 이벤트 전파
@@ -2384,6 +2480,10 @@ __decorate([
     property({ type: Boolean, attribute: 'board-tools' }),
     __metadata("design:type", Object)
 ], OxBoardAIChat.prototype, "boardTools", void 0);
+__decorate([
+    property({ type: Boolean, attribute: 'require-grounding-tools' }),
+    __metadata("design:type", Object)
+], OxBoardAIChat.prototype, "requireGroundingTools", void 0);
 __decorate([
     property({ type: Array }),
     __metadata("design:type", Array)