@formio/uag 1.13.2 → 2.0.0-rc.10

package/bin/uag-eval.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/**
+ * uag-eval: measure decision accuracy against automation on labeled examples.
+ *
+ *   uag-eval --form claim.json --examples claim-examples.json [--task triage]
+ *            [--engine jev] [--json report.json]
+ *
+ * --form      A Form.io form definition (JSON export).
+ * --task      The task to evaluate (default: the form's first).
+ * --examples  A JSON array of { "id", "data": { ... }, "expected": { "<path>": <value or null> } }.
+ *             null means "the input does not say", which expects the field to stay empty.
+ * --engine    The decision engine to evaluate: an instance named in UAG_ENGINES, or an
+ *             entry in its syntax (`jev`, `next:jev`). Default: the first in UAG_ENGINES.
+ * --json      Also write the full report as JSON.
+ * --project   The project URL the evaluation runs for (default: none). A real engine
+ *             needs a LICENSE_KEY that includes the UAG for this URL; the stub
+ *             engines need neither.
+ *
+ * The engine is loaded as the UAG loads it, so the same UAG_ENGINES and
+ * UAG_ENGINE_* variables give the same instance, with the same model. Its type
+ * may be built in, or an installed engine package. Resource-backed selects need
+ * a live project and are skipped.
+ */
+require('dotenv/config');
+const { readFileSync, writeFileSync } = require('fs');
+const { parseInstances } = require('@formio/uag-sdk');
+const { ProjectInterface, UAGProjectInterface, UAGFormInterface, loadUAGEngines } = require('../lib');
+const { FormflowService, formatReport } = require('../lib/formflow');
+
+/**
+ * The instance to evaluate: the one UAG_ENGINES names `name`, so a deployed
+ * instance is evaluated with its own settings, or else `name` as an entry.
+ */
+function engineEntry(name, env) {
+    const deployed = parseInstances(env.UAG_ENGINES);
+    if (!name) return deployed[0];
+    return deployed.find((instance) => instance.name === name) || parseInstances(name)[0];
+}
+
+function args(argv) {
+    const out = {};
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i].startsWith('--')) out[argv[i].slice(2)] = argv[i + 1];
+    }
+    return out;
+}
+
+async function main() {
+    const opts = args(process.argv.slice(2));
+    if (!opts.form || !opts.examples) {
+        console.error('Usage: uag-eval --form <form.json> --examples <examples.json> [--task <name>] [--engine <name>] [--json <out.json>] [--project <url>]');
+        process.exit(2);
+    }
+    if (opts.persona !== undefined) {
+        console.error('uag-eval: --persona was renamed --task in UAG 2.0.');
+        process.exit(2);
+    }
+    const task = opts.task || undefined;
+    const formDef = JSON.parse(readFileSync(opts.form, 'utf8'));
+    const examples = JSON.parse(readFileSync(opts.examples, 'utf8'));
+    const entry = engineEntry(opts.engine, process.env);
+    if (!entry) {
+        console.error('Name the decision engine with --engine or UAG_ENGINES.');
+        process.exit(2);
+    }
+
+    const registry = await loadUAGEngines({ engines: [entry] }, process.env);
+    const engine = registry.decision[0];
+    if (!engine) {
+        console.error(`"${registry.all[0].name}" is not a decision engine.`);
+        process.exit(2);
+    }
+
+    // The license the evaluation may use, read as a running UAG reads it.
+    await ProjectInterface.connect({ config: { license: String(process.env.UAG_LICENSE || ''), licenseType: 'uagServer', licenseFeature: 'uag' } });
+    // Build the form offline. Outside a running server the project would create
+    // the base form class, so the UAG form interface is constructed directly.
+    const project = new UAGProjectInterface(opts.project || 'http://offline.invalid');
+    const name = formDef.name || formDef.path || 'form';
+    formDef.tags = [...new Set([...(formDef.tags || []), 'uag'])];
+    // The constructor sets the form, which derives its UAG registration and tasks.
+    const form = new UAGFormInterface(project, formDef);
+    project.forms[name] = form;
+
+    const report = await new FormflowService(project).evaluate(form, task, examples, engine, {}, (done, total) => {
+        process.stderr.write(`\r${done}/${total} example(s)`);
+    });
+    process.stderr.write('\n');
+    console.log(formatReport(report));
+    if (opts.json) {
+        writeFileSync(opts.json, JSON.stringify(report, null, 2));
+        console.log(`Report written to ${opts.json}`);
+    }
+}
+
+main().catch((err) => {
+    console.error(err.message || err);
+    process.exit(1);
+});

package/bin/uag.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * uag: start the Form.io UAG.
+ *
+ *   uag                       the UAG with no module
+ *   UAG_MODULE=./my-module uag
+ *
+ * Configuration comes from the environment (PROJECT, PROJECT_KEY or ADMIN_KEY,
+ * JWT_SECRET, UAG_ENGINES, MONGO, ...) and an optional module: a file or
+ * folder exporting `{ config, actions, ... }`, named by UAG_MODULE.
+ *
+ * Engines are found among the installed packages, so a custom image holds only
+ * the engines it installs:
+ *
+ *   npm install @formio/uag@rc @formio/uag-claude@rc
+ *   UAG_ENGINES=claude CLAUDE_API_KEY=... npx uag
+ */
+// Before anything else, so a module that reads the environment sees .env too.
+require('dotenv/config');
+const path = require('path');
+
+/** isolated-vm, which runs form logic, needs Node's startup snapshot off. */
+function snapshotDisabled() {
+    return process.execArgv.includes('--no-node-snapshot') || /(^|\s)--no-node-snapshot(\s|$)/.test(process.env.NODE_OPTIONS || '');
+}
+
+/** Run this file again with the flag, passing signals on, and exit as it does. */
+function restartWithoutSnapshot() {
+    const { spawn } = require('child_process');
+    const child = spawn(process.execPath, ['--no-node-snapshot', ...process.execArgv, __filename, ...process.argv.slice(2)], { stdio: 'inherit' });
+    for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+        process.on(signal, () => child.kill(signal));
+    }
+    child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)));
+}
+
+/** Start the UAG with a module, listening on PORT (default 3200). */
+async function start(uagModule) {
+    const Express = require('express');
+    const { UAGServer, trustProxySetting, usePluginFiles } = require('../lib');
+    const server = new UAGServer();
+    // A module may be exported as a promise (an async module).
+    const resolved = await uagModule;
+    if (resolved) server.use(resolved);
+    // Then the plugins files: UAG_PLUGINS, or the image's /app/plugins (its
+    // index.mjs, or each add-on's folder under it).
+    await usePluginFiles(server);
+    const app = Express();
+    // Behind a reverse proxy, its forwarded headers give the public URL (TRUST_PROXY).
+    const trust = trustProxySetting(process.env.TRUST_PROXY);
+    if (trust !== undefined) app.set('trust proxy', trust);
+    // Loads the engines the module's `engines` setting, or else UAG_ENGINES,
+    // names; a misconfigured engine stops startup with its name in the error.
+    app.use(await server.router());
+    const port = process.env.PORT || 3200;
+    const listener = await new Promise((resolve) => {
+        const started = app.listen(port, () => resolve(started));
+    });
+    stopOnSignals(server, listener);
+    console.log(`Form.io UAG server running on port ${port}`);
+    console.log(`Visit http://localhost:${port} to access the application`);
+}
+
+/**
+ * On SIGTERM or SIGINT, stop taking connections and destroy the server, which
+ * calls each module's `close` and each plugin's, then exit. A shutdown that
+ * takes longer than `timeoutMs` exits with 1.
+ */
+function stopOnSignals(server, listener, { signals = ['SIGTERM', 'SIGINT'], exit = (code) => process.exit(code), on = process, timeoutMs = 10000 } = {}) {
+    let stopping = false;
+    const stop = async (signal) => {
+        if (stopping) return;
+        stopping = true;
+        console.log(`Received ${signal}: stopping the UAG.`);
+        const timer = setTimeout(() => {
+            console.error(`The UAG did not stop within ${timeoutMs} ms.`);
+            exit(1);
+        }, timeoutMs);
+        if (timer.unref) timer.unref();
+        if (listener) listener.close();
+        let code = 0;
+        try {
+            await server.destroy();
+        }
+        catch (error) {
+            console.error('Failed to stop the UAG cleanly:', error);
+            code = 1;
+        }
+        clearTimeout(timer);
+        exit(code);
+    };
+    // Not once: a repeated signal (a terminal's Ctrl-C reaches the restarted
+    // process twice, from the terminal and from its parent) must not fall back
+    // to Node's default handler and end the shutdown early.
+    for (const signal of signals) on.on(signal, () => stop(signal));
+    return stop;
+}
+
+function fail(error) {
+    console.error('Failed to start server:', error);
+    process.exit(1);
+}
+
+if (require.main === module) {
+    if (!snapshotDisabled()) {
+        restartWithoutSnapshot();
+    }
+    else {
+        Promise.resolve()
+            .then(() => (process.env.UAG_MODULE ? require(path.resolve(process.env.UAG_MODULE)) : undefined))
+            .then(start)
+            .catch(fail);
+    }
+}
+
+module.exports = { start, fail, stopOnSignals };

package/lib/UAGFormInterface.d.ts

@@ -1,7 +1,9 @@
 import { AppServerForm, AuthRequest, FormInterface, InterpolatedError } from "@formio/appserver";
+import type { FormflowForm, FormflowTask } from "./formflow";
 import { Component, Submission, DataObject, ComponentPaths } from "@formio/core";
 import { UAGForm } from "./config";
 import { ParentInfo } from "./tools";
+import { Router } from "express";
 export type UAGComponentInfo = {
     path: string;
     label: string;
@@ -49,14 +51,48 @@ export type FormFieldInfo = {
         components: UAGComponentInfo[];
     };
 };
+/** A field a chat may collect, with its current value. */
+export type ChatField = UAGComponentInfo & {
+    required: boolean;
+    empty: boolean;
+    value: any;
+};
+/** A component a chat cannot collect yet. */
+export type ChatUnsupportedField = {
+    path: string;
+    label: string;
+    required: boolean;
+    empty: boolean;
+};
+export type ChatFields = {
+    fields: ChatField[];
+    unsupported: ChatUnsupportedField[];
+    errors: FormFieldError[];
+};
 export type UAGFields = {
-    persona: string;
+    task: string;
     criteria: string;
     components: Record<string, UAGComponentInfo>;
+    /** Data paths of the components flagged `uagField: "input"`: the source text for extraction and decisions. */
+    inputs?: string[];
+    /** Task-level settings, read from the custom properties of the task's criteria component (e.g. `uagEngine`, `uagTools`). */
+    settings?: Record<string, string>;
 };
-export declare class UAGFormInterface extends FormInterface {
+export declare class UAGFormInterface extends FormInterface implements FormflowForm {
     uag: UAGForm | null;
     uagFields: Record<string, UAGFields>;
+    /**
+     * The form's routes, with its agent operations (`agent/extract`, `agent/decide`,
+     * `agent/generate`, `agent/chat`) beside its submissions: the project's authentication has
+     * already run, and the form is the one of the URL.
+     */
+    router(): Promise<Router>;
+    /**
+     * Sets the form, deriving its UAG registration and agent fields from it. The form is set again
+     * whenever it loads, and whenever a TTL refresh or a deploy brings a new version, so both are
+     * rebuilt from the form each time rather than added to what an earlier version left.
+     */
+    setForm(form: AppServerForm): AppServerForm;
     setComponent(form: AppServerForm, component: Component, path: string, components: Component[] | undefined, parent: Component | undefined, paths: ComponentPaths | undefined): void;
     getComponentFormat(component: Component): string;
     getComponentInfo(component: Component, path: string): UAGComponentInfo;
@@ -111,6 +147,19 @@ export declare class UAGFormInterface extends FormInterface {
      * @returns { Promise<FormFieldInfo> } - The extracted form field information.
      */
     getFields(submission: Submission, authInfo: AuthRequest, within?: string | string[]): Promise<FormFieldInfo>;
+    /** Whether the chat cannot collect this component yet, so the person finishes it in the form. */
+    isChatUnsupported(component: Component): boolean;
+    /** Data paths of the fields a task fills: its decision and value fields, not its inputs. */
+    taskOwnedPaths(): Set<string>;
+    /**
+     * The fields a chat may collect on this data: visible input fields that a
+     * person may enter, filled or not, with the rules the MCP tools give
+     * agents. Fields a task fills (and `uagAuthoritative` ones), hidden,
+     * disabled and calculated fields are left out; components the chat
+     * cannot collect yet are listed in `unsupported`, and their children are
+     * not visited.
+     */
+    chatFields(submission: Submission, authInfo: AuthRequest): Promise<ChatFields>;
     /**
      * Return the component at the specified data path.
      * @param path { string } - The data path of the component to retrieve.
@@ -133,5 +182,26 @@ export declare class UAGFormInterface extends FormInterface {
     convertToSubmission(data?: Record<string, any>): Submission;
     formatData(data?: DataObject): UAGData;
     formatSubmission(submission: Submission): UAGSubmission;
+    /** The form's name in Agentic Formflow responses and messages. */
+    get formflowName(): string;
+    /** The form's tasks, for Agentic Formflow. */
+    formflowTasks(): Record<string, FormflowTask>;
+    /** The submission's values in form order with their labels, for Agentic Formflow. */
+    formflowLabeledData(data?: DataObject): {
+        path: string;
+        label: string;
+    }[];
+    /**
+     * A value an agent engine generated, before it is checked and written: HTML
+     * for a rich text field is reduced to the markup its editor keeps.
+     */
+    formflowNormalizeValue(component: Component, value: any): any;
+    /**
+     * A value an MCP client writes at a data path (collect_field_data,
+     * confirm_form_submission, submit_completed_form, submission_update), as
+     * an engine's is: HTML for a rich text field is reduced to the markup its
+     * editor keeps. Row indices are ignored to find the component.
+     */
+    normalizeWrittenValue(path: string, value: any): any;
     htmlToMarkdown(html: string): string;
 }