@formio/uag 1.13.2 → 2.0.0-rc.10

package/lib/agent/router.js

@@ -0,0 +1,307 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_BODY_LIMIT = void 0;
+exports.agentBodyLimit = agentBodyLimit;
+exports.agentEndpoints = agentEndpoints;
+exports.AgentRouter = AgentRouter;
+exports.agentNotFound = agentNotFound;
+exports.agentCredentials = agentCredentials;
+exports.FormAgentRouter = FormAgentRouter;
+const lodash_1 = require("lodash");
+const express_1 = __importStar(require("express"));
+const errors_1 = require("./errors");
+const formflow_1 = require("../formflow");
+const requestId_1 = require("./requestId");
+const anonymous_1 = require("./anonymous");
+const chat_1 = require("./chat");
+const debug = require('debug')('formio:uag:agent');
+function wantsStream(req) {
+    return String(req.get('accept') || '').includes('text/event-stream');
+}
+/** Server-Sent Events over the POST response. */
+function openStream(res) {
+    res.status(200).set({
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        'Connection': 'keep-alive',
+        'X-Accel-Buffering': 'no'
+    });
+    res.flushHeaders?.();
+    return (event, data) => {
+        res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+    };
+}
+/** Who is asking, and who the operation runs as. */
+function contextOf(req) {
+    return { auth: req.auth, requestId: req.requestId, identity: (0, formflow_1.callerIdentity)(req.auth, req) };
+}
+/**
+ * The task the request names, if any. A request that still names a 1.x
+ * `persona` is refused: ignoring it would run every task, an engine call each.
+ */
+function taskOf(req) {
+    const named = (value) => typeof value === 'string' && value.trim() !== '';
+    const task = req.body?.task;
+    if (named(req.body?.persona) && !named(task)) {
+        throw new formflow_1.FormflowError(400, 'UAG 2.0 renamed "persona" to "task". Send "task" instead.');
+    }
+    return named(task) ? task : undefined;
+}
+/**
+ * Answer extract, streaming per-engine results when the client asks for a
+ * stream: decision results arrive before slower LLM results.
+ */
+async function respondWithStream(req, res, run) {
+    const stream = wantsStream(req);
+    let send = null;
+    const done = await run({
+        ...contextOf(req),
+        onStart: () => {
+            if (stream)
+                send = openStream(res);
+        },
+        onResult: (result) => {
+            if (!send)
+                return;
+            send('result', (0, formflow_1.resultEvent)(result));
+            if (result.error)
+                send('error', { kind: result.kind, task: result.task, error: result.error, attempts: result.attempts });
+        }
+    });
+    if (send) {
+        send('done', done);
+        res.end();
+    }
+    else {
+        res.json(done);
+    }
+}
+/** The largest request body an agent operation takes by default, in bytes. */
+exports.AGENT_BODY_LIMIT = 5 * 1024 * 1024;
+/**
+ * The largest request body the project's agent operations take: `agentApi.bodyLimit`,
+ * then AGENT_BODY_LIMIT, then 5 MB. A document sent inline (a base64 file a task reads)
+ * may need more; the server's own MAX_BODY_SIZE (16 MB) still applies first.
+ */
+function agentBodyLimit(project) {
+    const configured = Number(project.config?.agentApi?.bodyLimit ?? process.env.AGENT_BODY_LIMIT);
+    return Number.isFinite(configured) && configured > 0 ? configured : exports.AGENT_BODY_LIMIT;
+}
+/** The parts every Agent API endpoint shares: the request id, and errors answered as JSON (or as an event mid-stream). */
+function agentEndpoints(project) {
+    const limit = agentBodyLimit(project);
+    const parse = express_1.default.json({ limit });
+    // The server parses JSON bodies first, with its own larger limit, so the
+    // agent operations' limit is checked here on a body already read.
+    const json = (req, res, next) => {
+        if (req.body === undefined)
+            return parse(req, res, next);
+        const length = Number(req.get('content-length')) || Buffer.byteLength(JSON.stringify(req.body ?? null));
+        if (length > limit) {
+            return res.status(413).json({ error: `The request body is larger than the agent operations' limit of ${Math.round(limit / (1024 * 1024) * 10) / 10} MB.`, code: 'payload_too_large' });
+        }
+        next();
+    };
+    // The request id, usually assigned already by agentErrorShape, ahead of every
+    // refusal. One that is not a short token is replaced, so it is never echoed,
+    // logged or sent on.
+    const requestId = (req, res, next) => {
+        (0, errors_1.requestIdOf)(req, res);
+        next();
+    };
+    const handle = (operation, fn) => async (req, res) => {
+        const agentReq = req;
+        const service = (0, formflow_1.formflow)(project);
+        try {
+            service.takeCaller(operation, agentReq.auth);
+            // Remote engines send the request id on to the engine server.
+            await (0, requestId_1.withRequestId)(agentReq.requestId, () => fn(agentReq, res, service));
+        }
+        catch (err) {
+            const { status, body } = (0, errors_1.agentError)(agentReq.requestId, err);
+            if (status === 500) {
+                debug(`[${agentReq.requestId}] ${operation} failed:`, err);
+            }
+            if (err instanceof formflow_1.RateLimitError) {
+                res.set('Retry-After', String(Math.ceil(err.retryAfterMs / 1000)));
+            }
+            if (res.headersSent) {
+                // Mid-stream: report the failure as an event and close.
+                res.write(`event: error\ndata: ${JSON.stringify(body)}\n\n`);
+                res.end();
+            }
+            else {
+                res.status(status).json(body);
+            }
+        }
+    };
+    return { json, requestId, handle };
+}
+/**
+ * `GET /agent/capabilities`, behind `authenticate`. Only this path is claimed:
+ * any other `/agent...` path (a project form at `agent`, for one) falls through
+ * to the routes after this router.
+ */
+function AgentRouter(project, authenticate) {
+    const router = (0, express_1.Router)();
+    const { json, requestId, handle } = agentEndpoints(project);
+    router.get('/agent/capabilities', authenticate, json, requestId, handle('capabilities', async (req, res, service) => {
+        const capabilities = await service.capabilities();
+        // Chat is part of conversation forms: it needs an agent engine, never a license.
+        const engines = (0, chat_1.chatEngines)(project).map((engine) => engine.name);
+        capabilities.operations.chat = { available: engines.length > 0, engines };
+        res.json({ requestId: req.requestId, ...capabilities });
+    }));
+    return router;
+}
+/**
+ * A form's agent operation for a path that names no form of the project (the
+ * old root operations, a deleted form): answered 404 here, so it is never
+ * passed through to Form.io. A form that exists goes on to its own routes,
+ * which answer 404 themselves when it is not tagged `uag`.
+ */
+function agentNotFound(project) {
+    // Express matches routes ignoring case, so this does too.
+    const operation = /^(.*)\/agent\/(extract|decide|generate|chat)\/?$/i;
+    return async (req, res, next) => {
+        const match = req.method === 'POST' ? operation.exec(req.path) : null;
+        if (!match)
+            return next();
+        // The form's path under the project's mount: the root on Open Source,
+        // otherwise `/{name}` or `/project/{id}`, and nothing else.
+        const mounts = [/^\/project\/[0-9a-fA-F]{24}(?=\/|$)/i];
+        if (project.name)
+            mounts.push(new RegExp(`^/${(0, lodash_1.escapeRegExp)(project.name)}(?=/|$)`, 'i'));
+        let formPath = match[1];
+        const mount = mounts.find((pattern) => pattern.test(formPath));
+        if (mount)
+            formPath = formPath.replace(mount, '');
+        else if (!project.oss)
+            formPath = '';
+        formPath = formPath.replace(/^\/+/, '');
+        const byId = /^form\/([0-9a-fA-F]{24})$/i.exec(formPath);
+        const forms = Object.values(project.forms || {});
+        const known = byId
+            ? forms.some((form) => String(form.form?._id || '') === byId[1]) || !!(await project.getKnownFormById?.(byId[1]))
+            : !!formPath && forms.some((form) => String(form.path || '').toLowerCase() === formPath.toLowerCase());
+        if (known)
+            return next();
+        res.status(404).json({ error: `The form "${byId ? byId[1] : formPath}" does not exist or is not tagged "uag".`, code: 'form_not_found' });
+    };
+}
+function refuse(res, error) {
+    return res.status(401).json({ error, code: 'unauthorized' });
+}
+/**
+ * Who may call a form's agent operations, on top of the project's own
+ * authentication (Form.io user tokens, portal remote tokens, server keys):
+ * scoped tokens never (they are for /mcp), server keys only from servers, and
+ * UAG bearer tokens, verified here. A caller with no credential gets through
+ * only where the form allows anonymous use (see anonymousGate).
+ */
+function agentCredentials(project) {
+    const anonymous = (0, anonymous_1.anonymousGate)(project);
+    return (req, res, next) => {
+        const request = req;
+        const authorization = req.get('authorization');
+        const bearer = (0, formflow_1.bearerOf)(authorization);
+        // Scoped tokens are for a task's calls back into /mcp. They must never
+        // start new work: an admin scoped token would otherwise grant full
+        // admin access to the agent operations for its lifetime.
+        if (bearer && (0, formflow_1.isScopedToken)(bearer)) {
+            return refuse(res, 'Scoped tokens can only be used on /mcp.');
+        }
+        if (req.get('x-token') !== undefined || req.get('x-admin-key') !== undefined) {
+            // Browsers send Origin on cross-origin requests, and Sec-Fetch-Site on all
+            // of them. (Node's fetch sends Sec-Fetch-Mode but not Sec-Fetch-Site.)
+            if (req.get('origin') || req.get('sec-fetch-site')) {
+                return refuse(res, 'Admin credentials cannot be used from a browser. Use a bearer token.');
+            }
+            return request.auth?.admin ? next() : refuse(res, 'Invalid admin credential.');
+        }
+        if (request.auth?.admin || request.auth?.user) {
+            return next();
+        }
+        if (bearer) {
+            const form = request.form;
+            return project.authorizeRequest(request, res, () => {
+                if (request.auth)
+                    request.auth.form = form || null;
+                next();
+            });
+        }
+        return anonymous(req, res, next);
+    };
+}
+/**
+ * A form's agent operations, `POST /agent/extract|decide|generate|chat`, mounted on
+ * the form's own routes (see UAGFormInterface.router), so `req.form` is the
+ * form of the URL.
+ */
+function FormAgentRouter(project, credentials) {
+    const router = (0, express_1.Router)();
+    const { json, requestId, handle } = agentEndpoints(project);
+    const route = (path, operation, fn) => {
+        router.post(`/agent/${path}`, credentials, json, requestId, handle(operation, fn));
+    };
+    const formOf = (req) => req.form?.name;
+    route('extract', 'extract', async (req, res, service) => {
+        const { text, data, overwrite } = req.body || {};
+        const task = taskOf(req);
+        await respondWithStream(req, res, (context) => service.extract({ form: formOf(req), task, text, data, overwrite }, context));
+    });
+    route('decide', 'decide', async (req, res, service) => {
+        const { data, submissionId, overwrite } = req.body || {};
+        res.json(await service.decide({ form: formOf(req), task: taskOf(req), data, submissionId, overwrite }, contextOf(req)));
+    });
+    route('generate', 'generate', async (req, res, service) => {
+        const { data, overwrite } = req.body || {};
+        res.json(await service.generate({ form: formOf(req), task: taskOf(req), data, overwrite }, contextOf(req)));
+    });
+    // A turn of the form's chat. Not Agentic Formflow: no license check, as for the MCP tools.
+    route('chat', 'chat', async (req, res, service) => {
+        const form = await project.formflowForm(formOf(req));
+        if (!form) {
+            throw new formflow_1.FormflowError(404, `The form "${formOf(req)}" does not exist or is not tagged "uag".`, 'form_not_found');
+        }
+        if ((0, formflow_1.flagOff)(form.form?.properties?.uagChat)) {
+            throw new formflow_1.FormflowError(403, `Chat is turned off for the form "${form.formflowName}".`, 'chat_disabled');
+        }
+        service.requireAccess(req.auth, form, ['create']);
+        res.json(await (0, chat_1.chatTurn)(project, form, req.body, { auth: req.auth, requestId: req.requestId }));
+    });
+    return router;
+}

package/lib/agent/stubs.d.ts

@@ -0,0 +1,37 @@
+import type { GenerateRequest } from '@formio/uag-sdk';
+/**
+ * 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.
+ */
+export declare const StubDecisionEngine: Readonly<{
+    type: "engine";
+    name: string;
+    title: string;
+    kinds: "decision"[];
+    apiVersion: 1;
+    description: string;
+    create: ({ name }: import("@formio/uag-sdk").EngineCreateContext<any>) => import("@formio/appserver-core/lib/formflow").DecisionEngine & {
+        calls: number;
+    };
+}>;
+/** How many generate requests the stub agent engines keep: a UAG running them for a demo never grows without bound. */
+export declare const STUB_GENERATE_REQUESTS_KEPT = 20;
+/** The last generate requests the stub agent engines received (STUB_GENERATE_REQUESTS_KEPT), oldest first, for tests. */
+export declare const stubGenerateRequests: Array<Omit<GenerateRequest, 'signal' | 'onProgress'> & {
+    engine: string;
+}>;
+export declare const StubAgentEngine: Readonly<{
+    type: "engine";
+    name: string;
+    title: string;
+    kinds: "agent"[];
+    apiVersion: 1;
+    description: string;
+    create: ({ name }: import("@formio/uag-sdk").EngineCreateContext<any>) => import("@formio/appserver-core/lib/formflow").AgentEngine & {
+        calls: number;
+        lastExtract?: import("@formio/appserver-core/lib/formflow").ExtractRequest;
+    };
+}>;

package/lib/agent/stubs.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StubAgentEngine = exports.stubGenerateRequests = exports.STUB_GENERATE_REQUESTS_KEPT = 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: 'engine',
+    name: 'stub-decision',
+    title: 'Stub decision engine',
+    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 }),
+});
+/** How many generate requests the stub agent engines keep: a UAG running them for a demo never grows without bound. */
+exports.STUB_GENERATE_REQUESTS_KEPT = 20;
+/** The last generate requests the stub agent engines received (STUB_GENERATE_REQUESTS_KEPT), oldest first, for tests. */
+exports.stubGenerateRequests = [];
+exports.StubAgentEngine = (0, uag_sdk_1.defineEngine)({
+    type: 'engine',
+    name: 'stub-agent',
+    title: 'Stub agent engine',
+    kinds: ['agent'],
+    apiVersion: uag_sdk_1.ENGINE_API_VERSION,
+    description: 'Extracts nothing; generates a predictable answer from the text it is given. For tests and local development.',
+    // Text only; its generate answer shows what reached it. Observing its requests keeps it a built-in stub.
+    create: ({ name }) => (0, formflow_1.stubAgentEngine)({ name, onGenerate: (request) => {
+            exports.stubGenerateRequests.push({ ...request, engine: name });
+            if (exports.stubGenerateRequests.length > exports.STUB_GENERATE_REQUESTS_KEPT)
+                exports.stubGenerateRequests.splice(0, exports.stubGenerateRequests.length - exports.STUB_GENERATE_REQUESTS_KEPT);
+        } }),
+});

package/lib/agent/tools.d.ts

@@ -0,0 +1,31 @@
+import { FormflowTool } from "../formflow";
+import type { AuthRequest } from "@formio/appserver";
+import type { UAGProjectInterface } from "../UAGProjectInterface";
+import { ToolEntry, ToolInfo } from "../tools/utils";
+/** Record the module a tool came from: its `execute` gets the module's API as `extra.module`. */
+export declare function setToolModule(entry: object, api: any): void;
+/**
+ * A `config.tools` entry as a tool for the project: a bound tool's static
+ * fields, overlaid with what its `bind(project)` returns. A tool without
+ * `bind` (the 1.x shape) is used as it is.
+ */
+export declare function resolveTool(project: UAGProjectInterface, entry: ToolEntry): Promise<ToolInfo | undefined>;
+/**
+ * Every tool the UAG serves, including custom tools from configuration, each
+ * entry of which is a tool, optionally bound to the project.
+ */
+export declare function allTools(project: UAGProjectInterface): Promise<ToolInfo[]>;
+/**
+ * Run a tool with its arguments and the `ToolExtra` for the project: the same
+ * call on `/mcp` and for Agent API research. `context` is whatever else the
+ * caller has (on `/mcp`, the MCP SDK's request context, with `authInfo`).
+ */
+export declare function runTool(tool: ToolInfo, project: UAGProjectInterface, args: any, context: {
+    authInfo: AuthRequest;
+    [key: string]: any;
+}): any;
+/**
+ * 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, project: UAGProjectInterface): FormflowTool;

package/lib/agent/tools.js

@@ -0,0 +1,76 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setToolModule = setToolModule;
+exports.resolveTool = resolveTool;
+exports.allTools = allTools;
+exports.runTool = runTool;
+exports.formflowTool = formflowTool;
+const zod_1 = __importDefault(require("zod"));
+const tools_1 = require("../tools");
+const utils_1 = require("../tools/utils");
+/** The module API of the module each `config.tools` entry came from, for its `extra.module`. */
+const toolModules = new WeakMap();
+/** Record the module a tool came from: its `execute` gets the module's API as `extra.module`. */
+function setToolModule(entry, api) {
+    if (entry && typeof entry === 'object')
+        toolModules.set(entry, api);
+}
+/**
+ * A `config.tools` entry as a tool for the project: a bound tool's static
+ * fields, overlaid with what its `bind(project)` returns. A tool without
+ * `bind` (the 1.x shape) is used as it is.
+ */
+async function resolveTool(project, entry) {
+    if (!entry || typeof entry.bind !== 'function')
+        return entry;
+    const { bind, ...fixed } = entry;
+    const tool = { ...fixed, ...((await bind(project)) || {}) };
+    if (toolModules.has(entry))
+        toolModules.set(tool, toolModules.get(entry));
+    return tool;
+}
+/**
+ * Every tool the UAG serves, including custom tools from configuration, each
+ * entry of which is a tool, optionally bound to the project.
+ */
+async function allTools(project) {
+    (0, utils_1.assertToolEntries)(project.config?.tools);
+    const custom = await Promise.all((project.config?.tools || []).map((entry) => resolveTool(project, entry)));
+    return [...await (0, tools_1.getTools)(project), ...custom].filter((tool) => !!tool?.name);
+}
+/**
+ * Run a tool with its arguments and the `ToolExtra` for the project: the same
+ * call on `/mcp` and for Agent API research. `context` is whatever else the
+ * caller has (on `/mcp`, the MCP SDK's request context, with `authInfo`).
+ */
+function runTool(tool, project, args, context) {
+    if (!tool.execute) {
+        return { content: [{ type: 'text', text: `The tool "${tool.name}" has no implementation.` }], isError: true };
+    }
+    const module = toolModules.get(tool);
+    const extra = { ...context, authInfo: context.authInfo, project, ...(module && { module }) };
+    return tool.execute(args ?? {}, extra);
+}
+/**
+ * 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, project) {
+    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) => runTool(tool, project, args, { authInfo: auth })
+    };
+}

package/lib/config.d.ts

@@ -1,5 +1,8 @@
 import { ServerConfig } from '@formio/appserver';
-import { ToolInfo } from './tools/utils';
+import type { FormflowAgentApiConfig, FormflowRateLimit, FormflowRoutingConfig } from './formflow';
+import type { EngineInstanceSpec, EngineTypeDefinition } from '@formio/uag-sdk';
+import type { ToolEntry, ToolInfo } from './tools/utils';
+import type { UAGDatabaseOptions } from './database';
 export type UAGForm = {
     name: string;
     title: string;
@@ -43,13 +46,104 @@ export type UAGToolOverride = {
     submit_completed_form?: ToolInfo;
     submission_update?: ToolInfo;
     find_submissions?: ToolInfo;
-    agent_provide_data?: ToolInfo;
+    agent_provide?: ToolInfo;
+    agent_decide?: ToolInfo;
     fetch_external_data?: ToolInfo;
+    read_document?: ToolInfo;
 };
+/** `config.documents`: limits and choices of the AI Document module (@formio/uag-extras/modules/ai-document). */
+export type UAGDocumentsConfig = {
+    /** Largest uploaded file read, in bytes (25 MB). DOCUMENTS_MAX_FILE_BYTES. */
+    maxFileBytes?: number;
+    /** Most files one component sends (10). */
+    maxFiles?: number;
+    /** Most bytes of one request's files (32 MB, the provider request cap). */
+    maxTotalBytes?: number;
+    /** Most pages once converted (500). DOCUMENTS_MAX_PAGES. */
+    maxPages?: number;
+    /** Most characters of text once converted (2,000,000). */
+    maxTextChars?: number;
+    /** One processing request, in ms (600000). DOCUMENTS_TIMEOUT_MS. */
+    timeoutMs?: number;
+    /** Comment line interval on a streamed response, in ms (15000). */
+    heartbeatMs?: number;
+    /** Concurrent processing requests per identity (3). */
+    perUser?: number;
+    /** The engine instance documents use. Default: the first capable agent engine. DOCUMENTS_ENGINE. */
+    engine?: string;
+    /** Converter name by MIME type, when several can do a step. */
+    prefer?: Record<string, string>;
+};
+/**
+ * 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;
+    /** The largest request body an agent operation takes, in bytes (AGENT_BODY_LIMIT). Default 5 MB. */
+    bodyLimit?: number;
+};
+/**
+ * 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;
+    /** Limits and choices of the AI Document module. */
+    documents?: UAGDocumentsConfig;
     toolOverrides?: UAGToolOverride;
-    tools?: ToolInfo[];
+    /** Custom MCP tools: each a tool, optionally bound to the project with `bind(project)` (see ToolInfo.bind). */
+    tools?: ToolEntry[];
+    /**
+     * 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;
+}