@things-factory/ai-client-base 10.1.206 → 10.1.208

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/ai-client-base",
-  "version": "10.1.206",
+  "version": "10.1.208",
   "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.206",
+    "@things-factory/auth-base": "^10.1.208",
     "@things-factory/env": "^10.1.149",
-    "@things-factory/setting-base": "^10.1.206",
-    "@things-factory/shell": "^10.1.206",
+    "@things-factory/setting-base": "^10.1.208",
+    "@things-factory/shell": "^10.1.208",
     "openai": "^4.0.0"
   },
-  "gitHead": "18588a058a4a6cb21c379b2da5517e077c6442ba"
+  "gitHead": "ffc1ceaa9471b9f4a9b86f46c3021f2fed72d17d"
 }

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

@@ -158,7 +158,11 @@ export interface AgenticLoopOptions {
 
 export interface AgenticLoopInput<TCtx = unknown, TOp = unknown> {
   initialConversation: AIMessage[]
-  tools: any[]
+  /**
+   * The tools the model is offered. A function is asked before every call, so a conversation that opens tools in a
+   * turn (ADR-0061 decision 9, `openTools`) offers them from its next call on.
+   */
+  tools: any[] | (() => any[])
   options: AgenticLoopOptions
   /** LLM provider 의 chatWithTools 위임. provider-specific 구현. */
   chat: (
@@ -256,6 +260,8 @@ export async function runAgenticLoop<TCtx = unknown, TOp = unknown>(
   let lastFailedToolName: string | undefined
   let consecutiveFailures = 0
 
+  const toolsNow = () => (typeof tools === 'function' ? tools() : tools)
+
   let iter = 0
   for (; iter < maxIterations; iter++) {
     // (1) AbortSignal — iteration 시작 시 체크
@@ -273,7 +279,7 @@ export async function runAgenticLoop<TCtx = unknown, TOp = unknown>(
        * 일시 장애(429·5xx·네트워크)는 **다시 시도한다**: 모델 서비스는 가끔 잠깐 죽고(실제로 Gemini
        * 503 으로 대화가 끊겼다), 그때 한 번도 다시 걸지 않는 것은 우리 쪽 손해다. 요청·자격 오류는
        * 즉시 그대로 올린다(조용히 더 시도하면 원인이 늦게 드러난다). 판정·대기는 ai-client-base 가 소유. */
-      result = await retryTransient(() => chat(conversation, tools, {
+      result = await retryTransient(() => chat(conversation, toolsNow(), {
         systemPrompt: options.systemPrompt,
         model: options.model,
         temperature: options.temperature,
@@ -393,7 +399,7 @@ export async function runAgenticLoop<TCtx = unknown, TOp = unknown>(
      */
     if (options.salvageOnMaxIterations) {
       try {
-        const salvaged = await chat(conversation, tools, {
+        const salvaged = await chat(conversation, toolsNow(), {
           systemPrompt: `${options.systemPrompt}\n\n${options.salvagePrompt ?? DEFAULT_SALVAGE_PROMPT}`,
           model: options.model,
           temperature: options.temperature,

package/server/service/assistant/index.ts

@@ -6,6 +6,7 @@
 export * from './abort-notice.js'
 export * from './summarize.js'
 export * from './tool-scope.js'
+export * from './tool-budget.js'
 export * from './registry-gate.js'
 export * from './assistant-chat.js'
 export * from './registry-assistant.js'

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

@@ -21,13 +21,14 @@
  * may be dispatched cannot drift apart.
  */
 import type { AIClient, AIMessage } from '../types.js'
-import { narrowToolScope, resolveToolScope, toolScopeGuidance, type ToolAccessCheck } from './tool-scope.js'
+import { narrowToolScope, resolveToolScope, type ToolAccessCheck } from './tool-scope.js'
 import { assistantChat, type AssistantChatResult } from './assistant-chat.js'
 import { resultShapeOf } from './summarize.js'
 import type { GroundingSources } from '../utils/index.js'
 import type { ToolAttachment, ToolCallContext, UnattendedRunRef } from '../tool-registry/types.js'
 import { defaultValueTranslate } from '../tool-registry/translate.js'
 import { digestOf, recordToolCall, type ToolCallRecord, type ToolCallRun } from '../tool-registry/call-recorder.js'
+import { OPEN_TOOLS, TOOL_BUDGET_CATEGORY, toolOfferState, type ToolFront } from './tool-budget.js'
 
 
 /** Lookups a registry conversation may take before it answers from what it has (operato-twin's assistant takes 16 too). */
@@ -46,6 +47,12 @@ export interface RegistryAssistantInput {
    * category, which is how a Board-creating tool reached any conversation.
    */
   toolCategories?: string[]
+  /**
+   * What goes in front when the scope is larger than one call carries (ADR-0061 decision 9) - the screen's records,
+   * the tools this conversation used. The rest the model opens with `openTools`. Without it, only `openTools` is in
+   * front of a scope that does not fit.
+   */
+  front?: ToolFront
   /**
    * Answers whether the caller holds a tool's declared privilege. Without it, every tool that
    * declares a privilege stays closed. The host builds it from the request — this package does
@@ -100,6 +107,8 @@ export interface RegistryAssistantInput {
 export interface RegistryAssistantResult extends AssistantChatResult<unknown> {
   /** Tool names actually offered to the model this turn. The caller may log or return it. */
   offeredTools: string[]
+  /** Tools of the scope the model could have opened and did not (ADR-0061 decision 9) - with `offeredTools`, all it may use. */
+  openableTools: string[]
 }
 
 /**
@@ -125,21 +134,24 @@ export async function registryAssistantChat(input: RegistryAssistantInput): Prom
     await resolveToolScope(toolCategories, input.toolAccess),
     spec => spec.kind === 'read'
   )
-  const specs = scope.specs
-  const byName = new Map(specs.map(spec => [spec.name, spec]))
+  /* What one call carries is within the budget; what is offered and what may run are the same set as it grows. */
+  const offer = toolOfferState(scope, input.front)
   const categoryOf = new Map(scope.categories.flatMap(category => category.specs.map(spec => [spec.name, category.name] as [string, string])))
+  categoryOf.set(OPEN_TOOLS, TOOL_BUDGET_CATEGORY)
 
-  const tools = specs.map(spec => ({
-    name: spec.name,
-    description: spec.themeNote ? `${spec.description} ${spec.themeNote}` : spec.description,
-    parameters: spec.schema
-  }))
+  const tools = () =>
+    offer.offered().map(spec => ({
+      name: spec.name,
+      description: spec.themeNote ? `${spec.description} ${spec.themeNote}` : spec.description,
+      parameters: spec.schema
+    }))
 
   /*
-   * The rules for using a tool belong to whoever registered it. Collect only the exposed ones, so
-   * a surface never reads instructions for a category it cannot call.
+   * The rules for using a tool belong to whoever registered it. Collect only the offered ones, so
+   * a surface never reads instructions for a category it cannot call - an opened tool brings its
+   * category's with the opening.
    */
-  const guidance = toolScopeGuidance(scope)
+  const guidance = [...offer.frontGuidance(), offer.catalog()].filter(Boolean)
   const prompt = guidance.length > 0 ? `${systemPrompt}\n\n${guidance.join('\n\n')}` : systemPrompt
 
   /*
@@ -187,7 +199,7 @@ export async function registryAssistantChat(input: RegistryAssistantInput): Prom
     chat: (msgs, toolDefs, opts) => client.chatWithTools!(msgs, toolDefs, opts),
     context: toolContext,
     dispatch: {
-      isReadTool: name => byName.has(name),
+      isReadTool: name => offer.isOffered(name) || offer.isOpenable(name),
       /*
        * This surface has no document, so nothing here can write. Saying so plainly makes the loop
        * report an unknown name back to the model instead of accepting a call and dropping it.
@@ -196,7 +208,10 @@ export async function registryAssistantChat(input: RegistryAssistantInput): Prom
       isActionTool: () => false,
       /* 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 (offer.isOpenable(call.name)) {
+          return { rejected: true, error: 'tool-not-offered', message: `${call.name} is not open yet. Open it with ${OPEN_TOOLS} first, then call it.` }
+        }
+        const spec = offer.offered().find(one => one.name === call.name)
         if (!spec) return undefined
         const args = call.arguments ?? {}
         const started = Date.now()
@@ -219,5 +234,5 @@ export async function registryAssistantChat(input: RegistryAssistantInput): Prom
     t: input.t
   })
 
-  return { ...result, offeredTools: tools.map(tool => tool.name) }
+  return { ...result, offeredTools: offer.offered().map(spec => spec.name), openableTools: offer.openable() }
 }

package/server/service/assistant/tool-budget.test.ts

@@ -0,0 +1,235 @@
+/*
+ * What this guards: **no model call carries more than MAX_OFFERED_TOOLS tools, and nothing a person may do is lost by
+ * it** (ADR-0061 decision 9, operato-application design/ai/tool-budget.md).
+ *
+ * Office's conversation opened 165 tools and OpenAI refuses more than 128, so every turn of a person who may read
+ * everything failed. A scope that fits is offered whole as before. A larger one starts with what the caller puts in
+ * front and `openTools`; the rest is listed in the prompt, opened for the rest of the turn, and run through the same
+ * doors and recorders as any tool.
+ */
+import { registryAssistantChat } from './registry-assistant'
+import { MAX_OFFERED_TOOLS, OPEN_TOOLS, TOOL_BUDGET_CATEGORY, ToolBudgetError, planToolOffer } from './tool-budget'
+import { resolveToolScope } from './tool-scope'
+import { clearToolCallRecorders, clearToolRegistry, registerToolCallRecorder, registerToolCategory, type ToolCallRecord } from '../tool-registry/index.js'
+import type { AIToolCall, AIToolChatResult } from '../types.js'
+
+const TC = (name: string, args: any = {}, id = `t-${name}`): AIToolCall => ({ id, name, arguments: args, type: 'tool_use' } as any)
+const reply = (text?: string, toolCalls: AIToolCall[] = []): AIToolChatResult =>
+  ({ text, toolCalls, stopReason: toolCalls.length > 0 ? 'tool_use' : 'end_turn', usage: undefined } as any)
+
+function recordingClient(replies: AIToolChatResult[] = [reply('answered')]) {
+  const seen: Array<{ tools: any[]; options: any; messages: any[] }> = []
+  let turn = 0
+  return {
+    seen,
+    client: {
+      chatWithTools: async (messages: any[], tools: any[], options: any) => {
+        seen.push({ tools: [...tools], options, messages: [...messages] })
+        return replies[Math.min(turn++, replies.length - 1)]
+      }
+    } as any
+  }
+}
+
+const ran: string[] = []
+
+/** `count` categories of one read tool each - `list-0` … - behind the door `Query.<name>`. */
+function registerLists(count: number, prefix = 'list') {
+  for (let i = 0; i < count; i++) {
+    const name = `read${prefix[0].toUpperCase()}${prefix.slice(1)}${i}`
+    registerToolCategory({
+      name: `${prefix}-${i}`,
+      guidance: `- To answer from ${prefix} ${i}, call ${name}.`,
+      specs: [
+        {
+          kind: 'read',
+          name,
+          description: `Read ${prefix} ${i}. Every number comes from its result.`,
+          doors: [`Query.${name}`],
+          schema: { type: 'object', properties: { from: { type: 'string' } } },
+          builder: () => {
+            ran.push(name)
+            return { rows: [{ i }] }
+          }
+        }
+      ]
+    } as any)
+  }
+  return Array.from({ length: count }, (_, i) => `${prefix}-${i}`)
+}
+
+const input = (over: any = {}) => ({
+  client: recordingClient().client,
+  messages: [{ role: 'user' as const, content: 'how much came in this month' }],
+  systemPrompt: 'you read the books',
+  state: { domain: { id: 'dom-1' }, user: { id: 'u-1' } },
+  toolAccess: async () => true,
+  ...over
+})
+
+const names = (tools: any[]) => tools.map(tool => tool.name)
+
+beforeEach(() => {
+  clearToolRegistry()
+  clearToolCallRecorders()
+  ran.length = 0
+})
+afterAll(() => clearToolCallRecorders())
+
+describe('a scope that fits is offered whole, as before', () => {
+  it('★ every tool, no openTools, no list to open from', async () => {
+    const categories = registerLists(MAX_OFFERED_TOOLS)
+    const { client, seen } = recordingClient()
+    await registryAssistantChat(input({ client, toolCategories: categories }))
+
+    expect(seen[0].tools).toHaveLength(MAX_OFFERED_TOOLS)
+    expect(names(seen[0].tools)).not.toContain(OPEN_TOOLS)
+    expect(seen[0].options.systemPrompt).not.toContain(`Tools you can open with ${OPEN_TOOLS}`)
+    expect(seen[0].options.systemPrompt).toContain('- To answer from list 63, call readList63.')
+  })
+})
+
+describe('a scope larger than one call carries', () => {
+  it('★ the first call carries the front and openTools - never more than the budget', async () => {
+    const categories = registerLists(165)
+    const { client, seen } = recordingClient()
+    await registryAssistantChat(input({ client, toolCategories: categories, front: { categories: ['list-3', 'list-150'] } }))
+
+    expect(names(seen[0].tools)).toEqual(['readList3', 'readList150', OPEN_TOOLS])
+    expect(seen[0].tools.length).toBeLessThanOrEqual(MAX_OFFERED_TOOLS)
+  })
+
+  it('★ the rest is listed once in the prompt, the opening tool says only how to open', async () => {
+    const categories = registerLists(165)
+    const { client, seen } = recordingClient()
+    await registryAssistantChat(input({ client, toolCategories: categories, front: { categories: ['list-3'] } }))
+
+    const prompt = seen[0].options.systemPrompt
+    expect(prompt).toContain(`Tools you can open with ${OPEN_TOOLS}`)
+    expect(prompt).toContain('- readList150: Read list 150.')
+    expect(prompt).not.toContain('- readList3:')
+    /* Only the front's guidance - an unopened list's rules are not read to the model. */
+    expect(prompt).toContain('- To answer from list 3, call readList3.')
+    expect(prompt).not.toContain('call readList150.')
+    const opening = seen[0].tools.find(tool => tool.name === OPEN_TOOLS)
+    expect(opening.description).not.toContain('readList150')
+    expect(opening.description.length).toBeLessThan(1024)
+  })
+
+  it('★ an opened tool is offered from the next call on, with its guidance, and runs', async () => {
+    const categories = registerLists(165)
+    const { client, seen } = recordingClient([
+      reply(undefined, [TC(OPEN_TOOLS, { names: ['readList150'] })]),
+      reply(undefined, [TC('readList150', { from: '2026-10-01' })]),
+      reply('42 came in')
+    ])
+    const result = await registryAssistantChat(input({ client, toolCategories: categories, front: { categories: ['list-3'] } }))
+
+    expect(names(seen[0].tools)).not.toContain('readList150')
+    expect(names(seen[1].tools)).toContain('readList150')
+    const opened = JSON.parse(seen[1].messages.at(-1).content[0].content)
+    expect(opened).toMatchObject({ opened: ['readList150'], guidance: '- To answer from list 150, call readList150.' })
+    expect(ran).toEqual(['readList150'])
+    expect(result.offeredTools).toContain('readList150')
+    /* What it could still have opened - with the offered ones, all this person may use here. */
+    expect(result.openableTools).toHaveLength(165 - 2)
+    expect(result.openableTools).not.toContain('readList150')
+  })
+
+  it('★ the list says its tools are the model\'s to use - not something to tell the person is missing', async () => {
+    const categories = registerLists(165)
+    const { client, seen } = recordingClient()
+    await registryAssistantChat(input({ client, toolCategories: categories, front: { categories: ['list-3'] } }))
+
+    const prompt = seen[0].options.systemPrompt
+    expect(prompt).toMatch(/never tell the person a tool on this list is missing/)
+    expect(prompt).toMatch(/never ask the person to choose instead of opening it/)
+  })
+
+  it('★ opening a tool that is already offered says so - call it now', async () => {
+    const categories = registerLists(165)
+    const { client, seen } = recordingClient([reply(undefined, [TC(OPEN_TOOLS, { names: ['readList3', 'readList150'] })]), reply('done')])
+    await registryAssistantChat(input({ client, toolCategories: categories, front: { categories: ['list-3'] } }))
+
+    expect(JSON.parse(seen[1].messages.at(-1).content[0].content)).toMatchObject({ opened: ['readList150'], alreadyOffered: ['readList3'] })
+  })
+
+  it('★ a tool called before it is opened does not run - the model is told to open it', async () => {
+    const categories = registerLists(165)
+    const { client, seen } = recordingClient([reply(undefined, [TC('readList150')]), reply('done')])
+    await registryAssistantChat(input({ client, toolCategories: categories, front: { categories: ['list-3'] } }))
+
+    expect(ran).toEqual([])
+    expect(JSON.parse(seen[1].messages.at(-1).content[0].content)).toMatchObject({ error: 'tool-not-offered' })
+  })
+
+  it('★ a tool whose door the person cannot pass is not in the list, cannot be opened and never runs', async () => {
+    const categories = registerLists(165)
+    const { client, seen } = recordingClient([reply(undefined, [TC(OPEN_TOOLS, { names: ['readList150'] })]), reply(undefined, [TC('readList150')]), reply('done')])
+    await registryAssistantChat(
+      input({ client, toolCategories: categories, front: { categories: ['list-3'] }, toolAccess: async (door: string) => door !== 'Query.readList150' })
+    )
+
+    expect(seen[0].options.systemPrompt).not.toContain('readList150')
+    expect(JSON.parse(seen[1].messages.at(-1).content[0].content)).toMatchObject({ error: 'tool-not-offered', names: ['readList150'] })
+    expect(names(seen[1].tools)).not.toContain('readList150')
+    expect(ran).toEqual([])
+  })
+
+  it('★ opening past the budget is refused with the room left - no call ever carries more', async () => {
+    const categories = registerLists(165)
+    const many = Array.from({ length: 70 }, (_, i) => `readList${i + 10}`)
+    const { client, seen } = recordingClient([
+      reply(undefined, [TC(OPEN_TOOLS, { names: many })]),
+      reply(undefined, [TC(OPEN_TOOLS, { names: many.slice(0, 20) })]),
+      reply('done')
+    ])
+    await registryAssistantChat(input({ client, toolCategories: categories, front: { categories: ['list-3'] } }))
+
+    expect(JSON.parse(seen[1].messages.at(-1).content[0].content)).toMatchObject({ error: 'tool-budget-exceeded', room: MAX_OFFERED_TOOLS - 2 })
+    expect(seen[2].tools).toHaveLength(22)
+    for (const call of seen) expect(call.tools.length).toBeLessThanOrEqual(MAX_OFFERED_TOOLS)
+  })
+
+  it('★ the front tools fill only the room the categories leave', async () => {
+    const categories = registerLists(165)
+    const scope = await resolveToolScope(categories, async () => true)
+    const front = Array.from({ length: 100 }, (_, i) => `readList${i}`)
+    const plan = planToolOffer(scope, { categories: ['list-150'], tools: front })
+
+    expect(plan.offered).toHaveLength(MAX_OFFERED_TOOLS - 1)
+    expect(plan.offered[0].name).toBe('readList150')
+    expect(plan.openable).toHaveLength(165 - (MAX_OFFERED_TOOLS - 1))
+  })
+
+  it('★ front categories that do not fit are refused loudly, never cut', async () => {
+    const categories = registerLists(165)
+    const scope = await resolveToolScope(categories, async () => true)
+
+    expect(() => planToolOffer(scope, { categories: categories.slice(0, MAX_OFFERED_TOOLS) })).toThrow(ToolBudgetError)
+    await expect(registryAssistantChat(input({ toolCategories: categories, front: { categories: categories.slice(0, 80) } }))).rejects.toMatchObject({
+      code: 'tool-budget-exceeded'
+    })
+  })
+})
+
+describe('opening and the opened tool are recorded like any call (ADR-0061 decision 8, ADR-0141)', () => {
+  it('★ the recorders get the opening, under its own category, and the opened tool under its own', async () => {
+    const recorded: ToolCallRecord[] = []
+    registerToolCallRecorder(record => {
+      recorded.push(record)
+    })
+    const categories = registerLists(165)
+    const { client } = recordingClient([
+      reply(undefined, [TC(OPEN_TOOLS, { names: ['readList150'] })]),
+      reply(undefined, [TC('readList150', { from: '2026-10-01' })]),
+      reply('done')
+    ])
+    await registryAssistantChat(input({ client, toolCategories: categories, front: { categories: ['list-3'] }, mode: { kind: 'office.finance' } }))
+
+    expect(recorded.map(record => [record.tool, record.category, record.ok])).toEqual([
+      [OPEN_TOOLS, TOOL_BUDGET_CATEGORY, true],
+      ['readList150', 'list-150', true]
+    ])
+  })
+})

package/server/service/assistant/tool-budget.ts

@@ -0,0 +1,163 @@
+/*
+ * How many tools one model call carries (ADR-0061 decision 9, operato-application design/ai/tool-budget.md).
+ *
+ * A conversation used to send every tool its mode opened on every call. Office's conversation opened 165, and OpenAI
+ * refuses more than 128 - every turn of a person who may read everything failed. The tools also went with their
+ * guidance, some 140,000 characters a call.
+ *
+ * Now a call carries at most `MAX_OFFERED_TOOLS`. When the scope is larger, the caller names what goes in front (the
+ * screen's records, the tools this conversation used); the rest is listed once in the prompt and the model opens what
+ * it needs with `openTools` for the rest of the turn. Whether a person may use a tool is decided as before - the list
+ * holds only the tools of their scope, and opening runs no tool.
+ */
+import type { ToolSpec } from '../tool-registry/types.js'
+import type { ScopedCategory, ToolScope } from './tool-scope.js'
+
+/** Half the smallest provider limit known (OpenAI, 128). One constant - an application or a mode does not change it. */
+export const MAX_OFFERED_TOOLS = 64
+
+export const OPEN_TOOLS = 'openTools'
+
+/** The category the opening tool is recorded under - it is not registered; no mode names it. */
+export const TOOL_BUDGET_CATEGORY = 'tool-budget'
+
+/** What the caller puts in front when the scope does not fit: whole categories first, then single tools while there is room. */
+export interface ToolFront {
+  categories?: string[]
+  tools?: string[]
+}
+
+export class ToolBudgetError extends Error {
+  code = 'tool-budget-exceeded'
+  constructor(public front: number) {
+    super(`[tool-budget] the tools put in front (${front}) and openTools do not fit in ${MAX_OFFERED_TOOLS} - narrow the mode's own categories`)
+  }
+}
+
+export interface ToolOffer {
+  /** What the first call carries, openTools last when anything is left to open. */
+  offered: ToolSpec[]
+  /** In the scope and not offered - what openTools may open. */
+  openable: ToolSpec[]
+}
+
+/**
+ * What a turn starts with. The whole scope when it fits; otherwise the front categories (all of them, or it throws),
+ * the front tools while there is room, and openTools.
+ */
+export function planToolOffer(scope: ToolScope, front: ToolFront = {}): ToolOffer {
+  if (scope.specs.length <= MAX_OFFERED_TOOLS) return { offered: [...scope.specs], openable: [] }
+
+  const room = MAX_OFFERED_TOOLS - 1
+  const picked = new Map<string, ToolSpec>()
+  for (const name of front.categories ?? []) {
+    for (const spec of scope.categories.find(category => category.name === name)?.specs ?? []) picked.set(spec.name, spec)
+  }
+  if (picked.size > room) throw new ToolBudgetError(picked.size)
+
+  const byName = new Map(scope.specs.map(spec => [spec.name, spec]))
+  for (const name of front.tools ?? []) {
+    if (picked.size >= room) break
+    const spec = byName.get(name)
+    if (spec) picked.set(name, spec)
+  }
+
+  const offered = [...picked.values()]
+  return { offered, openable: scope.specs.filter(spec => !picked.has(spec.name)) }
+}
+
+const ONE_LINE = 160
+
+/** The first sentence of a description, on one line - what the list says of a tool. */
+function oneLine(description: string | undefined): string {
+  const flat = String(description ?? '').replace(/\s+/g, ' ').trim()
+  const sentence = /^(.+?[.!?])(\s|$)/.exec(flat)?.[1] ?? flat
+  return sentence.length > ONE_LINE ? `${sentence.slice(0, ONE_LINE - 1)}…` : sentence
+}
+
+/**
+ * The list of tools the model may open - one function builds it, wherever it goes. It goes in the prompt: OpenAI is
+ * reported to refuse a tool description over 1024 characters, and Office's list runs to some 150 lines.
+ */
+export function openableToolCatalog(openable: ReadonlyArray<ToolSpec>): string {
+  if (openable.length === 0) return ''
+  return [
+    /*
+     * Office's model, offered a bank lines' total it could open, told the person that read was not open and asked them
+     * to pick a range (2026-10-22) - an app's prompt said a missing tool means a missing permission. What is on this
+     * list is the model's to use.
+     */
+    `Tools you can open with ${OPEN_TOOLS} (name: what it does). They are yours to use in this conversation, only not loaded yet. ` +
+      `When the question needs one, open it with ${OPEN_TOOLS} and call it: never tell the person a tool on this list is missing, ` +
+      'and never ask the person to choose instead of opening it.',
+    ...openable.map(spec => `- ${spec.name}: ${oneLine(spec.description)}`)
+  ].join('\n')
+}
+
+/** The opening tool's definition. */
+export function openToolsSpec(open: (names: string[]) => unknown): ToolSpec {
+  return {
+    kind: 'read',
+    name: OPEN_TOOLS,
+    description:
+      `Open more tools for the rest of this answer. Pass the exact names from the list of tools you can open; they are offered from your next step on, with how to use them. At most ${MAX_OFFERED_TOOLS} tools are open at once.`,
+    schema: {
+      type: 'object',
+      required: ['names'],
+      properties: { names: { type: 'array', items: { type: 'string' }, description: 'Names from the list of tools you can open.' } }
+    },
+    builder: (args: any) => open(Array.isArray(args?.names) ? args.names.map(String) : [])
+  } as ToolSpec
+}
+
+/**
+ * The offer of one turn, as it grows. `open` adds tools to what the next call carries; it never runs one.
+ */
+export function toolOfferState(scope: ToolScope, front: ToolFront = {}) {
+  const plan = planToolOffer(scope, front)
+  const openable = new Map(plan.openable.map(spec => [spec.name, spec]))
+  const opening = openable.size > 0 ? openToolsSpec(names => open(names)) : undefined
+  const offered = new Map<string, ToolSpec>([...plan.offered, ...(opening ? [opening] : [])].map(spec => [spec.name, spec]))
+  const categoryOf = new Map<string, ScopedCategory>(scope.categories.flatMap(category => category.specs.map(spec => [spec.name, category] as [string, ScopedCategory])))
+
+  function open(names: string[]) {
+    const unknown = names.filter(name => !openable.has(name) && !offered.has(name))
+    if (unknown.length) {
+      return { rejected: true, error: 'tool-not-offered', names: unknown, message: `these are not in the list of tools you can open: ${unknown.join(', ')}. Use the exact names from the list.` }
+    }
+    const fresh = [...new Set(names)].filter(name => !offered.has(name))
+    const already = [...new Set(names)].filter(name => offered.has(name) && name !== OPEN_TOOLS)
+    const room = MAX_OFFERED_TOOLS - offered.size
+    if (fresh.length > room) {
+      return {
+        rejected: true,
+        error: 'tool-budget-exceeded',
+        room,
+        message: `only ${room} more tools fit in this answer. Open fewer - the ones this question needs - or answer from what you have read.`
+      }
+    }
+    for (const name of fresh) offered.set(name, openable.get(name)!)
+    const guidance = [...new Set(fresh.map(name => categoryOf.get(name)?.guidance).filter(Boolean))]
+    return {
+      opened: fresh,
+      ...(already.length ? { alreadyOffered: already } : {}),
+      ...(guidance.length ? { guidance: guidance.join('\n') } : {}),
+      message: already.length
+        ? `${already.join(', ')} ${already.length > 1 ? 'are' : 'is'} already open - call ${already.length > 1 ? 'them' : 'it'} now. ${fresh.length ? 'The others are open from your next step on.' : ''}`.trim()
+        : 'these tools are open from your next step on. Call them as the question needs.'
+    }
+  }
+
+  return {
+    /** What a call carries now. */
+    offered: () => [...offered.values()],
+    isOffered: (name: string) => offered.has(name),
+    /** In the scope and still to be opened - a call to one is answered with how to open it. */
+    isOpenable: (name: string) => openable.has(name) && !offered.has(name),
+    /** In the scope and not offered now. */
+    openable: () => [...openable.keys()].filter(name => !offered.has(name)),
+    /** The guidance of the categories in front - opened ones bring theirs with the result. */
+    frontGuidance: () => [...new Set(plan.offered.map(spec => categoryOf.get(spec.name)?.guidance).filter(Boolean) as string[])],
+    catalog: () => openableToolCatalog(plan.openable)
+  }
+}

package/translations/ko.json

@@ -1,7 +1,7 @@
 {
   "error.ai-not-configured": "이 사업장에는 AI 가 설정되어 있지 않습니다.",
   "error.ai-agent-not-available": "선택한 AI 에이전트를 이 사업장에서 사용할 수 없습니다.",
-  "error.ai-agent-provider-unknown": "\"{provider}\" 은(는) 에이전트가 쓸 수 있는 제공처가 아닙니다.",
+  "error.ai-agent-provider-unknown": "\"{provider}\"은(는) 에이전트에서 지원하지 않는 제공자입니다.",
   "error.ai-agent-key-required": "\"{agent}\" 의 API 키를 입력해 주세요.",
   "error.ai-agent-name-required": "에이전트마다 이름이 있어야 합니다.",
   "error.ai-agent-model-required": "\"{agent}\" 의 모델을 선택해 주세요.",