@things-factory/ai-assistant 10.1.6

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@things-factory/ai-assistant",
+  "version": "10.1.6",
+  "main": "dist-server/index.js",
+  "things-factory": true,
+  "author": "heartyoh",
+  "description": "AI 대화의 집 — 세션·메시지·참가자·인박스. 도메인을 모른다. 보드 저작은 @things-factory/board-ai 가 이 위에 선다.",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "@things-factory:registry": "https://registry.npmjs.org"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hatiolab/things-factory.git",
+    "directory": "packages/ai-assistant"
+  },
+  "scripts": {
+    "build": "npm run build:server && npm run build:client",
+    "build:server": "npm run clean:server && npx tsc --p ./tsconfig.json",
+    "copy:files": "copyfiles -e \"./client/**/*.{ts,js,json}\" -u 1 \"./client/**/*\" dist-client",
+    "build:client": "npm run clean:client && npm run copy:files && npx tsc --p ./client/tsconfig.json",
+    "clean:server": "rm -rf dist-server",
+    "clean:client": "rm -rf dist-client",
+    "clean": "npm run clean:server && npm run clean:client"
+  },
+  "dependencies": {
+    "@apollo/client": "^3.13.0",
+    "@operato/graphql": "^10.0.0",
+    "@operato/i18n": "^10.0.0",
+    "@operato/styles": "^10.0.0",
+    "@things-factory/ai-client-base": "^10.1.6",
+    "@things-factory/auth-base": "^10.1.6",
+    "@things-factory/env": "^10.1.3",
+    "@things-factory/shell": "^10.1.4",
+    "dompurify": "^3.0.0",
+    "graphql-scalars": "^1.22.0",
+    "graphql-tag": "^2.12.6",
+    "lit": "^3.1.2",
+    "marked": "^15.0.0"
+  },
+  "browser": "dist-client/index.js",
+  "devDependencies": {
+    "copyfiles": "^2.4.1",
+    "rimraf": "^5.0.0"
+  },
+  "gitHead": "963aeb9ac470be5aea05bb5842a0a92afcab6036"
+}

package/server/index.ts

@@ -0,0 +1,28 @@
+/**
+ * `@things-factory/ai-assistant` — **AI 대화의 집.**
+ *
+ * 세션·메시지·참가자·인박스·구독. 도메인을 모른다: 보드도, 공장도, 자산도.
+ *
+ * ── 왜 board-ai 에서 나왔나 (2026-09-10) ────────────────────────────────────
+ * 시작한 물음은 하나였다. **「왜 board-ai 에 종속되어 있는가.」** 공장에 「지금 몇 대 밀렸나」를
+ * 묻는 화면이 보드 편집 권한을 요구했고, 그 문 뒤에 스물다섯이 있는데 쓰는 것은 하나였다.
+ *
+ * 재 보니 문제는 「공통이냐 아니냐」가 아니었다 — `board-ui` 를 지나 **아홉 개 앱**이 이미 이
+ * 기계를 싣고 있었다. 이미 공통이었고, 이름과 게이트만 보드 편집기의 것이었다.
+ *
+ * ── 자르는 선 ───────────────────────────────────────────────────────────────
+ * 물음 하나로 줄였다: **「이것이 보드가 없는 제품에서도 뜻이 있나.」**
+ *
+ *   여기       세션·메시지·참가자·인박스·구독 인증·앵커
+ *   board-ai   보드 편집기 — assistant · 패치 · 프리팹 · 컴포넌트 트리 · 스타일링
+ *
+ * `assistant.ts`(113KB)는 **안 옮겼다.** 거의 전부 보드 편집이다. 가장 큰 파일이 제자리에 있다는
+ * 뜻이고, 그래서 이 분리는 생각보다 작았다.
+ *
+ * ── 의존은 한쪽이다 ─────────────────────────────────────────────────────────
+ * `board-ai → ai-assistant`. 반대는 없다. 그것을 위해 두 변을 먼저 끊었다 — `ChatSession` 의
+ * 보드 패치 관계와, 리졸버 안에 섞여 있던 보드 op 여섯.
+ *
+ * 설계 정본은 `things-factory/docs/design/ai-modules.md`.
+ */
+export * from './service/index.js'

package/server/service/chat-message/chat-message-broadcast.integration.test.ts

@@ -0,0 +1,73 @@
+/**
+ * chat-message 방송 spine — 독립 통합 테스트 (실서버·WS 없이 자족적).
+ *
+ * 순수 필터(chat-message-broadcast.test.ts)와 달리, 실제 서버가 쓰는 동일한 경로를 구동:
+ *   publishChatMessage → shell pubsub(in-memory) → 토픽 → chatMessageFilter → async iterator.
+ * = resolver 의 subscribe 합성과 동일. WS/Apollo 전송 계층은 patch spine(C2)에서 검증된
+ * generic 인프라라 본 테스트 범위 밖 (수동 스모크로 1회 확인).
+ */
+import { filter, pipe } from 'graphql-yoga'
+import { pubsub } from '@things-factory/shell'
+import { publishChatMessage } from './chat-message-publish'
+import { CHAT_MESSAGE_TOPIC, chatMessageFilter } from './chat-message-broadcast'
+
+const msg = (id: string, role = 'user', content = 'hi') => ({ id, role, content } as any)
+
+/** resolver 의 subscribe 와 동일한 합성으로 구독 이터레이터를 만든다. */
+function subscribe(domainId: string, sessionId: string) {
+  return pipe(pubsub.subscribe(CHAT_MESSAGE_TOPIC), filter(chatMessageFilter(domainId, sessionId)))[
+    Symbol.asyncIterator
+  ]()
+}
+
+/** it.next() 를 timeout 과 race — 안 오면 'TIMEOUT'. */
+function nextOrTimeout(it: AsyncIterator<any>, ms = 400): Promise<any> {
+  return Promise.race([
+    it.next().then(r => r.value),
+    new Promise(resolve => setTimeout(() => resolve('TIMEOUT'), ms))
+  ])
+}
+
+describe('chat-message 방송 통합 (publish → 필터 → 구독)', () => {
+  it('같은 domain+session 구독자가 방송 메시지를 수신', async () => {
+    const it = subscribe('d1', 's1')
+    const p = nextOrTimeout(it)
+    publishChatMessage({ domainId: 'd1', sessionId: 's1', message: msg('m1', 'assistant', 'done') })
+    const value = await p
+    expect(value).not.toBe('TIMEOUT')
+    expect(value.message.id).toBe('m1')
+    expect(value.message.role).toBe('assistant')
+    await it.return?.()
+  })
+
+  it('다른 세션 메시지는 격리 — 내 세션 것만 수신', async () => {
+    const it = subscribe('d1', 's1')
+    const p = nextOrTimeout(it)
+    publishChatMessage({ domainId: 'd1', sessionId: 's2', message: msg('other') }) // 다른 세션 — 필터됨
+    publishChatMessage({ domainId: 'd1', sessionId: 's1', message: msg('mine') }) // 내 세션
+    const value = await p
+    expect(value).not.toBe('TIMEOUT')
+    expect(value.message.id).toBe('mine')
+    await it.return?.()
+  })
+
+  it('다른 domain 메시지는 격리 (도메인 보안)', async () => {
+    const it = subscribe('d1', 's1')
+    const p = nextOrTimeout(it)
+    publishChatMessage({ domainId: 'd2', sessionId: 's1', message: msg('foreign') }) // 다른 도메인 — 필터됨
+    publishChatMessage({ domainId: 'd1', sessionId: 's1', message: msg('local') })
+    const value = await p
+    expect(value).not.toBe('TIMEOUT')
+    expect(value.message.id).toBe('local')
+    await it.return?.()
+  })
+
+  it('sessionId 없는 publish 는 방송 안 함 (구독자 미수신)', async () => {
+    const it = subscribe('d1', 's1')
+    const p = nextOrTimeout(it, 250)
+    publishChatMessage({ domainId: 'd1', sessionId: undefined, message: msg('nope') })
+    const value = await p
+    expect(value).toBe('TIMEOUT') // 아무것도 안 옴
+    await it.return?.()
+  })
+})

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

@@ -0,0 +1,40 @@
+/**
+ * chat-message 브로드캐스트 — 단위 테스트 (순수 로직).
+ *  - chatMessageFilter: domain+session 격리(보안 핵심) — 일치만 통과, 불일치/널/session없음 차단.
+ * (publishChatMessage / 구독 resolver 는 pubsub·graphql-ws 통합 영역 — 별도 검증.)
+ */
+import { chatMessageFilter, CHAT_MESSAGE_TOPIC } from './chat-message-broadcast'
+import type { ChatMessagePayload } from './chat-message-broadcast'
+
+const payload = (domainId: string, sessionId?: string): ChatMessagePayload => ({
+  domainId,
+  sessionId,
+  message: { id: 'm1' } as any
+})
+
+describe('chatMessageFilter (domain+session 격리)', () => {
+  it('domain+session 모두 일치 → 통과', () => {
+    expect(chatMessageFilter('d1', 's1')(payload('d1', 's1'))).toBe(true)
+  })
+
+  it('domain 불일치 → 차단 (도메인 격리)', () => {
+    expect(chatMessageFilter('d1', 's1')(payload('d2', 's1'))).toBe(false)
+  })
+
+  it('session 불일치 → 차단 (다른 세션 메시지 누수 방지)', () => {
+    expect(chatMessageFilter('d1', 's1')(payload('d1', 's2'))).toBe(false)
+  })
+
+  it('sessionId 없는 페이로드 → 차단', () => {
+    expect(chatMessageFilter('d1', 's1')(payload('d1', undefined))).toBe(false)
+  })
+
+  it('null/undefined 페이로드 안전 → 차단', () => {
+    expect(chatMessageFilter('d1', 's1')(null as any)).toBe(false)
+    expect(chatMessageFilter('d1', 's1')(undefined as any)).toBe(false)
+  })
+
+  it('토픽 상수', () => {
+    expect(CHAT_MESSAGE_TOPIC).toBe('board-ai-chat-message')
+  })
+})

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

@@ -0,0 +1,27 @@
+/*
+ * chat-message 브로드캐스트 — 순수 로직 (토픽/페이로드/필터). 데코레이터·pubsub import 없음
+ * → 단위테스트 가능. 데코레이터 resolver(chat-message-subscription.ts)와 pubsub 의존
+ * publishChatMessage 는 별도.
+ *
+ * patch spine(board-patch-broadcast.ts)과 동일 컨벤션. 다만 채팅 메시지는 board 가 아니라
+ * **ChatSession 단위**로 묶이므로 필터 키가 sessionId (+ domain 격리).
+ */
+import type { ChatMessage } from './chat-message.js' // type-only — 런타임 import 아님
+
+/** chat-message 브로드캐스트 토픽. */
+export const CHAT_MESSAGE_TOPIC = 'board-ai-chat-message'
+
+/** 방송 페이로드 — 구독 필터(domain+session)용 메타 + ChatMessage 본체. */
+export interface ChatMessagePayload {
+  domainId: string
+  sessionId?: string
+  message: ChatMessage
+}
+
+/**
+ * 같은 domain + session 구독자에게만 통과시키는 필터 (도메인 격리 = 보안 핵심).
+ */
+export function chatMessageFilter(domainId: string, sessionId: string) {
+  return (payload: ChatMessagePayload): boolean =>
+    !!payload && payload.domainId === domainId && payload.sessionId === sessionId
+}

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

@@ -0,0 +1,22 @@
+/*
+ * chat-message 방송 publisher — pubsub 의존, 데코레이터 없음.
+ *
+ * 데코레이터 resolver(chat-message-subscription.ts)와 분리한 이유: babel-jest 가 파라미터
+ * 데코레이터(@Root/@Arg)를 파싱 못 해 그 파일을 테스트에서 import 할 수 없다. 이 모듈은
+ * 데코레이터가 없어 통합 테스트가 실제 publish→방송 경로를 직접 구동할 수 있다.
+ */
+import { pubsub } from '@things-factory/shell'
+import { CHAT_MESSAGE_TOPIC, type ChatMessagePayload } from './chat-message-broadcast.js'
+
+/**
+ * ChatMessage 영속 직후 호출 — 같은 세션 구독자에게 방송.
+ * sessionId 없으면 skip. pubsub 미가용/실패해도 본 흐름(영속 완료)을 막지 않는다.
+ */
+export function publishChatMessage(payload: ChatMessagePayload): void {
+  if (!payload.sessionId) return
+  try {
+    pubsub.publish(CHAT_MESSAGE_TOPIC, payload)
+  } catch {
+    /* 방송 생략 — 영속은 이미 끝남 */
+  }
+}

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

@@ -0,0 +1,45 @@
+/*
+ * ChatMessageSubscription — 그룹챗 메시지 실시간 방송.
+ *
+ * 클래스 이름이 `BoardChatMessageSubscription` 이었다. 전선 이름(`chatMessageActivity`)은 처음부터
+ * 중립이었고 클래스 이름만 보드였다 — 중립 패키지로 옮기면서 고쳤다(2026-09-10). 전선이 안 바뀌므로
+ * 소비처는 그대로다.
+ *
+ * ChatMessage(사용자 / AI / system) 가 영속될 때마다 같은 세션 구독자에게 방송 →
+ * 그룹챗의 척추. 클라이언트(board-ai-chat)가 구독해 원격 메시지를 transcript 에 append.
+ * 자기 발신 에코는 클라이언트가 message.id 로 dedup (mutation 응답으로 이미 렌더).
+ *
+ * patch spine(board-patch-subscription.ts)과 동일 패턴 — PubSub + graphql-ws, domain 격리.
+ * 차이: 필터 키가 board 가 아닌 sessionId (채팅은 ChatSession 단위).
+ * 순수 로직(토픽/필터)은 chat-message-broadcast.ts (테스트 가능). 여기엔 pubsub 의존만.
+ */
+import { Resolver, Subscription, Root, Arg } from 'type-graphql'
+import { filter, pipe } from 'graphql-yoga'
+import { pubsub } from '@things-factory/shell'
+import { ChatMessage } from './chat-message.js'
+import { CHAT_MESSAGE_TOPIC, chatMessageFilter, type ChatMessagePayload } from './chat-message-broadcast.js'
+import { assertDomainSubscribeAllowed } from '../subscribe-auth.js'
+
+// publishChatMessage 는 데코레이터 없는 chat-message-publish.ts 에 분리 (테스트 import 가능).
+export { publishChatMessage } from './chat-message-publish.js'
+export { CHAT_MESSAGE_TOPIC, chatMessageFilter } from './chat-message-broadcast.js'
+export type { ChatMessagePayload } from './chat-message-broadcast.js'
+
+@Resolver(ChatMessage)
+export class ChatMessageSubscription {
+  @Subscription({
+    description:
+      'Subscribes to chat messages (user / assistant / system) of a session for real-time group chat.',
+    subscribe: async ({ args, context }) => {
+      const { domain, user } = context.state
+      const { sessionId } = args
+
+      await assertDomainSubscribeAllowed(domain, user, (d, u) => process.superUserGranted(d, u))
+
+      return pipe(pubsub.subscribe(CHAT_MESSAGE_TOPIC), filter(chatMessageFilter(domain.id, sessionId)))
+    }
+  })
+  chatMessageActivity(@Root() payload: ChatMessagePayload, @Arg('sessionId') sessionId: string): ChatMessage {
+    return payload.message
+  }
+}

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

@@ -0,0 +1,195 @@
+/**
+ * ChatMessage — ChatSession 의 한 메시지.
+ *
+ * role: 'user' | 'assistant' | 'system'
+ * 'system' 은 사용자 직접 편집/import 진행 등 시스템이 자동 생성하는 컨텍스트 메시지.
+ *
+ * relatedPatchId / relatedImportSessionId 로 메시지가 트리거한 패치·임포트와 연결.
+ */
+import {
+  Column,
+  CreateDateColumn,
+  DeleteDateColumn,
+  Entity,
+  Index,
+  ManyToOne,
+  PrimaryGeneratedColumn,
+  RelationId,
+  UpdateDateColumn
+} from 'typeorm'
+import { Field, ID, ObjectType } from 'type-graphql'
+import { GraphQLJSON } from 'graphql-scalars'
+
+import { User } from '@things-factory/auth-base'
+import { config } from '@things-factory/env'
+
+import { ChatSession } from '../chat-session/chat-session.js'
+
+const ORMCONFIG = config.get('ormconfig', {})
+const DATABASE_TYPE = ORMCONFIG.type
+
+@Entity()
+@Index('ix_chat_message_1', (message: ChatMessage) => [message.session, message.createdAt])
+@ObjectType({ description: 'A single chat message in a ChatSession.' })
+export class ChatMessage {
+  @PrimaryGeneratedColumn('uuid')
+  @Field(type => ID, { nullable: true })
+  readonly id?: string
+
+  @ManyToOne(type => ChatSession, session => session.messages, { onDelete: 'CASCADE' })
+  session?: ChatSession
+
+  @RelationId((message: ChatMessage) => message.session)
+  sessionId?: string
+
+  @Column({ type: 'varchar', length: 16 })
+  @Field({ description: "'user' | 'assistant' | 'system'" })
+  role!: string
+
+  @Column({
+    type:
+      DATABASE_TYPE == 'mysql' || DATABASE_TYPE == 'mariadb'
+        ? 'longtext'
+        : DATABASE_TYPE == 'oracle'
+          ? 'clob'
+          : DATABASE_TYPE == 'mssql'
+            ? 'nvarchar'
+            : 'text',
+    length: DATABASE_TYPE == 'mssql' ? 'MAX' : undefined
+  })
+  @Field({ description: 'Message content' })
+  content!: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'PatchEntry.id this message triggered (if any).' })
+  relatedPatchId?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'ImportSession.id this message triggered (if any).' })
+  relatedImportSessionId?: string
+
+  /**
+   * AI 가 응답을 만드는 동안 호출한 도구 trace — JSON-stringified.
+   *
+   * 컬럼은 string (PatchEntry.ops 와 동일 패턴), GraphQL 노출은 toolUsagesJson getter
+   * 로 parse 된 객체. UI 의 fold-able 박스 ("AI 가 이런 도구를 사용했습니다") 가
+   * 페이지 reload / loadHistory 후에도 살아있도록 영속.
+   *
+   * 형태: ToolUsage[] (assistant.ts 의 시간순 trace, summarizeToolResult 로 압축).
+   * null 이면 도구 호출 없었던 메시지 (text-only 응답).
+   */
+  @Column({
+    type:
+      DATABASE_TYPE == 'mysql' || DATABASE_TYPE == 'mariadb'
+        ? 'longtext'
+        : DATABASE_TYPE == 'oracle'
+          ? 'clob'
+          : DATABASE_TYPE == 'mssql'
+            ? 'nvarchar'
+            : 'text',
+    length: DATABASE_TYPE == 'mssql' ? 'MAX' : undefined,
+    nullable: true
+  })
+  toolUsages?: string
+
+  /** GraphQL 노출용 — JSON 배열로 parse. */
+  @Field(() => GraphQLJSON, {
+    nullable: true,
+    description:
+      'Tool usage trace — array of {name, arguments, result, kind}. Only on assistant messages.'
+  })
+  get toolUsagesJson(): any {
+    if (!this.toolUsages) return null
+    try {
+      return JSON.parse(this.toolUsages)
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * 접지 경고 — 이 답이 언급했으나 근거(프롬프트·보드 문맥·이력·도구 결과)에 없던 식별자 목록.
+   *
+   * **왜 영속하는가**: 도크의 협의는 여러 사람이 며칠에 걸쳐 읽는다. 경고가 그 자리에서만
+   * 보이고 새로 고치면 사라지면, 나중에 읽는 사람은 검증되지 않은 문장을 검증된 것으로 읽는다.
+   * 다시 계산할 수도 없다 — 근거였던 도구 결과 원문은 남지 않고 압축본만 남기 때문이다.
+   *
+   * 형태: 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' → 보낸 사용자
+   *   - role='assistant' → 그 응답을 트리거한 사용자 (직전 user 메시지의 작성자)
+   *   - role='system' → 시스템 액션을 일으킨 사용자 (예: 직접 편집한 사용자)
+   *
+   * nullable — legacy 메시지 (이 필드 추가 이전에 작성) 는 null. 또한 ad-hoc 모드 / 시스템
+   * 자동 메시지 중 사용자 컨텍스트가 없는 경우도 null 가능.
+   */
+  @ManyToOne(type => User, { nullable: true })
+  @Field(type => User, { nullable: true, description: 'User who triggered this message.' })
+  creator?: User
+
+  @RelationId((message: ChatMessage) => message.creator)
+  creatorId?: string
+
+  @ManyToOne(type => User, { nullable: true })
+  @Field(type => User, { nullable: true, description: 'Last user to update this message (for future edit support).' })
+  updater?: User
+
+  @RelationId((message: ChatMessage) => message.updater)
+  updaterId?: string
+
+  /**
+   * 부모 메시지 — 이 메시지가 "응답하는 대상" / "이어가는 메시지" 의 id.
+   *
+   * 의미 (role 별):
+   *   - 'user' → 직전 in-session 메시지 (보통 assistant 또는 system). 첫 turn 은 null.
+   *   - 'assistant' → 이 응답이 답하는 user 메시지. (regenerate 로 같은 user 메시지를 부모로
+   *     하는 형제 assistant 메시지가 생기면 자연스럽게 branching tree 가 됨)
+   *   - 'system' → 직전 in-session 메시지 (timeline 연속성 유지).
+   *
+   * 이 한 컬럼으로 향후 어떤 흐름이든 표현 가능 — linear chain / branching (regenerate) /
+   * tree (replies-to-specific-message) 등. UI/쿼리는 점진 도입.
+   *
+   * onDelete: 'SET NULL' — 부모 메시지가 삭제돼도 child 는 남되 dangling 마킹.
+   */
+  @ManyToOne(type => ChatMessage, { nullable: true, onDelete: 'SET NULL' })
+  parentMessage?: ChatMessage
+
+  @RelationId((message: ChatMessage) => message.parentMessage)
+  @Field({
+    nullable: true,
+    description:
+      'Id of the message this one is in-response-to / continues. Enables linear / branching / tree structures.'
+  })
+  parentMessageId?: string
+
+  @CreateDateColumn()
+  @Field({ nullable: true, description: 'Creation timestamp.' })
+  createdAt?: Date
+
+  @UpdateDateColumn()
+  @Field({ nullable: true, description: 'Last update timestamp (relevant once message editing is supported).' })
+  updatedAt?: Date
+
+  @DeleteDateColumn()
+  @Field({ nullable: true, description: 'Soft delete timestamp.' })
+  deletedAt?: Date
+}

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,77 @@
+/*
+ * 요약 접기 오케스트레이션 — **판정과 조립은 여기, 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 {
+  /** 시간 오름차순 이력. 기본은 **전체**이고, `rowsStartAfterSummary` 면 요약 뒤부터의 구간이다. */
+  rows: HistoryRow[]
+  /** 세션에 저장된 요약 상태. */
+  stored?: StoredSummary
+  /**
+   * `rows` 가 **이미 요약 뒤부터** 잘려 온 구간인가.
+   *
+   * ── 왜 이 플래그가 필요한가 ─────────────────────────────────────────────────
+   * 호출부가 DB 에서 워터마크(`stored.upToMessageId`) 뒤부터만 읽으면(대화가 길어져도 상수 시간),
+   * 여기서 `pendingForSummary` 로 **또 자를 것이 없다.** 그런데 그 함수는 「id 를 못 찾으면 전부
+   * 미반영으로 본다」는 안전 규칙을 갖고 있어서, 창으로 읽은 경우에도 우연히 맞는 답을 낸다.
+   *
+   * 우연에 기대지 않는다. 그 규칙은 **행이 지워졌을 때의 안전망**이고, 여기서 필요한 것은 「이미
+   * 잘랐다」는 사실이다. 둘을 같은 분기로 두면, 나중에 그 안전망을 고치는 사람이 이 경로를 조용히
+   * 망가뜨린다(요약이 앞부분을 두 번 담거나 빠뜨린다).
+   */
+  rowsStartAfterSummary?: boolean
+  /** 프롬프트 상한(이 밖으로 밀려난 것이 요약 대상). */
+  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 = input.rowsStartAfterSummary ? dropped : 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) }
+}