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

package/contract.d.ts

@@ -0,0 +1,223 @@
+/**
+ * The engine contract for the Form.io Universal Agent Gateway (UAG): what a
+ * decision engine or an agent engine receives and returns. Engine types
+ * declare `apiVersion: ENGINE_API_VERSION`; the UAG refuses a type built for
+ * another version at startup. It matches what @formio/appserver-core accepts.
+ */
+/**
+ * Engine contracts for the generic Agent API.
+ *
+ * Two kinds of model plug into the UAG. A decision engine answers closed-set
+ * questions — pick one option, place the input on an ordered scale, yes or no —
+ * and returns a probability for each answer. An agent engine produces open
+ * values, researching with read-only tools when a task allows. The two take different inputs and return
+ * different outputs, so they get separate contracts instead of one generic call.
+ */
+/** Pick one option from a set with no order between options. */
+export type ChoiceQuestion = {
+    type: 'choice';
+    instructions: string;
+    /** Option label → optional description. The labels are what the model chooses between. */
+    options: Record<string, string | null>;
+};
+/** Place the state at a position on an ordered list of levels. */
+export type ScoreQuestion = {
+    type: 'score';
+    instructions: string;
+    /** Levels in order, lowest first. */
+    levels: string[];
+};
+/** A yes/no question where the probability of "yes" is the useful signal. */
+export type NoulQuestion = {
+    type: 'noul';
+    instructions: string;
+    criteria?: {
+        true?: string;
+        false?: string;
+    };
+};
+export type DecisionQuestion = ChoiceQuestion | ScoreQuestion | NoulQuestion;
+export type ChoiceAnswer = {
+    type: 'choice';
+    choice: string;
+    /** Option label → probability. */
+    probabilities: Record<string, number>;
+    /** Normalized for the number of options: (p_max − 1/n) / (1 − 1/n). */
+    confidence: number;
+};
+export type ScoreAnswer = {
+    type: 'score';
+    /** Position along the levels; may fall between two of them. */
+    score: number;
+    /** Level index (as a string) → probability. */
+    probabilities: Record<string, number>;
+    confidence: number;
+};
+export type NoulAnswer = {
+    type: 'noul';
+    /** Probability of "yes", from 0 to 1. */
+    probability: number;
+};
+export type DecisionAnswer = ChoiceAnswer | ScoreAnswer | NoulAnswer;
+/**
+ * What every engine reads, as a structured object with named fields that
+ * questions refer to by name ("Based on `input`, …").
+ */
+export type DecisionState = {
+    /** The task's criteria. */
+    instructions?: string;
+    /** The task's input values keyed by field label (the whole submission when it has no input). */
+    input: Record<string, any>;
+    /** Values at the paths the task lists in `uagContext`, keyed by field label. */
+    context?: Record<string, any>;
+    /** Today's date, e.g. "Tuesday, October 20, 2026 (2026-10-20)". */
+    today: string;
+};
+export type DecisionRequest = {
+    state: DecisionState;
+    questions: Record<string, DecisionQuestion>;
+    signal?: AbortSignal;
+};
+export type EngineUsage = {
+    inputTokens?: number | null;
+    outputTokens?: number | null;
+};
+export type DecisionResponse = {
+    model: string;
+    answers: Record<string, DecisionAnswer>;
+    usage?: EngineUsage;
+};
+/**
+ * The version of this engine contract. An engine may declare the version it was
+ * built for as `apiVersion`; one built for another version is refused at startup.
+ */
+export declare const ENGINE_API_VERSION: 1;
+export interface DecisionEngine {
+    name: string;
+    kind: 'decision';
+    /** The engine contract version the engine was built for. */
+    apiVersion?: number;
+    model: string;
+    /** The most options a single Choice or Score question may carry. */
+    maxOptions: number;
+    decide(request: DecisionRequest): Promise<DecisionResponse>;
+}
+/** One field an agent engine is asked to produce a value for. */
+export type FieldSpec = {
+    path: string;
+    label: string;
+    type: string;
+    description: string;
+    /** How the value must be written, from the same rules `get_field_info` gives agents. */
+    rule: string;
+    format?: string;
+    /** For closed-set fields routed to an agent engine: the allowed values. */
+    options?: {
+        label: string;
+        value: any;
+    }[];
+    multiple?: boolean;
+};
+export type ExtractRequest = {
+    instructions: string;
+    state: DecisionState;
+    fields: FieldSpec[];
+    /** JSON schema of the object to return, keyed by field path. */
+    schema: Record<string, any>;
+    signal?: AbortSignal;
+    /**
+     * Read-only tools the engine may call before answering, when the task enables
+     * research (`uagTools`). Only engines that declare `toolUse` receive them. The
+     * answer is still structured values for `fields`; tools never write.
+     */
+    tools?: ToolDefinition[];
+    /**
+     * Call one of `tools`. Runs in process with the caller's identity, so Form.io
+     * permissions apply; names outside `tools` are refused. Set with `tools`.
+     */
+    callTool?(name: string, args: Record<string, any>): Promise<ToolCallResult>;
+    /** The most tool-use round trips before the engine must answer. Set with `tools`. */
+    maxIterations?: number;
+    /**
+     * A scoped token carrying the caller's identity and exactly `tools`, all
+     * read-only, for engines that run the model outside the UAG and call the
+     * tools back over `/mcp`. In-process engines use `callTool` and ignore it.
+     */
+    scopedToken?: string;
+};
+export type ExtractResponse = {
+    model: string;
+    /** Field path → value. Paths that were not asked for are discarded by the caller. */
+    values: Record<string, any>;
+    /** Tools the engine called while researching, in order. */
+    toolCalls?: {
+        name: string;
+        isError: boolean;
+    }[];
+    usage?: EngineUsage;
+};
+/** A tool as an agent engine sees it: plain JSON, ready for any model API. */
+export type ToolDefinition = {
+    name: string;
+    description: string;
+    /** JSON schema of the tool's arguments. */
+    inputSchema: Record<string, any>;
+};
+/** A tool call's outcome, in MCP content form. */
+export type ToolCallResult = {
+    content: {
+        type: string;
+        text?: string;
+        [key: string]: any;
+    }[];
+    isError?: boolean;
+};
+export interface AgentEngine {
+    name: string;
+    kind: 'agent';
+    /** The engine contract version the engine was built for. */
+    apiVersion?: number;
+    model: string;
+    /**
+     * Whether `extract` accepts read-only tools for research. Engines without it
+     * are passed over for field groups whose task enables tools.
+     */
+    toolUse?: boolean;
+    /** Structured extraction that returns values for the requested fields only. */
+    extract(request: ExtractRequest): Promise<ExtractResponse>;
+    /**
+     * The document representations `generate` reads natively. Default ['text'].
+     * An engine lists 'pdf' only when it sends PDFs to its model as documents.
+     */
+    accepts?: Array<'text' | 'pdf'>;
+    /** Free-text generation over attached documents, for document plugins. Optional. */
+    generate?(request: GenerateRequest): Promise<GenerateResponse>;
+}
+export type Engine = DecisionEngine | AgentEngine;
+
+/** A document an engine reads: PDF bytes, or text with its format. */
+export type Attachment =
+    | { kind: 'pdf'; data: Buffer; label: string; pages?: number }
+    | { kind: 'text'; text: string; label: string; textFormat?: 'plain' | 'markdown' | 'csv' };
+
+export type GenerateRequest = {
+    /** The user prompt. */
+    instructions: string;
+    system?: string;
+    /** Sent before the instructions, in order. */
+    attachments?: Attachment[];
+    format: 'markdown' | 'text';
+    /** Default: the engine's own output limit setting. */
+    maxTokens?: number;
+    signal?: AbortSignal;
+    /** Called as the answer streams, with the characters produced so far. */
+    onProgress?(outputChars: number): void;
+};
+
+export type GenerateResponse = {
+    text: string;
+    model: string;
+    /** 'max_tokens': the answer was cut off at the output limit. */
+    stopReason: 'end' | 'max_tokens';
+    usage?: EngineUsage;
+};

package/define.js

@@ -0,0 +1,142 @@
+'use strict';
+
+/** The engine contract version this SDK describes. */
+const ENGINE_API_VERSION = 1;
+
+/** Engine type and instance names: what `UAG_ENGINES` and routing lists use. */
+const ENGINE_NAME = /^[a-z][a-z0-9-]{0,62}$/;
+
+/** The plugin type of every engine definition. */
+const ENGINE_PLUGIN_TYPE = 'engine';
+
+/** The shape an engine definition takes, shown when one is in another shape. */
+function definitionShape(name = 'acme') {
+    return `{ type: 'engine', name: '${name}', title: '${name[0].toUpperCase()}${name.slice(1)}', version: '1.0.0', kinds, apiVersion, settings, create }`;
+}
+
+const KINDS = ['decision', 'agent'];
+const SETTING_NAME = /^[a-z][a-zA-Z0-9]*$/;
+const VARIABLE_NAME = /^[A-Z][A-Z0-9_]*$/;
+const SETTING_TYPES = ['string', 'number', 'boolean'];
+const SETTING_KEYS = ['env', 'required', 'secret', 'default', 'type', 'description'];
+
+/** The reasons a value is not a valid engine type definition; empty when it is. */
+function definitionProblems(definition) {
+    if (!definition || typeof definition !== 'object') {
+        return ['it is not an object'];
+    }
+    const problems = [];
+    if (definition.type !== ENGINE_PLUGIN_TYPE) {
+        // The 2.0 release candidates put the engine's name in "type". The shape was
+        // never in a final release, so it is refused rather than converted.
+        if (typeof definition.type === 'string' && definition.name === undefined) {
+            return [`it is in the shape of the 2.0 release candidates, { type: ${JSON.stringify(definition.type)}, kinds, ... }; ` +
+                `an engine definition is now a plugin: ${definitionShape(ENGINE_NAME.test(definition.type) ? definition.type : 'acme')}`];
+        }
+        problems.push(`"type" must be "${ENGINE_PLUGIN_TYPE}"`);
+    }
+    if (typeof definition.name !== 'string' || !ENGINE_NAME.test(definition.name)) {
+        problems.push('"name" must be a name of lowercase letters, digits and "-", starting with a letter');
+    }
+    if (definition.title !== undefined && (typeof definition.title !== 'string' || !definition.title)) {
+        problems.push('"title" must be a non-empty string');
+    }
+    if (definition.version !== undefined && (typeof definition.version !== 'string' || !/^\d+\.\d+\.\d+/.test(definition.version))) {
+        problems.push('"version" must be a semver string such as "1.0.0"');
+    }
+    if (!Array.isArray(definition.kinds) || !definition.kinds.length || !definition.kinds.every((kind) => KINDS.includes(kind))) {
+        problems.push('"kinds" must list "decision", "agent" or both');
+    }
+    if (!Number.isInteger(definition.apiVersion) || definition.apiVersion < 1) {
+        problems.push('"apiVersion" must be the engine contract version it was built for');
+    }
+    if (typeof definition.create !== 'function') {
+        problems.push('"create" must be a function');
+    }
+    const settings = definition.settings === undefined ? {} : definition.settings;
+    if (!settings || typeof settings !== 'object' || Array.isArray(settings)) {
+        problems.push('"settings" must be an object');
+    }
+    else {
+        for (const [key, spec] of Object.entries(settings)) {
+            problems.push(...settingProblems(key, spec));
+        }
+    }
+    return problems;
+}
+
+function settingProblems(key, spec) {
+    const label = `setting "${key}"`;
+    if (!SETTING_NAME.test(key)) {
+        return [`${label} must be a camelCase name`];
+    }
+    if (!spec || typeof spec !== 'object') {
+        return [`${label} must be an object`];
+    }
+    const problems = [];
+    const unknown = Object.keys(spec).filter((name) => !SETTING_KEYS.includes(name));
+    if (unknown.length) {
+        problems.push(`${label} has unknown keys: ${unknown.join(', ')}`);
+    }
+    const env = spec.env === undefined ? [] : [].concat(spec.env);
+    if (!env.every((name) => typeof name === 'string' && VARIABLE_NAME.test(name))) {
+        problems.push(`${label}: "env" must name upper-case environment variables`);
+    }
+    if (spec.type !== undefined && !SETTING_TYPES.includes(spec.type)) {
+        problems.push(`${label}: "type" must be one of ${SETTING_TYPES.join(', ')}`);
+    }
+    for (const flag of ['required', 'secret']) {
+        if (spec[flag] !== undefined && typeof spec[flag] !== 'boolean') {
+            problems.push(`${label}: "${flag}" must be true or false`);
+        }
+    }
+    if (spec.default !== undefined && typeof spec.default !== (spec.type || 'string')) {
+        problems.push(`${label}: "default" must be a ${spec.type || 'string'}`);
+    }
+    return problems;
+}
+
+/** Whether a value is a valid engine type definition, from this SDK or any other copy of it. */
+function isEngineType(value) {
+    return definitionProblems(value).length === 0;
+}
+
+/**
+ * Define an engine type. Validates the definition and returns it frozen, so a
+ * mistake in it fails when the package loads rather than when the UAG starts:
+ *
+ *   module.exports = defineEngine({
+ *       type: 'engine',
+ *       name: 'acme',
+ *       title: 'Acme',
+ *       version: '1.0.0',     // optional: an engine package's own version is used
+ *       kinds: ['agent'],
+ *       apiVersion: ENGINE_API_VERSION,
+ *       settings: { apiKey: { env: 'ACME_API_KEY', required: true, secret: true } },
+ *       create({ name, settings }) { return { name, kind: 'agent', model: '...', extract }; },
+ *   });
+ */
+function defineEngine(definition) {
+    const problems = definitionProblems(definition);
+    if (problems.length) {
+        const name = definition && typeof definition.name === 'string' ? definition.name : definition && typeof definition.type === 'string' && definition.type !== ENGINE_PLUGIN_TYPE ? definition.type : '';
+        throw new TypeError(`The engine type${name ? ` "${name}"` : ''} is not valid: ${problems.join('; ')}.`);
+    }
+    const settings = {};
+    for (const [key, spec] of Object.entries(definition.settings || {})) {
+        settings[key] = Object.freeze({ ...spec, ...(spec.env !== undefined && { env: Object.freeze([].concat(spec.env)) }) });
+    }
+    return Object.freeze({ ...definition, title: definition.title || definition.name, kinds: Object.freeze([...definition.kinds]), settings: Object.freeze(settings) });
+}
+
+/**
+ * A valid definition with its defaults: `title` is its name, and `version` the
+ * version of the package it was found in, when it does not give its own.
+ */
+function withDefaults(definition, packageVersion) {
+    if (definition.title && (definition.version || !packageVersion)) return definition;
+    const version = definition.version || packageVersion;
+    return { ...definition, title: definition.title || definition.name, ...(version && { version }) };
+}
+
+module.exports = { ENGINE_API_VERSION, ENGINE_NAME, ENGINE_PLUGIN_TYPE, KINDS, defineEngine, definitionProblems, definitionShape, isEngineType, withDefaults };

package/errors.js

@@ -0,0 +1,43 @@
+'use strict';
+
+/**
+ * An engine failure whose message is safe to show to API callers, such as
+ * "Quota exceeded for this API key". The UAG reports any other engine error only
+ * as "the engine failed (see the logs for request X)", because a provider SDK's
+ * error can carry URLs or account details.
+ */
+class EngineError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'EngineError';
+        Object.defineProperty(this, 'expose', { value: true, enumerable: true });
+    }
+}
+
+/**
+ * Thrown when an engine instance cannot be enabled. The message names the
+ * instance, and is what the operator reads when the UAG refuses to start.
+ */
+class EngineConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'EngineConfigError';
+    }
+}
+
+/** Shorter values are too likely to occur by chance to be worth redacting. */
+const MIN_SECRET_LENGTH = 4;
+
+/** `text` with every occurrence of each secret value replaced. */
+function redact(text, secrets) {
+    let result = String(text);
+    for (const secret of secrets || []) {
+        const value = secret === undefined || secret === null ? '' : String(secret);
+        if (value.length >= MIN_SECRET_LENGTH) {
+            result = result.split(value).join('[redacted]');
+        }
+    }
+    return result;
+}
+
+module.exports = { EngineError, EngineConfigError, redact };

package/helpers.js

@@ -0,0 +1,145 @@
+'use strict';
+const { EngineError } = require('./errors');
+
+/**
+ * Helpers shared by agent engines built on model APIs with structured outputs.
+ */
+
+/**
+ * The extraction schema with every field required, for strict structured
+ * outputs: providers limit how many optional properties and union types a
+ * strict schema may have, and OpenAI's strict mode needs every property in
+ * `required`. An empty value stands for "not stated": "" for text and options,
+ * [] for lists. Numbers and booleans travel as strings, keeping the field's
+ * title and description. `decode` maps an answer
+ * back to the UAG's schema, leaving the "not stated" fields out.
+ *
+ *   const { schema, decode } = requiredSchema(request.schema);
+ *   // ... ask the model for `schema` ...
+ *   return { model, values: decode(answer) };
+ */
+function requiredSchema(schema) {
+    const { schema: sent, decoders } = encodeObject(schema, false);
+    return { schema: sent, decode: (values) => decodeValues(values, decoders) };
+}
+
+function encodeObject(schema, nested) {
+    const properties = {};
+    const decoders = {};
+    for (const [path, property] of Object.entries((schema && schema.properties) || {})) {
+        const { sent, decode } = encodeProperty(property, nested);
+        properties[path] = sent;
+        if (decode) decoders[path] = decode;
+    }
+    return { schema: { ...schema, properties, required: Object.keys(properties) }, decoders };
+}
+
+function encodeProperty(property, nested) {
+    // Before the number and boolean cases, so a typed enum keeps its values.
+    if (Array.isArray(property.enum)) {
+        if (property.enum.every((value) => typeof value === 'string')) {
+            return { sent: { ...property, enum: [...new Set([...property.enum, ''])] } };
+        }
+        // Other values travel as their JSON text. A provider that does not
+        // enforce the schema may answer anything: only an allowed value is kept.
+        const { type, ...rest } = property;
+        const allowed = new Map(property.enum.map((value) => [JSON.stringify(value), value]));
+        return {
+            sent: { ...rest, type: 'string', enum: [...allowed.keys(), ''] },
+            decode: (value) => (allowed.has(value) ? allowed.get(value) : undefined),
+        };
+    }
+    if (property.type === 'number' || property.type === 'integer') {
+        return {
+            sent: { type: 'string', ...described(property, NUMBER_HINT) },
+            decode: parseNumber,
+        };
+    }
+    // Inside an object (select boxes) false already means "not selected".
+    if (property.type === 'boolean' && !nested) {
+        return {
+            sent: { enum: ['true', 'false', ''], ...described(property) },
+            decode: (value) => (value === 'true' || value === true ? true : value === 'false' || value === false ? false : undefined),
+        };
+    }
+    if (property.type === 'object' && property.properties) {
+        const inner = encodeObject(property, true);
+        return {
+            sent: inner.schema,
+            decode: (value) => {
+                const decoded = decodeValues(value, inner.decoders);
+                return Object.keys(decoded).length ? decoded : undefined;
+            },
+        };
+    }
+    return { sent: property };
+}
+
+const NUMBER_HINT = 'Answer in digits only, such as 4250 or -3.5, with no currency or units.';
+
+/** The field's title and description, which a string encoding would otherwise drop, with a hint. */
+function described(property, hint) {
+    const description = [property.description, hint].filter(Boolean).join(' ');
+    return { ...(property.title && { title: property.title }), ...(description && { description }) };
+}
+
+/**
+ * A number from a model's answer. Models write amounts as they read them
+ * ("$4,250"), so a currency sign and thousands separators are accepted;
+ * anything else that is not a plain number is "not stated".
+ */
+function parseNumber(value) {
+    if (typeof value === 'number') return Number.isFinite(value) ? value : undefined;
+    if (typeof value !== 'string') return undefined;
+    const match = /^\s*([+-])?\s*[$€£¥]?\s*(\d[\d,]*(?:\.\d+)?|\.\d+)\s*[$€£¥]?\s*$/.exec(value);
+    if (!match) return undefined;
+    const digits = match[2];
+    if (digits.includes(',') && !/^\d{1,3}(,\d{3})+(\.\d+)?$/.test(digits)) return undefined;
+    const number = Number(`${match[1] || ''}${digits.replace(/,/g, '')}`);
+    return Number.isFinite(number) ? number : undefined;
+}
+
+/** The answer without the empty "not stated" values, in the UAG's types. */
+function decodeValues(values, decoders) {
+    const decoded = {};
+    if (!values || typeof values !== 'object' || Array.isArray(values)) return decoded;
+    for (const [path, value] of Object.entries(values)) {
+        if (value === '' || value === null || (Array.isArray(value) && !value.length)) continue;
+        const result = decoders[path] ? decoders[path](value) : value;
+        if (result !== undefined) decoded[path] = result;
+    }
+    return decoded;
+}
+
+/**
+ * The first JSON object in a model's text answer, tolerating code fences and
+ * prose around it. Throws an `EngineError` when there is none.
+ */
+function parseJsonObject(text) {
+    const unfenced = String(text || '').replace(/```(?:json)?/gi, '');
+    const start = unfenced.indexOf('{');
+    const end = unfenced.lastIndexOf('}');
+    let parsed;
+    if (start !== -1 && end > start) {
+        try {
+            parsed = JSON.parse(unfenced.slice(start, end + 1));
+        }
+        catch {
+            parsed = undefined;
+        }
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new EngineError('The engine did not return a JSON object.');
+    }
+    return parsed;
+}
+
+/** A tool call's result as text for the model: its text blocks, other blocks as JSON. */
+function toolResultText(result) {
+    const text = ((result && result.content) || [])
+        .map((block) => (block && typeof block.text === 'string' ? block.text : JSON.stringify(block)))
+        .join('\n');
+    return text || '(no output)';
+}
+
+module.exports = { requiredSchema, decodeValues, parseJsonObject, toolResultText };

package/index.d.ts

@@ -0,0 +1,111 @@
+import type { Engine } from './contract';
+
+export * from './contract';
+
+/** Engine type and instance names: lowercase letters, digits and "-", starting with a letter. */
+export declare const ENGINE_NAME: RegExp;
+
+/** One setting an engine type reads. */
+export type SettingSpec = {
+    /** The type's own environment variables for the setting, read after `UAG_ENGINE_<NAME>_<SETTING>`. */
+    env?: string | readonly string[];
+    /** Startup fails, naming the instance and the variables, when no value is set. */
+    required?: boolean;
+    /** Kept out of startup errors and capability discovery. */
+    secret?: boolean;
+    default?: string | number | boolean;
+    /** Values from the environment are converted to this type. Default: "string". */
+    type?: 'string' | 'number' | 'boolean';
+    description?: string;
+};
+
+/** What an engine type's `create` receives for one instance. */
+export type EngineCreateContext<Settings = Record<string, any>> = {
+    /** The instance name. The engine must use it as its `name`. */
+    name: string;
+    /** The instance's value for each declared setting that has one. */
+    settings: Settings;
+    /** The instance's options as given in configuration, including ones that are not settings (such as a test client). */
+    options: Record<string, any>;
+    /** The host's configuration, read-only (for example routing timeouts). */
+    config: Record<string, any>;
+    /** A setting's value, or the standard "needs its setting" error, for settings required only in some cases. */
+    requireSetting(key: string): any;
+};
+
+/**
+ * What an engine package exports: a plugin of type "engine". The 2.0 release
+ * candidates' shape, with the engine's name in `type`, is refused.
+ */
+export interface EngineTypeDefinition<Settings = Record<string, any>> {
+    /** Always "engine": the plugin type. */
+    type: 'engine';
+    /** The type name, as in `UAG_ENGINES=<type>` and `<name>:<type>`. */
+    name: string;
+    /** A human-readable name. Defaults to `name`. */
+    title?: string;
+    /** The engine's own version (semver). Defaults to the version in its package's package.json. */
+    version?: string;
+    kinds: readonly ('decision' | 'agent')[];
+    /** The engine contract version the type was built for: `ENGINE_API_VERSION`. */
+    apiVersion: number;
+    description?: string;
+    settings?: Record<string, SettingSpec>;
+    create(context: EngineCreateContext<Settings>): Engine | Promise<Engine>;
+}
+
+/** Validate an engine type definition and return it frozen, its title defaulting to its name. Throws a TypeError naming every problem. */
+export declare function defineEngine<T extends EngineTypeDefinition<any>>(definition: T): Readonly<T>;
+
+/** Whether a value is a valid engine type definition, from this SDK, another copy of it, or none. */
+export declare function isEngineType(value: unknown): value is EngineTypeDefinition;
+
+/**
+ * An engine failure whose message is safe to show to API callers. Other engine
+ * errors are reported only as "the engine failed (see the logs for request X)".
+ */
+export declare class EngineError extends Error {
+    readonly expose: true;
+    constructor(message: string);
+}
+
+/** An engine instance that cannot be enabled. The message names the instance. */
+export declare class EngineConfigError extends Error {
+    constructor(message: string);
+}
+
+/** `text` with each secret value replaced by "[redacted]". */
+export declare function redact(text: unknown, secrets: unknown[]): string;
+
+/** An engine instance to enable. `name` is undefined until loading when only a package or definition was given. */
+export type EngineInstanceSpec = {
+    name?: string;
+    type: string | EngineTypeDefinition;
+    options?: Record<string, any>;
+};
+
+/** Parse a `UAG_ENGINES` string (`jev,fast:claude`) or a configuration list. Nothing named means none. */
+export declare function parseInstances(source: string | (string | EngineInstanceSpec)[] | undefined | null): EngineInstanceSpec[];
+
+/** The instances from configuration (`engines`) when it lists them, otherwise from `UAG_ENGINES`. */
+export declare function engineInstances(config?: Record<string, any>, env?: Record<string, string | undefined>): EngineInstanceSpec[];
+
+/** An instance's own variable for a setting: `UAG_ENGINE_<NAME>_<SETTING>`. */
+export declare function settingVariable(instance: string, setting: string): string;
+
+/** An instance's settings: options, then `UAG_ENGINE_<NAME>_<SETTING>`, then the type's variables, then the default. */
+export declare function resolveSettings(definition: EngineTypeDefinition, name: string, options?: Record<string, any>, env?: Record<string, string | undefined>): Record<string, any>;
+
+/**
+ * The extraction schema with every field required, for strict structured
+ * outputs, and `decode`, which maps an answer back to the UAG's schema.
+ */
+export declare function requiredSchema(schema: Record<string, any>): { schema: Record<string, any>; decode(values: unknown): Record<string, any> };
+
+export declare function decodeValues(values: unknown, decoders: Record<string, (value: any) => any>): Record<string, any>;
+
+/** The first JSON object in a model's text answer. Throws an `EngineError` when there is none. */
+export declare function parseJsonObject(text: string): Record<string, any>;
+
+/** A tool call's result as text for a model. */
+export declare function toolResultText(result: { content?: { type: string; text?: string; [key: string]: any }[] }): string;