@formio/uag-sdk 2.0.0-rc.1 → 2.0.0-rc.10

package/README.md

@@ -1,6 +1,6 @@
 # @formio/uag-sdk
 
-<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>
+<sub>[Form.io UAG](https://github.com/formio/uag/blob/v2.0.0-rc.8/README.md) &rsaquo; [Engines](https://github.com/formio/uag/blob/v2.0.0-rc.8/README.md#engines-and-routing) &rsaquo; this page</sub>
 
 Build engine packages for the Form.io Universal Agent Gateway (UAG). This package contains:
 
@@ -15,13 +15,15 @@ An engine package depends on this package only. It never needs `@formio/uag`.
 
 ## An engine package
 
-Name the package `@formio/uag-<type>` (official engines) or `uag-engine-<type>` (anyone's). Export one engine type definition:
+Name the package `@formio/uag-<type>` (official engines) or `uag-engine-<type>` (anyone's). Export one engine type definition. It is a plugin of type `"engine"`: `name` is the type name used in `UAG_ENGINES`, `title` (default: `name`) is shown to people, and `version` defaults to your package's own version:
 
 ```js
 const { defineEngine, EngineError, ENGINE_API_VERSION, requiredSchema } = require('@formio/uag-sdk');
 
 module.exports = defineEngine({
-    type: 'acme',
+    type: 'engine',
+    name: 'acme',
+    title: 'Acme',
     kinds: ['agent'],
     apiVersion: ENGINE_API_VERSION,
     settings: {
@@ -50,6 +52,23 @@ module.exports = defineEngine({
 
 The engine must use the instance `name` it is given, and one of the `kinds` it declares. A decision engine has `decide` and `maxOptions`; an agent engine has `extract`, and sets `toolUse: true` when `extract` accepts read-only research tools. See `contract.d.ts` for every request and response.
 
+A definition in the shape of the 2.0 release candidates, with the engine's name in `type` (`{ type: 'acme', kinds, ... }`), is refused with a message showing the shape above.
+
+### Generating text over documents
+
+An agent engine may also implement `generate(request)`, which document plugins call to write free text over uploaded documents, and declare `accepts`, the document kinds it reads natively (default `['text']`; list `'pdf'` only when your model reads PDFs as documents):
+
+```js
+accepts: ['text', 'pdf'],
+async generate({ instructions, system, attachments, format, maxTokens, signal, onProgress }) {
+    // attachments: { kind: 'pdf', data: Buffer, label, pages? } or { kind: 'text', text, label, textFormat? }
+    // Put the documents before the instructions; report progress as the answer streams.
+    return { text, model, stopReason: 'end' /* or 'max_tokens' when cut off */, usage };
+},
+```
+
+`generate` must honour `signal`, never log the documents, and report a truncated answer as `stopReason: 'max_tokens'` rather than failing.
+
 `create` receives `{ name, settings, options, config, requireSetting }`:
 
 - `settings`: the instance's value for each declared setting that has one.
@@ -135,8 +154,9 @@ The check creates an instance and calls it. Pass options, such as a fake client,
 - the definition and the engine have the contract's shape;
 - the engine uses the instance name and the `model` option;
 - `extract` returns only the fields it was asked about, or `decide` only the questions it was asked;
+- `accepts`, when set, lists only `text` and `pdf`; `generate`, when present, returns text, its model and a valid `stopReason`;
 - research stops at `maxIterations`, and reports every tool call it made;
-- an aborted signal stops the engine, including during research.
+- an aborted signal stops the engine, including during research and `generate`.
 
 A research round is the calls a model makes together; calls made one after another count as separate rounds.
 

package/conformance.js

@@ -206,6 +206,35 @@ async function checkEngine(definition, { name = 'conformance', options = {}, env
             controller.abort();
             await within(timeout, rejects(engine.extract(extractRequest({ signal: controller.signal })), 'extract with an aborted signal'), 'extract with an aborted signal');
         });
+        await check('accepts lists only known document kinds', () => {
+            if (engine.accepts === undefined) return;
+            if (!Array.isArray(engine.accepts) || !engine.accepts.length) fail('accepts must be a non-empty list of "text" and "pdf"');
+            const unknown = engine.accepts.filter((kind) => !['text', 'pdf'].includes(kind));
+            if (unknown.length) fail(`accepts lists unknown kinds: ${unknown.join(', ')}`);
+        });
+        if (typeof engine.generate === 'function') {
+            await check('generate returns text, its model and a valid stopReason', async () => {
+                const response = await within(timeout, engine.generate({
+                    instructions: 'Summarize the attached document in one sentence.',
+                    attachments: [{ kind: 'text', text: 'Ada Lovelace lives in London and works on engines.', label: 'Document 1: notes.txt', textFormat: 'plain' }],
+                    format: 'markdown',
+                    maxTokens: 200,
+                }), 'generate');
+                if (!response || typeof response !== 'object') fail('generate did not return an object');
+                if (typeof response.text !== 'string') fail('the response has no text');
+                if (typeof response.model !== 'string' || !response.model) fail('the response does not name its model');
+                if (!['end', 'max_tokens'].includes(response.stopReason)) fail(`stopReason must be "end" or "max_tokens", not ${JSON.stringify(response.stopReason)}`);
+                checkUsage(response);
+            });
+            await check('generate stops when its signal is aborted', async () => {
+                const controller = new AbortController();
+                controller.abort();
+                await within(timeout, rejects(engine.generate({ instructions: 'Summarize.', format: 'text', signal: controller.signal }), 'generate with an aborted signal'), 'generate with an aborted signal');
+            });
+        }
+        else if (engine.generate !== undefined) {
+            await check('generate is a function', () => fail('generate must be a function when present'));
+        }
         if (engine.toolUse) {
             await check('research reports its tool calls and stops at maxIterations', async () => {
                 const { state, callTool } = lookupTool();

package/contract.d.ts

@@ -185,5 +185,39 @@ export interface AgentEngine {
     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

@@ -6,6 +6,14 @@ 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_]*$/;
@@ -18,8 +26,23 @@ function definitionProblems(definition) {
         return ['it is not an object'];
     }
     const problems = [];
-    if (typeof definition.type !== 'string' || !ENGINE_NAME.test(definition.type)) {
-        problems.push('"type" must be a name of lowercase letters, digits and "-", starting with a letter');
+    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');
@@ -83,7 +106,10 @@ function isEngineType(value) {
  * mistake in it fails when the package loads rather than when the UAG starts:
  *
  *   module.exports = defineEngine({
- *       type: 'acme',
+ *       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 } },
@@ -93,14 +119,24 @@ function isEngineType(value) {
 function defineEngine(definition) {
     const problems = definitionProblems(definition);
     if (problems.length) {
-        const type = definition && typeof definition.type === 'string' ? ` "${definition.type}"` : '';
-        throw new TypeError(`The engine type${type} is not valid: ${problems.join('; ')}.`);
+        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, kinds: Object.freeze([...definition.kinds]), settings: Object.freeze(settings) });
+    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, KINDS, defineEngine, definitionProblems, isEngineType };
+module.exports = { ENGINE_API_VERSION, ENGINE_NAME, ENGINE_PLUGIN_TYPE, KINDS, defineEngine, definitionProblems, definitionShape, isEngineType, withDefaults };

package/index.d.ts

@@ -33,10 +33,19 @@ export type EngineCreateContext<Settings = Record<string, any>> = {
     requireSetting(key: string): any;
 };
 
-/** What an engine package exports. */
+/**
+ * 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>`. */
-    type: string;
+    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;
@@ -45,7 +54,7 @@ export interface EngineTypeDefinition<Settings = Record<string, any>> {
     create(context: EngineCreateContext<Settings>): Engine | Promise<Engine>;
 }
 
-/** Validate an engine type definition and return it frozen. Throws a TypeError naming every problem. */
+/** 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. */

package/loader.d.ts

@@ -15,7 +15,14 @@ export type LoadOptions = {
 /** 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;
 };
@@ -46,3 +53,15 @@ export declare function createEngine(definition: EngineTypeDefinition, options:
 
 /** 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

@@ -1,7 +1,7 @@
 'use strict';
 const fs = require('fs');
 const path = require('path');
-const { ENGINE_API_VERSION, definitionProblems } = require('./define');
+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');
@@ -87,19 +87,22 @@ 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. */
-function checkDefinition(definition, source, apiVersion) {
+/**
+ * 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.type}") was built for engine API version ${definition.apiVersion}; ` +
+            `${source} (engine type "${definition.name}") was built for engine API version ${definition.apiVersion}; ` +
             `this server supports version ${apiVersion}.`
         );
     }
-    return definition;
+    return withDefaults(definition, packageVersion);
 }
 
 /**
@@ -130,7 +133,7 @@ function resolveType(type, { types = {}, paths = [], apiVersion = ENGINE_API_VER
         }
         const definition = exported && exported.__esModule && exported.default ? exported.default : exported;
         return {
-            definition: checkDefinition(definition, `The package "${candidate}"`, apiVersion),
+            definition: checkDefinition(definition, `The package "${candidate}"`, apiVersion, pkg.version),
             package: candidate,
             ...(pkg.version && { version: pkg.version })
         };
@@ -165,7 +168,7 @@ function checkVariables(resolved) {
  * 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.type}")`;
+    const label = `The "${name}" engine (type "${definition.name}")`;
     const settings = resolveSettings(definition, name, options, env);
     const secrets = secretValues(definition, settings, options);
     let engine;
@@ -206,7 +209,7 @@ async function createEngine(definition, { name, options = {}, env = process.env,
 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.type;
+        const name = instance.name || found.definition.name;
         checkName(name);
         return { ...found, name, options: instance.options || {} };
     });
@@ -215,9 +218,55 @@ async function loadEngines(instances, { types = {}, paths = [], env = process.en
     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.type, ...(pkg && { package: pkg }), ...(version && { version }) });
+        loaded.push({ engine, type: definition.name, title: definition.title, kinds: [...definition.kinds], ...(definition.version && { typeVersion: definition.version }), ...(pkg && { package: pkg }), ...(version && { version }) });
     }
     return loaded;
 }
 
-module.exports = { enginePaths, packageCandidates, resolveType, createEngine, loadEngines };
+/**
+ * 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,6 @@
 {
   "name": "@formio/uag-sdk",
-  "version": "2.0.0-rc.1",
+  "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",

package/protocol.d.ts

@@ -1,4 +1,4 @@
-import type { DecisionQuestion, DecisionResponse, DecisionState, ExtractResponse, FieldSpec, ToolDefinition } from './contract';
+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;
@@ -25,8 +25,20 @@ export type RemoteEngineDescription = {
     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;
@@ -42,4 +54,8 @@ 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 };

package/protocol.js

@@ -26,6 +26,14 @@ const SCOPED_TOKEN_HEADER = 'x-uag-scoped-token';
 const REQUEST_ID_HEADER = 'x-request-id';
 const REQUEST_ID = /^[A-Za-z0-9._:-]{1,128}$/;
 
+/**
+ * The most PDF bytes one generate request carries: the provider request cap
+ * the UAG's documents.maxTotalBytes stays within (32 MB).
+ */
+const MAX_DOCUMENT_BYTES = 32 * 1024 * 1024;
+const DOCUMENT_KINDS = ['text', 'pdf'];
+const TEXT_FORMATS = ['plain', 'markdown', 'csv'];
+
 /** A request id that is safe to send and log: up to 128 letters, digits, `.`, `_`, `:` or `-`. Anything else is undefined. */
 function safeRequestId(value) {
     return typeof value === 'string' && REQUEST_ID.test(value) ? value : undefined;
@@ -102,16 +110,83 @@ function checkDescription(body) {
         if (engine.kind === 'decision') {
             check(Number.isInteger(engine.maxOptions) && engine.maxOptions >= 2, `The decision engine "${engine.name}" needs maxOptions.`);
         }
+        if (engine.kind === 'agent' && engine.accepts !== undefined) {
+            check(Array.isArray(engine.accepts) && engine.accepts.length && engine.accepts.every((kind) => DOCUMENT_KINDS.includes(kind)),
+                `The engine "${engine.name}" must list "text" and "pdf" only in "accepts".`);
+        }
         return {
             name: engine.name,
             kind: engine.kind,
             model: engine.model,
             ...(engine.kind === 'decision' && { maxOptions: engine.maxOptions }),
-            ...(engine.kind === 'agent' && { toolUse: engine.toolUse === true }),
+            ...(engine.kind === 'agent' && {
+                toolUse: engine.toolUse === true,
+                accepts: engine.accepts || ['text'],
+                generate: engine.generate === true,
+            }),
         };
     });
 }
 
+/**
+ * A generate request, as an engine server receives it. PDF attachments arrive
+ * as base64 and are returned as Buffers; their decoded total may not exceed
+ * `maxBytes`.
+ */
+function checkGenerateRequest(body, maxBytes = MAX_DOCUMENT_BYTES) {
+    checkVersion(body);
+    check(typeof body.instructions === 'string', '"instructions" must be a string.');
+    check(body.system === undefined || typeof body.system === 'string', '"system" must be a string.');
+    check(['markdown', 'text'].includes(body.format), '"format" must be "markdown" or "text".');
+    check(body.maxTokens === undefined || (Number.isInteger(body.maxTokens) && body.maxTokens > 0), '"maxTokens" must be a positive whole number.');
+    check(body.attachments === undefined || Array.isArray(body.attachments), '"attachments" must be a list.');
+    let pdfBytes = 0;
+    const attachments = (body.attachments || []).map((attachment, i) => {
+        const where = `Attachment ${i + 1}`;
+        check(isObject(attachment) && typeof attachment.label === 'string', `${where} needs a label.`);
+        if (attachment.kind === 'pdf') {
+            check(typeof attachment.data === 'string', `${where} must carry its PDF as base64 "data".`);
+            check(attachment.pages === undefined || (Number.isInteger(attachment.pages) && attachment.pages >= 0), `${where} "pages" must be a whole number.`);
+            const data = Buffer.from(attachment.data, 'base64');
+            pdfBytes += data.length;
+            check(pdfBytes <= maxBytes, `The attached PDFs exceed ${maxBytes} bytes.`, 413);
+            return { kind: 'pdf', data, label: attachment.label, ...(attachment.pages !== undefined && { pages: attachment.pages }) };
+        }
+        check(attachment.kind === 'text' && typeof attachment.text === 'string', `${where} must be a "pdf" or "text" attachment.`);
+        check(attachment.textFormat === undefined || TEXT_FORMATS.includes(attachment.textFormat), `${where} "textFormat" must be plain, markdown or csv.`);
+        return { kind: 'text', text: attachment.text, label: attachment.label, ...(attachment.textFormat && { textFormat: attachment.textFormat }) };
+    });
+    return {
+        instructions: body.instructions,
+        ...(body.system !== undefined && { system: body.system }),
+        attachments,
+        format: body.format,
+        ...(body.maxTokens !== undefined && { maxTokens: body.maxTokens }),
+    };
+}
+
+/** Attachments for the wire: PDF bytes as base64. Never logged. */
+function encodeAttachments(attachments = []) {
+    return attachments.map((attachment) => attachment.kind === 'pdf'
+        ? { kind: 'pdf', data: Buffer.from(attachment.data).toString('base64'), label: attachment.label, ...(attachment.pages !== undefined && { pages: attachment.pages }) }
+        : { kind: 'text', text: attachment.text, label: attachment.label, ...(attachment.textFormat && { textFormat: attachment.textFormat }) });
+}
+
+/** The decoded size of the PDFs among attachments. */
+function pdfByteLength(attachments = []) {
+    return attachments.reduce((total, attachment) => total + (attachment.kind === 'pdf' ? Buffer.byteLength(attachment.data) : 0), 0);
+}
+
+/** A generate response, as the UAG receives it. */
+function checkGenerateResponse(body) {
+    checkVersion(body, 'response');
+    check(typeof body.text === 'string', 'The response has no "text".');
+    check(typeof body.model === 'string', 'The response does not name its model.');
+    check(['end', 'max_tokens'].includes(body.stopReason), '"stopReason" must be "end" or "max_tokens".');
+    const usage = checkUsage(body.usage);
+    return { text: body.text, model: body.model, stopReason: body.stopReason, ...(usage && { usage }) };
+}
+
 /** A token count: a whole number, or null when not reported. */
 function tokenCount(value, key) {
     if (value === undefined || value === null) return null;
@@ -185,5 +260,10 @@ module.exports = {
     checkDescription,
     checkDecisionResponse,
     checkExtractResponse,
+    checkGenerateRequest,
+    checkGenerateResponse,
+    encodeAttachments,
+    pdfByteLength,
+    MAX_DOCUMENT_BYTES,
     errorBody,
 };

package/settings.js

@@ -81,7 +81,7 @@ function resolveSettings(definition, name, options = {}, env = process.env) {
 function missingSetting(definition, name, key) {
     const spec = (definition.settings || {})[key] || {};
     return new EngineConfigError(
-        `The "${name}" engine (type "${definition.type}") needs its ${key} setting: set ${listNames(settingVariables(name, key, spec))}.`
+        `The "${name}" engine (type "${definition.name}") needs its ${key} setting: set ${listNames(settingVariables(name, key, spec))}.`
     );
 }