@formio/uag 1.13.2 → 2.0.0-rc.10

package/lib/UAGFormInterface.js

@@ -2,34 +2,92 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UAGFormInterface = void 0;
 const appserver_1 = require("@formio/appserver");
+const formflow_1 = require("./formflow");
+const richText_1 = require("./richText");
 const core_1 = require("@formio/core");
 const lodash_1 = require("lodash");
 const node_html_markdown_1 = require("node-html-markdown");
+const router_1 = require("./agent/router");
+/** Component types a chat cannot collect yet: tables, nested forms, uploads, drawings and the like. */
+const CHAT_UNSUPPORTED = new Set([
+    'datagrid', 'editgrid', 'datatable', 'dynamicWizard', 'tagpad', 'form', 'datamap', 'address',
+    'file', 'signature', 'sketchpad', 'datasource', 'password', 'captcha'
+]);
+/**
+ * The components inside a layout or container flagged with `uag`, which makes
+ * each input inside it one of the task's fields. Panels, fieldsets, wells, tabs
+ * and containers hold theirs in `components`; columns in each column's
+ * `components`; tables in each cell's. Null for a component that holds none.
+ */
+function layoutChildren(component) {
+    const comp = component;
+    if (Array.isArray(comp.components))
+        return comp.components;
+    if (Array.isArray(comp.columns))
+        return comp.columns.flatMap((column) => column?.components || []);
+    if (Array.isArray(comp.rows))
+        return comp.rows.flat().flatMap((cell) => cell?.components || []);
+    return null;
+}
 class UAGFormInterface extends appserver_1.FormInterface {
-    constructor() {
-        super(...arguments);
-        this.uag = null;
+    /**
+     * The form's routes, with its agent operations (`agent/extract`, `agent/decide`,
+     * `agent/generate`, `agent/chat`) beside its submissions: the project's authentication has
+     * already run, and the form is the one of the URL.
+     */
+    async router() {
+        const router = await super.router();
+        const project = this.project;
+        router.use((0, router_1.FormAgentRouter)(project, (0, router_1.agentCredentials)(project)));
+        return router;
+    }
+    /**
+     * Sets the form, deriving its UAG registration and agent fields from it. The form is set again
+     * whenever it loads, and whenever a TTL refresh or a deploy brings a new version, so both are
+     * rebuilt from the form each time rather than added to what an earlier version left.
+     */
+    setForm(form) {
         this.uagFields = {};
+        const result = super.setForm(form);
+        const machineName = result.machineName;
+        this.uag = result.tags?.includes('uag') ? {
+            machineName,
+            name: result.name || result.path || machineName,
+            title: result.title || result.name || machineName,
+            description: result.properties?.description || `A form to submit new ${result.title} records.`
+        } : null;
+        return result;
     }
     setComponent(form, component, path, components, parent, paths) {
         if (form.tags?.includes('uag') && component.properties?.uag) {
-            const persona = component.properties?.uag;
+            const task = component.properties?.uag;
             if (!this.uagFields) {
                 this.uagFields = {};
             }
-            let uagFields = this.uagFields[persona];
+            let uagFields = this.uagFields[task];
             if (!uagFields) {
-                uagFields = { components: {} };
+                uagFields = { task, components: {} };
             }
             if (component.properties?.uagField) {
                 const property = component.properties?.uagField;
-                if (component?.html) {
+                if (property === 'input') {
+                    // An input can be a single field or a nested component; for a
+                    // nested one, every child value under this path is input.
+                    const inputPath = paths?.dataPath || component.key;
+                    uagFields.inputs = [...(uagFields.inputs || []), inputPath];
+                }
+                else if (component?.html) {
                     uagFields[property] = this.htmlToMarkdown(component.html);
                 }
+                if (property === 'criteria') {
+                    const { uag, uagField, ...settings } = component.properties || {};
+                    uagFields.settings = { ...(uagFields.settings || {}), ...settings };
+                }
             }
             else {
-                if (component.components) {
-                    core_1.Utils.eachComponent(component.components, (subComp, subPath) => {
+                const children = layoutChildren(component);
+                if (children) {
+                    core_1.Utils.eachComponent(children, (subComp, subPath) => {
                         subPath = paths?.dataPath ? `${paths.dataPath}.${subPath}` : subPath;
                         const compInfo = this.getComponentInfo(subComp, subPath);
                         compInfo.rule = this.getComponentValueRule(subComp);
@@ -42,7 +100,7 @@ class UAGFormInterface extends appserver_1.FormInterface {
                     uagFields.components[compInfo.path] = compInfo;
                 }
             }
-            this.uagFields[persona] = uagFields;
+            this.uagFields[task] = uagFields;
         }
         return super.setComponent(form, component, path, components, parent, paths);
     }
@@ -72,7 +130,8 @@ class UAGFormInterface extends appserver_1.FormInterface {
         if (component.placeholder) {
             fieldInfo.prompt = component.placeholder;
         }
-        if (component.type === 'select' || component.type === 'selectboxes') {
+        // A radio's options are what its rule tells the agent to choose from.
+        if (component.type === 'select' || component.type === 'selectboxes' || component.type === 'radio') {
             if (component.dataSrc === 'url') {
                 fieldInfo.options = [{ label: '** USE fetch_external_data TOOL **', value: `Call the \`fetch_external_data\` tool with \`field_path\`="${path}" to retrieve available options from the external URL.` }];
             }
@@ -88,10 +147,7 @@ class UAGFormInterface extends appserver_1.FormInterface {
                     fieldInfo.options = [{ label: '', value: 'No options available' }];
                 }
                 else {
-                    fieldInfo.options = values.reduce((acc, v) => {
-                        acc.push({ label: v.label, value: v.value });
-                        return acc;
-                    }, []);
+                    fieldInfo.options = values.map((v) => ({ label: v.label, value: v.value }));
                 }
             }
         }
@@ -114,19 +170,18 @@ class UAGFormInterface extends appserver_1.FormInterface {
             label: parent.label || parent.key,
             data_path: parent_path
         };
-        if (parent.tree ||
-            parent.type === 'datagrid' ||
-            parent.type === 'editgrid') {
-            parentInfo.isTable = true;
-            return parentInfo;
-        }
+        // The type comes first: the builder saves containers with `tree: true`
+        // too, and a container holds one object, not rows.
         if (parent.type === 'form') {
             parentInfo.isForm = true;
-            return parentInfo;
         }
-        if (parent.type === 'container') {
+        else if (parent.type === 'container') {
             parentInfo.isContainer = true;
-            return parentInfo;
+        }
+        else if (parent.tree ||
+            parent.type === 'datagrid' ||
+            parent.type === 'editgrid') {
+            parentInfo.isTable = true;
         }
         return parentInfo;
     }
@@ -163,20 +218,17 @@ class UAGFormInterface extends appserver_1.FormInterface {
         return `To determine what fields are within this component, use the \`get_form_fields\` tool with \`parent_path\`="<data_path>" (e.g. \`parent_path\`="${parent.data_path}"). To collect data for this component, use the \`collect_field_data\` tool with the \`parent_path\` set for the parent's data_path.`;
     }
     getComponentValueRule(component, data_path) {
-        let rule = '';
         const parent = this.getParentInfoFromComponent(component, data_path);
         if (parent?.isTable) {
-            rule += 'The value is a table of rows (array of objects), where each row is a new instance of data values for the child components. ' + this.getParentToolDescription(parent) + ' All `data_path`(s) for the components within this table should contain the current row index (e.g. `dataGrid[0].a`, `dataGrid[0].b`, `dataGrid[1].b`, etc.).';
-            return rule;
+            return 'The value is a table of rows (array of objects), where each row is a new instance of data values for the child components. ' + this.getParentToolDescription(parent) + ' All `data_path`(s) for the components within this table should contain the current row index (e.g. `dataGrid[0].a`, `dataGrid[0].b`, `dataGrid[1].b`, etc.).';
         }
         if (parent?.isForm) {
-            rule += 'The value is a nested form submission in the format `{data: {...}}` where `{...}` is the values for the child components. ' + this.getParentToolDescription(parent) + ' All `data_path`(s) for the components within this nested form should be prefixed with `data` (e.g. `nestedForm.data.exampleField`).';
-            return rule;
+            return 'The value is a nested form submission in the format `{data: {...}}` where `{...}` is the values for the child components. ' + this.getParentToolDescription(parent) + ' All `data_path`(s) for the components within this nested form should be prefixed with `data` (e.g. `nestedForm.data.exampleField`).';
         }
         if (parent?.isContainer) {
-            rule += 'The value is an object/map of nested component values in the format `{...}`. ' + this.getParentToolDescription(parent) + ' All `data_path`(s) for the components within this container should be prefixed with the container\'s `data_path` (e.g. `container.exampleField`).';
-            return rule;
+            return 'The value is an object/map of nested component values in the format `{...}`. ' + this.getParentToolDescription(parent) + ' All `data_path`(s) for the components within this container should be prefixed with the container\'s `data_path` (e.g. `container.exampleField`).';
         }
+        let rule = '';
         switch (component.type) {
             case 'tags':
                 rule += 'The value can be any alphanumeric string, containing letters, numbers, but no white space characters or symbols. Multiple tags should be comma-separated.';
@@ -184,8 +236,12 @@ class UAGFormInterface extends appserver_1.FormInterface {
             case 'signature':
                 rule += 'Have the user draw their signature. The value will be a base64-encoded PNG image string of that signature.';
                 break;
-            case 'textfield':
             case 'textarea':
+                rule += (0, richText_1.isRichText)(component)
+                    ? richText_1.RICH_TEXT_RULE
+                    : 'The value can be any alphanumeric string, containing letters, numbers, white space characters, and common symbols.';
+                break;
+            case 'textfield':
             case 'hidden':
                 rule += 'The value can be any alphanumeric string, containing letters, numbers, white space characters, and common symbols.';
                 break;
@@ -245,8 +301,6 @@ class UAGFormInterface extends appserver_1.FormInterface {
                     rule += `\n      - **${value.label}** (${value.value})`;
                 });
                 break;
-            default:
-                rule += '';
         }
         return rule;
     }
@@ -259,13 +313,10 @@ class UAGFormInterface extends appserver_1.FormInterface {
      * @returns { boolean } - True if the component is a nested data component, false otherwise.
      */
     isNestedComponent(component) {
-        if (component.tree ||
+        return !!component.tree ||
             component.type === 'datagrid' ||
             component.type === 'editgrid' ||
-            component.type === 'form') {
-            return true;
-        }
-        return false;
+            component.type === 'form';
     }
     /**
      * Determine if the component is a non-input component that should be skipped when collecting fields.
@@ -304,12 +355,10 @@ class UAGFormInterface extends appserver_1.FormInterface {
      * Override the process methods for the UAG.
      */
     async process(submission, auth, headers = {}, findQuery = {}, additional = []) {
-        const processors = [...core_1.Processors, ...additional];
-        // Remove the 'fetch' processor since UAG handles this with the fetch_external_data tool.
-        const fetchIndex = processors.findIndex((p) => p.name === 'fetch');
-        if (fetchIndex !== -1) {
-            processors.splice(fetchIndex, 1);
-        }
+        // Leave out 'fetch', since the UAG handles it with the fetch_external_data tool, and
+        // 'dereference', which expands a "Save as reference" select or a Data Table from the
+        // database the UAG does not have: it would throw for every form with one.
+        const processors = [...core_1.Processors, ...additional].filter((p) => p.name !== 'fetch' && p.name !== 'dereference');
         // Return the processed submission data.
         const context = await super.process(submission, auth, headers, findQuery, processors);
         // Filter the "required" validation since the UAG retrieves required fields separately.
@@ -374,19 +423,19 @@ class UAGFormInterface extends appserver_1.FormInterface {
                             return;
                         }
                         if (typeof within === 'string') {
-                            if (path.startsWith(within) && (path !== within)) {
-                                // Make sure to set the largest index for the nested component.
-                                const indexMatch = path.match(/\[(\d+)\]/);
-                                fieldInfo.rowIndex = indexMatch?.length ? parseInt(indexMatch[indexMatch.length - 1], 10) : 0;
+                            // Only paths below `within`: "customerNotes" is not within "customer".
+                            const rest = path.slice(within.length);
+                            if (path.startsWith(within) && (rest.startsWith('.') || rest.startsWith('['))) {
+                                // The row of `within` itself, not of a table it sits in
+                                // ("outer[0].inner[3].x" is row 3 of "outer[0].inner").
+                                const indexMatch = rest.match(/^\[(\d+)\]/);
+                                fieldInfo.rowIndex = indexMatch ? parseInt(indexMatch[1], 10) : 0;
                             }
                             else {
+                                // If within is a string, then it is a single path to limit components within (non-inclusive).
                                 return;
                             }
                         }
-                        // If within is a string, then it is a single path to limit components within (non-inclusive).
-                        if ((typeof within === 'string') && (!path.startsWith(within) || (path === within))) {
-                            return;
-                        }
                     }
                     // If this is a component within the nested path, then skip it...
                     else if (nestedPath && path.startsWith(nestedPath) && (path !== nestedPath)) {
@@ -412,7 +461,13 @@ class UAGFormInterface extends appserver_1.FormInterface {
                     }
                     // Add the component info to the appropriate list.
                     const criteria = component.validate?.required ? 'required' : 'optional';
-                    fieldInfo[criteria].rules[component.type] = this.getComponentValueRule(component, path);
+                    // Rules are listed by type, but some depend on the component (its
+                    // options source, multiple values, a survey's questions, a nested
+                    // component's path): one that differs gets an entry of its own.
+                    const rules = fieldInfo[criteria].rules;
+                    const rule = this.getComponentValueRule(component, path);
+                    const known = rules[component.type];
+                    rules[(known === undefined || known === rule) ? component.type : `${component.type} (${path})`] = rule;
                     fieldInfo[criteria].components.push(this.getComponentInfo(component, path));
                 }
             }
@@ -422,6 +477,86 @@ class UAGFormInterface extends appserver_1.FormInterface {
         }
         return fieldInfo;
     }
+    /** Whether the chat cannot collect this component yet, so the person finishes it in the form. */
+    isChatUnsupported(component) {
+        if (CHAT_UNSUPPORTED.has(component.type))
+            return true;
+        const dataSrc = component.dataSrc;
+        if (component.type === 'select' && (dataSrc === 'url' || dataSrc === 'resource'))
+            return true;
+        if (component.tree && component.type !== 'container')
+            return true;
+        return ['nestedArray', 'nestedDataArray', 'dataObject', 'map'].includes(core_1.Utils.getModelType(component));
+    }
+    /** Data paths of the fields a task fills: its decision and value fields, not its inputs. */
+    taskOwnedPaths() {
+        const owned = new Set();
+        for (const task of Object.values(this.uagFields || {})) {
+            Object.keys(task.components || {}).forEach((path) => owned.add(path));
+        }
+        return owned;
+    }
+    /**
+     * The fields a chat may collect on this data: visible input fields that a
+     * person may enter, filled or not, with the rules the MCP tools give
+     * agents. Fields a task fills (and `uagAuthoritative` ones), hidden,
+     * disabled and calculated fields are left out; components the chat
+     * cannot collect yet are listed in `unsupported`, and their children are
+     * not visited.
+     */
+    async chatFields(submission, authInfo) {
+        const result = { fields: [], unsupported: [], errors: [] };
+        const owned = this.taskOwnedPaths();
+        const skipped = [];
+        const within = (path, parent) => path.startsWith(`${parent}.`) || path.startsWith(`${parent}[`);
+        const context = await this.process(submission, authInfo, null, null, [
+            {
+                name: 'chatFields',
+                shouldProcess: () => true,
+                process: async (context) => {
+                    const { component, path } = context;
+                    if (this.isChatUnsupported(component) && !skipped.some((parent) => within(path, parent))) {
+                        skipped.push(path);
+                    }
+                },
+                postProcess: async (context) => {
+                    const { component, path, value } = context;
+                    if (skipped.some((parent) => within(path, parent)))
+                        return;
+                    if (skipped[skipped.length - 1] === path)
+                        skipped.pop();
+                    if (!this.inputComponent(component) || component.type === 'container')
+                        return;
+                    // A field inside a hidden panel or container is only marked `intentionallyHidden`.
+                    if (component.scope?.conditionallyHidden || component.scope?.intentionallyHidden || component.hidden || component.type === 'hidden')
+                        return;
+                    const required = !!component.validate?.required;
+                    const empty = !(0, core_1.componentHasValue)(component, value);
+                    if (this.isChatUnsupported(component)) {
+                        result.unsupported.push({ path, label: component.label || component.key || path, required, empty });
+                        return;
+                    }
+                    if (component.disabled || component.persistent === false || component.persistent === 'client-only')
+                        return;
+                    if (component.calculateValue && !component.allowCalculateOverride)
+                        return;
+                    if (owned.has(path) || (0, formflow_1.flagOn)(component.properties?.uagAuthoritative))
+                        return;
+                    result.fields.push({
+                        ...this.getComponentInfo(component, path),
+                        rule: this.getComponentValueRule(component, path),
+                        required,
+                        empty,
+                        value
+                    });
+                }
+            }
+        ]);
+        if (context.scope?.errors?.length) {
+            result.errors = this.convertToFormFieldErrors((0, core_1.interpolateErrors)(context.scope.errors));
+        }
+        return result;
+    }
     /**
      * Return the component at the specified data path.
      * @param path { string } - The data path of the component to retrieve.
@@ -466,7 +601,7 @@ class UAGFormInterface extends appserver_1.FormInterface {
             else if (value && this.isMultiple(comp) && typeof value === 'string') {
                 value = value.split(',').map((v) => v.trim());
             }
-            (0, lodash_1.set)(submission.data, path, value);
+            (0, lodash_1.set)(submission.data, path, this.normalizeWrittenValue(path, value));
         }
         return submission;
     }
@@ -491,7 +626,12 @@ class UAGFormInterface extends appserver_1.FormInterface {
             }
             else if (this.inputComponent(component) && (0, core_1.componentHasValue)(component, value)) {
                 const modelType = core_1.Utils.getModelType(component);
-                if ((0, lodash_1.isObjectLike)(value)) {
+                if ((0, formflow_1.isBinaryComponent)(component)) {
+                    // Files and signatures are described, never inlined: a base64 upload would fill the context.
+                    const described = (0, formflow_1.describeBinary)(component, value);
+                    value = (0, lodash_1.isObjectLike)(described) ? JSON.stringify(described) : described;
+                }
+                else if ((0, lodash_1.isObjectLike)(value)) {
                     value = JSON.stringify(value);
                 }
                 else if (modelType === 'string' && (0, lodash_1.isString)(value)) {
@@ -512,7 +652,7 @@ class UAGFormInterface extends appserver_1.FormInterface {
             }
         }, false, false, undefined, undefined, undefined, (component, data) => {
             if (this.isNestedComponent(component)) {
-                prefix = prefix.slice(0, -3);
+                prefix = prefix.slice(0, -2);
             }
             if (component.key === 'uag' || withinUAG) {
                 withinUAG = false;
@@ -528,6 +668,35 @@ class UAGFormInterface extends appserver_1.FormInterface {
             modified: submission.modified
         };
     }
+    /** The form's name in Agentic Formflow responses and messages. */
+    get formflowName() {
+        return this.uag?.name || this.form?.name || '';
+    }
+    /** The form's tasks, for Agentic Formflow. */
+    formflowTasks() {
+        return this.uagFields || {};
+    }
+    /** The submission's values in form order with their labels, for Agentic Formflow. */
+    formflowLabeledData(data = {}) {
+        return this.formatData(data).map(({ path, label }) => ({ path, label }));
+    }
+    /**
+     * A value an agent engine generated, before it is checked and written: HTML
+     * for a rich text field is reduced to the markup its editor keeps.
+     */
+    formflowNormalizeValue(component, value) {
+        return (0, richText_1.isRichText)(component) && typeof value === 'string' ? (0, richText_1.sanitizeRichText)(value) : value;
+    }
+    /**
+     * A value an MCP client writes at a data path (collect_field_data,
+     * confirm_form_submission, submit_completed_form, submission_update), as
+     * an engine's is: HTML for a rich text field is reduced to the markup its
+     * editor keeps. Row indices are ignored to find the component.
+     */
+    normalizeWrittenValue(path, value) {
+        const component = this.getComponent(String(path).replace(/\[\d+\]/g, ''));
+        return component ? this.formflowNormalizeValue(component, value) : value;
+    }
     htmlToMarkdown(html) {
         return node_html_markdown_1.NodeHtmlMarkdown.translate(html, {
             bulletMarker: '-',

package/lib/UAGProjectInterface.d.ts

@@ -1,22 +1,62 @@
 import { ProjectInterface, SubmissionRequest } from "@formio/appserver";
+import { EngineRegistry, FormflowConfig, FormflowFileReader, FormflowForm, FormflowHost, FormflowTool, ScopedTokenClaims } from "./formflow";
 import { UAGConfig } from "./config";
 import { Form } from "@formio/core";
 import { NextFunction, Response, Router } from "express";
 import { UAGFormInterface } from "./UAGFormInterface";
 import { ResponseTemplate, UAGTemplate } from "./template";
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-export declare class UAGProjectInterface extends ProjectInterface {
+import type { PluginRegistry } from "@formio/appserver";
+export declare class UAGProjectInterface extends ProjectInterface implements FormflowHost {
     user: any;
-    formNames: string[];
+    /** The names of the UAG forms the project currently has. */
+    get formNames(): string[];
     uagTemplate: UAGTemplate | null;
+    /** Engines enabled at startup; empty until UAGServer.router() resolves them. */
+    engines: EngineRegistry;
     mcpServer: McpServer;
     get config(): UAGConfig;
     constructor(endpoint?: string);
     initialize(): Promise<void>;
-    buildMcpServer(): Promise<McpServer>;
+    buildMcpServer(scope?: Pick<ScopedTokenClaims, 'tools'>): Promise<McpServer>;
     addForm(form: Form, machineName: string): UAGFormInterface | undefined;
-    uagRouter(): Router;
-    authorizeRequest(req: SubmissionRequest, res: Response, next: NextFunction): Promise<Response<any, Record<string, any>> | undefined>;
+    /**
+     * The UAG's routes: `/mcp`, and unless excluded, `/agent/capabilities`.
+     * UAGServer mounts capabilities separately, ahead of the project router. A
+     * form's agent operations are on the form's own routes (UAGFormInterface).
+     */
+    uagRouter(includeAgentApi?: boolean): Router;
+    /** `/agent/capabilities`, behind its own authentication. */
+    agentRouter(): Router;
+    /** Whether runs after the save are recorded and survive a restart (the UAG's database). */
+    durableRuns(): boolean;
+    /** The engines enabled for Agentic Formflow. */
+    formflowEngines(): EngineRegistry;
+    /**
+     * Agentic Formflow's routing, Agent API and auth settings. The engine
+     * settings stay here: the UAG loads the engines, not core.
+     */
+    formflowConfig(): FormflowConfig;
+    /** A form tagged "uag", or null. */
+    formflowForm(name: string): Promise<FormflowForm | null>;
+    /** The server's plugin registry, once its plugins are listed. */
+    plugins?: PluginRegistry;
+    /**
+     * Readers for uploaded documents: one built from the installed converters,
+     * which reads every type with a route to text.
+     */
+    formflowFileReaders(): FormflowFileReader[];
+    /** Every MCP tool, as Agentic Formflow tools. */
+    formflowTools(): Promise<FormflowTool[]>;
+    authorizeRequest(req: SubmissionRequest, res: Response, next: NextFunction): Promise<void | Response<any, Record<string, any>>>;
+    /**
+     * The user a Form.io token stands for, as the project's x-jwt-token
+     * authentication decides it: a token tied to a Form.io session is asked of
+     * Form.io; one signed with this UAG's secret is read from its claims, bound
+     * to this project; any other is asked of Form.io. Never an administrator:
+     * an administrator's research carries no user token.
+     */
+    private formioTokenAuth;
     mcpJSONResponse(data?: object, isError?: boolean): {
         content: {
             type: 'text';