@things-factory/board-ai 10.0.1 → 10.0.3

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

@@ -14,7 +14,7 @@ import { In } from 'typeorm'
 
 import { ChatSession } from './chat-session/chat-session.js'
 import { anchorColumns, anchorWhere } from './chat-session/session-anchor.js'
-import { buildInbox, activityPatch } from './chat-session/session-inbox.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'
@@ -56,6 +56,15 @@ class ChatSessionInboxEntry {
 
   @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()
@@ -118,23 +127,190 @@ export class ChatSessionResolver {
    */
   @Query(() => [ChatSessionInboxEntry], {
     description:
-      "List sessions anchored to a target with this viewer's unread state, ordered by recent activity. Uses the denormalized last-activity timestamp compared against the viewer's read point — no per-session aggregation."
+      "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: "board-ai", privilege: "query")')
   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: "board-ai", privilege: "query")')
+  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: "board-ai", privilege: "query")')
+  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)
+      where: anchorWhere(domain.id, anchorType, anchorId),
+      order: { lastMessageAt: 'DESC' },
+      take: INBOX_SCAN_CAP
     })
     if (sessions.length === 0) return []
-    const mine = await getRepository(ChatSessionParticipant).find({
+    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 }
     })
-    return buildInbox(sessions as any, mine as any) 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: "board-ai", privilege: "mutation")')
+  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: "board-ai", privilege: "mutation")')
+  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
   }
 
   /**
@@ -407,6 +583,122 @@ export class ChatSessionResolver {
     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: "board-ai", privilege: "mutation")')
+  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: "board-ai", privilege: "mutation")')
+  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
+  }
+
   @Directive('@transaction')
   @Mutation(() => PatchEntry, {
     description: 'Record a patch from user direct edit. Adds a system message so AI sees the change next turn.'

package/server/service/dock-contract.test.ts

@@ -0,0 +1,305 @@
+/**
+ * 협의 도크 계약 — **어시스턴트 경계의 배선**을 못박는다.
+ *
+ * 왜 이 파일이 따로 필요한가: 루프의 거동(도구 강제·근거 수집·제안 수집)은 agentic-loop.test 가,
+ * 접지 판정 규칙은 grounding.test 가 이미 잠근다. 비어 있던 것은 **그 둘을 잇는 한 줄들**이었고,
+ * 그 줄들이 끊어질 때 나타나는 증상이 실제로 겪은 실패와 1:1 로 대응한다:
+ *
+ *   · hostContext → ctx.state.host   끊기면 → AI 가 사용자에게 "어느 트윈이냐" 를 되묻는다
+ *   · requireGroundingTools → 루프    끊기면 → 도구 없이 상태를 단언한다("바쁘게 움직이고 있다")
+ *   · 접지 근거 4갈래                끊기면 → 정상 답에 경고가 붙거나(오탐) 없는 대상이 통과한다
+ *   · proposals → 응답               끊기면 → 실행 카드가 사라지고 제안이 도구 추적에 묻힌다
+ *
+ * 여기서 검증하지 **않는** 것: 실제 모델이 어느 도구를 고르는지. 그건 가짜 LLM 으로 알 수 없고,
+ * 도크의 도구 사용 패널이 보여준다. 이 파일의 값은 "배선이 살아 있다" 를 영구히 지키는 것이다.
+ */
+import type { AIClient } from '@things-factory/ai-client-base'
+import { registerToolCategory, clearToolRegistry } from '@things-factory/ai-client-base'
+
+import { DefaultBoardAIAssistant } from './assistant'
+
+/** 스크립트된 턴을 돌려주는 가짜 provider — 호출 옵션도 기록한다(toolChoice 확인용). */
+function mockClient(turns: Array<{ text?: string; toolCalls: any[] }>) {
+  let i = 0
+  const calls: any[] = []
+  const client: AIClient = {
+    id: 'mock:dock',
+    chat: async () => '',
+    generateJSON: async () => ({}),
+    chatWithTools: async (messages: any[], _tools: any[], options: any) => {
+      calls.push({ messages, options })
+      const turn = turns[i++] ?? { toolCalls: [] }
+      return {
+        text: turn.text,
+        toolCalls: turn.toolCalls,
+        stopReason: turn.toolCalls.length > 0 ? 'tool_use' : 'end_turn'
+      }
+    }
+  } as any
+  return { client, calls }
+}
+
+/** 트윈 도구 대역 — 실제 twin 카테고리와 같은 모양(대상을 문맥에서 해소하고 결과를 돌려준다). */
+function registerFakeTwinTools(seen: { host?: any; args?: any }) {
+  registerToolCategory({
+    name: 'twin-ops-fake',
+    description: 'fake ops tools for contract test',
+    specs: [
+      {
+        kind: 'read',
+        name: 'getSpaceStatus',
+        description: 'status of the twins running in the space this surface is looking at',
+        schema: { type: 'object', properties: { instanceId: { type: 'string' } } },
+        builder: async (args: any, ctx: any) => {
+          /* 대상을 **문맥에서** 정한다 — 사용자에게 되묻지 않는 경로가 이것이다. */
+          seen.host = ctx?.state?.host
+          seen.args = args
+          const target = args?.instanceId || ctx?.state?.host?.spaceId
+          return { instanceId: 'busan-wms', spaceId: target, nodes: [{ id: 'dock-1', occupancy: 0 }] }
+        }
+      } as any,
+      {
+        kind: 'read',
+        name: 'proposeHold',
+        description: 'record a proposed hold (never executes it)',
+        schema: { type: 'object', properties: { orderId: { type: 'string' } } },
+        builder: async (args: any) => ({
+          proposed: true,
+          command: 'order.hold',
+          args: { orderId: args?.orderId },
+          label: `${args?.orderId} 보류`,
+          instanceId: 'busan-wms'
+        })
+      } as any
+    ]
+  })
+}
+
+const TC = (name: string, args: any = {}, id = name) => ({ id, name, arguments: args })
+
+beforeEach(() => clearToolRegistry())
+afterEach(() => clearToolRegistry())
+
+describe('도크 계약 — 대화면 문맥(hostContext)', () => {
+  it('hostContext 가 도구의 ctx.state.host 로 도달한다 — 이게 끊기면 AI 가 식별자를 되묻는다', async () => {
+    const seen: { host?: any; args?: any } = {}
+    registerFakeTwinTools(seen)
+    const { client } = mockClient([{ toolCalls: [TC('getSpaceStatus', {})] }, { text: '여유롭습니다.', toolCalls: [] }])
+
+    await new DefaultBoardAIAssistant(client).chat([{ role: 'user', content: '지금 상태 어때?' }], undefined, {
+      toolCategories: ['twin-ops-fake'],
+      boardTools: false,
+      hostContext: { spaceId: 'busan' },
+      toolCallContext: { domain: { id: 'dom-1' } }
+    })
+
+    expect(seen.host).toEqual({ spaceId: 'busan' })
+  })
+
+  it('서버 문맥(domain)과 호스트 문맥이 함께 전달된다 — 권한은 서버 것, 범위는 호스트 것', async () => {
+    let state: any
+    registerToolCategory({
+      name: 'twin-ops-fake',
+      description: 'x',
+      specs: [
+        {
+          kind: 'read',
+          name: 'peek',
+          description: 'peek',
+          schema: { type: 'object', properties: {} },
+          builder: async (_a: any, ctx: any) => {
+            state = ctx?.state
+            return { ok: true }
+          }
+        } as any
+      ]
+    })
+    const { client } = mockClient([{ toolCalls: [TC('peek')] }, { text: 'ok', toolCalls: [] }])
+    await new DefaultBoardAIAssistant(client).chat([{ role: 'user', content: 'x' }], undefined, {
+      toolCategories: ['twin-ops-fake'],
+      boardTools: false,
+      hostContext: { spaceId: 'busan' },
+      toolCallContext: { domain: { id: 'dom-1' }, user: { id: 'u1' } }
+    })
+    expect(state.domain).toEqual({ id: 'dom-1' })
+    expect(state.host).toEqual({ spaceId: 'busan' })
+  })
+})
+
+describe('도크 계약 — 첫 턴 도구 강제', () => {
+  it('requireGroundingTools 를 켜면 첫 호출이 required, 이후 auto', async () => {
+    const seen: any = {}
+    registerFakeTwinTools(seen)
+    const { client, calls } = mockClient([
+      { toolCalls: [TC('getSpaceStatus', {})] },
+      { text: 'dock-1 은 여유롭습니다.', toolCalls: [] }
+    ])
+    await new DefaultBoardAIAssistant(client).chat([{ role: 'user', content: '상태?' }], undefined, {
+      toolCategories: ['twin-ops-fake'],
+      boardTools: false,
+      requireGroundingTools: true,
+      hostContext: { spaceId: 'busan' },
+      toolCallContext: { domain: { id: 'dom-1' } }
+    })
+    expect(calls.map(c => c.options.toolChoice)).toEqual(['required', 'auto'])
+  })
+
+  it('끄면 첫 호출도 auto — 라이브 상태를 다루지 않는 대화면은 강제하지 않는다', async () => {
+    const seen: any = {}
+    registerFakeTwinTools(seen)
+    const { client, calls } = mockClient([{ text: '네', toolCalls: [] }])
+    await new DefaultBoardAIAssistant(client).chat([{ role: 'user', content: '고마워' }], undefined, {
+      toolCategories: ['twin-ops-fake'],
+      boardTools: false,
+      toolCallContext: { domain: { id: 'dom-1' } }
+    })
+    expect(calls[0].options.toolChoice).toBe('auto')
+  })
+})
+
+describe('도크 계약 — 접지 경고', () => {
+  it('도구가 돌려준 식별자로 답하면 경고가 없다 — 도구 결과가 근거집합에 들어간다', async () => {
+    const seen: any = {}
+    registerFakeTwinTools(seen)
+    const { client } = mockClient([
+      { toolCalls: [TC('getSpaceStatus', {})] },
+      { text: 'dock-1 은 여유롭고 busan-wms 는 정상입니다.', toolCalls: [] }
+    ])
+    const r = await new DefaultBoardAIAssistant(client).chat([{ role: 'user', content: '상태?' }], undefined, {
+      toolCategories: ['twin-ops-fake'],
+      boardTools: false,
+      hostContext: { spaceId: 'busan' },
+      toolCallContext: { domain: { id: 'dom-1' } }
+    })
+    expect(r.groundingWarnings).toBeUndefined()
+  })
+
+  it('근거 밖의 대상을 지목하면 경고가 붙는다 — 답은 그대로 둔다(비파괴)', async () => {
+    const seen: any = {}
+    registerFakeTwinTools(seen)
+    const { client } = mockClient([
+      { toolCalls: [TC('getSpaceStatus', {})] },
+      { text: 'dock-9 에 적체가 있습니다.', toolCalls: [] }
+    ])
+    const r = await new DefaultBoardAIAssistant(client).chat([{ role: 'user', content: '상태?' }], undefined, {
+      toolCategories: ['twin-ops-fake'],
+      boardTools: false,
+      hostContext: { spaceId: 'busan' },
+      toolCallContext: { domain: { id: 'dom-1' } }
+    })
+    expect(r.groundingWarnings).toEqual(['dock-9'])
+    expect(r.reply).toContain('dock-9') // 경고는 붙이지만 답을 고치지 않는다
+  })
+
+  it('사용자가 말한 식별자를 되받는 것은 근거 있는 것이다 — 이력도 근거집합', async () => {
+    const seen: any = {}
+    registerFakeTwinTools(seen)
+    const { client } = mockClient([
+      { toolCalls: [TC('getSpaceStatus', {})] },
+      { text: 'rack-77 은 확인이 필요합니다.', toolCalls: [] }
+    ])
+    const r = await new DefaultBoardAIAssistant(client).chat(
+      [{ role: 'user', content: 'rack-77 어때?' }],
+      undefined,
+      {
+        toolCategories: ['twin-ops-fake'],
+        boardTools: false,
+        hostContext: { spaceId: 'busan' },
+        toolCallContext: { domain: { id: 'dom-1' } }
+      }
+    )
+    expect(r.groundingWarnings).toBeUndefined()
+  })
+})
+
+describe('도크 계약 — 조치 제안', () => {
+  it('proposed:true 도구 결과가 응답의 proposals 로 올라온다 — 실행 카드의 근거', async () => {
+    const seen: any = {}
+    registerFakeTwinTools(seen)
+    const { client } = mockClient([
+      { toolCalls: [TC('proposeHold', { orderId: 'o7' })] },
+      { text: '아래에서 확인해 주세요.', toolCalls: [] }
+    ])
+    const r = await new DefaultBoardAIAssistant(client).chat([{ role: 'user', content: 'o7 보류해줘' }], undefined, {
+      toolCategories: ['twin-ops-fake'],
+      boardTools: false,
+      hostContext: { spaceId: 'busan' },
+      toolCallContext: { domain: { id: 'dom-1' } }
+    })
+    expect(r.proposals).toHaveLength(1)
+    expect(r.proposals![0]).toMatchObject({ tool: 'proposeHold', command: 'order.hold', instanceId: 'busan-wms' })
+    /* 제안은 실행이 아니다 — 보드 패치도 액션도 만들어지지 않는다. */
+    expect(r.patch).toBeUndefined()
+    expect(r.actions).toBeUndefined()
+  })
+
+  it('조회만 한 응답에는 proposals 가 없다 — 규약은 플래그 하나뿐', async () => {
+    const seen: any = {}
+    registerFakeTwinTools(seen)
+    const { client } = mockClient([{ toolCalls: [TC('getSpaceStatus', {})] }, { text: '정상입니다.', toolCalls: [] }])
+    const r = await new DefaultBoardAIAssistant(client).chat([{ role: 'user', content: '상태?' }], undefined, {
+      toolCategories: ['twin-ops-fake'],
+      boardTools: false,
+      hostContext: { spaceId: 'busan' },
+      toolCallContext: { domain: { id: 'dom-1' } }
+    })
+    expect(r.proposals).toBeUndefined()
+  })
+})
+
+describe('도크 계약 — 능력 경계', () => {
+  it('보드 편집 도구를 끈 대화에서는 보드 편집이 실행되지 않는다 — 되돌릴 수 없는 면의 안전선', async () => {
+    const seen: any = {}
+    registerFakeTwinTools(seen)
+    const { client } = mockClient([
+      { toolCalls: [TC('addComponent', { type: 'rect', left: 0, top: 0, width: 10, height: 10 })] },
+      { text: '...', toolCalls: [] }
+    ])
+    const r = await new DefaultBoardAIAssistant(client).chat([{ role: 'user', content: 'rect 추가' }], undefined, {
+      toolCategories: ['twin-ops-fake'],
+      boardTools: false,
+      knownTypes: ['rect'],
+      toolCallContext: { domain: { id: 'dom-1' } }
+    })
+    expect(r.patch).toBeUndefined()
+  })
+})
+
+describe('도크 계약 — 도구 사용 규율이 프롬프트에 실린다', () => {
+  it('노출된 카테고리의 규율이 시스템 프롬프트에 붙는다 — 목록만 보내면 "언제 불러야 하는지" 가 빠진다', async () => {
+    registerToolCategory({
+      name: 'twin-ops-fake',
+      description: 'x',
+      guidance: '- 조치 요청에는 반드시 proposeHold 를 호출한다. 호출 없이 제안했다고 쓰지 말 것.',
+      specs: [
+        {
+          kind: 'read',
+          name: 'proposeHold',
+          description: 'propose',
+          schema: { type: 'object', properties: {} },
+          builder: async () => ({ proposed: true, command: 'order.hold' })
+        } as any
+      ]
+    })
+    const { client, calls } = mockClient([{ text: '네', toolCalls: [] }])
+    await new DefaultBoardAIAssistant(client).chat([{ role: 'user', content: 'o7 보류' }], undefined, {
+      toolCategories: ['twin-ops-fake'],
+      boardTools: false,
+      toolCallContext: { domain: { id: 'dom-1' } }
+    })
+    expect(calls[0].options.systemPrompt).toContain('반드시 proposeHold 를 호출한다')
+  })
+
+  it('노출하지 않은 카테고리의 규율은 새지 않는다 — 대화면마다 능력과 규율이 함께 좁혀진다', async () => {
+    registerToolCategory({ name: 'twin-ops-fake', guidance: 'OPS-RULE', specs: [] })
+    registerToolCategory({ name: 'other-fake', guidance: 'OTHER-RULE', specs: [] })
+    const { client, calls } = mockClient([{ text: '네', toolCalls: [] }])
+    await new DefaultBoardAIAssistant(client).chat([{ role: 'user', content: 'x' }], undefined, {
+      toolCategories: ['twin-ops-fake'],
+      boardTools: false,
+      toolCallContext: { domain: { id: 'dom-1' } }
+    })
+    expect(calls[0].options.systemPrompt).toContain('OPS-RULE')
+    expect(calls[0].options.systemPrompt).not.toContain('OTHER-RULE')
+  })
+})