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

package/server/service/assistant.test.ts

@@ -0,0 +1,2034 @@
+/**
+ * assistant.ts 의 pure helper 회귀 방지.
+ *
+ * 핵심 보호:
+ *  - LLM tool call → BoardEditOp 매핑이 잘못된 인자에서도 안전
+ *  - JSON fallback 응답 정규화: 망가진 ops, 빠진 confidence, 잘못된 타입에서도 적절히 무시
+ *  - summarizeBoard: 토큰 절감 — 컴포넌트 수 제한, 필요 속성만 노출
+ */
+import {
+  toolCallToBoardEditOp,
+  toolCallToBoardActionOp,
+  toolResultToChatResponse,
+  isReadTool,
+  isWriteTool,
+  isActionTool,
+  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 }
+    })
+  })
+
+  // Phase 2 — Scene 조작 tool dispatcher
+  test('alignComponents: 정상', () => {
+    const r = toolCallToBoardEditOp({
+      id: '1',
+      name: 'alignComponents',
+      arguments: { refids: [1, 2, 3], direction: 'left' }
+    } as any)
+    expect(r).toEqual({ op: 'align', refids: [1, 2, 3], direction: 'left' })
+  })
+
+  test('alignComponents: 잘못된 direction → null', () => {
+    expect(
+      toolCallToBoardEditOp({
+        id: '1',
+        name: 'alignComponents',
+        arguments: { refids: [1, 2], direction: 'sideways' }
+      } as any)
+    ).toBeNull()
+  })
+
+  test('alignComponents: refids 비어있음 → null', () => {
+    expect(
+      toolCallToBoardEditOp({
+        id: '1',
+        name: 'alignComponents',
+        arguments: { refids: [], direction: 'left' }
+      } as any)
+    ).toBeNull()
+  })
+
+  test('alignComponents: refids 안의 non-number 무시', () => {
+    const r = toolCallToBoardEditOp({
+      id: '1',
+      name: 'alignComponents',
+      arguments: { refids: [1, 'foo', 2, null], direction: 'center' }
+    } as any)
+    expect(r).toEqual({ op: 'align', refids: [1, 2], direction: 'center' })
+  })
+
+  test('distributeComponents: 정상', () => {
+    const r = toolCallToBoardEditOp({
+      id: '1',
+      name: 'distributeComponents',
+      arguments: { refids: [1, 2, 3], axis: 'horizontal' }
+    } as any)
+    expect(r).toEqual({ op: 'distribute', refids: [1, 2, 3], axis: 'horizontal' })
+  })
+
+  test('distributeComponents: 잘못된 axis → null', () => {
+    expect(
+      toolCallToBoardEditOp({
+        id: '1',
+        name: 'distributeComponents',
+        arguments: { refids: [1, 2, 3], axis: 'diagonal' }
+      } as any)
+    ).toBeNull()
+  })
+
+  test('groupComponents: 2개 이상 필수', () => {
+    expect(
+      toolCallToBoardEditOp({
+        id: '1',
+        name: 'groupComponents',
+        arguments: { refids: [1] }
+      } as any)
+    ).toBeNull()
+    expect(
+      toolCallToBoardEditOp({
+        id: '1',
+        name: 'groupComponents',
+        arguments: { refids: [1, 2] }
+      } as any)
+    ).toEqual({ op: 'group', refids: [1, 2] })
+  })
+
+  test('ungroupComponent: refid number 필수', () => {
+    expect(
+      toolCallToBoardEditOp({
+        id: '1',
+        name: 'ungroupComponent',
+        arguments: { refid: 5 }
+      } as any)
+    ).toEqual({ op: 'ungroup', refid: 5 })
+    expect(
+      toolCallToBoardEditOp({
+        id: '1',
+        name: 'ungroupComponent',
+        arguments: {}
+      } as any)
+    ).toBeNull()
+  })
+
+  test('changeZorder: 4 direction 모두', () => {
+    for (const d of ['front', 'back', 'forward', 'backward'] as const) {
+      const r = toolCallToBoardEditOp({
+        id: '1',
+        name: 'changeZorder',
+        arguments: { refid: 1, direction: d }
+      } as any)
+      expect(r).toEqual({ op: 'zorder', refid: 1, direction: d })
+    }
+  })
+
+  test('changeZorder: 잘못된 direction → null', () => {
+    expect(
+      toolCallToBoardEditOp({
+        id: '1',
+        name: 'changeZorder',
+        arguments: { refid: 1, direction: 'sideways' }
+      } as any)
+    ).toBeNull()
+  })
+
+  // C-1 — ephemeral action tool dispatcher (toolCallToBoardActionOp 별도)
+  test('toolCallToBoardActionOp — selectComponents 정상', () => {
+    const r = toolCallToBoardActionOp({
+      id: '1',
+      name: 'selectComponents',
+      arguments: { refids: [1, 2, 3] }
+    } as any)
+    expect(r).toEqual({ action: 'selectComponents', refids: [1, 2, 3] })
+  })
+
+  test('toolCallToBoardActionOp — selectComponents 빈 배열도 OK (deselect)', () => {
+    const r = toolCallToBoardActionOp({
+      id: '1',
+      name: 'selectComponents',
+      arguments: { refids: [] }
+    } as any)
+    expect(r).toEqual({ action: 'selectComponents', refids: [] })
+  })
+
+  test('toolCallToBoardActionOp — selectComponents non-number 무시', () => {
+    const r = toolCallToBoardActionOp({
+      id: '1',
+      name: 'selectComponents',
+      arguments: { refids: [1, 'foo', 2] }
+    } as any)
+    expect(r).toEqual({ action: 'selectComponents', refids: [1, 2] })
+  })
+
+  test('toolCallToBoardActionOp — centerToComponent + animated', () => {
+    expect(
+      toolCallToBoardActionOp({
+        id: '1',
+        name: 'centerToComponent',
+        arguments: { refid: 7, animated: false }
+      } as any)
+    ).toEqual({ action: 'centerToComponent', refid: 7, animated: false })
+  })
+
+  test('toolCallToBoardActionOp — centerToComponent refid 누락 → null', () => {
+    expect(
+      toolCallToBoardActionOp({
+        id: '1',
+        name: 'centerToComponent',
+        arguments: {}
+      } as any)
+    ).toBeNull()
+  })
+
+  test('toolCallToBoardActionOp — fitToView 인자 없음 OK', () => {
+    expect(
+      toolCallToBoardActionOp({ id: '1', name: 'fitToView', arguments: {} } as any)
+    ).toEqual({ action: 'fitToView' })
+  })
+
+  test('toolCallToBoardActionOp — fitToView 잘못된 mode 는 무시', () => {
+    expect(
+      toolCallToBoardActionOp({
+        id: '1',
+        name: 'fitToView',
+        arguments: { mode: 'diagonal' }
+      } as any)
+    ).toEqual({ action: 'fitToView' }) // mode 키 자체가 빠짐
+  })
+
+  test('toolCallToBoardActionOp — setSceneMode edit/view 만', () => {
+    expect(
+      toolCallToBoardActionOp({
+        id: '1',
+        name: 'setSceneMode',
+        arguments: { mode: 'edit' }
+      } as any)
+    ).toEqual({ action: 'setSceneMode', mode: 'edit' })
+    expect(
+      toolCallToBoardActionOp({
+        id: '1',
+        name: 'setSceneMode',
+        arguments: { mode: 'something' }
+      } as any)
+    ).toBeNull()
+  })
+
+  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()
+  })
+
+  // Sugar layout — arrangeInGrid/Row/Column dispatcher
+  test('arrangeInGrid: 정상 — refids + cols + 기본값', () => {
+    const r = toolCallToBoardEditOp({
+      id: '1',
+      name: 'arrangeInGrid',
+      arguments: { refids: [1, 2, 3, 4], cols: 2 }
+    } as any)
+    expect(r?.op).toBe('arrange')
+    if (r && r.op === 'arrange') {
+      expect(r.refids).toEqual([1, 2, 3, 4])
+      expect(r.layout).toEqual({ type: 'grid', cols: 2 })
+    }
+  })
+
+  test('arrangeInGrid: gap + anchor 반영', () => {
+    const r = toolCallToBoardEditOp({
+      id: '1',
+      name: 'arrangeInGrid',
+      arguments: {
+        refids: [1, 2, 3],
+        cols: 3,
+        gap: 20,
+        anchor: { left: 100, top: 50 }
+      }
+    } as any)
+    if (r && r.op === 'arrange' && r.layout.type === 'grid') {
+      expect(r.layout.gap).toBe(20)
+      expect(r.layout.anchor).toEqual({ left: 100, top: 50 })
+    }
+  })
+
+  test('arrangeInGrid: cols 누락 / refids 부족 → null', () => {
+    expect(
+      toolCallToBoardEditOp({
+        id: '1',
+        name: 'arrangeInGrid',
+        arguments: { refids: [1, 2] }
+      } as any)
+    ).toBeNull()
+    expect(
+      toolCallToBoardEditOp({
+        id: '1',
+        name: 'arrangeInGrid',
+        arguments: { refids: [1], cols: 2 }
+      } as any)
+    ).toBeNull()
+  })
+
+  test('arrangeInGrid: cols 가 1 미만 → null', () => {
+    expect(
+      toolCallToBoardEditOp({
+        id: '1',
+        name: 'arrangeInGrid',
+        arguments: { refids: [1, 2], cols: 0 }
+      } as any)
+    ).toBeNull()
+  })
+
+  test('arrangeInRow: 정상 — refids 만 있어도 OK', () => {
+    const r = toolCallToBoardEditOp({
+      id: '1',
+      name: 'arrangeInRow',
+      arguments: { refids: [1, 2, 3] }
+    } as any)
+    expect(r?.op).toBe('arrange')
+    if (r && r.op === 'arrange') {
+      expect(r.layout).toEqual({ type: 'row' })
+    }
+  })
+
+  test('arrangeInRow: align + gap', () => {
+    const r = toolCallToBoardEditOp({
+      id: '1',
+      name: 'arrangeInRow',
+      arguments: { refids: [1, 2], align: 'center', gap: 30 }
+    } as any)
+    if (r && r.op === 'arrange' && r.layout.type === 'row') {
+      expect(r.layout.align).toBe('center')
+      expect(r.layout.gap).toBe(30)
+    }
+  })
+
+  test('arrangeInRow: 잘못된 align 은 무시 (drop)', () => {
+    const r = toolCallToBoardEditOp({
+      id: '1',
+      name: 'arrangeInRow',
+      arguments: { refids: [1, 2], align: 'top' }
+    } as any)
+    if (r && r.op === 'arrange' && r.layout.type === 'row') {
+      expect(r.layout.align).toBeUndefined()
+    }
+  })
+
+  test('arrangeInColumn: 정상', () => {
+    const r = toolCallToBoardEditOp({
+      id: '1',
+      name: 'arrangeInColumn',
+      arguments: { refids: [1, 2], align: 'end', gap: 5 }
+    } as any)
+    if (r && r.op === 'arrange') {
+      expect(r.layout).toEqual({ type: 'column', gap: 5, align: 'end' })
+    }
+  })
+
+  test('arrangeInRow/Column: refids < 2 → null', () => {
+    expect(
+      toolCallToBoardEditOp({
+        id: '1',
+        name: 'arrangeInRow',
+        arguments: { refids: [1] }
+      } as any)
+    ).toBeNull()
+    expect(
+      toolCallToBoardEditOp({
+        id: '1',
+        name: 'arrangeInColumn',
+        arguments: { refids: [] }
+      } as any)
+    ).toBeNull()
+  })
+
+  test('arrange tool 들 모두 isWriteTool', () => {
+    expect(isWriteTool('arrangeInGrid')).toBe(true)
+    expect(isWriteTool('arrangeInRow')).toBe(true)
+    expect(isWriteTool('arrangeInColumn')).toBe(true)
+  })
+
+  // Prefab — addPrefab dispatcher
+  test('addPrefab: 정상 — registry 의 build 호출 + add op 으로 매핑', () => {
+    const r = toolCallToBoardEditOp({
+      id: '1',
+      name: 'addPrefab',
+      arguments: {
+        name: 'monitor-card',
+        left: 100,
+        top: 50,
+        options: { title: '온도', value: '23.5°C' }
+      }
+    } as any)
+    expect(r?.op).toBe('add')
+    if (r && r.op === 'add') {
+      expect((r.component as any).type).toBe('group')
+      expect((r.component as any).left).toBe(100)
+      expect((r.component as any).top).toBe(50)
+      // 옵션이 자식 텍스트로 반영
+      const texts = (r.component as any).components
+        .filter((c: any) => c.type === 'text')
+        .map((c: any) => c.text)
+      expect(texts).toContain('온도')
+    }
+  })
+
+  test('addPrefab: width/height override', () => {
+    const r = toolCallToBoardEditOp({
+      id: '1',
+      name: 'addPrefab',
+      arguments: { name: 'monitor-card', left: 0, top: 0, width: 300, height: 180 }
+    } as any)
+    if (r && r.op === 'add') {
+      expect((r.component as any).width).toBe(300)
+      expect((r.component as any).height).toBe(180)
+    }
+  })
+
+  test('addPrefab: 등록되지 않은 name → null', () => {
+    const r = toolCallToBoardEditOp({
+      id: '1',
+      name: 'addPrefab',
+      arguments: { name: 'no-such-prefab', left: 0, top: 0 }
+    } as any)
+    expect(r).toBeNull()
+  })
+
+  test('addPrefab: name 누락 → null', () => {
+    expect(
+      toolCallToBoardEditOp({
+        id: '1',
+        name: 'addPrefab',
+        arguments: { left: 0, top: 0 }
+      } as any)
+    ).toBeNull()
+  })
+
+  test('addPrefab: 좌표 누락 → null', () => {
+    expect(
+      toolCallToBoardEditOp({
+        id: '1',
+        name: 'addPrefab',
+        arguments: { name: 'monitor-card' }
+      } as any)
+    ).toBeNull()
+    expect(
+      toolCallToBoardEditOp({
+        id: '1',
+        name: 'addPrefab',
+        arguments: { name: 'monitor-card', left: 0 }
+      } as any)
+    ).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('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('41개 tool 모두 정의 (25 write + 8 read + 4 ephemeral action + 4 import)', () => {
+    const tools = buildBoardEditTools(['rect', 'circle'])
+    const names = tools.map(t => t.name).sort()
+    expect(names).toEqual([
+      'addComponent',
+      'addPrefab',
+      'alignComponents',
+      'arrangeInColumn',
+      'arrangeInGrid',
+      'arrangeInRow',
+      'centerToComponent',
+      'changeZorder',
+      'clearStyle',
+      'copyStyle',
+      'distributeComponents',
+      'findComponents',
+      'fitToView',
+      'getAtmosphereGuide',
+      'getAvailablePrefabs',
+      'getColorPalettes',
+      'getComponentByRefid',
+      'getComponentStyle',
+      'getImportSession',
+      'getLayoutTemplates',
+      'getSelection',
+      'groupComponents',
+      'importBoardAsync',
+      'listImportAdapters',
+      'materializeImportSession',
+      'modifyBoard',
+      'modifyComponentByRefid',
+      'removeComponentByRefid',
+      'replaceBoard',
+      'selectComponents',
+      'setFill',
+      'setFont',
+      'setMaterial',
+      'setOpacity',
+      'setSceneMode',
+      'setShadow',
+      'setShadowProperties',
+      'setStroke',
+      'setText',
+      'setVisible',
+      'ungroupComponent'
+    ])
+  })
+
+  test('alignComponents 는 refids + direction 필수', () => {
+    const tools = buildBoardEditTools([])
+    const t = tools.find(x => x.name === 'alignComponents')!
+    expect(t.parameters.required.sort()).toEqual(['direction', 'refids'])
+    expect(t.parameters.properties.direction.enum).toContain('left')
+    expect(t.parameters.properties.direction.enum).toContain('center')
+    expect(t.parameters.properties.direction.enum).toContain('bottom')
+  })
+
+  test('distributeComponents 는 axis 가 horizontal/vertical 만', () => {
+    const tools = buildBoardEditTools([])
+    const t = tools.find(x => x.name === 'distributeComponents')!
+    expect(t.parameters.properties.axis.enum).toEqual(['horizontal', 'vertical'])
+  })
+
+  test('changeZorder 는 direction 4종 (front/back/forward/backward)', () => {
+    const tools = buildBoardEditTools([])
+    const t = tools.find(x => x.name === 'changeZorder')!
+    expect(t.parameters.properties.direction.enum).toEqual([
+      'front',
+      'back',
+      'forward',
+      'backward'
+    ])
+  })
+
+  test('Phase 2 op 모두 isWriteTool', () => {
+    expect(isWriteTool('alignComponents')).toBe(true)
+    expect(isWriteTool('distributeComponents')).toBe(true)
+    expect(isWriteTool('groupComponents')).toBe(true)
+    expect(isWriteTool('ungroupComponent')).toBe(true)
+    expect(isWriteTool('changeZorder')).toBe(true)
+  })
+
+  test('C-1 ephemeral action tool — read 도 write 도 아닌 별개 분류', () => {
+    for (const n of ['selectComponents', 'centerToComponent', 'fitToView', 'setSceneMode']) {
+      expect(isReadTool(n)).toBe(false)
+      expect(isWriteTool(n)).toBe(false)
+      expect(isActionTool(n)).toBe(true)
+    }
+  })
+
+  test('selectComponents 는 refids 필수 (빈 배열은 deselect)', () => {
+    const tools = buildBoardEditTools([])
+    const t = tools.find(x => x.name === 'selectComponents')!
+    expect(t.parameters.required).toEqual(['refids'])
+  })
+
+  test('centerToComponent 는 refid 필수, animated 옵션', () => {
+    const tools = buildBoardEditTools([])
+    const t = tools.find(x => x.name === 'centerToComponent')!
+    expect(t.parameters.required).toEqual(['refid'])
+    expect(t.parameters.properties.animated.type).toBe('boolean')
+  })
+
+  test('fitToView 는 mode optional (fit/ratio/width/height)', () => {
+    const tools = buildBoardEditTools([])
+    const t = tools.find(x => x.name === 'fitToView')!
+    expect(t.parameters.required).toBeUndefined()
+    expect(t.parameters.properties.mode.enum).toEqual(['fit', 'ratio', 'width', 'height'])
+  })
+
+  test('setSceneMode 는 edit/view enum', () => {
+    const tools = buildBoardEditTools([])
+    const t = tools.find(x => x.name === 'setSceneMode')!
+    expect(t.parameters.required).toEqual(['mode'])
+    expect(t.parameters.properties.mode.enum).toEqual(['edit', 'view'])
+  })
+
+  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 — getAvailablePrefabs (Prefab 카탈로그)', () => {
+  test('인자 없음 — 모든 prefab 반환', () => {
+    const r = executeReadTool(
+      { id: '1', name: 'getAvailablePrefabs', arguments: {} } as any,
+      null,
+      []
+    )
+    expect(r.count).toBeGreaterThan(0)
+    expect(Array.isArray(r.prefabs)).toBe(true)
+    // default 3종 노출
+    const names = r.prefabs.map((p: any) => p.name).sort()
+    expect(names).toContain('monitor-card')
+    expect(names).toContain('gauge-panel')
+    expect(names).toContain('stat-tile')
+  })
+
+  test('category 필터', () => {
+    const r = executeReadTool(
+      {
+        id: '1',
+        name: 'getAvailablePrefabs',
+        arguments: { category: 'monitoring' }
+      } as any,
+      null,
+      []
+    )
+    expect(r.prefabs.every((p: any) => p.category === 'monitoring')).toBe(true)
+  })
+
+  test('keywordPattern 매칭', () => {
+    const r = executeReadTool(
+      {
+        id: '1',
+        name: 'getAvailablePrefabs',
+        arguments: { keywordPattern: '게이지' }
+      } as any,
+      null,
+      []
+    )
+    expect(r.prefabs.find((p: any) => p.name === 'gauge-panel')).toBeDefined()
+  })
+
+  test('build 함수는 결과에 포함되지 않음 (LLM 토큰 절감 + 직렬화)', () => {
+    const r = executeReadTool(
+      { id: '1', name: 'getAvailablePrefabs', arguments: {} } as any,
+      null,
+      []
+    )
+    for (const p of r.prefabs) {
+      expect(p.build).toBeUndefined()
+    }
+  })
+
+  test('isReadTool 분류 — read 로', () => {
+    expect(isReadTool('getAvailablePrefabs')).toBe(true)
+    expect(isWriteTool('getAvailablePrefabs')).toBe(false)
+  })
+
+  test('isWriteTool 분류 — addPrefab 은 write', () => {
+    expect(isWriteTool('addPrefab')).toBe(true)
+    expect(isReadTool('addPrefab')).toBe(false)
+  })
+})
+
+describe('executeReadTool — getColorPalettes (색 팔레트 카탈로그)', () => {
+  test('카탈로그 객체 반환 — overview / palettes / recommendations / workflow / pitfalls', () => {
+    const r = executeReadTool(
+      { id: '1', name: 'getColorPalettes', arguments: {} } as any,
+      null,
+      []
+    )
+    expect(r).toHaveProperty('overview')
+    expect(r).toHaveProperty('palettes')
+    expect(r).toHaveProperty('recommendations')
+    expect(r).toHaveProperty('workflow')
+    expect(r).toHaveProperty('pitfalls')
+  })
+
+  test('palettes 7종 모두 등록', () => {
+    const r = executeReadTool(
+      { id: '1', name: 'getColorPalettes', arguments: {} } as any,
+      null,
+      []
+    )
+    const names = Object.keys(r.palettes).sort()
+    expect(names).toEqual([
+      'control-room-dark',
+      'financial-trader',
+      'industrial-steel',
+      'logistics-warm',
+      'medical-clean',
+      'neon-cyberpunk',
+      'paper-light'
+    ])
+  })
+
+  test('각 palette 가 표준 토큰 보유 (base/surface/border/text/muted/accent/4-status)', () => {
+    const r = executeReadTool(
+      { id: '1', name: 'getColorPalettes', arguments: {} } as any,
+      null,
+      []
+    )
+    const requiredKeys = [
+      'description',
+      'base',
+      'surface',
+      'border',
+      'text',
+      'muted',
+      'accent',
+      'success',
+      'warning',
+      'danger',
+      'info'
+    ]
+    for (const palette of Object.values(r.palettes)) {
+      for (const k of requiredKeys) {
+        expect(palette).toHaveProperty(k)
+      }
+    }
+  })
+
+  test('palette 의 색상값이 hex 문자열 형식', () => {
+    const r = executeReadTool(
+      { id: '1', name: 'getColorPalettes', arguments: {} } as any,
+      null,
+      []
+    )
+    const colorKeys = ['base', 'surface', 'border', 'text', 'muted', 'accent']
+    for (const palette of Object.values<any>(r.palettes)) {
+      for (const k of colorKeys) {
+        expect(palette[k]).toMatch(/^#[0-9a-fA-F]{6}$/)
+      }
+    }
+  })
+
+  test('recommendations 가 모든 카테고리 → palette 이름 배열', () => {
+    const r = executeReadTool(
+      { id: '1', name: 'getColorPalettes', arguments: {} } as any,
+      null,
+      []
+    )
+    for (const candidates of Object.values<any>(r.recommendations)) {
+      expect(Array.isArray(candidates)).toBe(true)
+      expect(candidates.length).toBeGreaterThan(0)
+      for (const name of candidates) {
+        expect(r.palettes[name]).toBeDefined() // 실제 등록된 palette 만 추천
+      }
+    }
+  })
+
+  test('isReadTool 분류', () => {
+    expect(isReadTool('getColorPalettes')).toBe(true)
+    expect(isWriteTool('getColorPalettes')).toBe(false)
+  })
+})
+
+describe('executeReadTool — getLayoutTemplates (Layout 템플릿 카탈로그)', () => {
+  test('카탈로그 객체 반환 — overview / templates / workflow / pitfalls', () => {
+    const r = executeReadTool(
+      { id: '1', name: 'getLayoutTemplates', arguments: {} } as any,
+      null,
+      []
+    )
+    expect(r).toHaveProperty('overview')
+    expect(r).toHaveProperty('templates')
+    expect(r).toHaveProperty('workflow')
+    expect(r).toHaveProperty('pitfalls')
+  })
+
+  test('templates 6종 등록 (kpi-row / 3x3-grid / t-shape / side-rail / split-half / header-content-footer)', () => {
+    const r = executeReadTool(
+      { id: '1', name: 'getLayoutTemplates', arguments: {} } as any,
+      null,
+      []
+    )
+    const names = Object.keys(r.templates).sort()
+    expect(names).toEqual([
+      '3x3-grid',
+      'header-content-footer',
+      'kpi-row',
+      'side-rail',
+      'split-half',
+      't-shape-command'
+    ])
+  })
+
+  test('각 template 의 slots 가 실 좌표/크기 보유', () => {
+    const r = executeReadTool(
+      { id: '1', name: 'getLayoutTemplates', arguments: {} } as any,
+      null,
+      []
+    )
+    for (const tpl of Object.values<any>(r.templates)) {
+      expect(Array.isArray(tpl.slots)).toBe(true)
+      expect(tpl.slots.length).toBeGreaterThan(0)
+      for (const slot of tpl.slots) {
+        expect(typeof slot.name).toBe('string')
+        expect(typeof slot.region.left).toBe('number')
+        expect(typeof slot.region.top).toBe('number')
+        expect(typeof slot.region.width).toBe('number')
+        expect(typeof slot.region.height).toBe('number')
+        expect(slot.region.width).toBeGreaterThan(0)
+        expect(slot.region.height).toBeGreaterThan(0)
+      }
+    }
+  })
+
+  test('3x3-grid 는 정확히 9개 slot', () => {
+    const r = executeReadTool(
+      { id: '1', name: 'getLayoutTemplates', arguments: {} } as any,
+      null,
+      []
+    )
+    expect(r.templates['3x3-grid'].slots).toHaveLength(9)
+  })
+
+  test('kpi-row 는 4개 KPI slot + main-area', () => {
+    const r = executeReadTool(
+      { id: '1', name: 'getLayoutTemplates', arguments: {} } as any,
+      null,
+      []
+    )
+    const slots = r.templates['kpi-row'].slots
+    const kpiSlots = slots.filter((s: any) => s.name.startsWith('kpi-'))
+    expect(kpiSlots).toHaveLength(4)
+    expect(slots.find((s: any) => s.name === 'main-area')).toBeDefined()
+  })
+
+  test('slot region 이 1280×720 보드 내부에 있음', () => {
+    const r = executeReadTool(
+      { id: '1', name: 'getLayoutTemplates', arguments: {} } as any,
+      null,
+      []
+    )
+    for (const tpl of Object.values<any>(r.templates)) {
+      const bw = tpl.boardSize.width
+      const bh = tpl.boardSize.height
+      for (const slot of tpl.slots) {
+        expect(slot.region.left + slot.region.width).toBeLessThanOrEqual(bw)
+        expect(slot.region.top + slot.region.height).toBeLessThanOrEqual(bh)
+      }
+    }
+  })
+
+  test('isReadTool 분류', () => {
+    expect(isReadTool('getLayoutTemplates')).toBe(true)
+    expect(isWriteTool('getLayoutTemplates')).toBe(false)
+  })
+})
+
+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', left: 10, top: 10, width: 50, height: 50 }
+          }
+        ]
+      },
+      { 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]).toMatchObject({
+      op: 'add',
+      component: { refid: 9, type: 'rect', left: 10, top: 10 }
+    })
+    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', left: 10, top: 10, width: 50, height: 50 }
+          }
+        ]
+      },
+      { 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)
+  })
+
+  test('actions 수집 — selectComponents 호출 시 ChatResponse.actions 누적', async () => {
+    const { client } = makeMockClient([
+      {
+        toolCalls: [
+          {
+            id: 'c1',
+            name: 'selectComponents',
+            arguments: { refids: [3, 5] }
+          }
+        ]
+      },
+      { text: '선택했습니다', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: '3, 5 선택' }], undefined)
+    expect(r.actions).toBeDefined()
+    expect(r.actions).toHaveLength(1)
+    expect(r.actions![0]).toEqual({ action: 'selectComponents', refids: [3, 5] })
+    // patch 는 비어 있어야 — action 은 model 변경 X
+    expect(r.patch).toBeUndefined()
+  })
+
+  test('actions 수집 — 다중 action 시퀀스 (centerTo + select + fit)', async () => {
+    const { client } = makeMockClient([
+      {
+        toolCalls: [
+          { id: 'c1', name: 'centerToComponent', arguments: { refid: 7 } },
+          { id: 'c2', name: 'selectComponents', arguments: { refids: [7] } },
+          { id: 'c3', name: 'fitToView', arguments: {} }
+        ]
+      },
+      { text: 'ok', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: '7 보여줘' }], undefined)
+    expect(r.actions).toHaveLength(3)
+    expect(r.actions!.map(a => a.action)).toEqual([
+      'centerToComponent',
+      'selectComponents',
+      'fitToView'
+    ])
+  })
+
+  test('actions 수집 — write 와 action 혼합 (modify + setSceneMode)', async () => {
+    const board = {
+      width: 1000,
+      height: 600,
+      components: [{ refid: 1, type: 'rect' }]
+    }
+    const { client } = makeMockClient([
+      {
+        toolCalls: [
+          {
+            id: 'c1',
+            name: 'modifyComponentByRefid',
+            arguments: { refid: 1, patch: { left: 100 } }
+          },
+          { id: 'c2', name: 'setSceneMode', arguments: { mode: 'view' } }
+        ]
+      },
+      { text: 'done', toolCalls: [] }
+    ])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: '바꾸고 뷰모드로' }], board as any)
+    // modify 는 patch.ops, setSceneMode 는 actions
+    expect(r.patch?.ops).toHaveLength(1)
+    expect(r.patch?.ops[0]).toEqual({ op: 'modify', refid: 1, patch: { left: 100 } })
+    expect(r.actions).toHaveLength(1)
+    expect(r.actions![0]).toEqual({ action: 'setSceneMode', mode: 'view' })
+  })
+
+  test('actions 미발생 시 ChatResponse.actions 는 undefined', async () => {
+    const { client } = makeMockClient([{ text: 'ok', toolCalls: [] }])
+    const a = new DefaultBoardAIAssistant(client)
+    const r = await a.chat([{ role: 'user', content: '안녕' }], undefined)
+    expect(r.actions).toBeUndefined()
+  })
+})
+
+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/)
+  })
+})