@things-factory/board-ai 10.0.0-beta.64

package/server/service/assistant.test.ts

@@ -0,0 +1,1317 @@
+/**
+ * assistant.ts 의 pure helper 회귀 방지.
+ *
+ * 핵심 보호:
+ *  - LLM tool call → BoardEditOp 매핑이 잘못된 인자에서도 안전
+ *  - JSON fallback 응답 정규화: 망가진 ops, 빠진 confidence, 잘못된 타입에서도 적절히 무시
+ *  - summarizeBoard: 토큰 절감 — 컴포넌트 수 제한, 필요 속성만 노출
+ */
+import {
+  toolCallToBoardEditOp,
+  toolResultToChatResponse,
+  normalizeChatResponse,
+  isValidOp,
+  isReadTool,
+  isWriteTool,
+  executeReadTool,
+  summarizeBoard,
+  summarizeToolResult,
+  buildBoardEditTools,
+  DefaultBoardAIAssistant
+} from './assistant'
+
+describe('toolCallToBoardEditOp', () => {
+  test('addComponent: 정상 인자', () => {
+    const r = toolCallToBoardEditOp({
+      id: '1',
+      name: 'addComponent',
+      arguments: { id: 'a', type: 'rect', left: 0, top: 0 }
+    } as any)
+    expect(r).toEqual({ op: 'add', component: { id: 'a', type: 'rect', left: 0, top: 0 } })
+  })
+
+  test('addComponent: type 누락 → null', () => {
+    const r = toolCallToBoardEditOp({ id: '1', name: 'addComponent', arguments: { id: 'a' } } as any)
+    expect(r).toBeNull()
+  })
+
+  test('removeComponentByRefid: 정상', () => {
+    const r = toolCallToBoardEditOp({
+      id: '1',
+      name: 'removeComponentByRefid',
+      arguments: { refid: 35 }
+    } as any)
+    expect(r).toEqual({ op: 'remove', refid: 35 })
+  })
+
+  test('removeComponentByRefid: refid 누락 → null', () => {
+    const r = toolCallToBoardEditOp({
+      id: '1',
+      name: 'removeComponentByRefid',
+      arguments: {}
+    } as any)
+    expect(r).toBeNull()
+  })
+
+  test('removeComponentByRefid: refid 가 number 아니면 null (id 로는 targeting 안 함)', () => {
+    const r = toolCallToBoardEditOp({
+      id: '1',
+      name: 'removeComponentByRefid',
+      arguments: { refid: 'AGV-1' }
+    } as any)
+    expect(r).toBeNull()
+  })
+
+  test('modifyComponentByRefid: 정상', () => {
+    const r = toolCallToBoardEditOp({
+      id: '1',
+      name: 'modifyComponentByRefid',
+      arguments: { refid: 35, patch: { left: 100 } }
+    } as any)
+    expect(r).toEqual({ op: 'modify', refid: 35, patch: { left: 100 } })
+  })
+
+  test('modifyComponentByRefid: patch 가 객체가 아니면 null', () => {
+    const r = toolCallToBoardEditOp({
+      id: '1',
+      name: 'modifyComponentByRefid',
+      arguments: { refid: 35, patch: 'string' }
+    } as any)
+    expect(r).toBeNull()
+  })
+
+  test('modifyComponentByRefid: refid 누락 → null', () => {
+    const r = toolCallToBoardEditOp({
+      id: '1',
+      name: 'modifyComponentByRefid',
+      arguments: { patch: { left: 100 } }
+    } as any)
+    expect(r).toBeNull()
+  })
+
+  test('legacy 이름 (removeComponent / modifyComponent / getComponent) → null', () => {
+    // 이름이 refid 기반으로 명시 변경됐다 — legacy 이름은 invalid 로 거부.
+    expect(toolCallToBoardEditOp({ id: '1', name: 'removeComponent', arguments: { id: 'a' } } as any)).toBeNull()
+    expect(
+      toolCallToBoardEditOp({ id: '1', name: 'modifyComponent', arguments: { id: 'a', patch: {} } } as any)
+    ).toBeNull()
+  })
+
+  test('modifyBoard: patch 객체 정상 — root 속성 변경', () => {
+    const r = toolCallToBoardEditOp({
+      id: '1',
+      name: 'modifyBoard',
+      arguments: { patch: { fillStyle: '#0a1929' } }
+    } as any)
+    expect(r).toEqual({ op: 'modifyBoard', patch: { fillStyle: '#0a1929' } })
+  })
+
+  test('modifyBoard: patch 누락 → null', () => {
+    expect(
+      toolCallToBoardEditOp({ id: '1', name: 'modifyBoard', arguments: {} } as any)
+    ).toBeNull()
+  })
+
+  test('modifyBoard: patch 가 array 면 null (object 만 허용)', () => {
+    expect(
+      toolCallToBoardEditOp({
+        id: '1',
+        name: 'modifyBoard',
+        arguments: { patch: [1, 2] }
+      } as any)
+    ).toBeNull()
+  })
+
+  test('modifyBoard: 다중 root 속성 변경', () => {
+    const r = toolCallToBoardEditOp({
+      id: '1',
+      name: 'modifyBoard',
+      arguments: { patch: { fillStyle: '#0a1929', name: 'Production', width: 1920 } }
+    } as any)
+    expect(r).toEqual({
+      op: 'modifyBoard',
+      patch: { fillStyle: '#0a1929', name: 'Production', width: 1920 }
+    })
+  })
+
+  test('replaceBoard: 정상', () => {
+    const r = toolCallToBoardEditOp({
+      id: '1',
+      name: 'replaceBoard',
+      arguments: { width: 1920, height: 1080, components: [{ type: 'rect' }] }
+    } as any)
+    expect(r?.op).toBe('replace')
+    if (r && r.op === 'replace') {
+      expect(r.board.width).toBe(1920)
+      expect(r.board.components).toHaveLength(1)
+    }
+  })
+
+  test('replaceBoard: components 누락 → null', () => {
+    const r = toolCallToBoardEditOp({ id: '1', name: 'replaceBoard', arguments: {} } as any)
+    expect(r).toBeNull()
+  })
+
+  test('알 수 없는 tool name → null', () => {
+    const r = toolCallToBoardEditOp({ id: '1', name: 'unknownTool', arguments: {} } as any)
+    expect(r).toBeNull()
+  })
+
+  test('arguments 누락도 안전', () => {
+    const r = toolCallToBoardEditOp({ id: '1', name: 'addComponent' } as any)
+    expect(r).toBeNull()
+  })
+})
+
+describe('isValidOp', () => {
+  test('add: 컴포넌트와 type 필수', () => {
+    expect(isValidOp({ op: 'add', component: { type: 'rect' } })).toBe(true)
+    expect(isValidOp({ op: 'add', component: {} })).toBe(false)
+    expect(isValidOp({ op: 'add' })).toBe(false)
+  })
+
+  test('remove: refid number 필수', () => {
+    expect(isValidOp({ op: 'remove', refid: 35 })).toBe(true)
+    expect(isValidOp({ op: 'remove', refid: 'a' })).toBe(false)
+    expect(isValidOp({ op: 'remove' })).toBe(false)
+  })
+
+  test('modify: refid 와 patch 객체 필수', () => {
+    expect(isValidOp({ op: 'modify', refid: 35, patch: {} })).toBe(true)
+    expect(isValidOp({ op: 'modify', refid: 35 })).toBe(false)
+    expect(isValidOp({ op: 'modify', refid: 35, patch: 'str' })).toBe(false)
+    expect(isValidOp({ op: 'modify', patch: {} })).toBe(false)
+  })
+
+  test('replace: board.components 배열 필수', () => {
+    expect(isValidOp({ op: 'replace', board: { components: [] } })).toBe(true)
+    expect(isValidOp({ op: 'replace', board: {} })).toBe(false)
+    expect(isValidOp({ op: 'replace' })).toBe(false)
+  })
+
+  test('null/undefined/잘못된 입력', () => {
+    expect(isValidOp(null)).toBe(false)
+    expect(isValidOp(undefined)).toBe(false)
+    expect(isValidOp({})).toBe(false)
+    expect(isValidOp({ op: 'unknown' })).toBe(false)
+  })
+})
+
+describe('normalizeChatResponse', () => {
+  test('reply 만 있는 경우', () => {
+    expect(normalizeChatResponse({ reply: '안녕' })).toEqual({
+      reply: '안녕',
+      patch: undefined,
+      followUp: undefined
+    })
+  })
+
+  test('reply 가 string 이 아니면 빈 문자열', () => {
+    expect(normalizeChatResponse({ reply: 123 } as any).reply).toBe('')
+  })
+
+  test('정상 patch (refid 기반)', () => {
+    const r = normalizeChatResponse({
+      reply: 'ok',
+      patch: {
+        ops: [{ op: 'remove', refid: 1 }],
+        summary: '삭제',
+        confidence: 0.85
+      }
+    })
+    expect(r.patch).toBeDefined()
+    expect(r.patch?.ops).toHaveLength(1)
+    expect(r.patch?.confidence).toBe(0.85)
+    expect(r.patch?.summary).toBe('삭제')
+  })
+
+  test('잘못된 op 는 필터링 (id 기반은 invalid)', () => {
+    const r = normalizeChatResponse({
+      reply: 'ok',
+      patch: {
+        ops: [
+          { op: 'remove', refid: 1 }, // valid
+          { op: 'remove', id: 'a' }, // invalid — id 로는 targeting 안 함
+          { op: 'remove' }, // invalid
+          { op: 'modify', refid: 2, patch: { left: 0 } }, // valid
+          { op: 'modify', id: 'b', patch: { left: 0 } }, // invalid
+          { op: 'unknown' } // invalid
+        ],
+        summary: '',
+        confidence: 1
+      }
+    })
+    expect(r.patch?.ops).toHaveLength(2)
+  })
+
+  test('모든 op 가 invalid 면 patch 없음', () => {
+    const r = normalizeChatResponse({
+      reply: 'ok',
+      patch: {
+        ops: [{ op: 'unknown' }, { whatever: 1 }] as any,
+        summary: '',
+        confidence: 1
+      }
+    })
+    expect(r.patch).toBeUndefined()
+  })
+
+  test('confidence 누락 → 0.5 기본값', () => {
+    const r = normalizeChatResponse({
+      reply: 'ok',
+      patch: { ops: [{ op: 'remove', refid: 1 }], summary: '' } as any
+    })
+    expect(r.patch?.confidence).toBe(0.5)
+  })
+
+  test('빈 ops → patch 없음', () => {
+    const r = normalizeChatResponse({
+      reply: 'ok',
+      patch: { ops: [], summary: '', confidence: 1 }
+    })
+    expect(r.patch).toBeUndefined()
+  })
+
+  test('followUp 빈 문자열은 undefined', () => {
+    expect(normalizeChatResponse({ reply: 'ok', followUp: '' }).followUp).toBeUndefined()
+  })
+
+  test('followUp string', () => {
+    expect(normalizeChatResponse({ reply: 'ok', followUp: '?' }).followUp).toBe('?')
+  })
+})
+
+describe('toolResultToChatResponse — followUp 중복 노출 회귀 방지', () => {
+  // 핵심: reply 가 자연어 질문 ("?" 로 끝남) 형태여도 절대 followUp 에 복제하지 않는다.
+  // 복제하면 클라이언트가 .md-body (assistant 메시지) 와 .followup 박스 두 곳에 같은 텍스트를
+  // 표시 → 사용자에게는 "동일 응답이 두 번 반복" 으로 보임. 사용자 보고된 실제 버그.
+  test('? 로 끝나는 reply 라도 followUp 은 항상 undefined', () => {
+    const r = toolResultToChatResponse({
+      text: '어떤 색상으로 변경할까요?',
+      toolCalls: [],
+      stopReason: 'stop'
+    } as any)
+    expect(r.reply).toBe('어떤 색상으로 변경할까요?')
+    expect(r.followUp).toBeUndefined()
+  })
+
+  test('느낌표/마침표로 끝나는 reply 도 followUp 없음', () => {
+    expect(
+      toolResultToChatResponse({ text: '완료했습니다.', toolCalls: [], stopReason: 'stop' } as any).followUp
+    ).toBeUndefined()
+  })
+
+  test('한국어 물음표 (？) 도 동일', () => {
+    expect(
+      toolResultToChatResponse({ text: '어떤 종류？', toolCalls: [], stopReason: 'stop' } as any).followUp
+    ).toBeUndefined()
+  })
+
+  test('tool calls 있을 때 reply fallback', () => {
+    const r = toolResultToChatResponse({
+      text: '',
+      toolCalls: [{ name: 'addComponent', arguments: { type: 'rect' } }],
+      stopReason: 'tool_use'
+    } as any)
+    expect(r.reply).toBe('변경했습니다.')
+    expect(r.patch?.ops).toHaveLength(1)
+    expect(r.followUp).toBeUndefined()
+  })
+
+  test('tool calls 와 text 동시', () => {
+    const r = toolResultToChatResponse({
+      text: 'AGV 3대 추가했습니다.',
+      toolCalls: [
+        { name: 'addComponent', arguments: { type: 'rect', id: 'a' } },
+        { name: 'addComponent', arguments: { type: 'rect', id: 'b' } }
+      ],
+      stopReason: 'tool_use'
+    } as any)
+    expect(r.reply).toBe('AGV 3대 추가했습니다.')
+    expect(r.patch?.ops).toHaveLength(2)
+    expect(r.patch?.summary).toBe('AGV 3대 추가했습니다.')
+    expect(r.patch?.confidence).toBe(0.9)
+    expect(r.followUp).toBeUndefined()
+  })
+
+  test('text 와 toolCalls 모두 비어있으면 빈 reply', () => {
+    const r = toolResultToChatResponse({ text: '', toolCalls: [], stopReason: 'stop' } as any)
+    expect(r.reply).toBe('')
+    expect(r.patch).toBeUndefined()
+    expect(r.followUp).toBeUndefined()
+  })
+
+  test('잘못된 tool call 는 필터링되고 patch 생성 안 함', () => {
+    const r = toolResultToChatResponse({
+      text: 'msg',
+      toolCalls: [{ name: 'addComponent', arguments: {} }], // type 누락
+      stopReason: 'stop'
+    } as any)
+    expect(r.patch).toBeUndefined()
+  })
+})
+
+describe('summarizeBoard', () => {
+  test('null 입력 → null', () => {
+    expect(summarizeBoard(null)).toBeNull()
+    expect(summarizeBoard(undefined)).toBeNull()
+  })
+
+  test('빈 보드 — boardRoot 에 root 속성 포함', () => {
+    const r = summarizeBoard({ width: 1000, height: 600, components: [] })
+    expect(r.boardRoot.type).toBe('model')
+    expect(r.boardRoot.width).toBe(1000)
+    expect(r.boardRoot.height).toBe(600)
+    expect(r.componentCount).toBe(0)
+    expect(r.truncated).toBe(false)
+  })
+
+  test('보드 root 의 fillStyle / name 등 모든 비-internal 속성 노출 (회귀 방지)', () => {
+    // 보드는 최상위 부모 — 자체 속성을 갖는다. AI 가 보드 자체를 컴포넌트와 별개의
+    // 노드로 인식하도록 root 속성을 평면 whitelist 가 아닌 통째 노출.
+    const r = summarizeBoard({
+      width: 1920,
+      height: 1080,
+      fillStyle: '#0a1929',
+      name: 'Production Floor',
+      description: '심해 컬러 대시보드',
+      components: []
+    } as any)
+    expect(r.boardRoot.type).toBe('model')
+    expect(r.boardRoot.fillStyle).toBe('#0a1929')
+    expect(r.boardRoot.name).toBe('Production Floor')
+    expect(r.boardRoot.description).toBe('심해 컬러 대시보드')
+    // boardRoot 는 components 를 포함하지 않음 (children 는 별도)
+    expect(r.boardRoot.components).toBeUndefined()
+  })
+
+  test('컴포넌트 요약은 모든 type-specific 속성 통과', () => {
+    // 기존 좁은 화이트리스트가 type-specific 키 (text/value/cx/cy/radius/points 등) 를
+    // 떨어뜨려서 AI 가 modify 대상을 정확히 판단할 수 없었음. 이제는 \_prefix 가 아닌
+    // 모든 키를 통과시켜야 한다.
+    const r = summarizeBoard({
+      width: 1000,
+      height: 600,
+      components: [
+        {
+          id: 'a',
+          type: 'rect',
+          left: 10,
+          top: 20,
+          width: 100,
+          height: 50,
+          rotation: 30,
+          fillStyle: '#fff',
+          strokeStyle: '#000',
+          opacity: 0.8,
+          customProp: 'visible to AI'
+        } as any
+      ]
+    })
+    const c = r.components[0]
+    expect(c.type).toBe('rect')
+    expect(c.left).toBe(10)
+    expect(c.fillStyle).toBe('#fff')
+    expect(c.customProp).toBe('visible to AI')
+  })
+
+  test('type-specific 속성 보존 (회귀 방지)', () => {
+    // gauge.value, text.text, circle.cx/cy/radius, polyline.points 등
+    // — 이들이 누락되면 AI 가 정확한 modify 를 못 한다.
+    const r = summarizeBoard({
+      width: 1000,
+      height: 600,
+      components: [
+        { id: 'g', type: 'gauge-circle', value: 42, min: 0, max: 100 } as any,
+        { id: 't', type: 'text', text: '온도', fontSize: 14 } as any,
+        { id: 'c', type: 'circle', cx: 50, cy: 50, radius: 20 } as any,
+        { id: 'p', type: 'polyline', points: [[0, 0], [10, 10]] } as any
+      ]
+    })
+    expect(r.components[0].value).toBe(42)
+    expect(r.components[0].min).toBe(0)
+    expect(r.components[0].max).toBe(100)
+    expect(r.components[1].text).toBe('온도')
+    expect(r.components[1].fontSize).toBe(14)
+    expect(r.components[2].cx).toBe(50)
+    expect(r.components[2].radius).toBe(20)
+    expect(r.components[3].points).toEqual([[0, 0], [10, 10]])
+  })
+
+  test('threeD 의 모든 (비-internal) 속성 통과', () => {
+    const r = summarizeBoard({
+      width: 1000,
+      height: 600,
+      components: [
+        {
+          id: 'a',
+          type: 'rect',
+          threeD: {
+            enabled: true,
+            material: { color: '#ff0000' },
+            geometry: { type: 'box' },
+            extrudeDepth: 50
+          }
+        } as any
+      ]
+    })
+    const c = r.components[0]
+    expect(c.threeD.material.color).toBe('#ff0000')
+    expect(c.threeD.geometry.type).toBe('box')
+    expect(c.threeD.enabled).toBe(true)
+    expect(c.threeD.extrudeDepth).toBe(50)
+  })
+
+  test('_underscore prefix 키와 transient 내부 키는 제외', () => {
+    const r = summarizeBoard({
+      width: 1000,
+      height: 600,
+      components: [
+        {
+          id: 'a',
+          type: 'rect',
+          _state: 'internal',
+          _cache: 'blob',
+          _layout: { stale: true },
+          normalProp: 'visible'
+        } as any
+      ]
+    })
+    const c = r.components[0]
+    expect(c.normalProp).toBe('visible')
+    expect(c._state).toBeUndefined()
+    expect(c._cache).toBeUndefined()
+    expect(c._layout).toBeUndefined()
+  })
+
+  test('긴 문자열은 truncate', () => {
+    const longText = 'x'.repeat(500)
+    const r = summarizeBoard({
+      width: 1000,
+      height: 600,
+      components: [{ id: 'a', type: 'text', text: longText } as any]
+    })
+    const c = r.components[0]
+    expect(c.text.length).toBeLessThan(longText.length)
+    expect(c.text).toMatch(/…\[\+\d+ chars\]$/)
+  })
+
+  test('큰 배열은 truncate', () => {
+    const bigPoints = Array.from({ length: 100 }, (_, i) => [i, i])
+    const r = summarizeBoard({
+      width: 1000,
+      height: 600,
+      components: [{ id: 'p', type: 'polyline', points: bigPoints } as any]
+    })
+    const c = r.components[0]
+    expect(c.points.length).toBeLessThan(bigPoints.length + 2)
+    // 마지막에 truncation 마커
+    expect(c.points[c.points.length - 1]).toMatch(/items\]/)
+  })
+
+  test('80개 초과 컴포넌트는 truncate', () => {
+    const components = Array.from({ length: 100 }, (_, i) => ({ id: `c${i}`, type: 'rect' } as any))
+    const r = summarizeBoard({ width: 1000, height: 600, components })
+    expect(r.componentCount).toBe(100)
+    expect(r.components).toHaveLength(80)
+    expect(r.truncated).toBe(true)
+  })
+
+  test('rotation/opacity 가 undefined 이면 출력에 없음', () => {
+    const r = summarizeBoard({
+      width: 1000,
+      height: 600,
+      components: [{ id: 'a', type: 'rect' } as any]
+    })
+    expect(r.components[0].rotation).toBeUndefined()
+    expect(r.components[0].opacity).toBeUndefined()
+  })
+})
+
+describe('Tool 분류 (read/write)', () => {
+  test('read tool 식별', () => {
+    expect(isReadTool('getSelection')).toBe(true)
+    expect(isReadTool('getComponentByRefid')).toBe(true)
+    expect(isReadTool('findComponents')).toBe(true)
+    expect(isReadTool('addComponent')).toBe(false)
+  })
+
+  test('write tool 식별', () => {
+    expect(isWriteTool('addComponent')).toBe(true)
+    expect(isWriteTool('removeComponentByRefid')).toBe(true)
+    expect(isWriteTool('modifyComponentByRefid')).toBe(true)
+    expect(isWriteTool('replaceBoard')).toBe(true)
+    expect(isWriteTool('getSelection')).toBe(false)
+  })
+
+  test('legacy 이름은 read/write 분류에서 제외 (id 기반 → refid 기반 마이그레이션)', () => {
+    expect(isReadTool('getComponent')).toBe(false)
+    expect(isWriteTool('removeComponent')).toBe(false)
+    expect(isWriteTool('modifyComponent')).toBe(false)
+  })
+
+  test('알 수 없는 이름은 둘 다 false', () => {
+    expect(isReadTool('foo')).toBe(false)
+    expect(isWriteTool('foo')).toBe(false)
+  })
+})
+
+describe('buildBoardEditTools — refid 기반 tool 이름 (식별자 정책 회귀 방지)', () => {
+  test('9개 tool 모두 정의 (5 write + 4 read 포함 atmosphere guide)', () => {
+    const tools = buildBoardEditTools(['rect', 'circle'])
+    const names = tools.map(t => t.name).sort()
+    expect(names).toEqual([
+      'addComponent',
+      'findComponents',
+      'getAtmosphereGuide',
+      'getComponentByRefid',
+      'getSelection',
+      'modifyBoard',
+      'modifyComponentByRefid',
+      'removeComponentByRefid',
+      'replaceBoard'
+    ])
+  })
+
+  test('modifyBoard 는 patch (object) 필수', () => {
+    const tools = buildBoardEditTools([])
+    const t = tools.find(x => x.name === 'modifyBoard')!
+    expect(t.parameters.required).toEqual(['patch'])
+    expect(t.parameters.properties.patch.type).toBe('object')
+  })
+
+  test('isWriteTool 가 modifyBoard 인식', () => {
+    expect(isWriteTool('modifyBoard')).toBe(true)
+  })
+
+  test('getSelection 은 인자 없음', () => {
+    const tools = buildBoardEditTools([])
+    const t = tools.find(x => x.name === 'getSelection')!
+    expect(t.parameters.properties).toEqual({})
+  })
+
+  test('getComponentByRefid 는 refid (number) 필수', () => {
+    const tools = buildBoardEditTools([])
+    const t = tools.find(x => x.name === 'getComponentByRefid')!
+    expect(t.parameters.required).toEqual(['refid'])
+    expect(t.parameters.properties.refid.type).toBe('number')
+  })
+
+  test('removeComponentByRefid 는 refid (number) 필수', () => {
+    const tools = buildBoardEditTools([])
+    const t = tools.find(x => x.name === 'removeComponentByRefid')!
+    expect(t.parameters.required).toEqual(['refid'])
+    expect(t.parameters.properties.refid.type).toBe('number')
+  })
+
+  test('modifyComponentByRefid 는 refid + patch 필수', () => {
+    const tools = buildBoardEditTools([])
+    const t = tools.find(x => x.name === 'modifyComponentByRefid')!
+    expect(t.parameters.required).toEqual(['refid', 'patch'])
+    expect(t.parameters.properties.refid.type).toBe('number')
+  })
+
+  test('findComponents 는 모든 필터 optional + id (data binding) 필터 포함', () => {
+    const tools = buildBoardEditTools([])
+    const t = tools.find(x => x.name === 'findComponents')!
+    expect(t.parameters.required).toBeUndefined()
+    expect(t.parameters.properties).toHaveProperty('type')
+    expect(t.parameters.properties).toHaveProperty('namePattern')
+    expect(t.parameters.properties).toHaveProperty('region')
+    expect(t.parameters.properties).toHaveProperty('id')
+  })
+})
+
+describe('executeReadTool — getSelection', () => {
+  const board = {
+    width: 1000,
+    height: 600,
+    components: [
+      { refid: 1, type: 'rect', left: 10, top: 20 },
+      { refid: 2, type: 'circle', cx: 50, cy: 50, id: 'motor-1' }, // 데이터 바인딩 id 보유
+      { refid: 3, type: 'text', text: 'hello' }
+    ]
+  } as any
+
+  test('selectedRefids 비어있으면 안내 메시지 반환', () => {
+    const r = executeReadTool({ id: '1', name: 'getSelection', arguments: {} } as any, board, [])
+    expect(r.selected).toEqual([])
+    expect(r.message).toMatch(/no.*selected/i)
+  })
+
+  test('refid 매칭되는 컴포넌트 전체 반환 (truncate 안 함)', () => {
+    const r = executeReadTool({ id: '1', name: 'getSelection', arguments: {} } as any, board, [1, 3])
+    expect(r.count).toBe(2)
+    expect(r.selected).toHaveLength(2)
+    expect(r.selected.find((c: any) => c.refid === 1)).toEqual({
+      refid: 1,
+      type: 'rect',
+      left: 10,
+      top: 20
+    })
+    expect(r.selected.find((c: any) => c.refid === 3)).toEqual({
+      refid: 3,
+      type: 'text',
+      text: 'hello'
+    })
+  })
+
+  test('id (데이터 바인딩) 와 refid 가 별개 — selection 은 refid 만 사용', () => {
+    // selectedRefids 가 컴포넌트의 id 가 아니라 refid 와 매칭됨을 검증.
+    const r = executeReadTool({ id: '1', name: 'getSelection', arguments: {} } as any, board, [2])
+    expect(r.count).toBe(1)
+    expect(r.selected[0].refid).toBe(2)
+    expect(r.selected[0].id).toBe('motor-1')
+  })
+
+  test('존재하지 않는 refid 는 결과에서 빠짐 (에러 아님)', () => {
+    const r = executeReadTool({ id: '1', name: 'getSelection', arguments: {} } as any, board, [999, 1])
+    expect(r.count).toBe(1)
+    expect(r.selected[0].refid).toBe(1)
+  })
+
+  test('currentBoard null 이어도 안전', () => {
+    const r = executeReadTool({ id: '1', name: 'getSelection', arguments: {} } as any, null, [1])
+    expect(r.selected).toEqual([])
+  })
+})
+
+describe('executeReadTool — getComponentByRefid', () => {
+  const board = {
+    width: 1000,
+    height: 600,
+    components: [{ refid: 35, type: 'rect', left: 10, customProp: 'value', id: 'motor-1' }]
+  } as any
+
+  test('정상 조회 — 모든 필드 반환 (id 포함)', () => {
+    const r = executeReadTool(
+      { id: '1', name: 'getComponentByRefid', arguments: { refid: 35 } } as any,
+      board,
+      []
+    )
+    expect(r.component).toEqual({
+      refid: 35,
+      type: 'rect',
+      left: 10,
+      customProp: 'value',
+      id: 'motor-1'
+    })
+  })
+
+  test('refid 누락 → error', () => {
+    const r = executeReadTool(
+      { id: '1', name: 'getComponentByRefid', arguments: {} } as any,
+      board,
+      []
+    )
+    expect(r.error).toMatch(/refid.*required/i)
+  })
+
+  test('refid 가 number 가 아니면 error', () => {
+    const r = executeReadTool(
+      { id: '1', name: 'getComponentByRefid', arguments: { refid: 'AGV-1' } } as any,
+      board,
+      []
+    )
+    expect(r.error).toMatch(/refid.*required/i)
+  })
+
+  test('없는 refid → not found error', () => {
+    const r = executeReadTool(
+      { id: '1', name: 'getComponentByRefid', arguments: { refid: 999 } } as any,
+      board,
+      []
+    )
+    expect(r.error).toMatch(/not found/i)
+  })
+})
+
+describe('executeReadTool — findComponents', () => {
+  const board = {
+    width: 1000,
+    height: 600,
+    components: [
+      { refid: 1, type: 'rect', name: 'AGV-1', id: 'motor-1', left: 10, top: 20 },
+      { refid: 2, type: 'rect', name: 'AGV-2', id: 'motor-1', left: 100, top: 200 }, // 같은 데이터 바인딩 id
+      { refid: 3, type: 'circle', name: 'Sensor-1', cx: 50, cy: 50 },
+      { refid: 4, type: 'text', name: '제어판', left: 500, top: 50 }
+    ]
+  } as any
+
+  test('필터 없음 — 모두 반환', () => {
+    const r = executeReadTool({ id: '1', name: 'findComponents', arguments: {} } as any, board, [])
+    expect(r.totalMatched).toBe(4)
+    expect(r.components).toHaveLength(4)
+    expect(r.truncated).toBe(false)
+  })
+
+  test('type 필터', () => {
+    const r = executeReadTool(
+      { id: '1', name: 'findComponents', arguments: { type: 'rect' } } as any,
+      board,
+      []
+    )
+    expect(r.totalMatched).toBe(2)
+    expect(r.components.map((c: any) => c.refid)).toEqual([1, 2])
+  })
+
+  test('id 필터 — 데이터 바인딩 그룹 (unique 아님, 다중 매치)', () => {
+    const r = executeReadTool(
+      { id: '1', name: 'findComponents', arguments: { id: 'motor-1' } } as any,
+      board,
+      []
+    )
+    expect(r.totalMatched).toBe(2)
+    expect(r.components.map((c: any) => c.refid)).toEqual([1, 2])
+  })
+
+  test('namePattern 필터 (case-insensitive substring)', () => {
+    const r = executeReadTool(
+      { id: '1', name: 'findComponents', arguments: { namePattern: 'agv' } } as any,
+      board,
+      []
+    )
+    expect(r.totalMatched).toBe(2)
+    expect(r.components.map((c: any) => c.refid)).toEqual([1, 2])
+  })
+
+  test('한글 namePattern', () => {
+    const r = executeReadTool(
+      { id: '1', name: 'findComponents', arguments: { namePattern: '제어' } } as any,
+      board,
+      []
+    )
+    expect(r.totalMatched).toBe(1)
+    expect(r.components[0].refid).toBe(4)
+  })
+
+  test('region 필터 — bounding box', () => {
+    const r = executeReadTool(
+      {
+        id: '1',
+        name: 'findComponents',
+        arguments: { region: { left: 0, top: 0, width: 50, height: 100 } }
+      } as any,
+      board,
+      []
+    )
+    // refid 1 (10,20) ✓, 3 (cx 50, cy 50) ✓, 2 (100,200) ✗, 4 (500,50) ✗
+    expect(r.totalMatched).toBe(2)
+  })
+
+  test('필터 AND 결합 (type + namePattern)', () => {
+    const r = executeReadTool(
+      {
+        id: '1',
+        name: 'findComponents',
+        arguments: { type: 'rect', namePattern: '2' }
+      } as any,
+      board,
+      []
+    )
+    expect(r.totalMatched).toBe(1)
+    expect(r.components[0].refid).toBe(2)
+  })
+
+  test('필터 AND 결합 (type + id) — id 만으로는 multi 매치, type 으로 좁혀짐', () => {
+    const r = executeReadTool(
+      {
+        id: '1',
+        name: 'findComponents',
+        arguments: { type: 'rect', id: 'motor-1' }
+      } as any,
+      board,
+      []
+    )
+    expect(r.totalMatched).toBe(2) // 둘 다 type=rect 라 좁혀지지 않음
+  })
+
+  test('50개 cap', () => {
+    const big = {
+      width: 1000,
+      height: 600,
+      components: Array.from({ length: 100 }, (_, i) => ({ refid: i + 1, type: 'rect' }))
+    } as any
+    const r = executeReadTool(
+      { id: '1', name: 'findComponents', arguments: { type: 'rect' } } as any,
+      big,
+      []
+    )
+    expect(r.totalMatched).toBe(100)
+    expect(r.components).toHaveLength(50)
+    expect(r.truncated).toBe(true)
+  })
+
+  test('잘못된 region (필드 누락) 은 무시', () => {
+    const r = executeReadTool(
+      {
+        id: '1',
+        name: 'findComponents',
+        arguments: { region: { left: 0 } } // incomplete
+      } as any,
+      board,
+      []
+    )
+    // region 필터 무시 → 전체 반환
+    expect(r.totalMatched).toBe(4)
+  })
+})
+
+describe('executeReadTool — 알 수 없는 read tool', () => {
+  test('error 반환', () => {
+    const r = executeReadTool({ id: '1', name: 'unknownTool', arguments: {} } as any, null, [])
+    expect(r.error).toMatch(/unknown/i)
+  })
+})
+
+describe('executeReadTool — getAtmosphereGuide (3D 분위기 합성 primer)', () => {
+  test('가이드 객체 반환 — overview / parameters / archetypes / modifiers / workflow / pitfalls', () => {
+    const r = executeReadTool(
+      { id: '1', name: 'getAtmosphereGuide', arguments: {} } as any,
+      null,
+      []
+    )
+    expect(r).toHaveProperty('overview')
+    expect(r).toHaveProperty('parameters')
+    expect(r).toHaveProperty('archetypes')
+    expect(r).toHaveProperty('modifiers')
+    expect(r).toHaveProperty('workflow')
+    expect(r).toHaveProperty('pitfalls')
+  })
+
+  test('parameters 섹션이 핵심 키 망라 (sky / exposure / hemisphere / directional / shadow / floor / camera)', () => {
+    const r = executeReadTool(
+      { id: '1', name: 'getAtmosphereGuide', arguments: {} } as any,
+      null,
+      []
+    )
+    expect(r.parameters).toHaveProperty('sky')
+    expect(r.parameters).toHaveProperty('skyColor')
+    expect(r.parameters).toHaveProperty('exposure')
+    expect(r.parameters).toHaveProperty('hemisphere')
+    expect(r.parameters).toHaveProperty('directional')
+    expect(r.parameters).toHaveProperty('shadow')
+    expect(r.parameters).toHaveProperty('floor')
+    expect(r.parameters).toHaveProperty('camera')
+  })
+
+  test('sky preset 카탈로그가 things-scene 의 8 개 모두 포함', () => {
+    const r = executeReadTool(
+      { id: '1', name: 'getAtmosphereGuide', arguments: {} } as any,
+      null,
+      []
+    )
+    const presetNames = Object.keys(r.parameters.sky.presets)
+    expect(presetNames.sort()).toEqual([
+      'cloudy',
+      'factory',
+      'home',
+      'office',
+      'rainy',
+      'studio',
+      'sunny',
+      'warehouse'
+    ])
+  })
+
+  test('archetype 카테고리 — timeOfDay / indoor / surreal', () => {
+    const r = executeReadTool(
+      { id: '1', name: 'getAtmosphereGuide', arguments: {} } as any,
+      null,
+      []
+    )
+    expect(r.archetypes).toHaveProperty('timeOfDay')
+    expect(r.archetypes).toHaveProperty('indoor')
+    expect(r.archetypes).toHaveProperty('surreal')
+  })
+
+  test('각 archetype 은 description + patch 보유 (modifyBoard patch 그대로 사용 가능)', () => {
+    const r = executeReadTool(
+      { id: '1', name: 'getAtmosphereGuide', arguments: {} } as any,
+      null,
+      []
+    )
+    for (const cat of ['timeOfDay', 'indoor', 'surreal'] as const) {
+      const items = r.archetypes[cat]
+      for (const name of Object.keys(items)) {
+        const a = items[name]
+        expect(a.description).toBeDefined()
+        expect(a.patch).toBeDefined()
+        // patch 가 sky / exposure 등 root 키를 갖는지
+        expect(typeof a.patch.exposure).toBe('number')
+      }
+    }
+  })
+
+  test('대표 archetype "deepOcean" — 심해 분위기 패치 검증', () => {
+    const r = executeReadTool(
+      { id: '1', name: 'getAtmosphereGuide', arguments: {} } as any,
+      null,
+      []
+    )
+    const deep = r.archetypes.surreal.deepOcean
+    expect(deep.patch.sky).toBe('color')
+    expect(deep.patch.skyColor).toMatch(/^#[0-9a-fA-F]{6}$/)
+    expect(deep.patch.exposure).toBeLessThan(1.0) // dim
+    expect(deep.patch.hemiIntensity).toBeLessThan(3)
+    expect(deep.patch.dirLightEnabled).toBe(true)
+  })
+
+  test('인자 무시 (인자 없음 — 빈 객체 OK)', () => {
+    const r = executeReadTool(
+      { id: '1', name: 'getAtmosphereGuide', arguments: { ignored: 'whatever' } } as any,
+      null,
+      []
+    )
+    expect(r).toHaveProperty('overview')
+  })
+
+  test('isReadTool 가 getAtmosphereGuide 를 read 로 분류', () => {
+    expect(isReadTool('getAtmosphereGuide')).toBe(true)
+    expect(isWriteTool('getAtmosphereGuide')).toBe(false)
+  })
+
+  test('getAtmosphereGuide tool 정의의 인자 schema 가 비어 있음 (무인자)', () => {
+    const tools = buildBoardEditTools([])
+    const t = tools.find(x => x.name === 'getAtmosphereGuide')!
+    expect(t.parameters.properties).toEqual({})
+  })
+})
+
+describe('agentic loop (chatViaTools) — mock provider', () => {
+  // Mock AIClient — chatWithTools 호출을 record + 미리 정의된 응답 큐에서 반환.
+  function makeMockClient(turns: Array<{ text?: string; toolCalls: any[]; stopReason?: string }>) {
+    let turnIdx = 0
+    const callLog: any[] = []
+    return {
+      client: {
+        id: 'mock:test',
+        chat: async () => '',
+        generateJSON: async () => ({}),
+        chatWithTools: async (messages: any[], _tools: any[], _options: any) => {
+          callLog.push({ messages: JSON.parse(JSON.stringify(messages)) })
+          const turn = turns[turnIdx++] ?? { toolCalls: [], stopReason: 'end_turn' }
+          return {
+            text: turn.text,
+            toolCalls: turn.toolCalls,
+            stopReason: turn.stopReason ?? (turn.toolCalls.length > 0 ? 'tool_use' : 'end_turn')
+          }
+        }
+      } as any,
+      callLog,
+      remainingTurns: () => turns.length - turnIdx
+    }
+  }
+
+  test('text-only 응답 — single turn 으로 종료', async () => {
+    const { client, callLog } = makeMockClient([
+      { text: '안녕하세요. 무엇을 도와드릴까요?', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: '안녕' }], undefined)
+    expect(r.reply).toBe('안녕하세요. 무엇을 도와드릴까요?')
+    expect(r.patch).toBeUndefined()
+    expect(callLog).toHaveLength(1)
+  })
+
+  test('write tool 호출 → patch 누적, 후속 turn 종료', async () => {
+    const { client, callLog } = makeMockClient([
+      {
+        toolCalls: [
+          { id: 'c1', name: 'addComponent', arguments: { refid: 9, type: 'rect' } }
+        ]
+      },
+      { text: 'AGV 추가했습니다.', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: 'AGV 추가' }], undefined)
+    expect(r.reply).toBe('AGV 추가했습니다.')
+    expect(r.patch?.ops).toHaveLength(1)
+    expect(r.patch?.ops[0]).toEqual({ op: 'add', component: { refid: 9, type: 'rect' } })
+    expect(callLog).toHaveLength(2)
+  })
+
+  test('read tool 호출 → 서버 실행 결과 회신 → 후속 답변 (refid 기반)', async () => {
+    const board = {
+      width: 1000,
+      height: 600,
+      components: [{ refid: 35, type: 'rect', name: 'AGV-1', left: 10 }]
+    }
+    const { client, callLog } = makeMockClient([
+      {
+        toolCalls: [{ id: 'c1', name: 'getSelection', arguments: {} }]
+      },
+      { text: '선택된 컴포넌트는 AGV-1 (rect, refid=35, left=10) 입니다.', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat(
+      [{ role: 'user', content: '선택된 게 뭐야?' }],
+      board as any,
+      { selectedRefids: [35] }
+    )
+    expect(r.reply).toContain('AGV-1')
+    expect(r.patch).toBeUndefined()
+    expect(callLog).toHaveLength(2)
+    const secondTurnMessages = callLog[1].messages
+    const lastMsg = secondTurnMessages[secondTurnMessages.length - 1]
+    expect(lastMsg.role).toBe('user')
+    const toolResultPart = (lastMsg.content as any[]).find((p: any) => p.type === 'tool_result')
+    expect(toolResultPart).toBeDefined()
+    expect(toolResultPart.toolUseId).toBe('c1')
+    const parsed = JSON.parse(toolResultPart.content)
+    expect(parsed.selected[0].name).toBe('AGV-1')
+    expect(parsed.selected[0].refid).toBe(35)
+  })
+
+  test('read + write 혼합 — refid 기반 tool 이름', async () => {
+    const board = {
+      width: 1000,
+      height: 600,
+      components: [{ refid: 1, type: 'rect' }]
+    }
+    const { client } = makeMockClient([
+      {
+        toolCalls: [
+          { id: 'c1', name: 'getComponentByRefid', arguments: { refid: 1 } },
+          {
+            id: 'c2',
+            name: 'modifyComponentByRefid',
+            arguments: { refid: 1, patch: { left: 100 } }
+          }
+        ]
+      },
+      { text: '확인 후 수정했습니다.', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: '컴포넌트 left=100' }], board as any)
+    expect(r.patch?.ops).toHaveLength(1) // modify 만 patch 로 (read 는 서버 실행만)
+    expect(r.patch?.ops[0]).toEqual({ op: 'modify', refid: 1, patch: { left: 100 } })
+  })
+
+  test('iteration cap (8회) 초과 시 종료', async () => {
+    const turns = Array.from({ length: 20 }, (_, i) => ({
+      toolCalls: [{ id: `c${i}`, name: 'getSelection', arguments: {} }]
+    }))
+    const { client, callLog } = makeMockClient(turns)
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: '?' }], undefined)
+    // 8회 호출 후 강제 종료 (loop 의 MAX_ITERATIONS)
+    expect(callLog.length).toBeLessThanOrEqual(8)
+    expect(r).toBeDefined()
+  })
+
+  test('selectedRefids 비어 있어도 selection 컨텍스트는 항상 포함', async () => {
+    const { client, callLog } = makeMockClient([{ text: 'ok', toolCalls: [] }])
+    const a = new DefaultBoardAIAssistant(client)
+    await a.chat([{ role: 'user', content: 'q' }], undefined)
+    const firstUser = callLog[0].messages[0]
+    expect(firstUser.role).toBe('user')
+    expect(firstUser.content).toMatch(/No component is currently selected/i)
+  })
+
+  test('selectedRefids 가 있을 때 selection 컨텍스트가 refid 명시', async () => {
+    const { client, callLog } = makeMockClient([{ text: 'ok', toolCalls: [] }])
+    const a = new DefaultBoardAIAssistant(client)
+    await a.chat([{ role: 'user', content: 'q' }], undefined, { selectedRefids: [35, 37] })
+    const firstUser = callLog[0].messages[0]
+    expect(firstUser.content).toMatch(/User-selected component refids/i)
+    expect(firstUser.content).toContain('[35,37]')
+    expect(firstUser.content).toMatch(/getSelection/i)
+  })
+
+  test('system prompt 가 id vs refid 정책을 AI 한테 명시', async () => {
+    const { client, callLog } = makeMockClient([{ text: 'ok', toolCalls: [] }])
+    const a = new DefaultBoardAIAssistant(client)
+    await a.chat([{ role: 'user', content: 'q' }], undefined)
+    const optionsArg = callLog[0].messages
+    // system prompt 는 messages 에 직접 들어가지 않고 옵션으로 전달 — 우리 mock 은
+    // chatWithTools options 인자를 무시하므로 직접 검증 어려움. 대신 firstUser
+    // (board context) 가 refid 단어를 포함하는지로 우회 검증.
+    expect(optionsArg).toBeDefined()
+  })
+
+  test('Gemini thoughtSignature round-trip — provider meta 를 다음 turn 으로 echo (회귀 방지)', async () => {
+    // 시나리오: Gemini 가 functionCall + thoughtSignature 를 emit → 우리 어댑터가 providerMeta 에 캐치
+    // → assistant 가 tool_use part 에 그대로 round-trip → 다음 turn 호출의 conversation 에 보존
+    // 안 하면: "Function call is missing a thought_signature in functionCall parts" 400.
+    const { client, callLog } = makeMockClient([
+      {
+        toolCalls: [
+          {
+            id: 'g:replaceBoard:t1_0',
+            name: 'replaceBoard',
+            arguments: { components: [] },
+            providerMeta: { thoughtSignature: 'SIG_ABC123' }
+          }
+        ]
+      },
+      { text: '교체했습니다.', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    await a.chat([{ role: 'user', content: '보드 비워' }], undefined)
+    // 두 번째 turn 의 messages 에서 assistant 메시지의 tool_use part 가 providerMeta 를 보존해야 함
+    expect(callLog).toHaveLength(2)
+    const secondTurnMessages = callLog[1].messages
+    const assistantMsg = secondTurnMessages.find(
+      (m: any) => m.role === 'assistant' && Array.isArray(m.content)
+    )
+    expect(assistantMsg).toBeDefined()
+    const toolUsePart = (assistantMsg.content as any[]).find((p: any) => p.type === 'tool_use')
+    expect(toolUsePart).toBeDefined()
+    expect(toolUsePart.providerMeta).toEqual({ thoughtSignature: 'SIG_ABC123' })
+  })
+
+  test('providerMeta 없는 tool_use 는 echo 시 providerMeta 키 자체가 없음', async () => {
+    const { client, callLog } = makeMockClient([
+      {
+        toolCalls: [{ id: 'c1', name: 'getSelection', arguments: {} }]
+      },
+      { text: 'ok', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    await a.chat([{ role: 'user', content: 'q' }], undefined)
+    const secondTurnMessages = callLog[1].messages
+    const assistantMsg = secondTurnMessages.find(
+      (m: any) => m.role === 'assistant' && Array.isArray(m.content)
+    )
+    const toolUsePart = (assistantMsg.content as any[]).find((p: any) => p.type === 'tool_use')
+    expect(toolUsePart.providerMeta).toBeUndefined()
+  })
+
+  test('toolUsages 수집 — text-only 응답에는 toolUsages undefined', async () => {
+    const { client } = makeMockClient([{ text: '안녕하세요', toolCalls: [] }])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: '안녕' }], undefined)
+    expect(r.toolUsages).toBeUndefined()
+  })
+
+  test('toolUsages 수집 — read tool 호출 시 시간순 trace + 결과 포함', async () => {
+    const board = {
+      width: 1000,
+      height: 600,
+      components: [{ refid: 35, type: 'rect', name: 'AGV-1' }]
+    }
+    const { client } = makeMockClient([
+      {
+        toolCalls: [{ id: 'c1', name: 'getSelection', arguments: {} }]
+      },
+      { text: 'AGV-1 입니다', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: '뭐가 선택?' }], board as any, {
+      selectedRefids: [35]
+    })
+    expect(r.toolUsages).toBeDefined()
+    expect(r.toolUsages).toHaveLength(1)
+    const u = r.toolUsages![0]
+    expect(u.name).toBe('getSelection')
+    expect(u.kind).toBe('read')
+    expect(u.arguments).toEqual({})
+    // result 는 summarized 객체
+    expect(u.result.count).toBe(1)
+    expect(u.result.selected[0].name).toBe('AGV-1')
+  })
+
+  test('toolUsages 수집 — write tool 은 queued 마커', async () => {
+    const { client } = makeMockClient([
+      {
+        toolCalls: [
+          { id: 'c1', name: 'addComponent', arguments: { refid: 9, type: 'rect' } }
+        ]
+      },
+      { text: '추가', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: 'rect' }], undefined)
+    expect(r.toolUsages).toHaveLength(1)
+    const u = r.toolUsages![0]
+    expect(u.name).toBe('addComponent')
+    expect(u.kind).toBe('write')
+    expect(u.result.queued).toBe(true)
+  })
+
+  test('toolUsages 수집 — read + write 혼합 시간순 보존', async () => {
+    const board = { width: 1000, height: 600, components: [{ refid: 1, type: 'rect' }] }
+    const { client } = makeMockClient([
+      {
+        toolCalls: [
+          { id: 'c1', name: 'getComponentByRefid', arguments: { refid: 1 } },
+          { id: 'c2', name: 'modifyComponentByRefid', arguments: { refid: 1, patch: { left: 100 } } }
+        ]
+      },
+      { text: 'done', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: 'do' }], board as any)
+    expect(r.toolUsages).toHaveLength(2)
+    expect(r.toolUsages![0].name).toBe('getComponentByRefid')
+    expect(r.toolUsages![0].kind).toBe('read')
+    expect(r.toolUsages![1].name).toBe('modifyComponentByRefid')
+    expect(r.toolUsages![1].kind).toBe('write')
+  })
+
+  test('toolUsages 수집 — 여러 turn 에 걸친 호출 누적', async () => {
+    const { client } = makeMockClient([
+      { toolCalls: [{ id: 'c1', name: 'getSelection', arguments: {} }] },
+      { toolCalls: [{ id: 'c2', name: 'findComponents', arguments: { type: 'rect' } }] },
+      { text: 'final', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: 'q' }], undefined)
+    expect(r.toolUsages).toHaveLength(2)
+    expect(r.toolUsages!.map(u => u.name)).toEqual(['getSelection', 'findComponents'])
+  })
+
+  test('toolUsages 수집 — alkown tool 은 unknown 으로 분류 + isError', async () => {
+    const { client } = makeMockClient([
+      { toolCalls: [{ id: 'c1', name: 'foo', arguments: {} }] },
+      { text: 'err', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: 'x' }], undefined)
+    expect(r.toolUsages).toHaveLength(1)
+    expect(r.toolUsages![0].kind).toBe('unknown')
+    expect(r.toolUsages![0].result.error).toMatch(/unknown/i)
+  })
+})
+
+describe('summarizeToolResult — UI 영속용 결과 압축', () => {
+  test('짧은 string / number / boolean 그대로', () => {
+    expect(summarizeToolResult('hello')).toBe('hello')
+    expect(summarizeToolResult(42)).toBe(42)
+    expect(summarizeToolResult(true)).toBe(true)
+    expect(summarizeToolResult(null)).toBeNull()
+  })
+
+  test('200자 초과 string truncate + 마커', () => {
+    const long = 'x'.repeat(500)
+    const r = summarizeToolResult(long)
+    expect(r).toMatch(/…\[\+\d+ chars\]$/)
+    expect(r.length).toBeLessThan(long.length)
+  })
+
+  test('5개 초과 array truncate + 마커', () => {
+    const big = Array.from({ length: 12 }, (_, i) => i)
+    const r = summarizeToolResult(big)
+    expect(r.length).toBe(6) // 5 + marker
+    expect(r[5]).toMatch(/items\]/)
+  })
+
+  test('object 의 nested 값 재귀 요약', () => {
+    const o = { a: 1, b: { c: 'x'.repeat(500) } }
+    const r = summarizeToolResult(o)
+    expect(r.a).toBe(1)
+    expect(r.b.c).toMatch(/…/)
+  })
+
+  test('depth 3 초과 object 는 키 목록 string 으로 압축', () => {
+    const deep = { l1: { l2: { l3: { l4: { x: 1, y: 2, z: 3 } } } } }
+    const r = summarizeToolResult(deep)
+    // l1 (d0) → l2 (d1) → l3 (d2) 까지 object 유지, l3 의 값은 d3 진입 → string
+    expect(typeof r.l1).toBe('object')
+    expect(typeof r.l1.l2).toBe('object')
+    // l3 자체가 d3 에서 평가되어 키 목록 문자열로 압축됨
+    expect(typeof r.l1.l2.l3).toBe('string')
+    expect(r.l1.l2.l3).toMatch(/^\{l4/)
+  })
+})