@things-factory/board-ai 10.1.46 → 10.1.47

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/board-ai",
-  "version": "10.1.46",
+  "version": "10.1.47",
   "main": "dist-server/index.js",
   "browser": "dist-client/client/index.js",
   "things-factory": true,
@@ -32,12 +32,12 @@
     "@operato/i18n": "^10.0.0",
     "@operato/scene-ops": "^10.14.1",
     "@operato/styles": "^10.0.0",
-    "@things-factory/ai-assistant": "^10.1.46",
+    "@things-factory/ai-assistant": "^10.1.47",
     "@things-factory/ai-client-base": "^10.1.39",
-    "@things-factory/auth-base": "^10.1.46",
-    "@things-factory/board-import": "^10.1.46",
+    "@things-factory/auth-base": "^10.1.47",
+    "@things-factory/board-import": "^10.1.47",
     "@things-factory/env": "^10.1.20",
-    "@things-factory/shell": "^10.1.46",
+    "@things-factory/shell": "^10.1.47",
     "dompurify": "^3.0.0",
     "graphql-tag": "^2.12.6",
     "lit": "^3.1.2",
@@ -47,5 +47,5 @@
     "copyfiles": "^2.4.1",
     "rimraf": "^5.0.0"
   },
-  "gitHead": "d3467cde550453f3348fed0ed6c79a12a6ba0db4"
+  "gitHead": "185f20d7d9a15715a0ee2757a6a8189ec36cfb9d"
 }

package/server/service/assistant.ts

@@ -179,8 +179,10 @@ export class DefaultBoardAIAssistant implements BoardAIAssistant {
      * 답해, 사용자에게 없는 버튼을 누르라고 안내했다. 규율은 도구를 등록한 쪽이 소유하고 여기서는
      * 모아 붙이기만 한다(도메인 지식이 board-ai 프롬프트로 새지 않는다). */
     const guidance = getCategoryGuidance(options.toolCategories)
+    const surface = (options.surfacePrompt ?? '').trim()
     const systemPrompt =
       this.buildSystemPromptForTools(knownTypes, categories, schemas) +
+      (surface ? `\n\n==== THIS SURFACE (declared by the app) ====\n${surface}` : '') +
       (guidance.length ? `\n\n==== TOOL USE RULES (from the tools exposed to this conversation) ====\n${guidance.join('\n')}` : '')
 
     const selectedRefids = (options.selectedRefids ?? []).filter(

package/server/service/binding-tools.ts

@@ -0,0 +1,293 @@
+/**
+ * Data binding as first-class board tools — `getBindings`, `bindData`, `unbindData`.
+ *
+ * ── Why these exist ──────────────────────────────────────────────────────────
+ * A binding was reachable only through `modifyComponentByRefid` with a raw `mappings` array. The
+ * model had to know the mapping shape, where the mapping lives (on the component that HAS the
+ * data, not on the one that shows it), that a target is a selector, and that a `#id` selector
+ * needs the target to carry an id. It guessed, and a wrong guess is silent: the patch applies,
+ * nothing moves on the board, no error anywhere.
+ *
+ * These tools take refids and plain words and do the bookkeeping here:
+ *   - the mapping is appended to the SOURCE's `mappings` (same target + property replaces);
+ *   - a target given by refid gets an `id` if it has none, and the mapping points at `#id`;
+ *   - the rule's parameter lands where the engine reads it (`mapping.param`).
+ *
+ * The engine side is `things-scene/src/components/data/data.ts` (spreading) and `evaluator.ts`
+ * (value / map / range / eval). The property panel writes the same shape.
+ *
+ * Writes return scene-edit `modify` ops, so they go through the same preview → apply → revert →
+ * save path as every other board edit. Nothing here touches the database.
+ */
+import { registerToolCategory, type ToolCategory, type ToolSpec } from '@things-factory/ai-client-base'
+
+import { collectAllComponents, findComponentByRefid } from './component-tree'
+
+type Rule = 'value' | 'map' | 'range' | 'eval'
+const RULES: Rule[] = ['value', 'map', 'range', 'eval']
+
+interface Mapping {
+  source?: string
+  target?: string
+  property?: string
+  accessor?: string
+  rule?: Rule
+  param?: any
+  partial?: boolean
+  ndnsp?: boolean
+}
+
+/* The write builder receives the board's top-level components; wrap them so the tree helpers work. */
+const boardOf = (components: ReadonlyArray<any> | undefined) => ({ components: [...(components ?? [])] }) as any
+
+function idFor(component: any, refid: number, taken: Set<string>): string {
+  const base =
+    String(component?.type || 'component')
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '') || 'component'
+  let id = `${base}-${refid}`
+  for (let n = 2; taken.has(id); n++) id = `${base}-${refid}-${n}`
+  return id
+}
+
+/** What a mapping means, in the words the model and the person use. */
+function describeMapping(m: Mapping, index: number, idToRefids: Map<string, number[]>) {
+  const target = (m.target || '(self)').trim()
+  const refids = target.startsWith('#') ? idToRefids.get(target.slice(1)) : undefined
+  return {
+    index,
+    target,
+    ...(refids ? { targetRefids: refids } : {}),
+    property: m.property,
+    accessor: m.accessor || undefined,
+    rule: m.rule || 'value',
+    ...(m.param !== undefined ? { param: m.param } : {}),
+    ...(m.partial ? { partial: true } : {}),
+    ...(m.ndnsp ? { ndnsp: true } : {})
+  }
+}
+
+const getBindings: ToolSpec = {
+  kind: 'read',
+  name: 'getBindings',
+  /* Answers from the board the surface sent; nothing behind it to gate. */
+  doors: [],
+  description:
+    'List the data bindings on the board (or on one component). A binding lives on the component that holds the data ' +
+    '(the source) and spreads a value into a property of a target. Returns, per source component: refid, id, type, ' +
+    'whether it holds initial data, and its mappings with target selector, resolved target refids, property, accessor, rule and rule parameter. ' +
+    'Also lists components that already have an id (usable as targets without changes).',
+  schema: {
+    type: 'object',
+    properties: {
+      refid: { type: 'number', description: 'Only this component. Omit for every component that has bindings.' }
+    }
+  },
+  builder: (args: any, context: any) => {
+    const flat = collectAllComponents(context?.board)
+    const idToRefids = new Map<string, number[]>()
+    for (const f of flat) {
+      const id = (f.component as any)?.id
+      if (id && typeof f.refid === 'number') idToRefids.set(id, [...(idToRefids.get(id) ?? []), f.refid])
+    }
+
+    const only = typeof args?.refid === 'number' ? args.refid : undefined
+    const sources = flat
+      .filter(f => (only === undefined ? Array.isArray((f.component as any)?.mappings) && (f.component as any).mappings.length > 0 : f.refid === only))
+      .map(f => {
+        const c: any = f.component
+        const mappings: Mapping[] = Array.isArray(c.mappings) ? c.mappings : []
+        return {
+          refid: f.refid,
+          id: c.id || undefined,
+          type: c.type,
+          hasInitialData: c.data !== undefined && c.data !== null && c.data !== '',
+          mappings: mappings.map((m, i) => describeMapping(m, i, idToRefids))
+        }
+      })
+
+    if (only !== undefined && sources.length === 0) {
+      return { error: `No component with refid ${only} on this board.` }
+    }
+
+    return {
+      sources,
+      componentsWithId: [...idToRefids.entries()].map(([id, refids]) => ({ id, refids }))
+    }
+  }
+}
+
+const bindData: ToolSpec = {
+  kind: 'write',
+  name: 'bindData',
+  /* Proposes an edit the person saves through the board's own door — offer it only to those who can. */
+  doors: ['Mutation.updateBoard'],
+  description:
+    'Bind data from a source component to a property of a target component. Use this for every data binding - never write ' +
+    '`mappings` through modifyComponentByRefid. The binding is stored on the SOURCE (the component that holds or receives the data, ' +
+    'e.g. a data source, or the component itself). Give the target as targetRefid (an id is assigned to it if missing) or as a selector. ' +
+    'rule "value" passes the value through; "map" translates exact values ({"ON":"#2e7d32","OFF":"#c62828","default":"#9e9e9e"}); ' +
+    '"range" maps numeric ranges written "from~to", open ends allowed ({"~50":"green","50~80":"orange","80~":"red"}); ' +
+    '"eval" runs a short expression over `value` - use only when map or range cannot express it. ' +
+    'An existing binding with the same target and property on that source is replaced.',
+  schema: {
+    type: 'object',
+    properties: {
+      sourceRefid: { type: 'number', description: 'Component whose data is spread (where the binding is stored).' },
+      targetRefid: {
+        type: 'number',
+        description: 'Component that receives the value. Omit (or equal to sourceRefid) to bind into the source itself.'
+      },
+      targetSelector: {
+        type: 'string',
+        description: 'Instead of targetRefid: a selector for many targets, e.g. ".alarm" (class), "#line-3" (id), "(self)".'
+      },
+      property: {
+        type: 'string',
+        description: 'Property path on the target, e.g. "value", "text", "fillStyle", "strokeStyle", "hidden", "data", "rotation".'
+      },
+      accessor: {
+        type: 'string',
+        description: 'Path into the source data, e.g. "temperature" or "items[0].qty". Omit to pass the whole data.'
+      },
+      rule: { type: 'string', enum: RULES, description: 'How the value is turned into the property value. Default "value".' },
+      map: { type: 'object', description: 'rule "map": exact value -> result, optional "default".' },
+      range: { type: 'object', description: 'rule "range": "from~to" -> result, open ends allowed, optional "default".' },
+      eval: { type: 'string', description: 'rule "eval": a short JavaScript expression over `value` that returns the property value.' },
+      partial: { type: 'boolean', description: 'Merge an object value into the property instead of replacing it.' },
+      skipEmpty: { type: 'boolean', description: 'Do not spread empty values (null, undefined, "") - keeps the last value.' }
+    },
+    required: ['sourceRefid', 'property']
+  },
+  builder: (args: any, context: any) => {
+    const errors: string[] = []
+    const board = boardOf(context?.components)
+    const sourceRefid = args?.sourceRefid
+    const property = typeof args?.property === 'string' ? args.property.trim() : ''
+    const rule: Rule = RULES.includes(args?.rule) ? args.rule : 'value'
+
+    const source = typeof sourceRefid === 'number' ? findComponentByRefid(board, sourceRefid)?.component : undefined
+    if (!source) errors.push(`sourceRefid ${sourceRefid} is not a component on this board.`)
+    if (!property) errors.push('property is required (the property path on the target, e.g. "value").')
+    if (typeof args?.targetRefid === 'number' && args?.targetSelector) {
+      errors.push('Give either targetRefid or targetSelector, not both.')
+    }
+
+    let param: any = undefined
+    if (rule === 'map') {
+      if (!args?.map || typeof args.map !== 'object' || Array.isArray(args.map)) errors.push('rule "map" needs a "map" object.')
+      else param = args.map
+    } else if (rule === 'range') {
+      if (!args?.range || typeof args.range !== 'object' || Array.isArray(args.range))
+        errors.push('rule "range" needs a "range" object with "from~to" keys.')
+      else {
+        const bad = Object.keys(args.range).filter(k => k !== 'default' && !k.includes('~'))
+        if (bad.length) errors.push(`range keys must be written "from~to" (open ends allowed): ${bad.join(', ')}`)
+        param = args.range
+      }
+    } else if (rule === 'eval') {
+      if (typeof args?.eval !== 'string' || !args.eval.trim()) errors.push('rule "eval" needs an "eval" expression.')
+      else param = args.eval
+    }
+
+    const ops: any[] = []
+    let target = '(self)'
+
+    if (typeof args?.targetSelector === 'string' && args.targetSelector.trim()) {
+      target = args.targetSelector.trim()
+    } else if (typeof args?.targetRefid === 'number' && args.targetRefid !== sourceRefid) {
+      const found = findComponentByRefid(board, args.targetRefid)?.component as any
+      if (!found) {
+        errors.push(`targetRefid ${args.targetRefid} is not a component on this board.`)
+      } else if (found.id) {
+        target = `#${found.id}`
+      } else {
+        const taken = new Set(
+          collectAllComponents(board)
+            .map(f => (f.component as any)?.id)
+            .filter(Boolean)
+        )
+        const id = idFor(found, args.targetRefid, taken)
+        ops.push({ op: 'modify', refid: args.targetRefid, patch: { id } })
+        target = `#${id}`
+      }
+    }
+
+    if (errors.length) return { ops: [], errors }
+
+    const mapping: Mapping = {
+      target,
+      property,
+      rule,
+      ...(typeof args?.accessor === 'string' && args.accessor.trim() ? { accessor: args.accessor.trim() } : {}),
+      ...(param !== undefined ? { param } : {}),
+      ...(args?.partial ? { partial: true } : {}),
+      ...(args?.skipEmpty ? { ndnsp: true } : {})
+    }
+
+    const existing: Mapping[] = Array.isArray((source as any).mappings) ? (source as any).mappings : []
+    const same = existing.findIndex(m => (m?.target || '(self)').trim() === target && (m?.property || '') === property)
+    const mappings = same >= 0 ? existing.map((m, i) => (i === same ? mapping : m)) : [...existing, mapping]
+
+    ops.unshift({ op: 'modify', refid: sourceRefid, patch: { mappings } })
+    return { ops }
+  }
+}
+
+const unbindData: ToolSpec = {
+  kind: 'write',
+  name: 'unbindData',
+  doors: ['Mutation.updateBoard'],
+  description:
+    'Remove a data binding from a source component - by its index (from getBindings) or by target selector and property. ' +
+    'Leaves the target component unchanged.',
+  schema: {
+    type: 'object',
+    properties: {
+      sourceRefid: { type: 'number', description: 'Component the binding is stored on.' },
+      index: { type: 'number', description: 'Mapping index as returned by getBindings.' },
+      target: { type: 'string', description: 'Instead of index: the mapping target selector, e.g. "#gauge-12".' },
+      property: { type: 'string', description: 'Instead of index: the mapping property, with target.' }
+    },
+    required: ['sourceRefid']
+  },
+  builder: (args: any, context: any) => {
+    const board = boardOf(context?.components)
+    const source = typeof args?.sourceRefid === 'number' ? (findComponentByRefid(board, args.sourceRefid)?.component as any) : undefined
+    if (!source) return { ops: [], errors: [`sourceRefid ${args?.sourceRefid} is not a component on this board.`] }
+
+    const existing: Mapping[] = Array.isArray(source.mappings) ? source.mappings : []
+    let at = -1
+    if (typeof args?.index === 'number') at = args.index
+    else if (typeof args?.target === 'string' || typeof args?.property === 'string')
+      at = existing.findIndex(
+        m =>
+          (args.target === undefined || (m?.target || '(self)').trim() === String(args.target).trim()) &&
+          (args.property === undefined || m?.property === args.property)
+      )
+
+    if (at < 0 || at >= existing.length) {
+      return { ops: [], errors: [`No such binding on refid ${args.sourceRefid} (it has ${existing.length}). Call getBindings first.`] }
+    }
+
+    return { ops: [{ op: 'modify', refid: args.sourceRefid, patch: { mappings: existing.filter((_, i) => i !== at) } }] }
+  }
+}
+
+export const boardBindingToolsCategory: ToolCategory = {
+  name: 'board-binding',
+  description: 'Data binding on the open board: read, add, replace and remove mappings.',
+  guidance: [
+    'Data binding rules:',
+    '- For any request to connect, bind, link, drive or "show" data on components, use bindData. Never write `mappings` with modifyComponentByRefid.',
+    '- Call getBindings before changing or explaining bindings, so you speak from what is on the board.',
+    '- A binding is stored on the SOURCE - the component whose data is spread (a data source, or the component itself). Pick the target by refid.',
+    '- Prefer rule "map" for states and "range" for thresholds; use "eval" only when neither can express it.',
+    '- After a bindData or unbindData call, say which source feeds which target property and with what rule. The person reviews and saves; do not say it is saved.'
+  ].join('\n'),
+  specs: [getBindings, bindData, unbindData]
+}
+
+// Registered on load, like board-import's category.
+registerToolCategory(boardBindingToolsCategory)

package/server/service/board-ai-resolver.ts

@@ -18,6 +18,7 @@ import { DefaultBoardAIAssistant } from './assistant.js'
 import { effectiveBoardTools } from './board-tool-rights.js'
 import type { LLMMessage } from './types.js'
 import { ChatSession } from '@things-factory/ai-assistant'
+import { resolveModeSettings, requestTranslator, type ModeSettings } from '@things-factory/ai-assistant'
 import { ChatMessage } from '@things-factory/ai-assistant'
 import { buildLlmHistory } from '@things-factory/ai-assistant'
 import { splitByCap, summaryInstruction } from '@things-factory/ai-assistant'
@@ -75,6 +76,15 @@ class BoardAIMentionPickInput {
   refid: number
 }
 
+@InputType({ description: 'Which registered conversation this board chat is, and what it is about.' })
+export class BoardAIModeInput {
+  @Field({ description: 'A mode kind the app server registered, e.g. "board.modeller".' })
+  kind: string
+
+  @Field({ nullable: true, description: 'What the conversation is about, e.g. the board id.' })
+  target?: string
+}
+
 @InputType()
 class BoardAIChatInput {
   @Field({
@@ -112,6 +122,13 @@ class BoardAIChatInput {
   })
   truncateAfterMessageId?: string
 
+  @Field(() => BoardAIModeInput, {
+    nullable: true,
+    description:
+      'The registered conversation this is (ADR-0061 decision 7). When given, the server takes the persona, tool categories, model and limits from the mode the app registered, and ignores toolCategories / model / temperature / maxTokens / requireGroundingTools sent by the caller. Omit for the older behaviour.'
+  })
+  mode?: BoardAIModeInput
+
   @Field(() => [String], {
     nullable: true,
     description:
@@ -287,6 +304,15 @@ export class BoardAIChatResolver {
       )
     }
 
+    /*
+     * A declared conversation decides its own authority (ADR-0061 decision 7): with a mode, the
+     * categories, model and limits come from what the app server registered, not from the request.
+     * An unknown kind is refused here, before anything is saved, in the person's language.
+     */
+    const modeSettings: ModeSettings | undefined = input.mode?.kind
+      ? resolveModeSettings({ kind: input.mode.kind, target: input.mode.target }, requestTranslator(context))
+      : undefined
+
     const { domain, user } = context.state
     const sessionRepo = getRepository(ChatSession)
     const messageRepo = getRepository(ChatMessage)
@@ -416,18 +442,19 @@ export class BoardAIChatResolver {
     const r = await assistant.chat(llmMessages, input.currentBoard ?? undefined, {
       scopes: input.scopes,
       hostContext: input.hostContext ?? undefined,
-      /* 대화면별 도구 노출 — 미지정이면 현행(전부 허용) 그대로. */
-      toolCategories: input.toolCategories ?? undefined,
+      surfacePrompt: modeSettings?.systemPrompt,
+      /* 대화면별 도구 노출 — 모드가 있으면 서버 선언(빈 목록 = 외부 도구 없음), 없으면 호출자 값(미지정 = 전부). */
+      toolCategories: modeSettings ? modeSettings.toolCategories ?? [] : input.toolCategories ?? undefined,
       boardTools: await effectiveBoardTools(input.boardTools, context),
-      requireGroundingTools: input.requireGroundingTools ?? undefined,
+      requireGroundingTools: modeSettings ? modeSettings.requireToolOnFirstTurn : input.requireGroundingTools ?? undefined,
       knownTypes: input.knownTypes,
       categories: input.categories as ComponentCategory[] | undefined,
       selectedRefids: input.selectedRefids,
       mentionPicks: input.mentions,
       componentSchemas: Array.isArray(input.componentSchemas) ? input.componentSchemas : undefined,
-      model: input.model,
-      temperature: input.temperature ?? undefined,
-      maxTokens: input.maxTokens ?? undefined,
+      model: modeSettings ? modeSettings.model : input.model,
+      temperature: modeSettings ? modeSettings.temperature : input.temperature ?? undefined,
+      maxTokens: modeSettings ? modeSettings.maxTokens : input.maxTokens ?? undefined,
       // 외부 도메인 (board-import 등) 의 read/external tool builder 가 server-side
       // 의존성 (도메인 / 유저 / 트랜잭션) 을 사용할 수 있도록 ResolverContext.state 전달.
       // board-ai 코어 자체는 이 값을 알지 않고 dispatch 단계에서 closure 로만 흘림.

package/server/service/index.ts

@@ -21,6 +21,7 @@ export * from './mention-resolver.js'
 export * from './catalog-resolver.js'
 export * from './board-ai-resolver.js'
 export * from './patch-entry/index.js'
+export * from './binding-tools.js'
 
 /* 세션 계열 엔티티는 `ai-assistant` 가 낸다 — 프레임워크가 의존을 타고 재귀로 모은다. */
 export const entities = [...PatchEntryEntities]

package/server/service/types.ts

@@ -19,6 +19,12 @@ import type { LLMMessage } from '@things-factory/ai-assistant'
 export type { LLMMessage }
 
 export interface ChatOptions {
+  /**
+   * Who the assistant is on this surface — a registered mode's `systemPrompt` (ADR-0061 decision 7).
+   * Added after board-ai's own authoring instructions, which stay: they describe the board document
+   * and its tools, and the mode describes the product and the person's work.
+   */
+  surfacePrompt?: string
   /**
    * 이 대화에 노출할 **외부 도구 카테고리** 화이트리스트(registerToolCategory 이름).
    * 미지정 = 등록된 전부(현행 동작). 성격이 다른 대화면(보드 저작 도크 · 운영 도크)이

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

@@ -10,7 +10,7 @@
  * 이게 silent 데이터 손상을 막는 마지막 능동 방어선. 검증 통과한 args 만 누적
  * → patch 로 변환되므로 깨진 데이터가 영속까지 못 감.
  */
-import type { AIToolCall } from '@things-factory/ai-client-base'
+import { findToolSpec, type AIToolCall } from '@things-factory/ai-client-base'
 import {
   validateComponentPatch,
   validateComponent,
@@ -181,8 +181,21 @@ export function validateWriteToolCall(
     }
 
     // 그 외 — 기존 dispatcher 검증에 위임
-    default:
+    default: {
+      /*
+       * A write tool registered by another category (e.g. board-binding) checks its own arguments
+       * and says what is wrong in `errors`. Its ops were dropped with the errors unread, so the model
+       * heard nothing and told the person the edit was made. Return them as a validation failure.
+       */
+      const spec = findToolSpec(tc.name)
+      if (spec && spec.kind === 'write') {
+        const r: any = (spec.builder as any)(args, { components })
+        if (r && !Array.isArray(r) && Array.isArray(r.errors) && r.errors.length > 0) {
+          return { valid: false, errors: r.errors }
+        }
+      }
       return { valid: true }
+    }
   }
 }