@things-factory/board-ai 10.1.46 → 10.1.47

package/dist-server/service/binding-tools.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 { type ToolCategory } from '@things-factory/ai-client-base';
+export declare const boardBindingToolsCategory: ToolCategory;

package/dist-server/service/binding-tools.js

@@ -0,0 +1,269 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.boardBindingToolsCategory = void 0;
+/**
+ * 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.
+ */
+const ai_client_base_1 = require("@things-factory/ai-client-base");
+const component_tree_1 = require("./component-tree");
+const RULES = ['value', 'map', 'range', 'eval'];
+/* The write builder receives the board's top-level components; wrap them so the tree helpers work. */
+const boardOf = (components) => ({ components: [...(components ?? [])] });
+function idFor(component, refid, taken) {
+    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, index, idToRefids) {
+    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 = {
+    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, context) => {
+        const flat = (0, component_tree_1.collectAllComponents)(context?.board);
+        const idToRefids = new Map();
+        for (const f of flat) {
+            const id = f.component?.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?.mappings) && f.component.mappings.length > 0 : f.refid === only))
+            .map(f => {
+            const c = f.component;
+            const mappings = 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 = {
+    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, context) => {
+        const errors = [];
+        const board = boardOf(context?.components);
+        const sourceRefid = args?.sourceRefid;
+        const property = typeof args?.property === 'string' ? args.property.trim() : '';
+        const rule = RULES.includes(args?.rule) ? args.rule : 'value';
+        const source = typeof sourceRefid === 'number' ? (0, component_tree_1.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 = 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 = [];
+        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 = (0, component_tree_1.findComponentByRefid)(board, args.targetRefid)?.component;
+            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((0, component_tree_1.collectAllComponents)(board)
+                    .map(f => f.component?.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 = {
+            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 = Array.isArray(source.mappings) ? source.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 = {
+    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, context) => {
+        const board = boardOf(context?.components);
+        const source = typeof args?.sourceRefid === 'number' ? (0, component_tree_1.findComponentByRefid)(board, args.sourceRefid)?.component : undefined;
+        if (!source)
+            return { ops: [], errors: [`sourceRefid ${args?.sourceRefid} is not a component on this board.`] };
+        const existing = 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) } }] };
+    }
+};
+exports.boardBindingToolsCategory = {
+    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.
+(0, ai_client_base_1.registerToolCategory)(exports.boardBindingToolsCategory);
+//# sourceMappingURL=binding-tools.js.map

package/dist-server/service/binding-tools.js.map

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

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

@@ -7,6 +7,10 @@ declare class BoardAIMentionPickInput {
     token: string;
     refid: number;
 }
+export declare class BoardAIModeInput {
+    kind: string;
+    target?: string;
+}
 declare class BoardAIChatInput {
     sessionId?: string;
     messages: BoardAILLMMessageInput[];
@@ -14,6 +18,7 @@ declare class BoardAIChatInput {
     scopes?: string[];
     hostContext?: any;
     truncateAfterMessageId?: string;
+    mode?: BoardAIModeInput;
     toolCategories?: string[];
     boardTools?: boolean;
     requireGroundingTools?: boolean;

package/dist-server/service/board-ai-resolver.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BoardAIChatResolver = void 0;
+exports.BoardAIChatResolver = exports.BoardAIModeInput = void 0;
 const tslib_1 = require("tslib");
 /**
  * GraphQL resolver — AI 주도 보드 모델링 (chat).
@@ -22,6 +22,7 @@ const ai_assistant_2 = require("@things-factory/ai-assistant");
 const ai_assistant_3 = require("@things-factory/ai-assistant");
 const ai_assistant_4 = require("@things-factory/ai-assistant");
 const ai_assistant_5 = require("@things-factory/ai-assistant");
+const ai_assistant_6 = require("@things-factory/ai-assistant");
 /**
  * 모델에 넘길 최근 메시지 수 상한.
  *
@@ -37,13 +38,13 @@ const LLM_HISTORY_MAX_TURNS = 40;
  * 상한을 넘긴 뒤 매 턴 요약을 만들면 대화마다 LLM 호출이 두 번씩 붙는다. 10 개씩 모아 접는다.
  */
 const LLM_SUMMARY_THRESHOLD = 10;
-const ai_assistant_6 = require("@things-factory/ai-assistant");
 const ai_assistant_7 = require("@things-factory/ai-assistant");
 const ai_assistant_8 = require("@things-factory/ai-assistant");
+const ai_assistant_9 = require("@things-factory/ai-assistant");
 const patch_entry_js_1 = require("./patch-entry/patch-entry.js");
 const board_patch_subscription_js_1 = require("./patch-entry/board-patch-subscription.js");
-const ai_assistant_9 = require("@things-factory/ai-assistant");
 const ai_assistant_10 = require("@things-factory/ai-assistant");
+const ai_assistant_11 = require("@things-factory/ai-assistant");
 const mention_marker_js_1 = require("./mention-marker.js");
 let BoardAILLMMessageInput = class BoardAILLMMessageInput {
 };
@@ -73,6 +74,20 @@ tslib_1.__decorate([
 BoardAIMentionPickInput = tslib_1.__decorate([
     (0, type_graphql_1.InputType)()
 ], BoardAIMentionPickInput);
+let BoardAIModeInput = class BoardAIModeInput {
+};
+exports.BoardAIModeInput = BoardAIModeInput;
+tslib_1.__decorate([
+    (0, type_graphql_1.Field)({ description: 'A mode kind the app server registered, e.g. "board.modeller".' }),
+    tslib_1.__metadata("design:type", String)
+], BoardAIModeInput.prototype, "kind", void 0);
+tslib_1.__decorate([
+    (0, type_graphql_1.Field)({ nullable: true, description: 'What the conversation is about, e.g. the board id.' }),
+    tslib_1.__metadata("design:type", String)
+], BoardAIModeInput.prototype, "target", void 0);
+exports.BoardAIModeInput = BoardAIModeInput = tslib_1.__decorate([
+    (0, type_graphql_1.InputType)({ description: 'Which registered conversation this board chat is, and what it is about.' })
+], BoardAIModeInput);
 let BoardAIChatInput = class BoardAIChatInput {
 };
 tslib_1.__decorate([
@@ -113,6 +128,13 @@ tslib_1.__decorate([
     }),
     tslib_1.__metadata("design:type", String)
 ], BoardAIChatInput.prototype, "truncateAfterMessageId", void 0);
+tslib_1.__decorate([
+    (0, type_graphql_1.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.'
+    }),
+    tslib_1.__metadata("design:type", BoardAIModeInput)
+], BoardAIChatInput.prototype, "mode", void 0);
 tslib_1.__decorate([
     (0, type_graphql_1.Field)(() => [String], {
         nullable: true,
@@ -285,9 +307,17 @@ let BoardAIChatResolver = class BoardAIChatResolver {
         if (!base) {
             throw new Error('No AI client configured. Set config.aiClient = { provider: "anthropic" | "gemini", model, apiKey } or call setDefaultAIClient(...).');
         }
+        /*
+         * 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 = input.mode?.kind
+            ? (0, ai_assistant_2.resolveModeSettings)({ kind: input.mode.kind, target: input.mode.target }, (0, ai_assistant_2.requestTranslator)(context))
+            : undefined;
         const { domain, user } = context.state;
         const sessionRepo = (0, shell_1.getRepository)(ai_assistant_1.ChatSession);
-        const messageRepo = (0, shell_1.getRepository)(ai_assistant_2.ChatMessage);
+        const messageRepo = (0, shell_1.getRepository)(ai_assistant_3.ChatMessage);
         const patchRepo = (0, shell_1.getRepository)(patch_entry_js_1.PatchEntry);
         // ── Phase A: LLM 호출 전 짧은 DB 쓰기 ─────────────────────────
         let session;
@@ -323,16 +353,16 @@ let BoardAIChatResolver = class BoardAIChatResolver {
              * 훨씬 유용하다. 사용자가 직접 바꾼 이름은 여기서 건드리지 않는다(이름이 있으면 그대로).
              * best-effort: 실패해도 대화를 막지 않는다(목록 정렬이 한 칸 늦을 뿐). */
             try {
-                const patch = (0, ai_assistant_6.activityPatch)(enriched);
+                const patch = (0, ai_assistant_7.activityPatch)(enriched);
                 if (!session.name)
-                    patch.name = (0, ai_assistant_6.autoSessionName)(enriched);
+                    patch.name = (0, ai_assistant_7.autoSessionName)(enriched);
                 await sessionRepo.update(session.id, patch);
             }
             catch {
                 /* noop */
             }
             /* 내가 참여한 세션 활동 방송 — 창을 닫아 둔 다른 참여자의 배지·목록을 위해. */
-            (0, ai_assistant_7.publishSessionActivity)({
+            (0, ai_assistant_8.publishSessionActivity)({
                 domainId: domain.id,
                 sessionId: session.id,
                 kind: 'message',
@@ -343,7 +373,7 @@ let BoardAIChatResolver = class BoardAIChatResolver {
             });
             // C4: 사용자 메시지를 같은 세션 구독자에게 방송 (그룹챗 실시간). best-effort.
             // 자기 발신 에코는 클라이언트가 message.id 로 dedup.
-            (0, ai_assistant_8.publishChatMessage)({ domainId: domain.id, sessionId: session.id, message: saved });
+            (0, ai_assistant_9.publishChatMessage)({ domainId: domain.id, sessionId: session.id, message: saved });
             // C4: @user 멘션 → 세션 참여자(member) 자동 등록 (초대). best-effort — 실패해도 chat 흐름 무영향.
             // enriched content 의 {userId:UUID} 마커에서 추출 → 기존 참여자/자기 제외한 신규만 member 로 등록.
             try {
@@ -375,11 +405,11 @@ let BoardAIChatResolver = class BoardAIChatResolver {
                 order: { createdAt: 'ASC', id: 'ASC' }
             });
             /* 이번 턴에 상한 밖으로 밀려난 것이 있는가 — 화면이 "대화가 길어졌다" 를 알릴 근거(사실만). */
-            const capped = (0, ai_assistant_4.splitByCap)(rows.map(row => ({ id: row.id, role: row.role, content: row.content ?? '' })), LLM_HISTORY_MAX_TURNS);
+            const capped = (0, ai_assistant_5.splitByCap)(rows.map(row => ({ id: row.id, role: row.role, content: row.content ?? '' })), LLM_HISTORY_MAX_TURNS);
             if (capped.dropped.length > 0) {
                 historyFolded = { omitted: capped.dropped.length, summarized: !!session.lastSummary };
             }
-            llmMessages = (0, ai_assistant_3.buildLlmHistory)(rows.map(row => ({
+            llmMessages = (0, ai_assistant_4.buildLlmHistory)(rows.map(row => ({
                 id: row.id,
                 role: row.role,
                 content: (0, mention_marker_js_1.stripMentionRefids)(row.content ?? ''),
@@ -405,18 +435,19 @@ let BoardAIChatResolver = 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 (0, board_tool_rights_js_1.effectiveBoardTools)(input.boardTools, context),
-            requireGroundingTools: input.requireGroundingTools ?? undefined,
+            requireGroundingTools: modeSettings ? modeSettings.requireToolOnFirstTurn : input.requireGroundingTools ?? undefined,
             knownTypes: input.knownTypes,
             categories: input.categories,
             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 로만 흘림.
@@ -465,9 +496,9 @@ let BoardAIChatResolver = class BoardAIChatResolver {
             });
             assistantMessageId = aiMsg.id;
             // C4: AI 응답도 같은 세션 구독자에게 방송 (트리거한 본인 포함 — id dedup). best-effort.
-            (0, ai_assistant_8.publishChatMessage)({ domainId: domain.id, sessionId: session.id, message: aiMsg });
+            (0, ai_assistant_9.publishChatMessage)({ domainId: domain.id, sessionId: session.id, message: aiMsg });
             /* AI 응답도 세션 활동이다 — 이걸 빼면 다른 참여자에게 "새 소식 없음" 으로 보인다. */
-            (0, ai_assistant_7.publishSessionActivity)({
+            (0, ai_assistant_8.publishSessionActivity)({
                 domainId: domain.id,
                 sessionId: session.id,
                 kind: 'message',
@@ -480,7 +511,7 @@ let BoardAIChatResolver = class BoardAIChatResolver {
                 aiClientId: base.id,
                 updater: user,
                 /* AI 응답도 세션 활동이다 — 이걸 빼면 다른 참여자에게 "새 소식 없음"으로 보인다. */
-                ...(0, ai_assistant_6.activityPatch)(enrichedReply)
+                ...(0, ai_assistant_7.activityPatch)(enrichedReply)
             });
             /* ── Phase D: 이력 요약 접기 ────────────────────────────────────────────
              * 응답을 **돌려준 뒤** 갱신한다 — 사용자 대기 시간에 요약용 LLM 호출을 얹지 않는다.
@@ -533,14 +564,14 @@ let BoardAIChatResolver = class BoardAIChatResolver {
                 senderId: row.creator?.id,
                 senderName: row.creator?.name || row.creator?.username
             }));
-            const { patch } = await (0, ai_assistant_5.foldHistorySummary)({
+            const { patch } = await (0, ai_assistant_6.foldHistorySummary)({
                 rows: history,
                 rowsStartAfterSummary: startsAfterSummary,
                 stored,
                 maxTurns: LLM_HISTORY_MAX_TURNS,
                 threshold: LLM_SUMMARY_THRESHOLD,
                 summarize: content => client.chat([{ role: 'user', content }], {
-                    systemPrompt: (0, ai_assistant_4.summaryInstruction)(),
+                    systemPrompt: (0, ai_assistant_5.summaryInstruction)(),
                     maxTokens: 700,
                     /* 요약은 창작이 아니다 — 흔들림을 줄인다. */
                     temperature: 0
@@ -573,7 +604,7 @@ let BoardAIChatResolver = class BoardAIChatResolver {
      * id 로 가른다(원래 정렬이 이미 그 규약이다).
      */
     async _historyForFold(sessionId, stored) {
-        const repo = (0, shell_1.getRepository)(ai_assistant_2.ChatMessage);
+        const repo = (0, shell_1.getRepository)(ai_assistant_3.ChatMessage);
         const session = { id: sessionId };
         const order = { createdAt: 'ASC', id: 'ASC' };
         const relations = { creator: true };
@@ -604,7 +635,7 @@ let BoardAIChatResolver = class BoardAIChatResolver {
         const mentioned = (0, mention_marker_js_1.extractMentionUserIds)(content);
         if (mentioned.length === 0)
             return;
-        const repo = (0, shell_1.getRepository)(ai_assistant_9.ChatSessionParticipant);
+        const repo = (0, shell_1.getRepository)(ai_assistant_10.ChatSessionParticipant);
         const existing = await repo.find({
             where: { session: { id: sessionId }, domain: { id: domainId } },
             withDeleted: true
@@ -639,7 +670,7 @@ let BoardAIChatResolver = class BoardAIChatResolver {
     _notifyInvited(notify, userIds, boardId, inviter) {
         if (typeof notify !== 'function')
             return;
-        const payload = (0, ai_assistant_10.buildInviteNotification)(userIds, boardId, inviter);
+        const payload = (0, ai_assistant_11.buildInviteNotification)(userIds, boardId, inviter);
         if (!payload)
             return;
         Promise.resolve(notify(payload)).catch(() => {