@mvriu5/payload-ai 1.6.2 → 1.6.4

package/dist/handlers/chatHandler.js

@@ -1,568 +1,21 @@
 import { stepCountIs, streamText } from "ai";
 import { z } from "zod";
-import { signAIActionProposal } from "../ai/proposalSigning.js";
-import { isAIProvider } from "../ai/providerOptions.js";
-import { getModel, getProviderConfig } from "../ai/providerRuntime.js";
-import { createCachedSystemMessages, createPromptCacheProviderOptions, splitPromptCacheContext } from "../ai/promptCaching.js";
-import { compactProposalRepairIssues, createProposalRepairTracker } from "../ai/proposalRepair.js";
-import { containsSensitiveData, isSensitiveKey, redactSensitiveData } 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";
-import { getLogPreview, logHandlerEvent } from "../payload/logging.js";
-import { getOptionValue, getSafeProposalLabel, hasLocalizedData, hasValueAtPath, isRecord, setValueAtPath } from "../payload/shared.js";
-import { createLocalizedPayloadDataSchema, createPayloadDataSchema, genericPayloadDataSchema } from "../payload/toolSchemas.js";
-import { createToolFieldNamesSchema, resolveToolFieldSelection } from "../payload/toolFieldSelection.js";
+import { compactProposalRepairIssues } from "../features/proposals/repair.js";
+import { isSensitiveKey, redactSensitiveData } from "../features/sensitiveData.js";
+import { resolveAIRequestContext } from "../features/providers/requestContext.js";
+import { prepareProposalWriteData } from "../features/proposals/data.js";
+import { buildPromptWithMentionContext, createSchemaContextRegistry, describeCollectionLikeConfig, describeCollectionLikeSummary, getAllowedCollectionSlugs, getMentionContext } from "../features/schema/context.js";
+import { getLogPreview, logHandlerEvent } from "../utils/logging.js";
+import { getSafeProposalLabel, isRecord } from "../utils/data.js";
+import { createLocalizedPayloadDataSchema, createPayloadDataSchema, genericPayloadDataSchema } from "../features/schema/toolSchemas.js";
+import { createToolFieldNamesSchema, resolveToolFieldSelection } from "../features/schema/fieldSelection.js";
+import { createCollectionAliasMap, getChatIntent, getIntentToolChoice, getLikelyCollectionMatches, getToolNamesForIntent } from "./chat/intent.js";
+import { createChatPromptContext } from "./chat/prompt.js";
+import { createChatToolFactory } from "./chat/toolFactory.js";
+import { jsonError, logHandlerError, readJSONBody, withAuthenticatedHandler } from "./http.js";
+import { collectProposalBlockTypes, getCollectionBlockTypes, getProposalSummary, getRequestedBlockTypes, getRequiredFieldInfos, validateProposalReferences } from "./chat/proposalTools.js";
+import { createDebugPayload, createE2EChatResponse, createInitialChatDebug, getChatCompletionReason } from "./chat/streaming.js";
 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") || 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);
-    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;
-        const requiredField = field.required && fieldPath ? [
-            {
-                defaultValue: field.defaultValue,
-                isTitleField: field.name === titleFieldName,
-                localized: Boolean(field.localized),
-                options: field.options,
-                path: fieldPath,
-                type: field.type
-            }
-        ] : [];
-        const nestedFields = field.fields?.length ? getRequiredFieldInfos(field.fields, titleFieldName, fieldPath) : [];
-        const nestedBlocks = field.blocks?.length ? field.blocks.flatMap((block)=>getRequiredFieldInfos(block.fields || [], titleFieldName, `${fieldPath}.${block.slug}`)) : [];
-        return [
-            ...requiredField,
-            ...nestedFields,
-            ...nestedBlocks
-        ];
-    });
-};
-const getCreateFallbackValue = ({ field, label })=>{
-    if (field.defaultValue !== undefined) return field.defaultValue;
-    if (field.path === "_status") return "draft";
-    if (field.type === "checkbox") return false;
-    if (field.type === "select" || field.type === "radio") {
-        return getOptionValue(field.options?.[0]);
-    }
-    const terminalSegment = field.path.split(".").at(-1)?.toLowerCase();
-    if ((field.isTitleField || [
-        "title",
-        "name",
-        "label",
-        "headline"
-    ].includes(terminalSegment || "")) && [
-        "text",
-        "textarea"
-    ].includes(field.type || "")) {
-        return getSafeProposalLabel(label);
-    }
-    return undefined;
-};
-const fillMissingCreateFields = ({ data, label, localizedData, requiredFields })=>{
-    if (localizedData) {
-        const completedLocalizedData = Object.fromEntries(Object.entries(localizedData).map(([locale, localeData])=>[
-                locale,
-                {
-                    ...localeData
-                }
-            ]));
-        const localeEntries = Object.entries(completedLocalizedData);
-        const [firstLocale, firstLocaleData] = localeEntries[0] || [];
-        for (const [locale, localeData] of localeEntries){
-            for (const field of requiredFields.filter((item)=>item.localized)){
-                if (hasValueAtPath(localeData, field.path)) continue;
-                const fallbackValue = getCreateFallbackValue({
-                    field,
-                    label
-                });
-                if (fallbackValue !== undefined) {
-                    setValueAtPath(localeData, field.path, fallbackValue);
-                }
-            }
-        }
-        if (firstLocale && firstLocaleData) {
-            for (const field of requiredFields.filter((item)=>!item.localized)){
-                if (hasValueAtPath(firstLocaleData, field.path)) continue;
-                const fallbackValue = getCreateFallbackValue({
-                    field,
-                    label
-                });
-                if (fallbackValue !== undefined) {
-                    setValueAtPath(firstLocaleData, field.path, fallbackValue);
-                }
-            }
-        }
-        return {
-            localizedData: completedLocalizedData
-        };
-    }
-    const completedData = {
-        ...data || {}
-    };
-    for (const field of requiredFields){
-        if (hasValueAtPath(completedData, field.path)) continue;
-        const fallbackValue = getCreateFallbackValue({
-            field,
-            label
-        });
-        if (fallbackValue !== undefined) {
-            setValueAtPath(completedData, field.path, fallbackValue);
-        }
-    }
-    return {
-        data: completedData
-    };
-};
-const getMissingCreateFields = ({ data, localizedData, requiredFields })=>{
-    if (localizedData) {
-        const locales = Object.entries(localizedData);
-        const firstLocale = locales[0];
-        if (!firstLocale) {
-            return [
-                "localizedData must include at least one locale entry"
-            ];
-        }
-        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 localizedRequiredFields){
-                if (!hasValueAtPath(localeData, field.path)) {
-                    missing.push(`${locale}:${field.path}`);
-                }
-            }
-        }
-        for (const field of sharedRequiredFields){
-            if (!hasValueAtPath(firstLocale[1], field.path)) {
-                missing.push(`${firstLocale[0]}:${field.path}`);
-            }
-        }
-        return missing;
-    }
-    if (!data) return [
-        "data is required"
-    ];
-    return requiredFields.flatMap((field)=>hasValueAtPath(data, field.path) ? [] : [
-            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 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 && availableBlockTypeSet.has(mention.slug)) {
-            requestedBlockTypes.add(mention.slug);
-        }
-    }
-    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 [
-        ...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)) {
-                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;
-                    if (blockType) {
-                        foundBlockTypes.add(blockType);
-                    }
-                    if (blockType) {
-                        const blockConfig = blocksBySlug.get(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) {
-            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(...collectRelationshipTargets({
-                    data: item,
-                    fields: blockConfig.fields,
-                    path: `${fieldPath}.${index}`
-                }));
-            });
-        }
-    }
-    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 targetResults = await Promise.all(targets.map(async (target)=>{
-        try {
-            await req.payload.findByID({
-                collection: target.collection,
-                depth: 0,
-                id: String(target.id),
-                overrideAccess: false,
-                req
-            });
-            return null;
-        } catch  {
-            return target;
-        }
-    }));
-    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,
             id: "id" in mention ? mention.id : undefined,
@@ -606,194 +59,10 @@ const getMediaAttachmentContext = async ({ allowedCollectionsBySlug, attachments
     }
     return contexts;
 };
-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 = 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 [
-        ...matches
-    ];
-};
-const normalizeIntentText = (prompt)=>prompt.toLowerCase().replace(/ä/g, "ae").replace(/ö/g, "oe").replace(/ü/g, "ue").replace(/ß/g, "ss").normalize("NFKD").replace(/[\u0300-\u036f]/g, "");
-const deleteIntentPattern = /\b(?:delete|remove|erase|destroy|discard|purge|loesch\w*|losch\w*|entfern\w*|rausnehm\w*|wegnehm\w*|verwerf\w*)\b/;
-const createIntentPattern = /\b(?:create|build|generate|draft|compose|author|write|make|new|erstell\w*|anleg\w*|erzeug\w*|generier\w*|entwerf\w*|verfass\w*|schreib\w*|neu)\b/;
-const updateIntentPattern = /\b(?:update|edit|change|modify|revise|refine|rewrite|translate|replace|rename|correct|fix|set|publish|unpublish|aktualisier\w*|aender\w*|bearbeit\w*|anpass\w*|ueberarbeit\w*|uberarbeit\w*|umschreib\w*|uebersetz\w*|ubersetz\w*|ersetz\w*|umbenenn\w*|korrigier\w*|reparier\w*|setz\w*|veroeffentlich\w*|veroffentlich\w*|zurueckzieh\w*|zuruckzieh\w*)\b/;
-const additiveIntentPattern = /\b(?:add|insert|append|attach|assign|link|include|extend|ergaenz\w*|erganz\w*|hinzufueg\w*|hinzufug\w*|einfueg\w*|einfug\w*|anhaeng\w*|anhang\w*|zuweis\w*|verknuepf\w*|verknupf\w*)\b/;
-const searchIntentPattern = /\b(?:search|find|lookup|locate|list|show|fetch|browse|query|such\w*|find\w*|nachschlag\w*|auflist\w*|anzeig\w*|zeig\w*|hol\w*|durchsuch\w*)\b/;
-const separableDeleteIntentPattern = /\b(?:nimm|nehm\w*)\b(?:\s+\w+){0,8}\s+(?:raus|weg)\b/;
-const separableUpdateIntentPattern = /\b(?:pass(?:e|t|en|st)?\b(?:\s+\w+){0,8}\s+an|fueg\w*\b(?:\s+\w+){0,8}\s+(?:ein|hinzu)|haeng\w*\b(?:\s+\w+){0,8}\s+an|weis\w*\b(?:\s+\w+){0,8}\s+zu)\b/;
-const getChatIntent = ({ hasCurrentDocument, hasCurrentGlobal, prompt })=>{
-    const normalizedPrompt = normalizeIntentText(prompt);
-    if (deleteIntentPattern.test(normalizedPrompt) || separableDeleteIntentPattern.test(normalizedPrompt)) {
-        return hasCurrentGlobal ? "read" : "delete";
-    }
-    if (createIntentPattern.test(normalizedPrompt)) {
-        if (hasCurrentGlobal) return "updateGlobal";
-        if (hasCurrentDocument) return "update";
-        return "create";
-    }
-    if (updateIntentPattern.test(normalizedPrompt) || additiveIntentPattern.test(normalizedPrompt) || separableUpdateIntentPattern.test(normalizedPrompt)) {
-        return hasCurrentGlobal ? "updateGlobal" : "update";
-    }
-    if (searchIntentPattern.test(normalizedPrompt)) {
-        return "search";
-    }
-    return "read";
-};
-const getIntentToolChoice = ({ hasKnownCollection, hasKnownDocument, hasKnownGlobal, intent })=>{
-    if (intent === "create" && hasKnownCollection) {
-        return {
-            toolName: "proposeCreateDoc",
-            type: "tool"
-        };
-    }
-    if (intent === "update" && hasKnownDocument) {
-        return {
-            toolName: "proposeUpdateDoc",
-            type: "tool"
-        };
-    }
-    if (intent === "delete" && hasKnownDocument) {
-        return {
-            toolName: "proposeDeleteDoc",
-            type: "tool"
-        };
-    }
-    if (intent === "updateGlobal" && hasKnownGlobal) {
-        return {
-            toolName: "proposeUpdateGlobal",
-            type: "tool"
-        };
-    }
-    return undefined;
-};
-const getToolNamesForIntent = ({ hasAttachments, hasKnownCollection, hasCurrentDocument, hasCurrentGlobal, intent })=>{
-    if (hasCurrentGlobal) {
-        return new Set(intent === "updateGlobal" ? [
-            "getGlobal",
-            "listGlobals",
-            "proposeUpdateGlobal"
-        ] : [
-            "getGlobal",
-            "listGlobals"
-        ]);
-    }
-    if (hasCurrentDocument) {
-        if (intent === "delete") return new Set([
-            "getDoc",
-            "proposeDeleteDoc"
-        ]);
-        if (intent === "update" || intent === "create") return new Set([
-            "getDoc",
-            "listCollections",
-            "proposeUpdateDoc"
-        ]);
-        return new Set([
-            "getDoc",
-            "listCollections"
-        ]);
-    }
-    if (hasKnownCollection) {
-        if (intent === "create") return new Set([
-            "getDoc",
-            "listCollections",
-            "proposeCreateDoc",
-            "searchDocs"
-        ]);
-        if (intent === "update") return new Set([
-            "getDoc",
-            "listCollections",
-            "proposeUpdateDoc",
-            "searchDocs"
-        ]);
-        if (intent === "delete") return new Set([
-            "getDoc",
-            "proposeDeleteDoc",
-            "searchDocs"
-        ]);
-        return new Set([
-            "getDoc",
-            "listCollections",
-            "searchDocs"
-        ]);
-    }
-    const toolNames = intent === "create" ? new Set([
-        "getDoc",
-        "listCollections",
-        "proposeCreateDoc",
-        "searchDocs"
-    ]) : intent === "update" ? new Set([
-        "getDoc",
-        "getGlobal",
-        "listCollections",
-        "listGlobals",
-        "proposeUpdateDoc",
-        "proposeUpdateGlobal",
-        "searchDocs"
-    ]) : intent === "delete" ? new Set([
-        "getDoc",
-        "listCollections",
-        "proposeDeleteDoc",
-        "searchDocs"
-    ]) : new Set([
-        "getDoc",
-        "getGlobal",
-        "listCollections",
-        "listGlobals",
-        "searchDocs"
-    ]);
-    if (hasAttachments && (intent === "create" || intent === "update")) {
-        toolNames.add("proposeUpdateDoc");
-    }
-    return toolNames;
-};
-export const createChatHandler = (options = {})=>async (req)=>{
-        if (!req.user) return Response.json({
-            error: "Unauthorized"
-        }, {
-            status: 401
-        });
-        const body = req.json ? await req.json().catch(()=>null) : null;
+export const createChatHandler = (options = {})=>withAuthenticatedHandler(async (req)=>{
+        const body = await readJSONBody(req);
         const prompt = body?.prompt?.trim();
-        if (!prompt) return Response.json({
-            error: "Prompt is required"
-        }, {
-            status: 400
-        });
+        if (!prompt) return jsonError("Prompt is required");
         const selectedLocales = [];
         const selectedLocaleSet = new Set();
         for (const mention of body?.mentions || []){
@@ -810,79 +79,68 @@ export const createChatHandler = (options = {})=>async (req)=>{
             });
         }
         const user = req.user;
-        const exceededTokenUsageLimit = await getExceededTokenUsageLimit({
-            maxTokenUsage: options.maxTokenUsage,
+        const aiRequestResolution = await resolveAIRequestContext({
+            options,
             req,
-            userID: user.id
+            requestedModel: body?.model,
+            requestedProvider: body?.provider,
+            user
         });
-        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 (!aiRequestResolution.ok) {
+            if (aiRequestResolution.error.code === "token_limit") {
+                const exceededTokenUsageLimit = aiRequestResolution.error.tokenLimit;
+                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
+                });
+            }
+            if (aiRequestResolution.error.code !== "missing_api_key") {
+                return jsonError(aiRequestResolution.error.message);
+            }
+            const missingKeyError = aiRequestResolution.error;
+            const debug = createInitialChatDebug({
+                model: missingKeyError.modelID,
+                provider: missingKeyError.providerID
             });
-        }
-        if (!managedProvider && !isAIProvider(requestedProvider)) {
-            return Response.json({
-                error: `Unsupported AI provider: ${requestedProvider}`
-            }, {
-                status: 400
+            logHandlerEvent(req, "info", {
+                activeLocale,
+                debug,
+                mentionCount: mentionSummary.length,
+                mentions: mentionSummary,
+                msg: "AI chat started",
+                promptPreview: getLogPreview(prompt),
+                selectedLocales
             });
-        }
-        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
+            logHandlerEvent(req, "warn", {
+                activeLocale,
+                debug,
+                msg: "AI chat blocked: missing provider API key",
+                promptPreview: getLogPreview(prompt),
+                selectedLocales
             });
+            return jsonError(missingKeyError.managedProvider ? `Configure a ${missingKeyError.providerID} API key in the plugin config or server environment first.` : options.allowUserApiKeys === false ? `Configure a ${missingKeyError.provider} API key in the server environment first.` : `Add a ${missingKeyError.provider} API key to your account settings or configure it in the server environment first.`);
         }
-        const userApiKey = managedProvider ? managedProvider.apiKey : options.allowUserApiKeys === false ? null : user.aiApiKey;
-        const providerConfig = getProviderConfig({
-            apiKey: userApiKey,
-            defaultModels: options.models?.defaults,
-            model: requestedModel,
-            provider
+        const resolvedAIRequest = aiRequestResolution.context;
+        const provider = resolvedAIRequest.provider;
+        const managedProvider = resolvedAIRequest.managedProvider;
+        const debug = createInitialChatDebug({
+            model: resolvedAIRequest.modelID,
+            provider: resolvedAIRequest.providerID
         });
-        const debug = {
-            model: providerConfig.modelID,
-            provider: managedProvider?.id || provider,
-            tools: [
-                "getDoc",
-                "getGlobal",
-                "listCollections",
-                "listGlobals",
-                "proposeCreateDoc",
-                "proposeDeleteDoc",
-                "proposeUpdateDoc",
-                "proposeUpdateGlobal",
-                "searchDocs"
-            ]
-        };
         logHandlerEvent(req, "info", {
             activeLocale,
             debug,
@@ -892,117 +150,7 @@ export const createChatHandler = (options = {})=>async (req)=>{
             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: 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
-            });
-        }
         try {
-            const proposals = [];
-            const toolFailures = [];
-            const proposalRepairTracker = createProposalRepairTracker();
-            const registerToolFailure = (failure)=>{
-                toolFailures.push(failure);
-                logHandlerEvent(req, "warn", {
-                    debug,
-                    ...failure,
-                    msg: "AI tool validation failed",
-                    promptPreview: getLogPreview(prompt)
-                });
-            };
-            const createToolError = ({ collection, details, errorCode = "NON_RETRYABLE_TOOL_ERROR", message, slug, tool })=>{
-                registerToolFailure({
-                    collection,
-                    details,
-                    errorCode,
-                    message,
-                    retryable: false,
-                    slug,
-                    tool
-                });
-                return {
-                    error: message,
-                    errorCode,
-                    retryable: false
-                };
-            };
-            const createRepairableToolError = ({ collection, details, id, issues, message, slug, tool })=>{
-                const repair = proposalRepairTracker.registerFailure({
-                    collection,
-                    id,
-                    slug,
-                    tool
-                });
-                const responseMessage = repair.retryable ? message : "The single proposal repair attempt failed. Do not call the same proposal tool for this target again.";
-                registerToolFailure({
-                    collection,
-                    details,
-                    errorCode: repair.errorCode,
-                    message: responseMessage,
-                    retryable: repair.retryable,
-                    slug,
-                    tool
-                });
-                return {
-                    error: responseMessage,
-                    errorCode: repair.errorCode,
-                    repair: {
-                        attempt: repair.attempt,
-                        issues,
-                        maxAttempts: repair.maxAttempts
-                    },
-                    retryable: repair.retryable
-                };
-            };
-            const getProposalRepairLimitError = ({ collection, id, slug, tool })=>{
-                const callState = proposalRepairTracker.beginCall({
-                    collection,
-                    id,
-                    slug,
-                    tool
-                });
-                if (callState !== "blocked") return null;
-                return createToolError({
-                    collection,
-                    errorCode: "REPAIR_EXHAUSTED",
-                    message: "The single proposal repair attempt was already used. Do not call this proposal tool for the same target again.",
-                    slug,
-                    tool
-                });
-            };
-            const addSignedProposal = (proposal)=>{
-                if ("data" in proposal && proposal.data && containsSensitiveData(proposal.data)) {
-                    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 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 requestedDocumentScope = body?.documentScope;
             const configuredCollectionSlugs = getAllowedCollectionSlugs(req, options.collections);
             const configuredCollectionSlugSet = new Set(configuredCollectionSlugs);
@@ -1011,18 +159,10 @@ export const createChatHandler = (options = {})=>async (req)=>{
             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
-                });
+                return jsonError("The current collection is not available to the AI assistant.");
             }
             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
-                });
+                return jsonError("The current global is not available to the AI assistant.");
             }
             const collectionSlugs = requestedDocumentScope ? requestedCollectionSlug ? [
                 requestedCollectionSlug
@@ -1030,36 +170,20 @@ export const createChatHandler = (options = {})=>async (req)=>{
             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"
                 });
-                return Response.json({
-                    error: "No AI-enabled collections are configured."
-                }, {
-                    status: 400
-                });
+                return jsonError("No AI-enabled collections are configured.");
             }
-            const blockContexts = [
-                ...allowedCollections.flatMap((collection)=>collectBlocks({
-                        fields: collection.fields,
-                        parent: collection.slug
-                    })),
-                ...globalConfigs.flatMap((global)=>collectBlocks({
-                        fields: global.fields,
-                        parent: global.slug
-                    }))
-            ];
+            const schemaRegistry = createSchemaContextRegistry({
+                collections: allowedCollections,
+                globals: globalConfigs,
+                req
+            });
+            const { collectionConfigsBySlug: allowedCollectionsBySlug, globalConfigsBySlug } = schemaRegistry;
             const explicitlyMentionedDocumentKeys = new Set((body?.mentions || []).flatMap((mention)=>mention.type === "doc" && mention.collection && mention.id ? [
                     `${mention.collection}:${mention.id}`
                 ] : []));
@@ -1067,11 +191,9 @@ export const createChatHandler = (options = {})=>async (req)=>{
                     mention.slug
                 ] : []));
             const mentionContext = await getMentionContext({
-                blockContexts,
-                collectionSlugs,
                 collections: options.collections,
-                globalSlugs,
                 mentions: body?.mentions,
+                registry: schemaRegistry,
                 req
             });
             if (requestedCollectionSlug && requestedDocumentID) {
@@ -1247,35 +369,29 @@ export const createChatHandler = (options = {})=>async (req)=>{
             const updateLocalizedDataSchema = createLocalizedPayloadDataSchema(updateDataSchema);
             const globalDataSchema = focusedGlobalConfig ? focusedGlobalDataSchema : genericPayloadDataSchema;
             const globalLocalizedDataSchema = createLocalizedPayloadDataSchema(globalDataSchema);
-            const getDisallowedCollectionActionError = (collection, action)=>{
-                if (isCollectionActionAllowed({
-                    action,
-                    permissions: options.collections,
-                    req,
-                    slug: collection
-                })) return null;
-                return createToolError({
-                    collection,
-                    message: `${action} is not enabled for collection: ${collection}`,
-                    tool: "collectionPermissionCheck"
-                });
-            };
-            const allTools = {
-                getDoc: {
+            const { addProposal: addSignedProposal, collectionTool, error: createToolError, proposalCollectionTool, proposalTool, proposals, repairableError: createRepairableToolError, toolFailures } = createChatToolFactory({
+                collections: options.collections,
+                currentDocument: requestedCollectionSlug && requestedDocumentID ? {
+                    collection: requestedCollectionSlug,
+                    id: requestedDocumentID
+                } : undefined,
+                debug,
+                prompt,
+                req
+            });
+            const toolRegistry = {
+                getDoc: collectionTool({
+                    action: "read",
+                    currentDocumentOnly: Boolean(requestedDocumentScope),
                     description: "Read a compact document by collection and id. Optionally request up to 12 exact top-level schema fields. Explicitly @-mentioned documents remain complete.",
+                    getDocumentID: ({ id })=>id,
                     inputSchema: z.object({
                         collection: collectionSlugSchema,
                         fields: collectionReadFieldsSchema,
                         id: z.string().min(1)
                     }),
+                    name: "getDoc",
                     execute: async ({ collection, fields, id })=>{
-                        if (requestedDocumentScope && (collection !== requestedCollectionSlug || id !== requestedDocumentID)) {
-                            return createToolError({
-                                collection,
-                                message: "Only the current document can be read in this context.",
-                                tool: "getDoc"
-                            });
-                        }
                         const explicitlyMentioned = explicitlyMentionedDocumentKeys.has(`${collection}:${id}`);
                         const collectionConfig = allowedCollectionsBySlug.get(collection);
                         const fieldSelection = resolveToolFieldSelection({
@@ -1308,7 +424,7 @@ export const createChatHandler = (options = {})=>async (req)=>{
                         });
                         return redactSensitiveData(document);
                     }
-                },
+                }),
                 listCollections: {
                     description: "List collections; pass slug for one full schema.",
                     inputSchema: z.object({
@@ -1416,8 +532,13 @@ export const createChatHandler = (options = {})=>async (req)=>{
                             }));
                     }
                 },
-                proposeCreateDoc: {
+                proposeCreateDoc: proposalCollectionTool({
+                    action: "create",
                     description: "Propose document creation. Use exact schema fields; include required fields. Use localizedData for multi-locale writes.",
+                    getRepairTarget: ({ collection, label })=>({
+                            collection,
+                            id: getSafeProposalLabel(label)
+                        }),
                     inputSchema: z.object({
                         collection: focusedCollectionSlugSchema,
                         data: createDataSchema.optional(),
@@ -1426,16 +547,9 @@ export const createChatHandler = (options = {})=>async (req)=>{
                     }).refine((value)=>Boolean(value.data || value.localizedData), {
                         message: "Either data or localizedData is required."
                     }),
+                    name: "proposeCreateDoc",
                     execute: async ({ collection, data, label, localizedData })=>{
-                        const permissionError = getDisallowedCollectionActionError(collection, "create");
-                        if (permissionError) return permissionError;
                         const repairTargetID = getSafeProposalLabel(label);
-                        const repairLimitError = getProposalRepairLimitError({
-                            collection,
-                            id: repairTargetID,
-                            tool: "proposeCreateDoc"
-                        });
-                        if (repairLimitError) return repairLimitError;
                         const collectionConfig = allowedCollectionsBySlug.get(collection);
                         const collectionFields = collectionConfig?.fields || [];
                         const preparedData = prepareProposalWriteData({
@@ -1505,18 +619,14 @@ 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
-                                })) : []
-                        ];
+                        const { invalidRelationshipTargets, uploadTargetsOutsideAttachments } = await validateProposalReferences({
+                            allowedAttachmentKeys,
+                            data: preparedData.data,
+                            fields: collectionFields,
+                            localizedData: preparedData.localizedData,
+                            priority: "attachments",
+                            req
+                        });
                         if (uploadTargetsOutsideAttachments.length > 0) {
                             return createToolError({
                                 collection,
@@ -1530,18 +640,6 @@ export const createChatHandler = (options = {})=>async (req)=>{
                                 tool: "proposeCreateDoc"
                             });
                         }
-                        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,
@@ -1571,24 +669,19 @@ export const createChatHandler = (options = {})=>async (req)=>{
                         };
                         return addSignedProposal(proposal);
                     }
-                },
-                proposeDeleteDoc: {
+                }),
+                proposeDeleteDoc: collectionTool({
+                    action: "delete",
+                    currentDocumentOnly: Boolean(requestedDocumentScope),
                     description: "Propose document deletion.",
+                    getDocumentID: ({ id })=>id,
                     inputSchema: z.object({
                         collection: collectionSlugSchema,
                         id: z.string().min(1),
                         label: z.string().min(1)
                     }),
+                    name: "proposeDeleteDoc",
                     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 = {
                             action: "delete",
                             collection,
@@ -1600,9 +693,16 @@ export const createChatHandler = (options = {})=>async (req)=>{
                         };
                         return addSignedProposal(proposal);
                     }
-                },
-                proposeUpdateDoc: {
+                }),
+                proposeUpdateDoc: proposalCollectionTool({
+                    action: "update",
+                    currentDocumentOnly: Boolean(requestedDocumentScope),
                     description: "Propose document update. Use exact schema fields. Use localizedData for multi-locale writes.",
+                    getDocumentID: ({ id })=>id,
+                    getRepairTarget: ({ collection, id })=>({
+                            collection,
+                            id
+                        }),
                     inputSchema: z.object({
                         collection: updateHasMultipleTargets ? collectionSlugSchema : focusedCollectionSlugSchema,
                         data: updateDataSchema.optional(),
@@ -1612,22 +712,8 @@ export const createChatHandler = (options = {})=>async (req)=>{
                     }).refine((value)=>Boolean(value.data || value.localizedData), {
                         message: "Either data or localizedData is required."
                     }),
+                    name: "proposeUpdateDoc",
                     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 repairLimitError = getProposalRepairLimitError({
-                            collection,
-                            id,
-                            tool: "proposeUpdateDoc"
-                        });
-                        if (repairLimitError) return repairLimitError;
                         const collectionConfig = allowedCollectionsBySlug.get(collection);
                         const collectionFields = collectionConfig?.fields || [];
                         const preparedData = prepareProposalWriteData({
@@ -1650,18 +736,14 @@ export const createChatHandler = (options = {})=>async (req)=>{
                                 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() : []
-                        ];
+                        const { invalidRelationshipTargets, uploadTargetsOutsideAttachments } = await validateProposalReferences({
+                            allowedAttachmentKeys,
+                            data: preparedData.data,
+                            fields: collectionFields,
+                            localizedData: preparedData.localizedData,
+                            priority: "relationships",
+                            req
+                        });
                         if (invalidRelationshipTargets.length > 0) {
                             return createToolError({
                                 collection,
@@ -1672,18 +754,6 @@ 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,
@@ -1713,18 +783,9 @@ export const createChatHandler = (options = {})=>async (req)=>{
                         };
                         return addSignedProposal(proposal);
                     }
-                },
-                proposeUpdateGlobal: {
-                    description: "Propose global update. Use localizedData for multi-locale writes.",
-                    inputSchema: z.object({
-                        data: globalDataSchema.optional(),
-                        label: z.string().min(1),
-                        localizedData: globalLocalizedDataSchema.optional(),
-                        slug: requestedGlobalSlug ? z.literal(requestedGlobalSlug) : z.string().min(1)
-                    }).refine((value)=>Boolean(value.data || value.localizedData), {
-                        message: "Either data or localizedData is required."
-                    }),
-                    execute: async ({ data, label, localizedData, slug })=>{
+                }),
+                proposeUpdateGlobal: proposalTool({
+                    beforeRepair: ({ slug })=>{
                         if (requestedDocumentScope && slug !== requestedGlobalSlug) {
                             return createToolError({
                                 message: "Only the current global can be updated in this context.",
@@ -1732,19 +793,31 @@ export const createChatHandler = (options = {})=>async (req)=>{
                                 tool: "proposeUpdateGlobal"
                             });
                         }
-                        const globalConfig = globalConfigsBySlug.get(slug);
-                        if (!globalConfig) {
+                        if (!globalConfigsBySlug.has(slug)) {
                             return createToolError({
                                 message: `Unknown global: ${slug}`,
                                 slug,
                                 tool: "proposeUpdateGlobal"
                             });
                         }
-                        const repairLimitError = getProposalRepairLimitError({
-                            slug,
-                            tool: "proposeUpdateGlobal"
-                        });
-                        if (repairLimitError) return repairLimitError;
+                        return null;
+                    },
+                    description: "Propose global update. Use localizedData for multi-locale writes.",
+                    getRepairTarget: ({ slug })=>({
+                            slug
+                        }),
+                    inputSchema: z.object({
+                        data: globalDataSchema.optional(),
+                        label: z.string().min(1),
+                        localizedData: globalLocalizedDataSchema.optional(),
+                        slug: requestedGlobalSlug ? z.literal(requestedGlobalSlug) : z.string().min(1)
+                    }).refine((value)=>Boolean(value.data || value.localizedData), {
+                        message: "Either data or localizedData is required."
+                    }),
+                    name: "proposeUpdateGlobal",
+                    execute: async ({ data, label, localizedData, slug })=>{
+                        const globalConfig = globalConfigsBySlug.get(slug);
+                        if (!globalConfig) return null;
                         const preparedData = prepareProposalWriteData({
                             collectionConfig: {
                                 fields: globalConfig.fields || [],
@@ -1782,7 +855,7 @@ export const createChatHandler = (options = {})=>async (req)=>{
                         };
                         return addSignedProposal(proposal);
                     }
-                },
+                }),
                 searchDocs: {
                     description: "Search compact documents in one collection. Returns default identity fields or up to 12 requested exact top-level schema fields.",
                     inputSchema: z.object({
@@ -1852,7 +925,7 @@ export const createChatHandler = (options = {})=>async (req)=>{
                 hasCurrentGlobal: Boolean(requestedGlobalSlug),
                 intent: chatIntent
             });
-            const tools = Object.fromEntries(Object.entries(allTools).filter(([name])=>scopedToolNames.has(name)));
+            const tools = Object.fromEntries(Object.entries(toolRegistry).filter(([name])=>scopedToolNames.has(name)));
             debug.tools = Object.keys(tools);
             if (intentToolChoice && !scopedToolNames.has(intentToolChoice.toolName)) {
                 intentToolChoice = undefined;
@@ -1861,63 +934,21 @@ export const createChatHandler = (options = {})=>async (req)=>{
             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
-            });
+            const model = await resolvedAIRequest.loadModel();
             const promptCaching = options.promptCaching !== false;
             const explicitPromptCaching = promptCaching && !managedProvider?.baseURL;
-            const sanitizedMentionContext = redactSensitiveData(mentionContext);
-            const { cacheable: cacheableMentionContext, dynamic: dynamicMentionContext } = splitPromptCacheContext(sanitizedMentionContext);
-            const staticSystemInstructions = [
-                "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.",
-                "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.",
-                "Read tools return compact identity fields by default. Request only the additional fields needed for the current task; full schemas remain available separately.",
-                "If a proposal tool returns retryable=true, correct only repair.issues and call the same proposal tool once more. If retryable=false, do not retry that tool target."
-            ];
-            const cacheableSystemInstructions = [
-                `Collection aliases: ${JSON.stringify(collectionAliasMap)}.`,
-                `Focused required create fields: ${JSON.stringify(focusedRequiredFieldsByCollection)}.`,
-                `Focused title fields: ${JSON.stringify(focusedTitleFieldByCollection)}. Infer concise titles when needed.`
-            ];
-            const dynamicSystemInstructions = [
-                `Likely collection matches for this prompt: ${JSON.stringify(likelyCollectionMatches)}.`,
-                `Request intent: ${chatIntent}. Preferred proposal tool: ${intentToolChoice?.toolName || "none"}.`,
-                "Visible response: plain text, under 40 words, no Markdown, no proposed content."
-            ];
-            const system = createCachedSystemMessages({
-                cacheableContext: cacheableMentionContext,
-                cacheableInstructions: cacheableSystemInstructions,
-                dynamicInstructions: dynamicSystemInstructions,
-                enabled: explicitPromptCaching,
+            const { dynamicMentionContext, promptCacheProviderOptions, system } = createChatPromptContext({
+                chatIntent,
+                collectionAliasMap,
+                focusedRequiredFieldsByCollection,
+                focusedTitleFieldByCollection,
+                intentToolName: intentToolChoice?.toolName,
+                likelyCollectionMatches,
+                mentionContext,
+                modelID: resolvedAIRequest.modelID,
+                promptCaching: explicitPromptCaching,
                 provider,
-                staticInstructions: staticSystemInstructions
-            });
-            const promptCacheProviderOptions = createPromptCacheProviderOptions({
-                cacheKeyParts: [
-                    cacheableMentionContext,
-                    cacheableSystemInstructions,
-                    [
-                        ...scopedToolNames
-                    ].sort()
-                ],
-                enabled: explicitPromptCaching,
-                model: providerConfig.modelID,
-                provider
+                scopedToolNames
             });
             const result = streamText({
                 maxOutputTokens: options.maxOutputTokens || 700,
@@ -1958,15 +989,9 @@ export const createChatHandler = (options = {})=>async (req)=>{
                             if (part.type === "finish") {
                                 const finishPart = part;
                                 usage = finishPart.totalUsage || finishPart.usage || null;
-                                if (usage && options.maxTokenUsage) {
+                                if (usage) {
                                     try {
-                                        await recordTokenUsage({
-                                            model: providerConfig.modelID,
-                                            provider: managedProvider?.id || provider,
-                                            req,
-                                            usage,
-                                            userID: user.id
-                                        });
+                                        await resolvedAIRequest.recordUsage(usage);
                                     } catch (err) {
                                         req.payload.logger.error({
                                             err,
@@ -2070,15 +1095,14 @@ export const createChatHandler = (options = {})=>async (req)=>{
                 }
             });
         } catch (err) {
-            req.payload.logger.error({
-                debug,
-                err,
-                msg: "AI chat request failed"
-            });
-            return Response.json({
-                error: "AI request failed."
-            }, {
-                status: 500
+            return logHandlerError({
+                details: {
+                    debug
+                },
+                error: err,
+                logMessage: "AI chat request failed",
+                publicMessage: "AI request failed.",
+                req
             });
         }
-    };
+    });