@formio/uag 1.13.1 → 2.0.0-rc.1

package/lib/runner.js

@@ -0,0 +1,345 @@
+"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());
+            if (!stored)
+                throw new formflow_1.FormflowError(404, `Submission "${job.submission}" was not found.`);
+            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;
+            if (!changed) {
+                return { status: failed ? 'failed' : 'done', written: {}, cleared: [], engines, saved: false, ...(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, ...(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,
+        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,89 @@
+import { Collection, ObjectId } from 'mongodb';
+import type { ActingFor } from './identity';
+/**
+ * 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.
+ */
+export type TaskRunStatus = 'pending' | 'running' | 'done' | 'failed';
+export type TaskRunRecord = {
+    _id: ObjectId;
+    project: string;
+    /** The form's id, and its name for the runner. */
+    form: string;
+    formName: string;
+    submission?: string;
+    /** The action's title, and the task it runs. */
+    action: string;
+    task: string;
+    answer: 'decisions' | 'task';
+    /** When it ran: before the save, or after it. */
+    handler: 'before' | 'after';
+    method: string;
+    /** Resumed after a restart (it acts with an agent role). */
+    durable: boolean;
+    actingFor: ActingFor;
+    /** The X-Request-Id of the request that started the run. */
+    requestId?: string;
+    agentRole?: string;
+    /** How many runner saves led to this run. */
+    chain?: number;
+    status: TaskRunStatus;
+    attempts: number;
+    owner?: string;
+    leaseUntil?: Date;
+    engines?: {
+        kind: string;
+        engine: string | null;
+        model: string | null;
+    }[];
+    written?: string[];
+    cleared?: string[];
+    saved?: boolean;
+    error?: string;
+    created: Date;
+    modified: Date;
+    started?: Date;
+    finished?: Date;
+};
+export type NewTaskRun = Omit<TaskRunRecord, '_id' | 'attempts' | 'created' | 'modified' | 'status'> & {
+    status?: TaskRunStatus;
+};
+/** How long a replica holds a run before another may take it over, and how often it renews. */
+export declare const LEASE_MS: number;
+export declare const RENEW_MS: number;
+/** Attempts before a run that keeps losing its replica is given up. */
+export declare const MAX_ATTEMPTS = 3;
+export declare class TaskRunStore {
+    readonly collection: Collection<TaskRunRecord>;
+    readonly project?: string | undefined;
+    /** This replica, as the owner of the runs it holds. */
+    readonly owner: `${string}-${string}-${string}-${string}-${string}`;
+    /**
+     * `project` limits the durable runs this replica takes to its project's:
+     * UAGs of different projects may share one database.
+     */
+    constructor(collection: Collection<TaskRunRecord>, project?: string | undefined);
+    private get scope();
+    add(run: NewTaskRun): Promise<ObjectId>;
+    /**
+     * Take the oldest durable run that is pending, or whose holder's lease ran
+     * out, for this replica. Only one replica can take a run.
+     */
+    claim(now?: Date): Promise<TaskRunRecord | null>;
+    /** Fail the runs that lost their replica too many times. */
+    private giveUp;
+    /** Keep holding a run. False when another replica took it over. */
+    renew(id: ObjectId): Promise<boolean>;
+    /** Record how a run ended. Only the replica holding a durable run can. */
+    finish(id: ObjectId, result: Pick<TaskRunRecord, 'engines' | 'written' | 'cleared' | 'saved' | 'error'> & {
+        status: 'done' | 'failed';
+    }): Promise<void>;
+    get(id: string): Promise<TaskRunRecord | null>;
+    /** The project's records matching a filter, newest change first. */
+    list(filter: Record<string, any>, limit: number): Promise<{
+        items: TaskRunRecord[];
+        total: number;
+    }>;
+}

package/lib/runs.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskRunStore = exports.MAX_ATTEMPTS = exports.RENEW_MS = exports.LEASE_MS = void 0;
+const crypto_1 = require("crypto");
+const mongodb_1 = require("mongodb");
+/** How long a replica holds a run before another may take it over, and how often it renews. */
+exports.LEASE_MS = 2 * 60 * 1000;
+exports.RENEW_MS = 30 * 1000;
+/** Attempts before a run that keeps losing its replica is given up. */
+exports.MAX_ATTEMPTS = 3;
+class TaskRunStore {
+    /**
+     * `project` limits the durable runs this replica takes to its project's:
+     * UAGs of different projects may share one database.
+     */
+    constructor(collection, project) {
+        this.collection = collection;
+        this.project = project;
+        /** This replica, as the owner of the runs it holds. */
+        this.owner = (0, crypto_1.randomUUID)();
+    }
+    get scope() {
+        return this.project === undefined ? {} : { project: this.project };
+    }
+    async add(run) {
+        const now = new Date();
+        const record = { ...run, _id: new mongodb_1.ObjectId(), status: run.status || 'pending', attempts: 0, created: now, modified: now };
+        await this.collection.insertOne(record);
+        return record._id;
+    }
+    /**
+     * Take the oldest durable run that is pending, or whose holder's lease ran
+     * out, for this replica. Only one replica can take a run.
+     */
+    async claim(now = new Date()) {
+        await this.giveUp(now);
+        return this.collection.findOneAndUpdate({
+            ...this.scope,
+            durable: true,
+            attempts: { $lt: exports.MAX_ATTEMPTS },
+            $or: [{ status: 'pending' }, { status: 'running', leaseUntil: { $lt: now } }]
+        }, { $set: { status: 'running', owner: this.owner, leaseUntil: new Date(now.getTime() + exports.LEASE_MS), started: now, modified: now }, $inc: { attempts: 1 } }, { sort: { created: 1 }, returnDocument: 'after' });
+    }
+    /** Fail the runs that lost their replica too many times. */
+    async giveUp(now) {
+        await this.collection.updateMany({ ...this.scope, durable: true, status: 'running', leaseUntil: { $lt: now }, attempts: { $gte: exports.MAX_ATTEMPTS } }, { $set: { status: 'failed', error: `The run was given up after ${exports.MAX_ATTEMPTS} attempts.`, finished: now, modified: now }, $unset: { leaseUntil: '', owner: '' } });
+    }
+    /** Keep holding a run. False when another replica took it over. */
+    async renew(id) {
+        const now = new Date();
+        const result = await this.collection.updateOne({ _id: id, owner: this.owner, status: 'running' }, { $set: { leaseUntil: new Date(now.getTime() + exports.LEASE_MS), modified: now } });
+        return result.matchedCount > 0;
+    }
+    /** Record how a run ended. Only the replica holding a durable run can. */
+    async finish(id, result) {
+        const now = new Date();
+        await this.collection.updateOne({ _id: id, $or: [{ durable: false }, { owner: this.owner }] }, { $set: { ...result, finished: now, modified: now }, $unset: { leaseUntil: '', owner: '' } });
+    }
+    async get(id) {
+        if (!mongodb_1.ObjectId.isValid(id))
+            return null;
+        return this.collection.findOne({ _id: new mongodb_1.ObjectId(id) });
+    }
+    /** The project's records matching a filter, newest change first. */
+    async list(filter, limit) {
+        const [items, total] = await Promise.all([
+            // A limit of 0 would be none at all to MongoDB.
+            limit > 0 ? this.collection.find(filter).sort({ modified: -1 }).limit(limit).toArray() : Promise.resolve([]),
+            this.collection.countDocuments(filter)
+        ]);
+        return { items, total };
+    }
+}
+exports.TaskRunStore = TaskRunStore;

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/tools/SchemaBuilder.d.ts

@@ -109,8 +109,13 @@ 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).
+     */
+    task(): this;
+    /**
+     * The legacy name for `task`. Kept in the schema so clients that still send
+     * it are not silently given the default task.
      */
     persona(): this;
     /**

package/lib/tools/SchemaBuilder.js

@@ -168,11 +168,19 @@ 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).
+     */
+    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;
+    }
+    /**
+     * The legacy name for `task`. Kept in the schema so clients that still send
+     * it are not silently given the default task.
      */
     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.');
+        this.schema.persona = zod_1.default.string().optional().describe('Deprecated: the former name for `task`. Send `task` instead.');
         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().persona().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 = (0, formflow_1.resolveTaskName)(args, 'agent_decide');
+                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;