@extrachill/chat 0.2.0

package/src/hooks/useChat.ts

@@ -0,0 +1,310 @@
+import { useState, useCallback, useRef, useEffect } from 'react';
+import type { ChatMessage } from '../types/message.ts';
+import type { ChatSession } from '../types/session.ts';
+import type { ChatAvailability } from '../types/session.ts';
+import type { FetchFn, ChatApiConfig } from '../api.ts';
+import {
+	sendMessage as apiSendMessage,
+	continueResponse as apiContinueResponse,
+	listSessions as apiListSessions,
+	loadSession as apiLoadSession,
+	deleteSession as apiDeleteSession,
+} from '../api.ts';
+
+/**
+ * Configuration for the useChat hook.
+ */
+export interface UseChatOptions {
+	/**
+	 * Base path for the chat REST endpoints.
+	 * e.g. '/datamachine/v1/chat'
+	 */
+	basePath: string;
+	/**
+	 * Fetch function for API calls. Must accept { path, method?, data? }
+	 * and return parsed JSON. @wordpress/api-fetch works directly.
+	 */
+	fetchFn: FetchFn;
+	/**
+	 * Agent ID to scope the chat to.
+	 */
+	agentId?: number;
+	/**
+	 * Initial messages to hydrate state with (e.g. server-rendered).
+	 */
+	initialMessages?: ChatMessage[];
+	/**
+	 * Initial session ID (e.g. from server-rendered state).
+	 */
+	initialSessionId?: string;
+	/**
+	 * Maximum number of continuation turns before stopping.
+	 * Defaults to 20.
+	 */
+	maxContinueTurns?: number;
+	/**
+	 * Called when a new message is added to the conversation.
+	 */
+	onMessage?: (message: ChatMessage) => void;
+	/**
+	 * Called when an error occurs.
+	 */
+	onError?: (error: Error) => void;
+}
+
+/**
+ * Return value of the useChat hook.
+ */
+export interface UseChatReturn {
+	/** All messages in the current conversation. */
+	messages: ChatMessage[];
+	/** Whether a message is being sent/processed. */
+	isLoading: boolean;
+	/** Current continuation turn count (0 when not processing). */
+	turnCount: number;
+	/** Current availability state. */
+	availability: ChatAvailability;
+	/** Active session ID. */
+	sessionId: string | null;
+	/** List of sessions. */
+	sessions: ChatSession[];
+	/** Whether sessions are loading. */
+	sessionsLoading: boolean;
+	/** Send a user message. */
+	sendMessage: (content: string) => void;
+	/** Switch to a different session. */
+	switchSession: (sessionId: string) => void;
+	/** Create a new session. */
+	newSession: () => void;
+	/** Delete a session. */
+	deleteSession: (sessionId: string) => void;
+	/** Clear the current session's messages locally. */
+	clearSession: () => void;
+	/** Refresh the session list. */
+	refreshSessions: () => void;
+}
+
+let messageIdCounter = 0;
+function generateMessageId(): string {
+	return `msg_${Date.now()}_${++messageIdCounter}`;
+}
+
+/**
+ * Core state orchestrator for the chat UI.
+ *
+ * Manages messages, sessions, continuation loops, and availability
+ * by calling the standard chat REST endpoints directly.
+ *
+ * @example
+ * ```tsx
+ * import apiFetch from '@wordpress/api-fetch';
+ *
+ * const chat = useChat({
+ *   basePath: '/datamachine/v1/chat',
+ *   fetchFn: apiFetch,
+ *   agentId: 5,
+ * });
+ *
+ * return (
+ *   <>
+ *     <ChatMessages messages={chat.messages} />
+ *     <TypingIndicator visible={chat.isLoading} />
+ *     <ChatInput onSend={chat.sendMessage} disabled={chat.isLoading} />
+ *   </>
+ * );
+ * ```
+ */
+export function useChat({
+	basePath,
+	fetchFn,
+	agentId,
+	initialMessages,
+	initialSessionId,
+	maxContinueTurns = 20,
+	onMessage,
+	onError,
+}: UseChatOptions): UseChatReturn {
+	const [messages, setMessages] = useState<ChatMessage[]>(initialMessages ?? []);
+	const [isLoading, setIsLoading] = useState(false);
+	const [turnCount, setTurnCount] = useState(0);
+	const [availability, setAvailability] = useState<ChatAvailability>({ status: 'ready' });
+	const [sessionId, setSessionId] = useState<string | null>(initialSessionId ?? null);
+	const [sessions, setSessions] = useState<ChatSession[]>([]);
+	const [sessionsLoading, setSessionsLoading] = useState(false);
+
+	// Build API config from props
+	const configRef = useRef<ChatApiConfig>({ basePath, fetchFn, agentId });
+	configRef.current = { basePath, fetchFn, agentId };
+
+	const sessionIdRef = useRef(sessionId);
+	sessionIdRef.current = sessionId;
+
+	// Load sessions on mount
+	useEffect(() => {
+		const loadSessions = async () => {
+			setSessionsLoading(true);
+			try {
+				const list = await apiListSessions(configRef.current);
+				setSessions(list);
+			} catch (err) {
+				// Sessions not available — degrade gracefully
+				onError?.(err instanceof Error ? err : new Error(String(err)));
+			} finally {
+				setSessionsLoading(false);
+			}
+		};
+
+		loadSessions();
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, []);
+
+	const sendMessage = useCallback(async (content: string) => {
+		if (isLoading) return;
+
+		// Optimistically add user message
+		const userMessage: ChatMessage = {
+			id: generateMessageId(),
+			role: 'user',
+			content,
+			timestamp: new Date().toISOString(),
+		};
+
+		setMessages((prev) => [...prev, userMessage]);
+		onMessage?.(userMessage);
+		setIsLoading(true);
+		setTurnCount(0);
+
+		try {
+			const result = await apiSendMessage(
+				configRef.current,
+				content,
+				sessionIdRef.current ?? undefined,
+			);
+
+			// Update session ID (may be newly created)
+			setSessionId(result.sessionId);
+			sessionIdRef.current = result.sessionId;
+
+			// Replace all messages with the full normalized conversation
+			setMessages(result.messages);
+
+			// Handle multi-turn continuation
+			if (!result.completed && !result.maxTurnsReached) {
+				let completed = false;
+				let turns = 0;
+
+				while (!completed && turns < maxContinueTurns) {
+					turns++;
+					setTurnCount(turns);
+
+					const continuation = await apiContinueResponse(
+						configRef.current,
+						result.sessionId,
+					);
+
+					setMessages((prev) => [...prev, ...continuation.messages]);
+					for (const msg of continuation.messages) {
+						onMessage?.(msg);
+					}
+
+					completed = continuation.completed || continuation.maxTurnsReached;
+				}
+			}
+
+			// Refresh sessions list after a message
+			apiListSessions(configRef.current)
+				.then(setSessions)
+				.catch(() => { /* ignore */ });
+
+		} catch (err) {
+			const error = err instanceof Error ? err : new Error(String(err));
+			onError?.(error);
+
+			// Check if it's an auth error
+			if (error.message.includes('403') || error.message.includes('rest_forbidden')) {
+				setAvailability({ status: 'login-required' });
+			}
+
+			// Add error as assistant message so it's visible in the UI
+			const errorMessage: ChatMessage = {
+				id: generateMessageId(),
+				role: 'assistant',
+				content: `Sorry, something went wrong: ${error.message}`,
+				timestamp: new Date().toISOString(),
+			};
+			setMessages((prev) => [...prev, errorMessage]);
+		} finally {
+			setIsLoading(false);
+			setTurnCount(0);
+		}
+	}, [isLoading, maxContinueTurns, onMessage, onError]);
+
+	const switchSession = useCallback(async (newSessionId: string) => {
+		setSessionId(newSessionId);
+		sessionIdRef.current = newSessionId;
+		setIsLoading(true);
+
+		try {
+			const loaded = await apiLoadSession(configRef.current, newSessionId);
+			setMessages(loaded);
+		} catch (err) {
+			onError?.(err instanceof Error ? err : new Error(String(err)));
+			setMessages([]);
+		} finally {
+			setIsLoading(false);
+		}
+	}, [onError]);
+
+	const newSession = useCallback(() => {
+		setSessionId(null);
+		sessionIdRef.current = null;
+		setMessages([]);
+	}, []);
+
+	const deleteSessionHandler = useCallback(async (targetSessionId: string) => {
+		try {
+			await apiDeleteSession(configRef.current, targetSessionId);
+			setSessions((prev) => prev.filter((s) => s.id !== targetSessionId));
+
+			if (sessionIdRef.current === targetSessionId) {
+				setSessionId(null);
+				sessionIdRef.current = null;
+				setMessages([]);
+			}
+		} catch (err) {
+			onError?.(err instanceof Error ? err : new Error(String(err)));
+		}
+	}, [onError]);
+
+	const clearSession = useCallback(() => {
+		setMessages([]);
+	}, []);
+
+	const refreshSessions = useCallback(async () => {
+		setSessionsLoading(true);
+		try {
+			const list = await apiListSessions(configRef.current);
+			setSessions(list);
+		} catch (err) {
+			onError?.(err instanceof Error ? err : new Error(String(err)));
+		} finally {
+			setSessionsLoading(false);
+		}
+	}, [onError]);
+
+	return {
+		messages,
+		isLoading,
+		turnCount,
+		availability,
+		sessionId,
+		sessions,
+		sessionsLoading,
+		sendMessage,
+		switchSession,
+		newSession,
+		deleteSession: deleteSessionHandler,
+		clearSession,
+		refreshSessions,
+	};
+}

package/src/index.ts

@@ -0,0 +1,79 @@
+// Types
+export type {
+	MessageRole,
+	ToolCall,
+	ToolResultMeta,
+	ChatMessage,
+	ContentFormat,
+	ChatSession,
+	ChatAvailability,
+	ChatInitialState,
+	RawMessage,
+	RawSession,
+	SessionMetadata,
+} from './types/index.ts';
+
+// API
+export type { FetchFn, FetchOptions, ChatApiConfig, SendResult, ContinueResult } from './api.ts';
+export {
+	sendMessage,
+	continueResponse,
+	listSessions,
+	loadSession,
+	deleteSession,
+} from './api.ts';
+
+// Normalizer
+export { normalizeMessage, normalizeConversation, normalizeSession } from './normalizer.ts';
+
+// Components
+export {
+	ChatMessage as ChatMessageComponent,
+	type ChatMessageProps,
+} from './components/ChatMessage.tsx';
+
+export {
+	ChatMessages,
+	type ChatMessagesProps,
+} from './components/ChatMessages.tsx';
+
+export {
+	ChatInput,
+	type ChatInputProps,
+} from './components/ChatInput.tsx';
+
+export {
+	ToolMessage,
+	type ToolMessageProps,
+	type ToolGroup,
+} from './components/ToolMessage.tsx';
+
+export {
+	TypingIndicator,
+	type TypingIndicatorProps,
+} from './components/TypingIndicator.tsx';
+
+export {
+	SessionSwitcher,
+	type SessionSwitcherProps,
+} from './components/SessionSwitcher.tsx';
+
+export {
+	ErrorBoundary,
+	type ErrorBoundaryProps,
+} from './components/ErrorBoundary.tsx';
+
+export {
+	AvailabilityGate,
+	type AvailabilityGateProps,
+} from './components/AvailabilityGate.tsx';
+
+// Hook
+export {
+	useChat,
+	type UseChatOptions,
+	type UseChatReturn,
+} from './hooks/useChat.ts';
+
+// Composed
+export { Chat, type ChatProps } from './Chat.tsx';

package/src/normalizer.ts

@@ -0,0 +1,112 @@
+/**
+ * Normalize raw backend messages into the ChatMessage format
+ * used by the UI components.
+ *
+ * The backend stores tool calls and results as regular messages
+ * with metadata.type = 'tool_call' | 'tool_result'. This normalizer
+ * maps them into the package's role-based message model.
+ */
+
+import type { ChatMessage, ToolCall } from './types/message.ts';
+import type { ChatSession } from './types/session.ts';
+import type { RawMessage, RawSession } from './types/api.ts';
+
+let idCounter = 0;
+function generateId(): string {
+	return `msg_${Date.now()}_${++idCounter}`;
+}
+
+/**
+ * Normalize a raw backend message into a ChatMessage.
+ */
+export function normalizeMessage(raw: RawMessage, index: number): ChatMessage {
+	const type = raw.metadata?.type ?? 'text';
+	const timestamp = raw.metadata?.timestamp ?? new Date().toISOString();
+
+	if (type === 'tool_call') {
+		const toolCalls: ToolCall[] = [];
+
+		// Extract from metadata (single tool call)
+		if (raw.metadata?.tool_name) {
+			toolCalls.push({
+				id: `tc_${index}_${raw.metadata.tool_name}`,
+				name: raw.metadata.tool_name,
+				parameters: raw.metadata.parameters ?? {},
+			});
+		}
+
+		// Also check top-level tool_calls array
+		if (raw.tool_calls?.length) {
+			for (const tc of raw.tool_calls) {
+				// Avoid duplicates
+				if (!toolCalls.some((t) => t.name === tc.tool_name)) {
+					toolCalls.push({
+						id: `tc_${index}_${tc.tool_name}`,
+						name: tc.tool_name,
+						parameters: tc.parameters ?? {},
+					});
+				}
+			}
+		}
+
+		return {
+			id: generateId(),
+			role: 'tool_call',
+			content: raw.content,
+			timestamp,
+			toolCalls,
+		};
+	}
+
+	if (type === 'tool_result') {
+		return {
+			id: generateId(),
+			role: 'tool_result',
+			content: raw.content,
+			timestamp,
+			toolResult: {
+				toolName: raw.metadata?.tool_name ?? 'unknown',
+				success: raw.metadata?.success ?? false,
+			},
+		};
+	}
+
+	// Regular text message (user or assistant)
+	const message: ChatMessage = {
+		id: generateId(),
+		role: raw.role === 'user' ? 'user' : 'assistant',
+		content: raw.content,
+		timestamp,
+	};
+
+	// Assistant messages may carry tool_calls at the top level
+	if (raw.role === 'assistant' && raw.tool_calls?.length) {
+		message.toolCalls = raw.tool_calls.map((tc, i) => ({
+			id: `tc_${index}_${i}_${tc.tool_name}`,
+			name: tc.tool_name,
+			parameters: tc.parameters ?? {},
+		}));
+	}
+
+	return message;
+}
+
+/**
+ * Normalize a full conversation array.
+ */
+export function normalizeConversation(raw: RawMessage[]): ChatMessage[] {
+	return raw.map(normalizeMessage);
+}
+
+/**
+ * Normalize a raw session into a ChatSession.
+ */
+export function normalizeSession(raw: RawSession): ChatSession {
+	return {
+		id: raw.session_id,
+		title: raw.title ?? raw.first_message ?? undefined,
+		createdAt: raw.created_at,
+		updatedAt: raw.updated_at,
+		messageCount: raw.message_count,
+	};
+}

package/src/types/api.ts

@@ -0,0 +1,146 @@
+/**
+ * REST API contract types.
+ *
+ * These describe the expected shape of the chat REST endpoints.
+ * Any backend that wants to work with this package implements
+ * these same endpoints and response shapes.
+ */
+
+/**
+ * A raw message as stored/returned by the backend.
+ * The package normalizes these into ChatMessage before rendering.
+ */
+export interface RawMessage {
+	role: 'user' | 'assistant';
+	content: string;
+	metadata?: {
+		timestamp?: string;
+		type?: 'text' | 'tool_call' | 'tool_result';
+		tool_name?: string;
+		parameters?: Record<string, unknown>;
+		success?: boolean;
+		error?: string;
+		turn?: number;
+		tool_data?: Record<string, unknown>;
+	};
+	tool_calls?: Array<{
+		tool_name: string;
+		parameters: Record<string, unknown>;
+	}>;
+}
+
+/**
+ * POST /chat — Send a message.
+ */
+export interface SendRequest {
+	message: string;
+	session_id?: string;
+	agent_id?: number;
+}
+
+export interface SendResponse {
+	success: boolean;
+	data: {
+		session_id: string;
+		response: string;
+		tool_calls: Array<{
+			tool_name: string;
+			parameters: Record<string, unknown>;
+		}>;
+		conversation: RawMessage[];
+		metadata: SessionMetadata;
+		completed: boolean;
+		max_turns: number;
+		turn_number: number;
+		max_turns_reached: boolean;
+		warning?: string;
+	};
+}
+
+/**
+ * POST /chat/continue — Continue a multi-turn response.
+ */
+export interface ContinueRequest {
+	session_id: string;
+}
+
+export interface ContinueResponse {
+	success: boolean;
+	data: {
+		session_id: string;
+		new_messages: RawMessage[];
+		final_content: string;
+		tool_calls: Array<{
+			tool_name: string;
+			parameters: Record<string, unknown>;
+		}>;
+		completed: boolean;
+		turn_number: number;
+		max_turns: number;
+		max_turns_reached: boolean;
+	};
+}
+
+/**
+ * GET /chat/sessions — List sessions.
+ */
+export interface ListSessionsResponse {
+	success: boolean;
+	data: {
+		sessions: RawSession[];
+		total: number;
+		limit: number;
+		offset: number;
+	};
+}
+
+export interface RawSession {
+	session_id: string;
+	title: string | null;
+	context: string;
+	first_message: string | null;
+	message_count: number;
+	created_at: string;
+	updated_at: string;
+}
+
+/**
+ * GET /chat/{session_id} — Get a single session.
+ */
+export interface GetSessionResponse {
+	success: boolean;
+	data: {
+		session_id: string;
+		conversation: RawMessage[];
+		metadata: SessionMetadata;
+	};
+}
+
+/**
+ * DELETE /chat/{session_id} — Delete a session.
+ */
+export interface DeleteSessionResponse {
+	success: boolean;
+	data: {
+		session_id: string;
+		deleted: boolean;
+	};
+}
+
+/**
+ * Session metadata shape from the backend.
+ */
+export interface SessionMetadata {
+	status?: 'pending' | 'processing' | 'completed' | 'error';
+	started_at?: string;
+	last_activity?: string;
+	message_count?: number;
+	current_turn?: number;
+	has_pending_tools?: boolean;
+	token_usage?: {
+		prompt_tokens: number;
+		completion_tokens: number;
+		total_tokens: number;
+	};
+	error_message?: string;
+}

package/src/types/index.ts

@@ -0,0 +1,26 @@
+export type {
+	MessageRole,
+	ToolCall,
+	ToolResultMeta,
+	ChatMessage,
+	ContentFormat,
+} from './message.ts';
+
+export type {
+	ChatSession,
+	ChatAvailability,
+	ChatInitialState,
+} from './session.ts';
+
+export type {
+	RawMessage,
+	RawSession,
+	SendRequest,
+	SendResponse,
+	ContinueRequest,
+	ContinueResponse,
+	ListSessionsResponse,
+	GetSessionResponse,
+	DeleteSessionResponse,
+	SessionMetadata,
+} from './api.ts';