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

package/bin/uag.js

@@ -37,9 +37,13 @@ function restartWithoutSnapshot() {
 /** 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 { UAGServer, trustProxySetting, usePluginFiles } = require('../lib');
     const server = new UAGServer();
-    if (uagModule) server.use(uagModule);
+    // A module may be exported as a promise (an async module).
+    const resolved = await uagModule;
+    if (resolved) server.use(resolved);
+    // Then the plugins file: UAG_PLUGINS, or the image's /app/plugins/index.mjs.
+    await usePluginFiles(server);
     const app = Express();
     // Behind a reverse proxy, its forwarded headers give the public URL (TRUST_PROXY).
     const trust = trustProxySetting(process.env.TRUST_PROXY);

package/lib/UAGFormInterface.d.ts

@@ -191,5 +191,17 @@ export declare class UAGFormInterface extends FormInterface implements FormflowF
         path: string;
         label: string;
     }[];
+    /**
+     * A value an agent engine generated, before it is checked and written: HTML
+     * for a rich text field is reduced to the markup its editor keeps.
+     */
+    formflowNormalizeValue(component: Component, value: any): any;
+    /**
+     * A value an MCP client writes at a data path (collect_field_data,
+     * confirm_form_submission, submit_completed_form, submission_update), as
+     * an engine's is: HTML for a rich text field is reduced to the markup its
+     * editor keeps. Row indices are ignored to find the component.
+     */
+    normalizeWrittenValue(path: string, value: any): any;
     htmlToMarkdown(html: string): string;
 }

package/lib/UAGFormInterface.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.UAGFormInterface = void 0;
 const appserver_1 = require("@formio/appserver");
 const formflow_1 = require("./formflow");
+const richText_1 = require("./richText");
 const core_1 = require("@formio/core");
 const lodash_1 = require("lodash");
 const node_html_markdown_1 = require("node-html-markdown");
@@ -235,8 +236,12 @@ class UAGFormInterface extends appserver_1.FormInterface {
             case 'signature':
                 rule += 'Have the user draw their signature. The value will be a base64-encoded PNG image string of that signature.';
                 break;
-            case 'textfield':
             case 'textarea':
+                rule += (0, richText_1.isRichText)(component)
+                    ? richText_1.RICH_TEXT_RULE
+                    : 'The value can be any alphanumeric string, containing letters, numbers, white space characters, and common symbols.';
+                break;
+            case 'textfield':
             case 'hidden':
                 rule += 'The value can be any alphanumeric string, containing letters, numbers, white space characters, and common symbols.';
                 break;
@@ -596,7 +601,7 @@ class UAGFormInterface extends appserver_1.FormInterface {
             else if (value && this.isMultiple(comp) && typeof value === 'string') {
                 value = value.split(',').map((v) => v.trim());
             }
-            (0, lodash_1.set)(submission.data, path, value);
+            (0, lodash_1.set)(submission.data, path, this.normalizeWrittenValue(path, value));
         }
         return submission;
     }
@@ -621,7 +626,12 @@ class UAGFormInterface extends appserver_1.FormInterface {
             }
             else if (this.inputComponent(component) && (0, core_1.componentHasValue)(component, value)) {
                 const modelType = core_1.Utils.getModelType(component);
-                if ((0, lodash_1.isObjectLike)(value)) {
+                if ((0, formflow_1.isBinaryComponent)(component)) {
+                    // Files and signatures are described, never inlined: a base64 upload would fill the context.
+                    const described = (0, formflow_1.describeBinary)(component, value);
+                    value = (0, lodash_1.isObjectLike)(described) ? JSON.stringify(described) : described;
+                }
+                else if ((0, lodash_1.isObjectLike)(value)) {
                     value = JSON.stringify(value);
                 }
                 else if (modelType === 'string' && (0, lodash_1.isString)(value)) {
@@ -670,6 +680,23 @@ class UAGFormInterface extends appserver_1.FormInterface {
     formflowLabeledData(data = {}) {
         return this.formatData(data).map(({ path, label }) => ({ path, label }));
     }
+    /**
+     * A value an agent engine generated, before it is checked and written: HTML
+     * for a rich text field is reduced to the markup its editor keeps.
+     */
+    formflowNormalizeValue(component, value) {
+        return (0, richText_1.isRichText)(component) && typeof value === 'string' ? (0, richText_1.sanitizeRichText)(value) : value;
+    }
+    /**
+     * A value an MCP client writes at a data path (collect_field_data,
+     * confirm_form_submission, submit_completed_form, submission_update), as
+     * an engine's is: HTML for a rich text field is reduced to the markup its
+     * editor keeps. Row indices are ignored to find the component.
+     */
+    normalizeWrittenValue(path, value) {
+        const component = this.getComponent(String(path).replace(/\[\d+\]/g, ''));
+        return component ? this.formflowNormalizeValue(component, value) : value;
+    }
     htmlToMarkdown(html) {
         return node_html_markdown_1.NodeHtmlMarkdown.translate(html, {
             bulletMarker: '-',

package/lib/UAGProjectInterface.d.ts

@@ -1,11 +1,12 @@
 import { ProjectInterface, SubmissionRequest } from "@formio/appserver";
-import { EngineRegistry, FormflowConfig, FormflowForm, FormflowHost, FormflowTool, ScopedTokenClaims } from "./formflow";
+import { EngineRegistry, FormflowConfig, FormflowFileReader, FormflowForm, FormflowHost, FormflowTool, ScopedTokenClaims } from "./formflow";
 import { UAGConfig } from "./config";
 import { Form } from "@formio/core";
 import { NextFunction, Response, Router } from "express";
 import { UAGFormInterface } from "./UAGFormInterface";
 import { ResponseTemplate, UAGTemplate } from "./template";
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { PluginRegistry } from "@formio/appserver";
 export declare class UAGProjectInterface extends ProjectInterface implements FormflowHost {
     user: any;
     /** The names of the UAG forms the project currently has. */
@@ -38,6 +39,13 @@ export declare class UAGProjectInterface extends ProjectInterface implements For
     formflowConfig(): FormflowConfig;
     /** A form tagged "uag", or null. */
     formflowForm(name: string): Promise<FormflowForm | null>;
+    /** The server's plugin registry, once its plugins are listed. */
+    plugins?: PluginRegistry;
+    /**
+     * Readers for uploaded documents: one built from the installed converters,
+     * which reads every type with a route to text.
+     */
+    formflowFileReaders(): FormflowFileReader[];
     /** Every MCP tool, as Agentic Formflow tools. */
     formflowTools(): Promise<FormflowTool[]>;
     authorizeRequest(req: SubmissionRequest, res: Response, next: NextFunction): Promise<void | Response<any, Record<string, any>>>;

package/lib/UAGProjectInterface.js

@@ -15,6 +15,7 @@ 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 readers_1 = require("./documents/readers");
 const tools_1 = require("./agent/tools");
 const debug = require('debug')('formio:uag:UAGProjectInterface');
 class UAGProjectInterface extends appserver_1.ProjectInterface {
@@ -52,12 +53,15 @@ class UAGProjectInterface extends appserver_1.ProjectInterface {
             server.registerTool(tool.name, {
                 title: tool.title,
                 description: tool.description,
-                inputSchema: tool.inputSchema,
+                // Always a schema, even an empty one: the MCP SDK calls a tool
+                // registered without one as `execute(extra)`, and every tool is
+                // `execute(args, extra)`, as Agent API research calls it.
+                inputSchema: tool.inputSchema || {},
                 // Carries readOnly/destructive/idempotent/openWorld through to the
                 // client. Tools from config.tools may omit them, so this stays
                 // conditional rather than sending `annotations: undefined`.
                 ...(tool.annotations && { annotations: tool.annotations })
-            }, tool.execute);
+            }, (args, extra) => (0, tools_1.runTool)(tool, this, args, extra));
         }
         // A scoped token that allows no tools must still answer tools/list, with
         // an empty list: clients list tools first,
@@ -121,9 +125,16 @@ class UAGProjectInterface extends appserver_1.ProjectInterface {
         const form = await this.getForm(name);
         return form?.uag ? form : null;
     }
+    /**
+     * Readers for uploaded documents: one built from the installed converters,
+     * which reads every type with a route to text.
+     */
+    formflowFileReaders() {
+        return this.plugins ? [(0, readers_1.converterFileReader)(this.plugins)] : [];
+    }
     /** Every MCP tool, as Agentic Formflow tools. */
     async formflowTools() {
-        return (await (0, tools_1.allTools)(this)).map(tools_1.formflowTool);
+        return (await (0, tools_1.allTools)(this)).map((tool) => (0, tools_1.formflowTool)(tool, this));
     }
     async authorizeRequest(req, res, next) {
         try {

package/lib/agent/anonymous.js

@@ -76,7 +76,7 @@ function anonymousGate(project) {
         const form = request.form;
         const limits = anonymousLimits(project);
         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' });
+            return res.status(401).json({ error: 'Sign in to use this form\'s agent operations and routes.', code: 'sign_in_required' });
         }
         const taken = limiterFor(project).take(String(req.ip || req.socket?.remoteAddress || ''), limits);
         if (!taken.allowed) {

package/lib/agent/engines.d.ts

@@ -4,6 +4,16 @@ import { EngineRegistry } from '../formflow';
 export declare const UAG_ROOT: string;
 /** Engine types every UAG has, whatever is installed. */
 export declare const BUILT_IN_ENGINES: Record<string, EngineTypeDefinition>;
+/** What is known of each loaded engine type, by type name: for listing it as a plugin. */
+export type LoadedEngineType = {
+    name: string;
+    title: string;
+    version?: string;
+    kinds: ('decision' | 'agent')[];
+    instances: string[];
+};
+/** The engine types a registry's instances were created from, in order of first use. */
+export declare function engineTypesOf(registry: EngineRegistry | undefined): LoadedEngineType[];
 /**
  * Enable the engines the configuration names (`engines`), or else
  * `UAG_ENGINES`. Each type is resolved from the configuration's `engineTypes`,

package/lib/agent/engines.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BUILT_IN_ENGINES = exports.UAG_ROOT = void 0;
+exports.engineTypesOf = engineTypesOf;
 exports.loadUAGEngines = loadUAGEngines;
 const path_1 = __importDefault(require("path"));
 const uag_sdk_1 = require("@formio/uag-sdk");
@@ -19,6 +20,11 @@ exports.BUILT_IN_ENGINES = {
     'stub-decision': stubs_1.StubDecisionEngine,
     'stub-agent': stubs_1.StubAgentEngine,
 };
+const loadedTypes = new WeakMap();
+/** The engine types a registry's instances were created from, in order of first use. */
+function engineTypesOf(registry) {
+    return (registry && loadedTypes.get(registry)) || [];
+}
 /**
  * Enable the engines the configuration names (`engines`), or else
  * `UAG_ENGINES`. Each type is resolved from the configuration's `engineTypes`,
@@ -33,5 +39,13 @@ async function loadUAGEngines(config = {}, env = process.env) {
         config,
         apiVersion: appserver_1.Formflow.ENGINE_API_VERSION,
     });
-    return appserver_1.Formflow.engineRegistry(loaded);
+    const registry = appserver_1.Formflow.engineRegistry(loaded);
+    const types = new Map();
+    for (const entry of loaded) {
+        const type = types.get(entry.type) || { name: entry.type, title: entry.title || entry.type, version: entry.typeVersion || entry.version, kinds: entry.kinds || [entry.engine.kind], instances: [] };
+        type.instances.push(entry.engine.name);
+        types.set(entry.type, type);
+    }
+    loadedTypes.set(registry, [...types.values()]);
+    return registry;
 }

package/lib/agent/errors.d.ts

@@ -3,6 +3,15 @@ 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.";
+/**
+ * An error as the Agent API answers it: its status, and the body. Errors with
+ * a status (FormflowError) keep their message and code; anything else is a 500
+ * with no detail. Agent operations and module routes share it.
+ */
+export declare function agentError(requestId: string, err: any): {
+    status: number;
+    body: Record<string, any>;
+};
 /** 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. */

package/lib/agent/errors.js

@@ -3,11 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.INTERNAL_ERROR = void 0;
 exports.isAgentApiRequest = isAgentApiRequest;
 exports.errorCode = errorCode;
+exports.agentError = agentError;
 exports.requestIdOf = requestIdOf;
 exports.errorBody = errorBody;
 exports.agentErrorShape = agentErrorShape;
 const crypto_1 = require("crypto");
 const protocol_1 = require("@formio/uag-sdk/protocol");
+const formflow_1 = require("../formflow");
 /**
  * The Agent API's one error shape. Every error a form's agent operation or
  * `/agent/capabilities` answers is JSON
@@ -42,6 +44,24 @@ function errorCode(status) {
     }
 }
 exports.INTERNAL_ERROR = 'The request failed. See the UAG logs for this request id.';
+/**
+ * An error as the Agent API answers it: its status, and the body. Errors with
+ * a status (FormflowError) keep their message and code; anything else is a 500
+ * with no detail. Agent operations and module routes share it.
+ */
+function agentError(requestId, err) {
+    const known = err instanceof formflow_1.FormflowError;
+    const status = known ? err.status : 500;
+    return {
+        status,
+        body: {
+            requestId,
+            error: status === 500 ? exports.INTERNAL_ERROR : String(err?.message || exports.INTERNAL_ERROR),
+            code: (known && err.code) || errorCode(status),
+            ...(err?.edition && { edition: err.edition })
+        }
+    };
+}
 /** 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;

package/lib/agent/index.d.ts

@@ -1,4 +1,4 @@
-export { StubAgentEngine, StubDecisionEngine } from './stubs';
+export { StubAgentEngine, StubDecisionEngine, stubGenerateRequests } from './stubs';
 export { BUILT_IN_ENGINES, UAG_ROOT, loadUAGEngines } from './engines';
 export { AgentRouter, FormAgentRouter, agentCredentials, agentNotFound } from './router';
 export { RemoteEngine, MIN_KEY_LENGTH } from './remote';

package/lib/agent/index.js

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MIN_KEY_LENGTH = exports.RemoteEngine = exports.agentNotFound = exports.agentCredentials = exports.FormAgentRouter = exports.AgentRouter = exports.loadUAGEngines = exports.UAG_ROOT = exports.BUILT_IN_ENGINES = exports.StubDecisionEngine = exports.StubAgentEngine = void 0;
+exports.MIN_KEY_LENGTH = exports.RemoteEngine = exports.agentNotFound = exports.agentCredentials = exports.FormAgentRouter = exports.AgentRouter = exports.loadUAGEngines = exports.UAG_ROOT = exports.BUILT_IN_ENGINES = exports.stubGenerateRequests = exports.StubDecisionEngine = exports.StubAgentEngine = void 0;
 var stubs_1 = require("./stubs");
 Object.defineProperty(exports, "StubAgentEngine", { enumerable: true, get: function () { return stubs_1.StubAgentEngine; } });
 Object.defineProperty(exports, "StubDecisionEngine", { enumerable: true, get: function () { return stubs_1.StubDecisionEngine; } });
+Object.defineProperty(exports, "stubGenerateRequests", { enumerable: true, get: function () { return stubs_1.stubGenerateRequests; } });
 var engines_1 = require("./engines");
 Object.defineProperty(exports, "BUILT_IN_ENGINES", { enumerable: true, get: function () { return engines_1.BUILT_IN_ENGINES; } });
 Object.defineProperty(exports, "UAG_ROOT", { enumerable: true, get: function () { return engines_1.UAG_ROOT; } });

package/lib/agent/remote.d.ts

@@ -25,6 +25,8 @@ type Connection = {
     baseUrl: string;
     key: string;
     fetch: Fetch;
+    /** The most PDF bytes one generate request may send: documents.maxTotalBytes. */
+    maxDocumentBytes: number;
 };
 /**
  * Describe the remote engine, retrying while the engine server is unreachable
@@ -39,7 +41,9 @@ export declare function describeRemote(connection: Connection, engine: string, {
 /** An engine object for a described remote engine. */
 export declare function remoteEngine(connection: Connection, remoteName: string, described: RemoteEngineDescription): DecisionEngine | AgentEngine;
 export declare const RemoteEngine: Readonly<{
-    type: string;
+    type: "engine";
+    name: string;
+    title: string;
     kinds: ("agent" | "decision")[];
     apiVersion: 1;
     description: string;

package/lib/agent/remote.js

@@ -158,12 +158,13 @@ function remoteEngine(connection, remoteName, described) {
             },
         };
     }
-    return {
+    const agent = {
         name: connection.name,
         kind: 'agent',
         apiVersion: uag_sdk_1.ENGINE_API_VERSION,
         model: described.model,
         toolUse: described.toolUse === true,
+        accepts: described.accepts || ['text'],
         async extract(request) {
             const research = !!request.tools?.length;
             // The engine server researches through its own MCP connection to the
@@ -182,9 +183,30 @@ function remoteEngine(connection, remoteName, described) {
             return { ...response, model: response.model || described.model };
         },
     };
+    if (described.generate) {
+        agent.generate = async (request) => {
+            // Refused before anything is sent; the documents are never logged.
+            if ((0, protocol_1.pdfByteLength)(request.attachments) > connection.maxDocumentBytes) {
+                throw new uag_sdk_1.EngineError(`The attached PDFs exceed ${connection.maxDocumentBytes} bytes, the most one request to the engine server may carry.`);
+            }
+            const body = {
+                instructions: request.instructions,
+                ...(request.system !== undefined && { system: request.system }),
+                attachments: (0, protocol_1.encodeAttachments)(request.attachments),
+                format: request.format,
+                ...(request.maxTokens !== undefined && { maxTokens: request.maxTokens }),
+            };
+            const response = valid(protocol_1.checkGenerateResponse, await call(connection, `${path}/generate`, body, request.signal));
+            request.onProgress?.(response.text.length);
+            return { ...response, model: response.model || described.model };
+        };
+    }
+    return agent;
 }
 exports.RemoteEngine = (0, uag_sdk_1.defineEngine)({
-    type: 'remote',
+    type: 'engine',
+    name: 'remote',
+    title: 'Remote engine (engine server)',
     kinds: ['decision', 'agent'],
     apiVersion: uag_sdk_1.ENGINE_API_VERSION,
     description: 'An engine hosted by an engine server, over the remote engine protocol.',
@@ -216,6 +238,7 @@ exports.RemoteEngine = (0, uag_sdk_1.defineEngine)({
             baseUrl: url.href.replace(/\/+$/, ''),
             key: settings.key,
             fetch: options.fetch || fetch,
+            maxDocumentBytes: Math.min(Number(config?.documents?.maxTotalBytes) || protocol_1.MAX_DOCUMENT_BYTES, protocol_1.MAX_DOCUMENT_BYTES),
         };
         const remoteName = settings.engine || name;
         const described = await describeRemote(connection, remoteName, {

package/lib/agent/router.d.ts

@@ -1,7 +1,36 @@
-import { RequestHandler, Router } from "express";
+import { NextFunction, Request, RequestHandler, Response, Router } from "express";
+import { SubmissionRequest } from "@formio/appserver";
+import { FormflowService } from "../formflow";
 import type { UAGProjectInterface } from "../UAGProjectInterface";
-/** The largest request body an agent operation takes, in bytes. */
+/**
+ * The Agent API: HTTP adapters onto Agentic Formflow in @formio/appserver-core.
+ * Each endpoint reads its request, calls the service, and writes JSON (or, for
+ * extract, a Server-Sent Events stream). Errors answer with the status the
+ * service gives.
+ *
+ * The operations belong to a form, `{form}/agent/{operation}`, as its
+ * submissions do: the form comes from the URL and the caller from the
+ * project's own authentication. Capabilities describe the deployment, at
+ * `/agent/capabilities`.
+ */
+type AgentRequest = SubmissionRequest & {
+    requestId: string;
+};
+/** The largest request body an agent operation takes by default, in bytes. */
 export declare const AGENT_BODY_LIMIT: number;
+/**
+ * The largest request body the project's agent operations take: `agentApi.bodyLimit`,
+ * then AGENT_BODY_LIMIT, then 5 MB. A document sent inline (a base64 file a task reads)
+ * may need more; the server's own MAX_BODY_SIZE (16 MB) still applies first.
+ */
+export declare function agentBodyLimit(project: UAGProjectInterface): number;
+type Handler = (req: AgentRequest, res: Response, service: FormflowService) => Promise<void>;
+/** The parts every Agent API endpoint shares: the request id, and errors answered as JSON (or as an event mid-stream). */
+export declare function agentEndpoints(project: UAGProjectInterface): {
+    json: (req: Request, res: Response, next: NextFunction) => void | Response<any, Record<string, any>>;
+    requestId: (req: any, res: Response, next: NextFunction) => void;
+    handle: (operation: string, fn: Handler) => (req: Request, res: Response) => Promise<void>;
+};
 /**
  * `GET /agent/capabilities`, behind `authenticate`. Only this path is claimed:
  * any other `/agent...` path (a project form at `agent`, for one) falls through
@@ -29,3 +58,4 @@ export declare function agentCredentials(project: UAGProjectInterface): RequestH
  * form of the URL.
  */
 export declare function FormAgentRouter(project: UAGProjectInterface, credentials: RequestHandler): Router;
+export {};

package/lib/agent/router.js

@@ -34,6 +34,8 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AGENT_BODY_LIMIT = void 0;
+exports.agentBodyLimit = agentBodyLimit;
+exports.agentEndpoints = agentEndpoints;
 exports.AgentRouter = AgentRouter;
 exports.agentNotFound = agentNotFound;
 exports.agentCredentials = agentCredentials;
@@ -107,19 +109,29 @@ async function respondWithStream(req, res, run) {
         res.json(done);
     }
 }
-/** The largest request body an agent operation takes, in bytes. */
+/** The largest request body an agent operation takes by default, in bytes. */
 exports.AGENT_BODY_LIMIT = 5 * 1024 * 1024;
+/**
+ * The largest request body the project's agent operations take: `agentApi.bodyLimit`,
+ * then AGENT_BODY_LIMIT, then 5 MB. A document sent inline (a base64 file a task reads)
+ * may need more; the server's own MAX_BODY_SIZE (16 MB) still applies first.
+ */
+function agentBodyLimit(project) {
+    const configured = Number(project.config?.agentApi?.bodyLimit ?? process.env.AGENT_BODY_LIMIT);
+    return Number.isFinite(configured) && configured > 0 ? configured : exports.AGENT_BODY_LIMIT;
+}
 /** The parts every Agent API endpoint shares: the request id, and errors answered as JSON (or as an event mid-stream). */
 function agentEndpoints(project) {
-    const parse = express_1.default.json({ limit: exports.AGENT_BODY_LIMIT });
+    const limit = agentBodyLimit(project);
+    const parse = express_1.default.json({ limit });
     // The server parses JSON bodies first, with its own larger limit, so the
     // agent operations' limit is checked here on a body already read.
     const json = (req, res, next) => {
         if (req.body === undefined)
             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.`, code: 'payload_too_large' });
+        if (length > limit) {
+            return res.status(413).json({ error: `The request body is larger than the agent operations' limit of ${Math.round(limit / (1024 * 1024) * 10) / 10} MB.`, code: 'payload_too_large' });
         }
         next();
     };
@@ -139,19 +151,13 @@ function agentEndpoints(project) {
             await (0, requestId_1.withRequestId)(agentReq.requestId, () => fn(agentReq, res, service));
         }
         catch (err) {
-            const status = err instanceof formflow_1.FormflowError ? err.status : 500;
+            const { status, body } = (0, errors_1.agentError)(agentReq.requestId, err);
             if (status === 500) {
                 debug(`[${agentReq.requestId}] ${operation} failed:`, err);
             }
             if (err instanceof formflow_1.RateLimitError) {
                 res.set('Retry-After', String(Math.ceil(err.retryAfterMs / 1000)));
             }
-            const body = {
-                requestId: agentReq.requestId,
-                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) {
                 // Mid-stream: report the failure as an event and close.
                 res.write(`event: error\ndata: ${JSON.stringify(body)}\n\n`);

package/lib/agent/stubs.d.ts

@@ -1,3 +1,4 @@
+import type { GenerateRequest } from '@formio/uag-sdk';
 /**
  * Stand-in engines for tests and local development. They answer instantly with
  * predictable values, so the Agent API can be exercised end to end without
@@ -6,7 +7,9 @@
  * any instance name.
  */
 export declare const StubDecisionEngine: Readonly<{
-    type: string;
+    type: "engine";
+    name: string;
+    title: string;
     kinds: "decision"[];
     apiVersion: 1;
     description: string;
@@ -14,8 +17,16 @@ export declare const StubDecisionEngine: Readonly<{
         calls: number;
     };
 }>;
+/** How many generate requests the stub agent engines keep: a UAG running them for a demo never grows without bound. */
+export declare const STUB_GENERATE_REQUESTS_KEPT = 20;
+/** The last generate requests the stub agent engines received (STUB_GENERATE_REQUESTS_KEPT), oldest first, for tests. */
+export declare const stubGenerateRequests: Array<Omit<GenerateRequest, 'signal' | 'onProgress'> & {
+    engine: string;
+}>;
 export declare const StubAgentEngine: Readonly<{
-    type: string;
+    type: "engine";
+    name: string;
+    title: string;
     kinds: "agent"[];
     apiVersion: 1;
     description: string;

package/lib/agent/stubs.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.StubAgentEngine = exports.StubDecisionEngine = void 0;
+exports.StubAgentEngine = exports.stubGenerateRequests = exports.STUB_GENERATE_REQUESTS_KEPT = exports.StubDecisionEngine = void 0;
 const uag_sdk_1 = require("@formio/uag-sdk");
 const formflow_1 = require("../formflow");
 /**
@@ -11,16 +11,29 @@ const formflow_1 = require("../formflow");
  * any instance name.
  */
 exports.StubDecisionEngine = (0, uag_sdk_1.defineEngine)({
-    type: 'stub-decision',
+    type: 'engine',
+    name: 'stub-decision',
+    title: 'Stub decision engine',
     kinds: ['decision'],
     apiVersion: uag_sdk_1.ENGINE_API_VERSION,
     description: 'Answers every decision with a fixed, predictable value. For tests and local development.',
     create: ({ name }) => (0, formflow_1.stubDecisionEngine)({ name }),
 });
+/** How many generate requests the stub agent engines keep: a UAG running them for a demo never grows without bound. */
+exports.STUB_GENERATE_REQUESTS_KEPT = 20;
+/** The last generate requests the stub agent engines received (STUB_GENERATE_REQUESTS_KEPT), oldest first, for tests. */
+exports.stubGenerateRequests = [];
 exports.StubAgentEngine = (0, uag_sdk_1.defineEngine)({
-    type: 'stub-agent',
+    type: 'engine',
+    name: 'stub-agent',
+    title: 'Stub agent engine',
     kinds: ['agent'],
     apiVersion: uag_sdk_1.ENGINE_API_VERSION,
-    description: 'Extracts nothing. For tests and local development.',
-    create: ({ name }) => (0, formflow_1.stubAgentEngine)({ name }),
+    description: 'Extracts nothing; generates a predictable answer from the text it is given. For tests and local development.',
+    // Text only; its generate answer shows what reached it. Observing its requests keeps it a built-in stub.
+    create: ({ name }) => (0, formflow_1.stubAgentEngine)({ name, onGenerate: (request) => {
+            exports.stubGenerateRequests.push({ ...request, engine: name });
+            if (exports.stubGenerateRequests.length > exports.STUB_GENERATE_REQUESTS_KEPT)
+                exports.stubGenerateRequests.splice(0, exports.stubGenerateRequests.length - exports.STUB_GENERATE_REQUESTS_KEPT);
+        } }),
 });

package/lib/agent/tools.d.ts

@@ -1,10 +1,31 @@
 import { FormflowTool } from "../formflow";
+import type { AuthRequest } from "@formio/appserver";
 import type { UAGProjectInterface } from "../UAGProjectInterface";
-import { ToolInfo } from "../tools/utils";
-/** Every tool the UAG serves, including custom tools from configuration. */
+import { ToolEntry, ToolInfo } from "../tools/utils";
+/** Record the module a tool came from: its `execute` gets the module's API as `extra.module`. */
+export declare function setToolModule(entry: object, api: any): void;
+/**
+ * A `config.tools` entry as a tool for the project: a bound tool's static
+ * fields, overlaid with what its `bind(project)` returns. A tool without
+ * `bind` (the 1.x shape) is used as it is.
+ */
+export declare function resolveTool(project: UAGProjectInterface, entry: ToolEntry): Promise<ToolInfo | undefined>;
+/**
+ * Every tool the UAG serves, including custom tools from configuration, each
+ * entry of which is a tool, optionally bound to the project.
+ */
 export declare function allTools(project: UAGProjectInterface): Promise<ToolInfo[]>;
+/**
+ * Run a tool with its arguments and the `ToolExtra` for the project: the same
+ * call on `/mcp` and for Agent API research. `context` is whatever else the
+ * caller has (on `/mcp`, the MCP SDK's request context, with `authInfo`).
+ */
+export declare function runTool(tool: ToolInfo, project: UAGProjectInterface, args: any, context: {
+    authInfo: AuthRequest;
+    [key: string]: any;
+}): any;
 /**
  * An MCP tool as an Agentic Formflow tool: its schema as JSON, its arguments
  * validated with its own schema, and read-only only when annotated so.
  */
-export declare function formflowTool(tool: ToolInfo): FormflowTool;
+export declare function formflowTool(tool: ToolInfo, project: UAGProjectInterface): FormflowTool;