@things-factory/ai-client-base 10.1.167 → 10.1.169

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/ai-client-base",
-  "version": "10.1.167",
+  "version": "10.1.169",
   "main": "dist-server/index.js",
   "things-factory": true,
   "author": "heartyoh",
@@ -30,5 +30,5 @@
     "@things-factory/shell": "^10.1.165",
     "openai": "^4.0.0"
   },
-  "gitHead": "86283c5d35042880be6827f777067fc5e6417eed"
+  "gitHead": "9d71d02b443f3e0080b25de1768b982c51a64111"
 }

package/server/service/agentic-loop/agentic-loop.test.ts

@@ -431,6 +431,82 @@ describe('runAgenticLoop — error boundary (provider 예외)', () => {
   })
 })
 
+/*
+  A read tool that throws is the tool's answer, not the end of the turn (figure audit 2026-10-16 N1): the model reads why
+  and says it, or tries another way. Before, the exception left the loop and the whole turn failed with the raw message.
+*/
+describe('runAgenticLoop — a read tool that throws', () => {
+  test('the reason goes back to the model as an error result, and the turn goes on', async () => {
+    const sent: any[][] = []
+    let calls = 0
+    const input = mkInput(
+      {
+        chat: async (messages: any[]) => {
+          sent.push(JSON.parse(JSON.stringify(messages)))
+          calls++
+          return calls === 1 ? okResult(undefined, [TC('proposeThing')]) : okResult('It could not be made: the face is wrong.')
+        }
+      },
+      {
+        isReadTool: () => true,
+        executeReadTool: async () => {
+          throw new Error('The figure could not be made.\nATTACH_FACE: steps[4]')
+        }
+      }
+    )
+    const r = await runAgenticLoop(input)
+    expect(r.abortReason).toBeUndefined()
+    expect(r.lastText).toBe('It could not be made: the face is wrong.')
+    const result = sent[1]!.at(-1)!.content.find((part: any) => part.type === 'tool_result')
+    expect(result.isError).toBe(true)
+    expect(JSON.parse(result.content)).toEqual({ error: 'TOOL_FAILED', message: 'The figure could not be made.\nATTACH_FACE: steps[4]' })
+    expect(r.toolUsages).toMatchObject([{ name: 'proposeThing', kind: 'read', outcome: 'error' }])
+  })
+
+  test('the same tool failing turn after turn stops at the limit, as a write that keeps failing does', async () => {
+    let calls = 0
+    const input = mkInput(
+      {
+        options: { systemPrompt: 'x', repeatedFailureLimit: 3 },
+        chat: async () => {
+          calls++
+          return okResult(undefined, [TC('proposeThing', {}, `t${calls}`)])
+        }
+      },
+      {
+        isReadTool: () => true,
+        executeReadTool: () => {
+          throw new Error('no agent')
+        }
+      }
+    )
+    const r = await runAgenticLoop(input)
+    expect(r.abortReason).toMatchObject({ type: 'repeated_validation_failure', toolName: 'proposeThing', consecutive: 3 })
+    expect(calls).toBe(3)
+  })
+
+  test('a stop the person asked for while the tool ran is still a stop', async () => {
+    const ctrl = new AbortController()
+    const input = mkInput(
+      {
+        options: { systemPrompt: 'x', signal: ctrl.signal },
+        chat: async () => okResult(undefined, [TC('proposeThing')])
+      },
+      {
+        isReadTool: () => true,
+        executeReadTool: () => {
+          ctrl.abort()
+          const err = new Error('aborted')
+          ;(err as any).name = 'AbortError'
+          throw err
+        }
+      }
+    )
+    const r = await runAgenticLoop(input)
+    expect(r.abortReason).toMatchObject({ type: 'aborted' })
+  })
+})
+
 describe('runAgenticLoop — AbortSignal', () => {
   test('이미 abort 된 신호 — 첫 iteration 도 안 돔', async () => {
     const ctrl = new AbortController()

package/server/service/agentic-loop/agentic-loop.ts

@@ -472,6 +472,9 @@ function stableStringify(value: any): string {
  * 다른 tool 이 fail 하면 시퀀스 새로 시작 (전혀 다른 패턴이라).
  * tool 이 succeed 하면 카운터 reset.
  */
+/** What a read tool that threw answers, in place of its result. */
+export const TOOL_FAILED = 'TOOL_FAILED'
+
 function detectRepeatedValidationFailure(
   newUsages: ToolUsage[],
   lastFailedToolName: string | undefined,
@@ -483,9 +486,11 @@ function detectRepeatedValidationFailure(
   consecutive: number
   lastFailedToolName: string | undefined
 } {
-  // 이번 iteration 에서 실패한 write tool 들 (validation 거절)
+  // 이번 iteration 에서 실패한 write tool 들 (validation 거절), and read tools that threw
   const failed = newUsages.filter(
-    u => u.kind === 'write' && (u.result as any)?.error === 'Tool args failed validation'
+    u =>
+      (u.kind === 'write' && (u.result as any)?.error === 'Tool args failed validation') ||
+      (u.kind === 'read' && (u.result as any)?.error === TOOL_FAILED)
   )
 
   if (failed.length === 0) {
@@ -540,11 +545,25 @@ async function processToolCalls<TCtx, TOp>(
 
   for (const tc of toolCalls) {
     if (dispatch.isReadTool(tc.name)) {
+      /*
+       * A tool that throws has answered: the model reads why, and says it or tries another way (figure audit
+       * 2026-10-16 N1). Left to rise, the exception ended the whole turn and the person saw its raw message instead of
+       * an answer. A stop asked for while the tool ran is still seen at the top of the next iteration.
+       */
+      let executed: any
+      try {
+        executed = await dispatch.executeReadTool(tc, context)
+      } catch (e: any) {
+        const failure = { error: TOOL_FAILED, message: String(e?.message ?? e) }
+        toolResultParts.push({ type: 'tool_result', toolUseId: tc.id, content: JSON.stringify(failure), isError: true })
+        toolUsages.push({ name: tc.name, arguments: tc.arguments ?? {}, result: failure, kind: 'read', iter, outcome: 'error' })
+        continue
+      }
       /* await 필수 — registry 에 등록된 read/external builder 는 async 일 수 있다(DB·외부 호출).
        * await 없이 JSON.stringify 하면 Promise 가 '{}' 로 직렬화되어 LLM 이 **빈 결과**를 받는다
        * (문서 가져오기·트윈 구조 조회 등 — 무엇인지는 부르는 쪽이 안다). */
       /* Pictures a read tool hands back ride as image parts after the results - never inside the JSON. */
-      const { value: given, images } = takeToolImages(await dispatch.executeReadTool(tc, context))
+      const { value: given, images } = takeToolImages(executed)
       toolResultImages.push(...images)
       /* What only the card needs (a table of a thousand rows) goes to the screen, never to the model. */
       const { value, forScreen } = takeForScreen(given)

package/server/service/assistant/open-subject.ts

@@ -96,6 +96,9 @@ function quoted(name: string): string {
   return `"${plain(name, NAME_LIMIT).replace(/"/g, "'")}"`
 }
 
+/** A name put before the model as data: in quotes, on one line, without control characters, cut short (above). */
+export const quotedName = quoted
+
 /**
  * The line for this turn, or `undefined` when the conversation is about nothing in particular (`none`, or no
  * anchor). A subject that cannot be read is said to be unreadable - the model must not fill in a name.

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

@@ -12,7 +12,7 @@
  * tests fix that: offered and dispatchable are the same set, and it is the answering kinds only.
  */
 import { registryAssistantChat, REGISTRY_MAX_ITERATIONS } from './registry-assistant'
-import { clearToolRegistry, registerToolCategory } from '../tool-registry/index.js'
+import { clearToolCallRecorders, clearToolRegistry, registerToolCallRecorder, registerToolCategory, type ToolCallRecord } from '../tool-registry/index.js'
 import { toolCallContextFixture } from '../testing/tool-call-context.js'
 import type { AIToolCall, AIToolChatResult } from '../types.js'
 
@@ -376,3 +376,135 @@ describe('a question that needs many lookups', () => {
     expect(result.reply).toBe('found two; the third is missing')
   })
 })
+
+/*
+ * 도구가 사람이 읽는 글을 쓸 번역기와, 서버가 확인한 이번 턴의 파일 — ADR-0061 2026-10-16 판정 1·2.
+ *
+ * 둘 다 없던 칸이다. 그래서 도구는 카드 제목을 한국어로 박았고(`figure-tools.ts`), 데이터 읽기의
+ * `wordsOf` 는 `context.t` 를 읽었지만 채우는 문이 없어 늘 폴백을 냈다. 첨부는 바깥 대화에만 붙고
+ * 도구에는 `host` 만 갔으므로, 도형 생성기는 사람이 올린 그림을 받지 못했다.
+ */
+describe('the request translator and the checked attachments (ADR-0061, 2026-10-16)', () => {
+  const PNG = { id: 'att-1', name: 'sketch.png', kind: 'image' as const, mediaType: 'image/png', size: 4, data: Buffer.from([1, 2, 3, 4]) }
+
+  it('★ the request translator reaches the tool as context.t — the one the caller built', async () => {
+    const { client } = recordingClient([okResult(undefined, [TC('listFigures')]), okResult('ok')])
+    const t = (key: string) => `ko:${key}`
+
+    await registryAssistantChat(input({ client, toolCategories: ['figure-authoring'], t }))
+
+    expect(ran[0].context.t).toBe(t)
+  })
+
+  it('★ without one, the tool still has a translator — it writes the English default value, placeholders filled', async () => {
+    const { client } = recordingClient([okResult(undefined, [TC('listFigures')]), okResult('ok')])
+
+    await registryAssistantChat(input({ client, toolCategories: ['figure-authoring'] }))
+
+    expect(ran[0].context.t('figure.label', { name: 'Mixer', defaultValue: 'Make {name}' })).toBe('Make Mixer')
+    /* No default value: the key comes back, so a reader such as `wordsOf` knows nothing was translated. */
+    expect(ran[0].context.t('figure.label')).toBe('figure.label')
+  })
+
+  it('★ a translator in the host context is not the one a tool gets — the server builds it', async () => {
+    const { client } = recordingClient([okResult(undefined, [TC('listFigures')]), okResult('ok')])
+    const fromClient = () => 'from the client'
+
+    await registryAssistantChat(input({ client, toolCategories: ['figure-authoring'], hostContext: { t: fromClient } }))
+
+    expect(ran[0].context.t).not.toBe(fromClient)
+  })
+
+  it('★ the checked attachments reach the tool in their own field, never mixed into host', async () => {
+    const { client } = recordingClient([okResult(undefined, [TC('listFigures')]), okResult('ok')])
+
+    await registryAssistantChat(
+      input({ client, toolCategories: ['figure-authoring'], hostContext: { figureId: 'fig-1' }, attachments: [PNG] })
+    )
+
+    expect(ran[0].context.attachments).toEqual([PNG])
+    expect(ran[0].context.host).toEqual({ figureId: 'fig-1' })
+  })
+
+  it('★ files the client put in the host context are not attachments', async () => {
+    const { client } = recordingClient([okResult(undefined, [TC('listFigures')]), okResult('ok')])
+
+    await registryAssistantChat(
+      input({ client, toolCategories: ['figure-authoring'], hostContext: { image: { data: 'AAAA', mediaType: 'image/png' }, attachments: [PNG] } })
+    )
+
+    expect(ran[0].context.attachments).toEqual([])
+  })
+
+  it('the shared fixture builds the same shape the door hands — translator and attachments included', async () => {
+    const { client } = recordingClient([okResult(undefined, [TC('listFigures')]), okResult('ok')])
+    const t = (key: string) => key
+    const state = { domain: { id: 'dom-1' }, user: { id: 'u-1' } }
+
+    await registryAssistantChat(input({ client, state, toolCategories: ['figure-authoring'], t, attachments: [PNG] }))
+
+    expect(ran[0].context).toEqual(toolCallContextFixture({ domainId: 'dom-1', userId: 'u-1', t, attachments: [PNG] }))
+  })
+})
+
+describe('every call is handed to the recorders', () => {
+  const recorded: Array<{ record: ToolCallRecord; context: any }> = []
+  beforeEach(() => {
+    clearToolCallRecorders()
+    recorded.length = 0
+    registerToolCallRecorder((record, context) => {
+      recorded.push({ record, context })
+    })
+    registerToolCategory({
+      name: 'ledger',
+      guidance: 'Read the ledger before saying a balance.',
+      specs: [
+        {
+          kind: 'read',
+          name: 'readBrokenLedger',
+          description: 'a list whose query fails',
+          doors: ['Query.ledger'],
+          schema: { type: 'object', properties: {} },
+          builder: () => {
+            throw new Error('the ledger could not be read')
+          }
+        }
+      ]
+    } as any)
+  })
+  afterAll(() => clearToolCallRecorders())
+
+  it('★ the tool, its category, what it was called with and what came back - with the conversation it ran in', async () => {
+    const { client } = recordingClient([okResult(undefined, [TC('readOrderState', { line: 'L1' })]), okResult('three orders')])
+    await registryAssistantChat(input({ client, toolCategories: ['plant-ops'], mode: { kind: 'plant.station' } }))
+    expect(recorded).toHaveLength(1)
+    expect(recorded[0].record).toMatchObject({ tool: 'readOrderState', category: 'plant-ops', args: { line: 'L1' }, result: { orders: 3 } })
+    expect(recorded[0].record.error).toBeUndefined()
+    expect(recorded[0].context.mode).toEqual({ kind: 'plant.station' })
+    expect(recorded[0].context.state.domain.id).toBe('dom-1')
+  })
+
+  it('★ a tool that throws is recorded with why, and the model is still told', async () => {
+    const { client } = recordingClient([okResult(undefined, [TC('readBrokenLedger')]), okResult('could not read it')])
+    const result = await registryAssistantChat(input({ client, toolCategories: ['ledger'] }))
+    expect(recorded.map(one => one.record)).toEqual([expect.objectContaining({ tool: 'readBrokenLedger', category: 'ledger', error: 'the ledger could not be read' })])
+    expect(recorded[0].record.result).toBeUndefined()
+    expect(result.reply).toContain('could not read it')
+  })
+
+  it('a recorder that fails does not stop the answer', async () => {
+    registerToolCallRecorder(() => {
+      throw new Error('audit table missing')
+    })
+    const { client } = recordingClient([okResult(undefined, [TC('readOrderState')]), okResult('three orders')])
+    const result = await registryAssistantChat(input({ client, toolCategories: ['plant-ops'] }))
+    expect(result.reply).toContain('three orders')
+    expect(recorded).toHaveLength(1)
+  })
+
+  it('a tool that was not offered is not run, so nothing is recorded', async () => {
+    const { client } = recordingClient([okResult(undefined, [TC('readOrderState')]), okResult('done')])
+    await registryAssistantChat(input({ client, toolCategories: ['figure-authoring'] }))
+    expect(recorded).toHaveLength(0)
+  })
+})

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

@@ -25,7 +25,9 @@ import { narrowToolScope, resolveToolScope, toolScopeGuidance, type ToolAccessCh
 import { assistantChat, type AssistantChatResult } from './assistant-chat.js'
 import { summarizeToolResult } from './summarize.js'
 import type { GroundingSources } from '../utils/index.js'
-import type { ToolCallContext } from '../tool-registry/types.js'
+import type { ToolAttachment, ToolCallContext } from '../tool-registry/types.js'
+import { defaultValueTranslate } from '../tool-registry/translate.js'
+import { recordToolCall } from '../tool-registry/call-recorder.js'
 
 
 /** Lookups a registry conversation may take before it answers from what it has (operato-twin's assistant takes 16 too). */
@@ -67,8 +69,17 @@ 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. */
+  /**
+   * The request's translator — the stop notice is then in the reader's language, and tools write what a person
+   * reads with it (`context.t`). Without it tools get `defaultValueTranslate`: the English default values.
+   */
   t?: (key: string, params?: Record<string, any>) => string
+  /**
+   * The files sent with this turn, after the caller's server checked them — stored with this conversation, the
+   * conversation the caller's to write, the mode's policy met (ADR-0061, 2026-10-16 decision 2). Tools see them as
+   * `context.attachments`. Never built from the client's request: what a client puts in `hostContext` stays there.
+   */
+  attachments?: ToolAttachment[]
   /** Texts the answer is allowed to draw identifiers from, besides the tool results. */
   groundingSources?: Omit<GroundingSources, 'toolResults'>
 }
@@ -103,6 +114,7 @@ export async function registryAssistantChat(input: RegistryAssistantInput): Prom
   )
   const specs = scope.specs
   const byName = new Map(specs.map(spec => [spec.name, spec]))
+  const categoryOf = new Map(scope.categories.flatMap(category => category.specs.map(spec => [spec.name, category.name] as [string, string])))
 
   const tools = specs.map(spec => ({
     name: spec.name,
@@ -121,7 +133,14 @@ export async function registryAssistantChat(input: RegistryAssistantInput): Prom
    * `mode` 는 서버의 값이다 — 등록된 모드에서 왔고, `host` 와 달리 클라이언트가 못 고친다. A2 가 서기
    * 전에는 채울 것이 없어 비워 두었다(ADR-0061 결정 3 의 주석). 이제 부르는 쪽이 들고 있다.
    */
-  const toolContext: ToolCallContext = { state, host: hostContext ?? {}, ...(input.mode ? { mode: input.mode } : {}) }
+  const toolContext: ToolCallContext = {
+    state,
+    host: hostContext ?? {},
+    ...(input.mode ? { mode: input.mode } : {}),
+    /* 번역기와 첨부는 서버의 값이다 — `host` 에서 받지 않는다(ADR-0061 2026-10-16 판정 1·2). */
+    t: input.t ?? defaultValueTranslate,
+    attachments: input.attachments ?? []
+  }
 
   const result = await assistantChat<ToolCallContext, unknown>({
     initialConversation: messages,
@@ -149,10 +168,21 @@ export async function registryAssistantChat(input: RegistryAssistantInput): Prom
        */
       isWriteTool: () => false,
       isActionTool: () => false,
-      executeReadTool: (call, context) => {
+      /* Every call is handed to the recorders - an application's audit sees the tools other packages declared too. */
+      executeReadTool: async (call, context) => {
         const spec = byName.get(call.name)
         if (!spec) return undefined
-        return (spec.builder as any)(call.arguments ?? {}, context)
+        const args = call.arguments ?? {}
+        const started = Date.now()
+        const record = { tool: spec.name, category: categoryOf.get(spec.name) ?? '', args }
+        try {
+          const result = await (spec.builder as any)(args, context)
+          await recordToolCall({ ...record, result, durationMs: Date.now() - started }, context)
+          return result
+        } catch (e) {
+          await recordToolCall({ ...record, error: String((e as Error)?.message ?? e), durationMs: Date.now() - started }, context)
+          throw e
+        }
       },
       validateWriteToolCall: () => ({ valid: false, errors: ['this conversation has no document to write to'] }),
       toolCallToOp: () => null,

package/server/service/providers/anthropic.ts

@@ -39,6 +39,11 @@ export class AnthropicAIClient implements AIClient {
   }
 
   async chat(messages: AIMessage[], options: AIChatOptions = {}): Promise<string> {
+    return extractResponseText(await this.send(messages, options))
+  }
+
+  /** One request, the provider's response as it came: `generateJSON` reads whether it stopped at the output limit. */
+  private async send(messages: AIMessage[], options: AIChatOptions): Promise<any> {
     const systemFromMessages = messages
       .filter(m => m.role === 'system')
       .map(extractTextContent)
@@ -59,8 +64,7 @@ export class AnthropicAIClient implements AIClient {
       messages: conversation
     } as any)
     reportUsage(response, options, options.model ?? this.defaultModel)
-
-    return extractResponseText(response)
+    return response
   }
 
   async generateJSON<T = unknown>(
@@ -78,8 +82,8 @@ export class AnthropicAIClient implements AIClient {
       'Return only valid JSON. No markdown code fences, no commentary.' +
       schemaHint
 
-    const text = await this.chat(messages, { ...options, systemPrompt: enforcedSystem })
-    return parseJSONResponse<T>(text)
+    const response = await this.send(messages, { ...options, systemPrompt: enforcedSystem })
+    return parseJSONResponse<T>(extractResponseText(response), { cutShort: response?.stop_reason === 'max_tokens' })
   }
 
   async vision(

package/server/service/providers/gemini.ts

@@ -73,7 +73,7 @@ export class GeminiAIClient implements AIClient {
     const result = await model.generateContent({ contents } as any)
     reportUsage(result, options, options.model ?? this.defaultModel)
     const text = result.response.text()
-    return parseJSONResponse<T>(text)
+    return parseJSONResponse<T>(text, { cutShort: result.response.candidates?.[0]?.finishReason === 'MAX_TOKENS' })
   }
 
   async vision(

package/server/service/providers/json-answer.test.ts

@@ -0,0 +1,53 @@
+/*
+ * What this guards: an answer that is not JSON is told apart from a request that failed, and an answer cut off at the
+ * output limit says so (figure audit 2026-10-16 N2). A caller asks the model again only for the first -- a rejected key,
+ * a rate limit or a dropped connection asked again three times is three failures, said as "not valid JSON".
+ */
+import { AnthropicAIClient } from './anthropic'
+import { OpenAIAIClient } from './openai'
+import { GeminiAIClient } from './gemini'
+import { AIAnswerNotJSON } from '../utils/parse-json'
+
+const CUT = '{"steps":[{"kind":"add-part","part":{"id":"ro'
+
+function anthropic(text: string, stop: string) {
+  const client = new AnthropicAIClient({ apiKey: 'test' } as any)
+  ;(client as any).sdk = { messages: { create: async () => ({ content: [{ type: 'text', text }], stop_reason: stop, usage: { input_tokens: 1, output_tokens: 1 } }) } }
+  return client
+}
+function openai(text: string, finish: string) {
+  const client = new OpenAIAIClient({ apiKey: 'test' } as any)
+  ;(client as any).sdk = { chat: { completions: { create: async () => ({ choices: [{ message: { content: text }, finish_reason: finish }], usage: { prompt_tokens: 1, completion_tokens: 1 } }) } } }
+  return client
+}
+function gemini(text: string, finish: string) {
+  const client = new GeminiAIClient({ apiKey: 'test' } as any)
+  ;(client as any).sdk = {
+    getGenerativeModel: () => ({ generateContent: async () => ({ response: { text: () => text, candidates: [{ finishReason: finish }], usageMetadata: {} } }) })
+  }
+  return client
+}
+
+const providers = [
+  ['anthropic', anthropic, 'max_tokens', 'end_turn'],
+  ['openai', openai, 'length', 'stop'],
+  ['gemini', gemini, 'MAX_TOKENS', 'STOP']
+] as const
+
+describe.each(providers)('%s generateJSON', (_name, make, cut, done) => {
+  it('an answer cut off at the output limit is not JSON, and says it was cut off', async () => {
+    const failure = await make(CUT, cut).generateJSON('x').catch(e => e)
+    expect(failure).toBeInstanceOf(AIAnswerNotJSON)
+    expect(failure.cutShort).toBe(true)
+  })
+
+  it('an answer that ended and is not JSON is not JSON, not cut off', async () => {
+    const failure = await make('I would rather explain.', done).generateJSON('x').catch(e => e)
+    expect(failure).toBeInstanceOf(AIAnswerNotJSON)
+    expect(failure.cutShort).toBe(false)
+  })
+
+  it('a whole answer is read', async () => {
+    await expect(make('{"steps":[]}', done).generateJSON('x')).resolves.toEqual({ steps: [] })
+  })
+})

package/server/service/providers/openai.ts

@@ -81,7 +81,7 @@ export class OpenAIAIClient implements AIClient {
     })
     reportUsage(response, options, options.model ?? this.defaultModel)
     const text = response.choices[0]?.message?.content ?? '{}'
-    return parseJSONResponse<T>(text)
+    return parseJSONResponse<T>(text, { cutShort: response.choices[0]?.finish_reason === 'length' })
   }
 
   async vision(

package/server/service/testing/tool-call-context.ts

@@ -7,7 +7,8 @@
  * defines the neutral door, and that door's tests check it hands tools exactly this shape — so a tool
  * test built on it fails when the tool reads a field no door fills.
  */
-import type { ToolCallContext, ToolCallMode } from '../tool-registry/types.js'
+import type { ToolAttachment, ToolCallContext, ToolCallMode, ToolTranslate } from '../tool-registry/types.js'
+import { defaultValueTranslate } from '../tool-registry/translate.js'
 
 export interface ToolCallContextFixtureInput {
   domainId?: string
@@ -16,12 +17,18 @@ export interface ToolCallContextFixtureInput {
   state?: Record<string, any>
   host?: Record<string, any>
   mode?: ToolCallMode
+  /** The request translator. Absent: the one the door hands when it was given none. */
+  t?: ToolTranslate
+  /** The checked files of the turn. Absent: none. */
+  attachments?: ToolAttachment[]
 }
 
 export function toolCallContextFixture(input: ToolCallContextFixtureInput = {}): ToolCallContext {
   const context: ToolCallContext = {
     state: { domain: { id: input.domainId ?? 'domain-test' }, user: { id: input.userId ?? 'user-test' }, ...(input.state ?? {}) },
-    host: input.host ?? {}
+    host: input.host ?? {},
+    t: input.t ?? defaultValueTranslate,
+    attachments: input.attachments ?? []
   }
   if (input.mode) context.mode = input.mode
   return context

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

@@ -0,0 +1,47 @@
+/*
+ * Every tool call of a registry conversation, handed to whoever writes them down.
+ *
+ * An application that keeps an AI audit (operato-office's AI 감사 기록) needs each call - which tool, with what, what
+ * came back or why it failed - whoever registered the tool: its own tools, a read target's list query, a data entry
+ * target's proposal. Wrapping each tool in the application left out the tools other packages declare, so the audit
+ * missed the reads that mattered most (2026-10-16). The registry conversation runs every tool at one place and calls
+ * the recorders there.
+ *
+ * A recorder that fails is said in the log and the call goes on - an audit that cannot be written never stops an
+ * answer. A recorder decides for itself which conversations it writes down (`context.mode.kind`).
+ */
+import type { ToolCallContext } from './types'
+
+export interface ToolCallRecord {
+  tool: string
+  /** The category the tool was offered from. */
+  category: string
+  args: unknown
+  /** What the tool returned - absent when it threw. A refusal it returned (`{ rejected: true }`) is here. */
+  result?: unknown
+  /** Why it threw. */
+  error?: string
+  durationMs: number
+}
+
+export type ToolCallRecorder = (record: ToolCallRecord, context: ToolCallContext) => void | Promise<void>
+
+const recorders: ToolCallRecorder[] = []
+
+export function registerToolCallRecorder(recorder: ToolCallRecorder): void {
+  if (!recorders.includes(recorder)) recorders.push(recorder)
+}
+
+export function clearToolCallRecorders(): void {
+  recorders.length = 0
+}
+
+export async function recordToolCall(record: ToolCallRecord, context: ToolCallContext): Promise<void> {
+  for (const recorder of recorders) {
+    try {
+      await recorder(record, context)
+    } catch (e) {
+      console.warn(`[ai-client-base] a tool call recorder failed for ${record.tool}:`, (e as Error)?.message ?? e)
+    }
+  }
+}

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

@@ -17,6 +17,11 @@ export {
   getToolRegistryWarnings
 } from './registry'
 
+export { defaultValueTranslate } from './translate'
+
+export { registerToolCallRecorder, clearToolCallRecorders, recordToolCall } from './call-recorder'
+export type { ToolCallRecord, ToolCallRecorder } from './call-recorder'
+
 /* 대화별 노출 제한 타입은 registry 소유(정의가 거기 있다). */
 export type { ToolCategoryFilter, ToolRegistryWarning } from './registry'
 
@@ -36,5 +41,9 @@ export type {
   WriteToolContext,
   ExternalToolContext,
   ToolCallContext,
-  ToolCallMode
+  ToolCallMode,
+  ToolTranslate,
+  ToolAttachment,
+  ToolImageAttachment,
+  ToolTextAttachment
 } from './types'

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

@@ -0,0 +1,12 @@
+/*
+ * The translator a tool gets when the door was given none (ADR-0061, 2026-10-16 decision 1).
+ *
+ * A door that runs outside a request — a test, a job — has no request locale. The tool still writes the sentence a
+ * person reads: the English default value, as i18next does with its own fallback language, with the placeholders
+ * filled. A key with no default value comes back as the key, so a reader that compares (`wordsOf`) knows nothing was
+ * translated. One constant, so the door and the shared fixture hand the same function.
+ */
+import type { ToolTranslate } from './types'
+
+export const defaultValueTranslate: ToolTranslate = (key, params) =>
+  String(params?.defaultValue ?? key).replace(/\{(\w+)\}/g, (whole, name) => (params && name in params ? String(params[name]) : whole))