@simmalugnt-se/payload-editor-assistant 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 0.2.0
+
+Breaking: options that were accepted but did nothing are removed.
+
+- `tools` (and the `HostToolDefinition` type): host tools were validated but never given to the
+  model. They will come back when the assistant can run them.
+- `audit.retentionDays`: nothing deleted old audit entries.
+
+Also: README documents `validateProposal`.
+
+## 0.1.1
+
+- Provider failures are logged on the server through Payload's logger (missing model, `ai` not
+  installed, or the provider's own error), instead of only showing `provider_error` in the drawer.
+- README: how to connect the provider's API key, what the assistant may do, and the options.
+
+## 0.1.0
+
+- First release.
+- `ai` is a required peer: the AI SDK is loaded with a literal import so bundlers can resolve it.

package/README.md

@@ -9,24 +9,85 @@ your choice.
 
 ## Setup
 
-```ts
-import { deepSeek } from "@ai-sdk/deepseek";
-import { editorAssistantPlugin } from "@simmalugnt-se/payload-editor-assistant";
-
-plugins: [
-  editorAssistantPlugin({
-    model: deepSeek("deepseek-chat"),
-    collections: {
-      pages: {
-        capabilities: ["content.find", "content.findById", "form.read", "form.propose", "draft.create"],
-      },
-    },
-    globals: {
-      header: { capabilities: ["content.findById", "form.read", "form.propose"] },
-    },
-  }),
-];
-```
-
-Then regenerate the import map (`pnpm payload generate:importmap`). See `EditorAssistantPluginOptions`
-for allowlists, host tools and instructions. Design notes live in `docs/research` and `.wayfinder`.
+1. Install the plugin, the AI SDK and a provider (DeepSeek here; any AI SDK provider works):
+
+   ```bash
+   pnpm add @simmalugnt-se/payload-editor-assistant ai @ai-sdk/deepseek
+   ```
+
+2. Put the provider's API key in the server environment, e.g. `.env.local` locally and the
+   hosting provider's environment variables in production. Never expose it to the browser
+   (no `NEXT_PUBLIC_` prefix):
+
+   ```bash
+   DEEPSEEK_API_KEY=sk-...
+   ```
+
+3. Create the model with that key and pass it to the plugin:
+
+   ```ts
+   import { createDeepSeek } from "@ai-sdk/deepseek";
+   import { editorAssistantPlugin } from "@simmalugnt-se/payload-editor-assistant";
+
+   const deepSeek = createDeepSeek({ apiKey: process.env.DEEPSEEK_API_KEY });
+
+   plugins: [
+     editorAssistantPlugin({
+       model: deepSeek("deepseek-chat"),
+       collections: {
+         pages: {
+           capabilities: ["content.find", "content.findById", "form.read", "form.propose", "draft.create"],
+         },
+       },
+       globals: {
+         header: { capabilities: ["content.findById", "form.read", "form.propose"] },
+       },
+     }),
+   ];
+   ```
+
+4. Regenerate the import map: `pnpm payload generate:importmap`.
+
+## API keys
+
+The plugin has no provider or key of its own: it only receives the `model` you create, and the model
+is called on the server. To switch provider, install another AI SDK provider and create the model
+with its key, e.g. `createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY })`.
+
+Providers also read a default environment variable (`DEEPSEEK_API_KEY`, `ANTHROPIC_API_KEY`, ...)
+when no `apiKey` is passed, but passing it explicitly keeps the connection visible in your config.
+
+If the key is missing or wrong, the drawer shows `provider_error` and the cause is logged on the
+server through Payload's logger.
+
+## What the assistant may do
+
+Nothing is reachable unless you list it. Each collection or global gets the capabilities it allows:
+
+| Capability | What it does | Needs approval |
+|---|---|---|
+| `content.find` | search and list documents | no |
+| `content.findById` | read one document | no |
+| `form.read` | read the open edit form, including unsaved changes | no |
+| `form.propose` | propose changes to the open form; the editor reviews them before they apply | yes |
+| `draft.create` | create a new draft document (collections only) | yes |
+
+The assistant never publishes. Approved form changes land in the open form and the editor saves as
+usual; an approved `draft.create` saves a new, unpublished draft. The `users` collection, Payload's own collections and fields that look like
+secrets (`password`, `token`, `apiKey`, ...) are always off limits.
+
+## Options
+
+| Option | |
+|---|---|
+| `model` | The AI SDK model, or `({ userId }) => model` to choose per user. Required unless `disabled`. |
+| `collections`, `globals` | `{ [slug]: { capabilities, fields? } }`. `fields` narrows what is visible: `{ include: [...] }` or `{ exclude: [...] }`. |
+| `denyFields` | Field names hidden from the assistant in every collection and global. |
+| `instructions` | Project rules the assistant cannot infer from the schema, e.g. "the start page has slug `home`". |
+| `shortcuts` | One-click prompts in the drawer: `{ id, label, prompt, when?, entities? }`. |
+| `enabled` | `({ userId }) => boolean` to offer the assistant to some users only. |
+| `redact` | `({ slug, data }) => data` to strip values before documents reach the model. |
+| `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`). |
+| `disabled` | Turn the plugin off without removing its config. |

package/dist/config/validate.d.ts

@@ -1,15 +1,13 @@
-import type { EditorAssistantPluginOptions, EntityAllowlist, HostToolDefinition } from "../types.ts";
+import type { EditorAssistantPluginOptions, EntityAllowlist } from "../types.ts";
 export type ValidatedEditorAssistantOptions = EditorAssistantPluginOptions & {
     disabled: boolean;
     collections: Record<string, EntityAllowlist>;
     globals: Record<string, EntityAllowlist>;
     denyFields: string[];
     shortcuts: NonNullable<EditorAssistantPluginOptions["shortcuts"]>;
-    tools: HostToolDefinition[];
     trustedOrigins: string[];
     audit: {
         collection: string;
-        retentionDays?: number;
     };
 };
 export declare function validateEditorAssistantOptions(options: EditorAssistantPluginOptions): ValidatedEditorAssistantOptions;

package/dist/config/validate.js

@@ -1,6 +1,5 @@
-import { BUILTIN_RISK, EMBEDDED_ONLY_CAPABILITIES, isBuiltinCapability, isEntityCapability, } from "../capabilities.js";
+import { isEntityCapability } from "../capabilities.js";
 import { isDeniedCollectionSlug } from "./denied-fields.js";
-const RISK_ORDER = { auto: 0, approval: 1, forbidden: 2 };
 export function validateEditorAssistantOptions(options) {
     const disabled = options.disabled === true;
     const collections = options.collections ?? {};
@@ -11,7 +10,6 @@ export function validateEditorAssistantOptions(options) {
         }
         validateEntityMap("collections", collections, { allowDraftCreate: true });
         validateEntityMap("globals", globals, { allowDraftCreate: false });
-        validateHostTools(options.tools ?? []);
     }
     return {
         ...options,
@@ -20,11 +18,9 @@ export function validateEditorAssistantOptions(options) {
         globals,
         denyFields: options.denyFields ?? [],
         shortcuts: options.shortcuts ?? [],
-        tools: options.tools ?? [],
         trustedOrigins: options.trustedOrigins ?? [],
         audit: {
             collection: options.audit?.collection ?? "editor-assistant-audit",
-            retentionDays: options.audit?.retentionDays,
         },
     };
 }
@@ -62,25 +58,3 @@ function validateFields(entry, label) {
         throw new Error(`payload-editor-assistant: ${label} fields.exclude must be an array.`);
     }
 }
-function validateHostTools(tools) {
-    for (const tool of tools) {
-        if (!tool.id || !tool.capabilityId) {
-            throw new Error("payload-editor-assistant: host tools require id and capabilityId.");
-        }
-        const risk = tool.risk ?? "approval";
-        if (risk !== "auto" && risk !== "approval" && risk !== "forbidden") {
-            throw new Error(`payload-editor-assistant: host tool "${tool.id}" has invalid risk.`);
-        }
-        if (isBuiltinCapability(tool.capabilityId)) {
-            if (RISK_ORDER[risk] < RISK_ORDER[BUILTIN_RISK[tool.capabilityId]]) {
-                throw new Error(`payload-editor-assistant: host tool "${tool.id}" cannot loosen risk below ${tool.capabilityId}.`);
-            }
-            if (tool.mcp && EMBEDDED_ONLY_CAPABILITIES.has(tool.capabilityId)) {
-                throw new Error(`payload-editor-assistant: host tool "${tool.id}" cannot mark ${tool.capabilityId} as MCP-eligible.`);
-            }
-        }
-        if (risk === "auto" && tool.mcp === true && tool.capabilityId === "form.propose") {
-            throw new Error(`payload-editor-assistant: host tool "${tool.id}" cannot expose form writes to MCP.`);
-        }
-    }
-}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export type { BuiltinCapability, CapabilityRisk, EntityCapability } from "./capabilities.ts";
 export { BUILTIN_CAPABILITIES, BUILTIN_RISK, ENTITY_CAPABILITIES } from "./capabilities.ts";
 export { editorAssistantPlugin } from "./plugin.ts";
-export type { AssistantShortcut, EditorAssistantPluginOptions, EntityAllowlist, FieldAllowlist, HostLanguageModel, HostToolDefinition, ModelResolver, ProposalValidationResult, } from "./types.ts";
+export type { AssistantShortcut, EditorAssistantPluginOptions, EntityAllowlist, FieldAllowlist, HostLanguageModel, ModelResolver, ProposalValidationResult, } from "./types.ts";
 export { defineEditorAssistantConfig } from "./types.ts";

package/dist/runtime/agent.js

@@ -1,3 +1,4 @@
+import { PACKAGE_NAME } from "../package-name.js";
 import { loadTurnContext } from "./context.js";
 import { needsProposeRetry } from "./propose-loop.js";
 import { buildSystemPrompt } from "./system-prompt.js";
@@ -9,10 +10,12 @@ const TIMEOUT_MS = 60_000;
 export async function runAgentTurn(req, options, input) {
     const model = await resolveModel(options, req.user?.id);
     if (!model) {
+        logProviderError(req, "no model: the `model` option resolved to nothing for this user");
         return { ok: false, error: "provider_error" };
     }
     const ai = await loadAiSdk();
     if (!ai) {
+        logProviderError(req, "could not load the AI SDK: is `ai` installed in the project?");
         return { ok: false, error: "provider_error" };
     }
     const ctx = {
@@ -39,6 +42,7 @@ export async function runAgentTurn(req, options, input) {
             signal,
         });
         if (!first) {
+            logProviderError(req, "the model returned no result");
             return { ok: false, error: "provider_error" };
         }
         const collected = collectResult(String(first.text ?? ""), first, captured, input.bridge.language ?? input.bridge.locale);
@@ -79,6 +83,7 @@ export async function runAgentTurn(req, options, input) {
         if (signal.aborted) {
             return { ok: false, error: "timeout" };
         }
+        logProviderError(req, "the model provider failed", error);
         return {
             ok: false,
             error: "provider_error",
@@ -246,6 +251,13 @@ async function resolveModel(options, userId) {
     }
     return options.model;
 }
+/**
+ * The drawer only shows "provider_error"; the cause (missing key, wrong model id, provider outage)
+ * belongs in the server log where the host can see it.
+ */
+function logProviderError(req, message, error) {
+    req.payload?.logger?.error({ err: error, msg: `${PACKAGE_NAME}: ${message}` });
+}
 async function loadAiSdk() {
     try {
         // A literal specifier: bundlers only resolve `import()` they can read, and the host's `ai`

package/dist/types.d.ts

@@ -22,13 +22,6 @@ export type AssistantShortcut = {
     /** Collection or global slugs where the shortcut is shown. Views without an entity (dashboard) are not filtered. */
     entities?: string[];
 };
-export type HostToolRisk = "auto" | "approval" | "forbidden";
-export type HostToolDefinition = {
-    id: string;
-    capabilityId: string;
-    risk?: HostToolRisk;
-    mcp?: boolean;
-};
 export type ProposalValidationResult = {
     ok: true;
 } | {
@@ -43,7 +36,6 @@ export type EditorAssistantPluginOptions = {
     denyFields?: string[];
     instructions?: string;
     shortcuts?: AssistantShortcut[];
-    tools?: HostToolDefinition[];
     validateProposal?: (input: unknown) => ProposalValidationResult | Promise<ProposalValidationResult>;
     redact?: (input: {
         slug: string;
@@ -55,7 +47,6 @@ export type EditorAssistantPluginOptions = {
     trustedOrigins?: string[];
     audit?: {
         collection?: string;
-        retentionDays?: number;
     };
 };
 export declare function defineEditorAssistantConfig<T extends EditorAssistantPluginOptions>(options: T): T;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simmalugnt-se/payload-editor-assistant",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Context-aware editor assistant plugin for Payload Admin",
   "keywords": [
     "payload",
@@ -18,7 +18,8 @@
     "node": ">=22"
   },
   "files": [
-    "dist"
+    "dist",
+    "CHANGELOG.md"
   ],
   "sideEffects": [
     "*.css"