@things-factory/board-import 10.0.0-beta.71 → 10.0.0-beta.73

package/server/service/import-session/suggest-board-name.ts

@@ -0,0 +1,279 @@
+/**
+ * suggestBoardName — ImportSession 으로부터 새 Board 의 후보 이름을 추천한다.
+ *
+ * 정책:
+ *   1) base 후보 우선순위: input.hint → session.options.userPrompt → session.result.metadata.viewTypeReasoning
+ *      → attachment.name stem → 'Imported board'
+ *   2) base 정규화: 확장자 제거, _-. → 공백, 다중 공백 단일화, 50자 절단, trim
+ *   3) 도메인 격리 + 단일 LIKE query: `WHERE domain_id = ? AND (name = base OR name LIKE 'base (%)')`
+ *      한 번에 충돌 후보 다 가져오고 메모리에서 사용 가능한 가장 작은 (n) 결정
+ *   4) 결과: base 가 충돌 없으면 base, 있으면 'base (2)' / 'base (3)' / ...
+ *
+ * materializeFromSession 과 동일한 *RepoLike 패턴 — typeorm 의존성 주입으로 단위테스트 가능.
+ */
+
+const FALLBACK = 'Imported board'
+
+export interface SuggestBoardNameInput {
+  /** ImportSession id — 옵션. 있으면 거기서 hint / attachment 정보 추출. */
+  sessionId?: string
+  /**
+   * 명시 hint. session 정보보다 우선. 사용자가 wizard 에서 직접 메모를 쳐서 그것 기반 추천을
+   * 받고 싶을 때 사용.
+   */
+  hint?: string
+}
+
+export interface SessionForSuggest {
+  id: string
+  attachmentId?: string
+  optionsJson?: string | null
+  resultJson?: string | null
+}
+
+export interface AttachmentForSuggest {
+  id: string
+  name?: string
+}
+
+export interface SuggestSessionRepoLike {
+  findOneBy(criteria: any): Promise<SessionForSuggest | null>
+}
+
+export interface SuggestAttachmentRepoLike {
+  findOneBy(criteria: any): Promise<AttachmentForSuggest | null>
+}
+
+export interface SuggestBoardRepoLike {
+  /**
+   * 도메인 격리된 LIKE 쿼리. find({ where: { name: Like('base%'), domain: { id } } }) 형태로
+   * 호출자가 wiring. typeorm Like operator 노출을 피하기 위해 단순 string 으로 받음.
+   */
+  findExistingNames(opts: { domainId: string; basePrefix: string }): Promise<string[]>
+}
+
+export interface SuggestContext {
+  domain: { id: string; [k: string]: any }
+}
+
+export interface SuggestDeps {
+  sessionRepo: SuggestSessionRepoLike
+  attachmentRepo: SuggestAttachmentRepoLike
+  boardRepo: SuggestBoardRepoLike
+}
+
+export async function suggestBoardName(
+  input: SuggestBoardNameInput,
+  context: SuggestContext,
+  deps: SuggestDeps
+): Promise<string> {
+  const base = await resolveBaseName(input, context, deps)
+  const cleaned = sanitize(base) || FALLBACK
+
+  const existingNames = await deps.boardRepo.findExistingNames({
+    domainId: context.domain.id,
+    basePrefix: cleaned
+  })
+  return pickAvailableSuffix(cleaned, existingNames)
+}
+
+/**
+ * Board 이름 + 설명을 함께 추천. 이름은 짧고 심플 (운영 카드/리스트 표시용),
+ * 설명은 자세히 (사용자 hint + AI importStrategy + 통계 요약).
+ *
+ * 정책:
+ *   - **name**: hint / userPrompt / VLM reasoning / attachment stem 에서 짧은 base 추출 후
+ *     30자 이내로 자르고, 충돌 검사 + (n) suffix
+ *   - **description**: userPrompt + AI importStrategy + (있으면) reasoning + 카테고리 분포
+ *     를 자연어 단락으로 합성. 없으면 빈 문자열
+ */
+export interface SuggestBoardMetaResult {
+  name: string
+  description: string
+}
+
+export async function suggestBoardMeta(
+  input: SuggestBoardNameInput,
+  context: SuggestContext,
+  deps: SuggestDeps
+): Promise<SuggestBoardMetaResult> {
+  // 보드 정체성 = AI 가 도면을 보고 식별한 subject. import 처리 메타 (importStrategy /
+  // categoryDist / userPrompt — AI 에게 한 지시) 와는 별 차원이라 영속 데이터에 섞지 않는다.
+  const { subjectName, subjectDescription } = await resolveSubject(input, context, deps)
+
+  // name: subjectName > input.hint > attachment.name stem > FALLBACK
+  // 사용자가 명시 hint 를 줬으면 그것이 우선 (직접 의도). VLM subjectName 은 그 다음.
+  const baseName =
+    (input.hint && input.hint.trim() && firstSentence(input.hint)) ||
+    subjectName ||
+    (await resolveAttachmentStem(input, context, deps)) ||
+    FALLBACK
+  const cleanedName = shortenName(sanitize(baseName) || FALLBACK)
+
+  const existingNames = await deps.boardRepo.findExistingNames({
+    domainId: context.domain.id,
+    basePrefix: cleanedName
+  })
+  const name = pickAvailableSuffix(cleanedName, existingNames)
+
+  // description: subjectDescription > input.hint (full) > 빈 문자열
+  // AI 가 도면을 본 자세한 묘사가 있으면 그것이 가장 가치 있음.
+  const description =
+    subjectDescription || (input.hint && input.hint.trim()) || ''
+
+  return { name, description }
+}
+
+/** AI 가 도면을 보고 식별한 subject (보드 정체성) — VLM 응답의 subjectName / subjectDescription. */
+async function resolveSubject(
+  input: SuggestBoardNameInput,
+  context: SuggestContext,
+  deps: SuggestDeps
+): Promise<{ subjectName?: string; subjectDescription?: string }> {
+  if (!input.sessionId) return {}
+  const session = await deps.sessionRepo.findOneBy({
+    id: input.sessionId,
+    domain: { id: context.domain.id }
+  })
+  if (!session) return {}
+  const result = parseJsonSafe(session.resultJson)
+  const subjectName = typeof result?.metadata?.subjectName === 'string'
+    ? result.metadata.subjectName.trim()
+    : undefined
+  const subjectDescription = typeof result?.metadata?.subjectDescription === 'string'
+    ? result.metadata.subjectDescription.trim()
+    : undefined
+  return { subjectName, subjectDescription }
+}
+
+/** subject 미산출 시 fallback — attachment.name stem 만. */
+async function resolveAttachmentStem(
+  input: SuggestBoardNameInput,
+  context: SuggestContext,
+  deps: SuggestDeps
+): Promise<string | undefined> {
+  if (!input.sessionId) return undefined
+  const session = await deps.sessionRepo.findOneBy({
+    id: input.sessionId,
+    domain: { id: context.domain.id }
+  })
+  if (!session?.attachmentId) return undefined
+  const att = await deps.attachmentRepo.findOneBy({
+    id: session.attachmentId,
+    domain: { id: context.domain.id }
+  })
+  return stemOf(att?.name) || undefined
+}
+
+/**
+ * 짧은 이름 — 단순 30자 단위로 단어 경계에서 자르기. 너무 길면 그대로 자르되 단어 보존.
+ */
+function shortenName(s: string): string {
+  if (s.length <= 30) return s
+  // 30자 이내 마지막 공백에서 자르기
+  const truncated = s.slice(0, 30)
+  const lastSpace = truncated.lastIndexOf(' ')
+  if (lastSpace > 10) return truncated.slice(0, lastSpace).trim()
+  return truncated.trim()
+}
+
+
+// ── helpers ──────────────────────────────────────────────────────────
+
+async function resolveBaseName(
+  input: SuggestBoardNameInput,
+  context: SuggestContext,
+  deps: SuggestDeps
+): Promise<string> {
+  // 1) 명시 hint
+  if (input.hint && input.hint.trim()) return firstSentence(input.hint)
+
+  // 2) session 정보
+  if (input.sessionId) {
+    const session = await deps.sessionRepo.findOneBy({
+      id: input.sessionId,
+      domain: { id: context.domain.id }
+    })
+    if (session) {
+      // 2a) userPrompt 우선
+      const opts = parseJsonSafe(session.optionsJson)
+      const userPrompt = typeof opts?.userPrompt === 'string' ? opts.userPrompt.trim() : ''
+      if (userPrompt) return firstSentence(userPrompt)
+
+      // 2b) VLM reasoning
+      const result = parseJsonSafe(session.resultJson)
+      const reasoning =
+        typeof result?.boardModel?.importMeta?.viewTypeReasoning === 'string'
+          ? result.boardModel.importMeta.viewTypeReasoning.trim()
+          : typeof result?.metadata?.viewTypeReasoning === 'string'
+          ? result.metadata.viewTypeReasoning.trim()
+          : ''
+      if (reasoning) return firstSentence(reasoning)
+
+      // 2c) attachment name stem
+      if (session.attachmentId) {
+        const att = await deps.attachmentRepo.findOneBy({
+          id: session.attachmentId,
+          domain: { id: context.domain.id }
+        })
+        const stem = stemOf(att?.name)
+        if (stem) return stem
+      }
+    }
+  }
+
+  return FALLBACK
+}
+
+function parseJsonSafe(s: string | null | undefined): any {
+  if (!s) return undefined
+  try {
+    return JSON.parse(s)
+  } catch {
+    return undefined
+  }
+}
+
+function firstSentence(text: string): string {
+  // 첫 문장 종결 부호 또는 줄바꿈까지. 미발견 시 전체.
+  const m = text.match(/^([^.\n!?]{1,120})[.\n!?]?/)
+  return (m?.[1] ?? text).trim()
+}
+
+function stemOf(name: string | undefined | null): string {
+  if (!name) return ''
+  // 마지막 . 이후 (확장자) 제거. 점이 여러 번이면 가장 마지막만.
+  const lastDot = name.lastIndexOf('.')
+  if (lastDot > 0) return name.slice(0, lastDot)
+  return name
+}
+
+/**
+ * 정규화: _-. → 공백, 다중 공백 단일화, trim, 50자 절단.
+ * 결과가 빈 문자열이면 '' 반환 (호출자가 fallback).
+ */
+function sanitize(s: string): string {
+  if (!s) return ''
+  let cleaned = s.replace(/[_\-.]+/g, ' ').replace(/\s+/g, ' ').trim()
+  if (cleaned.length > 50) cleaned = cleaned.slice(0, 50).trim()
+  return cleaned
+}
+
+/**
+ * existingNames 안에서 base 가 그대로 비어있으면 base 반환, 아니면 'base (2)', '(3)', ...
+ * case-insensitive 비교 (postgres ilike 호환).
+ */
+export function pickAvailableSuffix(base: string, existingNames: string[]): string {
+  const lower = base.toLowerCase()
+  const taken = new Set<string>()
+  for (const name of existingNames) {
+    if (typeof name === 'string') taken.add(name.toLowerCase())
+  }
+  if (!taken.has(lower)) return base
+  for (let n = 2; n < 10000; n++) {
+    const candidate = `${base} (${n})`
+    if (!taken.has(candidate.toLowerCase())) return candidate
+  }
+  // 9999개 충돌 이라는 비현실 시나리오 — 마지막 fallback
+  return `${base} (${Date.now()})`
+}

package/server/service/import-tools.test.ts

@@ -0,0 +1,137 @@
+/**
+ * board-import 의 LLM tool 등록 + builder wiring — 단위 테스트.
+ *
+ * registry 통합 (등록 / kind 분류 / schema 노출) 외에 builder 가 service 함수와 정확히
+ * 결합되었는지 검증. service 함수 본체는 별도 파일 (import-actions.test, materialize-from-
+ * session.test) 에서 검증되어 있으므로 본 파일은 wiring 만 — ctx 누락 / placeholder 미사용
+ * 회귀 방지.
+ */
+import {
+  clearToolRegistry,
+  findToolSpec,
+  getToolKind,
+  getCategorySpecs
+} from '@things-factory/ai-client-base'
+import { registerBoardImportTools } from './import-tools'
+
+beforeEach(() => {
+  clearToolRegistry()
+  registerBoardImportTools()
+})
+
+afterEach(() => {
+  clearToolRegistry()
+})
+
+// ── 카테고리 등록 검증 ─────────────────────────────────────────────
+
+describe('import-tools — 카테고리 등록', () => {
+  test("'board-import' 카테고리 등록", () => {
+    expect(getCategorySpecs('board-import').length).toBeGreaterThan(0)
+  })
+
+  test('listImportAdapters / importBoardAsync / getImportSession / materializeImportSession 모두 등록', () => {
+    expect(findToolSpec('listImportAdapters')).toBeDefined()
+    expect(findToolSpec('importBoardAsync')).toBeDefined()
+    expect(findToolSpec('getImportSession')).toBeDefined()
+    expect(findToolSpec('materializeImportSession')).toBeDefined()
+  })
+})
+
+// ── kind 분류 ────────────────────────────────────────────────────
+
+describe('import-tools — kind 분류', () => {
+  test('listImportAdapters / getImportSession 은 read', () => {
+    expect(getToolKind('listImportAdapters')).toBe('read')
+    expect(getToolKind('getImportSession')).toBe('read')
+  })
+
+  test('importBoardAsync / materializeImportSession 은 external', () => {
+    expect(getToolKind('importBoardAsync')).toBe('external')
+    expect(getToolKind('materializeImportSession')).toBe('external')
+  })
+})
+
+// ── schema 노출 ──────────────────────────────────────────────────
+
+describe('import-tools — schema 노출', () => {
+  test('importBoardAsync schema 가 attachmentId required', () => {
+    const spec = findToolSpec('importBoardAsync')
+    expect(spec?.schema?.required).toContain('attachmentId')
+  })
+
+  test('materializeImportSession schema 가 sessionId / name required + type enum', () => {
+    const spec = findToolSpec('materializeImportSession')
+    expect(spec?.schema?.required).toEqual(expect.arrayContaining(['sessionId', 'name']))
+    expect(spec?.schema?.properties?.type?.enum).toEqual(['main', 'sub', 'popup'])
+  })
+
+  test('materializeImportSession 은 사용자 confirm 강조 themeNote 보유', () => {
+    const spec = findToolSpec('materializeImportSession')
+    expect(spec?.themeNote).toContain('confirm')
+  })
+})
+
+// ── builder wiring — ctx 누락 시 명확 에러 ───────────────────────────
+
+describe('import-tools — builder ctx 누락', () => {
+  test('importBoardAsync 가 ctx.state 없으면 의미있는 에러', async () => {
+    const spec = findToolSpec('importBoardAsync')
+    if (spec?.kind !== 'external') throw new Error('expected external')
+    await expect(spec.builder({ attachmentId: 'a1' }, {})).rejects.toThrow(/ctx\.state\.domain/)
+  })
+
+  test('getImportSession 가 ctx.state 없으면 의미있는 에러', async () => {
+    const spec = findToolSpec('getImportSession')
+    if (spec?.kind !== 'read') throw new Error('expected read')
+    await expect(spec.builder({ sessionId: 's1' }, {})).rejects.toThrow(/ctx\.state\.domain/)
+  })
+
+  test('materializeImportSession 가 ctx.state 없으면 의미있는 에러', async () => {
+    const spec = findToolSpec('materializeImportSession')
+    if (spec?.kind !== 'external') throw new Error('expected external')
+    await expect(
+      spec.builder({ sessionId: 's1', name: 'New' }, {})
+    ).rejects.toThrow(/ctx\.state\.domain/)
+  })
+})
+
+// ── builder wiring — listImportAdapters (ctx 무관) ───────────────────
+//
+// listImportAdapters builder 는 require('./pipeline/index') 로 DEFAULT_ADAPTERS 를
+// inspect 한다. pipeline 모듈 load chain (DxfAdapter / ImageAdapter / ai-client-base /
+// 외부 라이브러리) 의 typeorm-bound 또는 type-graphql Field reflection 평가가 단위 test
+// 환경에서 fail 하므로 본 단위 테스트에서는 격리 어렵다 — 통합 test (실 server bootstrap
+// 환경) 또는 e2e 에서 검증해야 한다. 핵심 wiring (kind / schema / ctx 누락 에러) 은
+// 위 describe 블록들이 충분히 보호.
+//
+// 향후 jest setup 에서 type-graphql / typeorm DataSource init 을 mock 해 격리 가능하면
+// describe.skip → describe 로 복원.
+describe.skip('import-tools — listImportAdapters (통합 test 영역)', () => {
+  test('AdapterInfo 배열 반환 — DXF 와 image 적어도 노출', async () => {
+    const spec = findToolSpec('listImportAdapters')
+    if (spec?.kind !== 'read') throw new Error('expected read')
+    const r = await spec.builder({}, {})
+    expect(Array.isArray(r)).toBe(true)
+    const formats = (r as any[]).map(a => a.format)
+    expect(formats).toContain('dxf')
+    expect(formats).toContain('image')
+  })
+
+  test('AdapterInfo 의 capabilities 가 모든 boolean 5 필드 보유', async () => {
+    const spec = findToolSpec('listImportAdapters')
+    if (spec?.kind !== 'read') throw new Error('expected read')
+    const r = await spec.builder({}, {})
+    for (const info of r as any[]) {
+      expect(info.capabilities).toEqual(
+        expect.objectContaining({
+          has2D: expect.any(Boolean),
+          has3D: expect.any(Boolean),
+          hasSemanticLabels: expect.any(Boolean),
+          hasTextLabels: expect.any(Boolean),
+          hasAttributes: expect.any(Boolean)
+        })
+      )
+    }
+  })
+})

package/server/service/import-tools.ts

@@ -0,0 +1,255 @@
+/**
+ * board-import 의 LLM tool 카테고리 등록.
+ *
+ * board-ai 의 chat 흐름 안에서 사용자가 "이 도면을 보드로 만들어줘" / "import 결과 검수
+ * 후 이 이름으로 저장" 같은 자연어를 발화하면 LLM 이 본 카테고리의 tool 들을 호출한다.
+ *
+ * 노출되는 tool:
+ *   - listImportAdapters       (read)     : 등록된 FormatAdapter 능력 조회
+ *   - importBoardAsync         (external) : Attachment → ImportSession 비동기 시작
+ *   - getImportSession         (read)     : ImportSession 진행/결과 조회
+ *   - materializeImportSession (external) : ImportSession.result → 새 Board entity
+ *
+ * dispatch wiring:
+ *   board-ai 의 chat 메서드가 ToolCallContext (resolver state — domain/user/tx) 를 closure 로
+ *   주입한다. builder 는 ctx.state 에서 typeorm getRepository / domain / user 를 추출해
+ *   service-level 함수 (import-actions, materialize-from-session) 를 호출한다.
+ *
+ *   이 layer 가 없으면 builder 가 typeorm 에 직접 의존해야 했고, board-ai 가 typeorm 까지
+ *   알게 되는 leakage 가 생겼을 것 — 의도적으로 builder 가 ctx.state.typeorm 같은 식으로
+ *   접근하지 않고 things-factory 표준 getRepository 를 호출.
+ */
+import { getRepository } from '@things-factory/shell'
+import {
+  registerToolCategory,
+  type ToolCategory,
+  type ToolSpec
+} from '@things-factory/ai-client-base'
+
+// 모든 server-side 의존성 (entity / service 함수 / 외부 패키지) 은 module-level import
+// 없이 lazy require — module load 만으로 typeorm decorator / 외부 controllers chain
+// (예: board-service 의 puppeteer pool) 이 평가되어 jest 환경에서 깨지는 것을 회피.
+// 운영에서는 builder 첫 호출 시 cache 채워져 이후 호출은 직접 dispatch.
+//
+// 이 패턴은 LLM tool layer 의 일반 정책으로 가져갈 수 있다 — registerToolCategory 가
+// 평가되는 시점은 server bootstrap 의 매우 이른 단계라, 그때 typeorm DataSource init 이
+// 아직 끝나지 않았을 가능성이 있다.
+let _depsCache: any | undefined
+function getDeps(): any {
+  if (!_depsCache) {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const isMod = require('./import-session/import-session')
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const bsMod = require('@things-factory/board-service')
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const actionsMod = require('./import-session/import-actions')
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const materializeMod = require('./import-session/materialize-from-session')
+    _depsCache = {
+      ImportSession: isMod.ImportSession,
+      Board: bsMod.Board,
+      Group: bsMod.Group,
+      startImportJobAsync: actionsMod.startImportJobAsync,
+      fetchImportSession: actionsMod.fetchImportSession,
+      describeAdapter: actionsMod.describeAdapter,
+      materializeFromSession: materializeMod.materializeFromSession
+    }
+  }
+  return _depsCache
+}
+
+/**
+ * tool builder 의 ctx.state 가 도메인 식별을 갖는지 검증. 미설정이면 명확한 에러로 실패 —
+ * board-ai 의 toolCallContext wiring 누락 / 비인증 호출 등을 빠르게 찾기 위해.
+ */
+function requireDomainContext(state: any): { domain: any; user: any } {
+  if (!state || !state.domain) {
+    throw new Error(
+      '[board-import] tool builder 의 ctx.state.domain 미설정. ' +
+        'board-ai 의 ChatOptions.toolCallContext 에 ResolverContext.state 가 전달됐는지 확인.'
+    )
+  }
+  return { domain: state.domain, user: state.user }
+}
+
+const importToolsCategory: ToolCategory = {
+  name: 'board-import',
+  description: 'Drawing/CAD/IFC/image → Board 변환 파이프라인 (zero-to-twin).',
+  specs: [
+    {
+      kind: 'read',
+      name: 'listImportAdapters',
+      description:
+        '등록된 도면 import 어댑터 (DXF / Image / 향후 IFC, glTF 등) 의 능력 조회. ' +
+        '사용자가 어떤 형식 import 가 가능한지 묻거나, LLM 이 적절한 어댑터 선택을 inspect 할 때 사용.',
+      schema: { type: 'object', properties: {} },
+      builder: async () => {
+        // 동적 import — pipeline 모듈의 DEFAULT_ADAPTERS 를 inspect.
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const pipelineModule = require('./pipeline/index')
+        const adapters: any[] = pipelineModule.DEFAULT_ADAPTERS ?? []
+        return adapters.map(getDeps().describeAdapter)
+      }
+    },
+    {
+      kind: 'external',
+      name: 'importBoardAsync',
+      description:
+        'Attachment(도면/조감도/사진) 을 비동기로 보드 모델로 변환 시작. 즉시 ImportSession 을 ' +
+        '반환하고 백그라운드에서 진행. status 가 completed 가 될 때까지 getImportSession 으로 ' +
+        'polling 해서 결과를 확인. 형식은 자동 감지 — DXF / GLTF / image 등.',
+      schema: {
+        type: 'object',
+        properties: {
+          attachmentId: {
+            type: 'string',
+            description: 'Attachment id (attachment-base 에 미리 업로드된 도면 파일).'
+          },
+          chatSessionId: {
+            type: 'string',
+            description: 'board-ai chat session id (선택). 진행 메시지가 chat 흐름에 합류.'
+          },
+          scopes: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'ImportRule 의 scope (예: ["fmsim"]). 도메인별 매핑 규칙 활성화.'
+          },
+          parseOptions: {
+            type: 'object',
+            description: 'Adapter 파싱 옵션 (excludeLayers / maxEntities / context 등).',
+            additionalProperties: true
+          }
+        },
+        required: ['attachmentId']
+      },
+      builder: async (args, ctx) => {
+        const { domain, user } = requireDomainContext(ctx?.state)
+        const session = await getDeps().startImportJobAsync(
+          {
+            attachmentId: args.attachmentId,
+            chatSessionId: args.chatSessionId,
+            scopes: args.scopes,
+            parseOptions: args.parseOptions
+          },
+          { domain, user },
+          getRepository(getDeps().ImportSession) as any
+        )
+        return {
+          sessionId: session.id,
+          status: session.status,
+          progress: session.progress,
+          message: session.message
+        }
+      }
+    },
+    {
+      kind: 'read',
+      name: 'getImportSession',
+      description:
+        'ImportSession 의 진행/결과 조회. status 가 queued/parsing/mapping/assembling/binding 인 ' +
+        '동안은 progress 와 message 를 반환, completed 면 result.boardModel 까지 포함. failed 면 ' +
+        'message 에 에러 사유.',
+      schema: {
+        type: 'object',
+        properties: {
+          sessionId: { type: 'string', description: 'ImportSession id (importBoardAsync 가 반환).' }
+        },
+        required: ['sessionId']
+      },
+      builder: async (args, ctx) => {
+        const { domain, user } = requireDomainContext(ctx?.state)
+        const session = await getDeps().fetchImportSession(
+          args.sessionId,
+          { domain, user },
+          getRepository(getDeps().ImportSession) as any
+        )
+        if (!session) return { found: false }
+        return {
+          found: true,
+          sessionId: session.id,
+          status: session.status,
+          progress: session.progress,
+          message: session.message,
+          // result 는 큰 boardModel 을 포함할 수 있어 status 가 completed 일 때만.
+          result: session.status === 'completed' ? session.result : undefined,
+          totalEntities: session.totalEntities,
+          completedAt: session.completedAt
+        }
+      }
+    },
+    {
+      kind: 'external',
+      name: 'materializeImportSession',
+      description:
+        '완료된 ImportSession 의 결과 boardModel 을 새 Board entity 로 영속화. status 가 ' +
+        'completed 인 세션만 처리. 결과 Board 는 state="draft" 로 생성되므로 사용자가 검수 후 ' +
+        '발행해야 한다.',
+      themeNote:
+        '⚠ 사용자의 명시적 confirm 후에만 호출. import 결과 미리보기를 보여주고 "이 이름으로 ' +
+        '저장하시겠어요?" 같은 확인 받은 다음 발동.',
+      schema: {
+        type: 'object',
+        properties: {
+          sessionId: { type: 'string' },
+          name: { type: 'string', description: '새 Board 이름 — 같은 도메인 내 unique.' },
+          description: { type: 'string' },
+          groupId: { type: 'string' },
+          type: { type: 'string', enum: ['main', 'sub', 'popup'] },
+          thumbnail: {
+            type: 'string',
+            description: 'Base64 thumbnail. 미지정 시 빈 placeholder 사용 (별도 thumbnail 생성 호출).'
+          }
+        },
+        required: ['sessionId', 'name']
+      },
+      builder: async (args, ctx) => {
+        const { domain, user } = requireDomainContext(ctx?.state)
+        const session = await getDeps().fetchImportSession(
+          args.sessionId,
+          { domain, user },
+          getRepository(getDeps().ImportSession) as any
+        )
+        const { Board, Group, materializeFromSession } = getDeps()
+        const board = await materializeFromSession(
+          session as any,
+          {
+            sessionId: args.sessionId,
+            name: args.name,
+            description: args.description,
+            groupId: args.groupId,
+            type: args.type,
+            thumbnail: args.thumbnail
+          },
+          { domain, user },
+          {
+            boardRepo: getRepository(Board) as any,
+            groupRepo: getRepository(Group) as any
+          }
+        )
+        // 큰 model 본문은 LLM 회신에서 제외 — id 와 메타만.
+        return {
+          boardId: (board as any).id,
+          name: (board as any).name,
+          state: (board as any).state,
+          sourceImportSessionId: (board as any).sourceImportSessionId
+        }
+      }
+    }
+  ] as ToolSpec[]
+}
+
+// 등록 — module 로드 시 side-effect.
+registerToolCategory(importToolsCategory)
+
+/**
+ * 명시적 register 함수 — 테스트나 lazy bootstrap 에서 import 만으로 발동되는 side-effect 가
+ * 부담스러울 때 import 후 명시 호출 가능.
+ */
+export function registerBoardImportTools(): void {
+  registerToolCategory(importToolsCategory)
+}
+
+/**
+ * 테스트용 — registerToolCategory 의 입력으로 사용된 카테고리 객체. 외부에서 inspect 가능.
+ */
+export const BOARD_IMPORT_TOOL_CATEGORY = importToolsCategory