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

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

@@ -0,0 +1,86 @@
+/*
+ * 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).
+ */
+import { getToolCategories, 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 const EMPTY_TOOL_SCOPE: ToolScope = Object.freeze({ categories: [], specs: [] })
+
+const privilegeKey = (p: ToolPrivilege) => [p.category, p.privilege, !!p.owner, !!p.super].join('|')
+
+export async function resolveToolScope(requested: ToolCategoryFilter, access?: ToolAccessCheck): Promise<ToolScope> {
+  if (!requested || requested.length === 0) return EMPTY_TOOL_SCOPE
+
+  /* One check per distinct privilege — a category of ten read tools asks once. */
+  const answers = new Map<string, Promise<boolean>>()
+  const mayUse = (spec: ToolSpec): Promise<boolean> => {
+    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: ScopedCategory[] = []
+  for (const category of 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.
+ */
+export function narrowToolScope(scope: ToolScope, keep: (spec: ToolSpec) => boolean): ToolScope {
+  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. */
+export function toolScopeGuidance(scope: ToolScope): string[] {
+  return scope.categories.map(category => category.guidance).filter(Boolean)
+}
+
+function fromCategories(categories: ScopedCategory[]): ToolScope {
+  return { categories, specs: categories.flatMap(category => category.specs) }
+}

package/server/service/index.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/server/service/testing/tool-call-context.ts

@@ -0,0 +1,28 @@
+/*
+ * The one way a test builds what a registered tool is handed (A3, 2026-09-17).
+ *
+ * The twin's space tools read `ctx.state.host` while the door passed `ctx.host`, and their tests
+ * stayed green because each test wrote its own context in the shape the tool expected. A fixture
+ * owned by each test agrees with its tool by construction. This one is owned by the package that
+ * defines the neutral door, and that door's tests check it hands tools exactly this shape — so a tool
+ * test built on it fails when the tool reads a field no door fills.
+ */
+import type { 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 function toolCallContextFixture(input: ToolCallContextFixtureInput = {}): ToolCallContext {
+  const context: ToolCallContext = {
+    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
+}

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

@@ -13,15 +13,17 @@ export {
   getToolKind,
   hasTool,
   getCategorySpecs,
-  clearToolRegistry
+  clearToolRegistry,
+  getToolRegistryWarnings
 } from './registry'
 
 /* 대화별 노출 제한 타입은 registry 소유(정의가 거기 있다). */
-export type { ToolCategoryFilter } from './registry'
+export type { ToolCategoryFilter, ToolRegistryWarning } from './registry'
 
 export type {
   ToolSpec,
   ToolSpecBase,
+  ToolPrivilege,
   ReadToolSpec,
   WriteToolSpec,
   ActionToolSpec,
@@ -33,5 +35,7 @@ export type {
   ExternalToolBuilder,
   ReadToolContext,
   WriteToolContext,
-  ExternalToolContext
+  ExternalToolContext,
+  ToolCallContext,
+  ToolCallMode
 } from './types'

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

@@ -14,7 +14,7 @@ import {
   getToolKind,
   hasTool,
   getCategorySpecs,
-  clearToolRegistry, getCategoryGuidance } from './registry'
+  clearToolRegistry, getCategoryGuidance, getToolRegistryWarnings } from './registry'
 import type { ToolCategory, ToolSpec } from './types'
 
 // 테스트 간 격리
@@ -34,6 +34,8 @@ function makeCategory(name: string, specs: Partial<ToolSpec>[]): ToolCategory {
       description: 'desc',
       schema: {},
       builder: () => ({}),
+      /* A tool that changes something must name its door (A1). The fixture does, like guidance. */
+      ...(s.kind && s.kind !== 'read' ? { privilege: { category: 'fixture', privilege: 'mutation' } } : {}),
       ...s
     })) as ToolSpec[]
   }
@@ -174,6 +176,7 @@ describe('registry — spec 보존', () => {
           kind: 'write',
           name: 't1',
           description: 'main desc',
+          privilege: { category: 'fixture', privilege: 'mutation' },
           themeNote: '⚠ note',
           schema: { type: 'object' },
           builder: () => null
@@ -258,3 +261,49 @@ describe('registry — 지침 없는 카테고리는 등록되지 않는다', ()
     expect(getToolCategories()[0].guidance).toContain('fixture guidance')
   })
 })
+
+describe('registry — a tool that changes something names its door (A1, stage one: surface)', () => {
+  test.each(['write', 'action', 'external'] as const)(
+    '★ a %s tool without a privilege registers, and the omission is recorded as a code',
+    kind => {
+      registerToolCategory({
+        name: 'no-door',
+        guidance: '- fixture guidance for no-door',
+        specs: [{ kind, name: 'changesThings', description: 'd', schema: {}, builder: () => null } as any]
+      })
+      expect(getToolKind('changesThings')).toBe(kind)
+      expect(getToolRegistryWarnings()).toEqual([
+        expect.objectContaining({
+          code: 'tool-privilege-undeclared',
+          params: { category: 'no-door', tool: 'changesThings', kind }
+        })
+      ])
+    }
+  )
+
+  test('a privilege with no privilege name is recorded the same way', () => {
+    registerToolCategory({
+      name: 'half-door',
+      guidance: '- fixture guidance for half-door',
+      specs: [
+        { kind: 'external', name: 'halfDoor', description: 'd', schema: {}, builder: () => null, privilege: { category: 'board' } } as any
+      ]
+    })
+    expect(getToolRegistryWarnings().map(w => w.params.tool)).toEqual(['halfDoor'])
+  })
+
+  test('a declared tool and a read tool leave no warning', () => {
+    registerToolCategory(makeCategory('declared', [{ name: 'w1', kind: 'write' }, { name: 'r1', kind: 'read' }]))
+    expect(getToolRegistryWarnings()).toEqual([])
+  })
+
+  test('re-registering a category replaces its warnings instead of piling them up', () => {
+    const undeclared = { kind: 'write', name: 'w9', description: 'd', schema: {}, builder: () => null } as any
+    registerToolCategory({ name: 'again', guidance: '- g', specs: [undeclared] })
+    registerToolCategory({ name: 'again', guidance: '- g', specs: [undeclared] })
+    expect(getToolRegistryWarnings()).toHaveLength(1)
+
+    registerToolCategory({ name: 'again', guidance: '- g', specs: [{ ...undeclared, privilege: { category: 'c', privilege: 'mutation' } }] })
+    expect(getToolRegistryWarnings()).toEqual([])
+  })
+})

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

@@ -29,6 +29,24 @@ import type { ToolCategory, ToolSpec } from './types'
 
 const categories: Map<string, ToolCategory> = new Map()
 
+/** 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
+}
+
+const warnings: ToolRegistryWarning[] = []
+
+/**
+ * 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 function getToolRegistryWarnings(): ReadonlyArray<ToolRegistryWarning> {
+  return warnings.slice()
+}
+
 /**
  * 카테고리 등록. tool name 충돌 시 throw, 이름 중복 등록 시 덮어쓰기 + warn.
  */
@@ -55,6 +73,34 @@ export function registerToolCategory(category: ToolCategory): void {
     )
   }
 
+  /*
+   * 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. ` +
@@ -180,4 +226,5 @@ export function getCategorySpecs(categoryName: string): ReadonlyArray<ToolSpec>
  */
 export function clearToolRegistry(): void {
   categories.clear()
+  warnings.length = 0
 }

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

@@ -27,6 +27,34 @@
 // 도메인 type 으로 좁힌다. 사용자가 ToolSpec<TWrite, TAction> generic 까지 정밀화하면
 // 좋겠지만, 11~50 개 spec 마다 type 인자 전파가 부담이라 unknown 으로 합의.
 
+// ── ToolCallContext — what the neutral conversation door hands a registered tool (A3) ──
+
+/**
+ * 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
+}
+
 // ── 카테고리별 builder 시그니처 ──────────────────────────────────────
 
 /**
@@ -48,7 +76,6 @@ export interface ReadToolContext {
   /** 이외 주입은 카테고리별로 자유. tool 등록자가 type 좁힐 수 있도록 unknown 으로 보존. */
   [k: string]: any
 }
-
 /**
  * Write tool — domain edit op 발생. host 가 patch 적용 후 영속화.
  * 예: board-ai 의 addComponent / setFill / modifyBoard.
@@ -65,7 +92,6 @@ export interface WriteToolContext {
   components?: ReadonlyArray<any>
   [k: string]: any
 }
-
 /**
  * Action tool — ephemeral scene 조작 (select / center / fit / sceneMode).
  * board model 변경 X, undo 영향 X. host 가 별도 channel 로 적용.
@@ -91,9 +117,25 @@ export interface ExternalToolContext {
   state?: any
   [k: string]: any
 }
-
 // ── ToolSpec — 카테고리별 변형 ──────────────────────────────────────
 
+/**
+ * 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 공통 메타데이터.
  */
@@ -109,6 +151,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 {