@formio/uag-sdk 2.0.0-rc.7 → 2.0.0-rc.9

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:
 
@@ -154,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/loader.d.ts

@@ -53,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

@@ -223,4 +223,50 @@ async function loadEngines(instances, { types = {}, paths = [], env = process.en
     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.7",
+  "version": "2.0.0-rc.9",
   "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",