@mvriu5/payload-ai 1.6.2 → 1.6.4

package/dist/handlers/chat/toolFactory.d.ts

@@ -0,0 +1,79 @@
+import type { PayloadHandler } from "payload";
+import type { ZodType } from "zod";
+import { type CompactProposalRepairIssue } from "../../features/proposals/repair.js";
+import type { ActionProposal } from "../../features/proposals/types.js";
+import { type CollectionAction, type ResolvedCollectionPermissionMap } from "../../features/collectionPermissions.js";
+import type { ToolFailure } from "./types.js";
+type ToolDefinition<Input> = {
+    description: string;
+    execute: (input: Input) => unknown | Promise<unknown>;
+    inputSchema: ZodType;
+};
+type ToolTarget = {
+    collection?: string;
+    id?: string;
+    slug?: string;
+};
+type ToolErrorInput = ToolFailure & {
+    id?: string;
+};
+type RepairableToolErrorInput = ToolErrorInput & {
+    issues: CompactProposalRepairIssue[];
+};
+type CollectionToolOptions<Input extends {
+    collection: string;
+}> = ToolDefinition<Input> & {
+    action?: CollectionAction;
+    currentDocumentOnly?: boolean;
+    getDocumentID?: (input: Input) => string | undefined;
+    name: string;
+};
+type ProposalToolOptions<Input> = ToolDefinition<Input> & {
+    beforeRepair?: (input: Input) => unknown | null;
+    getRepairTarget: (input: Input) => ToolTarget;
+    name: string;
+};
+export type ChatToolFactoryOptions = {
+    collections?: ResolvedCollectionPermissionMap;
+    currentDocument?: {
+        collection: string;
+        id: string;
+    };
+    debug: Record<string, unknown>;
+    prompt: string;
+    req: Parameters<PayloadHandler>[0];
+};
+export declare const createChatToolFactory: ({ collections, currentDocument, debug, prompt, req }: ChatToolFactoryOptions) => {
+    addProposal: <Proposal extends ActionProposal>(proposal: Proposal) => {
+        error: string;
+        errorCode: string;
+        retryable: boolean;
+    } | (Proposal & {
+        _aiSignature: import("../../features/proposals/types.js").AIActionSignature;
+    });
+    collectionTool: <Input extends {
+        collection: string;
+    }>({ action, currentDocumentOnly, description, execute, getDocumentID, inputSchema, name, }: CollectionToolOptions<Input>) => ToolDefinition<Input>;
+    error: ({ collection, details, errorCode, message, slug, tool }: ToolErrorInput) => {
+        error: string;
+        errorCode: string;
+        retryable: boolean;
+    };
+    proposalCollectionTool: <Input extends {
+        collection: string;
+    }>(options: CollectionToolOptions<Input> & Pick<ProposalToolOptions<Input>, "beforeRepair" | "getRepairTarget">) => ToolDefinition<Input>;
+    proposalTool: <Input>({ beforeRepair, description, execute, getRepairTarget, inputSchema, name, }: ProposalToolOptions<Input>) => ToolDefinition<Input>;
+    proposals: ActionProposal[];
+    repairableError: ({ collection, details, id, issues, message, slug, tool }: RepairableToolErrorInput) => {
+        error: string;
+        errorCode: "REPAIR_EXHAUSTED" | "INVALID_PROPOSAL_DATA";
+        repair: {
+            attempt: number;
+            issues: CompactProposalRepairIssue[];
+            maxAttempts: number;
+        };
+        retryable: boolean;
+    };
+    toolFailures: ToolFailure[];
+};
+export {};

package/dist/handlers/chat/toolFactory.js

@@ -0,0 +1,156 @@
+import { createProposalRepairTracker } from "../../features/proposals/repair.js";
+import { signAIActionProposal } from "../../features/proposals/signing.js";
+import { containsSensitiveData } from "../../features/sensitiveData.js";
+import { isCollectionActionAllowed } from "../../features/collectionPermissions.js";
+import { hasLocalizedData } from "../../utils/data.js";
+import { getLogPreview, logHandlerEvent } from "../../utils/logging.js";
+import { getProposalSummary } from "./proposalTools.js";
+export const createChatToolFactory = ({ collections, currentDocument, debug, prompt, req })=>{
+    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 error = ({ 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 repairableError = ({ 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 getRepairLimitError = ({ collection, id, slug, tool })=>{
+        const callState = proposalRepairTracker.beginCall({
+            collection,
+            id,
+            slug,
+            tool
+        });
+        if (callState !== "blocked") return null;
+        return error({
+            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 addProposal = (proposal)=>{
+        const containsSensitiveProposalData = "data" in proposal && proposal.data && containsSensitiveData(proposal.data) || "localizedData" in proposal && hasLocalizedData(proposal.localizedData) && Object.values(proposal.localizedData).some((value)=>containsSensitiveData(value));
+        if (containsSensitiveProposalData) {
+            return error({
+                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 collectionTool = ({ action, currentDocumentOnly, description, execute, getDocumentID, inputSchema, name })=>({
+            description,
+            inputSchema,
+            execute: async (input)=>{
+                if (currentDocumentOnly) {
+                    const id = getDocumentID?.(input);
+                    if (!currentDocument || input.collection !== currentDocument.collection || id !== currentDocument.id) {
+                        return error({
+                            collection: input.collection,
+                            message: `Only the current document can be ${action === "read" ? "read" : `${action}d`} in this context.`,
+                            tool: name
+                        });
+                    }
+                }
+                if (action && !isCollectionActionAllowed({
+                    action,
+                    permissions: collections,
+                    req,
+                    slug: input.collection
+                })) {
+                    return error({
+                        collection: input.collection,
+                        message: `${action} is not enabled for collection: ${input.collection}`,
+                        tool: "collectionPermissionCheck"
+                    });
+                }
+                return execute(input);
+            }
+        });
+    const proposalTool = ({ beforeRepair, description, execute, getRepairTarget, inputSchema, name })=>({
+            description,
+            inputSchema,
+            execute: async (input)=>{
+                const validationError = beforeRepair?.(input);
+                if (validationError) return validationError;
+                const repairLimitError = getRepairLimitError({
+                    ...getRepairTarget(input),
+                    tool: name
+                });
+                if (repairLimitError) return repairLimitError;
+                return execute(input);
+            }
+        });
+    const proposalCollectionTool = (options)=>collectionTool({
+            ...options,
+            ...proposalTool(options)
+        });
+    return {
+        addProposal,
+        collectionTool,
+        error,
+        proposalCollectionTool,
+        proposalTool,
+        proposals,
+        repairableError,
+        toolFailures
+    };
+};

package/dist/handlers/chat/types.d.ts

@@ -0,0 +1,57 @@
+import type { AIRequestOptions } from "../../features/providers/requestContext.js";
+import type { ResolvedCollectionPermissionMap } from "../../features/collectionPermissions.js";
+import type { ChatMention } from "../../features/schema/context.js";
+export type ChatMediaAttachment = {
+    collection?: string;
+    filename?: string;
+    filesize?: number;
+    id?: string;
+    mimeType?: string;
+    type?: "media";
+    url?: string;
+};
+export type ChatBody = {
+    attachments?: ChatMediaAttachment[];
+    documentScope?: {
+        collection?: string;
+        id?: string;
+        type?: "collection";
+    } | {
+        slug?: string;
+        type?: "global";
+    };
+    mentions?: ChatMention[];
+    model?: string;
+    prompt?: string;
+    provider?: string;
+};
+export type ChatDebug = {
+    model: string;
+    provider: string;
+    tools: string[];
+};
+export type ToolFailure = {
+    collection?: string;
+    details?: Record<string, unknown>;
+    errorCode?: string;
+    message: string;
+    retryable?: boolean;
+    slug?: string;
+    tool: string;
+};
+export type TokenUsage = {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+};
+export type ChatOptions = AIRequestOptions & {
+    collections?: ResolvedCollectionPermissionMap;
+    maxOutputTokens?: number;
+    promptCaching?: boolean;
+};
+export type ChatIntent = "create" | "delete" | "read" | "search" | "update" | "updateGlobal";
+export type ProposalToolName = "proposeCreateDoc" | "proposeDeleteDoc" | "proposeUpdateDoc" | "proposeUpdateGlobal";
+export type ToolChoice = {
+    toolName: ProposalToolName;
+    type: "tool";
+};

package/dist/handlers/chat/types.js

@@ -0,0 +1 @@
+export { };

package/dist/handlers/chatHandler.d.ts

@@ -1,46 +1,3 @@
 import type { PayloadHandler } from "payload";
-import { type AIActionSignature } from "../ai/proposalSigning.js";
-import { type AIModelConfig, type ResolvedAIProviderConfig } from "../ai/providerOptions.js";
-import { type ResolvedMaxTokenUsageOptions } from "../ai/tokenUsage.js";
-import { type ResolvedCollectionPermissionMap } from "../payload/collectionPermissions.js";
-type LocalizedDataInput = Record<string, Record<string, unknown>>;
-type ProposalWritePayload = {
-    data: Record<string, unknown>;
-    localizedData?: never;
-} | {
-    data?: never;
-    localizedData: LocalizedDataInput;
-};
-export type ActionProposal = (({
-    action: "create";
-    collection: string;
-    label: string;
-} & ProposalWritePayload) | {
-    action: "delete";
-    collection: string;
-    id: string;
-    label: string;
-} | ({
-    action: "update";
-    collection: string;
-    id: string;
-    label: string;
-} & ProposalWritePayload) | ({
-    action: "updateGlobal";
-    label: string;
-    slug: string;
-} & ProposalWritePayload)) & {
-    _aiSignature?: AIActionSignature;
-    locale?: string;
-};
-type ChatOptions = {
-    allowUserApiKeys?: boolean;
-    collections?: ResolvedCollectionPermissionMap;
-    maxOutputTokens?: number;
-    maxTokenUsage?: ResolvedMaxTokenUsageOptions;
-    models?: AIModelConfig;
-    promptCaching?: boolean;
-    providers?: ResolvedAIProviderConfig[];
-};
+import type { ChatOptions } from "./chat/types.js";
 export declare const createChatHandler: (options?: ChatOptions) => PayloadHandler;
-export {};