@optilogic/chat 1.0.0-beta.1 → 1.0.0-beta.11

package/src/components/agent-response/AgentResponse.tsx

@@ -6,11 +6,14 @@
  */
 
 import * as React from "react";
-import { useState, useMemo, useCallback } from "react";
+import { useState, useRef, useMemo, useCallback } from "react";
 import { cn } from "@optilogic/core";
-import { MetadataRow, ThinkingSection, ActionBar } from "./components";
+import { MetadataRow, ThinkingSection, ActionBar, HITLSection } from "./components";
 import { useThinkingTimer } from "./hooks";
 import type { AgentResponseState, FeedbackValue } from "./types";
+import type { HITLInteraction } from "../hitl-interactions";
+import { AgentTimeline, createTimelineUIState } from "../agent-timeline";
+import type { TimelineUIState } from "../agent-timeline";
 
 export interface AgentResponseProps extends React.HTMLAttributes<HTMLDivElement> {
   /** The response state to render */
@@ -37,6 +40,35 @@ export interface AgentResponseProps extends React.HTMLAttributes<HTMLDivElement>
   /** Action bar visibility mode */
   actionsVisible?: boolean | "hover";
 
+  /**
+   * Optional HITL (Human-in-the-Loop) interactions to display as a
+   * collapsible section within the response. When provided, a "Clarifying
+   * Questions" section appears between the thinking/metadata area and
+   * the response content.
+   */
+  hitlInteractions?: HITLInteraction[];
+
+  /** Whether the HITL section starts expanded (default: false) */
+  defaultHITLExpanded?: boolean;
+
+  /**
+   * Optional content to display in the MetadataRow's middle area,
+   * between the thinking toggle (left) and activity indicators (right).
+   * Typically used for ephemeral status messages during processing.
+   * The parent is responsible for setting and clearing this content.
+   *
+   * @example
+   * <AgentResponse
+   *   state={state}
+   *   statusContent={
+   *     state.status !== 'complete'
+   *       ? <TruncatedMessage message="Analyzing data..." />
+   *       : undefined
+   *   }
+   * />
+   */
+  statusContent?: React.ReactNode;
+
   /**
    * Custom markdown renderer for the response content.
    * If not provided, the response will be rendered as plain text.
@@ -48,6 +80,18 @@ export interface AgentResponseProps extends React.HTMLAttributes<HTMLDivElement>
    * />
    */
   renderMarkdown?: (content: string) => React.ReactNode;
+
+  /**
+   * Custom markdown renderer for the thinking content.
+   * If not provided, the thinking will be rendered as plain preformatted text.
+   *
+   * @example
+   * <AgentResponse
+   *   state={state}
+   *   renderThinkingMarkdown={(content) => <MyMarkdownRenderer content={content} />}
+   * />
+   */
+  renderThinkingMarkdown?: (content: string) => React.ReactNode;
 }
 
 /**
@@ -95,12 +139,19 @@ const AgentResponse = React.forwardRef<HTMLDivElement, AgentResponseProps>(
       thinkingExpanded: controlledThinkingExpanded,
       onThinkingExpandedChange,
       actionsVisible = "hover",
+      hitlInteractions,
+      defaultHITLExpanded = false,
+      statusContent,
       renderMarkdown,
+      renderThinkingMarkdown,
       className,
       ...props
     },
     ref
   ) => {
+    // Ref-backed timeline UI state (survives remounts during streaming)
+    const timelineUIStateRef = useRef<TimelineUIState>(createTimelineUIState());
+
     // Uncontrolled thinking expanded state
     const [uncontrolledExpanded, setUncontrolledExpanded] = useState(defaultThinkingExpanded);
 
@@ -136,20 +187,31 @@ const AgentResponse = React.forwardRef<HTMLDivElement, AgentResponseProps>(
       return (state.responseCompleteTime - state.firstMessageTime) / 1000;
     }, [state.firstMessageTime, state.responseCompleteTime]);
 
+    // Check if we have any thinking content (plain text, structured, or timeline)
+    const hasTimelineEntries = !!(state.timelineEntries && state.timelineEntries.length > 0);
+    const hasThinkingContent =
+      !!state.thinking || (state.thinkingSteps && state.thinkingSteps.length > 0) || hasTimelineEntries || false;
+
+    const hasHITLInteractions =
+      hitlInteractions && hitlInteractions.length > 0;
+
     // Derived state: has any content been received?
     const hasAnyContent =
-      state.thinking ||
+      hasThinkingContent ||
       state.toolCalls.length > 0 ||
       state.knowledge.length > 0 ||
       state.memory.length > 0 ||
+      state.statusUpdates.length > 0 ||
+      hasHITLInteractions ||
       state.response;
 
     // Derived state: should show metadata row?
     const showMetadataRow =
-      state.thinking ||
+      hasThinkingContent ||
       state.toolCalls.length > 0 ||
       state.knowledge.length > 0 ||
       state.memory.length > 0 ||
+      state.statusUpdates.length > 0 ||
       state.status === "processing";
 
     // Determine action bar visibility
@@ -177,24 +239,51 @@ const AgentResponse = React.forwardRef<HTMLDivElement, AgentResponseProps>(
           {showMetadataRow && (
             <>
               <MetadataRow
-                hasThinking={!!state.thinking}
+                hasThinking={hasThinkingContent}
                 isExpanded={thinkingExpanded}
                 onToggle={toggleThinking}
                 toolCalls={state.toolCalls}
                 knowledge={state.knowledge}
                 memory={state.memory}
+                statusUpdates={state.statusUpdates}
+                statusContent={statusContent}
                 status={state.status}
                 elapsedTime={elapsedTime}
               />
 
-              {/* Thinking Content - collapsible with max-height */}
-              <ThinkingSection
-                content={state.thinking}
-                isExpanded={thinkingExpanded}
-              />
+              {/* Thinking Content - AgentTimeline when timeline entries exist, ThinkingSection otherwise */}
+              {hasTimelineEntries ? (
+                thinkingExpanded && (
+                  <div className="px-3 pb-3 border-t border-border mt-2">
+                    <AgentTimeline
+                      entries={state.timelineEntries!}
+                      renderMarkdown={renderThinkingMarkdown}
+                      uiState={timelineUIStateRef.current}
+                    />
+                  </div>
+                )
+              ) : (
+                <ThinkingSection
+                  content={
+                    state.thinkingSteps && state.thinkingSteps.length > 0
+                      ? state.thinkingSteps
+                      : state.thinking
+                  }
+                  isExpanded={thinkingExpanded}
+                  renderMarkdown={renderThinkingMarkdown}
+                />
+              )}
             </>
           )}
 
+          {/* HITL Interactions - collapsible section */}
+          {hasHITLInteractions && (
+            <HITLSection
+              interactions={hitlInteractions}
+              defaultExpanded={defaultHITLExpanded}
+            />
+          )}
+
           {/* Response Section */}
           {state.response && (
             <div

package/src/components/agent-response/components/ActivityIndicators.tsx

@@ -5,9 +5,9 @@
  */
 
 import * as React from "react";
-import { Wrench, Book, HardDrive } from "lucide-react";
+import { Wrench, Book, HardDrive, Activity } from "lucide-react";
 import { cn, Popover, PopoverTrigger, PopoverContent } from "@optilogic/core";
-import type { ToolCall, KnowledgeItem, MemoryItem } from "../types";
+import type { ToolCall, KnowledgeItem, MemoryItem, StatusItem } from "../types";
 
 export interface ActivityIndicatorsProps extends React.HTMLAttributes<HTMLDivElement> {
   /** Tool calls to display */
@@ -16,6 +16,8 @@ export interface ActivityIndicatorsProps extends React.HTMLAttributes<HTMLDivEle
   knowledge: KnowledgeItem[];
   /** Memory items to display */
   memory: MemoryItem[];
+  /** Status updates to display */
+  statusUpdates?: StatusItem[];
 }
 
 /**
@@ -32,14 +34,44 @@ export interface ActivityIndicatorsProps extends React.HTMLAttributes<HTMLDivEle
  * />
  */
 const ActivityIndicators = React.forwardRef<HTMLDivElement, ActivityIndicatorsProps>(
-  ({ toolCalls, knowledge, memory, className, ...props }, ref) => {
+  ({ toolCalls, knowledge, memory, statusUpdates = [], className, ...props }, ref) => {
     const hasAnyActivity =
-      toolCalls.length > 0 || knowledge.length > 0 || memory.length > 0;
+      toolCalls.length > 0 || knowledge.length > 0 || memory.length > 0 || statusUpdates.length > 0;
 
     if (!hasAnyActivity) return null;
 
     return (
       <div ref={ref} className={cn("flex items-center gap-2", className)} {...props}>
+        {/* Status Updates */}
+        {statusUpdates.length > 0 && (
+          <Popover>
+            <PopoverTrigger asChild>
+              <button
+                className="flex items-center gap-1 text-muted-foreground hover:text-foreground transition-colors"
+                onClick={(e) => e.stopPropagation()}
+              >
+                <Activity className="w-3.5 h-3.5" />
+                <span className="text-xs">{statusUpdates.length}</span>
+              </button>
+            </PopoverTrigger>
+            <PopoverContent className="w-80">
+              <div className="space-y-2">
+                <h4 className="font-medium text-sm">Status Updates</h4>
+                <div className="space-y-2 max-h-60 overflow-auto">
+                  {statusUpdates.map((item) => (
+                    <div key={item.id} className="p-2 bg-muted rounded text-xs">
+                      {item.agent && (
+                        <div className="font-medium text-muted-foreground">{item.agent}</div>
+                      )}
+                      <div className={item.agent ? "mt-1" : ""}>{item.message}</div>
+                    </div>
+                  ))}
+                </div>
+              </div>
+            </PopoverContent>
+          </Popover>
+        )}
+
         {/* Tool Calls */}
         {toolCalls.length > 0 && (
           <Popover>

package/src/components/agent-response/components/HITLSection.tsx

@@ -0,0 +1,95 @@
+/**
+ * HITL Section Component
+ *
+ * Collapsible section for displaying completed HITL (Human-in-the-Loop)
+ * interactions within an AgentResponse. Follows the same pattern as
+ * ThinkingSection for consistent UX.
+ */
+
+import * as React from "react";
+import { useState, useCallback } from "react";
+import { ChevronDown, ChevronRight, MessageCircleQuestion } from "lucide-react";
+import { cn } from "@optilogic/core";
+import { HITLInteractionRecord } from "../../hitl-interactions";
+import type { HITLInteraction } from "../../hitl-interactions";
+
+export interface HITLSectionProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  /** The HITL interactions to display */
+  interactions: HITLInteraction[];
+  /** Whether the section starts expanded (uncontrolled) */
+  defaultExpanded?: boolean;
+  /** Whether the section is expanded (controlled) */
+  isExpanded?: boolean;
+  /** Callback when expansion state changes (controlled) */
+  onExpandedChange?: (expanded: boolean) => void;
+}
+
+const HITLSection = React.forwardRef<HTMLDivElement, HITLSectionProps>(
+  (
+    {
+      interactions,
+      defaultExpanded = false,
+      isExpanded: controlledExpanded,
+      onExpandedChange,
+      className,
+      ...props
+    },
+    ref
+  ) => {
+    const [uncontrolledExpanded, setUncontrolledExpanded] =
+      useState(defaultExpanded);
+
+    const isControlled = controlledExpanded !== undefined;
+    const isExpanded = isControlled ? controlledExpanded : uncontrolledExpanded;
+
+    const toggleExpanded = useCallback(() => {
+      const newValue = !isExpanded;
+      if (isControlled) {
+        onExpandedChange?.(newValue);
+      } else {
+        setUncontrolledExpanded(newValue);
+      }
+    }, [isExpanded, isControlled, onExpandedChange]);
+
+    if (!interactions || interactions.length === 0) {
+      return null;
+    }
+
+    return (
+      <div
+        ref={ref}
+        className={cn("border-t border-border", className)}
+        {...props}
+      >
+        {/* Collapsible header */}
+        <button
+          onClick={toggleExpanded}
+          className="w-full flex items-center gap-2 py-2 px-3 hover:bg-muted/50 transition-colors text-left"
+        >
+          {isExpanded ? (
+            <ChevronDown className="w-3.5 h-3.5 text-muted-foreground flex-shrink-0" />
+          ) : (
+            <ChevronRight className="w-3.5 h-3.5 text-muted-foreground flex-shrink-0" />
+          )}
+          <MessageCircleQuestion className="w-3.5 h-3.5 text-muted-foreground flex-shrink-0" />
+          <span className="text-xs font-medium text-foreground/80">
+            Clarifying Questions ({interactions.length})
+          </span>
+        </button>
+
+        {/* Expanded content */}
+        {isExpanded && (
+          <div className="px-3 pb-3 space-y-2">
+            {interactions.map((interaction, i) => (
+              <HITLInteractionRecord key={i} interaction={interaction} />
+            ))}
+          </div>
+        )}
+      </div>
+    );
+  }
+);
+HITLSection.displayName = "HITLSection";
+
+export { HITLSection };

package/src/components/agent-response/components/MetadataRow.tsx

@@ -9,7 +9,7 @@ import { ChevronDown, ChevronUp } from "lucide-react";
 import { cn, LoadingSpinner } from "@optilogic/core";
 import { ActivityIndicators } from "./ActivityIndicators";
 import { formatTime } from "../utils";
-import type { AgentResponseStatus, ToolCall, KnowledgeItem, MemoryItem } from "../types";
+import type { AgentResponseStatus, ToolCall, KnowledgeItem, MemoryItem, StatusItem } from "../types";
 
 export interface MetadataRowProps extends React.HTMLAttributes<HTMLDivElement> {
   /** Whether there is thinking content */
@@ -24,6 +24,10 @@ export interface MetadataRowProps extends React.HTMLAttributes<HTMLDivElement> {
   knowledge: KnowledgeItem[];
   /** Memory items to display */
   memory: MemoryItem[];
+  /** Status updates to display */
+  statusUpdates?: StatusItem[];
+  /** Optional content to display in the middle area between left content and activity indicators */
+  statusContent?: React.ReactNode;
   /** Current response status */
   status: AgentResponseStatus;
   /** Elapsed time in seconds */
@@ -57,6 +61,8 @@ const MetadataRow = React.forwardRef<HTMLDivElement, MetadataRowProps>(
       toolCalls,
       knowledge,
       memory,
+      statusUpdates = [],
+      statusContent,
       status,
       elapsedTime,
       className,
@@ -67,7 +73,7 @@ const MetadataRow = React.forwardRef<HTMLDivElement, MetadataRowProps>(
     const isProcessing = status === "processing";
     const isComplete = status === "complete";
     const hasActivity =
-      toolCalls.length > 0 || knowledge.length > 0 || memory.length > 0;
+      toolCalls.length > 0 || knowledge.length > 0 || memory.length > 0 || statusUpdates.length > 0;
 
     // Determine what to show on the left side
     const renderLeftContent = () => {
@@ -105,8 +111,8 @@ const MetadataRow = React.forwardRef<HTMLDivElement, MetadataRowProps>(
 
     const leftContent = renderLeftContent();
 
-    // If nothing to show (no thinking, not processing, no activity), hide the row
-    if (!leftContent && !hasActivity) {
+    // If nothing to show (no thinking, not processing, no activity, no status content), hide the row
+    if (!leftContent && !hasActivity && !statusContent) {
       return null;
     }
 
@@ -122,19 +128,28 @@ const MetadataRow = React.forwardRef<HTMLDivElement, MetadataRowProps>(
         {hasThinking ? (
           <button
             onClick={onToggle}
-            className="flex items-center gap-1.5 hover:bg-muted/50 -ml-1.5 pl-1.5 pr-2 py-0.5 rounded transition-colors"
+            className="flex items-center gap-1.5 hover:bg-muted/50 -ml-1.5 pl-1.5 pr-2 py-0.5 rounded transition-colors shrink-0"
           >
             {leftContent}
           </button>
         ) : (
-          <div className="flex items-center gap-1.5">
+          <div className="flex items-center gap-1.5 shrink-0">
             {leftContent}
           </div>
         )}
+
+        {/* Middle content - status content slot */}
+        {statusContent && (
+          <div className="flex-1 min-w-0 mx-2">
+            {statusContent}
+          </div>
+        )}
+
         <ActivityIndicators
           toolCalls={toolCalls}
           knowledge={knowledge}
           memory={memory}
+          statusUpdates={statusUpdates}
         />
       </div>
     );

package/src/components/agent-response/components/ThinkingSection.tsx

@@ -1,43 +1,135 @@
 /**
  * Thinking Section Component
  *
- * Collapsible section for displaying agent thinking/reasoning content
+ * Collapsible section for displaying agent thinking/reasoning content.
+ * Supports both plain text and structured collapsible sub-sections.
  */
 
 import * as React from "react";
+import { useState, useCallback } from "react";
+import { ChevronDown, ChevronRight } from "lucide-react";
 import { cn } from "@optilogic/core";
+import type { ThinkingStep } from "../types";
 
-export interface ThinkingSectionProps extends React.HTMLAttributes<HTMLDivElement> {
-  /** The thinking content to display */
-  content: string;
+export interface ThinkingSectionProps
+  extends Omit<React.HTMLAttributes<HTMLDivElement>, "content"> {
+  /** The thinking content to display (string or structured steps) */
+  content: string | ThinkingStep[];
   /** Whether the section is expanded */
   isExpanded: boolean;
+  /**
+   * Custom markdown renderer for the thinking content.
+   * If not provided, the content will be rendered as plain preformatted text.
+   */
+  renderMarkdown?: (content: string) => React.ReactNode;
 }
 
+/**
+ * Internal component for rendering a collapsible thinking step
+ */
+interface ThinkingStepItemProps {
+  step: ThinkingStep;
+  renderMarkdown?: (content: string) => React.ReactNode;
+}
+
+const ThinkingStepItem: React.FC<ThinkingStepItemProps> = ({ step, renderMarkdown }) => {
+  const [isCollapsed, setIsCollapsed] = useState(step.isCollapsed ?? false);
+
+  const toggleCollapse = useCallback(() => {
+    setIsCollapsed((prev) => !prev);
+  }, []);
+
+  const indentPadding = step.depth * 16;
+
+  return (
+    <div className="border-b border-border/50 last:border-b-0">
+      <button
+        onClick={toggleCollapse}
+        className="w-full flex items-center gap-1.5 py-1.5 px-2 hover:bg-muted/50 transition-colors text-left"
+        style={{ paddingLeft: `${indentPadding + 8}px` }}
+      >
+        {isCollapsed ? (
+          <ChevronRight className="w-3 h-3 text-muted-foreground flex-shrink-0" />
+        ) : (
+          <ChevronDown className="w-3 h-3 text-muted-foreground flex-shrink-0" />
+        )}
+        <span className="text-xs font-medium text-foreground/80">{step.label}</span>
+      </button>
+
+      {!isCollapsed && (
+        <div
+          className="pb-2 px-2"
+          style={{ paddingLeft: `${indentPadding + 28}px` }}
+        >
+          {renderMarkdown ? (
+            <div className="text-xs text-muted-foreground">
+              {renderMarkdown(step.content)}
+            </div>
+          ) : (
+            <pre className="text-xs text-muted-foreground whitespace-pre-wrap font-mono">
+              {step.content}
+            </pre>
+          )}
+        </div>
+      )}
+    </div>
+  );
+};
+
 /**
  * ThinkingSection Component
  *
  * Displays the agent's thinking/reasoning content in a collapsible panel.
+ * Supports both plain text content and structured collapsible sub-sections.
  *
  * @example
+ * // Plain text content
  * <ThinkingSection content={state.thinking} isExpanded={isExpanded} />
+ *
+ * @example
+ * // Structured content with sub-sections
+ * <ThinkingSection
+ *   content={[
+ *     { id: "1", label: "Analysis", content: "...", depth: 0 },
+ *     { id: "2", label: "Sub-analysis", content: "...", depth: 1 },
+ *   ]}
+ *   isExpanded={isExpanded}
+ * />
  */
 const ThinkingSection = React.forwardRef<HTMLDivElement, ThinkingSectionProps>(
-  ({ content, isExpanded, className, ...props }, ref) => {
-    if (!isExpanded || !content) {
+  ({ content, isExpanded, renderMarkdown, className, ...props }, ref) => {
+    if (!isExpanded || !content || (Array.isArray(content) && content.length === 0)) {
       return null;
     }
 
+    const isStructured = Array.isArray(content);
+
     return (
       <div
         ref={ref}
         className={cn("px-3 pb-3 border-t border-border", className)}
         {...props}
       >
-        <div className="mt-2 max-h-[200px] overflow-y-auto">
-          <pre className="text-xs text-muted-foreground whitespace-pre-wrap font-mono">
-            {content}
-          </pre>
+        <div className="mt-2 max-h-[200px] overflow-y-auto scrollbar-thin">
+          {isStructured ? (
+            <div className="space-y-0">
+              {content.map((step) => (
+                <ThinkingStepItem
+                  key={step.id}
+                  step={step}
+                  renderMarkdown={renderMarkdown}
+                />
+              ))}
+            </div>
+          ) : renderMarkdown ? (
+            <div className="text-xs text-muted-foreground">
+              {renderMarkdown(content)}
+            </div>
+          ) : (
+            <pre className="text-xs text-muted-foreground whitespace-pre-wrap font-mono">
+              {content}
+            </pre>
+          )}
         </div>
       </div>
     );

package/src/components/agent-response/components/TruncatedMessage.tsx

@@ -0,0 +1,52 @@
+/**
+ * Truncated Message Component
+ *
+ * Renders a single-line text message with CSS-based truncation (text-overflow: ellipsis).
+ * Designed as a standalone utility that can be used anywhere, including as
+ * the statusContent slot in MetadataRow.
+ */
+
+import * as React from "react";
+import { cn } from "@optilogic/core";
+
+export interface TruncatedMessageProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** The message string to display (truncated with ellipsis if it overflows) */
+  message: string;
+}
+
+/**
+ * TruncatedMessage Component
+ *
+ * Displays a single-line text message that truncates with an ellipsis when
+ * it overflows its container. Uses CSS text-overflow for zero-JS truncation.
+ *
+ * @example
+ * <TruncatedMessage message="Searching the knowledge base for relevant documents..." />
+ *
+ * @example
+ * // Inside MetadataRow's statusContent slot
+ * <AgentResponse
+ *   state={state}
+ *   statusContent={<TruncatedMessage message="Running analysis..." />}
+ * />
+ */
+const TruncatedMessage = React.forwardRef<HTMLDivElement, TruncatedMessageProps>(
+  ({ message, className, ...props }, ref) => {
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          "text-xs text-muted-foreground truncate min-w-0",
+          className
+        )}
+        title={message}
+        {...props}
+      >
+        {message}
+      </div>
+    );
+  }
+);
+TruncatedMessage.displayName = "TruncatedMessage";
+
+export { TruncatedMessage };

package/src/components/agent-response/components/index.ts

@@ -13,3 +13,9 @@ export type { ThinkingSectionProps } from "./ThinkingSection";
 
 export { ActionBar } from "./ActionBar";
 export type { ActionBarProps } from "./ActionBar";
+
+export { HITLSection } from "./HITLSection";
+export type { HITLSectionProps } from "./HITLSection";
+
+export { TruncatedMessage } from "./TruncatedMessage";
+export type { TruncatedMessageProps } from "./TruncatedMessage";