@things-factory/board-ai 10.0.2 → 10.0.4

package/dist-client/server/service/assistant.js

@@ -9,7 +9,7 @@ import { runAgenticLoop } from './agentic-loop';
 import { checkReplyGrounding } from './grounding';
 import { collectAllComponents, findComponentByRefid } from './component-tree';
 import { isStylingTool, dispatchStylingTool, buildStylingToolDefinitions } from './styling/registry.js';
-import { getToolSpecsFor, getToolKind, findToolSpec } from '@things-factory/ai-client-base';
+import { getToolSpecsFor, getToolKind, findToolSpec, getCategoryGuidance, isTransientAIError } from '@things-factory/ai-client-base';
 import { validateWriteToolCall } from './validation/tool-validation';
 const ALL_CATEGORIES = [
     'container',
@@ -79,7 +79,15 @@ export 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 = 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 을 호출할지 판단하는 데 필요.
@@ -196,6 +204,8 @@ export class DefaultBoardAIAssistant {
             followUp: undefined,
             toolUsages: toolUsages.length > 0 ? toolUsages : undefined,
             actions: accumulatedActions.length > 0 ? accumulatedActions : undefined,
+            /* 제안은 실행 전 상태다 — 대화면이 확인 버튼을 그린다. 서버는 실행하지 않는다. */
+            proposals: loopResult.proposals.length > 0 ? loopResult.proposals : undefined,
             groundingWarnings: warnings.length > 0 ? warnings : undefined
         };
     }
@@ -1789,7 +1799,12 @@ export function formatAbortNotice(abortReason) {
         case 'aborted':
             return '\n\n_(요청이 중단되어 일부만 처리됐어요.)_';
         case 'provider_error':
-            return `\n\n_(처리 중 오류가 발생했어요: ${abortReason.message})_`;
+            /* 남의 말(SDK 원문)을 사용자에게 보여주지 않는다 — "Error fetching from undefined: [503 …]" 은
+             * 사용자가 할 수 있는 일을 알려주지 않는다. 일시 장애는 이미 몇 번 다시 시도한 뒤이므로,
+             * 지금 필요한 안내는 "잠시 후 다시" 하나다. 원문은 서버 로그에 남는다. */
+            return isTransientAIError({ message: abortReason.message })
+                ? '\n\n_(AI 서비스가 일시적으로 응답하지 않았어요. 잠시 후 다시 시도해 주세요.)_'
+                : '\n\n_(처리 중 오류가 발생했어요. 같은 요청이 계속 실패하면 관리자에게 알려 주세요.)_';
         case 'max_iterations':
             return `\n\n_(작업이 너무 길어 ${abortReason.iter}회에서 중단했어요. 더 작게 나눠 요청해보세요.)_`;
         case 'repeated_validation_failure':