@formio/uag 1.13.2 → 2.0.0-rc.1

package/lib/agent/stubs.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StubAgentEngine = exports.StubDecisionEngine = void 0;
+const uag_sdk_1 = require("@formio/uag-sdk");
+const formflow_1 = require("../formflow");
+/**
+ * Stand-in engines for tests and local development. They answer instantly with
+ * predictable values, so the Agent API can be exercised end to end without
+ * model credentials: `UAG_ENGINES=stub-decision,stub-agent`. Core creates
+ * them, so they keep the standing that lets them run without a license under
+ * any instance name.
+ */
+exports.StubDecisionEngine = (0, uag_sdk_1.defineEngine)({
+    type: 'stub-decision',
+    kinds: ['decision'],
+    apiVersion: uag_sdk_1.ENGINE_API_VERSION,
+    description: 'Answers every decision with a fixed, predictable value. For tests and local development.',
+    create: ({ name }) => (0, formflow_1.stubDecisionEngine)({ name }),
+});
+exports.StubAgentEngine = (0, uag_sdk_1.defineEngine)({
+    type: 'stub-agent',
+    kinds: ['agent'],
+    apiVersion: uag_sdk_1.ENGINE_API_VERSION,
+    description: 'Extracts nothing. For tests and local development.',
+    create: ({ name }) => (0, formflow_1.stubAgentEngine)({ name }),
+});

package/lib/agent/tools.d.ts

@@ -0,0 +1,10 @@
+import { FormflowTool } from "../formflow";
+import type { UAGProjectInterface } from "../UAGProjectInterface";
+import { ToolInfo } from "../tools/utils";
+/** Every tool the UAG serves, including custom tools from configuration. */
+export declare function allTools(project: UAGProjectInterface): Promise<ToolInfo[]>;
+/**
+ * An MCP tool as an Agentic Formflow tool: its schema as JSON, its arguments
+ * validated with its own schema, and read-only only when annotated so.
+ */
+export declare function formflowTool(tool: ToolInfo): FormflowTool;

package/lib/agent/tools.js

@@ -0,0 +1,33 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.allTools = allTools;
+exports.formflowTool = formflowTool;
+const zod_1 = __importDefault(require("zod"));
+const tools_1 = require("../tools");
+/** Every tool the UAG serves, including custom tools from configuration. */
+async function allTools(project) {
+    return [...await (0, tools_1.getTools)(project), ...(project.config?.tools || [])].filter((tool) => !!tool?.name);
+}
+/**
+ * An MCP tool as an Agentic Formflow tool: its schema as JSON, its arguments
+ * validated with its own schema, and read-only only when annotated so.
+ */
+function formflowTool(tool) {
+    const schema = zod_1.default.object(tool.inputSchema || {});
+    const inputSchema = zod_1.default.toJSONSchema(schema, { io: 'input', unrepresentable: 'any' });
+    delete inputSchema.$schema;
+    return {
+        name: tool.name,
+        description: tool.description || tool.title || tool.name,
+        readOnly: tool.annotations?.readOnlyHint === true,
+        inputSchema,
+        parse: (args) => {
+            const parsed = schema.safeParse(args || {});
+            return parsed.success ? { ok: true, value: parsed.data } : { ok: false, error: parsed.error.message };
+        },
+        execute: async (args, auth) => tool.execute(args, { authInfo: auth })
+    };
+}

package/lib/config.d.ts

@@ -1,5 +1,8 @@
 import { ServerConfig } from '@formio/appserver';
+import type { FormflowAgentApiConfig, FormflowRateLimit, FormflowRoutingConfig } from './formflow';
+import type { EngineInstanceSpec, EngineTypeDefinition } from '@formio/uag-sdk';
 import { ToolInfo } from './tools/utils';
+import type { UAGDatabaseOptions } from './database';
 export type UAGForm = {
     name: string;
     title: string;
@@ -43,13 +46,77 @@ export type UAGToolOverride = {
     submit_completed_form?: ToolInfo;
     submission_update?: ToolInfo;
     find_submissions?: ToolInfo;
+    agent_provide?: ToolInfo;
+    /** @deprecated The earlier name of `agent_provide`; also applied to it when `agent_provide` is not set. */
     agent_provide_data?: ToolInfo;
+    agent_decide?: ToolInfo;
     fetch_external_data?: ToolInfo;
 };
+/**
+ * One engine instance: `"<type>"` or `"<name>:<type>"`, or `{ name, type, options }`, where the
+ * type is a type name, a package name, or an engine type definition.
+ */
+export type UAGEngineEntry = string | EngineInstanceSpec;
+/** Engine preference lists for each kind of work. See FormflowRoutingConfig. */
+export type UAGRoutingConfig = FormflowRoutingConfig;
+/** A request allowance. See FormflowRateLimit. */
+export type UAGRateLimit = FormflowRateLimit;
+/** Agent API defaults: thresholds, timeouts, tools and rate limits. See FormflowAgentApiConfig. */
+/** Limits on anonymous use of a form's agent operations, per minute in each UAG process. 0 turns anonymous use off. */
+export interface UAGAnonymousConfig {
+    /** Requests from one client address (AGENT_ANONYMOUS_RATE_LIMIT, default 10). */
+    rateLimit?: number;
+    /** Requests from all anonymous callers together (AGENT_ANONYMOUS_TOTAL_RATE_LIMIT, default 100). */
+    totalRateLimit?: number;
+}
+/** A form's chat (`{form}/agent/chat`): its engines and the bounds of a turn. */
+export interface UAGChatConfig {
+    /** Engine names, or `agent` for every agent engine, in the order to try them. Default: `['agent']`. */
+    engines?: string[];
+    /** Milliseconds to wait for one engine before trying the next. Default: the engine's routing timeout. */
+    timeout?: number;
+    /** Rounds of `check_values` calls an engine may make before it answers. Default: 3. */
+    maxIterations?: number;
+    /** The most messages a turn may carry. Default: 40. */
+    maxMessages?: number;
+    /** The most characters in one message. Default: 2000. */
+    maxMessageLength?: number;
+    /** The most characters of conversation sent to the engine; older messages are left out. Default: 24000. */
+    maxTranscriptChars?: number;
+}
+export type UAGAgentApiConfig = FormflowAgentApiConfig & {
+    anonymous?: UAGAnonymousConfig;
+    chat?: UAGChatConfig;
+};
+/**
+ * Express's `trust proxy` from TRUST_PROXY: `true` or `false`, a number of
+ * proxy hops, or addresses and ranges (`loopback, 10.0.0.0/8`). Unset when
+ * TRUST_PROXY is empty. With it, the UAG reads its public URL, and callers'
+ * addresses, from the proxy's forwarded headers.
+ */
+export declare function trustProxySetting(value: string | undefined): boolean | number | string | undefined;
 export interface UAGConfig extends ServerConfig {
+    /** The UAG's public URL (BASE_URL). Optional: derived from each request when unset. */
     baseUrl?: string;
     loginForm?: string;
     responseTemplates?: UAGTemplateConfig;
     toolOverrides?: UAGToolOverride;
     tools?: ToolInfo[];
+    /**
+     * The engine instances to enable, as in `UAG_ENGINES` (`"jev"`, `"fast:claude"`) or as
+     * `{ name, type, options }`. When unset, `UAG_ENGINES` is used; when neither names any, no
+     * engine is enabled.
+     */
+    engines?: UAGEngineEntry[];
+    /** Engine types this application provides, by type name, resolved before built-in types and packages. */
+    engineTypes?: Record<string, EngineTypeDefinition>;
+    routing?: UAGRoutingConfig;
+    agentApi?: UAGAgentApiConfig;
+    /**
+     * The UAG's own database (`MONGO`, `UAG_DATABASE`, `MONGO_CONFIG`,
+     * `TASK_RUN_RETENTION_DAYS`), for remote MCP sign-in and durable task runs.
+     * It needs a license that includes the UAG, unless the project and the
+     * database are both on development hosts.
+     */
+    database?: UAGDatabaseOptions;
 }

package/lib/config.js

@@ -1,2 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.trustProxySetting = trustProxySetting;
+/**
+ * Express's `trust proxy` from TRUST_PROXY: `true` or `false`, a number of
+ * proxy hops, or addresses and ranges (`loopback, 10.0.0.0/8`). Unset when
+ * TRUST_PROXY is empty. With it, the UAG reads its public URL, and callers'
+ * addresses, from the proxy's forwarded headers.
+ */
+function trustProxySetting(value) {
+    const text = String(value ?? '').trim();
+    if (!text)
+        return undefined;
+    if (text === 'true')
+        return true;
+    if (text === 'false')
+        return false;
+    if (/^\d+$/.test(text))
+        return parseInt(text, 10);
+    return text;
+}

package/lib/database.d.ts

@@ -0,0 +1,75 @@
+import { Collection, Db, MongoClient, MongoClientOptions } from 'mongodb';
+import type { AuthCodeStore } from '@formio/appserver-core';
+/**
+ * The UAG's own database (MONGO, with the database named by UAG_DATABASE). It
+ * holds only the UAG's state: authorization codes for remote MCP clients, the
+ * start of a license server outage, and task-run records. Never submissions.
+ *
+ * Every collection the UAG uses is named `uag-*`, and nothing else in the
+ * database is read or written, so the database may be shared. Before writing
+ * anything, the UAG checks that the `uag-*` collections are its own.
+ */
+/** The schema version this UAG writes. Older databases are migrated; newer ones refused. */
+export declare const UAG_SCHEMA_VERSION = 1;
+export declare const UAG_COLLECTIONS: Readonly<{
+    meta: "uag-meta";
+    authCodes: "uag-authcodes";
+    taskRuns: "uag-taskruns";
+}>;
+export type UAGDatabaseOptions = {
+    /** The connection string (MONGO). Its database, if any, is ignored: UAG_DATABASE names the one used. */
+    url: string;
+    /** The database to use (UAG_DATABASE). */
+    name?: string;
+    /** Driver options (MONGO_CONFIG), as JSON or an object. */
+    config?: string | MongoClientOptions;
+    /** Days a task-run record is kept (TASK_RUN_RETENTION_DAYS); 0 keeps it forever. */
+    retentionDays?: number;
+};
+/** Why the UAG may not use a database. Startup stops with this message. */
+export declare class UAGDatabaseError extends Error {
+    name: string;
+}
+export declare class UAGDatabase {
+    readonly client: MongoClient;
+    readonly db: Db;
+    readonly name: string;
+    readonly retentionDays: number;
+    private bootstrapped?;
+    private warned;
+    constructor(client: MongoClient, db: Db, options: UAGDatabaseOptions);
+    /**
+     * Connect, and select the database by name on the connection: the
+     * connection string's database and `authSource` are left as they are.
+     */
+    static connect(options: UAGDatabaseOptions): Promise<UAGDatabase>;
+    get meta(): Collection<any>;
+    get authCodes(): Collection<any>;
+    get taskRuns(): Collection<any>;
+    /**
+     * Check the database without writing anything: whether the UAG may use it,
+     * and what bootstrap would do. Refuses (throws) a database whose `uag-*`
+     * collections the UAG did not create, or that a newer UAG created.
+     */
+    inspect(): Promise<'fresh' | 'ready' | 'older'>;
+    /**
+     * Check the database (see inspect), then create what is missing: the schema
+     * marker first, then the collections and their indexes; or migrate an older
+     * schema. Safe to call again.
+     */
+    bootstrap(): Promise<'created' | 'ready' | 'migrated'>;
+    /** Create the collections and indexes, as needed; safe to repeat. */
+    private ensureCollections;
+    /** The task-run records' TTL index, following TASK_RUN_RETENTION_DAYS; none when it is 0. */
+    private ensureRetention;
+    /** Run database work, reporting a missing privilege with the database's name. */
+    private privileged;
+    /** Authorization codes for remote MCP clients (MCP_OAUTH), in `uag-authcodes`. */
+    authCodeStore(): AuthCodeStore;
+    /** When the license server became unreachable, in `uag-meta`, so a restart neither begins nor extends the grace period. */
+    licenseGrace(): {
+        read(): Promise<number | undefined>;
+        write(since?: number): Promise<void>;
+    };
+    close(): Promise<void>;
+}

package/lib/database.js

@@ -0,0 +1,229 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UAGDatabase = exports.UAGDatabaseError = exports.UAG_COLLECTIONS = exports.UAG_SCHEMA_VERSION = void 0;
+const crypto_1 = require("crypto");
+const mongodb_1 = require("mongodb");
+const debug = require('debug')('formio:uag:database');
+/**
+ * The UAG's own database (MONGO, with the database named by UAG_DATABASE). It
+ * holds only the UAG's state: authorization codes for remote MCP clients, the
+ * start of a license server outage, and task-run records. Never submissions.
+ *
+ * Every collection the UAG uses is named `uag-*`, and nothing else in the
+ * database is read or written, so the database may be shared. Before writing
+ * anything, the UAG checks that the `uag-*` collections are its own.
+ */
+/** The schema version this UAG writes. Older databases are migrated; newer ones refused. */
+exports.UAG_SCHEMA_VERSION = 1;
+exports.UAG_COLLECTIONS = Object.freeze({
+    meta: 'uag-meta',
+    authCodes: 'uag-authcodes',
+    taskRuns: 'uag-taskruns',
+});
+const PREFIX = 'uag-';
+const APP = 'formio-uag';
+const SCHEMA_ID = 'schema';
+const LICENSE_ID = 'license';
+const RETENTION_INDEX = 'retention';
+const DEFAULT_RETENTION_DAYS = 90;
+// MongoDB's "Unauthorized" error.
+const UNAUTHORIZED = 13;
+/** Why the UAG may not use a database. Startup stops with this message. */
+class UAGDatabaseError extends Error {
+    constructor() {
+        super(...arguments);
+        this.name = 'UAGDatabaseError';
+    }
+}
+exports.UAGDatabaseError = UAGDatabaseError;
+function driverOptions(config) {
+    if (!config)
+        return {};
+    if (typeof config !== 'string')
+        return config;
+    try {
+        return JSON.parse(config);
+    }
+    catch (err) {
+        throw new UAGDatabaseError(`MONGO_CONFIG is not valid JSON: ${err.message}`);
+    }
+}
+/** Authorization codes are stored by their hash, so the database never holds a usable code. */
+const codeKey = (code) => (0, crypto_1.createHash)('sha256').update(code).digest('base64url');
+/**
+ * An authorization code's token, sealed with a key only the code gives: the
+ * database holds neither the code nor a token it could use.
+ */
+const sealKey = (code) => (0, crypto_1.createHash)('sha256').update(`uag-authcode:${code}`).digest();
+function sealToken(code, token) {
+    const iv = (0, crypto_1.randomBytes)(12);
+    const cipher = (0, crypto_1.createCipheriv)('aes-256-gcm', sealKey(code), iv);
+    const sealed = Buffer.concat([cipher.update(token, 'utf8'), cipher.final()]);
+    return [iv, cipher.getAuthTag(), sealed].map((part) => part.toString('base64url')).join('.');
+}
+function openToken(code, sealed) {
+    try {
+        const [iv, tag, data] = sealed.split('.').map((part) => Buffer.from(part, 'base64url'));
+        const decipher = (0, crypto_1.createDecipheriv)('aes-256-gcm', sealKey(code), iv);
+        decipher.setAuthTag(tag);
+        return Buffer.concat([decipher.update(data), decipher.final()]).toString('utf8');
+    }
+    catch {
+        return null;
+    }
+}
+class UAGDatabase {
+    constructor(client, db, options) {
+        this.client = client;
+        this.db = db;
+        this.warned = false;
+        this.name = db.databaseName;
+        const days = options.retentionDays;
+        this.retentionDays = days === undefined || Number.isNaN(days) ? DEFAULT_RETENTION_DAYS : Math.max(0, days);
+    }
+    /**
+     * Connect, and select the database by name on the connection: the
+     * connection string's database and `authSource` are left as they are.
+     */
+    static async connect(options) {
+        const name = options.name || 'uag';
+        const client = new mongodb_1.MongoClient(options.url, driverOptions(options.config));
+        try {
+            await client.connect();
+        }
+        catch (err) {
+            throw new UAGDatabaseError(`Could not connect to MONGO: ${err.message}`);
+        }
+        return new UAGDatabase(client, client.db(name), { ...options, name });
+    }
+    get meta() { return this.db.collection(exports.UAG_COLLECTIONS.meta); }
+    get authCodes() { return this.db.collection(exports.UAG_COLLECTIONS.authCodes); }
+    get taskRuns() { return this.db.collection(exports.UAG_COLLECTIONS.taskRuns); }
+    /**
+     * Check the database without writing anything: whether the UAG may use it,
+     * and what bootstrap would do. Refuses (throws) a database whose `uag-*`
+     * collections the UAG did not create, or that a newer UAG created.
+     */
+    async inspect() {
+        return this.privileged(async () => {
+            const names = (await this.db.listCollections({}, { nameOnly: true }).toArray()).map((info) => info.name);
+            const ours = names.filter((name) => name.startsWith(PREFIX));
+            if (names.length > ours.length && !this.warned) {
+                this.warned = true;
+                console.warn(`[formio-uag] The database "${this.name}" holds other data too. The UAG uses only its uag-* collections there, ` +
+                    'but a database of its own is recommended (UAG_DATABASE).');
+            }
+            if (!ours.length)
+                return 'fresh';
+            const marker = ours.includes(exports.UAG_COLLECTIONS.meta) ? await this.meta.findOne({ _id: SCHEMA_ID }) : null;
+            if (!marker || marker.app !== APP || typeof marker.version !== 'number') {
+                throw new UAGDatabaseError(`The database "${this.name}" holds uag-* collections that the UAG did not create (${ours.join(', ')}). ` +
+                    'Nothing was changed. Choose another database with UAG_DATABASE.');
+            }
+            if (marker.version > exports.UAG_SCHEMA_VERSION) {
+                throw new UAGDatabaseError(`The database "${this.name}" was created by a newer UAG (schema version ${marker.version}; ` +
+                    `this UAG supports ${exports.UAG_SCHEMA_VERSION}). Upgrade the UAG, or choose another database with UAG_DATABASE.`);
+            }
+            return marker.version < exports.UAG_SCHEMA_VERSION ? 'older' : 'ready';
+        });
+    }
+    /**
+     * Check the database (see inspect), then create what is missing: the schema
+     * marker first, then the collections and their indexes; or migrate an older
+     * schema. Safe to call again.
+     */
+    bootstrap() {
+        this.bootstrapped = this.bootstrapped || this.privileged(async () => {
+            const state = await this.inspect();
+            if (state === 'fresh') {
+                // The marker first: a start interrupted after it finishes the rest next time.
+                await this.meta.insertOne({ _id: SCHEMA_ID, app: APP, version: exports.UAG_SCHEMA_VERSION, created: new Date() });
+                await this.ensureCollections();
+                debug(`Created the UAG's collections in "${this.name}".`);
+                return 'created';
+            }
+            await this.ensureCollections();
+            if (state === 'older') {
+                // No migrations yet: each schema version adds its steps here.
+                await this.meta.updateOne({ _id: SCHEMA_ID }, { $set: { version: exports.UAG_SCHEMA_VERSION, migrated: new Date() } });
+                return 'migrated';
+            }
+            return 'ready';
+        });
+        // A failed attempt can be tried again.
+        this.bootstrapped.catch(() => { this.bootstrapped = undefined; });
+        return this.bootstrapped;
+    }
+    /** Create the collections and indexes, as needed; safe to repeat. */
+    async ensureCollections() {
+        await this.authCodes.createIndex({ expiresAt: 1 }, { expireAfterSeconds: 0, name: 'expires' });
+        await this.taskRuns.createIndex({ status: 1, leaseUntil: 1 }, { name: 'claim' });
+        await this.taskRuns.createIndex({ project: 1, form: 1, submission: 1, created: -1 }, { name: 'submission' });
+        await this.ensureRetention();
+    }
+    /** The task-run records' TTL index, following TASK_RUN_RETENTION_DAYS; none when it is 0. */
+    async ensureRetention() {
+        const seconds = this.retentionDays * 24 * 60 * 60;
+        const indexes = await this.taskRuns.listIndexes().toArray().catch(() => []);
+        const existing = indexes.find((index) => index.name === RETENTION_INDEX);
+        if (!seconds) {
+            if (existing)
+                await this.taskRuns.dropIndex(RETENTION_INDEX);
+            return;
+        }
+        if (!existing) {
+            await this.taskRuns.createIndex({ created: 1 }, { expireAfterSeconds: seconds, name: RETENTION_INDEX });
+        }
+        else if (existing.expireAfterSeconds !== seconds) {
+            await this.db.command({ collMod: exports.UAG_COLLECTIONS.taskRuns, index: { name: RETENTION_INDEX, expireAfterSeconds: seconds } });
+        }
+    }
+    /** Run database work, reporting a missing privilege with the database's name. */
+    async privileged(work) {
+        try {
+            return await work();
+        }
+        catch (err) {
+            if (err?.code === UNAUTHORIZED) {
+                throw new UAGDatabaseError(`The MONGO user may not use the database "${this.name}" (${err.message}). ` +
+                    `Grant it the readWrite role on "${this.name}", or choose another database with UAG_DATABASE.`);
+            }
+            throw err;
+        }
+    }
+    /** Authorization codes for remote MCP clients (MCP_OAUTH), in `uag-authcodes`. */
+    authCodeStore() {
+        const collection = this.authCodes;
+        return {
+            async save(code, record, ttl) {
+                await collection.insertOne({ _id: codeKey(code), sealed: sealToken(code, record.jwt), codeChallenge: record.codeChallenge, expiresAt: new Date(Date.now() + ttl * 1000) });
+            },
+            async take(code) {
+                // The TTL monitor runs about once a minute, so expiry is checked here too.
+                const found = await collection.findOneAndDelete({ _id: codeKey(code), expiresAt: { $gt: new Date() } });
+                const jwt = typeof found?.sealed === 'string' ? openToken(code, found.sealed) : null;
+                return jwt ? { jwt, codeChallenge: found.codeChallenge } : null;
+            }
+        };
+    }
+    /** When the license server became unreachable, in `uag-meta`, so a restart neither begins nor extends the grace period. */
+    licenseGrace() {
+        const meta = this.meta;
+        const database = this;
+        return {
+            async read() {
+                const found = await meta.findOne({ _id: LICENSE_ID });
+                return typeof found?.outageSince === 'number' ? found.outageSince : undefined;
+            },
+            async write(since) {
+                // It may write before the license is known, so it never leaves uag-* collections without the marker.
+                await database.bootstrap();
+                await meta.updateOne({ _id: LICENSE_ID }, since === undefined ? { $unset: { outageSince: '' } } : { $set: { outageSince: since } }, { upsert: true });
+            }
+        };
+    }
+    async close() {
+        await this.client.close();
+    }
+}
+exports.UAGDatabase = UAGDatabase;

package/lib/formflow.d.ts

@@ -0,0 +1,40 @@
+import { Formflow } from '@formio/appserver-core';
+/**
+ * Agentic Formflow from @formio/appserver-core, imported directly rather than
+ * through @formio/appserver, under the names the UAG uses. Internal to the UAG:
+ * applications reach Formflow as `Formflow` from this package's exports.
+ */
+export declare const EngineConfigError: typeof Formflow.EngineConfigError, EngineRegistry: typeof Formflow.EngineRegistry, FormflowError: typeof Formflow.FormflowError, FormflowService: typeof Formflow.FormflowService, RateLimitError: typeof Formflow.RateLimitError, ScopedTokenError: typeof Formflow.ScopedTokenError, bearerOf: typeof Formflow.bearerOf, engineRegistry: typeof Formflow.engineRegistry, formflow: typeof Formflow.formflow, formflowAuthenticate: typeof Formflow.formflowAuthenticate, identityOf: typeof Formflow.identityOf, issueScopedToken: typeof Formflow.issueScopedToken, isScopedToken: typeof Formflow.isScopedToken, readScopedToken: typeof Formflow.readScopedToken, resolveTaskName: typeof Formflow.resolveTaskName, resultEvent: typeof Formflow.resultEvent, warnLegacy: typeof Formflow.warnLegacy, withoutOwnedValues: typeof Formflow.withoutOwnedValues, stubAgentEngine: typeof Formflow.stubAgentEngine, stubDecisionEngine: typeof Formflow.stubDecisionEngine, toolsForScope: typeof Formflow.toolsForScope, EngineError: typeof Formflow.EngineError, formatReport: typeof Formflow.formatReport;
+export type AgentEngine = Formflow.AgentEngine;
+export type CallerIdentity = Formflow.CallerIdentity;
+export type DecisionEngine = Formflow.DecisionEngine;
+export type DecisionRequest = Formflow.DecisionRequest;
+export type EngineInstance = Formflow.EngineInstance;
+export type EngineRegistry = Formflow.EngineRegistry;
+export type ExtractRequest = Formflow.ExtractRequest;
+export type ExtractResponse = Formflow.ExtractResponse;
+export type FieldSpec = Formflow.FieldSpec;
+export type ToolCallResult = Formflow.ToolCallResult;
+export type ToolDefinition = Formflow.ToolDefinition;
+export type FormflowAgentApiConfig = Formflow.FormflowAgentApiConfig;
+export type FormflowConfig = Formflow.FormflowConfig;
+export type FormflowForm = Formflow.FormflowForm;
+export type FormflowHost = Formflow.FormflowHost;
+export type FormflowRateLimit = Formflow.FormflowRateLimit;
+export type FormflowRoutingConfig = Formflow.FormflowRoutingConfig;
+export type FormflowService = Formflow.FormflowService;
+export type FormflowTask = Formflow.FormflowTask;
+export type FormflowTool = Formflow.FormflowTool;
+export type OperationContext = Formflow.OperationContext;
+export type OperationResult = Formflow.OperationResult;
+export type ScopedTokenClaims = Formflow.ScopedTokenClaims;
+/**
+ * Who an operation's research acts as: core's `identityOf`, and for a caller
+ * signed in with a Form.io token (`x-jwt-token`), that token, so a scoped token
+ * carries the user to /mcp as an `Authorization` bearer token would. A portal
+ * team member's remote token is never carried: research for them is refused,
+ * as it is for anonymous callers.
+ */
+export declare function callerIdentity(auth: any, req: {
+    get?: (name: string) => string | undefined;
+}): CallerIdentity;

package/lib/formflow.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatReport = exports.EngineError = exports.toolsForScope = exports.stubDecisionEngine = exports.stubAgentEngine = exports.withoutOwnedValues = exports.warnLegacy = exports.resultEvent = exports.resolveTaskName = exports.readScopedToken = exports.isScopedToken = exports.issueScopedToken = exports.identityOf = exports.formflowAuthenticate = exports.formflow = exports.engineRegistry = exports.bearerOf = exports.ScopedTokenError = exports.RateLimitError = exports.FormflowService = exports.FormflowError = exports.EngineRegistry = exports.EngineConfigError = void 0;
+exports.callerIdentity = callerIdentity;
+const appserver_core_1 = require("@formio/appserver-core");
+/**
+ * Agentic Formflow from @formio/appserver-core, imported directly rather than
+ * through @formio/appserver, under the names the UAG uses. Internal to the UAG:
+ * applications reach Formflow as `Formflow` from this package's exports.
+ */
+({ EngineConfigError: exports.EngineConfigError, EngineRegistry: exports.EngineRegistry, FormflowError: exports.FormflowError, FormflowService: exports.FormflowService, RateLimitError: exports.RateLimitError, ScopedTokenError: exports.ScopedTokenError, bearerOf: exports.bearerOf, engineRegistry: exports.engineRegistry, formflow: exports.formflow, formflowAuthenticate: exports.formflowAuthenticate, identityOf: exports.identityOf, issueScopedToken: exports.issueScopedToken, isScopedToken: exports.isScopedToken, readScopedToken: exports.readScopedToken, resolveTaskName: exports.resolveTaskName, resultEvent: exports.resultEvent, warnLegacy: exports.warnLegacy, withoutOwnedValues: exports.withoutOwnedValues, stubAgentEngine: exports.stubAgentEngine, stubDecisionEngine: exports.stubDecisionEngine, toolsForScope: exports.toolsForScope, EngineError: exports.EngineError, formatReport: exports.formatReport } = appserver_core_1.Formflow);
+/**
+ * Who an operation's research acts as: core's `identityOf`, and for a caller
+ * signed in with a Form.io token (`x-jwt-token`), that token, so a scoped token
+ * carries the user to /mcp as an `Authorization` bearer token would. A portal
+ * team member's remote token is never carried: research for them is refused,
+ * as it is for anonymous callers.
+ */
+function callerIdentity(auth, req) {
+    const identity = (0, exports.identityOf)(auth, req.get?.('authorization'));
+    if (identity.admin || identity.bearer)
+        return identity;
+    const formioToken = req.get?.('x-jwt-token');
+    if (auth?.user && !auth.remoteToken && typeof formioToken === 'string' && formioToken) {
+        return { admin: false, bearer: formioToken };
+    }
+    return identity;
+}

package/lib/identity.d.ts

@@ -0,0 +1,53 @@
+import { AuthRequest } from '@formio/appserver';
+import { FormflowError } from './formflow';
+import type { UAGProjectInterface } from './UAGProjectInterface';
+/**
+ * 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. */
+export declare const SIGNED_TOKEN_TTL = 300;
+/** The user the UAG acts for: who sent the submission. No token, ever. */
+export type ActingFor = {
+    /** The user's id; none for an anonymous caller. */
+    _id?: string;
+    /** Their roles when they submitted. */
+    roles: string[];
+    email?: string;
+};
+/** What a token the UAG signs says about why it was signed (Form.io ignores it). */
+export type AgentClaim = {
+    agent: boolean;
+    action?: string;
+    task?: string;
+};
+/** A token the UAG may not sign, or Form.io would not accept. */
+export declare class AgentIdentityError extends FormflowError {
+    constructor(message: string);
+}
+/** The user a request comes from, as the UAG records it. */
+export declare function actingForOf(auth: AuthRequest | undefined, project: UAGProjectInterface): ActingFor;
+/**
+ * Sign a Form.io token for `user` with `roles`. Refuses an admin role, and never
+ * marks the holder an administrator.
+ */
+export declare function signFormioToken(project: UAGProjectInterface, user: ActingFor, roles: string[], claim: AgentClaim): string;
+/** An identity that acts as `role` for `user`, with a newly signed token. */
+export declare function agentAuth(project: UAGProjectInterface, user: ActingFor, role: string, claim: Omit<AgentClaim, 'agent'>): Promise<AuthRequest>;
+/**
+ * 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.
+ */
+export declare function userAuth(project: UAGProjectInterface, user: ActingFor, claim: Omit<AgentClaim, 'agent'>): Promise<AuthRequest>;
+/**
+ * Explain a Form.io refusal of a token the UAG signed: almost always a
+ * JWT_SECRET that is not Form.io Enterprise's.
+ */
+export declare function refusedSignedToken(status: number | undefined): AgentIdentityError | null;