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

package/dist-server/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @things-factory/board-ai — AI 주도 보드 모델링.
+ *
+ * 단일 진입점 `chat()` 으로 보드 생성·편집·스타일링을 자연어로 통합 처리.
+ * board-import 의 BoardModel 위에서 동작하며, ai-client-base 가 LLM provider 추상화 담당.
+ *
+ * @public
+ *
+ * @example
+ * ```ts
+ * import { createAIClient } from '@things-factory/ai-client-base'
+ * import { DefaultBoardAIAssistant, applyBoardEditPatch } from '@things-factory/board-ai'
+ *
+ * const base = createAIClient({ provider: 'anthropic', apiKey: '...' })
+ * const ai = new DefaultBoardAIAssistant(base, { scopes: ['fmsim'] })
+ *
+ * let board
+ * const r = await ai.chat([{ role: 'user', content: 'AGV 3대를 우측에 추가' }], board)
+ * if (r.patch) board = applyBoardEditPatch(board, r.patch)
+ * console.log(r.reply)
+ * ```
+ */
+export * from './service/index.js';

package/dist-server/index.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+/**
+ * @things-factory/board-ai — AI 주도 보드 모델링.
+ *
+ * 단일 진입점 `chat()` 으로 보드 생성·편집·스타일링을 자연어로 통합 처리.
+ * board-import 의 BoardModel 위에서 동작하며, ai-client-base 가 LLM provider 추상화 담당.
+ *
+ * @public
+ *
+ * @example
+ * ```ts
+ * import { createAIClient } from '@things-factory/ai-client-base'
+ * import { DefaultBoardAIAssistant, applyBoardEditPatch } from '@things-factory/board-ai'
+ *
+ * const base = createAIClient({ provider: 'anthropic', apiKey: '...' })
+ * const ai = new DefaultBoardAIAssistant(base, { scopes: ['fmsim'] })
+ *
+ * let board
+ * const r = await ai.chat([{ role: 'user', content: 'AGV 3대를 우측에 추가' }], board)
+ * if (r.patch) board = applyBoardEditPatch(board, r.patch)
+ * console.log(r.reply)
+ * ```
+ */
+tslib_1.__exportStar(require("./service/index.js"), exports);
+//# sourceMappingURL=index.js.map

package/dist-server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../server/index.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,6DAAkC","sourcesContent":["/**\n * @things-factory/board-ai — AI 주도 보드 모델링.\n *\n * 단일 진입점 `chat()` 으로 보드 생성·편집·스타일링을 자연어로 통합 처리.\n * board-import 의 BoardModel 위에서 동작하며, ai-client-base 가 LLM provider 추상화 담당.\n *\n * @public\n *\n * @example\n * ```ts\n * import { createAIClient } from '@things-factory/ai-client-base'\n * import { DefaultBoardAIAssistant, applyBoardEditPatch } from '@things-factory/board-ai'\n *\n * const base = createAIClient({ provider: 'anthropic', apiKey: '...' })\n * const ai = new DefaultBoardAIAssistant(base, { scopes: ['fmsim'] })\n *\n * let board\n * const r = await ai.chat([{ role: 'user', content: 'AGV 3대를 우측에 추가' }], board)\n * if (r.patch) board = applyBoardEditPatch(board, r.patch)\n * console.log(r.reply)\n * ```\n */\nexport * from './service/index.js'\n"]}

package/dist-server/service/agentic-loop.d.ts

@@ -0,0 +1,87 @@
+import type { AIMessage, AIToolCall, AIToolChatResult } from '@things-factory/ai-client-base';
+import type { BoardModel } from '@things-factory/board-import';
+import type { BoardActionOp, ToolUsage } from './types';
+/**
+ * Loop 가 호출하는 dispatch 함수들. 모두 의존성 주입.
+ *
+ * assistant.ts 가 자기 자신의 함수 (isReadTool, executeReadTool 등) 를 그대로
+ * 넘겨주는 구조. 본 모듈은 이 함수들의 *시그니처* 만 알면 됨.
+ */
+export interface ToolDispatchHelpers {
+    isReadTool: (name: string) => boolean;
+    isWriteTool: (name: string) => boolean;
+    isActionTool: (name: string) => boolean;
+    executeReadTool: (tc: AIToolCall, board: BoardModel | undefined, selectedRefids: number[]) => any;
+    validateWriteToolCall: (tc: AIToolCall, components: any[]) => {
+        valid: boolean;
+        errors?: any[];
+        suggestion?: string;
+    };
+    toolCallToBoardActionOp: (tc: AIToolCall) => BoardActionOp | null;
+    summarizeToolResult: (value: any) => any;
+}
+export interface AgenticLoopOptions {
+    systemPrompt: string;
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    /** 최대 iteration. 기본 8. */
+    maxIterations?: number;
+    /**
+     * 사용자 abort 신호. iteration 시작 직전 / chat() 호출 후 체크.
+     * 이미 abort 된 신호로 들어오면 첫 iteration 도 안 돔.
+     */
+    signal?: AbortSignal;
+    /**
+     * 같은 tool 의 validation 실패가 N회 연속이면 조기 종료. 기본 3.
+     * LLM 이 같은 잘못을 무한 반복하는 경우 방어.
+     */
+    repeatedFailureLimit?: number;
+}
+export interface AgenticLoopInput {
+    initialConversation: AIMessage[];
+    tools: any[];
+    options: AgenticLoopOptions;
+    /** LLM provider 의 chatWithTools 위임. provider-specific 구현. */
+    chat: (messages: AIMessage[], tools: any[], options: any) => Promise<AIToolChatResult>;
+    dispatch: ToolDispatchHelpers;
+    currentBoard: BoardModel | undefined;
+    selectedRefids: number[];
+}
+export interface AgenticLoopResult {
+    lastText: string | undefined;
+    accumulatedWriteCalls: AIToolCall[];
+    accumulatedActions: BoardActionOp[];
+    toolUsages: ToolUsage[];
+    /** LLM 마지막 응답의 stopReason. provider-specific 문자열. */
+    stopReason: string;
+    /**
+     * 비정상 종료 사유 — 정상 종료 시 undefined.
+     * 호출자 (assistant.ts) 가 사용자 메시지에 반영 (예: '시도 중 오류가 발생했어요').
+     */
+    abortReason?: {
+        type: 'provider_error';
+        message: string;
+        iter: number;
+    } | {
+        type: 'aborted';
+        iter: number;
+    } | {
+        type: 'max_iterations';
+        iter: number;
+    } | {
+        type: 'repeated_validation_failure';
+        toolName: string;
+        consecutive: number;
+        iter: number;
+    };
+}
+/**
+ * multi-turn agentic loop.
+ *
+ * LLM 이 read tool 을 호출 → 서버에서 즉시 실행 → 결과 회신 → LLM 추론 반복.
+ * write tool 은 누적해 client 에 patch 로 전달. 무한 루프 방지를 위해 iteration cap.
+ *
+ * 본 함수는 *순수* — input 만 보고 결정. 외부 mutable state 없음.
+ */
+export declare function runAgenticLoop(input: AgenticLoopInput): Promise<AgenticLoopResult>;

package/dist-server/service/agentic-loop.js

@@ -0,0 +1,280 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAgenticLoop = runAgenticLoop;
+const tslib_1 = require("tslib");
+/**
+ * agentic-loop — multi-turn LLM ↔ tool 루프.
+ *
+ * assistant.ts 에서 추출 — loop 자체를 *순수 함수* 로 만들어:
+ *   1. 단위 테스트 가능 (assistant.ts 의 board-import → @aws-sdk transitive 경로 회피)
+ *   2. 관측성 (error boundary / iter log / AbortSignal / repeated-failure 조기 종료)
+ *      을 한 곳에 응집
+ *   3. 향후 split (Phase 3) 의 자연 경계
+ *
+ * 입력 — `chat` 함수와 dispatch helper 들을 의존성 주입. board-ai 본체는 본 모듈에
+ * 의존하지만 본 모듈은 board-ai 의 어떤 무거운 import 도 모름.
+ */
+const debug_1 = tslib_1.__importDefault(require("debug"));
+const log = (0, debug_1.default)('things-factory:board-ai:loop');
+// ── Loop ─────────────────────────────────────────────────────────
+const DEFAULT_MAX_ITERATIONS = 8;
+/**
+ * multi-turn agentic loop.
+ *
+ * LLM 이 read tool 을 호출 → 서버에서 즉시 실행 → 결과 회신 → LLM 추론 반복.
+ * write tool 은 누적해 client 에 patch 로 전달. 무한 루프 방지를 위해 iteration cap.
+ *
+ * 본 함수는 *순수* — input 만 보고 결정. 외부 mutable state 없음.
+ */
+async function runAgenticLoop(input) {
+    const { initialConversation, tools, options, chat, dispatch, currentBoard, selectedRefids } = input;
+    const maxIterations = options.maxIterations ?? DEFAULT_MAX_ITERATIONS;
+    const failureLimit = options.repeatedFailureLimit ?? 3;
+    const signal = options.signal;
+    let conversation = initialConversation;
+    const accumulatedWriteCalls = [];
+    const accumulatedActions = [];
+    const toolUsages = [];
+    let lastText;
+    let stopReason = 'end_turn';
+    let abortReason;
+    // 같은 tool 의 validation 실패 연속 카운터 — 다른 tool 호출 시 reset
+    let lastFailedToolName;
+    let consecutiveFailures = 0;
+    let iter = 0;
+    for (; iter < maxIterations; iter++) {
+        // (1) AbortSignal — iteration 시작 시 체크
+        if (signal?.aborted) {
+            log('iter %d: aborted by signal', iter);
+            abortReason = { type: 'aborted', iter };
+            break;
+        }
+        log('iter %d: chat() 호출', iter);
+        let result;
+        try {
+            // (2) Error boundary — provider 예외 시 graceful 종료
+            result = await chat(conversation, tools, {
+                systemPrompt: options.systemPrompt,
+                model: options.model,
+                temperature: options.temperature,
+                maxTokens: options.maxTokens,
+                toolChoice: 'auto',
+                allowParallelToolCalls: true,
+                signal
+            });
+        }
+        catch (e) {
+            // AbortError — 별도 분류
+            if (e?.name === 'AbortError' || signal?.aborted) {
+                log('iter %d: provider AbortError', iter);
+                abortReason = { type: 'aborted', iter };
+            }
+            else {
+                log('iter %d: provider error: %s', iter, e?.message);
+                abortReason = {
+                    type: 'provider_error',
+                    message: e?.message ?? String(e),
+                    iter
+                };
+            }
+            break;
+        }
+        lastText = result.text || lastText;
+        stopReason = result.stopReason;
+        log('iter %d: text=%s, toolCalls=%d, stopReason=%s', iter, result.text ? `"${result.text.slice(0, 60)}..."` : '(none)', result.toolCalls.length, result.stopReason);
+        if (result.toolCalls.length === 0)
+            break;
+        // (1b) 삭제: chat() 직후 abort 는 다음 iter 시작 시 (1) 에서 감지.
+        // 현재 iter tool 실행을 중단하면 read tool 결과도 버려져 테스트/동작 불일치.
+        // tool 결과 빌드 — read 는 즉시 실행, write 는 누적, action 은 별도 채널
+        const beforeUsages = toolUsages.length;
+        const toolResultParts = await processToolCalls(result.toolCalls, currentBoard, selectedRefids, dispatch, accumulatedWriteCalls, accumulatedActions, toolUsages);
+        // (4) 같은 tool 의 validation 실패 연속 감지 — LLM 이 같은 잘못 반복 시 abort
+        const newUsages = toolUsages.slice(beforeUsages);
+        const repeatedFailureAbort = detectRepeatedValidationFailure(newUsages, lastFailedToolName, consecutiveFailures, failureLimit);
+        if (repeatedFailureAbort.shouldAbort) {
+            log('iter %d: repeated validation failure on %s (%d consecutive) — abort', iter, repeatedFailureAbort.toolName, repeatedFailureAbort.consecutive);
+            abortReason = {
+                type: 'repeated_validation_failure',
+                toolName: repeatedFailureAbort.toolName,
+                consecutive: repeatedFailureAbort.consecutive,
+                iter
+            };
+            break;
+        }
+        lastFailedToolName = repeatedFailureAbort.lastFailedToolName;
+        consecutiveFailures = repeatedFailureAbort.consecutive;
+        // 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 }
+        ];
+    }
+    // (3) max iterations 도달 시 사용자에게 표면화
+    if (iter >= maxIterations && !abortReason) {
+        log('iter %d: max iterations reached', iter);
+        abortReason = { type: 'max_iterations', iter };
+    }
+    return {
+        lastText,
+        accumulatedWriteCalls,
+        accumulatedActions,
+        toolUsages,
+        stopReason,
+        abortReason
+    };
+}
+/**
+ * 같은 tool 의 validation 실패 연속 감지 — pure helper.
+ *
+ * 같은 tool 이 반복 fail 하면 LLM 이 self-correct 못 하는 상태.
+ * 다른 tool 이 fail 하면 시퀀스 새로 시작 (전혀 다른 패턴이라).
+ * tool 이 succeed 하면 카운터 reset.
+ */
+function detectRepeatedValidationFailure(newUsages, lastFailedToolName, consecutiveFailures, limit) {
+    // 이번 iteration 에서 실패한 write tool 들 (validation 거절)
+    const failed = newUsages.filter(u => u.kind === 'write' && u.result?.error === 'Tool args failed validation');
+    if (failed.length === 0) {
+        // 실패 없음 — reset
+        return {
+            shouldAbort: false,
+            toolName: '',
+            consecutive: 0,
+            lastFailedToolName: undefined
+        };
+    }
+    // 모든 실패가 같은 tool 인지 확인
+    const firstName = failed[0].name;
+    const allSame = failed.every(u => u.name === firstName);
+    if (allSame && firstName === lastFailedToolName) {
+        const consecutive = consecutiveFailures + 1;
+        return {
+            shouldAbort: consecutive >= limit,
+            toolName: firstName,
+            consecutive,
+            lastFailedToolName: firstName
+        };
+    }
+    // 다른 tool 또는 첫 실패
+    return {
+        shouldAbort: false,
+        toolName: firstName,
+        consecutive: 1,
+        lastFailedToolName: firstName
+    };
+}
+/**
+ * 한 iteration 의 tool 결과를 분류·실행·누적. (loop 에서 분리해 읽기 쉽게.)
+ */
+async function processToolCalls(toolCalls, currentBoard, selectedRefids, dispatch, accumulatedWriteCalls, accumulatedActions, toolUsages) {
+    const toolResultParts = [];
+    for (const tc of toolCalls) {
+        if (dispatch.isReadTool(tc.name)) {
+            const value = dispatch.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: dispatch.summarizeToolResult(value),
+                kind: 'read'
+            });
+        }
+        else if (dispatch.isWriteTool(tc.name)) {
+            // 사전 검증 — args 가 schema / build 함수 검증 통과해야 누적.
+            // 실패 시 LLM 한테 detailed error 반환 → 다음 turn 에서 자기 회복 (retry).
+            const components = (currentBoard?.components ?? []);
+            const validation = dispatch.validateWriteToolCall(tc, components);
+            if (!validation.valid) {
+                const errorResult = {
+                    error: 'Tool args failed validation',
+                    issues: validation.errors,
+                    suggestion: validation.suggestion,
+                    note: 'Fix the args and call the tool again.'
+                };
+                toolResultParts.push({
+                    type: 'tool_result',
+                    toolUseId: tc.id,
+                    content: JSON.stringify(errorResult)
+                });
+                toolUsages.push({
+                    name: tc.name,
+                    arguments: tc.arguments ?? {},
+                    result: errorResult,
+                    kind: 'write'
+                });
+                // continue — 누적 안 함. LLM 이 다음 turn 에서 정정 호출.
+            }
+            else {
+                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 if (dispatch.isActionTool(tc.name)) {
+            // ephemeral scene 조작 — accumulatedActions 로 누적, ChatResponse.actions 로 client 전달
+            const action = dispatch.toolCallToBoardActionOp(tc);
+            if (action)
+                accumulatedActions.push(action);
+            const queuedResult = {
+                queued: true,
+                note: 'Will be executed on the modeller (ephemeral).'
+            };
+            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'
+            });
+        }
+    }
+    return toolResultParts;
+}
+//# sourceMappingURL=agentic-loop.js.map

package/dist-server/service/agentic-loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentic-loop.js","sourceRoot":"","sources":["../../server/service/agentic-loop.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * agentic-loop — multi-turn LLM ↔ tool 루프.\n *\n * assistant.ts 에서 추출 — loop 자체를 *순수 함수* 로 만들어:\n *   1. 단위 테스트 가능 (assistant.ts 의 board-import → @aws-sdk transitive 경로 회피)\n *   2. 관측성 (error boundary / iter log / AbortSignal / repeated-failure 조기 종료)\n *      을 한 곳에 응집\n *   3. 향후 split (Phase 3) 의 자연 경계\n *\n * 입력 — `chat` 함수와 dispatch helper 들을 의존성 주입. board-ai 본체는 본 모듈에\n * 의존하지만 본 모듈은 board-ai 의 어떤 무거운 import 도 모름.\n */\nimport debug from 'debug'\nimport type {\n  AIMessage,\n  AIToolCall,\n  AIToolChatResult\n} from '@things-factory/ai-client-base'\nimport type { BoardModel } from '@things-factory/board-import'\nimport type { BoardActionOp, ToolUsage } from './types'\n\nconst log = debug('things-factory:board-ai:loop')\n\n// ── Public types ─────────────────────────────────────────────────\n\n/**\n * Loop 가 호출하는 dispatch 함수들. 모두 의존성 주입.\n *\n * assistant.ts 가 자기 자신의 함수 (isReadTool, executeReadTool 등) 를 그대로\n * 넘겨주는 구조. 본 모듈은 이 함수들의 *시그니처* 만 알면 됨.\n */\nexport interface ToolDispatchHelpers {\n  isReadTool: (name: string) => boolean\n  isWriteTool: (name: string) => boolean\n  isActionTool: (name: string) => boolean\n  executeReadTool: (\n    tc: AIToolCall,\n    board: BoardModel | undefined,\n    selectedRefids: number[]\n  ) => any\n  validateWriteToolCall: (\n    tc: AIToolCall,\n    components: any[]\n  ) => { valid: boolean; errors?: any[]; suggestion?: string }\n  toolCallToBoardActionOp: (tc: AIToolCall) => BoardActionOp | null\n  summarizeToolResult: (value: any) => any\n}\n\nexport interface AgenticLoopOptions {\n  systemPrompt: string\n  model?: string\n  temperature?: number\n  maxTokens?: number\n  /** 최대 iteration. 기본 8. */\n  maxIterations?: number\n  /**\n   * 사용자 abort 신호. iteration 시작 직전 / chat() 호출 후 체크.\n   * 이미 abort 된 신호로 들어오면 첫 iteration 도 안 돔.\n   */\n  signal?: AbortSignal\n  /**\n   * 같은 tool 의 validation 실패가 N회 연속이면 조기 종료. 기본 3.\n   * LLM 이 같은 잘못을 무한 반복하는 경우 방어.\n   */\n  repeatedFailureLimit?: number\n}\n\nexport interface AgenticLoopInput {\n  initialConversation: AIMessage[]\n  tools: any[]\n  options: AgenticLoopOptions\n  /** LLM provider 의 chatWithTools 위임. provider-specific 구현. */\n  chat: (\n    messages: AIMessage[],\n    tools: any[],\n    options: any\n  ) => Promise<AIToolChatResult>\n  dispatch: ToolDispatchHelpers\n  currentBoard: BoardModel | undefined\n  selectedRefids: number[]\n}\n\nexport interface AgenticLoopResult {\n  lastText: string | undefined\n  accumulatedWriteCalls: AIToolCall[]\n  accumulatedActions: BoardActionOp[]\n  toolUsages: ToolUsage[]\n  /** LLM 마지막 응답의 stopReason. provider-specific 문자열. */\n  stopReason: string\n  /**\n   * 비정상 종료 사유 — 정상 종료 시 undefined.\n   * 호출자 (assistant.ts) 가 사용자 메시지에 반영 (예: '시도 중 오류가 발생했어요').\n   */\n  abortReason?:\n    | { type: 'provider_error'; message: string; iter: number }\n    | { type: 'aborted'; iter: number }\n    | { type: 'max_iterations'; iter: number }\n    | { type: 'repeated_validation_failure'; toolName: string; consecutive: number; iter: number }\n}\n\n// ── Loop ─────────────────────────────────────────────────────────\n\nconst DEFAULT_MAX_ITERATIONS = 8\n\n/**\n * multi-turn agentic loop.\n *\n * LLM 이 read tool 을 호출 → 서버에서 즉시 실행 → 결과 회신 → LLM 추론 반복.\n * write tool 은 누적해 client 에 patch 로 전달. 무한 루프 방지를 위해 iteration cap.\n *\n * 본 함수는 *순수* — input 만 보고 결정. 외부 mutable state 없음.\n */\nexport async function runAgenticLoop(\n  input: AgenticLoopInput\n): Promise<AgenticLoopResult> {\n  const {\n    initialConversation,\n    tools,\n    options,\n    chat,\n    dispatch,\n    currentBoard,\n    selectedRefids\n  } = input\n\n  const maxIterations = options.maxIterations ?? DEFAULT_MAX_ITERATIONS\n  const failureLimit = options.repeatedFailureLimit ?? 3\n  const signal = options.signal\n\n  let conversation = initialConversation\n  const accumulatedWriteCalls: AIToolCall[] = []\n  const accumulatedActions: BoardActionOp[] = []\n  const toolUsages: ToolUsage[] = []\n  let lastText: string | undefined\n  let stopReason: string = 'end_turn'\n  let abortReason: AgenticLoopResult['abortReason']\n\n  // 같은 tool 의 validation 실패 연속 카운터 — 다른 tool 호출 시 reset\n  let lastFailedToolName: string | undefined\n  let consecutiveFailures = 0\n\n  let iter = 0\n  for (; iter < maxIterations; iter++) {\n    // (1) AbortSignal — iteration 시작 시 체크\n    if (signal?.aborted) {\n      log('iter %d: aborted by signal', iter)\n      abortReason = { type: 'aborted', iter }\n      break\n    }\n\n    log('iter %d: chat() 호출', iter)\n    let result: AIToolChatResult\n    try {\n      // (2) Error boundary — provider 예외 시 graceful 종료\n      result = await chat(conversation, tools, {\n        systemPrompt: options.systemPrompt,\n        model: options.model,\n        temperature: options.temperature,\n        maxTokens: options.maxTokens,\n        toolChoice: 'auto',\n        allowParallelToolCalls: true,\n        signal\n      })\n    } catch (e: any) {\n      // AbortError — 별도 분류\n      if (e?.name === 'AbortError' || signal?.aborted) {\n        log('iter %d: provider AbortError', iter)\n        abortReason = { type: 'aborted', iter }\n      } else {\n        log('iter %d: provider error: %s', iter, e?.message)\n        abortReason = {\n          type: 'provider_error',\n          message: e?.message ?? String(e),\n          iter\n        }\n      }\n      break\n    }\n\n    lastText = result.text || lastText\n    stopReason = result.stopReason\n\n    log(\n      'iter %d: text=%s, toolCalls=%d, stopReason=%s',\n      iter,\n      result.text ? `\"${result.text.slice(0, 60)}...\"` : '(none)',\n      result.toolCalls.length,\n      result.stopReason\n    )\n\n    if (result.toolCalls.length === 0) break\n\n    // (1b) 삭제: chat() 직후 abort 는 다음 iter 시작 시 (1) 에서 감지.\n    // 현재 iter tool 실행을 중단하면 read tool 결과도 버려져 테스트/동작 불일치.\n\n    // tool 결과 빌드 — read 는 즉시 실행, write 는 누적, action 은 별도 채널\n    const beforeUsages = toolUsages.length\n    const toolResultParts = await processToolCalls(\n      result.toolCalls,\n      currentBoard,\n      selectedRefids,\n      dispatch,\n      accumulatedWriteCalls,\n      accumulatedActions,\n      toolUsages\n    )\n\n    // (4) 같은 tool 의 validation 실패 연속 감지 — LLM 이 같은 잘못 반복 시 abort\n    const newUsages = toolUsages.slice(beforeUsages)\n    const repeatedFailureAbort = detectRepeatedValidationFailure(\n      newUsages,\n      lastFailedToolName,\n      consecutiveFailures,\n      failureLimit\n    )\n    if (repeatedFailureAbort.shouldAbort) {\n      log(\n        'iter %d: repeated validation failure on %s (%d consecutive) — abort',\n        iter,\n        repeatedFailureAbort.toolName,\n        repeatedFailureAbort.consecutive\n      )\n      abortReason = {\n        type: 'repeated_validation_failure',\n        toolName: repeatedFailureAbort.toolName,\n        consecutive: repeatedFailureAbort.consecutive,\n        iter\n      }\n      break\n    }\n    lastFailedToolName = repeatedFailureAbort.lastFailedToolName\n    consecutiveFailures = repeatedFailureAbort.consecutive\n\n    // assistant 의 tool_use turn + user 의 tool_result turn 을 conversation 에 누적\n    const assistantContent: any[] = []\n    if (result.text) assistantContent.push({ type: 'text', text: result.text })\n    for (const tc of result.toolCalls) {\n      // providerMeta (Gemini thoughtSignature 등) 를 그대로 round-trip — 안 보내면 400.\n      assistantContent.push({\n        type: 'tool_use',\n        id: tc.id,\n        name: tc.name,\n        arguments: tc.arguments,\n        ...(tc.providerMeta && { providerMeta: tc.providerMeta })\n      })\n    }\n\n    conversation = [\n      ...conversation,\n      { role: 'assistant', content: assistantContent },\n      { role: 'user', content: toolResultParts }\n    ]\n  }\n\n  // (3) max iterations 도달 시 사용자에게 표면화\n  if (iter >= maxIterations && !abortReason) {\n    log('iter %d: max iterations reached', iter)\n    abortReason = { type: 'max_iterations', iter }\n  }\n\n  return {\n    lastText,\n    accumulatedWriteCalls,\n    accumulatedActions,\n    toolUsages,\n    stopReason,\n    abortReason\n  }\n}\n\n/**\n * 같은 tool 의 validation 실패 연속 감지 — pure helper.\n *\n * 같은 tool 이 반복 fail 하면 LLM 이 self-correct 못 하는 상태.\n * 다른 tool 이 fail 하면 시퀀스 새로 시작 (전혀 다른 패턴이라).\n * tool 이 succeed 하면 카운터 reset.\n */\nfunction detectRepeatedValidationFailure(\n  newUsages: ToolUsage[],\n  lastFailedToolName: string | undefined,\n  consecutiveFailures: number,\n  limit: number\n): {\n  shouldAbort: boolean\n  toolName: string\n  consecutive: number\n  lastFailedToolName: string | undefined\n} {\n  // 이번 iteration 에서 실패한 write tool 들 (validation 거절)\n  const failed = newUsages.filter(\n    u => u.kind === 'write' && (u.result as any)?.error === 'Tool args failed validation'\n  )\n\n  if (failed.length === 0) {\n    // 실패 없음 — reset\n    return {\n      shouldAbort: false,\n      toolName: '',\n      consecutive: 0,\n      lastFailedToolName: undefined\n    }\n  }\n\n  // 모든 실패가 같은 tool 인지 확인\n  const firstName = failed[0].name\n  const allSame = failed.every(u => u.name === firstName)\n\n  if (allSame && firstName === lastFailedToolName) {\n    const consecutive = consecutiveFailures + 1\n    return {\n      shouldAbort: consecutive >= limit,\n      toolName: firstName,\n      consecutive,\n      lastFailedToolName: firstName\n    }\n  }\n\n  // 다른 tool 또는 첫 실패\n  return {\n    shouldAbort: false,\n    toolName: firstName,\n    consecutive: 1,\n    lastFailedToolName: firstName\n  }\n}\n\n/**\n * 한 iteration 의 tool 결과를 분류·실행·누적. (loop 에서 분리해 읽기 쉽게.)\n */\nasync function processToolCalls(\n  toolCalls: AIToolCall[],\n  currentBoard: BoardModel | undefined,\n  selectedRefids: number[],\n  dispatch: ToolDispatchHelpers,\n  accumulatedWriteCalls: AIToolCall[],\n  accumulatedActions: BoardActionOp[],\n  toolUsages: ToolUsage[]\n): Promise<any[]> {\n  const toolResultParts: any[] = []\n\n  for (const tc of toolCalls) {\n    if (dispatch.isReadTool(tc.name)) {\n      const value = dispatch.executeReadTool(tc, currentBoard, selectedRefids)\n      toolResultParts.push({\n        type: 'tool_result',\n        toolUseId: tc.id,\n        content: JSON.stringify(value)\n      })\n      toolUsages.push({\n        name: tc.name,\n        arguments: tc.arguments ?? {},\n        result: dispatch.summarizeToolResult(value),\n        kind: 'read'\n      })\n    } else if (dispatch.isWriteTool(tc.name)) {\n      // 사전 검증 — args 가 schema / build 함수 검증 통과해야 누적.\n      // 실패 시 LLM 한테 detailed error 반환 → 다음 turn 에서 자기 회복 (retry).\n      const components = (currentBoard?.components ?? []) as any[]\n      const validation = dispatch.validateWriteToolCall(tc, components)\n      if (!validation.valid) {\n        const errorResult = {\n          error: 'Tool args failed validation',\n          issues: validation.errors,\n          suggestion: validation.suggestion,\n          note: 'Fix the args and call the tool again.'\n        }\n        toolResultParts.push({\n          type: 'tool_result',\n          toolUseId: tc.id,\n          content: JSON.stringify(errorResult)\n        })\n        toolUsages.push({\n          name: tc.name,\n          arguments: tc.arguments ?? {},\n          result: errorResult,\n          kind: 'write'\n        })\n        // continue — 누적 안 함. LLM 이 다음 turn 에서 정정 호출.\n      } else {\n        accumulatedWriteCalls.push(tc)\n        const queuedResult = { queued: true, note: 'Will be applied on the client.' }\n        toolResultParts.push({\n          type: 'tool_result',\n          toolUseId: tc.id,\n          content: JSON.stringify(queuedResult)\n        })\n        toolUsages.push({\n          name: tc.name,\n          arguments: tc.arguments ?? {},\n          result: queuedResult,\n          kind: 'write'\n        })\n      }\n    } else if (dispatch.isActionTool(tc.name)) {\n      // ephemeral scene 조작 — accumulatedActions 로 누적, ChatResponse.actions 로 client 전달\n      const action = dispatch.toolCallToBoardActionOp(tc)\n      if (action) accumulatedActions.push(action)\n      const queuedResult = {\n        queued: true,\n        note: 'Will be executed on the modeller (ephemeral).'\n      }\n      toolResultParts.push({\n        type: 'tool_result',\n        toolUseId: tc.id,\n        content: JSON.stringify(queuedResult)\n      })\n      toolUsages.push({\n        name: tc.name,\n        arguments: tc.arguments ?? {},\n        result: queuedResult,\n        kind: 'write'\n      })\n    } else {\n      const errResult = { error: `Unknown tool: ${tc.name}` }\n      toolResultParts.push({\n        type: 'tool_result',\n        toolUseId: tc.id,\n        content: JSON.stringify(errResult),\n        isError: true\n      })\n      toolUsages.push({\n        name: tc.name,\n        arguments: tc.arguments ?? {},\n        result: errResult,\n        kind: 'unknown'\n      })\n    }\n  }\n\n  return toolResultParts\n}\n"]}

package/dist-server/service/apply-patch.d.ts

@@ -0,0 +1,47 @@
+/**
+ * BoardEditPatch 를 BoardModel 에 적용하는 표준 helper.
+ *
+ * 호출자가 patch 응답을 받아 보드에 반영할 때 사용.
+ * Pure function — 입력을 mutate 하지 않음.
+ */
+import type { BoardComponent, BoardModel } from '@things-factory/board-import';
+import type { BoardEditOp, BoardEditPatch } from './types.js';
+export interface PatchApplyReport {
+    /** 패치 적용 후 보드. 모든 op 가 noop 이어도 입력 그대로 반환. */
+    board: BoardModel;
+    /** 실제로 보드를 바꾼 op 들. */
+    applied: BoardEditOp[];
+    /** id 매칭 실패 등으로 noop 이 된 op 들 — 호출자가 사용자에게 알릴 단서. */
+    missed: BoardEditOp[];
+}
+export declare function applyBoardEditPatch(board: BoardModel | undefined, patch: BoardEditPatch): BoardModel;
+/**
+ * Verbose 변형 — 각 op 의 적용 여부를 보고.
+ *
+ * `modify` 와 `remove` 는 id 가 보드에 없으면 silent no-op 이 된다 (patch 함수의
+ * 의도적 단순화). LLM 이 잘못된 id 를 만들어 보내면 사용자에게 "수정했습니다"
+ * 라고 답하지만 실제로는 아무 변화도 없는 상황이 발생 — 호스트가 missed 를
+ * 보고 사용자에게 경고할 수 있도록 별도 entry point 제공.
+ */
+export declare function applyBoardEditPatchVerbose(board: BoardModel | undefined, patch: BoardEditPatch): PatchApplyReport;
+/**
+ * 주어진 board 상태에서 op 의 inverse 를 계산.
+ *
+ * Revert 기능의 코어 — patch 적용 직전 board 와 op 만 알면 그 op 의 역연산을
+ * 만들 수 있으므로, 호스트가 in-place 적용하면서 함께 누적해 두면 나중에
+ * 역순 실행만으로 복원 가능.
+ *
+ * 반환:
+ *   - inverse op 또는 null (unsupported / 데이터 부족)
+ *   - add 의 inverse 는 add 후 발급되는 refid 가 필요해서 모델 단계에서 계산 불가 →
+ *     호스트가 scene.add 직후 refid 를 캡처해 직접 만들 것 (이 함수는 pre-applied
+ *     board 만 보고 만들 수 있는 종류만 처리: remove / modify / modifyBoard / replace)
+ */
+export declare function computeInverseOp(board: BoardModel | undefined, op: BoardEditOp): BoardEditOp | null;
+export declare function applyOp(board: BoardModel, op: BoardEditOp): BoardModel;
+/**
+ * 컴포넌트에 부분 patch 를 적용.
+ * threeD 등 nested object 는 deep merge — 호출자가 색만 바꾸려고 했을 때 geometry 까지 사라지지 않도록.
+ * patchVal === null 이면 해당 키를 제거한다 (위 시맨틱 참조).
+ */
+export declare function mergeComponent(base: BoardComponent, patch: Partial<BoardComponent>): BoardComponent;