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

package/server/service/assistant.ts

@@ -0,0 +1,1431 @@
+/**
+ * DefaultBoardAIAssistant — base AIClient 위에 LLM 프롬프트로 chat() 구현.
+ */
+import type {
+  AIClient,
+  AIMessage,
+  AITool,
+  AIToolCall,
+  AIToolChatResult
+} from '@things-factory/ai-client-base'
+import {
+  getImportRules,
+  type BoardComponent,
+  type BoardModel,
+  type ComponentCategory
+} from '@things-factory/board-import'
+import type {
+  BoardAIAssistant,
+  BoardEditOp,
+  BoardEditPatch,
+  ChatOptions,
+  ChatResponse,
+  ComponentSchema,
+  LLMMessage,
+  ToolUsage
+} from './types.js'
+
+const ALL_CATEGORIES: ComponentCategory[] = [
+  'container',
+  'vehicle',
+  'path',
+  'region',
+  'equipment',
+  'io',
+  'marker',
+  'structure',
+  'unknown'
+]
+
+const MAX_BOARD_SUMMARY_COMPONENTS = 80
+
+export interface BoardAIAssistantOptions {
+  /** 기본 scope (chat 호출 시 옵션이 없으면 사용) */
+  scopes?: string[]
+  knownTypes?: string[]
+  categories?: ComponentCategory[]
+}
+
+export class DefaultBoardAIAssistant implements BoardAIAssistant {
+  readonly id: string
+  constructor(private base: AIClient, private options: BoardAIAssistantOptions = {}) {
+    this.id = base.id
+  }
+
+  async chat(
+    messages: LLMMessage[],
+    currentBoard: BoardModel | undefined,
+    options: ChatOptions = {}
+  ): Promise<ChatResponse> {
+    if (messages.length === 0) {
+      throw new Error('chat() requires at least one message')
+    }
+
+    const { knownTypes, categories } = this.resolveTypesAndCategories(options)
+    const schemas = options.componentSchemas ?? []
+
+    // Tool calling 가능하면 그 경로 (정확성 ★) — provider 가 schema 강제, invalid type / parse error 봉쇄
+    if (typeof this.base.chatWithTools === 'function') {
+      return await this.chatViaTools(messages, currentBoard, options, knownTypes, categories, schemas)
+    }
+
+    // Fallback — 기존 generateJSON 경로
+    return await this.chatViaJSON(messages, currentBoard, options, knownTypes, categories, schemas)
+  }
+
+  // ── Tool calling 경로 (agentic multi-turn) ─────────────────────────
+
+  private async chatViaTools(
+    messages: LLMMessage[],
+    currentBoard: BoardModel | undefined,
+    options: ChatOptions,
+    knownTypes: string[],
+    categories: ComponentCategory[],
+    schemas: ComponentSchema[]
+  ): Promise<ChatResponse> {
+    const tools = buildBoardEditTools(knownTypes)
+    const systemPrompt = this.buildSystemPromptForTools(knownTypes, categories, schemas)
+
+    const selectedRefids = (options.selectedRefids ?? []).filter(
+      (n): n is number => typeof n === 'number' && Number.isFinite(n)
+    )
+    // selection 정보는 항상 포함 (비어 있어도) — LLM 이 "선택된 게 뭐냐" 류 질문에
+    // getSelection 을 호출할지 판단하는 데 필요.
+    const selectionContext = selectedRefids.length > 0
+      ? `\n\nUser-selected component refids: ${JSON.stringify(selectedRefids)}\n` +
+        `When the user says "selected" / "선택한" / "this" / "그것" / "these" etc. ` +
+        `WITHOUT specifying targets, operate ONLY on these refids. ` +
+        `Do not modify other components unless explicitly asked. ` +
+        `For inspecting selected components, prefer calling \`getSelection\` over guessing.`
+      : `\n\nNo component is currently selected. If the user asks about "selected" / "this", ` +
+        `clarify or call \`getSelection\` to confirm.`
+
+    const boardContext = currentBoard
+      ? `Current board state (JSON, summarized; full details via \`getComponent\` / \`findComponents\`):\n` +
+        `${JSON.stringify(summarizeBoard(currentBoard), null, 2)}` + selectionContext
+      : 'No current board (empty start).' + selectionContext
+
+    let conversation: AIMessage[] = [
+      { role: 'user', content: boardContext },
+      ...messages.map<AIMessage>(m => ({
+        role: m.role === 'assistant' ? 'assistant' : 'user',
+        content: m.content
+      }))
+    ]
+
+    // multi-turn loop — LLM 이 read tool 을 호출하면 서버에서 즉시 실행 → 결과 회신 →
+    // LLM 이 다시 추론. write tool (add/remove/modify/replace) 은 누적해서 client 에 patch
+    // 로 전달. 무한 루프 방지를 위해 iteration cap.
+    const MAX_ITERATIONS = 8
+    const accumulatedWriteCalls: AIToolCall[] = []
+    const toolUsages: ToolUsage[] = []
+    let lastText: string | undefined
+    let stopReason: string = 'end_turn'
+
+    for (let iter = 0; iter < MAX_ITERATIONS; iter++) {
+      const result: AIToolChatResult = await this.base.chatWithTools!(conversation, tools, {
+        systemPrompt,
+        model: options.model,
+        temperature: options.temperature,
+        maxTokens: options.maxTokens,
+        toolChoice: 'auto',
+        allowParallelToolCalls: true
+      })
+
+      lastText = result.text || lastText
+      stopReason = result.stopReason
+
+      if (result.toolCalls.length === 0) break
+
+      // tool 결과 빌드 — read tool 은 서버 즉시 실행, write tool 은 누적 + LLM 에게 "queued"
+      const toolResultParts: any[] = []
+      for (const tc of result.toolCalls) {
+        if (isReadTool(tc.name)) {
+          const value = executeReadTool(tc, currentBoard, selectedRefids)
+          toolResultParts.push({
+            type: 'tool_result',
+            toolUseId: tc.id,
+            content: JSON.stringify(value)
+          })
+          toolUsages.push({
+            name: tc.name,
+            arguments: tc.arguments ?? {},
+            result: summarizeToolResult(value),
+            kind: 'read'
+          })
+        } else if (isWriteTool(tc.name)) {
+          accumulatedWriteCalls.push(tc)
+          const queuedResult = { queued: true, note: 'Will be applied on the client.' }
+          toolResultParts.push({
+            type: 'tool_result',
+            toolUseId: tc.id,
+            content: JSON.stringify(queuedResult)
+          })
+          toolUsages.push({
+            name: tc.name,
+            arguments: tc.arguments ?? {},
+            result: queuedResult,
+            kind: 'write'
+          })
+        } else {
+          const errResult = { error: `Unknown tool: ${tc.name}` }
+          toolResultParts.push({
+            type: 'tool_result',
+            toolUseId: tc.id,
+            content: JSON.stringify(errResult),
+            isError: true
+          })
+          toolUsages.push({
+            name: tc.name,
+            arguments: tc.arguments ?? {},
+            result: errResult,
+            kind: 'unknown'
+          })
+        }
+      }
+
+      // assistant 의 tool_use turn + user 의 tool_result turn 을 conversation 에 누적
+      const assistantContent: any[] = []
+      if (result.text) assistantContent.push({ type: 'text', text: result.text })
+      for (const tc of result.toolCalls) {
+        // providerMeta (Gemini thoughtSignature 등) 를 그대로 round-trip — 안 보내면 400.
+        assistantContent.push({
+          type: 'tool_use',
+          id: tc.id,
+          name: tc.name,
+          arguments: tc.arguments,
+          ...(tc.providerMeta && { providerMeta: tc.providerMeta })
+        })
+      }
+
+      conversation = [
+        ...conversation,
+        { role: 'assistant', content: assistantContent },
+        { role: 'user', content: toolResultParts }
+      ]
+
+      // write 만 있고 LLM 이 추가 추론 의도 없으면 다음 turn 으로 → 보통 final reply 1 턴이면 끝.
+      // read 도 없으면 굳이 더 돌릴 필요 없지만 일단 LLM 이 마무리 답변 줄 수 있도록 한 번 더 호출.
+    }
+
+    // accumulated write calls → BoardEditPatch
+    const ops = accumulatedWriteCalls
+      .map(toolCallToBoardEditOp)
+      .filter((op): op is BoardEditOp => op !== null)
+
+    const reply = lastText || (ops.length > 0 ? '변경했습니다.' : '')
+    let patch: BoardEditPatch | undefined
+    if (ops.length > 0) {
+      patch = {
+        ops,
+        summary: lastText ?? `${ops.length} edit op(s) applied`,
+        confidence: 0.9
+      }
+    }
+
+    return {
+      reply,
+      patch,
+      followUp: undefined,
+      toolUsages: toolUsages.length > 0 ? toolUsages : undefined
+    }
+  }
+
+  // ── Fallback (generateJSON) 경로 ──────────────────────────────────
+
+  private async chatViaJSON(
+    messages: LLMMessage[],
+    currentBoard: BoardModel | undefined,
+    options: ChatOptions,
+    knownTypes: string[],
+    categories: ComponentCategory[],
+    schemas: ComponentSchema[]
+  ): Promise<ChatResponse> {
+    const systemPrompt = this.buildSystemPrompt(knownTypes, categories, schemas)
+
+    const userPayload = {
+      currentBoard: currentBoard ? summarizeBoard(currentBoard) : null,
+      conversation: messages
+    }
+
+    const raw = await this.base.generateJSON<RawChatResponse>(
+      `User payload (JSON):\n${JSON.stringify(userPayload, null, 2)}`,
+      {
+        systemPrompt,
+        model: options.model,
+        temperature: options.temperature,
+        maxTokens: options.maxTokens
+      }
+    )
+
+    return normalizeChatResponse(raw)
+  }
+
+  private resolveTypesAndCategories(options: ChatOptions): {
+    knownTypes: string[]
+    categories: ComponentCategory[]
+  } {
+    const explicitTypes = options.knownTypes ?? this.options.knownTypes
+    const explicitCats = (options.categories ?? this.options.categories) as ComponentCategory[] | undefined
+    if (explicitTypes && explicitCats) {
+      return { knownTypes: explicitTypes, categories: explicitCats }
+    }
+
+    const scopes = options.scopes ?? this.options.scopes
+    if (scopes && scopes.length > 0) {
+      const rules = getImportRules(scopes)
+      const types = explicitTypes ?? Array.from(new Set(rules.map(r => r.componentType))).filter(Boolean)
+      const cats =
+        explicitCats ??
+        (Array.from(new Set(rules.map(r => r.category).filter(Boolean))) as ComponentCategory[])
+      return {
+        knownTypes: types,
+        categories: cats.length > 0 ? cats : ALL_CATEGORIES
+      }
+    }
+
+    return {
+      knownTypes: explicitTypes ?? [],
+      categories: explicitCats ?? ALL_CATEGORIES
+    }
+  }
+
+  private buildSystemPrompt(
+    knownTypes: string[],
+    categories: ComponentCategory[],
+    schemas: ComponentSchema[]
+  ): string {
+    const hasTypes = knownTypes.length > 0
+    const typeLine = hasTypes ? knownTypes.join(', ') : '(none registered)'
+    const catLine = categories.join(', ')
+    const schemaSection = formatSchemas(schemas, knownTypes)
+
+    return `You are a board modeling assistant. The user describes board components in natural language and you respond with:
+1. A short conversational reply in the same language as the user.
+2. Optionally, a board edit patch (4 op kinds: add, remove, modify, replace).
+
+==== AVAILABLE COMPONENT TYPES (STRICT WHITELIST) ====
+${typeLine}
+
+==== AVAILABLE GROUPS / CATEGORIES ====
+${catLine}
+
+==== COMPONENT SCHEMAS (type-specific geometry + properties) ====
+${schemaSection}
+
+CRITICAL — geometry discipline:
+- Each type has its OWN geometry keys, listed under "geometry:" above.
+- Use EXACTLY those keys for that type. Do NOT default to {left, top, width, height} for every type.
+- Examples:
+    rect/image/text: left, top, width, height
+    circle/ellipse: cx, cy, rx (or radius), ry
+    line/polyline: points or path or vertices array
+    gauge-* may use left, top, width, height OR cx, cy depending on the variant — follow the listed geometry keys.
+- For each component you add, include ALL its geometry keys with sensible numeric values (no undefined).
+- For type-specific REQUIRED properties (e.g., gauge needs value/min/max, chart needs data, text needs text), include them explicitly — do not omit.
+
+
+CRITICAL — type discipline:
+- Component "type" MUST be a value from the AVAILABLE COMPONENT TYPES list above. Exact string match.
+- DO NOT invent type names. DO NOT guess. DO NOT use domain names ("Stocker", "AGV", etc.) unless they appear verbatim in the list.
+- If the user describes a domain concept (e.g., "AGV", "스토커") that is NOT in the list:
+    a) Pick the closest registered type from the list, OR
+    b) Use a generic shape from the list (e.g. 'rect', 'ellipse', 'text') with descriptive fillStyle/strokeStyle and a "name" or "label" field that captures the user's intent.
+    c) NEVER fabricate a new type string.
+- If the AVAILABLE list is empty, you must respond with "followUp" asking the user to register components first; do NOT generate a patch.
+
+Respond ONLY with this JSON shape:
+{
+  "reply": "<short conversational text>",
+  "patch": {
+    "ops": [<op>...],
+    "summary": "<1-2 sentence summary>",
+    "confidence": <0..1>
+  } | null,
+  "followUp": "<clarifying question>" | null
+}
+
+Op shapes:
+- {"op":"add","component":{"type":"<from list>","id":"<unique>","left":<num>,"top":<num>,"width":<num>,"height":<num>,"rotation":<num,optional>,"fillStyle":"<css color, optional>","strokeStyle":"<css color, optional>","name":"<optional label>","threeD":{"geometry":{"kind":"box|cylinder|extrude|gltf",...},"material":{"color":"...","roughness":<0..1>,"metalness":<0..1>,"opacity":<0..1>}}}}
+- {"op":"remove","id":"<existing id>"}
+- {"op":"modify","id":"<existing id>","patch":{<partial fields including style/position/3D material>}}
+- {"op":"replace","board":{"width":<num>,"height":<num>,"components":[<component...>]}}
+
+Style edits (color, roughness, opacity, dash, 3D material) → use "modify" op with the changed style fields inside "patch". The "modify" op covers position/size/style/3D material — do NOT invent additional op kinds.
+
+Rules:
+- If user is asking a question rather than commanding, set "patch" to null and answer in "reply".
+- If user request is ambiguous, set "followUp" to a clarifying question and "patch" to null.
+- When the user starts from no current board, use "replace" op with a fresh board (or sensible default size: 1000x600).
+- Coordinates are in scene units (1 unit = 1 mm by convention); place components without overlap.
+- Output JSON only, no markdown fences, no commentary outside JSON.`
+  }
+
+  // ── Tool calling 용 system prompt ──────────────────────────────────
+
+  private buildSystemPromptForTools(
+    knownTypes: string[],
+    categories: ComponentCategory[],
+    schemas: ComponentSchema[]
+  ): string {
+    const typeLine = knownTypes.length > 0 ? knownTypes.join(', ') : '(none registered)'
+    const catLine = categories.join(', ')
+    const schemaSection = formatSchemas(schemas, knownTypes)
+
+    return `You are a board modeling assistant. Edit the board by calling the provided tools.
+
+==== BOARD HIERARCHY (CRITICAL) ====
+The BOARD itself is the TOPMOST PARENT. It is NOT a component — it has its own
+root-level properties separate from any child:
+
+  • Root attributes (board-level): \`fillStyle\` (background color), \`width\`,
+    \`height\` (dimensions), \`name\` (label), and possibly other metadata.
+  • Children: an array of components inside the board (rect / circle / text /
+    gauge / etc.).
+
+Rules:
+  - To change a board-level attribute (background color, board size, board name)
+    → call \`modifyBoard({ patch: { fillStyle: ..., width: ..., ... } })\`.
+  - To change a CHILD COMPONENT's attribute → call \`modifyComponentByRefid\`.
+  - DO NOT use modifyBoard to change a child. DO NOT use modifyComponentByRefid
+    to change board background.
+  - "보드 배경색", "board background", "테두리/캔버스 크기" 같은 요청은 root
+    attribute 변경 → \`modifyBoard\`.
+
+==== IDENTIFIER POLICY (CRITICAL) ====
+Each CHILD component has TWO distinct identifier-like fields. Do NOT confuse them:
+
+  • \`refid\` (number) — UNIVERSAL HANDLE. things-scene auto-assigns to every
+                       component. Always present. Unique per component within
+                       a board. The ONLY identifier used to target a component
+                       for inspection / modification / deletion.
+
+  • \`id\` (string) — DATA BINDING NAME. Optional. Multiple components MAY share
+                     the same id (e.g., several gauges all bound to the same
+                     data feed). NOT unique. Treat as metadata only.
+
+Rules:
+  - To inspect / modify / remove a child component → use refid.
+  - When you see "id: 'motor-1'" in board summary, it is a data-binding label,
+    not a unique handle. Two components with id='motor-1' may both exist.
+  - findComponents may return many matches when filtered by id (data binding
+    group); that is correct.
+  - Selection from the user is always communicated as a list of refids.
+  - The BOARD itself does NOT have refid (only children do). Use \`modifyBoard\`
+    for board-level changes.
+
+==== AVAILABLE TOOLS ====
+Board-level (root attributes):
+  - modifyBoard: change board's own fillStyle / width / height / name AND 3D atmosphere keys (sky / exposure / hemi* / dirLight* / floorMaterial3d / ...)
+  - replaceBoard: wholesale board reset (heavy — prefer modifyBoard for most changes)
+Child components:
+  - addComponent: add a new component (parallel calls for multiple adds)
+  - removeComponentByRefid: remove a child by refid
+  - modifyComponentByRefid: edit a child's properties by refid
+  - getComponentByRefid: inspect full data of one child by refid
+  - getSelection: return full data of components currently selected by the user
+  - findComponents: search children by type/id/name/region — returns matches with refid
+Knowledge:
+  - getAtmosphereGuide: 3D atmosphere synthesis primer — parameter physics, ranges, color theory, archetype recipes (time-of-day / indoor / surreal). Call BEFORE applying atmospheric/styling modifyBoard for any natural-language mood request.
+
+==== 3D ATMOSPHERE SYNTHESIS ====
+3D scene atmosphere = combination of (1) sky preset / color (2) exposure (3) hemisphere ambient (4) directional sun/key (5) floor material. ALL of these are root-level board attributes — applied via a SINGLE modifyBoard call.
+
+For ANY natural-language atmospheric request — "공장 분위기로", "심해 컬러", "황혼", "사이버펑크", "안개 자욱한 새벽", "1980 우주정거장", "따뜻하게", "차갑고 극적으로" — follow this workflow:
+
+  1. Call getAtmosphereGuide first.
+  2. From the guide's "archetypes" section, pick the closest base recipe (time-of-day / indoor / surreal). Interpolate if user combines multiple cues.
+  3. Apply user's nuance via the guide's "modifiers" (warm/cool, drama, saturation, contrast).
+  4. Sanity-check: avoid washout (all params maxed) or mud (all minned). Confirm hemi sky/ground colors and dir color are consistent with the mood.
+  5. Apply ALL keys in ONE modifyBoard({patch}) call (sky, skyColor?, exposure, hemiIntensity, hemiSkyColor, hemiGroundColor, dirLightEnabled, dirLightColor, dirLightIntensity, dirLightFollowCamera=false, dirLightAzimuth, dirLightElevation, fillStyle?). ONE patch — not multiple modifyBoard calls.
+  6. In the reply, briefly state which archetype + modifier you composed.
+
+Avoid:
+  - Calling modifyBoard with only "fillStyle" for atmospheric requests — that only changes 2D background and floor tint, NOT the 3D scene mood.
+  - Mixing a sky preset with explicit skyColor (preset wins, skyColor ignored).
+  - Setting dirLightAzimuth/Elevation while leaving dirLightFollowCamera=true (no effect — set follow=false first).
+  - Using only canned presets when the user describes a custom mood — the guide enables synthesis beyond presets.
+
+==== AVAILABLE COMPONENT TYPES (enum-enforced by tool schema) ====
+${typeLine}
+
+==== AVAILABLE GROUPS / CATEGORIES ====
+${catLine}
+
+==== COMPONENT SCHEMAS (type-specific geometry + properties) ====
+${schemaSection}
+
+CRITICAL — geometry discipline:
+- Each type has its OWN geometry keys, listed under "geometry:" above.
+- Use EXACTLY those keys for that type. Do NOT default to {left, top, width, height} for every type.
+  Examples:
+    rect/image/text: left, top, width, height
+    circle/ellipse: cx, cy, rx (or radius), ry
+    line/polyline: points or path or vertices array
+    gauge-* may use left, top, width, height OR cx, cy depending on the variant.
+- Include ALL the geometry keys for the type with sensible numeric values (no undefined).
+- Include type-specific REQUIRED properties (gauge needs value/min/max, chart needs data, text needs text).
+
+CRITICAL — type discipline:
+- The "type" parameter is enum-restricted by the tool schema. Use ONLY values from the registered list.
+- If a domain concept (e.g., "AGV", "Stocker") is NOT in the list, pick the closest registered type or use a generic shape ('rect', 'ellipse', 'text') with descriptive fillStyle and a "name" field.
+
+Behavioral rules:
+- If the user is asking a question rather than commanding, REPLY in TEXT WITHOUT calling any tool.
+- If the user's request is ambiguous, REPLY in TEXT (asking for clarification) WITHOUT calling any tool.
+- For multiple components, call addComponent multiple times in parallel.
+- The current board JSON is provided as the first user message in the conversation.
+
+Reply formatting rules (chat surface):
+- Reply ONCE with ONE form only. NEVER restate the same answer in a second form (e.g. do NOT add a prose summary after a bullet list, or vice versa).
+- Keep replies concise — chat-style, not document-style. Prefer 1–4 sentences or a short bullet list.
+- Use markdown for emphasis (**bold**, *italic*) and short lists. Avoid headings (#) and long structured documents.
+- Use the same language as the user's last message.`
+  }
+}
+
+// ── Tool 정의 ──────────────────────────────────────────────────────
+
+/**
+ * 4 op 직교 set 을 4 개의 도구로 정의.
+ *
+ * 핵심: addComponent 의 `type` 파라미터가 knownTypes 의 enum 으로 강제 →
+ *       LLM 이 등록 안 된 type 을 만들 수 없음 (provider 단계에서 차단).
+ *
+ * 좌표/크기 키들은 모두 optional 로 허용 (type 별로 사용 키 다름).
+ * type-specific 추가 속성은 additionalProperties 로 허용.
+ */
+export function buildBoardEditTools(knownTypes: string[]): AITool[] {
+  const typeProp: Record<string, any> = {
+    type: 'string',
+    description: 'Registered component type (must be from the enum).'
+  }
+  if (knownTypes.length > 0) {
+    typeProp.enum = knownTypes
+  }
+
+  const componentSchema: Record<string, any> = {
+    type: 'object',
+    description: 'Component fields (geometry + style + type-specific properties).',
+    properties: {
+      type: typeProp,
+      id: { type: 'string', description: 'Unique id within the board.' },
+      // 좌상단 기반 박스 좌표
+      left: { type: 'number' },
+      top: { type: 'number' },
+      width: { type: 'number' },
+      height: { type: 'number' },
+      rotation: { type: 'number' },
+      // 중심 기반 좌표 (circle/ellipse 등)
+      cx: { type: 'number' },
+      cy: { type: 'number' },
+      radius: { type: 'number' },
+      rx: { type: 'number' },
+      ry: { type: 'number' },
+      // 경로 (line/polyline 등)
+      points: { type: 'array', items: { type: 'object' } },
+      // 일반 스타일
+      fillStyle: { type: 'string', description: 'CSS color or pattern.' },
+      strokeStyle: { type: 'string' },
+      strokeWidth: { type: 'number' },
+      strokeDashArray: { type: 'string' },
+      opacity: { type: 'number' },
+      name: { type: 'string', description: 'Optional human label.' }
+    },
+    required: ['type'],
+    additionalProperties: true
+  }
+
+  return [
+    {
+      name: 'addComponent',
+      description:
+        'Add a new component to the board. Call this multiple times in parallel for multiple adds. Use the type-specific geometry keys (left/top vs cx/cy etc.) and include any required type-specific properties.',
+      parameters: componentSchema
+    },
+    {
+      name: 'removeComponentByRefid',
+      description:
+        'Remove an existing component by its `refid` — the universal numeric handle that things-scene auto-assigns to every component (visible in board summary as the `refid` field of each component).',
+      parameters: {
+        type: 'object',
+        properties: {
+          refid: {
+            type: 'number',
+            description: 'things-scene auto-assigned numeric handle. Always present.'
+          }
+        },
+        required: ['refid']
+      }
+    },
+    {
+      name: 'modifyComponentByRefid',
+      description:
+        'Modify properties of an existing component by its `refid`. The patch is deep-merged with the existing component (style/position/size/3D material all in one).',
+      parameters: {
+        type: 'object',
+        properties: {
+          refid: {
+            type: 'number',
+            description: 'things-scene auto-assigned numeric handle.'
+          },
+          patch: {
+            type: 'object',
+            description: 'Partial fields to merge.',
+            additionalProperties: true
+          }
+        },
+        required: ['refid', 'patch']
+      }
+    },
+    {
+      name: 'modifyBoard',
+      description:
+        "Modify the BOARD's OWN root-level properties — the board itself is the topmost parent and has its own attributes (NOT child components). Common keys: `fillStyle` (background color), `width`, `height`, `name`. Use this to change the board background, size, or label. Do NOT use for child component edits (use modifyComponentByRefid for those). Do NOT pass a `components` array here — children are managed by add/remove/modify ops separately.",
+      parameters: {
+        type: 'object',
+        properties: {
+          patch: {
+            type: 'object',
+            description:
+              'Root-level fields to merge into the board. Examples: { fillStyle: "#0a1929" } for dark navy background; { width: 1920, height: 1080 } for resize; { name: "Production Floor" } for label.',
+            additionalProperties: true
+          }
+        },
+        required: ['patch']
+      }
+    },
+    {
+      name: 'replaceBoard',
+      description:
+        'Replace the entire board (use ONLY for fresh start or wholesale redesign — heavy operation that resets undo history). For just changing background or size, prefer modifyBoard. Provide width/height and the full components array.',
+      parameters: {
+        type: 'object',
+        properties: {
+          width: { type: 'number' },
+          height: { type: 'number' },
+          fillStyle: { type: 'string' },
+          components: {
+            type: 'array',
+            items: { type: 'object', additionalProperties: true }
+          }
+        },
+        required: ['components']
+      }
+    },
+    // ── Read tools (서버측 즉시 실행, 결과를 LLM 에 회신) ─────────
+    {
+      name: 'getSelection',
+      description:
+        'Get full details of components currently selected by the user in the modeller. Call this when the user asks "what is selected?" / "선택된 게 뭐냐?" / refers to "the selected component" without specifying ids. Returns array of full component objects (no truncation).',
+      parameters: { type: 'object', properties: {} }
+    },
+    {
+      name: 'getComponentByRefid',
+      description:
+        'Get full details of a single component by its `refid` (the things-scene-assigned universal numeric handle). Use this to inspect properties not visible in the board summary.',
+      parameters: {
+        type: 'object',
+        properties: {
+          refid: {
+            type: 'number',
+            description: 'things-scene auto-assigned numeric handle. Universal.'
+          }
+        },
+        required: ['refid']
+      }
+    },
+    {
+      name: 'findComponents',
+      description:
+        'Search components by criteria. All filters are optional and AND-combined. Returns matching components (full data, capped at 50). Useful for grouping by data-binding `id` (multiple components may share an id).',
+      parameters: {
+        type: 'object',
+        properties: {
+          type: { type: 'string', description: 'Match by exact type.' },
+          id: {
+            type: 'string',
+            description:
+              'Match by exact data-binding id. Note: id is NOT unique — multiple components may share an id. Returns all matches.'
+          },
+          namePattern: {
+            type: 'string',
+            description: 'Case-insensitive substring match on the `name` field.'
+          },
+          region: {
+            type: 'object',
+            description:
+              'Bounding box. Components whose left/top fall within are returned. Provide all 4 fields when used.',
+            properties: {
+              left: { type: 'number' },
+              top: { type: 'number' },
+              width: { type: 'number' },
+              height: { type: 'number' }
+            }
+          }
+        }
+      }
+    },
+    {
+      name: 'getAtmosphereGuide',
+      description:
+        "Get a comprehensive 3D atmosphere synthesis guide — parameter physics (sky / exposure / hemisphere / directional / shadow / floor / camera), sane ranges, color theory, time-of-day archetypes, and indoor/surreal mood recipes. Call this BEFORE applying atmospheric/styling changes via modifyBoard whenever the user describes a mood / scene / time-of-day in natural language (e.g. '심해 컬러', '황혼', '공장 분위기', '사이버펑크', '안개 자욱한 새벽'). The guide enables you to synthesize concrete parameter values yourself, beyond canned presets.",
+      parameters: { type: 'object', properties: {} }
+    }
+  ]
+}
+
+// ── Read tool 분류 + 실행기 ────────────────────────────────────────
+
+const READ_TOOL_NAMES = new Set([
+  'getSelection',
+  'getComponentByRefid',
+  'findComponents',
+  'getAtmosphereGuide'
+])
+const WRITE_TOOL_NAMES = new Set([
+  'addComponent',
+  'removeComponentByRefid',
+  'modifyComponentByRefid',
+  'modifyBoard',
+  'replaceBoard'
+])
+
+const FIND_COMPONENTS_CAP = 50
+
+/**
+ * Read tool 의 서버측 실행기 — currentBoard / selectedRefids 에 대해 즉시 실행해 결과 반환.
+ * LLM 의 다음 turn 에 tool_result 로 회신된다.
+ *
+ * 식별자 정책:
+ *   - 컴포넌트 targeting 은 항상 refid (universal numeric handle).
+ *   - id 는 데이터 바인딩 이름이며 unique 가 아니다 — filter 용도로만 사용 (findComponents).
+ */
+export function executeReadTool(
+  call: AIToolCall,
+  currentBoard: BoardModel | null | undefined,
+  selectedRefids: number[]
+): any {
+  const board = currentBoard
+  const components = board?.components ?? []
+
+  switch (call.name) {
+    case 'getSelection': {
+      if (selectedRefids.length === 0) {
+        return { selected: [], message: 'No component is currently selected.' }
+      }
+      const matched = components.filter(
+        c => c && typeof (c as any).refid === 'number' && selectedRefids.includes((c as any).refid)
+      )
+      return { selected: matched, count: matched.length, selectedRefids }
+    }
+    case 'getComponentByRefid': {
+      const refid = call.arguments?.refid
+      if (typeof refid !== 'number') return { error: 'refid (number) is required' }
+      const found = components.find(c => c && (c as any).refid === refid)
+      if (!found) return { error: `Component with refid ${refid} not found.` }
+      return { component: found }
+    }
+    case 'findComponents': {
+      const args = call.arguments ?? {}
+      const type = typeof args.type === 'string' ? args.type : undefined
+      const namePattern =
+        typeof args.namePattern === 'string' && args.namePattern.length > 0
+          ? args.namePattern.toLowerCase()
+          : undefined
+      const idFilter = typeof args.id === 'string' && args.id.length > 0 ? args.id : undefined
+      const region =
+        args.region &&
+        typeof args.region === 'object' &&
+        typeof args.region.left === 'number' &&
+        typeof args.region.top === 'number' &&
+        typeof args.region.width === 'number' &&
+        typeof args.region.height === 'number'
+          ? args.region
+          : undefined
+
+      const matched = components.filter((c: any) => {
+        if (!c) return false
+        if (type && c.type !== type) return false
+        if (idFilter && c.id !== idFilter) return false
+        if (namePattern) {
+          const name = typeof c.name === 'string' ? c.name.toLowerCase() : ''
+          if (!name.includes(namePattern)) return false
+        }
+        if (region) {
+          const left = typeof c.left === 'number' ? c.left : c.cx
+          const top = typeof c.top === 'number' ? c.top : c.cy
+          if (typeof left !== 'number' || typeof top !== 'number') return false
+          if (
+            left < region.left ||
+            left > region.left + region.width ||
+            top < region.top ||
+            top > region.top + region.height
+          ) {
+            return false
+          }
+        }
+        return true
+      })
+
+      return {
+        components: matched.slice(0, FIND_COMPONENTS_CAP),
+        totalMatched: matched.length,
+        truncated: matched.length > FIND_COMPONENTS_CAP
+      }
+    }
+    case 'getAtmosphereGuide':
+      return ATMOSPHERE_GUIDE
+    default:
+      return { error: `Unknown read tool: ${call.name}` }
+  }
+}
+
+/**
+ * 3D 분위기 합성 지식 primer.
+ *
+ * 의도 — preset 한 단어로 끝나지 않는 사용자 요청 ("심해", "황혼", "1980 우주정거장",
+ * "안개 새벽") 에 AI 가 구체적 파라미터 값을 직접 합성하도록 물리/색채/미학 지식
+ * 동시 제공. AI 는 이 가이드를 받은 뒤 modifyBoard 로 한 번에 적용.
+ *
+ * things-scene 의 board model 에 들어가는 root level 키만 다룸 (modifyBoard 로
+ * 적용 가능한 것). camera position 같은 ephemeral 한 것은 별도 영역.
+ */
+const ATMOSPHERE_GUIDE = {
+  overview:
+    '3D 보드 분위기는 (1) sky preset 또는 단색 (2) tone mapping exposure (3) hemisphere ambient (4) directional sun/key (5) floor 의 조합. 모두 board root model 의 속성이라 modifyBoard 단일 op 로 한 번에 적용. 자연어 요청은 archetype 레시피를 base 로 잡고 modifier 로 fine-tune.',
+
+  parameters: {
+    sky: {
+      description:
+        '3D 배경 + IBL (image-based lighting) 의 source. preset / "color" / "" 셋 중 하나.',
+      presets: {
+        studio: 'Neutral white studio with soft IBL — product-photo / showroom 분위기',
+        warehouse: 'Indoor industrial space — moderate ambient, warm-tinted',
+        factory: 'Bright factory floor — high ceiling lights, ~6000K cool',
+        office: 'Clean office interior — neutral fluorescent feel',
+        home: 'Warm domestic interior',
+        sunny: 'Outdoor clear day — Three.js Sky shader, strong directional sun',
+        cloudy: 'Outdoor overcast — soft diffuse, low contrast',
+        rainy: 'Outdoor rainy — dim, cool, very diffuse'
+      },
+      special: {
+        color: '단색 배경 (skyColor 같이 지정). IBL 없음 — hemi/dir 만 유효.',
+        '""': 'no background, no IBL. 거의 안 씀.'
+      },
+      tip: '커스텀 분위기는 sky="color" + skyColor + hemi/dir 수동 튜닝 조합. preset 위에 hemi 등을 덮어쓰면 IBL 과 ambient 가 섞여 의도 흐려질 수 있다.'
+    },
+    skyColor: {
+      description: 'sky="color" 일 때 단색 배경. hex string.',
+      examples: {
+        '#0a1929': 'deep navy — 심해, 우주, 어두운 SF',
+        '#1a2540': 'midnight blue — 밤, 차가운 미래',
+        '#2c1b3d': 'deep violet — magical, mystical',
+        '#3a4a3a': 'forest moss — 자연, 안개숲',
+        '#f5e6d0': 'cream warm — 빈티지, 70년대',
+        '#0a0a0a': 'pure dark — 드라마, 미니멀'
+      }
+    },
+    exposure: {
+      description: 'tone mapping exposure (ACESFilmic). 카메라 노출과 동일 개념.',
+      range: '0.4 ~ 2.5 (sane), default ~1.2',
+      bands: {
+        '< 0.7': 'dim — 동굴, 심해, 음울, 야간',
+        '0.7 ~ 1.0': 'subdued — 황혼, 안개, 침착',
+        '1.0 ~ 1.4': 'balanced — 일반 실내/실외',
+        '1.4 ~ 2.0': 'bright — 쇼룸, 한낮, 클린룸',
+        '> 2.0': 'over — 매우 주의 (washout)'
+      },
+      pitfall: 'exposure 만 올리고 hemi/dir 도 동시에 올리면 wash 되어 평면화. 한쪽만 손대는 게 깔끔.'
+    },
+    hemisphere: {
+      description:
+        'Hemisphere light = 위(sky)/아래(ground) 두 색을 보간한 ambient. 환경의 base 색조 결정.',
+      keys: {
+        hemiIntensity: '0 ~ 10, default 4. 높을수록 wash, 낮을수록 contrast.',
+        hemiSkyColor: 'hex. 위에서 내려오는 빛 색조 (sky 의 색).',
+        hemiGroundColor: 'hex. 아래에서 올라오는 반사 색 (floor / ground 의 bounce).'
+      },
+      tip: 'sky/ground 색 차이가 크면 environmental tint 강조 (예: sky=warm orange, ground=cool blue → 일출 분위기). 비슷하면 평탄한 ambient.'
+    },
+    directional: {
+      description: 'Directional light = 태양/key light. 하나만 존재. 그림자 source.',
+      keys: {
+        dirLightEnabled: 'boolean. 태양 on/off. 야간 / 동굴 / 우주 등은 false.',
+        dirLightColor:
+          'hex. 색온도 — 0xfff0d0 따뜻 (~3000K), 0xffffff 중성, 0xd0e0ff 차가움 (~7000K).',
+        dirLightIntensity: '0 ~ 5, default 2. dramatic 은 높이고 hemi 낮춤.',
+        dirLightAzimuth:
+          '도. 0=북, 90=동, 180=남, 270=서. dirLightFollowCamera=false 일 때만 유효.',
+        dirLightElevation: '도. 0=수평선, 90=정수리. 일출/석양 5–15, 한낮 70–90.',
+        dirLightFollowCamera: 'true 면 카메라에 묶임 (편집 편의), false 면 world-fixed (sim 자연).'
+      },
+      sunPhysics: {
+        dawn: 'elevation 10–20, color #ffb070 (warm orange), intensity 1.0–1.5',
+        goldenHour: 'elevation 15–25, color #ffaf60 (saturated warm), intensity 2.0–2.5',
+        noon: 'elevation 80–90, color #ffffff (neutral), intensity 2.8–3.5',
+        sunset: 'elevation 5–15, color #ff7050 (red-orange), intensity 1.5–2.0',
+        moonlight: 'elevation 60–80, color #a0b0d0 (cool blue), intensity 0.4–0.7'
+      }
+    },
+    shadow: {
+      keys: {
+        dirShadowEnabled: 'boolean. drama 위해 on, exposure < 0.7 이면 의미 약함.',
+        dirShadowBias: 'small negative (-0.0005 default). artifact 시 -0.001 정도 시도.'
+      }
+    },
+    floor: {
+      keys: {
+        floorMaterial3d: '바닥 재질 preset (rubber/concrete/wood/metal/... — 도메인 별 등록).',
+        fillStyle:
+          '보드 배경 색 + preset 없을 때 floor tint. 3D 에서는 ground color 와 시각적으로 묶임.'
+      }
+    },
+    camera: {
+      keys: {
+        fov: '30 ~ 75, default ~45. 낮으면 telephoto/compressed (드라마틱), 높으면 wide-angle.',
+        near: '클리핑 near plane.',
+        far: '클리핑 far plane (큰 보드면 5000+).'
+      }
+    }
+  },
+
+  archetypes: {
+    timeOfDay: {
+      dawn: {
+        description: '해 뜨기 직전 — 차분, 기대감, 청량 + 약한 따뜻함',
+        patch: {
+          sky: 'color',
+          skyColor: '#a0b8d0',
+          exposure: 0.85,
+          hemiIntensity: 3,
+          hemiSkyColor: '#ffd0a0',
+          hemiGroundColor: '#3a3040',
+          dirLightEnabled: true,
+          dirLightColor: '#ffb070',
+          dirLightIntensity: 1.2,
+          dirLightFollowCamera: false,
+          dirLightElevation: 12,
+          dirLightAzimuth: 80
+        }
+      },
+      goldenHour: {
+        description: '황금시간 — 따뜻, 풍부, 영화적',
+        patch: {
+          sky: 'sunny',
+          exposure: 1.3,
+          hemiIntensity: 4,
+          hemiSkyColor: '#ffd5a0',
+          hemiGroundColor: '#5a4030',
+          dirLightEnabled: true,
+          dirLightColor: '#ffaf60',
+          dirLightIntensity: 2.2,
+          dirLightFollowCamera: false,
+          dirLightElevation: 20,
+          dirLightAzimuth: 250
+        }
+      },
+      noon: {
+        description: '한낮 — 밝고 또렷, 사실적',
+        patch: {
+          sky: 'sunny',
+          exposure: 1.4,
+          hemiIntensity: 5,
+          hemiSkyColor: '#cfe7ff',
+          hemiGroundColor: '#5a5550',
+          dirLightEnabled: true,
+          dirLightColor: '#ffffff',
+          dirLightIntensity: 3.0,
+          dirLightFollowCamera: false,
+          dirLightElevation: 85,
+          dirLightAzimuth: 180
+        }
+      },
+      dusk: {
+        description: '황혼 — melancholy, 따뜻한 노을',
+        patch: {
+          sky: 'color',
+          skyColor: '#3a4a6a',
+          exposure: 0.95,
+          hemiIntensity: 2.5,
+          hemiSkyColor: '#a070a0',
+          hemiGroundColor: '#2a2030',
+          dirLightEnabled: true,
+          dirLightColor: '#ff7050',
+          dirLightIntensity: 1.6,
+          dirLightFollowCamera: false,
+          dirLightElevation: 8,
+          dirLightAzimuth: 270
+        }
+      },
+      night: {
+        description: '밤 — 정적, 차가움, 달빛',
+        patch: {
+          sky: 'color',
+          skyColor: '#0a0e1a',
+          exposure: 0.7,
+          hemiIntensity: 1.5,
+          hemiSkyColor: '#3a4060',
+          hemiGroundColor: '#0a0a14',
+          dirLightEnabled: true,
+          dirLightColor: '#a0b0d0',
+          dirLightIntensity: 0.5,
+          dirLightFollowCamera: false,
+          dirLightElevation: 70,
+          dirLightAzimuth: 200
+        }
+      }
+    },
+
+    indoor: {
+      studioShowroom: {
+        description: '스튜디오 / 매장 — 깨끗, 균일, 제품-photo',
+        patch: {
+          sky: 'studio',
+          exposure: 1.3,
+          hemiIntensity: 4.5,
+          hemiSkyColor: '#ffffff',
+          hemiGroundColor: '#a0a0a0',
+          dirLightEnabled: true,
+          dirLightColor: '#ffffff',
+          dirLightIntensity: 2.0,
+          dirLightFollowCamera: false,
+          dirLightElevation: 70,
+          dirLightAzimuth: 135
+        }
+      },
+      industrialFactory: {
+        description: '공장 — 기능적, 밝음, 약간 차가움',
+        patch: {
+          sky: 'factory',
+          exposure: 1.2,
+          hemiIntensity: 4.5,
+          hemiSkyColor: '#e8eef5',
+          hemiGroundColor: '#404040',
+          dirLightEnabled: true,
+          dirLightColor: '#f0f5ff',
+          dirLightIntensity: 2.5,
+          dirLightFollowCamera: false,
+          dirLightElevation: 80,
+          dirLightAzimuth: 90
+        }
+      },
+      hospitalCleanroom: {
+        description: '병원/클린룸 — 매우 밝음, 차갑고 균일',
+        patch: {
+          sky: 'studio',
+          exposure: 1.5,
+          hemiIntensity: 6,
+          hemiSkyColor: '#ffffff',
+          hemiGroundColor: '#d8e0e8',
+          dirLightEnabled: true,
+          dirLightColor: '#ffffff',
+          dirLightIntensity: 1.5,
+          dirLightFollowCamera: false,
+          dirLightElevation: 90,
+          dirLightAzimuth: 0
+        }
+      },
+      cyberpunkLab: {
+        description: '사이버펑크 실험실 — 네온, 마젠타+시안, 어두움',
+        patch: {
+          sky: 'color',
+          skyColor: '#0a0a1a',
+          exposure: 1.0,
+          hemiIntensity: 3,
+          hemiSkyColor: '#5040a0',
+          hemiGroundColor: '#003a4a',
+          dirLightEnabled: true,
+          dirLightColor: '#a040c0',
+          dirLightIntensity: 1.8,
+          dirLightFollowCamera: false,
+          dirLightElevation: 50,
+          dirLightAzimuth: 135
+        }
+      }
+    },
+
+    surreal: {
+      deepOcean: {
+        description: '심해 — 차가운 청록, 위에서 약하게 비치는 빛',
+        patch: {
+          sky: 'color',
+          skyColor: '#0a1929',
+          exposure: 0.7,
+          hemiIntensity: 2,
+          hemiSkyColor: '#1a4060',
+          hemiGroundColor: '#050a14',
+          dirLightEnabled: true,
+          dirLightColor: '#5080a0',
+          dirLightIntensity: 0.8,
+          dirLightFollowCamera: false,
+          dirLightElevation: 75,
+          dirLightAzimuth: 90,
+          fillStyle: '#0a1929'
+        }
+      },
+      mistyForest: {
+        description: '안개 자욱한 숲 — 매우 diffuse, 채도 낮음',
+        patch: {
+          sky: 'cloudy',
+          exposure: 0.95,
+          hemiIntensity: 4,
+          hemiSkyColor: '#c0d0c8',
+          hemiGroundColor: '#3a4a3a',
+          dirLightEnabled: true,
+          dirLightColor: '#e0e0d0',
+          dirLightIntensity: 0.8,
+          dirLightFollowCamera: false,
+          dirLightElevation: 35,
+          dirLightAzimuth: 100
+        }
+      },
+      deepSpace: {
+        description: '우주 / SF — 검은 배경, 차갑고 강한 key',
+        patch: {
+          sky: 'color',
+          skyColor: '#020205',
+          exposure: 0.95,
+          hemiIntensity: 0.5,
+          hemiSkyColor: '#1a2040',
+          hemiGroundColor: '#000005',
+          dirLightEnabled: true,
+          dirLightColor: '#ffffff',
+          dirLightIntensity: 3,
+          dirLightFollowCamera: false,
+          dirLightElevation: 30,
+          dirLightAzimuth: 70
+        }
+      },
+      vintage70s: {
+        description: '70년대 빈티지 — 따뜻한 베이지, 부드러운 그림자',
+        patch: {
+          sky: 'color',
+          skyColor: '#d8b890',
+          exposure: 1.15,
+          hemiIntensity: 3.5,
+          hemiSkyColor: '#f5d8a8',
+          hemiGroundColor: '#705038',
+          dirLightEnabled: true,
+          dirLightColor: '#ffd098',
+          dirLightIntensity: 1.8,
+          dirLightFollowCamera: false,
+          dirLightElevation: 45,
+          dirLightAzimuth: 135
+        }
+      }
+    }
+  },
+
+  modifiers: {
+    warmCool:
+      'warm 으로 가려면 hemiSkyColor / dirLightColor 를 +30° hue red 방향. cool 은 반대.',
+    drama:
+      'drama 강조 — hemiIntensity 낮추고 dirLightIntensity 올림. 그림자 강해짐.',
+    saturation:
+      'vivid — 색채 그대로 유지하고 hemi 약간 낮춰 dir 가 punch 하게. muted — hemi 올리고 채도 낮은 색.',
+    contrast:
+      'high — exposure 1.0 이하 + dir 강하게. low — exposure 1.3 이상 + hemi 강하게.'
+  },
+
+  workflow: [
+    '1. 사용자 요청에서 archetype 키워드 식별 (시간대 / 실내 / 초현실 카테고리).',
+    '2. archetypes 에서 가장 가까운 base 레시피 선택.',
+    '3. modifiers 로 사용자 요청 뉘앙스 fine-tune (warm/cool/drama/...).',
+    '4. sanity check — exposure × hemi × dir 어느 한쪽 극단 아닌지, hemi sky/ground 색 모순 없는지.',
+    "5. modifyBoard({ patch: { ...combined keys... } }) 한 번에 적용. 사용자에게 어떤 archetype + modifier 조합으로 갔는지 한 줄로 설명."
+  ],
+
+  pitfalls: [
+    'sky preset 위에 skyColor 같이 지정하면 preset 이 우선 (skyColor 무시).',
+    'exposure 와 hemi/dir 모두 max 면 washout. 한 쪽만 강하게.',
+    'dirLightEnabled=false 인데 dirLight 색/강도 설정해도 효과 없음.',
+    'dirLightFollowCamera=true 일 땐 azimuth/elevation 무의미 — false 로 바꿔야 적용.',
+    "fillStyle 만 바꾸면 floor tint 도 같이 바뀜 (floor preset 없을 때). 의도 없으면 floorMaterial3d 같이 점검."
+  ]
+}
+
+export function isReadTool(name: string): boolean {
+  return READ_TOOL_NAMES.has(name)
+}
+
+/**
+ * tool 결과를 UI fold-able 박스에 보여줄 만한 크기로 요약.
+ *
+ * 원본 그대로면 findComponents 50개 / getAtmosphereGuide 같은 큰 객체가 ChatMessage
+ * 영속까지 부담 — 핵심 모양만 유지하고 나머지는 marker.
+ */
+export function summarizeToolResult(value: any, depth = 0): any {
+  if (value === null || value === undefined) return value
+  if (typeof value === 'string') {
+    return value.length > 200 ? `${value.slice(0, 200)}…[+${value.length - 200} chars]` : value
+  }
+  if (typeof value === 'number' || typeof value === 'boolean') return value
+  if (Array.isArray(value)) {
+    if (depth >= 2) return `[Array(${value.length})]`
+    const out = value.slice(0, 5).map(v => summarizeToolResult(v, depth + 1))
+    if (value.length > 5) out.push(`…[+${value.length - 5} items]`)
+    return out
+  }
+  if (typeof value === 'object') {
+    if (depth >= 3) {
+      const keys = Object.keys(value).slice(0, 6).join(',')
+      return `{${keys}${Object.keys(value).length > 6 ? ',…' : ''}}`
+    }
+    const out: any = {}
+    for (const key of Object.keys(value)) {
+      out[key] = summarizeToolResult(value[key], depth + 1)
+    }
+    return out
+  }
+  return undefined
+}
+
+export function isWriteTool(name: string): boolean {
+  return WRITE_TOOL_NAMES.has(name)
+}
+
+// ── Tool call → BoardEditOp 변환 ───────────────────────────────────
+
+/**
+ * AIToolChatResult → ChatResponse.
+ *
+ * 정책 — followUp 항상 undefined: reply 와 동일 텍스트를 followUp 에 복제하면 클라이언트
+ * 에서 .md-body 와 .followup 두 박스에 같은 내용이 표시되어 사용자에게 "동일 응답이
+ * 두 번 반복" 으로 보인다. 명확화 질문이 필요한 경우 LLM 이 reply 자체에 포함시키도록
+ * 설계.
+ */
+export function toolResultToChatResponse(result: AIToolChatResult): ChatResponse {
+  const ops = result.toolCalls
+    .map(toolCallToBoardEditOp)
+    .filter((op): op is BoardEditOp => op !== null)
+
+  const reply = result.text || (ops.length > 0 ? '변경했습니다.' : '')
+
+  let patch: BoardEditPatch | undefined
+  if (ops.length > 0) {
+    patch = {
+      ops,
+      summary: result.text ?? `${ops.length} edit op(s) applied`,
+      confidence: 0.9
+    }
+  }
+
+  return { reply, patch, followUp: undefined }
+}
+
+export function toolCallToBoardEditOp(tc: AIToolCall): BoardEditOp | null {
+  const args = tc.arguments ?? {}
+  switch (tc.name) {
+    case 'addComponent': {
+      if (typeof args.type !== 'string') return null
+      return { op: 'add', component: args as BoardComponent }
+    }
+    case 'removeComponentByRefid': {
+      if (typeof args.refid !== 'number') return null
+      return { op: 'remove', refid: args.refid }
+    }
+    case 'modifyComponentByRefid': {
+      if (typeof args.refid !== 'number' || !args.patch || typeof args.patch !== 'object') return null
+      return { op: 'modify', refid: args.refid, patch: args.patch as Partial<BoardComponent> }
+    }
+    case 'modifyBoard': {
+      if (!args.patch || typeof args.patch !== 'object' || Array.isArray(args.patch)) return null
+      return { op: 'modifyBoard', patch: args.patch as Partial<BoardModel> }
+    }
+    case 'replaceBoard': {
+      if (!Array.isArray(args.components)) return null
+      return {
+        op: 'replace',
+        board: {
+          width: typeof args.width === 'number' ? args.width : undefined,
+          height: typeof args.height === 'number' ? args.height : undefined,
+          fillStyle: typeof args.fillStyle === 'string' ? args.fillStyle : undefined,
+          components: args.components as BoardComponent[]
+        } as BoardModel
+      }
+    }
+    default:
+      return null
+  }
+}
+
+// ── 스킴 포맷 ──────────────────────────────────────────────────────
+
+/**
+ * ComponentSchema[] 를 LLM 친화적 형태로 압축. 토큰 절감을 위해:
+ *  - knownTypes 에 포함된 schema 만
+ *  - properties 의 nested object 는 키 목록만
+ */
+function formatSchemas(schemas: ComponentSchema[], knownTypes: string[]): string {
+  if (!schemas || schemas.length === 0) return '(none provided)'
+  const allowed = new Set(knownTypes)
+  const filtered = schemas.filter(s => s && allowed.has(s.type))
+  if (filtered.length === 0) return '(none provided)'
+
+  const lines: string[] = []
+  for (const s of filtered) {
+    const desc = s.description ? ` — ${s.description}` : ''
+    const grp = s.group ? ` [${s.group}]` : ''
+    const geom =
+      s.geometryKeys && s.geometryKeys.length > 0
+        ? `\n    geometry: ${s.geometryKeys.join(', ')}`
+        : ''
+    const propKeys = s.properties ? formatProperties(s.properties) : ''
+    const propLine = propKeys ? `\n    properties: ${propKeys}` : ''
+    lines.push(`- ${s.type}${grp}${desc}${geom}${propLine}`)
+  }
+  return lines.join('\n')
+}
+
+function formatProperties(props: Record<string, any>): string {
+  const items: string[] = []
+  for (const [k, v] of Object.entries(props)) {
+    if (v === null || v === undefined) {
+      items.push(k)
+    } else if (typeof v === 'object' && !Array.isArray(v)) {
+      const subKeys = Object.keys(v).slice(0, 6).join(',')
+      items.push(`${k}:{${subKeys}}`)
+    } else if (Array.isArray(v)) {
+      items.push(`${k}:[]`)
+    } else if (typeof v === 'string' && v.length > 24) {
+      items.push(`${k}:string`)
+    } else {
+      items.push(`${k}=${JSON.stringify(v)}`)
+    }
+  }
+  return items.join(', ')
+}
+
+// ── 응답 정규화 ─────────────────────────────────────────────────────
+
+interface RawChatResponse {
+  reply?: string
+  patch?: { ops?: any[]; summary?: string; confidence?: number } | null
+  followUp?: string | null
+}
+
+export function normalizeChatResponse(raw: RawChatResponse): ChatResponse {
+  const reply = typeof raw.reply === 'string' ? raw.reply : ''
+  const followUp = typeof raw.followUp === 'string' && raw.followUp.length > 0 ? raw.followUp : undefined
+
+  let patch: BoardEditPatch | undefined
+  if (raw.patch && Array.isArray(raw.patch.ops) && raw.patch.ops.length > 0) {
+    const ops = raw.patch.ops.filter(isValidOp)
+    if (ops.length > 0) {
+      patch = {
+        ops,
+        summary: raw.patch.summary ?? '',
+        confidence: typeof raw.patch.confidence === 'number' ? raw.patch.confidence : 0.5
+      }
+    }
+  }
+
+  return { reply, patch, followUp }
+}
+
+export function isValidOp(op: any): boolean {
+  if (!op || typeof op.op !== 'string') return false
+  switch (op.op) {
+    case 'add':
+      return !!op.component && typeof op.component.type === 'string'
+    case 'remove':
+      return typeof op.refid === 'number'
+    case 'modify':
+      return typeof op.refid === 'number' && !!op.patch && typeof op.patch === 'object'
+    case 'modifyBoard':
+      return !!op.patch && typeof op.patch === 'object' && !Array.isArray(op.patch)
+    case 'replace':
+      return !!op.board && Array.isArray(op.board.components)
+    default:
+      return false
+  }
+}
+
+// ── 보드 요약 (LLM 토큰 절감) ──────────────────────────────────────
+
+export function summarizeBoard(board: BoardModel | null | undefined): any {
+  if (!board || typeof board !== 'object') return null
+  const components = board.components ?? []
+
+  // 루트(보드 자체) 의 모든 비-internal 속성을 그대로 노출.
+  // 단순 whitelist (width/height/fillStyle) 로 좁히면 AI 가 보드 자체의 다른 속성
+  // (name 등) 을 모르고 또한 "보드는 단순 컨테이너" 로 오해할 수 있다. 보드도
+  // 자체 속성을 가진 부모 노드임을 분명히 보이도록.
+  const root: any = {}
+  for (const key of Object.keys(board)) {
+    if (key === 'components') continue // children 은 별도 처리
+    if (key.startsWith('_')) continue
+    root[key] = summarizeValue((board as any)[key], 0)
+  }
+
+  return {
+    // 'model' 은 things-scene 보드 root 의 type — 보드가 컴포넌트 같은 대상임을 명시.
+    boardRoot: { type: 'model', ...root },
+    componentCount: components.length,
+    components: components.slice(0, MAX_BOARD_SUMMARY_COMPONENTS).map(summarizeComponent),
+    truncated: components.length > MAX_BOARD_SUMMARY_COMPONENTS
+  }
+}
+
+// 요약에서 제외할 키 — things-scene 의 내부/transient 상태 (사용자가 편집 대상으로 삼지 않음)
+const COMPONENT_OMIT_KEYS = new Set<string>([
+  'components',  // group/container 의 children — 별도 처리
+  '_state',
+  '_cache',
+  '_layout',
+  '_dirty',
+  '_internal'
+])
+
+const MAX_STRING_LEN = 200
+const MAX_ARRAY_LEN = 50
+
+/**
+ * 컴포넌트 요약 — type-specific 속성 (text, value, cx/cy/radius, points, ...) 까지
+ * 포함해 LLM 이 정확한 modify 대상을 판단할 수 있도록.
+ *
+ * 토큰 절감을 위해:
+ *  - 긴 문자열/배열은 길이 제한 (말미 truncated 마커)
+ *  - things-scene 내부 키 (_state 등) 는 제외
+ *  - nested object 는 1단계까지 그대로, 그 이상은 키 목록만
+ */
+function summarizeComponent(c: BoardComponent): any {
+  if (!c || typeof c !== 'object') return c
+  const out: any = {}
+  for (const key of Object.keys(c)) {
+    if (COMPONENT_OMIT_KEYS.has(key)) continue
+    if (key.startsWith('_')) continue
+    out[key] = summarizeValue((c as any)[key], 0)
+  }
+  return out
+}
+
+function summarizeValue(v: any, depth: number): any {
+  if (v === null || v === undefined) return v
+  const t = typeof v
+  if (t === 'string') {
+    return v.length > MAX_STRING_LEN ? `${v.slice(0, MAX_STRING_LEN)}…[+${v.length - MAX_STRING_LEN} chars]` : v
+  }
+  if (t === 'number' || t === 'boolean') return v
+  if (Array.isArray(v)) {
+    if (v.length === 0) return []
+    if (depth >= 2) return `[Array(${v.length})]`
+    const out = v.slice(0, MAX_ARRAY_LEN).map(x => summarizeValue(x, depth + 1))
+    if (v.length > MAX_ARRAY_LEN) out.push(`…[+${v.length - MAX_ARRAY_LEN} items]`)
+    return out
+  }
+  if (t === 'object') {
+    if (depth >= 2) {
+      const keys = Object.keys(v).slice(0, 8)
+      return `{${keys.join(',')}${Object.keys(v).length > 8 ? ',…' : ''}}`
+    }
+    const out: any = {}
+    for (const key of Object.keys(v)) {
+      if (key.startsWith('_')) continue
+      out[key] = summarizeValue(v[key], depth + 1)
+    }
+    return out
+  }
+  return undefined
+}