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

package/dist-server/service/assistant.js

@@ -0,0 +1,1298 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultBoardAIAssistant = void 0;
+exports.buildBoardEditTools = buildBoardEditTools;
+exports.executeReadTool = executeReadTool;
+exports.isReadTool = isReadTool;
+exports.summarizeToolResult = summarizeToolResult;
+exports.isWriteTool = isWriteTool;
+exports.toolResultToChatResponse = toolResultToChatResponse;
+exports.toolCallToBoardEditOp = toolCallToBoardEditOp;
+exports.normalizeChatResponse = normalizeChatResponse;
+exports.isValidOp = isValidOp;
+exports.summarizeBoard = summarizeBoard;
+const board_import_1 = require("@things-factory/board-import");
+const ALL_CATEGORIES = [
+    'container',
+    'vehicle',
+    'path',
+    'region',
+    'equipment',
+    'io',
+    'marker',
+    'structure',
+    'unknown'
+];
+const MAX_BOARD_SUMMARY_COMPONENTS = 80;
+class DefaultBoardAIAssistant {
+    constructor(base, options = {}) {
+        this.base = base;
+        this.options = options;
+        this.id = base.id;
+    }
+    async chat(messages, currentBoard, options = {}) {
+        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) ─────────────────────────
+    async chatViaTools(messages, currentBoard, options, knownTypes, categories, schemas) {
+        const tools = buildBoardEditTools(knownTypes);
+        const systemPrompt = this.buildSystemPromptForTools(knownTypes, categories, schemas);
+        const selectedRefids = (options.selectedRefids ?? []).filter((n) => 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 = [
+            { role: 'user', content: boardContext },
+            ...messages.map(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 = [];
+        const toolUsages = [];
+        let lastText;
+        let stopReason = 'end_turn';
+        for (let iter = 0; iter < MAX_ITERATIONS; iter++) {
+            const result = 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 = [];
+            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 = [];
+            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 !== null);
+        const reply = lastText || (ops.length > 0 ? '변경했습니다.' : '');
+        let patch;
+        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) 경로 ──────────────────────────────────
+    async chatViaJSON(messages, currentBoard, options, knownTypes, categories, schemas) {
+        const systemPrompt = this.buildSystemPrompt(knownTypes, categories, schemas);
+        const userPayload = {
+            currentBoard: currentBoard ? summarizeBoard(currentBoard) : null,
+            conversation: messages
+        };
+        const raw = await this.base.generateJSON(`User payload (JSON):\n${JSON.stringify(userPayload, null, 2)}`, {
+            systemPrompt,
+            model: options.model,
+            temperature: options.temperature,
+            maxTokens: options.maxTokens
+        });
+        return normalizeChatResponse(raw);
+    }
+    resolveTypesAndCategories(options) {
+        const explicitTypes = options.knownTypes ?? this.options.knownTypes;
+        const explicitCats = (options.categories ?? this.options.categories);
+        if (explicitTypes && explicitCats) {
+            return { knownTypes: explicitTypes, categories: explicitCats };
+        }
+        const scopes = options.scopes ?? this.options.scopes;
+        if (scopes && scopes.length > 0) {
+            const rules = (0, board_import_1.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)));
+            return {
+                knownTypes: types,
+                categories: cats.length > 0 ? cats : ALL_CATEGORIES
+            };
+        }
+        return {
+            knownTypes: explicitTypes ?? [],
+            categories: explicitCats ?? ALL_CATEGORIES
+        };
+    }
+    buildSystemPrompt(knownTypes, categories, schemas) {
+        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 ──────────────────────────────────
+    buildSystemPromptForTools(knownTypes, categories, schemas) {
+        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.`;
+    }
+}
+exports.DefaultBoardAIAssistant = DefaultBoardAIAssistant;
+// ── Tool 정의 ──────────────────────────────────────────────────────
+/**
+ * 4 op 직교 set 을 4 개의 도구로 정의.
+ *
+ * 핵심: addComponent 의 `type` 파라미터가 knownTypes 의 enum 으로 강제 →
+ *       LLM 이 등록 안 된 type 을 만들 수 없음 (provider 단계에서 차단).
+ *
+ * 좌표/크기 키들은 모두 optional 로 허용 (type 별로 사용 키 다름).
+ * type-specific 추가 속성은 additionalProperties 로 허용.
+ */
+function buildBoardEditTools(knownTypes) {
+    const typeProp = {
+        type: 'string',
+        description: 'Registered component type (must be from the enum).'
+    };
+    if (knownTypes.length > 0) {
+        typeProp.enum = knownTypes;
+    }
+    const componentSchema = {
+        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).
+ */
+function executeReadTool(call, currentBoard, selectedRefids) {
+    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.refid === 'number' && selectedRefids.includes(c.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.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) => {
+                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 같이 점검."
+    ]
+};
+function isReadTool(name) {
+    return READ_TOOL_NAMES.has(name);
+}
+/**
+ * tool 결과를 UI fold-able 박스에 보여줄 만한 크기로 요약.
+ *
+ * 원본 그대로면 findComponents 50개 / getAtmosphereGuide 같은 큰 객체가 ChatMessage
+ * 영속까지 부담 — 핵심 모양만 유지하고 나머지는 marker.
+ */
+function summarizeToolResult(value, depth = 0) {
+    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 = {};
+        for (const key of Object.keys(value)) {
+            out[key] = summarizeToolResult(value[key], depth + 1);
+        }
+        return out;
+    }
+    return undefined;
+}
+function isWriteTool(name) {
+    return WRITE_TOOL_NAMES.has(name);
+}
+// ── Tool call → BoardEditOp 변환 ───────────────────────────────────
+/**
+ * AIToolChatResult → ChatResponse.
+ *
+ * 정책 — followUp 항상 undefined: reply 와 동일 텍스트를 followUp 에 복제하면 클라이언트
+ * 에서 .md-body 와 .followup 두 박스에 같은 내용이 표시되어 사용자에게 "동일 응답이
+ * 두 번 반복" 으로 보인다. 명확화 질문이 필요한 경우 LLM 이 reply 자체에 포함시키도록
+ * 설계.
+ */
+function toolResultToChatResponse(result) {
+    const ops = result.toolCalls
+        .map(toolCallToBoardEditOp)
+        .filter((op) => op !== null);
+    const reply = result.text || (ops.length > 0 ? '변경했습니다.' : '');
+    let patch;
+    if (ops.length > 0) {
+        patch = {
+            ops,
+            summary: result.text ?? `${ops.length} edit op(s) applied`,
+            confidence: 0.9
+        };
+    }
+    return { reply, patch, followUp: undefined };
+}
+function toolCallToBoardEditOp(tc) {
+    const args = tc.arguments ?? {};
+    switch (tc.name) {
+        case 'addComponent': {
+            if (typeof args.type !== 'string')
+                return null;
+            return { op: 'add', component: args };
+        }
+        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 };
+        }
+        case 'modifyBoard': {
+            if (!args.patch || typeof args.patch !== 'object' || Array.isArray(args.patch))
+                return null;
+            return { op: 'modifyBoard', patch: args.patch };
+        }
+        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
+                }
+            };
+        }
+        default:
+            return null;
+    }
+}
+// ── 스킴 포맷 ──────────────────────────────────────────────────────
+/**
+ * ComponentSchema[] 를 LLM 친화적 형태로 압축. 토큰 절감을 위해:
+ *  - knownTypes 에 포함된 schema 만
+ *  - properties 의 nested object 는 키 목록만
+ */
+function formatSchemas(schemas, knownTypes) {
+    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 = [];
+    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) {
+    const items = [];
+    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(', ');
+}
+function normalizeChatResponse(raw) {
+    const reply = typeof raw.reply === 'string' ? raw.reply : '';
+    const followUp = typeof raw.followUp === 'string' && raw.followUp.length > 0 ? raw.followUp : undefined;
+    let patch;
+    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 };
+}
+function isValidOp(op) {
+    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 토큰 절감) ──────────────────────────────────────
+function summarizeBoard(board) {
+    if (!board || typeof board !== 'object')
+        return null;
+    const components = board.components ?? [];
+    // 루트(보드 자체) 의 모든 비-internal 속성을 그대로 노출.
+    // 단순 whitelist (width/height/fillStyle) 로 좁히면 AI 가 보드 자체의 다른 속성
+    // (name 등) 을 모르고 또한 "보드는 단순 컨테이너" 로 오해할 수 있다. 보드도
+    // 자체 속성을 가진 부모 노드임을 분명히 보이도록.
+    const root = {};
+    for (const key of Object.keys(board)) {
+        if (key === 'components')
+            continue; // children 은 별도 처리
+        if (key.startsWith('_'))
+            continue;
+        root[key] = summarizeValue(board[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([
+    '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) {
+    if (!c || typeof c !== 'object')
+        return c;
+    const out = {};
+    for (const key of Object.keys(c)) {
+        if (COMPONENT_OMIT_KEYS.has(key))
+            continue;
+        if (key.startsWith('_'))
+            continue;
+        out[key] = summarizeValue(c[key], 0);
+    }
+    return out;
+}
+function summarizeValue(v, depth) {
+    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 = {};
+        for (const key of Object.keys(v)) {
+            if (key.startsWith('_'))
+                continue;
+            out[key] = summarizeValue(v[key], depth + 1);
+        }
+        return out;
+    }
+    return undefined;
+}
+//# sourceMappingURL=assistant.js.map