@things-factory/ai-assistant 10.1.25 → 10.1.26

package/docs/session-controller.md

@@ -41,7 +41,7 @@ Shared chat accepts synchronous `contextProvider(): {systemPrompt?, hostContext?
 
 `autoAskRequestId` distinguishes repeated identical user requests; generate it per user submission, not per render. Without it, legacy text-based deduplication remains.
 
-`board-edit-patch` and `board-action-execute` include local `detail.requestBase = {version: 1, sessionId, hostContext, modelFingerprint}`. `assistantModelFingerprint` returns a deterministic JSON signature, not a security hash. Undefined models have no signature. Hosts must validate target identity and compare the current model signature before applying a proposal. This metadata is not persisted into restored history; missing metadata is not proof that a historical proposal is safe. The framework captures the evidence but does not implement product-specific application guards.
+`scene-edit-patch` and `scene-action-execute` include local `detail.requestBase = {version: 1, sessionId, hostContext, modelFingerprint}`. `assistantModelFingerprint` returns a deterministic JSON signature, not a security hash. Undefined models have no signature. Hosts must validate target identity and compare the current model signature before applying a proposal. This metadata is not persisted into restored history; missing metadata is not proof that a historical proposal is safe. The framework captures the evidence but does not implement product-specific application guards.
 
 Figure browser verification after toolbar migration: selected old session, reset to session 3, observed sessions 1 and 2 retained; screenshot confirmed aligned controls. Models were not edited. Plant runtime validation is owned by its development task. Legacy Board forwarding has source-contract coverage, not full Board browser coverage.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/ai-assistant",
-  "version": "10.1.25",
+  "version": "10.1.26",
   "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.25",
-    "@things-factory/auth-base": "^10.1.24",
+    "@things-factory/ai-client-base": "^10.1.26",
+    "@things-factory/auth-base": "^10.1.26",
     "@things-factory/env": "^10.1.20",
-    "@things-factory/shell": "^10.1.20",
+    "@things-factory/shell": "^10.1.26",
     "dompurify": "^3.0.0",
     "graphql-scalars": "^1.22.0",
     "graphql-tag": "^2.12.6",
@@ -43,5 +43,6 @@
   "devDependencies": {
     "copyfiles": "^2.4.1",
     "rimraf": "^5.0.0"
-  }
+  },
+  "gitHead": "151bda14d899442c6846532ddded1e2bfe23a2f5"
 }

package/server/index.ts

@@ -26,3 +26,4 @@
  * 설계 정본은 `things-factory/docs/design/ai-modules.md`.
  */
 export * from './service/index.js'
+import './tool-registry-boot-report.js'

package/server/service/assistant-chat-resolver.ts

@@ -37,6 +37,7 @@ import { buildLlmHistory } from './chat-message/llm-history.js'
 import { publishChatMessage } from './chat-message/chat-message-publish.js'
 import { publishSessionActivity } from './chat-session/session-activity-publish.js'
 import { activityPatch, autoSessionName } from './chat-session/session-inbox.js'
+import { toolAccessFor } from './tool-access.js'
 
 /**
  * How many stored messages reach the model.
@@ -79,7 +80,7 @@ class AssistantChatInput {
   @Field(() => [String], {
     nullable: true,
     description:
-      'Registered tool categories this conversation may use (registerToolCategory names, e.g. ["figure-authoring"]). Omit to allow every registered category. An empty list allows none — a plain conversation.'
+      'Registered tool categories this conversation may use (registerToolCategory names, e.g. ["figure-authoring"]). Omitted or empty allows none — a plain conversation. A tool that declares a privilege is offered only to a caller who holds it.'
   })
   toolCategories?: string[]
 
@@ -292,6 +293,7 @@ export class AssistantChatResolver {
       messages: conversation as any,
       systemPrompt: input.systemPrompt,
       toolCategories: input.toolCategories,
+      toolAccess: toolAccessFor(context),
       hostContext: input.hostContext,
       state: context.state,
       model: input.model,

package/server/service/index.ts

@@ -9,6 +9,7 @@ import { entities as ChatSessionParticipantEntities } from './chat-session-parti
 export * from './types.js'
 export * from './chat-session-resolver.js'
 export * from './assistant-chat-resolver.js'
+export * from './tool-access.js'
 export * from './subscribe-auth.js'
 /* 앵커 순수 로직 — 호스트가 앵커 종류를 참조한다(리졸버는 데코레이터 때문에 무겁다). */
 export * from './chat-session/session-anchor.js'

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

@@ -0,0 +1,48 @@
+/*
+ * 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`
+ * 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.
+ */
+const mockCheckPermission = jest.fn()
+jest.mock('@things-factory/auth-base', () => ({ checkPermission: (...a: any[]) => mockCheckPermission(...a) }))
+
+import { toolAccessFor } from './tool-access'
+
+const state = {
+  domain: { id: 'dom-1' },
+  user: { id: 'u-1' },
+  unsafeIP: true,
+  prohibitedPrivileges: [{ category: 'board-import', privilege: 'mutation' }]
+}
+
+beforeEach(() => mockCheckPermission.mockReset())
+
+it('★ asks checkPermission with the declared privilege and everything the door would pass', async () => {
+  mockCheckPermission.mockResolvedValue(true)
+
+  const allowed = await toolAccessFor({ state })({ category: 'board-import', privilege: 'mutation', owner: true })
+
+  expect(allowed).toBe(true)
+  expect(mockCheckPermission).toHaveBeenCalledWith(
+    { category: 'board-import', privilege: 'mutation', owner: true, super: undefined },
+    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)
+})
+
+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)
+  expect(mockCheckPermission).not.toHaveBeenCalled()
+})

package/server/service/tool-access.ts

@@ -0,0 +1,27 @@
+/*
+ * 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.
+ */
+import { checkPermission } from '@things-factory/auth-base'
+import type { ToolAccessCheck, ToolPrivilege } from '@things-factory/ai-client-base'
+
+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. */
+    if (!user || !domain) return false
+    return !!(await checkPermission(
+      { category: privilege.category, privilege: privilege.privilege, owner: privilege.owner, super: privilege.super },
+      user,
+      domain,
+      unsafeIP,
+      prohibitedPrivileges
+    ))
+  }
+}

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

@@ -0,0 +1,18 @@
+jest.mock('@things-factory/env', () => ({ logger: { warn: jest.fn() } }))
+
+import { formatToolRegistryWarnings } from './tool-registry-boot-report'
+
+it('★ groups the recorded omissions by code and names every tool', () => {
+  const lines = formatToolRegistryWarnings([
+    { code: 'tool-privilege-undeclared', params: { category: 'twin-authoring', tool: 'bindTwinEntity', kind: 'write' }, message: '' },
+    { code: 'tool-privilege-undeclared', params: { category: 'x-ops', tool: 'runThing', kind: 'external' }, message: '' }
+  ])
+
+  expect(lines).toEqual([
+    '[ai-assistant] tool-privilege-undeclared ×2: twin-authoring/bindTwinEntity(write), x-ops/runThing(external)'
+  ])
+})
+
+it('says nothing when every tool is declared', () => {
+  expect(formatToolRegistryWarnings([])).toEqual([])
+})

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

@@ -0,0 +1,26 @@
+/*
+ * At boot, say which registered tools are not yet what the tool contract requires (A1 stage one).
+ *
+ * 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.
+ */
+import { logger } from '@things-factory/env'
+import { getToolRegistryWarnings, type ToolRegistryWarning } from '@things-factory/ai-client-base'
+
+/** One line per code: the code, how many, and which tools. Empty when there is nothing to report. */
+export function formatToolRegistryWarnings(warnings: ReadonlyArray<ToolRegistryWarning>): string[] {
+  const byCode = new Map<string, string[]>()
+  for (const warning of warnings) {
+    const tools = byCode.get(warning.code) ?? []
+    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(', ')}`)
+}
+
+process.on('bootstrap-module-start' as any, () => {
+  for (const line of formatToolRegistryWarnings(getToolRegistryWarnings())) logger.warn(line)
+})

package/test/assistant-request-context.test.ts

@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict'
-import { test } from 'node:test'
 import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
 import { assistantAutoAskKey, assistantModelFingerprint, assistantRecentSessions } from '../client/utils/assistant-request-context.ts'
 
 test('model signature ignores object key order but detects nested edits and array order', () => {
@@ -21,7 +21,7 @@ test('recent tabs retain the selected older conversation without mutating the in
   assert.deepEqual(assistantRecentSessions([], '', 5), [])
 })
 test('send captures current context before optimistic input and attaches request base to edit events', () => {
-  const chat = readFileSync(new URL('../client/components/assistant-chat.ts', import.meta.url), 'utf8')
+  const chat = readFileSync(join(__dirname, '../client/components/assistant-chat.ts'), 'utf8')
   const send = chat.slice(chat.indexOf('private async send()'))
   assert.ok(send.indexOf('this.contextProvider?.()') < send.indexOf('// optimistic'))
   assert.match(send, /modelFingerprint: assistantModelFingerprint\(liveBoard\)/)

package/test/assistant-session-controller.test.ts

@@ -1,5 +1,4 @@
 import assert from 'node:assert/strict'
-import { test } from 'node:test'
 import { AssistantSessionController, type AssistantSession, type AssistantSessionTarget } from '../client/utils/assistant-session-controller.ts'
 
 const target = (id: string, scope = 'user:domain'): AssistantSessionTarget => ({ scope, anchorType: 'figure', anchorId: id })

package/test/assistant-session-toolbar.test.ts

@@ -1,7 +1,7 @@
 import assert from 'node:assert/strict'
 import { readFileSync } from 'node:fs'
-import { test } from 'node:test'
-const read = (file: string) => readFileSync(new URL(file, import.meta.url), 'utf8')
+import { join } from 'node:path'
+const read = (file: string) => readFileSync(join(__dirname, file), 'utf8')
 const toolbar = read('../client/components/assistant-session-toolbar.ts')
 test('toolbar emits domain-neutral intent and never calls persistence APIs', () => {
   for (const event of ['assistant-session-select', 'assistant-session-reset', 'assistant-session-retry']) assert.ok(toolbar.includes(event))