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

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,10 @@
+/*
+ * 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'
+export * from './registry-assistant.js'

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

@@ -0,0 +1,182 @@
+/*
+ * What this guards: **a product with no document of its own gets a working conversation, and only
+ * the tools it can actually run.**
+ *
+ * The gap this closes: the registry half of building a conversation lived inside board-ai, so
+ * operato-figure mounted the dock, registered four tools, and had nothing to call — the only
+ * mutation that could run them was in a package figure does not load.
+ *
+ * The trap on the other side is subtler. A registered category can carry `write` and `action`
+ * tools, which produce edit ops for a document the host owns. A host with no document cannot
+ * apply them, so offering them would put a name in front of the model that leads nowhere. These
+ * tests fix that: offered and dispatchable are the same set, and it is the answering kinds only.
+ */
+import { registryAssistantChat } from './registry-assistant'
+import { clearToolRegistry, registerToolCategory } from '../tool-registry/index.js'
+import type { AIToolCall, AIToolChatResult } from '../types.js'
+
+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)
+
+/** Records what the provider was handed, so the tests can read the offer rather than infer it. */
+function recordingClient(replies: AIToolChatResult[] = [okResult('answered')]) {
+  const seen: Array<{ tools: any[]; options: any }> = []
+  let turn = 0
+  return {
+    seen,
+    client: {
+      chatWithTools: async (_msgs: any, tools: any[], options: any) => {
+        seen.push({ tools, options })
+        return replies[Math.min(turn++, replies.length - 1)]
+      }
+    } as any
+  }
+}
+
+const ran: Array<{ name: string; args: any; context: any }> = []
+
+beforeEach(() => {
+  clearToolRegistry()
+  ran.length = 0
+
+  registerToolCategory({
+    name: 'figure-authoring',
+    guidance: 'Always look at the figure before describing it.',
+    specs: [
+      {
+        kind: 'read',
+        name: 'listFigures',
+        description: 'lists figures',
+        schema: { type: 'object', properties: {} },
+        builder: (args: any, context: any) => {
+          ran.push({ name: 'listFigures', args, context })
+          return { figures: ['roller-conveyor'] }
+        }
+      },
+      {
+        kind: 'write',
+        name: 'addComponent',
+        description: 'adds a component to the document',
+        schema: { type: 'object', properties: {} },
+        builder: () => {
+          ran.push({ name: 'addComponent', args: {}, context: null })
+          return []
+        }
+      }
+    ]
+  } as any)
+
+  registerToolCategory({
+    name: 'plant-ops',
+    guidance: 'Never state a quantity you did not read.',
+    specs: [
+      {
+        kind: 'external',
+        name: 'readOrderState',
+        description: 'reads live order state',
+        schema: { type: 'object', properties: {} },
+        builder: (args: any, context: any) => {
+          ran.push({ name: 'readOrderState', args, context })
+          return { orders: 3 }
+        }
+      }
+    ]
+  } as any)
+})
+
+const input = (over: any = {}) => ({
+  client: recordingClient().client,
+  messages: [{ role: 'user' as const, content: 'what figures do we have' }],
+  systemPrompt: 'you help someone draw a figure',
+  state: { domain: { id: 'dom-1' }, user: { id: 'u-1' } },
+  ...over
+})
+
+describe('what the model is offered', () => {
+  it('★ only the kinds that answer — a write tool is not offered to a surface with no document', async () => {
+    const { client, seen } = recordingClient()
+    await registryAssistantChat(input({ client }))
+
+    const offered = seen[0].tools.map(tool => tool.name)
+    expect(offered).toEqual(expect.arrayContaining(['listFigures', 'readOrderState']))
+    expect(offered).not.toContain('addComponent')
+  })
+
+  it('the category filter narrows the offer', async () => {
+    const { client, seen } = recordingClient()
+    await registryAssistantChat(input({ client, toolCategories: ['figure-authoring'] }))
+
+    expect(seen[0].tools.map(tool => tool.name)).toEqual(['listFigures'])
+  })
+
+  it('an empty category list offers nothing — a plain conversation is a legitimate surface', async () => {
+    const { client, seen } = recordingClient()
+    await registryAssistantChat(input({ client, toolCategories: [] }))
+
+    expect(seen[0].tools).toEqual([])
+  })
+
+  it('the result reports what was offered, so the caller can log it without guessing', async () => {
+    const result = await registryAssistantChat(input({ toolCategories: ['plant-ops'] }))
+    expect(result.offeredTools).toEqual(['readOrderState'])
+  })
+})
+
+describe('the rules for using a tool travel with it', () => {
+  it('★ guidance of the exposed categories reaches the prompt', async () => {
+    const { client, seen } = recordingClient()
+    await registryAssistantChat(input({ client, toolCategories: ['figure-authoring'] }))
+
+    expect(seen[0].options.systemPrompt).toContain('you help someone draw a figure')
+    expect(seen[0].options.systemPrompt).toContain('Always look at the figure before describing it.')
+  })
+
+  it('guidance of a category this conversation cannot call is not read to the model', async () => {
+    const { client, seen } = recordingClient()
+    await registryAssistantChat(input({ client, toolCategories: ['figure-authoring'] }))
+
+    expect(seen[0].options.systemPrompt).not.toContain('Never state a quantity you did not read.')
+  })
+})
+
+describe('running a tool', () => {
+  it('★ the registered builder runs and is handed the caller state and the host context', async () => {
+    const { client } = recordingClient([okResult(undefined, [TC('listFigures', { q: 'roller' })]), okResult('two of them')])
+
+    const result = await registryAssistantChat(
+      input({ client, hostContext: { surface: 'figure-modeller', figureId: 'fig-1' } })
+    )
+
+    expect(ran).toHaveLength(1)
+    expect(ran[0].name).toBe('listFigures')
+    expect(ran[0].args).toEqual({ q: 'roller' })
+    expect(ran[0].context.state.domain.id).toBe('dom-1')
+    expect(ran[0].context.host).toEqual({ surface: 'figure-modeller', figureId: 'fig-1' })
+    expect(result.reply).toContain('two of them')
+  })
+
+  it('★ a write tool call is not executed — the same set decides offering and dispatch', async () => {
+    const { client } = recordingClient([okResult(undefined, [TC('addComponent')]), okResult('cannot do that')])
+
+    await registryAssistantChat(input({ client }))
+
+    expect(ran.map(one => one.name)).not.toContain('addComponent')
+  })
+
+  it('★ a tool outside the allowed categories does not run', async () => {
+    const { client } = recordingClient([okResult(undefined, [TC('readOrderState')]), okResult('done')])
+
+    await registryAssistantChat(input({ client, toolCategories: ['figure-authoring'] }))
+
+    expect(ran.map(one => one.name)).not.toContain('readOrderState')
+  })
+})
+
+describe('a client that cannot call tools', () => {
+  it('★ refuses instead of answering from nothing', async () => {
+    await expect(registryAssistantChat(input({ client: {} as any }))).rejects.toThrow(/cannot call tools/)
+  })
+})

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

@@ -0,0 +1,137 @@
+/*
+ * A conversation for a product that has no editor of its own.
+ *
+ * ── What this is for ───────────────────────────────────────────────────────────
+ * `board-ai` assembles its conversation from two sources: its own board editing tools, and
+ * whatever other packages registered in the tool registry. The second half is the same work for
+ * every product — read the specs, build the definitions, dispatch by name — but it only existed
+ * inside the board assistant, so a product without a board had nowhere to ask a question from.
+ * operato-figure hit exactly that: the dock was mounted, the tools were registered, and the only
+ * mutation that could run them lived in a package figure does not load.
+ *
+ * ── Read and external only ─────────────────────────────────────────────────────
+ * A registry category may also carry `write` and `action` tools. Those produce edit ops for a
+ * document the host owns, and a host with no document cannot apply them. Offering them here would
+ * declare a door with no road behind it — the model would call one and the call would go nowhere.
+ * So this runner offers, and dispatches, `read` and `external` only. A host that owns a document
+ * keeps assembling its own conversation, as board-ai does.
+ *
+ * The gate answers from the same list the definitions are built from, so what is offered and what
+ * may be dispatched cannot drift apart.
+ */
+import type { AIClient, AIMessage } from '../types.js'
+import { getCategoryGuidance, getToolSpecsFor, type ToolCategoryFilter, type ToolSpec } from '../tool-registry/index.js'
+import { assistantChat, type AssistantChatResult } from './assistant-chat.js'
+import { summarizeToolResult } from './summarize.js'
+import type { GroundingSources } from '../utils/index.js'
+
+/** What a registry tool is handed when it runs. `state` is the caller's koa state. */
+export interface RegistryToolCallContext {
+  state: any
+  /** What this surface is looking at — the host passes it through; tools read it as `host`. */
+  host?: any
+}
+
+export interface RegistryAssistantInput {
+  /** Provider client. Must implement `chatWithTools`. */
+  client: AIClient
+  /** The conversation so far, newest last. The caller owns history and truncation. */
+  messages: AIMessage[]
+  /** Who the assistant is and what this surface is. The host owns this prose. */
+  systemPrompt: string
+  /**
+   * Categories this conversation may use. Omit to allow every registered category.
+   *
+   * An empty array is not the same as omitting: it allows nothing, and the conversation runs with
+   * no tools at all. That is a legitimate surface (plain chat), so it is not corrected here.
+   */
+  toolCategories?: string[]
+  /** Passed to tools as `context.host`. Client-supplied — never used for authorization. */
+  hostContext?: any
+  /** Caller's koa state (domain, user, tx). Tools that read the database need it. */
+  state: any
+  model?: string
+  temperature?: number
+  maxTokens?: number
+  /** Make the model call a tool before it may answer. For surfaces that report live state. */
+  requireToolOnFirstTurn?: boolean
+  /** Texts the answer is allowed to draw identifiers from, besides the tool results. */
+  groundingSources?: Omit<GroundingSources, 'toolResults'>
+}
+
+export interface RegistryAssistantResult extends AssistantChatResult<unknown> {
+  /** Tool names actually offered to the model this turn. The caller may log or return it. */
+  offeredTools: string[]
+}
+
+/** `read` and `external` are the two kinds that answer a question without changing a document. */
+function answeringSpecs(filter: ToolCategoryFilter): ToolSpec[] {
+  return getToolSpecsFor(filter).filter(spec => spec.kind === 'read' || spec.kind === 'external')
+}
+
+/**
+ * Run one turn of a conversation whose only tools come from the registry.
+ *
+ * Throws when the client cannot use tools at all — a surface built on registered tools that
+ * silently ran without them would answer from nothing and look like it had checked.
+ */
+export async function registryAssistantChat(input: RegistryAssistantInput): Promise<RegistryAssistantResult> {
+  const { client, messages, systemPrompt, toolCategories, hostContext, state } = input
+
+  if (!client.chatWithTools) {
+    throw new Error('[registry-assistant] the configured AI client cannot call tools, so this conversation cannot run')
+  }
+
+  const filter: ToolCategoryFilter = toolCategories
+  const specs = answeringSpecs(filter)
+  const byName = new Map(specs.map(spec => [spec.name, spec]))
+
+  const tools = specs.map(spec => ({
+    name: spec.name,
+    description: spec.themeNote ? `${spec.description} ${spec.themeNote}` : spec.description,
+    parameters: spec.schema
+  }))
+
+  /*
+   * The rules for using a tool belong to whoever registered it. Collect only the exposed ones, so
+   * a surface never reads instructions for a category it cannot call.
+   */
+  const guidance = getCategoryGuidance(filter)
+  const prompt = guidance.length > 0 ? `${systemPrompt}\n\n${guidance.join('\n\n')}` : systemPrompt
+
+  const toolContext: RegistryToolCallContext = { state, host: hostContext }
+
+  const result = await assistantChat<RegistryToolCallContext, unknown>({
+    initialConversation: messages,
+    tools,
+    options: {
+      systemPrompt: prompt,
+      model: input.model,
+      temperature: input.temperature,
+      maxTokens: input.maxTokens,
+      requireToolOnFirstTurn: input.requireToolOnFirstTurn
+    },
+    chat: (msgs, toolDefs, opts) => client.chatWithTools!(msgs, toolDefs, opts),
+    context: toolContext,
+    dispatch: {
+      isReadTool: name => byName.has(name),
+      /*
+       * This surface has no document, so nothing here can write. Saying so plainly makes the loop
+       * report an unknown name back to the model instead of accepting a call and dropping it.
+       */
+      isWriteTool: () => false,
+      isActionTool: () => false,
+      executeReadTool: (call, context) => {
+        const spec = byName.get(call.name)
+        if (!spec) return undefined
+        return (spec.builder as any)(call.arguments ?? {}, context)
+      },
+      validateWriteToolCall: () => ({ valid: false, errors: ['this conversation has no document to write to'] }),
+      toolCallToOp: () => null,
+      summarizeToolResult
+    },
+    groundingSources: input.groundingSources
+  })
+
+  return { ...result, offeredTools: tools.map(tool => tool.name) }
+}