@formio/uag 2.0.0-rc.3 → 2.0.0-rc.5

package/README.md

@@ -55,7 +55,7 @@ A person talks to Claude, ChatGPT or your own chat app, and the agent fills in a
 
 An application saves a submission through the UAG; an **Agent: Run task** action runs the form's task after the save and saves the result, which can start the next task. [Try it](https://ai.form.io/examples/workflow) · [source](./demo/server/workflow.mjs) · build it with [Workflows](https://ai.form.io/developers/workflows) · [prompt for your coding agent](https://github.com/formio/ai/blob/main/examples/agents/admissions-workflow.md).
 
-![The admissions rubric and the Run task actions in the portal; an applicant submits; the admissions agent scores the application and its save starts the finance agent, which picks the award.](./demo/public/images/demo-workflow.gif)
+![The admissions criteria and the Run task actions in the portal; an applicant submits; the admissions agent scores the application and its save starts the finance agent, which picks the award.](./demo/public/images/demo-workflow.gif)
 
 ### Agentic Formflow
 
@@ -90,7 +90,7 @@ services:
       retries: 40
 
   formio-uag:
-    image: formio/uag
+    image: formio/uag:rc
     depends_on:
       formio: { condition: service_healthy }
     ports: ["3200:3200"]
@@ -267,7 +267,7 @@ app.use(await server.router());
 app.listen(process.env.PORT || 3200);
 ```
 
-Run Node 22 or newer with `--no-node-snapshot` (isolated-vm, which runs form logic, needs it), and install the engines you use next to the UAG (`npm install @formio/uag-claude`). See [Node.js API](https://ai.form.io/developers/node-api).
+Run Node 22 or newer with `--no-node-snapshot` (isolated-vm, which runs form logic, needs it), and install the engines you use next to the UAG (`npm install @formio/uag-claude@rc`). See [Node.js API](https://ai.form.io/developers/node-api).
 - **[`@formio/uag-js`](./packages/uag-js)** connects a formio.js application to the UAG. Register it once with `Formio.use(UAG('https://uag.example.com'))`: submissions of forms tagged `uag` are then saved through the UAG, and Agent Input fills those forms from what the user wrote, through `{form}/agent/extract`, when they leave the input, pause, move to the next page, or press a button. `Formio.createChat(element, formUrl)` renders any of them as a chat instead, templated, translated and themed like a formio.js form. See [JavaScript (formio.js)](https://ai.form.io/developers/renderer) and [Chat widget](https://ai.form.io/developers/chat).
 
 ## Deployment
@@ -323,7 +323,7 @@ The full table, with the Agent API's errors: [Troubleshooting](https://ai.form.i
 | [`@formio/uag-sdk`](./packages/engine-sdk) | 2.x | ≥ 2.0.0 | Engine contract version 1, remote engine protocol version 1. |
 | [`@formio/uag-engines`](./packages/engine-server), image `formio/uag-engines` | 2.x | ≥ 2.0.0 | The engine server. |
 | [`@formio/uag-js`](./packages/uag-js) | 2.x | ≥ 2.0.0 | The formio.js module: saves `uag` forms through the UAG, adds Agent Input, and renders forms as a chat. Runs in the browser. |
-| `@formio/uag-claude` | 1.3.x | ≥ 1.12.0 | The retired Claude integration. Security fixes only; see [MIGRATING-2.0.md](./MIGRATING-2.0.md). |
+| `@formio/uag-claude` | 1.3.x | 1.12.0 – 1.13.x | The retired Claude integration (against 2.0, only its direct commands). Security fixes only; see [MIGRATING-2.0.md](./MIGRATING-2.0.md). |
 
 `@formio/uag-claude` 2.x is the Claude *engine*, not the 1.x integration; pin `@formio/uag-claude@^1` if you still install the integration. Upgrading from 1.x: [MIGRATING-2.0.md](./MIGRATING-2.0.md).
 

package/bin/uag-eval.js

@@ -6,7 +6,7 @@
  *            [--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.
+ * --task      The task to evaluate (default: the form's first).
  * --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
@@ -25,7 +25,7 @@ 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');
+const { FormflowService, formatReport } = require('../lib/formflow');
 
 /**
  * The instance to evaluate: the one UAG_ENGINES names `name`, so a deployed
@@ -51,7 +51,11 @@ async function main() {
         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');
+    if (opts.persona !== undefined) {
+        console.error('uag-eval: --persona was renamed --task in UAG 2.0.');
+        process.exit(2);
+    }
+    const task = opts.task || undefined;
     const formDef = JSON.parse(readFileSync(opts.form, 'utf8'));
     const examples = JSON.parse(readFileSync(opts.examples, 'utf8'));
     const entry = engineEntry(opts.engine, process.env);

package/lib/UAGFormInterface.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UAGFormInterface = void 0;
 const appserver_1 = require("@formio/appserver");
+const formflow_1 = require("./formflow");
 const core_1 = require("@formio/core");
 const lodash_1 = require("lodash");
 const node_html_markdown_1 = require("node-html-markdown");
@@ -11,6 +12,22 @@ 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 {
     /**
      * The form's routes, with its agent operations (`agent/extract`, `agent/decide`,
@@ -67,8 +84,9 @@ class UAGFormInterface extends appserver_1.FormInterface {
                 }
             }
             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);
@@ -332,12 +350,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.
@@ -519,7 +535,7 @@ class UAGFormInterface extends appserver_1.FormInterface {
                         return;
                     if (component.calculateValue && !component.allowCalculateOverride)
                         return;
-                    if (owned.has(path) || component.properties?.uagAuthoritative === 'true')
+                    if (owned.has(path) || (0, formflow_1.flagOn)(component.properties?.uagAuthoritative))
                         return;
                     result.fields.push({
                         ...this.getComponentInfo(component, path),

package/lib/UAGProjectInterface.js

@@ -12,6 +12,7 @@ const express_1 = require("express");
 const router_1 = require("./router");
 const template_1 = require("./template");
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const version_1 = require("./version");
 const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
 const router_2 = require("./agent/router");
 const tools_1 = require("./agent/tools");
@@ -28,7 +29,7 @@ class UAGProjectInterface extends appserver_1.ProjectInterface {
         this.uagTemplate = null;
         /** Engines enabled at startup; empty until UAGServer.router() resolves them. */
         this.engines = new formflow_1.EngineRegistry();
-        this.mcpServer = new mcp_js_1.McpServer({ name: 'formio-uag', version: '1.0.0' });
+        this.mcpServer = new mcp_js_1.McpServer({ name: 'formio-uag', version: version_1.UAG_VERSION });
     }
     async initialize() {
         await super.initialize();
@@ -40,7 +41,7 @@ class UAGProjectInterface extends appserver_1.ProjectInterface {
     // A scoped token narrows the tools to its own list, and only ever to tools
     // annotated read-only: no model may write through /mcp with one.
     async buildMcpServer(scope) {
-        const server = new mcp_js_1.McpServer({ name: 'formio-uag', version: '1.0.0' });
+        const server = new mcp_js_1.McpServer({ name: 'formio-uag', version: version_1.UAG_VERSION });
         // The standard UAG tools, plus the custom tools from config.
         let tools = await (0, tools_1.allTools)(this);
         if (scope) {
@@ -164,10 +165,16 @@ class UAGProjectInterface extends appserver_1.ProjectInterface {
             // Point MCP clients at OAuth sign-in only when it is on (MCP_OAUTH, with the database).
             const pkce = this.provider('auth.pkce');
             const metadata = pkce?.oauthReady ? `, resource_metadata="${pkce.publicUrl(req)}/.well-known/oauth-protected-resource"` : '';
+            // RFC 6750 3.1: a request that presented a token is told it is invalid; one
+            // that presented none gets no error code, only the challenge.
+            const presented = !!(0, formflow_1.bearerOf)(req.get('authorization'));
+            const description = String(err?.message || err || 'Unauthorized').replace(/["\\]/g, '');
+            const challenge = presented ? `, error="invalid_token", error_description="${description}"` : '';
             return res.status(401).set({
-                'WWW-Authenticate': `Bearer realm="uag-server"${metadata}`
+                'WWW-Authenticate': `Bearer realm="uag-server"${challenge}${metadata}`
             }).json({
-                detail: err.message || err
+                error: presented ? 'invalid_token' : 'unauthorized',
+                error_description: presented ? description : 'Send an access token: Authorization: Bearer <token>.'
             });
         }
     }

package/lib/actionLogs.js

@@ -35,12 +35,14 @@ function actionItem(record) {
     if (record.finished) {
         const written = record.written || [];
         const cleared = record.cleared || [];
-        const info = record.status === 'failed'
+        const refused = record.refused || [];
+        const left = refused.length ? ` Left out answers the form refused: ${refused.join(', ')}.` : '';
+        const info = (record.status === 'failed'
             ? `Failed: ${record.error || 'unknown error'}`
             : record.saved
                 ? `Saved ${written.length} field(s)${written.length ? `: ${written.join(', ')}` : ''}${cleared.length ? `; cleared ${cleared.join(', ')}` : ''}.`
-                : 'Nothing changed, so nothing was saved.';
-        messages.push({ datetime: record.finished.toISOString(), info, data: { engines: record.engines || [], written, cleared } });
+                : 'Nothing changed, so nothing was saved.') + left;
+        messages.push({ datetime: record.finished.toISOString(), info, data: { engines: record.engines || [], written, cleared, ...(refused.length && { refused }) } });
     }
     return {
         _id: String(record._id),

package/lib/actions/runTask.js

@@ -9,6 +9,7 @@ const formflow_1 = require("../formflow");
 const runner_1 = require("../runner");
 const protocol_1 = require("@formio/uag-sdk/protocol");
 const requestId_1 = require("../agent/requestId");
+const errors_1 = require("../agent/errors");
 const identity_1 = require("../identity");
 const debug = require('debug')('formio:uag:actions:runTask');
 exports.RUN_TASK = 'agentRunTask';
@@ -89,12 +90,12 @@ function onBehalfHook() {
             if (roles.length > 1) {
                 console.error(`[formio-uag] The Run task actions of "${form.name}" that run on create name different agent roles ` +
                     `(${actions.map((action) => action.title || action.machineName).join(', ')}). Choose one agent role for them all.`);
-                return res.status(500).json({ name: 'ConfigurationError', message: `The form "${form.name}" is not configured correctly: its Run task actions name different agent roles.` });
+                return res.status(500).json({ name: 'ConfigurationError', message: `The form "${form.name}" is not configured correctly: its Run task actions name different agent roles.`, code: 'configuration_error' });
             }
             const [role] = roles;
             const submitters = actions.flatMap((action) => action.settings.submitterRoles || []).map(String);
             if (!appserver_1.AuthRequest.hasRole([role], access[appserver_1.AuthorizedStateType.ALL], project) || !has(submitters)) {
-                return res.status(403).json({ name: 'ForbiddenError', message: 'You may not submit this form.' });
+                return res.status(403).json({ name: 'ForbiddenError', message: 'You may not submit this form.', code: 'forbidden' });
             }
             try {
                 req.forwardAuth = await (0, identity_1.agentAuth)(project, actingFor, role, { task: actions[0].settings.task });
@@ -127,7 +128,7 @@ function refuse(res, err) {
     res.status(err.status).json({
         name: err.name,
         message: err.message,
-        ...(err.code && { code: err.code }),
+        code: err.code || (0, errors_1.errorCode)(err.status),
         ...(err.edition && { edition: err.edition })
     });
 }

package/lib/agent/anonymous.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AnonymousLimiter = void 0;
 exports.anonymousLimits = anonymousLimits;
 exports.anonymousGate = anonymousGate;
+const formflow_1 = require("../formflow");
 const debug = require('debug')('formio:uag:agent');
 const WINDOW_MS = 60000;
 /** A number from the configuration, else the environment, else the default. */
@@ -74,14 +75,14 @@ function anonymousGate(project) {
         const request = req;
         const form = request.form;
         const limits = anonymousLimits(project);
-        if (limits.perAddress === 0 || limits.total === 0 || String(form?.form?.properties?.uagAnonymous) !== 'true') {
-            return res.status(401).json({ detail: 'Sign in to use this form\'s agent operations.' });
+        if (limits.perAddress === 0 || limits.total === 0 || !(0, formflow_1.flagOn)(form?.form?.properties?.uagAnonymous)) {
+            return res.status(401).json({ error: 'Sign in to use this form\'s agent operations.', code: 'sign_in_required' });
         }
         const taken = limiterFor(project).take(String(req.ip || req.socket?.remoteAddress || ''), limits);
         if (!taken.allowed) {
             debug(`Refused an anonymous ${req.method} ${req.path}: over the anonymous rate limit.`);
             res.set('Retry-After', String(taken.retryAfter));
-            return res.status(429).json({ detail: 'Too many requests. Try again shortly.' });
+            return res.status(429).json({ error: 'Too many requests. Try again shortly.', code: 'rate_limited' });
         }
         let permissions = {};
         try {
@@ -91,7 +92,7 @@ function anonymousGate(project) {
             permissions = {};
         }
         if (!permissions.create) {
-            return res.status(403).json({ detail: 'Anonymous visitors may not submit this form.' });
+            return res.status(403).json({ error: 'Anonymous visitors may not submit this form.', code: 'forbidden' });
         }
         next();
     };

package/lib/agent/chat.js

@@ -162,7 +162,9 @@ function fieldSpec(form, field) {
         label: field.label,
         type: field.type,
         description: [field.required ? 'Required.' : 'Optional.', field.description, field.prompt && `Placeholder: ${field.prompt}`].filter(Boolean).join(' '),
-        rule: field.rule || '',
+        // The host's rule, then the component's validation (lengths, pattern, range, mask), so a
+        // first answer is likely to pass the form's checks.
+        rule: (0, formflow_1.ruleWithConstraints)(field.rule, component),
     };
     if (field.format)
         spec.format = field.format;
@@ -387,7 +389,7 @@ async function chatTurn(project, form, body, context) {
     const request = readChatRequest(body, settings);
     const engines = chatEngines(project, settings);
     if (!engines.length) {
-        throw new formflow_1.FormflowError(503, 'No enabled engine can serve chat. Enable an agent engine with UAG_ENGINES.');
+        throw new formflow_1.FormflowError(503, 'No enabled engine can serve chat. Enable an agent engine with UAG_ENGINES.', 'no_engine');
     }
     const service = (0, formflow_1.formflow)(project);
     const before = await form.chatFields({ data: (0, lodash_1.cloneDeep)(request.data) }, context.auth);

package/lib/agent/engines.js

@@ -8,7 +8,7 @@ exports.loadUAGEngines = loadUAGEngines;
 const path_1 = __importDefault(require("path"));
 const uag_sdk_1 = require("@formio/uag-sdk");
 const loader_1 = require("@formio/uag-sdk/loader");
-const appserver_core_1 = require("@formio/appserver-core");
+const appserver_1 = require("@formio/appserver");
 const remote_1 = require("./remote");
 const stubs_1 = require("./stubs");
 /** The UAG's own installation, where engine packages are looked up first. */
@@ -31,7 +31,7 @@ async function loadUAGEngines(config = {}, env = process.env) {
         paths: (0, loader_1.enginePaths)(exports.UAG_ROOT, env),
         env,
         config,
-        apiVersion: appserver_core_1.Formflow.ENGINE_API_VERSION,
+        apiVersion: appserver_1.Formflow.ENGINE_API_VERSION,
     });
-    return appserver_core_1.Formflow.engineRegistry(loaded);
+    return appserver_1.Formflow.engineRegistry(loaded);
 }

package/lib/agent/errors.d.ts

@@ -0,0 +1,16 @@
+import { Request, RequestHandler, Response } from "express";
+export declare function isAgentApiRequest(req: Request): boolean;
+/** The code for a status, when the error names none. */
+export declare function errorCode(status: number): string;
+export declare const INTERNAL_ERROR = "The request failed. See the UAG logs for this request id.";
+/** The request's id, assigned once: the caller's, when it is a short token, or a new one. */
+export declare function requestIdOf(req: Request, res: Response): string;
+/** The error body for a status and whatever a handler sent: an object, JSON text, plain text or nothing. */
+export declare function errorBody(requestId: string, status: number, sent: unknown): Record<string, any>;
+/**
+ * Mounted ahead of every route: for an Agent API request, assigns the request
+ * id and rewrites any error response into the one shape, so refusals from
+ * middleware the UAG does not own (the project's authentication answers plain
+ * text, the portal's team access an empty 401) look like every other.
+ */
+export declare function agentErrorShape(): RequestHandler;

package/lib/agent/errors.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INTERNAL_ERROR = void 0;
+exports.isAgentApiRequest = isAgentApiRequest;
+exports.errorCode = errorCode;
+exports.requestIdOf = requestIdOf;
+exports.errorBody = errorBody;
+exports.agentErrorShape = agentErrorShape;
+const crypto_1 = require("crypto");
+const protocol_1 = require("@formio/uag-sdk/protocol");
+/**
+ * The Agent API's one error shape. Every error a form's agent operation or
+ * `/agent/capabilities` answers is JSON
+ *
+ *     { "requestId": "...", "error": "a message for people", "code": "a_stable_code", ... }
+ *
+ * with the same id in `X-Request-Id`, whatever refused it: the UAG, the
+ * project's authentication, the portal's team access, the body parser.
+ * Clients branch on `code`; `error` is for people. A 500 never carries details:
+ * those are in the UAG's log under the request id.
+ */
+/** A form's agent operations, and the capabilities. */
+const OPERATION = /\/agent\/(extract|decide|generate|chat)\/?$/i;
+const CAPABILITIES = /^\/agent\/capabilities\/?$/i;
+function isAgentApiRequest(req) {
+    return (req.method === 'POST' && OPERATION.test(req.path)) || (req.method === 'GET' && CAPABILITIES.test(req.path));
+}
+/** The code for a status, when the error names none. */
+function errorCode(status) {
+    switch (status) {
+        case 400: return 'invalid_request';
+        case 401: return 'unauthorized';
+        case 403: return 'forbidden';
+        case 404: return 'not_found';
+        case 409: return 'conflict';
+        case 413: return 'payload_too_large';
+        case 429: return 'rate_limited';
+        case 502: return 'engines_failed';
+        case 503: return 'unavailable';
+        case 504: return 'timeout';
+        default: return status >= 500 ? 'internal_error' : 'invalid_request';
+    }
+}
+exports.INTERNAL_ERROR = 'The request failed. See the UAG logs for this request id.';
+/** The request's id, assigned once: the caller's, when it is a short token, or a new one. */
+function requestIdOf(req, res) {
+    const request = req;
+    if (!request.requestId) {
+        request.requestId = (0, protocol_1.safeRequestId)(req.get('x-request-id')) || (0, crypto_1.randomUUID)();
+    }
+    if (!res.headersSent)
+        res.set('X-Request-Id', request.requestId);
+    return request.requestId;
+}
+/** The error body for a status and whatever a handler sent: an object, JSON text, plain text or nothing. */
+function errorBody(requestId, status, sent) {
+    let value = sent;
+    if (Buffer.isBuffer(value))
+        value = value.toString('utf8');
+    if (typeof value === 'string') {
+        try {
+            value = JSON.parse(value);
+        }
+        catch {
+            value = { error: value };
+        }
+    }
+    const given = value && typeof value === 'object' ? value : {};
+    const text = [given.error, given.detail, given.message].find((part) => typeof part === 'string' && part.trim());
+    // A 500's own message may carry internals: only the UAG's fixed sentence goes out.
+    const error = status >= 500 && status !== 502 && status !== 503 && status !== 504 ? exports.INTERNAL_ERROR : (text || defaultMessage(status));
+    return {
+        requestId,
+        error,
+        code: typeof given.code === 'string' && given.code ? given.code : errorCode(status),
+        ...(typeof given.edition === 'string' && { edition: given.edition })
+    };
+}
+function defaultMessage(status) {
+    switch (status) {
+        case 401: return 'Unauthorized.';
+        case 403: return 'Forbidden.';
+        case 404: return 'Not found.';
+        case 413: return 'The request body is too large.';
+        case 429: return 'Too many requests. Try again shortly.';
+        default: return 'The request could not be completed.';
+    }
+}
+/**
+ * Mounted ahead of every route: for an Agent API request, assigns the request
+ * id and rewrites any error response into the one shape, so refusals from
+ * middleware the UAG does not own (the project's authentication answers plain
+ * text, the portal's team access an empty 401) look like every other.
+ */
+function agentErrorShape() {
+    return (req, res, next) => {
+        if (!isAgentApiRequest(req))
+            return next();
+        const requestId = requestIdOf(req, res);
+        const send = res.send.bind(res);
+        let shaped = false;
+        res.send = ((body) => {
+            // An event stream writes its own error events; only whole responses are shaped.
+            if (shaped || res.statusCode < 400)
+                return send(body);
+            shaped = true;
+            res.type('application/json');
+            return send(JSON.stringify(errorBody(requestId, res.statusCode, body)));
+        });
+        next();
+    };
+}

package/lib/agent/router.js

@@ -38,10 +38,9 @@ exports.AgentRouter = AgentRouter;
 exports.agentNotFound = agentNotFound;
 exports.agentCredentials = agentCredentials;
 exports.FormAgentRouter = FormAgentRouter;
-const crypto_1 = require("crypto");
 const lodash_1 = require("lodash");
 const express_1 = __importStar(require("express"));
-const protocol_1 = require("@formio/uag-sdk/protocol");
+const errors_1 = require("./errors");
 const formflow_1 = require("../formflow");
 const requestId_1 = require("./requestId");
 const anonymous_1 = require("./anonymous");
@@ -67,10 +66,17 @@ function openStream(res) {
 function contextOf(req) {
     return { auth: req.auth, requestId: req.requestId, identity: (0, formflow_1.callerIdentity)(req.auth, req) };
 }
-/** The task the request names, if any. */
+/**
+ * The task the request names, if any. A request that still names a 1.x
+ * `persona` is refused: ignoring it would run every task, an engine call each.
+ */
 function taskOf(req) {
+    const named = (value) => typeof value === 'string' && value.trim() !== '';
     const task = req.body?.task;
-    return typeof task === 'string' && task ? task : undefined;
+    if (named(req.body?.persona) && !named(task)) {
+        throw new formflow_1.FormflowError(400, 'UAG 2.0 renamed "persona" to "task". Send "task" instead.');
+    }
+    return named(task) ? task : undefined;
 }
 /**
  * Answer extract, streaming per-engine results when the client asks for a
@@ -113,15 +119,15 @@ function agentEndpoints(project) {
             return parse(req, res, next);
         const length = Number(req.get('content-length')) || Buffer.byteLength(JSON.stringify(req.body ?? null));
         if (length > exports.AGENT_BODY_LIMIT) {
-            return res.status(413).json({ error: `The request body is larger than the agent operations' limit of ${exports.AGENT_BODY_LIMIT / (1024 * 1024)} MB.` });
+            return res.status(413).json({ error: `The request body is larger than the agent operations' limit of ${exports.AGENT_BODY_LIMIT / (1024 * 1024)} MB.`, code: 'payload_too_large' });
         }
         next();
     };
-    // Request id, after authentication: refused requests carry none. One that
-    // is not a short token is replaced, so it is never echoed, logged or sent on.
+    // The request id, usually assigned already by agentErrorShape, ahead of every
+    // refusal. One that is not a short token is replaced, so it is never echoed,
+    // logged or sent on.
     const requestId = (req, res, next) => {
-        req.requestId = (0, protocol_1.safeRequestId)(req.get('x-request-id')) || (0, crypto_1.randomUUID)();
-        res.set('X-Request-Id', req.requestId);
+        (0, errors_1.requestIdOf)(req, res);
         next();
     };
     const handle = (operation, fn) => async (req, res) => {
@@ -142,8 +148,8 @@ function agentEndpoints(project) {
             }
             const body = {
                 requestId: agentReq.requestId,
-                error: status === 500 ? 'The request failed. See the UAG logs for this request id.' : err.message,
-                ...(err instanceof formflow_1.FormflowError && err.code && { code: err.code }),
+                error: status === 500 ? errors_1.INTERNAL_ERROR : err.message,
+                code: (err instanceof formflow_1.FormflowError && err.code) || (0, errors_1.errorCode)(status),
                 ...(err?.edition && { edition: err.edition })
             };
             if (res.headersSent) {
@@ -207,11 +213,11 @@ function agentNotFound(project) {
             : !!formPath && forms.some((form) => String(form.path || '').toLowerCase() === formPath.toLowerCase());
         if (known)
             return next();
-        res.status(404).json({ error: `The form "${byId ? byId[1] : formPath}" does not exist or is not tagged "uag".` });
+        res.status(404).json({ error: `The form "${byId ? byId[1] : formPath}" does not exist or is not tagged "uag".`, code: 'form_not_found' });
     };
 }
-function refuse(res, detail) {
-    return res.status(401).json({ detail });
+function refuse(res, error) {
+    return res.status(401).json({ error, code: 'unauthorized' });
 }
 /**
  * Who may call a form's agent operations, on top of the project's own
@@ -283,10 +289,10 @@ function FormAgentRouter(project, credentials) {
     route('chat', 'chat', async (req, res, service) => {
         const form = await project.formflowForm(formOf(req));
         if (!form) {
-            throw new formflow_1.FormflowError(404, `The form "${formOf(req)}" does not exist or is not tagged "uag".`);
+            throw new formflow_1.FormflowError(404, `The form "${formOf(req)}" does not exist or is not tagged "uag".`, 'form_not_found');
         }
-        if (String(form.form?.properties?.uagChat) === 'false') {
-            throw new formflow_1.FormflowError(403, `Chat is turned off for the form "${form.formflowName}".`);
+        if ((0, formflow_1.flagOff)(form.form?.properties?.uagChat)) {
+            throw new formflow_1.FormflowError(403, `Chat is turned off for the form "${form.formflowName}".`, 'chat_disabled');
         }
         service.requireAccess(req.auth, form, ['create']);
         res.json(await (0, chat_1.chatTurn)(project, form, req.body, { auth: req.auth, requestId: req.requestId }));

package/lib/config.d.ts

@@ -47,8 +47,6 @@ export type UAGToolOverride = {
     submission_update?: ToolInfo;
     find_submissions?: ToolInfo;
     agent_provide?: ToolInfo;
-    /** @deprecated The earlier name of `agent_provide`; also applied to it when `agent_provide` is not set. */
-    agent_provide_data?: ToolInfo;
     agent_decide?: ToolInfo;
     fetch_external_data?: ToolInfo;
 };

package/lib/database.d.ts

@@ -1,5 +1,5 @@
 import { Collection, Db, MongoClient, MongoClientOptions } from 'mongodb';
-import type { AuthCodeStore } from '@formio/appserver-core';
+import type { AuthCodeStore } from '@formio/appserver';
 /**
  * The UAG's own database (MONGO, with the database named by UAG_DATABASE). It
  * holds only the UAG's state: authorization codes for remote MCP clients, the

package/lib/formflow.d.ts

@@ -1,10 +1,10 @@
-import { Formflow } from '@formio/appserver-core';
+import { Formflow } from '@formio/appserver';
 /**
- * Agentic Formflow from @formio/appserver-core, imported directly rather than
- * through @formio/appserver, under the names the UAG uses. Internal to the UAG:
+ * Agentic Formflow from @formio/appserver-core, through @formio/appserver (see
+ * assertSingleCore), under the names the UAG uses. Internal to the UAG:
  * applications reach Formflow as `Formflow` from this package's exports.
  */
-export declare const EngineConfigError: typeof Formflow.EngineConfigError, EngineRegistry: typeof Formflow.EngineRegistry, FormflowError: typeof Formflow.FormflowError, FormflowService: typeof Formflow.FormflowService, RateLimitError: typeof Formflow.RateLimitError, ScopedTokenError: typeof Formflow.ScopedTokenError, bearerOf: typeof Formflow.bearerOf, engineRegistry: typeof Formflow.engineRegistry, formflow: typeof Formflow.formflow, formflowAuthenticate: typeof Formflow.formflowAuthenticate, identityOf: typeof Formflow.identityOf, issueScopedToken: typeof Formflow.issueScopedToken, isScopedToken: typeof Formflow.isScopedToken, readScopedToken: typeof Formflow.readScopedToken, resolveTaskName: typeof Formflow.resolveTaskName, resultEvent: typeof Formflow.resultEvent, warnLegacy: typeof Formflow.warnLegacy, withoutOwnedValues: typeof Formflow.withoutOwnedValues, stubAgentEngine: typeof Formflow.stubAgentEngine, stubDecisionEngine: typeof Formflow.stubDecisionEngine, toolsForScope: typeof Formflow.toolsForScope, EngineError: typeof Formflow.EngineError, formatReport: typeof Formflow.formatReport;
+export declare const EngineConfigError: typeof Formflow.EngineConfigError, EngineRegistry: typeof Formflow.EngineRegistry, FormflowError: typeof Formflow.FormflowError, FormflowService: typeof Formflow.FormflowService, RateLimitError: typeof Formflow.RateLimitError, ScopedTokenError: typeof Formflow.ScopedTokenError, bearerOf: typeof Formflow.bearerOf, engineRegistry: typeof Formflow.engineRegistry, formflow: typeof Formflow.formflow, formflowAuthenticate: typeof Formflow.formflowAuthenticate, identityOf: typeof Formflow.identityOf, issueScopedToken: typeof Formflow.issueScopedToken, isScopedToken: typeof Formflow.isScopedToken, readScopedToken: typeof Formflow.readScopedToken, resultEvent: typeof Formflow.resultEvent, withoutOwnedValues: typeof Formflow.withoutOwnedValues, stubAgentEngine: typeof Formflow.stubAgentEngine, stubDecisionEngine: typeof Formflow.stubDecisionEngine, toolsForScope: typeof Formflow.toolsForScope, EngineError: typeof Formflow.EngineError, formatReport: typeof Formflow.formatReport, flagOn: typeof Formflow.flagOn, flagOff: typeof Formflow.flagOff, ruleWithConstraints: typeof Formflow.ruleWithConstraints;
 export type AgentEngine = Formflow.AgentEngine;
 export type CallerIdentity = Formflow.CallerIdentity;
 export type DecisionEngine = Formflow.DecisionEngine;

package/lib/formflow.js

@@ -1,14 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.formatReport = exports.EngineError = exports.toolsForScope = exports.stubDecisionEngine = exports.stubAgentEngine = exports.withoutOwnedValues = exports.warnLegacy = exports.resultEvent = exports.resolveTaskName = exports.readScopedToken = exports.isScopedToken = exports.issueScopedToken = exports.identityOf = exports.formflowAuthenticate = exports.formflow = exports.engineRegistry = exports.bearerOf = exports.ScopedTokenError = exports.RateLimitError = exports.FormflowService = exports.FormflowError = exports.EngineRegistry = exports.EngineConfigError = void 0;
+exports.ruleWithConstraints = exports.flagOff = exports.flagOn = exports.formatReport = exports.EngineError = exports.toolsForScope = exports.stubDecisionEngine = exports.stubAgentEngine = exports.withoutOwnedValues = exports.resultEvent = exports.readScopedToken = exports.isScopedToken = exports.issueScopedToken = exports.identityOf = exports.formflowAuthenticate = exports.formflow = exports.engineRegistry = exports.bearerOf = exports.ScopedTokenError = exports.RateLimitError = exports.FormflowService = exports.FormflowError = exports.EngineRegistry = exports.EngineConfigError = void 0;
 exports.callerIdentity = callerIdentity;
-const appserver_core_1 = require("@formio/appserver-core");
+const appserver_1 = require("@formio/appserver");
 /**
- * Agentic Formflow from @formio/appserver-core, imported directly rather than
- * through @formio/appserver, under the names the UAG uses. Internal to the UAG:
+ * Agentic Formflow from @formio/appserver-core, through @formio/appserver (see
+ * assertSingleCore), under the names the UAG uses. Internal to the UAG:
  * applications reach Formflow as `Formflow` from this package's exports.
  */
-({ EngineConfigError: exports.EngineConfigError, EngineRegistry: exports.EngineRegistry, FormflowError: exports.FormflowError, FormflowService: exports.FormflowService, RateLimitError: exports.RateLimitError, ScopedTokenError: exports.ScopedTokenError, bearerOf: exports.bearerOf, engineRegistry: exports.engineRegistry, formflow: exports.formflow, formflowAuthenticate: exports.formflowAuthenticate, identityOf: exports.identityOf, issueScopedToken: exports.issueScopedToken, isScopedToken: exports.isScopedToken, readScopedToken: exports.readScopedToken, resolveTaskName: exports.resolveTaskName, resultEvent: exports.resultEvent, warnLegacy: exports.warnLegacy, withoutOwnedValues: exports.withoutOwnedValues, stubAgentEngine: exports.stubAgentEngine, stubDecisionEngine: exports.stubDecisionEngine, toolsForScope: exports.toolsForScope, EngineError: exports.EngineError, formatReport: exports.formatReport } = appserver_core_1.Formflow);
+({ EngineConfigError: exports.EngineConfigError, EngineRegistry: exports.EngineRegistry, FormflowError: exports.FormflowError, FormflowService: exports.FormflowService, RateLimitError: exports.RateLimitError, ScopedTokenError: exports.ScopedTokenError, bearerOf: exports.bearerOf, engineRegistry: exports.engineRegistry, formflow: exports.formflow, formflowAuthenticate: exports.formflowAuthenticate, identityOf: exports.identityOf, issueScopedToken: exports.issueScopedToken, isScopedToken: exports.isScopedToken, readScopedToken: exports.readScopedToken, resultEvent: exports.resultEvent, withoutOwnedValues: exports.withoutOwnedValues, stubAgentEngine: exports.stubAgentEngine, stubDecisionEngine: exports.stubDecisionEngine, toolsForScope: exports.toolsForScope, EngineError: exports.EngineError, formatReport: exports.formatReport, flagOn: exports.flagOn, flagOff: exports.flagOff, ruleWithConstraints: exports.ruleWithConstraints } = appserver_1.Formflow);
 /**
  * Who an operation's research acts as: core's `identityOf`, and for a caller
  * signed in with a Form.io token (`x-jwt-token`), that token, so a scoped token

package/lib/index.d.ts

@@ -1,5 +1,5 @@
 import { Server, ServerModule } from '@formio/appserver';
-import { Router } from 'express';
+import { Request, Response, Router } from 'express';
 import { UAGProjectInterface } from './UAGProjectInterface';
 import { UAGFormInterface } from './UAGFormInterface';
 import { UAGConfig } from './config';
@@ -8,12 +8,19 @@ export type UAGModule = ServerModule & {
     config?: UAGConfig;
 };
 /**
- * Agentic Formflow keeps its license state inside @formio/appserver-core, so the
- * UAG and @formio/appserver must load the same copy of it, at 2.24.1 or later.
- * A second copy (an older lockfile, or a package manager that nests it) would
- * otherwise fail in confusing ways; say what to do instead.
+ * Agentic Formflow keeps its license state inside @formio/appserver-core. The UAG
+ * loads it only through @formio/appserver, so the two always share one copy,
+ * which must be 2.25.2 or later. An older @formio/appserver, or an old lockfile,
+ * can still resolve an older one, which would fail in confusing ways; say what
+ * to do instead.
  */
-export declare function assertSingleCore(core?: any, appserver?: any, version?: string): void;
+export declare function assertSingleCore(version?: string): void;
+/**
+ * isolated-vm, which runs form logic, needs Node's startup snapshot off. Without
+ * it nothing fails at once: the process can crash later, in native code. So an
+ * embedding server that forgot the flag is stopped here, saying what to do.
+ */
+export declare function assertNodeSnapshotDisabled(execArgv?: string[], nodeOptions?: string): void;
 export declare class UAGServer extends Server {
     config: UAGConfig;
     /** The UAG's own database, once it may be used. */
@@ -36,6 +43,12 @@ export declare class UAGServer extends Server {
      * otherwise leave it untouched, close it, and say why.
      */
     protected enableDatabase(project: UAGProjectInterface): Promise<void>;
+    /**
+     * An Agent API request that failed before its handlers (a body that is not JSON,
+     * one over the size limit) is answered in the Agent API's error shape; every other
+     * route keeps Form.io's plain-text answer.
+     */
+    protected sendError(req: Request, res: Response, status: number, message: string, err?: any): void;
     /** Browsers reading Agent API responses need the request id too. */
     get exposedHeaders(): string[];
     /** The loaded UAG project, once the project router has been built. */

package/lib/index.js

@@ -13,11 +13,16 @@ var __createBinding = (this && this.__createBinding) || (Object.create ? (functi
 var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UAGFormInterface = exports.UAGProjectInterface = exports.UAGServer = void 0;
 exports.assertSingleCore = assertSingleCore;
+exports.assertNodeSnapshotDisabled = assertNodeSnapshotDisabled;
 const appserver_1 = require("@formio/appserver");
 const formflow_1 = require("./formflow");
+const path_1 = __importDefault(require("path"));
 const UAGProjectInterface_1 = require("./UAGProjectInterface");
 Object.defineProperty(exports, "UAGProjectInterface", { enumerable: true, get: function () { return UAGProjectInterface_1.UAGProjectInterface; } });
 const UAGFormInterface_1 = require("./UAGFormInterface");
@@ -25,26 +30,63 @@ Object.defineProperty(exports, "UAGFormInterface", { enumerable: true, get: func
 const lodash_1 = require("lodash");
 const engines_1 = require("./agent/engines");
 const router_1 = require("./agent/router");
+const errors_1 = require("./agent/errors");
 const database_1 = require("./database");
 const runs_1 = require("./runs");
 const actionLogs_1 = require("./actionLogs");
 const runner_1 = require("./runner");
 const runTask_1 = require("./actions/runTask");
+const version_1 = require("./version");
 const debug = require('debug')('formio:uag');
 /**
- * Agentic Formflow keeps its license state inside @formio/appserver-core, so the
- * UAG and @formio/appserver must load the same copy of it, at 2.24.1 or later.
- * A second copy (an older lockfile, or a package manager that nests it) would
- * otherwise fail in confusing ways; say what to do instead.
+ * Agentic Formflow keeps its license state inside @formio/appserver-core. The UAG
+ * loads it only through @formio/appserver, so the two always share one copy,
+ * which must be 2.25.2 or later. An older @formio/appserver, or an old lockfile,
+ * can still resolve an older one, which would fail in confusing ways; say what
+ * to do instead.
  */
-function assertSingleCore(core = require('@formio/appserver-core'), appserver = require('@formio/appserver'), version = String(require('@formio/appserver-core/package.json').version || '0.0.0')) {
+function assertSingleCore(version = appserverCoreVersion()) {
     const [major, minor, patch] = version.split('.').map((part) => parseInt(part, 10) || 0);
-    if (major < 2 || (major === 2 && (minor < 24 || (minor === 24 && patch < 1)))) {
-        throw new Error(`@formio/uag needs @formio/appserver-core 2.24.1 or later; ${version} is installed.`);
+    if (major < 2 || (major === 2 && (minor < 25 || (minor === 25 && patch < 2)))) {
+        throw new Error(`@formio/uag needs @formio/appserver-core 2.25.2 or later, through @formio/appserver; ${version} is installed. Upgrade @formio/appserver.`);
+    }
+}
+/** The version of the @formio/appserver-core that @formio/appserver loads. */
+function appserverCoreVersion() {
+    const appserver = path_1.default.dirname(require.resolve('@formio/appserver/package.json'));
+    return String(require(require.resolve('@formio/appserver-core/package.json', { paths: [appserver] })).version || '0.0.0');
+}
+/**
+ * isolated-vm, which runs form logic, needs Node's startup snapshot off. Without
+ * it nothing fails at once: the process can crash later, in native code. So an
+ * embedding server that forgot the flag is stopped here, saying what to do.
+ */
+function assertNodeSnapshotDisabled(execArgv = process.execArgv, nodeOptions = process.env.NODE_OPTIONS || '') {
+    if (execArgv.includes('--no-node-snapshot') || /(^|\s)--no-node-snapshot(\s|$)/.test(nodeOptions))
+        return;
+    throw new Error('@formio/uag needs Node started with --no-node-snapshot: isolated-vm, which runs form logic, can crash the process without it. ' +
+        'Start node with --no-node-snapshot, or set NODE_OPTIONS=--no-node-snapshot. The uag command and the formio/uag image do this for you.');
+}
+/** A host name a browser cannot reach: a container or service name, with no dot. */
+function internalHost(url) {
+    try {
+        const { hostname } = new URL(url);
+        return !!hostname && hostname !== 'localhost' && !hostname.includes('.') && !hostname.includes(':');
     }
-    if (appserver.Formflow !== core.Formflow || appserver.ProjectInterface !== core.ProjectInterface) {
-        throw new Error('Two copies of @formio/appserver-core are installed: one for @formio/uag and an older one for @formio/appserver. ' +
-            'Upgrade @formio/appserver to 2.24.1 or later and deduplicate (for example `yarn dedupe @formio/appserver-core`).');
+    catch {
+        return false;
+    }
+}
+/** Warnings for settings that start fine and fail later, in ways far from their cause. */
+function warnAboutSettings(config, secretGiven) {
+    if (!secretGiven) {
+        console.warn('[formio-uag] JWT_SECRET is not set, so the UAG signs its tokens with a random secret that lasts only as long as this process: ' +
+            'every token stops working when it restarts, and other instances refuse it. Set JWT_SECRET, the same on every instance.');
+    }
+    const auth = config.auth || {};
+    if (auth.mcpOAuth && !auth.loginForm && internalHost(String(config.project || ''))) {
+        console.warn(`[formio-uag] MCP_OAUTH is on, but LOGIN_FORM is not set: the sign-in page loads ${String(config.project).replace(/\/+$/, '')}/user/login, ` +
+            'an address a person\'s browser cannot reach. Set LOGIN_FORM to the login form\'s public URL.');
     }
 }
 /** The UAG's own database from the environment, when `MONGO` is set. */
@@ -62,8 +104,11 @@ function databaseFromEnv(env = process.env) {
 }
 class UAGServer extends appserver_1.Server {
     constructor(config) {
+        assertNodeSnapshotDisabled();
         assertSingleCore();
         const configuredDb = !!config?.db;
+        // Read before the server fills in a random one.
+        const secretGiven = !!(config?.auth?.secret || (0, lodash_1.get)(process.env, 'JWT_SECRET', '').toString());
         const uagLicense = (0, lodash_1.get)(process.env, 'UAG_LICENSE', '').toString();
         if (uagLicense) {
             console.warn('[formio-uag] UAG_LICENSE is deprecated. Put a Form.io license that includes the UAG in LICENSE_KEY instead; UAG_LICENSE keeps working until UAG 3.0.');
@@ -85,6 +130,10 @@ class UAGServer extends appserver_1.Server {
             retryDelay: parseInt((0, lodash_1.get)(process.env, 'PROJECT_RETRY_DELAY', 5000).toString(), 10),
             submissionProxy: true,
             processAsClient: true,
+            // GET /status names the UAG's version beside the Form.io packages it runs on.
+            status: { '@formio/uag': version_1.UAG_VERSION },
+            // Bodies are parsed before authentication, so keep them to what Form.io accepts.
+            maxBodySize: (0, lodash_1.get)(process.env, 'MAX_BODY_SIZE', '16mb').toString(),
             auth: { pkce: true, mcpOAuth: (0, lodash_1.get)(process.env, 'MCP_OAUTH', '').toString() === 'true' },
             database: databaseFromEnv()
         }));
@@ -94,6 +143,7 @@ class UAGServer extends appserver_1.Server {
             delete this.module.db;
             delete this.config.db;
         }
+        warnAboutSettings(this.config, secretGiven);
         this.use({
             ProjectInterface: UAGProjectInterface_1.UAGProjectInterface,
             FormInterface: UAGFormInterface_1.UAGFormInterface,
@@ -163,6 +213,18 @@ class UAGServer extends appserver_1.Server {
             console.warn('[formio-uag] MCP_OAUTH is set, but remote MCP sign-in is off: it needs the UAG\'s database (MONGO), and a license that includes the UAG to use it.');
         }
     }
+    /**
+     * An Agent API request that failed before its handlers (a body that is not JSON,
+     * one over the size limit) is answered in the Agent API's error shape; every other
+     * route keeps Form.io's plain-text answer.
+     */
+    sendError(req, res, status, message, err) {
+        if (!(0, errors_1.isAgentApiRequest)(req))
+            return super.sendError(req, res, status, message, err);
+        const error = err?.type === 'entity.parse.failed' ? 'The request body is not valid JSON.' : message;
+        // Written past any shaping wrapper, which may not have run for this request.
+        res.status(status).type('application/json').end(JSON.stringify((0, errors_1.errorBody)((0, errors_1.requestIdOf)(req, res), status, { error })));
+    }
     /** Browsers reading Agent API responses need the request id too. */
     get exposedHeaders() {
         return [...super.exposedHeaders, 'X-Request-Id'];
@@ -181,6 +243,8 @@ class UAGServer extends appserver_1.Server {
         await super.extendRouter(router);
         const uagProject = this.uagProject;
         if (uagProject) {
+            // First: the Agent API's request id and one error shape, for every refusal after it.
+            router.use((0, errors_1.agentErrorShape)());
             router.use(uagProject.agentRouter());
             // An agent operation of a form the project does not have is answered here, not passed to Form.io.
             router.use((0, router_1.agentNotFound)(uagProject));

package/lib/runner.d.ts

@@ -53,6 +53,8 @@ export type TaskRunOutcome = {
     }[];
     /** Whether the results were saved (nothing is saved when nothing changed). */
     saved: boolean;
+    /** Answers the form's validation refused, left out: path to the form's message. */
+    refused?: Record<string, string>;
     error?: string;
 };
 /**

package/lib/runner.js

@@ -268,8 +268,9 @@ class TaskRunner {
         const service = (0, formflow_1.formflow)(this.project);
         const load = async () => {
             const stored = await form.loadSubmission(job.submission, await act());
+            // Form.io answers a submission the caller may not read as missing, so say both.
             if (!stored)
-                throw new formflow_1.FormflowError(404, `Submission "${job.submission}" was not found.`);
+                throw new formflow_1.FormflowError(404, `Submission "${job.submission}" was not found, or the user the run acts as may not read it (give submitters Read Own access, or the action an agent role).`);
             return stored;
         };
         let stored = await load();
@@ -278,8 +279,14 @@ class TaskRunner {
             const engines = run.results.map((result) => ({ kind: result.kind, engine: result.engine ?? null, model: result.model ?? null }));
             const failed = run.failed.map((group) => group.error || 'no engine could answer').join('; ');
             const changed = Object.keys(run.written).length > 0 || run.cleared.length > 0;
+            const refused = run.refused || {};
+            if (Object.keys(refused).length) {
+                console.warn(`[formio-uag] Run task "${job.task}" left out answers the form refused for submission ${job.submission} of "${job.form}": ` +
+                    Object.entries(refused).map(([path, message]) => `${path} (${message})`).join('; '));
+            }
+            const left = Object.keys(refused).length ? { refused } : {};
             if (!changed) {
-                return { status: failed ? 'failed' : 'done', written: {}, cleared: [], engines, saved: false, ...(failed && { error: failed }) };
+                return { status: failed ? 'failed' : 'done', written: {}, cleared: [], engines, saved: false, ...left, ...(failed && { error: failed }) };
             }
             try {
                 // Only the task's fields changed; `modified` refuses the save if a person saved in the meantime.
@@ -291,7 +298,7 @@ class TaskRunner {
                     ...(job.caller ? { [exports.RUN_TASK_CALLER]: job.caller, [exports.RUN_TASK_IDENTITY]: job.identity } : { [exports.RUN_TASK_AS_USER]: true }),
                     [exports.RUN_TASK_CHAIN]: (job.chain || 0) + 1
                 });
-                return { status: failed ? 'failed' : 'done', written: run.written, cleared: run.cleared, engines, saved: true, ...(failed && { error: failed }) };
+                return { status: failed ? 'failed' : 'done', written: run.written, cleared: run.cleared, engines, saved: true, ...left, ...(failed && { error: failed }) };
             }
             catch (err) {
                 if (err?.name !== 'ConflictError' || attempt >= 2) {
@@ -313,6 +320,7 @@ function resultOf(outcome) {
         engines: outcome.engines,
         written: Object.keys(outcome.written),
         cleared: outcome.cleared,
+        ...(outcome.refused && { refused: Object.keys(outcome.refused) }),
         saved: outcome.saved,
         ...(outcome.error && { error: outcome.error })
     };

package/lib/runs.d.ts

@@ -40,6 +40,8 @@ export type TaskRunRecord = {
     }[];
     written?: string[];
     cleared?: string[];
+    /** Paths whose answers the form's validation refused, left out of the save. */
+    refused?: string[];
     saved?: boolean;
     error?: string;
     created: Date;
@@ -77,7 +79,7 @@ export declare class TaskRunStore {
     /** Keep holding a run. False when another replica took it over. */
     renew(id: ObjectId): Promise<boolean>;
     /** Record how a run ended. Only the replica holding a durable run can. */
-    finish(id: ObjectId, result: Pick<TaskRunRecord, 'engines' | 'written' | 'cleared' | 'saved' | 'error'> & {
+    finish(id: ObjectId, result: Pick<TaskRunRecord, 'engines' | 'written' | 'cleared' | 'refused' | 'saved' | 'error'> & {
         status: 'done' | 'failed';
     }): Promise<void>;
     get(id: string): Promise<TaskRunRecord | null>;

package/lib/tools/SchemaBuilder.d.ts

@@ -113,11 +113,6 @@ export declare class SchemaBuilder {
      * components' `uag` property).
      */
     task(): this;
-    /**
-     * The legacy name for `task`. Kept in the schema so clients that still send
-     * it are not silently given the default task.
-     */
-    persona(): this;
     /**
      * The data_path of a specific field within the form.
      */

package/lib/tools/SchemaBuilder.js

@@ -175,14 +175,6 @@ class SchemaBuilder {
         this.schema.task = zod_1.default.string().optional().describe('The name of a task defined on the form: the value of its components\' `uag` property, such as "triage". Not a description of the work. If not provided, the form\'s first task is used.');
         return this;
     }
-    /**
-     * The legacy name for `task`. Kept in the schema so clients that still send
-     * it are not silently given the default task.
-     */
-    persona() {
-        this.schema.persona = zod_1.default.string().optional().describe('Deprecated: the former name for `task`. Send `task` instead.');
-        return this;
-    }
     /**
      * The data_path of a specific field within the form.
      */

package/lib/tools/agentDecide.js

@@ -22,7 +22,7 @@ const agentDecide = async (project) => {
         description: 'Return the decision questions for a task\'s closed-set fields (radio, select, checkbox, select boxes, survey and small resource selects) as structured JSON: the state to decide on, every question, and how each answer maps back to a field value. Answer the questions with a decision model, then write the values with `submission_update`. Provide either `submission_id` or `form_data`.',
         annotations: (0, annotations_1.reads)('Get decision questions'),
         inputSchema: {
-            ...(new SchemaBuilder_1.SchemaBuilder(project)).form_name().submission_id().task().persona().schema,
+            ...(new SchemaBuilder_1.SchemaBuilder(project)).form_name().submission_id().task().schema,
             form_data: zod_1.default.record(zod_1.default.string(), zod_1.default.any()).optional().describe('The current form data as a submission data object (nested by data path). Used when `submission_id` is not given.')
         },
         execute: async (args, extra) => {
@@ -40,7 +40,7 @@ const agentDecide = async (project) => {
                 data = submission.data || {};
             }
             try {
-                const task = (0, formflow_1.resolveTaskName)(args, 'agent_decide');
+                const task = args.task || undefined;
                 const out = await (0, formflow_1.formflow)(project).questions(form, { task, data, submissionId: submission_id }, extra.authInfo);
                 return project.mcpJSONResponse({ form: form_name, ...out });
             }

package/lib/tools/agentProvide.d.ts

@@ -6,8 +6,3 @@ import { ToolInfo } from "./utils";
  * agent writes its values with `submission_update`.
  */
 export declare const agentProvide: (project: UAGProjectInterface) => Promise<ToolInfo>;
-/**
- * `agent_provide_data`: the earlier name of `agent_provide`, kept so MCP clients
- * and integrations that call it keep working. Removed in a future major release.
- */
-export declare const agentProvideData: (project: UAGProjectInterface) => Promise<ToolInfo>;

package/lib/tools/agentProvide.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.agentProvideData = exports.agentProvide = void 0;
+exports.agentProvide = void 0;
 const template_1 = require("../template");
 const lodash_1 = require("lodash");
 const SchemaBuilder_1 = require("./SchemaBuilder");
@@ -29,66 +29,33 @@ async function refusal(project) {
  * agent writes its values with `submission_update`.
  */
 const agentProvide = async (project) => {
-    // Overrides written for the tool's earlier name still apply, except a rename,
-    // which belongs to the deprecated tool and would clash with it.
-    const overrides = project.config?.toolOverrides;
-    const own = overrides?.agent_provide || (overrides?.agent_provide_data ? (0, lodash_1.omit)(overrides.agent_provide_data, 'name') : {});
     // Merged into a new object: the overrides are shared config, and the tools are
     // built again for every request.
-    return (0, lodash_1.defaultsDeep)({}, own, provideTool(project, 'agent_provide'));
+    return (0, lodash_1.defaultsDeep)({}, project.config?.toolOverrides?.agent_provide, provideTool(project));
 };
 exports.agentProvide = agentProvide;
-/**
- * `agent_provide_data`: the earlier name of `agent_provide`, kept so MCP clients
- * and integrations that call it keep working. Removed in a future major release.
- */
-const agentProvideData = async (project) => {
-    const tool = provideTool(project, 'agent_provide_data');
-    const execute = tool.execute;
-    return (0, lodash_1.defaultsDeep)({}, project.config?.toolOverrides?.agent_provide_data, {
-        ...tool,
-        title: 'Agent Provide Data (deprecated)',
-        description: `Deprecated: use \`agent_provide\`, which takes the same arguments. ${DESCRIPTION}`,
-        execute: (args, extra) => {
-            (0, formflow_1.warnLegacy)('agent_provide_data', 'the agent_provide_data MCP tool; use agent_provide.');
-            return execute(args, extra);
-        }
-    });
-};
-exports.agentProvideData = agentProvideData;
-function provideTool(project, name) {
+function provideTool(project) {
     return {
-        name,
+        name: 'agent_provide',
         title: 'Agent Provide',
         description: DESCRIPTION,
         annotations: (0, annotations_1.reads)('Process submission data'),
         inputSchema: (new SchemaBuilder_1.SchemaBuilder(project))
             .form_name()
             .submission_id()
-            .task()
-            .persona().schema,
+            .task().schema,
         execute: async (args, extra) => {
             const { form_name, submission_id } = args;
             const refused = await refusal(project);
             if (refused)
                 return project.mcpJSONResponse(refused, true);
-            let requested;
-            try {
-                requested = (0, formflow_1.resolveTaskName)(args, name);
-            }
-            catch (err) {
-                if (err instanceof formflow_1.FormflowError)
-                    return project.mcpJSONResponse({ error: err.message }, true);
-                throw err;
-            }
+            const requested = args.task || undefined;
             const form = await project.getForm(form_name);
             if (!form) {
                 return project.mcpResponse(template_1.ResponseTemplate.formNotFound, { formName: form_name }, true);
             }
             const task = requested || Object.keys(form.uagFields)[0] || 'default';
-            // Templates get the task under both names: deployments may have
-            // customized a template that still renders `persona`.
-            const names = { task, persona: task };
+            const names = { task };
             const uag = form.uagFields[task];
             if (!uag) {
                 return project.mcpResponse(template_1.ResponseTemplate.uagComponentNotFound, {

package/lib/tools/collectData.js

@@ -34,7 +34,8 @@ const collectData = async (project) => {
             const fields = await form.getFields(submission, extra.authInfo, parent?.data_path);
             if (fields.errors.length > 0) {
                 if (as_json) {
-                    return project.mcpJSONResponse(fields.errors);
+                    // structuredContent must be an object: an MCP client refuses a bare array.
+                    return project.mcpJSONResponse({ errors: fields.errors }, true);
                 }
                 return project.mcpResponse(template_1.ResponseTemplate.fieldValidationErrors, { invalidFields: fields.errors });
             }

package/lib/tools/index.d.ts

@@ -8,10 +8,10 @@ import { findSubmission } from "./findSubmission";
 import { submissionUpdate } from "./submissionUpdate";
 import { ToolInfo } from "./utils";
 import { UAGProjectInterface } from "../UAGProjectInterface";
-import { agentProvide, agentProvideData } from "./agentProvide";
+import { agentProvide } from "./agentProvide";
 import { agentDecide } from "./agentDecide";
 import { fetchExternalData } from "./fetchExternalData";
 export * from './utils';
 export * from './annotations';
-export { getForms, getFormFields, getFieldInfo, collectData, confirmSubmission, submitCompletedForm, findSubmission, submissionUpdate, fetchExternalData, agentProvide, agentProvideData, agentDecide };
+export { getForms, getFormFields, getFieldInfo, collectData, confirmSubmission, submitCompletedForm, findSubmission, submissionUpdate, fetchExternalData, agentProvide, agentDecide };
 export declare const getTools: (project: UAGProjectInterface) => Promise<ToolInfo[]>;

package/lib/tools/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getTools = exports.agentDecide = exports.agentProvideData = exports.agentProvide = exports.fetchExternalData = exports.submissionUpdate = exports.findSubmission = exports.submitCompletedForm = exports.confirmSubmission = exports.collectData = exports.getFieldInfo = exports.getFormFields = exports.getForms = void 0;
+exports.getTools = exports.agentDecide = exports.agentProvide = exports.fetchExternalData = exports.submissionUpdate = exports.findSubmission = exports.submitCompletedForm = exports.confirmSubmission = exports.collectData = exports.getFieldInfo = exports.getFormFields = exports.getForms = void 0;
 const getForms_1 = require("./getForms");
 Object.defineProperty(exports, "getForms", { enumerable: true, get: function () { return getForms_1.getForms; } });
 const getFormFields_1 = require("./getFormFields");
@@ -33,7 +33,6 @@ const submissionUpdate_1 = require("./submissionUpdate");
 Object.defineProperty(exports, "submissionUpdate", { enumerable: true, get: function () { return submissionUpdate_1.submissionUpdate; } });
 const agentProvide_1 = require("./agentProvide");
 Object.defineProperty(exports, "agentProvide", { enumerable: true, get: function () { return agentProvide_1.agentProvide; } });
-Object.defineProperty(exports, "agentProvideData", { enumerable: true, get: function () { return agentProvide_1.agentProvideData; } });
 const agentDecide_1 = require("./agentDecide");
 Object.defineProperty(exports, "agentDecide", { enumerable: true, get: function () { return agentDecide_1.agentDecide; } });
 const fetchExternalData_1 = require("./fetchExternalData");
@@ -52,8 +51,6 @@ const getTools = async (project) => {
         (0, submissionUpdate_1.submissionUpdate)(project),
         (0, agentProvide_1.agentProvide)(project),
         (0, agentDecide_1.agentDecide)(project),
-        // Deprecated: the earlier name of agent_provide.
-        (0, agentProvide_1.agentProvideData)(project),
         (0, fetchExternalData_1.fetchExternalData)(project)
     ]);
 };

package/lib/version.d.ts

@@ -0,0 +1,2 @@
+/** The UAG's own version, from its package.json (src/ and lib/ both sit one level below it). */
+export declare const UAG_VERSION: string;

package/lib/version.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UAG_VERSION = void 0;
+/** The UAG's own version, from its package.json (src/ and lib/ both sit one level below it). */
+exports.UAG_VERSION = require('../package.json').version;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formio/uag",
-  "version": "2.0.0-rc.3",
+  "version": "2.0.0-rc.5",
   "mcpName": "io.form/formio-uag",
   "description": "The Form.io Universal Agent Gateway (UAG).",
   "main": "lib/index.js",
@@ -26,6 +26,7 @@
     "build:docker": "docker build -t formio/uag$(node -p \"require('./package.json').version.includes('-rc.') ? ':rc' : ''\") --platform=linux/amd64 .",
     "test": "tsc --noEmit -p tsconfig.test.json && mocha --no-node-snapshot",
     "test:e2e": "mocha --config .mocharc.e2e.json",
+    "test:getting-started": "mocha --no-config --node-option no-node-snapshot --require dotenv/config --timeout 1800000 test/e2e/layer3.getting-started.e2e.mjs",
     "release": "node scripts/release.mjs",
     "release:version": "node scripts/set-version.mjs",
     "dev": "tsx --no-node-snapshot index.js",
@@ -42,10 +43,9 @@
   "author": "Form.io Developers",
   "license": "MIT",
   "dependencies": {
-    "@formio/appserver": "^2.24.1",
-    "@formio/appserver-core": "^2.24.1",
+    "@formio/appserver": "^2.25.2",
     "@formio/core": "2.9.0",
-    "@formio/uag-sdk": "^2.0.0-rc.3",
+    "@formio/uag-sdk": "^2.0.0-rc.5",
     "@modelcontextprotocol/sdk": "1.32.2",
     "cors": "^2.8.6",
     "debug": "^4.4.3",
@@ -68,20 +68,20 @@
   },
   "devDependencies": {
     "@anthropic-ai/sdk": "^1.3.0",
-    "@formio/js": "5.6.1",
+    "@formio/js": "5.7.0",
     "@types/chai": "^5.2.3",
     "@types/cors": "^2.8.19",
     "@types/debug": "^4.1.13",
     "@types/dotenv": "^8.2.3",
     "@types/express": "^5.0.6",
-    "@types/jsdom": "^30",
+    "@types/jsdom": "^30.0.0",
     "@types/jsonwebtoken": "^9.0.10",
     "@types/lodash": "^4.17.27",
     "@types/mocha": "^10.0.10",
-    "@types/node": "^26.6.5",
+    "@types/node": "^26.6.6",
     "@types/supertest": "^7.2.1",
     "chai": "^6.3.0",
-    "jsdom": "30.1.2",
+    "jsdom": "30.1.3",
     "mocha": "^12.0.3",
     "mongodb-memory-server": "^11.3.0",
     "playwright": "1.64.1",