@mvriu5/payload-ai 0.5.10 → 1.2.0

package/dist/handlers/chatHandler.js

@@ -5,8 +5,134 @@ import { isAIProvider } from "../ai/providerOptions.js";
 import { getModel, getProviderConfig } from "../ai/providerRuntime.js";
 import { containsSensitiveData } from "../ai/sensitiveData.js";
 import { isCollectionActionAllowed } from "../payload/collectionPermissions.js";
+import { prepareProposalWriteData } from "../payload/proposalData.js";
 import { buildPromptWithMentionContext, collectBlocks, describeCollectionLikeConfig, describeCollectionLikeSummary, getAllowedCollectionSlugs, getMentionContext } from "../payload/schemaContext.js";
-import { getOptionValue, getSafeProposalLabel, hasLocalizedData, hasValueAtPath, setValueAtPath } from "../payload/shared.js";
+import { getLogPreview, logHandlerEvent } from "../payload/logging.js";
+import { getOptionValue, getSafeProposalLabel, hasLocalizedData, hasValueAtPath, isRecord, setValueAtPath } from "../payload/shared.js";
+const nonEmptyLocalizedDataSchema = z.record(z.string(), z.record(z.string(), z.unknown())).refine((value)=>Object.keys(value).length > 0, {
+    message: "localizedData must include at least one locale entry."
+});
+const e2eModeEnabled = ()=>process.env.PAYLOAD_AI_E2E_MODE === "true";
+const createSSEEventStream = (events)=>{
+    const encoder = new TextEncoder();
+    return new ReadableStream({
+        start (controller) {
+            for (const { data, event } of events){
+                controller.enqueue(encoder.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`));
+            }
+            controller.close();
+        }
+    });
+};
+const getChatCompletionReason = ({ proposalCount, toolFailures, writeIntent })=>{
+    if (proposalCount > 0) return "proposal_created";
+    if (toolFailures.length > 0) return "tool_validation_failed";
+    if (writeIntent) return "write_intent_without_tool_call";
+    return "model_did_not_call_tool";
+};
+const createDebugPayload = ({ activeLocale, debug, proposalCount, selectedLocales, toolFailures, usage, writeIntent })=>({
+        activeLocale,
+        model: debug.model,
+        proposalCount,
+        provider: debug.provider,
+        reason: getChatCompletionReason({
+            proposalCount,
+            toolFailures,
+            writeIntent
+        }),
+        selectedLocales,
+        toolFailures,
+        usage
+    });
+const createE2EChatResponse = ({ prompt, selectedLocales })=>{
+    const normalizedPrompt = prompt.toLowerCase();
+    const wantsCreatePost = normalizedPrompt.includes("post") && (normalizedPrompt.includes("create") || normalizedPrompt.includes("erstell"));
+    const mentionsMars = normalizedPrompt.includes("mars");
+    const multipleLocales = selectedLocales.length > 1;
+    const activeLocale = selectedLocales.at(-1);
+    const proposalLabel = multipleLocales ? normalizedPrompt.includes("locale review") ? "Create localized locale review draft post about Mars" : "Create localized draft post about Mars" : normalizedPrompt.includes("apply flow") ? "Create apply flow draft post about Mars" : normalizedPrompt.includes("proposal review") ? "Create proposal review draft post about Mars" : "Create draft post about Mars";
+    const proposal = wantsCreatePost && mentionsMars ? signAIActionProposal(multipleLocales ? {
+        action: "create",
+        collection: "posts",
+        label: proposalLabel,
+        localizedData: Object.fromEntries(selectedLocales.map((locale)=>[
+                locale,
+                {
+                    content: locale === "de" ? "Mars ist der vierte Planet von der Sonne." : "Mars is the fourth planet from the Sun.",
+                    excerpt: locale === "de" ? "Ein kurzer Entwurf ueber Mars." : "A short draft about Mars.",
+                    title: locale === "de" ? "Mars im Ueberblick" : "Mars Overview"
+                }
+            ])),
+        ...activeLocale ? {
+            locale: activeLocale
+        } : {}
+    } : {
+        action: "create",
+        collection: "posts",
+        data: {
+            content: "Mars is the fourth planet from the Sun.",
+            excerpt: "A short draft about Mars.",
+            status: "draft",
+            title: "Mars Overview"
+        },
+        label: proposalLabel,
+        ...activeLocale ? {
+            locale: activeLocale
+        } : {}
+    }) : null;
+    const responseText = proposal ? "Prepared one draft post proposal." : "No content change was proposed.";
+    const debugPayload = createDebugPayload({
+        debug: {
+            model: "e2e-model",
+            provider: "openai",
+            tools: []
+        },
+        proposalCount: proposal ? 1 : 0,
+        selectedLocales,
+        toolFailures: [],
+        usage: {
+            inputTokens: 42,
+            outputTokens: 27,
+            totalTokens: 69
+        },
+        writeIntent: wantsCreatePost
+    });
+    return new Response(createSSEEventStream([
+        {
+            data: {
+                delta: responseText
+            },
+            event: "text"
+        },
+        {
+            data: {
+                proposals: proposal ? [
+                    proposal
+                ] : [],
+                usage: {
+                    inputTokens: 42,
+                    outputTokens: 27,
+                    totalTokens: 69
+                }
+            },
+            event: "proposals"
+        },
+        {
+            data: debugPayload,
+            event: "debug"
+        },
+        {
+            data: {},
+            event: "done"
+        }
+    ]), {
+        headers: {
+            "Cache-Control": "no-cache, no-transform",
+            Connection: "keep-alive",
+            "Content-Type": "text/event-stream; charset=utf-8"
+        }
+    });
+};
 const getRequiredFieldInfos = (fields, titleFieldName, path = "")=>{
     return fields.flatMap((field)=>{
         const fieldPath = field.name ? path ? `${path}.${field.name}` : field.name : path;
@@ -134,6 +260,277 @@ const getMissingCreateFields = ({ data, localizedData, requiredFields })=>{
     ];
     return requiredFields.filter((field)=>!hasValueAtPath(data, field.path)).map((field)=>field.path);
 };
+const getProposalSummary = (proposal)=>({
+        action: proposal.action,
+        collection: "collection" in proposal ? proposal.collection : undefined,
+        hasData: "data" in proposal && Boolean(proposal.data),
+        hasLocalizedData: "localizedData" in proposal && Boolean(proposal.localizedData),
+        id: "id" in proposal ? proposal.id : undefined,
+        label: proposal.label,
+        locale: proposal.locale,
+        locales: "localizedData" in proposal && proposal.localizedData ? Object.keys(proposal.localizedData) : undefined,
+        slug: "slug" in proposal ? proposal.slug : undefined
+    });
+const getCollectionBlockTypes = (fields)=>{
+    const blockTypes = new Set();
+    const visitFields = (items)=>{
+        for (const field of items){
+            if (field.type === "blocks" && field.blocks) {
+                for (const block of field.blocks){
+                    blockTypes.add(block.slug);
+                    if (block.fields?.length) {
+                        visitFields(block.fields);
+                    }
+                }
+            }
+            if (field.fields?.length) {
+                visitFields(field.fields);
+            }
+        }
+    };
+    visitFields(fields);
+    return [
+        ...blockTypes
+    ];
+};
+const getRequestedBlockTypes = ({ availableBlockTypes, mentions, prompt })=>{
+    const requestedBlockTypes = new Set();
+    const normalizedPrompt = prompt.toLowerCase();
+    for (const mention of mentions || []){
+        if (mention.type === "block" && mention.slug && availableBlockTypes.includes(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);
+        }
+    }
+    return [
+        ...requestedBlockTypes
+    ];
+};
+const collectProposalBlockTypes = ({ data, fields })=>{
+    const foundBlockTypes = new Set();
+    const visitFields = (items, value)=>{
+        for (const field of items){
+            if (!field.name) continue;
+            const fieldValue = value[field.name];
+            if (fieldValue === undefined || fieldValue === null) continue;
+            if (field.type === "blocks" && Array.isArray(fieldValue)) {
+                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;
+                    if (blockType) {
+                        foundBlockTypes.add(blockType);
+                    }
+                    if (blockType) {
+                        const blockConfig = field.blocks?.find((candidate)=>candidate.slug === blockType);
+                        if (blockConfig?.fields?.length) {
+                            visitFields(blockConfig.fields, blockItem);
+                        }
+                    }
+                }
+                continue;
+            }
+            if (field.type === "group" && isRecord(fieldValue) && field.fields?.length) {
+                visitFields(field.fields, fieldValue);
+                continue;
+            }
+            if (field.type === "array" && Array.isArray(fieldValue) && field.fields?.length) {
+                for (const item of fieldValue){
+                    if (isRecord(item)) {
+                        visitFields(field.fields, item);
+                    }
+                }
+            }
+        }
+    };
+    visitFields(fields, data);
+    return foundBlockTypes;
+};
+const collectRelationshipTargets = ({ 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 === "relationship" || 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(...collectRelationshipTargets({
+                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(...collectRelationshipTargets({
+                    data: item,
+                    fields: field.fields,
+                    path: `${fieldPath}.${index}`
+                }));
+            });
+            continue;
+        }
+        if (field.type === "blocks" && Array.isArray(fieldValue) && field.blocks?.length) {
+            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);
+                if (!blockConfig?.fields?.length) return;
+                targets.push(...collectRelationshipTargets({
+                    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){
+        try {
+            await req.payload.findByID({
+                collection: target.collection,
+                depth: 0,
+                id: String(target.id),
+                overrideAccess: false,
+                req
+            });
+        } catch  {
+            invalidTargets.push(target);
+        }
+    }
+    return invalidTargets;
+};
+const getMentionSummary = (mentions)=>mentions?.map((mention)=>({
+            collection: "collection" in mention ? mention.collection : undefined,
+            id: "id" in mention ? mention.id : undefined,
+            slug: mention.slug,
+            type: mention.type
+        })) || [];
+const formatProposalIssuesForRetry = (issues)=>{
+    return issues.slice(0, 6).map((issue)=>{
+        switch(issue.code){
+            case "invalid_block_type":
+                return `${issue.path}: use an exact blockType from the schema`;
+            case "invalid_blocks":
+                return `${issue.path}: blocks fields must be arrays of objects with blockType and exact field names`;
+            case "invalid_array":
+                return `${issue.path}: array fields must be arrays of complete objects`;
+            case "missing_required_field":
+                return `${issue.path}: required field missing`;
+            case "unknown_field":
+                return `${issue.path}: unknown field, use exact schema field names only`;
+            case "invalid_relationship":
+                return `${issue.path}: use relationship IDs or { relationTo, value }, not free text`;
+            default:
+                return `${issue.path}: ${issue.message}`;
+        }
+    }).join("; ");
+};
+const createCollectionAliasMap = (collections)=>{
+    const aliasMap = new Map();
+    const addAlias = (alias, slug)=>{
+        const normalizedAlias = alias?.trim().toLowerCase();
+        if (!normalizedAlias) return;
+        if (!aliasMap.has(normalizedAlias)) {
+            aliasMap.set(normalizedAlias, slug);
+        }
+    };
+    for (const collection of collections){
+        addAlias(collection.slug, collection.slug);
+        addAlias(collection.slug.replace(/-/g, " "), collection.slug);
+        const singular = typeof collection.labels?.singular === "string" ? collection.labels.singular : undefined;
+        const plural = typeof collection.labels?.plural === "string" ? collection.labels.plural : undefined;
+        addAlias(singular, collection.slug);
+        addAlias(plural, collection.slug);
+        if (singular?.endsWith("s")) {
+            addAlias(singular.slice(0, -1), collection.slug);
+        }
+        if (plural?.endsWith("s")) {
+            addAlias(plural.slice(0, -1), collection.slug);
+        }
+    }
+    return Object.fromEntries(aliasMap.entries());
+};
+const getLikelyCollectionMatches = ({ aliasMap, prompt })=>{
+    const normalizedPrompt = prompt.toLowerCase();
+    const matches = Object.entries(aliasMap).filter(([alias])=>normalizedPrompt.includes(alias)).map(([, slug])=>slug);
+    return [
+        ...new Set(matches)
+    ];
+};
+const hasWriteIntent = (prompt)=>{
+    const normalizedPrompt = prompt.toLowerCase();
+    return /\b(create|build|generate|write|draft|make|add|update|edit|change|revise|refine|rewrite|translate|delete|remove)\b/.test(normalizedPrompt);
+};
+const getIntentToolChoice = (prompt)=>{
+    const normalizedPrompt = prompt.toLowerCase();
+    if (/\b(delete|remove)\b/.test(normalizedPrompt)) {
+        return {
+            toolName: "proposeDeleteDoc",
+            type: "tool"
+        };
+    }
+    if (/\b(create|build|generate|write|draft|make|add)\b/.test(normalizedPrompt)) {
+        return {
+            toolName: "proposeCreateDoc",
+            type: "tool"
+        };
+    }
+    if (/\b(update|edit|change|revise|refine|rewrite|translate)\b/.test(normalizedPrompt)) {
+        return {
+            toolName: "proposeUpdateDoc",
+            type: "tool"
+        };
+    }
+    return undefined;
+};
 export const createChatHandler = (options = {})=>async (req)=>{
         if (!req.user) return Response.json({
             error: "Unauthorized"
@@ -147,6 +544,15 @@ 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 activeLocale = selectedLocales.at(-1);
+        const mentionSummary = getMentionSummary(body?.mentions);
+        if (e2eModeEnabled()) {
+            return createE2EChatResponse({
+                prompt,
+                selectedLocales
+            });
+        }
         const user = req.user;
         const requestedProvider = body?.provider || user.aiProvider || "openai";
         if (!isAIProvider(requestedProvider)) return Response.json({
@@ -177,7 +583,23 @@ export const createChatHandler = (options = {})=>async (req)=>{
                 "searchDocs"
             ]
         };
+        logHandlerEvent(req, "info", {
+            activeLocale,
+            debug,
+            mentionCount: mentionSummary.length,
+            mentions: mentionSummary,
+            msg: "AI chat started",
+            promptPreview: getLogPreview(prompt),
+            selectedLocales
+        });
         if (!providerConfig.apiKey) {
+            logHandlerEvent(req, "warn", {
+                activeLocale,
+                debug,
+                msg: "AI chat blocked: missing provider API key",
+                promptPreview: getLogPreview(prompt),
+                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.`
             }, {
@@ -186,25 +608,60 @@ export const createChatHandler = (options = {})=>async (req)=>{
         }
         try {
             const proposals = [];
+            const toolFailures = [];
+            const registerToolFailure = (failure)=>{
+                toolFailures.push(failure);
+                logHandlerEvent(req, "warn", {
+                    debug,
+                    ...failure,
+                    msg: "AI tool validation failed",
+                    promptPreview: getLogPreview(prompt)
+                });
+            };
+            const createToolError = ({ collection, details, message, slug, tool })=>{
+                registerToolFailure({
+                    collection,
+                    details,
+                    message,
+                    slug,
+                    tool
+                });
+                return {
+                    error: message
+                };
+            };
             const addSignedProposal = (proposal)=>{
                 if ("data" in proposal && proposal.data && containsSensitiveData(proposal.data)) {
-                    return {
-                        error: "Proposal contains sensitive fields and cannot be created."
-                    };
+                    return createToolError({
+                        details: getProposalSummary(proposal),
+                        message: "Proposal contains sensitive fields and cannot be created.",
+                        tool: `propose${proposal.action[0]?.toUpperCase()}${proposal.action.slice(1)}`
+                    });
                 }
                 if ("localizedData" in proposal && hasLocalizedData(proposal.localizedData) && Object.values(proposal.localizedData).some((value)=>containsSensitiveData(value))) {
-                    return {
-                        error: "Proposal contains sensitive fields and cannot be created."
-                    };
+                    return createToolError({
+                        details: getProposalSummary(proposal),
+                        message: "Proposal contains sensitive fields and cannot be created.",
+                        tool: `propose${proposal.action[0]?.toUpperCase()}${proposal.action.slice(1)}`
+                    });
                 }
                 const signedProposal = signAIActionProposal(proposal);
                 proposals.push(signedProposal);
+                logHandlerEvent(req, "info", {
+                    debug,
+                    msg: "AI proposal created",
+                    proposal: getProposalSummary(signedProposal)
+                });
                 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) {
+                logHandlerEvent(req, "warn", {
+                    debug,
+                    msg: "AI chat blocked: no AI-enabled collections configured"
+                });
                 return Response.json({
                     error: "No AI-enabled collections are configured."
                 }, {
@@ -229,8 +686,6 @@ export const createChatHandler = (options = {})=>async (req)=>{
                 mentions: body?.mentions,
                 req
             });
-            const selectedLocales = (body?.mentions?.filter((mention)=>mention.type === "locale" && mention.slug).map((mention)=>mention.slug) || []).filter((locale, index, array)=>array.indexOf(locale) === index);
-            const activeLocale = selectedLocales.at(-1);
             const mentionedCollectionSlugs = (body?.mentions?.flatMap((mention)=>{
                 if (mention.type === "collection" && mention.slug) return [
                     mention.slug
@@ -260,6 +715,38 @@ export const createChatHandler = (options = {})=>async (req)=>{
                         titleFieldByCollection[slug]
                     ]
                 ] : []));
+            const collectionAliasMap = createCollectionAliasMap(allowedCollections);
+            const likelyCollectionMatches = getLikelyCollectionMatches({
+                aliasMap: collectionAliasMap,
+                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;
+            if (inferredCollectionConfig && !mentionContext.some((item)=>item.type === "collection" && item.slug === inferredCollectionConfig.slug)) {
+                mentionContext.push({
+                    ...describeCollectionLikeConfig({
+                        config: inferredCollectionConfig,
+                        permissions: options.collections,
+                        type: "collection"
+                    }),
+                    inferredFromPrompt: true
+                });
+            }
+            const intentToolChoice = inferredCollectionConfig ? getIntentToolChoice(prompt) : undefined;
+            logHandlerEvent(req, "info", {
+                activeLocale,
+                allowedCollectionCount: allowedCollections.length,
+                collectionSlugs,
+                focusedCollections: mentionedCollectionSlugs,
+                globalSlugs,
+                inferredCollectionSlug,
+                intentToolChoice,
+                likelyCollectionMatches,
+                msg: "AI chat context prepared",
+                selectedLocales,
+                writeIntent
+            });
             const collectionSlugSchema = z.enum(collectionSlugs);
             const getDisallowedCollectionActionError = (collection, action)=>{
                 if (isCollectionActionAllowed({
@@ -268,9 +755,11 @@ export const createChatHandler = (options = {})=>async (req)=>{
                     req,
                     slug: collection
                 })) return null;
-                return {
-                    error: `${action} is not enabled for collection: ${collection}`
-                };
+                return createToolError({
+                    collection,
+                    message: `${action} is not enabled for collection: ${collection}`,
+                    tool: "collectionPermissionCheck"
+                });
             };
             const tools = {
                 getDoc: {
@@ -300,9 +789,13 @@ export const createChatHandler = (options = {})=>async (req)=>{
                     execute: async ({ slug })=>{
                         if (slug) {
                             const collection = allowedCollections.find((item)=>item.slug === slug);
-                            if (!collection) return {
-                                error: `Unknown collection: ${slug}`
-                            };
+                            if (!collection) {
+                                return createToolError({
+                                    message: `Unknown collection: ${slug}`,
+                                    slug,
+                                    tool: "listCollections"
+                                });
+                            }
                             return describeCollectionLikeConfig({
                                 config: collection,
                                 permissions: options.collections,
@@ -323,9 +816,13 @@ export const createChatHandler = (options = {})=>async (req)=>{
                     }),
                     execute: async ({ slug })=>{
                         const globalConfig = req.payload.config.globals?.find((global)=>global.slug === slug);
-                        if (!globalConfig) return {
-                            error: `Unknown global: ${slug}`
-                        };
+                        if (!globalConfig) {
+                            return createToolError({
+                                message: `Unknown global: ${slug}`,
+                                slug,
+                                tool: "getGlobal"
+                            });
+                        }
                         return req.payload.findGlobal({
                             depth: 2,
                             ...activeLocale ? {
@@ -346,9 +843,13 @@ export const createChatHandler = (options = {})=>async (req)=>{
                         const globals = req.payload.config.globals || [];
                         if (slug) {
                             const global = globals.find((item)=>item.slug === slug);
-                            if (!global) return {
-                                error: `Unknown global: ${slug}`
-                            };
+                            if (!global) {
+                                return createToolError({
+                                    message: `Unknown global: ${slug}`,
+                                    slug,
+                                    tool: "listGlobals"
+                                });
+                            }
                             return describeCollectionLikeConfig({
                                 config: global,
                                 type: "global"
@@ -366,43 +867,108 @@ export const createChatHandler = (options = {})=>async (req)=>{
                         collection: collectionSlugSchema,
                         data: z.record(z.string(), z.unknown()).optional(),
                         label: z.string().min(1),
-                        localizedData: z.record(z.string(), z.record(z.string(), z.unknown())).optional()
+                        localizedData: nonEmptyLocalizedDataSchema.optional()
                     }).refine((value)=>Boolean(value.data || value.localizedData), {
                         message: "Either data or localizedData is required."
                     }),
                     execute: async ({ collection, data, label, localizedData })=>{
                         const permissionError = getDisallowedCollectionActionError(collection, "create");
                         if (permissionError) return permissionError;
-                        const completedCreatePayload = fillMissingCreateFields({
+                        const collectionConfig = allowedCollections.find((item)=>item.slug === collection);
+                        const collectionFields = collectionConfig?.fields || [];
+                        const preparedData = prepareProposalWriteData({
+                            collectionConfig: collectionConfig,
                             data,
+                            inferenceText: prompt,
                             label,
                             localizedData,
-                            requiredFields: createRequiredFieldsByCollection[collection] || []
-                        });
-                        const missingFields = getMissingCreateFields({
-                            data: completedCreatePayload.data,
-                            localizedData: completedCreatePayload.localizedData,
-                            requiredFields: createRequiredFieldsByCollection[collection] || []
+                            mode: "create"
                         });
-                        if (missingFields.length > 0) {
+                        if (preparedData.issues.length > 0) {
                             const titleFieldName = titleFieldByCollection[collection];
-                            const missingTitleField = titleFieldName ? missingFields.some((field)=>field === titleFieldName || field.endsWith(`:${titleFieldName}`)) : false;
-                            return {
-                                error: missingTitleField ? `Create proposal is missing the required title field "${titleFieldName}" for ${collection}. Infer a concise title from the user request and retry.` : `Create proposal is missing required fields for ${collection}: ${missingFields.join(", ")}`
-                            };
+                            const missingTitleField = titleFieldName ? preparedData.issues.some((issue)=>issue.path === titleFieldName || issue.path.endsWith(`.${titleFieldName}`)) : false;
+                            return createToolError({
+                                collection,
+                                details: {
+                                    issues: preparedData.issues,
+                                    titleFieldName
+                                },
+                                message: missingTitleField ? `Create proposal is missing the required title field "${titleFieldName}" for ${collection}. Infer a concise title from the user request and retry.` : `Create proposal for ${collection} is invalid. Retry with exact schema fields and complete array/block objects: ${formatProposalIssuesForRetry(preparedData.issues)}`,
+                                tool: "proposeCreateDoc"
+                            });
+                        }
+                        const requestedBlockTypes = getRequestedBlockTypes({
+                            availableBlockTypes: getCollectionBlockTypes(collectionFields),
+                            mentions: body?.mentions,
+                            prompt
+                        });
+                        if (requestedBlockTypes.length > 0) {
+                            const proposalBlockTypes = new Set();
+                            if (preparedData.data) {
+                                for (const blockType of collectProposalBlockTypes({
+                                    data: preparedData.data,
+                                    fields: collectionFields
+                                })){
+                                    proposalBlockTypes.add(blockType);
+                                }
+                            }
+                            if (preparedData.localizedData) {
+                                for (const localeData of Object.values(preparedData.localizedData)){
+                                    for (const blockType of collectProposalBlockTypes({
+                                        data: localeData,
+                                        fields: collectionFields
+                                    })){
+                                        proposalBlockTypes.add(blockType);
+                                    }
+                                }
+                            }
+                            const missingBlockTypes = requestedBlockTypes.filter((blockType)=>!proposalBlockTypes.has(blockType));
+                            if (missingBlockTypes.length > 0) {
+                                return createToolError({
+                                    collection,
+                                    details: {
+                                        missingBlockTypes,
+                                        requestedBlockTypes
+                                    },
+                                    message: `Create proposal for ${collection} is missing required block types from the request: ${missingBlockTypes.join(", ")}. Add them to the appropriate blocks field using exact blockType values and complete required fields.`,
+                                    tool: "proposeCreateDoc"
+                                });
+                            }
                         }
-                        const proposal = completedCreatePayload.localizedData ? {
+                        const invalidRelationshipTargets = [
+                            ...preparedData.data ? await validateRelationshipTargetsExist({
+                                data: preparedData.data,
+                                fields: collectionFields,
+                                req
+                            }) : [],
+                            ...preparedData.localizedData ? (await Promise.all(Object.values(preparedData.localizedData).map((localeData)=>validateRelationshipTargetsExist({
+                                    data: localeData,
+                                    fields: collectionFields,
+                                    req
+                                })))).flat() : []
+                        ];
+                        if (invalidRelationshipTargets.length > 0) {
+                            return createToolError({
+                                collection,
+                                details: {
+                                    invalidRelationshipTargets
+                                },
+                                message: `Create proposal for ${collection} contains relationship or upload references that do not exist: ${invalidRelationshipTargets.map((target)=>`${target.path} -> ${target.collection}:${target.id}`).join(", ")}.`,
+                                tool: "proposeCreateDoc"
+                            });
+                        }
+                        const proposal = preparedData.localizedData ? {
                             action: "create",
                             collection,
                             label: getSafeProposalLabel(label),
-                            localizedData: completedCreatePayload.localizedData,
+                            localizedData: preparedData.localizedData,
                             ...activeLocale ? {
                                 locale: activeLocale
                             } : {}
                         } : {
                             action: "create",
                             collection,
-                            data: completedCreatePayload.data || {},
+                            data: preparedData.data || {},
                             label: getSafeProposalLabel(label),
                             ...activeLocale ? {
                                 locale: activeLocale
@@ -440,20 +1006,62 @@ export const createChatHandler = (options = {})=>async (req)=>{
                         data: z.record(z.string(), z.unknown()).optional(),
                         id: z.string().min(1),
                         label: z.string().min(1),
-                        localizedData: z.record(z.string(), z.record(z.string(), z.unknown())).optional()
+                        localizedData: nonEmptyLocalizedDataSchema.optional()
                     }).refine((value)=>Boolean(value.data || value.localizedData), {
                         message: "Either data or localizedData is required."
                     }),
                     execute: async ({ collection, data, id, label, localizedData })=>{
                         const permissionError = getDisallowedCollectionActionError(collection, "update");
                         if (permissionError) return permissionError;
+                        const collectionConfig = allowedCollections.find((item)=>item.slug === collection);
+                        const collectionFields = collectionConfig?.fields || [];
+                        const preparedData = prepareProposalWriteData({
+                            collectionConfig: collectionConfig,
+                            data,
+                            inferenceText: prompt,
+                            label,
+                            localizedData,
+                            mode: "update"
+                        });
+                        if (preparedData.issues.length > 0) {
+                            return createToolError({
+                                collection,
+                                details: {
+                                    issues: preparedData.issues
+                                },
+                                message: `Update proposal for ${collection} is invalid. Retry with exact schema fields and complete array/block objects: ${formatProposalIssuesForRetry(preparedData.issues)}`,
+                                tool: "proposeUpdateDoc"
+                            });
+                        }
+                        const invalidRelationshipTargets = [
+                            ...preparedData.data ? await validateRelationshipTargetsExist({
+                                data: preparedData.data,
+                                fields: collectionFields,
+                                req
+                            }) : [],
+                            ...preparedData.localizedData ? (await Promise.all(Object.values(preparedData.localizedData).map((localeData)=>validateRelationshipTargetsExist({
+                                    data: localeData,
+                                    fields: collectionFields,
+                                    req
+                                })))).flat() : []
+                        ];
+                        if (invalidRelationshipTargets.length > 0) {
+                            return createToolError({
+                                collection,
+                                details: {
+                                    invalidRelationshipTargets
+                                },
+                                message: `Update proposal for ${collection} contains relationship or upload references that do not exist: ${invalidRelationshipTargets.map((target)=>`${target.path} -> ${target.collection}:${target.id}`).join(", ")}.`,
+                                tool: "proposeUpdateDoc"
+                            });
+                        }
                         const proposal = {
                             action: "update",
                             collection,
-                            ...localizedData ? {
-                                localizedData
+                            ...preparedData.localizedData ? {
+                                localizedData: preparedData.localizedData
                             } : {
-                                data: data || {}
+                                data: preparedData.data || {}
                             },
                             id,
                             label: getSafeProposalLabel(label),
@@ -469,22 +1077,47 @@ export const createChatHandler = (options = {})=>async (req)=>{
                     inputSchema: z.object({
                         data: z.record(z.string(), z.unknown()).optional(),
                         label: z.string().min(1),
-                        localizedData: z.record(z.string(), z.record(z.string(), z.unknown())).optional(),
+                        localizedData: nonEmptyLocalizedDataSchema.optional(),
                         slug: z.string().min(1)
                     }).refine((value)=>Boolean(value.data || value.localizedData), {
                         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 (!globalConfig) return {
-                            error: `Unknown global: ${slug}`
-                        };
+                        if (!globalConfig) {
+                            return createToolError({
+                                message: `Unknown global: ${slug}`,
+                                slug,
+                                tool: "proposeUpdateGlobal"
+                            });
+                        }
+                        const preparedData = prepareProposalWriteData({
+                            collectionConfig: {
+                                fields: globalConfig.fields || [],
+                                slug: globalConfig.slug
+                            },
+                            data,
+                            inferenceText: prompt,
+                            label,
+                            localizedData,
+                            mode: "update"
+                        });
+                        if (preparedData.issues.length > 0) {
+                            return createToolError({
+                                details: {
+                                    issues: preparedData.issues
+                                },
+                                message: `Update proposal for global ${slug} is invalid. Retry with exact schema fields and complete array/block objects: ${formatProposalIssuesForRetry(preparedData.issues)}`,
+                                slug,
+                                tool: "proposeUpdateGlobal"
+                            });
+                        }
                         const proposal = {
                             action: "updateGlobal",
-                            ...localizedData ? {
-                                localizedData
+                            ...preparedData.localizedData ? {
+                                localizedData: preparedData.localizedData
                             } : {
-                                data: data || {}
+                                data: preparedData.data || {}
                             },
                             label: getSafeProposalLabel(label),
                             ...activeLocale ? {
@@ -551,12 +1184,22 @@ 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.",
-                    "For create/update/delete use proposal tools. Put concrete field values only in tool data, not visible text.",
-                    "If schema details are missing, call listCollections/listGlobals with a slug before proposing.",
+                    "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.",
+                    "For blocks fields: use exact blockType values from schema, exact field names, and complete objects for required block fields.",
+                    "For arrays: every item must be an object matching the child field schema, not free text.",
+                    "If schema details are missing, call listCollections/listGlobals with a slug before proposing. If an inferred collection schema is already present in context, use it directly.",
+                    `Collection aliases: ${JSON.stringify(collectionAliasMap)}.`,
+                    `Likely collection matches for this prompt: ${JSON.stringify(likelyCollectionMatches)}.`,
                     `Focused required create fields: ${JSON.stringify(focusedRequiredFieldsByCollection)}.`,
                     `Focused title fields: ${JSON.stringify(focusedTitleFieldByCollection)}. Infer concise titles when needed.`,
+                    `Preferred proposal tool for this prompt: ${intentToolChoice?.toolName || "none"}.`,
                     "Visible response: plain text, under 40 words, no Markdown, no proposed content."
                 ].join("\n"),
+                ...intentToolChoice ? {
+                    toolChoice: intentToolChoice
+                } : {},
                 tools
             });
             const stream = new ReadableStream({
@@ -581,19 +1224,75 @@ export const createChatHandler = (options = {})=>async (req)=>{
                             if (part.type === "finish") {
                                 const finishPart = part;
                                 usage = finishPart.totalUsage || finishPart.usage || null;
+                                const reason = getChatCompletionReason({
+                                    proposalCount: proposals.length,
+                                    toolFailures,
+                                    writeIntent
+                                });
+                                const debugPayload = createDebugPayload({
+                                    activeLocale,
+                                    debug,
+                                    proposalCount: proposals.length,
+                                    selectedLocales,
+                                    toolFailures,
+                                    usage,
+                                    writeIntent
+                                });
+                                logHandlerEvent(req, proposals.length > 0 ? "info" : "warn", {
+                                    activeLocale,
+                                    debug,
+                                    msg: proposals.length > 0 ? "AI chat completed with proposals" : "AI chat completed without proposals",
+                                    proposalCount: proposals.length,
+                                    proposals: proposals.map((proposal)=>getProposalSummary(proposal)),
+                                    promptPreview: getLogPreview(prompt),
+                                    reason,
+                                    selectedLocales,
+                                    toolFailureCount: toolFailures.length,
+                                    toolFailures,
+                                    usage
+                                });
                                 sendEvent(controller, "proposals", {
                                     proposals,
                                     usage
                                 });
+                                sendEvent(controller, "debug", debugPayload);
                                 sendEvent(controller, "done", {});
                                 didSendTerminalEvent = true;
                             }
                         }
                         if (!didSendTerminalEvent) {
+                            const reason = getChatCompletionReason({
+                                proposalCount: proposals.length,
+                                toolFailures,
+                                writeIntent
+                            });
+                            const debugPayload = createDebugPayload({
+                                activeLocale,
+                                debug,
+                                proposalCount: proposals.length,
+                                selectedLocales,
+                                toolFailures,
+                                usage,
+                                writeIntent
+                            });
+                            logHandlerEvent(req, proposals.length > 0 ? "info" : "warn", {
+                                activeLocale,
+                                debug,
+                                msg: proposals.length > 0 ? "AI chat completed with proposals" : "AI chat completed without proposals",
+                                proposalCount: proposals.length,
+                                proposals: proposals.map((proposal)=>getProposalSummary(proposal)),
+                                promptPreview: getLogPreview(prompt),
+                                reason,
+                                selectedLocales,
+                                toolFailureCount: toolFailures.length,
+                                toolFailures,
+                                usage
+                            });
                             sendEvent(controller, "proposals", {
                                 proposals,
                                 usage
                             });
+                            sendEvent(controller, "debug", debugPayload);
                             sendEvent(controller, "done", {});
                         }
                     } catch (err) {