@things-factory/board-ai 10.1.4 → 10.1.6

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

@@ -4,8 +4,8 @@
 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 '@things-factory/ai-client-base';
-import { type ToolSpec, type ToolCategoryFilter } from '@things-factory/ai-client-base';
+import { formatAbortNotice, summarizeToolResult, type ToolGate as NeutralToolGate } from '@things-factory/ai-client-base';
+import { type ToolCategoryFilter } from '@things-factory/ai-client-base';
 export interface BoardAIAssistantOptions {
     /** 기본 scope (chat 호출 시 옵션이 없으면 사용) */
     scopes?: string[];
@@ -51,20 +51,7 @@ export declare function listColorPaletteNames(): string[];
  * 등록된 레이아웃 템플릿 이름 목록 — 위와 동일.
  */
 export declare function listLayoutTemplateNames(): string[];
-/**
- * agentic loop 의 비정상 종료 사유 → 사용자 메시지에 부기할 한국어 한 줄.
- *
- * 정상 종료 (abortReason undefined) 면 빈 문자열 — concat 해도 무해.
- * 사용자에게 "왜 중간에 멈췄는지" 단서 제공이 목적 — 침묵 종료 금지.
- */
-export declare function formatAbortNotice(abortReason: AgenticLoopResult['abortReason']): string;
-/**
- * tool 결과를 UI fold-able 박스에 보여줄 만한 크기로 요약.
- *
- * 원본 그대로면 findComponents 50개 / getAtmosphereGuide 같은 큰 객체가 ChatMessage
- * 영속까지 부담 — 핵심 모양만 유지하고 나머지는 marker.
- */
-export declare function summarizeToolResult(value: any, depth?: number): any;
+export { formatAbortNotice, summarizeToolResult };
 export declare function isWriteTool(name: string): boolean;
 export declare function isActionTool(name: string): boolean;
 /**
@@ -86,14 +73,27 @@ export interface ToolExposure {
     /** 외부 카테고리 화이트리스트(registerToolCategory 이름). 미지정 = 전부. */
     toolCategories?: ToolCategoryFilter;
 }
-export interface ToolGate {
+/**
+ * 보드의 게이트 — 공용 게이트 + 이 패키지가 가진 코어 도구 이름집합.
+ *
+ * `coreOn` 이 여기 있는 이유: 「코어 보드 편집 도구」라는 것이 board-ai 에만 있는 개념이다.
+ * 공용 게이트는 레지스트리만 안다.
+ */
+export interface ToolGate extends NeutralToolGate {
     coreOn: boolean;
-    filter: ToolCategoryFilter;
-    isRead(name: string): boolean;
-    isWrite(name: string): boolean;
-    isAction(name: string): boolean;
-    spec(name: string): ToolSpec | undefined;
 }
+/**
+ * ── 레지스트리 판정을 공용으로 옮겼다 (2026-09-10) ─────────────────────────
+ * 이 함수가 두 출처에 답하고 있었다 — **도구 레지스트리**(등록된 카테고리의 kind·spec)와
+ * **이 패키지의 코어 이름집합**. 앞엣것은 중립이다: 「이 이름이 어느 종류이고 이 대화가 볼 수
+ * 있나」는 호스트가 누구든 같은 답이다.
+ *
+ * 그래서 앞엣것은 `registryToolGate` 로 내려갔고, 여기서 뒤엣것을 **더한다**. 이 갈이가 없으면
+ * 보드 없는 제품이 같은 dispatch 규율을 받으려고 자기 게이트를 써야 하고, 그러면 접지 가드가
+ * 갈렸던 것과 같은 일이 게이트에서 난다.
+ *
+ * 더하는 것이지 덮는 것이 아니다 — 덮으면 코어 이름집합에 없는 등록 도구가 조용히 잠긴다.
+ */
 export declare function buildToolGate(exposure?: ToolExposure): ToolGate;
 /**
  * Tool call → BoardActionOp 변환 (C-1 ephemeral scene 조작).

package/dist-server/service/assistant.js

@@ -1,13 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DefaultBoardAIAssistant = void 0;
+exports.summarizeToolResult = exports.formatAbortNotice = exports.DefaultBoardAIAssistant = void 0;
 exports.buildBoardEditTools = buildBoardEditTools;
 exports.executeReadTool = executeReadTool;
 exports.isReadTool = isReadTool;
 exports.listColorPaletteNames = listColorPaletteNames;
 exports.listLayoutTemplateNames = listLayoutTemplateNames;
-exports.formatAbortNotice = formatAbortNotice;
-exports.summarizeToolResult = summarizeToolResult;
 exports.isWriteTool = isWriteTool;
 exports.isActionTool = isActionTool;
 exports.buildToolGate = buildToolGate;
@@ -30,6 +28,8 @@ const read_tools_1 = require("./styling/read-tools");
  * board 의 것(문서·선택 refid·편집 op)은 타입 매개변수로 넘긴다 — 루프는 그 모양을 모른다.
  */
 const ai_client_base_1 = require("@things-factory/ai-client-base");
+Object.defineProperty(exports, "formatAbortNotice", { enumerable: true, get: function () { return ai_client_base_1.formatAbortNotice; } });
+Object.defineProperty(exports, "summarizeToolResult", { enumerable: true, get: function () { return ai_client_base_1.summarizeToolResult; } });
 const grounding_1 = require("./grounding");
 const component_tree_1 = require("./component-tree");
 const registry_js_1 = require("./styling/registry.js");
@@ -184,7 +184,7 @@ class DefaultBoardAIAssistant {
                 /* 문서에서 부품을 꺼내는 일은 **여기서** 한다 — 루프는 board 의 모양을 모른다. */
                 validateWriteToolCall: (tc, ctx) => (0, tool_validation_1.validateWriteToolCall)(tc, (ctx.board?.components ?? [])),
                 toolCallToOp: toolCallToBoardActionOp,
-                summarizeToolResult
+                summarizeToolResult: ai_client_base_1.summarizeToolResult
             },
             context: { board: currentBoard, selectedRefids }
         });
@@ -205,7 +205,7 @@ class DefaultBoardAIAssistant {
         // abortReason 이 있으면 사용자 메시지에 한 줄 부기 — 침묵 종료 방지.
         // (정상 종료 시 abortReason undefined 로 부기 없음.)
         const baseReply = lastText || (ops.length > 0 ? '변경했습니다.' : '');
-        const reply = baseReply + formatAbortNotice(loopResult.abortReason);
+        const reply = baseReply + (0, ai_client_base_1.formatAbortNotice)(loopResult.abortReason);
         let patch;
         if (ops.length > 0) {
             patch = {
@@ -218,7 +218,8 @@ class DefaultBoardAIAssistant {
          * 근거집합의 정의와 사정거리는 ./grounding 머리말 참조(식별자 없는 창작 서술은 잡지 못한다). */
         const warnings = (0, grounding_1.checkReplyGrounding)(baseReply, {
             systemPrompt,
-            boardContext,
+            /* 근거집합의 칸 이름은 공용 패키지의 것이다 — 이 값이 보드 문맥이라는 것은 이 파일만 안다. */
+            hostContext: boardContext,
             messages: messages.map(m => (typeof m.content === 'string' ? m.content : '')),
             toolResults: loopResult.groundedTexts
         });
@@ -1811,66 +1812,6 @@ function listColorPaletteNames() {
 function listLayoutTemplateNames() {
     return Object.keys(LAYOUT_TEMPLATES.templates);
 }
-/**
- * agentic loop 의 비정상 종료 사유 → 사용자 메시지에 부기할 한국어 한 줄.
- *
- * 정상 종료 (abortReason undefined) 면 빈 문자열 — concat 해도 무해.
- * 사용자에게 "왜 중간에 멈췄는지" 단서 제공이 목적 — 침묵 종료 금지.
- */
-function formatAbortNotice(abortReason) {
-    if (!abortReason)
-        return '';
-    switch (abortReason.type) {
-        case 'aborted':
-            return '\n\n_(요청이 중단되어 일부만 처리됐어요.)_';
-        case 'provider_error':
-            /* 남의 말(SDK 원문)을 사용자에게 보여주지 않는다 — "Error fetching from undefined: [503 …]" 은
-             * 사용자가 할 수 있는 일을 알려주지 않는다. 일시 장애는 이미 몇 번 다시 시도한 뒤이므로,
-             * 지금 필요한 안내는 "잠시 후 다시" 하나다. 원문은 서버 로그에 남는다. */
-            return (0, ai_client_base_2.isTransientAIError)({ message: abortReason.message })
-                ? '\n\n_(AI 서비스가 일시적으로 응답하지 않았어요. 잠시 후 다시 시도해 주세요.)_'
-                : '\n\n_(처리 중 오류가 발생했어요. 같은 요청이 계속 실패하면 관리자에게 알려 주세요.)_';
-        case 'max_iterations':
-            return `\n\n_(작업이 너무 길어 ${abortReason.iter}회에서 중단했어요. 더 작게 나눠 요청해보세요.)_`;
-        case 'repeated_validation_failure':
-            return `\n\n_(\`${abortReason.toolName}\` 호출이 ${abortReason.consecutive}회 연속 실패해 중단했어요. 요청을 다시 표현해보세요.)_`;
-    }
-}
-/**
- * tool 결과를 UI fold-able 박스에 보여줄 만한 크기로 요약.
- *
- * 원본 그대로면 findComponents 50개 / getAtmosphereGuide 같은 큰 객체가 ChatMessage
- * 영속까지 부담 — 핵심 모양만 유지하고 나머지는 marker.
- */
-function summarizeToolResult(value, depth = 0) {
-    if (value === null || value === undefined)
-        return value;
-    if (typeof value === 'string') {
-        return value.length > 200 ? `${value.slice(0, 200)}…[+${value.length - 200} chars]` : value;
-    }
-    if (typeof value === 'number' || typeof value === 'boolean')
-        return value;
-    if (Array.isArray(value)) {
-        if (depth >= 2)
-            return `[Array(${value.length})]`;
-        const out = value.slice(0, 5).map(v => summarizeToolResult(v, depth + 1));
-        if (value.length > 5)
-            out.push(`…[+${value.length - 5} items]`);
-        return out;
-    }
-    if (typeof value === 'object') {
-        if (depth >= 3) {
-            const keys = Object.keys(value).slice(0, 6).join(',');
-            return `{${keys}${Object.keys(value).length > 6 ? ',…' : ''}}`;
-        }
-        const out = {};
-        for (const key of Object.keys(value)) {
-            out[key] = summarizeToolResult(value[key], depth + 1);
-        }
-        return out;
-    }
-    return undefined;
-}
 function isWriteTool(name) {
     if (WRITE_TOOL_NAMES.has(name))
         return true;
@@ -1881,18 +1822,26 @@ function isActionTool(name) {
         return true;
     return (0, ai_client_base_2.getToolKind)(name) === 'action';
 }
+/**
+ * ── 레지스트리 판정을 공용으로 옮겼다 (2026-09-10) ─────────────────────────
+ * 이 함수가 두 출처에 답하고 있었다 — **도구 레지스트리**(등록된 카테고리의 kind·spec)와
+ * **이 패키지의 코어 이름집합**. 앞엣것은 중립이다: 「이 이름이 어느 종류이고 이 대화가 볼 수
+ * 있나」는 호스트가 누구든 같은 답이다.
+ *
+ * 그래서 앞엣것은 `registryToolGate` 로 내려갔고, 여기서 뒤엣것을 **더한다**. 이 갈이가 없으면
+ * 보드 없는 제품이 같은 dispatch 규율을 받으려고 자기 게이트를 써야 하고, 그러면 접지 가드가
+ * 갈렸던 것과 같은 일이 게이트에서 난다.
+ *
+ * 더하는 것이지 덮는 것이 아니다 — 덮으면 코어 이름집합에 없는 등록 도구가 조용히 잠긴다.
+ */
 function buildToolGate(exposure = {}) {
     const coreOn = exposure.boardTools !== false;
-    const filter = exposure.toolCategories;
-    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_2.findToolSpec)(name, filter)
-    };
+    const gate = (0, ai_client_base_1.extendToolGate)((0, ai_client_base_1.registryToolGate)(exposure.toolCategories), {
+        isRead: name => coreOn && READ_TOOL_NAMES.has(name),
+        isWrite: name => coreOn && WRITE_TOOL_NAMES.has(name),
+        isAction: name => coreOn && ACTION_TOOL_NAMES.has(name)
+    });
+    return { ...gate, coreOn };
 }
 /**
  * tool-registry plugin point — 등록된 모든 외부 카테고리의 LLM tool 정의를 도출.