@formio/uag 1.13.2 → 2.0.0-rc.10

package/lib/actions/runTask.js

@@ -0,0 +1,324 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RunTaskAction = exports.RUN_TASK = void 0;
+exports.ownedFieldHooks = ownedFieldHooks;
+exports.onBehalfHook = onBehalfHook;
+exports.runTaskHooks = runTaskHooks;
+const appserver_1 = require("@formio/appserver");
+const formflow_1 = require("../formflow");
+const runner_1 = require("../runner");
+const protocol_1 = require("@formio/uag-sdk/protocol");
+const requestId_1 = require("../agent/requestId");
+const errors_1 = require("../agent/errors");
+const identity_1 = require("../identity");
+const debug = require('debug')('formio:uag:actions:runTask');
+exports.RUN_TASK = 'agentRunTask';
+/** The tasks a form defines. */
+const tasksOf = (form) => Object.keys(form.uagFields || {});
+/** The form's Run task actions, for a method (create or update) when one is given, whatever their conditions. */
+function runTaskActions(form, method) {
+    return Object.values(form.project.template?.actions || {}).filter((action) => action?.name === exports.RUN_TASK
+        && (action.form?.split(':').pop() || '') === form.form.machineName
+        && (!method || (action.method || []).includes(method))
+        && action.settings?.task);
+}
+/**
+ * Remove, from what a client sends, the values of the fields each of the form's
+ * Run task actions owns and marks `uagAuthoritative`: on an update they keep
+ * their stored values; on a create they start empty. This covers every Run
+ * task action on the form, whatever its method, conditions or when it runs, so
+ * a client can never store a value the server decides: not before the task
+ * runs, and not through a method the task does not run on. The runner's own
+ * save is not a client's, and is left alone.
+ *
+ * As `before:submission:<op>` hooks, these run after an update has loaded the
+ * stored submission and before the request's data replaces it.
+ */
+function ownedFieldHooks() {
+    const hook = (op) => async (form) => {
+        if (!runTaskActions(form).length)
+            return form;
+        return async (req, res, next) => {
+            if (req[runner_1.RUN_TASK_SAVE])
+                return next();
+            const actions = runTaskActions(form);
+            const tasks = new Set(tasksOf(form));
+            if (op === 'update') {
+                let body = req.body || {};
+                for (const { settings } of actions) {
+                    if (tasks.has(settings.task))
+                        body = (0, formflow_1.withoutOwnedValues)(form, settings.task, body, req.submission || { data: {} });
+                }
+                req.body = body;
+            }
+            else {
+                let submission = req.submission || { data: {} };
+                for (const { settings } of actions) {
+                    if (tasks.has(settings.task))
+                        submission = (0, formflow_1.withoutOwnedValues)(form, settings.task, submission);
+                }
+                req.submission = submission;
+            }
+            next();
+        };
+    };
+    return { 'before:submission:create': hook('create'), 'before:submission:update': hook('update') };
+}
+/**
+ * Decide how a submission is created through the UAG, from the form's
+ * submission access and its Run task actions that run on create:
+ * - a caller whose roles may create submissions creates it with their own token;
+ * - otherwise, when an action names an agent role the form grants "Create All",
+ *   and the caller has one of the actions' submitter roles, the agent creates it
+ *   on their behalf, owned by them;
+ * - otherwise the create is refused.
+ * Run as a `before:access:create` hook, before the caller's access is checked.
+ */
+function onBehalfHook() {
+    return async (form) => {
+        if (!runTaskActions(form, 'create').some((action) => action.settings.agentRole))
+            return form;
+        return async (req, res, next) => {
+            const project = form.project;
+            const access = form.accessInfo[appserver_1.AuthorizedMethod.CREATE];
+            const actingFor = (0, identity_1.actingForOf)(req.auth, project);
+            const has = (roles) => appserver_1.AuthRequest.hasRole(actingFor.roles, roles, project);
+            if (req.auth?.admin || has(access[appserver_1.AuthorizedStateType.OWN]) || has(access[appserver_1.AuthorizedStateType.ALL]))
+                return next();
+            const actions = runTaskActions(form, 'create').filter((action) => action.settings.agentRole);
+            const roles = [...new Set(actions.map((action) => project.roleId(String(action.settings.agentRole))))];
+            if (roles.length > 1) {
+                console.error(`[formio-uag] The Run task actions of "${form.name}" that run on create name different agent roles ` +
+                    `(${actions.map((action) => action.title || action.machineName).join(', ')}). Choose one agent role for them all.`);
+                return res.status(500).json({ name: 'ConfigurationError', message: `The form "${form.name}" is not configured correctly: its Run task actions name different agent roles.`, code: 'configuration_error' });
+            }
+            const [role] = roles;
+            const submitters = actions.flatMap((action) => action.settings.submitterRoles || []).map(String);
+            if (!appserver_1.AuthRequest.hasRole([role], access[appserver_1.AuthorizedStateType.ALL], project) || !has(submitters)) {
+                return res.status(403).json({ name: 'ForbiddenError', message: 'You may not submit this form.', code: 'forbidden' });
+            }
+            try {
+                req.forwardAuth = await (0, identity_1.agentAuth)(project, actingFor, role, { task: actions[0].settings.task });
+            }
+            catch (err) {
+                if (err instanceof formflow_1.FormflowError)
+                    return refuse(res, err);
+                throw err;
+            }
+            next();
+        };
+    };
+}
+/** The hooks Run task needs: owned fields kept from clients, and creation on a user's behalf. */
+function runTaskHooks() {
+    return { ...ownedFieldHooks(), 'before:access:create': onBehalfHook() };
+}
+/** The request's X-Request-Id (or the one the runner's save carries on), passed to the engines and the runs it starts. */
+function requestIdOf(req) {
+    return req[runner_1.RUN_TASK_REQUEST_ID] || (0, protocol_1.safeRequestId)(req.get?.('x-request-id')) || undefined;
+}
+/** The runs made before the save on this request, by action, until the save gives them a submission. */
+function runsBefore(req) {
+    const request = req;
+    request.uagRunsBefore = request.uagRunsBefore || new Map();
+    return request.uagRunsBefore;
+}
+/** Answer a Formflow error as JSON with its status. */
+function refuse(res, err) {
+    res.status(err.status).json({
+        name: err.name,
+        message: err.message,
+        code: err.code || (0, errors_1.errorCode)(err.status),
+        ...(err.edition && { edition: err.edition })
+    });
+}
+/**
+ * "Agent: Run task": run one of the form's tasks on a submission sent to the
+ * UAG, before the save (the submitter waits, and Form.io stores the result as
+ * the one save) or after it, in the background (the results are saved as an
+ * update, which runs the form's update actions in turn).
+ */
+exports.RunTaskAction = {
+    get info() {
+        return {
+            name: exports.RUN_TASK,
+            title: 'Agent: Run task',
+            group: 'default',
+            description: 'Runs one of the form\'s agent tasks on the submission, before the save or after it in the background.',
+            priority: 20,
+            defaults: {
+                handler: ['before', 'after'],
+                method: ['create']
+            },
+            access: {
+                handler: false,
+                method: true
+            }
+        };
+    },
+    async settingsForm(form) {
+        const tasks = tasksOf(form);
+        // An agent never acts with an admin role.
+        const roles = Object.values(form.project.access?.roles || {})
+            .filter((role) => role?._id && !role.admin)
+            .map((role) => ({ label: role.title || String(role._id), value: String(role._id) }));
+        return [
+            ...(tasks.length ? [] : [{
+                    type: 'htmlelement',
+                    key: 'noTasks',
+                    tag: 'p',
+                    content: 'This form defines no task. Mark its components with the "uag" property to define one.'
+                }]),
+            {
+                type: 'select',
+                input: true,
+                key: 'task',
+                label: 'Task',
+                tooltip: 'The task to run, from the tasks the form defines.',
+                dataSrc: 'values',
+                data: { values: tasks.map((task) => ({ label: task, value: task })) },
+                validate: { required: true }
+            },
+            {
+                type: 'radio',
+                input: true,
+                key: 'answer',
+                label: 'Answer',
+                defaultValue: 'task',
+                values: [
+                    { label: 'The whole task', value: 'task' },
+                    { label: 'Its decision fields only', value: 'decisions' }
+                ],
+                validate: { required: true }
+            },
+            {
+                type: 'select',
+                input: true,
+                key: 'agentRole',
+                label: 'Agent role',
+                tooltip: 'Act at Form.io with this role, on behalf of the user, to save the task\'s results and to create submissions users may not create themselves. Needs JWT_SECRET to be the same as Form.io Enterprise\'s. Leave empty to act with the user\'s own token.',
+                dataSrc: 'values',
+                data: { values: roles }
+            },
+            {
+                type: 'select',
+                input: true,
+                key: 'submitterRoles',
+                label: 'Submitter roles',
+                tooltip: 'Who may submit this form through the agent when the form does not let their roles create submissions: the agent creates it on their behalf.',
+                multiple: true,
+                dataSrc: 'values',
+                data: { values: roles },
+                customConditional: 'show = !!data.agentRole;'
+            },
+            {
+                type: 'radio',
+                input: true,
+                key: 'when',
+                label: 'When',
+                defaultValue: 'after',
+                values: [
+                    { label: 'After the save, in the background', value: 'after' },
+                    { label: 'Before the save (the submitter waits)', value: 'before' }
+                ],
+                validate: { required: true }
+            }
+        ];
+    },
+    async executor(form, action, handler, method) {
+        const settings = action?.settings || {};
+        const when = settings.when === 'before' ? 'before' : 'after';
+        const answer = settings.answer === 'decisions' ? 'decisions' : 'task';
+        const project = form.project;
+        const title = action?.title || exports.RUN_TASK;
+        if (!settings.task) {
+            return async (req, res, next) => next();
+        }
+        if (when === 'before' && handler === 'before') {
+            return async (req, res, next) => {
+                // The runner's own save carries the agent's results.
+                if (req[runner_1.RUN_TASK_SAVE])
+                    return next();
+                try {
+                    const identity = (0, formflow_1.callerIdentity)(req.auth, req);
+                    // The owned fields were already made the server's own (ownedFieldHooks).
+                    const requestId = requestIdOf(req);
+                    const run = await (0, requestId_1.withRequestId)(requestId, () => (0, formflow_1.formflow)(project).runTask(form, settings.task, req.submission || { data: {} }, req.auth, { answer, stored: true, identity, requestId }));
+                    req.submission = run.submission;
+                    // Recorded once the save gives the submission its id (below).
+                    const failed = run.failed.map((group) => group.error || 'no engine could answer').join('; ');
+                    runsBefore(req).set(action, {
+                        status: failed ? 'failed' : 'done',
+                        written: run.written,
+                        cleared: run.cleared,
+                        engines: run.results.map((result) => ({ kind: result.kind, engine: result.engine ?? null, model: result.model ?? null })),
+                        saved: true,
+                        ...(failed && { error: failed })
+                    });
+                    return next();
+                }
+                catch (err) {
+                    if (err instanceof formflow_1.FormflowError)
+                        return refuse(res, err);
+                    throw err;
+                }
+            };
+        }
+        if (when === 'before') {
+            // After the save: record the run made before it, now that the submission has its id.
+            return async (req, res, next) => {
+                const outcome = runsBefore(req).get(action);
+                const saved = res.resource?.item;
+                if (outcome && saved?._id) {
+                    await (0, runner_1.taskRunner)(project).recordBefore({
+                        form: form.name, formId: String(form.form._id || ''), method, submission: String(saved._id),
+                        task: settings.task, answer, action: title, actingFor: (0, identity_1.actingForOf)(req.auth, project), requestId: requestIdOf(req)
+                    }, outcome);
+                }
+                next();
+            };
+        }
+        if (handler !== 'after') {
+            return async (req, res, next) => next();
+        }
+        return async (req, res, next) => {
+            const saved = res.resource?.item;
+            const chain = req[runner_1.RUN_TASK_CHAIN] || 0;
+            if (saved?._id && chain > runner_1.MAX_CHAIN) {
+                console.error(`[formio-uag] Run task "${settings.task}" was not run on submission ${saved._id} of "${form.name}": ` +
+                    `${runner_1.MAX_CHAIN} runs in a row were each started by the save of the one before. Check that the form's Run task actions do not start each other without end.`);
+            }
+            else if (saved?._id) {
+                // A run the runner's own save starts acts for the same user as the run that saved:
+                // with the caller's own token, or as the user with tokens the UAG signs, never
+                // with the agent role of the run that saved.
+                const actingFor = req[runner_1.RUN_TASK_ACTING_FOR] || (0, identity_1.actingForOf)(req.auth, project);
+                const chained = req[runner_1.RUN_TASK_CALLER];
+                const caller = chained || req.auth;
+                const asUser = !chained && !!req[runner_1.RUN_TASK_AS_USER];
+                // A durable run is recorded before the response is sent.
+                await (0, runner_1.taskRunner)(project).enqueue({
+                    form: form.name,
+                    formId: String(form.form._id || ''),
+                    method,
+                    submission: String(saved._id),
+                    task: settings.task,
+                    answer,
+                    actingFor,
+                    action: title,
+                    requestId: requestIdOf(req),
+                    ...(chain && { chain }),
+                    ...(settings.agentRole
+                        ? { agentRole: project.roleId(String(settings.agentRole)) }
+                        : asUser
+                            ? { asUser: true }
+                            : { caller: caller.clone(), identity: chained ? req[runner_1.RUN_TASK_IDENTITY] : (0, formflow_1.callerIdentity)(caller, req) })
+                });
+            }
+            else {
+                debug(`${form.name}: no saved submission to run "${settings.task}" on`);
+            }
+            next();
+        };
+    }
+};

package/lib/agent/anonymous.d.ts

@@ -0,0 +1,34 @@
+import { NextFunction, Request, Response } from 'express';
+import type { UAGProjectInterface } from '../UAGProjectInterface';
+/** The anonymous limits in force: a per-address and a total count per minute. */
+export declare function anonymousLimits(project: UAGProjectInterface): {
+    perAddress: number;
+    total: number;
+};
+/**
+ * Counts anonymous requests in fixed one-minute windows, per client address and
+ * in total. Addresses are counted only while the total allows, so a window never
+ * holds more addresses than the total limit.
+ */
+export declare class AnonymousLimiter {
+    private windowStart;
+    private total;
+    private addresses;
+    /** Count a request, or say how many seconds remain until one would be allowed. */
+    take(address: string, limits: {
+        perAddress: number;
+        total: number;
+    }, now?: number): {
+        allowed: true;
+    } | {
+        allowed: false;
+        retryAfter: number;
+    };
+}
+/**
+ * Admits a caller with no credential to a form's agent operations only when
+ * the form opts in (`uagAnonymous: "true"` in its custom properties), both
+ * limits allow it, and the form lets the Anonymous role create submissions.
+ * Every refusal comes before any engine is called.
+ */
+export declare function anonymousGate(project: UAGProjectInterface): (req: Request, res: Response, next: NextFunction) => Response<any, Record<string, any>> | undefined;

package/lib/agent/anonymous.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnonymousLimiter = void 0;
+exports.anonymousLimits = anonymousLimits;
+exports.anonymousGate = anonymousGate;
+const formflow_1 = require("../formflow");
+const debug = require('debug')('formio:uag:agent');
+const WINDOW_MS = 60000;
+/** A number from the configuration, else the environment, else the default. */
+function limitOf(configured, env, fallback) {
+    for (const value of [configured, env]) {
+        if (value === undefined || value === null || value === '')
+            continue;
+        const number = Number(value);
+        if (Number.isFinite(number) && number >= 0)
+            return Math.floor(number);
+    }
+    return fallback;
+}
+/** The anonymous limits in force: a per-address and a total count per minute. */
+function anonymousLimits(project) {
+    const configured = project.formflowConfig()?.agentApi?.anonymous || {};
+    return {
+        perAddress: limitOf(configured.rateLimit, process.env.AGENT_ANONYMOUS_RATE_LIMIT, 10),
+        total: limitOf(configured.totalRateLimit, process.env.AGENT_ANONYMOUS_TOTAL_RATE_LIMIT, 100)
+    };
+}
+/**
+ * Counts anonymous requests in fixed one-minute windows, per client address and
+ * in total. Addresses are counted only while the total allows, so a window never
+ * holds more addresses than the total limit.
+ */
+class AnonymousLimiter {
+    constructor() {
+        this.windowStart = 0;
+        this.total = 0;
+        this.addresses = new Map();
+    }
+    /** Count a request, or say how many seconds remain until one would be allowed. */
+    take(address, limits, now = Date.now()) {
+        if (now - this.windowStart >= WINDOW_MS) {
+            this.windowStart = now;
+            this.total = 0;
+            this.addresses.clear();
+        }
+        const retryAfter = Math.max(1, Math.ceil((this.windowStart + WINDOW_MS - now) / 1000));
+        if (this.total >= limits.total)
+            return { allowed: false, retryAfter };
+        const count = this.addresses.get(address) || 0;
+        if (count >= limits.perAddress)
+            return { allowed: false, retryAfter };
+        this.addresses.set(address, count + 1);
+        this.total++;
+        return { allowed: true };
+    }
+}
+exports.AnonymousLimiter = AnonymousLimiter;
+const limiters = new WeakMap();
+function limiterFor(project) {
+    let limiter = limiters.get(project);
+    if (!limiter) {
+        limiter = new AnonymousLimiter();
+        limiters.set(project, limiter);
+    }
+    return limiter;
+}
+/**
+ * Admits a caller with no credential to a form's agent operations only when
+ * the form opts in (`uagAnonymous: "true"` in its custom properties), both
+ * limits allow it, and the form lets the Anonymous role create submissions.
+ * Every refusal comes before any engine is called.
+ */
+function anonymousGate(project) {
+    return (req, res, next) => {
+        const request = req;
+        const form = request.form;
+        const limits = anonymousLimits(project);
+        if (limits.perAddress === 0 || limits.total === 0 || !(0, formflow_1.flagOn)(form?.form?.properties?.uagAnonymous)) {
+            return res.status(401).json({ error: 'Sign in to use this form\'s agent operations and routes.', code: 'sign_in_required' });
+        }
+        const taken = limiterFor(project).take(String(req.ip || req.socket?.remoteAddress || ''), limits);
+        if (!taken.allowed) {
+            debug(`Refused an anonymous ${req.method} ${req.path}: over the anonymous rate limit.`);
+            res.set('Retry-After', String(taken.retryAfter));
+            return res.status(429).json({ error: 'Too many requests. Try again shortly.', code: 'rate_limited' });
+        }
+        let permissions = {};
+        try {
+            permissions = request.auth?.formPermissions?.(form) || {};
+        }
+        catch {
+            permissions = {};
+        }
+        if (!permissions.create) {
+            return res.status(403).json({ error: 'Anonymous visitors may not submit this form.', code: 'forbidden' });
+        }
+        next();
+    };
+}

package/lib/agent/chat.d.ts

@@ -0,0 +1,114 @@
+import type { AuthRequest } from "@formio/appserver";
+import { CHAT_INSTRUCTIONS } from "../formflow";
+import type { AgentEngine } from "../formflow";
+import type { UAGProjectInterface } from "../UAGProjectInterface";
+import type { ChatField, ChatFields, ChatUnsupportedField, FormFieldError, UAGFormInterface } from "../UAGFormInterface";
+/**
+ * A form's chat: one stateless turn of a conversation that fills the form in.
+ *
+ * The client sends the conversation so far and the form's current data; one
+ * agent engine reads them, through the same `extract` contract as the Agent
+ * API, and returns the values the person gave plus the next message to them.
+ * The values are checked against the form here, and the form never leaves the
+ * client's hands: nothing is stored and nothing is saved. The person submits
+ * the form themselves, through the UAG, where its own actions run.
+ *
+ * Chat belongs with the MCP conversation tools, not Agentic Formflow: it runs
+ * no task, decision engine or research, and needs no license.
+ */
+export type ChatMessage = {
+    role: 'user' | 'assistant';
+    content: string;
+};
+export type ChatRequest = {
+    messages: ChatMessage[];
+    data: Record<string, any>;
+    /** Fields the person set in the form itself: the turn never changes them. */
+    locked: string[];
+};
+export type ChatFieldResult = {
+    path: string;
+    label: string;
+    status: 'suggested' | 'invalid';
+    value: any;
+    error?: string;
+};
+export type ChatRemaining = {
+    required: {
+        path: string;
+        label: string;
+    }[];
+    optional: {
+        path: string;
+        label: string;
+    }[];
+    unsupported: ChatUnsupportedField[];
+};
+export type ChatResponse = {
+    requestId?: string;
+    reply: string;
+    patch: Record<string, any>;
+    data: Record<string, any>;
+    fields: Record<string, ChatFieldResult>;
+    errors: FormFieldError[];
+    remaining: ChatRemaining;
+    complete: boolean;
+    confirmed: boolean;
+    engine: {
+        name: string;
+        model: string;
+        latencyMs: number;
+        toolCalls: {
+            name: string;
+            isError: boolean;
+        }[];
+        usage?: {
+            inputTokens?: number | null;
+            outputTokens?: number | null;
+        };
+    };
+};
+/**
+ * The two values of a turn that are not form fields. A Form.io key cannot
+ * start with `-`, so no field's path can be either, and model APIs that limit
+ * property names to letters, digits, `_`, `.` and `-` accept them.
+ */
+export declare const REPLY = "-reply";
+export declare const CONFIRMED = "-confirmed";
+export declare const CHAT_DEFAULTS: {
+    engines: string[];
+    maxIterations: number;
+    maxMessages: number;
+    maxMessageLength: number;
+    maxTranscriptChars: number;
+};
+export type ChatSettings = typeof CHAT_DEFAULTS & {
+    timeout?: number;
+};
+/** The chat settings in force (`agentApi.chat`), with their defaults. */
+export declare function chatSettings(project: UAGProjectInterface): ChatSettings;
+/** Read and check a turn's body, or throw a 400. Nothing is called before this passes. */
+export declare function readChatRequest(body: any, settings: ChatSettings): ChatRequest;
+/**
+ * The newest messages that fit in `maxChars`, starting at one the person
+ * wrote. The newest message always stays, whatever its length.
+ */
+export declare function trimTranscript(messages: ChatMessage[], maxChars: number): ChatMessage[];
+export declare function transcriptText(messages: ChatMessage[]): string;
+/** The instructions every turn runs with (Agentic Formflow's, which builds each turn's request). */
+export { CHAT_INSTRUCTIONS };
+/** The JSON schema of a field's value, for structured extraction. */
+export declare function chatValueSchema(form: UAGFormInterface, field: ChatField): Record<string, any>;
+/** What the form still needs, from its fields on the current data. */
+export declare function remainingOf(fields: ChatFields): ChatRemaining;
+export type ChatContext = {
+    auth: AuthRequest;
+    requestId?: string;
+};
+/** The agent engines that may serve chat, in order. */
+export declare function chatEngines(project: UAGProjectInterface, settings?: ChatSettings): AgentEngine[];
+/**
+ * Run one turn of a form's chat. The caller has already been authenticated,
+ * and checked for create access to the form.
+ */
+export declare function chatTurn(project: UAGProjectInterface, form: UAGFormInterface, body: any, context: ChatContext): Promise<ChatResponse>;