@formio/uag 1.13.1 → 2.0.0-rc.1

package/bin/uag-eval.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/**
+ * uag-eval: measure decision accuracy against automation on labeled examples.
+ *
+ *   uag-eval --form claim.json --examples claim-examples.json [--task triage]
+ *            [--engine jev] [--json report.json]
+ *
+ * --form      A Form.io form definition (JSON export).
+ * --task      The task to evaluate (default: the form's first). `--persona` is the old name.
+ * --examples  A JSON array of { "id", "data": { ... }, "expected": { "<path>": <value or null> } }.
+ *             null means "the input does not say", which expects the field to stay empty.
+ * --engine    The decision engine to evaluate: an instance named in UAG_ENGINES, or an
+ *             entry in its syntax (`jev`, `next:jev`). Default: the first in UAG_ENGINES.
+ * --json      Also write the full report as JSON.
+ * --project   The project URL the evaluation runs for (default: none). A real engine
+ *             needs a LICENSE_KEY that includes the UAG for this URL; the stub
+ *             engines need neither.
+ *
+ * The engine is loaded as the UAG loads it, so the same UAG_ENGINES and
+ * UAG_ENGINE_* variables give the same instance, with the same model. Its type
+ * may be built in, or an installed engine package. Resource-backed selects need
+ * a live project and are skipped.
+ */
+require('dotenv/config');
+const { readFileSync, writeFileSync } = require('fs');
+const { parseInstances } = require('@formio/uag-sdk');
+const { ProjectInterface, UAGProjectInterface, UAGFormInterface, loadUAGEngines } = require('../lib');
+const { FormflowService, formatReport, resolveTaskName } = require('../lib/formflow');
+
+/**
+ * The instance to evaluate: the one UAG_ENGINES names `name`, so a deployed
+ * instance is evaluated with its own settings, or else `name` as an entry.
+ */
+function engineEntry(name, env) {
+    const deployed = parseInstances(env.UAG_ENGINES);
+    if (!name) return deployed[0];
+    return deployed.find((instance) => instance.name === name) || parseInstances(name)[0];
+}
+
+function args(argv) {
+    const out = {};
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i].startsWith('--')) out[argv[i].slice(2)] = argv[i + 1];
+    }
+    return out;
+}
+
+async function main() {
+    const opts = args(process.argv.slice(2));
+    if (!opts.form || !opts.examples) {
+        console.error('Usage: uag-eval --form <form.json> --examples <examples.json> [--task <name>] [--engine <name>] [--json <out.json>] [--project <url>]');
+        process.exit(2);
+    }
+    const task = resolveTaskName(opts, 'uag-eval');
+    const formDef = JSON.parse(readFileSync(opts.form, 'utf8'));
+    const examples = JSON.parse(readFileSync(opts.examples, 'utf8'));
+    const entry = engineEntry(opts.engine, process.env);
+    if (!entry) {
+        console.error('Name the decision engine with --engine or UAG_ENGINES.');
+        process.exit(2);
+    }
+
+    const registry = await loadUAGEngines({ engines: [entry] }, process.env);
+    const engine = registry.decision[0];
+    if (!engine) {
+        console.error(`"${registry.all[0].name}" is not a decision engine.`);
+        process.exit(2);
+    }
+
+    // The license the evaluation may use, read as a running UAG reads it.
+    await ProjectInterface.connect({ config: { license: String(process.env.UAG_LICENSE || ''), licenseType: 'uagServer', licenseFeature: 'uag' } });
+    // Build the form offline. Outside a running server the project would create
+    // the base form class, so the UAG form interface is constructed directly.
+    const project = new UAGProjectInterface(opts.project || 'http://offline.invalid');
+    const name = formDef.name || formDef.path || 'form';
+    formDef.tags = [...new Set([...(formDef.tags || []), 'uag'])];
+    // The constructor sets the form, which derives its UAG registration and tasks.
+    const form = new UAGFormInterface(project, formDef);
+    project.forms[name] = form;
+
+    const report = await new FormflowService(project).evaluate(form, task, examples, engine, {}, (done, total) => {
+        process.stderr.write(`\r${done}/${total} example(s)`);
+    });
+    process.stderr.write('\n');
+    console.log(formatReport(report));
+    if (opts.json) {
+        writeFileSync(opts.json, JSON.stringify(report, null, 2));
+        console.log(`Report written to ${opts.json}`);
+    }
+}
+
+main().catch((err) => {
+    console.error(err.message || err);
+    process.exit(1);
+});

package/bin/uag.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+/**
+ * uag: start the Form.io UAG.
+ *
+ *   uag                       the UAG with no module
+ *   UAG_MODULE=./my-module uag
+ *
+ * Configuration comes from the environment (PROJECT, PROJECT_KEY or ADMIN_KEY,
+ * JWT_SECRET, UAG_ENGINES, MONGO, ...) and an optional module: a file or
+ * folder exporting `{ config, actions, ... }`, named by UAG_MODULE.
+ *
+ * Engines are found among the installed packages, so a custom image holds only
+ * the engines it installs:
+ *
+ *   npm install @formio/uag @formio/uag-claude
+ *   UAG_ENGINES=claude CLAUDE_API_KEY=... npx uag
+ */
+// Before anything else, so a module that reads the environment sees .env too.
+require('dotenv/config');
+const path = require('path');
+
+/** isolated-vm, which runs form logic, needs Node's startup snapshot off. */
+function snapshotDisabled() {
+    return process.execArgv.includes('--no-node-snapshot') || /(^|\s)--no-node-snapshot(\s|$)/.test(process.env.NODE_OPTIONS || '');
+}
+
+/** Run this file again with the flag, passing signals on, and exit as it does. */
+function restartWithoutSnapshot() {
+    const { spawn } = require('child_process');
+    const child = spawn(process.execPath, ['--no-node-snapshot', ...process.execArgv, __filename, ...process.argv.slice(2)], { stdio: 'inherit' });
+    for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+        process.on(signal, () => child.kill(signal));
+    }
+    child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)));
+}
+
+/** Start the UAG with a module, listening on PORT (default 3200). */
+async function start(uagModule) {
+    const Express = require('express');
+    const { UAGServer, trustProxySetting } = require('../lib');
+    const server = new UAGServer();
+    if (uagModule) server.use(uagModule);
+    const app = Express();
+    // Behind a reverse proxy, its forwarded headers give the public URL (TRUST_PROXY).
+    const trust = trustProxySetting(process.env.TRUST_PROXY);
+    if (trust !== undefined) app.set('trust proxy', trust);
+    // Loads the engines the module's `engines` setting, or else UAG_ENGINES,
+    // names; a misconfigured engine stops startup with its name in the error.
+    app.use(await server.router());
+    const port = process.env.PORT || 3200;
+    await new Promise((resolve) => app.listen(port, resolve));
+    console.log(`Form.io UAG server running on port ${port}`);
+    console.log(`Visit http://localhost:${port} to access the application`);
+}
+
+function fail(error) {
+    console.error('Failed to start server:', error);
+    process.exit(1);
+}
+
+if (require.main === module) {
+    if (!snapshotDisabled()) {
+        restartWithoutSnapshot();
+    }
+    else {
+        Promise.resolve()
+            .then(() => (process.env.UAG_MODULE ? require(path.resolve(process.env.UAG_MODULE)) : undefined))
+            .then(start)
+            .catch(fail);
+    }
+}
+
+module.exports = { start, fail };

package/lib/UAGFormInterface.d.ts

@@ -1,7 +1,9 @@
 import { AppServerForm, AuthRequest, FormInterface, InterpolatedError } from "@formio/appserver";
+import type { FormflowForm, FormflowTask } from "./formflow";
 import { Component, Submission, DataObject, ComponentPaths } from "@formio/core";
 import { UAGForm } from "./config";
 import { ParentInfo } from "./tools";
+import { Router } from "express";
 export type UAGComponentInfo = {
     path: string;
     label: string;
@@ -49,14 +51,48 @@ export type FormFieldInfo = {
         components: UAGComponentInfo[];
     };
 };
+/** A field a chat may collect, with its current value. */
+export type ChatField = UAGComponentInfo & {
+    required: boolean;
+    empty: boolean;
+    value: any;
+};
+/** A component a chat cannot collect yet. */
+export type ChatUnsupportedField = {
+    path: string;
+    label: string;
+    required: boolean;
+    empty: boolean;
+};
+export type ChatFields = {
+    fields: ChatField[];
+    unsupported: ChatUnsupportedField[];
+    errors: FormFieldError[];
+};
 export type UAGFields = {
-    persona: string;
+    task: string;
     criteria: string;
     components: Record<string, UAGComponentInfo>;
+    /** Data paths of the components flagged `uagField: "input"`: the source text for extraction and decisions. */
+    inputs?: string[];
+    /** Task-level settings, read from the custom properties of the task's criteria component (e.g. `uagEngine`, `uagTools`). */
+    settings?: Record<string, string>;
 };
-export declare class UAGFormInterface extends FormInterface {
+export declare class UAGFormInterface extends FormInterface implements FormflowForm {
     uag: UAGForm | null;
     uagFields: Record<string, UAGFields>;
+    /**
+     * 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.
+     */
+    router(): Promise<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: AppServerForm): AppServerForm;
     setComponent(form: AppServerForm, component: Component, path: string, components: Component[] | undefined, parent: Component | undefined, paths: ComponentPaths | undefined): void;
     getComponentFormat(component: Component): string;
     getComponentInfo(component: Component, path: string): UAGComponentInfo;
@@ -111,6 +147,19 @@ export declare class UAGFormInterface extends FormInterface {
      * @returns { Promise<FormFieldInfo> } - The extracted form field information.
      */
     getFields(submission: Submission, authInfo: AuthRequest, within?: string | string[]): Promise<FormFieldInfo>;
+    /** Whether the chat cannot collect this component yet, so the person finishes it in the form. */
+    isChatUnsupported(component: Component): boolean;
+    /** Data paths of the fields a task fills: its decision and value fields, not its inputs. */
+    taskOwnedPaths(): Set<string>;
+    /**
+     * 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.
+     */
+    chatFields(submission: Submission, authInfo: AuthRequest): Promise<ChatFields>;
     /**
      * Return the component at the specified data path.
      * @param path { string } - The data path of the component to retrieve.
@@ -133,5 +182,14 @@ export declare class UAGFormInterface extends FormInterface {
     convertToSubmission(data?: Record<string, any>): Submission;
     formatData(data?: DataObject): UAGData;
     formatSubmission(submission: Submission): UAGSubmission;
+    /** The form's name in Agentic Formflow responses and messages. */
+    get formflowName(): string;
+    /** The form's tasks, for Agentic Formflow. */
+    formflowTasks(): Record<string, FormflowTask>;
+    /** The submission's values in form order with their labels, for Agentic Formflow. */
+    formflowLabeledData(data?: DataObject): {
+        path: string;
+        label: string;
+    }[];
     htmlToMarkdown(html: string): string;
 }

package/lib/UAGFormInterface.js

@@ -5,27 +5,66 @@ const appserver_1 = require("@formio/appserver");
 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'
+]);
 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) {
@@ -42,7 +81,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 +111,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 +128,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 +151,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 +199,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.';
@@ -245,8 +278,6 @@ class UAGFormInterface extends appserver_1.FormInterface {
                     rule += `\n      - **${value.label}** (${value.value})`;
                 });
                 break;
-            default:
-                rule += '';
         }
         return rule;
     }
@@ -259,13 +290,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.
@@ -374,19 +402,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 +440,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 +456,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) || component.properties?.uagAuthoritative === 'true')
+                        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.
@@ -512,7 +626,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 +642,18 @@ 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 }));
+    }
     htmlToMarkdown(html) {
         return node_html_markdown_1.NodeHtmlMarkdown.translate(html, {
             bulletMarker: '-',

package/lib/UAGProjectInterface.d.ts

@@ -1,22 +1,54 @@
 import { ProjectInterface, SubmissionRequest } from "@formio/appserver";
+import { EngineRegistry, FormflowConfig, 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 {
+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>;
+    /** 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';