@things-factory/board-ai 10.0.18 → 10.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/board-ai",
-  "version": "10.0.18",
+  "version": "10.1.0",
   "main": "dist-server/index.js",
   "browser": "dist-client/client/index.js",
   "things-factory": true,
@@ -31,11 +31,11 @@
     "@operato/graphql": "^10.0.0",
     "@operato/i18n": "^10.0.0",
     "@operato/styles": "^10.0.0",
-    "@things-factory/ai-client-base": "^10.0.8",
-    "@things-factory/auth-base": "^10.0.18",
-    "@things-factory/board-import": "^10.0.18",
+    "@things-factory/ai-client-base": "^10.1.0",
+    "@things-factory/auth-base": "^10.1.0",
+    "@things-factory/board-import": "^10.1.0",
     "@things-factory/env": "^10.0.8",
-    "@things-factory/shell": "^10.0.18",
+    "@things-factory/shell": "^10.1.0",
     "dompurify": "^3.0.0",
     "graphql-tag": "^2.12.6",
     "lit": "^3.1.2",
@@ -45,5 +45,5 @@
     "copyfiles": "^2.4.1",
     "rimraf": "^5.0.0"
   },
-  "gitHead": "806c7af400517177f1323645df03558451587533"
+  "gitHead": "8407b1e9d1f47f6676af144d4a33c8ac01cb49c4"
 }

package/server/service/assistant.ts

@@ -33,7 +33,18 @@ import { resolveCatalogMentions } from './catalog-resolver'
 // styling write tool builder 들은 registry (./styling/registry.ts) 에서 등록 + dispatch.
 // 직접 import 안 함 — 신규 styling tool 추가 시 registry 에만 spec 추가하면 됨.
 import { buildComponentStyleSummary } from './styling/read-tools'
-import { runAgenticLoop, type AgenticLoopResult } from './agentic-loop'
+/*
+ * 도구 루프는 **계약 층이 소유한다**(2026-09-05). 전에는 이 패키지 안에 있었고, twin-ai 에 같은
+ * 모양이 한 벌 더 있었다 — 그래서 안전 장치가 서로 반대로 갈렸다(여기는 중단·조기종료, 저쪽은
+ * 접지 가드). 합친 것이 `@things-factory/ai-client-base` 에 있다.
+ *
+ * board 의 것(문서·선택 refid·편집 op)은 타입 매개변수로 넘긴다 — 루프는 그 모양을 모른다.
+ */
+import { runAgenticLoop, type AgenticLoopResult } from '@things-factory/ai-client-base'
+import type { BoardActionOp } from './types.js'
+
+/** 이 대화면의 도구가 알아야 하는 것 — 루프는 나르기만 한다. */
+type BoardToolContext = { board: BoardModel | undefined; selectedRefids: number[] }
 import { checkReplyGrounding } from './grounding'
 import { collectAllComponents, findComponentByRefid } from './component-tree'
 import {
@@ -227,7 +238,7 @@ export class DefaultBoardAIAssistant implements BoardAIAssistant {
       return undefined
     }
 
-    const loopResult = await runAgenticLoop({
+    const loopResult = await runAgenticLoop<BoardToolContext, BoardActionOp>({
       initialConversation: conversation,
       tools,
       options: {
@@ -244,13 +255,13 @@ export class DefaultBoardAIAssistant implements BoardAIAssistant {
         isReadTool: gate.isRead,
         isWriteTool: gate.isWrite,
         isActionTool: gate.isAction,
-        executeReadTool: wrappedExecuteReadTool,
-        validateWriteToolCall,
-        toolCallToBoardActionOp,
+        executeReadTool: (tc, ctx) => wrappedExecuteReadTool(tc, ctx.board, ctx.selectedRefids),
+        /* 문서에서 부품을 꺼내는 일은 **여기서** 한다 — 루프는 board 의 모양을 모른다. */
+        validateWriteToolCall: (tc, ctx) => validateWriteToolCall(tc, (ctx.board?.components ?? []) as any[]),
+        toolCallToOp: toolCallToBoardActionOp,
         summarizeToolResult
       },
-      currentBoard,
-      selectedRefids
+      context: { board: currentBoard, selectedRefids }
     })
     const accumulatedWriteCalls = loopResult.accumulatedWriteCalls
     const accumulatedActions = loopResult.accumulatedActions

package/server/service/types.ts

@@ -112,37 +112,14 @@ export interface ComponentSchema {
 }
 
 /**
- * AI 가 응답을 만드는 동안 호출한 도구의 시간순 trace.
+ * 도구 사용 기록 — **`@things-factory/ai-client-base` 가 소유한다.**
  *
- * UX 목적 — 사용자가 "왜 이렇게 답했지" 의문 가질 때 fold-able 박스에서 확인.
- * 디버그용 + 신뢰도 향상.
+ * 도메인 중립이라 루프와 함께 그리로 옮겼다(2026-09-05). 여기서 다시 내보내는 것은 부르는 쪽의
+ * import 를 그대로 두기 위해서다 — 뜻의 정본은 저쪽 한 곳이다.
  */
-export interface ToolUsage {
-  /** 도구 이름 (예: 'getSelection', 'modifyBoard', 'addComponent') */
-  name: string
-  /** 호출 인자 JSON */
-  arguments: any
-  /** 도구 결과 — read tool 은 실제 값 (truncated 가능), write tool 은 queued 마커 */
-  result: any
-  /** read tool / write tool 분류 */
-  kind: 'read' | 'write' | 'unknown'
-  /**
-   * 몇 번째 LLM 턴에서 불렀는가(0부터). 판단 과정을 단계로 읽을 수 있게 한다 —
-   * "조회 → 거절 → 정정 → 제안" 이 한 턴 안의 일인지 여러 턴에 걸친 일인지가 진단의 절반이다.
-   */
-  iter?: number
-  /**
-   * 이 호출이 **어떻게 끝났는가** — 화면이 배지로 보여줄 판정.
-   *   ok        조회·실행이 정상 완료
-   *   rejected  도구가 거절(인자 누락·대상 없음 등). 무엇이 빠졌는지는 result 에 있다.
-   *   queued    보드 편집처럼 클라이언트에서 적용될 예정
-   *   proposed  조치 제안이 만들어졌다(실행 아님 — 사용자가 버튼을 누른다)
-   *   folded    같은 효과의 제안이 이미 있어 접혔다. **조용히 버리지 않는다** — 접힌 사실이 보여야
-   *             "왜 카드가 하나뿐인가" 를 추적할 수 있다.
-   *   error     알 수 없는 도구·검증 실패
-   */
-  outcome?: 'ok' | 'rejected' | 'queued' | 'proposed' | 'folded' | 'error'
-}
+import type { ToolUsage } from '@things-factory/ai-client-base'
+export type { ToolUsage }
+
 
 export interface ChatResponse {
   /** 사용자에게 보여줄 텍스트 응답 */

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

@@ -1,121 +0,0 @@
-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;
-    /** read/external 도구 실행. **Promise 를 반환할 수 있다** — 호출부는 반드시 await 한다. */
-    executeReadTool: (tc: AIToolCall, board: BoardModel | undefined, selectedRefids: number[]) => any | Promise<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;
-    /**
-     * **첫 턴에 도구 호출을 강제**한다(toolChoice: 'required'). 두 번째 턴부터는 자유(auto).
-     *
-     * 왜: 접지 가드는 답이 지어낸 **식별자**를 잡지만, 식별자 없이 지어낸 **상황 서술**은 잡지 못한다
-     * ("지게차들이 바쁘게 움직이고 있다" — 실제로 이 답이 나왔다). 그건 도구를 아예 부르지 않고 답한
-     * 경우이고, 사후 검사로는 막을 수 없다. 첫 턴에 무엇이든 조회하게 만들면 근거 없이 상태를 단언할
-     * 길이 없어진다 — 개념·사용법 질문도 문서 조회 도구로 답하므로 막히지 않는다.
-     *
-     * 대화면이 정한다(라이브 상태를 다루는 면에서만 켠다) — 여기서 질문 내용을 눈치로 분류하지 않는다.
-     */
-    requireToolOnFirstTurn?: boolean;
-}
-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 에게 실제로 회신된 도구 결과 문자열(시간순) — **접지 판정의 근거집합**.
-     *
-     * `toolUsages[].result` 를 쓰면 안 된다: 그건 UI 표시용으로 압축된(잘린) 값이라 근거로 삼으면
-     * 잘려 나간 식별자를 "근거 없음" 으로 오판한다. 여기 담기는 것은 tool_result 로 보낸 원문 그대로다.
-     */
-    groundedTexts: string[];
-    /**
-     * **제안** — 도구가 "실행하지 않고 제안만 했다" 고 알린 결과들(시간순).
-     *
-     * 규약: read/external 도구의 결과에 `proposed === true` 가 있으면 그것은 조치 제안이다. 그 도구가
-     * 어느 도메인인지 이 루프는 모른다 — 결과를 그대로 실어 올리고, 해석·실행 확인은 대화면이 한다.
-     * 되돌릴 수 없는 조치를 AI 가 직접 실행하지 않게 하는 경계가 이 채널이다(사람이 버튼을 누른다).
-     */
-    proposals: any[];
-    /** 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>;
-/**
- * 제안의 **효과 키** — 도구·명령·대상·인자만 본다(설명 문구는 제외).
- *
- * 인자는 **키 순서를 정렬**해 문자열로 만든다: 같은 인자를 다른 순서로 받았을 뿐인데 다른 제안으로
- * 보이면 카드가 둘이 되고, 사용자가 같은 명령을 두 번 실행할 수 있다.
- */
-export declare function proposalEffectKey(p: any): string;

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

@@ -1,349 +0,0 @@
-/**
- * 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 도 모름.
- */
-import debug from 'debug';
-import { retryTransient } from '@things-factory/ai-client-base';
-const log = debug('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 없음.
- */
-export 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 = [];
-    /* 접지 근거 — tool_result 로 LLM 에 보낸 원문(압축 전). 호출부가 답의 접지를 검사한다. */
-    const groundedTexts = [];
-    /* 제안 — 도구가 실행하지 않고 제안만 한 것들. 실행 버튼은 대화면이 그린다. */
-    const proposals = [];
-    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 종료.
-             *
-             * 일시 장애(429·5xx·네트워크)는 **다시 시도한다**: 모델 서비스는 가끔 잠깐 죽고(실제로 Gemini
-             * 503 으로 대화가 끊겼다), 그때 한 번도 다시 걸지 않는 것은 우리 쪽 손해다. 요청·자격 오류는
-             * 즉시 그대로 올린다(조용히 더 시도하면 원인이 늦게 드러난다). 판정·대기는 ai-client-base 가 소유. */
-            result = await retryTransient(() => chat(conversation, tools, {
-                systemPrompt: options.systemPrompt,
-                model: options.model,
-                temperature: options.temperature,
-                maxTokens: options.maxTokens,
-                /* 첫 턴만 강제 — 이후는 자유. 계속 강제하면 조회 결과를 받아 놓고도 답을 못 쓰고 도구를 또 부른다. */
-                toolChoice: iter === 0 && options.requireToolOnFirstTurn ? 'required' : 'auto',
-                allowParallelToolCalls: true,
-                signal
-            }), {
-                onRetry: ({ attempt, delayMs, error }) => log('iter %d: 일시 장애 재시도 %d회 (%dms 후): %s', iter, attempt, delayMs, error?.message)
-            });
-        }
-        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, proposals, iter);
-        /* 접지 근거 누적 — 모델이 tool_result 로 받은 원문 그대로. 압축 전 값이어야 한다(위 필드 주석). */
-        for (const part of toolResultParts) {
-            if (typeof part?.content === 'string')
-                groundedTexts.push(part.content);
-        }
-        // (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,
-        groundedTexts,
-        proposals,
-        stopReason,
-        abortReason
-    };
-}
-/**
- * 제안의 **효과 키** — 도구·명령·대상·인자만 본다(설명 문구는 제외).
- *
- * 인자는 **키 순서를 정렬**해 문자열로 만든다: 같은 인자를 다른 순서로 받았을 뿐인데 다른 제안으로
- * 보이면 카드가 둘이 되고, 사용자가 같은 명령을 두 번 실행할 수 있다.
- */
-export function proposalEffectKey(p) {
-    return [p?.tool ?? '', p?.command ?? '', p?.instanceId ?? '', stableStringify(p?.args)].join('|');
-}
-/** 키 정렬 직렬화 — 순서에 흔들리지 않는 비교를 위해. */
-function stableStringify(value) {
-    if (value === null || typeof value !== 'object')
-        return JSON.stringify(value ?? null);
-    if (Array.isArray(value))
-        return `[${value.map(stableStringify).join(',')}]`;
-    const keys = Object.keys(value).sort();
-    return `{${keys.map(k => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(',')}}`;
-}
-/**
- * 같은 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, proposals, 
-/** 몇 번째 LLM 턴인가 — 기록에 남겨 화면이 단계로 읽을 수 있게 한다. */
-iter) {
-    const toolResultParts = [];
-    for (const tc of toolCalls) {
-        if (dispatch.isReadTool(tc.name)) {
-            /* await 필수 — registry 에 등록된 read/external builder 는 async 일 수 있다(DB·외부 호출).
-             * await 없이 JSON.stringify 하면 Promise 가 '{}' 로 직렬화되어 LLM 이 **빈 결과**를 받는다
-             * (board-import 의 getImportSession/importBoardAsync, operato-twin 의 getTwinStructure 등). */
-            const value = await dispatch.executeReadTool(tc, currentBoard, selectedRefids);
-            /* 제안 규약 — 결과가 `proposed: true` 면 조치 제안이다(도메인은 모른 채 그대로 실어 올린다).
-             * 이 채널이 없으면 대화면은 도구 추적(trace)을 뒤져야 하고, 실행 버튼을 만들 근거가 없다. */
-            /* 판정(outcome) — 화면이 단계별 배지로 보여줄 값. 조용한 무동작을 남기지 않는다. */
-            let outcome = 'ok';
-            if (value && typeof value === 'object' && value.proposed === true) {
-                /* **같은 조치는 한 번만** — 모델이 같은 것을 두 번 제안하는 일이 실제로 있었다(하나는 인자가
-                 * 비어 있었다). 카드가 둘이면 사용자가 같은 명령을 두 번 실행할 수 있고, 그건 되돌릴 수 없다.
-                 * 판정은 **효과**(도구·명령·대상·인자)로 한다 — 설명 문구(label·reason)가 달라도 같은 조치다. */
-                const candidate = { tool: tc.name, ...value };
-                const key = proposalEffectKey(candidate);
-                if (proposals.some(p => proposalEffectKey(p) === key)) {
-                    outcome = 'folded'; // 접힌 사실을 남긴다 — "왜 카드가 하나뿐인가" 가 추적 가능해야 한다
-                }
-                else {
-                    proposals.push(candidate);
-                    outcome = 'proposed';
-                }
-            }
-            else if (value && typeof value === 'object' && (value.rejected === true || value.error)) {
-                outcome = 'rejected';
-            }
-            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',
-                iter,
-                outcome
-            });
-        }
-        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',
-                    iter,
-                    outcome: 'rejected'
-                });
-                // 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',
-                    iter,
-                    outcome: 'queued'
-                });
-            }
-        }
-        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',
-                iter,
-                outcome: 'queued'
-            });
-        }
-        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',
-                iter,
-                outcome: 'error'
-            });
-        }
-    }
-    return toolResultParts;
-}
-//# sourceMappingURL=agentic-loop.js.map