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

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,90 @@ 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 leaves no warning', () => {
+    registerToolCategory(makeCategory('declared', [{ name: 'w1', kind: 'write' }]))
+    expect(getToolRegistryWarnings()).toEqual([])
+  })
+
+  /*
+   * 읽는 도구도 자기가 닿는 문을 말한다(ADR-0071 결정 2). 그전까지 업무 권한을 스스로 확인하는 것은
+   * plant 뿐이었고, twin · figure 의 읽는 도구는 테넌트만 봤다 — 대화 문 권한만 있으면 그 자료를 읽었다.
+   */
+  test('★ a read tool that says nothing about its door is recorded too', () => {
+    registerToolCategory(makeCategory('reads', [{ name: 'r1', kind: 'read' }]))
+
+    expect(getToolRegistryWarnings()).toEqual([
+      expect.objectContaining({ code: 'tool-privilege-undeclared', params: { category: 'reads', tool: 'r1', kind: 'read' } })
+    ])
+  })
+
+  test('★ `doors: []` is an answer — a tool that reaches no door has nothing to gate', () => {
+    registerToolCategory({
+      name: 'surface-only',
+      guidance: '- fixture guidance for surface-only',
+      specs: [
+        { kind: 'read', name: 'getOpenScene', description: 'd', schema: {}, builder: () => null, doors: [] } as any
+      ]
+    })
+
+    expect(getToolRegistryWarnings()).toEqual([])
+  })
+
+  test('★ a named door with no privilege of its own is its own fact, not an omission', () => {
+    registerToolCategory({
+      name: 'waiting',
+      guidance: '- fixture guidance for waiting',
+      specs: [
+        { kind: 'read', name: 'twinNowTool', description: 'd', schema: {}, builder: () => null, doors: ['Query.twinNow'] } as any
+      ]
+    })
+
+    expect(getToolRegistryWarnings()).toEqual([
+      expect.objectContaining({
+        code: 'tool-door-has-no-privilege',
+        params: { category: 'waiting', tool: 'twinNowTool', kind: 'read', doors: ['Query.twinNow'] }
+      })
+    ])
+  })
+
+  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,30 @@ 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 {
+  /**
+   * `tool-privilege-undeclared` — nothing said which door this tool reaches.
+   * `tool-door-has-no-privilege` — the door was named and it declares no privilege of its own yet
+   *   (twin's queries, waiting on AUTH stage two). The tool cannot be stricter than its door, so
+   *   this is a different fact from saying nothing, and the report keeps the two apart.
+   */
+  code: 'tool-privilege-undeclared' | 'tool-door-has-no-privilege'
+  params: { category: string; tool: string; kind: ToolSpec['kind']; doors?: string[] }
+  /** 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,10 +79,61 @@ 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) {
+    const declared = Boolean(spec.privilege?.category && spec.privilege?.privilege)
+    if (declared) continue
+
+    /*
+     * An empty list says this tool reaches no door — the ones that hand back what the surface sent
+     * are that. Nothing to gate, nothing to report.
+     */
+    if (Array.isArray(spec.doors) && spec.doors.length === 0) continue
+
+    if (spec.doors?.length) {
+      /*
+       * The door is named and carries no privilege yet. The tool cannot be stricter than the door
+       * it reaches, so this is not an omission by whoever wrote the tool — it is the door's turn
+       * (ADR-0071 decision 2). Reported under its own code so the two are not read as one list.
+       */
+      warnings.push({
+        code: 'tool-door-has-no-privilege',
+        params: { category: category.name, tool: spec.name, kind: spec.kind, doors: spec.doors },
+        message:
+          `tool '${spec.name}' reaches ${spec.doors.join(' + ')}, which declare no privilege — ` +
+          'the tool is as open as the doors it reaches until they declare one'
+      })
+      continue
+    }
+
+    warnings.push({
+      code: 'tool-privilege-undeclared',
+      params: { category: category.name, tool: spec.name, kind: spec.kind },
+      message:
+        `tool '${spec.name}' in category '${category.name}' says nothing about the doors it reaches — ` +
+        "declare `doors` with the same { category, privilege } those doors use, or `doors: []` when it reaches none"
+    })
+  }
+
   if (categories.has(category.name)) {
     console.warn(
       `[board-ai/tool-registry] category '${category.name}' already registered — overwriting. ` +
-        `(dev hot-reload 시 정상이지만 운영 환경에서 발생하면 buildup bug)`
+        '(normal on a dev hot reload; in production it means the same category is registered twice)'
     )
   }
 
@@ -180,4 +255,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,39 @@ 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).
+   */
+  privilege?: ToolPrivilege
+
+  /**
+   * Which GraphQL doors this tool reaches — `['Query.twinNow']`,
+   * `['Query.productionSummary', 'Query.pendingSummary']`.
+   *
+   * **A read tool names its doors too** (ADR-0071 decision 2, shaped by ADR-0072). Before that,
+   * only plant's tools asked whether the caller may read what they read; twin's and figure's
+   * checked the tenant and nothing else, so holding the conversation's own privilege was enough to
+   * reach their business data.
+   *
+   * **Always a list, even for one** — one shape to read. A tool that answers from several doors
+   * needs the caller to hold **all** of them (AND, the same reading as AUTH's `requiresAll`):
+   * plant's factory overview answers from two, and asking for only one of them would hand back
+   * half of what the caller may not see.
+   *
+   * Three states, and the boot report keeps them apart:
+   *   - doors and a privilege — the gate checks it
+   *   - `doors: []` — this tool reaches no door at all. The ones that hand back what the surface
+   *     sent (`getOpenScene`, `getStationScreen`) are this: there is nothing behind them to gate.
+   *   - doors with no privilege — the doors themselves declare none yet (twin's queries, waiting
+   *     on AUTH stage two). A tool cannot be stricter than the door it reaches.
+   *
+   * The privilege is **the door's**, copied, and a test in each app compares the copy with the
+   * directive on that field. When the schema can be read at boot, the copy goes away.
+   */
+  doors?: string[]
 }
 
 export interface ReadToolSpec extends ToolSpecBase {