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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/ai-client-base",
-  "version": "10.1.168",
+  "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": "fe067ff11d90effffc2523374453d9b8313b489f"
+  "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'
 
@@ -446,3 +446,65 @@ describe('the request translator and the checked attachments (ADR-0061, 2026-10-
     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

@@ -27,6 +27,7 @@ import { summarizeToolResult } 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'
+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). */
@@ -113,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,
@@ -166,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/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

@@ -19,6 +19,9 @@ export {
 
 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'
 

package/server/service/utils/parse-json.ts

@@ -13,9 +13,24 @@
  *   3) 그래도 실패하면 raw 출력 포함한 명확한 에러
  */
 
-export function parseJSONResponse<T = unknown>(text: string): T {
+/**
+ * The model answered, and the answer is not JSON (figure audit 2026-10-16 N2). Told apart from a request that failed --
+ * a rejected key, a rate limit, a dropped connection -- because only this is worth asking again, with why it was not.
+ * `cutShort`: the answer stopped at the output limit before it ended, so asking again for the same is cut off again.
+ */
+export class AIAnswerNotJSON extends Error {
+  constructor(
+    message: string,
+    readonly cutShort = false
+  ) {
+    super(message)
+    this.name = 'AIAnswerNotJSON'
+  }
+}
+
+export function parseJSONResponse<T = unknown>(text: string, { cutShort = false }: { cutShort?: boolean } = {}): T {
   if (typeof text !== 'string') {
-    throw new Error(`AI response is not a string (got ${typeof text})`)
+    throw new AIAnswerNotJSON(`AI response is not a string (got ${typeof text})`, cutShort)
   }
 
   const stripped = stripCodeFences(text).trim()
@@ -33,13 +48,14 @@ export function parseJSONResponse<T = unknown>(text: string): T {
     try {
       return JSON.parse(extracted) as T
     } catch (e) {
-      throw new Error(
-        `AI response is not valid JSON (after extraction): ${(e as Error).message}\n----- raw -----\n${text}`
+      throw new AIAnswerNotJSON(
+        `AI response is not valid JSON (after extraction): ${(e as Error).message}\n----- raw -----\n${text}`,
+        cutShort
       )
     }
   }
 
-  throw new Error(`AI response is not valid JSON: no balanced JSON found.\n----- raw -----\n${text}`)
+  throw new AIAnswerNotJSON(`AI response is not valid JSON: no balanced JSON found.\n----- raw -----\n${text}`, cutShort)
 }
 
 function stripCodeFences(text: string): string {