@formio/uag 1.13.2 → 2.0.0-rc.10

package/lib/runner.js

@@ -0,0 +1,353 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskRunner = exports.SWEEP_MS = exports.MAX_CHAIN = exports.RUN_TASK_CHAIN = exports.RUN_TASK_AS_USER = exports.RUN_TASK_IDENTITY = exports.RUN_TASK_REQUEST_ID = exports.RUN_TASK_CALLER = exports.RUN_TASK_ACTING_FOR = exports.RUN_TASK_SAVE = void 0;
+exports.taskRunner = taskRunner;
+const formflow_1 = require("./formflow");
+const identity_1 = require("./identity");
+const runs_1 = require("./runs");
+const requestId_1 = require("./agent/requestId");
+const debug = require('debug')('formio:uag:runner');
+/**
+ * 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.
+ */
+exports.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.
+ */
+exports.RUN_TASK_ACTING_FOR = 'uagActingFor';
+exports.RUN_TASK_CALLER = 'uagCaller';
+exports.RUN_TASK_REQUEST_ID = 'uagRequestId';
+exports.RUN_TASK_IDENTITY = 'uagIdentity';
+exports.RUN_TASK_AS_USER = 'uagAsUser';
+exports.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.
+ */
+exports.MAX_CHAIN = 5;
+const DEFAULT_CONCURRENCY = 4;
+/** How often a replica looks for runs that are pending or lost their replica. */
+exports.SWEEP_MS = 60 * 1000;
+/**
+ * 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.
+ */
+class TaskRunner {
+    constructor(project, concurrency = DEFAULT_CONCURRENCY) {
+        this.project = project;
+        this.concurrency = concurrency;
+        this.queue = [];
+        this.active = 0;
+        this.waiting = [];
+        this.sweeping = false;
+    }
+    /** Whether runs acting with an agent role are recorded and survive a restart. */
+    get durable() {
+        return !!this.store;
+    }
+    /** Record runs in the UAG's database, and take durable runs from it. */
+    useStore(store) {
+        this.store = store;
+        this.stop();
+        this.sweeper = setInterval(() => this.sweep(), exports.SWEEP_MS);
+        this.sweeper.unref?.();
+        this.sweep();
+    }
+    /** Stop sweeping (the runs in progress finish). */
+    stop() {
+        if (this.sweeper)
+            clearInterval(this.sweeper);
+        this.sweeper = undefined;
+    }
+    /** The project's run records, when there is a database. */
+    get records() {
+        return this.store;
+    }
+    /**
+     * 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.
+     */
+    async enqueue(job) {
+        if (this.store) {
+            const durable = !!job.agentRole;
+            try {
+                const record = await this.store.add(this.newRecord(job, durable));
+                if (durable) {
+                    this.sweep();
+                    return;
+                }
+                this.queue.push({ job, record });
+            }
+            catch (err) {
+                console.error(`[formio-uag] Run task "${job.task}" could not be recorded (${err?.message || err}); it runs in memory.`);
+                this.queue.push({ job });
+            }
+        }
+        else {
+            this.queue.push({ job });
+        }
+        this.drain();
+    }
+    /** Record a run made before the save, once the save gave the submission its id. */
+    async recordBefore(job, outcome) {
+        if (!this.store)
+            return;
+        try {
+            const record = await this.store.add({ ...this.newRecord(job, false, 'before'), status: 'running' });
+            await this.store.finish(record, resultOf(outcome));
+        }
+        catch (err) {
+            debug(`Could not record a run before the save: ${err?.message || err}`);
+        }
+    }
+    newRecord(job, durable, handler = 'after') {
+        return {
+            project: String(this.project.project?._id || ''),
+            form: job.formId || '',
+            formName: job.form,
+            submission: job.submission,
+            action: job.action || 'Agent: Run task',
+            task: job.task,
+            answer: job.answer,
+            handler,
+            method: job.method || 'create',
+            durable,
+            actingFor: job.actingFor,
+            ...(job.agentRole && { agentRole: job.agentRole }),
+            ...(job.requestId && { requestId: job.requestId }),
+            ...(job.chain && { chain: job.chain }),
+            status: (durable ? 'pending' : 'running')
+        };
+    }
+    /** Resolves once every queued and running job has finished (for tests and shutdown). */
+    idle() {
+        if (this.isIdle())
+            return Promise.resolve();
+        return new Promise((resolve) => this.waiting.push(resolve));
+    }
+    isIdle() {
+        return !this.active && !this.queue.length && !this.sweeping;
+    }
+    settled() {
+        if (this.isIdle())
+            this.waiting.splice(0).forEach((resolve) => resolve());
+    }
+    drain() {
+        while (this.active < this.concurrency && this.queue.length) {
+            const { job, record } = this.queue.shift();
+            this.track(job, record ? (outcome) => this.store.finish(record, resultOf(outcome)) : undefined);
+        }
+    }
+    /** Take durable runs from the database while there is room. */
+    async sweep() {
+        if (!this.store || this.sweeping)
+            return;
+        this.sweeping = true;
+        try {
+            while (this.active < this.concurrency) {
+                const record = await this.store.claim();
+                if (!record)
+                    break;
+                this.runRecord(record);
+            }
+        }
+        catch (err) {
+            debug(`Could not take runs from the database: ${err?.message || err}`);
+        }
+        finally {
+            this.sweeping = false;
+            this.settled();
+        }
+    }
+    runRecord(record) {
+        const store = this.store;
+        const renewal = setInterval(() => store.renew(record._id).catch(() => { }), runs_1.RENEW_MS);
+        renewal.unref?.();
+        this.track(jobOf(record), (outcome) => store.finish(record._id, resultOf(outcome)), () => {
+            clearInterval(renewal);
+            this.sweep();
+        });
+    }
+    /** Run a job, report it, and record its end. */
+    track(job, finish, done) {
+        this.active++;
+        // Engines (the remote type) send the id of the request that started the run.
+        (0, requestId_1.withRequestId)(job.requestId, () => this.execute(job))
+            .catch((err) => ({ status: 'failed', written: {}, cleared: [], engines: [], saved: false, error: err?.message || String(err) }))
+            .then(async (outcome) => {
+            this.report(job, outcome);
+            await finish?.(outcome).catch((err) => debug(`Could not record the end of a run: ${err?.message || err}`));
+        })
+            .finally(() => {
+            this.active--;
+            done?.();
+            this.drain();
+            this.settled();
+        });
+    }
+    report(job, outcome) {
+        if (outcome.status === 'failed') {
+            console.error(`[formio-uag] Run task "${job.task}" failed for submission ${job.submission} of "${job.form}": ${outcome.error}`);
+        }
+        else {
+            debug(`Run task "${job.task}" on ${job.form}/${job.submission}: ${outcome.saved ? `saved ${Object.keys(outcome.written).length} field(s)` : 'nothing changed'}`);
+        }
+    }
+    /**
+     * 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.
+     */
+    async identities(job) {
+        if (job.agentRole) {
+            const claim = { action: job.action, task: job.task };
+            const research = await (0, identity_1.userAuth)(this.project, job.actingFor, claim);
+            return {
+                act: () => (0, identity_1.agentAuth)(this.project, job.actingFor, job.agentRole, claim),
+                research,
+                identity: (0, formflow_1.identityOf)(research, `Bearer ${research.token}`)
+            };
+        }
+        if (job.asUser) {
+            const claim = { action: job.action, task: job.task };
+            const research = await (0, identity_1.userAuth)(this.project, job.actingFor, claim);
+            return {
+                act: () => (0, identity_1.userAuth)(this.project, job.actingFor, claim),
+                research,
+                identity: (0, formflow_1.identityOf)(research, `Bearer ${research.token}`)
+            };
+        }
+        if (!job.caller)
+            throw new formflow_1.FormflowError(500, 'A run without an agent role needs the caller\'s identity.');
+        const caller = job.caller;
+        return { act: async () => caller.clone(), research: caller, identity: job.identity };
+    }
+    /**
+     * 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.
+     */
+    async refusal(job) {
+        if (!job.agentRole || !this.project.endpoint)
+            return null;
+        try {
+            const auth = await (0, identity_1.agentAuth)(this.project, job.actingFor, job.agentRole, { action: job.action, task: job.task });
+            const response = await fetch(`${this.project.endpoint}/current`, { headers: { 'x-jwt-token': auth.token || '', Accept: 'application/json' } });
+            return (0, identity_1.refusedSignedToken)(response.status);
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Run one job to completion. */
+    async execute(job) {
+        try {
+            return await this.run(job);
+        }
+        catch (err) {
+            throw (await this.refusal(job)) || err;
+        }
+    }
+    async run(job) {
+        const form = await this.project.formflowForm(job.form);
+        if (!form)
+            throw new formflow_1.FormflowError(404, `The form "${job.form}" was not found.`);
+        const { act, research, identity } = await this.identities(job);
+        const service = (0, formflow_1.formflow)(this.project);
+        const load = async () => {
+            const stored = await form.loadSubmission(job.submission, await act());
+            // Form.io answers a submission the caller may not read as missing, so say both.
+            if (!stored)
+                throw new formflow_1.FormflowError(404, `Submission "${job.submission}" was not found, or the user the run acts as may not read it (give submitters Read Own access, or the action an agent role).`);
+            return stored;
+        };
+        let stored = await load();
+        for (let attempt = 1;; attempt++) {
+            const run = await service.runTask(form, job.task, stored, research, { answer: job.answer, stored: true, identity, requestId: job.requestId });
+            const engines = run.results.map((result) => ({ kind: result.kind, engine: result.engine ?? null, model: result.model ?? null }));
+            const failed = run.failed.map((group) => group.error || 'no engine could answer').join('; ');
+            const changed = Object.keys(run.written).length > 0 || run.cleared.length > 0;
+            const refused = run.refused || {};
+            if (Object.keys(refused).length) {
+                console.warn(`[formio-uag] Run task "${job.task}" left out answers the form refused for submission ${job.submission} of "${job.form}": ` +
+                    Object.entries(refused).map(([path, message]) => `${path} (${message})`).join('; '));
+            }
+            const left = Object.keys(refused).length ? { refused } : {};
+            if (!changed) {
+                return { status: failed ? 'failed' : 'done', written: {}, cleared: [], engines, saved: false, ...left, ...(failed && { error: failed }) };
+            }
+            try {
+                // Only the task's fields changed; `modified` refuses the save if a person saved in the meantime.
+                await form.submit({ _id: stored._id, modified: stored.modified, data: run.submission.data, metadata: run.submission.metadata }, await act(), {
+                    [exports.RUN_TASK_SAVE]: true,
+                    [exports.RUN_TASK_ACTING_FOR]: job.actingFor,
+                    ...(job.requestId && { [exports.RUN_TASK_REQUEST_ID]: job.requestId }),
+                    // The runs this save starts act as the user, never with this run's agent role.
+                    ...(job.caller ? { [exports.RUN_TASK_CALLER]: job.caller, [exports.RUN_TASK_IDENTITY]: job.identity } : { [exports.RUN_TASK_AS_USER]: true }),
+                    [exports.RUN_TASK_CHAIN]: (job.chain || 0) + 1
+                });
+                return { status: failed ? 'failed' : 'done', written: run.written, cleared: run.cleared, engines, saved: true, ...left, ...(failed && { error: failed }) };
+            }
+            catch (err) {
+                if (err?.name !== 'ConflictError' || attempt >= 2) {
+                    if (err?.name === 'ConflictError') {
+                        throw new formflow_1.FormflowError(409, 'The submission changed while its task was running, and again on the second try. Nothing was saved.');
+                    }
+                    throw err;
+                }
+                stored = await load();
+            }
+        }
+    }
+}
+exports.TaskRunner = TaskRunner;
+/** What a record keeps of a run's outcome: paths, never values. */
+function resultOf(outcome) {
+    return {
+        status: outcome.status,
+        engines: outcome.engines,
+        written: Object.keys(outcome.written),
+        cleared: outcome.cleared,
+        ...(outcome.refused && { refused: Object.keys(outcome.refused) }),
+        saved: outcome.saved,
+        ...(outcome.error && { error: outcome.error })
+    };
+}
+/** The job a durable record describes. */
+function jobOf(record) {
+    return {
+        form: record.formName,
+        formId: record.form,
+        submission: record.submission,
+        task: record.task,
+        answer: record.answer,
+        actingFor: record.actingFor,
+        agentRole: record.agentRole,
+        action: record.action,
+        method: record.method,
+        ...(record.requestId && { requestId: record.requestId }),
+        ...(record.chain && { chain: record.chain })
+    };
+}
+/** The project's runner, created on first use. */
+const runners = new WeakMap();
+function taskRunner(project) {
+    let runner = runners.get(project);
+    if (!runner) {
+        runner = new TaskRunner(project);
+        runners.set(project, runner);
+    }
+    return runner;
+}

package/lib/runs.d.ts

@@ -0,0 +1,27 @@
+import { ObjectId } from 'mongodb';
+import type { ActingFor } from './identity';
+import { LEASE_MS, MAX_ATTEMPTS, RENEW_MS } from './formflow';
+import type { CoreNewTaskRun, CoreTaskRunRecord, CoreTaskRunStore, TaskRunStatus } from './formflow';
+/**
+ * Run task records in the UAG's database (`uag-taskruns`): one per run, for
+ * audit (Action Logs), and, for runs that act with an agent role, the queue
+ * that lets a run survive a restart and be taken by one replica at a time.
+ * A record never holds a token.
+ *
+ * The store is Agentic Formflow's (`useDatabase`); the UAG gives it the
+ * collection and its ids.
+ */
+export type { TaskRunStatus };
+export type TaskRunRecord = CoreTaskRunRecord<ObjectId> & {
+    actingFor: ActingFor;
+};
+export type NewTaskRun = CoreNewTaskRun<ObjectId> & {
+    actingFor: ActingFor;
+};
+export type TaskRunStore = CoreTaskRunStore<ObjectId>;
+export { LEASE_MS, MAX_ATTEMPTS, RENEW_MS };
+/** The ids of the UAG's database: MongoDB ObjectIds. */
+export declare const OBJECT_IDS: {
+    create: () => ObjectId;
+    parse: (id: string) => ObjectId | null;
+};

package/lib/runs.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OBJECT_IDS = exports.RENEW_MS = exports.MAX_ATTEMPTS = exports.LEASE_MS = void 0;
+const mongodb_1 = require("mongodb");
+const formflow_1 = require("./formflow");
+Object.defineProperty(exports, "LEASE_MS", { enumerable: true, get: function () { return formflow_1.LEASE_MS; } });
+Object.defineProperty(exports, "MAX_ATTEMPTS", { enumerable: true, get: function () { return formflow_1.MAX_ATTEMPTS; } });
+Object.defineProperty(exports, "RENEW_MS", { enumerable: true, get: function () { return formflow_1.RENEW_MS; } });
+/** The ids of the UAG's database: MongoDB ObjectIds. */
+exports.OBJECT_IDS = {
+    create: () => new mongodb_1.ObjectId(),
+    parse: (id) => (mongodb_1.ObjectId.isValid(id) ? new mongodb_1.ObjectId(id) : null)
+};

package/lib/template.js

@@ -89,18 +89,16 @@ class UAGTemplate {
      * @returns The compiled template function
      */
     getTemplate(templateName) {
-        if (this.templateCache.has(templateName)) {
-            return this.templateCache.get(templateName);
+        const cached = this.templateCache.get(templateName);
+        if (cached) {
+            return cached;
         }
-        let templateContent = '';
-        if (this.config[templateName]) {
-            templateContent = this.config[templateName];
-        }
-        else {
-            const templatePath = path.join(path.join(__dirname, 'templates') || '', `${templateName}.md`);
+        let templateContent = this.config[templateName];
+        if (!templateContent) {
+            const templatePath = path.join(__dirname, 'templates', `${templateName}.md`);
             if (!fs.existsSync(templatePath))
                 throw new Error(`Template '${templateName}' not found at ${templatePath}`);
-            templateContent = this.config[templateName] || fs.readFileSync(templatePath, 'utf-8');
+            templateContent = fs.readFileSync(templatePath, 'utf-8');
         }
         const compiled = (0, lodash_1.template)(templateContent);
         this.templateCache.set(templateName, compiled);

package/lib/templates/uagComponentNotFound.md

@@ -1,11 +1,11 @@
 <% if (error === 'no_uag') { %>
-There are no `uag` fields present within the provided form. In order to use the `agent_provide_data` tool, you must first flag certain fields as the **Criteria** and **Agent Fields**.
- - **Criteria**: A content component with properties `uag="<%= persona %>"` and `uagField="criteria"`. Within the content of this component, provide detailed instructions (criteria) for the agent to follow when analyzing the data.
- - **Agent Fields**: Any fields you wish the agent to populate with its own data, you must flag those fields with the property `uag="<%= persona %>"`. These fields will then be handed to the AI Agent as required fields for them to populate according to the provided **Criteria**.
+There are no `uag` fields present within the provided form. In order to use the `agent_provide` tool, you must first flag certain fields as the **Criteria** and **Agent Fields**.
+ - **Criteria**: A content component with properties `uag="<%= task %>"` and `uagField="criteria"`. Within the content of this component, provide detailed instructions (criteria) for the agent to follow when analyzing the data.
+ - **Agent Fields**: Any fields you wish the agent to populate with its own data, you must flag those fields with the property `uag="<%= task %>"`. These fields will then be handed to the AI Agent as required fields for them to populate according to the provided **Criteria**.
 <% } %>
 <% if (error === 'no_criteria') { %>
-No `criteria` field was found within this form with the properties `uag="<%= persona %>"` and `uagField="criteria"`. To add `criteria`, add a Content component to the form and then give it the following properties: `uag="<%= persona %>"` and `uagField="criteria"`. Within the content of this component, provide detailed instructions (the criteria) for the agent to follow when analyzing the data.
+No `criteria` field was found within this form with the properties `uag="<%= task %>"` and `uagField="criteria"`. To add `criteria`, add a Content component to the form and then give it the following properties: `uag="<%= task %>"` and `uagField="criteria"`. Within the content of this component, provide detailed instructions (the criteria) for the agent to follow when analyzing the data.
 <% } %>
 <% if (error === 'no_fields') { %>
-There are no `uag` fields within this form under the provided `persona=<%= persona %>` that are available for the AI Agent to provide values for. To flag a field as fillable by the AI Agent, you must add the property and value `uag="<%= persona %>"`
+There are no `uag` fields within this form under the provided `task=<%= task %>` that are available for the AI Agent to provide values for. To flag a field as fillable by the AI Agent, you must add the property and value `uag="<%= task %>"`
 <% } %>

package/lib/testing.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @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.
+ */
+import express from 'express';
+import type { AuthRequest, ModuleForm, ServerModule } from '@formio/appserver';
+import type { UAGModuleApi } from './modules/types';
+/** An engine for tests: an agent engine that generates. */
+export type TestEngine = {
+    name: string;
+    model?: string;
+    accepts?: Array<'text' | 'pdf'>;
+    generate(request: any): any;
+    kind?: 'agent';
+};
+export type TestModuleOptions = {
+    /** The settings as given, instead of running the module's `settings`. */
+    settings?: Record<string, any>;
+    /** The configuration and environment the module's `settings` gets ({} by default). */
+    config?: Record<string, any>;
+    env?: Record<string, string | undefined>;
+    /** Plugins to register beside the module's own (document plugins, converters). */
+    plugins?: any[];
+    /** The engines `api.engines.select()` chooses from. */
+    engines?: TestEngine[];
+    /** Whether Agentic Formflow is licensed (true): false makes `requireLicense` and engine handles' `generate` refuse with 403. */
+    licensed?: boolean;
+    /** Reads a stored file value that is not base64 (the test form reads those). */
+    files?: (value: any, options: {
+        component?: any;
+        maxBytes?: number;
+    }) => Buffer | null | Promise<Buffer | null>;
+};
+/** A form for tests, as module routes get it: `definition` is the form's JSON. */
+export declare function testForm(definition: Record<string, any>, options?: {
+    id?: string;
+    files?: TestModuleOptions['files'];
+}): ModuleForm & {
+    readFile(value: any, auth: any, options?: any): Promise<Buffer | null>;
+};
+/**
+ * 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 }`).
+ */
+export declare function testAuth(options?: {
+    user?: Record<string, any>;
+    permissions?: Array<'create' | 'read' | 'update' | 'delete'> | Partial<Record<'create' | 'read' | 'update' | 'delete', boolean>>;
+    admin?: boolean;
+}): AuthRequest;
+/** The UAG's module API for a module, in a test. */
+export declare function createTestModuleApi<Settings extends Record<string, any> = Record<string, any>>(module: ServerModule<any>, options?: TestModuleOptions): Promise<UAGModuleApi<Settings>>;
+/**
+ * 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.
+ */
+export declare function mountModuleRoutes(module: ServerModule<any>, options: TestModuleOptions & {
+    form: ReturnType<typeof testForm>;
+    auth?: AuthRequest;
+    api?: UAGModuleApi;
+}): Promise<express.Express>;