@formio/uag 1.13.2 → 2.0.0-rc.10

package/lib/plugins.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toolPluginType = exports.enginePluginType = void 0;
+exports.listEngines = listEngines;
+exports.listTools = listTools;
+const uag_sdk_1 = require("@formio/uag-sdk");
+const tools_1 = require("./agent/tools");
+const engines_1 = require("./agent/engines");
+const version_1 = require("./version");
+/**
+ * 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.
+ */
+exports.enginePluginType = {
+    type: 'engine',
+    title: 'Engine',
+    apiVersions: [1],
+    editForm: 'none',
+    // A misconfigured engine stops startup.
+    unavailable: 'error',
+    registration: 'internal',
+    stability: 'stable',
+    validate: (plugin) => uag_sdk_1.ENGINE_NAME.test(plugin.name) ? [] : [`engine name "${plugin.name}" must be lowercase letters, digits and "-", starting with a letter`],
+    manifest: (plugin) => ({
+        kinds: plugin.kinds,
+        accepts: plugin.accepts,
+        generate: plugin.generate,
+        instances: plugin.instances
+    })
+};
+exports.toolPluginType = {
+    type: 'tool',
+    title: 'MCP tool',
+    apiVersions: [1],
+    editForm: 'none',
+    unavailable: 'error',
+    registration: 'internal',
+    stability: 'stable',
+    validate: (plugin) => /^[A-Za-z][A-Za-z0-9_-]*$/.test(plugin.name) ? [] : [`tool name "${plugin.name}" must start with a letter and hold only letters, digits, "_" and "-"`],
+    manifest: (plugin) => ({ annotations: plugin.annotations ?? null })
+};
+const semver = (version) => (version && /^\d+\.\d+\.\d+/.test(version)) ? version : version_1.UAG_VERSION;
+/** List each loaded engine type: its instances, kinds, what agent instances read, and whether they generate. */
+function listEngines(registry, project) {
+    const engines = project.formflowEngines();
+    const entries = (0, engines_1.engineTypesOf)(engines).map((type) => {
+        const instances = type.instances.map((name) => engines.get(name)).filter(Boolean);
+        const agents = instances.filter((engine) => engine.kind === 'agent');
+        const accepts = [...new Set(agents.flatMap((engine) => Array.isArray(engine.accepts) ? engine.accepts : ['text']))];
+        return {
+            type: 'engine',
+            name: type.name,
+            title: type.title,
+            version: semver(type.version),
+            apiVersion: 1,
+            kinds: type.kinds,
+            accepts,
+            generate: agents.some((engine) => typeof engine.generate === 'function'),
+            instances: type.instances
+        };
+    });
+    registry.addType(exports.enginePluginType, '@formio/uag');
+    registry.add(entries, 'UAG_ENGINES', { server: true });
+}
+/**
+ * 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.
+ */
+async function listTools(registry, project, log = console) {
+    const seen = new Set();
+    const entries = [];
+    for (const tool of await (0, tools_1.allTools)(project)) {
+        const name = String(tool.name);
+        if (seen.has(name)) {
+            log.warn(`[plugins] tool:${name} is defined more than once; it is listed once`);
+            continue;
+        }
+        seen.add(name);
+        entries.push({
+            type: 'tool',
+            name,
+            title: tool.title || name,
+            description: tool.description,
+            version: version_1.UAG_VERSION,
+            apiVersion: 1,
+            annotations: tool.annotations
+        });
+    }
+    registry.addType(exports.toolPluginType, '@formio/uag');
+    registry.add(entries, 'config.tools', { server: true });
+}

package/lib/richText.d.ts

@@ -0,0 +1,20 @@
+import type { Component } from '@formio/core';
+/**
+ * HTML for rich text fields (textareas with the CKEditor or Quill editor).
+ *
+ * What an agent engine writes into such a field is reduced to the markup the
+ * editors keep, because the engine's input can be steered (a document it reads
+ * is someone else's text), and the field is later rendered for reviewers. The
+ * HTML is parsed and written out again: allowed elements with their allowed
+ * attributes, text escaped, everything else dropped. An element that is not
+ * allowed is dropped and its children kept, except for elements whose content
+ * is never text to show (scripts, styles, frames, embedded documents).
+ */
+/** Allowed elements, each with the attributes it may keep. */
+export declare const RICH_TEXT_TAGS: Record<string, string[]>;
+/** Whether a component is a rich text field, whose value is HTML. */
+export declare function isRichText(component: Component | undefined): boolean;
+/** Reduce HTML to the markup rich text editors keep (RICH_TEXT_TAGS). */
+export declare function sanitizeRichText(html: string): string;
+/** The rule agents are given for a rich text field's value. */
+export declare const RICH_TEXT_RULE: string;

package/lib/richText.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RICH_TEXT_RULE = exports.RICH_TEXT_TAGS = void 0;
+exports.isRichText = isRichText;
+exports.sanitizeRichText = sanitizeRichText;
+const node_html_parser_1 = require("node-html-parser");
+/**
+ * HTML for rich text fields (textareas with the CKEditor or Quill editor).
+ *
+ * What an agent engine writes into such a field is reduced to the markup the
+ * editors keep, because the engine's input can be steered (a document it reads
+ * is someone else's text), and the field is later rendered for reviewers. The
+ * HTML is parsed and written out again: allowed elements with their allowed
+ * attributes, text escaped, everything else dropped. An element that is not
+ * allowed is dropped and its children kept, except for elements whose content
+ * is never text to show (scripts, styles, frames, embedded documents).
+ */
+/** Allowed elements, each with the attributes it may keep. */
+exports.RICH_TEXT_TAGS = {
+    p: [], br: [], hr: [],
+    strong: [], b: [], em: [], i: [], u: [], s: [], sub: [], sup: [], code: [], pre: [],
+    h1: [], h2: [], h3: [], h4: [], h5: [], h6: [],
+    ul: [], ol: [], li: [],
+    blockquote: [],
+    a: ['href'],
+    figure: [], table: [], thead: [], tbody: [], tfoot: [], tr: [],
+    th: ['colspan', 'rowspan'], td: ['colspan', 'rowspan']
+};
+/** Elements dropped with everything inside them. */
+const DROPPED_WITH_CONTENT = new Set(['script', 'style', 'noscript', 'template', 'iframe', 'frame', 'frameset', 'object', 'embed', 'svg', 'math', 'head', 'title', 'textarea', 'select']);
+const VOID = new Set(['br', 'hr']);
+/** Whether a component is a rich text field, whose value is HTML. */
+function isRichText(component) {
+    const editor = component?.editor;
+    return component?.type === 'textarea' && (editor === 'ckeditor' || editor === 'quill');
+}
+function escapeText(text) {
+    return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+function escapeAttribute(value) {
+    return escapeText(value).replace(/"/g, '&quot;');
+}
+/** Only links to web pages and mail addresses: never `javascript:`, `data:` or the like. */
+function safeHref(value) {
+    const href = String(value || '').replace(/[\u0000-\u001F\u007F\s]+/g, '');
+    return /^(https?:\/\/|mailto:)/i.test(href) ? String(value).trim() : null;
+}
+function attributesOf(element, allowed) {
+    let out = '';
+    for (const name of allowed) {
+        const raw = element.getAttribute(name);
+        if (raw === undefined || raw === null)
+            continue;
+        let value = raw;
+        if (name === 'href')
+            value = safeHref(raw);
+        if ((name === 'colspan' || name === 'rowspan'))
+            value = /^\d{1,3}$/.test(raw.trim()) ? raw.trim() : null;
+        if (value === null)
+            continue;
+        out += ` ${name}="${escapeAttribute(value)}"`;
+    }
+    return out;
+}
+function write(node) {
+    if (node.nodeType === node_html_parser_1.NodeType.TEXT_NODE) {
+        // `text` is the decoded text; it is escaped once, here.
+        return escapeText(node.text);
+    }
+    if (node.nodeType !== node_html_parser_1.NodeType.ELEMENT_NODE)
+        return '';
+    const element = node;
+    const children = () => element.childNodes.map(write).join('');
+    const tag = String(element.rawTagName || '').toLowerCase();
+    if (!tag)
+        return children();
+    if (DROPPED_WITH_CONTENT.has(tag))
+        return '';
+    const allowed = exports.RICH_TEXT_TAGS[tag];
+    if (!allowed)
+        return children();
+    const open = `<${tag}${attributesOf(element, allowed)}>`;
+    return VOID.has(tag) ? open : `${open}${children()}</${tag}>`;
+}
+/** Reduce HTML to the markup rich text editors keep (RICH_TEXT_TAGS). */
+function sanitizeRichText(html) {
+    const root = (0, node_html_parser_1.parse)(String(html ?? ''), {
+        comment: false,
+        lowerCaseTagName: true,
+        // Read as raw text, so their content is never parsed as markup; they are dropped.
+        blockTextElements: { script: true, style: true, noscript: true }
+    });
+    return root.childNodes.map(write).join('').trim();
+}
+/** The rule agents are given for a rich text field's value. */
+exports.RICH_TEXT_RULE = 'The value is HTML for a rich text editor. Use only these elements: ' +
+    Object.keys(exports.RICH_TEXT_TAGS).join(', ') +
+    ', with no attributes except href on a (http, https or mailto links only) and colspan and rowspan on td and th. ' +
+    'No other elements, styles, classes, images or scripts, which are removed. Write HTML, not Markdown, and do not wrap it in a code fence.';

package/lib/router.d.ts

@@ -1,3 +1,12 @@
 import { Router } from 'express';
 import { UAGProjectInterface } from './UAGProjectInterface';
+import type { ScopedTokenClaims } from './formflow';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Hold a scoped token to its tools whatever built the server: a project
+ * interface a module replaces may override buildMcpServer() and register tools
+ * without the scope it was given. Every tool the token does not list, and every
+ * tool not annotated read-only, is disabled, so it is neither listed nor run.
+ */
+export declare function restrictToScope(server: McpServer, scope: Pick<ScopedTokenClaims, 'tools'>): void;
 export declare function UAGRouter(project: UAGProjectInterface): Router;

package/lib/router.js

@@ -1,16 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.restrictToScope = restrictToScope;
 exports.UAGRouter = UAGRouter;
 const express_1 = require("express");
 const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
 // Helper function to create JSON RPC error responses
-const createJsonRpcErrorResponse = (code, message) => {
-    return JSON.stringify({
-        error: { code, message },
-        id: null,
-        jsonrpc: "2.0",
-    });
-};
+const createJsonRpcErrorResponse = (code, message) => ({
+    error: { code, message },
+    id: null,
+    jsonrpc: "2.0",
+});
 /**
  * Handle errors that occur during response processing.
  * @param error The error that occurred.
@@ -29,16 +28,34 @@ const handleResponseError = (error, res) => {
         return true;
     }
     console.error("[formio-uag] error handling request", error);
-    res.status(500).json(JSON.parse(createJsonRpcErrorResponse(-32603, "Internal Server Error")));
+    res.status(500).json(createJsonRpcErrorResponse(-32603, "Internal Server Error"));
     return false;
 };
+/**
+ * Hold a scoped token to its tools whatever built the server: a project
+ * interface a module replaces may override buildMcpServer() and register tools
+ * without the scope it was given. Every tool the token does not list, and every
+ * tool not annotated read-only, is disabled, so it is neither listed nor run.
+ */
+function restrictToScope(server, scope) {
+    const allowed = new Set(scope.tools || []);
+    // The SDK keeps registered tools here; it has no public list of them.
+    const registered = server._registeredTools || {};
+    for (const [name, tool] of Object.entries(registered)) {
+        if (!allowed.has(name) || tool?.annotations?.readOnlyHint !== true) {
+            tool.disable?.();
+        }
+    }
+}
 /**
  * Build a per-request McpServer + transport (stateless mode) and tear both down
  * when the response closes. A fresh instance per request keeps concurrent requests
  * from overwriting each other's transport.
  */
-const connectMcpTransport = async (project, res) => {
-    const server = await project.buildMcpServer();
+const connectMcpTransport = async (project, res, scope) => {
+    const server = await project.buildMcpServer(scope);
+    if (scope)
+        restrictToScope(server, scope);
     const transport = new streamableHttp_js_1.StreamableHTTPServerTransport({
         sessionIdGenerator: undefined, // Use "undefined" to trigger stateless mode.
     });
@@ -51,26 +68,18 @@ const connectMcpTransport = async (project, res) => {
 };
 function UAGRouter(project) {
     const router = (0, express_1.Router)();
-    // Handles the MCP post requests.
-    router.post('/', async (req, res) => {
+    // Handles the MCP requests: posts carry a JSON-RPC body, gets do not (health checks, etc).
+    const handleMcpRequest = (withBody) => async (req, res) => {
         try {
-            const transport = await connectMcpTransport(project, res);
-            await transport.handleRequest(req, res, req.body);
+            const transport = await connectMcpTransport(project, res, req.uagScope);
+            await transport.handleRequest(req, res, withBody ? req.body : undefined);
         }
         catch (error) {
             handleResponseError(error, res);
         }
-    });
-    // Handles the MCP get requests (for health checks, etc).
-    router.get('/', async (req, res) => {
-        try {
-            const transport = await connectMcpTransport(project, res);
-            await transport.handleRequest(req, res);
-        }
-        catch (err) {
-            handleResponseError(err, res);
-        }
-    });
+    };
+    router.post('/', handleMcpRequest(true));
+    router.get('/', handleMcpRequest(false));
     // Return the router
     return router;
 }

package/lib/runner.d.ts

@@ -0,0 +1,149 @@
+import { AuthRequest } from '@formio/appserver';
+import type { CallerIdentity } from './formflow';
+import { ActingFor } from './identity';
+import { TaskRunStore } from './runs';
+import type { UAGProjectInterface } from './UAGProjectInterface';
+/** A Run task action's run after the save, on the submission Form.io stored. */
+export type TaskRunJob = {
+    /** The form's name. */
+    form: string;
+    submission: string;
+    task: string;
+    answer: 'decisions' | 'task';
+    /** The user the run acts for: who sent the submission. Never a token. */
+    actingFor: ActingFor;
+    /**
+     * The role the agent acts with at Form.io, on the user's behalf. Such runs
+     * can be recorded and resumed: everything they need is in the job.
+     */
+    agentRole?: string;
+    /**
+     * Without an agent role, the caller's own identity (with their token), kept
+     * in memory only and never recorded.
+     */
+    caller?: AuthRequest;
+    /** Without an agent role, who the engines research as (the caller's bearer token, if any). */
+    identity?: CallerIdentity;
+    /**
+     * Without an agent role or the caller's token: act as the user, with their
+     * recorded roles and tokens the UAG signs. A run started by the save of a
+     * run that acted with an agent role, so it never inherits that role.
+     */
+    asUser?: boolean;
+    /** How many runner saves led to this run: none for a run a client's request started. */
+    chain?: number;
+    /** The action that started the run, for the record. */
+    action?: string;
+    /** For the record: the form's id, and the method that started the run. */
+    formId?: string;
+    method?: string;
+    /** The X-Request-Id of the request that started the run, passed on to the engines. */
+    requestId?: string;
+};
+export type TaskRunOutcome = {
+    status: 'done' | 'failed';
+    /** Paths written, with their values, and paths cleared. Empty when nothing changed. */
+    written: Record<string, any>;
+    cleared: string[];
+    /** The engines and models that answered. */
+    engines: {
+        kind: string;
+        engine: string | null;
+        model: string | null;
+    }[];
+    /** Whether the results were saved (nothing is saved when nothing changed). */
+    saved: boolean;
+    /** Answers the form's validation refused, left out: path to the form's message. */
+    refused?: Record<string, string>;
+    error?: string;
+};
+/**
+ * The request field that marks the runner's own save, so the form's Run task
+ * actions that run before the save skip it: its data is the agent's output.
+ */
+export declare const RUN_TASK_SAVE = "uagRunTaskSave";
+/**
+ * The request fields that carry, through the runner's own save, who the run
+ * acts for, so a Run task action that the save starts acts for the same user.
+ */
+export declare const RUN_TASK_ACTING_FOR = "uagActingFor";
+export declare const RUN_TASK_CALLER = "uagCaller";
+export declare const RUN_TASK_REQUEST_ID = "uagRequestId";
+export declare const RUN_TASK_IDENTITY = "uagIdentity";
+export declare const RUN_TASK_AS_USER = "uagAsUser";
+export declare const RUN_TASK_CHAIN = "uagChain";
+/**
+ * Runs a runner's save may start in a row: a task whose save starts a task
+ * that changes something each time would otherwise never stop.
+ */
+export declare const MAX_CHAIN = 5;
+/** How often a replica looks for runs that are pending or lost their replica. */
+export declare const SWEEP_MS: number;
+/**
+ * Runs Run task actions' background runs: load the stored submission, run the
+ * task, and save only what changed, as an update through the UAG's own
+ * pipeline (so the form's update actions, including other Run task actions,
+ * run on it). If the submission changes while the task runs, the run starts
+ * again once on the new version, then gives up as a conflict.
+ *
+ * Without the UAG's database, runs are kept in memory, a few at a time, and
+ * are lost if the process stops. With it, every run is recorded; a run that
+ * acts with an agent role is recorded as pending before the caller's response
+ * and taken from the database by one replica at a time, under a lease it
+ * renews, so it survives a restart. A sweep at startup and every minute takes
+ * runs that are pending or whose replica stopped.
+ */
+export declare class TaskRunner {
+    private project;
+    private concurrency;
+    private queue;
+    private active;
+    private waiting;
+    private store?;
+    private sweeper?;
+    private sweeping;
+    constructor(project: UAGProjectInterface, concurrency?: number);
+    /** Whether runs acting with an agent role are recorded and survive a restart. */
+    get durable(): boolean;
+    /** Record runs in the UAG's database, and take durable runs from it. */
+    useStore(store: TaskRunStore): void;
+    /** Stop sweeping (the runs in progress finish). */
+    stop(): void;
+    /** The project's run records, when there is a database. */
+    get records(): TaskRunStore | undefined;
+    /**
+     * Start a run. A durable run is recorded as pending before this resolves, so
+     * the caller's response is sent only once it can survive a restart.
+     */
+    enqueue(job: TaskRunJob): Promise<void>;
+    /** Record a run made before the save, once the save gave the submission its id. */
+    recordBefore(job: TaskRunJob, outcome: TaskRunOutcome): Promise<void>;
+    private newRecord;
+    /** Resolves once every queued and running job has finished (for tests and shutdown). */
+    idle(): Promise<void>;
+    private isIdle;
+    private settled;
+    private drain;
+    /** Take durable runs from the database while there is room. */
+    private sweep;
+    private runRecord;
+    /** Run a job, report it, and record its end. */
+    private track;
+    protected report(job: TaskRunJob, outcome: TaskRunOutcome): void;
+    /**
+     * Who the job acts as at Form.io (`act`: a new identity for each request,
+     * since signed tokens are short-lived), and who its engines research as.
+     * Never the project's key: the agent role's signed token, or the caller's own.
+     */
+    private identities;
+    /**
+     * Why Form.io refused the agent's signed token, when it did: asks Form.io who
+     * the token is, so a JWT_SECRET that is not Form.io's is told apart from
+     * other failures.
+     */
+    private refusal;
+    /** Run one job to completion. */
+    execute(job: TaskRunJob): Promise<TaskRunOutcome>;
+    private run;
+}
+export declare function taskRunner(project: UAGProjectInterface): TaskRunner;