@things-factory/board-ai 10.0.18 → 10.1.0

package/dist-server/service/assistant.d.ts

@@ -4,7 +4,7 @@
 import type { AIClient, AITool, AIToolCall, AIToolChatResult } from '@things-factory/ai-client-base';
 import { type BoardModel, type ComponentCategory } from '@things-factory/board-import';
 import type { BoardAIAssistant, BoardEditOp, ChatOptions, ChatResponse, LLMMessage } from './types.js';
-import { type AgenticLoopResult } from './agentic-loop';
+import { type AgenticLoopResult } from '@things-factory/ai-client-base';
 import { type ToolSpec, type ToolCategoryFilter } from '@things-factory/ai-client-base';
 export interface BoardAIAssistantOptions {
     /** 기본 scope (chat 호출 시 옵션이 없으면 사용) */

package/dist-server/service/assistant.js

@@ -22,11 +22,18 @@ const catalog_resolver_1 = require("./catalog-resolver");
 // styling write tool builder 들은 registry (./styling/registry.ts) 에서 등록 + dispatch.
 // 직접 import 안 함 — 신규 styling tool 추가 시 registry 에만 spec 추가하면 됨.
 const read_tools_1 = require("./styling/read-tools");
-const agentic_loop_1 = require("./agentic-loop");
+/*
+ * 도구 루프는 **계약 층이 소유한다**(2026-09-05). 전에는 이 패키지 안에 있었고, twin-ai 에 같은
+ * 모양이 한 벌 더 있었다 — 그래서 안전 장치가 서로 반대로 갈렸다(여기는 중단·조기종료, 저쪽은
+ * 접지 가드). 합친 것이 `@things-factory/ai-client-base` 에 있다.
+ *
+ * board 의 것(문서·선택 refid·편집 op)은 타입 매개변수로 넘긴다 — 루프는 그 모양을 모른다.
+ */
+const ai_client_base_1 = require("@things-factory/ai-client-base");
 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");
+const ai_client_base_2 = require("@things-factory/ai-client-base");
 const tool_validation_1 = require("./validation/tool-validation");
 const ALL_CATEGORIES = [
     'container',
@@ -102,7 +109,7 @@ class DefaultBoardAIAssistant {
          * 실제로 그 공백에서 사고가 났다 — 조치 요청에 제안 도구를 부르지 않고 "제안해 두었습니다" 라고만
          * 답해, 사용자에게 없는 버튼을 누르라고 안내했다. 규율은 도구를 등록한 쪽이 소유하고 여기서는
          * 모아 붙이기만 한다(도메인 지식이 board-ai 프롬프트로 새지 않는다). */
-        const guidance = (0, ai_client_base_1.getCategoryGuidance)(options.toolCategories);
+        const guidance = (0, ai_client_base_2.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));
@@ -156,7 +163,7 @@ class DefaultBoardAIAssistant {
             // 3) 미등록 / 잘못된 분기 — 빈 응답. agentic-loop 가 LLM 에 회신 후 다음 turn.
             return undefined;
         };
-        const loopResult = await (0, agentic_loop_1.runAgenticLoop)({
+        const loopResult = await (0, ai_client_base_1.runAgenticLoop)({
             initialConversation: conversation,
             tools,
             options: {
@@ -173,13 +180,13 @@ class DefaultBoardAIAssistant {
                 isReadTool: gate.isRead,
                 isWriteTool: gate.isWrite,
                 isActionTool: gate.isAction,
-                executeReadTool: wrappedExecuteReadTool,
-                validateWriteToolCall: tool_validation_1.validateWriteToolCall,
-                toolCallToBoardActionOp,
+                executeReadTool: (tc, ctx) => wrappedExecuteReadTool(tc, ctx.board, ctx.selectedRefids),
+                /* 문서에서 부품을 꺼내는 일은 **여기서** 한다 — 루프는 board 의 모양을 모른다. */
+                validateWriteToolCall: (tc, ctx) => (0, tool_validation_1.validateWriteToolCall)(tc, (ctx.board?.components ?? [])),
+                toolCallToOp: toolCallToBoardActionOp,
                 summarizeToolResult
             },
-            currentBoard,
-            selectedRefids
+            context: { board: currentBoard, selectedRefids }
         });
         const accumulatedWriteCalls = loopResult.accumulatedWriteCalls;
         const accumulatedActions = loopResult.accumulatedActions;
@@ -1012,7 +1019,7 @@ function buildBoardEditTools(knownTypes, exposure = {}) {
     /* 코어(보드 편집) 도구를 끈 대화는 **외부 카테고리 도구만** 남긴다.
      * 배열 리터럴 안 어디에 있든 이름 기준으로 걸러 누락이 없게 한다. */
     if (!gate.coreOn) {
-        const externalNames = new Set((0, ai_client_base_1.getToolSpecsFor)(gate.filter).map(spec => spec.name));
+        const externalNames = new Set((0, ai_client_base_2.getToolSpecsFor)(gate.filter).map(spec => spec.name));
         return tools.filter(tool => externalNames.has(tool.name));
     }
     return tools;
@@ -1788,7 +1795,7 @@ function isReadTool(name) {
     // tool-registry plugin point — 'read' 와 'external' 는 LLM 측에서 동일하게 다뤄짐
     // (server 즉시 실행 + 결과 회신). external 은 board model 외부 entity 변경이
     // 가능한 점에서 의미 차이가 있지만, dispatch path 는 read 와 같다.
-    const kind = (0, ai_client_base_1.getToolKind)(name);
+    const kind = (0, ai_client_base_2.getToolKind)(name);
     return kind === 'read' || kind === 'external';
 }
 /**
@@ -1820,7 +1827,7 @@ function formatAbortNotice(abortReason) {
             /* 남의 말(SDK 원문)을 사용자에게 보여주지 않는다 — "Error fetching from undefined: [503 …]" 은
              * 사용자가 할 수 있는 일을 알려주지 않는다. 일시 장애는 이미 몇 번 다시 시도한 뒤이므로,
              * 지금 필요한 안내는 "잠시 후 다시" 하나다. 원문은 서버 로그에 남는다. */
-            return (0, ai_client_base_1.isTransientAIError)({ message: abortReason.message })
+            return (0, ai_client_base_2.isTransientAIError)({ message: abortReason.message })
                 ? '\n\n_(AI 서비스가 일시적으로 응답하지 않았어요. 잠시 후 다시 시도해 주세요.)_'
                 : '\n\n_(처리 중 오류가 발생했어요. 같은 요청이 계속 실패하면 관리자에게 알려 주세요.)_';
         case 'max_iterations':
@@ -1867,24 +1874,24 @@ function summarizeToolResult(value, depth = 0) {
 function isWriteTool(name) {
     if (WRITE_TOOL_NAMES.has(name))
         return true;
-    return (0, ai_client_base_1.getToolKind)(name) === 'write';
+    return (0, ai_client_base_2.getToolKind)(name) === 'write';
 }
 function isActionTool(name) {
     if (ACTION_TOOL_NAMES.has(name))
         return true;
-    return (0, ai_client_base_1.getToolKind)(name) === 'action';
+    return (0, ai_client_base_2.getToolKind)(name) === 'action';
 }
 function buildToolGate(exposure = {}) {
     const coreOn = exposure.boardTools !== false;
     const filter = exposure.toolCategories;
-    const kind = (name) => (0, ai_client_base_1.getToolKind)(name, filter);
+    const kind = (name) => (0, ai_client_base_2.getToolKind)(name, filter);
     return {
         coreOn,
         filter,
         isRead: name => (coreOn && READ_TOOL_NAMES.has(name)) || kind(name) === 'read' || kind(name) === 'external',
         isWrite: name => (coreOn && WRITE_TOOL_NAMES.has(name)) || kind(name) === 'write',
         isAction: name => (coreOn && ACTION_TOOL_NAMES.has(name)) || kind(name) === 'action',
-        spec: name => (0, ai_client_base_1.findToolSpec)(name, filter)
+        spec: name => (0, ai_client_base_2.findToolSpec)(name, filter)
     };
 }
 /**
@@ -1893,7 +1900,7 @@ function buildToolGate(exposure = {}) {
  * (board-import 등) 도 본 함수로 합집합. buildBoardEditTools 의 spread 부분에서 호출.
  */
 function buildExternalCategoryDefinitions(filter) {
-    return (0, ai_client_base_1.getToolSpecsFor)(filter).map(spec => ({
+    return (0, ai_client_base_2.getToolSpecsFor)(filter).map(spec => ({
         name: spec.name,
         description: spec.themeNote ? `${spec.description} ${spec.themeNote}` : spec.description,
         parameters: spec.schema