@formio/uag 2.0.0-rc.1 → 2.0.0-rc.10

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,25 @@
+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;
+    /** Generate with an engine from the registry. */
+    generate(engine: any, request: any): Promise<any>;
+    /** Throw 403 license_required unless Agentic Formflow is allowed. */
+    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,98 @@
+"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(),
+        generate: (engine, request) => (0, formflow_1.formflow)(project()).engineGenerate(engine, request),
+        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 generate = deps.generate;
+    const api = {
+        ...base,
+        ...(deps.requireAccess && { requireAccess: deps.requireAccess }),
+        requireLicense: deps.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.
+                return {
+                    name: engine.name,
+                    model: engine.model,
+                    accepts: readsOf(engine),
+                    generate: (request) => generate(engine, 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 };
+}

package/lib/modules/types.d.ts

@@ -0,0 +1,68 @@
+import type { Request } from 'express';
+import type { ModuleApi, ModuleRequest, ModuleRoute } from '@formio/appserver';
+import type { Converter, ConverterOutput, Representation } from '../documents/types';
+import type { FileRoute, Pins, AcceptEntry } from '../documents/routes';
+/** A module route's request in the UAG: also its request id. */
+export type UAGModuleRequest = ModuleRequest & {
+    requestId: string;
+};
+/** The names of the UAG's own rate-limited operations, which module routes may not take. */
+export declare const UAG_OPERATIONS: string[];
+/** An agent engine a module may use: its name and model, and generate, which checks the license first. */
+export type GeneratingEngine = {
+    name: string;
+    model: string;
+    accepts: Representation[];
+    generate(request: any): Promise<any>;
+};
+/**
+ * The module API the UAG gives a module (version 1): appserver's, with the
+ * license check, engines, converters and the UAG's helpers. The project and
+ * the engines themselves are never handed out.
+ */
+export type UAGModuleApi<Settings extends Record<string, any> = Record<string, any>> = ModuleApi<Settings> & {
+    /** Throws 403 license_required unless Agentic Formflow is allowed. */
+    requireLicense(): Promise<void>;
+    converters: {
+        list(): Converter[];
+        identify(buffer: Buffer, hint: {
+            name: string;
+            type?: string;
+        }): string;
+        route(type: string, inputs: Representation[][], pins?: Pins): FileRoute | null;
+        accept(inputs: Representation[][]): AcceptEntry[];
+        run(steps: Converter[], input: {
+            buffer: Buffer;
+            type: string;
+            name: string;
+        }, to: Representation, options: {
+            signal: AbortSignal;
+        }): Promise<ConverterOutput>;
+        stepName(converter: {
+            name: string;
+            version?: string;
+        }): string;
+    };
+    engines: {
+        /**
+         * The named engine, or the first agent engine that generates and reads every
+         * representation in `needs`; throws 503 no_engine. Its `generate` checks the
+         * license first, so no module calls a model outside it.
+         */
+        select(options: {
+            name?: string;
+            needs?: Representation[];
+        }): GeneratingEngine;
+    };
+    markdown: {
+        sanitize(text: string): string;
+        fromHtml(html: string): string;
+    };
+    pdf: {
+        pageCount(pdf: Buffer): Promise<number | undefined>;
+    };
+    /** Who the request is from, for limits: the user or token, or, for an anonymous caller, `anonymous:<ip>`. */
+    callerKey(req: Request): string;
+};
+/** A form route of a UAG module. */
+export type UAGModuleRoute = ModuleRoute<UAGModuleApi>;

package/lib/modules/types.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UAG_OPERATIONS = void 0;
+/** The names of the UAG's own rate-limited operations, which module routes may not take. */
+exports.UAG_OPERATIONS = ['extract', 'decide', 'generate', 'chat', 'capabilities'];

package/lib/pluginFiles.d.ts

@@ -0,0 +1,28 @@
+import type { UAGServer } from './index';
+/** The image's plugins folder: add-ons are mounted in folders under it. */
+export declare const DEFAULT_PLUGINS_DIR = "/app/plugins";
+/**
+ * The plugins files a path holds, in load order:
+ * - a file: that file;
+ * - a folder with an `index.mjs`: that file alone (one plugins folder);
+ * - any other folder: the `index.mjs` of each folder directly in it, in
+ *   name order (one per add-on), skipping folders whose name starts with
+ *   "." and `node_modules`.
+ */
+export declare function pluginFilesIn(target: string): string[];
+/**
+ * The plugins files to load: those UAG_PLUGINS names (a file, a folder, or
+ * "off"), or else those in the image's plugins folder when it exists.
+ */
+export declare function pluginFiles(env?: Record<string, string | undefined>, defaultDir?: string): string[];
+/**
+ * Load the plugins files, if any, and use each in turn, named by its path in
+ * error messages. A file's default export is a plugin or a list of plugins;
+ * or a module (an extra, with its plugins), or a list mixing modules and
+ * plugins, each module used in turn. Several files merge as several modules
+ * do: a module used again by name is used once, and two files that register
+ * the same plugin, plugin type, route or component stop startup, naming both.
+ * Plugins are trusted code: they run in the UAG process. Returns the files
+ * loaded.
+ */
+export declare function usePluginFiles(server: Pick<UAGServer, 'use'>, env?: Record<string, string | undefined>, defaultDir?: string): Promise<string[]>;

package/lib/pluginFiles.js

@@ -0,0 +1,101 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PLUGINS_DIR = void 0;
+exports.pluginFilesIn = pluginFilesIn;
+exports.pluginFiles = pluginFiles;
+exports.usePluginFiles = usePluginFiles;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const url_1 = require("url");
+const appserver_1 = require("@formio/appserver");
+/** The image's plugins folder: add-ons are mounted in folders under it. */
+exports.DEFAULT_PLUGINS_DIR = '/app/plugins';
+/** The file that makes a folder one plugins folder. */
+const INDEX = 'index.mjs';
+const isDirectory = (target) => {
+    try {
+        return fs_1.default.statSync(target).isDirectory();
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * The plugins files a path holds, in load order:
+ * - a file: that file;
+ * - a folder with an `index.mjs`: that file alone (one plugins folder);
+ * - any other folder: the `index.mjs` of each folder directly in it, in
+ *   name order (one per add-on), skipping folders whose name starts with
+ *   "." and `node_modules`.
+ */
+function pluginFilesIn(target) {
+    if (!isDirectory(target))
+        return [target];
+    const own = path_1.default.join(target, INDEX);
+    if (fs_1.default.existsSync(own))
+        return [own];
+    return fs_1.default.readdirSync(target, { withFileTypes: true })
+        .filter((entry) => !entry.name.startsWith('.') && entry.name !== 'node_modules')
+        .filter((entry) => entry.isDirectory() || (entry.isSymbolicLink() && isDirectory(path_1.default.join(target, entry.name))))
+        .map((entry) => entry.name)
+        .sort()
+        .map((name) => path_1.default.join(target, name, INDEX))
+        .filter((file) => fs_1.default.existsSync(file));
+}
+/**
+ * The plugins files to load: those UAG_PLUGINS names (a file, a folder, or
+ * "off"), or else those in the image's plugins folder when it exists.
+ */
+function pluginFiles(env = process.env, defaultDir = exports.DEFAULT_PLUGINS_DIR) {
+    const setting = String(env.UAG_PLUGINS || '').trim();
+    if (setting.toLowerCase() === 'off')
+        return [];
+    if (setting)
+        return pluginFilesIn(path_1.default.resolve(setting));
+    return fs_1.default.existsSync(defaultDir) ? pluginFilesIn(defaultDir) : [];
+}
+/** A real dynamic import(), kept one after compilation to CommonJS. */
+const dynamicImport = new Function('specifier', 'return import(specifier)');
+/**
+ * The keys only a module has: an entry with one of them (and no plugin `type`)
+ * is a module, anything else a plugin. Plugins have a `name` and `settings`
+ * too, so a name says nothing, and `settings` counts only as a function.
+ * (`uag` too, so a module written for the old shape is refused saying what to
+ * change, not read as a plugin.)
+ */
+const MODULE_KEYS = ['uag', 'routes', 'components', 'initialize', 'plugins', 'pluginTypes', 'config', 'formRoutes', 'actions', 'hooks', 'providers', 'processors'];
+const isModule = (entry) => !!entry && typeof entry === 'object' && !Array.isArray(entry) && typeof entry.type !== 'string'
+    && (MODULE_KEYS.some((key) => key in entry) || typeof entry.settings === 'function');
+/** Use one plugins file, named by its path in error messages. */
+async function usePluginFile(server, file) {
+    const exported = (await dynamicImport((0, url_1.pathToFileURL)(file).href))?.default;
+    const entries = [].concat(exported ?? []);
+    if (entries.some(isModule)) {
+        const plugins = entries.filter((entry) => !isModule(entry));
+        server.use([...entries.filter(isModule), ...(plugins.length ? [{ plugins }] : [])], file);
+        console.log(`[formio-uag] Plugins and modules loaded from ${file}.`);
+        return;
+    }
+    const plugins = await (0, appserver_1.loadPluginFile)(file);
+    server.use({ plugins }, file);
+    console.log(`[formio-uag] Plugins loaded from ${file}.`);
+}
+/**
+ * Load the plugins files, if any, and use each in turn, named by its path in
+ * error messages. A file's default export is a plugin or a list of plugins;
+ * or a module (an extra, with its plugins), or a list mixing modules and
+ * plugins, each module used in turn. Several files merge as several modules
+ * do: a module used again by name is used once, and two files that register
+ * the same plugin, plugin type, route or component stop startup, naming both.
+ * Plugins are trusted code: they run in the UAG process. Returns the files
+ * loaded.
+ */
+async function usePluginFiles(server, env = process.env, defaultDir = exports.DEFAULT_PLUGINS_DIR) {
+    const files = pluginFiles(env, defaultDir);
+    for (const file of files)
+        await usePluginFile(server, file);
+    return files;
+}

package/lib/plugins.d.ts

@@ -0,0 +1,17 @@
+import type { PluginLog, PluginRegistry, PluginType } from '@formio/appserver';
+import type { UAGProjectInterface } from './UAGProjectInterface';
+/**
+ * Engines and MCP tools, listed in the plugin registry (phase 1). The UAG keeps
+ * loading them its own way (UAG_ENGINES, config.tools); the registry only lists
+ * them, so they appear in GET {project}/plugins. Settings values are never listed.
+ */
+export declare const enginePluginType: PluginType;
+export declare const toolPluginType: PluginType;
+/** List each loaded engine type: its instances, kinds, what agent instances read, and whether they generate. */
+export declare function listEngines(registry: PluginRegistry, project: UAGProjectInterface): void;
+/**
+ * List every MCP tool the project serves (built-in, then config.tools). A name
+ * served twice is listed once, with a warning: listing never refuses what the
+ * tool loader allows.
+ */
+export declare function listTools(registry: PluginRegistry, project: UAGProjectInterface, log?: PluginLog): Promise<void>;