@formio/uag 1.13.2 → 2.0.0-rc.10

package/lib/agent/errors.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INTERNAL_ERROR = void 0;
+exports.isAgentApiRequest = isAgentApiRequest;
+exports.errorCode = errorCode;
+exports.agentError = agentError;
+exports.requestIdOf = requestIdOf;
+exports.errorBody = errorBody;
+exports.agentErrorShape = agentErrorShape;
+const crypto_1 = require("crypto");
+const protocol_1 = require("@formio/uag-sdk/protocol");
+const formflow_1 = require("../formflow");
+/**
+ * The Agent API's one error shape. Every error a form's agent operation or
+ * `/agent/capabilities` answers is JSON
+ *
+ *     { "requestId": "...", "error": "a message for people", "code": "a_stable_code", ... }
+ *
+ * with the same id in `X-Request-Id`, whatever refused it: the UAG, the
+ * project's authentication, the portal's team access, the body parser.
+ * Clients branch on `code`; `error` is for people. A 500 never carries details:
+ * those are in the UAG's log under the request id.
+ */
+/** A form's agent operations, and the capabilities. */
+const OPERATION = /\/agent\/(extract|decide|generate|chat)\/?$/i;
+const CAPABILITIES = /^\/agent\/capabilities\/?$/i;
+function isAgentApiRequest(req) {
+    return (req.method === 'POST' && OPERATION.test(req.path)) || (req.method === 'GET' && CAPABILITIES.test(req.path));
+}
+/** The code for a status, when the error names none. */
+function errorCode(status) {
+    switch (status) {
+        case 400: return 'invalid_request';
+        case 401: return 'unauthorized';
+        case 403: return 'forbidden';
+        case 404: return 'not_found';
+        case 409: return 'conflict';
+        case 413: return 'payload_too_large';
+        case 429: return 'rate_limited';
+        case 502: return 'engines_failed';
+        case 503: return 'unavailable';
+        case 504: return 'timeout';
+        default: return status >= 500 ? 'internal_error' : 'invalid_request';
+    }
+}
+exports.INTERNAL_ERROR = 'The request failed. See the UAG logs for this request id.';
+/**
+ * An error as the Agent API answers it: its status, and the body. Errors with
+ * a status (FormflowError) keep their message and code; anything else is a 500
+ * with no detail. Agent operations and module routes share it.
+ */
+function agentError(requestId, err) {
+    const known = err instanceof formflow_1.FormflowError;
+    const status = known ? err.status : 500;
+    return {
+        status,
+        body: {
+            requestId,
+            error: status === 500 ? exports.INTERNAL_ERROR : String(err?.message || exports.INTERNAL_ERROR),
+            code: (known && err.code) || errorCode(status),
+            ...(err?.edition && { edition: err.edition })
+        }
+    };
+}
+/** The request's id, assigned once: the caller's, when it is a short token, or a new one. */
+function requestIdOf(req, res) {
+    const request = req;
+    if (!request.requestId) {
+        request.requestId = (0, protocol_1.safeRequestId)(req.get('x-request-id')) || (0, crypto_1.randomUUID)();
+    }
+    if (!res.headersSent)
+        res.set('X-Request-Id', request.requestId);
+    return request.requestId;
+}
+/** The error body for a status and whatever a handler sent: an object, JSON text, plain text or nothing. */
+function errorBody(requestId, status, sent) {
+    let value = sent;
+    if (Buffer.isBuffer(value))
+        value = value.toString('utf8');
+    if (typeof value === 'string') {
+        try {
+            value = JSON.parse(value);
+        }
+        catch {
+            value = { error: value };
+        }
+    }
+    const given = value && typeof value === 'object' ? value : {};
+    const text = [given.error, given.detail, given.message].find((part) => typeof part === 'string' && part.trim());
+    // A 500's own message may carry internals: only the UAG's fixed sentence goes out.
+    const error = status >= 500 && status !== 502 && status !== 503 && status !== 504 ? exports.INTERNAL_ERROR : (text || defaultMessage(status));
+    return {
+        requestId,
+        error,
+        code: typeof given.code === 'string' && given.code ? given.code : errorCode(status),
+        ...(typeof given.edition === 'string' && { edition: given.edition })
+    };
+}
+function defaultMessage(status) {
+    switch (status) {
+        case 401: return 'Unauthorized.';
+        case 403: return 'Forbidden.';
+        case 404: return 'Not found.';
+        case 413: return 'The request body is too large.';
+        case 429: return 'Too many requests. Try again shortly.';
+        default: return 'The request could not be completed.';
+    }
+}
+/**
+ * Mounted ahead of every route: for an Agent API request, assigns the request
+ * id and rewrites any error response into the one shape, so refusals from
+ * middleware the UAG does not own (the project's authentication answers plain
+ * text, the portal's team access an empty 401) look like every other.
+ */
+function agentErrorShape() {
+    return (req, res, next) => {
+        if (!isAgentApiRequest(req))
+            return next();
+        const requestId = requestIdOf(req, res);
+        const send = res.send.bind(res);
+        let shaped = false;
+        res.send = ((body) => {
+            // An event stream writes its own error events; only whole responses are shaped.
+            if (shaped || res.statusCode < 400)
+                return send(body);
+            shaped = true;
+            res.type('application/json');
+            return send(JSON.stringify(errorBody(requestId, res.statusCode, body)));
+        });
+        next();
+    };
+}

package/lib/agent/index.d.ts

@@ -0,0 +1,4 @@
+export { StubAgentEngine, StubDecisionEngine, stubGenerateRequests } from './stubs';
+export { BUILT_IN_ENGINES, UAG_ROOT, loadUAGEngines } from './engines';
+export { AgentRouter, FormAgentRouter, agentCredentials, agentNotFound } from './router';
+export { RemoteEngine, MIN_KEY_LENGTH } from './remote';

package/lib/agent/index.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIN_KEY_LENGTH = exports.RemoteEngine = exports.agentNotFound = exports.agentCredentials = exports.FormAgentRouter = exports.AgentRouter = exports.loadUAGEngines = exports.UAG_ROOT = exports.BUILT_IN_ENGINES = exports.stubGenerateRequests = exports.StubDecisionEngine = exports.StubAgentEngine = void 0;
+var stubs_1 = require("./stubs");
+Object.defineProperty(exports, "StubAgentEngine", { enumerable: true, get: function () { return stubs_1.StubAgentEngine; } });
+Object.defineProperty(exports, "StubDecisionEngine", { enumerable: true, get: function () { return stubs_1.StubDecisionEngine; } });
+Object.defineProperty(exports, "stubGenerateRequests", { enumerable: true, get: function () { return stubs_1.stubGenerateRequests; } });
+var engines_1 = require("./engines");
+Object.defineProperty(exports, "BUILT_IN_ENGINES", { enumerable: true, get: function () { return engines_1.BUILT_IN_ENGINES; } });
+Object.defineProperty(exports, "UAG_ROOT", { enumerable: true, get: function () { return engines_1.UAG_ROOT; } });
+Object.defineProperty(exports, "loadUAGEngines", { enumerable: true, get: function () { return engines_1.loadUAGEngines; } });
+var router_1 = require("./router");
+Object.defineProperty(exports, "AgentRouter", { enumerable: true, get: function () { return router_1.AgentRouter; } });
+Object.defineProperty(exports, "FormAgentRouter", { enumerable: true, get: function () { return router_1.FormAgentRouter; } });
+Object.defineProperty(exports, "agentCredentials", { enumerable: true, get: function () { return router_1.agentCredentials; } });
+Object.defineProperty(exports, "agentNotFound", { enumerable: true, get: function () { return router_1.agentNotFound; } });
+var remote_1 = require("./remote");
+Object.defineProperty(exports, "RemoteEngine", { enumerable: true, get: function () { return remote_1.RemoteEngine; } });
+Object.defineProperty(exports, "MIN_KEY_LENGTH", { enumerable: true, get: function () { return remote_1.MIN_KEY_LENGTH; } });

package/lib/agent/remote.d.ts

@@ -0,0 +1,71 @@
+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;
+    /** The most PDF bytes one generate request may send: documents.maxTotalBytes. */
+    maxDocumentBytes: number;
+};
+/**
+ * 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: "engine";
+    name: string;
+    title: 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,252 @@
+"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 };
+            },
+        };
+    }
+    const agent = {
+        name: connection.name,
+        kind: 'agent',
+        apiVersion: uag_sdk_1.ENGINE_API_VERSION,
+        model: described.model,
+        toolUse: described.toolUse === true,
+        accepts: described.accepts || ['text'],
+        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 };
+        },
+    };
+    if (described.generate) {
+        agent.generate = async (request) => {
+            // Refused before anything is sent; the documents are never logged.
+            if ((0, protocol_1.pdfByteLength)(request.attachments) > connection.maxDocumentBytes) {
+                throw new uag_sdk_1.EngineError(`The attached PDFs exceed ${connection.maxDocumentBytes} bytes, the most one request to the engine server may carry.`);
+            }
+            const body = {
+                instructions: request.instructions,
+                ...(request.system !== undefined && { system: request.system }),
+                attachments: (0, protocol_1.encodeAttachments)(request.attachments),
+                format: request.format,
+                ...(request.maxTokens !== undefined && { maxTokens: request.maxTokens }),
+            };
+            const response = valid(protocol_1.checkGenerateResponse, await call(connection, `${path}/generate`, body, request.signal));
+            request.onProgress?.(response.text.length);
+            return { ...response, model: response.model || described.model };
+        };
+    }
+    return agent;
+}
+exports.RemoteEngine = (0, uag_sdk_1.defineEngine)({
+    type: 'engine',
+    name: 'remote',
+    title: 'Remote engine (engine server)',
+    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,
+            maxDocumentBytes: Math.min(Number(config?.documents?.maxTotalBytes) || protocol_1.MAX_DOCUMENT_BYTES, protocol_1.MAX_DOCUMENT_BYTES),
+        };
+        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,61 @@
+import { NextFunction, Request, RequestHandler, Response, Router } from "express";
+import { SubmissionRequest } from "@formio/appserver";
+import { FormflowService } from "../formflow";
+import type { UAGProjectInterface } from "../UAGProjectInterface";
+/**
+ * The Agent API: HTTP adapters onto Agentic Formflow in @formio/appserver-core.
+ * Each endpoint reads its request, calls the service, and writes JSON (or, for
+ * extract, a Server-Sent Events stream). Errors answer with the status the
+ * service gives.
+ *
+ * The operations belong to a form, `{form}/agent/{operation}`, as its
+ * submissions do: the form comes from the URL and the caller from the
+ * project's own authentication. Capabilities describe the deployment, at
+ * `/agent/capabilities`.
+ */
+type AgentRequest = SubmissionRequest & {
+    requestId: string;
+};
+/** The largest request body an agent operation takes by default, in bytes. */
+export declare const AGENT_BODY_LIMIT: number;
+/**
+ * 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.
+ */
+export declare function agentBodyLimit(project: UAGProjectInterface): number;
+type Handler = (req: AgentRequest, res: Response, service: FormflowService) => Promise<void>;
+/** The parts every Agent API endpoint shares: the request id, and errors answered as JSON (or as an event mid-stream). */
+export declare function agentEndpoints(project: UAGProjectInterface): {
+    json: (req: Request, res: Response, next: NextFunction) => void | Response<any, Record<string, any>>;
+    requestId: (req: any, res: Response, next: NextFunction) => void;
+    handle: (operation: string, fn: Handler) => (req: Request, res: Response) => Promise<void>;
+};
+/**
+ * `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;
+export {};