@things-factory/board-ai 10.0.1 → 10.0.3

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

@@ -38,6 +38,17 @@ export interface AgenticLoopOptions {
      * LLM 이 같은 잘못을 무한 반복하는 경우 방어.
      */
     repeatedFailureLimit?: number;
+    /**
+     * **첫 턴에 도구 호출을 강제**한다(toolChoice: 'required'). 두 번째 턴부터는 자유(auto).
+     *
+     * 왜: 접지 가드는 답이 지어낸 **식별자**를 잡지만, 식별자 없이 지어낸 **상황 서술**은 잡지 못한다
+     * ("지게차들이 바쁘게 움직이고 있다" — 실제로 이 답이 나왔다). 그건 도구를 아예 부르지 않고 답한
+     * 경우이고, 사후 검사로는 막을 수 없다. 첫 턴에 무엇이든 조회하게 만들면 근거 없이 상태를 단언할
+     * 길이 없어진다 — 개념·사용법 질문도 문서 조회 도구로 답하므로 막히지 않는다.
+     *
+     * 대화면이 정한다(라이브 상태를 다루는 면에서만 켠다) — 여기서 질문 내용을 눈치로 분류하지 않는다.
+     */
+    requireToolOnFirstTurn?: boolean;
 }
 export interface AgenticLoopInput {
     initialConversation: AIMessage[];
@@ -54,6 +65,21 @@ export interface AgenticLoopResult {
     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;
     /**
@@ -86,3 +112,10 @@ export interface AgenticLoopResult {
  * 본 함수는 *순수* — input 만 보고 결정. 외부 mutable state 없음.
  */
 export declare function runAgenticLoop(input: AgenticLoopInput): Promise<AgenticLoopResult>;
+/**
+ * 제안의 **효과 키** — 도구·명령·대상·인자만 본다(설명 문구는 제외).
+ *
+ * 인자는 **키 순서를 정렬**해 문자열로 만든다: 같은 인자를 다른 순서로 받았을 뿐인데 다른 제안으로
+ * 보이면 카드가 둘이 되고, 사용자가 같은 명령을 두 번 실행할 수 있다.
+ */
+export declare function proposalEffectKey(p: any): string;

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runAgenticLoop = runAgenticLoop;
+exports.proposalEffectKey = proposalEffectKey;
 const tslib_1 = require("tslib");
 /**
  * agentic-loop — multi-turn LLM ↔ tool 루프.
@@ -15,6 +16,7 @@ const tslib_1 = require("tslib");
  * 의존하지만 본 모듈은 board-ai 의 어떤 무거운 import 도 모름.
  */
 const debug_1 = tslib_1.__importDefault(require("debug"));
+const ai_client_base_1 = require("@things-factory/ai-client-base");
 const log = (0, debug_1.default)('things-factory:board-ai:loop');
 // ── Loop ─────────────────────────────────────────────────────────
 const DEFAULT_MAX_ITERATIONS = 8;
@@ -35,6 +37,10 @@ async function runAgenticLoop(input) {
     const accumulatedWriteCalls = [];
     const accumulatedActions = [];
     const toolUsages = [];
+    /* 접지 근거 — tool_result 로 LLM 에 보낸 원문(압축 전). 호출부가 답의 접지를 검사한다. */
+    const groundedTexts = [];
+    /* 제안 — 도구가 실행하지 않고 제안만 한 것들. 실행 버튼은 대화면이 그린다. */
+    const proposals = [];
     let lastText;
     let stopReason = 'end_turn';
     let abortReason;
@@ -52,15 +58,22 @@ async function runAgenticLoop(input) {
         log('iter %d: chat() 호출', iter);
         let result;
         try {
-            // (2) Error boundary — provider 예외 시 graceful 종료
-            result = await chat(conversation, tools, {
+            /* (2) Error boundary — provider 예외 시 graceful 종료.
+             *
+             * 일시 장애(429·5xx·네트워크)는 **다시 시도한다**: 모델 서비스는 가끔 잠깐 죽고(실제로 Gemini
+             * 503 으로 대화가 끊겼다), 그때 한 번도 다시 걸지 않는 것은 우리 쪽 손해다. 요청·자격 오류는
+             * 즉시 그대로 올린다(조용히 더 시도하면 원인이 늦게 드러난다). 판정·대기는 ai-client-base 가 소유. */
+            result = await (0, ai_client_base_1.retryTransient)(() => chat(conversation, tools, {
                 systemPrompt: options.systemPrompt,
                 model: options.model,
                 temperature: options.temperature,
                 maxTokens: options.maxTokens,
-                toolChoice: 'auto',
+                /* 첫 턴만 강제 — 이후는 자유. 계속 강제하면 조회 결과를 받아 놓고도 답을 못 쓰고 도구를 또 부른다. */
+                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) {
@@ -88,7 +101,12 @@ async function runAgenticLoop(input) {
         // 현재 iter tool 실행을 중단하면 read tool 결과도 버려져 테스트/동작 불일치.
         // tool 결과 빌드 — read 는 즉시 실행, write 는 누적, action 은 별도 채널
         const beforeUsages = toolUsages.length;
-        const toolResultParts = await processToolCalls(result.toolCalls, currentBoard, selectedRefids, dispatch, accumulatedWriteCalls, accumulatedActions, toolUsages);
+        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);
@@ -134,10 +152,30 @@ async function runAgenticLoop(input) {
         accumulatedWriteCalls,
         accumulatedActions,
         toolUsages,
+        groundedTexts,
+        proposals,
         stopReason,
         abortReason
     };
 }
+/**
+ * 제안의 **효과 키** — 도구·명령·대상·인자만 본다(설명 문구는 제외).
+ *
+ * 인자는 **키 순서를 정렬**해 문자열로 만든다: 같은 인자를 다른 순서로 받았을 뿐인데 다른 제안으로
+ * 보이면 카드가 둘이 되고, 사용자가 같은 명령을 두 번 실행할 수 있다.
+ */
+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.
  *
@@ -180,7 +218,9 @@ function detectRepeatedValidationFailure(newUsages, lastFailedToolName, consecut
 /**
  * 한 iteration 의 tool 결과를 분류·실행·누적. (loop 에서 분리해 읽기 쉽게.)
  */
-async function processToolCalls(toolCalls, currentBoard, selectedRefids, dispatch, accumulatedWriteCalls, accumulatedActions, toolUsages) {
+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)) {
@@ -188,6 +228,27 @@ async function processToolCalls(toolCalls, currentBoard, selectedRefids, dispatc
              * 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,
@@ -197,7 +258,9 @@ async function processToolCalls(toolCalls, currentBoard, selectedRefids, dispatc
                 name: tc.name,
                 arguments: tc.arguments ?? {},
                 result: dispatch.summarizeToolResult(value),
-                kind: 'read'
+                kind: 'read',
+                iter,
+                outcome
             });
         }
         else if (dispatch.isWriteTool(tc.name)) {
@@ -221,7 +284,9 @@ async function processToolCalls(toolCalls, currentBoard, selectedRefids, dispatc
                     name: tc.name,
                     arguments: tc.arguments ?? {},
                     result: errorResult,
-                    kind: 'write'
+                    kind: 'write',
+                    iter,
+                    outcome: 'rejected'
                 });
                 // continue — 누적 안 함. LLM 이 다음 turn 에서 정정 호출.
             }
@@ -237,7 +302,9 @@ async function processToolCalls(toolCalls, currentBoard, selectedRefids, dispatc
                     name: tc.name,
                     arguments: tc.arguments ?? {},
                     result: queuedResult,
-                    kind: 'write'
+                    kind: 'write',
+                    iter,
+                    outcome: 'queued'
                 });
             }
         }
@@ -259,7 +326,9 @@ async function processToolCalls(toolCalls, currentBoard, selectedRefids, dispatc
                 name: tc.name,
                 arguments: tc.arguments ?? {},
                 result: queuedResult,
-                kind: 'write'
+                kind: 'write',
+                iter,
+                outcome: 'queued'
             });
         }
         else {
@@ -274,7 +343,9 @@ async function processToolCalls(toolCalls, currentBoard, selectedRefids, dispatc
                 name: tc.name,
                 arguments: tc.arguments ?? {},
                 result: errResult,
-                kind: 'unknown'
+                kind: 'unknown',
+                iter,
+                outcome: 'error'
             });
         }
     }

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

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

package/dist-server/service/assistant.js

@@ -23,6 +23,7 @@ const catalog_resolver_1 = require("./catalog-resolver");
 // 직접 import 안 함 — 신규 styling tool 추가 시 registry 에만 spec 추가하면 됨.
 const read_tools_1 = require("./styling/read-tools");
 const agentic_loop_1 = require("./agentic-loop");
+const grounding_1 = require("./grounding");
 const component_tree_1 = require("./component-tree");
 const registry_js_1 = require("./styling/registry.js");
 const ai_client_base_1 = require("@things-factory/ai-client-base");
@@ -95,7 +96,15 @@ class DefaultBoardAIAssistant {
          * 정의만 숨기면 모델이 이름을 추측하거나 옛 대화가 재생될 때 숨긴 도구가 실행된다. */
         const gate = buildToolGate({ boardTools: options.boardTools, toolCategories: options.toolCategories });
         const tools = buildBoardEditTools(knownTypes, { boardTools: options.boardTools, toolCategories: options.toolCategories });
-        const systemPrompt = this.buildSystemPromptForTools(knownTypes, categories, schemas);
+        /* 노출된 도구 카테고리의 **사용 규율**을 프롬프트에 함께 싣는다.
+         *
+         * 도구 목록만 보내면 모델은 "무엇이 있는지" 는 알지만 "언제 반드시 불러야 하는지" 는 모른다.
+         * 실제로 그 공백에서 사고가 났다 — 조치 요청에 제안 도구를 부르지 않고 "제안해 두었습니다" 라고만
+         * 답해, 사용자에게 없는 버튼을 누르라고 안내했다. 규율은 도구를 등록한 쪽이 소유하고 여기서는
+         * 모아 붙이기만 한다(도메인 지식이 board-ai 프롬프트로 새지 않는다). */
+        const guidance = (0, ai_client_base_1.getCategoryGuidance)(options.toolCategories);
+        const systemPrompt = this.buildSystemPromptForTools(knownTypes, categories, schemas) +
+            (guidance.length ? `\n\n==== TOOL USE RULES (from the tools exposed to this conversation) ====\n${guidance.join('\n')}` : '');
         const selectedRefids = (options.selectedRefids ?? []).filter((n) => typeof n === 'number' && Number.isFinite(n));
         // selection 정보는 항상 포함 (비어 있어도) — LLM 이 "선택된 게 뭐냐" 류 질문에
         // getSelection 을 호출할지 판단하는 데 필요.
@@ -154,7 +163,9 @@ class DefaultBoardAIAssistant {
                 systemPrompt,
                 model: options.model,
                 temperature: options.temperature,
-                maxTokens: options.maxTokens
+                maxTokens: options.maxTokens,
+                /* 라이브 상태를 다루는 대화면은 첫 턴에 조회를 강제한다 — 근거 없이 상태를 단언할 길을 막는다. */
+                requireToolOnFirstTurn: options.requireGroundingTools
             },
             chat: (msgs, tools, opts) => this.base.chatWithTools(msgs, tools, opts),
             dispatch: {
@@ -196,12 +207,23 @@ class DefaultBoardAIAssistant {
                 confidence: 0.9
             };
         }
+        /* 접지 검사 — 답이 **모델이 받은 것** 밖의 식별자를 지목했는지. 답은 고치지 않고 경고만 낸다.
+         * 근거집합의 정의와 사정거리는 ./grounding 머리말 참조(식별자 없는 창작 서술은 잡지 못한다). */
+        const warnings = (0, grounding_1.checkReplyGrounding)(baseReply, {
+            systemPrompt,
+            boardContext,
+            messages: messages.map(m => (typeof m.content === 'string' ? m.content : '')),
+            toolResults: loopResult.groundedTexts
+        });
         return {
             reply,
             patch,
             followUp: undefined,
             toolUsages: toolUsages.length > 0 ? toolUsages : undefined,
-            actions: accumulatedActions.length > 0 ? accumulatedActions : undefined
+            actions: accumulatedActions.length > 0 ? accumulatedActions : undefined,
+            /* 제안은 실행 전 상태다 — 대화면이 확인 버튼을 그린다. 서버는 실행하지 않는다. */
+            proposals: loopResult.proposals.length > 0 ? loopResult.proposals : undefined,
+            groundingWarnings: warnings.length > 0 ? warnings : undefined
         };
     }
     resolveTypesAndCategories(options) {
@@ -1795,7 +1817,12 @@ function formatAbortNotice(abortReason) {
         case 'aborted':
             return '\n\n_(요청이 중단되어 일부만 처리됐어요.)_';
         case 'provider_error':
-            return `\n\n_(처리 중 오류가 발생했어요: ${abortReason.message})_`;
+            /* 남의 말(SDK 원문)을 사용자에게 보여주지 않는다 — "Error fetching from undefined: [503 …]" 은
+             * 사용자가 할 수 있는 일을 알려주지 않는다. 일시 장애는 이미 몇 번 다시 시도한 뒤이므로,
+             * 지금 필요한 안내는 "잠시 후 다시" 하나다. 원문은 서버 로그에 남는다. */
+            return (0, ai_client_base_1.isTransientAIError)({ message: abortReason.message })
+                ? '\n\n_(AI 서비스가 일시적으로 응답하지 않았어요. 잠시 후 다시 시도해 주세요.)_'
+                : '\n\n_(처리 중 오류가 발생했어요. 같은 요청이 계속 실패하면 관리자에게 알려 주세요.)_';
         case 'max_iterations':
             return `\n\n_(작업이 너무 길어 ${abortReason.iter}회에서 중단했어요. 더 작게 나눠 요청해보세요.)_`;
         case 'repeated_validation_failure':