@things-factory/ai-client-base 10.1.3 → 10.1.6

package/server/service/assistant/assistant-chat.test.ts

@@ -0,0 +1,218 @@
+/*
+ * What this guards: **the two things a product must not be able to skip.**
+ *
+ * The loop came out of board-ai on 2026-09-05 and the guards around it did not, so for four days
+ * "run the loop" and "run the loop safely" were two different calls and only one of them was
+ * reachable from a product without a board. The failure that made this urgent is recorded in
+ * board-ai's grounding file: the twin's header route had the grounding guard and its dock route
+ * did not, so the same question was verified on one side and not the other.
+ *
+ * So these tests are not about the loop's control flow — `agentic-loop.test.ts` covers that. They
+ * assert that a caller who does nothing special still gets:
+ *
+ *   ① the reason the loop stopped, in the reply
+ *   ② the reply checked against what the model was actually handed
+ *
+ * and that ② reads `groundedTexts`, never the display summaries.
+ */
+import { assistantChat } from './assistant-chat'
+import type { AIToolCall, AIToolChatResult } from '../types.js'
+import type { ToolDispatchHelpers } from '../agentic-loop/index.js'
+
+/*
+ * ⚠ 식별자 픽스처가 **소문자**인 이유: 접지 가드의 `ID_TOKEN` 이
+ * `[a-z][a-z0-9]*(-[a-z0-9]+)+` 다. 대문자 식별자(`WO-99871`)는 애초에 추출되지 않아 경고가 나올
+ * 수 없고, 그것으로 시험을 쓰면 **구현이 무엇을 하든 초록**이 된다(처음에 그렇게 썼다).
+ *
+ * 그 사정거리 자체가 별 문제다 — plant 의 오더(`WO-…`)와 트윈의 태그(`TAG-FUNC-…`)가 대문자라
+ * **이 가드가 그 제품들에는 닿지 않는다.** 이 파일이 고칠 것은 아니고(9개 앱이 이 규칙을 쓴다),
+ * `utils/grounding.ts` 의 `ID_TOKEN` 을 넓히는 별 판단이다.
+ */
+const TC = (name: string, args: any = {}, id = 't1'): AIToolCall =>
+  ({ id, name, arguments: args, type: 'tool_use' } as any)
+
+const okResult = (text?: string, toolCalls: AIToolCall[] = []): AIToolChatResult =>
+  ({
+    text,
+    toolCalls,
+    stopReason: toolCalls.length > 0 ? 'tool_use' : 'end_turn',
+    usage: undefined
+  } as any)
+
+const dispatch = (overrides: Partial<ToolDispatchHelpers> = {}): ToolDispatchHelpers => ({
+  isReadTool: () => false,
+  isWriteTool: () => false,
+  isActionTool: () => false,
+  executeReadTool: () => ({ stub: true }),
+  validateWriteToolCall: () => ({ valid: true }),
+  toolCallToOp: () => null,
+  summarizeToolResult: v => v,
+  ...overrides
+})
+
+const input = (overrides: any = {}, dispatchOverrides: Partial<ToolDispatchHelpers> = {}) => ({
+  initialConversation: [{ role: 'user' as const, content: 'hi' }],
+  tools: [],
+  options: { systemPrompt: 'you are a bot' },
+  chat: async () => okResult('done'),
+  dispatch: dispatch(dispatchOverrides),
+  context: {},
+  ...overrides
+})
+
+describe('assistantChat — ① 중단 이유가 답에 닿는다', () => {
+  it('정상 종료면 답이 모델의 말 그대로다 — 없는 통지를 붙이지 않는다', async () => {
+    const r = await assistantChat(input({ chat: async () => okResult('열두 대입니다') }))
+    expect(r.reply).toBe('열두 대입니다')
+    expect(r.baseText).toBe('열두 대입니다')
+  })
+
+  it('공급자 오류로 멈추면 그 사실이 답에 붙는다 — 잘린 답이 완결로 보이지 않는다', async () => {
+    const r = await assistantChat(
+      input({
+        chat: async () => {
+          throw new Error('Error fetching from undefined: [503 Service Unavailable]')
+        }
+      })
+    )
+    expect(r.loop.abortReason?.type).toBe('provider_error')
+    expect(r.reply).toMatch(/다시/)
+    /* 남의 말(SDK 원문)을 사용자에게 보여주지 않는다. */
+    expect(r.reply).not.toMatch(/503/)
+    expect(r.reply).not.toMatch(/Error fetching/)
+  })
+
+  it('반복 한계로 멈추면 답이 그것을 말한다', async () => {
+    /* 도구를 계속 부르게 해서 max_iterations 로 몰아넣는다. */
+    const r = await assistantChat(
+      input(
+        {
+          options: { systemPrompt: 's', maxIterations: 2 },
+          chat: async () => okResult(undefined, [TC('read1')])
+        },
+        { isReadTool: () => true }
+      )
+    )
+    expect(r.loop.abortReason?.type).toBe('max_iterations')
+    expect(r.reply).toMatch(/중단/)
+  })
+
+  it('통지는 답을 고치지 않고 뒤에 붙는다', async () => {
+    const r = await assistantChat(
+      input(
+        {
+          options: { systemPrompt: 's', maxIterations: 1 },
+          chat: async () => okResult('부분 결과', [TC('read1')])
+        },
+        { isReadTool: () => true }
+      )
+    )
+    expect(r.baseText).toBe('부분 결과')
+    expect(r.reply.startsWith('부분 결과')).toBe(true)
+    expect(r.reply.length).toBeGreaterThan(r.baseText.length)
+  })
+})
+
+describe('assistantChat — ② 접지 검사가 그냥 돈다', () => {
+  it('아무 설정 없이도 근거 밖 식별자가 잡힌다 — 켜는 것을 잊을 수 없다', async () => {
+    const r = await assistantChat(input({ chat: async () => okResult('wo-99871 이 밀렸습니다') }))
+    expect(r.groundingWarnings).toBeDefined()
+    expect(r.groundingWarnings!.join(' ')).toMatch(/wo-99871/)
+  })
+
+  it('도구가 준 원문 안의 식별자는 경고가 아니다', async () => {
+    const r = await assistantChat(
+      input(
+        {
+          chat: async (msgs: any[]) =>
+            msgs.some(m => JSON.stringify(m.content).includes('wo-99871'))
+              ? okResult('wo-99871 이 밀렸습니다')
+              : okResult(undefined, [TC('findOrders')])
+        },
+        { isReadTool: () => true, executeReadTool: () => ({ orders: ['wo-99871'] }) }
+      )
+    )
+    expect(r.baseText).toBe('wo-99871 이 밀렸습니다')
+    expect(r.groundingWarnings).toBeUndefined()
+  })
+
+  it('★ 근거는 groundedTexts 다 — 화면용 요약이 잘라낸 식별자를 「근거 없음」으로 오판하지 않는다', async () => {
+    /*
+     * 이 시험이 이 파일의 이유다. `summarizeToolResult` 를 「전부 버린다」로 두면, 화면 요약을 근거로
+     * 읽는 구현은 정상 답을 경고로 만든다. 모델은 원문을 받았기 때문이다.
+     */
+    const r = await assistantChat(
+      input(
+        {
+          chat: async (msgs: any[]) =>
+            msgs.some(m => JSON.stringify(m.content).includes('wo-99871'))
+              ? okResult('wo-99871 이 밀렸습니다')
+              : okResult(undefined, [TC('findOrders')])
+        },
+        {
+          isReadTool: () => true,
+          executeReadTool: () => ({ orders: ['wo-99871'] }),
+          summarizeToolResult: () => '…(생략)'
+        }
+      )
+    )
+    expect(r.loop.toolUsages[0].result).toBe('…(생략)')
+    expect(r.loop.groundedTexts.join(' ')).toMatch(/wo-99871/)
+    expect(r.groundingWarnings).toBeUndefined()
+  })
+
+  it('호스트가 준 문맥도 근거다 — 안 주면 정상 답이 경고를 받는다', async () => {
+    const reply = 'board-77 을 고쳤습니다'
+
+    const without = await assistantChat(input({ chat: async () => okResult(reply) }))
+    expect(without.groundingWarnings?.join(' ')).toMatch(/board-77/)
+
+    const withContext = await assistantChat(
+      input({ chat: async () => okResult(reply), groundingSources: { hostContext: 'current board: board-77' } })
+    )
+    expect(withContext.groundingWarnings).toBeUndefined()
+  })
+
+  it('명시로만 끌 수 있다 — 그리고 끈 것은 경고를 버린 것과 구별된다', async () => {
+    const r = await assistantChat(
+      input({ chat: async () => okResult('wo-99871 이 밀렸습니다'), skipGrounding: true })
+    )
+    expect(r.groundingWarnings).toBeUndefined()
+  })
+
+  it('경고가 없으면 undefined 다 — 빈 배열을 주지 않는다', async () => {
+    const r = await assistantChat(input({ chat: async () => okResult('네') }))
+    expect(r.groundingWarnings).toBeUndefined()
+  })
+})
+
+describe('assistantChat — 말을 지어내지 않는다', () => {
+  it('모델이 말을 안 하고 끝나면 답이 비어 있다 — 도메인을 모르는 자리에서 서술하지 않는다', async () => {
+    const r = await assistantChat(
+      input({ chat: async () => okResult(undefined) })
+    )
+    expect(r.baseText).toBe('')
+    expect(r.reply).toBe('')
+    /* 말이 없으면 검사할 것도 없다 — 빈 답에 대고 경고를 만들지 않는다. */
+    expect(r.groundingWarnings).toBeUndefined()
+  })
+
+  it('루프 결과는 그대로 넘어온다 — 호스트가 자기 뜻으로 해석한다', async () => {
+    /* 도구를 한 번만 부르게 한다 — 매번 같은 호출을 돌려주면 루프가 반복 한계까지 돈다. */
+    let called = false
+    const r = await assistantChat(
+      input(
+        {
+          chat: async () => {
+            if (called) return okResult('했습니다')
+            called = true
+            return okResult(undefined, [TC('write1')])
+          }
+        },
+        { isWriteTool: () => true }
+      )
+    )
+    expect(r.loop.accumulatedWriteCalls.map(c => c.name)).toEqual(['write1'])
+    expect(r.baseText).toBe('했습니다')
+  })
+})

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

@@ -0,0 +1,99 @@
+/*
+ * One turn of an assistant — the loop **with the guards that must not be optional.**
+ *
+ * ── Why this exists (2026-09-10) ────────────────────────────────────────────────
+ * `runAgenticLoop` is neutral and has been since 2026-09-05, when the same loop running in two
+ * places was consolidated. The note on that change is the reason this file exists: it was "not a
+ * duplication, a defect" — the two copies had **their safety measures set opposite ways**.
+ *
+ * The loop came out. The guards around it did not. They stayed in `board-ai`, wrapped around
+ * `DefaultBoardAIAssistant.chat`, which meant a product with no board of its own could only get
+ * them by going through the board editor. The plant lane read that correctly — it uses none of
+ * board's session machinery — and asked whether it could call `runAgenticLoop` directly instead.
+ *
+ * The answer was no, and the reason is written in `board-ai`'s own grounding file: the twin's
+ * header route had a grounding guard and its dock route did not, so **the same question was
+ * verified on one side and not the other.** A per-product door makes that three ways. This file is
+ * the door instead.
+ *
+ * ── What is guaranteed here, and what the host still owns ───────────────────────
+ * Guaranteed, because a caller cannot skip it:
+ *   · the loop stops for a reason and the reason reaches the reply  (`formatAbortNotice`)
+ *   · the reply is checked against what the model was actually given (`groundingWarnings`)
+ *
+ * Still the host's, because only the host knows the domain:
+ *   · which tools exist and what a write call means      → `gate`, `dispatch`
+ *   · what counts as evidence beyond the tool results    → `groundingSources`
+ *
+ * ── Grounding sources: leaving one out produces false warnings ──────────────────
+ * The corpus is everything the model saw this turn. The tool results are added here, from
+ * `groundedTexts` — the raw strings sent back as `tool_result`, never `toolUsages[].result`, which
+ * is depth-limited for display. A check reading the display copy can pass while the model was
+ * handed `{}`; an un-awaited async builder did exactly that.
+ *
+ * Anything else the host put in front of the model — a system prompt, a state summary, the user's
+ * own words — has to be declared, or a correct answer quoting it gets warned about.
+ */
+import { runAgenticLoop, type AgenticLoopInput, type AgenticLoopResult } from '../agentic-loop/index.js'
+import { buildGroundedCorpus, groundingWarnings, type GroundingSources } from '../utils/index.js'
+import { formatAbortNotice } from './abort-notice.js'
+
+export interface AssistantChatInput<TCtx = unknown, TOp = unknown> extends AgenticLoopInput<TCtx, TOp> {
+  /**
+   * 이 턴에 모델이 본 것 — **도구 결과 말고** 전부. 도구 결과는 이 함수가 루프에서 받아 더한다.
+   *
+   * 빠뜨리면 정상 답이 경고를 받는다(오탐). 시스템 프롬프트에 적어 보낸 타입 이름을 모델이 말하는
+   * 것은 근거 있는 발언이다.
+   */
+  groundingSources?: Omit<GroundingSources, 'toolResults'>
+  /**
+   * 접지 검사를 끈다 — **기본은 켜짐.**
+   *
+   * 끄는 것이 맞는 자리가 있다: 식별자를 다루지 않는 대화(문서 상담·개념 질문)는 근거집합에 식별자가
+   * 없어 모든 고유명사가 경고로 나온다. 그때는 끄는 것이 정직하고, **켠 채로 경고를 버리는 것**이
+   * 정직하지 않다.
+   */
+  skipGrounding?: boolean
+}
+
+export interface AssistantChatResult<TOp = unknown> {
+  /**
+   * 사용자에게 보일 답 — 모델의 마지막 말 + 중단 통지.
+   *
+   * 모델의 말을 고치지 않는다. 통지는 **뒤에 붙는다.**
+   */
+  reply: string
+  /** 통지가 붙기 전의 답. 접지 검사가 본 것이고, 호스트가 다시 판정할 때 쓴다. */
+  baseText: string
+  /** 근거 밖의 식별자를 지목한 자리들. 없으면 undefined — 빈 배열을 주지 않는다. */
+  groundingWarnings?: string[]
+  /** 루프 결과 원본 — 쓰기 호출·조치·제안·도구 흔적. 호스트가 자기 뜻으로 해석한다. */
+  loop: AgenticLoopResult<TOp>
+}
+
+/**
+ * 한 턴을 돌린다.
+ *
+ * `lastText` 가 없을 수 있다(도구만 부르고 말을 안 한 턴). 그 경우 `baseText` 는 빈 문자열이고,
+ * 무엇을 대신 말할지는 호스트가 정한다 — 여기서 「변경했습니다」 같은 말을 지어내지 않는다.
+ * 도메인을 모르는 자리에서 결과를 서술하면 그것이 곧 지어낸 원인이 된다.
+ */
+export async function assistantChat<TCtx = unknown, TOp = unknown>(
+  input: AssistantChatInput<TCtx, TOp>
+): Promise<AssistantChatResult<TOp>> {
+  const { groundingSources, skipGrounding, ...loopInput } = input
+
+  const loop = await runAgenticLoop<TCtx, TOp>(loopInput)
+
+  const baseText = loop.lastText ?? ''
+  const reply = baseText + formatAbortNotice(loop.abortReason)
+
+  let warnings: string[] | undefined
+  if (!skipGrounding && baseText) {
+    const corpus = buildGroundedCorpus({ ...(groundingSources ?? {}), toolResults: loop.groundedTexts })
+    const found = groundingWarnings(baseText, corpus)
+    warnings = found.length > 0 ? found : undefined
+  }
+
+  return { reply, baseText, groundingWarnings: warnings, loop }
+}

package/server/service/assistant/index.ts

@@ -0,0 +1,9 @@
+/*
+ * The neutral assistant layer — the agentic loop plus the guards that must not be optional.
+ *
+ * See `assistant-chat.ts` for why this is not in a product package.
+ */
+export * from './abort-notice.js'
+export * from './summarize.js'
+export * from './registry-gate.js'
+export * from './assistant-chat.js'

package/server/service/assistant/registry-gate.ts

@@ -0,0 +1,76 @@
+/*
+ * Which tools this conversation may call — the registry half.
+ *
+ * ── Why a gate at all ───────────────────────────────────────────────────────────
+ * One product grows several conversation surfaces (a board authoring dock, an operations dock, a
+ * header assistant). Board edits can be reverted; an operations command reaches a real factory.
+ * If both sets hang in one conversation, the boundary is a label on the screen.
+ *
+ * **Hiding the definitions is not enough.** A model can guess a name, and an older conversation
+ * can be replayed with tool calls still in it. So the same gate has to decide *both* what is
+ * offered and what may be dispatched. A name that fails the gate is reported back to the model as
+ * unregistered — never a silent no-op, which the model would read as success.
+ *
+ * ── Why the registry half is here and the rest is not (2026-09-10) ──────────────
+ * This came out of `board-ai`, where the gate answered from two sources at once: the tool registry
+ * *and* board's own core tool-name sets. The first is neutral — any host asking "what kind of tool
+ * is this name, and may this conversation see it" wants the same answer. The second is board's.
+ *
+ * So the registry half lives here and a host **extends** it with whatever it owns
+ * (`extendToolGate`). Splitting it this way is what lets a product with no board of its own get
+ * the same dispatch discipline, instead of each product writing its own gate and diverging — which
+ * is what happened with the grounding guard: the twin's header route had it and the dock route did
+ * not, so the same question was verified on one side and not the other.
+ */
+import { findToolSpec, getToolKind, type ToolCategoryFilter, type ToolSpec } from '../tool-registry/index.js'
+
+/** 이름 하나에 대한 판정. 정의 조립과 dispatch 가 **같은 것**을 쓴다. */
+export interface ToolGate {
+  /** 이 대화에 허용된 카테고리 목록. 없음 = 전부. */
+  filter: ToolCategoryFilter
+  isRead(name: string): boolean
+  isWrite(name: string): boolean
+  isAction(name: string): boolean
+  spec(name: string): ToolSpec | undefined
+}
+
+/** 호스트가 자기 도구를 더할 때 주는 것. 준 것만 더해지고, 안 준 축은 레지스트리 판정 그대로다. */
+export interface ToolGateExtension {
+  isRead?(name: string): boolean
+  isWrite?(name: string): boolean
+  isAction?(name: string): boolean
+  spec?(name: string): ToolSpec | undefined
+}
+
+/**
+ * 레지스트리만 보고 답하는 게이트.
+ *
+ * `external` 은 읽기로 본다 — 등록한 쪽이 「밖에서 값을 가져온다」고 말한 것이고, 그것은 쓰지 않는다.
+ */
+export function registryToolGate(filter?: ToolCategoryFilter): ToolGate {
+  const kind = (name: string) => getToolKind(name, filter)
+  return {
+    filter,
+    isRead: name => kind(name) === 'read' || kind(name) === 'external',
+    isWrite: name => kind(name) === 'write',
+    isAction: name => kind(name) === 'action',
+    spec: name => findToolSpec(name, filter)
+  }
+}
+
+/**
+ * 호스트의 판정을 **더한다.** 겹치면 어느 쪽이든 참이면 참이다 — 게이트는 「이 이름을 다룰 수 있나」를
+ * 묻고, 두 출처 중 하나가 안다고 하면 다룰 수 있다.
+ *
+ * 한쪽으로 덮지 않는 이유: 덮으면 호스트가 자기 이름집합에 없는 등록 도구를 **조용히 잠근다.** 그러면
+ * 대화면이 카테고리를 허용했는데 호출이 미등록으로 회신되고, 원인이 두 자리에 나뉘어 있어 못 찾는다.
+ */
+export function extendToolGate(base: ToolGate, extension: ToolGateExtension): ToolGate {
+  return {
+    filter: base.filter,
+    isRead: name => base.isRead(name) || !!extension.isRead?.(name),
+    isWrite: name => base.isWrite(name) || !!extension.isWrite?.(name),
+    isAction: name => base.isAction(name) || !!extension.isAction?.(name),
+    spec: name => base.spec(name) ?? extension.spec?.(name)
+  }
+}

package/server/service/assistant/summarize.ts

@@ -0,0 +1,61 @@
+/*
+ * Tool results, cut down to what a screen can hold.
+ *
+ * ── Why this is here and not in a product (2026-09-10) ───────────────────────────
+ * This came out of `board-ai`, and measuring the other consumer is what settled it: `twin-ai`
+ * passes `summarizeToolResult: v => v` — the identity function. So one product compressed its
+ * tool results before persisting them and the other did not, for no stated reason. That is the
+ * shape of a layer living in the wrong package: the second product does not decide differently,
+ * it just never gets the decision.
+ *
+ * ── ⚠ This is for the screen, never for a judgement ─────────────────────────────
+ * The output is depth- and length-limited, so it is **not evidence of what the model received**.
+ * A check that reads these summaries can pass while the model was handed `{}` — an un-awaited
+ * async builder did exactly that, and the screen still showed a successful call.
+ *
+ * What the model actually received is `AgenticLoopResult.groundedTexts`. Grounding already uses
+ * it, and anything that judges correctness must use it too.
+ */
+
+/** 문자열은 이 길이에서 자른다. 자른 사실과 잘린 양을 남긴다 — 조용히 짧아지지 않는다. */
+const MAX_STRING = 200
+/** 배열은 이 개수까지 보이고 나머지는 수로 말한다. */
+const MAX_ITEMS = 5
+/** 배열 안의 배열은 이 깊이에서 모양만 남긴다. */
+const MAX_ARRAY_DEPTH = 2
+/** 객체는 이 깊이에서 키 이름만 남긴다. */
+const MAX_OBJECT_DEPTH = 3
+/** 깊이 한계에서 남길 키 개수. */
+const MAX_KEYS = 6
+
+/**
+ * 도구 결과를 화면·영속에 쓸 크기로 줄인다.
+ *
+ * 줄인 자리마다 **줄였다는 표시**를 남긴다(`…[+N chars]` · `…[+N items]` · `[Array(N)]`).
+ * 표시가 없으면 읽는 사람이 그것을 원본으로 믿는다.
+ */
+export function summarizeToolResult(value: any, depth = 0): any {
+  if (value === null || value === undefined) return value
+  if (typeof value === 'string') {
+    return value.length > MAX_STRING ? `${value.slice(0, MAX_STRING)}…[+${value.length - MAX_STRING} chars]` : value
+  }
+  if (typeof value === 'number' || typeof value === 'boolean') return value
+  if (Array.isArray(value)) {
+    if (depth >= MAX_ARRAY_DEPTH) return `[Array(${value.length})]`
+    const out = value.slice(0, MAX_ITEMS).map(v => summarizeToolResult(v, depth + 1))
+    if (value.length > MAX_ITEMS) out.push(`…[+${value.length - MAX_ITEMS} items]`)
+    return out
+  }
+  if (typeof value === 'object') {
+    if (depth >= MAX_OBJECT_DEPTH) {
+      const keys = Object.keys(value).slice(0, MAX_KEYS).join(',')
+      return `{${keys}${Object.keys(value).length > MAX_KEYS ? ',…' : ''}}`
+    }
+    const out: any = {}
+    for (const key of Object.keys(value)) {
+      out[key] = summarizeToolResult(value[key], depth + 1)
+    }
+    return out
+  }
+  return undefined
+}

package/server/service/index.ts

@@ -4,3 +4,4 @@ export * from './providers/index.js'
 export * from './utils/index.js'
 export * from './tool-registry/index.js'
 export * from './agentic-loop/index.js'
+export * from './assistant/index.js'

package/server/service/tool-registry/registry.test.ts

@@ -26,6 +26,8 @@ afterEach(() => {
 function makeCategory(name: string, specs: Partial<ToolSpec>[]): ToolCategory {
   return {
     name,
+    /* 지침은 필수다(2026-09-09). 픽스처가 그 강제를 우회하지 않도록 여기서도 채운다. */
+    guidance: `- fixture guidance for ${name}`,
     specs: specs.map(s => ({
       kind: 'read' as const,
       name: 'unnamed',
@@ -141,6 +143,7 @@ describe('registry — spec 보존', () => {
     const builder = jest.fn(() => ({ ok: true }))
     registerToolCategory({
       name: 'cat1',
+      guidance: '- fixture guidance for cat1',
       specs: [
         {
           kind: 'read',
@@ -165,6 +168,7 @@ describe('registry — spec 보존', () => {
   test('description / themeNote / schema 보존', () => {
     registerToolCategory({
       name: 'cat1',
+      guidance: '- fixture guidance for cat1',
       specs: [
         {
           kind: 'write',
@@ -196,10 +200,61 @@ describe('getCategoryGuidance — 도구와 함께 가는 사용 규율', () =>
     expect(getCategoryGuidance(undefined)).toEqual(['RULE-A'])
   })
 
-  it('규율이 없는 카테고리는 건너뛴다 — 빈 줄을 프롬프트에 넣지 않는다', () => {
-    registerToolCategory({ name: 'a', specs: [] })
-    registerToolCategory({ name: 'b', guidance: '   ', specs: [] })
+  /*
+   * This test used to register two categories with no guidance and assert they were skipped, so
+   * that no blank line reached the prompt. Registration now refuses them (see the enforcement
+   * block below), which means the skip branch inside `getCategoryGuidance` can no longer be
+   * reached through the registry — it is left in place only so a mutated entry cannot emit a
+   * blank line.
+   *
+   * What is still worth asserting is the outcome that test was protecting: whatever a caller
+   * asks for, the collected guidance never contains an empty string.
+   */
+  it('collected guidance never contains a blank entry', () => {
+    registerToolCategory({ name: 'a', guidance: 'RULE-A', specs: [] })
     registerToolCategory({ name: 'c', guidance: 'RULE-C', specs: [] })
-    expect(getCategoryGuidance(undefined)).toEqual(['RULE-C'])
+
+    for (const collected of [getCategoryGuidance(undefined), getCategoryGuidance(['a']), getCategoryGuidance(['a', 'c'])]) {
+      expect(collected.length).toBeGreaterThan(0)
+      for (const line of collected) expect(line.trim()).not.toBe('')
+    }
+  })
+})
+
+// ── 지침 강제 ────────────────────────────────────────────────────────
+
+describe('registry — 지침 없는 카테고리는 등록되지 않는다', () => {
+  /*
+   * 왜 이 검사가 있나: 도구 목록만 받은 모델이 「언제 반드시 불러야 하는지」를 못 맞힌 사고가 있었다 —
+   * 조치 요청에 `proposeAction` 을 부르지 않고 「제안해 두었습니다」라고 답해 사용자에게 없는 버튼을
+   * 누르라고 안내했다. 규율을 적을 자리는 그 뒤에 생겼지만 **선택이었고**, 그래서 그 사고를 아는
+   * 사람만 채웠다.
+   *
+   * 여기서 재는 것은 「빠지면 거절하는가」다. 거절하지 않으면 이 규율은 다음 새 카테고리까지만 간다.
+   */
+  test('지침이 없으면 던진다', () => {
+    const withoutGuidance = { name: 'no-guidance', specs: [] } as unknown as ToolCategory
+    expect(() => registerToolCategory(withoutGuidance)).toThrow(/no guidance/)
+    expect(getToolCategories()).toEqual([])
+  })
+
+  test('빈 문자열·공백도 거절한다 — 「없음」을 「적었다」로 위장하지 못한다', () => {
+    for (const blank of ['', '   ', '\n\t']) {
+      const category = { name: 'blank', specs: [], guidance: blank } as ToolCategory
+      expect(() => registerToolCategory(category)).toThrow(/no guidance/)
+    }
+    expect(getToolCategories()).toEqual([])
+  })
+
+  test('거절 문장이 무엇을 하라고 말한다 — 이름만 대면 사람이 다시 찾는다', () => {
+    const withoutGuidance = { name: 'no-guidance', specs: [] } as unknown as ToolCategory
+    expect(() => registerToolCategory(withoutGuidance)).toThrow(/when the model must call/)
+    expect(() => registerToolCategory(withoutGuidance)).toThrow(/no-guidance/)
+  })
+
+  test('지침이 있으면 그대로 등록된다', () => {
+    registerToolCategory(makeCategory('ok', [{ name: 'tool1' }]))
+    expect(getToolCategories()).toHaveLength(1)
+    expect(getToolCategories()[0].guidance).toContain('fixture guidance')
   })
 })

package/server/service/tool-registry/registry.ts

@@ -33,6 +33,28 @@ const categories: Map<string, ToolCategory> = new Map()
  * 카테고리 등록. tool name 충돌 시 throw, 이름 중복 등록 시 덮어쓰기 + warn.
  */
 export function registerToolCategory(category: ToolCategory): void {
+  /*
+   * 지침 없는 카테고리는 **등록하지 않는다.**
+   *
+   * 도구 목록만 보낸 모델이 「불러야 할 때 부른다」를 맞히지 못한 사고가 있었다 — 조치 요청에
+   * `proposeAction` 을 부르지 않고 「제안해 두었습니다」라고 답해, 사용자에게 없는 버튼을 누르라고
+   * 안내했다. 화면에는 아무 일도 없었고 오류도 나지 않았다(§`ToolCategory.guidance`).
+   *
+   * 그 뒤로 규율을 적는 자리를 만들었지만 **선택이었다.** 선택인 규율은 그 사고를 아는 사람만
+   * 채운다. 여기서 거절하는 이유가 그것이다 — 빠진 것을 부팅에서 만든 사람이 보고, 모델이 헛말을
+   * 한 뒤에 사용자가 보지 않는다.
+   *
+   * 빈 문자열·공백도 거절한다. 통과시키면 이 검사가 형식이 되고, 형식이 된 검사는 없는 것과 같다.
+   */
+  if (!String(category.guidance ?? '').trim()) {
+    throw new Error(
+      `[ai-client-base/tool-registry] category '${category.name}' has no guidance. ` +
+        'Tool descriptions say what a tool does; guidance says when the model must call one. ' +
+        'Without it a model answers as though it called a tool it did not, and nothing errors. ' +
+        'Write the rules for these tools in `guidance` — the side that registers them owns them.'
+    )
+  }
+
   if (categories.has(category.name)) {
     console.warn(
       `[board-ai/tool-registry] category '${category.name}' already registered — overwriting. ` +

package/server/service/tool-registry/types.ts

@@ -155,6 +155,16 @@ export interface ToolCategory {
    *
    * 규율은 도구를 등록한 쪽이 소유한다. 호스트(board-ai)는 도메인을 모르는 채 **노출된 카테고리의
    * 규율만 모아 붙인다** — 도메인 지식이 호스트 프롬프트로 새지 않는다.
+   *
+   * ── 왜 필수인가 (2026-09-09) ──────────────────────────────────────────────
+   * 선택 필드였다. 그래서 위에 적힌 사고를 아는 사람만 채웠고, 세 제품이 각자 도구를 붙이기
+   * 시작한 지금 **채운 넷과 안 채운 하나**가 있었다.
+   *
+   * 안 채운 쪽은 조용하다 — 등록은 성공하고 부팅도 성공하고, 모델이 도구를 덜 부르거나 지어낸
+   * 뒤에 사람이 화면을 보고 안다. **두 개를 기억해야 성립하는 규칙은 다음 새 카테고리까지만
+   * 간다.** 그래서 기억이 아니라 등록이 거절한다(§`registerToolCategory`).
+   *
+   * 빈 문자열도 거절한다. 「없음」을 「적었다」로 위장하는 값이 통과하면 이 강제가 형식이 된다.
    */
-  guidance?: string
+  guidance: string
 }

package/server/service/utils/grounding.test.ts

@@ -68,3 +68,52 @@ describe('groundingWarnings — 대화면 진입점', () => {
     expect(groundingWarnings('지게차들이 바쁘게 움직이고 있습니다.', corpus)).toEqual([])
   })
 })
+
+/*
+ * ── 대문자 식별자 (2026-09-10) ──────────────────────────────────────────────
+ *
+ * `ID_TOKEN` 이 `[a-z]…` 이던 동안, 대문자 식별자를 쓰는 제품에는 이 가드가 **아예 닿지
+ * 않았다.** plant 의 실제 오더 이름이 `WO-ECU-SET-2609B` 이고, 그것에서 추출되는 토큰이 0 개였다.
+ *
+ * 그 상태의 무서운 점은 조용하다는 것이 아니라 **깨끗해 보인다**는 것이다 — 경고 0 건이 「지어낸
+ * 식별자가 없다」로 읽혔다. 없는 것과 안 보는 것이 같은 그림이었다.
+ *
+ * 이 블록은 그 구멍을 다시 열면 실패한다. 패턴을 소문자로 되돌리고 돌려 확인했다.
+ */
+describe('식별자는 대문자도 본다 — 소문자만 보면 두 제품이 통째로 빠진다', () => {
+  it('근거에 없는 대문자 오더 번호를 경고한다', () => {
+    const warnings = groundingWarnings('WO-ECU-SET-2609B 가 밀렸습니다', '주문 목록: WO-ECU-SET-2601A')
+    expect(warnings.join(' ')).toContain('WO-ECU-SET-2609B')
+  })
+
+  it('근거에 있으면 경고하지 않는다', () => {
+    expect(groundingWarnings('WO-ECU-SET-2609B 가 밀렸습니다', '{"orders":["WO-ECU-SET-2609B"]}')).toEqual([])
+  })
+
+  it('표기만 다른 것은 다른 대상이 아니다 — 대소문자를 무시하고 대조한다', () => {
+    /* 모델이 오더 번호를 소문자로 적는 것은 형식이지 창작이 아니다. 그것을 경고로 만들면
+     * 경고가 소음이 되고, 소음이 되면 사람이 경고 자체를 안 본다. */
+    expect(groundingWarnings('wo-ecu-set-2609b 가 밀렸습니다', '{"orders":["WO-ECU-SET-2609B"]}')).toEqual([])
+    expect(groundingWarnings('WO-ECU-SET-2609B 가 밀렸습니다', '{"orders":["wo-ecu-set-2609b"]}')).toEqual([])
+  })
+
+  it('트윈의 태그도 잡힌다', () => {
+    expect(groundingWarnings('TAG-FUNC-AGING 을 적용했습니다', '가용 태그: TAG-FUNC-WELD').join(' ')).toContain(
+      'TAG-FUNC-AGING'
+    )
+  })
+
+  it('★ 대문자 영어 합성어는 경고가 아니다 — 넓힌 대가로 소음을 사지 않는다', () => {
+    /*
+     * 넓히면서 걱정한 것이 이것이다. `filterEntityLike` 가 뒤에서 거른다 — 숫자도 없고 근거에
+     * 같은 계열도 없다. 이 줄이 깨지면 넓힌 것이 손해다.
+     */
+    for (const reply of ['This is Read-Only for now', 'Hand-Off complete', 'a Follow-Up is needed']) {
+      expect(groundingWarnings(reply, '보드 상태: 컴포넌트 3개')).toEqual([])
+    }
+  })
+
+  it('근거에 같은 계열이 있으면 대문자 합성어도 잡는다 — 같은 계열의 없는 대상', () => {
+    expect(groundingWarnings('DOCK-North 로 보냈습니다', '{"docks":["DOCK-South"]}').join(' ')).toContain('DOCK-North')
+  })
+})