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

package/lib/index.js

@@ -17,7 +17,7 @@ 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.UAGFormInterface = exports.UAGProjectInterface = exports.RICH_TEXT_RULE = exports.RICH_TEXT_TAGS = exports.isRichText = exports.sanitizeRichText = exports.DEFAULT_PLUGINS_FILE = exports.pluginsFile = exports.usePluginFiles = exports.sanitizeMarkdown = exports.UAGServer = void 0;
 exports.assertSingleCore = assertSingleCore;
 exports.assertNodeSnapshotDisabled = assertNodeSnapshotDisabled;
 const appserver_1 = require("@formio/appserver");
@@ -37,18 +37,26 @@ const actionLogs_1 = require("./actionLogs");
 const runner_1 = require("./runner");
 const runTask_1 = require("./actions/runTask");
 const version_1 = require("./version");
+const utils_1 = require("./tools/utils");
+const plugins_1 = require("./plugins");
+const plugins_2 = require("./documents/plugins");
+const uagJs_1 = require("./documents/uagJs");
+const modules_1 = require("./modules");
+const tools_1 = require("./agent/tools");
+/** Projects whose engines were loaded while the plugins were listed. */
+const enginesLoaded = new WeakSet();
 const debug = require('debug')('formio:uag');
 /**
- * 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.
+ * Agentic Formflow keeps its license state inside @formio/appserver-core, and
+ * modules are built on its module framework. The UAG loads it only through
+ * @formio/appserver, so the two always share one copy, which must be 2.26.0 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(version = appserverCoreVersion()) {
-    const [major, minor, patch] = version.split('.').map((part) => parseInt(part, 10) || 0);
-    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.`);
+    const [major, minor] = version.split('.').map((part) => parseInt(part, 10) || 0);
+    if (major < 2 || (major === 2 && minor < 26)) {
+        throw new Error(`@formio/uag needs @formio/appserver-core 2.26.0 or later, through @formio/appserver; ${version} is installed. Upgrade @formio/appserver.`);
     }
 }
 /** The version of the @formio/appserver-core that @formio/appserver loads. */
@@ -103,6 +111,53 @@ function databaseFromEnv(env = process.env) {
     };
 }
 class UAGServer extends appserver_1.Server {
+    /**
+     * Use a module, or a list of modules (each in turn). A module used twice (by
+     * its `name`) is used once. `config.tools` adds up across modules; an MCP
+     * tool or engine type that two modules define stops startup, naming both.
+     * A route's `rateLimit` is the default for its name, unless the operator set one.
+     */
+    use(module, source) {
+        module = appserver_1.Server.defaultExport(module);
+        if (module && typeof module === 'object' && !Array.isArray(module) && module.uag !== undefined) {
+            const label = source || (typeof module.name === 'string' && module.name) || 'a module';
+            throw new Error(`The module ${label} has a "uag" key, which UAG modules no longer use: move its keys (name, apiVersion, settings, routes, components, initialize) onto the module itself.`);
+        }
+        super.use(module, source);
+        if (typeof module?.name === 'string' && this.modules.get(module.name)?.definition === module)
+            this.routeRateLimits(module);
+    }
+    /** MCP tools and engine types, which only one module may define. */
+    moduleClaims(definition) {
+        return [
+            ...(definition.config?.tools || []).filter((tool) => tool?.name).map((tool) => `MCP tool "${tool.name}"`),
+            ...Object.keys(definition.config?.engineTypes || {}).map((name) => `engine type "${name}"`)
+        ];
+    }
+    /**
+     * MCP tools add up across modules (lodash would merge them index by index),
+     * and a named module's tools get its API as `extra.module`. Its routes'
+     * `rateLimit`s become the defaults for their names.
+     */
+    mergeModuleConfig(config, module) {
+        const { tools, ...rest } = config;
+        super.mergeModuleConfig(rest, module);
+        if (Array.isArray(tools) && tools.length) {
+            if (module)
+                for (const tool of tools)
+                    (0, tools_1.setToolModule)(tool, this.modules.apiFor(module));
+            this.config.tools = [...(this.config.tools || []), ...tools];
+        }
+    }
+    /** Route rate-limit defaults, for the names the operator left unset. */
+    routeRateLimits(module) {
+        for (const route of Object.values(module?.routes?.form || {})) {
+            const name = route?.name || module.name;
+            if (!route?.rateLimit || (0, lodash_1.get)(this.config, ['agentApi', 'rateLimits', 'caller', name]))
+                continue;
+            (0, lodash_1.set)(this.config, ['agentApi', 'rateLimits', 'caller', name], route.rateLimit);
+        }
+    }
     constructor(config) {
         assertNodeSnapshotDisabled();
         assertSingleCore();
@@ -135,8 +190,16 @@ class UAGServer extends appserver_1.Server {
             // 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()
+            database: databaseFromEnv(),
+            // Modules an operator turns off, such as one an image includes.
+            modules: { disabled: (0, lodash_1.get)(process.env, 'MODULES_DISABLED', '').toString().split(',').map((name) => name.trim()).filter(Boolean) }
         }));
+        // The server's own MCP tools and engine types: a module may not define them again.
+        for (const tool of (this.config.tools || []))
+            if (tool?.name)
+                this.modules.claim(`MCP tool "${tool.name}"`, "the server's configuration");
+        for (const name of Object.keys(this.config.engineTypes || {}))
+            this.modules.claim(`engine type "${name}"`, "the server's configuration");
         // MONGO is the UAG's own database, not a database for the appserver to keep
         // submissions in: Form.io stores those.
         if (!configuredDb && this.module.db) {
@@ -219,12 +282,20 @@ class UAGServer extends appserver_1.Server {
      * route keeps Form.io's plain-text answer.
      */
     sendError(req, res, status, message, err) {
-        if (!(0, errors_1.isAgentApiRequest)(req))
+        if (!(0, errors_1.isAgentApiRequest)(req) && !this.isModuleRouteRequest(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 })));
     }
+    /** Whether a request is for a module's form route: its method, and a path ending in the route's. */
+    isModuleRouteRequest(req) {
+        const path = String(req.path || '').toLowerCase().replace(/\/+$/, '');
+        return this.modules.list.some((module) => Object.keys(module.definition.routes?.form || {}).some((key) => {
+            const [method, route] = key.split(' ');
+            return req.method === method && path.endsWith(String(route).toLowerCase().replace(/\/+$/, ''));
+        }));
+    }
     /** Browsers reading Agent API responses need the request id too. */
     get exposedHeaders() {
         return [...super.exposedHeaders, 'X-Request-Id'];
@@ -240,7 +311,11 @@ class UAGServer extends appserver_1.Server {
      * on the form's own routes.
      */
     async extendRouter(router) {
+        // A bare function in config.tools (the unreleased factory form) stops startup.
+        (0, utils_1.assertToolEntries)(this.config.tools);
         await super.extendRouter(router);
+        // @formio/uag-js, the portal script and stylesheet: public, ahead of the project routes.
+        router.use((0, uagJs_1.uagJsRouter)(() => this.plugins, () => this.modules.components()));
         const uagProject = this.uagProject;
         if (uagProject) {
             // First: the Agent API's request id and one error shape, for every refusal after it.
@@ -252,6 +327,52 @@ class UAGServer extends appserver_1.Server {
             router.use((0, actionLogs_1.ActionLogRouter)(uagProject));
         }
     }
+    /**
+     * List the UAG's engines and MCP tools in the plugin registry, beside
+     * appserver-core's form actions. They keep loading their own way.
+     */
+    async listPlugins() {
+        await super.listPlugins();
+        // Converters: the converter type and the built-in converters, for task file inputs, read_document and modules.
+        (0, plugins_2.registerDocuments)(this.plugins);
+        const project = this.uagProject;
+        if (project instanceof UAGProjectInterface_1.UAGProjectInterface)
+            project.plugins = this.plugins;
+        if (project instanceof UAGProjectInterface_1.UAGProjectInterface) {
+            // Decide which engines are on before serving anything, so a misconfigured
+            // engine stops startup with its name in the error instead of failing the
+            // first request.
+            project.engines = await (0, engines_1.loadUAGEngines)(project.config || {}, process.env);
+            enginesLoaded.add(project);
+            (0, plugins_1.listEngines)(this.plugins, project);
+            await (0, plugins_1.listTools)(this.plugins, project);
+        }
+    }
+    /** A form's own route segments, which module routes may not use: appserver's, and the agent operations. */
+    get reservedFormPaths() {
+        return [...super.reservedFormPaths, 'agent'];
+    }
+    /** Module routes may not take the names of the UAG's own rate-limited operations. */
+    get reservedRouteNames() {
+        return modules_1.UAG_OPERATIONS;
+    }
+    get hostName() {
+        return 'uag';
+    }
+    get hostVersion() {
+        return version_1.UAG_VERSION;
+    }
+    /** The module API: appserver's, with the UAG's license check, engines, converters and helpers. */
+    createModuleApi(module) {
+        return (0, modules_1.uagModuleApi)(super.createModuleApi(module), (0, modules_1.serverDeps)(() => this.uagProject));
+    }
+    /** Module routes run behind what the agent operations run behind: the caller check, body limit, request id, rate limits and error shape. */
+    moduleRouteHandlers(project, route, module) {
+        return (0, modules_1.uagRouteHandlers)(project, route.name);
+    }
+    moduleErrorBody(req, err) {
+        return (0, modules_1.uagErrorBody)(req, err);
+    }
     async router() {
         await this.connectDatabase();
         const router = await super.router();
@@ -269,10 +390,11 @@ class UAGServer extends appserver_1.Server {
         }
         // A database of the UAG's own needs the license, on every edition.
         await this.enableDatabase(uagProject);
-        // Decide which engines are on before serving anything, so a misconfigured
-        // engine stops startup with its name in the error instead of failing the
-        // first request.
-        uagProject.engines = await (0, engines_1.loadUAGEngines)(uagProject.config || {}, process.env);
+        // The engines are loaded while the plugins are listed (listPlugins); a
+        // project interface that is not the UAG's own loads them here.
+        if (!enginesLoaded.has(uagProject)) {
+            uagProject.engines = await (0, engines_1.loadUAGEngines)(uagProject.config || {}, process.env);
+        }
         // Say which edition this is, and whether Agentic Formflow will run, so an
         // operator knows before the first request is refused.
         // A failure here only loses the message; it never stops the UAG starting.
@@ -296,5 +418,18 @@ __exportStar(require("@formio/appserver"), exports);
 __exportStar(require("./config"), exports);
 __exportStar(require("./agent"), exports);
 __exportStar(require("./tools"), exports);
+__exportStar(require("./documents"), exports);
+__exportStar(require("./modules"), exports);
+var markdown_1 = require("./markdown");
+Object.defineProperty(exports, "sanitizeMarkdown", { enumerable: true, get: function () { return markdown_1.sanitizeMarkdown; } });
+var pluginFiles_1 = require("./pluginFiles");
+Object.defineProperty(exports, "usePluginFiles", { enumerable: true, get: function () { return pluginFiles_1.usePluginFiles; } });
+Object.defineProperty(exports, "pluginsFile", { enumerable: true, get: function () { return pluginFiles_1.pluginsFile; } });
+Object.defineProperty(exports, "DEFAULT_PLUGINS_FILE", { enumerable: true, get: function () { return pluginFiles_1.DEFAULT_PLUGINS_FILE; } });
 __exportStar(require("./router"), exports);
 __exportStar(require("./template"), exports);
+var richText_1 = require("./richText");
+Object.defineProperty(exports, "sanitizeRichText", { enumerable: true, get: function () { return richText_1.sanitizeRichText; } });
+Object.defineProperty(exports, "isRichText", { enumerable: true, get: function () { return richText_1.isRichText; } });
+Object.defineProperty(exports, "RICH_TEXT_TAGS", { enumerable: true, get: function () { return richText_1.RICH_TEXT_TAGS; } });
+Object.defineProperty(exports, "RICH_TEXT_RULE", { enumerable: true, get: function () { return richText_1.RICH_TEXT_RULE; } });

package/lib/markdown.d.ts

@@ -0,0 +1 @@
+export declare function sanitizeMarkdown(markdown: string): string;

package/lib/markdown.js

@@ -0,0 +1,166 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeMarkdown = sanitizeMarkdown;
+const markdown_it_1 = __importDefault(require("markdown-it"));
+/**
+ * The Markdown contract of AI-generated content: GitHub-flavored Markdown,
+ * UTF-8, `\n` line endings, no code fence around the whole value.
+ *
+ * `sanitizeMarkdown` keeps what the AI Document's renderer shows and nothing
+ * that could act in a browser:
+ * - raw HTML is removed, keeping its text;
+ * - links keep only http, https and mailto targets (others become their text);
+ * - images are dropped;
+ * - a code fence wrapping the whole value is removed;
+ * - trailing whitespace is trimmed and more than two blank lines collapsed.
+ * Code blocks and inline code are kept as they are: the renderer escapes them.
+ *
+ * The result is then parsed as a CommonMark renderer parses it (markdown-it,
+ * with tables and strikethrough). A block still holding raw HTML, an image or a
+ * link to another target (Markdown that line-by-line cleaning misreads, such as
+ * a link whose label holds brackets, or HTML spanning lines) has its `<`, `[`,
+ * `]` and `\` escaped, so it shows as text, until the parse finds none.
+ */
+const SAFE_LINK = /^(https?:|mailto:)/i;
+// Up to three spaces: a tab, or four spaces, begins an indented code block, never a fence.
+const FENCE = /^ {0,3}(`{3,}|~{3,})/;
+/** HTML recognized, so that it is found, and every link target kept, so that it is checked. */
+const parser = new markdown_it_1.default('default', { html: true, linkify: false });
+parser.validateLink = () => true;
+/** The line ranges (from, to: 0-based, end excluded) of blocks holding HTML, an image or a link sanitizeMarkdown never keeps. */
+function unsafeBlocks(markdown) {
+    const ranges = [];
+    let block = null;
+    for (const token of parser.parse(markdown, {})) {
+        if (token.map)
+            block = token.map;
+        if (token.type === 'html_block') {
+            if (token.map)
+                ranges.push(token.map);
+            continue;
+        }
+        if (token.type !== 'inline' || !token.children)
+            continue;
+        const unsafe = token.children.some((child) => child.type === 'html_inline' || child.type === 'image' ||
+            (child.type === 'link_open' && !SAFE_LINK.test(String(child.attrGet('href') || '').trim())));
+        const lines = token.map || block;
+        if (unsafe && lines)
+            ranges.push(lines);
+    }
+    return ranges;
+}
+/** A line whose markup can form no HTML, image or link: its text shows as it is. */
+function escapeLine(line) {
+    return line.replace(/[\\<[\]]/g, (char) => `\\${char}`);
+}
+/** The lines of fenced and indented code blocks, which can hold nothing that acts. */
+function codeLines(markdown) {
+    const lines = new Set();
+    for (const token of parser.parse(markdown, {})) {
+        if ((token.type === 'fence' || token.type === 'code_block') && token.map) {
+            for (let i = token.map[0]; i < token.map[1]; i++)
+                lines.add(i);
+        }
+    }
+    return lines;
+}
+/** Escape the blocks the parse finds unsafe until it finds none; at worst, every line outside code. */
+function escapeUnsafeBlocks(markdown) {
+    let text = markdown;
+    for (let pass = 0; pass < 5; pass++) {
+        const ranges = unsafeBlocks(text);
+        if (!ranges.length)
+            return text;
+        const lines = text.split('\n');
+        for (const [from, to] of ranges) {
+            for (let i = from; i < to && i < lines.length; i++)
+                lines[i] = escapeLine(lines[i]);
+        }
+        text = lines.join('\n');
+    }
+    const code = codeLines(text);
+    text = text.split('\n').map((line, i) => (code.has(i) ? line : escapeLine(line))).join('\n');
+    return unsafeBlocks(text).length ? text.split('\n').map(escapeLine).join('\n') : text;
+}
+/** A whole value wrapped in one code fence: its contents. */
+function unwrapFence(text) {
+    const trimmed = text.trim();
+    const match = /^(`{3,}|~{3,})[^\n]*\n([\s\S]*?)\n?\1\s*$/.exec(trimmed);
+    if (!match)
+        return text;
+    // Only when no other fence of the same kind is inside: then it really is one block.
+    if (new RegExp(`^\\s{0,3}${match[1][0] === '`' ? '`' : '~'}{3,}`, 'm').test(match[2]))
+        return text;
+    return match[2];
+}
+/** Clean the text of one line outside code: HTML, images and unsafe links. */
+function cleanLine(line) {
+    // Inline code spans are kept as they are.
+    const parts = line.split(/(`+[^`]*`+)/);
+    return parts.map((part, i) => {
+        if (i % 2 === 1)
+            return part;
+        let out = part;
+        // Images: dropped, inline and reference style.
+        out = out.replace(/!\[[^\]]*\]\([^)]*\)/g, '').replace(/!\[[^\]]*\]\[[^\]]*\]/g, '');
+        // Links: kept only for safe targets.
+        out = out.replace(/\[([^\]]*)\]\(\s*<?((?:[^()\s<>]|\([^()\s]*\))*)>?(?:\s+"[^"]*")?\s*\)/g, (whole, label, target) => SAFE_LINK.test(target) ? `[${label}](${target})` : label);
+        // Autolinks: <https://...> kept when safe; anything else in angle brackets is HTML.
+        const autolinks = [];
+        out = out.replace(/<([a-z][a-z0-9+.-]*:[^>\s]*)>/gi, (whole, target) => {
+            if (!SAFE_LINK.test(target))
+                return '';
+            autolinks.push(`<${target}>`);
+            return `\u0000${autolinks.length - 1}\u0000`;
+        });
+        // Raw HTML: tags removed, their text kept.
+        out = out.replace(/<!--[\s\S]*?-->/g, '').replace(/<\/?[A-Za-z][^<>]*>/g, '');
+        return out.replace(/\u0000(\d+)\u0000/g, (whole, index) => autolinks[Number(index)]);
+    }).join('');
+}
+function sanitizeMarkdown(markdown) {
+    const text = unwrapFence(String(markdown ?? '').replace(/\r\n?/g, '\n'));
+    const out = [];
+    let fence = null;
+    // HTML blocks spanning several lines (a comment, a script) are removed whole.
+    let inComment = false;
+    for (const raw of text.split('\n')) {
+        let line = raw;
+        const opener = FENCE.exec(line);
+        if (fence) {
+            if (opener && opener[1][0] === fence[0] && opener[1].length >= fence.length && line.trim().replace(/[`~]/g, '') === '')
+                fence = null;
+            out.push(line.replace(/\s+$/, ''));
+            continue;
+        }
+        if (opener) {
+            fence = opener[1];
+            out.push(line.replace(/\s+$/, ''));
+            continue;
+        }
+        if (inComment) {
+            const end = line.indexOf('-->');
+            if (end < 0)
+                continue;
+            line = line.slice(end + 3);
+            inComment = false;
+        }
+        const start = line.indexOf('<!--');
+        if (start >= 0 && line.indexOf('-->', start) < 0) {
+            line = line.slice(0, start);
+            inComment = true;
+        }
+        // Reference definitions with an unsafe target are dropped.
+        const definition = /^\s{0,3}\[[^\]]+\]:\s*<?(\S+?)>?(\s.*)?$/.exec(line);
+        if (definition) {
+            if (SAFE_LINK.test(definition[1]))
+                out.push(line.replace(/\s+$/, ''));
+            continue;
+        }
+        out.push(cleanLine(line).replace(/\s+$/, ''));
+    }
+    return escapeUnsafeBlocks(out.join('\n').replace(/\n{4,}/g, '\n\n\n').trim());
+}

package/lib/modules/api.d.ts

@@ -0,0 +1,22 @@
+import type { ModuleApi } from '@formio/appserver';
+import type { UAGProjectInterface } from '../UAGProjectInterface';
+import type { PluginRegistry } from '@formio/appserver';
+import type { UAGModuleApi } from './types';
+/** What the UAG's members of the module API run on: the server's, or a test kit's. */
+export type UAGModuleApiDeps = {
+    registry(): PluginRegistry;
+    /** The enabled engines: by name, and the agent engines in preference order. */
+    engines(): {
+        get(name: string): any;
+        agent: any[];
+    } | undefined;
+    requireLicense(): Promise<void>;
+    requireAccess?: ModuleApi['requireAccess'];
+};
+/** The server's: its one project, looked up when a member is called. */
+export declare function serverDeps(projectOf: () => UAGProjectInterface | undefined): UAGModuleApiDeps;
+/**
+ * The UAG's module API (version 1): appserver's, with the Agent API's access
+ * check, the license check, converters, engines and helpers, behind stable names.
+ */
+export declare function uagModuleApi(base: ModuleApi, deps: UAGModuleApiDeps): UAGModuleApi;

package/lib/modules/api.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serverDeps = serverDeps;
+exports.uagModuleApi = uagModuleApi;
+const node_html_markdown_1 = require("node-html-markdown");
+const formflow_1 = require("../formflow");
+const markdown_1 = require("../markdown");
+const detect_1 = require("../documents/detect");
+const convert_1 = require("../documents/convert");
+const plugins_1 = require("../documents/plugins");
+const routes_1 = require("../documents/routes");
+async function pageCount(pdf) {
+    try {
+        const { PDFDocument } = require('pdf-lib');
+        return (await PDFDocument.load(pdf, { ignoreEncryption: true, updateMetadata: false })).getPageCount();
+    }
+    catch {
+        return undefined;
+    }
+}
+const readsOf = (engine) => (Array.isArray(engine?.accepts) ? engine.accepts : ['text']);
+/** The server's: its one project, looked up when a member is called. */
+function serverDeps(projectOf) {
+    const project = () => {
+        const found = projectOf();
+        if (!found)
+            throw new formflow_1.FormflowError(503, 'The server is still starting.', 'not_ready');
+        return found;
+    };
+    return {
+        registry: () => {
+            const plugins = project().plugins;
+            if (!plugins)
+                throw new formflow_1.FormflowError(503, 'The server is still starting.', 'not_ready');
+            return plugins;
+        },
+        engines: () => project().formflowEngines(),
+        requireLicense: () => (0, formflow_1.formflow)(project()).requireLicense(),
+        // The Agent API's own check, so a module's refusals read as the agent operations' do.
+        requireAccess: (auth, form, methods) => (0, formflow_1.formflow)(project()).requireAccess(auth, form, methods)
+    };
+}
+/**
+ * The UAG's module API (version 1): appserver's, with the Agent API's access
+ * check, the license check, converters, engines and helpers, behind stable names.
+ */
+function uagModuleApi(base, deps) {
+    const registry = deps.registry;
+    const requireLicense = deps.requireLicense;
+    const api = {
+        ...base,
+        ...(deps.requireAccess && { requireAccess: deps.requireAccess }),
+        requireLicense,
+        converters: {
+            list: () => registry().list('converter'),
+            identify: (buffer, hint) => (0, detect_1.identify)(buffer, hint, registry().list('converter')),
+            route: (type, inputs, pins) => (0, plugins_1.documentsOf)(registry()).routes.route(type, inputs, pins || {}),
+            accept: (inputs) => (0, plugins_1.documentsOf)(registry()).routes.accept(inputs),
+            run: (steps, input, to, options) => (0, convert_1.runRoute)(steps, input, to, {
+                signal: options.signal,
+                log: base.log,
+                settingsOf: (converter) => registry().settings('converter', converter.name)
+            }),
+            stepName: (converter) => (0, routes_1.stepName)(converter)
+        },
+        engines: {
+            select({ name, needs = [] }) {
+                const engines = deps.engines();
+                if (!engines)
+                    throw new formflow_1.FormflowError(503, 'The engines are not loaded yet.', 'not_ready');
+                const capable = (engine) => engine?.kind === 'agent' && typeof engine.generate === 'function' && needs.every((kind) => readsOf(engine).includes(kind));
+                const engine = name ? engines.get(name) : engines.agent.find(capable);
+                if (!engine || !capable(engine)) {
+                    const missing = needs.find((kind) => !engine || !readsOf(engine).includes(kind)) || needs[0] || 'text';
+                    throw new formflow_1.FormflowError(503, name && !engine ? `The engine "${name}" is not enabled.` : `no enabled engine can read ${missing} documents`, 'no_engine');
+                }
+                // A handle, not the engine: generating always goes through the license check.
+                return {
+                    name: engine.name,
+                    model: engine.model,
+                    accepts: readsOf(engine),
+                    async generate(request) {
+                        await requireLicense();
+                        return engine.generate(request);
+                    }
+                };
+            }
+        },
+        markdown: {
+            sanitize: (text) => (0, markdown_1.sanitizeMarkdown)(text),
+            fromHtml: (html) => node_html_markdown_1.NodeHtmlMarkdown.translate(String(html || '')).trim()
+        },
+        pdf: { pageCount },
+        callerKey: (req) => {
+            const key = (0, formflow_1.callerKey)(req.auth);
+            return key === 'anonymous' ? `anonymous:${req.ip || req.socket?.remoteAddress || ''}` : key;
+        }
+    };
+    return api;
+}

package/lib/modules/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types';
+export { uagModuleApi, serverDeps } from './api';
+export type { UAGModuleApiDeps } from './api';
+export { uagRouteHandlers, uagErrorBody } from './routes';

package/lib/modules/index.js

@@ -0,0 +1,24 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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.uagErrorBody = exports.uagRouteHandlers = exports.serverDeps = exports.uagModuleApi = void 0;
+__exportStar(require("./types"), exports);
+var api_1 = require("./api");
+Object.defineProperty(exports, "uagModuleApi", { enumerable: true, get: function () { return api_1.uagModuleApi; } });
+Object.defineProperty(exports, "serverDeps", { enumerable: true, get: function () { return api_1.serverDeps; } });
+var routes_1 = require("./routes");
+Object.defineProperty(exports, "uagRouteHandlers", { enumerable: true, get: function () { return routes_1.uagRouteHandlers; } });
+Object.defineProperty(exports, "uagErrorBody", { enumerable: true, get: function () { return routes_1.uagErrorBody; } });

package/lib/modules/routes.d.ts

@@ -0,0 +1,14 @@
+import type { Request } from 'express';
+import type { ModuleRouteHandlers } from '@formio/appserver';
+import type { UAGProjectInterface } from '../UAGProjectInterface';
+/**
+ * What runs around each module route in the UAG, as around the agent
+ * operations: the caller check, the agent operations' JSON body limit and a
+ * request id before it; the named operation's rate limits and the Agent API's
+ * error shape around its run.
+ */
+export declare function uagRouteHandlers(project: UAGProjectInterface, name: string): ModuleRouteHandlers;
+/** A module route's `failed` event: the Agent API's error shape, with the status the event cannot carry otherwise. */
+export declare function uagErrorBody(req: Request, err: unknown): Record<string, any> & {
+    status: number;
+};

package/lib/modules/routes.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uagRouteHandlers = uagRouteHandlers;
+exports.uagErrorBody = uagErrorBody;
+const router_1 = require("../agent/router");
+const errors_1 = require("../agent/errors");
+/**
+ * What runs around each module route in the UAG, as around the agent
+ * operations: the caller check, the agent operations' JSON body limit and a
+ * request id before it; the named operation's rate limits and the Agent API's
+ * error shape around its run.
+ */
+function uagRouteHandlers(project, name) {
+    const { json, requestId, handle } = (0, router_1.agentEndpoints)(project);
+    return { before: [(0, router_1.agentCredentials)(project), json, requestId], wrap: (run) => handle(name, run) };
+}
+/** A module route's `failed` event: the Agent API's error shape, with the status the event cannot carry otherwise. */
+function uagErrorBody(req, err) {
+    const { status, body } = (0, errors_1.agentError)(req.requestId, err);
+    return { status, ...body };
+}