@things-factory/ai-client-base 10.1.203 → 10.1.205

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/ai-client-base",
-  "version": "10.1.203",
+  "version": "10.1.205",
   "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.203",
+    "@things-factory/auth-base": "^10.1.205",
     "@things-factory/env": "^10.1.149",
-    "@things-factory/setting-base": "^10.1.203",
-    "@things-factory/shell": "^10.1.188",
+    "@things-factory/setting-base": "^10.1.205",
+    "@things-factory/shell": "^10.1.205",
     "openai": "^4.0.0"
   },
-  "gitHead": "031aaae3b75b2975e6bce007b3ad7d8d74fe60c8"
+  "gitHead": "7311492aa5eaa00993c0325053f5f7ae8b1fb024"
 }

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

@@ -545,3 +545,83 @@ describe('every call is handed to the recorders - as a digest (ADR-0061 decision
     expect(recorded).toHaveLength(0)
   })
 })
+
+describe('an unattended run goes through the same door (design/ai/unattended-run.md)', () => {
+  const recorded: Array<{ record: ToolCallRecord; context: any }> = []
+  const RUN = { id: 'run-1', source: 'office.strategy-review', subject: 'policy-9', scheduledAt: '2026-11-01T07:00:00.000Z' }
+  beforeEach(() => {
+    clearToolCallRecorders()
+    recorded.length = 0
+    registerToolCallRecorder((record, context) => {
+      recorded.push({ record, context })
+    })
+    registerToolCategory({
+      name: 'ledger',
+      guidance: 'Read the pay before saying it.',
+      specs: [
+        {
+          kind: 'read',
+          name: 'readPay',
+          description: 'pay lines',
+          doors: ['Query.pay'],
+          schema: { type: 'object', properties: {} },
+          builder: (args: any, context: any) => {
+            ran.push({ name: 'readPay', args, context })
+            if (args.fail) throw new Error('the pay of 김급여 could not be read')
+            return { read: 1, rows: [{ name: '김급여', net: 3_100_000 }] }
+          }
+        }
+      ]
+    } as any)
+  })
+  afterAll(() => clearToolCallRecorders())
+
+  it('★ the run reaches the tool and the recorder as context.run - and a turn carries none', async () => {
+    const run = recordingClient([okResult(undefined, [TC('readPay')]), okResult('drafted')])
+    await registryAssistantChat(input({ client: run.client, toolCategories: ['ledger'], run: RUN }))
+    expect(ran[0].context.run).toEqual(RUN)
+    expect(recorded[0].context.run).toEqual(RUN)
+
+    const turn = recordingClient([okResult(undefined, [TC('readPay')]), okResult('answered')])
+    await registryAssistantChat(input({ client: turn.client, toolCategories: ['ledger'] }))
+    expect('run' in ran[1].context).toBe(false)
+    expect('run' in recorded[1].context).toBe(false)
+  })
+
+  it('★ onToolCall is handed the very digest the recorders get - one reading of a call, success and failure', async () => {
+    const seen: ToolCallRecord[] = []
+    const { client } = recordingClient([okResult(undefined, [TC('readPay', { employeeId: 'e-7' }, 'a'), TC('readPay', { fail: true }, 'b')]), okResult('drafted')])
+    await registryAssistantChat(input({ client, toolCategories: ['ledger'], run: RUN, onToolCall: (record: ToolCallRecord) => seen.push(record) }))
+    expect(seen).toHaveLength(2)
+    const strip = ({ durationMs: _d, ...rest }: any) => rest
+    expect(seen.map(strip)).toEqual(recorded.map(one => strip(one.record)))
+    expect(seen[0]).toMatchObject({ tool: 'readPay', targetIds: ['e-7'], ok: true, resultCount: 1 })
+    expect(seen[1]).toMatchObject({ tool: 'readPay', ok: false, errorCode: 'tool-threw', resultSize: 0 })
+    expect(JSON.stringify(seen)).not.toMatch(/김급여|3100000/)
+  })
+
+  it('an onToolCall that throws does not stop the run or the recorders', async () => {
+    const { client } = recordingClient([okResult(undefined, [TC('readPay')]), okResult('drafted')])
+    const result = await registryAssistantChat(input({ client, toolCategories: ['ledger'], onToolCall: () => { throw new Error('boom') } }))
+    expect(result.reply).toContain('drafted')
+    expect(recorded).toHaveLength(1)
+  })
+
+  it('★ the signal reaches every provider request, and the step limit holds with no wrap-up call', async () => {
+    const abort = new AbortController()
+    const { client, seen } = recordingClient([okResult(undefined, [TC('readPay')])])
+    const result = await registryAssistantChat(
+      input({ client, toolCategories: ['ledger'], signal: abort.signal, maxIterations: 3, salvageOnMaxIterations: false })
+    )
+    expect(seen).toHaveLength(3)
+    expect(seen.every(one => one.options.signal === abort.signal)).toBe(true)
+    expect(result.loop.abortReason).toMatchObject({ type: 'max_iterations' })
+  })
+
+  it('without the new inputs a turn keeps its limit and its wrap-up', async () => {
+    const { client, seen } = recordingClient([okResult(undefined, [TC('readPay')])])
+    await registryAssistantChat(input({ client, toolCategories: ['ledger'] }))
+    /* REGISTRY_MAX_ITERATIONS lookups and one wrap-up without tools. */
+    expect(seen).toHaveLength(REGISTRY_MAX_ITERATIONS + 1)
+  })
+})

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

@@ -25,9 +25,9 @@ import { narrowToolScope, resolveToolScope, toolScopeGuidance, type ToolAccessCh
 import { assistantChat, type AssistantChatResult } from './assistant-chat.js'
 import { resultShapeOf } from './summarize.js'
 import type { GroundingSources } from '../utils/index.js'
-import type { ToolAttachment, ToolCallContext } from '../tool-registry/types.js'
+import type { ToolAttachment, ToolCallContext, UnattendedRunRef } from '../tool-registry/types.js'
 import { defaultValueTranslate } from '../tool-registry/translate.js'
-import { recordToolCall } from '../tool-registry/call-recorder.js'
+import { digestOf, recordToolCall, type ToolCallRecord, type ToolCallRun } 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). */
@@ -82,6 +82,19 @@ export interface RegistryAssistantInput {
   attachments?: ToolAttachment[]
   /** Texts the answer is allowed to draw identifiers from, besides the tool results. */
   groundingSources?: Omit<GroundingSources, 'toolResults'>
+  /** Stops the loop and the provider request - an unattended run's time limit. */
+  signal?: AbortSignal
+  /** Lookups before the answer; `REGISTRY_MAX_ITERATIONS` when absent. */
+  maxIterations?: number
+  /** At the lookup limit, one more call without tools to answer from what was read. On when absent. */
+  salvageOnMaxIterations?: boolean
+  /**
+   * Each call as the recorders get it (`digestOf`, never its raw values) - an unattended run lists the reads its draft
+   * rested on from the same digest the audit keeps, so the two cannot describe one call differently.
+   */
+  onToolCall?: (record: ToolCallRecord) => void
+  /** Set for an unattended run; tools and recorders see it as `context.run`. */
+  run?: UnattendedRunRef
 }
 
 export interface RegistryAssistantResult extends AssistantChatResult<unknown> {
@@ -139,7 +152,19 @@ export async function registryAssistantChat(input: RegistryAssistantInput): Prom
     ...(input.mode ? { mode: input.mode } : {}),
     /* 번역기와 첨부는 서버의 값이다 — `host` 에서 받지 않는다(ADR-0061 2026-10-16 판정 1·2). */
     t: input.t ?? defaultValueTranslate,
-    attachments: input.attachments ?? []
+    attachments: input.attachments ?? [],
+    ...(input.run ? { run: input.run } : {})
+  }
+
+  const recorded = async (run: ToolCallRun, context: ToolCallContext) => {
+    if (input.onToolCall) {
+      try {
+        input.onToolCall(digestOf(run))
+      } catch (e) {
+        console.warn(`[registry-assistant] onToolCall failed for ${run.tool}:`, (e as Error)?.message ?? e)
+      }
+    }
+    await recordToolCall(run, context)
   }
 
   const result = await assistantChat<ToolCallContext, unknown>({
@@ -155,8 +180,9 @@ export async function registryAssistantChat(input: RegistryAssistantInput): Prom
        * A question across a product's records takes many lookups. At the limit the model answers from
        * what it read and says what is missing — the person is never told to split the question.
        */
-      maxIterations: REGISTRY_MAX_ITERATIONS,
-      salvageOnMaxIterations: true
+      maxIterations: input.maxIterations ?? REGISTRY_MAX_ITERATIONS,
+      salvageOnMaxIterations: input.salvageOnMaxIterations ?? true,
+      signal: input.signal
     },
     chat: (msgs, toolDefs, opts) => client.chatWithTools!(msgs, toolDefs, opts),
     context: toolContext,
@@ -177,10 +203,10 @@ export async function registryAssistantChat(input: RegistryAssistantInput): Prom
         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)
+          await recorded({ ...record, result, durationMs: Date.now() - started }, context)
           return result
         } catch (e) {
-          await recordToolCall({ ...record, error: e, durationMs: Date.now() - started }, context)
+          await recorded({ ...record, error: e, durationMs: Date.now() - started }, context)
           throw e
         }
       },

package/server/service/providers/anthropic.ts

@@ -20,6 +20,7 @@ import type {
 } from '../types.js'
 import { registerAIProvider } from '../factory.js'
 import { parseJSONResponse } from '../utils/parse-json.js'
+import { requestOptionsOf } from './request-options.js'
 
 const DEFAULT_MODEL = 'claude-sonnet-4-6'
 const DEFAULT_MAX_TOKENS = 4096
@@ -62,7 +63,7 @@ export class AnthropicAIClient implements AIClient {
       ...(system && { system }),
       ...(options.stopSequences && { stop_sequences: options.stopSequences }),
       messages: conversation
-    } as any)
+    } as any, requestOptionsOf(options))
     reportUsage(response, options, options.model ?? this.defaultModel)
     return response
   }
@@ -135,7 +136,7 @@ export class AnthropicAIClient implements AIClient {
       messages: conversation,
       tools: sdkTools,
       ...(toolChoice && { tool_choice: toolChoice })
-    } as any)
+    } as any, requestOptionsOf(options))
     reportUsage(response, options, options.model ?? this.defaultModel)
 
     const text = extractResponseText(response) || undefined

package/server/service/providers/gemini.ts

@@ -23,6 +23,7 @@ import type {
 } from '../types.js'
 import { registerAIProvider } from '../factory.js'
 import { parseJSONResponse } from '../utils/parse-json.js'
+import { requestOptionsOf } from './request-options.js'
 
 // `gemini-3-pro` 는 2026-03-09 종료됨. 후속 권장 모델로 변경.
 // 사용자가 자기 환경에서 활용 가능한 정확한 ID 는 ListModels 로 확인:
@@ -48,7 +49,7 @@ export class GeminiAIClient implements AIClient {
   async chat(messages: AIMessage[], options: AIChatOptions = {}): Promise<string> {
     const { systemPrompt, contents } = splitMessages(messages, options.systemPrompt)
     const model = this.buildModel(options, systemPrompt)
-    const result = await model.generateContent({ contents } as any)
+    const result = await model.generateContent({ contents } as any, requestOptionsOf(options))
     reportUsage(result, options, options.model ?? this.defaultModel)
     return result.response.text()
   }
@@ -70,7 +71,7 @@ export class GeminiAIClient implements AIClient {
       ...(systemPrompt && { systemInstruction: systemPrompt }),
       generationConfig
     }, this.requestOptions)
-    const result = await model.generateContent({ contents } as any)
+    const result = await model.generateContent({ contents } as any, requestOptionsOf(options))
     reportUsage(result, options, options.model ?? this.defaultModel)
     const text = result.response.text()
     return parseJSONResponse<T>(text, { cutShort: result.response.candidates?.[0]?.finishReason === 'MAX_TOKENS' })
@@ -128,7 +129,7 @@ export class GeminiAIClient implements AIClient {
       ...(toolConfig && { toolConfig })
     } as any, this.requestOptions)
 
-    const result = await model.generateContent({ contents } as any)
+    const result = await model.generateContent({ contents } as any, requestOptionsOf(options))
     reportUsage(result, options, options.model ?? this.defaultModel)
     const response: any = result.response
 

package/server/service/providers/openai.ts

@@ -22,6 +22,7 @@ import type {
 } from '../types.js'
 import { registerAIProvider } from '../factory.js'
 import { parseJSONResponse } from '../utils/parse-json.js'
+import { requestOptionsOf } from './request-options.js'
 
 const DEFAULT_MODEL = 'gpt-4o'
 const DEFAULT_MAX_TOKENS = 4096
@@ -50,7 +51,7 @@ export class OpenAIAIClient implements AIClient {
       ...(options.temperature !== undefined && { temperature: options.temperature }),
       ...(options.stopSequences && { stop: options.stopSequences }),
       messages: sdkMessages as any
-    })
+    }, requestOptionsOf(options))
     reportUsage(response, options, options.model ?? this.defaultModel)
     return response.choices[0]?.message?.content ?? ''
   }
@@ -78,7 +79,7 @@ export class OpenAIAIClient implements AIClient {
       ...(options.temperature !== undefined && { temperature: options.temperature }),
       response_format: { type: 'json_object' },
       messages: sdkMessages as any
-    })
+    }, requestOptionsOf(options))
     reportUsage(response, options, options.model ?? this.defaultModel)
     const text = response.choices[0]?.message?.content ?? '{}'
     return parseJSONResponse<T>(text, { cutShort: response.choices[0]?.finish_reason === 'length' })
@@ -131,7 +132,7 @@ export class OpenAIAIClient implements AIClient {
       tools: sdkTools,
       ...(toolChoice !== undefined && { tool_choice: toolChoice as any }),
       ...(options.allowParallelToolCalls === false && { parallel_tool_calls: false })
-    })
+    }, requestOptionsOf(options))
     reportUsage(response, options, options.model ?? this.defaultModel)
 
     const choice = response.choices?.[0]

package/server/service/providers/request-options.ts

@@ -0,0 +1,12 @@
+/*
+ * What a provider SDK is handed per request besides the body - the caller's abort signal (types.ts `signal`).
+ *
+ * The three adapters each take it the same way, so it is said once. Aborting stops our wait and frees the loop; the
+ * provider may still finish the request on its side and bill it, which is why a run's spend is capped by its token
+ * limit and not by its clock.
+ */
+import type { AIChatOptions } from '../types.js'
+
+export function requestOptionsOf(options: AIChatOptions | undefined): { signal: AbortSignal } | undefined {
+  return options?.signal ? { signal: options.signal } : undefined
+}

package/server/service/providers/request-signal.test.ts

@@ -0,0 +1,77 @@
+/*
+ * What this guards: a stop reaches the provider request.
+ *
+ * The loop passed `signal` on every request and no adapter handed it to its SDK, so a person's stop and an unattended
+ * run's time limit ended our side while the request kept running (2026-10-20). Each adapter's SDK is replaced with a
+ * stand-in that keeps what it was handed per request, for every call that sends one.
+ */
+import { AnthropicAIClient } from './anthropic'
+import { OpenAIAIClient } from './openai'
+import { GeminiAIClient } from './gemini'
+
+type Seen = Array<{ body: any; request: any }>
+
+function anthropic(seen: Seen) {
+  const client: any = new AnthropicAIClient({ provider: 'anthropic', apiKey: 'test-key' } as any)
+  client.sdk = {
+    messages: {
+      create: async (body: any, request: any) => {
+        seen.push({ body, request })
+        return { model: 'm', content: [{ type: 'text', text: '{"ok":true}' }], stop_reason: 'end_turn', usage: {} }
+      }
+    }
+  }
+  return client
+}
+
+function openai(seen: Seen) {
+  const client: any = new OpenAIAIClient({ provider: 'openai', apiKey: 'test-key' } as any)
+  client.sdk = {
+    chat: {
+      completions: {
+        create: async (body: any, request: any) => {
+          seen.push({ body, request })
+          return { model: 'm', choices: [{ message: { content: '{"ok":true}' }, finish_reason: 'stop' }], usage: {} }
+        }
+      }
+    }
+  }
+  return client
+}
+
+function gemini(seen: Seen) {
+  const client: any = new GeminiAIClient({ provider: 'gemini', apiKey: 'test-key' } as any)
+  client.sdk = {
+    getGenerativeModel: () => ({
+      generateContent: async (body: any, request: any) => {
+        seen.push({ body, request })
+        const response = { candidates: [{ content: { parts: [{ text: '{"ok":true}' }] }, finishReason: 'STOP' }], text: () => '{"ok":true}' }
+        return { response }
+      }
+    })
+  }
+  return client
+}
+
+const ADAPTERS = { anthropic, openai, gemini }
+const tools = [{ name: 'readGoals', description: 'goals', parameters: { type: 'object', properties: {} } }]
+const user = [{ role: 'user' as const, content: 'hello' }]
+
+describe.each(Object.entries(ADAPTERS))('%s', (_name, make) => {
+  it('★ chat, generateJSON and chatWithTools hand the signal to the SDK request', async () => {
+    const seen: Seen = []
+    const client = make(seen)
+    const { signal } = new AbortController()
+    await client.chat(user, { signal })
+    await client.generateJSON('give json', { signal })
+    await client.chatWithTools(user, tools, { signal })
+    expect(seen).toHaveLength(3)
+    expect(seen.every(one => one.request?.signal === signal)).toBe(true)
+  })
+
+  it('without a signal the SDK is handed nothing extra', async () => {
+    const seen: Seen = []
+    await make(seen).chatWithTools(user, tools, {})
+    expect(seen[0].request).toBeUndefined()
+  })
+})

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

@@ -7,7 +7,7 @@
  * 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 { ToolAttachment, ToolCallContext, ToolCallMode, ToolTranslate } from '../tool-registry/types.js'
+import type { ToolAttachment, ToolCallContext, ToolCallMode, ToolTranslate, UnattendedRunRef } from '../tool-registry/types.js'
 import { defaultValueTranslate } from '../tool-registry/translate.js'
 
 export interface ToolCallContextFixtureInput {
@@ -21,6 +21,8 @@ export interface ToolCallContextFixtureInput {
   t?: ToolTranslate
   /** The checked files of the turn. Absent: none. */
   attachments?: ToolAttachment[]
+  /** The unattended run the call belongs to. Absent: a turn of a conversation. */
+  run?: UnattendedRunRef
 }
 
 export function toolCallContextFixture(input: ToolCallContextFixtureInput = {}): ToolCallContext {
@@ -31,5 +33,6 @@ export function toolCallContextFixture(input: ToolCallContextFixtureInput = {}):
     attachments: input.attachments ?? []
   }
   if (input.mode) context.mode = input.mode
+  if (input.run) context.run = input.run
   return context
 }

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

@@ -42,6 +42,7 @@ export type {
   ExternalToolContext,
   ToolCallContext,
   ToolCallMode,
+  UnattendedRunRef,
   ToolTranslate,
   ToolAttachment,
   ToolImageAttachment,

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

@@ -69,6 +69,12 @@ export interface ToolCallContext {
    * reads every entry of `kind: 'image'` — it does not pick the first one.
    */
   attachments: ToolAttachment[]
+  /**
+   * Set when no person is in this conversation: a scheduled run of the mode, as the caller named it
+   * (operato-application/design/ai/unattended-run.md §6). A recorder tells an unattended run's calls from a turn's by
+   * it; a turn has none. The server's value - never from `host`.
+   */
+  run?: UnattendedRunRef
 }
 
 export interface ToolCallMode {
@@ -76,6 +82,17 @@ export interface ToolCallMode {
   target?: string
 }
 
+/** Which unattended run a call belongs to - the stored run's id and the identity its caller gave it. */
+export interface UnattendedRunRef {
+  id: string
+  /** Who scheduled it - `<app>.<work>`, e.g. `office.strategy-review`. */
+  source: string
+  /** What it is about in the source's terms - a policy id. */
+  subject: string
+  /** The occurrence it is, ISO 8601. */
+  scheduledAt: 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
 

package/server/service/types.ts

@@ -85,6 +85,11 @@ export interface AIChatOptions {
    * call so the usage row knows whose call it was; adapters call it once for every request they send.
    */
   onUsage?: (usage: AIProviderUsage) => void
+  /**
+   * Stops waiting for the request - a person's stop, or an unattended run's time limit. Every adapter hands it to its
+   * SDK. The provider may still complete and bill a request it already received.
+   */
+  signal?: AbortSignal
 }
 
 /** What one provider request used, as the provider reported it. A count the provider did not report stays undefined. */