orchid-ai 2.1.4 → 2.2.0

package/src/hooks/useOrchidAiChat.js

@@ -10,13 +10,6 @@ import {
   orchidAiProcessTraceHasDisplayableContent,
 } from '../orchidAiProcessTrace';
 
-/**
- * Default status message strings. Export these so server-side code can import
- * and reference the same values, making it easy to keep client and server in sync
- * or swap them out per-app.
- *
- * Set showStatus: false on the hook to suppress status display entirely.
- */
 export const ORCHID_AI_DEFAULT_STATUS = {
   thinking: 'Thinking',
   compilingResponse: ORCHID_AI_SSE_STATUS_CLEAR_STREAM,
@@ -24,25 +17,29 @@ export const ORCHID_AI_DEFAULT_STATUS = {
 };
 
 /**
- * React hook for Orchid AI chat. Handles SSE streaming when the server responds
- * with Content-Type: text/event-stream, falling back to plain JSON for non-streaming
- * backends.
+ * React hook for Orchid AI chat. Handles SSE streaming, stop-generation, and
+ * multi-slot request queuing (messages submitted while loading are held out of
+ * chat history until they fire, then inserted in order).
  *
  * @param {object} opts
- * @param {string} opts.endpoint - POST endpoint URL
- * @param {(userMessage: string, history: Array, sendOptions?: object) => object} opts.buildBody - builds the request body
- * @param {() => object} [opts.getHeaders] - returns extra request headers (e.g. CSRF token)
- * @param {boolean} [opts.showStatus=true] - set false to suppress status text entirely
- * @param {Array} [opts.initialMessages=[]] - seed the conversation (e.g. from localStorage)
+ * @param {string} opts.endpoint
+ * @param {(userMessage: string, history: Array, sendOptions?: object) => object} opts.buildBody
+ * @param {() => object} [opts.getHeaders]
+ * @param {boolean} [opts.showStatus=true]
+ * @param {Array} [opts.initialMessages=[]]
  *
- * @returns {{ messages, loading, statusText, sendMessage, clearMessages }}
+ * @returns {{ messages, loading, statusText, queuedMessages, sendMessage, stopGeneration, clearQueuedMessage, clearMessages }}
  */
 export function useOrchidAiChat({ endpoint, buildBody, getHeaders, showStatus = true, initialMessages = [] }) {
   const [messages, setMessages] = useState(initialMessages);
   const [loading, setLoading] = useState(false);
   const [statusText, setStatusText] = useState('');
+  const [queuedMessages, setQueuedMessages] = useState([]);
 
   const messagesRef = useRef(initialMessages);
+  const abortRef = useRef(null);
+  // Array of { message, sendOptions } held back from chat history until each fires.
+  const queueRef = useRef([]);
 
   const buildBodyRef = useRef(buildBody);
   const getHeadersRef = useRef(getHeaders);
@@ -57,149 +54,243 @@ export function useOrchidAiChat({ endpoint, buildBody, getHeaders, showStatus =
     });
   }, []);
 
-  const sendMessage = useCallback(
-    async (userMessage, sendOptions = {}) => {
-      const history = messagesRef.current.slice();
-      addMessage({ role: 'user', content: userMessage });
-      setLoading(true);
-      setStatusText('');
+  const stopGeneration = useCallback(() => {
+    abortRef.current?.abort();
+  }, []);
 
-      try {
-        const response = await fetch(endpoint, {
-          method: 'POST',
-          headers: {
-            'Content-Type': 'application/json',
-            ...getHeadersRef.current?.(),
-          },
-          body: JSON.stringify(buildBodyRef.current(userMessage, history, sendOptions)),
-        });
+  const clearQueuedMessage = useCallback((index) => {
+    if (typeof index === 'number') {
+      queueRef.current = queueRef.current.filter((_, i) => i !== index);
+    } else {
+      queueRef.current = [];
+    }
+    setQueuedMessages(queueRef.current.map((q) => q.message));
+  }, []);
 
-        const contentType = response.headers.get('content-type') ?? '';
+  /**
+   * Internal — makes the actual API call without touching message history.
+   * `history` is a snapshot captured before the user message was appended.
+   */
+  const _doRequest = useCallback(async (userMessage, sendOptions, history) => {
+    setLoading(true);
+    setStatusText('');
 
-        if (contentType.includes('text/event-stream') && response.body) {
-          const reader = response.body.getReader();
-          const decoder = new TextDecoder();
-          let buffer = '';
-          const collector = createOrchidAiProcessTraceCollector();
+    const controller = new AbortController();
+    abortRef.current = controller;
+    let collector = null;
+    let rafId = null;
 
-          addMessage({
-            role: 'assistant',
-            content: '',
-            isStreaming: true,
-            processTrace: snapshotOrchidAiProcessTraceItems(collector),
-            processInterimLive: '',
+    try {
+      const response = await fetch(endpoint, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          ...getHeadersRef.current?.(),
+        },
+        body: JSON.stringify(buildBodyRef.current(userMessage, history, sendOptions)),
+        signal: controller.signal,
+      });
+
+      const contentType = response.headers.get('content-type') ?? '';
+
+      if (contentType.includes('text/event-stream') && response.body) {
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        collector = createOrchidAiProcessTraceCollector();
+
+        addMessage({
+          role: 'assistant',
+          content: '',
+          isStreaming: true,
+          processTrace: snapshotOrchidAiProcessTraceItems(collector),
+          processInterimLive: '',
+        });
+
+        const patchStreamingAssistant = () => {
+          setMessages((prev) => {
+            const next = [...prev];
+            const last = next[next.length - 1];
+            if (last?.role !== 'assistant' || last?.isStreaming !== true) return prev;
+            next[next.length - 1] = {
+              ...last,
+              content: collector.getLiveMain(),
+              processTrace: augmentLiveProcessTraceSnapshot(
+                snapshotOrchidAiProcessTraceItems(collector),
+                collector.getLiveMain(),
+                collector.getLiveInterim()
+              ),
+              processInterimLive: collector.getLiveInterim(),
+            };
+            messagesRef.current = next;
+            return next;
+          });
+        };
+
+        // Batch delta-driven re-renders to one per animation frame (~60fps max).
+        // Status/query events still update immediately since they're infrequent.
+        const schedulePatch = () => {
+          if (rafId !== null) return;
+          rafId = requestAnimationFrame(() => {
+            rafId = null;
+            patchStreamingAssistant();
           });
+        };
 
-          const patchStreamingAssistant = () => {
-            setMessages((prev) => {
-              const next = [...prev];
-              const last = next[next.length - 1];
-              if (last?.role !== 'assistant' || last?.isStreaming !== true) return prev;
-              next[next.length - 1] = {
-                ...last,
-                content: collector.getLiveMain(),
-                processTrace: augmentLiveProcessTraceSnapshot(
-                  snapshotOrchidAiProcessTraceItems(collector),
-                  collector.getLiveMain(),
-                  collector.getLiveInterim()
-                ),
-                processInterimLive: collector.getLiveInterim(),
-              };
-              messagesRef.current = next;
-              return next;
-            });
-          };
-
-          while (true) {
-            const { done, value } = await reader.read();
-            if (done) break;
-            buffer += decoder.decode(value, { stream: true });
-            const lines = buffer.split('\n');
-            buffer = lines.pop() ?? '';
-
-            for (const line of lines) {
-              if (!line.startsWith('data: ')) continue;
-              try {
-                const event = JSON.parse(line.slice(6));
-                if (event.type === 'status') {
-                  if (showStatus) setStatusText(event.text);
-                  collector.onStatus(event.text, {
-                    isClearStream: orchidAiStatusClearsStreamBuffer(event.text),
-                  });
-                  patchStreamingAssistant();
-                } else if (event.type === 'query') {
-                  collector.onQuery(event.tool, event.input);
-                  patchStreamingAssistant();
-                } else if (event.type === 'delta') {
-                  collector.onDelta(event.text);
-                  patchStreamingAssistant();
-                } else if (event.type === 'done') {
-                  const rawTrace = collector.buildPersistedTrace();
-                  const trace =
-                    rawTrace && orchidAiProcessTraceHasDisplayableContent(rawTrace, '')
-                      ? rawTrace
-                      : undefined;
-                  setMessages((prev) => {
-                    const next = [...prev];
-                    const last = next[next.length - 1];
-                    const finalMsg = {
-                      role: 'assistant',
-                      content: event.response,
-                      truncated: event.truncated === true,
-                      ...(trace ? { processTrace: trace } : {}),
-                      ...(event.queryContext ? { queryContext: event.queryContext } : {}),
-                    };
-                    if (last?.role === 'assistant' && last?.isStreaming) {
-                      next[next.length - 1] = finalMsg;
-                    } else {
-                      next.push(finalMsg);
-                    }
-                    messagesRef.current = next;
-                    return next;
-                  });
-                } else if (event.type === 'error') {
-                  setMessages((prev) => {
-                    const next = [...prev];
-                    const last = next[next.length - 1];
-                    const errMsg = { role: 'assistant', content: event.error || 'Something went wrong.' };
-                    if (last?.role === 'assistant' && last?.isStreaming) {
-                      next[next.length - 1] = errMsg;
-                    } else {
-                      next.push(errMsg);
-                    }
-                    messagesRef.current = next;
-                    return next;
-                  });
-                }
-              } catch {
-                // ignore malformed SSE lines
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buffer += decoder.decode(value, { stream: true });
+          const lines = buffer.split('\n');
+          buffer = lines.pop() ?? '';
+
+          for (const line of lines) {
+            if (!line.startsWith('data: ')) continue;
+            try {
+              const event = JSON.parse(line.slice(6));
+              if (event.type === 'status') {
+                if (showStatus) setStatusText(event.text);
+                collector.onStatus(event.text, {
+                  isClearStream: orchidAiStatusClearsStreamBuffer(event.text),
+                });
+                patchStreamingAssistant();
+              } else if (event.type === 'query') {
+                collector.onQuery(event.tool, event.input);
+                patchStreamingAssistant();
+              } else if (event.type === 'delta') {
+                collector.onDelta(event.text);
+                schedulePatch();
+              } else if (event.type === 'done') {
+                const rawTrace = collector.buildPersistedTrace();
+                const trace =
+                  rawTrace && orchidAiProcessTraceHasDisplayableContent(rawTrace, '')
+                    ? rawTrace
+                    : undefined;
+                setMessages((prev) => {
+                  const next = [...prev];
+                  const last = next[next.length - 1];
+                  const finalMsg = {
+                    role: 'assistant',
+                    content: event.response,
+                    truncated: event.truncated === true,
+                    ...(trace ? { processTrace: trace } : {}),
+                    ...(event.queryContext ? { queryContext: event.queryContext } : {}),
+                  };
+                  if (last?.role === 'assistant' && last?.isStreaming) {
+                    next[next.length - 1] = finalMsg;
+                  } else {
+                    next.push(finalMsg);
+                  }
+                  messagesRef.current = next;
+                  return next;
+                });
+              } else if (event.type === 'error') {
+                setMessages((prev) => {
+                  const next = [...prev];
+                  const last = next[next.length - 1];
+                  const errMsg = { role: 'assistant', content: event.error || 'Something went wrong.' };
+                  if (last?.role === 'assistant' && last?.isStreaming) {
+                    next[next.length - 1] = errMsg;
+                  } else {
+                    next.push(errMsg);
+                  }
+                  messagesRef.current = next;
+                  return next;
+                });
               }
+            } catch {
+              // ignore malformed SSE lines
             }
           }
+        }
+      } else {
+        const data = await response.json();
+        if (response.ok) {
+          addMessage({
+            role: 'assistant',
+            content: data.response,
+            truncated: data.truncated,
+            ...(data.queryContext ? { queryContext: data.queryContext } : {}),
+          });
         } else {
-          const data = await response.json();
-          if (response.ok) {
-            addMessage({
+          addMessage({ role: 'assistant', content: data.error || 'Something went wrong.' });
+        }
+      }
+    } catch (err) {
+      if (err?.name === 'AbortError') {
+        // User-initiated stop — finalise the partial streaming message if one exists.
+        setMessages((prev) => {
+          const next = [...prev];
+          const last = next[next.length - 1];
+          if (last?.role === 'assistant' && last?.isStreaming) {
+            const rawTrace = collector?.buildPersistedTrace();
+            const trace =
+              rawTrace && orchidAiProcessTraceHasDisplayableContent(rawTrace, '')
+                ? rawTrace
+                : undefined;
+            next[next.length - 1] = {
               role: 'assistant',
-              content: data.response,
-              truncated: data.truncated,
-              ...(data.queryContext ? { queryContext: data.queryContext } : {}),
-            });
-          } else {
-            addMessage({ role: 'assistant', content: data.error || 'Something went wrong.' });
+              content: collector?.getLiveMain() ?? '',
+              stopped: true,
+              ...(trace ? { processTrace: trace } : {}),
+            };
+            messagesRef.current = next;
           }
-        }
-      } catch {
-        addMessage({
-          role: 'assistant',
-          content: 'Network error. Please check your connection and try again.',
+          return next;
         });
-      } finally {
-        setLoading(false);
-        setStatusText('');
+        // Fall through to finally — do not add a network-error message.
+        return;
       }
+      setMessages((prev) => {
+        const next = [...prev];
+        const last = next[next.length - 1];
+        const errMsg = { role: 'assistant', content: 'Network error. Please check your connection and try again.' };
+        if (last?.role === 'assistant' && last?.isStreaming) {
+          next[next.length - 1] = errMsg;
+        } else {
+          next.push(errMsg);
+        }
+        messagesRef.current = next;
+        return next;
+      });
+    } finally {
+      if (rafId !== null) { cancelAnimationFrame(rafId); rafId = null; }
+      abortRef.current = null;
+      setLoading(false);
+      setStatusText('');
+
+      // Auto-fire the next queued message if one exists. The queued user message
+      // was NOT added to messages while waiting, so we insert it now before firing.
+      if (queueRef.current.length > 0) {
+        const [next, ...rest] = queueRef.current;
+        queueRef.current = rest;
+        setQueuedMessages(rest.map((q) => q.message));
+        const history = messagesRef.current.slice();
+        const attPreviews = next.sendOptions?.attachments?.map(({ name, mediaType, preview }) => ({ name, mediaType, preview }));
+        const withUser = [...history, { role: 'user', content: next.message, ...(attPreviews?.length ? { attachments: attPreviews } : {}) }];
+        messagesRef.current = withUser;
+        setMessages(withUser);
+        _doRequest(next.message, next.sendOptions, history);
+      }
+    }
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [endpoint, showStatus, addMessage]);
+
+  const sendMessage = useCallback(
+    (userMessage, sendOptions = {}) => {
+      if (abortRef.current) {
+        // A request is in flight — hold this message out of chat history until it fires.
+        queueRef.current = [...queueRef.current, { message: userMessage, sendOptions }];
+        setQueuedMessages(queueRef.current.map((q) => q.message));
+        return;
+      }
+      const history = messagesRef.current.slice();
+      // Store display-only attachment info (preview + name) — raw base64 data stays in sendOptions for buildBody.
+      const attPreviews = sendOptions.attachments?.map(({ name, mediaType, preview }) => ({ name, mediaType, preview }));
+      addMessage({ role: 'user', content: userMessage, ...(attPreviews?.length ? { attachments: attPreviews } : {}) });
+      _doRequest(userMessage, sendOptions, history);
     },
-    [endpoint, showStatus, addMessage]
+    [addMessage, _doRequest]
   );
 
   const clearMessages = useCallback(() => {
@@ -207,5 +298,5 @@ export function useOrchidAiChat({ endpoint, buildBody, getHeaders, showStatus =
     messagesRef.current = [];
   }, []);
 
-  return { messages, loading, statusText, sendMessage, clearMessages };
+  return { messages, loading, statusText, queuedMessages, sendMessage, stopGeneration, clearQueuedMessage, clearMessages };
 }

package/src/index.d.ts

@@ -2,12 +2,36 @@ import * as React from 'react';
 
 // ─── Chat UI ────────────────────────────────────────────────────────────────
 
+/** Full attachment object held in ChatInput state and passed via onSend / sendOptions. */
+export interface ChatAttachment {
+  id: string;
+  name: string;
+  /** MIME type, e.g. "image/jpeg" or "application/pdf". */
+  mediaType: string;
+  /** Base64-encoded file content (no data-URL prefix). Pass this to the server. */
+  data: string;
+  /** Data URL for image preview — images only, null for other files. */
+  preview: string | null;
+  size: number;
+}
+
+/** Slim attachment record stored in ChatMessage (no raw base64 — display only). */
+export interface ChatMessageAttachment {
+  name: string;
+  mediaType: string;
+  preview: string | null;
+}
+
 export interface ChatMessage {
   role: 'user' | 'assistant';
   content: string;
   truncated?: boolean;
   /** When true, UI may show streaming placeholders (orchid-ai ChatWindow). */
   isStreaming?: boolean;
+  /** When true, generation was stopped by the user before the response completed. */
+  stopped?: boolean;
+  /** Attachments shown in the user bubble (display-only — no raw base64 data). */
+  attachments?: ChatMessageAttachment[];
   /** Collapsible interim trace (statuses, text, and query steps). Persisted for Hermes-style chats. */
   processTrace?: {
     items: Array<OrchidAiProcessTraceItem>;
@@ -27,6 +51,12 @@ export interface ChatWindowProps {
   messages: ChatMessage[];
   loading?: boolean;
   statusText?: string;
+  /** Messages currently waiting in the queue (held out of chat history until each fires). */
+  queuedMessages?: string[];
+  /** Called with the index of the queued item to remove, or omit index to clear all. */
+  onCancelQueue?: (index: number) => void;
+  /** Called when the user clicks "Send now" on the first queued item (stops current + auto-fires). */
+  onStop?: () => void;
   onSuggestionClick?: (text: string) => void;
   aiEnabled?: boolean;
   organisationName?: string;
@@ -43,7 +73,11 @@ export interface ChatWindowProps {
 }
 
 export interface ChatInputProps {
-  onSend: (text: string) => void;
+  onSend: (text: string, attachments?: ChatAttachment[]) => void;
+  /** Called when the user clicks the Stop button during generation. */
+  onStop?: () => void;
+  /** When true, shows the Stop button instead of Send. Does not disable the textarea. */
+  loading?: boolean;
   disabled?: boolean;
   disabledReason?: string;
   onDisabledClick?: () => void;
@@ -63,6 +97,7 @@ export interface MessageProps {
   showProcessTracePanel?: boolean;
   queryContext?: Record<string, unknown>;
   showQuerySummary?: boolean;
+  attachments?: ChatMessageAttachment[];
 }
 
 export const ChatWindow: React.FC<ChatWindowProps>;
@@ -75,6 +110,8 @@ export const Message: React.FC<MessageProps>;
 export interface OrchidAiChatSendOptions {
   allowWebResearch?: boolean;
   urlsToCheck?: string[];
+  /** Files/images to include in this message. buildBody receives these via sendOptions. */
+  attachments?: ChatAttachment[];
 }
 
 export interface OrchidAiChatOptions {
@@ -105,7 +142,13 @@ export interface OrchidAiChatState {
   loading: boolean;
   /** Live status text emitted by the server (e.g. "Thinking", "Compiling response") */
   statusText: string;
-  sendMessage: (userMessage: string, sendOptions?: OrchidAiChatSendOptions) => Promise<void>;
+  /** Messages waiting in the send queue (held out of chat history until each fires). */
+  queuedMessages: string[];
+  sendMessage: (userMessage: string, sendOptions?: OrchidAiChatSendOptions) => void;
+  /** Abort the current in-flight request. The next queued message auto-fires after abort. */
+  stopGeneration: () => void;
+  /** Remove a specific queued item by index, or clear the entire queue when called with no argument. */
+  clearQueuedMessage: (index?: number) => void;
   clearMessages: () => void;
 }