@things-factory/ai-assistant 10.1.29 → 10.1.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/ai-assistant",
-  "version": "10.1.29",
+  "version": "10.1.32",
   "main": "dist-server/index.js",
   "things-factory": true,
   "author": "heartyoh",
@@ -29,10 +29,10 @@
     "@operato/graphql": "^10.0.0",
     "@operato/i18n": "^10.0.0",
     "@operato/styles": "^10.0.0",
-    "@things-factory/ai-client-base": "^10.1.29",
-    "@things-factory/auth-base": "^10.1.29",
+    "@things-factory/ai-client-base": "^10.1.31",
+    "@things-factory/auth-base": "^10.1.31",
     "@things-factory/env": "^10.1.20",
-    "@things-factory/shell": "^10.1.29",
+    "@things-factory/shell": "^10.1.31",
     "dompurify": "^3.0.0",
     "graphql-scalars": "^1.22.0",
     "graphql-tag": "^2.12.6",
@@ -44,5 +44,5 @@
     "copyfiles": "^2.4.1",
     "rimraf": "^5.0.0"
   },
-  "gitHead": "e6bf9dec003fe5e794746aaeb5852b3b50478232"
+  "gitHead": "67b211e001da3a923e562cb048e4691bd961315c"
 }

package/server/service/assistant-mode/index.ts

@@ -1,7 +1,7 @@
 /**
  * Modes — what each conversation is, declared by the app server that owns the screen.
  *
- * Design: ADR-0061 decision 7 (`operato-twin/design/04-decisions.md`) and the AI standard's A2.
+ * Design: ADR-0061 decision 7 (`operato-application/adr/ADR-0061.md`) and the AI standard's A2.
  */
 export {
   registerAssistantMode,

package/server/service/testing/conversation-scenario.test.ts

@@ -22,10 +22,11 @@ beforeEach(() => {
     name: 'twin-ops',
     guidance: 'call summarizeStatus before describing the line',
     specs: [
-      { kind: 'read', name: 'summarizeStatus', description: 'read the line', schema: {}, builder: async () => ({ line: 3, stopped: true }) },
+      { kind: 'read', name: 'summarizeStatus', doors: ['Query.twinReplay'], description: 'read the line', schema: {}, builder: async () => ({ line: 3, stopped: true }) },
       {
         kind: 'read',
         name: 'proposeAction',
+        doors: ['Query.twinReplay'],
         description: 'propose stopping the line',
         schema: {},
         builder: async () => ({ proposed: true, command: 'stop', instanceId: 'LINE-3', label: '3 라인 정지' })

package/server/service/testing/conversation-script.test.ts

@@ -16,8 +16,8 @@ beforeEach(() => {
     name: 'twin-ops',
     guidance: 'call summarizeStatus before describing the line',
     specs: [
-      { kind: 'read', name: 'summarizeStatus', description: 'read the line', schema: {}, builder: async () => ({ stopped: true }) },
-      { kind: 'write', name: 'stopLine', description: 'stop the line', schema: {}, builder: async () => ({ ok: true }) }
+      { kind: 'read', name: 'summarizeStatus', doors: ['Query.twinReplay'], description: 'read the line', schema: {}, builder: async () => ({ stopped: true }) },
+      { kind: 'write', name: 'stopLine', doors: ['Mutation.twinCommand'], description: 'stop the line', schema: {}, builder: async () => ({ ok: true }) }
     ]
   } as any)
 })
@@ -101,6 +101,8 @@ it('★ a proposal belongs to the turn that asked for it', async () => {
       {
         kind: 'read',
         name: 'proposeSceneEdit',
+        /* 저작 도구는 열린 씬만 본다 — 저장소에 닿지 않으므로 문이 없다. */
+        doors: [],
         description: 'propose placing a component',
         schema: {},
         builder: async () => ({ proposed: true, kind: 'scene-edit', label: 'place EQ-1', ops: [] })

package/server/service/testing/conversation-script.ts

@@ -131,6 +131,13 @@ export interface ConversationOptions {
   systemPrompt?: string
   /** Which registered categories this conversation may use. Omitted allows none. */
   toolCategories?: string[]
+  /**
+   * Which doors this script's speaker may pass (ADR-0071 decision 2). A tool is offered when the
+   * caller passes every door it names, so a script that says nothing here is written as someone who
+   * passes them all — the permission axis belongs to `tool-access`, not to a conversation script.
+   * Name the doors to write the other case: a person the tool is not offered to.
+   */
+  toolAccess?: (door: string) => Promise<boolean>
   /** Request state the tools receive (domain, user). */
   state?: any
   /** What the surface is looking at — reaches tools as `ctx.host`, never the model. */
@@ -263,6 +270,7 @@ export function conversation(options: ConversationOptions = {}) {
           messages: buildLlmHistory(rows, {}) as any,
           systemPrompt: options.systemPrompt ?? 'you are a test assistant',
           toolCategories: options.toolCategories,
+          toolAccess: options.toolAccess ?? (async () => true),
           hostContext: options.hostContext,
           state: options.state ?? { domain: { id: 'dom-1' }, user: { id: 'u-1' } },
           requireToolOnFirstTurn: options.requireToolOnFirstTurn

package/server/service/testing/mode-conformance.test.ts

@@ -0,0 +1,48 @@
+/*
+ * What this guards: the harness an app uses to check its own modes asks about **modes**, not about
+ * permission.
+ *
+ * `runRegisteredMode` answers "which tools does this mode open". Since the gate moved onto `doors`
+ * (ADR-0071 decision 2), a tool that names a door is closed to a caller with no access check —
+ * which is right in a request and wrong in a conformance run: an app checking that its mode opens
+ * four tools would see three, and the one that vanishes is the one that reads real data.
+ *
+ * So the harness runs as someone who passes every door, and an app that wants the other case names
+ * it. The permission axis has its own tests (`tool-access.test.ts` · `tool-scope.test.ts`).
+ */
+import { clearAssistantModes, registerAssistantMode } from '../assistant-mode/registry'
+import { clearToolRegistry, registerToolCategory } from '@things-factory/ai-client-base'
+
+import { runRegisteredMode } from './mode-conformance'
+
+const client = {
+  chatWithTools: async () => ({ text: '한 턴', toolCalls: [], stopReason: 'end_turn' })
+}
+
+beforeEach(() => {
+  clearAssistantModes()
+  clearToolRegistry()
+  registerToolCategory({
+    name: 'twin-authoring',
+    guidance: 'read the scene before proposing an edit',
+    specs: [
+      /* 화면이 보낸 것을 되돌려 준다 — 저장소에 안 닿는다. */
+      { kind: 'read', name: 'getOpenScene', description: 'the open scene', schema: {}, doors: [], builder: () => ({}) },
+      /* 저장소를 읽는다 — 문을 적는다. 관문이 이 자리를 가른다. */
+      { kind: 'read', name: 'getTwinStructure', description: 'the twin structure', schema: {}, doors: ['Query.twinInstances'], builder: () => ({}) }
+    ]
+  } as any)
+  registerAssistantMode({ kind: 'twin.space', systemPrompt: 'you answer about one space', toolCategories: ['twin-authoring'] } as any)
+})
+
+it('★ a mode opens the tools that read real data too — a conformance run is not a caller without permission', async () => {
+  const result = await runRegisteredMode('twin.space', { client })
+
+  expect(result.offeredTools.sort()).toEqual(['getOpenScene', 'getTwinStructure'])
+})
+
+it('an app that wants to see the other case names it — the door the caller cannot pass', async () => {
+  const result = await runRegisteredMode('twin.space', { client, toolAccess: async () => false })
+
+  expect(result.offeredTools).toEqual(['getOpenScene'])
+})

package/server/service/testing/mode-conformance.ts

@@ -52,7 +52,14 @@ export async function runRegisteredMode(
     temperature: settings.temperature,
     maxTokens: settings.maxTokens,
     hostContext: options.hostContext,
-    toolAccess: options.toolAccess,
+    /*
+     * 이 하네스가 묻는 것은 **모드**다 — 「이 모드가 무엇을 여는가」이지 「이 사람이 문을 지나는가」가
+     * 아니다. 관문이 `doors` 로 옮겨간 뒤(ADR-0071 결정 2) 검사를 안 넘기면 문을 적은 도구가 전부
+     * 닫히고, 그러면 앱의 적합성 시험에서 **실제 자료를 읽는 도구만** 조용히 사라진다. 그래서 기본은
+     * 모든 문을 지나는 사람이고, 다른 쪽을 보고 싶은 앱은 `toolAccess` 를 적어 그 경우를 쓴다.
+     * 권한 축은 자기 시험이 따로 본다(`tool-access.test.ts` · `tool-scope.test.ts`).
+     */
+    toolAccess: options.toolAccess ?? (async () => true),
     state: options.state ?? { domain: { id: 'dom-1' }, user: { id: 'u-1' } }
   })
 

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

@@ -1,48 +1,96 @@
 /*
  * What this guards: a registered tool is asked the same question its GraphQL door asks.
  *
- * The tool declares `{ category, privilege }`; `@privilege` on the door runs `checkPermission`
+ * The tool names the door; AUTH's field table says what that door declares; `checkPermission` runs
  * with the request's user, domain, address safety and prohibited list. If this passed fewer of
  * those — say, dropped `unsafeIP` — the tool would be a softer way into the same door.
+ *
+ * `checkPermission` itself is fixed by auth-base's own tests (`permission-gate.test.ts`), including
+ * the two cases below: a domain owner passes a role-less door from a safe address, and from an
+ * unsafe one ownership counts for nothing and the role decides. What this file fixes is that the
+ * tool gate hands that function everything it needs to answer either way.
  */
 const mockCheckPermission = jest.fn()
-jest.mock('@things-factory/auth-base', () => ({ checkPermission: (...a: any[]) => mockCheckPermission(...a) }))
+const mockPrivilegeOfField = jest.fn()
+jest.mock('@things-factory/auth-base', () => ({
+  checkPermission: (...a: any[]) => mockCheckPermission(...a),
+  privilegeOfField: (...a: any[]) => mockPrivilegeOfField(...a)
+}))
 
 import { toolAccessFor } from './tool-access'
 
 const state = {
   domain: { id: 'dom-1' },
   user: { id: 'u-1' },
-  unsafeIP: true,
+  unsafeIP: false,
   prohibitedPrivileges: [{ category: 'board-import', privilege: 'mutation' }]
 }
 
-beforeEach(() => mockCheckPermission.mockReset())
+/** What plant's five doors declare — `@privilege(category, privilege, domainOwnerGranted: true)`. */
+const OWNER_GRANTED = { category: 'job-order', privilege: 'query', owner: true }
+
+beforeEach(() => {
+  mockCheckPermission.mockReset()
+  mockPrivilegeOfField.mockReset()
+  mockPrivilegeOfField.mockReturnValue({ known: true, gate: OWNER_GRANTED })
+})
 
-it('★ asks checkPermission with the declared privilege and everything the door would pass', async () => {
+it('★ asks checkPermission with the door’s own declaration and everything the door would pass', async () => {
   mockCheckPermission.mockResolvedValue(true)
 
-  const allowed = await toolAccessFor({ state })({ category: 'board-import', privilege: 'mutation', owner: true })
+  const allowed = await toolAccessFor({ state })('Query.jobOrders')
 
   expect(allowed).toBe(true)
-  expect(mockCheckPermission).toHaveBeenCalledWith(
-    { category: 'board-import', privilege: 'mutation', owner: true, super: undefined },
-    state.user,
-    state.domain,
-    true,
-    state.prohibitedPrivileges
-  )
+  expect(mockPrivilegeOfField).toHaveBeenCalledWith('Query', 'jobOrders')
+  expect(mockCheckPermission).toHaveBeenCalledWith(OWNER_GRANTED, state.user, state.domain, false, state.prohibitedPrivileges)
+})
+
+/*
+ * Plant's five doors are all `domainOwnerGranted: true`, so moving the gate onto the doors opens
+ * those five tools to a domain owner holding no privilege row. That is the right answer — the owner
+ * already sees the same numbers on the screen — and it is right only because the address travels
+ * with it. From an unsafe address ownership counts for nothing and the role decides.
+ */
+it('★ the owner-granted door gets the address too, so the answer can differ by where the caller sits', async () => {
+  mockCheckPermission.mockResolvedValue(true)
+  await toolAccessFor({ state })('Query.jobOrders')
+  expect(mockCheckPermission).toHaveBeenLastCalledWith(OWNER_GRANTED, state.user, state.domain, false, state.prohibitedPrivileges)
+
+  /* The same owner, the same door, an unsafe address: auth is asked again with that fact. */
+  mockCheckPermission.mockResolvedValue(false)
+  const fromUnsafe = await toolAccessFor({ state: { ...state, unsafeIP: true } })('Query.jobOrders')
+
+  expect(fromUnsafe).toBe(false)
+  expect(mockCheckPermission).toHaveBeenLastCalledWith(OWNER_GRANTED, state.user, state.domain, true, state.prohibitedPrivileges)
 })
 
 it('a refusal is a refusal', async () => {
   mockCheckPermission.mockResolvedValue(false)
-  expect(await toolAccessFor({ state })({ category: 'board-import', privilege: 'query' })).toBe(false)
+  expect(await toolAccessFor({ state })('Query.jobOrders')).toBe(false)
+})
+
+it('★ a door with no declaration of its own opens as far as that door opens — auth is not asked', async () => {
+  mockPrivilegeOfField.mockReturnValue({ known: true, gate: null })
+
+  expect(await toolAccessFor({ state })('Query.twinReplay')).toBe(true)
+  expect(mockCheckPermission).not.toHaveBeenCalled()
+})
+
+it('★ a door the schema does not have is closed, not open — a typo hides a tool, it does not free it', async () => {
+  mockPrivilegeOfField.mockReturnValue({ known: false })
+
+  expect(await toolAccessFor({ state })('Query.twinRepaly')).toBe(false)
+  expect(mockCheckPermission).not.toHaveBeenCalled()
+})
+
+it('a door name that is not a root field passes nobody', async () => {
+  expect(await toolAccessFor({ state })('jobOrders')).toBe(false)
+  expect(mockPrivilegeOfField).not.toHaveBeenCalled()
 })
 
-it('★ a request with no user or no domain holds no privilege, and auth is not asked', async () => {
-  const privilege = { category: 'board-import', privilege: 'query' }
-  expect(await toolAccessFor({ state: { domain: state.domain } })(privilege)).toBe(false)
-  expect(await toolAccessFor({ state: { user: state.user } })(privilege)).toBe(false)
-  expect(await toolAccessFor(undefined)(privilege)).toBe(false)
+it('★ a request with no user or no domain passes no door, and auth is not asked', async () => {
+  expect(await toolAccessFor({ state: { domain: state.domain } })('Query.jobOrders')).toBe(false)
+  expect(await toolAccessFor({ state: { user: state.user } })('Query.jobOrders')).toBe(false)
+  expect(await toolAccessFor(undefined)('Query.jobOrders')).toBe(false)
   expect(mockCheckPermission).not.toHaveBeenCalled()
 })

package/server/service/tool-access.ts

@@ -2,26 +2,35 @@
  * Who may use a registered tool — the request's answer to `ToolAccessCheck`.
  *
  * `ai-client-base` decides *which* tools a conversation may use but does not know auth, so the
- * conversation doors hand it this. A tool declares the same `{ category, privilege }` its GraphQL
- * door uses (A1, 2026-09-17), and this asks exactly what `@privilege` on that door would ask: the
- * same `checkPermission`, with the request's user, domain, address safety and prohibited list.
- * Asking anything looser here would make the tool a second, softer way into that door.
+ * conversation doors hand it this. A tool names the GraphQL doors it reaches (ADR-0071 decision 2);
+ * this resolves each one against AUTH's field table (`privilegeOfField`, ADR-0072 decision 5) and
+ * asks `checkPermission` exactly what `@privilege` on that field asks — the same user, domain,
+ * address safety and prohibited list. Asking anything looser here would make the tool a second,
+ * softer way into that door.
+ *
+ * **The declaration is the door's, and it is read, not copied.** Until 2026-09-18 a tool carried its
+ * own `{ category, privilege }` and this asked that copy. A copy drifts from the door it mirrors and
+ * the looser of the two wins; the table removed the need for one.
+ *
+ * The three answers of the table are read exactly as the reader's gate reads them (`door-access.ts`)
+ * — an unknown field closes, a field with no declaration opens as far as that field opens.
  */
-import { checkPermission } from '@things-factory/auth-base'
-import type { ToolAccessCheck, ToolPrivilege } from '@things-factory/ai-client-base'
+import { checkPermission, privilegeOfField } from '@things-factory/auth-base'
+import type { ToolAccessCheck } from '@things-factory/ai-client-base'
+
+import { doorCheck } from './chat-message/door-access.js'
 
 export function toolAccessFor(context: { state?: any } | undefined): ToolAccessCheck {
   const { domain, user, unsafeIP, prohibitedPrivileges } = context?.state ?? {}
 
-  return async (privilege: ToolPrivilege) => {
-    /* No caller, no answer — a request without a user or domain holds no privilege. */
+  const passes = doorCheck({
+    lookup: privilegeOfField,
+    permits: gate => checkPermission(gate as any, user, domain, unsafeIP, prohibitedPrivileges)
+  })
+
+  return async (door: string) => {
+    /* No caller, no answer — a request without a user or domain passes no door. */
     if (!user || !domain) return false
-    return !!(await checkPermission(
-      { category: privilege.category, privilege: privilege.privilege, owner: privilege.owner, super: privilege.super },
-      user,
-      domain,
-      unsafeIP,
-      prohibitedPrivileges
-    ))
+    return await passes(door)
   }
 }

package/server/tool-registry-boot-report.ts

@@ -1,14 +1,14 @@
 /*
- * At boot, say what registered but is not yet what the contracts require — tools with no privilege
- * (A1 stage one) and modes offering `/` sentences their tools cannot answer (ADR-0058 decision 3).
+ * At boot, say what registered but is not yet what the contracts require — tools that named no doors
+ * (ADR-0071 decision 2) and modes offering `/` sentences their tools cannot answer (ADR-0058
+ * decision 3).
  *
  * One window, because it is one question: what state is this deployment's AI in (standard A7-a).
  *
- * Registration no longer refuses a tool that changes something without declaring its privilege —
- * refusing would stop apps whose tools predate the field. The registry records each omission as a
- * code instead. This prints that list once, after every module has registered, grouped by code,
- * so the person starting the server sees which tools still need a declaration. When the list is
- * empty across the apps, registration becomes a refusal and this report goes away.
+ * A tool that names no doors still registers; refusing at registration would stop a whole app from
+ * booting over one omission. It is the **gate** that refuses it, tool by tool — such a tool is
+ * offered to no conversation (`resolveToolScope`). So this list is not a soft warning about
+ * something that still works: it names the tools that are not working, and why.
  */
 import { logger } from '@things-factory/env'
 import { getToolRegistryWarnings, type ToolRegistryWarning } from '@things-factory/ai-client-base'
@@ -22,8 +22,7 @@ export function formatToolRegistryWarnings(warnings: ReadonlyArray<ToolRegistryW
   for (const warning of warnings) {
     const tools = byCode.get(warning.code) ?? []
     /* 문 이름이 있으면 함께 적는다 — 「어느 문이 아직 선언이 없나」가 다음에 할 일이다. */
-    const doors = warning.params.doors?.length ? ` → ${warning.params.doors.join(' + ')}` : ''
-    tools.push(`${warning.params.category}/${warning.params.tool}(${warning.params.kind})${doors}`)
+    tools.push(`${warning.params.category}/${warning.params.tool}(${warning.params.kind})`)
     byCode.set(warning.code, tools)
   }
   return [...byCode].map(([code, tools]) => `[ai-assistant] ${code} ×${tools.length}: ${tools.join(', ')}`)