@formio/uag-engines 0.0.0-stage → 2.0.0-rc.1

package/LICENSE.txt

@@ -0,0 +1,19 @@
+The MIT License (MIT)
+Copyright (c) 2025 Form.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in the
+Software without restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,83 @@
-# Temporary Holding Version
+# @formio/uag-engines
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<sub>[Form.io UAG](https://github.com/formio/uag/blob/main/README.md) &rsaquo; [Engines](https://github.com/formio/uag/blob/main/README.md#engines-and-routing) &rsaquo; this page</sub>
+
+Runs engine packages for the Form.io UAG in their own process, behind the remote engine protocol. The UAG reaches them with its built-in `remote` engine type. Model API keys and model traffic then stay in this container, and the UAG holds no model credential. Any engine package works here, unchanged.
+
+The engine server holds no Form.io credential. The UAG never sends it one: every request carries only the engine server key. For research, the UAG adds a short-lived scoped token, and the engine server uses it to call the UAG's `/mcp`. The token allows only the task's read-only tools, with the caller's identity.
+
+## Run it
+
+The `formio/uag-engines` image includes the official engines: `jev`, `claude`, `openai`, `grok` and `gemini`.
+
+```yaml
+services:
+  formio-uag:
+    image: formio/uag:2
+    environment:
+      UAG_ENGINES: jev:remote,claude:remote
+      UAG_ENGINE_JEV_URL: http://uag-engines:3300
+      UAG_ENGINE_JEV_KEY: ${UAG_ENGINE_SERVER_KEY}
+      UAG_ENGINE_CLAUDE_URL: http://uag-engines:3300
+      UAG_ENGINE_CLAUDE_KEY: ${UAG_ENGINE_SERVER_KEY}
+      JWT_SECRET: ${JWT_SECRET}            # signs the scoped tokens for research
+      # ... PROJECT, keys and the rest of the UAG's settings
+    depends_on:
+      uag-engines:
+        condition: service_healthy
+
+  uag-engines:
+    image: formio/uag-engines:2
+    environment:
+      UAG_ENGINES: jev,claude
+      TYPESAFE_API_KEY: ${TYPESAFE_API_KEY}
+      CLAUDE_API_KEY: ${CLAUDE_API_KEY}
+      UAG_ENGINE_SERVER_KEY: ${UAG_ENGINE_SERVER_KEY}
+      UAG_SERVER: http://formio-uag:3200   # where research calls /mcp
+    # No published port: only the UAG, on the same private network, reaches it.
+```
+
+On the UAG, `<name>:remote` is an instance hosted here; by default it uses the engine of the same name on the engine server (`UAG_ENGINE_<NAME>_ENGINE` names another). Any mix works: `UAG_ENGINES=jev,claude:remote` keeps `jev` in the UAG, with its key there, and moves only Claude.
+
+Without Docker: `npm install @formio/uag-engines @formio/uag-claude`, then run `npx uag-engines` with the same variables.
+
+## Settings
+
+| Variable | Meaning | Default |
+|---|---|---|
+| `UAG_ENGINE_SERVER_KEY` | **Required.** The key every request must carry, at least 32 characters. The UAG's `remote` instances send it as `UAG_ENGINE_<NAME>_KEY`. | |
+| `UAG_ENGINES` | The engine instances to host, as on the UAG: `jev,fast:claude,local:openai`. | |
+| `UAG_ENGINE_<NAME>_<SETTING>` and each engine's own variables | Each instance's settings, resolved as on the UAG. See each engine's README. | |
+| `UAG_SERVER` | The UAG's URL, for research. Research calls go to `${UAG_SERVER}/mcp`, never to a URL taken from a request. Without it, research extracts are refused. | |
+| `UAG_ENGINE_PATH` | Absolute directories with more engine packages installed, such as a mounted volume. | |
+| `PORT`, `HOST` | Where it listens. The `formio/uag-engines` image sets `HOST=0.0.0.0`. | `3300`, `127.0.0.1` |
+| `SHUTDOWN_TIMEOUT` | On SIGTERM or SIGINT, how long to let requests in flight finish before exiting, in milliseconds. | `10000` |
+| `DEBUG` | `formio:uag:engine-server` also logs each engine failure's stack. Without it, each failure is one line on stderr: the request id, the route, and the error's name, status and message, never the request. | |
+
+Engines are resolved as on the UAG: an instance named in `UAG_ENGINES` is looked up as `@formio/uag-<type>`, then `uag-engine-<type>`, from the `node_modules` of this package's installation and the directories above it, then from `<dir>/node_modules` of each directory in `UAG_ENGINE_PATH`; never from the working directory, `NODE_PATH` or Node's global folders.
+
+## Security
+
+- Every route, including `/health`, needs `Authorization: Bearer <UAG_ENGINE_SERVER_KEY>`. The key is compared in constant time, before the request body is read.
+- Keep the engine server on a private network that only the UAG reaches, and do not publish its port. It warns at startup when it listens on a public address.
+- Research uses only the tools that the request asks for and the UAG's `/mcp` lists for the scoped token. Every call is recorded, and the calls this server made are what it reports back, whatever the engine says. No model can write: the token allows only read-only tools.
+- When the UAG abandons a request (its routing timeout), the engine is aborted, research stops (also while it is still connecting), and the MCP connection is closed.
+- Engine errors are passed on only when the engine marks them safe to show (`EngineError`); anything else is reported as "The engine failed". Every failure is logged here in one line, with the error's message: a provider SDK's message can name an account or a URL, so treat these logs as private.
+
+## Protocol
+
+`GET /health`, `GET /v1/engines`, `POST /v1/engines/:name/decide` and `POST /v1/engines/:name/extract`, all JSON, with `protocol: 1` in every body. See [`@formio/uag-sdk/protocol`](https://github.com/formio/uag/blob/main/packages/engine-sdk/protocol.js) for the shapes.
+
+Decide and extract calls may carry the Agent API request's `X-Request-Id`. The engine server sends it on with every research request to the UAG's `/mcp` and puts it in its logs, so a logging proxy can group every leg of a run. Only a short token (up to 128 letters, digits, `.`, `_`, `:` or `-`) is passed on; the header is optional either way, and the protocol version is unchanged.
+
+## Building the image
+
+From the repository root:
+
+```
+docker build -f packages/engine-server/Dockerfile -t formio/uag-engines .
+```
+
+To add an engine package, either derive an image (the image runs as `node`, so switch to `USER root` for `RUN npm install --prefix /engines uag-engine-acme`, then back to `USER node`, with `ENV UAG_ENGINE_PATH=/engines`), or mount a directory that contains `node_modules/uag-engine-acme` and list it in `UAG_ENGINE_PATH`.
+
+License: MIT.

package/bin/uag-engines.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+/**
+ * uag-engines: host engine packages for the Form.io UAG behind the remote
+ * engine protocol.
+ *
+ *   UAG_ENGINES=claude CLAUDE_API_KEY=... UAG_ENGINE_SERVER_KEY=... \
+ *   UAG_SERVER=http://formio-uag:3200 uag-engines
+ *
+ * PORT (default 3300) and HOST (default 127.0.0.1; the Docker image sets
+ * 0.0.0.0) choose where it listens. SIGTERM and SIGINT stop it once the
+ * requests in flight finish, or after SHUTDOWN_TIMEOUT milliseconds (10000).
+ */
+const { createEngineServer } = require('..');
+const { publicAddresses } = require('../network');
+
+async function main() {
+    const { app, engines, uagServer } = await createEngineServer();
+    const port = Number(process.env.PORT || 3300);
+    const host = process.env.HOST || '127.0.0.1';
+    const server = await new Promise((resolve, reject) => {
+        const listening = app.listen(port, host, () => resolve(listening));
+        listening.on('error', reject);
+    });
+    stopOnSignals(server);
+    console.log(`[uag-engines] Serving ${engines.map(({ engine }) => `${engine.name} (${engine.kind}, ${engine.model})`).join(', ')} on ${host}:${port}.`);
+    if (!uagServer) {
+        console.log('[uag-engines] UAG_SERVER is not set: research extracts are refused.');
+    }
+    const exposed = publicAddresses(host);
+    if (exposed.length) {
+        console.warn(`[uag-engines] Warning: listening on public address(es) ${exposed.join(', ')}. Keep the engine server on a private network that only the UAG can reach.`);
+    }
+}
+
+/** Stop accepting requests on SIGTERM or SIGINT, and exit when those in flight finish. */
+function stopOnSignals(server) {
+    let stopping = false;
+    const stop = (signal) => {
+        if (stopping) process.exit(1);
+        stopping = true;
+        console.log(`[uag-engines] ${signal}: finishing the requests in flight.`);
+        server.close(() => process.exit(0));
+        server.closeIdleConnections();
+        setTimeout(() => {
+            console.error('[uag-engines] Requests still in flight at the shutdown timeout; exiting.');
+            process.exit(1);
+        }, Number(process.env.SHUTDOWN_TIMEOUT || 10000)).unref();
+    };
+    process.on('SIGTERM', stop);
+    process.on('SIGINT', stop);
+}
+
+main().catch((err) => {
+    console.error(`[uag-engines] Failed to start: ${err && err.message ? err.message : err}`);
+    process.exit(1);
+});

package/index.js

@@ -0,0 +1,281 @@
+'use strict';
+const crypto = require('crypto');
+const path = require('path');
+const express = require('express');
+const { engineInstances } = require('@formio/uag-sdk');
+const { enginePaths, loadEngines } = require('@formio/uag-sdk/loader');
+const {
+    PROTOCOL_VERSION,
+    REQUEST_ID_HEADER,
+    SCOPED_TOKEN_HEADER,
+    ProtocolError,
+    checkDecideRequest,
+    checkExtractRequest,
+    errorBody,
+    safeRequestId,
+} = require('@formio/uag-sdk/protocol');
+const { openResearch, connectMcp } = require('./research');
+const debug = require('debug')('formio:uag:engine-server');
+
+/**
+ * The UAG engine server: hosts engine instances, resolved and configured as on
+ * the UAG, behind the remote engine protocol. The UAG's `remote` engine type
+ * calls it, so model credentials and model traffic stay in this process.
+ *
+ * It holds no Form.io credential. For research it connects back to the UAG's
+ * `/mcp` with the scoped token the UAG sent, at the UAG URL it is configured
+ * with, never one taken from a request. The UAG's request id, when it sends a
+ * short token, goes on with that connection and into this server's logs.
+ */
+
+const MIN_KEY_LENGTH = 32;
+const ROOT = __dirname;
+
+/** An error as one short log line: its name, status and the first line of its message. */
+function failureLine(err) {
+    if (!err || typeof err !== 'object') return String(err).slice(0, 300);
+    const status = err.status || err.statusCode;
+    const message = String(err.message || '').split('\n')[0].slice(0, 300);
+    return `${err.name || 'Error'}${status ? ` (${status})` : ''}: ${message}`;
+}
+
+/** Thrown for a configuration the server cannot start with. */
+class EngineServerConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'EngineServerConfigError';
+    }
+}
+
+/** An error answered with a status and the protocol's error body. */
+class HttpError extends Error {
+    constructor(status, message, expose = true) {
+        super(message);
+        this.status = status;
+        this.expose = expose;
+    }
+}
+
+const digest = (value) => crypto.createHash('sha256').update(String(value)).digest();
+
+/** Compare a presented key with the server key in constant time, whatever their lengths. */
+function keyMatches(presented, key) {
+    return typeof presented === 'string' && crypto.timingSafeEqual(digest(presented), digest(key));
+}
+
+/** The engine server key, refusing a missing or short one. */
+function serverKey(env) {
+    const key = env.UAG_ENGINE_SERVER_KEY;
+    if (!key) {
+        throw new EngineServerConfigError('UAG_ENGINE_SERVER_KEY is not set. The engine server refuses to start without a key.');
+    }
+    if (key.length < MIN_KEY_LENGTH) {
+        throw new EngineServerConfigError(`UAG_ENGINE_SERVER_KEY must be at least ${MIN_KEY_LENGTH} characters.`);
+    }
+    return key;
+}
+
+/** What `GET /v1/engines` says about one engine. */
+function describe(engine) {
+    return {
+        name: engine.name,
+        kind: engine.kind,
+        model: engine.model,
+        ...(engine.kind === 'decision' && { maxOptions: engine.maxOptions }),
+        ...(engine.kind === 'agent' && { toolUse: engine.toolUse === true }),
+    };
+}
+
+/** An abort signal that fires when the client goes away before the answer is sent. */
+function requestSignal(res) {
+    const controller = new AbortController();
+    res.on('close', () => {
+        if (!res.writableFinished) controller.abort(new Error('The UAG closed the request.'));
+    });
+    return controller.signal;
+}
+
+/** The UAG's request id for a call, when it sent one that is safe to pass on and log. */
+function requestIdOf(req) {
+    return safeRequestId(req.get(REQUEST_ID_HEADER));
+}
+
+/** Only the keys asked for. */
+function pick(object, keys) {
+    return Object.fromEntries(Object.entries(object || {}).filter(([key]) => keys.has(key)));
+}
+
+/**
+ * Build the engine server's Express app for already-loaded engines.
+ *
+ * Options:
+ * - `engines`: `{ engine }` entries from the SDK loader;
+ * - `key`: the engine server key;
+ * - `uagServer`: the UAG's base URL, for research;
+ * - `connect(url, token, requestId)`: the MCP client factory (for tests).
+ */
+function engineServerApp({ engines, key, uagServer, connect = connectMcp }) {
+    const byName = new Map(engines.map(({ engine }) => [engine.name, engine]));
+    const app = express();
+    app.disable('x-powered-by');
+
+    // The key is checked before anything else, including reading the body.
+    app.use((req, res, next) => {
+        const presented = /^Bearer (.+)$/.exec(req.get('authorization') || '')?.[1];
+        if (!keyMatches(presented, key)) {
+            res.status(401).json(errorBody('Unauthorized.', true));
+            return;
+        }
+        next();
+    });
+    app.use(express.json({ limit: '5mb' }));
+
+    app.get('/health', (req, res) => {
+        res.json({ status: 'ok', engines: byName.size });
+    });
+
+    app.get('/v1/engines', (req, res) => {
+        res.json({ protocol: PROTOCOL_VERSION, engines: [...byName.values()].map(describe) });
+    });
+
+    function engineFor(name, kind) {
+        const engine = byName.get(name);
+        if (!engine) {
+            throw new HttpError(404, `This engine server does not host an engine named "${name}".`);
+        }
+        if (engine.kind !== kind) {
+            throw new HttpError(400, `The engine "${name}" is a ${engine.kind} engine.`);
+        }
+        return engine;
+    }
+
+    app.post('/v1/engines/:name/decide', async (req, res, next) => {
+        try {
+            const engine = engineFor(req.params.name, 'decision');
+            const { state, questions } = checkDecideRequest(req.body);
+            const response = await engine.decide({ state, questions, signal: requestSignal(res) });
+            res.json({
+                protocol: PROTOCOL_VERSION,
+                model: response.model || engine.model,
+                answers: pick(response.answers, new Set(Object.keys(questions))),
+                ...(response.usage && { usage: response.usage }),
+            });
+        }
+        catch (err) {
+            next(err);
+        }
+    });
+
+    app.post('/v1/engines/:name/extract', async (req, res, next) => {
+        let research;
+        try {
+            const engine = engineFor(req.params.name, 'agent');
+            const request = checkExtractRequest(req.body);
+            const signal = requestSignal(res);
+            if (request.tools) {
+                const token = req.get(SCOPED_TOKEN_HEADER);
+                if (!token) {
+                    throw new HttpError(400, `A research extract needs a scoped token in the ${SCOPED_TOKEN_HEADER} header.`);
+                }
+                if (!engine.toolUse) {
+                    throw new HttpError(400, `The engine "${engine.name}" does not research with tools.`);
+                }
+                if (!uagServer) {
+                    throw new HttpError(503, 'This engine server cannot research: UAG_SERVER is not set.');
+                }
+                research = await openResearch({ uagServer, token, requestId: requestIdOf(req), requested: request.tools, signal, connect });
+            }
+            const response = await engine.extract({
+                instructions: request.instructions,
+                state: request.state,
+                fields: request.fields,
+                schema: request.schema,
+                signal,
+                ...(research && { tools: research.tools, callTool: research.callTool, maxIterations: request.maxIterations }),
+            });
+            res.json({
+                protocol: PROTOCOL_VERSION,
+                model: response.model || engine.model,
+                values: pick(response.values, new Set(Object.keys((request.schema && request.schema.properties) || {}))),
+                // The calls this server made for the engine, not what the engine reports.
+                ...(research && { toolCalls: research.calls }),
+                ...(response.usage && { usage: response.usage }),
+            });
+        }
+        catch (err) {
+            next(err);
+        }
+        finally {
+            if (research) await research.close();
+        }
+    });
+
+    app.use((req, res) => {
+        res.status(404).json(errorBody(`No route for ${req.method} ${req.path}.`, true));
+    });
+
+    // eslint-disable-next-line no-unused-vars
+    app.use((err, req, res, _next) => {
+        if (res.headersSent || res.destroyed) return;
+        if (err instanceof HttpError || err instanceof ProtocolError) {
+            res.status(err.status).json(errorBody(err.message, true));
+            return;
+        }
+        if (err && err.type === 'entity.parse.failed') {
+            res.status(400).json(errorBody('The request body is not valid JSON.', true));
+            return;
+        }
+        if (err && err.type === 'entity.too.large') {
+            res.status(413).json(errorBody('The request body is too large.', true));
+            return;
+        }
+        // Any other request body problem (an unsupported charset or encoding, an aborted upload).
+        if (err && typeof err.type === 'string' && Number.isInteger(err.status) && err.status >= 400 && err.status < 500) {
+            res.status(err.status).json(errorBody(err.expose === true ? err.message : 'The request body could not be read.', true));
+            return;
+        }
+        // Always one line, so a refused provider key or a quota shows in the
+        // default logs: the error's name and message, never the request.
+        console.error(`[uag-engines] [${requestIdOf(req) || '-'}] ${req.method} ${req.path} failed: ${failureLine(err)}`);
+        debug(`[${requestIdOf(req) || '-'}] Engine failure on ${req.method} ${req.path}: ${err && err.stack ? err.stack : err}`);
+        // Engines mark the messages that are safe to show; everything else stays here.
+        res.status(502).json(err && err.expose === true
+            ? errorBody(err.message, true)
+            : errorBody('The engine failed (see the engine server logs).', false));
+    });
+
+    return app;
+}
+
+/**
+ * Load the engines and build the app from the environment: `UAG_ENGINES` (and
+ * each instance's `UAG_ENGINE_*` settings), `UAG_ENGINE_SERVER_KEY`,
+ * `UAG_SERVER` and `UAG_ENGINE_PATH`.
+ */
+async function createEngineServer({ env = process.env, config = {}, types = {}, root = ROOT, connect } = {}) {
+    const key = serverKey(env);
+    const uagServer = env.UAG_SERVER ? String(env.UAG_SERVER) : undefined;
+    if (uagServer && !/^https?:\/\//.test(uagServer)) {
+        throw new EngineServerConfigError('UAG_SERVER must be an http or https URL.');
+    }
+    const engines = await loadEngines(engineInstances(config, env), {
+        types,
+        paths: enginePaths(root, env),
+        env,
+        config,
+    });
+    if (!engines.length) {
+        throw new EngineServerConfigError('UAG_ENGINES names no engines, so there is nothing to serve.');
+    }
+    return { app: engineServerApp({ engines, key, uagServer, connect }), engines, uagServer };
+}
+
+module.exports = {
+    MIN_KEY_LENGTH,
+    EngineServerConfigError,
+    createEngineServer,
+    engineServerApp,
+    keyMatches,
+    describe,
+    root: path.resolve(ROOT),
+};

package/network.js

@@ -0,0 +1,37 @@
+'use strict';
+const os = require('os');
+const net = require('net');
+
+/**
+ * Whether an address is private: loopback, link-local, RFC 1918, carrier-grade
+ * NAT, or an IPv6 unique-local address.
+ */
+function isPrivateAddress(address) {
+    const ip = String(address).replace(/^::ffff:/, '').split('%')[0];
+    if (net.isIPv4(ip)) {
+        const [a, b] = ip.split('.').map(Number);
+        return a === 10 || a === 127 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168)
+            || (a === 169 && b === 254) || (a === 100 && b >= 64 && b <= 127);
+    }
+    if (net.isIPv6(ip)) {
+        const lower = ip.toLowerCase();
+        return lower === '::1' || lower.startsWith('fc') || lower.startsWith('fd') || lower.startsWith('fe80');
+    }
+    return false;
+}
+
+/**
+ * The public addresses a server bound to `host` is reachable on: `host` itself
+ * when it is public, or every public interface address for a wildcard bind.
+ */
+function publicAddresses(host, interfaces = os.networkInterfaces()) {
+    const wildcard = !host || host === '0.0.0.0' || host === '::';
+    if (!wildcard) {
+        return net.isIP(host) && !isPrivateAddress(host) ? [host] : [];
+    }
+    return Object.values(interfaces).flat()
+        .filter((entry) => entry && !entry.internal && !isPrivateAddress(entry.address))
+        .map((entry) => entry.address);
+}
+
+module.exports = { isPrivateAddress, publicAddresses };

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@formio/uag-engines",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.0-rc.1",
+  "description": "Host engine packages for the Form.io Universal Agent Gateway (UAG) in their own process, behind the remote engine protocol, so model credentials and model traffic stay out of the UAG.",
+  "keywords": [
+    "formio",
+    "uag",
+    "universal-agent-gateway",
+    "ai",
+    "agents",
+    "engine",
+    "server",
+    "mcp"
+  ],
+  "license": "MIT",
+  "main": "index.js",
+  "bin": "bin/uag-engines.js",
+  "files": [
+    "index.js",
+    "network.js",
+    "research.js",
+    "bin",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "mocha"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/formio/uag.git",
+    "directory": "packages/engine-server"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@formio/uag-sdk": "^2.0.0-rc.1",
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "debug": "^4.4.3",
+    "express": "^5.3.0"
+  },
+  "devDependencies": {
+    "chai": "^6.3.0",
+    "mocha": "^12.0.3"
+  }
+}

package/research.js

@@ -0,0 +1,74 @@
+'use strict';
+const { REQUEST_ID_HEADER } = require('@formio/uag-sdk/protocol');
+
+/**
+ * Research for an extract request: an MCP connection to the UAG's `/mcp`,
+ * authenticated with the scoped token the UAG sent. The UAG decides what the
+ * token allows (the task's read-only tools, with the caller's identity); this
+ * side offers the model only the tools that were both requested and listed
+ * there, and records every call.
+ */
+
+/** Connect an MCP client to `url` with `token` as its bearer token, and the UAG's request id when there is one. */
+async function connectMcp(url, token, requestId) {
+    const { Client } = require('@modelcontextprotocol/sdk/client/index.js');
+    const { StreamableHTTPClientTransport } = require('@modelcontextprotocol/sdk/client/streamableHttp.js');
+    const client = new Client({ name: 'uag-engines', version: require('./package.json').version });
+    await client.connect(new StreamableHTTPClientTransport(new URL(url), {
+        requestInit: { headers: { Authorization: `Bearer ${token}`, ...(requestId && { [REQUEST_ID_HEADER]: requestId }) } },
+    }));
+    return client;
+}
+
+/**
+ * Open research: connect, intersect the tools, and return what the engine's
+ * extract needs, the calls made, and `close`, which is safe to call twice.
+ */
+async function openResearch({ uagServer, token, requestId, requested, signal, connect = connectMcp }) {
+    signal.throwIfAborted();
+    const client = await connect(`${uagServer.replace(/\/+$/, '')}/mcp`, token, requestId);
+    let closed = false;
+    const close = async () => {
+        if (closed) return;
+        closed = true;
+        await client.close().catch(() => {});
+    };
+    signal.addEventListener('abort', close, { once: true });
+    try {
+        // The UAG may have given up while this side was connecting.
+        signal.throwIfAborted();
+        const listed = new Map(((await client.listTools()).tools || []).map((tool) => [tool.name, tool]));
+        const names = new Set(requested.map((tool) => tool.name).filter((name) => listed.has(name)));
+        const tools = [...names].map((name) => {
+            const tool = listed.get(name);
+            return { name, description: tool.description || '', inputSchema: tool.inputSchema || { type: 'object' } };
+        });
+        const calls = [];
+        async function callTool(name, args) {
+            if (signal.aborted || closed) {
+                throw signal.reason || new Error('The research was stopped.');
+            }
+            if (!names.has(name)) {
+                calls.push({ name, isError: true });
+                return { content: [{ type: 'text', text: `The tool "${name}" is not available to this task.` }], isError: true };
+            }
+            let result;
+            try {
+                result = await client.callTool({ name, arguments: args || {} }, undefined, { signal });
+            }
+            catch (err) {
+                if (signal.aborted) throw signal.reason || err;
+                result = { content: [{ type: 'text', text: err && err.message ? err.message : 'The tool call failed.' }], isError: true };
+            }
+            calls.push({ name, isError: !!result.isError });
+            return result;
+        }
+        return { tools, callTool, calls, close };
+    }
+    catch (err) {
+        await close();
+        throw err;
+    }
+}
+
+module.exports = { connectMcp, openResearch };