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

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

@@ -2,6 +2,7 @@ import type { AIClient, AIMessage } from '../types.js';
 import { type ToolAccessCheck } from './tool-scope.js';
 import { type AssistantChatResult } from './assistant-chat.js';
 import type { GroundingSources } from '../utils/index.js';
+import type { ToolAttachment } from '../tool-registry/types.js';
 /** Lookups a registry conversation may take before it answers from what it has (operato-twin's assistant takes 16 too). */
 export declare const REGISTRY_MAX_ITERATIONS = 16;
 export interface RegistryAssistantInput {
@@ -43,8 +44,17 @@ export interface RegistryAssistantInput {
     maxTokens?: number;
     /** Make the model call a tool before it may answer. For surfaces that report live state. */
     requireToolOnFirstTurn?: boolean;
-    /** The request's translator — the stop notice is then in the reader's language. */
+    /**
+     * The request's translator — the stop notice is then in the reader's language, and tools write what a person
+     * reads with it (`context.t`). Without it tools get `defaultValueTranslate`: the English default values.
+     */
     t?: (key: string, params?: Record<string, any>) => string;
+    /**
+     * The files sent with this turn, after the caller's server checked them — stored with this conversation, the
+     * conversation the caller's to write, the mode's policy met (ADR-0061, 2026-10-16 decision 2). Tools see them as
+     * `context.attachments`. Never built from the client's request: what a client puts in `hostContext` stays there.
+     */
+    attachments?: ToolAttachment[];
     /** Texts the answer is allowed to draw identifiers from, besides the tool results. */
     groundingSources?: Omit<GroundingSources, 'toolResults'>;
 }

package/dist-server/service/assistant/registry-assistant.js

@@ -5,6 +5,7 @@ exports.registryAssistantChat = registryAssistantChat;
 const tool_scope_js_1 = require("./tool-scope.js");
 const assistant_chat_js_1 = require("./assistant-chat.js");
 const summarize_js_1 = require("./summarize.js");
+const translate_js_1 = require("../tool-registry/translate.js");
 /** Lookups a registry conversation may take before it answers from what it has (operato-twin's assistant takes 16 too). */
 exports.REGISTRY_MAX_ITERATIONS = 16;
 /**
@@ -42,7 +43,14 @@ async function registryAssistantChat(input) {
      * `mode` 는 서버의 값이다 — 등록된 모드에서 왔고, `host` 와 달리 클라이언트가 못 고친다. A2 가 서기
      * 전에는 채울 것이 없어 비워 두었다(ADR-0061 결정 3 의 주석). 이제 부르는 쪽이 들고 있다.
      */
-    const toolContext = { state, host: hostContext ?? {}, ...(input.mode ? { mode: input.mode } : {}) };
+    const toolContext = {
+        state,
+        host: hostContext ?? {},
+        ...(input.mode ? { mode: input.mode } : {}),
+        /* 번역기와 첨부는 서버의 값이다 — `host` 에서 받지 않는다(ADR-0061 2026-10-16 판정 1·2). */
+        t: input.t ?? translate_js_1.defaultValueTranslate,
+        attachments: input.attachments ?? []
+    };
     const result = await (0, assistant_chat_js_1.assistantChat)({
         initialConversation: messages,
         tools,

package/dist-server/service/assistant/registry-assistant.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry-assistant.js","sourceRoot":"","sources":["../../../server/service/assistant/registry-assistant.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * A conversation for a product that has no editor of its own.\n *\n * ── What this is for ───────────────────────────────────────────────────────────\n * `board-ai` assembles its conversation from two sources: its own board editing tools, and\n * whatever other packages registered in the tool registry. The second half is the same work for\n * every product — read the specs, build the definitions, dispatch by name — but it only existed\n * inside the board assistant, so a product without a board had nowhere to ask a question from.\n * operato-figure hit exactly that: the dock was mounted, the tools were registered, and the only\n * mutation that could run them lived in a package figure does not load.\n *\n * ── Read only ──────────────────────────────────────────────────────────────────\n * A registry category may also carry `write` and `action` tools. Those produce edit ops for a\n * document the host owns, and a host with no document cannot apply them. Offering them here would\n * declare a door with no road behind it — the model would call one and the call would go nowhere.\n * `external` tools change something outside the conversation (board-import's\n * `materializeImportSession` creates a Board) and this door has no confirm-and-apply step, so they\n * are not offered either (A1, 2026-09-17). This runner offers, and dispatches, `read` only.\n *\n * The gate answers from the same list the definitions are built from, so what is offered and what\n * may be dispatched cannot drift apart.\n */\nimport type { AIClient, AIMessage } from '../types.js'\nimport { narrowToolScope, resolveToolScope, toolScopeGuidance, type ToolAccessCheck } from './tool-scope.js'\nimport { assistantChat, type AssistantChatResult } from './assistant-chat.js'\nimport { summarizeToolResult } from './summarize.js'\nimport type { GroundingSources } from '../utils/index.js'\nimport type { ToolCallContext } from '../tool-registry/types.js'\n\n\n/** Lookups a registry conversation may take before it answers from what it has (operato-twin's assistant takes 16 too). */\nexport const REGISTRY_MAX_ITERATIONS = 16\n\nexport interface RegistryAssistantInput {\n  /** Provider client. Must implement `chatWithTools`. */\n  client: AIClient\n  /** The conversation so far, newest last. The caller owns history and truncation. */\n  messages: AIMessage[]\n  /** Who the assistant is and what this surface is. The host owns this prose. */\n  systemPrompt: string\n  /**\n   * Categories this conversation may use. **Omitting it allows nothing** — the same as an empty\n   * list, a plain conversation with no tools (A1, 2026-09-17). It used to mean every registered\n   * category, which is how a Board-creating tool reached any conversation.\n   */\n  toolCategories?: string[]\n  /**\n   * Answers whether the caller holds a tool's declared privilege. Without it, every tool that\n   * declares a privilege stays closed. The host builds it from the request — this package does\n   * not know auth.\n   */\n  toolAccess?: ToolAccessCheck\n  /** Passed to tools as `context.host`. Client-supplied — never used for authorization. */\n  hostContext?: any\n  /**\n   * Which conversation this is — `{ kind, target }` from the registered mode (ADR-0061 decision 3).\n   *\n   * Tools see it as `context.mode`. It is the server's value, resolved from the registry before the\n   * turn runs, so a tool that behaves differently in two conversations reads it here and not from\n   * `host`, which the client fills.\n   */\n  mode?: { kind: string; target?: string }\n  /** Caller's koa state (domain, user, tx). Tools that read the database need it. */\n  state: any\n  model?: string\n  temperature?: number\n  maxTokens?: number\n  /** Make the model call a tool before it may answer. For surfaces that report live state. */\n  requireToolOnFirstTurn?: boolean\n  /** The request's translator — the stop notice is then in the reader's language. */\n  t?: (key: string, params?: Record<string, any>) => string\n  /** Texts the answer is allowed to draw identifiers from, besides the tool results. */\n  groundingSources?: Omit<GroundingSources, 'toolResults'>\n}\n\nexport interface RegistryAssistantResult extends AssistantChatResult<unknown> {\n  /** Tool names actually offered to the model this turn. The caller may log or return it. */\n  offeredTools: string[]\n}\n\n/**\n * Run one turn of a conversation whose only tools come from the registry.\n *\n * Throws when the client cannot use tools at all — a surface built on registered tools that\n * silently ran without them would answer from nothing and look like it had checked.\n */\nexport async function registryAssistantChat(input: RegistryAssistantInput): Promise<RegistryAssistantResult> {\n  const { client, messages, systemPrompt, toolCategories, hostContext, state } = input\n\n  if (!client.chatWithTools) {\n    throw new Error('[registry-assistant] the configured AI client cannot call tools, so this conversation cannot run')\n  }\n\n  /*\n   * Only `read` is offered here. `external` means the tool changes something outside the\n   * conversation (board-import's `materializeImportSession` creates a Board); this door answers\n   * questions and has no confirm-and-apply step, so a tool with an effect does not go through it\n   * even when the caller holds the privilege.\n   */\n  const scope = narrowToolScope(\n    await resolveToolScope(toolCategories, input.toolAccess),\n    spec => spec.kind === 'read'\n  )\n  const specs = scope.specs\n  const byName = new Map(specs.map(spec => [spec.name, spec]))\n\n  const tools = specs.map(spec => ({\n    name: spec.name,\n    description: spec.themeNote ? `${spec.description} ${spec.themeNote}` : spec.description,\n    parameters: spec.schema\n  }))\n\n  /*\n   * The rules for using a tool belong to whoever registered it. Collect only the exposed ones, so\n   * a surface never reads instructions for a category it cannot call.\n   */\n  const guidance = toolScopeGuidance(scope)\n  const prompt = guidance.length > 0 ? `${systemPrompt}\\n\\n${guidance.join('\\n\\n')}` : systemPrompt\n\n  /*\n   * `mode` 는 서버의 값이다 — 등록된 모드에서 왔고, `host` 와 달리 클라이언트가 못 고친다. A2 가 서기\n   * 전에는 채울 것이 없어 비워 두었다(ADR-0061 결정 3 의 주석). 이제 부르는 쪽이 들고 있다.\n   */\n  const toolContext: ToolCallContext = { state, host: hostContext ?? {}, ...(input.mode ? { mode: input.mode } : {}) }\n\n  const result = await assistantChat<ToolCallContext, unknown>({\n    initialConversation: messages,\n    tools,\n    options: {\n      systemPrompt: prompt,\n      model: input.model,\n      temperature: input.temperature,\n      maxTokens: input.maxTokens,\n      requireToolOnFirstTurn: input.requireToolOnFirstTurn,\n      /*\n       * A question across a product's records takes many lookups. At the limit the model answers from\n       * what it read and says what is missing — the person is never told to split the question.\n       */\n      maxIterations: REGISTRY_MAX_ITERATIONS,\n      salvageOnMaxIterations: true\n    },\n    chat: (msgs, toolDefs, opts) => client.chatWithTools!(msgs, toolDefs, opts),\n    context: toolContext,\n    dispatch: {\n      isReadTool: name => byName.has(name),\n      /*\n       * This surface has no document, so nothing here can write. Saying so plainly makes the loop\n       * report an unknown name back to the model instead of accepting a call and dropping it.\n       */\n      isWriteTool: () => false,\n      isActionTool: () => false,\n      executeReadTool: (call, context) => {\n        const spec = byName.get(call.name)\n        if (!spec) return undefined\n        return (spec.builder as any)(call.arguments ?? {}, context)\n      },\n      validateWriteToolCall: () => ({ valid: false, errors: ['this conversation has no document to write to'] }),\n      toolCallToOp: () => null,\n      summarizeToolResult\n    },\n    groundingSources: input.groundingSources,\n    t: input.t\n  })\n\n  return { ...result, offeredTools: tools.map(tool => tool.name) }\n}\n"]}
+{"version":3,"file":"registry-assistant.js","sourceRoot":"","sources":["../../../server/service/assistant/registry-assistant.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * A conversation for a product that has no editor of its own.\n *\n * ── What this is for ───────────────────────────────────────────────────────────\n * `board-ai` assembles its conversation from two sources: its own board editing tools, and\n * whatever other packages registered in the tool registry. The second half is the same work for\n * every product — read the specs, build the definitions, dispatch by name — but it only existed\n * inside the board assistant, so a product without a board had nowhere to ask a question from.\n * operato-figure hit exactly that: the dock was mounted, the tools were registered, and the only\n * mutation that could run them lived in a package figure does not load.\n *\n * ── Read only ──────────────────────────────────────────────────────────────────\n * A registry category may also carry `write` and `action` tools. Those produce edit ops for a\n * document the host owns, and a host with no document cannot apply them. Offering them here would\n * declare a door with no road behind it — the model would call one and the call would go nowhere.\n * `external` tools change something outside the conversation (board-import's\n * `materializeImportSession` creates a Board) and this door has no confirm-and-apply step, so they\n * are not offered either (A1, 2026-09-17). This runner offers, and dispatches, `read` only.\n *\n * The gate answers from the same list the definitions are built from, so what is offered and what\n * may be dispatched cannot drift apart.\n */\nimport type { AIClient, AIMessage } from '../types.js'\nimport { narrowToolScope, resolveToolScope, toolScopeGuidance, type ToolAccessCheck } from './tool-scope.js'\nimport { assistantChat, type AssistantChatResult } from './assistant-chat.js'\nimport { summarizeToolResult } from './summarize.js'\nimport type { GroundingSources } from '../utils/index.js'\nimport type { ToolAttachment, ToolCallContext } from '../tool-registry/types.js'\nimport { defaultValueTranslate } from '../tool-registry/translate.js'\n\n\n/** Lookups a registry conversation may take before it answers from what it has (operato-twin's assistant takes 16 too). */\nexport const REGISTRY_MAX_ITERATIONS = 16\n\nexport interface RegistryAssistantInput {\n  /** Provider client. Must implement `chatWithTools`. */\n  client: AIClient\n  /** The conversation so far, newest last. The caller owns history and truncation. */\n  messages: AIMessage[]\n  /** Who the assistant is and what this surface is. The host owns this prose. */\n  systemPrompt: string\n  /**\n   * Categories this conversation may use. **Omitting it allows nothing** — the same as an empty\n   * list, a plain conversation with no tools (A1, 2026-09-17). It used to mean every registered\n   * category, which is how a Board-creating tool reached any conversation.\n   */\n  toolCategories?: string[]\n  /**\n   * Answers whether the caller holds a tool's declared privilege. Without it, every tool that\n   * declares a privilege stays closed. The host builds it from the request — this package does\n   * not know auth.\n   */\n  toolAccess?: ToolAccessCheck\n  /** Passed to tools as `context.host`. Client-supplied — never used for authorization. */\n  hostContext?: any\n  /**\n   * Which conversation this is — `{ kind, target }` from the registered mode (ADR-0061 decision 3).\n   *\n   * Tools see it as `context.mode`. It is the server's value, resolved from the registry before the\n   * turn runs, so a tool that behaves differently in two conversations reads it here and not from\n   * `host`, which the client fills.\n   */\n  mode?: { kind: string; target?: string }\n  /** Caller's koa state (domain, user, tx). Tools that read the database need it. */\n  state: any\n  model?: string\n  temperature?: number\n  maxTokens?: number\n  /** Make the model call a tool before it may answer. For surfaces that report live state. */\n  requireToolOnFirstTurn?: boolean\n  /**\n   * The request's translator — the stop notice is then in the reader's language, and tools write what a person\n   * reads with it (`context.t`). Without it tools get `defaultValueTranslate`: the English default values.\n   */\n  t?: (key: string, params?: Record<string, any>) => string\n  /**\n   * The files sent with this turn, after the caller's server checked them — stored with this conversation, the\n   * conversation the caller's to write, the mode's policy met (ADR-0061, 2026-10-16 decision 2). Tools see them as\n   * `context.attachments`. Never built from the client's request: what a client puts in `hostContext` stays there.\n   */\n  attachments?: ToolAttachment[]\n  /** Texts the answer is allowed to draw identifiers from, besides the tool results. */\n  groundingSources?: Omit<GroundingSources, 'toolResults'>\n}\n\nexport interface RegistryAssistantResult extends AssistantChatResult<unknown> {\n  /** Tool names actually offered to the model this turn. The caller may log or return it. */\n  offeredTools: string[]\n}\n\n/**\n * Run one turn of a conversation whose only tools come from the registry.\n *\n * Throws when the client cannot use tools at all — a surface built on registered tools that\n * silently ran without them would answer from nothing and look like it had checked.\n */\nexport async function registryAssistantChat(input: RegistryAssistantInput): Promise<RegistryAssistantResult> {\n  const { client, messages, systemPrompt, toolCategories, hostContext, state } = input\n\n  if (!client.chatWithTools) {\n    throw new Error('[registry-assistant] the configured AI client cannot call tools, so this conversation cannot run')\n  }\n\n  /*\n   * Only `read` is offered here. `external` means the tool changes something outside the\n   * conversation (board-import's `materializeImportSession` creates a Board); this door answers\n   * questions and has no confirm-and-apply step, so a tool with an effect does not go through it\n   * even when the caller holds the privilege.\n   */\n  const scope = narrowToolScope(\n    await resolveToolScope(toolCategories, input.toolAccess),\n    spec => spec.kind === 'read'\n  )\n  const specs = scope.specs\n  const byName = new Map(specs.map(spec => [spec.name, spec]))\n\n  const tools = specs.map(spec => ({\n    name: spec.name,\n    description: spec.themeNote ? `${spec.description} ${spec.themeNote}` : spec.description,\n    parameters: spec.schema\n  }))\n\n  /*\n   * The rules for using a tool belong to whoever registered it. Collect only the exposed ones, so\n   * a surface never reads instructions for a category it cannot call.\n   */\n  const guidance = toolScopeGuidance(scope)\n  const prompt = guidance.length > 0 ? `${systemPrompt}\\n\\n${guidance.join('\\n\\n')}` : systemPrompt\n\n  /*\n   * `mode` 는 서버의 값이다 — 등록된 모드에서 왔고, `host` 와 달리 클라이언트가 못 고친다. A2 가 서기\n   * 전에는 채울 것이 없어 비워 두었다(ADR-0061 결정 3 의 주석). 이제 부르는 쪽이 들고 있다.\n   */\n  const toolContext: ToolCallContext = {\n    state,\n    host: hostContext ?? {},\n    ...(input.mode ? { mode: input.mode } : {}),\n    /* 번역기와 첨부는 서버의 값이다 — `host` 에서 받지 않는다(ADR-0061 2026-10-16 판정 1·2). */\n    t: input.t ?? defaultValueTranslate,\n    attachments: input.attachments ?? []\n  }\n\n  const result = await assistantChat<ToolCallContext, unknown>({\n    initialConversation: messages,\n    tools,\n    options: {\n      systemPrompt: prompt,\n      model: input.model,\n      temperature: input.temperature,\n      maxTokens: input.maxTokens,\n      requireToolOnFirstTurn: input.requireToolOnFirstTurn,\n      /*\n       * A question across a product's records takes many lookups. At the limit the model answers from\n       * what it read and says what is missing — the person is never told to split the question.\n       */\n      maxIterations: REGISTRY_MAX_ITERATIONS,\n      salvageOnMaxIterations: true\n    },\n    chat: (msgs, toolDefs, opts) => client.chatWithTools!(msgs, toolDefs, opts),\n    context: toolContext,\n    dispatch: {\n      isReadTool: name => byName.has(name),\n      /*\n       * This surface has no document, so nothing here can write. Saying so plainly makes the loop\n       * report an unknown name back to the model instead of accepting a call and dropping it.\n       */\n      isWriteTool: () => false,\n      isActionTool: () => false,\n      executeReadTool: (call, context) => {\n        const spec = byName.get(call.name)\n        if (!spec) return undefined\n        return (spec.builder as any)(call.arguments ?? {}, context)\n      },\n      validateWriteToolCall: () => ({ valid: false, errors: ['this conversation has no document to write to'] }),\n      toolCallToOp: () => null,\n      summarizeToolResult\n    },\n    groundingSources: input.groundingSources,\n    t: input.t\n  })\n\n  return { ...result, offeredTools: tools.map(tool => tool.name) }\n}\n"]}

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

@@ -1,4 +1,4 @@
-import type { ToolCallContext, ToolCallMode } from '../tool-registry/types.js';
+import type { ToolAttachment, ToolCallContext, ToolCallMode, ToolTranslate } from '../tool-registry/types.js';
 export interface ToolCallContextFixtureInput {
     domainId?: string;
     userId?: string;
@@ -6,5 +6,9 @@ export interface ToolCallContextFixtureInput {
     state?: Record<string, any>;
     host?: Record<string, any>;
     mode?: ToolCallMode;
+    /** The request translator. Absent: the one the door hands when it was given none. */
+    t?: ToolTranslate;
+    /** The checked files of the turn. Absent: none. */
+    attachments?: ToolAttachment[];
 }
 export declare function toolCallContextFixture(input?: ToolCallContextFixtureInput): ToolCallContext;

package/dist-server/service/testing/tool-call-context.js

@@ -1,10 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toolCallContextFixture = toolCallContextFixture;
+const translate_js_1 = require("../tool-registry/translate.js");
 function toolCallContextFixture(input = {}) {
     const context = {
         state: { domain: { id: input.domainId ?? 'domain-test' }, user: { id: input.userId ?? 'user-test' }, ...(input.state ?? {}) },
-        host: input.host ?? {}
+        host: input.host ?? {},
+        t: input.t ?? translate_js_1.defaultValueTranslate,
+        attachments: input.attachments ?? []
     };
     if (input.mode)
         context.mode = input.mode;

package/dist-server/service/testing/tool-call-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-call-context.js","sourceRoot":"","sources":["../../../server/service/testing/tool-call-context.ts"],"names":[],"mappings":";;AAoBA,wDAOC;AAPD,SAAgB,sBAAsB,CAAC,QAAqC,EAAE;IAC5E,MAAM,OAAO,GAAoB;QAC/B,KAAK,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,KAAK,CAAC,QAAQ,IAAI,aAAa,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,KAAK,CAAC,MAAM,IAAI,WAAW,EAAE,EAAE,GAAG,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE;QAC7H,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,EAAE;KACvB,CAAA;IACD,IAAI,KAAK,CAAC,IAAI;QAAE,OAAO,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAA;IACzC,OAAO,OAAO,CAAA;AAChB,CAAC","sourcesContent":["/*\n * The one way a test builds what a registered tool is handed (A3, 2026-09-17).\n *\n * The twin's space tools read `ctx.state.host` while the door passed `ctx.host`, and their tests\n * stayed green because each test wrote its own context in the shape the tool expected. A fixture\n * owned by each test agrees with its tool by construction. This one is owned by the package that\n * defines the neutral door, and that door's tests check it hands tools exactly this shape — so a tool\n * test built on it fails when the tool reads a field no door fills.\n */\nimport type { ToolCallContext, ToolCallMode } from '../tool-registry/types.js'\n\nexport interface ToolCallContextFixtureInput {\n  domainId?: string\n  userId?: string\n  /** Extra request-state fields a tool reads (e.g. `tx`). Merged after domain and user. */\n  state?: Record<string, any>\n  host?: Record<string, any>\n  mode?: ToolCallMode\n}\n\nexport function toolCallContextFixture(input: ToolCallContextFixtureInput = {}): ToolCallContext {\n  const context: ToolCallContext = {\n    state: { domain: { id: input.domainId ?? 'domain-test' }, user: { id: input.userId ?? 'user-test' }, ...(input.state ?? {}) },\n    host: input.host ?? {}\n  }\n  if (input.mode) context.mode = input.mode\n  return context\n}\n"]}
+{"version":3,"file":"tool-call-context.js","sourceRoot":"","sources":["../../../server/service/testing/tool-call-context.ts"],"names":[],"mappings":";;AAyBA,wDASC;AAxBD,gEAAqE;AAerE,SAAgB,sBAAsB,CAAC,QAAqC,EAAE;IAC5E,MAAM,OAAO,GAAoB;QAC/B,KAAK,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,KAAK,CAAC,QAAQ,IAAI,aAAa,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,KAAK,CAAC,MAAM,IAAI,WAAW,EAAE,EAAE,GAAG,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE;QAC7H,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,EAAE;QACtB,CAAC,EAAE,KAAK,CAAC,CAAC,IAAI,oCAAqB;QACnC,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,EAAE;KACrC,CAAA;IACD,IAAI,KAAK,CAAC,IAAI;QAAE,OAAO,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAA;IACzC,OAAO,OAAO,CAAA;AAChB,CAAC","sourcesContent":["/*\n * The one way a test builds what a registered tool is handed (A3, 2026-09-17).\n *\n * The twin's space tools read `ctx.state.host` while the door passed `ctx.host`, and their tests\n * stayed green because each test wrote its own context in the shape the tool expected. A fixture\n * owned by each test agrees with its tool by construction. This one is owned by the package that\n * defines the neutral door, and that door's tests check it hands tools exactly this shape — so a tool\n * test built on it fails when the tool reads a field no door fills.\n */\nimport type { ToolAttachment, ToolCallContext, ToolCallMode, ToolTranslate } from '../tool-registry/types.js'\nimport { defaultValueTranslate } from '../tool-registry/translate.js'\n\nexport interface ToolCallContextFixtureInput {\n  domainId?: string\n  userId?: string\n  /** Extra request-state fields a tool reads (e.g. `tx`). Merged after domain and user. */\n  state?: Record<string, any>\n  host?: Record<string, any>\n  mode?: ToolCallMode\n  /** The request translator. Absent: the one the door hands when it was given none. */\n  t?: ToolTranslate\n  /** The checked files of the turn. Absent: none. */\n  attachments?: ToolAttachment[]\n}\n\nexport function toolCallContextFixture(input: ToolCallContextFixtureInput = {}): ToolCallContext {\n  const context: ToolCallContext = {\n    state: { domain: { id: input.domainId ?? 'domain-test' }, user: { id: input.userId ?? 'user-test' }, ...(input.state ?? {}) },\n    host: input.host ?? {},\n    t: input.t ?? defaultValueTranslate,\n    attachments: input.attachments ?? []\n  }\n  if (input.mode) context.mode = input.mode\n  return context\n}\n"]}

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

@@ -4,5 +4,6 @@
  * 자세한 설계는 ./types 와 ./registry 의 헤더 주석 참조.
  */
 export { registerToolCategory, getToolCategories, getAllToolSpecs, getToolSpecsFor, getCategoryGuidance, findToolSpec, getToolKind, hasTool, getCategorySpecs, clearToolRegistry, getToolRegistryWarnings } from './registry';
+export { defaultValueTranslate } from './translate';
 export type { ToolCategoryFilter, ToolRegistryWarning } from './registry';
-export type { ToolSpec, ToolSpecBase, ReadToolSpec, WriteToolSpec, ActionToolSpec, ExternalToolSpec, ToolCategory, ReadToolBuilder, WriteToolBuilder, ActionToolBuilder, ExternalToolBuilder, ReadToolContext, WriteToolContext, ExternalToolContext, ToolCallContext, ToolCallMode } from './types';
+export type { ToolSpec, ToolSpecBase, ReadToolSpec, WriteToolSpec, ActionToolSpec, ExternalToolSpec, ToolCategory, ReadToolBuilder, WriteToolBuilder, ActionToolBuilder, ExternalToolBuilder, ReadToolContext, WriteToolContext, ExternalToolContext, ToolCallContext, ToolCallMode, ToolTranslate, ToolAttachment, ToolImageAttachment, ToolTextAttachment } from './types';

package/dist-server/service/tool-registry/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getToolRegistryWarnings = exports.clearToolRegistry = exports.getCategorySpecs = exports.hasTool = exports.getToolKind = exports.findToolSpec = exports.getCategoryGuidance = exports.getToolSpecsFor = exports.getAllToolSpecs = exports.getToolCategories = exports.registerToolCategory = void 0;
+exports.defaultValueTranslate = exports.getToolRegistryWarnings = exports.clearToolRegistry = exports.getCategorySpecs = exports.hasTool = exports.getToolKind = exports.findToolSpec = exports.getCategoryGuidance = exports.getToolSpecsFor = exports.getAllToolSpecs = exports.getToolCategories = exports.registerToolCategory = void 0;
 /**
  * Tool Registry — board-ai 의 외부 도메인 LLM tool 노출 plugin point.
  *
@@ -18,4 +18,6 @@ Object.defineProperty(exports, "hasTool", { enumerable: true, get: function () {
 Object.defineProperty(exports, "getCategorySpecs", { enumerable: true, get: function () { return registry_1.getCategorySpecs; } });
 Object.defineProperty(exports, "clearToolRegistry", { enumerable: true, get: function () { return registry_1.clearToolRegistry; } });
 Object.defineProperty(exports, "getToolRegistryWarnings", { enumerable: true, get: function () { return registry_1.getToolRegistryWarnings; } });
+var translate_1 = require("./translate");
+Object.defineProperty(exports, "defaultValueTranslate", { enumerable: true, get: function () { return translate_1.defaultValueTranslate; } });
 //# sourceMappingURL=index.js.map

package/dist-server/service/tool-registry/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../server/service/tool-registry/index.ts"],"names":[],"mappings":";;;AAAA;;;;GAIG;AACH,uCAYmB;AAXjB,gHAAA,oBAAoB,OAAA;AACpB,6GAAA,iBAAiB,OAAA;AACjB,2GAAA,eAAe,OAAA;AACf,2GAAA,eAAe,OAAA;AACf,+GAAA,mBAAmB,OAAA;AACnB,wGAAA,YAAY,OAAA;AACZ,uGAAA,WAAW,OAAA;AACX,mGAAA,OAAO,OAAA;AACP,4GAAA,gBAAgB,OAAA;AAChB,6GAAA,iBAAiB,OAAA;AACjB,mHAAA,uBAAuB,OAAA","sourcesContent":["/**\n * Tool Registry — board-ai 의 외부 도메인 LLM tool 노출 plugin point.\n *\n * 자세한 설계는 ./types 와 ./registry 의 헤더 주석 참조.\n */\nexport {\n  registerToolCategory,\n  getToolCategories,\n  getAllToolSpecs,\n  getToolSpecsFor,\n  getCategoryGuidance,\n  findToolSpec,\n  getToolKind,\n  hasTool,\n  getCategorySpecs,\n  clearToolRegistry,\n  getToolRegistryWarnings\n} from './registry'\n\n/* 대화별 노출 제한 타입은 registry 소유(정의가 거기 있다). */\nexport type { ToolCategoryFilter, ToolRegistryWarning } from './registry'\n\nexport type {\n  ToolSpec,\n  ToolSpecBase,\n  ReadToolSpec,\n  WriteToolSpec,\n  ActionToolSpec,\n  ExternalToolSpec,\n  ToolCategory,\n  ReadToolBuilder,\n  WriteToolBuilder,\n  ActionToolBuilder,\n  ExternalToolBuilder,\n  ReadToolContext,\n  WriteToolContext,\n  ExternalToolContext,\n  ToolCallContext,\n  ToolCallMode\n} from './types'\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../server/service/tool-registry/index.ts"],"names":[],"mappings":";;;AAAA;;;;GAIG;AACH,uCAYmB;AAXjB,gHAAA,oBAAoB,OAAA;AACpB,6GAAA,iBAAiB,OAAA;AACjB,2GAAA,eAAe,OAAA;AACf,2GAAA,eAAe,OAAA;AACf,+GAAA,mBAAmB,OAAA;AACnB,wGAAA,YAAY,OAAA;AACZ,uGAAA,WAAW,OAAA;AACX,mGAAA,OAAO,OAAA;AACP,4GAAA,gBAAgB,OAAA;AAChB,6GAAA,iBAAiB,OAAA;AACjB,mHAAA,uBAAuB,OAAA;AAGzB,yCAAmD;AAA1C,kHAAA,qBAAqB,OAAA","sourcesContent":["/**\n * Tool Registry — board-ai 의 외부 도메인 LLM tool 노출 plugin point.\n *\n * 자세한 설계는 ./types 와 ./registry 의 헤더 주석 참조.\n */\nexport {\n  registerToolCategory,\n  getToolCategories,\n  getAllToolSpecs,\n  getToolSpecsFor,\n  getCategoryGuidance,\n  findToolSpec,\n  getToolKind,\n  hasTool,\n  getCategorySpecs,\n  clearToolRegistry,\n  getToolRegistryWarnings\n} from './registry'\n\nexport { defaultValueTranslate } from './translate'\n\n/* 대화별 노출 제한 타입은 registry 소유(정의가 거기 있다). */\nexport type { ToolCategoryFilter, ToolRegistryWarning } from './registry'\n\nexport type {\n  ToolSpec,\n  ToolSpecBase,\n  ReadToolSpec,\n  WriteToolSpec,\n  ActionToolSpec,\n  ExternalToolSpec,\n  ToolCategory,\n  ReadToolBuilder,\n  WriteToolBuilder,\n  ActionToolBuilder,\n  ExternalToolBuilder,\n  ReadToolContext,\n  WriteToolContext,\n  ExternalToolContext,\n  ToolCallContext,\n  ToolCallMode,\n  ToolTranslate,\n  ToolAttachment,\n  ToolImageAttachment,\n  ToolTextAttachment\n} from './types'\n"]}

package/dist-server/service/tool-registry/translate.d.ts

@@ -0,0 +1,2 @@
+import type { ToolTranslate } from './types';
+export declare const defaultValueTranslate: ToolTranslate;

package/dist-server/service/tool-registry/translate.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultValueTranslate = void 0;
+const defaultValueTranslate = (key, params) => String(params?.defaultValue ?? key).replace(/\{(\w+)\}/g, (whole, name) => (params && name in params ? String(params[name]) : whole));
+exports.defaultValueTranslate = defaultValueTranslate;
+//# sourceMappingURL=translate.js.map

package/dist-server/service/tool-registry/translate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"translate.js","sourceRoot":"","sources":["../../../server/service/tool-registry/translate.ts"],"names":[],"mappings":";;;AAUO,MAAM,qBAAqB,GAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,CAClE,MAAM,CAAC,MAAM,EAAE,YAAY,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,MAAM,IAAI,IAAI,IAAI,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAA;AAD1H,QAAA,qBAAqB,yBACqG","sourcesContent":["/*\n * The translator a tool gets when the door was given none (ADR-0061, 2026-10-16 decision 1).\n *\n * A door that runs outside a request — a test, a job — has no request locale. The tool still writes the sentence a\n * person reads: the English default value, as i18next does with its own fallback language, with the placeholders\n * filled. A key with no default value comes back as the key, so a reader that compares (`wordsOf`) knows nothing was\n * translated. One constant, so the door and the shared fixture hand the same function.\n */\nimport type { ToolTranslate } from './types'\n\nexport const defaultValueTranslate: ToolTranslate = (key, params) =>\n  String(params?.defaultValue ?? key).replace(/\\{(\\w+)\\}/g, (whole, name) => (params && name in params ? String(params[name]) : whole))\n"]}

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

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

package/dist-server/service/tool-registry/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../server/service/tool-registry/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,uEAAuE;AACvE,kEAAkE;AAClE,iFAAiF;AACjF,mEAAmE;AACnE,wDAAwD","sourcesContent":["/**\n * Tool Registry — board-ai 의 LLM tool 노출 plugin point.\n *\n * 동기:\n *   기존엔 board-ai 가 자기 도메인 (board edit) tool 들만 hardcoded 정의했고, styling\n *   영역만 STYLING_TOOLS registry 로 분리되어 있었다. 외부 도메인 패키지 (board-import,\n *   fmsim 등) 가 자기 tool 을 LLM 에 노출하려면 board-ai 자체를 fork/수정해야 했다.\n *\n *   본 registry 는 외부 패키지가 server bootstrap 시 자기 tool category 를 등록하면\n *   assistant.ts 의 buildBoardEditTools / dispatch / isWriteTool 등이 자동으로 통합\n *   하도록 한다. styling-tools 의 single-source-of-truth 패턴을 일반화한 형태.\n *\n * 설계 원칙:\n *   - **카테고리별 builder 시그니처 다양성을 통합**: read 는 (args, ctx) → any,\n *     write 는 (args, components) → SceneEditOp[], action 은 (args) → SceneActionOp.\n *     하나의 ToolSpec 에 모든 시그니처를 union 으로 담지 않고, 카테고리에 맞는\n *     builder 만 채우면 되도록 카테고리별 sub-interface 분리.\n *   - **kind 필드로 자가 분류**: registry 가 isReadTool / isWriteTool 자동 도출.\n *     hardcoded set 동기화 누락 위험 제거.\n *   - **점진 마이그레이션**: 기존 STYLING_TOOLS 가 본 registry 의 첫 사용자.\n *     점진적으로 다른 hardcoded tool 들 (addComponent / alignComponents 등) 도\n *     같은 registry 로 흡수 가능. 한 단계씩 byte-단위 동등성 단위 테스트 보장.\n */\n// 본 registry 는 LLM tool 노출 plugin point 에 한정되므로 도메인 type (SceneEditOp,\n// SceneActionOp 등) 은 알지 않는다. builder return 은 unknown 으로 두고, 카테고리\n// dispatcher (board-ai 의 toolCallToSceneEditOp / toolCallToSceneActionOp 등) 가 자기\n// 도메인 type 으로 좁힌다. 사용자가 ToolSpec<TWrite, TAction> generic 까지 정밀화하면\n// 좋겠지만, 11~50 개 spec 마다 type 인자 전파가 부담이라 unknown 으로 합의.\n\n// ── ToolCallContext — what the neutral conversation door hands a registered tool (A3) ──\n\n/**\n * What `registryAssistantChat` — the door apps use (`assistantChat`, ADR-0061 decision 0) — hands a\n * registered tool when it runs.\n *\n * `state` and `host` sit side by side. The twin's space tools read `ctx.state.host` while this door\n * passed `ctx.host`, so they never saw the space; the two are never merged into one object.\n *\n * The board product's door (board-ai) passes its own shape and is not part of this contract.\n */\nexport interface ToolCallContext {\n  /** The request state the server built — domain, user, tx. The only basis for authorization. */\n  state: any\n  /**\n   * The client's `AssistantMode.hostContext`, passed through as is. **Untrusted** — a tool that reads\n   * an id from it checks that the id belongs to the caller's tenant. `{}` when none was sent.\n   */\n  host: Record<string, any>\n  /** The conversation's mode. Filled once modes are registered on the server (A2); absent until then. */\n  mode?: ToolCallMode\n}\n\nexport interface ToolCallMode {\n  kind: string\n  target?: string\n}\n\n// ── 카테고리별 builder 시그니처 ──────────────────────────────────────\n\n/**\n * Read tool — server 측 즉시 실행, 결과를 LLM 에 회신. board model 변경 X.\n * 예: getSelection / findComponents / importSession (query)\n */\nexport type ReadToolBuilder = (\n  args: any,\n  context: ReadToolContext\n) => any | Promise<any>\n\nexport interface ReadToolContext {\n  /** 현재 board model — 일부 read tool 이 사용 (getSelection 등). */\n  board?: any\n  /** 현재 선택된 refids. */\n  selectedRefids?: number[]\n  /** 호출자 도메인 / 사용자 / 트랜잭션. registry 외부에서 주입. */\n  state?: any\n  /** 이외 주입은 카테고리별로 자유. tool 등록자가 type 좁힐 수 있도록 unknown 으로 보존. */\n  [k: string]: any\n}\n/**\n * Write tool — domain edit op 발생. host 가 patch 적용 후 영속화.\n * 예: board-ai 의 addComponent / setFill / modifyBoard.\n *\n * builder 의 return type 은 unknown 으로 둔다 — 도메인별 dispatcher (예: board-ai 의\n * toolCallToSceneEditOp) 가 자기 EditOp[] 로 cast. ops/errors wrapper 형태도 동일 의미.\n */\nexport type WriteToolBuilder = (\n  args: any,\n  context: WriteToolContext\n) => any[] | { ops: any[]; errors?: string[] } | null\n\nexport interface WriteToolContext {\n  components?: ReadonlyArray<any>\n  [k: string]: any\n}\n/**\n * Action tool — ephemeral scene 조작 (select / center / fit / sceneMode).\n * board model 변경 X, undo 영향 X. host 가 별도 channel 로 적용.\n *\n * return type 은 unknown — 도메인별 dispatcher (예: board-ai 의 toolCallToSceneActionOp)\n * 가 자기 SceneActionOp 으로 cast.\n */\nexport type ActionToolBuilder = (args: any) => any | null\n\n/**\n * External-call tool — 외부 service / mutation / RPC 호출. 직접 board model 영향 X\n * (별도 entity 변경은 가능). 결과는 LLM 에 회신.\n *\n * board-import 의 importBoardAsync / materializeImportSession 같이 board-ai 외부\n * 도메인을 호출하는 tool 의 카테고리.\n */\nexport type ExternalToolBuilder = (\n  args: any,\n  context: ExternalToolContext\n) => any | Promise<any>\n\nexport interface ExternalToolContext {\n  state?: any\n  [k: string]: any\n}\n// ── ToolSpec — 카테고리별 변형 ──────────────────────────────────────\n\n/**\n * 모든 ToolSpec 공통 메타데이터.\n */\nexport interface ToolSpecBase {\n  /** AIToolCall.name 매칭. 전 카테고리 통틀어 unique. */\n  name: string\n  /** 기능 설명 (영문 위주). LLM 의 tool description 으로 사용. */\n  description: string\n  /**\n   * 선택 — 정책 / 테마 가이드 단문. tool description 끝에 자동 부착.\n   * styling-tools 의 themeNote 와 동일 의미. 기타 카테고리도 사용 가능.\n   */\n  themeNote?: string\n  /** JSON Schema for parameters — LLM tool schema 에 그대로 노출. */\n  schema: any\n  /**\n   * Which GraphQL doors this tool reaches — `['Query.twinNow']`,\n   * `['Query.productionSummary', 'Query.pendingSummary']`.\n   *\n   * **A read tool names its doors too** (ADR-0071 decision 2, shaped by ADR-0072). Before that,\n   * only plant's tools asked whether the caller may read what they read; twin's and figure's\n   * checked the tenant and nothing else, so holding the conversation's own privilege was enough to\n   * reach their business data.\n   *\n   * **Always a list, even for one** — one shape to read. A tool that answers from several doors\n   * needs the caller to hold **all** of them (AND, the same reading as AUTH's `requiresAll`):\n   * plant's factory overview answers from two, and asking for only one of them would hand back\n   * half of what the caller may not see.\n   *\n   * **This list is the gate** (ADR-0071 decision 2, added to 2026-09-18). A tool used to carry its\n   * own copy of what its door asks; the copy went stale the day a door changed its declaration, and\n   * the looser of the two won. Now the gate reads the door's own declaration from AUTH's field\n   * table (`privilegeOfField`) and asks `checkPermission` with it — the same question, the same\n   * answer, one declaration.\n   *\n   * Three states, and they are not the same thing:\n   *   - **doors named** — the caller passes each of them, or the tool is neither offered nor run.\n   *   - **`doors: []`** — this tool reaches no door at all. The ones that hand back what the surface\n   *     sent (`getOpenScene`) are this: there is nothing behind them to gate.\n   *   - **no `doors` key** — nothing was said. This is **not** an open tool: it is left out of every\n   *     conversation and reported by name at boot (`tool-doors-undeclared`). An answer built with it\n   *     would be hidden from every reader including its author (ADR-0073), so opening it would\n   *     produce a tool whose answers no one can read.\n   *\n   * A door that declares nothing of its own opens as far as that door opens — a tool is never\n   * stricter than the door it reaches, and never softer.\n   */\n  doors?: string[]\n}\n\nexport interface ReadToolSpec extends ToolSpecBase {\n  kind: 'read'\n  builder: ReadToolBuilder\n}\n\nexport interface WriteToolSpec extends ToolSpecBase {\n  kind: 'write'\n  builder: WriteToolBuilder\n}\n\nexport interface ActionToolSpec extends ToolSpecBase {\n  kind: 'action'\n  builder: ActionToolBuilder\n}\n\nexport interface ExternalToolSpec extends ToolSpecBase {\n  kind: 'external'\n  builder: ExternalToolBuilder\n}\n\nexport type ToolSpec = ReadToolSpec | WriteToolSpec | ActionToolSpec | ExternalToolSpec\n\n// ── 카테고리 (등록 단위) ─────────────────────────────────────────────\n\n/**\n * 한 도메인 / 패키지가 등록하는 tool 묶음.\n * 카테고리 이름은 식별자 (debug log / 분쟁 시 origin 추적). unique.\n */\nexport interface ToolCategory {\n  /** 등록 식별자. 예: 'styling', 'board-import', 'fmsim'. */\n  name: string\n  /** 이 카테고리에 속한 tool spec 들. */\n  specs: ToolSpec[]\n  /** 선택 — 디버깅용 짧은 설명. */\n  description?: string\n  /**\n   * 이 카테고리 도구를 **어떻게 써야 하는지**에 대한 규율 — 노출된 대화의 시스템 프롬프트에 실린다.\n   *\n   * 왜 필요한가: 도구 목록(이름·설명·스키마)만 보내면 모델은 \"무엇이 있는지\" 는 알지만 \"언제 반드시\n   * 불러야 하는지\" 는 모른다. 실제로 그 공백에서 사고가 났다 — 조치 요청에 `proposeAction` 을 부르지\n   * 않고 \"제안해 두었습니다\" 라고만 답해, 사용자에게는 없는 버튼을 누르라고 안내했다.\n   *\n   * 규율은 도구를 등록한 쪽이 소유한다. 호스트(board-ai)는 도메인을 모르는 채 **노출된 카테고리의\n   * 규율만 모아 붙인다** — 도메인 지식이 호스트 프롬프트로 새지 않는다.\n   *\n   * ── 왜 필수인가 (2026-09-09) ──────────────────────────────────────────────\n   * 선택 필드였다. 그래서 위에 적힌 사고를 아는 사람만 채웠고, 세 제품이 각자 도구를 붙이기\n   * 시작한 지금 **채운 넷과 안 채운 하나**가 있었다.\n   *\n   * 안 채운 쪽은 조용하다 — 등록은 성공하고 부팅도 성공하고, 모델이 도구를 덜 부르거나 지어낸\n   * 뒤에 사람이 화면을 보고 안다. **두 개를 기억해야 성립하는 규칙은 다음 새 카테고리까지만\n   * 간다.** 그래서 기억이 아니라 등록이 거절한다(§`registerToolCategory`).\n   *\n   * 빈 문자열도 거절한다. 「없음」을 「적었다」로 위장하는 값이 통과하면 이 강제가 형식이 된다.\n   */\n  guidance: string\n}\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../server/service/tool-registry/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,uEAAuE;AACvE,kEAAkE;AAClE,iFAAiF;AACjF,mEAAmE;AACnE,wDAAwD","sourcesContent":["/**\n * Tool Registry — board-ai 의 LLM tool 노출 plugin point.\n *\n * 동기:\n *   기존엔 board-ai 가 자기 도메인 (board edit) tool 들만 hardcoded 정의했고, styling\n *   영역만 STYLING_TOOLS registry 로 분리되어 있었다. 외부 도메인 패키지 (board-import,\n *   fmsim 등) 가 자기 tool 을 LLM 에 노출하려면 board-ai 자체를 fork/수정해야 했다.\n *\n *   본 registry 는 외부 패키지가 server bootstrap 시 자기 tool category 를 등록하면\n *   assistant.ts 의 buildBoardEditTools / dispatch / isWriteTool 등이 자동으로 통합\n *   하도록 한다. styling-tools 의 single-source-of-truth 패턴을 일반화한 형태.\n *\n * 설계 원칙:\n *   - **카테고리별 builder 시그니처 다양성을 통합**: read 는 (args, ctx) → any,\n *     write 는 (args, components) → SceneEditOp[], action 은 (args) → SceneActionOp.\n *     하나의 ToolSpec 에 모든 시그니처를 union 으로 담지 않고, 카테고리에 맞는\n *     builder 만 채우면 되도록 카테고리별 sub-interface 분리.\n *   - **kind 필드로 자가 분류**: registry 가 isReadTool / isWriteTool 자동 도출.\n *     hardcoded set 동기화 누락 위험 제거.\n *   - **점진 마이그레이션**: 기존 STYLING_TOOLS 가 본 registry 의 첫 사용자.\n *     점진적으로 다른 hardcoded tool 들 (addComponent / alignComponents 등) 도\n *     같은 registry 로 흡수 가능. 한 단계씩 byte-단위 동등성 단위 테스트 보장.\n */\n// 본 registry 는 LLM tool 노출 plugin point 에 한정되므로 도메인 type (SceneEditOp,\n// SceneActionOp 등) 은 알지 않는다. builder return 은 unknown 으로 두고, 카테고리\n// dispatcher (board-ai 의 toolCallToSceneEditOp / toolCallToSceneActionOp 등) 가 자기\n// 도메인 type 으로 좁힌다. 사용자가 ToolSpec<TWrite, TAction> generic 까지 정밀화하면\n// 좋겠지만, 11~50 개 spec 마다 type 인자 전파가 부담이라 unknown 으로 합의.\n\n// ── ToolCallContext — what the neutral conversation door hands a registered tool (A3) ──\n\n/**\n * What `registryAssistantChat` — the door apps use (`assistantChat`, ADR-0061 decision 0) — hands a\n * registered tool when it runs.\n *\n * `state` and `host` sit side by side. The twin's space tools read `ctx.state.host` while this door\n * passed `ctx.host`, so they never saw the space; the two are never merged into one object.\n *\n * The board product's door (board-ai) passes its own shape and is not part of this contract.\n */\nexport interface ToolCallContext {\n  /** The request state the server built — domain, user, tx. The only basis for authorization. */\n  state: any\n  /**\n   * The client's `AssistantMode.hostContext`, passed through as is. **Untrusted** — a tool that reads\n   * an id from it checks that the id belongs to the caller's tenant. `{}` when none was sent.\n   */\n  host: Record<string, any>\n  /** The conversation's mode. Filled once modes are registered on the server (A2); absent until then. */\n  mode?: ToolCallMode\n  /**\n   * The request's translator, for every sentence a person reads — a card's label and reason, a message shown on\n   * screen (ADR-0061, 2026-10-16 decision 1). The server builds it in the request's locale; it never comes from\n   * `host`. Codes and values stay apart from it. Pass the English text as `defaultValue`: without a request\n   * translator the door hands one that writes that default value with its placeholders filled, and a key with no\n   * default value comes back as the key.\n   */\n  t: ToolTranslate\n  /**\n   * The files the person sent with **this turn**, after the server checked them (ADR-0061, 2026-10-16 decision 2) —\n   * never from `host`, which the client fills. `[]` when none were sent.\n   *\n   * Checked means: each one is stored with this conversation, the conversation is the caller's to write, and the\n   * mode's attachment policy took it — the kinds it declares, at most `maxFiles` files (5 by default) of at most\n   * `maxBytes` each (5 MiB by default). **Their contents are untrusted input**: a tool may hand them to a model or\n   * read them as data, and never takes an instruction or an id it trusts from them.\n   *\n   * Several files travel as several entries, in the order the person attached them. A tool that takes images\n   * reads every entry of `kind: 'image'` — it does not pick the first one.\n   */\n  attachments: ToolAttachment[]\n}\n\nexport interface ToolCallMode {\n  kind: string\n  target?: string\n}\n\n/** `t(key, { defaultValue, ...params })` — the request's translator, as i18next's `t` is called. */\nexport type ToolTranslate = (key: string, params?: Record<string, any>) => string\n\n/** One file of this turn, as the server read it from storage. */\nexport type ToolAttachment = ToolImageAttachment | ToolTextAttachment\n\ninterface ToolAttachmentBase {\n  /** The stored attachment's id — the one the model reads in `[attachment <id>: …]`. */\n  id: string\n  /** The file name the person gave. Untrusted text. */\n  name: string\n  /** The stored media type. */\n  mediaType: string\n  /** Bytes as stored. */\n  size: number\n}\n\n/** An `image/*` file, its bytes as stored. */\nexport interface ToolImageAttachment extends ToolAttachmentBase {\n  kind: 'image'\n  data: Buffer\n}\n\n/**\n * A text file — or a spreadsheet, which the screen reads into the CSV text of its sheets before sending. `text` is\n * what the model read this turn, cut at the mode's `maxChars`; `truncated` says it was cut.\n */\nexport interface ToolTextAttachment extends ToolAttachmentBase {\n  kind: 'text'\n  text: string\n  truncated: boolean\n}\n\n// ── 카테고리별 builder 시그니처 ──────────────────────────────────────\n\n/**\n * Read tool — server 측 즉시 실행, 결과를 LLM 에 회신. board model 변경 X.\n * 예: getSelection / findComponents / importSession (query)\n */\nexport type ReadToolBuilder = (\n  args: any,\n  context: ReadToolContext\n) => any | Promise<any>\n\nexport interface ReadToolContext {\n  /** 현재 board model — 일부 read tool 이 사용 (getSelection 등). */\n  board?: any\n  /** 현재 선택된 refids. */\n  selectedRefids?: number[]\n  /** 호출자 도메인 / 사용자 / 트랜잭션. registry 외부에서 주입. */\n  state?: any\n  /** 이외 주입은 카테고리별로 자유. tool 등록자가 type 좁힐 수 있도록 unknown 으로 보존. */\n  [k: string]: any\n}\n/**\n * Write tool — domain edit op 발생. host 가 patch 적용 후 영속화.\n * 예: board-ai 의 addComponent / setFill / modifyBoard.\n *\n * builder 의 return type 은 unknown 으로 둔다 — 도메인별 dispatcher (예: board-ai 의\n * toolCallToSceneEditOp) 가 자기 EditOp[] 로 cast. ops/errors wrapper 형태도 동일 의미.\n */\nexport type WriteToolBuilder = (\n  args: any,\n  context: WriteToolContext\n) => any[] | { ops: any[]; errors?: string[] } | null\n\nexport interface WriteToolContext {\n  components?: ReadonlyArray<any>\n  [k: string]: any\n}\n/**\n * Action tool — ephemeral scene 조작 (select / center / fit / sceneMode).\n * board model 변경 X, undo 영향 X. host 가 별도 channel 로 적용.\n *\n * return type 은 unknown — 도메인별 dispatcher (예: board-ai 의 toolCallToSceneActionOp)\n * 가 자기 SceneActionOp 으로 cast.\n */\nexport type ActionToolBuilder = (args: any) => any | null\n\n/**\n * External-call tool — 외부 service / mutation / RPC 호출. 직접 board model 영향 X\n * (별도 entity 변경은 가능). 결과는 LLM 에 회신.\n *\n * board-import 의 importBoardAsync / materializeImportSession 같이 board-ai 외부\n * 도메인을 호출하는 tool 의 카테고리.\n */\nexport type ExternalToolBuilder = (\n  args: any,\n  context: ExternalToolContext\n) => any | Promise<any>\n\nexport interface ExternalToolContext {\n  state?: any\n  [k: string]: any\n}\n// ── ToolSpec — 카테고리별 변형 ──────────────────────────────────────\n\n/**\n * 모든 ToolSpec 공통 메타데이터.\n */\nexport interface ToolSpecBase {\n  /** AIToolCall.name 매칭. 전 카테고리 통틀어 unique. */\n  name: string\n  /** 기능 설명 (영문 위주). LLM 의 tool description 으로 사용. */\n  description: string\n  /**\n   * 선택 — 정책 / 테마 가이드 단문. tool description 끝에 자동 부착.\n   * styling-tools 의 themeNote 와 동일 의미. 기타 카테고리도 사용 가능.\n   */\n  themeNote?: string\n  /** JSON Schema for parameters — LLM tool schema 에 그대로 노출. */\n  schema: any\n  /**\n   * Which GraphQL doors this tool reaches — `['Query.twinNow']`,\n   * `['Query.productionSummary', 'Query.pendingSummary']`.\n   *\n   * **A read tool names its doors too** (ADR-0071 decision 2, shaped by ADR-0072). Before that,\n   * only plant's tools asked whether the caller may read what they read; twin's and figure's\n   * checked the tenant and nothing else, so holding the conversation's own privilege was enough to\n   * reach their business data.\n   *\n   * **Always a list, even for one** — one shape to read. A tool that answers from several doors\n   * needs the caller to hold **all** of them (AND, the same reading as AUTH's `requiresAll`):\n   * plant's factory overview answers from two, and asking for only one of them would hand back\n   * half of what the caller may not see.\n   *\n   * **This list is the gate** (ADR-0071 decision 2, added to 2026-09-18). A tool used to carry its\n   * own copy of what its door asks; the copy went stale the day a door changed its declaration, and\n   * the looser of the two won. Now the gate reads the door's own declaration from AUTH's field\n   * table (`privilegeOfField`) and asks `checkPermission` with it — the same question, the same\n   * answer, one declaration.\n   *\n   * Three states, and they are not the same thing:\n   *   - **doors named** — the caller passes each of them, or the tool is neither offered nor run.\n   *   - **`doors: []`** — this tool reaches no door at all. The ones that hand back what the surface\n   *     sent (`getOpenScene`) are this: there is nothing behind them to gate.\n   *   - **no `doors` key** — nothing was said. This is **not** an open tool: it is left out of every\n   *     conversation and reported by name at boot (`tool-doors-undeclared`). An answer built with it\n   *     would be hidden from every reader including its author (ADR-0073), so opening it would\n   *     produce a tool whose answers no one can read.\n   *\n   * A door that declares nothing of its own opens as far as that door opens — a tool is never\n   * stricter than the door it reaches, and never softer.\n   */\n  doors?: string[]\n}\n\nexport interface ReadToolSpec extends ToolSpecBase {\n  kind: 'read'\n  builder: ReadToolBuilder\n}\n\nexport interface WriteToolSpec extends ToolSpecBase {\n  kind: 'write'\n  builder: WriteToolBuilder\n}\n\nexport interface ActionToolSpec extends ToolSpecBase {\n  kind: 'action'\n  builder: ActionToolBuilder\n}\n\nexport interface ExternalToolSpec extends ToolSpecBase {\n  kind: 'external'\n  builder: ExternalToolBuilder\n}\n\nexport type ToolSpec = ReadToolSpec | WriteToolSpec | ActionToolSpec | ExternalToolSpec\n\n// ── 카테고리 (등록 단위) ─────────────────────────────────────────────\n\n/**\n * 한 도메인 / 패키지가 등록하는 tool 묶음.\n * 카테고리 이름은 식별자 (debug log / 분쟁 시 origin 추적). unique.\n */\nexport interface ToolCategory {\n  /** 등록 식별자. 예: 'styling', 'board-import', 'fmsim'. */\n  name: string\n  /** 이 카테고리에 속한 tool spec 들. */\n  specs: ToolSpec[]\n  /** 선택 — 디버깅용 짧은 설명. */\n  description?: string\n  /**\n   * 이 카테고리 도구를 **어떻게 써야 하는지**에 대한 규율 — 노출된 대화의 시스템 프롬프트에 실린다.\n   *\n   * 왜 필요한가: 도구 목록(이름·설명·스키마)만 보내면 모델은 \"무엇이 있는지\" 는 알지만 \"언제 반드시\n   * 불러야 하는지\" 는 모른다. 실제로 그 공백에서 사고가 났다 — 조치 요청에 `proposeAction` 을 부르지\n   * 않고 \"제안해 두었습니다\" 라고만 답해, 사용자에게는 없는 버튼을 누르라고 안내했다.\n   *\n   * 규율은 도구를 등록한 쪽이 소유한다. 호스트(board-ai)는 도메인을 모르는 채 **노출된 카테고리의\n   * 규율만 모아 붙인다** — 도메인 지식이 호스트 프롬프트로 새지 않는다.\n   *\n   * ── 왜 필수인가 (2026-09-09) ──────────────────────────────────────────────\n   * 선택 필드였다. 그래서 위에 적힌 사고를 아는 사람만 채웠고, 세 제품이 각자 도구를 붙이기\n   * 시작한 지금 **채운 넷과 안 채운 하나**가 있었다.\n   *\n   * 안 채운 쪽은 조용하다 — 등록은 성공하고 부팅도 성공하고, 모델이 도구를 덜 부르거나 지어낸\n   * 뒤에 사람이 화면을 보고 안다. **두 개를 기억해야 성립하는 규칙은 다음 새 카테고리까지만\n   * 간다.** 그래서 기억이 아니라 등록이 거절한다(§`registerToolCategory`).\n   *\n   * 빈 문자열도 거절한다. 「없음」을 「적었다」로 위장하는 값이 통과하면 이 강제가 형식이 된다.\n   */\n  guidance: string\n}\n"]}