@things-factory/ai-assistant 10.1.6

package/server/service/chat-session-resolver.ts

@@ -0,0 +1,644 @@
+/**
+ * ChatSession lifecycle resolver — start/get/recordDirectPatch/revertPatch + 메시지·패치 페이징 query.
+ *
+ * 핵심: `recordDirectPatch` — 사용자가 모델러에서 직접 편집 시 클라이언트가 호출.
+ * 이게 PatchEntry(source:'user-direct') + system 메시지 자동 추가 → AI 가 모든 변경을 인지.
+ */
+import { Resolver, Query, Mutation, Arg, Ctx, Directive, Int, ObjectType, Field, ID } from 'type-graphql'
+import { GraphQLJSON } from 'graphql-scalars'
+import { User } from '@things-factory/auth-base'
+import { buildDomainUsersQueryBuilder } from '@things-factory/auth-base/dist-server/utils/get-domain-users.js'
+
+import { getRepository } from '@things-factory/shell'
+import { In } from 'typeorm'
+
+import { ChatSession } from './chat-session/chat-session.js'
+import { anchorColumns, anchorWhere } from './chat-session/session-anchor.js'
+import { buildInbox, applyHidden, activityPatch, searchInbox, INBOX_SCAN_CAP } from './chat-session/session-inbox.js'
+import { publishSessionActivity } from './chat-session/session-activity-publish.js'
+import { ChatMessage } from './chat-message/chat-message.js'
+import { ChatSessionParticipant } from './chat-session-participant/chat-session-participant.js'
+import { publishChatMessage } from './chat-message/chat-message-publish.js'
+
+@ObjectType({
+  description:
+    'Session list entry for the inbox — a session plus this viewer\'s unread state. Ordered by recent activity so a user can find where to go back to.'
+})
+class ChatSessionInboxEntry {
+  @Field(type => ID, { nullable: true, description: 'Session id.' })
+  id?: string
+
+  @Field({ nullable: true, description: 'User-given session name (tab label).' })
+  name?: string
+
+  @Field({ nullable: true, description: "What the session is anchored to: 'board' | 'space' | 'instance' | 'none'." })
+  anchorType?: string
+
+  @Field({ nullable: true, description: 'Id of the anchored target.' })
+  anchorId?: string
+
+  @Field({ nullable: true, description: 'Connected board id (board-anchored sessions).' })
+  boardId?: string
+
+  @Field({ nullable: true, description: 'Timestamp of the last message (list ordering / unread comparison).' })
+  lastMessageAt?: Date
+
+  @Field({ nullable: true, description: 'Short preview of the last message.' })
+  lastMessagePreview?: string
+
+  @Field({ nullable: true, description: 'Session creation timestamp.' })
+  createdAt?: Date
+
+  @Field({ description: 'Whether this viewer has unread activity in the session.' })
+  unread!: boolean
+
+  @Field({ description: 'Whether this viewer is a participant of the session (non-participants get no unread state).' })
+  participant!: boolean
+
+  /* 삭제는 되돌릴 수 없으므로 **만든 사람**만 한다 — 클라이언트가 버튼을 보일지 판단하는 근거.
+   * (권한 판정은 서버가 다시 한다. 이 값은 UI 힌트일 뿐이다.) */
+  @Field({ description: 'Whether this viewer created the session — only the creator may delete it.' })
+  mine!: boolean
+
+  /* 숨김은 나에게만 적용되고 되돌릴 수 있다 — 필터를 켠 사용자가 무엇이 숨겨진 것인지 알아야 한다. */
+  @Field({ nullable: true, description: 'Whether this viewer hid the session from their own list (only returned when showHidden is on).' })
+  hidden?: boolean
+}
+
+@Resolver()
+export class ChatSessionResolver {
+  @Query(() => ChatSession, { nullable: true, description: 'Get AI chat session by id.' })
+  @Directive('@privilege(category: "ai-assistant", privilege: "query", legacy: "board-ai")')
+  async chatSession(
+    @Arg('id') id: string,
+    @Ctx() context: ResolverContext
+  ): Promise<ChatSession | null> {
+    const { domain } = context.state
+    return (await getRepository(ChatSession).findOneBy({ id, domain: { id: domain.id } })) ?? null
+  }
+
+  @Query(() => [ChatSession], {
+    description:
+      'List AI chat sessions anchored to a target (oldest first). Anchor decides the nature and the history boundary of the conversation: board = authoring, space = the site and the twins running there. Board anchor also matches legacy rows that only have boardId.'
+  })
+  @Directive('@privilege(category: "ai-assistant", privilege: "query", legacy: "board-ai")')
+  async chatSessionsByAnchor(
+    @Arg('anchorType') anchorType: string,
+    @Arg('anchorId') anchorId: string,
+    @Ctx() context: ResolverContext
+  ): Promise<ChatSession[]> {
+    const { domain } = context.state
+    return await getRepository(ChatSession).find({
+      where: anchorWhere(domain.id, anchorType, anchorId),
+      order: { createdAt: 'ASC' }
+    })
+  }
+
+  /**
+   * 받은편지함 — 앵커의 세션 목록 + 내 안 읽음 상태. 최근 활동순.
+   * 집계 쿼리를 쓰지 않는다: 세션의 비정규화된 lastMessageAt 과 내 참여자 lastReadAt 을 **값 비교**한다
+   * (5개 DB 드라이버 지원 때문에 group by/MAX 를 목록 경로에 두지 않는다).
+   */
+  @Query(() => [ChatSessionInboxEntry], {
+    description:
+      "List sessions anchored to a target with this viewer's unread state, most recent activity first. Supports free-text search over name and last preview, a mine-only filter, hidden inclusion, and paging. Uses the denormalized last-activity timestamp compared against the viewer's read point — no per-session aggregation."
+  })
+  @Directive('@privilege(category: "ai-assistant", privilege: "query", legacy: "board-ai")')
+  async chatSessionInbox(
+    @Arg('anchorType') anchorType: string,
+    @Arg('anchorId') anchorId: string,
+    @Ctx() context: ResolverContext,
+    /* 숨긴 대화 보기 — 숨김이 한 번 넣으면 못 꺼내는 함정이 되지 않도록 필터를 준다. */
+    @Arg('showHidden', { nullable: true }) showHidden?: boolean,
+    /* 대량 목록 대응 — 검색·소유 필터·페이지. 목록 UI 는 처음부터 이걸 갖고 있어야 한다. */
+    @Arg('search', { nullable: true }) search?: string,
+    @Arg('mineOnly', { nullable: true }) mineOnly?: boolean,
+    @Arg('limit', () => Int, { nullable: true }) limit?: number,
+    @Arg('offset', () => Int, { nullable: true }) offset?: number
+  ): Promise<ChatSessionInboxEntry[]> {
+    const filtered = await this._inboxFiltered(anchorType, anchorId, context, { showHidden, search, mineOnly })
+    const from = Math.max(0, offset ?? 0)
+    const size = Math.min(Math.max(1, limit ?? 50), 200)
+    return filtered.slice(from, from + size) as any
+  }
+
+  /**
+   * 필터를 통과한 **전체 개수** — "더 보기" 가 남았는지, 검색 결과가 몇 건인지.
+   *
+   * 목록과 같은 요청에 담아 가져가므로 왕복은 늘지 않는다. 개수를 모르면 사용자는 목록의 끝이
+   * 페이지의 끝인지 자료의 끝인지 구별할 수 없다.
+   */
+  @Query(() => Int, {
+    description:
+      'Total number of sessions matching the same filters as chatSessionInbox (before paging). Request it alongside the list so the UI can tell "end of page" from "end of data".'
+  })
+  @Directive('@privilege(category: "ai-assistant", privilege: "query", legacy: "board-ai")')
+  async chatSessionInboxTotal(
+    @Arg('anchorType') anchorType: string,
+    @Arg('anchorId') anchorId: string,
+    @Ctx() context: ResolverContext,
+    @Arg('showHidden', { nullable: true }) showHidden?: boolean,
+    @Arg('search', { nullable: true }) search?: string,
+    @Arg('mineOnly', { nullable: true }) mineOnly?: boolean
+  ): Promise<number> {
+    return (await this._inboxFiltered(anchorType, anchorId, context, { showHidden, search, mineOnly })).length
+  }
+
+  /** 필터 적용(페이지 전) — 목록·개수가 **같은 규칙**을 쓰도록 한 곳에 둔다(어긋나면 "더 보기" 가 거짓말이 된다). */
+  private async _inboxFiltered(
+    anchorType: string,
+    anchorId: string,
+    context: ResolverContext,
+    opts: { showHidden?: boolean; search?: string; mineOnly?: boolean }
+  ): Promise<ChatSessionInboxEntry[]> {
+    const all = await this._inboxEntries(anchorType, anchorId, context)
+    let entries = opts.showHidden ? all : all.filter(e => !e.hidden)
+    if (opts.mineOnly) entries = entries.filter(e => (e as any).mine)
+    return searchInbox(entries as any, opts.search) as any
+  }
+
+  /**
+   * 내가 숨긴 대화 수 — 필터에 "몇 개가 접혀 있는지" 를 보여주기 위한 값.
+   *
+   * 숨긴 것이 몇 개인지 모르면 필터를 눌러 볼 이유가 생기지 않는다(숨긴 사실 자체를 잊는다).
+   * 목록 조회와 **같은 요청**에 담아 가져갈 수 있으므로 왕복은 늘지 않는다.
+   */
+  @Query(() => Int, {
+    description:
+      "Number of sessions on this anchor that the caller has hidden and that have had no activity since. Meant to be requested alongside chatSessionInbox in the same operation so the filter can say how many are folded away."
+  })
+  @Directive('@privilege(category: "ai-assistant", privilege: "query", legacy: "board-ai")')
+  async hiddenSessionCount(
+    @Arg('anchorType') anchorType: string,
+    @Arg('anchorId') anchorId: string,
+    @Ctx() context: ResolverContext
+  ): Promise<number> {
+    const all = await this._inboxEntries(anchorType, anchorId, context)
+    return all.filter(e => e.hidden).length
+  }
+
+  /** 목록 조립 — 숨김 표시까지 붙인 **전체**. 목록·개수 두 진입점이 같은 규칙을 쓰도록 한 곳에 둔다. */
+  private async _inboxEntries(
+    anchorType: string,
+    anchorId: string,
+    context: ResolverContext
+  ): Promise<ChatSessionInboxEntry[]> {
+    const { domain, user } = context.state
+    /* 조회 상한 — 한 앵커의 대화가 아무리 늘어도 한 번에 이만큼만 훑는다. 최근 활동순으로 자른다
+     * (오래된 대화가 잘리는 것이 최근 대화가 잘리는 것보다 낫다). 정렬·검색·페이지는 순수 로직이 한다. */
+    const sessions = await getRepository(ChatSession).find({
+      where: anchorWhere(domain.id, anchorType, anchorId),
+      order: { lastMessageAt: 'DESC' },
+      take: INBOX_SCAN_CAP
+    })
+    if (sessions.length === 0) return []
+    const rows = await getRepository(ChatSessionParticipant).find({
+      where: { domain: { id: domain.id } as any, user: { id: user.id } as any, session: { id: In(sessions.map(s => s.id!)) } as any }
+    })
+    /* 'viewer' 는 대화에 낀 사람이 아니다 — 숨김을 기록하려고 만든 행이므로 읽음·안 읽음 판정에서 뺀다.
+     * (참여자가 아닌 사람에게 남의 협의 배지를 띄우지 않는다.) */
+    const participations = rows.filter(r => r.role !== 'viewer')
+    const hiddenAt = new Map(rows.map(r => [(r as any).sessionId as string, r.hiddenAt]))
+    /* 내가 만든 대화인지 표시 — 삭제 버튼을 보일지 결정하는 UI 힌트(권한은 서버가 다시 판정한다). */
+    const createdByMe = new Set(sessions.filter(s => (s as any).creatorId === user?.id).map(s => s.id))
+    const entries = buildInbox(sessions as any, participations as any).map(entry => ({
+      ...entry,
+      mine: createdByMe.has(entry.id)
+    }))
+    /* showHidden=true 로 불러 **전체**를 얻는다 — 숨김 여부 판정을 두 곳에 복제하지 않기 위함. */
+    return applyHidden(entries as any, hiddenAt, true) as any
+  }
+
+  /**
+   * 세션 삭제 — **만든 사람만.**
+   *
+   * 협의는 여럿의 기록이고 삭제는 화면에서 되돌릴 수 없다. 그래서 권한을 좁힌다(이름 변경은 되돌릴 수
+   * 있어서 누구나 할 수 있는 것과 대비). 권한이 없는 사람에게는 `hideAISession`(내 목록에서만 숨김)이
+   * 있다 — 남의 기록을 지우지 않고 자기 목록을 정리하는 길.
+   *
+   * 소프트 삭제(deletedAt)다 — 메시지·패치는 세션을 통해서만 도달하므로 함께 사라지고, 잘못 지운 경우
+   * 데이터로는 남아 있다. 다른 참여자 목록에서도 사라져야 하므로 meta 활동으로 방송한다.
+   */
+  @Mutation(() => Boolean, {
+    description:
+      'Delete a chat session — creator only, since a shared deliberation cannot be un-deleted from the UI. Participants who are not the creator can hide it from their own list instead (hideAISession). Soft delete; broadcast as meta activity so every list drops it.'
+  })
+  @Directive('@privilege(category: "ai-assistant", privilege: "mutation", legacy: "board-ai")')
+  async deleteAISession(@Arg('sessionId') sessionId: string, @Ctx() context: ResolverContext): Promise<boolean> {
+    const { domain, user } = context.state
+    const repo = getRepository(ChatSession)
+    const session = await repo.findOneBy({ id: sessionId, domain: { id: domain.id } as any })
+    if (!session) return false
+    if (!user?.id || (session as any).creatorId !== user.id) {
+      /* 조용한 무동작이 아니라 명시 실패 — 지워진 줄 알고 넘어가면 안 된다. */
+      throw new Error('Only the user who created this session may delete it. Hide it from your own list instead.')
+    }
+    await repo.softDelete(sessionId)
+    publishSessionActivity({
+      domainId: domain.id,
+      sessionId,
+      kind: 'meta',
+      anchorType: (session as any).anchorType,
+      anchorId: (session as any).anchorId,
+      actorId: user?.id
+    })
+    return true
+  }
+
+  /**
+   * 내 목록에서 숨기기·되돌리기 — **나에게만** 적용된다(대화·다른 참여자 목록은 그대로).
+   *
+   * 참여자가 아니어도 숨길 수 있어야 한다 — 목록에는 같은 공간의 남의 협의도 보이고, 그것을 정리하는
+   * 것은 남에게 아무 영향이 없다. 그 경우 'viewer' 역할로 기록만 남긴다(참여자 명부·배지에는 들지 않는다).
+   */
+  @Mutation(() => Boolean, {
+    description:
+      'Hide (or unhide) a session from the calling user\'s own list. Per-user and reversible — the session and other participants are unaffected. Activity newer than the hide makes it reappear; the inbox filter (showHidden) reveals hidden ones.'
+  })
+  @Directive('@privilege(category: "ai-assistant", privilege: "mutation", legacy: "board-ai")')
+  async hideAISession(
+    @Arg('sessionId') sessionId: string,
+    @Ctx() context: ResolverContext,
+    @Arg('hidden', { nullable: true }) hidden?: boolean
+  ): Promise<boolean> {
+    const { domain, user } = context.state
+    if (!user?.id) return false
+    const session = await getRepository(ChatSession).findOneBy({ id: sessionId, domain: { id: domain.id } as any })
+    if (!session) return false
+    const repo = getRepository(ChatSessionParticipant)
+    const existing = await repo.findOne({
+      where: { domain: { id: domain.id } as any, session: { id: sessionId } as any, user: { id: user.id } as any }
+    })
+    const hiddenAt = hidden === false ? null : new Date()
+    if (existing) {
+      await repo.update(existing.id!, { hiddenAt, updater: user } as any)
+    } else {
+      if (hidden === false) return true // 숨긴 적이 없으면 되돌릴 것도 없다
+      await repo.save({
+        domain: { id: domain.id } as any,
+        session: { id: sessionId } as any,
+        user: { id: user.id } as any,
+        role: 'viewer', // 대화에 낀 것이 아니라 숨김만 기록한다
+        hiddenAt,
+        creator: user,
+        updater: user
+      } as any)
+    }
+    return true
+  }
+
+  /**
+   * 세션 이름 변경 — **참여자 누구나** 할 수 있다.
+   *
+   * 왜 소유자 전용이 아닌가: 이름은 대화의 주제표이고 협의는 여럿이 한다. 논의가 흘러 주제가 달라졌는데
+   * 만든 사람만 고칠 수 있으면 그 사람이 없을 때 목록이 계속 어긋난다. 되돌릴 수 있는 변경이고 대화
+   * 내용에 영향이 없으므로 권한을 좁힐 이유가 없다(되돌릴 수 없는 것만 좁힌다).
+   *
+   * 변경은 **meta 활동**으로 방송한다 — 모든 참여자 목록에 즉시 반영되지만 안 읽음 배지는 올리지 않는다
+   * (이름 변경을 "새 소식" 으로 알리면 소음이다).
+   */
+  @Mutation(() => Boolean, {
+    description:
+      'Rename a chat session. Any participant may rename it — the name is the topic label of a shared deliberation and the change is reversible. Broadcast as meta activity so every participant sees it without raising unread badges.'
+  })
+  @Directive('@privilege(category: "ai-assistant", privilege: "mutation", legacy: "board-ai")')
+  async renameAISession(
+    @Arg('sessionId') sessionId: string,
+    @Arg('name') name: string,
+    @Ctx() context: ResolverContext
+  ): Promise<boolean> {
+    const { domain, user } = context.state
+    const trimmed = (name ?? '').trim().slice(0, 200)
+    if (!trimmed) return false // 빈 이름으로 지우지 않는다 — 지우려면 별도 의도가 필요하다
+    const participant = await getRepository(ChatSessionParticipant).findOne({
+      where: { domain: { id: domain.id } as any, session: { id: sessionId } as any, user: { id: user.id } as any }
+    })
+    if (!participant) return false // 참여자가 아니면 남의 대화 제목을 바꿀 수 없다
+    const session = await getRepository(ChatSession).findOneBy({ id: sessionId, domain: { id: domain.id } as any })
+    if (!session) return false
+    await getRepository(ChatSession).update(sessionId, { name: trimmed, updater: user } as any)
+    publishSessionActivity({
+      domainId: domain.id,
+      sessionId,
+      kind: 'meta',
+      anchorType: (session as any).anchorType,
+      anchorId: (session as any).anchorId,
+      actorId: user?.id
+    })
+    return true
+  }
+
+  /**
+   * 읽은 지점 갱신 — 이 세션을 여기까지 읽었다. 멱등(여러 번 호출해도 최신 시각으로만 이동).
+   * 접속 표시(lastSeenAt)와 분리한다 — 창을 열어 두고 화면을 안 볼 수 있다.
+   */
+  @Mutation(() => Boolean, {
+    description:
+      "Mark a session as read up to now for the current user. Idempotent. Distinct from presence (lastSeenAt) — a window can be open without being read."
+  })
+  @Directive('@privilege(category: "ai-assistant", privilege: "mutation", legacy: "board-ai")')
+  async markSessionRead(
+    @Arg('sessionId') sessionId: string,
+    @Ctx() context: ResolverContext
+  ): Promise<boolean> {
+    const { domain, user } = context.state
+    const repo = getRepository(ChatSessionParticipant)
+    const mine = await repo.findOne({
+      where: { domain: { id: domain.id } as any, session: { id: sessionId } as any, user: { id: user.id } as any }
+    })
+    /* 참여자가 아니면 읽음 상태를 만들지 않는다 — 참여하지 않은 대화에 내 읽음 지점을 남기지 않는다. */
+    if (!mine) return false
+    await repo.update(mine.id!, { lastReadAt: new Date(), updater: user } as any)
+    return true
+  }
+
+  @Query(() => [User], {
+    description:
+      'List users in the current domain for `@` mention popup. board-ai 권한이면 누구나 멘션용 검색 가능 (관리자 전용 users() 와 별도).'
+  })
+  @Directive('@privilege(category: "ai-assistant", privilege: "query", legacy: "board-ai")')
+  async domainUsersForMention(
+    @Arg('query', { nullable: true, description: 'Substring to match against name/email (case-insensitive). Empty → all.' }) query: string | undefined,
+    @Arg('limit', () => Int, { nullable: true, defaultValue: 50 }) limit: number,
+    @Ctx() context: ResolverContext
+  ): Promise<User[]> {
+    const { domain } = context.state
+    const qb = buildDomainUsersQueryBuilder(domain.id, 'USER')
+    if (query?.trim()) {
+      const q = `%${query.trim().toLowerCase()}%`
+      qb.andWhere('(LOWER(USER.name) LIKE :q OR LOWER(USER.email) LIKE :q)', { q })
+    }
+    qb.orderBy('USER.name', 'ASC').limit(limit)
+    return await qb.getMany()
+  }
+
+  @Query(() => [ChatSessionParticipant], {
+    description: 'List participants of a ChatSession (members / owner).'
+  })
+  @Directive('@privilege(category: "ai-assistant", privilege: "query", legacy: "board-ai")')
+  async chatSessionParticipants(
+    @Arg('sessionId') sessionId: string,
+    @Ctx() context: ResolverContext
+  ): Promise<ChatSessionParticipant[]> {
+    const { domain } = context.state
+    const session = await getRepository(ChatSession).findOneBy({
+      id: sessionId,
+      domain: { id: domain.id }
+    })
+    if (!session) return []
+    return await getRepository(ChatSessionParticipant).find({
+      where: { session: { id: sessionId } as any, domain: { id: domain.id } },
+      order: { createdAt: 'ASC' }
+    })
+  }
+
+  @Mutation(() => Boolean, {
+    description: 'Presence heartbeat — bump current user\'s lastSeenAt in the session (online indicator).'
+  })
+  @Directive('@privilege(category: "ai-assistant", privilege: "mutation", legacy: "board-ai")')
+  async touchPresence(@Arg('sessionId') sessionId: string, @Ctx() context: ResolverContext): Promise<boolean> {
+    const { domain, user } = context.state
+    const repo = getRepository(ChatSessionParticipant)
+    const part = await repo.findOne({
+      where: { session: { id: sessionId } as any, user: { id: user.id } as any, domain: { id: domain.id } as any }
+    })
+    if (!part) return false // 참여자가 아니면 heartbeat 무시 (초대 전)
+    await repo.update(part.id!, { lastSeenAt: new Date(), updater: user } as any)
+    return true
+  }
+
+  @Query(() => [ChatMessage], { description: 'List chat messages of a session, oldest first.' })
+  @Directive('@privilege(category: "ai-assistant", privilege: "query", legacy: "board-ai")')
+  async chatMessages(
+    @Arg('sessionId') sessionId: string,
+    @Arg('limit', () => Int, { nullable: true, defaultValue: 100 }) limit: number,
+    @Arg('offset', () => Int, { nullable: true, defaultValue: 0 }) offset: number,
+    @Ctx() context: ResolverContext
+  ): Promise<ChatMessage[]> {
+    const { domain } = context.state
+    const session = await getRepository(ChatSession).findOneBy({
+      id: sessionId,
+      domain: { id: domain.id }
+    })
+    if (!session) return []
+    return await getRepository(ChatMessage).find({
+      where: { session: { id: sessionId } as any },
+      // creator: 그룹챗 발신자 표시(name) + 자기 여부 판정(email). 내부 관리키(id)에 의존하지 않는다.
+      relations: { creator: true },
+      order: { createdAt: 'ASC' },
+      take: limit,
+      skip: offset
+    })
+  }
+
+  @Directive('@transaction')
+  @Mutation(() => ChatSession, {
+    description:
+      'Start (or get existing) AI chat session anchored to a target. Idempotent — returns first existing or creates one. Use anchorType board for board authoring, space for a site (its co-located twins).'
+  })
+  @Directive('@privilege(category: "ai-assistant", privilege: "mutation", legacy: "board-ai")')
+  async startAISession(
+    @Arg('anchorType') anchorType: string,
+    @Arg('anchorId') anchorId: string,
+    @Ctx() context: ResolverContext
+  ): Promise<ChatSession> {
+    const { domain, user, tx } = context.state
+    const repo = getRepository(ChatSession, tx)
+
+    const existing = await repo.findOneBy(anchorWhere(domain.id, anchorType, anchorId))
+    if (existing) return existing
+
+    const session = await repo.save({
+      domain,
+      ...anchorColumns(anchorType, anchorId),
+      creator: user,
+      updater: user
+    } as any)
+    // creator 를 owner participant 로 자동 등록 — 다자간 채팅 기반.
+    await getRepository(ChatSessionParticipant, tx).save({
+      domain,
+      session: { id: session.id } as any,
+      user,
+      role: 'owner',
+      creator: user,
+      updater: user
+    } as any)
+    return session
+  }
+
+  @Directive('@transaction')
+  @Mutation(() => ChatSession, {
+    description:
+      'Always create a new AI chat session anchored to a target (no idempotent reuse). For multi-session UX — 새 탭 열기.'
+  })
+  @Directive('@privilege(category: "ai-assistant", privilege: "mutation", legacy: "board-ai")')
+  async createAISession(
+    @Arg('anchorType') anchorType: string,
+    @Arg('anchorId') anchorId: string,
+    @Arg('name', { nullable: true, description: 'Optional name (defaults to auto-generated `세션 N`).' }) name: string | undefined,
+    @Ctx() context: ResolverContext
+  ): Promise<ChatSession> {
+    const { domain, user, tx } = context.state
+    const repo = getRepository(ChatSession, tx)
+
+    // 이름 미지정 시 자동 생성 — **같은 앵커**의 기존 세션 수 + 1.
+    let finalName = name?.trim()
+    if (!finalName) {
+      const count = await repo.count({ where: anchorWhere(domain.id, anchorType, anchorId) })
+      finalName = `세션 ${count + 1}`
+    }
+
+    const session = await repo.save({
+      domain,
+      ...anchorColumns(anchorType, anchorId),
+      creator: user,
+      updater: user,
+      name: finalName
+    } as any)
+    // creator 를 owner participant 로 자동 등록.
+    await getRepository(ChatSessionParticipant, tx).save({
+      domain,
+      session: { id: session.id } as any,
+      user,
+      role: 'owner',
+      creator: user,
+      updater: user
+    } as any)
+    return session
+  }
+
+  @Directive('@transaction')
+  @Mutation(() => Boolean, {
+    description: 'Rename a ChatSession (tab label).'
+  })
+  @Directive('@privilege(category: "ai-assistant", privilege: "mutation", legacy: "board-ai")')
+  async renameChatSession(
+    @Arg('sessionId') sessionId: string,
+    @Arg('name') name: string,
+    @Ctx() context: ResolverContext
+  ): Promise<boolean> {
+    const { domain, user, tx } = context.state
+    const repo = getRepository(ChatSession, tx)
+    const session = await repo.findOneBy({ id: sessionId, domain: { id: domain.id } })
+    if (!session) throw new Error(`ChatSession ${sessionId} not found`)
+    await repo.update(sessionId, { name: name.trim() || null, updater: user } as any)
+    return true
+  }
+
+  @Directive('@transaction')
+  @Mutation(() => Boolean, {
+    description:
+      'Append a system note to a session — context that did not come from a participant typing (e.g. a conversation carried over from another surface, an external state change). The AI sees it as part of the shared history.'
+  })
+  @Directive('@privilege(category: "ai-assistant", privilege: "mutation", legacy: "board-ai")')
+  async appendSessionNote(
+    @Arg('sessionId') sessionId: string,
+    @Arg('content') content: string,
+    @Ctx() context: ResolverContext
+  ): Promise<boolean> {
+    const { domain, user, tx } = context.state
+    const session = await getRepository(ChatSession, tx).findOneBy({ id: sessionId, domain: { id: domain.id } })
+    if (!session) throw new Error(`ChatSession ${sessionId} not found`)
+    /* 프롬프트가 한 기록으로 폭증하지 않도록 자른다 — 맥락 전달이 목적이고 전문 보존이 아니다. */
+    const body = (content ?? '').trim().slice(0, 4000)
+    if (!body) return false
+
+    const previousLast = await getRepository(ChatMessage, tx).findOne({
+      where: { session: { id: session.id } as any },
+      order: { createdAt: 'DESC' }
+    })
+    const sysMsg = await getRepository(ChatMessage, tx).save({
+      session: { id: session.id } as any,
+      role: 'system',
+      content: body,
+      creator: user,
+      updater: user,
+      parentMessage: previousLast ? ({ id: previousLast.id } as any) : undefined
+    } as any)
+
+    /* 활동 갱신 + 방송 — 다른 참여자 목록·안 읽음과 열려 있는 화면의 transcript 일관성. best-effort. */
+    try {
+      await getRepository(ChatSession, tx).update(session.id!, activityPatch(body) as any)
+    } catch {
+      /* 기록 자체를 막지 않는다 */
+    }
+    publishSessionActivity({
+      domainId: domain.id,
+      sessionId: session.id!,
+      kind: 'message',
+      anchorType: (session as any).anchorType,
+      anchorId: (session as any).anchorId,
+      preview: body,
+      actorId: user?.id
+    })
+    publishChatMessage({ domainId: domain.id, sessionId: session.id, message: sysMsg })
+    return true
+  }
+
+  @Directive('@transaction')
+  @Mutation(() => Boolean, {
+    description:
+      'Carry a conversation from another surface into this session as its own turns (user / assistant), preserving order. Use when a lightweight exchange is promoted into a persistent discussion — the participants should read it as the conversation continuing, not as a machine dump.'
+  })
+  @Directive('@privilege(category: "ai-assistant", privilege: "mutation", legacy: "board-ai")')
+  async appendSessionTurns(
+    @Arg('sessionId') sessionId: string,
+    @Arg('turns', () => GraphQLJSON) turns: { role?: string; content?: string }[],
+    @Ctx() context: ResolverContext
+  ): Promise<boolean> {
+    const { domain, user, tx } = context.state
+    const session = await getRepository(ChatSession, tx).findOneBy({ id: sessionId, domain: { id: domain.id } })
+    if (!session) throw new Error(`ChatSession ${sessionId} not found`)
+
+    /* 옮겨온 대화는 **그 대화의 발언 그대로** 들어간다 — 한 덩어리 기록으로 뭉치면 사람이 읽을 수 없고
+     * (화면 하나를 잡아먹는 이탤릭 덩어리), 마크다운도 죽는다. 대신 개수·길이는 제한한다: 맥락 전달이
+     * 목적이고 전문 보존이 아니다. */
+    const rows = (Array.isArray(turns) ? turns : [])
+      .map(t => ({
+        role: t?.role === 'ai' || t?.role === 'assistant' ? 'assistant' : t?.role === 'user' ? 'user' : 'system',
+        content: (t?.content ?? '').trim().slice(0, 4000)
+      }))
+      .filter(t => t.content)
+      .slice(-40)
+    if (!rows.length) return false
+
+    let previous = await getRepository(ChatMessage, tx).findOne({
+      where: { session: { id: session.id } as any },
+      order: { createdAt: 'DESC' }
+    })
+    const saved: ChatMessage[] = []
+    for (const row of rows) {
+      previous = await getRepository(ChatMessage, tx).save({
+        session: { id: session.id } as any,
+        role: row.role,
+        content: row.content,
+        creator: user,
+        updater: user,
+        parentMessage: previous ? ({ id: previous.id } as any) : undefined
+      } as any)
+      saved.push(previous!)
+    }
+
+    /* 활동은 마지막 발언 기준 한 번만 — 옮긴 줄마다 목록을 흔들 이유가 없다. */
+    const last = rows[rows.length - 1]
+    try {
+      await getRepository(ChatSession, tx).update(session.id!, activityPatch(last.content) as any)
+    } catch {
+      /* best-effort — 옮기기 자체를 막지 않는다 */
+    }
+    publishSessionActivity({
+      domainId: domain.id,
+      sessionId: session.id!,
+      kind: 'message',
+      anchorType: (session as any).anchorType,
+      anchorId: (session as any).anchorId,
+      preview: last.content,
+      actorId: user?.id
+    })
+    for (const message of saved) {
+      publishChatMessage({ domainId: domain.id, sessionId: session.id, message })
+    }
+    return true
+  }
+
+}

package/server/service/index.ts

@@ -0,0 +1,37 @@
+import { ChatSessionResolver } from './chat-session-resolver.js'
+import { MySessionActivitySubscription } from './chat-session/session-activity-subscription.js'
+import { ChatMessageSubscription } from './chat-message/chat-message-subscription.js'
+import { entities as ChatSessionEntities } from './chat-session/index.js'
+import { entities as ChatMessageEntities } from './chat-message/index.js'
+import { entities as ChatSessionParticipantEntities } from './chat-session-participant/index.js'
+
+export * from './types.js'
+export * from './chat-session-resolver.js'
+export * from './subscribe-auth.js'
+/* 앵커 순수 로직 — 호스트가 앵커 종류를 참조한다(리졸버는 데코레이터 때문에 무겁다). */
+export * from './chat-session/session-anchor.js'
+export * from './chat-session/index.js'
+/* 순수 로직들 — 호스트(board-ai 등)가 같은 규칙을 쓰라고 공개한다. 베끼면 한쪽만 고쳐진다. */
+export * from './chat-session/session-inbox.js'
+export * from './chat-session/session-activity-publish.js'
+export * from './chat-session/session-activity-broadcast.js'
+export * from './chat-message/llm-history.js'
+export * from './chat-message/history-summary.js'
+export * from './chat-message/fold-history.js'
+export * from './chat-message/chat-message-publish.js'
+export * from './chat-message/chat-message-broadcast.js'
+export * from './chat-session-participant/invite-notification.js'
+export * from './chat-session-participant/presence.js'
+export * from './chat-message/index.js'
+export * from './chat-session-participant/index.js'
+
+export const entities = [...ChatSessionEntities, ...ChatMessageEntities, ...ChatSessionParticipantEntities]
+
+export const schema = {
+  resolverClasses: [
+    ChatSessionResolver,
+    ChatMessageSubscription,
+    /* 내가 참여한 모든 세션의 활동 — 창을 닫아 둔 표면이 배지·목록을 갱신할 수 있게. */
+    MySessionActivitySubscription
+  ]
+}