@things-factory/board-ai 10.0.1 → 10.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/board-ai",
-  "version": "10.0.1",
+  "version": "10.0.3",
   "main": "dist-server/index.js",
   "browser": "dist-client/client/index.js",
   "things-factory": true,
@@ -30,11 +30,11 @@
     "@operato/graphql": "^10.0.0",
     "@operato/i18n": "^10.0.0",
     "@operato/styles": "^10.0.0",
-    "@things-factory/ai-client-base": "^10.0.0",
-    "@things-factory/auth-base": "^10.0.0",
-    "@things-factory/board-import": "^10.0.1",
+    "@things-factory/ai-client-base": "^10.0.3",
+    "@things-factory/auth-base": "^10.0.3",
+    "@things-factory/board-import": "^10.0.3",
     "@things-factory/env": "^10.0.0",
-    "@things-factory/shell": "^10.0.0",
+    "@things-factory/shell": "^10.0.3",
     "dompurify": "^3.0.0",
     "graphql-tag": "^2.12.6",
     "lit": "^3.1.2",
@@ -44,5 +44,5 @@
     "copyfiles": "^2.4.1",
     "rimraf": "^5.0.0"
   },
-  "gitHead": "6dd5b25ed1fe863415793bd156c3411ffe1ce47d"
+  "gitHead": "c7d253b722b6917e8911f6ef6e78e5fc2b295e82"
 }

package/server/service/agentic-loop.test.ts

@@ -703,3 +703,157 @@ describe('runAgenticLoop — currentBoard / selectedRefids 전달', () => {
     expect(receivedComponents).toEqual([{ refid: 7 }])
   })
 })
+
+describe('runAgenticLoop — 접지 근거 수집', () => {
+  test('도구 결과 원문을 groundedTexts 에 담는다 — 압축본(toolUsages.result)이 아니라 원문이어야 한다', async () => {
+    let callCount = 0
+    const input = mkInput(
+      {
+        chat: async () => {
+          callCount++
+          return callCount === 1 ? okResult(undefined, [TC('getTwinStructure', {})]) : okResult('done')
+        }
+      },
+      {
+        isReadTool: () => true,
+        executeReadTool: () => ({ nodes: [{ id: 'dock-1' }, { id: 'dock-2' }] }),
+        /* 표시용 압축이 식별자를 잘라내도 근거는 온전해야 한다. */
+        summarizeToolResult: () => ({ nodes: '…(생략)' })
+      }
+    )
+    const r = await runAgenticLoop(input)
+    expect(r.groundedTexts).toEqual([JSON.stringify({ nodes: [{ id: 'dock-1' }, { id: 'dock-2' }] })])
+    expect(r.toolUsages[0].result).toEqual({ nodes: '…(생략)' })
+  })
+
+  test('도구를 부르지 않으면 근거가 비어 있다 — 그 답은 접지될 수 없다', async () => {
+    const r = await runAgenticLoop(mkInput({ chat: async () => okResult('바쁘게 움직이고 있습니다') }))
+    expect(r.groundedTexts).toEqual([])
+  })
+})
+
+describe('runAgenticLoop — 첫 턴 도구 강제(근거 없는 단언 차단)', () => {
+  /** 각 iteration 의 toolChoice 를 기록하는 mock. */
+  const recordChoices = (turns: number) => {
+    const choices: any[] = []
+    let i = 0
+    return {
+      choices,
+      chat: async (_m: any, _t: any, opts: any) => {
+        choices.push(opts.toolChoice)
+        i++
+        return i < turns ? okResult(undefined, [TC('getSelection', {})]) : okResult('done')
+      }
+    }
+  }
+
+  test('켜면 첫 턴만 required, 두 번째부터 auto — 조회 결과를 받고도 또 부르지 않게', async () => {
+    const rec = recordChoices(2)
+    await runAgenticLoop(
+      mkInput(
+        { chat: rec.chat, options: { systemPrompt: 'x', requireToolOnFirstTurn: true } },
+        { isReadTool: () => true, executeReadTool: () => ({ ok: 1 }) }
+      )
+    )
+    expect(rec.choices).toEqual(['required', 'auto'])
+  })
+
+  test('끄면 기존 그대로 auto — 라이브 상태를 다루지 않는 대화면은 강제하지 않는다', async () => {
+    const rec = recordChoices(2)
+    await runAgenticLoop(
+      mkInput({ chat: rec.chat }, { isReadTool: () => true, executeReadTool: () => ({ ok: 1 }) })
+    )
+    expect(rec.choices).toEqual(['auto', 'auto'])
+  })
+})
+
+describe('runAgenticLoop — 제안 채널(실행은 사용자)', () => {
+  test('도구 결과에 proposed:true 가 있으면 제안으로 올린다 — 대화면이 실행 버튼을 그릴 근거', async () => {
+    let i = 0
+    const input = mkInput(
+      {
+        chat: async () => {
+          i++
+          return i === 1 ? okResult(undefined, [TC('proposeAction', { command: 'order.hold' })]) : okResult('확인해 주세요')
+        }
+      },
+      {
+        isReadTool: () => true,
+        executeReadTool: () => ({
+          proposed: true,
+          command: 'order.hold',
+          args: { orderId: 'o7' },
+          label: 'o7 보류',
+          instanceId: 'busan-wms'
+        })
+      }
+    )
+    const r = await runAgenticLoop(input)
+    expect(r.proposals).toHaveLength(1)
+    expect(r.proposals[0]).toMatchObject({ tool: 'proposeAction', command: 'order.hold', instanceId: 'busan-wms' })
+  })
+
+  test('평범한 조회 결과는 제안이 아니다 — 규약은 proposed 플래그 하나뿐', async () => {
+    const r = await runAgenticLoop(
+      mkInput(
+        {
+          chat: async () => okResult('상태 정상')
+        },
+        { isReadTool: () => true, executeReadTool: () => ({ occupancy: 0 }) }
+      )
+    )
+    expect(r.proposals).toEqual([])
+  })
+})
+
+describe('runAgenticLoop — 같은 조치는 한 번만 제안된다', () => {
+  /* 실제 사고: 모델이 같은 조치를 두 번 제안했고(하나는 인자가 비어 있었다) 카드가 둘 떴다.
+   * 하나를 실행한 뒤에도 나머지가 살아 있어 **같은 명령을 두 번** 보낼 수 있었다. */
+  test('효과가 같은 제안은 하나로 접는다 — 설명 문구가 달라도 같은 조치다', async () => {
+    let i = 0
+    const input = mkInput(
+      {
+        chat: async () => {
+          i++
+          return i === 1
+            ? okResult(undefined, [TC('proposeAction', { n: 1 }, 'p1'), TC('proposeAction', { n: 2 }, 'p2')])
+            : okResult('확인해 주세요')
+        }
+      },
+      {
+        isReadTool: () => true,
+        /* 같은 명령·같은 인자(키 순서만 다름), 설명만 다르게 — 같은 조치다. */
+        executeReadTool: (tc: any) =>
+          tc.id === 'p1'
+            ? { proposed: true, command: 'resource.add', instanceId: 'w1', args: { kind: 'fk', count: 3 }, label: 'A', reason: '가' }
+            : { proposed: true, command: 'resource.add', instanceId: 'w1', args: { count: 3, kind: 'fk' }, label: 'B', reason: '나' }
+      }
+    )
+    const r = await runAgenticLoop(input)
+    expect(r.proposals).toHaveLength(1)
+    expect(r.proposals[0].label).toBe('A') // 먼저 온 것을 남긴다
+  })
+
+  test('효과가 다르면 각각 남는다 — 서로 다른 결정이다', async () => {
+    let i = 0
+    const input = mkInput(
+      {
+        chat: async () => {
+          i++
+          return i === 1
+            ? okResult(undefined, [TC('proposeAction', {}, 'p1'), TC('proposeAction', {}, 'p2')])
+            : okResult('확인')
+        }
+      },
+      {
+        isReadTool: () => true,
+        executeReadTool: (tc: any) =>
+          tc.id === 'p1'
+            ? { proposed: true, command: 'resource.add', instanceId: 'w1', args: { count: 3 } }
+            : { proposed: true, command: 'resource.add', instanceId: 'w1', args: { count: 5 } }
+      }
+    )
+    const r = await runAgenticLoop(input)
+    expect(r.proposals).toHaveLength(2)
+  })
+})

package/server/service/agentic-loop.ts

@@ -16,6 +16,7 @@ import type {
   AIToolCall,
   AIToolChatResult
 } from '@things-factory/ai-client-base'
+import { retryTransient } from '@things-factory/ai-client-base'
 import type { BoardModel } from '@things-factory/board-import'
 import type { BoardActionOp, ToolUsage } from './types'
 
@@ -64,6 +65,17 @@ export interface AgenticLoopOptions {
    * LLM 이 같은 잘못을 무한 반복하는 경우 방어.
    */
   repeatedFailureLimit?: number
+  /**
+   * **첫 턴에 도구 호출을 강제**한다(toolChoice: 'required'). 두 번째 턴부터는 자유(auto).
+   *
+   * 왜: 접지 가드는 답이 지어낸 **식별자**를 잡지만, 식별자 없이 지어낸 **상황 서술**은 잡지 못한다
+   * ("지게차들이 바쁘게 움직이고 있다" — 실제로 이 답이 나왔다). 그건 도구를 아예 부르지 않고 답한
+   * 경우이고, 사후 검사로는 막을 수 없다. 첫 턴에 무엇이든 조회하게 만들면 근거 없이 상태를 단언할
+   * 길이 없어진다 — 개념·사용법 질문도 문서 조회 도구로 답하므로 막히지 않는다.
+   *
+   * 대화면이 정한다(라이브 상태를 다루는 면에서만 켠다) — 여기서 질문 내용을 눈치로 분류하지 않는다.
+   */
+  requireToolOnFirstTurn?: boolean
 }
 
 export interface AgenticLoopInput {
@@ -86,6 +98,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
   /**
@@ -132,6 +159,10 @@ export async function runAgenticLoop(
   const accumulatedWriteCalls: AIToolCall[] = []
   const accumulatedActions: BoardActionOp[] = []
   const toolUsages: ToolUsage[] = []
+  /* 접지 근거 — tool_result 로 LLM 에 보낸 원문(압축 전). 호출부가 답의 접지를 검사한다. */
+  const groundedTexts: string[] = []
+  /* 제안 — 도구가 실행하지 않고 제안만 한 것들. 실행 버튼은 대화면이 그린다. */
+  const proposals: any[] = []
   let lastText: string | undefined
   let stopReason: string = 'end_turn'
   let abortReason: AgenticLoopResult['abortReason']
@@ -152,15 +183,23 @@ export async function runAgenticLoop(
     log('iter %d: chat() 호출', iter)
     let result: AIToolChatResult
     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 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: any) {
       // AbortError — 별도 분류
@@ -203,9 +242,16 @@ export async function runAgenticLoop(
       dispatch,
       accumulatedWriteCalls,
       accumulatedActions,
-      toolUsages
+      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(
@@ -264,11 +310,31 @@ export async function runAgenticLoop(
     accumulatedWriteCalls,
     accumulatedActions,
     toolUsages,
+    groundedTexts,
+    proposals,
     stopReason,
     abortReason
   }
 }
 
+/**
+ * 제안의 **효과 키** — 도구·명령·대상·인자만 본다(설명 문구는 제외).
+ *
+ * 인자는 **키 순서를 정렬**해 문자열로 만든다: 같은 인자를 다른 순서로 받았을 뿐인데 다른 제안으로
+ * 보이면 카드가 둘이 되고, 사용자가 같은 명령을 두 번 실행할 수 있다.
+ */
+export function proposalEffectKey(p: any): string {
+  return [p?.tool ?? '', p?.command ?? '', p?.instanceId ?? '', stableStringify(p?.args)].join('|')
+}
+
+/** 키 정렬 직렬화 — 순서에 흔들리지 않는 비교를 위해. */
+function stableStringify(value: any): string {
+  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.
  *
@@ -335,7 +401,10 @@ async function processToolCalls(
   dispatch: ToolDispatchHelpers,
   accumulatedWriteCalls: AIToolCall[],
   accumulatedActions: BoardActionOp[],
-  toolUsages: ToolUsage[]
+  toolUsages: ToolUsage[],
+  proposals: any[],
+  /** 몇 번째 LLM 턴인가 — 기록에 남겨 화면이 단계로 읽을 수 있게 한다. */
+  iter: number
 ): Promise<any[]> {
   const toolResultParts: any[] = []
 
@@ -345,6 +414,25 @@ async function processToolCalls(
        * 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: ToolUsage['outcome'] = 'ok'
+      if (value && typeof value === 'object' && (value as any).proposed === true) {
+        /* **같은 조치는 한 번만** — 모델이 같은 것을 두 번 제안하는 일이 실제로 있었다(하나는 인자가
+         * 비어 있었다). 카드가 둘이면 사용자가 같은 명령을 두 번 실행할 수 있고, 그건 되돌릴 수 없다.
+         * 판정은 **효과**(도구·명령·대상·인자)로 한다 — 설명 문구(label·reason)가 달라도 같은 조치다. */
+        const candidate = { tool: tc.name, ...(value as any) }
+        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 as any).rejected === true || (value as any).error)) {
+        outcome = 'rejected'
+      }
       toolResultParts.push({
         type: 'tool_result',
         toolUseId: tc.id,
@@ -354,7 +442,9 @@ async function processToolCalls(
         name: tc.name,
         arguments: tc.arguments ?? {},
         result: dispatch.summarizeToolResult(value),
-        kind: 'read'
+        kind: 'read',
+        iter,
+        outcome
       })
     } else if (dispatch.isWriteTool(tc.name)) {
       // 사전 검증 — args 가 schema / build 함수 검증 통과해야 누적.
@@ -377,7 +467,9 @@ async function processToolCalls(
           name: tc.name,
           arguments: tc.arguments ?? {},
           result: errorResult,
-          kind: 'write'
+          kind: 'write',
+          iter,
+          outcome: 'rejected'
         })
         // continue — 누적 안 함. LLM 이 다음 turn 에서 정정 호출.
       } else {
@@ -392,7 +484,9 @@ async function processToolCalls(
           name: tc.name,
           arguments: tc.arguments ?? {},
           result: queuedResult,
-          kind: 'write'
+          kind: 'write',
+          iter,
+          outcome: 'queued'
         })
       }
     } else if (dispatch.isActionTool(tc.name)) {
@@ -412,7 +506,9 @@ async function processToolCalls(
         name: tc.name,
         arguments: tc.arguments ?? {},
         result: queuedResult,
-        kind: 'write'
+        kind: 'write',
+        iter,
+        outcome: 'queued'
       })
     } else {
       const errResult = { error: `Unknown tool: ${tc.name}` }
@@ -426,7 +522,9 @@ async function processToolCalls(
         name: tc.name,
         arguments: tc.arguments ?? {},
         result: errResult,
-        kind: 'unknown'
+        kind: 'unknown',
+        iter,
+        outcome: 'error'
       })
     }
   }

package/server/service/assistant.ts

@@ -34,6 +34,7 @@ import { resolveCatalogMentions } from './catalog-resolver'
 // 직접 import 안 함 — 신규 styling tool 추가 시 registry 에만 spec 추가하면 됨.
 import { buildComponentStyleSummary } from './styling/read-tools'
 import { runAgenticLoop, type AgenticLoopResult } from './agentic-loop'
+import { checkReplyGrounding } from './grounding'
 import { collectAllComponents, findComponentByRefid } from './component-tree'
 import {
   isStylingTool,
@@ -46,7 +47,9 @@ import {
   getToolKind,
   findToolSpec,
   type ToolSpec,
-  type ToolCategoryFilter
+  type ToolCategoryFilter,
+  getCategoryGuidance,
+  isTransientAIError
 } from '@things-factory/ai-client-base'
 import { validateWriteToolCall } from './validation/tool-validation'
 
@@ -152,7 +155,16 @@ export class DefaultBoardAIAssistant implements BoardAIAssistant {
      * 정의만 숨기면 모델이 이름을 추측하거나 옛 대화가 재생될 때 숨긴 도구가 실행된다. */
     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): n is number => typeof n === 'number' && Number.isFinite(n)
@@ -222,7 +234,9 @@ export class DefaultBoardAIAssistant implements BoardAIAssistant {
         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: {
@@ -267,12 +281,24 @@ export class DefaultBoardAIAssistant implements BoardAIAssistant {
       }
     }
 
+    /* 접지 검사 — 답이 **모델이 받은 것** 밖의 식별자를 지목했는지. 답은 고치지 않고 경고만 낸다.
+     * 근거집합의 정의와 사정거리는 ./grounding 머리말 참조(식별자 없는 창작 서술은 잡지 못한다). */
+    const warnings = 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
     }
   }
 
@@ -1967,7 +1993,12 @@ export function formatAbortNotice(
     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':