@formio/uag-sdk 0.0.0-stage → 2.0.0-rc.10

package/index.js

@@ -0,0 +1,30 @@
+'use strict';
+/**
+ * @formio/uag-sdk: what engine packages for the Form.io UAG are built
+ * with. The engine contract's types are in contract.d.ts; the loader is
+ * `@formio/uag-sdk/loader` and the conformance check
+ * `@formio/uag-sdk/conformance`.
+ */
+const { ENGINE_API_VERSION, ENGINE_NAME, defineEngine, isEngineType } = require('./define');
+const { EngineError, EngineConfigError, redact } = require('./errors');
+const { parseInstances, engineInstances } = require('./instances');
+const { settingVariable, resolveSettings } = require('./settings');
+const { requiredSchema, decodeValues, parseJsonObject, toolResultText } = require('./helpers');
+
+module.exports = {
+    ENGINE_API_VERSION,
+    ENGINE_NAME,
+    defineEngine,
+    isEngineType,
+    EngineError,
+    EngineConfigError,
+    redact,
+    parseInstances,
+    engineInstances,
+    settingVariable,
+    resolveSettings,
+    requiredSchema,
+    decodeValues,
+    parseJsonObject,
+    toolResultText,
+};

package/instances.js

@@ -0,0 +1,117 @@
+'use strict';
+const { ENGINE_NAME } = require('./define');
+const { EngineConfigError } = require('./errors');
+
+/**
+ * npm package names, scoped or not. Every segment starts with a letter or digit,
+ * so "." and ".." (and so any relative path) can never match.
+ */
+const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+const MAX_PACKAGE_NAME = 214;
+
+/**
+ * Whether a type is given as a package name rather than a type name: scoped
+ * (`@acme/uag-engine-x`), or unscoped with the conventional prefix (`uag-engine-x`).
+ */
+function isPackageName(type) {
+    return type.startsWith('@') || type.includes('/') || type.startsWith('uag-engine-');
+}
+
+/** Refuse a type that is neither a type name nor a package name, before any lookup. */
+function checkType(type) {
+    const valid = isPackageName(type)
+        ? PACKAGE_NAME.test(type) && type.length <= MAX_PACKAGE_NAME
+        : ENGINE_NAME.test(type);
+    if (!valid) {
+        throw new EngineConfigError(
+            `The engine type name ${JSON.stringify(type)} is not valid. Use a type name such as "claude", ` +
+            'or a package name such as "@acme/uag-engine-x" or "uag-engine-x".'
+        );
+    }
+}
+
+function checkName(name) {
+    if (!ENGINE_NAME.test(name)) {
+        throw new EngineConfigError(
+            `The engine name ${JSON.stringify(name)} is not valid: use lowercase letters, digits and "-", ` +
+            'starting with a letter, up to 63 characters.'
+        );
+    }
+}
+
+/** Refuse two instances with the same name. Instances without a name yet are skipped. */
+function checkUnique(instances) {
+    const seen = new Set();
+    for (const { name } of instances) {
+        if (!name) continue;
+        if (seen.has(name)) {
+            throw new EngineConfigError(`Two engines are named "${name}". Engine instance names must be unique.`);
+        }
+        seen.add(name);
+    }
+}
+
+/** One `UAG_ENGINES` entry: `<type>` or `<name>:<type>`. */
+function parseEntry(entry) {
+    const colon = entry.indexOf(':');
+    const name = colon === -1 ? undefined : entry.slice(0, colon).trim();
+    const type = colon === -1 ? entry : entry.slice(colon + 1).trim();
+    if (name !== undefined) checkName(name);
+    checkType(type);
+    // A bare package name takes its type's name, which is known once it loads.
+    return { name: name ?? (isPackageName(type) ? undefined : type), type, options: {} };
+}
+
+/** One configuration entry: a `UAG_ENGINES` string, or `{ name, type, options }`. */
+function parseConfigured(entry) {
+    if (typeof entry === 'string') {
+        return parseEntry(entry.trim());
+    }
+    if (!entry || typeof entry !== 'object') {
+        throw new EngineConfigError(`An engine entry must be a string or { name, type, options }, not ${JSON.stringify(entry)}.`);
+    }
+    const { name, type, options = {} } = entry;
+    if (name !== undefined) checkName(name);
+    if (typeof type === 'string') {
+        checkType(type);
+    }
+    else if (!type || typeof type !== 'object') {
+        throw new EngineConfigError(`The engine${name ? ` "${name}"` : ''} needs a type: a type name, a package name, or an engine type definition.`);
+    }
+    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+        throw new EngineConfigError(`The options of the engine${name ? ` "${name}"` : ''} must be an object.`);
+    }
+    const named = name ?? (typeof type === 'string' ? (isPackageName(type) ? undefined : type) : undefined);
+    return { name: named, type, options };
+}
+
+/**
+ * The engine instances in a `UAG_ENGINES` string or a configuration list. Each
+ * is `{ name, type, options }`; `name` is undefined until the type is known when
+ * the entry names only a package or a definition. Nothing named means none.
+ */
+function parseInstances(source) {
+    if (source === undefined || source === null) return [];
+    let entries;
+    if (typeof source === 'string') {
+        entries = source.split(',').map((entry) => entry.trim()).filter(Boolean).map(parseEntry);
+    }
+    else if (Array.isArray(source)) {
+        entries = source.filter((entry) => entry !== '').map(parseConfigured);
+    }
+    else {
+        throw new EngineConfigError('The engine list must be a comma-separated string or an array.');
+    }
+    checkUnique(entries);
+    return entries;
+}
+
+/**
+ * The instances to enable: from configuration (`engines`) when it lists them,
+ * otherwise from `UAG_ENGINES`. Configuration takes precedence.
+ */
+function engineInstances(config = {}, env = process.env) {
+    return parseInstances(Array.isArray(config && config.engines) ? config.engines : env.UAG_ENGINES);
+}
+
+module.exports = { PACKAGE_NAME, isPackageName, checkName, checkType, checkUnique, parseInstances, engineInstances };

package/loader.d.ts

@@ -0,0 +1,67 @@
+import type { Engine } from './contract';
+import type { EngineInstanceSpec, EngineTypeDefinition } from './index';
+
+export type LoadOptions = {
+    /** Types resolved before any package: the built-in ones, and ones the embedding application passes. */
+    types?: Record<string, EngineTypeDefinition>;
+    /** The directories whose `node_modules` packages are looked up in, from `enginePaths`; nowhere else. */
+    paths?: string[];
+    env?: Record<string, string | undefined>;
+    config?: Record<string, any>;
+    /** The engine contract version the host supports. Default: this SDK's. */
+    apiVersion?: number;
+};
+
+/** An enabled engine and where it came from, ready for `Formflow.engineRegistry`. */
+export type LoadedEngine = {
+    engine: Engine;
+    /** The engine type's name. */
+    type: string;
+    /** The engine type's title. */
+    title?: string;
+    /** The kinds the engine type declares. */
+    kinds?: ('decision' | 'agent')[];
+    /** The engine type's own version, from its definition or its package. */
+    typeVersion?: string;
+    package?: string;
+    version?: string;
+};
+
+/**
+ * The directories whose `node_modules` packages are looked up in: the host's own
+ * installation and each directory above it, then each absolute directory in
+ * `UAG_ENGINE_PATH` (without the directories above it).
+ */
+export declare function enginePaths(root: string | undefined, env?: Record<string, string | undefined>): string[];
+
+/** The packages a type name may come from, in order. */
+export declare function packageCandidates(type: string): string[];
+
+export declare function resolveType(type: string | EngineTypeDefinition, options?: LoadOptions): {
+    definition: EngineTypeDefinition;
+    package?: string;
+    version?: string;
+};
+
+/** Create one engine for an instance, resolving its settings. */
+export declare function createEngine(definition: EngineTypeDefinition, options: {
+    name: string;
+    options?: Record<string, any>;
+    env?: Record<string, string | undefined>;
+    config?: Record<string, any>;
+}): Promise<Engine>;
+
+/** Resolve, configure and create each instance. Any problem stops loading, with the instance named. */
+export declare function loadEngines(instances: EngineInstanceSpec[], options?: LoadOptions): Promise<LoadedEngine[]>;
+
+/** One instance planned but not created: what creating it takes, and how a failure to start reads. */
+export type PlannedEngine = Omit<LoadedEngine, 'engine'> & {
+    name: string;
+    kinds: ('decision' | 'agent')[];
+    definition: EngineTypeDefinition;
+    args: { name: string; settings: Record<string, any>; options: Record<string, any>; config: Record<string, any>; requireSetting(key: string): any };
+    failure(err: unknown): string;
+};
+
+/** Resolve and configure each instance without creating it, for a host that creates engines elsewhere. */
+export declare function planEngines(instances: EngineInstanceSpec[], options?: LoadOptions): PlannedEngine[];

package/loader.js

@@ -0,0 +1,272 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { ENGINE_API_VERSION, definitionProblems, withDefaults } = require('./define');
+const { EngineConfigError, redact } = require('./errors');
+const { checkName, checkType, checkUnique, isPackageName } = require('./instances');
+const { missingSetting, resolveSettings, secretValues, settingVariable } = require('./settings');
+
+/**
+ * Finding, configuring and creating engine instances. The UAG, `uag-eval` and
+ * the engine server all load engines here, so one configuration means the same
+ * engines in each.
+ */
+
+/**
+ * The directories whose `node_modules` engine packages are looked up in: the
+ * host's own installation and each directory above it (where Node finds the
+ * host's own dependencies, so engines installed beside the host are found),
+ * then each absolute directory in `UAG_ENGINE_PATH`, without the directories
+ * above it. Never the working directory, `NODE_PATH` or Node's global folders.
+ */
+function enginePaths(root, env = process.env) {
+    const extra = String(env.UAG_ENGINE_PATH || '').split(path.delimiter).map((dir) => dir.trim()).filter(Boolean);
+    for (const dir of extra) {
+        if (!path.isAbsolute(dir)) {
+            throw new EngineConfigError(`UAG_ENGINE_PATH must list absolute directories; "${dir}" is relative.`);
+        }
+    }
+    const host = [];
+    for (let dir = root && path.resolve(root); dir; ) {
+        // As Node does, never look for node_modules/node_modules.
+        if (path.basename(dir) !== 'node_modules') host.push(dir);
+        const parent = path.dirname(dir);
+        dir = parent === dir ? undefined : parent;
+    }
+    return [...host, ...extra];
+}
+
+/** The packages a type name may come from, in order. */
+function packageCandidates(type) {
+    return isPackageName(type) ? [type] : [`@formio/uag-${type}`, `uag-engine-${type}`];
+}
+
+/** Whether `file` is `dir` or inside it. */
+function isInside(file, dir) {
+    const relative = path.relative(dir, file);
+    return relative === '' || (!!relative && !relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+/**
+ * Find `name` in `<dir>/node_modules` of the first of `paths` that has it, and
+ * nowhere else: not in the directories above, `NODE_PATH` or Node's global
+ * folders, which `require.resolve` would also search. Returns its entry file
+ * and package.json, or undefined when no path has it.
+ */
+function findPackage(name, paths) {
+    for (const dir of paths) {
+        const packageDir = path.join(dir, 'node_modules', ...name.split('/'));
+        const manifest = path.join(packageDir, 'package.json');
+        if (!fs.existsSync(manifest)) continue;
+        let json;
+        try {
+            json = JSON.parse(fs.readFileSync(manifest, 'utf8'));
+        }
+        catch (err) {
+            throw new EngineConfigError(`The package "${name}" has an unreadable package.json (${manifest}): ${err && err.message}`);
+        }
+        let entry;
+        try {
+            entry = require.resolve(name, { paths: [dir] });
+        }
+        catch (err) {
+            throw new EngineConfigError(`The package "${name}" (${packageDir}) has no entry point that require() can load: ${err && (err.code || err.message)}.`);
+        }
+        // A broken package must not fall through to a copy found elsewhere.
+        // Real paths, so a linked workspace package is still its own.
+        if (!isInside(fs.realpathSync(entry), fs.realpathSync(packageDir))) {
+            throw new EngineConfigError(`The package "${name}" in ${packageDir} resolved to ${entry}, outside it; it was not loaded.`);
+        }
+        return { entry, json };
+    }
+    return undefined;
+}
+
+/** The message of anything thrown, including a string. */
+function errorText(err) {
+    return err && typeof err === 'object' && 'message' in err ? String(err.message) : String(err);
+}
+
+/**
+ * Check a definition, from this SDK, another copy of it, or none, and return it
+ * with its defaults (`title`, and `version` from the package it came from).
+ */
+function checkDefinition(definition, source, apiVersion, packageVersion) {
+    const problems = definitionProblems(definition);
+    if (problems.length) {
+        throw new EngineConfigError(`${source} is not a UAG engine: it does not export a valid engine type definition (${problems.join('; ')}).`);
+    }
+    if (definition.apiVersion !== apiVersion) {
+        throw new EngineConfigError(
+            `${source} (engine type "${definition.name}") was built for engine API version ${definition.apiVersion}; ` +
+            `this server supports version ${apiVersion}.`
+        );
+    }
+    return withDefaults(definition, packageVersion);
+}
+
+/**
+ * The definition for an instance's type: a definition given directly, a type in
+ * `types` (built-in, or passed by the embedding application), then the packages
+ * `@formio/uag-<type>` and `uag-engine-<type>`, or the package named.
+ * Returns the package's name and version when it came from one.
+ */
+function resolveType(type, { types = {}, paths = [], apiVersion = ENGINE_API_VERSION } = {}) {
+    if (type && typeof type === 'object') {
+        return { definition: checkDefinition(type, 'The engine type given in configuration', apiVersion) };
+    }
+    checkType(type);
+    if (!isPackageName(type) && Object.prototype.hasOwnProperty.call(types, type)) {
+        return { definition: checkDefinition(types[type], `The built-in engine type "${type}"`, apiVersion) };
+    }
+    const candidates = packageCandidates(type);
+    for (const candidate of candidates) {
+        const found = findPackage(candidate, paths);
+        if (!found) continue;
+        const { entry, json: pkg } = found;
+        let exported;
+        try {
+            exported = require(entry);
+        }
+        catch (err) {
+            throw new EngineConfigError(`The package "${candidate}" failed to load: ${errorText(err)}`);
+        }
+        const definition = exported && exported.__esModule && exported.default ? exported.default : exported;
+        return {
+            definition: checkDefinition(definition, `The package "${candidate}"`, apiVersion, pkg.version),
+            package: candidate,
+            ...(pkg.version && { version: pkg.version })
+        };
+    }
+    const known = Object.keys(types);
+    throw new EngineConfigError(
+        `No engine type "${type}" is installed. Looked for ${candidates.map((name) => `"${name}"`).join(' and ')}. ` +
+        `Install one (npm install ${candidates[0]}), or add a directory that contains it to UAG_ENGINE_PATH.` +
+        (known.length ? ` Types available without installing: ${known.join(', ')}.` : '')
+    );
+}
+
+/** Refuse two instance settings that would read the same `UAG_ENGINE_*` variable. */
+function checkVariables(resolved) {
+    const owners = new Map();
+    for (const { name, definition } of resolved) {
+        for (const key of Object.keys(definition.settings || {})) {
+            const variable = settingVariable(name, key);
+            const owner = owners.get(variable);
+            if (owner && owner.name !== name) {
+                throw new EngineConfigError(
+                    `The engines "${owner.name}" and "${name}" would both read ${variable} (for ${owner.key} and ${key}). Rename one of them.`
+                );
+            }
+            owners.set(variable, { name, key });
+        }
+    }
+}
+
+/**
+ * Create one engine from its definition, for an instance name and options.
+ * Errors name the instance and its type, and never contain a secret setting.
+ */
+async function createEngine(definition, { name, options = {}, env = process.env, config = {} }) {
+    const label = `The "${name}" engine (type "${definition.name}")`;
+    const settings = resolveSettings(definition, name, options, env);
+    const secrets = secretValues(definition, settings, options);
+    let engine;
+    try {
+        engine = await definition.create({
+            name,
+            settings,
+            options,
+            config,
+            requireSetting: (key) => {
+                if (settings[key] === undefined) throw missingSetting(definition, name, key);
+                return settings[key];
+            },
+        });
+    }
+    catch (err) {
+        const message = redact(errorText(err), secrets);
+        throw new EngineConfigError(err instanceof EngineConfigError || (err && err.name === 'EngineConfigError') ? message : `${label} failed to start: ${message}`);
+    }
+    if (!engine || typeof engine !== 'object') {
+        throw new EngineConfigError(`${label} did not create an engine.`);
+    }
+    if (engine.name !== name) {
+        throw new EngineConfigError(`${label} created an engine named ${JSON.stringify(engine.name)}; it must use the instance name.`);
+    }
+    if (!definition.kinds.includes(engine.kind)) {
+        throw new EngineConfigError(`${label} created a ${JSON.stringify(engine.kind)} engine; its type declares ${definition.kinds.join(' and ')}.`);
+    }
+    return engine;
+}
+
+/**
+ * Load the given instances (from `parseInstances` or `engineInstances`): resolve
+ * each type, resolve its settings, and create the engine. Returns
+ * `{ engine, type, package, version }` for each, in order, ready for
+ * `Formflow.engineRegistry`. Any problem stops loading with the instance named.
+ */
+async function loadEngines(instances, { types = {}, paths = [], env = process.env, config = {}, apiVersion = ENGINE_API_VERSION } = {}) {
+    const resolved = instances.map((instance) => {
+        const found = resolveType(instance.type, { types, paths, apiVersion });
+        const name = instance.name || found.definition.name;
+        checkName(name);
+        return { ...found, name, options: instance.options || {} };
+    });
+    checkUnique(resolved);
+    checkVariables(resolved);
+    const loaded = [];
+    for (const { definition, name, options, package: pkg, version } of resolved) {
+        const engine = await createEngine(definition, { name, options, env, config });
+        loaded.push({ engine, type: definition.name, title: definition.title, kinds: [...definition.kinds], ...(definition.version && { typeVersion: definition.version }), ...(pkg && { package: pkg }), ...(version && { version }) });
+    }
+    return loaded;
+}
+
+/**
+ * Plan the given instances without creating them: resolve each type and its
+ * settings, and describe how each is created and how a failure to start reads
+ * (with secrets left out). For a host that has engines created elsewhere, such
+ * as Agentic Formflow's `startEngines`, which creates and wraps them.
+ */
+function planEngines(instances, { types = {}, paths = [], env = process.env, config = {}, apiVersion = ENGINE_API_VERSION } = {}) {
+    const resolved = instances.map((instance) => {
+        const found = resolveType(instance.type, { types, paths, apiVersion });
+        const name = instance.name || found.definition.name;
+        checkName(name);
+        return { ...found, name, options: instance.options || {} };
+    });
+    checkUnique(resolved);
+    checkVariables(resolved);
+    return resolved.map(({ definition, name, options, package: pkg, version }) => {
+        const label = `The "${name}" engine (type "${definition.name}")`;
+        const settings = resolveSettings(definition, name, options, env);
+        const secrets = secretValues(definition, settings, options);
+        return {
+            name,
+            type: definition.name,
+            title: definition.title,
+            kinds: [...definition.kinds],
+            ...(definition.version && { typeVersion: definition.version }),
+            ...(pkg && { package: pkg }),
+            ...(version && { version }),
+            definition,
+            args: {
+                name,
+                settings,
+                options,
+                config,
+                requireSetting: (key) => {
+                    if (settings[key] === undefined) throw missingSetting(definition, name, key);
+                    return settings[key];
+                },
+            },
+            failure: (err) => {
+                const message = redact(errorText(err), secrets);
+                return err instanceof EngineConfigError || (err && err.name === 'EngineConfigError') ? message : `${label} failed to start: ${message}`;
+            },
+        };
+    });
+}
+
+module.exports = { enginePaths, packageCandidates, resolveType, createEngine, loadEngines, planEngines };

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@formio/uag-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.0-rc.10",
+  "description": "Build engine packages for the Form.io Universal Agent Gateway (UAG): the engine contract, defineEngine, settings and instance resolution, the engine loader, and a conformance check.",
+  "keywords": [
+    "formio",
+    "uag",
+    "universal-agent-gateway",
+    "ai",
+    "agents",
+    "engine",
+    "sdk"
+  ],
+  "license": "MIT",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./loader": {
+      "types": "./loader.d.ts",
+      "default": "./loader.js"
+    },
+    "./conformance": {
+      "types": "./conformance.d.ts",
+      "default": "./conformance.js"
+    },
+    "./protocol": {
+      "types": "./protocol.d.ts",
+      "default": "./protocol.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "*.js",
+    "*.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "mocha"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/formio/uag.git",
+    "directory": "packages/engine-sdk"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "chai": "^6.3.0",
+    "mocha": "^12.0.3"
+  }
+}

package/protocol.d.ts

@@ -0,0 +1,61 @@
+import type { Attachment, DecisionQuestion, DecisionResponse, DecisionState, ExtractResponse, FieldSpec, GenerateRequest, GenerateResponse, ToolDefinition } from './contract';
+
+/** The remote engine protocol version this SDK speaks. */
+export declare const PROTOCOL_VERSION: 1;
+
+/** The header that carries a scoped token, on research extracts only. */
+export declare const SCOPED_TOKEN_HEADER: 'x-uag-scoped-token';
+
+/** The optional header that carries the Agent API request id, on decide and extract. */
+export declare const REQUEST_ID_HEADER: 'x-request-id';
+
+/** A request id that is safe to send and log (up to 128 of `[A-Za-z0-9._:-]`), or undefined. */
+export declare function safeRequestId(value: unknown): string | undefined;
+
+/** A message in another protocol version, or of the wrong shape. */
+export declare class ProtocolError extends Error {
+    status: number;
+    constructor(message: string, status?: number);
+}
+
+/** One engine an engine server hosts, as `GET /v1/engines` describes it. */
+export type RemoteEngineDescription = {
+    name: string;
+    kind: 'decision' | 'agent';
+    model: string;
+    maxOptions?: number;
+    toolUse?: boolean;
+    /** Agent engines: the document kinds generate reads. Default ['text']. */
+    accepts?: Array<'text' | 'pdf'>;
+    /** Agent engines: whether the engine generates free text. */
+    generate?: boolean;
+};
+
+/** The most PDF bytes one generate request carries (32 MB). */
+export declare const MAX_DOCUMENT_BYTES: number;
+
+/** A generate request on the wire: PDFs as base64. */
+export type WireAttachment =
+    | { kind: 'pdf'; data: string; label: string; pages?: number }
+    | { kind: 'text'; text: string; label: string; textFormat?: 'plain' | 'markdown' | 'csv' };
+
+export type RemoteExtractRequest = {
+    instructions: string;
+    state: DecisionState;
+    fields: FieldSpec[];
+    schema: Record<string, any>;
+    tools?: ToolDefinition[];
+    maxIterations?: number;
+};
+
+export declare function checkVersion(body: unknown, side?: 'request' | 'response'): void;
+export declare function checkDecideRequest(body: unknown): { state: DecisionState; questions: Record<string, DecisionQuestion> };
+export declare function checkExtractRequest(body: unknown): RemoteExtractRequest;
+export declare function checkDescription(body: unknown): RemoteEngineDescription[];
+export declare function checkDecisionResponse(body: unknown): DecisionResponse;
+export declare function checkExtractResponse(body: unknown): ExtractResponse;
+export declare function checkGenerateRequest(body: unknown, maxBytes?: number): Omit<GenerateRequest, 'signal' | 'onProgress'>;
+export declare function checkGenerateResponse(body: unknown): GenerateResponse;
+export declare function encodeAttachments(attachments?: Attachment[]): WireAttachment[];
+export declare function pdfByteLength(attachments?: Attachment[]): number;
+export declare function errorBody(message: string, expose?: boolean): { protocol: 1; error: string; expose: boolean };