@things-factory/ai-client-base 10.1.26 → 10.1.28

package/server/service/assistant/abort-notice.ts

@@ -10,35 +10,57 @@
  * and the person acts on half of it. That failure is silent by construction, which is why the
  * notice belongs beside the loop rather than beside each product's prose.
  *
- * ── Known debt: the strings are Korean ─────────────────────────────────────────
- * They were Korean in board-ai and they still are. Moving them does not make that worse, but a
- * framework package is the wrong home for untranslated user-facing text. When this needs a second
- * locale, the shape is a caller-supplied translator, not a table in here — the notice is one line
- * appended to a reply the product already owns.
+ * ── The words are the reader's, and the caller owns the reader (2026-09-18) ────────
+ * These lines were Korean literals in a framework package, so every product said them in Korean
+ * whatever language the person was reading in (ADR-0049 ② · ADR-0054). The notice now names a key
+ * and carries an English default; a caller that has the request's translator hands it in and the
+ * person reads the line in their own language.
  */
 import type { AgenticLoopResult } from '../agentic-loop/index.js'
 import { isTransientAIError } from '../utils/index.js'
 
+/** Turns a key and its values into the reader's sentence. `ai-assistant` hands in the request's `context.t`. */
+export type TranslateNotice = (key: string, params?: Record<string, any>) => string
+
+/** The English sentence for each reason, used when the caller has no translator. */
+const NOTICE_DEFAULTS: Record<string, string> = {
+  'ai-assistant.notice.stopped': 'the request stopped partway, so only part of it was done.',
+  'ai-assistant.notice.provider-busy': 'the ai service did not answer just now. try again in a moment.',
+  'ai-assistant.notice.provider-error': 'something went wrong while handling this. tell an administrator if it keeps happening.',
+  'ai-assistant.notice.too-long': 'this ran long and stopped at step {iter}. try asking in smaller pieces.',
+  'ai-assistant.notice.tool-kept-failing': '{tool} failed {count} times in a row, so it stopped. try saying it differently.'
+}
+
+function line(key: string, params: Record<string, any>, t?: TranslateNotice): string {
+  const said = t
+    ? t(key, { defaultValue: NOTICE_DEFAULTS[key], ...params })
+    : Object.entries(params).reduce((text, [k, v]) => text.replaceAll(`{${k}}`, String(v)), NOTICE_DEFAULTS[key])
+  return `\n\n_(${said})_`
+}
+
 /**
  * 중단 이유 → 답에 덧붙일 한 줄. 정상 종료면 빈 문자열이다.
  *
  * 답을 고치지 않고 **뒤에 붙인다** — 모델이 한 말을 우리가 다시 쓰지 않는다.
  */
-export function formatAbortNotice(abortReason: AgenticLoopResult<any>['abortReason']): string {
+export function formatAbortNotice(
+  abortReason: AgenticLoopResult<any>['abortReason'],
+  t?: TranslateNotice
+): string {
   if (!abortReason) return ''
   switch (abortReason.type) {
     case 'aborted':
-      return '\n\n_(요청이 중단되어 일부만 처리됐어요.)_'
+      return line('ai-assistant.notice.stopped', {}, t)
     case 'provider_error':
       /* 남의 말(SDK 원문)을 사용자에게 보여주지 않는다 — "Error fetching from undefined: [503 …]" 은
        * 사용자가 할 수 있는 일을 알려주지 않는다. 일시 장애는 이미 몇 번 다시 시도한 뒤이므로,
        * 지금 필요한 안내는 "잠시 후 다시" 하나다. 원문은 서버 로그에 남는다. */
       return isTransientAIError({ message: abortReason.message })
-        ? '\n\n_(AI 서비스가 일시적으로 응답하지 않았어요. 잠시 후 다시 시도해 주세요.)_'
-        : '\n\n_(처리 중 오류가 발생했어요. 같은 요청이 계속 실패하면 관리자에게 알려 주세요.)_'
+        ? line('ai-assistant.notice.provider-busy', {}, t)
+        : line('ai-assistant.notice.provider-error', {}, t)
     case 'max_iterations':
-      return `\n\n_(작업이 너무 길어 ${abortReason.iter}회에서 중단했어요. 더 작게 나눠 요청해보세요.)_`
+      return line('ai-assistant.notice.too-long', { iter: abortReason.iter }, t)
     case 'repeated_validation_failure':
-      return `\n\n_(\`${abortReason.toolName}\` 호출이 ${abortReason.consecutive}회 연속 실패해 중단했어요. 요청을 다시 표현해보세요.)_`
+      return line('ai-assistant.notice.tool-kept-failing', { tool: abortReason.toolName, count: abortReason.consecutive }, t)
   }
 }

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

@@ -76,7 +76,7 @@ describe('assistantChat — ① 중단 이유가 답에 닿는다', () => {
       })
     )
     expect(r.loop.abortReason?.type).toBe('provider_error')
-    expect(r.reply).toMatch(/다시/)
+    expect(r.reply).toMatch(/try again in a moment/)
     /* 남의 말(SDK 원문)을 사용자에게 보여주지 않는다. */
     expect(r.reply).not.toMatch(/503/)
     expect(r.reply).not.toMatch(/Error fetching/)
@@ -94,7 +94,29 @@ describe('assistantChat — ① 중단 이유가 답에 닿는다', () => {
       )
     )
     expect(r.loop.abortReason?.type).toBe('max_iterations')
-    expect(r.reply).toMatch(/중단/)
+    /* No translator was handed in, so the line falls back to English. */
+    expect(r.reply).toMatch(/stopped at step 2/)
+  })
+
+  it('★ 통지의 말은 읽는 사람의 것이다 — 번역기를 주면 그것이 쓴 문장이 붙는다', async () => {
+    const asked: any[] = []
+    const r = await assistantChat(
+      input(
+        {
+          options: { systemPrompt: 's', maxIterations: 2 },
+          chat: async () => okResult(undefined, [TC('read1')]),
+          t: (key: string, params: any) => {
+            asked.push({ key, params })
+            return `멈췄습니다(${params.iter}단계)`
+          }
+        },
+        { isReadTool: () => true }
+      )
+    )
+    expect(asked[0].key).toBe('ai-assistant.notice.too-long')
+    expect(asked[0].params.iter).toBe(2)
+    expect(asked[0].params.defaultValue).toMatch(/stopped at step/)
+    expect(r.reply).toContain('멈췄습니다(2단계)')
   })
 
   it('통지는 답을 고치지 않고 뒤에 붙는다', async () => {

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

@@ -36,9 +36,14 @@
  */
 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'
+import { formatAbortNotice, type TranslateNotice } from './abort-notice.js'
 
 export interface AssistantChatInput<TCtx = unknown, TOp = unknown> extends AgenticLoopInput<TCtx, TOp> {
+  /**
+   * The request's translator, so a notice this function appends is in the reader's language
+   * (ADR-0054). Without it the notice falls back to English.
+   */
+  t?: TranslateNotice
   /**
    * 이 턴에 모델이 본 것 — **도구 결과 말고** 전부. 도구 결과는 이 함수가 루프에서 받아 더한다.
    *
@@ -86,7 +91,7 @@ export async function assistantChat<TCtx = unknown, TOp = unknown>(
   const loop = await runAgenticLoop<TCtx, TOp>(loopInput)
 
   const baseText = loop.lastText ?? ''
-  const reply = baseText + formatAbortNotice(loop.abortReason)
+  const reply = baseText + formatAbortNotice(loop.abortReason, input.t)
 
   let warnings: string[] | undefined
   if (!skipGrounding && baseText) {

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

@@ -56,6 +56,8 @@ export interface RegistryAssistantInput {
   maxTokens?: number
   /** Make the model call a tool before it may answer. For surfaces that report live state. */
   requireToolOnFirstTurn?: boolean
+  /** The request's translator — the stop notice is then in the reader's language. */
+  t?: (key: string, params?: Record<string, any>) => string
   /** Texts the answer is allowed to draw identifiers from, besides the tool results. */
   groundingSources?: Omit<GroundingSources, 'toolResults'>
 }
@@ -135,7 +137,8 @@ export async function registryAssistantChat(input: RegistryAssistantInput): Prom
       toolCallToOp: () => null,
       summarizeToolResult
     },
-    groundingSources: input.groundingSources
+    groundingSources: input.groundingSources,
+    t: input.t
   })
 
   return { ...result, offeredTools: tools.map(tool => tool.name) }

package/server/service/capability.test.ts

@@ -0,0 +1,52 @@
+/*
+ * What this guards: a screen can ask whether this deployment has an AI, instead of finding out by
+ * pressing a button that fails.
+ *
+ * The defect this replaces: twin decided the same question from whether a mutation had thrown once.
+ * The mutation stopped being called, the flag stayed true, and deployments with no provider showed
+ * the button anyway (standard A7-a).
+ */
+const mockConfigGet = jest.fn()
+jest.mock('@things-factory/env', () => ({ config: { get: (...args: any[]) => mockConfigGet(...args) } }))
+
+import { aiCapability } from './capability'
+import { registerAIProvider, setDefaultAIClient } from './factory'
+
+beforeEach(() => {
+  mockConfigGet.mockReset()
+  setDefaultAIClient(undefined as any)
+})
+
+it('★ a configured deployment says so, and names what answers', () => {
+  mockConfigGet.mockReturnValue(null)
+  setDefaultAIClient({ id: 'anthropic:claude-sonnet-5' } as any)
+
+  expect(aiCapability()).toEqual({ state: 'configured', provider: 'anthropic', model: 'claude-sonnet-5' })
+})
+
+it('★ no configuration at all is "not configured", with the reason — never silence', () => {
+  mockConfigGet.mockReturnValue(null)
+
+  expect(aiCapability()).toEqual({ state: 'not-configured', reason: 'no-config' })
+})
+
+it('a configuration naming a provider nobody registered says which one', () => {
+  mockConfigGet.mockReturnValue({ provider: 'nonesuch', model: 'x' })
+
+  expect(aiCapability()).toEqual({ state: 'not-configured', provider: 'nonesuch', reason: 'unknown-provider' })
+})
+
+it('a configuration with no provider field is its own reason', () => {
+  mockConfigGet.mockReturnValue({ model: 'x' })
+
+  expect(aiCapability()).toEqual({ state: 'not-configured', reason: 'no-provider' })
+})
+
+it('★ a provider whose adapter throws is not configured — it does not throw at the caller', () => {
+  registerAIProvider('explodes', () => {
+    throw new Error('no api key')
+  })
+  mockConfigGet.mockReturnValue({ provider: 'explodes', model: 'x' })
+
+  expect(aiCapability()).toEqual({ state: 'not-configured', provider: 'explodes', model: 'x', reason: 'no-adapter' })
+})

package/server/service/capability.ts

@@ -0,0 +1,58 @@
+/**
+ * Is there an AI on this deployment, and what is missing — asked before anything is tried.
+ *
+ * The twin had a button that asked the assistant, and whether to show it was decided by whether a
+ * now-dead mutation had failed once. When the dock moved to the neutral door nothing called that
+ * mutation any more, so the answer was "configured" forever: the button appeared on deployments
+ * with no provider at all and failed when pressed (standard A7-a).
+ *
+ * A capability is read, not discovered by failing (ADR-0042 decision ②). It lives here because the
+ * provider configuration does, and the answer has three states — the third is the one a screen
+ * must not fold away: **not asked yet** is not "configured".
+ */
+import { config as envConfig } from '@things-factory/env'
+
+import { getDefaultAIClient, listRegisteredProviders } from './factory.js'
+
+export type AiCapabilityState = 'configured' | 'not-configured'
+
+export interface AiCapability {
+  state: AiCapabilityState
+  /** Which provider answers, when one does — for the person reading a boot log, not for a screen. */
+  provider?: string
+  /** The default model this deployment would use. */
+  model?: string
+  /** Why it is not configured, as a code: no-config · no-provider · unknown-provider · no-adapter. */
+  reason?: string
+}
+
+/**
+ * What this server can do, as of now.
+ *
+ * Creating the client is what proves a provider adapter is loaded and the configuration parses, so
+ * this asks for it. It never throws: a deployment with no AI is a normal deployment.
+ */
+export function aiCapability(): AiCapability {
+  const client = safeDefaultClient()
+  if (client) {
+    const [provider, model] = String(client.id ?? '').split(':')
+    return { state: 'configured', provider: provider || undefined, model: model || undefined }
+  }
+
+  const cfg = envConfig.get('aiClient', null) as { provider?: string; model?: string } | null
+  if (!cfg) return { state: 'not-configured', reason: 'no-config' }
+  if (!cfg.provider) return { state: 'not-configured', reason: 'no-provider' }
+  if (!listRegisteredProviders().includes(cfg.provider)) {
+    return { state: 'not-configured', provider: cfg.provider, reason: 'unknown-provider' }
+  }
+  return { state: 'not-configured', provider: cfg.provider, model: cfg.model, reason: 'no-adapter' }
+}
+
+function safeDefaultClient() {
+  try {
+    return getDefaultAIClient()
+  } catch {
+    /* A broken configuration is "not configured", and it is the reason below that says which. */
+    return undefined
+  }
+}

package/server/service/index.ts

@@ -6,4 +6,6 @@ export * from './tool-registry/index.js'
 export * from './agentic-loop/index.js'
 export * from './assistant/index.js'
 export * from './analysis-contract.js'
+/* 「이 배포에 AI 가 있나」 — 시도해서 알아내지 않고 먼저 읽는다(표준 A7-a). */
+export * from './capability.js'
 export * from './testing/tool-call-context.js'

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

@@ -292,11 +292,52 @@ describe('registry — a tool that changes something names its door (A1, stage o
     expect(getToolRegistryWarnings().map(w => w.params.tool)).toEqual(['halfDoor'])
   })
 
-  test('a declared tool and a read tool leave no warning', () => {
-    registerToolCategory(makeCategory('declared', [{ name: 'w1', kind: 'write' }, { name: 'r1', kind: 'read' }]))
+  test('a declared tool leaves no warning', () => {
+    registerToolCategory(makeCategory('declared', [{ name: 'w1', kind: 'write' }]))
     expect(getToolRegistryWarnings()).toEqual([])
   })
 
+  /*
+   * 읽는 도구도 자기가 닿는 문을 말한다(ADR-0071 결정 2). 그전까지 업무 권한을 스스로 확인하는 것은
+   * plant 뿐이었고, twin · figure 의 읽는 도구는 테넌트만 봤다 — 대화 문 권한만 있으면 그 자료를 읽었다.
+   */
+  test('★ a read tool that says nothing about its door is recorded too', () => {
+    registerToolCategory(makeCategory('reads', [{ name: 'r1', kind: 'read' }]))
+
+    expect(getToolRegistryWarnings()).toEqual([
+      expect.objectContaining({ code: 'tool-privilege-undeclared', params: { category: 'reads', tool: 'r1', kind: 'read' } })
+    ])
+  })
+
+  test('★ `doors: []` is an answer — a tool that reaches no door has nothing to gate', () => {
+    registerToolCategory({
+      name: 'surface-only',
+      guidance: '- fixture guidance for surface-only',
+      specs: [
+        { kind: 'read', name: 'getOpenScene', description: 'd', schema: {}, builder: () => null, doors: [] } as any
+      ]
+    })
+
+    expect(getToolRegistryWarnings()).toEqual([])
+  })
+
+  test('★ a named door with no privilege of its own is its own fact, not an omission', () => {
+    registerToolCategory({
+      name: 'waiting',
+      guidance: '- fixture guidance for waiting',
+      specs: [
+        { kind: 'read', name: 'twinNowTool', description: 'd', schema: {}, builder: () => null, doors: ['Query.twinNow'] } as any
+      ]
+    })
+
+    expect(getToolRegistryWarnings()).toEqual([
+      expect.objectContaining({
+        code: 'tool-door-has-no-privilege',
+        params: { category: 'waiting', tool: 'twinNowTool', kind: 'read', doors: ['Query.twinNow'] }
+      })
+    ])
+  })
+
   test('re-registering a category replaces its warnings instead of piling them up', () => {
     const undeclared = { kind: 'write', name: 'w9', description: 'd', schema: {}, builder: () => null } as any
     registerToolCategory({ name: 'again', guidance: '- g', specs: [undeclared] })

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

@@ -31,8 +31,14 @@ const categories: Map<string, ToolCategory> = new Map()
 
 /** A registration that was accepted but is not yet what the contract requires. Code + params, not prose. */
 export interface ToolRegistryWarning {
-  code: 'tool-privilege-undeclared'
-  params: { category: string; tool: string; kind: ToolSpec['kind'] }
+  /**
+   * `tool-privilege-undeclared` — nothing said which door this tool reaches.
+   * `tool-door-has-no-privilege` — the door was named and it declares no privilege of its own yet
+   *   (twin's queries, waiting on AUTH stage two). The tool cannot be stricter than its door, so
+   *   this is a different fact from saying nothing, and the report keeps the two apart.
+   */
+  code: 'tool-privilege-undeclared' | 'tool-door-has-no-privilege'
+  params: { category: string; tool: string; kind: ToolSpec['kind']; doors?: string[] }
   /** For a person reading it; the code and params are what callers act on. */
   message: string
 }
@@ -90,21 +96,44 @@ export function registerToolCategory(category: ToolCategory): void {
    */
   warnings.splice(0, warnings.length, ...warnings.filter(w => w.params.category !== category.name))
   for (const spec of category.specs) {
-    if (spec.kind !== 'read' && !(spec.privilege?.category && spec.privilege?.privilege)) {
+    const declared = Boolean(spec.privilege?.category && spec.privilege?.privilege)
+    if (declared) continue
+
+    /*
+     * An empty list says this tool reaches no door — the ones that hand back what the surface sent
+     * are that. Nothing to gate, nothing to report.
+     */
+    if (Array.isArray(spec.doors) && spec.doors.length === 0) continue
+
+    if (spec.doors?.length) {
+      /*
+       * The door is named and carries no privilege yet. The tool cannot be stricter than the door
+       * it reaches, so this is not an omission by whoever wrote the tool — it is the door's turn
+       * (ADR-0071 decision 2). Reported under its own code so the two are not read as one list.
+       */
       warnings.push({
-        code: 'tool-privilege-undeclared',
-        params: { category: category.name, tool: spec.name, kind: spec.kind },
+        code: 'tool-door-has-no-privilege',
+        params: { category: category.name, tool: spec.name, kind: spec.kind, doors: spec.doors },
         message:
-          `tool '${spec.name}' in category '${category.name}' is '${spec.kind}' but declares no privilege — ` +
-          'declare the same { category, privilege } its GraphQL door uses'
+          `tool '${spec.name}' reaches ${spec.doors.join(' + ')}, which declare no privilege — ` +
+          'the tool is as open as the doors it reaches until they declare one'
       })
+      continue
     }
+
+    warnings.push({
+      code: 'tool-privilege-undeclared',
+      params: { category: category.name, tool: spec.name, kind: spec.kind },
+      message:
+        `tool '${spec.name}' in category '${category.name}' says nothing about the doors it reaches — ` +
+        "declare `doors` with the same { category, privilege } those doors use, or `doors: []` when it reaches none"
+    })
   }
 
   if (categories.has(category.name)) {
     console.warn(
       `[board-ai/tool-registry] category '${category.name}' already registered — overwriting. ` +
-        `(dev hot-reload 시 정상이지만 운영 환경에서 발생하면 buildup bug)`
+        '(normal on a dev hot reload; in production it means the same category is registered twice)'
     )
   }
 

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

@@ -155,10 +155,35 @@ export interface ToolSpecBase {
    * The privilege a caller needs before this tool is offered or run. See `ToolPrivilege`.
    *
    * Expected for `write`, `action` and `external` — registration records a
-   * `tool-privilege-undeclared` warning for one without it (A1 stage one). A `read` tool without it is
-   * offered on domain membership alone, and its builder must check what it reads.
+   * `tool-privilege-undeclared` warning for one without it (A1 stage one).
    */
   privilege?: ToolPrivilege
+
+  /**
+   * Which GraphQL doors this tool reaches — `['Query.twinNow']`,
+   * `['Query.productionSummary', 'Query.pendingSummary']`.
+   *
+   * **A read tool names its doors too** (ADR-0071 decision 2, shaped by ADR-0072). Before that,
+   * only plant's tools asked whether the caller may read what they read; twin's and figure's
+   * checked the tenant and nothing else, so holding the conversation's own privilege was enough to
+   * reach their business data.
+   *
+   * **Always a list, even for one** — one shape to read. A tool that answers from several doors
+   * needs the caller to hold **all** of them (AND, the same reading as AUTH's `requiresAll`):
+   * plant's factory overview answers from two, and asking for only one of them would hand back
+   * half of what the caller may not see.
+   *
+   * Three states, and the boot report keeps them apart:
+   *   - doors and a privilege — the gate checks it
+   *   - `doors: []` — this tool reaches no door at all. The ones that hand back what the surface
+   *     sent (`getOpenScene`, `getStationScreen`) are this: there is nothing behind them to gate.
+   *   - doors with no privilege — the doors themselves declare none yet (twin's queries, waiting
+   *     on AUTH stage two). A tool cannot be stricter than the door it reaches.
+   *
+   * The privilege is **the door's**, copied, and a test in each app compares the copy with the
+   * directive on that field. When the schema can be read at boot, the copy goes away.
+   */
+  doors?: string[]
 }
 
 export interface ReadToolSpec extends ToolSpecBase {