@mvriu5/payload-ai 1.2.0 → 1.4.0

package/dist/handlers/chatHandler.js

@@ -4,6 +4,7 @@ import { signAIActionProposal } from "../ai/proposalSigning.js";
 import { isAIProvider } from "../ai/providerOptions.js";
 import { getModel, getProviderConfig } from "../ai/providerRuntime.js";
 import { containsSensitiveData } from "../ai/sensitiveData.js";
+import { getExceededTokenUsageLimit, recordTokenUsage } from "../ai/tokenUsage.js";
 import { isCollectionActionAllowed } from "../payload/collectionPermissions.js";
 import { prepareProposalWriteData } from "../payload/proposalData.js";
 import { buildPromptWithMentionContext, collectBlocks, describeCollectionLikeConfig, describeCollectionLikeSummary, getAllowedCollectionSlugs, getMentionContext } from "../payload/schemaContext.js";
@@ -46,7 +47,7 @@ const createDebugPayload = ({ activeLocale, debug, proposalCount, selectedLocale
     });
 const createE2EChatResponse = ({ prompt, selectedLocales })=>{
     const normalizedPrompt = prompt.toLowerCase();
-    const wantsCreatePost = normalizedPrompt.includes("post") && (normalizedPrompt.includes("create") || normalizedPrompt.includes("erstell"));
+    const wantsCreatePost = normalizedPrompt.includes("post") && (normalizedPrompt.includes("create") || normalizedPrompt.includes("erstell") || normalizedPrompt.includes("apply flow") || normalizedPrompt.includes("locale review") || normalizedPrompt.includes("proposal review"));
     const mentionsMars = normalizedPrompt.includes("mars");
     const multipleLocales = selectedLocales.length > 1;
     const activeLocale = selectedLocales.at(-1);
@@ -241,14 +242,23 @@ const getMissingCreateFields = ({ data, localizedData, requiredFields })=>{
             ];
         }
         const missing = [];
+        const localizedRequiredFields = [];
+        const sharedRequiredFields = [];
+        for (const field of requiredFields){
+            if (field.localized) {
+                localizedRequiredFields.push(field);
+            } else {
+                sharedRequiredFields.push(field);
+            }
+        }
         for (const [locale, localeData] of locales){
-            for (const field of requiredFields.filter((item)=>item.localized)){
+            for (const field of localizedRequiredFields){
                 if (!hasValueAtPath(localeData, field.path)) {
                     missing.push(`${locale}:${field.path}`);
                 }
             }
         }
-        for (const field of requiredFields.filter((item)=>!item.localized)){
+        for (const field of sharedRequiredFields){
             if (!hasValueAtPath(firstLocale[1], field.path)) {
                 missing.push(`${firstLocale[0]}:${field.path}`);
             }
@@ -258,7 +268,9 @@ const getMissingCreateFields = ({ data, localizedData, requiredFields })=>{
     if (!data) return [
         "data is required"
     ];
-    return requiredFields.filter((field)=>!hasValueAtPath(data, field.path)).map((field)=>field.path);
+    return requiredFields.flatMap((field)=>hasValueAtPath(data, field.path) ? [] : [
+            field.path
+        ]);
 };
 const getProposalSummary = (proposal)=>({
         action: proposal.action,
@@ -293,19 +305,28 @@ const getCollectionBlockTypes = (fields)=>{
         ...blockTypes
     ];
 };
+const regexSpecialCharactersPattern = /[.*+?^${}()|[\]\\]/g;
 const getRequestedBlockTypes = ({ availableBlockTypes, mentions, prompt })=>{
     const requestedBlockTypes = new Set();
     const normalizedPrompt = prompt.toLowerCase();
+    const availableBlockTypeSet = new Set(availableBlockTypes);
+    const blockTypesByNormalizedSlug = new Map(availableBlockTypes.map((blockType)=>[
+            blockType.toLowerCase(),
+            blockType
+        ]));
+    const escapedBlockTypes = availableBlockTypes.map((blockType)=>blockType.replace(regexSpecialCharactersPattern, "\\$&")).join("|");
+    const blockPattern = escapedBlockTypes ? new RegExp(`\\b(${escapedBlockTypes})\\b(?:\\s+block)?`, "gi") : null;
     for (const mention of mentions || []){
-        if (mention.type === "block" && mention.slug && availableBlockTypes.includes(mention.slug)) {
+        if (mention.type === "block" && mention.slug && availableBlockTypeSet.has(mention.slug)) {
             requestedBlockTypes.add(mention.slug);
         }
     }
-    for (const blockType of availableBlockTypes){
-        const escapedBlockType = blockType.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-        const blockPattern = new RegExp(`\\b${escapedBlockType}\\b(?:\\s+block)?`, "i");
-        if (blockPattern.test(normalizedPrompt)) {
-            requestedBlockTypes.add(blockType);
+    if (blockPattern) {
+        for (const match of normalizedPrompt.matchAll(blockPattern)){
+            const blockType = match[1] ? blockTypesByNormalizedSlug.get(match[1].toLowerCase()) : null;
+            if (blockType) {
+                requestedBlockTypes.add(blockType);
+            }
         }
     }
     return [
@@ -320,6 +341,10 @@ const collectProposalBlockTypes = ({ data, fields })=>{
             const fieldValue = value[field.name];
             if (fieldValue === undefined || fieldValue === null) continue;
             if (field.type === "blocks" && Array.isArray(fieldValue)) {
+                const blocksBySlug = new Map(field.blocks?.map((block)=>[
+                        block.slug,
+                        block
+                    ]));
                 for (const blockItem of fieldValue){
                     if (!isRecord(blockItem)) continue;
                     const blockType = typeof blockItem.blockType === "string" ? blockItem.blockType : typeof blockItem.type === "string" ? blockItem.type : typeof blockItem.slug === "string" ? blockItem.slug : null;
@@ -327,7 +352,7 @@ const collectProposalBlockTypes = ({ data, fields })=>{
                         foundBlockTypes.add(blockType);
                     }
                     if (blockType) {
-                        const blockConfig = field.blocks?.find((candidate)=>candidate.slug === blockType);
+                        const blockConfig = blocksBySlug.get(blockType);
                         if (blockConfig?.fields?.length) {
                             visitFields(blockConfig.fields, blockItem);
                         }
@@ -410,11 +435,15 @@ const collectRelationshipTargets = ({ data, fields, path = "" })=>{
             continue;
         }
         if (field.type === "blocks" && Array.isArray(fieldValue) && field.blocks?.length) {
+            const blocksBySlug = new Map(field.blocks.map((block)=>[
+                    block.slug,
+                    block
+                ]));
             fieldValue.forEach((item, index)=>{
                 if (!isRecord(item)) return;
                 const blockType = typeof item.blockType === "string" ? item.blockType : typeof item.type === "string" ? item.type : typeof item.slug === "string" ? item.slug : null;
                 if (!blockType) return;
-                const blockConfig = field.blocks?.find((candidate)=>candidate.slug === blockType);
+                const blockConfig = blocksBySlug.get(blockType);
                 if (!blockConfig?.fields?.length) return;
                 targets.push(...collectRelationshipTargets({
                     data: item,
@@ -426,13 +455,91 @@ const collectRelationshipTargets = ({ data, fields, path = "" })=>{
     }
     return targets;
 };
+const collectUploadTargets = ({ data, fields, path = "" })=>{
+    const targets = [];
+    for (const field of fields){
+        if (!field.name) continue;
+        const fieldPath = path ? `${path}.${field.name}` : field.name;
+        const fieldValue = data[field.name];
+        if (fieldValue === undefined || fieldValue === null) continue;
+        if (field.type === "upload") {
+            const relationTargets = Array.isArray(field.relationTo) ? field.relationTo.filter((item)=>typeof item === "string") : typeof field.relationTo === "string" ? [
+                field.relationTo
+            ] : [];
+            const collectSingle = (value, itemPath)=>{
+                if (typeof value === "string" || typeof value === "number") {
+                    if (relationTargets.length === 1) {
+                        targets.push({
+                            collection: relationTargets[0],
+                            id: value,
+                            path: itemPath
+                        });
+                    }
+                    return;
+                }
+                if (!isRecord(value)) return;
+                const relationTo = typeof value.relationTo === "string" ? value.relationTo : relationTargets[0];
+                const id = typeof value.id === "string" || typeof value.id === "number" ? value.id : typeof value.value === "string" || typeof value.value === "number" ? value.value : undefined;
+                if (!relationTo || id === undefined) return;
+                targets.push({
+                    collection: relationTo,
+                    id,
+                    path: itemPath
+                });
+            };
+            if (field.hasMany && Array.isArray(fieldValue)) {
+                fieldValue.forEach((item, index)=>collectSingle(item, `${fieldPath}.${index}`));
+            } else {
+                collectSingle(fieldValue, fieldPath);
+            }
+            continue;
+        }
+        if (field.type === "group" && isRecord(fieldValue) && field.fields?.length) {
+            targets.push(...collectUploadTargets({
+                data: fieldValue,
+                fields: field.fields,
+                path: fieldPath
+            }));
+            continue;
+        }
+        if (field.type === "array" && Array.isArray(fieldValue) && field.fields?.length) {
+            fieldValue.forEach((item, index)=>{
+                if (!isRecord(item)) return;
+                targets.push(...collectUploadTargets({
+                    data: item,
+                    fields: field.fields,
+                    path: `${fieldPath}.${index}`
+                }));
+            });
+            continue;
+        }
+        if (field.type === "blocks" && Array.isArray(fieldValue) && field.blocks?.length) {
+            const blocksBySlug = new Map(field.blocks.map((block)=>[
+                    block.slug,
+                    block
+                ]));
+            fieldValue.forEach((item, index)=>{
+                if (!isRecord(item)) return;
+                const blockType = typeof item.blockType === "string" ? item.blockType : typeof item.type === "string" ? item.type : typeof item.slug === "string" ? item.slug : null;
+                if (!blockType) return;
+                const blockConfig = blocksBySlug.get(blockType);
+                if (!blockConfig?.fields?.length) return;
+                targets.push(...collectUploadTargets({
+                    data: item,
+                    fields: blockConfig.fields,
+                    path: `${fieldPath}.${index}`
+                }));
+            });
+        }
+    }
+    return targets;
+};
 const validateRelationshipTargetsExist = async ({ data, fields, req })=>{
     const targets = collectRelationshipTargets({
         data,
         fields
     });
-    const invalidTargets = [];
-    for (const target of targets){
+    const targetResults = await Promise.all(targets.map(async (target)=>{
         try {
             await req.payload.findByID({
                 collection: target.collection,
@@ -441,11 +548,19 @@ const validateRelationshipTargetsExist = async ({ data, fields, req })=>{
                 overrideAccess: false,
                 req
             });
+            return null;
         } catch  {
-            invalidTargets.push(target);
+            return target;
         }
-    }
-    return invalidTargets;
+    }));
+    return targetResults.filter((target)=>Boolean(target));
+};
+const getUploadTargetsOutsideAttachments = ({ allowedAttachmentKeys, data, fields })=>{
+    if (allowedAttachmentKeys.size === 0) return [];
+    return collectUploadTargets({
+        data,
+        fields
+    }).filter((target)=>!allowedAttachmentKeys.has(`${target.collection}:${String(target.id)}`));
 };
 const getMentionSummary = (mentions)=>mentions?.map((mention)=>({
             collection: "collection" in mention ? mention.collection : undefined,
@@ -453,6 +568,39 @@ const getMentionSummary = (mentions)=>mentions?.map((mention)=>({
             slug: mention.slug,
             type: mention.type
         })) || [];
+const getMediaAttachmentContext = async ({ allowedCollectionsBySlug, attachments, collections, req })=>{
+    if (!attachments?.length) return [];
+    const contexts = [];
+    const seen = new Set();
+    for (const attachment of attachments.slice(0, 8)){
+        if (attachment.type !== "media" || !attachment.collection || !attachment.id) continue;
+        const key = `${attachment.collection}:${attachment.id}`;
+        if (seen.has(key)) continue;
+        const collectionConfig = allowedCollectionsBySlug.get(attachment.collection);
+        if (!collectionConfig?.upload) continue;
+        const doc = await req.payload.findByID({
+            collection: attachment.collection,
+            depth: 1,
+            id: attachment.id,
+            overrideAccess: false,
+            req
+        }).catch(()=>null);
+        if (!doc) continue;
+        seen.add(key);
+        contexts.push({
+            attachment,
+            collection: attachment.collection,
+            doc,
+            schema: describeCollectionLikeConfig({
+                config: collectionConfig,
+                permissions: collections,
+                type: "collection"
+            }),
+            type: "mediaAttachment"
+        });
+    }
+    return contexts;
+};
 const formatProposalIssuesForRetry = (issues)=>{
     return issues.slice(0, 6).map((issue)=>{
         switch(issue.code){
@@ -500,9 +648,19 @@ const createCollectionAliasMap = (collections)=>{
 };
 const getLikelyCollectionMatches = ({ aliasMap, prompt })=>{
     const normalizedPrompt = prompt.toLowerCase();
-    const matches = Object.entries(aliasMap).filter(([alias])=>normalizedPrompt.includes(alias)).map(([, slug])=>slug);
+    const matches = new Set();
+    const aliases = Object.keys(aliasMap).sort((a, b)=>b.length - a.length);
+    const aliasPattern = aliases.length > 0 ? new RegExp(aliases.map((alias)=>alias.replace(regexSpecialCharactersPattern, "\\$&")).join("|"), "g") : null;
+    if (!aliasPattern) return [];
+    for (const match of normalizedPrompt.matchAll(aliasPattern)){
+        const alias = match[0];
+        const slug = aliasMap[alias];
+        if (slug) {
+            matches.add(slug);
+        }
+    }
     return [
-        ...new Set(matches)
+        ...matches
     ];
 };
 const hasWriteIntent = (prompt)=>{
@@ -517,15 +675,17 @@ const getIntentToolChoice = (prompt)=>{
             type: "tool"
         };
     }
-    if (/\b(create|build|generate|write|draft|make|add)\b/.test(normalizedPrompt)) {
+    // Update existing document (add block, modify content, etc.)
+    if (/\b(update|edit|change|modify|einfügen|hinzufügen|addieren)\b/.test(normalizedPrompt)) {
         return {
-            toolName: "proposeCreateDoc",
+            toolName: "proposeUpdateDoc",
             type: "tool"
         };
     }
-    if (/\b(update|edit|change|revise|refine|rewrite|translate)\b/.test(normalizedPrompt)) {
+    // Create a new document
+    if (/\b(create|build|generate|write|draft|make|add|füge|einfügen|hinzufügen|addieren)\b/.test(normalizedPrompt)) {
         return {
-            toolName: "proposeUpdateDoc",
+            toolName: "proposeCreateDoc",
             type: "tool"
         };
     }
@@ -544,7 +704,13 @@ export const createChatHandler = (options = {})=>async (req)=>{
         }, {
             status: 400
         });
-        const selectedLocales = (body?.mentions?.filter((mention)=>mention.type === "locale" && mention.slug).map((mention)=>mention.slug) || []).filter((locale, index, array)=>array.indexOf(locale) === index);
+        const selectedLocales = [];
+        const selectedLocaleSet = new Set();
+        for (const mention of body?.mentions || []){
+            if (mention.type !== "locale" || !mention.slug || selectedLocaleSet.has(mention.slug)) continue;
+            selectedLocaleSet.add(mention.slug);
+            selectedLocales.push(mention.slug);
+        }
         const activeLocale = selectedLocales.at(-1);
         const mentionSummary = getMentionSummary(body?.mentions);
         if (e2eModeEnabled()) {
@@ -554,23 +720,67 @@ export const createChatHandler = (options = {})=>async (req)=>{
             });
         }
         const user = req.user;
-        const requestedProvider = body?.provider || user.aiProvider || "openai";
-        if (!isAIProvider(requestedProvider)) return Response.json({
-            error: `Unsupported AI provider: ${requestedProvider}`
-        }, {
-            status: 400
+        const exceededTokenUsageLimit = await getExceededTokenUsageLimit({
+            maxTokenUsage: options.maxTokenUsage,
+            req,
+            userID: user.id
         });
-        const provider = requestedProvider;
-        const userApiKey = options.allowUserApiKeys === false ? null : user.aiApiKey;
+        if (exceededTokenUsageLimit) {
+            const scope = options.maxTokenUsage?.type === "site" ? "site" : "user";
+            const periodLabel = exceededTokenUsageLimit.period === "day" ? "Daily" : "Weekly";
+            logHandlerEvent(req, "warn", {
+                limit: exceededTokenUsageLimit.limit,
+                msg: "AI chat blocked: token usage limit reached",
+                period: exceededTokenUsageLimit.period,
+                scope,
+                used: exceededTokenUsageLimit.used,
+                userID: String(user.id)
+            });
+            return Response.json({
+                error: `${periodLabel} AI token limit reached for this ${scope}.`,
+                limit: exceededTokenUsageLimit.limit,
+                period: exceededTokenUsageLimit.period,
+                used: exceededTokenUsageLimit.used
+            }, {
+                status: 429
+            });
+        }
+        const managedProviders = options.providers?.length ? options.providers : null;
+        const requestedProvider = body?.provider || (managedProviders ? managedProviders[0].id : user.aiProvider || "openai");
+        const managedProvider = managedProviders?.find((providerConfig)=>providerConfig.id === requestedProvider);
+        if (managedProviders && !managedProvider) {
+            return Response.json({
+                error: `Unsupported AI provider: ${requestedProvider}`
+            }, {
+                status: 400
+            });
+        }
+        if (!managedProvider && !isAIProvider(requestedProvider)) {
+            return Response.json({
+                error: `Unsupported AI provider: ${requestedProvider}`
+            }, {
+                status: 400
+            });
+        }
+        const provider = managedProvider?.provider || requestedProvider;
+        const requestedModel = body?.model || managedProvider?.defaultModel;
+        if (managedProvider && requestedModel && !managedProvider.models.some((model)=>model.value === requestedModel)) {
+            return Response.json({
+                error: `Unsupported model "${requestedModel}" for AI provider "${managedProvider.id}".`
+            }, {
+                status: 400
+            });
+        }
+        const userApiKey = managedProvider ? managedProvider.apiKey : options.allowUserApiKeys === false ? null : user.aiApiKey;
         const providerConfig = getProviderConfig({
             apiKey: userApiKey,
             defaultModels: options.models?.defaults,
-            model: body?.model,
+            model: requestedModel,
             provider
         });
         const debug = {
             model: providerConfig.modelID,
-            provider,
+            provider: managedProvider?.id || provider,
             tools: [
                 "getDoc",
                 "getGlobal",
@@ -601,7 +811,7 @@ export const createChatHandler = (options = {})=>async (req)=>{
                 selectedLocales
             });
             return Response.json({
-                error: options.allowUserApiKeys === false ? `Configure a ${provider} API key in the server environment first.` : `Add a ${provider} API key to your account settings or configure it in the server environment first.`
+                error: managedProvider ? `Configure a ${managedProvider?.id || provider} API key in the plugin config or server environment first.` : options.allowUserApiKeys === false ? `Configure a ${provider} API key in the server environment first.` : `Add a ${provider} API key to your account settings or configure it in the server environment first.`
             }, {
                 status: 400
             });
@@ -654,10 +864,43 @@ export const createChatHandler = (options = {})=>async (req)=>{
                 });
                 return signedProposal;
             };
-            const collectionSlugs = getAllowedCollectionSlugs(req, options.collections);
-            const globalSlugs = req.payload.config.globals?.map((global)=>global.slug) || [];
-            const allowedCollections = req.payload.config.collections.filter((collection)=>collectionSlugs.includes(collection.slug));
-            if (collectionSlugs.length === 0) {
+            const requestedDocumentScope = body?.documentScope;
+            const configuredCollectionSlugs = getAllowedCollectionSlugs(req, options.collections);
+            const configuredCollectionSlugSet = new Set(configuredCollectionSlugs);
+            const allGlobalConfigs = req.payload.config.globals || [];
+            const requestedCollectionSlug = requestedDocumentScope?.type === "collection" && typeof requestedDocumentScope.collection === "string" ? requestedDocumentScope.collection.trim() : undefined;
+            const requestedGlobalSlug = requestedDocumentScope?.type === "global" && typeof requestedDocumentScope.slug === "string" ? requestedDocumentScope.slug.trim() : undefined;
+            const requestedDocumentID = requestedDocumentScope?.type === "collection" && typeof requestedDocumentScope.id === "string" ? requestedDocumentScope.id.trim() : undefined;
+            if (requestedDocumentScope?.type === "collection" && (!requestedCollectionSlug || !configuredCollectionSlugSet.has(requestedCollectionSlug))) {
+                return Response.json({
+                    error: "The current collection is not available to the AI assistant."
+                }, {
+                    status: 400
+                });
+            }
+            if (requestedDocumentScope?.type === "global" && (!requestedGlobalSlug || !allGlobalConfigs.some((global)=>global.slug === requestedGlobalSlug))) {
+                return Response.json({
+                    error: "The current global is not available to the AI assistant."
+                }, {
+                    status: 400
+                });
+            }
+            const collectionSlugs = requestedDocumentScope ? requestedCollectionSlug ? [
+                requestedCollectionSlug
+            ] : [] : configuredCollectionSlugs;
+            const collectionSlugSet = new Set(collectionSlugs);
+            const globalConfigs = requestedDocumentScope ? requestedGlobalSlug ? allGlobalConfigs.filter((global)=>global.slug === requestedGlobalSlug) : [] : allGlobalConfigs;
+            const globalSlugs = globalConfigs.map((global)=>global.slug);
+            const globalConfigsBySlug = new Map(globalConfigs.map((global)=>[
+                    global.slug,
+                    global
+                ]));
+            const allowedCollections = req.payload.config.collections.filter((collection)=>collectionSlugSet.has(collection.slug));
+            const allowedCollectionsBySlug = new Map(allowedCollections.map((collection)=>[
+                    collection.slug,
+                    collection
+                ]));
+            if (collectionSlugs.length === 0 && globalConfigs.length === 0) {
                 logHandlerEvent(req, "warn", {
                     debug,
                     msg: "AI chat blocked: no AI-enabled collections configured"
@@ -673,10 +916,10 @@ export const createChatHandler = (options = {})=>async (req)=>{
                         fields: collection.fields,
                         parent: collection.slug
                     })),
-                ...req.payload.config.globals?.flatMap((global)=>collectBlocks({
+                ...globalConfigs.flatMap((global)=>collectBlocks({
                         fields: global.fields,
                         parent: global.slug
-                    })) || []
+                    }))
             ];
             const mentionContext = await getMentionContext({
                 blockContexts,
@@ -686,15 +929,60 @@ export const createChatHandler = (options = {})=>async (req)=>{
                 mentions: body?.mentions,
                 req
             });
-            const mentionedCollectionSlugs = (body?.mentions?.flatMap((mention)=>{
-                if (mention.type === "collection" && mention.slug) return [
-                    mention.slug
-                ];
-                if (mention.type === "doc" && mention.collection) return [
-                    mention.collection
-                ];
-                return [];
-            }).filter((slug)=>collectionSlugs.includes(slug)) || []).filter((slug, index, array)=>array.indexOf(slug) === index);
+            if (requestedCollectionSlug && requestedDocumentID) {
+                const currentDocument = await req.payload.findByID({
+                    collection: requestedCollectionSlug,
+                    depth: 2,
+                    id: requestedDocumentID,
+                    ...activeLocale ? {
+                        locale: activeLocale
+                    } : {},
+                    overrideAccess: false,
+                    req
+                });
+                mentionContext.push({
+                    collection: requestedCollectionSlug,
+                    document: currentDocument,
+                    id: requestedDocumentID,
+                    type: "currentDocument"
+                });
+            } else if (requestedGlobalSlug) {
+                const currentGlobal = await req.payload.findGlobal({
+                    depth: 2,
+                    ...activeLocale ? {
+                        locale: activeLocale
+                    } : {},
+                    overrideAccess: false,
+                    req,
+                    slug: requestedGlobalSlug
+                });
+                mentionContext.push({
+                    global: currentGlobal,
+                    slug: requestedGlobalSlug,
+                    type: "currentGlobal"
+                });
+            }
+            const mediaAttachmentContext = await getMediaAttachmentContext({
+                allowedCollectionsBySlug,
+                attachments: body?.attachments,
+                collections: options.collections,
+                req
+            });
+            const allowedAttachmentKeys = new Set(mediaAttachmentContext.flatMap((context)=>{
+                const attachment = context.attachment;
+                return isRecord(attachment) && typeof attachment.collection === "string" && typeof attachment.id === "string" ? [
+                    `${attachment.collection}:${attachment.id}`
+                ] : [];
+            }));
+            mentionContext.push(...mediaAttachmentContext);
+            const mentionedCollectionSlugs = [];
+            const mentionedCollectionSlugSet = new Set();
+            for (const mention of body?.mentions || []){
+                const slug = mention.type === "collection" && mention.slug ? mention.slug : mention.type === "doc" && mention.collection ? mention.collection : null;
+                if (!slug || !collectionSlugSet.has(slug) || mentionedCollectionSlugSet.has(slug)) continue;
+                mentionedCollectionSlugSet.add(slug);
+                mentionedCollectionSlugs.push(slug);
+            }
             const createRequiredFieldsByCollection = Object.fromEntries(allowedCollections.map((collection)=>[
                     collection.slug,
                     getRequiredFieldInfos(collection.fields, collection.admin?.useAsTitle)
@@ -721,8 +1009,8 @@ export const createChatHandler = (options = {})=>async (req)=>{
                 prompt
             });
             const writeIntent = hasWriteIntent(prompt);
-            const inferredCollectionSlug = mentionedCollectionSlugs.length === 1 ? mentionedCollectionSlugs[0] : mentionedCollectionSlugs.length === 0 && likelyCollectionMatches.length === 1 ? likelyCollectionMatches[0] : undefined;
-            const inferredCollectionConfig = inferredCollectionSlug ? allowedCollections.find((collection)=>collection.slug === inferredCollectionSlug) : undefined;
+            const inferredCollectionSlug = requestedCollectionSlug || (mentionedCollectionSlugs.length === 1 ? mentionedCollectionSlugs[0] : mentionedCollectionSlugs.length === 0 && likelyCollectionMatches.length === 1 ? likelyCollectionMatches[0] : undefined);
+            const inferredCollectionConfig = inferredCollectionSlug ? allowedCollectionsBySlug.get(inferredCollectionSlug) : undefined;
             if (inferredCollectionConfig && !mentionContext.some((item)=>item.type === "collection" && item.slug === inferredCollectionConfig.slug)) {
                 mentionContext.push({
                     ...describeCollectionLikeConfig({
@@ -733,7 +1021,16 @@ export const createChatHandler = (options = {})=>async (req)=>{
                     inferredFromPrompt: true
                 });
             }
-            const intentToolChoice = inferredCollectionConfig ? getIntentToolChoice(prompt) : undefined;
+            if (requestedGlobalSlug) {
+                const currentGlobalConfig = globalConfigsBySlug.get(requestedGlobalSlug);
+                if (currentGlobalConfig) {
+                    mentionContext.push(describeCollectionLikeConfig({
+                        config: currentGlobalConfig,
+                        type: "global"
+                    }));
+                }
+            }
+            let intentToolChoice = inferredCollectionConfig ? getIntentToolChoice(prompt) : undefined;
             logHandlerEvent(req, "info", {
                 activeLocale,
                 allowedCollectionCount: allowedCollections.length,
@@ -747,7 +1044,7 @@ export const createChatHandler = (options = {})=>async (req)=>{
                 selectedLocales,
                 writeIntent
             });
-            const collectionSlugSchema = z.enum(collectionSlugs);
+            const collectionSlugSchema = collectionSlugs.length > 0 ? z.enum(collectionSlugs) : z.string().refine(()=>false, "No collection is in scope.");
             const getDisallowedCollectionActionError = (collection, action)=>{
                 if (isCollectionActionAllowed({
                     action,
@@ -761,14 +1058,21 @@ export const createChatHandler = (options = {})=>async (req)=>{
                     tool: "collectionPermissionCheck"
                 });
             };
-            const tools = {
+            const allTools = {
                 getDoc: {
-                    description: "Read one document by collection slug and document id.",
+                    description: "Read a document by collection and id.",
                     inputSchema: z.object({
                         collection: collectionSlugSchema,
                         id: z.string().min(1)
                     }),
                     execute: async ({ collection, id })=>{
+                        if (requestedDocumentScope && (collection !== requestedCollectionSlug || id !== requestedDocumentID)) {
+                            return createToolError({
+                                collection,
+                                message: "Only the current document can be read in this context.",
+                                tool: "getDoc"
+                            });
+                        }
                         return req.payload.findByID({
                             collection: collection,
                             depth: 2,
@@ -782,13 +1086,13 @@ export const createChatHandler = (options = {})=>async (req)=>{
                     }
                 },
                 listCollections: {
-                    description: "List AI-enabled Payload collections. Omit slug for compact summaries; pass slug to get full field schema for one collection.",
+                    description: "List collections; pass slug for one full schema.",
                     inputSchema: z.object({
                         slug: collectionSlugSchema.optional()
                     }),
                     execute: async ({ slug })=>{
                         if (slug) {
-                            const collection = allowedCollections.find((item)=>item.slug === slug);
+                            const collection = allowedCollectionsBySlug.get(slug);
                             if (!collection) {
                                 return createToolError({
                                     message: `Unknown collection: ${slug}`,
@@ -810,12 +1114,19 @@ export const createChatHandler = (options = {})=>async (req)=>{
                     }
                 },
                 getGlobal: {
-                    description: "Read one Payload CMS global by slug.",
+                    description: "Read a global by slug.",
                     inputSchema: z.object({
                         slug: z.string().min(1)
                     }),
                     execute: async ({ slug })=>{
-                        const globalConfig = req.payload.config.globals?.find((global)=>global.slug === slug);
+                        if (requestedDocumentScope && slug !== requestedGlobalSlug) {
+                            return createToolError({
+                                message: "Only the current global can be read in this context.",
+                                slug,
+                                tool: "getGlobal"
+                            });
+                        }
+                        const globalConfig = globalConfigsBySlug.get(slug);
                         if (!globalConfig) {
                             return createToolError({
                                 message: `Unknown global: ${slug}`,
@@ -835,14 +1146,13 @@ export const createChatHandler = (options = {})=>async (req)=>{
                     }
                 },
                 listGlobals: {
-                    description: "List Payload globals. Omit slug for compact summaries; pass slug to get full field schema for one global.",
+                    description: "List globals; pass slug for one full schema.",
                     inputSchema: z.object({
                         slug: z.string().optional()
                     }),
                     execute: async ({ slug })=>{
-                        const globals = req.payload.config.globals || [];
                         if (slug) {
-                            const global = globals.find((item)=>item.slug === slug);
+                            const global = globalConfigsBySlug.get(slug);
                             if (!global) {
                                 return createToolError({
                                     message: `Unknown global: ${slug}`,
@@ -855,14 +1165,14 @@ export const createChatHandler = (options = {})=>async (req)=>{
                                 type: "global"
                             });
                         }
-                        return globals.map((global)=>describeCollectionLikeSummary({
+                        return globalConfigs.map((global)=>describeCollectionLikeSummary({
                                 config: global,
                                 type: "global"
                             }));
                     }
                 },
                 proposeCreateDoc: {
-                    description: "Prepare a CMS document creation proposal. This does not write to the database. Use exact field names from listCollections. Include every required field for the target collection. For localizedData, include every localized required field in every locale entry, and include non-localized required fields in the first locale entry. For array fields, provide arrays of objects matching their child fields. For richText fields, prefer plain text or omit if unsure. Use localizedData when writing multiple locales in one proposal.",
+                    description: "Propose document creation. Use exact schema fields; include required fields. Use localizedData for multi-locale writes.",
                     inputSchema: z.object({
                         collection: collectionSlugSchema,
                         data: z.record(z.string(), z.unknown()).optional(),
@@ -874,7 +1184,7 @@ export const createChatHandler = (options = {})=>async (req)=>{
                     execute: async ({ collection, data, label, localizedData })=>{
                         const permissionError = getDisallowedCollectionActionError(collection, "create");
                         if (permissionError) return permissionError;
-                        const collectionConfig = allowedCollections.find((item)=>item.slug === collection);
+                        const collectionConfig = allowedCollectionsBySlug.get(collection);
                         const collectionFields = collectionConfig?.fields || [];
                         const preparedData = prepareProposalWriteData({
                             collectionConfig: collectionConfig,
@@ -935,6 +1245,31 @@ export const createChatHandler = (options = {})=>async (req)=>{
                                 });
                             }
                         }
+                        const uploadTargetsOutsideAttachments = [
+                            ...preparedData.data ? getUploadTargetsOutsideAttachments({
+                                allowedAttachmentKeys,
+                                data: preparedData.data,
+                                fields: collectionFields
+                            }) : [],
+                            ...preparedData.localizedData ? Object.values(preparedData.localizedData).flatMap((localeData)=>getUploadTargetsOutsideAttachments({
+                                    allowedAttachmentKeys,
+                                    data: localeData,
+                                    fields: collectionFields
+                                })) : []
+                        ];
+                        if (uploadTargetsOutsideAttachments.length > 0) {
+                            return createToolError({
+                                collection,
+                                details: {
+                                    allowedAttachments: [
+                                        ...allowedAttachmentKeys
+                                    ],
+                                    uploadTargetsOutsideAttachments
+                                },
+                                message: `Create proposal for ${collection} uses upload references that are not in the uploaded attachments: ${uploadTargetsOutsideAttachments.map((target)=>`${target.path} -> ${target.collection}:${target.id}`).join(", ")}. Use only uploaded media attachment IDs for upload fields.`,
+                                tool: "proposeCreateDoc"
+                            });
+                        }
                         const invalidRelationshipTargets = [
                             ...preparedData.data ? await validateRelationshipTargetsExist({
                                 data: preparedData.data,
@@ -978,13 +1313,20 @@ export const createChatHandler = (options = {})=>async (req)=>{
                     }
                 },
                 proposeDeleteDoc: {
-                    description: "Prepare a CMS document deletion proposal. This does not write to the database.",
+                    description: "Propose document deletion.",
                     inputSchema: z.object({
                         collection: collectionSlugSchema,
                         id: z.string().min(1),
                         label: z.string().min(1)
                     }),
                     execute: async ({ collection, id, label })=>{
+                        if (requestedDocumentScope && (collection !== requestedCollectionSlug || id !== requestedDocumentID)) {
+                            return createToolError({
+                                collection,
+                                message: "Only the current document can be deleted in this context.",
+                                tool: "proposeDeleteDoc"
+                            });
+                        }
                         const permissionError = getDisallowedCollectionActionError(collection, "delete");
                         if (permissionError) return permissionError;
                         const proposal = {
@@ -1000,7 +1342,7 @@ export const createChatHandler = (options = {})=>async (req)=>{
                     }
                 },
                 proposeUpdateDoc: {
-                    description: "Prepare a CMS document update proposal. This does not write to the database. Use exact field names from listCollections. For array fields, provide arrays of objects matching their child fields. For richText fields, prefer plain text or omit if unsure. Use localizedData when writing multiple locales in one proposal.",
+                    description: "Propose document update. Use exact schema fields. Use localizedData for multi-locale writes.",
                     inputSchema: z.object({
                         collection: collectionSlugSchema,
                         data: z.record(z.string(), z.unknown()).optional(),
@@ -1011,9 +1353,16 @@ export const createChatHandler = (options = {})=>async (req)=>{
                         message: "Either data or localizedData is required."
                     }),
                     execute: async ({ collection, data, id, label, localizedData })=>{
+                        if (requestedDocumentScope && (collection !== requestedCollectionSlug || id !== requestedDocumentID)) {
+                            return createToolError({
+                                collection,
+                                message: "Only the current document can be updated in this context.",
+                                tool: "proposeUpdateDoc"
+                            });
+                        }
                         const permissionError = getDisallowedCollectionActionError(collection, "update");
                         if (permissionError) return permissionError;
-                        const collectionConfig = allowedCollections.find((item)=>item.slug === collection);
+                        const collectionConfig = allowedCollectionsBySlug.get(collection);
                         const collectionFields = collectionConfig?.fields || [];
                         const preparedData = prepareProposalWriteData({
                             collectionConfig: collectionConfig,
@@ -1055,6 +1404,31 @@ export const createChatHandler = (options = {})=>async (req)=>{
                                 tool: "proposeUpdateDoc"
                             });
                         }
+                        const uploadTargetsOutsideAttachments = [
+                            ...preparedData.data ? getUploadTargetsOutsideAttachments({
+                                allowedAttachmentKeys,
+                                data: preparedData.data,
+                                fields: collectionFields
+                            }) : [],
+                            ...preparedData.localizedData ? Object.values(preparedData.localizedData).flatMap((localeData)=>getUploadTargetsOutsideAttachments({
+                                    allowedAttachmentKeys,
+                                    data: localeData,
+                                    fields: collectionFields
+                                })) : []
+                        ];
+                        if (uploadTargetsOutsideAttachments.length > 0) {
+                            return createToolError({
+                                collection,
+                                details: {
+                                    allowedAttachments: [
+                                        ...allowedAttachmentKeys
+                                    ],
+                                    uploadTargetsOutsideAttachments
+                                },
+                                message: `Update proposal for ${collection} uses upload references that are not in the uploaded attachments: ${uploadTargetsOutsideAttachments.map((target)=>`${target.path} -> ${target.collection}:${target.id}`).join(", ")}. Use only uploaded media attachment IDs for upload fields.`,
+                                tool: "proposeUpdateDoc"
+                            });
+                        }
                         const proposal = {
                             action: "update",
                             collection,
@@ -1073,7 +1447,7 @@ export const createChatHandler = (options = {})=>async (req)=>{
                     }
                 },
                 proposeUpdateGlobal: {
-                    description: "Prepare a Payload global update proposal. This does not write to the database. Use localizedData when writing multiple locales in one proposal.",
+                    description: "Propose global update. Use localizedData for multi-locale writes.",
                     inputSchema: z.object({
                         data: z.record(z.string(), z.unknown()).optional(),
                         label: z.string().min(1),
@@ -1083,7 +1457,14 @@ export const createChatHandler = (options = {})=>async (req)=>{
                         message: "Either data or localizedData is required."
                     }),
                     execute: async ({ data, label, localizedData, slug })=>{
-                        const globalConfig = req.payload.config.globals?.find((global)=>global.slug === slug);
+                        if (requestedDocumentScope && slug !== requestedGlobalSlug) {
+                            return createToolError({
+                                message: "Only the current global can be updated in this context.",
+                                slug,
+                                tool: "proposeUpdateGlobal"
+                            });
+                        }
+                        const globalConfig = globalConfigsBySlug.get(slug);
                         if (!globalConfig) {
                             return createToolError({
                                 message: `Unknown global: ${slug}`,
@@ -1129,19 +1510,24 @@ export const createChatHandler = (options = {})=>async (req)=>{
                     }
                 },
                 searchDocs: {
-                    description: "Search documents in one collection. Use query for a loose text search where possible.",
+                    description: "Search documents in one collection.",
                     inputSchema: z.object({
                         collection: collectionSlugSchema,
                         limit: z.number().int().min(1).max(10).default(5),
                         query: z.string().optional()
                     }),
                     execute: async ({ collection, limit, query })=>{
-                        const collectionConfig = allowedCollections.find((item)=>item.slug === collection);
-                        const searchableFields = collectionConfig?.fields.filter((field)=>"name" in field && [
+                        const collectionConfig = allowedCollectionsBySlug.get(collection);
+                        const searchableFields = collectionConfig?.fields.flatMap((field)=>{
+                            if (!("name" in field) || ![
                                 "email",
                                 "text",
                                 "textarea"
-                            ].includes(field.type)).map((field)=>"name" in field ? field.name : null).filter(Boolean) || [];
+                            ].includes(field.type) || !field.name) return [];
+                            return [
+                                field.name
+                            ];
+                        }) || [];
                         const where = query && searchableFields.length > 0 ? {
                             or: searchableFields.map((field)=>({
                                     [field]: {
@@ -1163,12 +1549,31 @@ export const createChatHandler = (options = {})=>async (req)=>{
                     }
                 }
             };
+            const scopedToolNames = requestedCollectionSlug ? requestedDocumentID ? new Set([
+                "getDoc",
+                "listCollections",
+                "proposeUpdateDoc"
+            ]) : new Set([
+                "listCollections",
+                "proposeCreateDoc"
+            ]) : requestedGlobalSlug ? new Set([
+                "getGlobal",
+                "listGlobals",
+                "proposeUpdateGlobal"
+            ]) : null;
+            const tools = scopedToolNames ? Object.fromEntries(Object.entries(allTools).filter(([name])=>scopedToolNames.has(name))) : allTools;
+            if (intentToolChoice && scopedToolNames && !scopedToolNames.has(intentToolChoice.toolName)) {
+                intentToolChoice = undefined;
+            }
             const encoder = new TextEncoder();
             const sendEvent = (controller, event, data)=>{
                 controller.enqueue(encoder.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`));
             };
             const model = await getModel({
                 apiKey: providerConfig.apiKey,
+                ...managedProvider?.baseURL ? {
+                    baseURL: managedProvider.baseURL
+                } : {},
                 model: providerConfig.modelID,
                 provider
             });
@@ -1184,6 +1589,9 @@ export const createChatHandler = (options = {})=>async (req)=>{
                     "You are a Payload CMS assistant. Inspect schema/content with tools before proposing writes.",
                     "Mentions define the active CMS scope. Locale mentions define active locale; multiple locales require localizedData keyed by locale.",
                     "Writes are proposals only. Never claim changes were applied before user confirmation.",
+                    "Uploaded media attachments appear in context as mediaAttachment entries. Use their exact IDs for upload fields.",
+                    "If an uploaded media document has editable descriptive fields, propose an update to that media document with suitable values.",
+                    "If a collection has a required `slug` field and the user does not provide it, generate a URL‑friendly slug from the title or from the first meaningful word of the prompt.",
                     "For create/update/delete requests, you must use proposal tools. Do not end with plain text if the user asked for a content change.",
                     "If the user asks to create, update, refine, translate, remove, or delete content, produce at least one proposal tool call unless blocked by missing schema information or permissions.",
                     "Put concrete field values only in tool data, not visible text.",
@@ -1224,6 +1632,23 @@ export const createChatHandler = (options = {})=>async (req)=>{
                             if (part.type === "finish") {
                                 const finishPart = part;
                                 usage = finishPart.totalUsage || finishPart.usage || null;
+                                if (usage && options.maxTokenUsage) {
+                                    try {
+                                        await recordTokenUsage({
+                                            model: providerConfig.modelID,
+                                            provider: managedProvider?.id || provider,
+                                            req,
+                                            usage,
+                                            userID: user.id
+                                        });
+                                    } catch (err) {
+                                        req.payload.logger.error({
+                                            err,
+                                            msg: "AI token usage could not be recorded",
+                                            userID: String(user.id)
+                                        });
+                                    }
+                                }
                                 const reason = getChatCompletionReason({
                                     proposalCount: proposals.length,
                                     toolFailures,