@newfold/wp-module-ai-chat 1.0.0

package/src/constants/nfdAgents/storageKeys.js

@@ -0,0 +1,102 @@
+/**
+ * NFD Agents Storage Key Constants
+ *
+ * Site-scoped localStorage key construction and site ID management.
+ * Used by useNfdAgentsWebSocket, archiveConversation, and ChatHistoryList.
+ * Key format: nfd-ai-chat-{siteId}-{consumer}-{suffix} (or nfd-ai-chat-{consumer}-{suffix} when siteId is empty).
+ */
+
+/* global localStorage */
+
+const SITE_ID_KEY = "nfd-ai-chat-site-id";
+
+/** Suffixes for consumer-scoped keys. Single source of truth for migrateStorageKeys and getChatHistoryStorageKeys. */
+const STORAGE_KEY_SUFFIXES = {
+	history: "history",
+	conversationId: "conversation-id",
+	sessionId: "session-id",
+	archive: "archive",
+};
+
+/**
+ * Get the cached site ID from localStorage.
+ * Returns '' if not yet cached (backwards compatible with pre-migration keys).
+ *
+ * @return {string} Cached site ID or empty string
+ */
+export const getSiteId = () => {
+	try {
+		return localStorage.getItem(SITE_ID_KEY) || "";
+	} catch {
+		return "";
+	}
+};
+
+/**
+ * Cache the site ID in localStorage.
+ *
+ * @param {string} id Site ID to cache
+ */
+export const setSiteId = (id) => {
+	try {
+		localStorage.setItem(SITE_ID_KEY, id);
+	} catch {
+		// Ignore storage errors (e.g. private mode, quota).
+	}
+};
+
+/**
+ * Build key prefix for a consumer (with or without site ID).
+ *
+ * @param {string} siteId   Site ID or '' for pre-migration keys
+ * @param {string} consumer Consumer identifier
+ * @return {string} Key prefix for consumer-scoped keys (e.g. nfd-ai-chat-{siteId}-{consumer}).
+ */
+const getKeyPrefix = (siteId, consumer) =>
+	siteId ? `nfd-ai-chat-${siteId}-${consumer}` : `nfd-ai-chat-${consumer}`;
+
+/**
+ * Migrate localStorage data from old-prefix keys to new-prefix keys.
+ * Only copies when the new key has no data; then removes the old key.
+ *
+ * @param {string} oldSiteId Previous site ID ('' for pre-migration keys)
+ * @param {string} newSiteId New site ID from config
+ * @param {string} consumer  Consumer identifier (must match useNfdAgentsWebSocket for same surface)
+ */
+export const migrateStorageKeys = (oldSiteId, newSiteId, consumer) => {
+	const oldPrefix = getKeyPrefix(oldSiteId, consumer);
+	const newPrefix = getKeyPrefix(newSiteId, consumer);
+
+	try {
+		for (const suffix of Object.values(STORAGE_KEY_SUFFIXES)) {
+			const oldKey = `${oldPrefix}-${suffix}`;
+			const newKey = `${newPrefix}-${suffix}`;
+			const oldData = localStorage.getItem(oldKey);
+			if (oldData && !localStorage.getItem(newKey)) {
+				localStorage.setItem(newKey, oldData);
+			}
+			if (oldData) {
+				localStorage.removeItem(oldKey);
+			}
+		}
+	} catch {
+		// Ignore storage errors.
+	}
+};
+
+/**
+ * Get localStorage keys for chat history and related data for a given consumer.
+ * Includes the cached site ID in the key prefix for multisite isolation.
+ * Must match the keys used in useNfdAgentsWebSocket for the same consumer.
+ *
+ * @param {string} consumer Consumer identifier (must match useNfdAgentsWebSocket for same surface)
+ * @return {{ history: string, conversationId: string, sessionId: string, archive: string }} Object with localStorage key strings for history, conversationId, sessionId, and archive.
+ */
+export const getChatHistoryStorageKeys = (consumer) => {
+	const prefix = getKeyPrefix(getSiteId(), consumer);
+	const keys = {};
+	for (const [name, suffix] of Object.entries(STORAGE_KEY_SUFFIXES)) {
+		keys[name] = `${prefix}-${suffix}`;
+	}
+	return keys;
+};

package/src/constants/nfdAgents/typingStatus.js

@@ -0,0 +1,40 @@
+/**
+ * Typing indicator status keys and event mapping.
+ * Single source of truth for status values shown between typing_start and typing_stop.
+ * Hook maps WebSocket event types to these keys; UI maps keys to display strings.
+ */
+
+/** Status keys for the typing indicator (no UI copy here) */
+export const TYPING_STATUS = {
+	PROCESSING: "processing",
+	CONNECTING: "connecting",
+	WS_CONNECTING: "ws_connecting",
+	TOOL_CALL: "tool_call",
+	WORKING: "working",
+	// Existing keys used elsewhere
+	RECEIVED: "received",
+	GENERATING: "generating",
+	SUMMARIZING: "summarizing",
+	COMPLETED: "completed",
+	FAILED: "failed",
+};
+
+/**
+ * Map WebSocket message type to typing status key.
+ * Add new event types here to drive status without scattering branches.
+ * Returns null for typing_stop (and unknown types) to clear the indicator.
+ *
+ * @param {string} eventType data.type from WebSocket message
+ * @return {string|null} TYPING_STATUS key, or null to clear the typing indicator
+ */
+export function getStatusForEventType(eventType) {
+	const map = {
+		typing_start: TYPING_STATUS.PROCESSING,
+		handoff_request: TYPING_STATUS.CONNECTING,
+		handoff_accept: TYPING_STATUS.CONNECTING,
+		tool_call: TYPING_STATUS.TOOL_CALL,
+		tool_result: TYPING_STATUS.WORKING,
+		typing_stop: null,
+	};
+	return map[eventType] ?? null;
+}

package/src/constants/nfdAgents/websocket.js

@@ -0,0 +1,44 @@
+/**
+ * NFD Agents WebSocket Configuration
+ *
+ * Constants for WebSocket connection, reconnection, typing indicator timeout,
+ * and JWT refresh. Storage key construction lives in storageKeys.js (getChatHistoryStorageKeys).
+ */
+
+/** WebSocket close code: authentication failed (e.g. expired token). */
+export const WS_CLOSE_AUTH_FAILED = 4000;
+
+/** WebSocket close code: missing authentication token. */
+export const WS_CLOSE_MISSING_TOKEN = 4001;
+
+/** Buffer (ms) before JWT exp at which to proactively refresh (e.g. 5 min). */
+const FIVE_MINUTES_MS = 5 * 60 * 1000;
+
+/** Never schedule proactive refresh sooner than this (ms). */
+const FIVE_MINUTES_MIN_DELAY_MS = 5 * 60 * 1000;
+
+/** Don't schedule another proactive refresh sooner than this after the last one (ms). */
+const ONE_HOUR_MS = 60 * 60 * 1000;
+
+/** Don't clear config + reset attempts on 4000/4001 more than once per this window (ms). */
+const AUTH_REFRESH_COOLDOWN_MS = 3 * 60 * 1000;
+
+/** Consider token expired if exp is within this many ms from now (pre-connect check). */
+const JWT_EXPIRED_BUFFER_MS = 60 * 1000;
+
+/** When proactive refresh fires during an in-flight reply, reschedule after this many ms. */
+const JWT_PROACTIVE_REFRESH_DEFER_MS = 30 * 1000;
+
+export const NFD_AGENTS_WEBSOCKET = {
+	MAX_RECONNECT_ATTEMPTS: 5,
+	RECONNECT_DELAY: 1000, // Base delay between reconnect attempts (ms)
+	TYPING_TIMEOUT: 60000, // Hide typing indicator if no response within this time (ms)
+	WS_CLOSE_AUTH_FAILED,
+	WS_CLOSE_MISSING_TOKEN,
+	JWT_REFRESH_BUFFER_MS: FIVE_MINUTES_MS,
+	JWT_REFRESH_MIN_DELAY_MS: FIVE_MINUTES_MIN_DELAY_MS,
+	JWT_PROACTIVE_REFRESH_COOLDOWN_MS: ONE_HOUR_MS,
+	AUTH_REFRESH_COOLDOWN_MS,
+	JWT_EXPIRED_BUFFER_MS,
+	JWT_PROACTIVE_REFRESH_DEFER_MS,
+};

package/src/hooks/useAIChat.js

@@ -0,0 +1,432 @@
+/**
+ * WordPress dependencies
+ */
+import { useState, useCallback, useRef, useEffect } from "@wordpress/element";
+
+/**
+ * Internal dependencies
+ */
+import { generateSessionId } from "../utils/helpers";
+
+/**
+ * Chat status enumeration
+ */
+export const CHAT_STATUS = {
+	IDLE: "idle",
+	RECEIVED: "received",
+	GENERATING: "generating",
+	TOOL_CALL: "tool_call",
+	SUMMARIZING: "summarizing",
+	COMPLETED: "completed",
+	FAILED: "failed",
+};
+
+/**
+ * Default system prompt
+ */
+const DEFAULT_SYSTEM_PROMPT = `You are a helpful AI assistant. Be concise and helpful in your responses.`;
+
+/**
+ * useAIChat Hook
+ *
+ * A configurable React hook for managing AI chat conversations.
+ * Provides extension points for tool handling and message processing.
+ *
+ * @param {Object}   options                   - Hook configuration options
+ * @param {Object}   options.mcpClient         - MCP client instance for tool execution
+ * @param {Object}   options.openaiClient      - OpenAI client instance for chat completions
+ * @param {string}   options.systemPrompt      - System prompt for the AI
+ * @param {Function} options.onToolCall        - Callback before tool execution (can intercept)
+ * @param {Function} options.onToolResult      - Callback after tool execution (for glue code)
+ * @param {Function} options.onMessageComplete - Callback when a message is complete
+ * @param {Function} options.onError           - Callback for errors
+ * @param {boolean}  options.autoInitialize    - Auto-initialize MCP client (default: true)
+ * @return {Object} Chat state and controls
+ */
+export const useAIChat = ({
+	mcpClient = null,
+	openaiClient = null,
+	systemPrompt = DEFAULT_SYSTEM_PROMPT,
+	onToolCall = null,
+	onToolResult = null,
+	onMessageComplete = null,
+	onError = null,
+	autoInitialize = true,
+} = {}) => {
+	// Chat state
+	const [messages, setMessages] = useState([]);
+	const [isLoading, setIsLoading] = useState(false);
+	const [error, setError] = useState(null);
+	const [status, setStatus] = useState(CHAT_STATUS.IDLE);
+	const [sessionId, setSessionId] = useState(() => generateSessionId());
+
+	// Tool execution state
+	const [activeToolCall, setActiveToolCall] = useState(null);
+	const [executedTools, setExecutedTools] = useState([]);
+	const [pendingTools, setPendingTools] = useState([]);
+	const [toolProgress, setToolProgress] = useState(null);
+
+	// MCP state
+	const [mcpConnected, setMcpConnected] = useState(false);
+	const [mcpTools, setMcpTools] = useState([]);
+
+	// Refs
+	const isProcessingRef = useRef(false);
+	const abortControllerRef = useRef(null);
+
+	/**
+	 * Initialize MCP client
+	 */
+	const initializeMCP = useCallback(async () => {
+		if (!mcpClient) {
+			return false;
+		}
+
+		try {
+			if (!mcpClient.isConnected()) {
+				await mcpClient.connect();
+			}
+			await mcpClient.initialize();
+			setMcpTools(mcpClient.getTools());
+			setMcpConnected(true);
+			return true;
+		} catch (err) {
+			// eslint-disable-next-line no-console
+			console.error("Failed to initialize MCP:", err);
+			setError(`Failed to initialize MCP: ${err.message}`);
+			onError?.(err);
+			return false;
+		}
+	}, [mcpClient, onError]);
+
+	/**
+	 * Auto-initialize MCP on mount
+	 */
+	useEffect(() => {
+		if (autoInitialize && mcpClient) {
+			initializeMCP();
+		}
+
+		// Copy ref to variable for cleanup function
+		const abortController = abortControllerRef.current;
+
+		return () => {
+			if (abortController) {
+				abortController.abort();
+			}
+		};
+	}, [autoInitialize, mcpClient, initializeMCP]);
+
+	/**
+	 * Create a new message object
+	 */
+	const createMessage = useCallback((role, content, extras = {}) => {
+		return {
+			id: `${role}-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
+			role,
+			type: role,
+			content,
+			timestamp: new Date(),
+			...extras,
+		};
+	}, []);
+
+	/**
+	 * Execute a single tool call
+	 *
+	 * The onToolCall callback can return an object with { intercepted: true, result: {...} }
+	 * to handle the tool call locally instead of calling MCP.
+	 */
+	const executeTool = useCallback(
+		async (toolCall) => {
+			if (!mcpClient) {
+				throw new Error("MCP client not available");
+			}
+
+			const { name, arguments: args } = toolCall;
+
+			// Call onToolCall - it can optionally intercept and return a result
+			if (onToolCall) {
+				const interceptResult = await onToolCall(toolCall);
+
+				// If the callback intercepted the call, use its result
+				if (interceptResult && interceptResult.intercepted) {
+					const result = interceptResult.result || {
+						content: [],
+						isError: false,
+					};
+
+					// Notify after execution (for glue code to react to changes)
+					if (onToolResult) {
+						await onToolResult(toolCall, result);
+					}
+
+					return {
+						id: toolCall.id,
+						name,
+						result,
+						isError: result.isError || false,
+						hasChanges: result.hasChanges || false,
+						undoData: interceptResult.undoData,
+					};
+				}
+			}
+
+			try {
+				const result = await mcpClient.callTool(name, args);
+
+				// Notify after execution (for glue code to react to changes)
+				if (onToolResult) {
+					await onToolResult(toolCall, result);
+				}
+
+				return {
+					id: toolCall.id,
+					name,
+					result,
+					isError: result.isError || false,
+				};
+			} catch (err) {
+				return {
+					id: toolCall.id,
+					name,
+					error: err.message,
+					isError: true,
+				};
+			}
+		},
+		[mcpClient, onToolCall, onToolResult]
+	);
+
+	/**
+	 * Execute all tool calls
+	 */
+	const executeToolCalls = useCallback(
+		async (toolCalls) => {
+			const results = [];
+			setPendingTools(toolCalls.slice(1));
+
+			for (let i = 0; i < toolCalls.length; i++) {
+				const toolCall = toolCalls[i];
+
+				setActiveToolCall({
+					...toolCall,
+					index: i + 1,
+					total: toolCalls.length,
+				});
+
+				const result = await executeTool(toolCall);
+				results.push(result);
+
+				setExecutedTools((prev) => [...prev, { ...toolCall, ...result }]);
+				setPendingTools(toolCalls.slice(i + 2));
+			}
+
+			setActiveToolCall(null);
+			setPendingTools([]);
+			return results;
+		},
+		[executeTool]
+	);
+
+	/**
+	 * Send a message and get AI response
+	 */
+	const sendMessage = useCallback(
+		async (userMessage) => {
+			if (!openaiClient) {
+				setError("OpenAI client not configured");
+				return;
+			}
+
+			if (isProcessingRef.current) {
+				return;
+			}
+
+			isProcessingRef.current = true;
+			setIsLoading(true);
+			setError(null);
+			setStatus(CHAT_STATUS.RECEIVED);
+			setExecutedTools([]);
+
+			// Add user message
+			const userMsg = createMessage("user", userMessage);
+			setMessages((prev) => [...prev, userMsg]);
+
+			try {
+				// Build conversation history
+				const conversationHistory = [
+					{ role: "system", content: systemPrompt },
+					...messages.map((msg) => ({
+						role: msg.role === "user" ? "user" : "assistant",
+						content: msg.content,
+						toolCalls: msg.toolCalls,
+						toolResults: msg.toolResults,
+					})),
+					{ role: "user", content: userMessage },
+				];
+
+				// Get tools in OpenAI format
+				const tools = mcpConnected && mcpClient ? mcpClient.getToolsForOpenAI() : [];
+
+				setStatus(CHAT_STATUS.GENERATING);
+
+				let response = null;
+				let allToolResults = [];
+
+				// Streaming completion
+				await openaiClient.createStreamingCompletion(
+					{
+						messages: openaiClient.convertMessagesToOpenAI(conversationHistory),
+						tools: tools.length > 0 ? tools : undefined,
+						tool_choice: tools.length > 0 ? "auto" : undefined,
+					},
+					// onChunk - streaming content updates could be added here
+					() => {},
+					// onComplete
+					async (fullMessage, toolCalls) => {
+						if (toolCalls && toolCalls.length > 0) {
+							setStatus(CHAT_STATUS.TOOL_CALL);
+
+							// Execute tool calls
+							const toolResults = await executeToolCalls(toolCalls);
+							allToolResults = toolResults;
+
+							// Continue conversation with tool results
+							setStatus(CHAT_STATUS.SUMMARIZING);
+
+							const followUpHistory = [
+								...conversationHistory,
+								{
+									role: "assistant",
+									content: fullMessage || null,
+									toolCalls,
+									toolResults: toolResults.map((r) => ({
+										id: r.id,
+										result: r.result,
+										error: r.error,
+									})),
+								},
+							];
+
+							// Get follow-up response
+							const followUp = await openaiClient.createChatCompletion({
+								messages: openaiClient.convertMessagesToOpenAI(followUpHistory),
+							});
+
+							response = followUp.choices?.[0]?.message?.content || "";
+						} else {
+							response = fullMessage;
+						}
+					},
+					// onError
+					(err) => {
+						throw err;
+					}
+				);
+
+				// Add assistant message
+				if (response) {
+					const assistantMsg = createMessage("assistant", response, {
+						toolCalls: allToolResults.length > 0 ? allToolResults : undefined,
+						executedTools: allToolResults.length > 0 ? allToolResults : undefined,
+					});
+					setMessages((prev) => [...prev, assistantMsg]);
+					onMessageComplete?.(assistantMsg);
+				}
+
+				setStatus(CHAT_STATUS.COMPLETED);
+			} catch (err) {
+				// eslint-disable-next-line no-console
+				console.error("Chat error:", err);
+				setError(err.message);
+				setStatus(CHAT_STATUS.FAILED);
+				onError?.(err);
+			} finally {
+				isProcessingRef.current = false;
+				setIsLoading(false);
+				setActiveToolCall(null);
+				setExecutedTools([]);
+				setPendingTools([]);
+			}
+		},
+		[
+			openaiClient,
+			mcpClient,
+			mcpConnected,
+			messages,
+			systemPrompt,
+			createMessage,
+			executeToolCalls,
+			onMessageComplete,
+			onError,
+		]
+	);
+
+	/**
+	 * Stop the current request
+	 */
+	const stopRequest = useCallback(() => {
+		if (abortControllerRef.current) {
+			abortControllerRef.current.abort();
+		}
+		isProcessingRef.current = false;
+		setIsLoading(false);
+		setStatus(CHAT_STATUS.IDLE);
+		setActiveToolCall(null);
+	}, []);
+
+	/**
+	 * Clear conversation history
+	 */
+	const clearMessages = useCallback(() => {
+		setMessages([]);
+		setError(null);
+		setStatus(CHAT_STATUS.IDLE);
+		setSessionId(generateSessionId());
+	}, []);
+
+	/**
+	 * Add a message programmatically
+	 */
+	const addMessage = useCallback(
+		(role, content, extras = {}) => {
+			const msg = createMessage(role, content, extras);
+			setMessages((prev) => [...prev, msg]);
+			return msg;
+		},
+		[createMessage]
+	);
+
+	return {
+		// State
+		messages,
+		isLoading,
+		error,
+		status,
+		sessionId,
+
+		// Tool execution state
+		activeToolCall,
+		executedTools,
+		pendingTools,
+		toolProgress,
+
+		// MCP state
+		mcpConnected,
+		mcpTools,
+
+		// Actions
+		sendMessage,
+		stopRequest,
+		clearMessages,
+		addMessage,
+		initializeMCP,
+
+		// Setters for advanced usage
+		setError,
+		setToolProgress,
+	};
+};
+
+export default useAIChat;