@formio/uag 1.13.2 → 2.0.0-rc.2

package/lib/identity.js

@@ -0,0 +1,107 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentIdentityError = exports.SIGNED_TOKEN_TTL = void 0;
+exports.actingForOf = actingForOf;
+exports.signFormioToken = signFormioToken;
+exports.agentAuth = agentAuth;
+exports.userAuth = userAuth;
+exports.refusedSignedToken = refusedSignedToken;
+const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
+const appserver_1 = require("@formio/appserver");
+const formflow_1 = require("./formflow");
+/**
+ * Who the UAG acts as at Form.io when it runs a task for someone: the caller,
+ * with the token they sent, or a Run task action's agent role, acting on the
+ * caller's behalf with a Form.io token the UAG signs.
+ *
+ * The UAG signs Form.io "external" tokens with JWT_SECRET, which must be Form.io
+ * Enterprise's: Form.io then takes the user, and their roles, from the token. A
+ * token the UAG signs is short-lived, never marks an administrator, and never
+ * carries an admin role.
+ */
+/** Seconds a token the UAG signs is valid for. */
+exports.SIGNED_TOKEN_TTL = 300;
+/** A token the UAG may not sign, or Form.io would not accept. */
+class AgentIdentityError extends formflow_1.FormflowError {
+    constructor(message) {
+        super(500, message, 'agent_identity');
+        this.name = 'AgentIdentityError';
+    }
+}
+exports.AgentIdentityError = AgentIdentityError;
+/** The user a request comes from, as the UAG records it. */
+function actingForOf(auth, project) {
+    const user = auth?.user;
+    if (!user?._id) {
+        return { roles: project.anonymousRoles };
+    }
+    const email = user.data?.email;
+    return {
+        _id: String(user._id),
+        roles: (user.roles || []).map(String),
+        ...(typeof email === 'string' && { email })
+    };
+}
+/** The project's admin role ids, from its access settings. */
+function adminRoles(project) {
+    return new Set(Object.values(project.access?.roles || {})
+        .filter((role) => role?.admin)
+        .map((role) => String(role._id)));
+}
+/**
+ * Sign a Form.io token for `user` with `roles`. Refuses an admin role, and never
+ * marks the holder an administrator.
+ */
+function signFormioToken(project, user, roles, claim) {
+    const secret = project.config?.auth?.secret;
+    if (!secret)
+        throw new AgentIdentityError('Acting on behalf of a user needs JWT_SECRET, the same as Form.io Enterprise\'s.');
+    const admin = adminRoles(project);
+    if (roles.some((role) => admin.has(String(role)))) {
+        throw new AgentIdentityError('An agent cannot act with an admin role. Choose a role without admin access.');
+    }
+    const projectId = String(project.project?._id || '');
+    if (!projectId)
+        throw new AgentIdentityError('Acting on behalf of a user needs the project to be loaded.');
+    const payload = {
+        external: true,
+        // Form.io names an external user without an id from its data.
+        user: user._id
+            ? { _id: user._id, data: { ...(user.email && { email: user.email }) }, roles: roles.map(String) }
+            : { _id: 'external', data: { id: 'uag-anonymous' }, roles: roles.map(String) },
+        project: { _id: projectId },
+        uag: claim
+    };
+    return jsonwebtoken_1.default.sign(payload, secret, { expiresIn: exports.SIGNED_TOKEN_TTL });
+}
+/** An identity that acts as `role` for `user`, with a newly signed token. */
+async function agentAuth(project, user, role, claim) {
+    return authFor(project, user, [role], { agent: true, ...claim });
+}
+/**
+ * An identity that acts as `user`, with their recorded roles, for research and
+ * for the runs that act as them. A user's admin roles are left out: the UAG
+ * never signs a token with one, so the user acts with their other roles.
+ */
+async function userAuth(project, user, claim) {
+    const admin = adminRoles(project);
+    return authFor(project, user, user.roles.filter((role) => !admin.has(String(role))), { agent: false, ...claim });
+}
+async function authFor(project, user, roles, claim) {
+    const token = signFormioToken(project, user, roles, claim);
+    const auth = new appserver_1.AuthRequest(project);
+    await auth.fromFormioUser({ _id: user._id || 'external', roles, data: user.email ? { email: user.email } : {} }, token, project);
+    return auth;
+}
+/**
+ * Explain a Form.io refusal of a token the UAG signed: almost always a
+ * JWT_SECRET that is not Form.io Enterprise's.
+ */
+function refusedSignedToken(status) {
+    if (status !== 401 && status !== 440)
+        return null;
+    return new AgentIdentityError('Form.io refused the token the UAG signed to act on the user\'s behalf: JWT_SECRET must be the same as Form.io Enterprise\'s.');
+}

package/lib/index.d.ts

@@ -1,16 +1,57 @@
 import { Server, ServerModule } from '@formio/appserver';
+import { Router } from 'express';
 import { UAGProjectInterface } from './UAGProjectInterface';
 import { UAGFormInterface } from './UAGFormInterface';
 import { UAGConfig } from './config';
+import { UAGDatabase } from './database';
 export type UAGModule = ServerModule & {
     config?: UAGConfig;
 };
+/**
+ * Agentic Formflow keeps its license state inside @formio/appserver-core, so the
+ * UAG and @formio/appserver must load the same copy of it, at 2.24.1 or later.
+ * A second copy (an older lockfile, or a package manager that nests it) would
+ * otherwise fail in confusing ways; say what to do instead.
+ */
+export declare function assertSingleCore(core?: any, appserver?: any, version?: string): void;
 export declare class UAGServer extends Server {
+    config: UAGConfig;
+    /** The UAG's own database, once it may be used. */
+    database?: UAGDatabase;
+    /** The database between connecting and the license check. */
+    private pendingDatabase?;
     constructor(config?: UAGConfig);
+    /**
+     * Connect the UAG's own database before the project loads, and check it
+     * without writing: a database the UAG may not use stops startup. It is used
+     * (its collections created, its stores handed out) only once the license is
+     * known; see enableDatabase. Until then only the license check may write to
+     * it, to record a license server outage.
+     */
+    protected connectDatabase(): Promise<void>;
+    /**
+     * Use the database once the project and its license are loaded: with a
+     * license that includes the UAG (or the project and the database both on
+     * development hosts), create its collections and hand out its stores;
+     * otherwise leave it untouched, close it, and say why.
+     */
+    protected enableDatabase(project: UAGProjectInterface): Promise<void>;
+    /** Browsers reading Agent API responses need the request id too. */
+    get exposedHeaders(): string[];
+    /** The loaded UAG project, once the project router has been built. */
+    get uagProject(): UAGProjectInterface | undefined;
+    /**
+     * Mount `/agent/capabilities` ahead of the project routes. The project routes,
+     * and the admin passthrough after them, would otherwise answer for it and
+     * forward admin requests to the Form.io server. A form's agent operations are
+     * on the form's own routes.
+     */
+    protected extendRouter(router: Router): Promise<void>;
     router(): Promise<any>;
 }
 export * from '@formio/appserver';
 export * from './config';
+export * from './agent';
 export * from './tools';
 export * from './router';
 export * from './template';

package/lib/index.js

@@ -15,33 +15,183 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UAGFormInterface = exports.UAGProjectInterface = exports.UAGServer = void 0;
+exports.assertSingleCore = assertSingleCore;
 const appserver_1 = require("@formio/appserver");
+const formflow_1 = require("./formflow");
 const UAGProjectInterface_1 = require("./UAGProjectInterface");
 Object.defineProperty(exports, "UAGProjectInterface", { enumerable: true, get: function () { return UAGProjectInterface_1.UAGProjectInterface; } });
 const UAGFormInterface_1 = require("./UAGFormInterface");
 Object.defineProperty(exports, "UAGFormInterface", { enumerable: true, get: function () { return UAGFormInterface_1.UAGFormInterface; } });
 const lodash_1 = require("lodash");
+const engines_1 = require("./agent/engines");
+const router_1 = require("./agent/router");
+const database_1 = require("./database");
+const runs_1 = require("./runs");
+const actionLogs_1 = require("./actionLogs");
+const runner_1 = require("./runner");
+const runTask_1 = require("./actions/runTask");
+const debug = require('debug')('formio:uag');
+/**
+ * Agentic Formflow keeps its license state inside @formio/appserver-core, so the
+ * UAG and @formio/appserver must load the same copy of it, at 2.24.1 or later.
+ * A second copy (an older lockfile, or a package manager that nests it) would
+ * otherwise fail in confusing ways; say what to do instead.
+ */
+function assertSingleCore(core = require('@formio/appserver-core'), appserver = require('@formio/appserver'), version = String(require('@formio/appserver-core/package.json').version || '0.0.0')) {
+    const [major, minor, patch] = version.split('.').map((part) => parseInt(part, 10) || 0);
+    if (major < 2 || (major === 2 && (minor < 24 || (minor === 24 && patch < 1)))) {
+        throw new Error(`@formio/uag needs @formio/appserver-core 2.24.1 or later; ${version} is installed.`);
+    }
+    if (appserver.Formflow !== core.Formflow || appserver.ProjectInterface !== core.ProjectInterface) {
+        throw new Error('Two copies of @formio/appserver-core are installed: one for @formio/uag and an older one for @formio/appserver. ' +
+            'Upgrade @formio/appserver to 2.24.1 or later and deduplicate (for example `yarn dedupe @formio/appserver-core`).');
+    }
+}
+/** The UAG's own database from the environment, when `MONGO` is set. */
+function databaseFromEnv(env = process.env) {
+    const url = (0, lodash_1.get)(env, 'MONGO', '').toString();
+    if (!url)
+        return undefined;
+    const retention = (0, lodash_1.get)(env, 'TASK_RUN_RETENTION_DAYS', '').toString();
+    return {
+        url,
+        name: (0, lodash_1.get)(env, 'UAG_DATABASE', '').toString() || 'uag',
+        config: (0, lodash_1.get)(env, 'MONGO_CONFIG', '').toString() || undefined,
+        ...(retention && { retentionDays: parseInt(retention, 10) })
+    };
+}
 class UAGServer extends appserver_1.Server {
     constructor(config) {
+        assertSingleCore();
+        const configuredDb = !!config?.db;
+        const uagLicense = (0, lodash_1.get)(process.env, 'UAG_LICENSE', '').toString();
+        if (uagLicense) {
+            console.warn('[formio-uag] UAG_LICENSE is deprecated. Put a Form.io license that includes the UAG in LICENSE_KEY instead; UAG_LICENSE keeps working until UAG 3.0.');
+        }
         super((0, lodash_1.defaultsDeep)(config || {}, {
             baseUrl: (0, lodash_1.get)(process.env, 'BASE_URL', '').toString(),
-            license: (0, lodash_1.get)(process.env, 'UAG_LICENSE', '').toString(),
+            // Deprecated: core also reads LICENSE_KEY, the Form.io license, and a
+            // feature is on when either key grants it.
+            license: uagLicense,
+            licenseName: 'UAG_LICENSE',
+            // The license server counts each UAG environment as a "uagServer", and the
+            // UAG runs on the "uag" feature: a key the license server accepts as a
+            // uagServer, or one whose terms carry the "uag" option.
+            licenseType: 'uagServer',
+            licenseFeature: 'uag',
             // A project that is still starting up (a Form.io server in the same compose
             // file, for example) is retried with backoff before the load is given up on.
             retries: parseInt((0, lodash_1.get)(process.env, 'PROJECT_RETRIES', 5).toString(), 10),
             retryDelay: parseInt((0, lodash_1.get)(process.env, 'PROJECT_RETRY_DELAY', 5000).toString(), 10),
             submissionProxy: true,
             processAsClient: true,
-            auth: { pkce: true }
+            auth: { pkce: true, mcpOAuth: (0, lodash_1.get)(process.env, 'MCP_OAUTH', '').toString() === 'true' },
+            database: databaseFromEnv()
         }));
+        // MONGO is the UAG's own database, not a database for the appserver to keep
+        // submissions in: Form.io stores those.
+        if (!configuredDb && this.module.db) {
+            delete this.module.db;
+            delete this.config.db;
+        }
         this.use({
             ProjectInterface: UAGProjectInterface_1.UAGProjectInterface,
-            FormInterface: UAGFormInterface_1.UAGFormInterface
+            FormInterface: UAGFormInterface_1.UAGFormInterface,
+            actions: { agentRunTask: runTask_1.RunTaskAction },
+            hooks: (0, runTask_1.runTaskHooks)()
         });
     }
+    /**
+     * Connect the UAG's own database before the project loads, and check it
+     * without writing: a database the UAG may not use stops startup. It is used
+     * (its collections created, its stores handed out) only once the license is
+     * known; see enableDatabase. Until then only the license check may write to
+     * it, to record a license server outage.
+     */
+    async connectDatabase() {
+        const options = this.config.database;
+        if (!options?.url) {
+            console.log('[formio-uag] No database (MONGO): runs after the save are kept in memory, remote MCP sign-in (MCP_OAUTH) is unavailable, ' +
+                'and the licensed features turn off at once, with no grace period, whenever the license server cannot be reached.');
+            return;
+        }
+        if (this.database || this.pendingDatabase)
+            return;
+        const database = await database_1.UAGDatabase.connect(options);
+        try {
+            await database.inspect();
+        }
+        catch (err) {
+            await database.close().catch(() => { });
+            throw err;
+        }
+        this.pendingDatabase = database;
+        this.config.licenseGrace = database.licenseGrace();
+    }
+    /**
+     * Use the database once the project and its license are loaded: with a
+     * license that includes the UAG (or the project and the database both on
+     * development hosts), create its collections and hand out its stores;
+     * otherwise leave it untouched, close it, and say why.
+     */
+    async enableDatabase(project) {
+        const database = this.pendingDatabase;
+        this.pendingDatabase = undefined;
+        if (database) {
+            let refusal = '';
+            try {
+                project.requireDatabaseLicense(this.config.database.url);
+            }
+            catch (err) {
+                refusal = err?.message || String(err);
+            }
+            if (refusal) {
+                console.warn(`[formio-uag] The database (MONGO) is not used: ${refusal} Runs after the save are kept in memory, and remote MCP sign-in (MCP_OAUTH) is off.`);
+                this.config.licenseGrace = undefined;
+                await database.close().catch(() => { });
+            }
+            else {
+                await database.bootstrap();
+                this.database = database;
+                (0, lodash_1.set)(this.config, 'auth.authCodeStore', database.authCodeStore());
+                (0, runner_1.taskRunner)(project).useStore(new runs_1.TaskRunStore(database.taskRuns, String(project.project?._id || '')));
+                console.log(`[formio-uag] Using the database "${database.name}": runs are recorded, and runs that act with an agent role survive a restart.` +
+                    (this.config.auth?.mcpOAuth ? ' Remote MCP sign-in (MCP_OAUTH) is on.' : ''));
+            }
+        }
+        if (this.config.auth?.mcpOAuth && !this.database) {
+            console.warn('[formio-uag] MCP_OAUTH is set, but remote MCP sign-in is off: it needs the UAG\'s database (MONGO), and a license that includes the UAG to use it.');
+        }
+    }
+    /** Browsers reading Agent API responses need the request id too. */
+    get exposedHeaders() {
+        return [...super.exposedHeaders, 'X-Request-Id'];
+    }
+    /** The loaded UAG project, once the project router has been built. */
+    get uagProject() {
+        return Object.values(this.projectRouter?.projects || {})[0];
+    }
+    /**
+     * Mount `/agent/capabilities` ahead of the project routes. The project routes,
+     * and the admin passthrough after them, would otherwise answer for it and
+     * forward admin requests to the Form.io server. A form's agent operations are
+     * on the form's own routes.
+     */
+    async extendRouter(router) {
+        await super.extendRouter(router);
+        const uagProject = this.uagProject;
+        if (uagProject) {
+            router.use(uagProject.agentRouter());
+            // An agent operation of a form the project does not have is answered here, not passed to Form.io.
+            router.use((0, router_1.agentNotFound)(uagProject));
+            // Action Logs in a connected portal stage, with the UAG's run records.
+            router.use((0, actionLogs_1.ActionLogRouter)(uagProject));
+        }
+    }
     async router() {
+        await this.connectDatabase();
         const router = await super.router();
-        const uagProject = Object.values(this.projectRouter?.projects || {})[0];
+        const uagProject = this.uagProject;
         // Without a project there are no forms to expose, so there is nothing to
         // serve. Say why: this used to throw "Cannot read properties of undefined
         // (reading 'uagRouter')", which told the operator nothing about the
@@ -49,16 +199,38 @@ class UAGServer extends appserver_1.Server {
         if (!uagProject) {
             throw new Error('No Form.io project could be loaded, so the UAG has nothing to serve. Check that PROJECT ' +
                 'points at a reachable Form.io deployment, and that it is paired with the right ' +
-                'credential — ADMIN_KEY for an Open Source server, or PROJECT_KEY plus UAG_LICENSE for ' +
-                'an Enterprise project. Earlier log lines report why the project load failed.');
+                'credential — ADMIN_KEY for an Open Source server, PROJECT_KEY for a project on Form.io\'s ' +
+                'hosted service, or PROJECT_KEY plus a license (LICENSE_KEY) for a self-hosted Enterprise project. ' +
+                'Earlier log lines report why the project load failed.');
+        }
+        // A database of the UAG's own needs the license, on every edition.
+        await this.enableDatabase(uagProject);
+        // Decide which engines are on before serving anything, so a misconfigured
+        // engine stops startup with its name in the error instead of failing the
+        // first request.
+        uagProject.engines = await (0, engines_1.loadUAGEngines)(uagProject.config || {}, process.env);
+        // Say which edition this is, and whether Agentic Formflow will run, so an
+        // operator knows before the first request is refused.
+        // A failure here only loses the message; it never stops the UAG starting.
+        try {
+            const formflowState = await (0, formflow_1.formflow)(uagProject).state();
+            // A project on Form.io's hosted service runs under Form.io's license.
+            const hosted = formflowState.reason === 'hosted' ? ', on Form.io\'s hosted service (no license needed)' : '';
+            const reason = formflowState.licensedBy ? `licensed by ${formflowState.licensedBy}` : formflowState.reason;
+            console.log(`[formio-uag] ${formflowState.edition === 'enterprise' ? 'Enterprise' : 'Open Source'} edition${hosted}. Agentic Formflow ` +
+                (formflowState.allowed ? `is enabled (${reason}).` : 'requires a license (LICENSE_KEY) that includes the UAG, or a project on Form.io\'s hosted service; MCP and conversation forms are unaffected.'));
+        }
+        catch (err) {
+            debug(`Could not report the edition: ${err?.message || err}`);
         }
-        router.use(uagProject.uagRouter());
+        router.use(uagProject.uagRouter(false));
         return router;
     }
 }
 exports.UAGServer = UAGServer;
 __exportStar(require("@formio/appserver"), exports);
 __exportStar(require("./config"), exports);
+__exportStar(require("./agent"), exports);
 __exportStar(require("./tools"), exports);
 __exportStar(require("./router"), exports);
 __exportStar(require("./template"), exports);

package/lib/router.js

@@ -4,13 +4,11 @@ exports.UAGRouter = UAGRouter;
 const express_1 = require("express");
 const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
 // Helper function to create JSON RPC error responses
-const createJsonRpcErrorResponse = (code, message) => {
-    return JSON.stringify({
-        error: { code, message },
-        id: null,
-        jsonrpc: "2.0",
-    });
-};
+const createJsonRpcErrorResponse = (code, message) => ({
+    error: { code, message },
+    id: null,
+    jsonrpc: "2.0",
+});
 /**
  * Handle errors that occur during response processing.
  * @param error The error that occurred.
@@ -29,7 +27,7 @@ const handleResponseError = (error, res) => {
         return true;
     }
     console.error("[formio-uag] error handling request", error);
-    res.status(500).json(JSON.parse(createJsonRpcErrorResponse(-32603, "Internal Server Error")));
+    res.status(500).json(createJsonRpcErrorResponse(-32603, "Internal Server Error"));
     return false;
 };
 /**
@@ -37,8 +35,8 @@ const handleResponseError = (error, res) => {
  * when the response closes. A fresh instance per request keeps concurrent requests
  * from overwriting each other's transport.
  */
-const connectMcpTransport = async (project, res) => {
-    const server = await project.buildMcpServer();
+const connectMcpTransport = async (project, res, scope) => {
+    const server = await project.buildMcpServer(scope);
     const transport = new streamableHttp_js_1.StreamableHTTPServerTransport({
         sessionIdGenerator: undefined, // Use "undefined" to trigger stateless mode.
     });
@@ -51,26 +49,18 @@ const connectMcpTransport = async (project, res) => {
 };
 function UAGRouter(project) {
     const router = (0, express_1.Router)();
-    // Handles the MCP post requests.
-    router.post('/', async (req, res) => {
+    // Handles the MCP requests: posts carry a JSON-RPC body, gets do not (health checks, etc).
+    const handleMcpRequest = (withBody) => async (req, res) => {
         try {
-            const transport = await connectMcpTransport(project, res);
-            await transport.handleRequest(req, res, req.body);
+            const transport = await connectMcpTransport(project, res, req.uagScope);
+            await transport.handleRequest(req, res, withBody ? req.body : undefined);
         }
         catch (error) {
             handleResponseError(error, res);
         }
-    });
-    // Handles the MCP get requests (for health checks, etc).
-    router.get('/', async (req, res) => {
-        try {
-            const transport = await connectMcpTransport(project, res);
-            await transport.handleRequest(req, res);
-        }
-        catch (err) {
-            handleResponseError(err, res);
-        }
-    });
+    };
+    router.post('/', handleMcpRequest(true));
+    router.get('/', handleMcpRequest(false));
     // Return the router
     return router;
 }

package/lib/runner.d.ts

@@ -0,0 +1,147 @@
+import { AuthRequest } from '@formio/appserver';
+import type { CallerIdentity } from './formflow';
+import { ActingFor } from './identity';
+import { TaskRunStore } from './runs';
+import type { UAGProjectInterface } from './UAGProjectInterface';
+/** A Run task action's run after the save, on the submission Form.io stored. */
+export type TaskRunJob = {
+    /** The form's name. */
+    form: string;
+    submission: string;
+    task: string;
+    answer: 'decisions' | 'task';
+    /** The user the run acts for: who sent the submission. Never a token. */
+    actingFor: ActingFor;
+    /**
+     * The role the agent acts with at Form.io, on the user's behalf. Such runs
+     * can be recorded and resumed: everything they need is in the job.
+     */
+    agentRole?: string;
+    /**
+     * Without an agent role, the caller's own identity (with their token), kept
+     * in memory only and never recorded.
+     */
+    caller?: AuthRequest;
+    /** Without an agent role, who the engines research as (the caller's bearer token, if any). */
+    identity?: CallerIdentity;
+    /**
+     * Without an agent role or the caller's token: act as the user, with their
+     * recorded roles and tokens the UAG signs. A run started by the save of a
+     * run that acted with an agent role, so it never inherits that role.
+     */
+    asUser?: boolean;
+    /** How many runner saves led to this run: none for a run a client's request started. */
+    chain?: number;
+    /** The action that started the run, for the record. */
+    action?: string;
+    /** For the record: the form's id, and the method that started the run. */
+    formId?: string;
+    method?: string;
+    /** The X-Request-Id of the request that started the run, passed on to the engines. */
+    requestId?: string;
+};
+export type TaskRunOutcome = {
+    status: 'done' | 'failed';
+    /** Paths written, with their values, and paths cleared. Empty when nothing changed. */
+    written: Record<string, any>;
+    cleared: string[];
+    /** The engines and models that answered. */
+    engines: {
+        kind: string;
+        engine: string | null;
+        model: string | null;
+    }[];
+    /** Whether the results were saved (nothing is saved when nothing changed). */
+    saved: boolean;
+    error?: string;
+};
+/**
+ * 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.
+ */
+export declare const 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.
+ */
+export declare const RUN_TASK_ACTING_FOR = "uagActingFor";
+export declare const RUN_TASK_CALLER = "uagCaller";
+export declare const RUN_TASK_REQUEST_ID = "uagRequestId";
+export declare const RUN_TASK_IDENTITY = "uagIdentity";
+export declare const RUN_TASK_AS_USER = "uagAsUser";
+export declare const 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.
+ */
+export declare const MAX_CHAIN = 5;
+/** How often a replica looks for runs that are pending or lost their replica. */
+export declare const SWEEP_MS: number;
+/**
+ * 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.
+ */
+export declare class TaskRunner {
+    private project;
+    private concurrency;
+    private queue;
+    private active;
+    private waiting;
+    private store?;
+    private sweeper?;
+    private sweeping;
+    constructor(project: UAGProjectInterface, concurrency?: number);
+    /** Whether runs acting with an agent role are recorded and survive a restart. */
+    get durable(): boolean;
+    /** Record runs in the UAG's database, and take durable runs from it. */
+    useStore(store: TaskRunStore): void;
+    /** Stop sweeping (the runs in progress finish). */
+    stop(): void;
+    /** The project's run records, when there is a database. */
+    get records(): TaskRunStore | undefined;
+    /**
+     * 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.
+     */
+    enqueue(job: TaskRunJob): Promise<void>;
+    /** Record a run made before the save, once the save gave the submission its id. */
+    recordBefore(job: TaskRunJob, outcome: TaskRunOutcome): Promise<void>;
+    private newRecord;
+    /** Resolves once every queued and running job has finished (for tests and shutdown). */
+    idle(): Promise<void>;
+    private isIdle;
+    private settled;
+    private drain;
+    /** Take durable runs from the database while there is room. */
+    private sweep;
+    private runRecord;
+    /** Run a job, report it, and record its end. */
+    private track;
+    protected report(job: TaskRunJob, outcome: TaskRunOutcome): void;
+    /**
+     * 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.
+     */
+    private identities;
+    /**
+     * 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.
+     */
+    private refusal;
+    /** Run one job to completion. */
+    execute(job: TaskRunJob): Promise<TaskRunOutcome>;
+    private run;
+}
+export declare function taskRunner(project: UAGProjectInterface): TaskRunner;