@optilogic/chat 1.0.0-beta.8 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optilogic/chat",
-  "version": "1.0.0-beta.8",
+  "version": "1.0.0",
   "description": "Chat UI components for Optilogic - AgentResponse and related components for LLM interactions",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -24,8 +24,8 @@
     "README.md"
   ],
   "dependencies": {
-    "@optilogic/core": "1.0.0-beta.8",
-    "@optilogic/editor": "1.0.0-beta.8"
+    "@optilogic/core": "1.0.0",
+    "@optilogic/editor": "1.0.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",

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.
@@ -60,6 +92,12 @@ export interface AgentResponseProps extends React.HTMLAttributes<HTMLDivElement>
    * />
    */
   renderThinkingMarkdown?: (content: string) => React.ReactNode;
+
+  /**
+   * Maximum height of the AgentTimeline scrollable container.
+   * Defaults to "300px". Set to "none" to disable the constraint.
+   */
+  timelineMaxHeight?: string;
 }
 
 /**
@@ -107,13 +145,20 @@ const AgentResponse = React.forwardRef<HTMLDivElement, AgentResponseProps>(
       thinkingExpanded: controlledThinkingExpanded,
       onThinkingExpandedChange,
       actionsVisible = "hover",
+      hitlInteractions,
+      defaultHITLExpanded = false,
+      statusContent,
       renderMarkdown,
       renderThinkingMarkdown,
+      timelineMaxHeight,
       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);
 
@@ -149,9 +194,13 @@ 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 or structured)
+    // 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) || false;
+      !!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 =
@@ -160,6 +209,7 @@ const AgentResponse = React.forwardRef<HTMLDivElement, AgentResponseProps>(
       state.knowledge.length > 0 ||
       state.memory.length > 0 ||
       state.statusUpdates.length > 0 ||
+      hasHITLInteractions ||
       state.response;
 
     // Derived state: should show metadata row?
@@ -203,23 +253,45 @@ const AgentResponse = React.forwardRef<HTMLDivElement, AgentResponseProps>(
                 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.thinkingSteps && state.thinkingSteps.length > 0
-                    ? state.thinkingSteps
-                    : state.thinking
-                }
-                isExpanded={thinkingExpanded}
-                renderMarkdown={renderThinkingMarkdown}
-              />
+              {/* Thinking Content - AgentTimeline when timeline entries exist, ThinkingSection otherwise */}
+              {hasTimelineEntries ? (
+                thinkingExpanded && (
+                  <div className="pb-3 border-t border-border">
+                    <AgentTimeline
+                      entries={state.timelineEntries!}
+                      renderMarkdown={renderThinkingMarkdown}
+                      uiState={timelineUIStateRef.current}
+                      maxHeight={timelineMaxHeight}
+                    />
+                  </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/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

@@ -26,6 +26,8 @@ export interface MetadataRowProps extends React.HTMLAttributes<HTMLDivElement> {
   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 */
@@ -60,6 +62,7 @@ const MetadataRow = React.forwardRef<HTMLDivElement, MetadataRowProps>(
       knowledge,
       memory,
       statusUpdates = [],
+      statusContent,
       status,
       elapsedTime,
       className,
@@ -108,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;
     }
 
@@ -125,15 +128,23 @@ 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}

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";

package/src/components/agent-response/hooks/useAgentResponseAccumulator.ts

@@ -15,7 +15,9 @@ import {
   type MemoryItem,
   type StatusItem,
   type ThinkingStep,
+  type PotentialResponse,
 } from "../types";
+import { buildTimelineEntries } from "../../agent-timeline/utils";
 
 export interface UseAgentResponseAccumulatorOptions {
   /** WebSocket topic to filter messages (optional, for convenience) */
@@ -94,33 +96,50 @@ export function useAgentResponseAccumulator(
                 id: payload.thinkingStep.id || `step-${Date.now()}`,
                 label: payload.thinkingStep.label,
                 content: payload.thinkingStep.content,
-                depth: payload.thinkingStep.depth ?? 0,
+                depth: payload.thinkingStep.depth ?? payload.depth ?? 0,
                 isCollapsed: payload.thinkingStep.isCollapsed,
+                timestamp: Date.now(),
+                agentName: payload.agentName,
+                parentAgent: payload.parentAgent,
               };
               const thinkingStartTime = prev.thinkingStartTime ?? Date.now();
-              return {
+              const next = {
                 ...prev,
                 status: newStatus,
                 thinkingSteps: [...(prev.thinkingSteps || []), newStep],
                 thinkingStartTime,
                 firstMessageTime,
               };
+              return { ...next, timelineEntries: buildTimelineEntries(next) };
             }
 
-            // Plain text thinking (existing behavior)
+            // Plain text thinking — concatenate for backward compat AND
+            // push a ThinkingStep so the timeline gets individual entries.
             const newThinking = payload.message || payload.content || "";
             // Add line break between thinking messages
             const separator = prev.thinking && newThinking ? "\n\n" : "";
             // Set thinkingStartTime on first thinking message
             const thinkingStartTime =
               prev.thinkingStartTime ?? (newThinking ? Date.now() : null);
-            return {
+            const prevSteps = prev.thinkingSteps || [];
+            const plainStep: ThinkingStep = {
+              id: `step-${prevSteps.length}`,
+              label: newThinking,
+              content: newThinking,
+              depth: payload.depth ?? 0,
+              timestamp: Date.now(),
+              agentName: payload.agentName,
+              parentAgent: payload.parentAgent,
+            };
+            const next = {
               ...prev,
               status: newStatus,
               thinking: prev.thinking + separator + newThinking,
+              thinkingSteps: [...prevSteps, plainStep],
               thinkingStartTime,
               firstMessageTime,
             };
+            return { ...next, timelineEntries: buildTimelineEntries(next) };
           }
 
           case "tool_call": {
@@ -132,13 +151,17 @@ export function useAgentResponseAccumulator(
                 name: toolName,
                 arguments: payload.tool?.arguments,
                 timestamp: Date.now(),
+                agentName: payload.agentName,
+                parentAgent: payload.parentAgent,
+                depth: payload.depth,
               };
-              return {
+              const next = {
                 ...prev,
                 status: newStatus,
                 toolCalls: [...prev.toolCalls, newToolCall],
                 firstMessageTime,
               };
+              return { ...next, timelineEntries: buildTimelineEntries(next) };
             }
             return { ...prev, status: newStatus, firstMessageTime };
           }
@@ -152,13 +175,17 @@ export function useAgentResponseAccumulator(
                 source: payload.knowledge?.source || "unknown",
                 content: knowledgeContent,
                 timestamp: Date.now(),
+                agentName: payload.agentName,
+                parentAgent: payload.parentAgent,
+                depth: payload.depth,
               };
-              return {
+              const next = {
                 ...prev,
                 status: newStatus,
                 knowledge: [...prev.knowledge, newKnowledge],
                 firstMessageTime,
               };
+              return { ...next, timelineEntries: buildTimelineEntries(next) };
             }
             return { ...prev, status: newStatus, firstMessageTime };
           }
@@ -172,13 +199,17 @@ export function useAgentResponseAccumulator(
                 type: payload.memory?.type || "unknown",
                 content: memoryContent,
                 timestamp: Date.now(),
+                agentName: payload.agentName,
+                parentAgent: payload.parentAgent,
+                depth: payload.depth,
               };
-              return {
+              const next = {
                 ...prev,
                 status: newStatus,
                 memory: [...prev.memory, newMemory],
                 firstMessageTime,
               };
+              return { ...next, timelineEntries: buildTimelineEntries(next) };
             }
             return { ...prev, status: newStatus, firstMessageTime };
           }
@@ -200,13 +231,39 @@ export function useAgentResponseAccumulator(
                 message: statusMessage,
                 agent: payload.statusUpdate?.agent,
                 timestamp: Date.now(),
+                agentName: payload.agentName,
+                parentAgent: payload.parentAgent,
+                depth: payload.depth,
               };
-              return {
+              const next = {
                 ...prev,
                 status: newStatus,
                 statusUpdates: [...prev.statusUpdates, newStatusItem],
                 firstMessageTime,
               };
+              return { ...next, timelineEntries: buildTimelineEntries(next) };
+            }
+            return { ...prev, status: newStatus, firstMessageTime };
+          }
+
+          case "potential_response": {
+            const respContent = payload.message || payload.content || "";
+            if (respContent) {
+              const newResp: PotentialResponse = {
+                id: `resp-${Date.now()}`,
+                content: respContent,
+                timestamp: Date.now(),
+                agentName: payload.agentName,
+                parentAgent: payload.parentAgent,
+                depth: payload.depth,
+              };
+              const next = {
+                ...prev,
+                status: newStatus,
+                potentialResponses: [...(prev.potentialResponses || []), newResp],
+                firstMessageTime,
+              };
+              return { ...next, timelineEntries: buildTimelineEntries(next) };
             }
             return { ...prev, status: newStatus, firstMessageTime };
           }

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

@@ -15,10 +15,14 @@ export {
   MetadataRow,
   ThinkingSection,
   ActionBar,
+  HITLSection,
+  TruncatedMessage,
   type ActivityIndicatorsProps,
   type MetadataRowProps,
   type ThinkingSectionProps,
   type ActionBarProps,
+  type HITLSectionProps,
+  type TruncatedMessageProps,
 } from "./components";
 
 // Hooks
@@ -41,6 +45,7 @@ export type {
   StatusItem,
   ThinkingStep,
   ThinkingContent,
+  PotentialResponse,
   AgentMessage,
   GenericWebSocketMessage,
 } from "./types";
@@ -49,3 +54,19 @@ export { initialAgentResponseState } from "./types";
 
 // Utilities
 export { formatTime, formatTotalTime } from "./utils";
+
+// Agent Timeline (replaces ThinkingSection for rich execution visibility)
+export {
+  AgentTimeline,
+  createTimelineUIState,
+  buildTimelineEntries,
+  groupIntoAgentRuns,
+  deduplicateEntries,
+} from "../agent-timeline";
+export type {
+  TimelineUIState,
+  TimelineEntry,
+  TimelineEntryType,
+  AgentRun,
+  DisplayEntry,
+} from "../agent-timeline";