@things-factory/ai-client-base 10.1.176 → 10.1.177

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/ai-client-base",
-  "version": "10.1.176",
+  "version": "10.1.177",
   "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": "24928f127d73de0e9946423bd4c3295f54cce03d"
+  "gitHead": "91da09c945ec5e77ab960074db8f53b9ea8ac534"
 }

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

@@ -556,7 +556,7 @@ async function processToolCalls<TCtx, TOp>(
       } 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' })
+        toolUsages.push({ name: tc.name, arguments: tc.arguments ?? {}, result: dispatch.summarizeToolResult(failure), kind: 'read', iter, outcome: 'error' })
         continue
       }
       /* await 필수 — registry 에 등록된 read/external builder 는 async 일 수 있다(DB·외부 호출).
@@ -628,7 +628,7 @@ async function processToolCalls<TCtx, TOp>(
         toolUsages.push({
           name: tc.name,
           arguments: tc.arguments ?? {},
-          result: errorResult,
+          result: dispatch.summarizeToolResult(errorResult),
           kind: 'write',
           iter,
           outcome: 'rejected'
@@ -645,7 +645,7 @@ async function processToolCalls<TCtx, TOp>(
         toolUsages.push({
           name: tc.name,
           arguments: tc.arguments ?? {},
-          result: queuedResult,
+          result: dispatch.summarizeToolResult(queuedResult),
           kind: 'write',
           iter,
           outcome: 'queued'
@@ -667,7 +667,7 @@ async function processToolCalls<TCtx, TOp>(
       toolUsages.push({
         name: tc.name,
         arguments: tc.arguments ?? {},
-        result: queuedResult,
+        result: dispatch.summarizeToolResult(queuedResult),
         kind: 'write',
         iter,
         outcome: 'queued'
@@ -683,7 +683,7 @@ async function processToolCalls<TCtx, TOp>(
       toolUsages.push({
         name: tc.name,
         arguments: tc.arguments ?? {},
-        result: errResult,
+        result: dispatch.summarizeToolResult(errResult),
         kind: 'unknown',
         iter,
         outcome: 'error'

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

@@ -447,14 +447,14 @@ describe('the request translator and the checked attachments (ADR-0061, 2026-10-
   })
 })
 
-describe('every call is handed to the recorders', () => {
+describe('every call is handed to the recorders - as a digest (ADR-0061 decision 8)', () => {
   const recorded: Array<{ record: ToolCallRecord; context: any }> = []
+  const keep = (record: ToolCallRecord, context: any) => {
+    recorded.push({ record, context })
+  }
   beforeEach(() => {
     clearToolCallRecorders()
     recorded.length = 0
-    registerToolCallRecorder((record, context) => {
-      recorded.push({ record, context })
-    })
     registerToolCategory({
       name: 'ledger',
       guidance: 'Read the ledger before saying a balance.',
@@ -466,29 +466,64 @@ describe('every call is handed to the recorders', () => {
           doors: ['Query.ledger'],
           schema: { type: 'object', properties: {} },
           builder: () => {
-            throw new Error('the ledger could not be read')
+            throw new Error('the ledger of 김급여 could not be read')
           }
+        },
+        {
+          kind: 'read',
+          name: 'readPay',
+          description: 'pay lines',
+          doors: ['Query.pay'],
+          schema: { type: 'object', properties: {} },
+          builder: (args: any) => (args.refuse ? { rejected: true, error: 'query-failed', message: 'unauthorized' } : { read: 2, rows: [{ name: '김급여', net: 3_100_000 }, { name: '이급여', net: 2_900_000 }] })
         }
       ]
     } 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' } }))
+  it('★ the tool, its category, the ids it names, the size and hash of what came back - and the conversation it ran in', async () => {
+    registerToolCallRecorder(keep)
+    const { client } = recordingClient([okResult(undefined, [TC('readPay', { employeeId: 'e-7', month: '2026-09' })]), okResult('two people')])
+    await registryAssistantChat(input({ client, toolCategories: ['ledger'], mode: { kind: 'office.finance' } }))
     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')
+    const { record, context } = recorded[0]
+    expect(record).toMatchObject({ tool: 'readPay', category: 'ledger', targetIds: ['e-7'], resultCount: 2, ok: true })
+    expect(record.argsHash).toMatch(/^[0-9a-f]{64}$/)
+    expect(record.resultHash).toMatch(/^[0-9a-f]{64}$/)
+    expect(record.resultSize).toBeGreaterThan(0)
+    expect(context.mode).toEqual({ kind: 'office.finance' })
+    expect(context.state.domain.id).toBe('dom-1')
+  })
+
+  it('★ pay and names are not in the record by default - only a category the recorder names carries them', async () => {
+    registerToolCallRecorder(keep)
+    const { client } = recordingClient([okResult(undefined, [TC('readPay', { month: '2026-09' })]), okResult('two people')])
+    const turn: any = await registryAssistantChat(input({ client, toolCategories: ['ledger'] }))
+    expect(recorded[0].record.raw).toBeUndefined()
+    /* The conversation row keeps the same shape - the dock's tool panel shows how many, never whose pay. */
+    expect(turn.loop.toolUsages[0].result).toEqual({ size: expect.any(Number), count: 2, keys: ['read', 'rows'] })
+    expect(JSON.stringify(turn.loop.toolUsages)).not.toMatch(/김급여|3100000/)
+    expect(JSON.stringify(recorded[0].record)).not.toMatch(/김급여|3100000|2026-09/)
+
+    clearToolCallRecorders()
+    recorded.length = 0
+    registerToolCallRecorder(keep, { raw: ['ledger'] })
+    const again = recordingClient([okResult(undefined, [TC('readPay', { month: '2026-09' })]), okResult('two people')])
+    await registryAssistantChat(input({ client: again.client, toolCategories: ['ledger'] }))
+    expect(recorded[0].record.raw).toEqual({ args: { month: '2026-09' }, result: { read: 2, rows: [{ name: '김급여', net: 3_100_000 }, { name: '이급여', net: 2_900_000 }] } })
   })
 
-  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')])
+  it('★ a tool that throws or refuses is recorded by a code, never by its message - and the model is still told', async () => {
+    registerToolCallRecorder(keep)
+    const { client } = recordingClient([okResult(undefined, [TC('readBrokenLedger'), TC('readPay', { refuse: true }, 't2')]), 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(recorded.map(one => [one.record.tool, one.record.errorCode, one.record.ok])).toEqual([
+      ['readBrokenLedger', 'tool-threw', false],
+      ['readPay', 'query-failed', false]
+    ])
+    expect(recorded[0].record.resultSize).toBe(0)
+    expect(JSON.stringify(recorded[0].record)).not.toMatch(/김급여/)
     expect(result.reply).toContain('could not read it')
   })
 
@@ -496,6 +531,7 @@ describe('every call is handed to the recorders', () => {
     registerToolCallRecorder(() => {
       throw new Error('audit table missing')
     })
+    registerToolCallRecorder(keep)
     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')
@@ -503,6 +539,7 @@ describe('every call is handed to the recorders', () => {
   })
 
   it('a tool that was not offered is not run, so nothing is recorded', async () => {
+    registerToolCallRecorder(keep)
     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

@@ -23,7 +23,7 @@
 import type { AIClient, AIMessage } from '../types.js'
 import { narrowToolScope, resolveToolScope, toolScopeGuidance, type ToolAccessCheck } from './tool-scope.js'
 import { assistantChat, type AssistantChatResult } from './assistant-chat.js'
-import { summarizeToolResult } from './summarize.js'
+import { resultShapeOf } from './summarize.js'
 import type { GroundingSources } from '../utils/index.js'
 import type { ToolAttachment, ToolCallContext } from '../tool-registry/types.js'
 import { defaultValueTranslate } from '../tool-registry/translate.js'
@@ -180,13 +180,14 @@ export async function registryAssistantChat(input: RegistryAssistantInput): Prom
           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)
+          await recordToolCall({ ...record, error: e, durationMs: Date.now() - started }, context)
           throw e
         }
       },
       validateWriteToolCall: () => ({ valid: false, errors: ['this conversation has no document to write to'] }),
       toolCallToOp: () => null,
-      summarizeToolResult
+      /* The conversation row keeps the shape of each answer, as the audit does - never its values (ADR-0061 decision 8). */
+      summarizeToolResult: resultShapeOf
     },
     groundingSources: input.groundingSources,
     t: input.t

package/server/service/assistant/summarize.ts

@@ -1,61 +1,47 @@
 /*
- * Tool results, cut down to what a screen can hold.
+ * A tool result as it is kept - its shape, never its values (ADR-0061 decision 8, ruled 2026-10-17).
  *
- * ── 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.
+ * Two records keep what a tool answered: the conversation row (`toolUsages`, the dock's tool panel) and the AI audit
+ * (the call recorder's digest). Both keep the same thing, through this one function: how big the answer was, how many
+ * rows it carried, the names of its fields, and the code it failed with. The values - pay, shareholdings, a person's
+ * name - stay in their own tables; copying them into a conversation row puts them in its backups and exports too,
+ * whoever may read the row.
  *
- * ── ⚠ 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.
+ * ── ⚠ This is for the panel and the audit, never for a judgement ─────────────────
+ * What the model actually received is `AgenticLoopResult.groundedTexts`. Grounding 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
+/** Field names kept of an object answer - its first ones; an answer with more says how many. */
+const MAX_KEYS = 20
 
-/**
- * 도구 결과를 화면·영속에 쓸 크기로 줄인다.
- *
- * 줄인 자리마다 **줄였다는 표시**를 남긴다(`…[+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
+export interface ResultShape {
+  /** Characters of the answer as JSON. */
+  size: number
+  /** Rows it carried - `read` of a list read, else the length of the answer or of its first list. */
+  count?: number
+  /** The field names of an object answer - names only. */
+  keys?: string[]
+  /** More field names than `keys` holds. */
+  moreKeys?: number
+  /** The code it failed with - a refusal's `error`, or the `error` code of a failure. */
+  errorCode?: string
+}
+
+export function resultShapeOf(value: unknown): ResultShape {
+  const size = JSON.stringify(value ?? null).length
+  if (Array.isArray(value)) return { size, count: value.length }
+  if (!value || typeof value !== 'object') return { size }
+  const answer = value as Record<string, any>
+  const names = Object.keys(answer)
+  const lists = Object.values(answer).filter(Array.isArray)
+  const count = typeof answer.read === 'number' ? answer.read : lists.length ? lists[0].length : undefined
+  const errorCode = answer.rejected === true ? String(answer.error ?? 'rejected') : typeof answer.error === 'string' ? answer.error : undefined
+  return {
+    size,
+    ...(count === undefined ? {} : { count }),
+    keys: names.slice(0, MAX_KEYS),
+    ...(names.length > MAX_KEYS ? { moreKeys: names.length - MAX_KEYS } : {}),
+    ...(errorCode ? { errorCode } : {})
   }
-  return undefined
 }

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

@@ -1,47 +1,116 @@
 /*
- * Every tool call of a registry conversation, handed to whoever writes them down.
+ * Every tool call of a registry conversation, handed to whoever writes them down (ADR-0061 decision 8).
  *
- * 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.
+ * An application that keeps an AI audit (operato-office's AI 감사 기록) needs each call - which tool, about what,
+ * how much 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 is handed a digest: the tool, its category, the ids its arguments name, the size and hash of what came
+ * back, an error code. The arguments and the result themselves - pay, shareholdings - are not copied into an audit
+ * by default; a recorder that must keep them names the categories it keeps them for (`raw`).
  *
  * 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 { createHash } from 'crypto'
+
+import { resultShapeOf } from '../assistant/summarize'
 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
+  /** The ids the arguments name - `id`, `…Id`, `ids`, `…Ids` - and nothing else of them. */
+  targetIds: string[]
+  /** sha256 of the arguments - the same call is the same hash. */
+  argsHash: string
+  /** Characters of the result as JSON; 0 when the tool threw. */
+  resultSize: number
+  /** How many rows it carried - `read` of a list read, else the length of its first list; absent when it says none. */
+  resultCount?: number
+  resultHash?: string
+  /** Why it failed: the code a refusal returned (`{ rejected: true, error }`), the thrown error's code, or `tool-threw`. */
+  errorCode?: string
+  ok: boolean
   durationMs: number
+  /** The arguments and the result as they were - only for a category the recorder named in `raw`. */
+  raw?: { args: unknown; result?: unknown; error?: string }
 }
 
 export type ToolCallRecorder = (record: ToolCallRecord, context: ToolCallContext) => void | Promise<void>
 
-const recorders: ToolCallRecorder[] = []
+export interface ToolCallRecorderOptions {
+  /** Categories whose calls the recorder is handed with their arguments and result as they were. */
+  raw?: string[]
+}
+
+/** A call as it ran - the registry door's side, before it is cut down for a recorder. */
+export interface ToolCallRun {
+  tool: string
+  category: string
+  args: unknown
+  result?: unknown
+  error?: unknown
+  durationMs: number
+}
+
+const recorders: { recorder: ToolCallRecorder; raw: Set<string> }[] = []
 
-export function registerToolCallRecorder(recorder: ToolCallRecorder): void {
-  if (!recorders.includes(recorder)) recorders.push(recorder)
+export function registerToolCallRecorder(recorder: ToolCallRecorder, options: ToolCallRecorderOptions = {}): void {
+  if (recorders.some(one => one.recorder === recorder)) return
+  recorders.push({ recorder, raw: new Set(options.raw ?? []) })
 }
 
 export function clearToolCallRecorders(): void {
   recorders.length = 0
 }
 
-export async function recordToolCall(record: ToolCallRecord, context: ToolCallContext): Promise<void> {
-  for (const recorder of recorders) {
+const hash = (value: unknown) => createHash('sha256').update(JSON.stringify(value ?? null)).digest('hex')
+
+/** The ids an argument object names, by its keys - a value under any other key is not carried. */
+function idsOf(args: unknown): string[] {
+  if (!args || typeof args !== 'object') return []
+  const ids: string[] = []
+  for (const [key, value] of Object.entries(args as Record<string, unknown>)) {
+    if (!/^(id|ids)$|[a-z](Id|Ids)$/.test(key)) continue
+    for (const one of Array.isArray(value) ? value : [value]) if (typeof one === 'string' || typeof one === 'number') ids.push(String(one))
+  }
+  return ids
+}
+
+/** A run as a recorder sees it - the digest, and the raw text when its category was asked for. */
+export function digestOf(run: ToolCallRun, raw = false): ToolCallRecord {
+  const threw = run.error !== undefined
+  const result: any = run.result
+  /* The same shape the conversation row keeps (resultShapeOf) - one reading of an answer. */
+  const shape = threw ? undefined : resultShapeOf(result)
+  const errorCode = threw ? String((run.error as any)?.code ?? 'tool-threw') : shape!.errorCode
+  const resultSize = shape?.size ?? 0
+  const resultCount = shape?.count
+  return {
+    tool: run.tool,
+    category: run.category,
+    targetIds: idsOf(run.args),
+    argsHash: hash(run.args),
+    resultSize,
+    ...(resultCount === undefined ? {} : { resultCount }),
+    ...(threw ? {} : { resultHash: hash(result) }),
+    ...(errorCode ? { errorCode } : {}),
+    ok: !errorCode,
+    durationMs: run.durationMs,
+    ...(raw ? { raw: { args: run.args, ...(threw ? { error: String((run.error as any)?.message ?? run.error) } : { result }) } } : {})
+  }
+}
+
+export async function recordToolCall(run: ToolCallRun, context: ToolCallContext): Promise<void> {
+  for (const { recorder, raw } of recorders) {
     try {
-      await recorder(record, context)
+      await recorder(digestOf(run, raw.has(run.category)), context)
     } catch (e) {
-      console.warn(`[ai-client-base] a tool call recorder failed for ${record.tool}:`, (e as Error)?.message ?? e)
+      console.warn(`[ai-client-base] a tool call recorder failed for ${run.tool}:`, (e as Error)?.message ?? e)
     }
   }
 }

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

@@ -19,8 +19,8 @@ export {
 
 export { defaultValueTranslate } from './translate'
 
-export { registerToolCallRecorder, clearToolCallRecorders, recordToolCall } from './call-recorder'
-export type { ToolCallRecord, ToolCallRecorder } from './call-recorder'
+export { registerToolCallRecorder, clearToolCallRecorders, recordToolCall, digestOf } from './call-recorder'
+export type { ToolCallRecord, ToolCallRecorder, ToolCallRecorderOptions, ToolCallRun } from './call-recorder'
 
 /* 대화별 노출 제한 타입은 registry 소유(정의가 거기 있다). */
 export type { ToolCategoryFilter, ToolRegistryWarning } from './registry'