@simmalugnt-se/payload-editor-assistant 0.14.1 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.15.0
+
+- Extensions: other packages, or the project, give the assistant tools, instructions and
+  descriptions of their Admin views through `config.custom.editorAssistantExtensions`. Off until
+  the host names them in the new `extensions` option. Extension tools only read; their input is
+  checked, their answers bounded and every call audited. See "Extensions" in the README.
+- Admin views outside collections and globals are `{ kind: "custom", path }` instead of `other` in
+  the panel, so a shortcut with `when: ["other"]` no longer shows there.
+- The built-in tools are modules in one registry; what the model is given is unchanged.
+
+- Upload and relationship fields for several collections, such as an image or a video, take one of
+  them. Before, any draft or change touching such a field was refused, even when it left the field
+  empty: a new page with a hero could not be created.
+
 ## 0.14.1
 
 - npm links to simmalugnt.se instead of the private source repository.

package/README.md

@@ -94,7 +94,7 @@ alt text, which the editor keeps or undoes like any other change:
 
 ```ts
 collections: {
-  media: { capabilities: ["form.read", "form.propose", "media.view"] },
+  images: { capabilities: ["form.read", "form.propose", "media.view"] },
 },
 ```
 
@@ -110,7 +110,7 @@ candidates at a time (12 per turn) and proposes one it has seen, or says none fi
 
 ```ts
 collections: {
-  media: { capabilities: ["content.find", "form.read", "form.propose", "media.view"] },
+  images: { capabilities: ["content.find", "form.read", "form.propose", "media.view"] },
 },
 ```
 
@@ -182,6 +182,23 @@ prompt as a task, and the editor starts it. A link alone never makes the assista
 The plugin publishes its allowlisted collections as `config.admin.custom.editorAssistant.collections`
 so the work list knows where to offer it; the packages do not import each other.
 
+### Asking about content health
+
+With content health's extension turned on, the assistant reads the findings itself: "what should I
+fix first?" on the dashboard, or "what is wrong with this page?" on a document, gets an answer about
+real pages, and it can take the editor to the work list or to "Fix N with the assistant" for one
+check. The editor still starts each fix.
+
+```ts
+editorAssistantPlugin({
+  extensions: { "content-health": true },
+  // ...
+});
+```
+
+Needs `@simmalugnt-se/payload-content-health` 0.8.0 or later. See
+[Extensions](#extensions) for how other packages add abilities.
+
 ## Batches
 
 With `content.update` on a collection, content health's work list offers "Fix N with the assistant"
@@ -192,7 +209,7 @@ assistant's panel in batch mode beside the list, with up to 20 documents:
 ```ts
 collections: {
   pages: { capabilities: ["content.findById", "form.read", "form.propose", "content.update"] },
-  media: { capabilities: ["content.findById", "form.read", "form.propose", "media.view", "content.update"] },
+  images: { capabilities: ["content.findById", "form.read", "form.propose", "media.view", "content.update"] },
 },
 ```
 
@@ -206,7 +223,7 @@ collections: {
 - Nothing is written until **Save N selected**. Checked proposals are saved one by one, each checked
   again on the server: the editor, the one-time approval, `content.update`, the document's lock, and
   that the saved document has not changed since the proposal (otherwise the card says so and
-  nothing is written). A collection with drafts gets a draft; one without, such as media, is saved
+  nothing is written). A collection with drafts gets a draft; one without, such as images, is saved
   directly, and the card says which. Unchecked proposals are rejected.
 - The audit collection logs every document with `requestId: "batch:<id>"`. When the editor
   reworded a value, the executed event's `canonicalHash` differs from the proposed one's.
@@ -258,8 +275,59 @@ chat** clears the current one.
 | `validateProposal` | `({ operations, data }) => ({ ok: true } \| { ok: false, errors })` for project rules. Runs before a proposal reaches the editor; errors go back to the assistant, which can correct itself. |
 | `trustedOrigins` | Origins allowed to call the assistant's endpoints. Default: only the origin serving Admin. When set, only the listed origins. |
 | `audit.collection` | Slug of the collection that logs assistant actions (default `editor-assistant-audit`). |
+| `extensions` | Abilities other packages add, turned on by id: `{ "content-health": true }`, or `{ tools: [...] }` for some of an extension's tools. Off until named. See [Extensions](#extensions). |
 | `disabled` | Turn the plugin off without removing its config. |
 
+## Extensions
+
+Another package, or the project itself, gives the assistant abilities with an extension: short
+instructions for the prompt, tools the model may call, and descriptions of Admin views it owns. It
+registers the extension in `config.custom.editorAssistantExtensions` from its own plugin, without
+importing this package, and the host turns it on with `extensions`. Content health is the example
+(`packages/payload-content-health/src/assistant.ts`).
+
+```ts
+import type { AssistantExtension } from "@simmalugnt-se/payload-editor-assistant";
+
+const notes: AssistantExtension = {
+  id: "site-notes",
+  instructions: "Site notes say what editors must remember. Read them with site-notes.list.",
+  views: [{ path: "/site-notes", description: "The editor is on the site notes page." }],
+  tools: [
+    {
+      name: "site-notes.list",
+      description: "Lists the site's notes, newest first.",
+      input: { type: "object", additionalProperties: false, properties: {} },
+      risk: "auto",
+      run: async (_input, { req }) => {
+        const { docs } = await req.payload.find({
+          collection: "notes",
+          overrideAccess: false,
+          user: req.user,
+        });
+        return { ok: true, data: docs.map((doc) => doc.text) };
+      },
+    },
+  ],
+};
+
+// In a plugin: (config) => ({ ...config, custom: { ...config.custom,
+//   editorAssistantExtensions: [...(config.custom?.editorAssistantExtensions ?? []), notes] } })
+```
+
+- **Tools only read** for now (`risk: "auto"`): changes go through the assistant's own proposals.
+  `run` gets the editor's request; read with `overrideAccess: false`.
+- Tool names start with the extension id and a dot. The input is checked against `input` (an object
+  schema: strings, numbers, booleans, arrays, `enum`, `required`) before `run`.
+- The answer is quoted to the model as data and cut at 12 000 characters. A thrown error becomes a
+  failure the model reports. Every call is written to the audit collection.
+- `navigate` in a result takes the editor to that place in Admin, as the assistant's own navigation
+  does.
+- `views` describe Admin views by path; `"/"` adds to what the assistant knows about the dashboard.
+- Extension tools are not offered in a batch, which stays on its one document.
+- At startup the assistant warns about invalid extensions and about ids the host named that no
+  package registered.
+
 ## Reference images in chat
 
 Use **Add images**, drop images on the assistant panel, or paste a screenshot into the message.

package/dist/config/validate.d.ts

@@ -9,5 +9,6 @@ export type ValidatedEditorAssistantOptions = EditorAssistantPluginOptions & {
     audit: {
         collection: string;
     };
+    extensions: NonNullable<EditorAssistantPluginOptions["extensions"]>;
 };
 export declare function validateEditorAssistantOptions(options: EditorAssistantPluginOptions): ValidatedEditorAssistantOptions;

package/dist/config/validate.js

@@ -10,6 +10,7 @@ export function validateEditorAssistantOptions(options) {
         }
         validateEntityMap("collections", collections, { allowDraftCreate: true });
         validateEntityMap("globals", globals, { allowDraftCreate: false });
+        validateExtensions(options.extensions);
     }
     return {
         ...options,
@@ -22,8 +23,17 @@ export function validateEditorAssistantOptions(options) {
         audit: {
             collection: options.audit?.collection ?? "editor-assistant-audit",
         },
+        extensions: options.extensions ?? {},
     };
 }
+function validateExtensions(extensions) {
+    for (const [id, setting] of Object.entries(extensions ?? {})) {
+        const tools = setting === true ? [] : setting?.tools;
+        if (!Array.isArray(tools) || tools.some((tool) => typeof tool !== "string")) {
+            throw new Error(`payload-editor-assistant: extensions "${id}" must be true or { tools: string[] }.`);
+        }
+    }
+}
 function validateEntityMap(kind, map, rules) {
     for (const [slug, entry] of Object.entries(map)) {
         if (kind === "collections" && isDeniedCollectionSlug(slug)) {

package/dist/endpoints/chat.js

@@ -1,4 +1,5 @@
 import { imageByteLength, isChatImage, MAX_CHAT_IMAGES, MAX_CHAT_IMAGES_BYTES, } from "../chat-images.js";
+import { enabledExtensions } from "../extensions/resolve.js";
 import { ENDPOINT_PREFIX } from "../package-name.js";
 import { runAgentTurn } from "../runtime/agent.js";
 import { beginInflight, endInflight } from "../runtime/inflight.js";
@@ -68,7 +69,7 @@ export function createChatEndpoint(options) {
                         locale,
                         language,
                         uiLanguage: nonEmpty(body.uiLanguage)?.startsWith("sv") ? "sv" : "en",
-                        view: sanitizeAdminView(body.view, options),
+                        view: sanitizeAdminView(body.view, options, enabledExtensions(req.payload.config, options).flatMap((extension) => extension.views.map((view) => view.path))),
                         selection: typeof body.selection === "string" ? body.selection : undefined,
                         openProposal: sanitizeOpenProposal(body.openProposal),
                     },

package/dist/extensions/contract.d.ts

@@ -0,0 +1,62 @@
+import type { PayloadRequest } from "payload";
+/**
+ * Other packages give the assistant abilities through `config.custom[EXTENSIONS_CUSTOM_KEY]`, an
+ * array of extensions, without importing it. Copied in each package that contributes one; the
+ * contract tests compare the copies. The host turns each on with the plugin's `extensions` option.
+ */
+export declare const EXTENSIONS_CUSTOM_KEY = "editorAssistantExtensions";
+export type AssistantExtension = {
+    /** Unique, kebab-case: "content-health". Its tool names start with it and a dot. */
+    id: string;
+    /** Added to the prompt while the extension is on. Cannot override the assistant's rules. */
+    instructions?: string;
+    /**
+     * Admin views the extension owns, by path under the admin route ("/content-health"), and what
+     * the editor sees there. "/" is the dashboard: its description adds to the dashboard's.
+     */
+    views?: AssistantExtensionView[];
+    tools?: AssistantExtensionTool[];
+};
+export type AssistantExtensionView = {
+    path: string;
+    description: string;
+};
+export type AssistantExtensionTool = {
+    /** "content-health.findings": the extension id, a dot, then letters, digits or dashes. */
+    name: string;
+    /** When to use it and what it returns, written for the model: it chooses tools by this text. */
+    description: string;
+    /** JSON Schema of the input, an object; checked before `run` (see `input.ts` for the subset). */
+    input: Record<string, unknown>;
+    /** Only reads for now: the tool runs without the editor's decision. */
+    risk: "auto";
+    /** Runs on the server for the signed-in editor; read with their access (`overrideAccess: false`). */
+    run: (input: Record<string, unknown>, context: AssistantExtensionContext) => Promise<AssistantExtensionResult>;
+};
+export type AssistantExtensionContext = {
+    /** The editor's request: user, payload, locale. Shared by every tool call in one turn. */
+    req: PayloadRequest;
+    /** Where the editor is: "/" for the dashboard, else the path under the admin route, if known. */
+    path?: string;
+    /** The open document or global, when there is one. */
+    open?: {
+        collection?: string;
+        global?: string;
+        id?: string | number;
+        locale: string;
+    };
+};
+export type AssistantExtensionResult = {
+    ok: true;
+    /** What the model reads: compact, structured, quoted to it as data. */
+    data: unknown;
+    /** A place in Admin to take the editor to: the panel opens it, as with `admin.navigate`. */
+    navigate?: {
+        href: string;
+        label: string;
+    };
+} | {
+    ok: false;
+    error: string;
+    message: string;
+};

package/dist/extensions/contract.js

@@ -0,0 +1,6 @@
+/**
+ * Other packages give the assistant abilities through `config.custom[EXTENSIONS_CUSTOM_KEY]`, an
+ * array of extensions, without importing it. Copied in each package that contributes one; the
+ * contract tests compare the copies. The host turns each on with the plugin's `extensions` option.
+ */
+export const EXTENSIONS_CUSTOM_KEY = "editorAssistantExtensions";

package/dist/extensions/input.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Checks a tool's input against the subset of JSON Schema that extension tools use: an object with
+ * `properties`, `required` and `additionalProperties: false`; values of type string, number, integer,
+ * boolean or array (with `items` of such a type), with `enum`, `minimum`, `maximum` and `maxItems`.
+ * Returns a sentence for the model, or null when the input fits.
+ */
+export declare function inputError(schema: Record<string, unknown>, input: unknown): string | null;

package/dist/extensions/input.js

@@ -0,0 +1,81 @@
+/**
+ * Checks a tool's input against the subset of JSON Schema that extension tools use: an object with
+ * `properties`, `required` and `additionalProperties: false`; values of type string, number, integer,
+ * boolean or array (with `items` of such a type), with `enum`, `minimum`, `maximum` and `maxItems`.
+ * Returns a sentence for the model, or null when the input fits.
+ */
+export function inputError(schema, input) {
+    if (!isRecord(input))
+        return "The input must be an object.";
+    const properties = isRecord(schema.properties) ? schema.properties : {};
+    const required = Array.isArray(schema.required) ? schema.required : [];
+    for (const name of required) {
+        if (input[name] === undefined || input[name] === null)
+            return `"${name}" is required.`;
+    }
+    for (const [name, value] of Object.entries(input)) {
+        if (value === undefined || value === null)
+            continue;
+        const property = properties[name];
+        if (!isRecord(property)) {
+            if (schema.additionalProperties === false)
+                return `"${name}" is not an input of this tool.`;
+            continue;
+        }
+        const error = valueError(name, property, value);
+        if (error)
+            return error;
+    }
+    return null;
+}
+function valueError(name, schema, value) {
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+    if (!types.some((type) => typeMatches(type, value))) {
+        return `"${name}" must be ${types.filter(Boolean).join(" or ")}.`;
+    }
+    if (Array.isArray(schema.enum) && !schema.enum.includes(value)) {
+        return `"${name}" must be one of ${schema.enum.map((option) => JSON.stringify(option)).join(", ")}.`;
+    }
+    if (typeof value === "number") {
+        if (typeof schema.minimum === "number" && value < schema.minimum) {
+            return `"${name}" must be at least ${schema.minimum}.`;
+        }
+        if (typeof schema.maximum === "number" && value > schema.maximum) {
+            return `"${name}" must be at most ${schema.maximum}.`;
+        }
+    }
+    if (Array.isArray(value)) {
+        if (typeof schema.maxItems === "number" && value.length > schema.maxItems) {
+            return `"${name}" takes at most ${schema.maxItems} items.`;
+        }
+        if (isRecord(schema.items)) {
+            for (const item of value) {
+                const error = valueError(`${name} item`, schema.items, item);
+                if (error)
+                    return error;
+            }
+        }
+    }
+    return null;
+}
+function typeMatches(type, value) {
+    switch (type) {
+        case "string":
+            return typeof value === "string";
+        case "number":
+            return typeof value === "number" && Number.isFinite(value);
+        case "integer":
+            return Number.isInteger(value);
+        case "boolean":
+            return typeof value === "boolean";
+        case "array":
+            return Array.isArray(value);
+        case undefined:
+            return true;
+        default:
+            return false;
+    }
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}

package/dist/extensions/resolve.d.ts

@@ -0,0 +1,27 @@
+import type { SanitizedConfig } from "payload";
+import type { ValidatedEditorAssistantOptions } from "../config/validate.ts";
+import type { AssistantTool } from "../runtime/capabilities/tool.ts";
+import type { AdminView } from "../view.ts";
+import { type AssistantExtensionView } from "./contract.ts";
+/** What the model reads from one extension tool call, at most; longer answers are cut. */
+export declare const MAX_RESULT_CHARACTERS = 12000;
+/** An extension the host turned on, with its tools in the assistant's own shape. */
+export type ResolvedExtension = {
+    id: string;
+    instructions?: string;
+    views: AssistantExtensionView[];
+    tools: AssistantTool[];
+};
+/** The extensions packages registered, valid or not; reading the config never throws. */
+export declare function registeredExtensions(config: Pick<SanitizedConfig, "custom">): unknown[];
+/** Why a registered extension cannot be used, or null. */
+export declare function extensionProblem(value: unknown): string | null;
+/**
+ * Problems to report at startup: registered extensions that are invalid, and extensions the host
+ * named that no package registered, or tools it named that the extension does not have.
+ */
+export declare function extensionWarnings(config: Pick<SanitizedConfig, "custom">, options: Pick<ValidatedEditorAssistantOptions, "extensions">): string[];
+/** The extensions the host turned on, valid ones only, with the tools it allowed. */
+export declare function enabledExtensions(config: Pick<SanitizedConfig, "custom">, options: ValidatedEditorAssistantOptions): ResolvedExtension[];
+/** The editor's place in Admin as a path under the admin route. */
+export declare function viewPath(view?: AdminView): string | undefined;

package/dist/extensions/resolve.js

@@ -0,0 +1,187 @@
+import { writeAudit } from "../domain/audit.js";
+import { EXTENSIONS_CUSTOM_KEY, } from "./contract.js";
+import { inputError } from "./input.js";
+/** What the model reads from one extension tool call, at most; longer answers are cut. */
+export const MAX_RESULT_CHARACTERS = 12_000;
+const EXTENSION_ID = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const TOOL_SUFFIX = /^[a-zA-Z][a-zA-Z0-9-]*$/;
+/** The extensions packages registered, valid or not; reading the config never throws. */
+export function registeredExtensions(config) {
+    const value = config.custom?.[EXTENSIONS_CUSTOM_KEY];
+    return Array.isArray(value) ? value : [];
+}
+/** Why a registered extension cannot be used, or null. */
+export function extensionProblem(value) {
+    if (!value || typeof value !== "object")
+        return "an extension is not an object";
+    const extension = value;
+    if (typeof extension.id !== "string" || !EXTENSION_ID.test(extension.id)) {
+        return `extension id ${JSON.stringify(extension.id)} is not kebab-case`;
+    }
+    for (const tool of extension.tools ?? []) {
+        const name = typeof tool?.name === "string" ? tool.name : "";
+        const [prefix, suffix, ...rest] = name.split(".");
+        if (prefix !== extension.id || !suffix || rest.length > 0 || !TOOL_SUFFIX.test(suffix)) {
+            return `tool "${name}" of "${extension.id}" must be named "${extension.id}.<name>"`;
+        }
+        if (tool.risk !== "auto") {
+            return `tool "${name}" has risk ${JSON.stringify(tool.risk)}; extensions may only read ("auto")`;
+        }
+        if (typeof tool.run !== "function" || typeof tool.description !== "string") {
+            return `tool "${name}" needs a description and a run function`;
+        }
+        if (tool.input?.type !== "object") {
+            return `tool "${name}" must take an object as input`;
+        }
+    }
+    return null;
+}
+/**
+ * Problems to report at startup: registered extensions that are invalid, and extensions the host
+ * named that no package registered, or tools it named that the extension does not have.
+ */
+export function extensionWarnings(config, options) {
+    const warnings = [];
+    const valid = new Map();
+    for (const value of registeredExtensions(config)) {
+        const problem = extensionProblem(value);
+        if (problem)
+            warnings.push(problem);
+        else
+            valid.set(value.id, value);
+    }
+    for (const [id, setting] of Object.entries(options.extensions ?? {})) {
+        const extension = valid.get(id);
+        if (!extension) {
+            warnings.push(`extension "${id}" is turned on but no installed package provides it`);
+            continue;
+        }
+        if (setting !== true) {
+            const names = new Set((extension.tools ?? []).map((tool) => tool.name));
+            for (const name of setting.tools) {
+                if (!names.has(name))
+                    warnings.push(`extension "${id}" has no tool "${name}"`);
+            }
+        }
+    }
+    return warnings;
+}
+/** The extensions the host turned on, valid ones only, with the tools it allowed. */
+export function enabledExtensions(config, options) {
+    const settings = options.extensions ?? {};
+    const resolved = [];
+    const seen = new Set();
+    for (const value of registeredExtensions(config)) {
+        if (extensionProblem(value))
+            continue;
+        const extension = value;
+        const setting = settings[extension.id];
+        if (!setting || seen.has(extension.id))
+            continue;
+        seen.add(extension.id);
+        const allowed = setting === true ? undefined : new Set(setting.tools);
+        resolved.push({
+            id: extension.id,
+            instructions: extension.instructions?.trim() || undefined,
+            views: (extension.views ?? []).filter((view) => typeof view?.path === "string" && typeof view.description === "string"),
+            tools: (extension.tools ?? [])
+                .filter((tool) => !allowed || allowed.has(tool.name))
+                .map((tool) => asAssistantTool(tool, options)),
+        });
+    }
+    return resolved;
+}
+/** An extension tool under the assistant's rules: input checked, errors caught, answer bounded, audited. */
+function asAssistantTool(tool, options) {
+    return {
+        name: tool.name,
+        description: tool.description,
+        input: tool.input,
+        risk: "auto",
+        step: "reading",
+        // A batch turn stays on its one saved document.
+        notInBatch: true,
+        run: async (input, ctx) => {
+            const failure = (error, message) => ({
+                ok: false,
+                capability: tool.name,
+                error,
+                message,
+            });
+            const invalid = inputError(tool.input, input);
+            let outcome;
+            if (invalid) {
+                outcome = failure("invalid_input", invalid);
+            }
+            else {
+                try {
+                    const result = await tool.run(input, {
+                        req: ctx.req,
+                        path: viewPath(ctx.bridge.view),
+                        open: openDocument(ctx.bridge),
+                    });
+                    outcome = result.ok
+                        ? {
+                            ok: true,
+                            capability: tool.name,
+                            data: bounded(result.data),
+                            ...(result.navigate ? { navigate: result.navigate } : {}),
+                        }
+                        : failure(result.error, result.message);
+                }
+                catch (error) {
+                    ctx.req.payload.logger.error({
+                        err: error,
+                        msg: `editor-assistant: ${tool.name} failed`,
+                    });
+                    outcome = failure("tool_failed", "This tool failed. Say so; do not guess its answer.");
+                }
+            }
+            await writeAudit(ctx.req, options, {
+                capability: tool.name,
+                risk: "auto",
+                outcome: outcome.ok ? "executed" : "failed",
+                errorClass: outcome.ok ? undefined : outcome.error,
+                locale: ctx.bridge.locale,
+            });
+            return outcome;
+        },
+    };
+}
+/** The data, or its first characters with a note when it is too long for the model. */
+function bounded(data) {
+    const text = JSON.stringify(data ?? null);
+    if (text.length <= MAX_RESULT_CHARACTERS)
+        return data;
+    return {
+        truncated: `Cut at ${MAX_RESULT_CHARACTERS} characters; ask with narrower input for the rest.`,
+        text: text.slice(0, MAX_RESULT_CHARACTERS),
+    };
+}
+/** The editor's place in Admin as a path under the admin route. */
+export function viewPath(view) {
+    switch (view?.kind) {
+        case "dashboard":
+            return "/";
+        case "custom":
+            return view.path;
+        case "list":
+            return `/collections/${view.collection}`;
+        case "document":
+            return `/collections/${view.collection}${view.documentId ? `/${view.documentId}` : "/create"}`;
+        case "global":
+            return `/globals/${view.global}`;
+        default:
+            return undefined;
+    }
+}
+function openDocument(bridge) {
+    if (!bridge.collection && !bridge.global)
+        return undefined;
+    return {
+        collection: bridge.collection,
+        global: bridge.global,
+        id: bridge.documentId,
+        locale: bridge.locale,
+    };
+}

package/dist/form/relation-shape.d.ts

@@ -5,7 +5,8 @@ import { type FieldNode } from "../schema/fields.ts";
  * including relations inside changed groups, rows and blocks. A single-collection
  * polymorphic relation still needs { relationTo, value }. Missing required relationships in a
  * changed group are checked against Payload's trusted field conditions and primitive defaults.
- * Fields pointing at several collections are refused. Unrelated fields are not checked.
+ * A field for several collections takes { relationTo, value } with one of them. Unrelated fields
+ * are not checked.
  * Whether the ids exist and are readable is `verifyDocumentRelations`' job.
  */
 export declare function relationValueError(fields: FieldNode[], data: Record<string, unknown>, paths: string[], context?: {

package/dist/form/relation-shape.js

@@ -6,7 +6,8 @@ const ID = /^[\w-]+$/;
  * including relations inside changed groups, rows and blocks. A single-collection
  * polymorphic relation still needs { relationTo, value }. Missing required relationships in a
  * changed group are checked against Payload's trusted field conditions and primitive defaults.
- * Fields pointing at several collections are refused. Unrelated fields are not checked.
+ * A field for several collections takes { relationTo, value } with one of them. Unrelated fields
+ * are not checked.
  * Whether the ids exist and are readable is `verifyDocumentRelations`' job.
  */
 export function relationValueError(fields, data, paths, context = {}) {
@@ -55,7 +56,7 @@ export function relationValueError(fields, data, paths, context = {}) {
             }
             if (required) {
                 const format = field.polymorphic
-                    ? ` Set it to {"relationTo":"${field.relationTo?.[0]}","value":"<found document id>"}, not a URL.`
+                    ? ` Set it to {"relationTo":${collectionsOf(field)},"value":"<found document id>"}, not a URL.`
                     : " Set it to a found document id, not a URL.";
                 return `"${path}" is required.${format}`;
             }
@@ -88,9 +89,6 @@ export function relationValueError(fields, data, paths, context = {}) {
 }
 function fieldError(field, path, value) {
     const noun = field.type === "upload" ? "image" : "document";
-    if ((field.relationTo?.length ?? 0) > 1) {
-        return `"${path}" points at several collections; the assistant cannot choose for it yet.`;
-    }
     if (value === null || value === undefined) {
         return null;
     }
@@ -124,13 +122,18 @@ function fieldError(field, path, value) {
 function entryError(field, path, value, noun) {
     if (field.polymorphic) {
         return isRecord(value) &&
-            value.relationTo === field.relationTo?.[0] &&
+            typeof value.relationTo === "string" &&
+            (field.relationTo ?? []).includes(value.relationTo) &&
             idOf(value.value) !== undefined
             ? null
-            : `"${path}" needs {"relationTo":"${field.relationTo?.[0]}","value":"<found ${noun} id>"}. A URL or bare id cannot fill this field.`;
+            : `"${path}" needs {"relationTo":${collectionsOf(field)},"value":"<found ${noun} id>"}. A URL or bare id cannot fill this field.`;
     }
     return idOf(value) !== undefined ? null : `"${path}" needs a valid ${noun} id, not a URL.`;
 }
+/** `"images"`, or `"images" or "videos"` for a field that takes several collections. */
+function collectionsOf(field) {
+    return (field.relationTo ?? []).map((slug) => `"${slug}"`).join(" or ");
+}
 function isRecord(value) {
     return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export type { BuiltinCapability, CapabilityRisk, EntityCapability } from "./capabilities.ts";
 export { BUILTIN_CAPABILITIES, BUILTIN_RISK, ENTITY_CAPABILITIES } from "./capabilities.ts";
+export type { AssistantExtension, AssistantExtensionContext, AssistantExtensionResult, AssistantExtensionTool, AssistantExtensionView, } from "./extensions/contract.ts";
+export { EXTENSIONS_CUSTOM_KEY } from "./extensions/contract.ts";
 export { editorAssistantPlugin } from "./plugin.ts";
 export type { AssistantShortcut, EditorAssistantPluginOptions, EntityAllowlist, FieldAllowlist, HostLanguageModel, ModelResolver, ProposalValidationResult, } from "./types.ts";
 export { defineEditorAssistantConfig } from "./types.ts";

package/dist/index.js

@@ -1,3 +1,4 @@
 export { BUILTIN_CAPABILITIES, BUILTIN_RISK, ENTITY_CAPABILITIES } from "./capabilities.js";
+export { EXTENSIONS_CUSTOM_KEY } from "./extensions/contract.js";
 export { editorAssistantPlugin } from "./plugin.js";
 export { defineEditorAssistantConfig } from "./types.js";