@formio/uag 1.13.2 → 2.0.0-rc.10

package/lib/testing.js

@@ -0,0 +1,180 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.testForm = testForm;
+exports.testAuth = testAuth;
+exports.createTestModuleApi = createTestModuleApi;
+exports.mountModuleRoutes = mountModuleRoutes;
+/**
+ * @formio/uag/testing: test a module without a Form.io project or a running UAG.
+ *
+ *   const { createTestModuleApi, testForm, testAuth, mountModuleRoutes } = require('@formio/uag/testing');
+ *
+ *   const api = await createTestModuleApi(MyModule, { config: { myModule: { max: 2 } } });
+ *   const app = await mountModuleRoutes(MyModule, { form: testForm(definition), auth: testAuth() });
+ *   await supertest(app).post('/notes/my-module/check').send({ ... });
+ *
+ * The API is the UAG's own (errors, stream, forms, converters, engine handles,
+ * Markdown, callerKey), with stand-ins only for what needs a project: the
+ * caller's access (from `testAuth`), the license (`licensed`), engines
+ * (`engines`) and stored files (`testForm` reads base64 values; `files` for
+ * others). Settings go through the module's own `settings`, with the server's rules.
+ */
+const express_1 = __importDefault(require("express"));
+const crypto_1 = require("crypto");
+const appserver_1 = require("@formio/appserver");
+const formflow_1 = require("./formflow");
+const plugins_1 = require("./documents/plugins");
+const errors_1 = require("./agent/errors");
+const version_1 = require("./version");
+const api_1 = require("./modules/api");
+const routes_1 = require("./modules/routes");
+/** A form for tests, as module routes get it: `definition` is the form's JSON. */
+function testForm(definition, options = {}) {
+    const form = {
+        id: options.id || String(definition._id || 'test-form'),
+        name: String(definition.name || definition.path || 'test'),
+        path: String(definition.path || definition.name || 'test'),
+        title: String(definition.title || definition.name || ''),
+        definition,
+        async readFile(value, _auth, readOptions = {}) {
+            const url = String(value?.url || '');
+            if (url.startsWith('data:')) {
+                const bytes = Buffer.from(url.slice(url.indexOf(',') + 1), url.includes(';base64,') ? 'base64' : 'utf8');
+                if (readOptions.maxBytes !== undefined && bytes.length > readOptions.maxBytes) {
+                    throw new Error(`The file "${value?.originalName || value?.name || 'unnamed'}" is larger than the ${readOptions.maxBytes} bytes that may be read.`);
+                }
+                return bytes;
+            }
+            const files = options.files || this?.files;
+            if (files)
+                return files(value, readOptions);
+            throw new Error('testForm reads base64 (data: URL) files only: give testForm, createTestModuleApi or mountModuleRoutes a "files" function for others.');
+        }
+    };
+    return form;
+}
+/**
+ * A caller for tests: a user with these permissions on every form (create and
+ * update by default), as a list (`['read']`) or as `formPermissions()` gives
+ * them (`{ read: true }`).
+ */
+function testAuth(options = {}) {
+    const given = options.permissions || ['create', 'update'];
+    const granted = { create: false, read: false, update: false, delete: false };
+    if (Array.isArray(given)) {
+        for (const method of given)
+            granted[method] = true;
+    }
+    else if (given && typeof given === 'object') {
+        for (const method of Object.keys(granted))
+            granted[method] = given[method] === true;
+    }
+    else {
+        throw new Error('testAuth: "permissions" is a list of create, read, update and delete, or { read: true, ... }');
+    }
+    return {
+        user: options.user || { _id: 'test-user' },
+        admin: !!options.admin,
+        formPermissions: () => (options.admin ? { create: true, read: true, update: true, delete: true } : granted)
+    };
+}
+/** The module, checked for what a test needs: a name and an apiVersion. */
+function loadedOf(module, settings) {
+    if (!module || typeof module.name !== 'string' || module.apiVersion === undefined) {
+        throw new Error('The module needs a "name" and an "apiVersion" to be tested as a module.');
+    }
+    return { definition: module, name: module.name, source: 'test', settings };
+}
+/** The module's settings, as the server resolves them. */
+function settingsOf(module, options) {
+    if (options.settings)
+        return Object.freeze({ ...options.settings });
+    const settings = module.settings ? module.settings(options.config || {}, options.env || {}) : {};
+    if (settings && typeof settings.then === 'function')
+        throw new Error(`Module ${module.name}: "settings" returned a promise; it must return the settings themselves (no async)`);
+    return Object.freeze({ ...(settings || {}) });
+}
+/** The form, reading stored values that are not base64 through `files` unless it has its own. */
+function withFiles(form, files) {
+    return files && form && typeof form === 'object' && !form.files ? { ...form, files } : form;
+}
+/** The UAG's module API for a module, in a test. */
+async function createTestModuleApi(module, options = {}) {
+    const loaded = loadedOf(module, settingsOf(module, options));
+    const registry = new appserver_1.PluginRegistry();
+    (0, plugins_1.registerDocuments)(registry);
+    const licensed = options.licensed !== false;
+    const requireLicense = async () => {
+        if (!licensed)
+            throw new formflow_1.FormflowError(403, 'Agentic Formflow requires a license (the test API was created with licensed: false).', 'license_required');
+    };
+    const generate = async (engine, request) => {
+        await requireLicense();
+        return engine.generate(request);
+    };
+    const engines = (options.engines || []).map((engine) => ({ kind: 'agent', model: engine.name, accepts: ['text'], ...engine }));
+    const base = (0, appserver_1.createBaseModuleApi)(loaded, registry, { name: () => 'uag', version: () => version_1.UAG_VERSION, errorBody: routes_1.uagErrorBody });
+    const api = (0, api_1.uagModuleApi)(base, {
+        registry: () => registry,
+        engines: () => ({ get: (name) => engines.find((engine) => engine.name === name), agent: engines.filter((engine) => engine.kind === 'agent') }),
+        generate,
+        requireLicense
+    });
+    const pluginTypes = typeof module.pluginTypes === 'function' ? module.pluginTypes(api) : (module.pluginTypes || []);
+    for (const type of pluginTypes)
+        registry.addType(type, module.name);
+    if (module.plugins)
+        registry.add(module.plugins, module.name);
+    if (options.plugins?.length)
+        registry.add(options.plugins, 'test');
+    await registry.initialize({ server: {} });
+    if (options.files) {
+        // A form without its own "files" function reads other stored values through this one.
+        const read = api.files.read;
+        api.files.read = (form, value, auth, readOptions) => read(withFiles(form, options.files), value, auth, readOptions);
+    }
+    return api;
+}
+/**
+ * The module's form routes on an Express app, as the UAG mounts them on a
+ * form (by its path, and by `form/<id>`), for supertest: with the form, the
+ * caller, a request id, the access check and the UAG's error shape. No rate
+ * limits. `api` is created with `options` unless given.
+ */
+async function mountModuleRoutes(module, options) {
+    const api = options.api || await createTestModuleApi(module, options);
+    const loaded = loadedOf(module, api.settings);
+    const app = (0, express_1.default)();
+    app.use(express_1.default.json({ limit: '50mb' }));
+    const host = {
+        errorBody: routes_1.uagErrorBody,
+        routeHandlers: (_project, route) => ({
+            before: [(req, res, next) => {
+                    req.requestId = req.get('x-request-id') || (0, crypto_1.randomUUID)();
+                    res.set('X-Request-Id', req.requestId);
+                    next();
+                }],
+            wrap: (run) => async (req, res) => {
+                try {
+                    await run(req, res);
+                }
+                catch (err) {
+                    const { status, body } = (0, errors_1.agentError)(req.requestId, err);
+                    res.status(status).json(body);
+                }
+            }
+        })
+    };
+    const router = (0, appserver_1.moduleFormRouter)({}, loaded, api, host);
+    const withForm = (req, res, next) => {
+        req.form = withFiles(options.form, options.files);
+        req.auth = options.auth || testAuth();
+        next();
+    };
+    app.use(`/${options.form.path}`, withForm, router);
+    app.use(`/form/${options.form.id}`, withForm, router);
+    return app;
+}

package/lib/tools/SchemaBuilder.d.ts

@@ -109,10 +109,10 @@ export declare class SchemaBuilder {
      */
     parent_path(): this;
     /**
-     * The agent persona "type" to use when processing the existing submission data. The persona provides context to the agent on how to interpret and understand the data within the form submission. If not provided, the default persona defined within the form's UAG settings will be used.
-     * @returns
+     * The task to work on: the name of a task the form defines (the value of its
+     * components' `uag` property).
      */
-    persona(): this;
+    task(): this;
     /**
      * The data_path of a specific field within the form.
      */

package/lib/tools/SchemaBuilder.js

@@ -168,11 +168,11 @@ class SchemaBuilder {
         return this;
     }
     /**
-     * The agent persona "type" to use when processing the existing submission data. The persona provides context to the agent on how to interpret and understand the data within the form submission. If not provided, the default persona defined within the form's UAG settings will be used.
-     * @returns
+     * The task to work on: the name of a task the form defines (the value of its
+     * components' `uag` property).
      */
-    persona() {
-        this.schema.persona = zod_1.default.string().optional().describe('The agent persona "type" to use when processing the existing submission data. The persona provides context to the agent on how to interpret and understand the data within the form submission. If not provided, the default persona defined within the form\'s UAG settings will be used.');
+    task() {
+        this.schema.task = zod_1.default.string().optional().describe('The name of a task defined on the form: the value of its components\' `uag` property, such as "triage". Not a description of the work. If not provided, the form\'s first task is used.');
         return this;
     }
     /**

package/lib/tools/agentDecide.d.ts

@@ -0,0 +1,8 @@
+import { UAGProjectInterface } from "../UAGProjectInterface";
+import { ToolInfo } from "./utils";
+/**
+ * Returns a task's decision questions as structured JSON, so any decision
+ * model — an enabled engine, or one the MCP client calls itself — can answer
+ * them. No model is called here.
+ */
+export declare const agentDecide: (project: UAGProjectInterface) => Promise<ToolInfo>;

package/lib/tools/agentDecide.js

@@ -0,0 +1,57 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentDecide = void 0;
+const lodash_1 = require("lodash");
+const zod_1 = __importDefault(require("zod"));
+const template_1 = require("../template");
+const formflow_1 = require("../formflow");
+const SchemaBuilder_1 = require("./SchemaBuilder");
+const annotations_1 = require("./annotations");
+/**
+ * Returns a task's decision questions as structured JSON, so any decision
+ * model — an enabled engine, or one the MCP client calls itself — can answer
+ * them. No model is called here.
+ */
+const agentDecide = async (project) => {
+    return (0, lodash_1.defaultsDeep)({}, project.config?.toolOverrides?.agent_decide, {
+        name: 'agent_decide',
+        title: 'Agent Decide',
+        description: 'Return the decision questions for a task\'s closed-set fields (radio, select, checkbox, select boxes, survey and small resource selects) as structured JSON: the state to decide on, every question, and how each answer maps back to a field value. Answer the questions with a decision model, then write the values with `submission_update`. Provide either `submission_id` or `form_data`.',
+        annotations: (0, annotations_1.reads)('Get decision questions'),
+        inputSchema: {
+            ...(new SchemaBuilder_1.SchemaBuilder(project)).form_name().submission_id().task().schema,
+            form_data: zod_1.default.record(zod_1.default.string(), zod_1.default.any()).optional().describe('The current form data as a submission data object (nested by data path). Used when `submission_id` is not given.')
+        },
+        execute: async (args, extra) => {
+            const { form_name, submission_id, form_data } = args;
+            const form = await project.getForm(form_name);
+            if (!form) {
+                return project.mcpResponse(template_1.ResponseTemplate.formNotFound, { formName: form_name }, true);
+            }
+            let data = form_data || {};
+            if (submission_id) {
+                const submission = await form.loadSubmission(submission_id, extra.authInfo);
+                if (!submission) {
+                    return project.mcpResponse(template_1.ResponseTemplate.submissionNotFound, { form: form.form, submissionId: submission_id }, true);
+                }
+                data = submission.data || {};
+            }
+            try {
+                const task = args.task || undefined;
+                const out = await (0, formflow_1.formflow)(project).questions(form, { task, data, submissionId: submission_id }, extra.authInfo);
+                return project.mcpJSONResponse({ form: form_name, ...out });
+            }
+            catch (err) {
+                // A request that cannot be planned, or Agentic Formflow without its license.
+                if (err instanceof formflow_1.FormflowError) {
+                    return project.mcpJSONResponse({ error: err.message, ...(err.code && { code: err.code }) }, true);
+                }
+                throw err;
+            }
+        }
+    });
+};
+exports.agentDecide = agentDecide;

package/lib/tools/agentProvide.d.ts

@@ -0,0 +1,8 @@
+import { UAGProjectInterface } from "../UAGProjectInterface";
+import { ToolInfo } from "./utils";
+/**
+ * `agent_provide`: a task's criteria, the submission's values and the task's
+ * fields, as instructions for an agent to fill those fields. It reads only; the
+ * agent writes its values with `submission_update`.
+ */
+export declare const agentProvide: (project: UAGProjectInterface) => Promise<ToolInfo>;

package/lib/tools/agentProvide.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentProvide = void 0;
+const template_1 = require("../template");
+const lodash_1 = require("lodash");
+const SchemaBuilder_1 = require("./SchemaBuilder");
+const annotations_1 = require("./annotations");
+const formflow_1 = require("../formflow");
+const DESCRIPTION = 'Provides a mechanism for agents to process existing submission data, understand it, and then to provide additional data values provided a criteria and form context.';
+/**
+ * Agentic workflow over MCP is Agentic Formflow: it needs a license or a project
+ * on Form.io's hosted service, as the Agent API does. The stub engines do not
+ * count, since this tool calls no engine. Answers the refusal, or null.
+ */
+async function refusal(project) {
+    const state = await (0, formflow_1.formflow)(project).state();
+    if (state.allowed && (state.reason === 'licensed' || state.reason === 'hosted'))
+        return null;
+    return {
+        error: 'Agentic workflows require a license (LICENSE_KEY) that includes the UAG (an online license with UAG servers, or an offline license ' +
+            'with the "uag" option), or a project on Form.io\'s hosted service. ' +
+            'MCP tools and conversation forms do not need either.',
+        code: 'license_required',
+    };
+}
+/**
+ * `agent_provide`: a task's criteria, the submission's values and the task's
+ * fields, as instructions for an agent to fill those fields. It reads only; the
+ * agent writes its values with `submission_update`.
+ */
+const agentProvide = async (project) => {
+    // Merged into a new object: the overrides are shared config, and the tools are
+    // built again for every request.
+    return (0, lodash_1.defaultsDeep)({}, project.config?.toolOverrides?.agent_provide, provideTool(project));
+};
+exports.agentProvide = agentProvide;
+function provideTool(project) {
+    return {
+        name: 'agent_provide',
+        title: 'Agent Provide',
+        description: DESCRIPTION,
+        annotations: (0, annotations_1.reads)('Process submission data'),
+        inputSchema: (new SchemaBuilder_1.SchemaBuilder(project))
+            .form_name()
+            .submission_id()
+            .task().schema,
+        execute: async (args, extra) => {
+            const { form_name, submission_id } = args;
+            const refused = await refusal(project);
+            if (refused)
+                return project.mcpJSONResponse(refused, true);
+            const requested = args.task || undefined;
+            const form = await project.getForm(form_name);
+            if (!form) {
+                return project.mcpResponse(template_1.ResponseTemplate.formNotFound, { formName: form_name }, true);
+            }
+            const task = requested || Object.keys(form.uagFields)[0] || 'default';
+            const names = { task };
+            const uag = form.uagFields[task];
+            if (!uag) {
+                return project.mcpResponse(template_1.ResponseTemplate.uagComponentNotFound, {
+                    ...names,
+                    error: 'no_uag'
+                }, true);
+            }
+            const submission = await form.loadSubmission(submission_id, extra.authInfo);
+            if (!submission) {
+                return project.mcpResponse(template_1.ResponseTemplate.submissionNotFound, {
+                    form: form.form,
+                    submissionId: submission_id
+                }, true);
+            }
+            if (!uag.criteria) {
+                return project.mcpResponse(template_1.ResponseTemplate.uagComponentNotFound, {
+                    ...names,
+                    error: 'no_criteria'
+                }, true);
+            }
+            const agentFields = Object.values(uag.components);
+            if (agentFields.length === 0) {
+                return project.mcpResponse(template_1.ResponseTemplate.uagComponentNotFound, {
+                    ...names,
+                    error: 'no_fields'
+                }, true);
+            }
+            // Collect more required fields.
+            return project.mcpResponse(template_1.ResponseTemplate.agentProcessData, {
+                ...names,
+                criteria: uag.criteria,
+                values: project.uagTemplate?.renderTemplate(template_1.ResponseTemplate.fieldValues, {
+                    data: form.formatData(submission.data)
+                }),
+                fields: project.uagTemplate?.renderTemplate(template_1.ResponseTemplate.fieldList, { fields: agentFields })
+            });
+        }
+    };
+}

package/lib/tools/collectData.js

@@ -6,7 +6,7 @@ const lodash_1 = require("lodash");
 const SchemaBuilder_1 = require("./SchemaBuilder");
 const annotations_1 = require("./annotations");
 const collectData = async (project) => {
-    return (0, lodash_1.defaultsDeep)(project.config?.toolOverrides?.collect_field_data || {}, {
+    return (0, lodash_1.defaultsDeep)({}, project.config?.toolOverrides?.collect_field_data, {
         name: 'collect_field_data',
         title: 'Collect Field Data',
         description: 'Collect data for a form, or a specific field with nested components. Identify the component by its path, validate the provided value, and update the form_data object. After updating, determine the next required field to collect or indicate if all required fields are complete. PREREQUISITE: This tool should only be called after the `get_form_fields` tool AND subsequentially the `get_field_info` tool have been called to understand the structure and validation rules of the fields.',
@@ -34,7 +34,8 @@ const collectData = async (project) => {
             const fields = await form.getFields(submission, extra.authInfo, parent?.data_path);
             if (fields.errors.length > 0) {
                 if (as_json) {
-                    return project.mcpJSONResponse(fields.errors);
+                    // structuredContent must be an object: an MCP client refuses a bare array.
+                    return project.mcpJSONResponse({ errors: fields.errors }, true);
                 }
                 return project.mcpResponse(template_1.ResponseTemplate.fieldValidationErrors, { invalidFields: fields.errors });
             }

package/lib/tools/confirmSubmission.js

@@ -6,7 +6,7 @@ const lodash_1 = require("lodash");
 const SchemaBuilder_1 = require("./SchemaBuilder");
 const annotations_1 = require("./annotations");
 const confirmSubmission = async (project) => {
-    return (0, lodash_1.defaultsDeep)(project.config?.toolOverrides?.confirm_form_submission || {}, {
+    return (0, lodash_1.defaultsDeep)({}, project.config?.toolOverrides?.confirm_form_submission, {
         name: 'confirm_form_submission',
         title: 'Confirm Form Submission',
         description: 'Show a summary of the collected form data if the user wishes to see a summary of the collected data',

package/lib/tools/fetchExternalData.js

@@ -41,9 +41,10 @@ function extractValue(item, component) {
 }
 /**
  * Check if a component is a select-type component with external data (url or resource).
+ * A radio can load its options from a URL too.
  */
 function isExternalSelect(component) {
-    if (component.type !== 'select' && component.type !== 'selectboxes')
+    if (component.type !== 'select' && component.type !== 'selectboxes' && component.type !== 'radio')
         return false;
     const dataSrc = component.dataSrc;
     return dataSrc === 'url' || dataSrc === 'resource';
@@ -71,7 +72,7 @@ function interpolateHeaders(headers, context) {
     return result;
 }
 const fetchExternalData = async (project) => {
-    return (0, lodash_1.defaultsDeep)(project.config?.toolOverrides?.fetch_external_data || {}, {
+    return (0, lodash_1.defaultsDeep)({}, project.config?.toolOverrides?.fetch_external_data, {
         name: 'fetch_external_data',
         title: 'Fetch External Data',
         description: 'Fetch external data for a component that loads data from an external URL, a Form.io Resource, or a DataSource. Use this tool when `get_form_fields` indicates that a field requires calling `fetch_external_data` to retrieve its data. For select components, this returns the available options. For datasource components, this returns the fetched data. You can optionally provide a `search_value` to filter results server-side. If the component\'s URL or headers contain interpolation tokens (e.g. `{{ data.someField }}`), you MUST provide `form_data` with the current collected data so the tokens can be resolved.',
@@ -123,24 +124,14 @@ const fetchExternalData = async (project) => {
                 if (!isExternalSelect(component)) {
                     return project.mcpResponse(template_1.ResponseTemplate.fetchExternalDataError, {
                         dataPath: data_path,
-                        error: `Component at "${data_path}" is of type "${component.type}" and does not load external data. This tool only supports select/selectboxes components with dataSrc "url" or "resource", and datasource components.`
+                        error: `Component at "${data_path}" is of type "${component.type}" and does not load external data. This tool only supports select, selectboxes and radio components with dataSrc "url" or "resource", and datasource components.`
                     }, true);
                 }
+                // isExternalSelect() has checked that dataSrc is "url" or "resource".
                 const selectComponent = component;
-                const dataSrc = selectComponent.dataSrc;
-                if (dataSrc !== 'url' && dataSrc !== 'resource') {
-                    return project.mcpResponse(template_1.ResponseTemplate.fetchExternalDataError, {
-                        dataPath: data_path,
-                        error: `Component at "${data_path}" has dataSrc "${dataSrc}". Only "url" and "resource" are supported by this tool.`
-                    }, true);
-                }
-                let items = [];
-                if (dataSrc === 'url') {
-                    items = await fetchUrlData(selectComponent, search_value, extra.authInfo, evalContext);
-                }
-                else if (dataSrc === 'resource') {
-                    items = await fetchResourceData(selectComponent, search_value, extra.authInfo, project, evalContext);
-                }
+                const items = selectComponent.dataSrc === 'url'
+                    ? await fetchUrlData(selectComponent, search_value, extra.authInfo, evalContext)
+                    : await fetchResourceData(selectComponent, search_value, extra.authInfo, project, evalContext);
                 const options = items.map(item => ({
                     label: extractLabel(item, selectComponent, evalContext),
                     value: extractValue(item, selectComponent)

package/lib/tools/findSubmission.js

@@ -7,8 +7,36 @@ const lodash_1 = require("lodash");
 const SchemaBuilder_1 = require("./SchemaBuilder");
 const annotations_1 = require("./annotations");
 const error = require('debug')('formio:uag:findSubmission:error');
+/** The query parameter suffix for each operator that compares the value as given. */
+const COMPARISON_SUFFIXES = new Map([
+    ['equals', ''],
+    ['greater_than', '__gt'],
+    ['greater_than_equal', '__gte'],
+    ['less_than', '__lt'],
+    ['less_than_equal', '__lte'],
+    ['not_equals', '__ne'],
+]);
+/** The query parameter suffix for each operator that takes comma-separated values. */
+const LIST_SUFFIXES = new Map([
+    ['in', '__in'],
+    ['nin', '__nin'],
+]);
+/** The `__regex` pattern for each operator that matches the value literally. */
+const LITERAL_PATTERNS = new Map([
+    ['contains', (value) => `/${(0, utils_1.escapeSearchPattern)(value)}/i`],
+    ['starts_with', (value) => `/^${(0, utils_1.escapeSearchPattern)(value)}/i`],
+    ['ends_with', (value) => `/${(0, utils_1.escapeSearchPattern)(value)}$/i`],
+]);
+/**
+ * A regex operator's pattern with every "/" in it, bare or escaped, written as
+ * the `\x2f` escape, which matches the same character. See escapeSearchPattern()
+ * for why the query parameter cannot carry a slash.
+ */
+const withoutSlashes = (pattern) => pattern.replace(/\\.|\//g, (match) => (match === '/' || match === '\\/') ? '\\x2f' : match);
+/** The last 4 characters of a submission's id, which users disambiguate with. */
+const partialIdOf = (submission) => submission._id ? submission._id.toString().slice(-4) : 'N/A';
 const findSubmission = async (project) => {
-    return (0, lodash_1.defaultsDeep)(project.config?.toolOverrides?.find_submissions || {}, {
+    return (0, lodash_1.defaultsDeep)({}, project.config?.toolOverrides?.find_submissions, {
         name: 'find_submissions',
         title: 'Find submissions within a form',
         description: 'Find existing form submissions based on field values (search query). Use this to search for people, records, or data by name, email, phone, position, company, or other field values. Examples: find a contact by name, find someone who works at a company, find records with specific criteria. To retrieve the total count of records within a form, use this tool without providing a `search_query`.',
@@ -36,6 +64,8 @@ const findSubmission = async (project) => {
                             error: 'Each search criterion must include both data_path and search_value'
                         }, true);
                     }
+                    let key;
+                    let value;
                     if (criterion.operator === 'regex') {
                         // The value is a pattern by request here, so it is passed through
                         // unescaped. It is still compiled first: the server drops a filter
@@ -51,42 +81,20 @@ const findSubmission = async (project) => {
                                 error: `"${criterion.search_value}" is not a valid regular expression for "${criterion.data_path}". Use the "contains" operator to search for it literally.`
                             }, true);
                         }
-                        query[`data.${criterion.data_path}__regex`] = `/${criterion.search_value}/i`;
+                        key = `data.${criterion.data_path}__regex`;
+                        value = `/${withoutSlashes(criterion.search_value)}/i`;
                     }
-                    else if (criterion.operator === 'equals') {
-                        query[`data.${criterion.data_path}`] = criterion.search_value;
+                    else if (LITERAL_PATTERNS.has(criterion.operator)) {
+                        key = `data.${criterion.data_path}__regex`;
+                        value = LITERAL_PATTERNS.get(criterion.operator)(criterion.search_value);
                     }
-                    else if (criterion.operator === 'contains') {
-                        query[`data.${criterion.data_path}__regex`] = `/${(0, utils_1.escapeSearchPattern)(criterion.search_value)}/i`;
+                    else if (COMPARISON_SUFFIXES.has(criterion.operator)) {
+                        key = `data.${criterion.data_path}${COMPARISON_SUFFIXES.get(criterion.operator)}`;
+                        value = criterion.search_value;
                     }
-                    else if (criterion.operator === 'starts_with') {
-                        query[`data.${criterion.data_path}__regex`] = `/^${(0, utils_1.escapeSearchPattern)(criterion.search_value)}/i`;
-                    }
-                    else if (criterion.operator === 'ends_with') {
-                        query[`data.${criterion.data_path}__regex`] = `/${(0, utils_1.escapeSearchPattern)(criterion.search_value)}$/i`;
-                    }
-                    else if (criterion.operator === 'greater_than') {
-                        query[`data.${criterion.data_path}__gt`] = criterion.search_value;
-                    }
-                    else if (criterion.operator === 'greater_than_equal') {
-                        query[`data.${criterion.data_path}__gte`] = criterion.search_value;
-                    }
-                    else if (criterion.operator === 'less_than') {
-                        query[`data.${criterion.data_path}__lt`] = criterion.search_value;
-                    }
-                    else if (criterion.operator === 'less_than_equal') {
-                        query[`data.${criterion.data_path}__lte`] = criterion.search_value;
-                    }
-                    else if (criterion.operator === 'not_equals') {
-                        query[`data.${criterion.data_path}__ne`] = criterion.search_value;
-                    }
-                    else if (criterion.operator === 'in') {
-                        const values = criterion.search_value.split(',').map((v) => v.trim());
-                        query[`data.${criterion.data_path}__in`] = values;
-                    }
-                    else if (criterion.operator === 'nin') {
-                        const values = criterion.search_value.split(',').map((v) => v.trim());
-                        query[`data.${criterion.data_path}__nin`] = values;
+                    else if (LIST_SUFFIXES.has(criterion.operator)) {
+                        key = `data.${criterion.data_path}${LIST_SUFFIXES.get(criterion.operator)}`;
+                        value = criterion.search_value.split(',').map((v) => v.trim());
                     }
                     else {
                         return project.mcpResponse(template_1.ResponseTemplate.submissionSearchError, {
@@ -95,6 +103,16 @@ const findSubmission = async (project) => {
                             error: `Unsupported operator "${criterion.operator}"`
                         }, true);
                     }
+                    // Criteria are ANDed, but each query parameter holds one value: a
+                    // second one would replace the first and widen the search.
+                    if (key in query) {
+                        return project.mcpResponse(template_1.ResponseTemplate.submissionSearchError, {
+                            form: form.form,
+                            searchQuery: search_query,
+                            error: `"${criterion.data_path}" has two criteria that cannot be combined (contains, starts_with, ends_with and regex count as one kind). Use a single "regex" criterion that matches both, or "in"/"nin" for several values.`
+                        }, true);
+                    }
+                    query[key] = value;
                 }
             }
             try {
@@ -129,7 +147,7 @@ const findSubmission = async (project) => {
                         formName: form_name
                     });
                 }
-                if (submission_id_partial && submissions.length > 1) {
+                if (submission_id_partial) {
                     const matchingSubmissions = submissions.filter(sub => sub._id && sub._id.toString().toLowerCase().includes(submission_id_partial.toLowerCase()));
                     if (matchingSubmissions.length === 0) {
                         return project.mcpResponse(template_1.ResponseTemplate.submissionPartialIdNotFound, {
@@ -138,7 +156,7 @@ const findSubmission = async (project) => {
                             partialId: submission_id_partial,
                             availableSubmissions: submissions.map(sub => ({
                                 ...form.formatSubmission(sub),
-                                partialId: sub._id ? sub._id.toString().slice(-4) : 'N/A'
+                                partialId: partialIdOf(sub)
                             }))
                         }, true);
                     }
@@ -150,35 +168,23 @@ const findSubmission = async (project) => {
                             matchingSubmissions: matchingSubmissions.map(sub => ({
                                 ...form.formatSubmission(sub),
                                 fullId: sub._id,
-                                partialId: sub._id ? sub._id.toString().slice(-4) : 'N/A'
+                                partialId: partialIdOf(sub)
                             }))
                         }, true);
                     }
                     submissions = matchingSubmissions;
                 }
-                function getFieldValues(submission) {
-                    if (!fields_requested || fields_requested.length === 0) {
-                        return [];
-                    }
-                    const data = [];
-                    for (const fieldPath of fields_requested) {
-                        data.push({ path: fieldPath, value: (0, lodash_1.get)(submission.data, fieldPath, null) });
-                    }
-                    return data;
-                }
                 return project.mcpResponse(template_1.ResponseTemplate.submissionsFound, {
                     form: form.form,
                     searchQuery: JSON.stringify(search_query),
                     submissionCount,
-                    submissions: submissions.map(sub => {
-                        return {
-                            _id: sub._id,
-                            created: sub.created,
-                            modified: sub.modified,
-                            data: getFieldValues(sub),
-                            partialId: sub._id ? sub._id.toString().slice(-4) : 'N/A'
-                        };
-                    })
+                    submissions: submissions.map(sub => ({
+                        _id: sub._id,
+                        created: sub.created,
+                        modified: sub.modified,
+                        data: (fields_requested || []).map((path) => ({ path, value: (0, lodash_1.get)(sub.data, path, null) })),
+                        partialId: partialIdOf(sub)
+                    }))
                 });
             }
             catch (err) {