@mvriu5/payload-ai 1.4.0 → 1.6.0

package/dist/handlers/chatHandler.js

@@ -3,16 +3,17 @@ import { z } from "zod";
 import { signAIActionProposal } from "../ai/proposalSigning.js";
 import { isAIProvider } from "../ai/providerOptions.js";
 import { getModel, getProviderConfig } from "../ai/providerRuntime.js";
-import { containsSensitiveData } from "../ai/sensitiveData.js";
+import { 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";
-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."
-});
+import { createLocalizedPayloadDataSchema, createPayloadDataSchema, genericPayloadDataSchema } from "../payload/toolSchemas.js";
+import { createToolFieldNamesSchema, resolveToolFieldSelection } from "../payload/toolFieldSelection.js";
 const e2eModeEnabled = ()=>process.env.PAYLOAD_AI_E2E_MODE === "true";
 const createSSEEventStream = (events)=>{
     const encoder = new TextEncoder();
@@ -578,12 +579,16 @@ const getMediaAttachmentContext = async ({ allowedCollectionsBySlug, attachments
         if (seen.has(key)) continue;
         const collectionConfig = allowedCollectionsBySlug.get(attachment.collection);
         if (!collectionConfig?.upload) continue;
+        const fieldSelection = resolveToolFieldSelection({
+            config: collectionConfig
+        });
         const doc = await req.payload.findByID({
             collection: attachment.collection,
-            depth: 1,
+            depth: fieldSelection.depth,
             id: attachment.id,
             overrideAccess: false,
-            req
+            req,
+            select: fieldSelection.select
         }).catch(()=>null);
         if (!doc) continue;
         seen.add(key);
@@ -601,26 +606,6 @@ const getMediaAttachmentContext = async ({ allowedCollectionsBySlug, attachments
     }
     return contexts;
 };
-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)=>{
@@ -663,34 +648,139 @@ const getLikelyCollectionMatches = ({ aliasMap, prompt })=>{
         ...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 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 = (prompt)=>{
-    const normalizedPrompt = prompt.toLowerCase();
-    if (/\b(delete|remove)\b/.test(normalizedPrompt)) {
+const getIntentToolChoice = ({ hasKnownCollection, hasKnownDocument, hasKnownGlobal, intent })=>{
+    if (intent === "create" && hasKnownCollection) {
         return {
-            toolName: "proposeDeleteDoc",
+            toolName: "proposeCreateDoc",
             type: "tool"
         };
     }
-    // Update existing document (add block, modify content, etc.)
-    if (/\b(update|edit|change|modify|einfügen|hinzufügen|addieren)\b/.test(normalizedPrompt)) {
+    if (intent === "update" && hasKnownDocument) {
         return {
             toolName: "proposeUpdateDoc",
             type: "tool"
         };
     }
-    // Create a new document
-    if (/\b(create|build|generate|write|draft|make|add|füge|einfügen|hinzufügen|addieren)\b/.test(normalizedPrompt)) {
+    if (intent === "delete" && hasKnownDocument) {
         return {
-            toolName: "proposeCreateDoc",
+            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"
@@ -819,6 +909,7 @@ export const createChatHandler = (options = {})=>async (req)=>{
         try {
             const proposals = [];
             const toolFailures = [];
+            const proposalRepairTracker = createProposalRepairTracker();
             const registerToolFailure = (failure)=>{
                 toolFailures.push(failure);
                 logHandlerEvent(req, "warn", {
@@ -828,18 +919,66 @@ export const createChatHandler = (options = {})=>async (req)=>{
                     promptPreview: getLogPreview(prompt)
                 });
             };
-            const createToolError = ({ collection, details, message, slug, tool })=>{
+            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: message
+                    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({
@@ -921,6 +1060,12 @@ export const createChatHandler = (options = {})=>async (req)=>{
                         parent: global.slug
                     }))
             ];
+            const explicitlyMentionedDocumentKeys = new Set((body?.mentions || []).flatMap((mention)=>mention.type === "doc" && mention.collection && mention.id ? [
+                    `${mention.collection}:${mention.id}`
+                ] : []));
+            const explicitlyMentionedGlobalSlugs = new Set((body?.mentions || []).flatMap((mention)=>mention.type === "global" && mention.slug ? [
+                    mention.slug
+                ] : []));
             const mentionContext = await getMentionContext({
                 blockContexts,
                 collectionSlugs,
@@ -930,37 +1075,65 @@ export const createChatHandler = (options = {})=>async (req)=>{
                 req
             });
             if (requestedCollectionSlug && requestedDocumentID) {
-                const currentDocument = await req.payload.findByID({
-                    collection: requestedCollectionSlug,
-                    depth: 2,
-                    id: requestedDocumentID,
-                    ...activeLocale ? {
-                        locale: activeLocale
-                    } : {},
-                    overrideAccess: false,
-                    req
-                });
-                mentionContext.push({
-                    collection: requestedCollectionSlug,
-                    document: currentDocument,
-                    id: requestedDocumentID,
-                    type: "currentDocument"
-                });
+                const currentDocumentKey = `${requestedCollectionSlug}:${requestedDocumentID}`;
+                if (explicitlyMentionedDocumentKeys.has(currentDocumentKey)) {
+                    mentionContext.push({
+                        collection: requestedCollectionSlug,
+                        id: requestedDocumentID,
+                        source: "mention",
+                        type: "currentDocumentScope"
+                    });
+                } else {
+                    const currentCollectionConfig = allowedCollectionsBySlug.get(requestedCollectionSlug);
+                    const fieldSelection = resolveToolFieldSelection({
+                        config: currentCollectionConfig
+                    });
+                    const currentDocument = await req.payload.findByID({
+                        collection: requestedCollectionSlug,
+                        depth: fieldSelection.depth,
+                        id: requestedDocumentID,
+                        ...activeLocale ? {
+                            locale: activeLocale
+                        } : {},
+                        overrideAccess: false,
+                        req,
+                        select: fieldSelection.select
+                    });
+                    mentionContext.push({
+                        collection: requestedCollectionSlug,
+                        document: currentDocument,
+                        id: requestedDocumentID,
+                        type: "currentDocument"
+                    });
+                }
             } else if (requestedGlobalSlug) {
-                const currentGlobal = await req.payload.findGlobal({
-                    depth: 2,
-                    ...activeLocale ? {
-                        locale: activeLocale
-                    } : {},
-                    overrideAccess: false,
-                    req,
-                    slug: requestedGlobalSlug
-                });
-                mentionContext.push({
-                    global: currentGlobal,
-                    slug: requestedGlobalSlug,
-                    type: "currentGlobal"
-                });
+                if (explicitlyMentionedGlobalSlugs.has(requestedGlobalSlug)) {
+                    mentionContext.push({
+                        slug: requestedGlobalSlug,
+                        source: "mention",
+                        type: "currentGlobalScope"
+                    });
+                } else {
+                    const currentGlobalConfig = globalConfigsBySlug.get(requestedGlobalSlug);
+                    const fieldSelection = resolveToolFieldSelection({
+                        config: currentGlobalConfig
+                    });
+                    const currentGlobal = await req.payload.findGlobal({
+                        depth: fieldSelection.depth,
+                        ...activeLocale ? {
+                            locale: activeLocale
+                        } : {},
+                        overrideAccess: false,
+                        req,
+                        select: fieldSelection.select,
+                        slug: requestedGlobalSlug
+                    });
+                    mentionContext.push({
+                        global: currentGlobal,
+                        slug: requestedGlobalSlug,
+                        type: "currentGlobal"
+                    });
+                }
             }
             const mediaAttachmentContext = await getMediaAttachmentContext({
                 allowedCollectionsBySlug,
@@ -1008,7 +1181,17 @@ export const createChatHandler = (options = {})=>async (req)=>{
                 aliasMap: collectionAliasMap,
                 prompt
             });
-            const writeIntent = hasWriteIntent(prompt);
+            const chatIntent = getChatIntent({
+                hasCurrentDocument: Boolean(requestedCollectionSlug && requestedDocumentID),
+                hasCurrentGlobal: Boolean(requestedGlobalSlug),
+                prompt
+            });
+            const writeIntent = [
+                "create",
+                "delete",
+                "update",
+                "updateGlobal"
+            ].includes(chatIntent);
             const inferredCollectionSlug = requestedCollectionSlug || (mentionedCollectionSlugs.length === 1 ? mentionedCollectionSlugs[0] : mentionedCollectionSlugs.length === 0 && likelyCollectionMatches.length === 1 ? likelyCollectionMatches[0] : undefined);
             const inferredCollectionConfig = inferredCollectionSlug ? allowedCollectionsBySlug.get(inferredCollectionSlug) : undefined;
             if (inferredCollectionConfig && !mentionContext.some((item)=>item.type === "collection" && item.slug === inferredCollectionConfig.slug)) {
@@ -1030,10 +1213,16 @@ export const createChatHandler = (options = {})=>async (req)=>{
                     }));
                 }
             }
-            let intentToolChoice = inferredCollectionConfig ? getIntentToolChoice(prompt) : undefined;
+            let intentToolChoice = getIntentToolChoice({
+                hasKnownCollection: Boolean(inferredCollectionConfig),
+                hasKnownDocument: Boolean(requestedCollectionSlug && requestedDocumentID),
+                hasKnownGlobal: Boolean(requestedGlobalSlug),
+                intent: chatIntent
+            });
             logHandlerEvent(req, "info", {
                 activeLocale,
                 allowedCollectionCount: allowedCollections.length,
+                chatIntent,
                 collectionSlugs,
                 focusedCollections: mentionedCollectionSlugs,
                 globalSlugs,
@@ -1045,6 +1234,19 @@ export const createChatHandler = (options = {})=>async (req)=>{
                 writeIntent
             });
             const collectionSlugSchema = collectionSlugs.length > 0 ? z.enum(collectionSlugs) : z.string().refine(()=>false, "No collection is in scope.");
+            const focusedCollectionDataSchema = createPayloadDataSchema(inferredCollectionConfig);
+            const focusedCollectionSlugSchema = inferredCollectionSlug ? z.literal(inferredCollectionSlug) : collectionSlugSchema;
+            const focusedGlobalConfig = requestedGlobalSlug ? globalConfigsBySlug.get(requestedGlobalSlug) : undefined;
+            const focusedGlobalDataSchema = createPayloadDataSchema(focusedGlobalConfig);
+            const collectionReadFieldsSchema = createToolFieldNamesSchema(allowedCollections);
+            const globalReadFieldsSchema = createToolFieldNamesSchema(globalConfigs);
+            const createDataSchema = inferredCollectionConfig ? focusedCollectionDataSchema : genericPayloadDataSchema;
+            const createLocalizedDataSchema = createLocalizedPayloadDataSchema(createDataSchema);
+            const updateHasMultipleTargets = mediaAttachmentContext.length > 0 && !requestedDocumentID;
+            const updateDataSchema = inferredCollectionConfig && !updateHasMultipleTargets ? focusedCollectionDataSchema : genericPayloadDataSchema;
+            const updateLocalizedDataSchema = createLocalizedPayloadDataSchema(updateDataSchema);
+            const globalDataSchema = focusedGlobalConfig ? focusedGlobalDataSchema : genericPayloadDataSchema;
+            const globalLocalizedDataSchema = createLocalizedPayloadDataSchema(globalDataSchema);
             const getDisallowedCollectionActionError = (collection, action)=>{
                 if (isCollectionActionAllowed({
                     action,
@@ -1060,12 +1262,13 @@ export const createChatHandler = (options = {})=>async (req)=>{
             };
             const allTools = {
                 getDoc: {
-                    description: "Read a document by collection and id.",
+                    description: "Read a compact document by collection and id. Optionally request up to 12 exact top-level schema fields. Explicitly @-mentioned documents remain complete.",
                     inputSchema: z.object({
                         collection: collectionSlugSchema,
+                        fields: collectionReadFieldsSchema,
                         id: z.string().min(1)
                     }),
-                    execute: async ({ collection, id })=>{
+                    execute: async ({ collection, fields, id })=>{
                         if (requestedDocumentScope && (collection !== requestedCollectionSlug || id !== requestedDocumentID)) {
                             return createToolError({
                                 collection,
@@ -1073,16 +1276,37 @@ export const createChatHandler = (options = {})=>async (req)=>{
                                 tool: "getDoc"
                             });
                         }
-                        return req.payload.findByID({
+                        const explicitlyMentioned = explicitlyMentionedDocumentKeys.has(`${collection}:${id}`);
+                        const collectionConfig = allowedCollectionsBySlug.get(collection);
+                        const fieldSelection = resolveToolFieldSelection({
+                            config: collectionConfig,
+                            requestedFields: fields
+                        });
+                        if (!explicitlyMentioned && fieldSelection.invalidFields.length > 0) {
+                            return createToolError({
+                                collection,
+                                details: {
+                                    invalidFields: fieldSelection.invalidFields
+                                },
+                                errorCode: "INVALID_FIELD_SELECTION",
+                                message: `Unknown or sensitive fields requested for ${collection}: ${fieldSelection.invalidFields.join(", ")}.`,
+                                tool: "getDoc"
+                            });
+                        }
+                        const document = await req.payload.findByID({
                             collection: collection,
-                            depth: 2,
+                            depth: explicitlyMentioned ? 2 : fieldSelection.depth,
                             id,
                             ...activeLocale ? {
                                 locale: activeLocale
                             } : {},
                             overrideAccess: false,
-                            req
+                            req,
+                            ...!explicitlyMentioned ? {
+                                select: fieldSelection.select
+                            } : {}
                         });
+                        return redactSensitiveData(document);
                     }
                 },
                 listCollections: {
@@ -1114,11 +1338,12 @@ export const createChatHandler = (options = {})=>async (req)=>{
                     }
                 },
                 getGlobal: {
-                    description: "Read a global by slug.",
+                    description: "Read a compact global. Optionally request up to 12 exact top-level schema fields. Explicitly @-mentioned globals remain complete.",
                     inputSchema: z.object({
+                        fields: globalReadFieldsSchema,
                         slug: z.string().min(1)
                     }),
-                    execute: async ({ slug })=>{
+                    execute: async ({ fields, slug })=>{
                         if (requestedDocumentScope && slug !== requestedGlobalSlug) {
                             return createToolError({
                                 message: "Only the current global can be read in this context.",
@@ -1134,15 +1359,35 @@ export const createChatHandler = (options = {})=>async (req)=>{
                                 tool: "getGlobal"
                             });
                         }
-                        return req.payload.findGlobal({
-                            depth: 2,
+                        const explicitlyMentioned = explicitlyMentionedGlobalSlugs.has(slug);
+                        const fieldSelection = resolveToolFieldSelection({
+                            config: globalConfig,
+                            requestedFields: fields
+                        });
+                        if (!explicitlyMentioned && fieldSelection.invalidFields.length > 0) {
+                            return createToolError({
+                                details: {
+                                    invalidFields: fieldSelection.invalidFields
+                                },
+                                errorCode: "INVALID_FIELD_SELECTION",
+                                message: `Unknown or sensitive fields requested for global ${slug}: ${fieldSelection.invalidFields.join(", ")}.`,
+                                slug,
+                                tool: "getGlobal"
+                            });
+                        }
+                        const global = await req.payload.findGlobal({
+                            depth: explicitlyMentioned ? 2 : fieldSelection.depth,
                             ...activeLocale ? {
                                 locale: activeLocale
                             } : {},
                             overrideAccess: false,
                             req,
+                            ...!explicitlyMentioned ? {
+                                select: fieldSelection.select
+                            } : {},
                             slug: slug
                         });
+                        return redactSensitiveData(global);
                     }
                 },
                 listGlobals: {
@@ -1174,16 +1419,23 @@ export const createChatHandler = (options = {})=>async (req)=>{
                 proposeCreateDoc: {
                     description: "Propose document creation. Use exact schema fields; include required fields. Use localizedData for multi-locale writes.",
                     inputSchema: z.object({
-                        collection: collectionSlugSchema,
-                        data: z.record(z.string(), z.unknown()).optional(),
+                        collection: focusedCollectionSlugSchema,
+                        data: createDataSchema.optional(),
                         label: z.string().min(1),
-                        localizedData: nonEmptyLocalizedDataSchema.optional()
+                        localizedData: createLocalizedDataSchema.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 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({
@@ -1197,13 +1449,15 @@ export const createChatHandler = (options = {})=>async (req)=>{
                         if (preparedData.issues.length > 0) {
                             const titleFieldName = titleFieldByCollection[collection];
                             const missingTitleField = titleFieldName ? preparedData.issues.some((issue)=>issue.path === titleFieldName || issue.path.endsWith(`.${titleFieldName}`)) : false;
-                            return createToolError({
+                            return createRepairableToolError({
                                 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)}`,
+                                id: repairTargetID,
+                                issues: compactProposalRepairIssues(preparedData.issues),
+                                message: missingTitleField ? `Create proposal is missing the required title field "${titleFieldName}" for ${collection}.` : `Create proposal data for ${collection} is invalid. Correct only repair.issues and call the same tool once more.`,
                                 tool: "proposeCreateDoc"
                             });
                         }
@@ -1234,13 +1488,19 @@ export const createChatHandler = (options = {})=>async (req)=>{
                             }
                             const missingBlockTypes = requestedBlockTypes.filter((blockType)=>!proposalBlockTypes.has(blockType));
                             if (missingBlockTypes.length > 0) {
-                                return createToolError({
+                                return createRepairableToolError({
                                     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.`,
+                                    id: repairTargetID,
+                                    issues: missingBlockTypes.map((blockType)=>({
+                                            code: "missing_requested_block",
+                                            hint: `Add a complete "${blockType}" block using the exact blockType and schema fields.`,
+                                            path: "blocks"
+                                        })),
+                                    message: `Create proposal for ${collection} is missing requested block types: ${missingBlockTypes.join(", ")}.`,
                                     tool: "proposeCreateDoc"
                                 });
                             }
@@ -1344,11 +1604,11 @@ export const createChatHandler = (options = {})=>async (req)=>{
                 proposeUpdateDoc: {
                     description: "Propose document update. Use exact schema fields. Use localizedData for multi-locale writes.",
                     inputSchema: z.object({
-                        collection: collectionSlugSchema,
-                        data: z.record(z.string(), z.unknown()).optional(),
+                        collection: updateHasMultipleTargets ? collectionSlugSchema : focusedCollectionSlugSchema,
+                        data: updateDataSchema.optional(),
                         id: z.string().min(1),
                         label: z.string().min(1),
-                        localizedData: nonEmptyLocalizedDataSchema.optional()
+                        localizedData: updateLocalizedDataSchema.optional()
                     }).refine((value)=>Boolean(value.data || value.localizedData), {
                         message: "Either data or localizedData is required."
                     }),
@@ -1362,6 +1622,12 @@ export const createChatHandler = (options = {})=>async (req)=>{
                         }
                         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({
@@ -1373,12 +1639,14 @@ export const createChatHandler = (options = {})=>async (req)=>{
                             mode: "update"
                         });
                         if (preparedData.issues.length > 0) {
-                            return createToolError({
+                            return createRepairableToolError({
                                 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)}`,
+                                id,
+                                issues: compactProposalRepairIssues(preparedData.issues),
+                                message: `Update proposal data for ${collection}:${id} is invalid. Correct only repair.issues and call the same tool once more.`,
                                 tool: "proposeUpdateDoc"
                             });
                         }
@@ -1449,10 +1717,10 @@ export const createChatHandler = (options = {})=>async (req)=>{
                 proposeUpdateGlobal: {
                     description: "Propose global update. Use localizedData for multi-locale writes.",
                     inputSchema: z.object({
-                        data: z.record(z.string(), z.unknown()).optional(),
+                        data: globalDataSchema.optional(),
                         label: z.string().min(1),
-                        localizedData: nonEmptyLocalizedDataSchema.optional(),
-                        slug: 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."
                     }),
@@ -1472,6 +1740,11 @@ export const createChatHandler = (options = {})=>async (req)=>{
                                 tool: "proposeUpdateGlobal"
                             });
                         }
+                        const repairLimitError = getProposalRepairLimitError({
+                            slug,
+                            tool: "proposeUpdateGlobal"
+                        });
+                        if (repairLimitError) return repairLimitError;
                         const preparedData = prepareProposalWriteData({
                             collectionConfig: {
                                 fields: globalConfig.fields || [],
@@ -1484,11 +1757,12 @@ export const createChatHandler = (options = {})=>async (req)=>{
                             mode: "update"
                         });
                         if (preparedData.issues.length > 0) {
-                            return createToolError({
+                            return createRepairableToolError({
                                 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)}`,
+                                issues: compactProposalRepairIssues(preparedData.issues),
+                                message: `Update proposal data for global ${slug} is invalid. Correct only repair.issues and call the same tool once more.`,
                                 slug,
                                 tool: "proposeUpdateGlobal"
                             });
@@ -1510,20 +1784,37 @@ export const createChatHandler = (options = {})=>async (req)=>{
                     }
                 },
                 searchDocs: {
-                    description: "Search documents in one collection.",
+                    description: "Search compact documents in one collection. Returns default identity fields or up to 12 requested exact top-level schema fields.",
                     inputSchema: z.object({
                         collection: collectionSlugSchema,
+                        fields: collectionReadFieldsSchema,
                         limit: z.number().int().min(1).max(10).default(5),
                         query: z.string().optional()
                     }),
-                    execute: async ({ collection, limit, query })=>{
+                    execute: async ({ collection, fields, limit, query })=>{
                         const collectionConfig = allowedCollectionsBySlug.get(collection);
+                        const fieldSelection = resolveToolFieldSelection({
+                            config: collectionConfig,
+                            mode: "search",
+                            requestedFields: fields
+                        });
+                        if (fieldSelection.invalidFields.length > 0) {
+                            return createToolError({
+                                collection,
+                                details: {
+                                    invalidFields: fieldSelection.invalidFields
+                                },
+                                errorCode: "INVALID_FIELD_SELECTION",
+                                message: `Unknown or sensitive fields requested for ${collection}: ${fieldSelection.invalidFields.join(", ")}.`,
+                                tool: "searchDocs"
+                            });
+                        }
                         const searchableFields = collectionConfig?.fields.flatMap((field)=>{
                             if (!("name" in field) || ![
                                 "email",
                                 "text",
                                 "textarea"
-                            ].includes(field.type) || !field.name) return [];
+                            ].includes(field.type) || !field.name || isSensitiveKey(field.name)) return [];
                             return [
                                 field.name
                             ];
@@ -1535,34 +1826,35 @@ export const createChatHandler = (options = {})=>async (req)=>{
                                     }
                                 }))
                         } : undefined;
-                        return req.payload.find({
+                        const result = await req.payload.find({
                             collection: collection,
-                            depth: 1,
+                            depth: fieldSelection.depth,
                             limit,
                             ...activeLocale ? {
                                 locale: activeLocale
                             } : {},
                             overrideAccess: false,
                             req,
+                            select: fieldSelection.select,
                             where
                         });
+                        return redactSensitiveData({
+                            docs: result.docs,
+                            hasNextPage: result.hasNextPage
+                        });
                     }
                 }
             };
-            const scopedToolNames = requestedCollectionSlug ? requestedDocumentID ? new Set([
-                "getDoc",
-                "listCollections",
-                "proposeUpdateDoc"
-            ]) : new Set([
-                "listCollections",
-                "proposeCreateDoc"
-            ]) : requestedGlobalSlug ? new Set([
-                "getGlobal",
-                "listGlobals",
-                "proposeUpdateGlobal"
-            ]) : null;
-            const tools = scopedToolNames ? Object.fromEntries(Object.entries(allTools).filter(([name])=>scopedToolNames.has(name))) : allTools;
-            if (intentToolChoice && scopedToolNames && !scopedToolNames.has(intentToolChoice.toolName)) {
+            const scopedToolNames = getToolNamesForIntent({
+                hasAttachments: Boolean(body?.attachments?.length),
+                hasKnownCollection: Boolean(inferredCollectionConfig),
+                hasCurrentDocument: Boolean(requestedCollectionSlug && requestedDocumentID),
+                hasCurrentGlobal: Boolean(requestedGlobalSlug),
+                intent: chatIntent
+            });
+            const tools = Object.fromEntries(Object.entries(allTools).filter(([name])=>scopedToolNames.has(name)));
+            debug.tools = Object.keys(tools);
+            if (intentToolChoice && !scopedToolNames.has(intentToolChoice.toolName)) {
                 intentToolChoice = undefined;
             }
             const encoder = new TextEncoder();
@@ -1577,34 +1869,68 @@ export const createChatHandler = (options = {})=>async (req)=>{
                 model: providerConfig.modelID,
                 provider
             });
+            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,
+                provider,
+                staticInstructions: staticSystemInstructions
+            });
+            const promptCacheProviderOptions = createPromptCacheProviderOptions({
+                cacheKeyParts: [
+                    cacheableMentionContext,
+                    cacheableSystemInstructions,
+                    [
+                        ...scopedToolNames
+                    ].sort()
+                ],
+                enabled: explicitPromptCaching,
+                model: providerConfig.modelID,
+                provider
+            });
             const result = streamText({
                 maxOutputTokens: options.maxOutputTokens || 700,
                 model,
                 prompt: buildPromptWithMentionContext({
-                    mentionContext,
+                    mentionContext: dynamicMentionContext,
                     prompt
                 }),
+                ...promptCacheProviderOptions ? {
+                    providerOptions: promptCacheProviderOptions
+                } : {},
                 stopWhen: stepCountIs(6),
-                system: [
-                    "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.",
-                    `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"),
+                system,
                 ...intentToolChoice ? {
                     toolChoice: intentToolChoice
                 } : {},