@things-factory/board-ai 10.0.1 → 10.0.3

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'
@@ -105,6 +124,13 @@ class BoardAIChatInput {
   })
   boardTools?: boolean
 
+  @Field({
+    nullable: true,
+    description:
+      'Force a tool call on the first turn (toolChoice: required). Turn this on for surfaces that discuss live state: the grounding guard catches invented identifiers but not an invented situation stated without any, which only happens when the model answers without querying at all. Concept / how-to questions are unaffected — they are answered through a documentation tool.'
+  })
+  requireGroundingTools?: boolean
+
   @Field(() => [String], {
     nullable: true,
     description: 'Component types the LLM is allowed to emit (e.g. ["rect", "label"]). Constrains generation to the current solution.'
@@ -196,6 +222,27 @@ class BoardAIChatOutput {
       'Ephemeral scene actions (selection/view/mode) — sequence of BoardActionOp. Applied via board-action-execute event on the host. Distinct from `patch` which carries persistent model changes.'
   })
   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:
+      'Ungrounded identifiers mentioned by the reply — present in the answer but absent from everything the model received (prompt, board context, history, tool results). Hallucination candidates surfaced to the user; the reply itself is not altered. Null when the answer is grounded.'
+  })
+  groundingWarnings?: any
 }
 
 @Resolver()
@@ -307,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,
@@ -325,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 {
@@ -341,6 +401,7 @@ export class BoardAIChatResolver {
       /* 대화면별 도구 노출 — 미지정이면 현행(전부 허용) 그대로. */
       toolCategories: input.toolCategories ?? undefined,
       boardTools: input.boardTools ?? undefined,
+      requireGroundingTools: input.requireGroundingTools ?? undefined,
       knownTypes: input.knownTypes,
       categories: input.categories as ComponentCategory[] | undefined,
       selectedRefids: input.selectedRefids,
@@ -385,6 +446,12 @@ export class BoardAIChatResolver {
         content: enrichedReply,
         relatedPatchId: patchEntry?.id,
         toolUsages: r.toolUsages && r.toolUsages.length > 0 ? JSON.stringify(r.toolUsages) : undefined,
+        /* 접지 경고를 함께 영속 — 나중에 읽는 참여자도 같은 주의를 봐야 한다(재계산 불가: 근거 원문이 남지 않는다).
+         * 컬럼 길이(1024) 안에 들도록 앞 20개까지만 — 그 이상이면 목록이 아니라 답 자체가 문제다. */
+        groundingWarnings:
+          r.groundingWarnings && r.groundingWarnings.length > 0
+            ? JSON.stringify(r.groundingWarnings.slice(0, 20))
+            : undefined,
         // assistant 메시지의 creator = 이 응답을 트리거한 user (= 직전 user 메시지의 작성자).
         // 같은 turn 으로 묶임 → 향후 사용자별 필터에서 user/assistant 가 함께 따라옴.
         creator: user,
@@ -414,6 +481,12 @@ export class BoardAIChatResolver {
         /* AI 응답도 세션 활동이다 — 이걸 빼면 다른 참여자에게 "새 소식 없음"으로 보인다. */
         ...activityPatch(enrichedReply)
       })
+
+      /* ── Phase D: 이력 요약 접기 ────────────────────────────────────────────
+       * 응답을 **돌려준 뒤** 갱신한다 — 사용자 대기 시간에 요약용 LLM 호출을 얹지 않는다.
+       * 기다리지 않으므로(await 없음) 실패해도 대화에는 영향이 없다: 요약이 없으면 다음 턴은
+       * "N개 생략" 으로 정직하게 알리고 넘어간다(조용한 맥락 상실이 아니다). */
+      void this._foldHistorySummary(session.id!, domain.id, base)
     }
 
     return {
@@ -426,7 +499,63 @@ export class BoardAIChatResolver {
       assistantMessageId,
       patchId,
       toolUsages: r.toolUsages ?? null,
-      actions: r.actions && r.actions.length > 0 ? r.actions : 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 {
+      /* 요약 실패는 대화를 막지 않는다 — 다음 턴은 "생략" 으로 정직하게 알린다. */
     }
   }
 

package/server/service/chat-message/chat-message.ts

@@ -107,6 +107,32 @@ export class ChatMessage {
     }
   }
 
+  /**
+   * 접지 경고 — 이 답이 언급했으나 근거(프롬프트·보드 문맥·이력·도구 결과)에 없던 식별자 목록.
+   *
+   * **왜 영속하는가**: 도크의 협의는 여러 사람이 며칠에 걸쳐 읽는다. 경고가 그 자리에서만
+   * 보이고 새로 고치면 사라지면, 나중에 읽는 사람은 검증되지 않은 문장을 검증된 것으로 읽는다.
+   * 다시 계산할 수도 없다 — 근거였던 도구 결과 원문은 남지 않고 압축본만 남기 때문이다.
+   *
+   * 형태: string[] 를 JSON-stringify. 비었으면 null(= 접지 정상).
+   */
+  @Column({ type: 'varchar', length: 1024, nullable: true })
+  groundingWarnings?: string
+
+  /** GraphQL 노출용 — 식별자 배열로 parse. */
+  @Field(() => GraphQLJSON, {
+    nullable: true,
+    description: 'Ungrounded identifiers mentioned by this reply (hallucination candidates). Null when grounded.'
+  })
+  get groundingWarningsJson(): any {
+    if (!this.groundingWarnings) return null
+    try {
+      return JSON.parse(this.groundingWarnings)
+    } catch {
+      return null
+    }
+  }
+
   /**
    * 메시지를 일으킨 사용자.
    *   - role='user' → 보낸 사용자

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')
+  })
+})

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

@@ -0,0 +1,60 @@
+/*
+ * 요약 접기 오케스트레이션 — **판정과 조립은 여기, DB 는 호출부**.
+ *
+ * 왜 분리하는가: 요약을 만드는 결정(무엇을·언제·무엇에 이어)은 규칙이고, 규칙은 테스트로 고정할 수
+ * 있어야 한다. 리졸버 안에 두면 DB 없이 검증할 수 없어 "배선했지만 한 번도 안 돌아본" 코드가 된다.
+ * 요약 생성기(LLM)와 이력·저장은 호출부가 주입한다.
+ */
+import type { HistoryRow } from './llm-history.js'
+import {
+  splitByCap,
+  pendingForSummary,
+  shouldResummarize,
+  summaryUserContent,
+  summaryPatch,
+  type StoredSummary
+} from './history-summary.js'
+
+export interface FoldHistoryInput {
+  /** 시간 오름차순 이력 전체. */
+  rows: HistoryRow[]
+  /** 세션에 저장된 요약 상태. */
+  stored?: StoredSummary
+  /** 프롬프트 상한(이 밖으로 밀려난 것이 요약 대상). */
+  maxTurns: number
+  /** 새로 밀려난 것이 이 수 이상일 때만 요약을 만든다(매 턴 호출 방지). */
+  threshold: number
+  /** 요약 생성 — 실패하면 throw 하거나 빈 문자열을 돌려주면 된다(둘 다 "접지 않음" 으로 처리). */
+  summarize: (content: string) => Promise<string | undefined | null>
+}
+
+export interface FoldHistoryResult {
+  /** 세션에 저장할 값. null 이면 이번엔 접지 않는다(대상 없음·임계치 미만·생성 실패). */
+  patch: { lastSummary: string; summaryUpToMessageId?: string } | null
+  /** 접지 않은 이유 — 관측·테스트용(조용한 무동작을 남기지 않는다). */
+  skipped?: 'nothing-dropped' | 'below-threshold' | 'empty-summary' | 'failed'
+}
+
+/**
+ * 접을지 판정하고, 접어야 하면 요약을 만들어 저장 값을 돌려준다.
+ *
+ * 실패를 삼키되 **왜 안 접었는지**는 남긴다 — 조용한 무동작은 나중에 "요약이 왜 안 생기지" 를
+ * 추적 불가능하게 만든다.
+ */
+export async function foldHistorySummary(input: FoldHistoryInput): Promise<FoldHistoryResult> {
+  const { dropped } = splitByCap(input.rows, input.maxTurns)
+  if (dropped.length === 0) return { patch: null, skipped: 'nothing-dropped' }
+
+  const pending = pendingForSummary(dropped, input.stored)
+  if (!shouldResummarize(pending, input.threshold)) return { patch: null, skipped: 'below-threshold' }
+
+  let text: string | undefined | null
+  try {
+    text = await input.summarize(summaryUserContent(input.stored?.text, pending))
+  } catch {
+    return { patch: null, skipped: 'failed' }
+  }
+  if (!text || !text.trim()) return { patch: null, skipped: 'empty-summary' }
+
+  return { patch: summaryPatch(text, pending) }
+}

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

@@ -0,0 +1,127 @@
+/*
+ * 이력 요약 접기 규칙 검증.
+ *
+ * 무엇을 지키는가:
+ *  ① **누적** — 이전 요약 뒤부터만 새로 접는다(전체 재요약=비용, 중복 접기=왜곡).
+ *  ② **아껴 만든다** — 새로 밀려난 것이 임계치를 넘을 때만. 상한 넘긴 뒤 매 턴 부르면 호출이 두 배.
+ *  ③ **덮은 범위를 함께 저장** — 본문과 upToMessageId 는 항상 같이 간다(따로 저장하면 어긋난다).
+ *  ④ **모르면 다시 요약** — 기록된 id 를 이력에서 못 찾으면 전부 미반영으로 본다(맥락 상실 방지).
+ *  ⑤ **지시는 사실 위주** — 결정·미결·식별자 보존을 요구하고 창작을 금지한다.
+ */
+import {
+  splitByCap,
+  pendingForSummary,
+  shouldResummarize,
+  summarySourceText,
+  summaryUserContent,
+  summaryInstruction,
+  summaryPatch
+} from './history-summary'
+
+const rows = (n: number, from = 0) =>
+  Array.from({ length: n }, (_, i) => ({
+    id: `m${from + i}`,
+    role: (from + i) % 2 ? 'assistant' : 'user',
+    content: `말 ${from + i}`
+  }))
+
+describe('splitByCap', () => {
+  it('상한 이하면 아무것도 밀려나지 않는다', () => {
+    const r = splitByCap(rows(5), 10)
+    expect(r.dropped).toEqual([])
+    expect(r.kept).toHaveLength(5)
+  })
+
+  it('상한을 넘으면 앞부분이 밀려나고 최근이 남는다', () => {
+    const r = splitByCap(rows(12), 4)
+    expect(r.dropped).toHaveLength(8)
+    expect(r.kept.map(x => x.id)).toEqual(['m8', 'm9', 'm10', 'm11'])
+  })
+})
+
+describe('pendingForSummary — 누적', () => {
+  const dropped = rows(8)
+
+  it('요약이 없으면 밀려난 전부가 대상', () => {
+    expect(pendingForSummary(dropped, undefined)).toHaveLength(8)
+  })
+
+  it('요약이 덮은 지점 뒤부터만 대상 — 이미 접은 것을 또 접지 않는다', () => {
+    const p = pendingForSummary(dropped, { text: '앞부분 요약', upToMessageId: 'm4' })
+    expect(p.map(x => x.id)).toEqual(['m5', 'm6', 'm7'])
+  })
+
+  it('기록된 id 를 못 찾으면 전부 다시 — 빠뜨리는 쪽보다 안전하다', () => {
+    const p = pendingForSummary(dropped, { text: '요약', upToMessageId: 'deleted' })
+    expect(p).toHaveLength(8)
+  })
+
+  it('본문 없는 기록은 요약이 없는 것으로 본다', () => {
+    expect(pendingForSummary(dropped, { text: '', upToMessageId: 'm4' })).toHaveLength(8)
+  })
+})
+
+describe('shouldResummarize — 아껴 만들기', () => {
+  it('임계치를 넘으면 만든다', () => {
+    expect(shouldResummarize(rows(10), 10)).toBe(true)
+  })
+  it('임계치 미만이면 만들지 않는다 — 매 턴 호출 방지', () => {
+    expect(shouldResummarize(rows(9), 10)).toBe(false)
+  })
+  it('밀려난 것이 없으면 만들지 않는다', () => {
+    expect(shouldResummarize([], 10)).toBe(false)
+  })
+})
+
+describe('요약 입력', () => {
+  it('발신자 표기를 유지한다 — 협의에서 누가 말했는지가 핵심 정보', () => {
+    const text = summarySourceText([
+      { id: 'a', role: 'user', content: '도크 포화 확인 필요', senderName: '김철수' },
+      { id: 'b', role: 'assistant', content: 'dock-1 점유 92%' },
+      { id: 'c', role: 'system', content: '실행됨: o7 보류' }
+    ])
+    expect(text).toContain('김철수: 도크 포화 확인 필요')
+    expect(text).toContain('AI: dock-1 점유 92%')
+    expect(text).toContain('SYSTEM: 실행됨: o7 보류')
+  })
+
+  it('이전 요약을 앞에 얹어 누적 입력을 만든다', () => {
+    const content = summaryUserContent('앞에서 정한 것: 지게차 1대 추가', rows(2))
+    expect(content).toContain('SUMMARY SO FAR')
+    expect(content).toContain('지게차 1대 추가')
+    expect(content).toContain('NEW MESSAGES TO FOLD IN')
+  })
+
+  it('이전 요약이 없으면 새 대화만 넣는다', () => {
+    expect(summaryUserContent(null, rows(2))).not.toContain('SUMMARY SO FAR')
+  })
+})
+
+describe('요약 지시', () => {
+  const instruction = summaryInstruction()
+
+  it('결정·미결을 남기라고 요구한다 — 그게 나중까지 필요한 것이다', () => {
+    expect(instruction).toMatch(/decided/i)
+    expect(instruction).toMatch(/still open/i)
+  })
+
+  it('식별자를 그대로 보존하라고 요구한다 — 이름이 바뀌면 이후 접지가 깨진다', () => {
+    expect(instruction).toMatch(/identifiers/i)
+    expect(instruction).toMatch(/EXACTLY/)
+  })
+
+  it('없는 사실을 더하지 말라고 못박는다', () => {
+    expect(instruction).toMatch(/Never add facts/i)
+  })
+})
+
+describe('summaryPatch — 본문과 범위는 함께', () => {
+  it('마지막으로 접은 메시지 id 를 함께 저장한다', () => {
+    const patch = summaryPatch('요약 본문', rows(3))
+    expect(patch).toEqual({ lastSummary: '요약 본문', summaryUpToMessageId: 'm2' })
+  })
+
+  it('본문은 상한(4000)으로 자른다 — 요약이 프롬프트를 다시 부풀리지 않게', () => {
+    expect(summaryPatch('가'.repeat(5000), rows(1)).lastSummary).toHaveLength(4000)
+  })
+})

package/server/service/chat-message/history-summary.ts

@@ -0,0 +1,100 @@
+/*
+ * 이력 요약 접기 — 긴 협의의 앞부분을 **요약으로 대체**한다.
+ *
+ * ── 왜 필요한가 ─────────────────────────────────────────────────────────────
+ * 모델은 기억이 없어 매 턴 이력을 다시 받는다. 그래서 상한(maxTurns)을 두었지만, 상한만으로는
+ * 넘친 앞부분이 **그냥 사라진다** — 며칠 이어지는 협의에서 앞에서 합의한 내용이 없던 일이 된다.
+ * 요약을 대신 실어 보내면 토큰은 상한 안에 머물면서 맥락은 남는다.
+ *
+ * ── 규율 ────────────────────────────────────────────────────────────────────
+ * ① **어디까지 요약했는지 기록한다**(upToMessageId). 그것이 없으면 매 턴 전체를 다시 요약하거나
+ *    (비용) 이미 요약한 것을 또 이어 붙인다(중복).
+ * ② **누적 요약**이다: 이전 요약 + 새로 밀려난 메시지 → 새 요약. 원본 전체를 다시 읽지 않는다.
+ * ③ **아껴 만든다**: 새로 밀려난 것이 임계치를 넘을 때만 다시 만든다. 상한을 넘긴 뒤 매 턴
+ *    요약을 만들면 대화마다 LLM 호출이 두 번씩 붙는다.
+ * ④ **요약은 요약이라고 밝힌다**: 프롬프트에 "요약(원문 아님)" 으로 표기해 모델이 그것을 인용
+ *    가능한 원문처럼 다루지 않게 한다. 요약에 없는 사실은 사용자에게 다시 확인해야 한다.
+ *
+ * 이 파일은 순수 로직이다 — LLM 호출·DB 는 리졸버가 한다(테스트 가능성 유지).
+ */
+import type { HistoryRow } from './llm-history.js'
+
+/** 세션에 저장된 요약 상태. */
+export interface StoredSummary {
+  /** 요약 본문(사람이 읽어도 되는 몇 문장). 없으면 아직 요약이 없다. */
+  text?: string | null
+  /** 이 메시지까지 요약에 반영됐다. 이후 메시지는 아직 요약 밖. */
+  upToMessageId?: string | null
+}
+
+/** 상한 기준으로 이력을 둘로 나눈다 — 밀려나는 앞부분과 원문으로 남길 최근 부분. */
+export function splitByCap(rows: HistoryRow[], maxTurns: number): { dropped: HistoryRow[]; kept: HistoryRow[] } {
+  if (!maxTurns || maxTurns <= 0 || rows.length <= maxTurns) return { dropped: [], kept: rows }
+  return { dropped: rows.slice(0, rows.length - maxTurns), kept: rows.slice(-maxTurns) }
+}
+
+/**
+ * 아직 요약에 반영되지 않은, 밀려난 메시지들.
+ *
+ * 저장된 요약이 어디까지 덮는지(upToMessageId)를 기준으로 그 **뒤부터** 센다. 기록된 id 가 이력에
+ * 없으면(삭제·편집) 덮은 범위를 알 수 없으므로 **전부 미반영으로 본다** — 빠뜨리는 쪽보다 다시
+ * 요약하는 쪽이 안전하다(맥락 상실은 답을 망친다).
+ */
+export function pendingForSummary(dropped: HistoryRow[], stored: StoredSummary | undefined): HistoryRow[] {
+  const upTo = stored?.upToMessageId
+  if (!upTo || !stored?.text) return dropped
+  const idx = dropped.findIndex(r => r.id === upTo)
+  return idx < 0 ? dropped : dropped.slice(idx + 1)
+}
+
+/**
+ * 요약을 다시 만들 때인가 — 새로 밀려난 것이 임계치 이상일 때만.
+ * (상한을 넘긴 뒤 매 턴 만들면 대화마다 LLM 호출이 두 번씩 붙는다.)
+ */
+export function shouldResummarize(pending: HistoryRow[], threshold = 10): boolean {
+  return pending.length >= Math.max(1, threshold)
+}
+
+/** 요약 대상 텍스트 — 발신자 표기를 유지해 누가 무엇을 말했는지 남긴다(협의의 핵심 정보). */
+export function summarySourceText(pending: HistoryRow[]): string {
+  return pending
+    .map(r => {
+      const who = r.role === 'assistant' ? 'AI' : r.role === 'system' ? 'SYSTEM' : r.senderName || 'USER'
+      return `${who}: ${(r.content ?? '').trim()}`
+    })
+    .filter(line => line.length > 6)
+    .join('\n')
+}
+
+/**
+ * 요약 생성 지시 — **사실만, 짧게, 지어내지 말 것.**
+ *
+ * 협의에서 나중까지 필요한 것은 "무엇을 확인했고, 무엇을 정했고, 무엇이 남았는지" 다. 잡담·인사는
+ * 버려도 되지만 **결정과 미결**은 남아야 한다. 식별자는 원문 그대로 유지하라고 지시한다 — 요약이
+ * 이름을 바꾸면 이후 대화의 접지가 깨진다.
+ */
+export function summaryInstruction(locale?: string): string {
+  return [
+    'Summarize the earlier part of a shared operations deliberation so it can be carried into later turns.',
+    'Keep ONLY what stays relevant: what was checked and found, what was decided, what is still open, and any action that was executed.',
+    'Drop greetings, small talk, and repetition.',
+    'Preserve identifiers (node / order / instance ids) EXACTLY as written — renaming them breaks grounding in later turns.',
+    'Never add facts that are not in the text. If something is unclear, leave it out.',
+    'At most 8 short bullet points. No preamble, no closing remark.',
+    locale ? `Write the summary in the language of locale "${locale}".` : ''
+  ]
+    .filter(Boolean)
+    .join(' ')
+}
+
+/** 이전 요약과 새로 밀려난 대화를 합쳐 넘길 본문 — 누적 요약의 입력. */
+export function summaryUserContent(previous: string | null | undefined, pending: HistoryRow[]): string {
+  const head = previous?.trim() ? `SUMMARY SO FAR:\n${previous.trim()}\n\n` : ''
+  return `${head}NEW MESSAGES TO FOLD IN:\n${summarySourceText(pending)}`
+}
+
+/** 요약 저장 값 — 본문과 "어디까지 덮었는지". 둘은 항상 함께 저장한다(따로 저장하면 어긋난다). */
+export function summaryPatch(text: string, pending: HistoryRow[]): { lastSummary: string; summaryUpToMessageId?: string } {
+  const last = [...pending].reverse().find(r => r.id)?.id
+  return { lastSummary: text.trim().slice(0, 4000), summaryUpToMessageId: last }
+}