@things-factory/ai-client-base 10.1.20 → 10.1.26

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

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

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

@@ -8,6 +8,7 @@ const tslib_1 = require("tslib");
  */
 tslib_1.__exportStar(require("./abort-notice.js"), exports);
 tslib_1.__exportStar(require("./summarize.js"), exports);
+tslib_1.__exportStar(require("./tool-scope.js"), exports);
 tslib_1.__exportStar(require("./registry-gate.js"), exports);
 tslib_1.__exportStar(require("./assistant-chat.js"), exports);
 tslib_1.__exportStar(require("./registry-assistant.js"), exports);

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../server/service/assistant/index.ts"],"names":[],"mappings":";;;AAAA;;;;GAIG;AACH,4DAAiC;AACjC,yDAA8B;AAC9B,6DAAkC;AAClC,8DAAmC;AACnC,kEAAuC","sourcesContent":["/*\n * The neutral assistant layer — the agentic loop plus the guards that must not be optional.\n *\n * See `assistant-chat.ts` for why this is not in a product package.\n */\nexport * from './abort-notice.js'\nexport * from './summarize.js'\nexport * from './registry-gate.js'\nexport * from './assistant-chat.js'\nexport * from './registry-assistant.js'\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../server/service/assistant/index.ts"],"names":[],"mappings":";;;AAAA;;;;GAIG;AACH,4DAAiC;AACjC,yDAA8B;AAC9B,0DAA+B;AAC/B,6DAAkC;AAClC,8DAAmC;AACnC,kEAAuC","sourcesContent":["/*\n * The neutral assistant layer — the agentic loop plus the guards that must not be optional.\n *\n * See `assistant-chat.ts` for why this is not in a product package.\n */\nexport * from './abort-notice.js'\nexport * from './summarize.js'\nexport * from './tool-scope.js'\nexport * from './registry-gate.js'\nexport * from './assistant-chat.js'\nexport * from './registry-assistant.js'\n"]}

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

@@ -1,12 +1,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';
-/** What a registry tool is handed when it runs. `state` is the caller's koa state. */
-export interface RegistryToolCallContext {
-    state: any;
-    /** What this surface is looking at — the host passes it through; tools read it as `host`. */
-    host?: any;
-}
 export interface RegistryAssistantInput {
     /** Provider client. Must implement `chatWithTools`. */
     client: AIClient;
@@ -15,12 +10,17 @@ export interface RegistryAssistantInput {
     /** Who the assistant is and what this surface is. The host owns this prose. */
     systemPrompt: string;
     /**
-     * Categories this conversation may use. Omit to allow every registered category.
-     *
-     * An empty array is not the same as omitting: it allows nothing, and the conversation runs with
-     * no tools at all. That is a legitimate surface (plain chat), so it is not corrected here.
+     * Categories this conversation may use. **Omitting it allows nothing** — the same as an empty
+     * list, a plain conversation with no tools (A1, 2026-09-17). It used to mean every registered
+     * category, which is how a Board-creating tool reached any conversation.
      */
     toolCategories?: string[];
+    /**
+     * 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
+     * not know auth.
+     */
+    toolAccess?: ToolAccessCheck;
     /** Passed to tools as `context.host`. Client-supplied — never used for authorization. */
     hostContext?: any;
     /** Caller's koa state (domain, user, tx). Tools that read the database need it. */

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

@@ -1,13 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registryAssistantChat = registryAssistantChat;
-const index_js_1 = require("../tool-registry/index.js");
+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");
-/** `read` and `external` are the two kinds that answer a question without changing a document. */
-function answeringSpecs(filter) {
-    return (0, index_js_1.getToolSpecsFor)(filter).filter(spec => spec.kind === 'read' || spec.kind === 'external');
-}
 /**
  * Run one turn of a conversation whose only tools come from the registry.
  *
@@ -19,8 +15,14 @@ async function registryAssistantChat(input) {
     if (!client.chatWithTools) {
         throw new Error('[registry-assistant] the configured AI client cannot call tools, so this conversation cannot run');
     }
-    const filter = toolCategories;
-    const specs = answeringSpecs(filter);
+    /*
+     * Only `read` is offered here. `external` means the tool changes something outside the
+     * conversation (board-import's `materializeImportSession` creates a Board); this door answers
+     * questions and has no confirm-and-apply step, so a tool with an effect does not go through it
+     * even when the caller holds the privilege.
+     */
+    const scope = (0, tool_scope_js_1.narrowToolScope)(await (0, tool_scope_js_1.resolveToolScope)(toolCategories, input.toolAccess), spec => spec.kind === 'read');
+    const specs = scope.specs;
     const byName = new Map(specs.map(spec => [spec.name, spec]));
     const tools = specs.map(spec => ({
         name: spec.name,
@@ -31,9 +33,9 @@ async function registryAssistantChat(input) {
      * 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.
      */
-    const guidance = (0, index_js_1.getCategoryGuidance)(filter);
+    const guidance = (0, tool_scope_js_1.toolScopeGuidance)(scope);
     const prompt = guidance.length > 0 ? `${systemPrompt}\n\n${guidance.join('\n\n')}` : systemPrompt;
-    const toolContext = { state, host: hostContext };
+    const toolContext = { state, host: hostContext ?? {} };
     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 and external 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 * So this runner offers, and dispatches, `read` and `external` only. A host that owns a document\n * keeps assembling its own conversation, as board-ai does.\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 { getCategoryGuidance, getToolSpecsFor, type ToolCategoryFilter, type ToolSpec } from '../tool-registry/index.js'\nimport { assistantChat, type AssistantChatResult } from './assistant-chat.js'\nimport { summarizeToolResult } from './summarize.js'\nimport type { GroundingSources } from '../utils/index.js'\n\n/** What a registry tool is handed when it runs. `state` is the caller's koa state. */\nexport interface RegistryToolCallContext {\n  state: any\n  /** What this surface is looking at — the host passes it through; tools read it as `host`. */\n  host?: any\n}\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. Omit to allow every registered category.\n   *\n   * An empty array is not the same as omitting: it allows nothing, and the conversation runs with\n   * no tools at all. That is a legitimate surface (plain chat), so it is not corrected here.\n   */\n  toolCategories?: string[]\n  /** Passed to tools as `context.host`. Client-supplied — never used for authorization. */\n  hostContext?: any\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  /** 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/** `read` and `external` are the two kinds that answer a question without changing a document. */\nfunction answeringSpecs(filter: ToolCategoryFilter): ToolSpec[] {\n  return getToolSpecsFor(filter).filter(spec => spec.kind === 'read' || spec.kind === 'external')\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  const filter: ToolCategoryFilter = toolCategories\n  const specs = answeringSpecs(filter)\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 = getCategoryGuidance(filter)\n  const prompt = guidance.length > 0 ? `${systemPrompt}\\n\\n${guidance.join('\\n\\n')}` : systemPrompt\n\n  const toolContext: RegistryToolCallContext = { state, host: hostContext }\n\n  const result = await assistantChat<RegistryToolCallContext, 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    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  })\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 { ToolCallContext } from '../tool-registry/types.js'\n\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  /** 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  /** 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  const toolContext: ToolCallContext = { state, host: hostContext ?? {} }\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    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  })\n\n  return { ...result, offeredTools: tools.map(tool => tool.name) }\n}\n"]}

package/dist-server/service/assistant/tool-scope.d.ts

@@ -0,0 +1,25 @@
+import { type ToolCategoryFilter } from '../tool-registry/index.js';
+import type { ToolPrivilege, ToolSpec } from '../tool-registry/types.js';
+/** Answers "may this caller use a door guarded by this privilege". */
+export type ToolAccessCheck = (privilege: ToolPrivilege) => Promise<boolean>;
+export interface ScopedCategory {
+    readonly name: string;
+    readonly guidance: string;
+    /** The tools of this category this caller may use. Never empty — a category with none is left out. */
+    readonly specs: ReadonlyArray<ToolSpec>;
+}
+export interface ToolScope {
+    /** Categories with at least one usable tool, in registration order. */
+    readonly categories: ReadonlyArray<ScopedCategory>;
+    /** Every usable tool, flat. Offering and dispatch both read this. */
+    readonly specs: ReadonlyArray<ToolSpec>;
+}
+export declare const EMPTY_TOOL_SCOPE: ToolScope;
+export declare function resolveToolScope(requested: ToolCategoryFilter, access?: ToolAccessCheck): Promise<ToolScope>;
+/**
+ * Keep only the tools a surface can run — e.g. a surface with no document keeps `read`. A category
+ * left with nothing drops out, so its guidance is not read to a model that cannot call it.
+ */
+export declare function narrowToolScope(scope: ToolScope, keep: (spec: ToolSpec) => boolean): ToolScope;
+/** The rules of the categories in scope, for the system prompt. */
+export declare function toolScopeGuidance(scope: ToolScope): string[];

package/dist-server/service/assistant/tool-scope.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EMPTY_TOOL_SCOPE = void 0;
+exports.resolveToolScope = resolveToolScope;
+exports.narrowToolScope = narrowToolScope;
+exports.toolScopeGuidance = toolScopeGuidance;
+/*
+ * Which registered tools one conversation may use — decided once per request, before anything is
+ * offered, so offering and dispatch read the same list.
+ *
+ * ── Two questions, one list ───────────────────────────────────────────────────────
+ *   Which categories did this surface ask for?     `toolCategories`
+ *   Which of their tools may this caller use?      each spec's `privilege`, asked of `access`
+ *
+ * **Nothing asked means nothing offered.** Omitting the category list used to mean "every
+ * registered category"; that default is the one that opened board-import's Board-creating tool to
+ * any conversation. An absent answer leans to the closed side (ADR-0047 ② · ADR-0053).
+ *
+ * **No access check means privileged tools stay closed.** A caller that cannot say who is asking
+ * gets only the tools that need no privilege.
+ *
+ * The permission check itself belongs to auth, which this package does not depend on, so the host
+ * hands it in (`ai-assistant` builds it from the request state).
+ */
+const index_js_1 = require("../tool-registry/index.js");
+exports.EMPTY_TOOL_SCOPE = Object.freeze({ categories: [], specs: [] });
+const privilegeKey = (p) => [p.category, p.privilege, !!p.owner, !!p.super].join('|');
+async function resolveToolScope(requested, access) {
+    if (!requested || requested.length === 0)
+        return exports.EMPTY_TOOL_SCOPE;
+    /* One check per distinct privilege — a category of ten read tools asks once. */
+    const answers = new Map();
+    const mayUse = (spec) => {
+        const privilege = spec.privilege;
+        if (!privilege)
+            return Promise.resolve(true);
+        if (!access)
+            return Promise.resolve(false);
+        const key = privilegeKey(privilege);
+        if (!answers.has(key))
+            answers.set(key, access(privilege).catch(() => false));
+        return answers.get(key);
+    };
+    const categories = [];
+    for (const category of (0, index_js_1.getToolCategories)()) {
+        if (!requested.includes(category.name))
+            continue;
+        const allowed = await Promise.all(category.specs.map(mayUse));
+        const specs = category.specs.filter((_, i) => allowed[i]);
+        if (specs.length > 0)
+            categories.push({ name: category.name, guidance: String(category.guidance ?? '').trim(), specs });
+    }
+    return fromCategories(categories);
+}
+/**
+ * Keep only the tools a surface can run — e.g. a surface with no document keeps `read`. A category
+ * left with nothing drops out, so its guidance is not read to a model that cannot call it.
+ */
+function narrowToolScope(scope, keep) {
+    return fromCategories(scope.categories
+        .map(category => ({ ...category, specs: category.specs.filter(keep) }))
+        .filter(category => category.specs.length > 0));
+}
+/** The rules of the categories in scope, for the system prompt. */
+function toolScopeGuidance(scope) {
+    return scope.categories.map(category => category.guidance).filter(Boolean);
+}
+function fromCategories(categories) {
+    return { categories, specs: categories.flatMap(category => category.specs) };
+}
+//# sourceMappingURL=tool-scope.js.map

package/dist-server/service/assistant/tool-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-scope.js","sourceRoot":"","sources":["../../../server/service/assistant/tool-scope.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Which registered tools one conversation may use — decided once per request, before anything is\n * offered, so offering and dispatch read the same list.\n *\n * ── Two questions, one list ───────────────────────────────────────────────────────\n *   Which categories did this surface ask for?     `toolCategories`\n *   Which of their tools may this caller use?      each spec's `privilege`, asked of `access`\n *\n * **Nothing asked means nothing offered.** Omitting the category list used to mean \"every\n * registered category\"; that default is the one that opened board-import's Board-creating tool to\n * any conversation. An absent answer leans to the closed side (ADR-0047 ② · ADR-0053).\n *\n * **No access check means privileged tools stay closed.** A caller that cannot say who is asking\n * gets only the tools that need no privilege.\n *\n * The permission check itself belongs to auth, which this package does not depend on, so the host\n * hands it in (`ai-assistant` builds it from the request state).\n */\nimport { getToolCategories, type ToolCategoryFilter } from '../tool-registry/index.js'\nimport type { ToolPrivilege, ToolSpec } from '../tool-registry/types.js'\n\n/** Answers \"may this caller use a door guarded by this privilege\". */\nexport type ToolAccessCheck = (privilege: ToolPrivilege) => Promise<boolean>\n\nexport interface ScopedCategory {\n  readonly name: string\n  readonly guidance: string\n  /** The tools of this category this caller may use. Never empty — a category with none is left out. */\n  readonly specs: ReadonlyArray<ToolSpec>\n}\n\nexport interface ToolScope {\n  /** Categories with at least one usable tool, in registration order. */\n  readonly categories: ReadonlyArray<ScopedCategory>\n  /** Every usable tool, flat. Offering and dispatch both read this. */\n  readonly specs: ReadonlyArray<ToolSpec>\n}\n\nexport const EMPTY_TOOL_SCOPE: ToolScope = Object.freeze({ categories: [], specs: [] })\n\nconst privilegeKey = (p: ToolPrivilege) => [p.category, p.privilege, !!p.owner, !!p.super].join('|')\n\nexport async function resolveToolScope(requested: ToolCategoryFilter, access?: ToolAccessCheck): Promise<ToolScope> {\n  if (!requested || requested.length === 0) return EMPTY_TOOL_SCOPE\n\n  /* One check per distinct privilege — a category of ten read tools asks once. */\n  const answers = new Map<string, Promise<boolean>>()\n  const mayUse = (spec: ToolSpec): Promise<boolean> => {\n    const privilege = spec.privilege\n    if (!privilege) return Promise.resolve(true)\n    if (!access) return Promise.resolve(false)\n    const key = privilegeKey(privilege)\n    if (!answers.has(key)) answers.set(key, access(privilege).catch(() => false))\n    return answers.get(key)!\n  }\n\n  const categories: ScopedCategory[] = []\n  for (const category of getToolCategories()) {\n    if (!requested.includes(category.name)) continue\n    const allowed = await Promise.all(category.specs.map(mayUse))\n    const specs = category.specs.filter((_, i) => allowed[i])\n    if (specs.length > 0) categories.push({ name: category.name, guidance: String(category.guidance ?? '').trim(), specs })\n  }\n  return fromCategories(categories)\n}\n\n/**\n * Keep only the tools a surface can run — e.g. a surface with no document keeps `read`. A category\n * left with nothing drops out, so its guidance is not read to a model that cannot call it.\n */\nexport function narrowToolScope(scope: ToolScope, keep: (spec: ToolSpec) => boolean): ToolScope {\n  return fromCategories(\n    scope.categories\n      .map(category => ({ ...category, specs: category.specs.filter(keep) }))\n      .filter(category => category.specs.length > 0)\n  )\n}\n\n/** The rules of the categories in scope, for the system prompt. */\nexport function toolScopeGuidance(scope: ToolScope): string[] {\n  return scope.categories.map(category => category.guidance).filter(Boolean)\n}\n\nfunction fromCategories(categories: ScopedCategory[]): ToolScope {\n  return { categories, specs: categories.flatMap(category => category.specs) }\n}\n"]}

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

@@ -6,3 +6,4 @@ export * from './tool-registry/index.js';
 export * from './agentic-loop/index.js';
 export * from './assistant/index.js';
 export * from './analysis-contract.js';
+export * from './testing/tool-call-context.js';

package/dist-server/service/index.js

@@ -9,4 +9,5 @@ tslib_1.__exportStar(require("./tool-registry/index.js"), exports);
 tslib_1.__exportStar(require("./agentic-loop/index.js"), exports);
 tslib_1.__exportStar(require("./assistant/index.js"), exports);
 tslib_1.__exportStar(require("./analysis-contract.js"), exports);
+tslib_1.__exportStar(require("./testing/tool-call-context.js"), exports);
 //# sourceMappingURL=index.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../server/service/index.ts"],"names":[],"mappings":";;;AAAA,qDAA0B;AAC1B,uDAA4B;AAC5B,+DAAoC;AACpC,2DAAgC;AAChC,mEAAwC;AACxC,kEAAuC;AACvC,+DAAoC;AACpC,iEAAsC","sourcesContent":["export * from './types.js'\nexport * from './factory.js'\nexport * from './providers/index.js'\nexport * from './utils/index.js'\nexport * from './tool-registry/index.js'\nexport * from './agentic-loop/index.js'\nexport * from './assistant/index.js'\nexport * from './analysis-contract.js'\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../server/service/index.ts"],"names":[],"mappings":";;;AAAA,qDAA0B;AAC1B,uDAA4B;AAC5B,+DAAoC;AACpC,2DAAgC;AAChC,mEAAwC;AACxC,kEAAuC;AACvC,+DAAoC;AACpC,iEAAsC;AACtC,yEAA8C","sourcesContent":["export * from './types.js'\nexport * from './factory.js'\nexport * from './providers/index.js'\nexport * from './utils/index.js'\nexport * from './tool-registry/index.js'\nexport * from './agentic-loop/index.js'\nexport * from './assistant/index.js'\nexport * from './analysis-contract.js'\nexport * from './testing/tool-call-context.js'\n"]}

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

@@ -0,0 +1,10 @@
+import type { ToolCallContext, ToolCallMode } from '../tool-registry/types.js';
+export interface ToolCallContextFixtureInput {
+    domainId?: string;
+    userId?: string;
+    /** Extra request-state fields a tool reads (e.g. `tx`). Merged after domain and user. */
+    state?: Record<string, any>;
+    host?: Record<string, any>;
+    mode?: ToolCallMode;
+}
+export declare function toolCallContextFixture(input?: ToolCallContextFixtureInput): ToolCallContext;

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

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toolCallContextFixture = toolCallContextFixture;
+function toolCallContextFixture(input = {}) {
+    const context = {
+        state: { domain: { id: input.domainId ?? 'domain-test' }, user: { id: input.userId ?? 'user-test' }, ...(input.state ?? {}) },
+        host: input.host ?? {}
+    };
+    if (input.mode)
+        context.mode = input.mode;
+    return context;
+}
+//# sourceMappingURL=tool-call-context.js.map

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

@@ -0,0 +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"]}

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

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

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.clearToolRegistry = exports.getCategorySpecs = exports.hasTool = exports.getToolKind = exports.findToolSpec = exports.getCategoryGuidance = exports.getToolSpecsFor = exports.getAllToolSpecs = exports.getToolCategories = exports.registerToolCategory = void 0;
+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.
  *
@@ -17,4 +17,5 @@ Object.defineProperty(exports, "getToolKind", { enumerable: true, get: function
 Object.defineProperty(exports, "hasTool", { enumerable: true, get: function () { return registry_1.hasTool; } });
 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; } });
 //# 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,uCAWmB;AAVjB,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","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} from './registry'\n\n/* 대화별 노출 제한 타입은 registry 소유(정의가 거기 있다). */\nexport type { ToolCategoryFilter } 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} 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","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  ToolPrivilege,\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"]}

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

@@ -26,6 +26,22 @@
  *   - clear() 는 테스트 전용. 운영 환경에서 호출 금지.
  */
 import type { ToolCategory, ToolSpec } from './types';
+/** A registration that was accepted but is not yet what the contract requires. Code + params, not prose. */
+export interface ToolRegistryWarning {
+    code: 'tool-privilege-undeclared';
+    params: {
+        category: string;
+        tool: string;
+        kind: ToolSpec['kind'];
+    };
+    /** For a person reading it; the code and params are what callers act on. */
+    message: string;
+}
+/**
+ * What registration accepted but the contract does not yet allow. Stage one of A1 records these
+ * instead of refusing; a host shows them at boot, and when the list is empty the rule becomes a refusal.
+ */
+export declare function getToolRegistryWarnings(): ReadonlyArray<ToolRegistryWarning>;
 /**
  * 카테고리 등록. tool name 충돌 시 throw, 이름 중복 등록 시 덮어쓰기 + warn.
  */

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

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getToolRegistryWarnings = getToolRegistryWarnings;
 exports.registerToolCategory = registerToolCategory;
 exports.getToolCategories = getToolCategories;
 exports.getAllToolSpecs = getAllToolSpecs;
@@ -11,6 +12,14 @@ exports.hasTool = hasTool;
 exports.getCategorySpecs = getCategorySpecs;
 exports.clearToolRegistry = clearToolRegistry;
 const categories = new Map();
+const warnings = [];
+/**
+ * What registration accepted but the contract does not yet allow. Stage one of A1 records these
+ * instead of refusing; a host shows them at boot, and when the list is empty the rule becomes a refusal.
+ */
+function getToolRegistryWarnings() {
+    return warnings.slice();
+}
 /**
  * 카테고리 등록. tool name 충돌 시 throw, 이름 중복 등록 시 덮어쓰기 + warn.
  */
@@ -34,6 +43,32 @@ function registerToolCategory(category) {
             'Without it a model answers as though it called a tool it did not, and nothing errors. ' +
             'Write the rules for these tools in `guidance` — the side that registers them owns them.');
     }
+    /*
+     * A tool that changes something must say which privilege it goes through (A1, 2026-09-17).
+     *
+     * The conversation door checks one privilege — may this person talk to the assistant. Without a
+     * privilege on the tool, that single check opened every tool behind it: a user holding only
+     * `ai-assistant:mutation` could reach board-import's `materializeImportSession` and create a
+     * Board.
+     *
+     * **This is stage one of two: surface, then refuse** (ADR-0037, "먼저 드러내고, 목록이 비면 막는다").
+     * Refusing now would stop every app whose tools predate the `privilege` field from booting, and
+     * those apps compile against an installed copy that does not have the field yet. So an undeclared
+     * tool still registers, and the omission is recorded as a code (`getToolRegistryWarnings`), not
+     * a log line — a warning only a log carries is not distinguishable from no warning. When the list
+     * is empty across the apps, this becomes a refusal.
+     */
+    warnings.splice(0, warnings.length, ...warnings.filter(w => w.params.category !== category.name));
+    for (const spec of category.specs) {
+        if (spec.kind !== 'read' && !(spec.privilege?.category && spec.privilege?.privilege)) {
+            warnings.push({
+                code: 'tool-privilege-undeclared',
+                params: { category: category.name, tool: spec.name, kind: spec.kind },
+                message: `tool '${spec.name}' in category '${category.name}' is '${spec.kind}' but declares no privilege — ` +
+                    'declare the same { category, privilege } its GraphQL door uses'
+            });
+        }
+    }
     if (categories.has(category.name)) {
         console.warn(`[board-ai/tool-registry] category '${category.name}' already registered — overwriting. ` +
             `(dev hot-reload 시 정상이지만 운영 환경에서 발생하면 buildup bug)`);
@@ -141,5 +176,6 @@ function getCategorySpecs(categoryName) {
  */
 function clearToolRegistry() {
     categories.clear();
+    warnings.length = 0;
 }
 //# sourceMappingURL=registry.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../server/service/tool-registry/registry.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * ToolCategoryRegistry — 외부 도메인 패키지가 LLM tool category 를 동적 등록하는 점.\n *\n * 사용 패턴 (외부 패키지의 server bootstrap):\n *   ```ts\n *   import { registerToolCategory } from '@things-factory/board-ai'\n *\n *   registerToolCategory({\n *     name: 'board-import',\n *     specs: [\n *       { kind: 'external', name: 'importBoardAsync', schema: {...}, builder: ... },\n *       { kind: 'read',     name: 'getImportSession', schema: {...}, builder: ... },\n *       ...\n *     ]\n *   })\n *   ```\n *\n * board-ai assistant.ts 의 buildBoardEditTools / dispatch / isWriteTool 등이\n * 본 registry 에서 자동 도출.\n *\n * 정책:\n *   - 카테고리 이름은 unique. 같은 이름으로 재등록하면 덮어쓰기 (외부 패키지의\n *     hot-reload / dev 환경 대응). console.warn 으로 알림.\n *   - tool name 은 카테고리 간 통틀어 unique. 충돌 시 등록 거부 + 명확한 에러\n *     (LLM dispatch 가 모호해지지 않도록).\n *   - clear() 는 테스트 전용. 운영 환경에서 호출 금지.\n */\nimport type { ToolCategory, ToolSpec } from './types'\n\nconst categories: Map<string, ToolCategory> = new Map()\n\n/**\n * 카테고리 등록. tool name 충돌 시 throw, 이름 중복 등록 시 덮어쓰기 + warn.\n */\nexport function registerToolCategory(category: ToolCategory): void {\n  /*\n   * 지침 없는 카테고리는 **등록하지 않는다.**\n   *\n   * 도구 목록만 보낸 모델이 「불러야 할 때 부른다」를 맞히지 못한 사고가 있었다 — 조치 요청에\n   * `proposeAction` 을 부르지 않고 「제안해 두었습니다」라고 답해, 사용자에게 없는 버튼을 누르라고\n   * 안내했다. 화면에는 아무 일도 없었고 오류도 나지 않았다(§`ToolCategory.guidance`).\n   *\n   * 그 뒤로 규율을 적는 자리를 만들었지만 **선택이었다.** 선택인 규율은 그 사고를 아는 사람만\n   * 채운다. 여기서 거절하는 이유가 그것이다 — 빠진 것을 부팅에서 만든 사람이 보고, 모델이 헛말을\n   * 한 뒤에 사용자가 보지 않는다.\n   *\n   * 빈 문자열·공백도 거절한다. 통과시키면 이 검사가 형식이 되고, 형식이 된 검사는 없는 것과 같다.\n   */\n  if (!String(category.guidance ?? '').trim()) {\n    throw new Error(\n      `[ai-client-base/tool-registry] category '${category.name}' has no guidance. ` +\n        'Tool descriptions say what a tool does; guidance says when the model must call one. ' +\n        'Without it a model answers as though it called a tool it did not, and nothing errors. ' +\n        'Write the rules for these tools in `guidance` — the side that registers them owns them.'\n    )\n  }\n\n  if (categories.has(category.name)) {\n    console.warn(\n      `[board-ai/tool-registry] category '${category.name}' already registered — overwriting. ` +\n        `(dev hot-reload 시 정상이지만 운영 환경에서 발생하면 buildup bug)`\n    )\n  }\n\n  // tool name 충돌 검사 — 다른 카테고리에 같은 name 있으면 거부\n  const newNames = new Set(category.specs.map(s => s.name))\n  for (const [otherName, other] of categories) {\n    if (otherName === category.name) continue // 같은 카테고리 재등록은 덮어쓰기 OK\n    for (const spec of other.specs) {\n      if (newNames.has(spec.name)) {\n        throw new Error(\n          `[board-ai/tool-registry] tool name '${spec.name}' already registered in category ` +\n            `'${otherName}', cannot register in '${category.name}'. tool names must be globally unique.`\n        )\n      }\n    }\n  }\n\n  categories.set(category.name, category)\n}\n\n/**\n * 대화별 도구 노출 제한 — 허용 카테고리 목록.\n *\n * `undefined` 는 **제한 없음**(등록된 전부). 호스트가 목록을 주면 그 카테고리에 속한 spec 만\n * 정의·실행 대상이 된다. 정의를 숨기는 것만으로는 부족하다 — 모델이 이름을 추측하거나 옛 대화가\n * 재생되면 숨긴 도구도 호출되므로 **dispatch 조회(findToolSpec)에도 같은 목록을 넘겨야** 한다.\n */\nexport type ToolCategoryFilter = ReadonlyArray<string> | undefined\n\n/** 허용 목록에 든 카테고리인가. 목록 없음 = 전부 허용. */\nfunction allowed(name: string, filter: ToolCategoryFilter): boolean {\n  return !filter || filter.includes(name)\n}\n\n/**\n * 등록된 모든 카테고리 (등록 순서 보존). 외부에서 불변 read-only 로 사용.\n */\nexport function getToolCategories(): ReadonlyArray<ToolCategory> {\n  return Array.from(categories.values())\n}\n\n/**\n * 등록된 모든 tool spec 의 평면 view. assistant.ts 의 buildBoardEditTools 가\n * LLM tool 정의 합집합으로 사용.\n */\nexport function getAllToolSpecs(): ReadonlyArray<ToolSpec> {\n  return getToolSpecsFor(undefined)\n}\n\n/**\n * 허용 카테고리의 spec 평면 view. `undefined` = 전부(= getAllToolSpecs 와 동일).\n * LLM 도구 정의를 만들 때 이 함수를 쓰면 대화별 노출 제한이 그대로 반영된다.\n */\nexport function getToolSpecsFor(filter: ToolCategoryFilter): ReadonlyArray<ToolSpec> {\n  const out: ToolSpec[] = []\n  for (const [catName, cat] of categories) {\n    if (!allowed(catName, filter)) continue\n    for (const spec of cat.specs) out.push(spec)\n  }\n  return out\n}\n\n/**\n * 노출된 카테고리들의 **사용 규율** 모음(등록 순서). 시스템 프롬프트에 붙이는 용도.\n *\n * 도구 목록만 보내면 모델은 \"무엇이 있는지\" 는 알지만 \"언제 반드시 불러야 하는지\" 는 모른다.\n * 규율은 도구를 등록한 쪽이 소유하고, 호스트는 노출된 것만 모아 붙인다(도메인 지식이 새지 않는다).\n */\nexport function getCategoryGuidance(filter: ToolCategoryFilter): string[] {\n  const out: string[] = []\n  for (const [catName, cat] of categories) {\n    if (!allowed(catName, filter)) continue\n    const guidance = (cat.guidance ?? '').trim()\n    if (guidance) out.push(guidance)\n  }\n  return out\n}\n\n/**\n * tool name 으로 spec 검색. 없으면 undefined.\n */\nexport function findToolSpec(name: string, filter?: ToolCategoryFilter): ToolSpec | undefined {\n  for (const [catName, cat] of categories) {\n    if (!allowed(catName, filter)) continue\n    const spec = cat.specs.find(s => s.name === name)\n    if (spec) return spec\n  }\n  return undefined\n}\n\n/**\n * tool name 의 카테고리 (read/write/action/external). 미등록 tool 은 undefined.\n * assistant.ts 의 isReadTool / isWriteTool / isActionTool 이 이 함수에 위임할 수 있다.\n */\nexport function getToolKind(name: string, filter?: ToolCategoryFilter): ToolSpec['kind'] | undefined {\n  return findToolSpec(name, filter)?.kind\n}\n\n/**\n * 등록된 tool 인지. dispatch path 가 hardcoded set 와 registry 양쪽 fallback 시 사용.\n */\nexport function hasTool(name: string, filter?: ToolCategoryFilter): boolean {\n  return findToolSpec(name, filter) !== undefined\n}\n\n/**\n * 카테고리 이름으로 spec 만 추출.\n */\nexport function getCategorySpecs(categoryName: string): ReadonlyArray<ToolSpec> {\n  return categories.get(categoryName)?.specs ?? []\n}\n\n/**\n * 테스트 전용 — 모든 등록 해제. 운영 환경에서 호출 금지.\n *\n * jest 의 setupFilesAfterEach 또는 명시적 afterEach 에서 호출해 테스트 간 격리.\n * 실제로 STYLING_TOOLS 는 board-ai 자체 부트스트랩에서 다시 등록되므로 clear 후\n * 명시 register 가 필요한 것은 동적 카테고리 (board-import 등) 뿐.\n */\nexport function clearToolRegistry(): void {\n  categories.clear()\n}\n"]}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../server/service/tool-registry/registry.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * ToolCategoryRegistry — 외부 도메인 패키지가 LLM tool category 를 동적 등록하는 점.\n *\n * 사용 패턴 (외부 패키지의 server bootstrap):\n *   ```ts\n *   import { registerToolCategory } from '@things-factory/board-ai'\n *\n *   registerToolCategory({\n *     name: 'board-import',\n *     specs: [\n *       { kind: 'external', name: 'importBoardAsync', schema: {...}, builder: ... },\n *       { kind: 'read',     name: 'getImportSession', schema: {...}, builder: ... },\n *       ...\n *     ]\n *   })\n *   ```\n *\n * board-ai assistant.ts 의 buildBoardEditTools / dispatch / isWriteTool 등이\n * 본 registry 에서 자동 도출.\n *\n * 정책:\n *   - 카테고리 이름은 unique. 같은 이름으로 재등록하면 덮어쓰기 (외부 패키지의\n *     hot-reload / dev 환경 대응). console.warn 으로 알림.\n *   - tool name 은 카테고리 간 통틀어 unique. 충돌 시 등록 거부 + 명확한 에러\n *     (LLM dispatch 가 모호해지지 않도록).\n *   - clear() 는 테스트 전용. 운영 환경에서 호출 금지.\n */\nimport type { ToolCategory, ToolSpec } from './types'\n\nconst categories: Map<string, ToolCategory> = new Map()\n\n/** A registration that was accepted but is not yet what the contract requires. Code + params, not prose. */\nexport interface ToolRegistryWarning {\n  code: 'tool-privilege-undeclared'\n  params: { category: string; tool: string; kind: ToolSpec['kind'] }\n  /** For a person reading it; the code and params are what callers act on. */\n  message: string\n}\n\nconst warnings: ToolRegistryWarning[] = []\n\n/**\n * What registration accepted but the contract does not yet allow. Stage one of A1 records these\n * instead of refusing; a host shows them at boot, and when the list is empty the rule becomes a refusal.\n */\nexport function getToolRegistryWarnings(): ReadonlyArray<ToolRegistryWarning> {\n  return warnings.slice()\n}\n\n/**\n * 카테고리 등록. tool name 충돌 시 throw, 이름 중복 등록 시 덮어쓰기 + warn.\n */\nexport function registerToolCategory(category: ToolCategory): void {\n  /*\n   * 지침 없는 카테고리는 **등록하지 않는다.**\n   *\n   * 도구 목록만 보낸 모델이 「불러야 할 때 부른다」를 맞히지 못한 사고가 있었다 — 조치 요청에\n   * `proposeAction` 을 부르지 않고 「제안해 두었습니다」라고 답해, 사용자에게 없는 버튼을 누르라고\n   * 안내했다. 화면에는 아무 일도 없었고 오류도 나지 않았다(§`ToolCategory.guidance`).\n   *\n   * 그 뒤로 규율을 적는 자리를 만들었지만 **선택이었다.** 선택인 규율은 그 사고를 아는 사람만\n   * 채운다. 여기서 거절하는 이유가 그것이다 — 빠진 것을 부팅에서 만든 사람이 보고, 모델이 헛말을\n   * 한 뒤에 사용자가 보지 않는다.\n   *\n   * 빈 문자열·공백도 거절한다. 통과시키면 이 검사가 형식이 되고, 형식이 된 검사는 없는 것과 같다.\n   */\n  if (!String(category.guidance ?? '').trim()) {\n    throw new Error(\n      `[ai-client-base/tool-registry] category '${category.name}' has no guidance. ` +\n        'Tool descriptions say what a tool does; guidance says when the model must call one. ' +\n        'Without it a model answers as though it called a tool it did not, and nothing errors. ' +\n        'Write the rules for these tools in `guidance` — the side that registers them owns them.'\n    )\n  }\n\n  /*\n   * A tool that changes something must say which privilege it goes through (A1, 2026-09-17).\n   *\n   * The conversation door checks one privilege — may this person talk to the assistant. Without a\n   * privilege on the tool, that single check opened every tool behind it: a user holding only\n   * `ai-assistant:mutation` could reach board-import's `materializeImportSession` and create a\n   * Board.\n   *\n   * **This is stage one of two: surface, then refuse** (ADR-0037, \"먼저 드러내고, 목록이 비면 막는다\").\n   * Refusing now would stop every app whose tools predate the `privilege` field from booting, and\n   * those apps compile against an installed copy that does not have the field yet. So an undeclared\n   * tool still registers, and the omission is recorded as a code (`getToolRegistryWarnings`), not\n   * a log line — a warning only a log carries is not distinguishable from no warning. When the list\n   * is empty across the apps, this becomes a refusal.\n   */\n  warnings.splice(0, warnings.length, ...warnings.filter(w => w.params.category !== category.name))\n  for (const spec of category.specs) {\n    if (spec.kind !== 'read' && !(spec.privilege?.category && spec.privilege?.privilege)) {\n      warnings.push({\n        code: 'tool-privilege-undeclared',\n        params: { category: category.name, tool: spec.name, kind: spec.kind },\n        message:\n          `tool '${spec.name}' in category '${category.name}' is '${spec.kind}' but declares no privilege — ` +\n          'declare the same { category, privilege } its GraphQL door uses'\n      })\n    }\n  }\n\n  if (categories.has(category.name)) {\n    console.warn(\n      `[board-ai/tool-registry] category '${category.name}' already registered — overwriting. ` +\n        `(dev hot-reload 시 정상이지만 운영 환경에서 발생하면 buildup bug)`\n    )\n  }\n\n  // tool name 충돌 검사 — 다른 카테고리에 같은 name 있으면 거부\n  const newNames = new Set(category.specs.map(s => s.name))\n  for (const [otherName, other] of categories) {\n    if (otherName === category.name) continue // 같은 카테고리 재등록은 덮어쓰기 OK\n    for (const spec of other.specs) {\n      if (newNames.has(spec.name)) {\n        throw new Error(\n          `[board-ai/tool-registry] tool name '${spec.name}' already registered in category ` +\n            `'${otherName}', cannot register in '${category.name}'. tool names must be globally unique.`\n        )\n      }\n    }\n  }\n\n  categories.set(category.name, category)\n}\n\n/**\n * 대화별 도구 노출 제한 — 허용 카테고리 목록.\n *\n * `undefined` 는 **제한 없음**(등록된 전부). 호스트가 목록을 주면 그 카테고리에 속한 spec 만\n * 정의·실행 대상이 된다. 정의를 숨기는 것만으로는 부족하다 — 모델이 이름을 추측하거나 옛 대화가\n * 재생되면 숨긴 도구도 호출되므로 **dispatch 조회(findToolSpec)에도 같은 목록을 넘겨야** 한다.\n */\nexport type ToolCategoryFilter = ReadonlyArray<string> | undefined\n\n/** 허용 목록에 든 카테고리인가. 목록 없음 = 전부 허용. */\nfunction allowed(name: string, filter: ToolCategoryFilter): boolean {\n  return !filter || filter.includes(name)\n}\n\n/**\n * 등록된 모든 카테고리 (등록 순서 보존). 외부에서 불변 read-only 로 사용.\n */\nexport function getToolCategories(): ReadonlyArray<ToolCategory> {\n  return Array.from(categories.values())\n}\n\n/**\n * 등록된 모든 tool spec 의 평면 view. assistant.ts 의 buildBoardEditTools 가\n * LLM tool 정의 합집합으로 사용.\n */\nexport function getAllToolSpecs(): ReadonlyArray<ToolSpec> {\n  return getToolSpecsFor(undefined)\n}\n\n/**\n * 허용 카테고리의 spec 평면 view. `undefined` = 전부(= getAllToolSpecs 와 동일).\n * LLM 도구 정의를 만들 때 이 함수를 쓰면 대화별 노출 제한이 그대로 반영된다.\n */\nexport function getToolSpecsFor(filter: ToolCategoryFilter): ReadonlyArray<ToolSpec> {\n  const out: ToolSpec[] = []\n  for (const [catName, cat] of categories) {\n    if (!allowed(catName, filter)) continue\n    for (const spec of cat.specs) out.push(spec)\n  }\n  return out\n}\n\n/**\n * 노출된 카테고리들의 **사용 규율** 모음(등록 순서). 시스템 프롬프트에 붙이는 용도.\n *\n * 도구 목록만 보내면 모델은 \"무엇이 있는지\" 는 알지만 \"언제 반드시 불러야 하는지\" 는 모른다.\n * 규율은 도구를 등록한 쪽이 소유하고, 호스트는 노출된 것만 모아 붙인다(도메인 지식이 새지 않는다).\n */\nexport function getCategoryGuidance(filter: ToolCategoryFilter): string[] {\n  const out: string[] = []\n  for (const [catName, cat] of categories) {\n    if (!allowed(catName, filter)) continue\n    const guidance = (cat.guidance ?? '').trim()\n    if (guidance) out.push(guidance)\n  }\n  return out\n}\n\n/**\n * tool name 으로 spec 검색. 없으면 undefined.\n */\nexport function findToolSpec(name: string, filter?: ToolCategoryFilter): ToolSpec | undefined {\n  for (const [catName, cat] of categories) {\n    if (!allowed(catName, filter)) continue\n    const spec = cat.specs.find(s => s.name === name)\n    if (spec) return spec\n  }\n  return undefined\n}\n\n/**\n * tool name 의 카테고리 (read/write/action/external). 미등록 tool 은 undefined.\n * assistant.ts 의 isReadTool / isWriteTool / isActionTool 이 이 함수에 위임할 수 있다.\n */\nexport function getToolKind(name: string, filter?: ToolCategoryFilter): ToolSpec['kind'] | undefined {\n  return findToolSpec(name, filter)?.kind\n}\n\n/**\n * 등록된 tool 인지. dispatch path 가 hardcoded set 와 registry 양쪽 fallback 시 사용.\n */\nexport function hasTool(name: string, filter?: ToolCategoryFilter): boolean {\n  return findToolSpec(name, filter) !== undefined\n}\n\n/**\n * 카테고리 이름으로 spec 만 추출.\n */\nexport function getCategorySpecs(categoryName: string): ReadonlyArray<ToolSpec> {\n  return categories.get(categoryName)?.specs ?? []\n}\n\n/**\n * 테스트 전용 — 모든 등록 해제. 운영 환경에서 호출 금지.\n *\n * jest 의 setupFilesAfterEach 또는 명시적 afterEach 에서 호출해 테스트 간 격리.\n * 실제로 STYLING_TOOLS 는 board-ai 자체 부트스트랩에서 다시 등록되므로 clear 후\n * 명시 register 가 필요한 것은 동적 카테고리 (board-import 등) 뿐.\n */\nexport function clearToolRegistry(): void {\n  categories.clear()\n  warnings.length = 0\n}\n"]}

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

@@ -12,7 +12,7 @@
  *
  * 설계 원칙:
  *   - **카테고리별 builder 시그니처 다양성을 통합**: read 는 (args, ctx) → any,
- *     write 는 (args, components) → BoardEditOp[], action 은 (args) → BoardActionOp.
+ *     write 는 (args, components) → SceneEditOp[], action 은 (args) → SceneActionOp.
  *     하나의 ToolSpec 에 모든 시그니처를 union 으로 담지 않고, 카테고리에 맞는
  *     builder 만 채우면 되도록 카테고리별 sub-interface 분리.
  *   - **kind 필드로 자가 분류**: registry 가 isReadTool / isWriteTool 자동 도출.
@@ -21,6 +21,30 @@
  *     점진적으로 다른 hardcoded tool 들 (addComponent / alignComponents 등) 도
  *     같은 registry 로 흡수 가능. 한 단계씩 byte-단위 동등성 단위 테스트 보장.
  */
+/**
+ * What `registryAssistantChat` — the door apps use (`assistantChat`, ADR-0061 decision 0) — hands a
+ * registered tool when it runs.
+ *
+ * `state` and `host` sit side by side. The twin's space tools read `ctx.state.host` while this door
+ * passed `ctx.host`, so they never saw the space; the two are never merged into one object.
+ *
+ * The board product's door (board-ai) passes its own shape and is not part of this contract.
+ */
+export interface ToolCallContext {
+    /** The request state the server built — domain, user, tx. The only basis for authorization. */
+    state: any;
+    /**
+     * The client's `AssistantMode.hostContext`, passed through as is. **Untrusted** — a tool that reads
+     * an id from it checks that the id belongs to the caller's tenant. `{}` when none was sent.
+     */
+    host: Record<string, any>;
+    /** The conversation's mode. Filled once modes are registered on the server (A2); absent until then. */
+    mode?: ToolCallMode;
+}
+export interface ToolCallMode {
+    kind: string;
+    target?: string;
+}
 /**
  * Read tool — server 측 즉시 실행, 결과를 LLM 에 회신. board model 변경 X.
  * 예: getSelection / findComponents / importSession (query)
@@ -41,7 +65,7 @@ export interface ReadToolContext {
  * 예: board-ai 의 addComponent / setFill / modifyBoard.
  *
  * builder 의 return type 은 unknown 으로 둔다 — 도메인별 dispatcher (예: board-ai 의
- * toolCallToBoardEditOp) 가 자기 EditOp[] 로 cast. ops/errors wrapper 형태도 동일 의미.
+ * toolCallToSceneEditOp) 가 자기 EditOp[] 로 cast. ops/errors wrapper 형태도 동일 의미.
  */
 export type WriteToolBuilder = (args: any, context: WriteToolContext) => any[] | {
     ops: any[];
@@ -55,8 +79,8 @@ export interface WriteToolContext {
  * Action tool — ephemeral scene 조작 (select / center / fit / sceneMode).
  * board model 변경 X, undo 영향 X. host 가 별도 channel 로 적용.
  *
- * return type 은 unknown — 도메인별 dispatcher (예: board-ai 의 toolCallToBoardActionOp)
- * 가 자기 BoardActionOp 으로 cast.
+ * return type 은 unknown — 도메인별 dispatcher (예: board-ai 의 toolCallToSceneActionOp)
+ * 가 자기 SceneActionOp 으로 cast.
  */
 export type ActionToolBuilder = (args: any) => any | null;
 /**
@@ -71,6 +95,22 @@ export interface ExternalToolContext {
     state?: any;
     [k: string]: any;
 }
+/**
+ * The privilege a tool requires — the same `category`/`privilege` the tool's GraphQL door declares
+ * (`@privilege(category, privilege, owner?, super?)`), so the fields mirror `PrivilegeObject`.
+ *
+ * A tool is not a new door; it is another way into a door that already exists. A tool that creates
+ * a Board goes through the privilege that creating a Board already needs. Minting an AI-only
+ * privilege name would put two doors on one effect, and one of them would end up looser.
+ */
+export interface ToolPrivilege {
+    category: string;
+    privilege: string;
+    /** Domain owners pass without the privilege — mirror the door's `domainOwnerGranted`. */
+    owner?: boolean;
+    /** Super users pass without the privilege — mirror the door's `superUserGranted`. */
+    super?: boolean;
+}
 /**
  * 모든 ToolSpec 공통 메타데이터.
  */
@@ -86,6 +126,14 @@ export interface ToolSpecBase {
     themeNote?: string;
     /** JSON Schema for parameters — LLM tool schema 에 그대로 노출. */
     schema: any;
+    /**
+     * The privilege a caller needs before this tool is offered or run. See `ToolPrivilege`.
+     *
+     * Expected for `write`, `action` and `external` — registration records a
+     * `tool-privilege-undeclared` warning for one without it (A1 stage one). A `read` tool without it is
+     * offered on domain membership alone, and its builder must check what it reads.
+     */
+    privilege?: ToolPrivilege;
 }
 export interface ReadToolSpec extends ToolSpecBase {
     kind: 'read';