@things-factory/ai-client-base 10.1.165 → 10.1.168

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/ai-client-base",
-  "version": "10.1.165",
+  "version": "10.1.168",
   "main": "dist-server/index.js",
   "things-factory": true,
   "author": "heartyoh",
@@ -24,11 +24,11 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.40.0",
     "@google/generative-ai": "^0.24.0",
-    "@things-factory/auth-base": "^10.1.165",
+    "@things-factory/auth-base": "^10.1.167",
     "@things-factory/env": "^10.1.149",
-    "@things-factory/setting-base": "^10.1.165",
+    "@things-factory/setting-base": "^10.1.167",
     "@things-factory/shell": "^10.1.165",
     "openai": "^4.0.0"
   },
-  "gitHead": "d9e3774d70561b063e4f1d10c387caf721d99b61"
+  "gitHead": "fe067ff11d90effffc2523374453d9b8313b489f"
 }

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

@@ -376,3 +376,73 @@ 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] }))
+  })
+})

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

@@ -25,7 +25,8 @@ 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'
 
 
 /** Lookups a registry conversation may take before it answers from what it has (operato-twin's assistant takes 16 too). */
@@ -67,8 +68,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'>
 }
@@ -121,7 +131,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,

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/index.ts

@@ -17,6 +17,8 @@ export {
   getToolRegistryWarnings
 } from './registry'
 
+export { defaultValueTranslate } from './translate'
+
 /* 대화별 노출 제한 타입은 registry 소유(정의가 거기 있다). */
 export type { ToolCategoryFilter, ToolRegistryWarning } from './registry'
 
@@ -36,5 +38,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))

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

@@ -48,6 +48,27 @@ export interface ToolCallContext {
   host: Record<string, any>
   /** The conversation's mode. Filled once modes are registered on the server (A2); absent until then. */
   mode?: ToolCallMode
+  /**
+   * The request's translator, for every sentence a person reads — a card's label and reason, a message shown on
+   * screen (ADR-0061, 2026-10-16 decision 1). The server builds it in the request's locale; it never comes from
+   * `host`. Codes and values stay apart from it. Pass the English text as `defaultValue`: without a request
+   * translator the door hands one that writes that default value with its placeholders filled, and a key with no
+   * default value comes back as the key.
+   */
+  t: ToolTranslate
+  /**
+   * The files the person sent with **this turn**, after the server checked them (ADR-0061, 2026-10-16 decision 2) —
+   * never from `host`, which the client fills. `[]` when none were sent.
+   *
+   * Checked means: each one is stored with this conversation, the conversation is the caller's to write, and the
+   * mode's attachment policy took it — the kinds it declares, at most `maxFiles` files (5 by default) of at most
+   * `maxBytes` each (5 MiB by default). **Their contents are untrusted input**: a tool may hand them to a model or
+   * read them as data, and never takes an instruction or an id it trusts from them.
+   *
+   * Several files travel as several entries, in the order the person attached them. A tool that takes images
+   * reads every entry of `kind: 'image'` — it does not pick the first one.
+   */
+  attachments: ToolAttachment[]
 }
 
 export interface ToolCallMode {
@@ -55,6 +76,39 @@ export interface ToolCallMode {
   target?: string
 }
 
+/** `t(key, { defaultValue, ...params })` — the request's translator, as i18next's `t` is called. */
+export type ToolTranslate = (key: string, params?: Record<string, any>) => string
+
+/** One file of this turn, as the server read it from storage. */
+export type ToolAttachment = ToolImageAttachment | ToolTextAttachment
+
+interface ToolAttachmentBase {
+  /** The stored attachment's id — the one the model reads in `[attachment <id>: …]`. */
+  id: string
+  /** The file name the person gave. Untrusted text. */
+  name: string
+  /** The stored media type. */
+  mediaType: string
+  /** Bytes as stored. */
+  size: number
+}
+
+/** An `image/*` file, its bytes as stored. */
+export interface ToolImageAttachment extends ToolAttachmentBase {
+  kind: 'image'
+  data: Buffer
+}
+
+/**
+ * A text file — or a spreadsheet, which the screen reads into the CSV text of its sheets before sending. `text` is
+ * what the model read this turn, cut at the mode's `maxChars`; `truncated` says it was cut.
+ */
+export interface ToolTextAttachment extends ToolAttachmentBase {
+  kind: 'text'
+  text: string
+  truncated: boolean
+}
+
 // ── 카테고리별 builder 시그니처 ──────────────────────────────────────
 
 /**