@formio/uag 1.13.2 → 2.0.0-rc.10

package/lib/agent/chat.js

@@ -0,0 +1,475 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CHAT_INSTRUCTIONS = exports.CHAT_DEFAULTS = exports.CONFIRMED = exports.REPLY = void 0;
+exports.chatSettings = chatSettings;
+exports.readChatRequest = readChatRequest;
+exports.trimTranscript = trimTranscript;
+exports.transcriptText = transcriptText;
+exports.chatValueSchema = chatValueSchema;
+exports.remainingOf = remainingOf;
+exports.chatEngines = chatEngines;
+exports.chatTurn = chatTurn;
+const lodash_1 = require("lodash");
+const formflow_1 = require("../formflow");
+Object.defineProperty(exports, "CHAT_INSTRUCTIONS", { enumerable: true, get: function () { return formflow_1.CHAT_INSTRUCTIONS; } });
+const debug = require('debug')('formio:uag:agent');
+/**
+ * The two values of a turn that are not form fields. A Form.io key cannot
+ * start with `-`, so no field's path can be either, and model APIs that limit
+ * property names to letters, digits, `_`, `.` and `-` accept them.
+ */
+exports.REPLY = formflow_1.CHAT_REPLY;
+exports.CONFIRMED = formflow_1.CHAT_CONFIRMED;
+exports.CHAT_DEFAULTS = {
+    engines: ['agent'],
+    maxIterations: 3,
+    maxMessages: 40,
+    maxMessageLength: 2000,
+    maxTranscriptChars: 24000,
+};
+function positive(value, fallback) {
+    const number = Number(value);
+    return Number.isFinite(number) && number > 0 ? Math.floor(number) : fallback;
+}
+/** The chat settings in force (`agentApi.chat`), with their defaults. */
+function chatSettings(project) {
+    const configured = project.formflowConfig()?.agentApi?.chat || {};
+    const engines = Array.isArray(configured.engines) && configured.engines.length ? configured.engines.map(String) : exports.CHAT_DEFAULTS.engines;
+    return {
+        engines,
+        maxIterations: positive(configured.maxIterations, exports.CHAT_DEFAULTS.maxIterations),
+        maxMessages: positive(configured.maxMessages, exports.CHAT_DEFAULTS.maxMessages),
+        maxMessageLength: positive(configured.maxMessageLength, exports.CHAT_DEFAULTS.maxMessageLength),
+        maxTranscriptChars: positive(configured.maxTranscriptChars, exports.CHAT_DEFAULTS.maxTranscriptChars),
+        ...(configured.timeout !== undefined && { timeout: positive(configured.timeout, 0) || undefined }),
+    };
+}
+/** Read and check a turn's body, or throw a 400. Nothing is called before this passes. */
+function readChatRequest(body, settings) {
+    const messages = body?.messages;
+    if (!Array.isArray(messages) || !messages.length) {
+        throw new formflow_1.FormflowError(400, 'Send the conversation as "messages": a list of { role, content }, ending with the person\'s message.');
+    }
+    if (messages.length > settings.maxMessages) {
+        throw new formflow_1.FormflowError(400, `A conversation may carry at most ${settings.maxMessages} messages. Start a new one.`);
+    }
+    for (const message of messages) {
+        if (!message || (message.role !== 'user' && message.role !== 'assistant') || typeof message.content !== 'string') {
+            throw new formflow_1.FormflowError(400, 'Each message must be { "role": "user" | "assistant", "content": "<text>" }.');
+        }
+        if (message.content.length > settings.maxMessageLength) {
+            throw new formflow_1.FormflowError(400, `Messages are limited to ${settings.maxMessageLength} characters.`);
+        }
+    }
+    if (messages[messages.length - 1].role !== 'user') {
+        throw new formflow_1.FormflowError(400, 'The last message must be the person\'s ("role": "user").');
+    }
+    const data = body?.data;
+    if (data !== undefined && data !== null && (typeof data !== 'object' || Array.isArray(data))) {
+        throw new formflow_1.FormflowError(400, '"data" must be an object: the form\'s current data.');
+    }
+    const locked = body?.locked;
+    if (locked !== undefined && (!Array.isArray(locked) || locked.length > 500 || !locked.every((path) => typeof path === 'string'))) {
+        throw new formflow_1.FormflowError(400, '"locked" must be a list of field paths: the fields the person set in the form.');
+    }
+    return {
+        messages: messages.map((message) => ({ role: message.role, content: message.content })),
+        data: (0, lodash_1.cloneDeep)(data || {}),
+        locked: locked || []
+    };
+}
+/**
+ * The newest messages that fit in `maxChars`, starting at one the person
+ * wrote. The newest message always stays, whatever its length.
+ */
+function trimTranscript(messages, maxChars) {
+    let start = messages.length - 1;
+    let total = messages[start].content.length;
+    while (start > 0 && total + messages[start - 1].content.length <= maxChars) {
+        start--;
+        total += messages[start].content.length;
+    }
+    while (start < messages.length - 1 && messages[start].role !== 'user')
+        start++;
+    return messages.slice(start);
+}
+function transcriptText(messages) {
+    return messages.map((message) => `${message.role === 'user' ? 'Person' : 'Assistant'}: ${message.content.trim()}`).join('\n\n');
+}
+/** The static options of a closed-set field, or none (free text, or options the chat does not know). */
+function staticOptions(field) {
+    const options = (field.options || []).filter((option) => !String(option.label || '').startsWith('**') && option.label !== '');
+    return options.length ? options : undefined;
+}
+/** The JSON schema of a field's value, for structured extraction. */
+function chatValueSchema(form, field) {
+    const component = form.getComponent(field.path) || {};
+    const options = staticOptions(field);
+    switch (component.type) {
+        case 'checkbox':
+            return { type: 'boolean' };
+        case 'number':
+        case 'currency':
+            return { type: 'number' };
+        case 'selectboxes':
+            return {
+                type: 'object',
+                properties: Object.fromEntries((options || []).map((option) => [String(option.value), { type: 'boolean' }])),
+                additionalProperties: false
+            };
+        case 'survey': {
+            const questions = (component.questions || []);
+            const values = (component.values || []);
+            return {
+                type: 'object',
+                properties: Object.fromEntries(questions.map((question) => [question.value, { enum: values.map((value) => value.value) }])),
+                additionalProperties: false
+            };
+        }
+        default:
+            if (options && component.multiple)
+                return { type: 'array', items: { enum: options.map((option) => option.value) } };
+            if (options)
+                return { enum: options.map((option) => option.value) };
+            return component.multiple || component.type === 'tags' ? { type: 'array', items: { type: 'string' } } : { type: 'string' };
+    }
+}
+function fieldSpec(form, field) {
+    const component = form.getComponent(field.path) || {};
+    const spec = {
+        path: field.path,
+        label: field.label,
+        type: field.type,
+        description: [field.required ? 'Required.' : 'Optional.', field.description, field.prompt && `Placeholder: ${field.prompt}`].filter(Boolean).join(' '),
+        // The host's rule, then the component's validation (lengths, pattern, range, mask), so a
+        // first answer is likely to pass the form's checks.
+        rule: (0, formflow_1.ruleWithConstraints)(field.rule, component),
+    };
+    if (field.format)
+        spec.format = field.format;
+    const options = staticOptions(field);
+    if (options)
+        spec.options = options;
+    if (component.multiple || component.type === 'selectboxes' || component.type === 'tags')
+        spec.multiple = true;
+    return spec;
+}
+/** The longest value, in characters, the engine is shown for one field. */
+const MAX_VALUE_CHARS = 500;
+/**
+ * A labeled line per value the chat collects, for the engine's context. Only
+ * the form's collectable fields, each value and the whole bounded: the request's
+ * data is the client's, and its size must not decide what an engine is sent.
+ */
+function collectedText(fields, data, maxChars) {
+    const lines = [];
+    let total = 0;
+    for (const field of fields) {
+        const value = (0, lodash_1.get)(data, field.path);
+        if (value === undefined || value === null || value === '')
+            continue;
+        let text = typeof value === 'string' ? value : JSON.stringify(value);
+        if (text.length > MAX_VALUE_CHARS)
+            text = `${text.slice(0, MAX_VALUE_CHARS)}…`;
+        const line = `- ${field.label}: ${text}`;
+        if (total + line.length > maxChars)
+            break;
+        lines.push(line);
+        total += line.length + 1;
+    }
+    return lines.length ? lines.join('\n') : '(nothing yet)';
+}
+function labels(fields) {
+    return fields.length ? fields.map((field) => `- ${field.label}`).join('\n') : '(none)';
+}
+/** What the form still needs, from its fields on the current data. */
+function remainingOf(fields) {
+    const brief = (field) => ({ path: field.path, label: field.label });
+    return {
+        required: fields.fields.filter((field) => field.required && field.empty).map(brief),
+        optional: fields.fields.filter((field) => !field.required && field.empty).map(brief),
+        unsupported: fields.unsupported
+    };
+}
+function isComplete(fields) {
+    return !fields.errors.length
+        && !fields.fields.some((field) => field.required && field.empty)
+        && !fields.unsupported.some((field) => field.required && field.empty);
+}
+/** A value as the form stores it: comma-separated multiple values and select boxes become arrays and maps. */
+function normalized(form, path, value) {
+    return (0, lodash_1.get)(form.convertToSubmission({ [path]: value }).data, path);
+}
+/**
+ * Check a value's shape against its field, which the engine's schema only
+ * asks for: options, numbers, booleans, and the keys of select boxes and
+ * surveys. Returns the value as the form stores it, or why it is refused.
+ */
+function checkValue(form, field, value) {
+    const component = form.getComponent(field.path) || {};
+    const options = staticOptions(field);
+    const optionValues = (options || []).map((option) => JSON.stringify(option.value));
+    const isOption = (item) => optionValues.includes(JSON.stringify(item));
+    const notOption = { error: `${field.label} must be one of: ${(options || []).map((option) => option.label).join(', ')}.` };
+    switch (component.type) {
+        case 'number':
+        case 'currency': {
+            const number = typeof value === 'number' ? value : (typeof value === 'string' && value.trim() !== '' ? Number(value) : NaN);
+            return Number.isFinite(number) ? { value: number } : { error: `${field.label} must be a number.` };
+        }
+        case 'checkbox':
+            if (typeof value === 'boolean')
+                return { value };
+            if (value === 'true' || value === 'false')
+                return { value: value === 'true' };
+            return { error: `${field.label} must be true or false.` };
+        case 'selectboxes':
+            if (!value || typeof value !== 'object' || Array.isArray(value))
+                return notOption;
+            if (!Object.keys(value).every((key) => optionValues.includes(JSON.stringify(key)) || (options || []).some((option) => String(option.value) === key)))
+                return notOption;
+            return { value: Object.fromEntries(Object.entries(value).map(([key, checked]) => [key, checked === true || checked === 'true'])) };
+        case 'survey': {
+            const questions = new Set((component.questions || []).map((question) => String(question.value)));
+            const answers = (component.values || []).map((answer) => JSON.stringify(answer.value));
+            if (!value || typeof value !== 'object' || Array.isArray(value)
+                || !Object.entries(value).every(([key, answer]) => questions.has(key) && answers.includes(JSON.stringify(answer)))) {
+                return { error: `${field.label} must answer its questions with one of their options.` };
+            }
+            return { value };
+        }
+        default:
+            if (options && !(Array.isArray(value) ? value : [value]).every(isOption))
+                return notOption;
+            return { value };
+    }
+}
+/**
+ * Merge an engine's values into the data and validate them with the form: a
+ * value the form rejects is put back as it was and reported `invalid`.
+ */
+async function applyValues(form, auth, data, collectable, values) {
+    const byPath = new Map(collectable.map((field) => [field.path, field]));
+    const merged = (0, lodash_1.cloneDeep)(data);
+    const fields = {};
+    const rejected = [];
+    const changed = [];
+    for (const [path, raw] of Object.entries(values || {})) {
+        const field = byPath.get(path);
+        if (!field || raw === undefined || raw === null)
+            continue;
+        const checked = checkValue(form, field, normalized(form, path, raw));
+        if ('error' in checked) {
+            const result = { path, label: field.label, status: 'invalid', value: raw, error: checked.error };
+            fields[path] = result;
+            rejected.push(result);
+            continue;
+        }
+        if ((0, lodash_1.isEqual)(checked.value, (0, lodash_1.get)(data, path)))
+            continue;
+        (0, lodash_1.set)(merged, path, checked.value);
+        changed.push(path);
+    }
+    // The form's processors change the data they are given (defaults, cleared
+    // hidden values): they read a copy, so the values sent back are the engine's.
+    let current = await form.chatFields({ data: (0, lodash_1.cloneDeep)(merged) }, auth);
+    const invalid = changed.filter((path) => current.errors.some((error) => error.path === path));
+    for (const path of invalid) {
+        const field = byPath.get(path);
+        const error = current.errors.find((item) => item.path === path);
+        const result = { path, label: field.label, status: 'invalid', value: (0, lodash_1.get)(merged, path), error: error.error };
+        fields[path] = result;
+        rejected.push(result);
+        const before = (0, lodash_1.get)(data, path);
+        if (before === undefined)
+            (0, lodash_1.unset)(merged, path);
+        else
+            (0, lodash_1.set)(merged, path, (0, lodash_1.cloneDeep)(before));
+    }
+    if (invalid.length)
+        current = await form.chatFields({ data: (0, lodash_1.cloneDeep)(merged) }, auth);
+    const patch = {};
+    for (const path of changed.filter((item) => !invalid.includes(item))) {
+        const field = byPath.get(path);
+        patch[path] = (0, lodash_1.get)(merged, path);
+        fields[path] = { path, label: field.label, status: 'suggested', value: patch[path] };
+    }
+    return { data: merged, patch, fields, rejected, current };
+}
+/** The validation tool an in-process engine may call before answering. */
+function checkTool(form, auth, data, collectable) {
+    const definition = formflow_1.CHAT_CHECK_TOOL;
+    const call = async (name, args) => {
+        if (name !== definition.name) {
+            return { content: [{ type: 'text', text: `The tool "${name}" is not available.` }], isError: true };
+        }
+        const values = args?.values && typeof args.values === 'object' && !Array.isArray(args.values) ? args.values : {};
+        const applied = await applyValues(form, auth, data, collectable, values);
+        const remaining = remainingOf(applied.current);
+        const lines = applied.rejected.length
+            ? ['Not accepted:', ...applied.rejected.map((result) => `- ${result.label}: ${result.error}`)]
+            : ['Every value is accepted.'];
+        lines.push('', 'Still needed after these values:', labels(remaining.required));
+        return { content: [{ type: 'text', text: lines.join('\n') }] };
+    };
+    return { definition, call };
+}
+/** Run one engine call with a timeout; the signal is aborted when it passes. */
+async function withTimeout(ms, call) {
+    const controller = new AbortController();
+    if (!ms)
+        return call(controller.signal);
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            controller.abort();
+            reject(new Error(`timed out after ${ms} ms`));
+        }, ms);
+    });
+    try {
+        return await Promise.race([call(controller.signal), timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** The agent engines that may serve chat, in order. */
+function chatEngines(project, settings = chatSettings(project)) {
+    return (0, formflow_1.formflow)(project).policy.expand(settings.engines).filter((engine) => engine.kind === 'agent');
+}
+/**
+ * Run one turn of a form's chat. The caller has already been authenticated,
+ * and checked for create access to the form.
+ */
+async function chatTurn(project, form, body, context) {
+    const settings = chatSettings(project);
+    const request = readChatRequest(body, settings);
+    const engines = chatEngines(project, settings);
+    if (!engines.length) {
+        throw new formflow_1.FormflowError(503, 'No enabled engine can serve chat. Enable an agent engine with UAG_ENGINES.', 'no_engine');
+    }
+    const service = (0, formflow_1.formflow)(project);
+    const before = await form.chatFields({ data: (0, lodash_1.cloneDeep)(request.data) }, context.auth);
+    // What the person set in the form itself stays theirs: shown to the engine, never asked for.
+    const locked = new Set(request.locked);
+    const collectable = before.fields.filter((field) => !locked.has(field.path));
+    const wasComplete = isComplete(before);
+    const remainingBefore = remainingOf(before);
+    // Agentic Formflow builds the engine's request from these.
+    const conversation = transcriptText(trimTranscript(request.messages, settings.maxTranscriptChars));
+    const contextNow = {
+        'Collected so far': collectedText(before.fields, request.data, settings.maxTranscriptChars),
+        'Still needed': labels(remainingBefore.required),
+        'Optional, not yet answered': labels(remainingBefore.optional),
+        ...(remainingBefore.unsupported.some((field) => field.empty) && {
+            'Finished in the form, not in this chat': labels(remainingBefore.unsupported.filter((field) => field.empty))
+        })
+    };
+    const fields = collectable.map((field) => ({ spec: fieldSpec(form, field), schema: chatValueSchema(form, field) }));
+    const failed = [];
+    let limited = 0;
+    let retryAfterMs = 0;
+    for (const engine of engines) {
+        const started = Date.now();
+        // Only engines in this process can call the tool back; remote ones would need /mcp.
+        const tools = engine.toolUse === true && project.formflowEngines().source(engine).type !== 'remote';
+        const check = tools ? checkTool(form, context.auth, request.data, collectable) : null;
+        let response;
+        try {
+            service.engineLimiter.take(engine.name);
+            response = await withTimeout(settings.timeout ?? service.policy.timeout(engine), (signal) => service.chatExtract(engine, {
+                form: form,
+                fields,
+                conversation,
+                context: contextNow,
+                ...(check && { checkValues: check.call, maxIterations: settings.maxIterations }),
+                signal
+            }));
+        }
+        catch (err) {
+            if (err instanceof formflow_1.RateLimitError) {
+                limited++;
+                retryAfterMs = retryAfterMs ? Math.min(retryAfterMs, err.retryAfterMs) : err.retryAfterMs;
+            }
+            failed.push(engine.name);
+            debug(`[${context.requestId}] chat engine ${engine.name} failed:`, err?.message || err);
+            continue;
+        }
+        const values = { ...(response.values || {}) };
+        let reply = typeof values[exports.REPLY] === 'string' ? values[exports.REPLY].trim() : '';
+        const saidConfirmed = values[exports.CONFIRMED] === true || values[exports.CONFIRMED] === 'true';
+        delete values[exports.REPLY];
+        delete values[exports.CONFIRMED];
+        const applied = await applyValues(form, context.auth, request.data, collectable, values);
+        const toolCalls = [...(response.toolCalls || [])];
+        const usage = { ...(response.usage || {}) };
+        const checked = toolCalls.some((call) => call.name === 'check_values');
+        if (applied.rejected.length && !checked) {
+            // The reply was written before the form rejected a value: ask for one that says so.
+            try {
+                service.engineLimiter.take(engine.name);
+                const corrected = await withTimeout(settings.timeout ?? service.policy.timeout(engine), (signal) => service.chatExtract(engine, {
+                    form: form,
+                    fields: [],
+                    conversation,
+                    context: {
+                        ...contextNow,
+                        'Collected so far': collectedText(before.fields, applied.data, settings.maxTranscriptChars),
+                        'Still needed': labels(remainingOf(applied.current).required),
+                        'Not accepted (ask again for these)': applied.rejected.map((result) => `- ${result.label}: ${result.error}`).join('\n')
+                    },
+                    signal
+                }));
+                const text = typeof corrected.values?.[exports.REPLY] === 'string' ? corrected.values[exports.REPLY].trim() : '';
+                if (text)
+                    reply = text;
+                if (corrected.usage) {
+                    usage.inputTokens = (usage.inputTokens || 0) + (corrected.usage.inputTokens || 0);
+                    usage.outputTokens = (usage.outputTokens || 0) + (corrected.usage.outputTokens || 0);
+                }
+            }
+            catch (err) {
+                debug(`[${context.requestId}] chat reply correction with ${engine.name} failed:`, err?.message || err);
+            }
+        }
+        const remaining = remainingOf(applied.current);
+        const complete = isComplete(applied.current);
+        if (!reply)
+            reply = fallbackReply(remaining, complete, applied.rejected);
+        // The client sends the reply back with the next turn, where messages are limited.
+        if (reply.length > settings.maxMessageLength)
+            reply = `${reply.slice(0, settings.maxMessageLength - 1).trimEnd()}…`;
+        return {
+            requestId: context.requestId,
+            reply,
+            patch: applied.patch,
+            data: applied.data,
+            fields: applied.fields,
+            errors: applied.current.errors,
+            remaining,
+            complete,
+            confirmed: saidConfirmed && wasComplete && complete && !Object.keys(applied.patch).length && !applied.rejected.length,
+            engine: {
+                name: engine.name,
+                model: response.model,
+                latencyMs: Date.now() - started,
+                toolCalls,
+                ...((usage.inputTokens !== undefined || usage.outputTokens !== undefined) && { usage })
+            }
+        };
+    }
+    if (limited === engines.length) {
+        throw new formflow_1.RateLimitError('Every engine that could answer this chat is over its rate limit. Try again shortly.', retryAfterMs);
+    }
+    // Engine errors can carry provider details: they go to the log, not the caller.
+    throw new formflow_1.FormflowError(502, `The chat could not be answered (engines tried: ${failed.join(', ')}). See the UAG logs for this request id.`);
+}
+/** A reply for when the engine wrote none. */
+function fallbackReply(remaining, complete, rejected) {
+    if (rejected.length)
+        return `${rejected[0].error} Could you give it again?`;
+    if (complete)
+        return 'Thanks, that is everything needed. Please review your answers and confirm to submit them.';
+    const next = remaining.required[0] || remaining.unsupported.find((field) => field.required && field.empty);
+    return next ? `Thanks. Next, please tell me: ${next.label}.` : 'Thanks. Is there anything else you would like to add?';
+}

package/lib/agent/engines.d.ts

@@ -0,0 +1,17 @@
+import type { EngineTypeDefinition } from '@formio/uag-sdk';
+import { EngineRegistry } from '../formflow';
+/** The UAG's own installation, where engine packages are looked up first. */
+export declare const UAG_ROOT: string;
+/** Engine types every UAG has, whatever is installed. */
+export declare const BUILT_IN_ENGINES: Record<string, EngineTypeDefinition>;
+/** What is known of each loaded engine type, by type name: for listing it as a plugin. */
+export type LoadedEngineType = {
+    name: string;
+    title: string;
+    version?: string;
+    kinds: ('decision' | 'agent')[];
+    instances: string[];
+};
+/** The engine types a registry's instances were created from, in order of first use. */
+export declare function engineTypesOf(registry: EngineRegistry | undefined): LoadedEngineType[];
+export declare function loadUAGEngines(config?: Record<string, any>, env?: Record<string, string | undefined>): Promise<EngineRegistry>;

package/lib/agent/engines.js

@@ -0,0 +1,46 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUILT_IN_ENGINES = exports.UAG_ROOT = void 0;
+exports.engineTypesOf = engineTypesOf;
+exports.loadUAGEngines = loadUAGEngines;
+const path_1 = __importDefault(require("path"));
+const uag_sdk_1 = require("@formio/uag-sdk");
+const loader_1 = require("@formio/uag-sdk/loader");
+const appserver_1 = require("@formio/appserver");
+const remote_1 = require("./remote");
+const stubs_1 = require("./stubs");
+/** The UAG's own installation, where engine packages are looked up first. */
+exports.UAG_ROOT = path_1.default.resolve(__dirname, '..', '..');
+/** Engine types every UAG has, whatever is installed. */
+exports.BUILT_IN_ENGINES = {
+    remote: remote_1.RemoteEngine,
+    'stub-decision': stubs_1.StubDecisionEngine,
+    'stub-agent': stubs_1.StubAgentEngine,
+};
+const loadedTypes = new WeakMap();
+/** The engine types a registry's instances were created from, in order of first use. */
+function engineTypesOf(registry) {
+    return (registry && loadedTypes.get(registry)) || [];
+}
+async function loadUAGEngines(config = {}, env = process.env) {
+    const loaded = (0, loader_1.planEngines)((0, uag_sdk_1.engineInstances)(config, env), {
+        types: { ...exports.BUILT_IN_ENGINES, ...(config.engineTypes || {}) },
+        paths: (0, loader_1.enginePaths)(exports.UAG_ROOT, env),
+        env,
+        config,
+        apiVersion: appserver_1.Formflow.ENGINE_API_VERSION,
+    });
+    // Agentic Formflow creates the engines from the plans.
+    const registry = await appserver_1.Formflow.startEngines(loaded);
+    const types = new Map();
+    for (const entry of loaded) {
+        const type = types.get(entry.type) || { name: entry.type, title: entry.title || entry.type, version: entry.typeVersion || entry.version, kinds: entry.kinds, instances: [] };
+        type.instances.push(entry.name);
+        types.set(entry.type, type);
+    }
+    loadedTypes.set(registry, [...types.values()]);
+    return registry;
+}

package/lib/agent/errors.d.ts

@@ -0,0 +1,25 @@
+import { Request, RequestHandler, Response } from "express";
+export declare function isAgentApiRequest(req: Request): boolean;
+/** The code for a status, when the error names none. */
+export declare function errorCode(status: number): string;
+export declare const 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.
+ */
+export declare function agentError(requestId: string, err: any): {
+    status: number;
+    body: Record<string, any>;
+};
+/** The request's id, assigned once: the caller's, when it is a short token, or a new one. */
+export declare function requestIdOf(req: Request, res: Response): string;
+/** The error body for a status and whatever a handler sent: an object, JSON text, plain text or nothing. */
+export declare function errorBody(requestId: string, status: number, sent: unknown): Record<string, any>;
+/**
+ * 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.
+ */
+export declare function agentErrorShape(): RequestHandler;