@extrachill/chat 0.3.0 → 0.5.0

package/src/hooks/useChat.ts

@@ -1,8 +1,9 @@
 import { useState, useCallback, useRef, useEffect } from 'react';
-import type { ChatMessage } from '../types/message.ts';
+import type { ChatMessage, ToolCall } 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 type { MediaAttachment } from '../types/message.ts';
+import type { FetchFn, ChatApiConfig, SendAttachment } from '../api.ts';
 import {
 	sendMessage as apiSendMessage,
 	continueResponse as apiContinueResponse,
@@ -50,6 +51,23 @@ export interface UseChatOptions {
 	 * Called when an error occurs.
 	 */
 	onError?: (error: Error) => void;
+	/**
+	 * Called after each turn when tool calls are present in the response.
+	 * Use this to react to tool executions (e.g. invalidate caches,
+	 * apply diffs to the editor, update external state).
+	 */
+	onToolCalls?: (toolCalls: ToolCall[]) => void;
+	/**
+	 * Arbitrary metadata forwarded to the backend with each message.
+	 * Use for context scoping (e.g. `{ selected_pipeline_id: 42 }`,
+	 * `{ post_id: 100, context: 'editor' }`).
+	 */
+	metadata?: Record<string, unknown>;
+	/**
+	 * Optional context filter for session listing.
+	 * Only sessions created in the matching context are shown.
+	 */
+	sessionContext?: string;
 }
 
 /**
@@ -66,12 +84,19 @@ export interface UseChatReturn {
 	availability: ChatAvailability;
 	/** Active session ID. */
 	sessionId: string | null;
+	/**
+	 * The session ID that initiated the current request.
+	 * Use to avoid stale loading indicators when the user switches
+	 * sessions while a request is in flight.
+	 * Null when idle.
+	 */
+	processingSessionId: string | null;
 	/** List of sessions. */
 	sessions: ChatSession[];
 	/** Whether sessions are loading. */
 	sessionsLoading: boolean;
-	/** Send a user message. */
-	sendMessage: (content: string) => void;
+	/** Send a user message (with optional file attachments). */
+	sendMessage: (content: string, files?: File[]) => void;
 	/** Switch to a different session. */
 	switchSession: (sessionId: string) => void;
 	/** Create a new session. */
@@ -141,12 +166,16 @@ export function useChat({
 	maxContinueTurns = 20,
 	onMessage,
 	onError,
+	onToolCalls,
+	metadata,
+	sessionContext,
 }: 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 [processingSessionId, setProcessingSessionId] = useState<string | null>(null);
 	const [sessions, setSessions] = useState<ChatSession[]>([]);
 	const [sessionsLoading, setSessionsLoading] = useState(false);
 
@@ -157,12 +186,26 @@ export function useChat({
 	const sessionIdRef = useRef(sessionId);
 	sessionIdRef.current = sessionId;
 
+	// Refs for latest callback/metadata values (avoid stale closures).
+	const onToolCallsRef = useRef(onToolCalls);
+	onToolCallsRef.current = onToolCalls;
+	const metadataRef = useRef(metadata);
+	metadataRef.current = metadata;
+	const sessionContextRef = useRef(sessionContext);
+	sessionContextRef.current = sessionContext;
+	// Guard against concurrent session creation.
+	const isCreatingRef = useRef(false);
+
 	// Load sessions on mount
 	useEffect(() => {
 		const loadSessions = async () => {
 			setSessionsLoading(true);
 			try {
-				const list = await apiListSessions(configRef.current);
+				const list = await apiListSessions(
+					configRef.current,
+					20,
+					sessionContextRef.current,
+				);
 				setSessions(list);
 			} catch (err) {
 				// Sessions not available — degrade gracefully
@@ -176,8 +219,47 @@ export function useChat({
 		// eslint-disable-next-line react-hooks/exhaustive-deps
 	}, []);
 
-	const sendMessage = useCallback(async (content: string) => {
-		if (isLoading) return;
+	/**
+	 * Collect tool calls from a list of messages and fire the onToolCalls callback.
+	 */
+	const fireToolCalls = useCallback((msgs: ChatMessage[]) => {
+		const cb = onToolCallsRef.current;
+		if (!cb) return;
+
+		const allToolCalls: ToolCall[] = [];
+		for (const msg of msgs) {
+			if (msg.toolCalls?.length) {
+				allToolCalls.push(...msg.toolCalls);
+			}
+		}
+		if (allToolCalls.length > 0) {
+			cb(allToolCalls);
+		}
+	}, []);
+
+	const sendMessage = useCallback(async (content: string, files?: File[]) => {
+		if (isLoading || isCreatingRef.current) return;
+
+		// Build optimistic attachment previews from local files.
+		let optimisticAttachments: MediaAttachment[] | undefined;
+		let sendAttachments: SendAttachment[] | undefined;
+
+		if (files?.length) {
+			optimisticAttachments = files.map((file) => ({
+				type: file.type.startsWith('image/') ? 'image' as const
+					: file.type.startsWith('video/') ? 'video' as const
+					: 'file' as const,
+				url: URL.createObjectURL(file),
+				filename: file.name,
+				mimeType: file.type,
+				size: file.size,
+			}));
+
+			sendAttachments = files.map((file) => ({
+				filename: file.name,
+				mime_type: file.type,
+			}));
+		}
 
 		// Optimistically add user message
 		const userMessage: ChatMessage = {
@@ -185,27 +267,45 @@ export function useChat({
 			role: 'user',
 			content,
 			timestamp: new Date().toISOString(),
+			attachments: optimisticAttachments,
 		};
 
+		// Guard against concurrent session creation.
+		if (!sessionIdRef.current) {
+			isCreatingRef.current = true;
+		}
+
 		setMessages((prev) => [...prev, userMessage]);
 		onMessage?.(userMessage);
 		setIsLoading(true);
 		setTurnCount(0);
 
+		// Track which session initiated the request.
+		const initiatingSessionId = sessionIdRef.current;
+		setProcessingSessionId(initiatingSessionId);
+
 		try {
 			const result = await apiSendMessage(
 				configRef.current,
 				content,
 				sessionIdRef.current ?? undefined,
+				sendAttachments,
+				metadataRef.current,
 			);
 
+			isCreatingRef.current = false;
+
 			// Update session ID (may be newly created)
 			setSessionId(result.sessionId);
 			sessionIdRef.current = result.sessionId;
+			setProcessingSessionId(result.sessionId);
 
 			// Replace all messages with the full normalized conversation
 			setMessages(result.messages);
 
+			// Fire tool call callback for the initial response.
+			fireToolCalls(result.messages);
+
 			// Handle multi-turn continuation
 			if (!result.completed && !result.maxTurnsReached) {
 				let completed = false;
@@ -225,16 +325,20 @@ export function useChat({
 						onMessage?.(msg);
 					}
 
+					// Fire tool call callback for each continuation turn.
+					fireToolCalls(continuation.messages);
+
 					completed = continuation.completed || continuation.maxTurnsReached;
 				}
 			}
 
 			// Refresh sessions list after a message
-			apiListSessions(configRef.current)
+			apiListSessions(configRef.current, 20, sessionContextRef.current)
 				.then(setSessions)
 				.catch(() => { /* ignore */ });
 
 		} catch (err) {
+			isCreatingRef.current = false;
 			const error = toError(err);
 			onError?.(error);
 
@@ -254,8 +358,9 @@ export function useChat({
 		} finally {
 			setIsLoading(false);
 			setTurnCount(0);
+			setProcessingSessionId(null);
 		}
-	}, [isLoading, maxContinueTurns, onMessage, onError]);
+	}, [isLoading, maxContinueTurns, onMessage, onError, fireToolCalls]);
 
 	const switchSession = useCallback(async (newSessionId: string) => {
 		setSessionId(newSessionId);
@@ -301,7 +406,11 @@ export function useChat({
 	const refreshSessions = useCallback(async () => {
 		setSessionsLoading(true);
 		try {
-			const list = await apiListSessions(configRef.current);
+			const list = await apiListSessions(
+				configRef.current,
+				20,
+				sessionContextRef.current,
+			);
 			setSessions(list);
 		} catch (err) {
 			onError?.(toError(err));
@@ -316,6 +425,7 @@ export function useChat({
 		turnCount,
 		availability,
 		sessionId,
+		processingSessionId,
 		sessions,
 		sessionsLoading,
 		sendMessage,

package/src/index.ts

@@ -3,18 +3,20 @@ export type {
 	MessageRole,
 	ToolCall,
 	ToolResultMeta,
+	MediaAttachment,
 	ChatMessage,
 	ContentFormat,
 	ChatSession,
 	ChatAvailability,
 	ChatInitialState,
+	RawAttachment,
 	RawMessage,
 	RawSession,
 	SessionMetadata,
 } from './types/index.ts';
 
 // API
-export type { FetchFn, FetchOptions, ChatApiConfig, SendResult, ContinueResult } from './api.ts';
+export type { FetchFn, FetchOptions, ChatApiConfig, SendResult, ContinueResult, SendAttachment } from './api.ts';
 export {
 	sendMessage,
 	continueResponse,

package/src/normalizer.ts

@@ -7,9 +7,9 @@
  * maps them into the package's role-based message model.
  */
 
-import type { ChatMessage, ToolCall } from './types/message.ts';
+import type { ChatMessage, MediaAttachment, ToolCall } from './types/message.ts';
 import type { ChatSession } from './types/session.ts';
-import type { RawMessage, RawSession } from './types/api.ts';
+import type { RawMessage, RawAttachment, RawSession } from './types/api.ts';
 
 let idCounter = 0;
 function generateId(): string {
@@ -75,10 +75,16 @@ export function normalizeMessage(raw: RawMessage, index: number): ChatMessage {
 	const message: ChatMessage = {
 		id: generateId(),
 		role: raw.role === 'user' ? 'user' : 'assistant',
-		content: raw.content,
+		content: extractTextContent(raw.content),
 		timestamp,
 	};
 
+	// Extract attachments from metadata (user uploads and tool-produced media).
+	const attachments = normalizeAttachments(raw);
+	if (attachments.length > 0) {
+		message.attachments = attachments;
+	}
+
 	// 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) => ({
@@ -110,3 +116,82 @@ export function normalizeSession(raw: RawSession): ChatSession {
 		messageCount: raw.message_count,
 	};
 }
+
+/**
+ * Extract text content from a message that may be multi-modal.
+ *
+ * When the backend sends multi-modal content, `content` is an array of
+ * content blocks. We extract the text portion for display.
+ */
+function extractTextContent(content: unknown): string {
+	if (typeof content === 'string') return content;
+
+	if (Array.isArray(content)) {
+		const textParts = content
+			.filter((block: Record<string, unknown>) => block.type === 'text' && typeof block.text === 'string')
+			.map((block: Record<string, unknown>) => block.text as string);
+		return textParts.join('\n');
+	}
+
+	return '';
+}
+
+/**
+ * Normalize a single raw attachment into a MediaAttachment.
+ */
+function normalizeRawAttachment(raw: RawAttachment): MediaAttachment | null {
+	if (!raw.url) return null;
+
+	const mimeType = raw.mime_type ?? '';
+	let type: MediaAttachment['type'] = 'file';
+
+	if (raw.type === 'image' || raw.type === 'video' || raw.type === 'file') {
+		type = raw.type;
+	} else if (mimeType.startsWith('image/')) {
+		type = 'image';
+	} else if (mimeType.startsWith('video/')) {
+		type = 'video';
+	}
+
+	const attachment: MediaAttachment = {
+		type,
+		url: raw.url,
+	};
+
+	if (raw.alt) attachment.alt = raw.alt;
+	if (raw.filename) attachment.filename = raw.filename;
+	if (mimeType) attachment.mimeType = mimeType;
+	if (raw.size) attachment.size = raw.size;
+	if (raw.media_id) attachment.mediaId = raw.media_id;
+	if (raw.thumbnail_url) attachment.thumbnailUrl = raw.thumbnail_url;
+
+	return attachment;
+}
+
+/**
+ * Extract all attachments from a raw message.
+ *
+ * Checks metadata.attachments (user uploads) and metadata.media
+ * (tool-produced media) for renderable media.
+ */
+function normalizeAttachments(raw: RawMessage): MediaAttachment[] {
+	const attachments: MediaAttachment[] = [];
+
+	// User-uploaded attachments.
+	if (raw.metadata?.attachments) {
+		for (const rawAtt of raw.metadata.attachments) {
+			const att = normalizeRawAttachment(rawAtt);
+			if (att) attachments.push(att);
+		}
+	}
+
+	// Tool-produced media.
+	if (raw.metadata?.media) {
+		for (const rawMedia of raw.metadata.media) {
+			const att = normalizeRawAttachment(rawMedia);
+			if (att) attachments.push(att);
+		}
+	}
+
+	return attachments;
+}

package/src/types/api.ts

@@ -10,18 +10,36 @@
  * A raw message as stored/returned by the backend.
  * The package normalizes these into ChatMessage before rendering.
  */
+/**
+ * A raw media attachment as returned by the backend.
+ */
+export interface RawAttachment {
+	type?: string;
+	url?: string;
+	alt?: string;
+	filename?: string;
+	mime_type?: string;
+	size?: number;
+	media_id?: number;
+	thumbnail_url?: string;
+}
+
 export interface RawMessage {
 	role: 'user' | 'assistant';
 	content: string;
 	metadata?: {
 		timestamp?: string;
-		type?: 'text' | 'tool_call' | 'tool_result';
+		type?: 'text' | 'multimodal' | 'tool_call' | 'tool_result';
 		tool_name?: string;
 		parameters?: Record<string, unknown>;
 		success?: boolean;
 		error?: string;
 		turn?: number;
 		tool_data?: Record<string, unknown>;
+		/** Attachments sent with the message. */
+		attachments?: RawAttachment[];
+		/** Media produced by tool results. */
+		media?: RawAttachment[];
 	};
 	tool_calls?: Array<{
 		tool_name: string;
@@ -36,6 +54,13 @@ export interface SendRequest {
 	message: string;
 	session_id?: string;
 	agent_id?: number;
+	/** Media attachments to send with the message. */
+	attachments?: Array<{
+		url?: string;
+		media_id?: number;
+		mime_type?: string;
+		filename?: string;
+	}>;
 }
 
 export interface SendResponse {

package/src/types/index.ts

@@ -2,6 +2,7 @@ export type {
 	MessageRole,
 	ToolCall,
 	ToolResultMeta,
+	MediaAttachment,
 	ChatMessage,
 	ContentFormat,
 } from './message.ts';
@@ -13,6 +14,7 @@ export type {
 } from './session.ts';
 
 export type {
+	RawAttachment,
 	RawMessage,
 	RawSession,
 	SendRequest,

package/src/types/message.ts

@@ -38,6 +38,28 @@ export interface ToolResultMeta {
 	success: boolean;
 }
 
+/**
+ * A media attachment on a chat message (image, video, or file).
+ */
+export interface MediaAttachment {
+	/** Media type. */
+	type: 'image' | 'video' | 'file';
+	/** Public URL of the media. */
+	url: string;
+	/** Alt text or description. */
+	alt?: string;
+	/** Original filename. */
+	filename?: string;
+	/** MIME type (e.g. 'image/jpeg'). */
+	mimeType?: string;
+	/** File size in bytes. */
+	size?: number;
+	/** WordPress media library attachment ID. */
+	mediaId?: number;
+	/** Thumbnail URL for previews. */
+	thumbnailUrl?: string;
+}
+
 /**
  * A single message in a chat conversation.
  */
@@ -54,6 +76,8 @@ export interface ChatMessage {
 	toolCalls?: ToolCall[];
 	/** Tool result metadata (only on tool_result messages). */
 	toolResult?: ToolResultMeta;
+	/** Media attachments (images, videos, files) on this message. */
+	attachments?: MediaAttachment[];
 }
 
 /**