@formio/uag 1.13.2 → 2.0.0-rc.1

package/lib/agent/remote.d.ts

@@ -0,0 +1,67 @@
+import type { RemoteEngineDescription } from '@formio/uag-sdk/protocol';
+import type { AgentEngine, DecisionEngine } from '../formflow';
+/**
+ * The `remote` engine type: an engine hosted by an engine server
+ * (`formio/uag-engines`), reached over the remote engine protocol. Any
+ * engine package can run there, so model credentials and model traffic stay in
+ * that container.
+ *
+ *   UAG_ENGINES=jev,claude:remote
+ *   UAG_ENGINE_CLAUDE_URL=http://engines:3300
+ *   UAG_ENGINE_CLAUDE_KEY=<the engine server key, at least 32 characters>
+ *
+ * Every request carries the engine server key, and never a Form.io credential.
+ * Research extracts also carry a scoped token, which the engine server uses for
+ * its own MCP connection back to the UAG: it allows only the task's read-only
+ * tools, with the caller's identity. Each call also carries the Agent API
+ * request id, when it is a short token, for logs on either side.
+ */
+/** The shortest engine server key accepted. */
+export declare const MIN_KEY_LENGTH = 32;
+type Fetch = typeof fetch;
+type Connection = {
+    /** The instance name, for errors. */
+    name: string;
+    baseUrl: string;
+    key: string;
+    fetch: Fetch;
+};
+/**
+ * Describe the remote engine, retrying while the engine server is unreachable
+ * or failing, with the backoff used to wait for a Form.io project. A refused
+ * key, or a server that does not host the engine, stops startup at once.
+ */
+export declare function describeRemote(connection: Connection, engine: string, { retries, retryDelay, timeout }?: {
+    retries?: number;
+    retryDelay?: number;
+    timeout?: number;
+}): Promise<RemoteEngineDescription>;
+/** An engine object for a described remote engine. */
+export declare function remoteEngine(connection: Connection, remoteName: string, described: RemoteEngineDescription): DecisionEngine | AgentEngine;
+export declare const RemoteEngine: Readonly<{
+    type: string;
+    kinds: ("agent" | "decision")[];
+    apiVersion: 1;
+    description: string;
+    settings: {
+        url: {
+            required: true;
+            description: string;
+        };
+        key: {
+            required: true;
+            secret: true;
+            description: string;
+        };
+        engine: {
+            description: string;
+        };
+        timeout: {
+            type: "number";
+            default: number;
+            description: string;
+        };
+    };
+    create({ name, settings, options, config }: import("@formio/uag-sdk").EngineCreateContext<any>): Promise<import("@formio/appserver-core/lib/formflow").AgentEngine | import("@formio/appserver-core/lib/formflow").DecisionEngine>;
+}>;
+export {};

package/lib/agent/remote.js

@@ -0,0 +1,229 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RemoteEngine = exports.MIN_KEY_LENGTH = void 0;
+exports.describeRemote = describeRemote;
+exports.remoteEngine = remoteEngine;
+const uag_sdk_1 = require("@formio/uag-sdk");
+const protocol_1 = require("@formio/uag-sdk/protocol");
+const requestId_1 = require("./requestId");
+const debug = require('debug')('formio:uag:remote');
+/**
+ * The `remote` engine type: an engine hosted by an engine server
+ * (`formio/uag-engines`), reached over the remote engine protocol. Any
+ * engine package can run there, so model credentials and model traffic stay in
+ * that container.
+ *
+ *   UAG_ENGINES=jev,claude:remote
+ *   UAG_ENGINE_CLAUDE_URL=http://engines:3300
+ *   UAG_ENGINE_CLAUDE_KEY=<the engine server key, at least 32 characters>
+ *
+ * Every request carries the engine server key, and never a Form.io credential.
+ * Research extracts also carry a scoped token, which the engine server uses for
+ * its own MCP connection back to the UAG: it allows only the task's read-only
+ * tools, with the caller's identity. Each call also carries the Agent API
+ * request id, when it is a short token, for logs on either side.
+ */
+/** The shortest engine server key accepted. */
+exports.MIN_KEY_LENGTH = 32;
+const DEFAULT_RETRIES = 5;
+const DEFAULT_RETRY_DELAY = 5000;
+const MAX_RETRY_DELAY = 60000;
+class StartupError extends uag_sdk_1.EngineConfigError {
+    /** Whether trying again may help: the server was unreachable or failing. */
+    constructor(message, retry) {
+        super(message);
+        this.retry = retry;
+    }
+}
+async function readJson(response) {
+    try {
+        return await response.json();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Describe the remote engine, retrying while the engine server is unreachable
+ * or failing, with the backoff used to wait for a Form.io project. A refused
+ * key, or a server that does not host the engine, stops startup at once.
+ */
+async function describeRemote(connection, engine, { retries = DEFAULT_RETRIES, retryDelay = DEFAULT_RETRY_DELAY, timeout = 10000 } = {}) {
+    const where = `the engine server at ${connection.baseUrl}`;
+    const attempts = Math.max(1, retries);
+    for (let attempt = 1;; attempt++) {
+        try {
+            return await describeOnce(connection, engine, where, timeout);
+        }
+        catch (err) {
+            if (!(err instanceof StartupError && err.retry) || attempt >= attempts) {
+                throw new uag_sdk_1.EngineConfigError(`The "${connection.name}" engine could not start: ${err.message}`);
+            }
+            const delay = Math.min(retryDelay * Math.pow(2, attempt - 1), MAX_RETRY_DELAY);
+            debug(`${err.message} Retrying in ${delay}ms (attempt ${attempt} of ${attempts}).`);
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+    }
+}
+async function describeOnce(connection, engine, where, timeout) {
+    let response;
+    try {
+        response = await connection.fetch(`${connection.baseUrl}/v1/engines`, {
+            headers: { Accept: 'application/json', Authorization: `Bearer ${connection.key}` },
+            signal: AbortSignal.timeout(timeout),
+        });
+    }
+    catch (err) {
+        throw new StartupError(`${where} is unreachable (${err?.cause?.code || err?.name || 'no response'}).`, true);
+    }
+    if (response.status === 401 || response.status === 403) {
+        throw new StartupError(`${where} refused the engine server key (HTTP ${response.status}).`, false);
+    }
+    if (!response.ok) {
+        throw new StartupError(`${where} answered HTTP ${response.status}.`, response.status >= 500);
+    }
+    let engines;
+    try {
+        engines = (0, protocol_1.checkDescription)(await readJson(response));
+    }
+    catch (err) {
+        throw new StartupError(`${where} did not answer as an engine server: ${err.message}`, false);
+    }
+    const described = engines.find((candidate) => candidate.name === engine);
+    if (!described) {
+        throw new StartupError(`${where} does not host an engine named "${engine}"` +
+            (engines.length ? ` (it hosts ${engines.map((e) => `"${e.name}"`).join(', ')}).` : ' (it hosts none).'), false);
+    }
+    return described;
+}
+/** One protocol call. Failures are engine failures, safe to show unless the server says otherwise. */
+async function call(connection, path, body, signal, scopedToken) {
+    signal?.throwIfAborted();
+    const requestId = (0, protocol_1.safeRequestId)((0, requestId_1.currentRequestId)());
+    const headers = {
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+        Authorization: `Bearer ${connection.key}`,
+        ...(scopedToken && { [protocol_1.SCOPED_TOKEN_HEADER]: scopedToken }),
+        ...(requestId && { [protocol_1.REQUEST_ID_HEADER]: requestId }),
+    };
+    let response;
+    try {
+        response = await connection.fetch(`${connection.baseUrl}${path}`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({ protocol: protocol_1.PROTOCOL_VERSION, ...body }),
+            signal,
+        });
+    }
+    catch (err) {
+        if (signal?.aborted)
+            throw signal.reason ?? err;
+        // Callers see the failure; only the UAG's log names where the engine server is.
+        debug(`The engine server at ${connection.baseUrl} could not be reached: ${err?.cause?.code || err?.name || 'no response'}`);
+        throw new uag_sdk_1.EngineError('The engine server could not be reached.');
+    }
+    const json = await readJson(response);
+    if (!response.ok) {
+        if (json?.expose === true && typeof json.error === 'string') {
+            throw new uag_sdk_1.EngineError(json.error);
+        }
+        debug(`The engine server answered HTTP ${response.status}: ${json?.error || '(no message)'}`);
+        throw new uag_sdk_1.EngineError(`The engine server answered HTTP ${response.status}.`);
+    }
+    return json;
+}
+/** Validate a response, reporting a malformed one as an engine failure. */
+function valid(check, body) {
+    try {
+        return check(body);
+    }
+    catch (err) {
+        throw new uag_sdk_1.EngineError(`The engine server's answer did not follow the remote engine protocol: ${err.message}`);
+    }
+}
+/** An engine object for a described remote engine. */
+function remoteEngine(connection, remoteName, described) {
+    const path = `/v1/engines/${encodeURIComponent(remoteName)}`;
+    if (described.kind === 'decision') {
+        return {
+            name: connection.name,
+            kind: 'decision',
+            apiVersion: uag_sdk_1.ENGINE_API_VERSION,
+            model: described.model,
+            maxOptions: described.maxOptions,
+            async decide({ state, questions, signal }) {
+                const response = valid(protocol_1.checkDecisionResponse, await call(connection, `${path}/decide`, { state, questions }, signal));
+                return { ...response, model: response.model || described.model };
+            },
+        };
+    }
+    return {
+        name: connection.name,
+        kind: 'agent',
+        apiVersion: uag_sdk_1.ENGINE_API_VERSION,
+        model: described.model,
+        toolUse: described.toolUse === true,
+        async extract(request) {
+            const research = !!request.tools?.length;
+            // The engine server researches through its own MCP connection to the
+            // UAG, which needs a scoped token; without one (no JWT_SECRET), no call.
+            if (research && !request.scopedToken) {
+                throw new uag_sdk_1.EngineError('The remote engine cannot research without a scoped token. Set JWT_SECRET on the UAG.');
+            }
+            const body = {
+                instructions: request.instructions,
+                state: request.state,
+                fields: request.fields,
+                schema: request.schema,
+                ...(research && { tools: request.tools, maxIterations: request.maxIterations || 10 }),
+            };
+            const response = valid(protocol_1.checkExtractResponse, await call(connection, `${path}/extract`, body, request.signal, research ? request.scopedToken : undefined));
+            return { ...response, model: response.model || described.model };
+        },
+    };
+}
+exports.RemoteEngine = (0, uag_sdk_1.defineEngine)({
+    type: 'remote',
+    kinds: ['decision', 'agent'],
+    apiVersion: uag_sdk_1.ENGINE_API_VERSION,
+    description: 'An engine hosted by an engine server, over the remote engine protocol.',
+    settings: {
+        url: { required: true, description: 'The engine server, such as http://engines:3300.' },
+        key: { required: true, secret: true, description: `The engine server key, at least ${exports.MIN_KEY_LENGTH} characters.` },
+        engine: { description: 'The engine\'s name on the engine server. Default: the instance name.' },
+        timeout: { type: 'number', default: 10000, description: 'Milliseconds for each attempt to describe the engine at startup.' },
+    },
+    async create({ name, settings, options, config }) {
+        let url;
+        try {
+            url = new URL(settings.url);
+        }
+        catch {
+            throw new uag_sdk_1.EngineConfigError(`The "${name}" engine's url setting is not a URL: ${JSON.stringify(settings.url)}.`);
+        }
+        if (!['http:', 'https:'].includes(url.protocol)) {
+            throw new uag_sdk_1.EngineConfigError(`The "${name}" engine's url setting must be an http or https URL.`);
+        }
+        if (url.username || url.password) {
+            throw new uag_sdk_1.EngineConfigError(`The "${name}" engine's url setting must not include a user name or password: its key setting authenticates the UAG to the engine server.`);
+        }
+        if (String(settings.key).length < exports.MIN_KEY_LENGTH) {
+            throw new uag_sdk_1.EngineConfigError(`The "${name}" engine's key setting must be at least ${exports.MIN_KEY_LENGTH} characters, the same key as the engine server's UAG_ENGINE_SERVER_KEY.`);
+        }
+        const connection = {
+            name,
+            baseUrl: url.href.replace(/\/+$/, ''),
+            key: settings.key,
+            fetch: options.fetch || fetch,
+        };
+        const remoteName = settings.engine || name;
+        const described = await describeRemote(connection, remoteName, {
+            retries: config.retries,
+            retryDelay: config.retryDelay,
+            timeout: settings.timeout,
+        });
+        debug(`"${name}" is the ${described.kind} engine "${remoteName}" (${described.model}) at ${connection.baseUrl}.`);
+        return remoteEngine(connection, remoteName, described);
+    },
+});

package/lib/agent/requestId.d.ts

@@ -0,0 +1,4 @@
+/** Run `fn` as part of the request `requestId`. */
+export declare function withRequestId<T>(requestId: string | undefined, fn: () => T): T;
+/** The id of the request being served, if any. */
+export declare function currentRequestId(): string | undefined;

package/lib/agent/requestId.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withRequestId = withRequestId;
+exports.currentRequestId = currentRequestId;
+const async_hooks_1 = require("async_hooks");
+/**
+ * The Agent API request an operation runs for, so the `remote` engine type can
+ * send its id to the engine server: the engine contract carries no request id,
+ * and Formflow calls engines within the operation's async context.
+ */
+const current = new async_hooks_1.AsyncLocalStorage();
+/** Run `fn` as part of the request `requestId`. */
+function withRequestId(requestId, fn) {
+    return current.run(requestId, fn);
+}
+/** The id of the request being served, if any. */
+function currentRequestId() {
+    return current.getStore();
+}

package/lib/agent/router.d.ts

@@ -0,0 +1,31 @@
+import { RequestHandler, Router } from "express";
+import type { UAGProjectInterface } from "../UAGProjectInterface";
+/** The largest request body an agent operation takes, in bytes. */
+export declare const AGENT_BODY_LIMIT: number;
+/**
+ * `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.
+ */
+export declare function AgentRouter(project: UAGProjectInterface, authenticate: RequestHandler): 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`.
+ */
+export declare function agentNotFound(project: UAGProjectInterface): RequestHandler;
+/**
+ * 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).
+ */
+export declare function agentCredentials(project: UAGProjectInterface): RequestHandler;
+/**
+ * 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.
+ */
+export declare function FormAgentRouter(project: UAGProjectInterface, credentials: RequestHandler): Router;

package/lib/agent/router.js

@@ -0,0 +1,295 @@
+"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.AgentRouter = AgentRouter;
+exports.agentNotFound = agentNotFound;
+exports.agentCredentials = agentCredentials;
+exports.FormAgentRouter = FormAgentRouter;
+const crypto_1 = require("crypto");
+const lodash_1 = require("lodash");
+const express_1 = __importStar(require("express"));
+const protocol_1 = require("@formio/uag-sdk/protocol");
+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. */
+function taskOf(req) {
+    const task = req.body?.task;
+    return typeof task === 'string' && 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, in bytes. */
+exports.AGENT_BODY_LIMIT = 5 * 1024 * 1024;
+/** 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 parse = express_1.default.json({ limit: exports.AGENT_BODY_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 > exports.AGENT_BODY_LIMIT) {
+            return res.status(413).json({ error: `The request body is larger than the agent operations' limit of ${exports.AGENT_BODY_LIMIT / (1024 * 1024)} MB.` });
+        }
+        next();
+    };
+    // Request id, after authentication: refused requests carry none. One that
+    // is not a short token is replaced, so it is never echoed, logged or sent on.
+    const requestId = (req, res, next) => {
+        req.requestId = (0, protocol_1.safeRequestId)(req.get('x-request-id')) || (0, crypto_1.randomUUID)();
+        res.set('X-Request-Id', req.requestId);
+        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 = err instanceof formflow_1.FormflowError ? err.status : 500;
+            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)));
+            }
+            const body = {
+                requestId: agentReq.requestId,
+                error: status === 500 ? 'The request failed. See the UAG logs for this request id.' : err.message,
+                ...(err instanceof formflow_1.FormflowError && err.code && { code: err.code }),
+                ...(err?.edition && { edition: err.edition })
+            };
+            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".` });
+    };
+}
+function refuse(res, detail) {
+    return res.status(401).json({ detail });
+}
+/**
+ * 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".`);
+        }
+        if (String(form.form?.properties?.uagChat) === 'false') {
+            throw new formflow_1.FormflowError(403, `Chat is turned off for the form "${form.formflowName}".`);
+        }
+        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,26 @@
+/**
+ * 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: string;
+    kinds: "decision"[];
+    apiVersion: 1;
+    description: string;
+    create: ({ name }: import("@formio/uag-sdk").EngineCreateContext<any>) => import("@formio/appserver-core/lib/formflow").DecisionEngine & {
+        calls: number;
+    };
+}>;
+export declare const StubAgentEngine: Readonly<{
+    type: 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;
+    };
+}>;