@things-factory/ai-assistant 10.1.6

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

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

@@ -0,0 +1,12 @@
+import { ChatMessage } from './chat-message.js'
+
+export { ChatMessage }
+export {
+  ChatMessageSubscription,
+  publishChatMessage,
+  CHAT_MESSAGE_TOPIC,
+  chatMessageFilter
+} from './chat-message-subscription.js'
+export type { ChatMessagePayload } from './chat-message-subscription.js'
+
+export const entities = [ChatMessage]

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

@@ -0,0 +1,194 @@
+/*
+ * 에이전트에게 넘길 대화 이력 조립 검증.
+ *
+ * 무엇을 지키는가:
+ *  ① **발신자 구별** — 여러 사람이 참여한 세션에서 누가 말했는지 모델이 알 수 있어야 한다.
+ *     예전에는 모든 사람 발언이 role='user' 하나로 뭉개져, "승인합니다"를 누가 했는지 알 수 없었다.
+ *  ② **혼자 대화는 그대로** — 표기를 넣으면 노이즈·토큰이 늘고 기존 프롬프트가 달라진다.
+ *  ③ **system 기록 전달** — 캔버스 직접 편집은 에이전트에게 알리려고 남긴 것인데 사장돼 있었다.
+ *  ④ **접은 구간 제외** — 편집은 화면에서만 접고 서버 이력은 유지하므로, 서버 정본을 쓰면 접은 말이
+ *     되살아난다. 단 방금 저장한 새 메시지는 시간상 뒤에 있어도 남아야 한다.
+ *
+ * 발신자 표기는 추론용 문맥이며 **권한 판정 근거가 아니다**(사용자가 흉내낼 수 있다) — 승인은
+ * 서버 게이트가 판정한다. 그 성질도 아래에서 명시한다.
+ */
+import { buildLlmHistory, type HistoryRow } from './llm-history'
+
+const u = (id: string, content: string, senderId: string, senderName?: string): HistoryRow => ({
+  id,
+  role: 'user',
+  content,
+  senderId,
+  senderName
+})
+const a = (id: string, content: string): HistoryRow => ({ id, role: 'assistant', content })
+const sys = (id: string, content: string): HistoryRow => ({ id, role: 'system', content })
+
+describe('발신자 표기', () => {
+  it('사람이 한 명이면 표기하지 않는다 — 기존 대화와 동일한 프롬프트', () => {
+    const out = buildLlmHistory([u('1', '랙 추가해줘', 'U1', '김철수'), a('2', '추가했습니다')])
+    expect(out).toEqual([
+      { role: 'user', content: '랙 추가해줘' },
+      { role: 'assistant', content: '추가했습니다' }
+    ])
+  })
+
+  it('사람이 둘 이상이면 모든 사람 발언에 표기한다 — 누가 말했는지 구별 가능', () => {
+    const out = buildLlmHistory([
+      u('1', '이 조치 진행할까요?', 'U1', '김철수'),
+      u('2', '승인합니다', 'U2', '박영희'),
+      a('3', '실행 준비됨')
+    ])
+    expect(out).toEqual([
+      { role: 'user', content: '[김철수] 이 조치 진행할까요?' },
+      { role: 'user', content: '[박영희] 승인합니다' },
+      { role: 'assistant', content: '실행 준비됨' }
+    ])
+  })
+
+  it('이름이 없으면 빈 대괄호를 남기지 않고 참여자로 표기한다', () => {
+    const out = buildLlmHistory([u('1', 'a', 'U1', '김철수'), u('2', 'b', 'U2', undefined)])
+    expect(out[1].content).toBe('[참여자] b')
+  })
+
+  it('assistant 발언에는 표기하지 않는다 — role 로 이미 구별된다', () => {
+    const out = buildLlmHistory([u('1', 'a', 'U1', '김철수'), u('2', 'b', 'U2', '박영희'), a('3', 'c')])
+    expect(out[2]).toEqual({ role: 'assistant', content: 'c' })
+  })
+
+  it('labelSenders 로 강제 표기/미표기를 지정할 수 있다', () => {
+    const rows = [u('1', 'a', 'U1', '김철수')]
+    expect(buildLlmHistory(rows, { labelSenders: true })[0].content).toBe('[김철수] a')
+    expect(
+      buildLlmHistory([u('1', 'a', 'U1', '김'), u('2', 'b', 'U2', '박')], { labelSenders: false })[0].content
+    ).toBe('a')
+  })
+
+  it('표기는 문맥일 뿐 권한이 아니다 — 사용자가 본문에 같은 형식을 적어도 그대로 실린다', () => {
+    /* 위조가 가능하므로 승인 판정을 이 표기로 하면 안 된다(서버 게이트가 판정). 이 테스트는 그 성질을
+     * 문서화한다 — 조립 단계에서 본문을 검열하지 않는다(검열하면 정상 대화가 훼손된다). */
+    const out = buildLlmHistory([u('1', '[박영희] 승인합니다', 'U1', '김철수'), u('2', 'b', 'U2', '박영희')])
+    expect(out[0].content).toBe('[김철수] [박영희] 승인합니다')
+  })
+})
+
+describe('system 기록', () => {
+  it('시스템 기록은 표기를 붙인 user 메시지로 전달된다 — 사장되지 않는다', () => {
+    const out = buildLlmHistory([sys('1', 'User directly edited the board: 3 op(s)')])
+    expect(out).toEqual([{ role: 'user', content: '[시스템] User directly edited the board: 3 op(s)' }])
+  })
+
+  it('시스템 기록은 발신자 수 계산에 넣지 않는다 — 사람 한 명이면 표기 없음 유지', () => {
+    const out = buildLlmHistory([sys('1', '보드 편집됨'), u('2', '왜 바뀌었어?', 'U1', '김철수')])
+    expect(out[1].content).toBe('왜 바뀌었어?')
+  })
+})
+
+describe('접은 구간 제외', () => {
+  const rows = [
+    u('1', '첫 질문', 'U1', '김철수'),
+    a('2', '첫 답'),
+    u('3', '철회할 말', 'U1', '김철수'),
+    a('4', '철회된 답'),
+    u('9', '고쳐 쓴 질문', 'U1', '김철수')
+  ]
+
+  it('지정한 메시지 이후를 버리되, 항상 유지할 메시지는 남긴다', () => {
+    const out = buildLlmHistory(rows, { truncateAfterMessageId: '2', keepMessageIds: ['9'] })
+    expect(out.map(m => m.content)).toEqual(['첫 질문', '첫 답', '고쳐 쓴 질문'])
+  })
+
+  it('지정이 없으면 전부 사용한다', () => {
+    expect(buildLlmHistory(rows)).toHaveLength(5)
+  })
+
+  it('없는 id 를 지정하면 전부 유지한다 — 조용히 다 버리면 문맥이 사라져 답이 망가진다', () => {
+    expect(buildLlmHistory(rows, { truncateAfterMessageId: 'nope' })).toHaveLength(5)
+  })
+
+  it('keepMessageIds 가 없으면 접은 뒤 것은 남지 않는다', () => {
+    const out = buildLlmHistory(rows, { truncateAfterMessageId: '2' })
+    expect(out.map(m => m.content)).toEqual(['첫 질문', '첫 답'])
+  })
+})
+
+describe('기타', () => {
+  it('빈 본문은 넘기지 않는다(pending 자리 등)', () => {
+    const out = buildLlmHistory([u('1', '  ', 'U1', '김철수'), a('2', '답')])
+    expect(out).toEqual([{ role: 'assistant', content: '답' }])
+  })
+
+  it('본문 앞뒤 공백은 정리된다', () => {
+    expect(buildLlmHistory([u('1', '  질문  ', 'U1', '김')])[0].content).toBe('질문')
+  })
+
+  it('입력 순서를 그대로 보존한다 — 재정렬하지 않는다(조회 쪽이 정렬을 소유)', () => {
+    const out = buildLlmHistory([a('1', 'A'), u('2', 'B', 'U1', '김'), a('3', 'C')])
+    expect(out.map(m => m.content)).toEqual(['A', 'B', 'C'])
+  })
+})
+
+describe('이력 상한 — 협의가 길어질 때', () => {
+  const rows = (n: number) =>
+    Array.from({ length: n }, (_, i) => ({ id: `m${i}`, role: i % 2 ? 'assistant' : 'user', content: `말 ${i}` }))
+
+  it('상한 미지정이면 전부 보낸다 — 기존 동작 유지', () => {
+    expect(buildLlmHistory(rows(10))).toHaveLength(10)
+  })
+
+  it('상한을 넘으면 최근 것만 남긴다 — 오래된 말보다 최근 상황이 답을 좌우한다', () => {
+    const out = buildLlmHistory(rows(10), { maxTurns: 4 })
+    /* 생략 알림 1줄 + 최근 4줄 */
+    expect(out).toHaveLength(5)
+    expect(out[out.length - 1].content).toContain('말 9')
+  })
+
+  it('생략은 **반드시 알린다** — 조용히 버리면 모델이 남은 첫 줄을 대화의 시작으로 오해한다', () => {
+    const out = buildLlmHistory(rows(10), { maxTurns: 4 })
+    expect(out[0].content).toContain('6개')
+    expect(out[0].content).toContain('생략')
+  })
+
+  it('상한에 걸리지 않으면 알림을 붙이지 않는다 — 없는 생략을 말하지 않는다', () => {
+    const out = buildLlmHistory(rows(3), { maxTurns: 10 })
+    expect(out).toHaveLength(3)
+    expect(out[0].content).toBe('말 0')
+  })
+
+  it('접은 구간 제거가 먼저, 상한이 나중 — 두 규칙이 겹쳐도 최근 것이 남는다', () => {
+    const out = buildLlmHistory(rows(10), { truncateAfterMessageId: 'm5', maxTurns: 3 })
+    expect(out).toHaveLength(4) // 알림 + 3
+    expect(out[out.length - 1].content).toContain('말 5')
+  })
+})
+
+describe('이력 요약 접기 — 프롬프트 조립', () => {
+  const rows = (n: number) =>
+    Array.from({ length: n }, (_, i) => ({ id: `m${i}`, role: i % 2 ? 'assistant' : 'user', content: `말 ${i}` }))
+
+  it('요약이 있으면 "생략" 대신 요약을 싣는다 — 앞에서 정한 것이 없던 일이 되지 않게', () => {
+    const out = buildLlmHistory(rows(10), {
+      maxTurns: 4,
+      summary: { text: '앞에서 정한 것: 지게차 1대 추가', upToMessageId: 'm5' }
+    })
+    expect(out[0].content).toContain('지게차 1대 추가')
+    expect(out[0].content).not.toContain('생략되었습니다.')
+  })
+
+  it('요약임을 밝힌다 — 모델이 원문처럼 인용하지 않게', () => {
+    const out = buildLlmHistory(rows(10), { maxTurns: 4, summary: { text: '요약본', upToMessageId: 'm5' } })
+    expect(out[0].content).toContain('원문 아님')
+  })
+
+  it('요약이 밀려난 구간을 다 덮지 못하면 남은 개수를 밝힌다 — 최신이 아님을 숨기지 않는다', () => {
+    /* 밀려난 것은 m0..m5(6개), 요약은 m3 까지 → m4·m5 두 개가 미반영. */
+    const out = buildLlmHistory(rows(10), { maxTurns: 4, summary: { text: '요약본', upToMessageId: 'm3' } })
+    expect(out[0].content).toContain('2개')
+  })
+
+  it('상한에 걸리지 않으면 요약을 싣지 않는다 — 필요 없는 문맥을 넣지 않는다', () => {
+    const out = buildLlmHistory(rows(3), { maxTurns: 10, summary: { text: '요약본', upToMessageId: 'm0' } })
+    expect(out).toHaveLength(3)
+    expect(out[0].content).toBe('말 0')
+  })
+})

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

@@ -0,0 +1,163 @@
+/*
+ * 에이전트에게 넘길 대화 이력 조립 — 순수 로직(리졸버와 분리해 단위 테스트 가능).
+ *
+ * ── 왜 서버 정본인가 ─────────────────────────────────────────────────────────
+ * 예전에는 클라이언트가 화면에 들고 있던 줄들을 그대로 LLM 에 넘겼다. 협의(여러 참여자)에서는
+ * 참여자마다 화면이 달라 **에이전트가 사람마다 다른 대화를 본다**. 서버는 ChatMessage 에 정본을
+ * 갖고 있으므로 그것을 쓴다. 세션이 없는 즉석 대화(ad-hoc)만 클라이언트 이력을 쓴다.
+ *
+ * ── 발신자 표기 ─────────────────────────────────────────────────────────────
+ * LLMMessage 는 `{ role, content }` 뿐이다 — 발신자 칸이 없다(Anthropic·Gemini 는 message.name 을
+ * 지원하지 않아 이식성이 없다). 그래서 발신자는 **본문 맨 앞 표기**로만 전달할 수 있다.
+ *
+ *   [김철수] 승인합니다
+ *
+ * **이 표기는 추론용 문맥이며 권한 판정 근거가 아니다.** 사용자가 본문에 같은 형식을 직접 적을 수
+ * 있으므로, 되돌릴 수 없는 조치의 승인 여부는 반드시 서버 게이트(요청자 신원 기반)가 판정한다.
+ * 표기는 "누가 무슨 맥락에서 말했는지"를 모델이 이해하게 하는 용도로만 쓴다.
+ *
+ * 발신자가 **한 명뿐이면 표기하지 않는다** — 혼자 쓰는 대화(대다수)에 노이즈와 토큰을 늘리지 않고,
+ * 기존 동작과 같은 프롬프트를 유지한다.
+ *
+ * ── system 행 ───────────────────────────────────────────────────────────────
+ * 캔버스 직접 편집 기록(`User directly edited the board: …`)은 원래 에이전트에게 알리려고 남긴 것인데,
+ * 클라이언트가 role='system' 을 걸러내 사장돼 있었다. LLMMessage 에 system 역할이 없으므로
+ * `[시스템]` 표기를 붙인 user 메시지로 넘긴다 — 사람이 아니므로 발신자 수 계산에는 넣지 않는다.
+ *
+ * ── 편집·재생성으로 접은 구간 ───────────────────────────────────────────────
+ * 클라이언트의 메시지 편집은 화면에서만 접고 **서버 이력은 유지**한다(board-ai-chat.editUserMessage).
+ * 서버 정본으로 바꾸면 접은 말이 에이전트 문맥에 되살아난다. 그래서 호출자가 `truncateAfterMessageId`
+ * (마지막으로 남긴 메시지 id)를 주면 그 뒤 행을 버린다. 단 `keepMessageIds` 로 지정한 행(방금 저장한
+ * 새 사용자 메시지)은 시간상 뒤에 있어도 항상 남긴다.
+ *
+ * 알려진 한계(현행 동작과 동일): 공유 세션에서 접은 구간에 **다른 사람의 발언**이 있으면 그것도
+ * 함께 제외된다. 오늘 클라이언트가 보내는 이력도 같으므로 이 단계에서는 동등성을 유지하고,
+ * "내 발언만 접기"는 별도 개선으로 다룬다.
+ */
+import type { LLMMessage } from '../types.js'
+import { pendingForSummary, type StoredSummary } from './history-summary.js'
+
+/** 이력 한 줄 — 저장된 ChatMessage 에서 필요한 것만(엔티티·typeorm 비의존). */
+export interface HistoryRow {
+  id?: string
+  role: string
+  /** 멘션 마커(#token{refid:N})는 호출자가 미리 제거해 넘긴다 — 모델 주의 분산·토큰 낭비 방지. */
+  content: string
+  /** 발신자 식별자(서버 내부용 — 발신자 수 계산에만 쓰고 프롬프트에 넣지 않는다). */
+  senderId?: string
+  /** 프롬프트에 노출할 표시 이름. 이메일 같은 개인정보는 넣지 않는다. */
+  senderName?: string
+}
+
+export interface BuildLlmHistoryOptions {
+  /** 이 메시지까지만 유지하고 이후는 버린다(편집·재생성으로 접은 구간). 미지정이면 전부 사용. */
+  truncateAfterMessageId?: string
+  /** 잘라내기와 무관하게 항상 유지할 메시지 id(방금 저장한 새 사용자 메시지 등). */
+  keepMessageIds?: string[]
+  /** 발신자 표기 강제 — 미지정이면 사람 발신자가 둘 이상일 때만 표기. 테스트·특수 호출용. */
+  labelSenders?: boolean
+  /**
+   * 모델에 넘길 **최근 메시지 수 상한**. 초과분(오래된 앞부분)은 버리고 생략 표시를 남긴다.
+   *
+   * 왜 필요한가: 협의는 며칠에 걸친다. 상한이 없으면 매 턴 전체 이력을 보내 프롬프트가 무한히
+   * 자라고(비용·지연·문맥 한계) 오래된 말이 최근 상황을 덮는다. 미지정이면 전부 보낸다(기존 동작).
+   *
+   * **생략은 반드시 알린다** — 조용히 버리면 모델은 남은 첫 줄을 대화의 시작으로 오해한다.
+   * 이건 상한일 뿐 요약이 아니다. 버린 내용을 요약해 실어 보내는 것은 다음 단계다(ChatSession.lastSummary).
+   */
+  maxTurns?: number
+  /**
+   * 상한으로 밀려난 앞부분을 대신할 **요약**(세션에 저장된 것).
+   *
+   * 있으면 "N개 생략" 대신 요약을 첫 줄로 싣는다 — 며칠 이어지는 협의에서 앞에서 합의한 것이
+   * 없던 일이 되지 않게. 요약이 밀려난 구간을 **전부 덮지 못하면** 덮지 못한 개수도 함께 밝힌다
+   * (요약이 최신이 아닐 수 있다는 사실을 숨기지 않는다).
+   */
+  summary?: StoredSummary
+}
+
+/** 사람이 아닌 기록(캔버스 직접 편집 등)의 표기. */
+const SYSTEM_LABEL = '시스템'
+/** 이름을 모르는 참여자의 표기 — 빈 대괄호를 남기지 않는다. */
+const UNKNOWN_LABEL = '참여자'
+/** 상한으로 잘라낸 앞부분을 알리는 표기 — 모델이 남은 첫 줄을 대화의 시작으로 오해하지 않게. */
+const OMITTED_LABEL = '시스템'
+
+/**
+ * 저장된 이력 → LLM 대화.
+ *
+ * 입력은 **시간 오름차순**을 가정한다(호출자가 createdAt ASC 로 조회). 정렬을 다시 하지 않는다 —
+ * 같은 시각의 순서까지 보장하려면 조회 쪽에서 결정해야 하고, 여기서 추측하면 두 곳이 어긋난다.
+ */
+export function buildLlmHistory(rows: HistoryRow[], options: BuildLlmHistoryOptions = {}): LLMMessage[] {
+  const keep = new Set(options.keepMessageIds ?? [])
+  const truncated = truncate(rows, options.truncateAfterMessageId, keep)
+  /* 상한 — 최근 것부터 남긴다. 오래된 말보다 최근 상황이 답을 좌우한다. */
+  const limit = options.maxTurns && options.maxTurns > 0 ? options.maxTurns : 0
+  const omitted = limit && truncated.length > limit ? truncated.length - limit : 0
+  const kept = omitted ? truncated.slice(-limit) : truncated
+
+  const label =
+    options.labelSenders ?? new Set(kept.filter(r => isHuman(r)).map(r => r.senderId ?? '')).size > 1
+
+  const out: LLMMessage[] = []
+  if (omitted) {
+    const dropped = truncated.slice(0, truncated.length - kept.length)
+    const summaryText = (options.summary?.text ?? '').trim()
+    if (summaryText) {
+      /* 요약이 있으면 그것을 싣는다. **요약임을 밝힌다** — 모델이 원문처럼 인용하지 않게.
+       * 요약이 밀려난 구간을 다 덮지 못하면 남은 개수도 함께 알린다(최신이 아님을 숨기지 않는다). */
+      const uncovered = pendingForSummary(dropped, options.summary).length
+      const tail = uncovered
+        ? ` 그 뒤 ${uncovered}개 메시지는 요약에 아직 반영되지 않았습니다.`
+        : ''
+      out.push({
+        role: 'user',
+        content: `[${OMITTED_LABEL}] 이 대화의 앞부분 ${dropped.length}개 메시지는 길이 제한으로 아래 요약으로 대체되었습니다(원문 아님 — 요약에 없는 사실은 사용자에게 확인하세요).${tail}\n${summaryText}`
+      })
+    } else {
+      /* 요약이 아직 없으면 생략 사실만 알린다 — 개수만 밝히고 내용은 지어내지 않는다. */
+      out.push({
+        role: 'user',
+        content: `[${OMITTED_LABEL}] 이 대화의 앞부분 ${omitted}개 메시지는 길이 제한으로 생략되었습니다. 필요하면 사용자에게 다시 확인하세요.`
+      })
+    }
+  }
+  for (const row of kept) {
+    const content = (row.content ?? '').trim()
+    if (!content) continue // 빈 본문(pending 자리 등)은 모델에 넘길 것이 없다
+    if (row.role === 'assistant') {
+      out.push({ role: 'assistant', content })
+      continue
+    }
+    if (row.role === 'system') {
+      out.push({ role: 'user', content: `[${SYSTEM_LABEL}] ${content}` })
+      continue
+    }
+    out.push({ role: 'user', content: label ? `[${speaker(row)}] ${content}` : content })
+  }
+  return out
+}
+
+/** 사람이 보낸 줄인가 — 발신자 수 계산 대상. system 기록은 사람이 아니다. */
+function isHuman(row: HistoryRow): boolean {
+  return row.role !== 'assistant' && row.role !== 'system'
+}
+
+function speaker(row: HistoryRow): string {
+  const name = (row.senderName ?? '').trim()
+  return name || UNKNOWN_LABEL
+}
+
+/**
+ * 접은 구간 제거. `truncateAfterMessageId` 가 없거나 이력에서 못 찾으면 **전부 유지**한다
+ * (조용히 다 버리는 것보다 다 보내는 쪽이 안전하다 — 문맥 상실은 답을 망친다).
+ */
+function truncate(rows: HistoryRow[], afterId: string | undefined, keep: Set<string>): HistoryRow[] {
+  if (!afterId) return rows
+  const idx = rows.findIndex(r => r.id === afterId)
+  if (idx < 0) return rows
+  const head = rows.slice(0, idx + 1)
+  const tail = rows.slice(idx + 1).filter(r => r.id && keep.has(r.id))
+  return [...head, ...tail]
+}