@things-factory/board-ai 10.0.2 → 10.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/board-ai",
-  "version": "10.0.2",
+  "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.2",
-    "@things-factory/auth-base": "^10.0.0",
-    "@things-factory/board-import": "^10.0.2",
+    "@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": "a69c3592a44e27bfa8212bc06268bff6140afc9a"
+  "gitHead": "c7d253b722b6917e8911f6ef6e78e5fc2b295e82"
 }

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

@@ -766,3 +766,94 @@ describe('runAgenticLoop — 첫 턴 도구 강제(근거 없는 단언 차단)'
     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'
 
@@ -104,6 +105,14 @@ export interface AgenticLoopResult {
    * 잘려 나간 식별자를 "근거 없음" 으로 오판한다. 여기 담기는 것은 tool_result 로 보낸 원문 그대로다.
    */
   groundedTexts: string[]
+  /**
+   * **제안** — 도구가 "실행하지 않고 제안만 했다" 고 알린 결과들(시간순).
+   *
+   * 규약: read/external 도구의 결과에 `proposed === true` 가 있으면 그것은 조치 제안이다. 그 도구가
+   * 어느 도메인인지 이 루프는 모른다 — 결과를 그대로 실어 올리고, 해석·실행 확인은 대화면이 한다.
+   * 되돌릴 수 없는 조치를 AI 가 직접 실행하지 않게 하는 경계가 이 채널이다(사람이 버튼을 누른다).
+   */
+  proposals: any[]
   /** LLM 마지막 응답의 stopReason. provider-specific 문자열. */
   stopReason: string
   /**
@@ -152,6 +161,8 @@ export async function runAgenticLoop(
   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']
@@ -172,8 +183,12 @@ 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,
@@ -182,6 +197,9 @@ export async function runAgenticLoop(
         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 — 별도 분류
@@ -224,7 +242,9 @@ export async function runAgenticLoop(
       dispatch,
       accumulatedWriteCalls,
       accumulatedActions,
-      toolUsages
+      toolUsages,
+      proposals,
+      iter
     )
 
     /* 접지 근거 누적 — 모델이 tool_result 로 받은 원문 그대로. 압축 전 값이어야 한다(위 필드 주석). */
@@ -291,11 +311,30 @@ export async function runAgenticLoop(
     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.
  *
@@ -362,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[] = []
 
@@ -372,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,
@@ -381,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 함수 검증 통과해야 누적.
@@ -404,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 {
@@ -419,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)) {
@@ -439,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}` }
@@ -453,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

@@ -47,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'
 
@@ -153,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)
@@ -285,6 +296,8 @@ export class DefaultBoardAIAssistant implements BoardAIAssistant {
       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
     }
   }
@@ -1980,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':

package/server/service/board-ai-resolver.ts

@@ -18,6 +18,25 @@ import type { LLMMessage } from './types.js'
 import { ChatSession } from './chat-session/chat-session.js'
 import { ChatMessage } from './chat-message/chat-message.js'
 import { buildLlmHistory } from './chat-message/llm-history.js'
+import { splitByCap, summaryInstruction } from './chat-message/history-summary.js'
+import { foldHistorySummary } from './chat-message/fold-history.js'
+
+/**
+ * 모델에 넘길 최근 메시지 수 상한.
+ *
+ * 협의는 여럿이 며칠에 걸쳐 이어진다 — 상한 없이 전체를 매 턴 보내면 프롬프트가 무한히 자라고
+ * (비용·지연·문맥 한계) 오래된 말이 최근 상황을 덮는다. 40 은 첫 경계선이다: 한 자리의 협의를
+ * 담기에 넉넉하고, 넘치면 생략 사실을 모델에 알린다(조용히 버리지 않는다).
+ * 버린 앞부분을 **요약해서** 실어 보내는 것이 다음 단계다(ChatSession.lastSummary 미사용 상태).
+ */
+const LLM_HISTORY_MAX_TURNS = 40
+
+/**
+ * 요약을 다시 만드는 임계치 — 상한 밖으로 **새로 밀려난** 메시지 수.
+ *
+ * 상한을 넘긴 뒤 매 턴 요약을 만들면 대화마다 LLM 호출이 두 번씩 붙는다. 10 개씩 모아 접는다.
+ */
+const LLM_SUMMARY_THRESHOLD = 10
 import { activityPatch, autoSessionName } from './chat-session/session-inbox.js'
 import { publishSessionActivity } from './chat-session/session-activity-publish.js'
 import { publishChatMessage } from './chat-message/chat-message-publish.js'
@@ -204,6 +223,20 @@ class BoardAIChatOutput {
   })
   actions?: any
 
+  @Field(() => GraphQLJSON, {
+    nullable: true,
+    description:
+      'Reported when the stored history exceeded the prompt cap for this turn: { omitted, summarized }. The surface uses it to tell the user the conversation grew long — a new conversation is better for a different topic. Objective fact only; no topic-change detection.'
+  })
+  historyFolded?: any
+
+  @Field(() => GraphQLJSON, {
+    nullable: true,
+    description:
+      'Action proposals the AI recorded without executing — each carries what a tool returned alongside `proposed: true`. The surface renders a confirm button; execution is the user\'s act, never the assistant\'s. Null when nothing was proposed.'
+  })
+  proposals?: any
+
   @Field(() => GraphQLJSON, {
     nullable: true,
     description:
@@ -321,12 +354,21 @@ export class BoardAIChatResolver {
      * 정렬은 createdAt ASC + id ASC — 같은 시각 삽입의 순서까지 결정적으로 만든다(조립 쪽에서
      * 다시 정렬하지 않으므로 여기서 확정해야 한다). 멘션 마커는 여기서 제거해 넘긴다. */
     let llmMessages: LLMMessage[]
+    let historyFolded: { omitted: number; summarized: boolean } | undefined
     if (session) {
       const rows = await messageRepo.find({
         where: { session: { id: session.id } as any },
         relations: { creator: true },
         order: { createdAt: 'ASC', id: 'ASC' }
       })
+      /* 이번 턴에 상한 밖으로 밀려난 것이 있는가 — 화면이 "대화가 길어졌다" 를 알릴 근거(사실만). */
+      const capped = splitByCap(
+        rows.map(row => ({ id: row.id, role: row.role, content: row.content ?? '' })),
+        LLM_HISTORY_MAX_TURNS
+      )
+      if (capped.dropped.length > 0) {
+        historyFolded = { omitted: capped.dropped.length, summarized: !!(session as any).lastSummary }
+      }
       llmMessages = buildLlmHistory(
         rows.map(row => ({
           id: row.id,
@@ -339,7 +381,11 @@ export class BoardAIChatResolver {
         {
           truncateAfterMessageId: input.truncateAfterMessageId ?? undefined,
           /* 방금 저장한 사용자 메시지는 접은 구간보다 뒤에 있어도 반드시 남긴다. */
-          keepMessageIds: userMessageId ? [userMessageId] : []
+          keepMessageIds: userMessageId ? [userMessageId] : [],
+          /* 이력 상한 — 협의는 며칠 이어진다. 상한이 없으면 매 턴 전체를 보내 프롬프트가 무한히 자란다. */
+          maxTurns: LLM_HISTORY_MAX_TURNS,
+          /* 밀려난 앞부분은 요약으로 대체한다(있으면). 요약은 응답 뒤에 갱신한다 — 아래 Phase D. */
+          summary: { text: (session as any).lastSummary, upToMessageId: (session as any).summaryUpToMessageId }
         }
       )
     } else {
@@ -435,6 +481,12 @@ export class BoardAIChatResolver {
         /* AI 응답도 세션 활동이다 — 이걸 빼면 다른 참여자에게 "새 소식 없음"으로 보인다. */
         ...activityPatch(enrichedReply)
       })
+
+      /* ── Phase D: 이력 요약 접기 ────────────────────────────────────────────
+       * 응답을 **돌려준 뒤** 갱신한다 — 사용자 대기 시간에 요약용 LLM 호출을 얹지 않는다.
+       * 기다리지 않으므로(await 없음) 실패해도 대화에는 영향이 없다: 요약이 없으면 다음 턴은
+       * "N개 생략" 으로 정직하게 알리고 넘어간다(조용한 맥락 상실이 아니다). */
+      void this._foldHistorySummary(session.id!, domain.id, base)
     }
 
     return {
@@ -448,10 +500,65 @@ export class BoardAIChatResolver {
       patchId,
       toolUsages: r.toolUsages ?? null,
       actions: r.actions && r.actions.length > 0 ? r.actions : null,
+      proposals: r.proposals && r.proposals.length > 0 ? r.proposals : null,
+      historyFolded: historyFolded ?? null,
       groundingWarnings: r.groundingWarnings && r.groundingWarnings.length > 0 ? r.groundingWarnings : null
     }
   }
 
+  /**
+   * 이력 요약 접기 — 상한 밖으로 밀려난 앞부분을 요약으로 눌러 담는다.
+   *
+   * 왜 이렇게 나눠 두었나: 판정(무엇을 요약할지·다시 만들 때인지)은 순수 로직(history-summary)이
+   * 갖고, 여기서는 **호출과 저장**만 한다. 그래야 규칙을 테스트로 고정할 수 있다.
+   *
+   * 아껴 만든다: 새로 밀려난 것이 임계치를 넘을 때만 LLM 을 부른다(상한을 넘긴 뒤 매 턴 부르면
+   * 대화마다 호출이 두 번씩 붙는다). 실패는 조용히 넘긴다 — 다음 턴이 "생략" 으로 알리고,
+   * 다음 임계치에서 다시 시도한다.
+   */
+  private async _foldHistorySummary(
+    sessionId: string,
+    domainId: string,
+    client: AIClient
+  ): Promise<void> {
+    try {
+      const sessionRepo = getRepository(ChatSession)
+      const session = await sessionRepo.findOneBy({ id: sessionId, domain: { id: domainId } as any })
+      if (!session) return
+      const rows = await getRepository(ChatMessage).find({
+        where: { session: { id: sessionId } as any },
+        relations: { creator: true },
+        order: { createdAt: 'ASC', id: 'ASC' }
+      })
+      const history = rows.map(row => ({
+        id: row.id,
+        role: row.role,
+        content: stripMentionRefids(row.content ?? ''),
+        senderId: (row as any).creator?.id,
+        senderName: (row as any).creator?.name || (row as any).creator?.username
+      }))
+      const { patch } = await foldHistorySummary({
+        rows: history,
+        stored: {
+          text: (session as any).lastSummary,
+          upToMessageId: (session as any).summaryUpToMessageId
+        },
+        maxTurns: LLM_HISTORY_MAX_TURNS,
+        threshold: LLM_SUMMARY_THRESHOLD,
+        summarize: content =>
+          client.chat([{ role: 'user', content }], {
+            systemPrompt: summaryInstruction(),
+            maxTokens: 700,
+            /* 요약은 창작이 아니다 — 흔들림을 줄인다. */
+            temperature: 0
+          })
+      })
+      if (patch) await sessionRepo.update(sessionId, patch as any)
+    } catch {
+      /* 요약 실패는 대화를 막지 않는다 — 다음 턴은 "생략" 으로 정직하게 알린다. */
+    }
+  }
+
   /**
    * C4: 메시지에 @멘션된 사용자를 세션 참여자(member)로 자동 등록 — 초대.
    * enriched content 의 {userId:UUID} 마커에서 추출 → 기존 참여자·자기 제외한 신규만 등록.

package/server/service/chat-message/fold-history.test.ts

@@ -0,0 +1,98 @@
+/*
+ * 요약 접기 오케스트레이션 검증 — **"배선했지만 한 번도 안 돌아본" 코드를 만들지 않기 위해.**
+ *
+ * 이 경로는 51번째 메시지부터 처음 돌기 때문에 실제 대화로 확인하려면 오래 걸린다. 그래서 요약
+ * 생성기(LLM)만 대역으로 끼우고 **판정·조립·저장 값**을 여기서 고정한다.
+ *
+ * 무엇을 지키는가:
+ *  ① 밀려난 것이 없으면 부르지 않는다(비용).
+ *  ② 임계치 미만이면 부르지 않는다(매 턴 호출 방지).
+ *  ③ 이전 요약을 이어 넘긴다(누적 — 전체 재요약 금지).
+ *  ④ 저장 값은 본문 + 어디까지 접었는지, 항상 함께.
+ *  ⑤ 생성 실패·빈 응답은 삼키되 **이유를 남긴다**(조용한 무동작 금지).
+ */
+import { foldHistorySummary } from './fold-history'
+
+const rows = (n: number) =>
+  Array.from({ length: n }, (_, i) => ({
+    id: `m${i}`,
+    role: i % 2 ? 'assistant' : 'user',
+    content: `말 ${i}`
+  }))
+
+/** 호출 여부·입력을 기록하는 요약 생성기 대역. */
+function recorder(reply: string | undefined | null = '요약 결과') {
+  const calls: string[] = []
+  return {
+    calls,
+    summarize: async (content: string) => {
+      calls.push(content)
+      return reply
+    }
+  }
+}
+
+describe('foldHistorySummary', () => {
+  it('상한 안이면 요약기를 부르지 않는다 — 비용을 쓰지 않는다', async () => {
+    const rec = recorder()
+    const r = await foldHistorySummary({ rows: rows(10), maxTurns: 40, threshold: 10, summarize: rec.summarize })
+    expect(r.patch).toBeNull()
+    expect(r.skipped).toBe('nothing-dropped')
+    expect(rec.calls).toHaveLength(0)
+  })
+
+  it('밀려났지만 임계치 미만이면 부르지 않는다 — 상한 넘긴 뒤 매 턴 호출 방지', async () => {
+    const rec = recorder()
+    /* 45개 중 40개 유지 → 5개 밀려남(임계치 10 미만) */
+    const r = await foldHistorySummary({ rows: rows(45), maxTurns: 40, threshold: 10, summarize: rec.summarize })
+    expect(r.skipped).toBe('below-threshold')
+    expect(rec.calls).toHaveLength(0)
+  })
+
+  it('임계치를 넘으면 요약을 만들고 저장 값을 돌려준다', async () => {
+    const rec = recorder('· dock-1 포화 확인\n· 지게차 1대 추가로 합의')
+    const r = await foldHistorySummary({ rows: rows(52), maxTurns: 40, threshold: 10, summarize: rec.summarize })
+    expect(rec.calls).toHaveLength(1)
+    expect(r.patch).toEqual({
+      lastSummary: '· dock-1 포화 확인\n· 지게차 1대 추가로 합의',
+      /* 밀려난 것은 m0..m11 → 마지막으로 접은 것이 m11 */
+      summaryUpToMessageId: 'm11'
+    })
+  })
+
+  it('이전 요약을 이어 넘긴다 — 원본 전체를 다시 읽지 않는다(누적)', async () => {
+    const rec = recorder()
+    await foldHistorySummary({
+      rows: rows(60),
+      stored: { text: '앞에서 정한 것: 지게차 1대 추가', upToMessageId: 'm5' },
+      maxTurns: 40,
+      threshold: 10,
+      summarize: rec.summarize
+    })
+    const sent = rec.calls[0]
+    expect(sent).toContain('앞에서 정한 것: 지게차 1대 추가')
+    /* 이미 접은 m0..m5 는 다시 넘기지 않는다 */
+    expect(sent).not.toContain('말 0')
+    expect(sent).toContain('말 6')
+  })
+
+  it('빈 요약은 저장하지 않는다 — 이유를 남긴다', async () => {
+    const rec = recorder('   ')
+    const r = await foldHistorySummary({ rows: rows(52), maxTurns: 40, threshold: 10, summarize: rec.summarize })
+    expect(r.patch).toBeNull()
+    expect(r.skipped).toBe('empty-summary')
+  })
+
+  it('요약기가 실패해도 대화를 막지 않는다 — 이유를 남기고 넘어간다', async () => {
+    const r = await foldHistorySummary({
+      rows: rows(52),
+      maxTurns: 40,
+      threshold: 10,
+      summarize: async () => {
+        throw new Error('provider down')
+      }
+    })
+    expect(r.patch).toBeNull()
+    expect(r.skipped).toBe('failed')
+  })
+})