@optilogic/chat 1.0.0-beta.9 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optilogic/chat",
-  "version": "1.0.0-beta.9",
+  "version": "1.1.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.9",
-    "@optilogic/editor": "1.0.0-beta.9"
+    "@optilogic/core": "1.1.0",
+    "@optilogic/editor": "1.1.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",

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

@@ -6,12 +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, 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 */
@@ -49,6 +51,24 @@ export interface AgentResponseProps extends React.HTMLAttributes<HTMLDivElement>
   /** 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.
@@ -72,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;
 }
 
 /**
@@ -121,13 +147,18 @@ const AgentResponse = React.forwardRef<HTMLDivElement, AgentResponseProps>(
       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);
 
@@ -163,9 +194,10 @@ 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;
@@ -221,20 +253,34 @@ 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}
+                />
+              )}
             </>
           )}
 

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

@@ -16,3 +16,6 @@ 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

@@ -16,11 +16,13 @@ export {
   ThinkingSection,
   ActionBar,
   HITLSection,
+  TruncatedMessage,
   type ActivityIndicatorsProps,
   type MetadataRowProps,
   type ThinkingSectionProps,
   type ActionBarProps,
   type HITLSectionProps,
+  type TruncatedMessageProps,
 } from "./components";
 
 // Hooks
@@ -43,6 +45,7 @@ export type {
   StatusItem,
   ThinkingStep,
   ThinkingContent,
+  PotentialResponse,
   AgentMessage,
   GenericWebSocketMessage,
 } from "./types";
@@ -51,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";

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

@@ -4,6 +4,8 @@
  * Type definitions for the library-ready agent response component
  */
 
+import type { TimelineEntry } from "../agent-timeline/types";
+
 /**
  * Status of the agent response cycle
  */
@@ -22,6 +24,12 @@ export interface ToolCall {
   name: string;
   arguments?: Record<string, unknown>;
   timestamp: number;
+  /** Agent that made this call (multi-agent scenarios) */
+  agentName?: string | null;
+  /** Parent agent name */
+  parentAgent?: string | null;
+  /** Nesting depth in agent hierarchy */
+  depth?: number;
 }
 
 /**
@@ -32,6 +40,12 @@ export interface KnowledgeItem {
   source: string;
   content: string;
   timestamp: number;
+  /** Agent that retrieved this (multi-agent scenarios) */
+  agentName?: string | null;
+  /** Parent agent name */
+  parentAgent?: string | null;
+  /** Nesting depth in agent hierarchy */
+  depth?: number;
 }
 
 /**
@@ -42,6 +56,24 @@ export interface MemoryItem {
   type: string;
   content: string;
   timestamp: number;
+  /** Agent that accessed this (multi-agent scenarios) */
+  agentName?: string | null;
+  /** Parent agent name */
+  parentAgent?: string | null;
+  /** Nesting depth in agent hierarchy */
+  depth?: number;
+}
+
+/**
+ * Potential response (sub-agent intermediate AI response)
+ */
+export interface PotentialResponse {
+  id: string;
+  content: string;
+  timestamp: number;
+  agentName?: string | null;
+  parentAgent?: string | null;
+  depth?: number;
 }
 
 /**
@@ -53,6 +85,12 @@ export interface StatusItem {
   timestamp: number;
   /** Optional agent name if in multi-agent scenario */
   agent?: string;
+  /** Agent that produced this (multi-agent scenarios) */
+  agentName?: string | null;
+  /** Parent agent name */
+  parentAgent?: string | null;
+  /** Nesting depth in agent hierarchy */
+  depth?: number;
 }
 
 /**
@@ -69,6 +107,12 @@ export interface ThinkingStep {
   depth: number;
   /** Whether this step should start collapsed (default: false) */
   isCollapsed?: boolean;
+  /** Timestamp for timeline ordering */
+  timestamp?: number;
+  /** Agent that produced this (multi-agent scenarios) */
+  agentName?: string | null;
+  /** Parent agent name */
+  parentAgent?: string | null;
 }
 
 /**
@@ -96,8 +140,14 @@ export interface AgentResponseState {
   memory: MemoryItem[];
   /** Status updates from the agent */
   statusUpdates: StatusItem[];
+  /** Potential responses (sub-agent intermediate AI responses) */
+  potentialResponses?: PotentialResponse[];
+  /** Custom timeline entries (consumer-provided) */
+  customTimelineEntries?: TimelineEntry[];
   /** Final response text */
   response: string;
+  /** Timeline entries derived from all accumulator arrays (for AgentTimeline) */
+  timelineEntries?: TimelineEntry[];
   /** Timestamp when first thinking message was received (for timer) */
   thinkingStartTime: number | null;
   /** Timestamp when response was completed (for final timer display) */
@@ -110,13 +160,21 @@ export interface AgentResponseState {
  * WebSocket message payload for agent responses
  */
 export interface AgentMessage {
-  type: "status" | "thinking" | "tool_call" | "knowledge" | "memory" | "response" | "status_update";
+  type: "status" | "thinking" | "tool_call" | "knowledge" | "memory" | "response" | "status_update" | "potential_response";
   /** Message content - for simple string payloads */
   message?: string;
   /** Alternative content field */
   content?: string;
   /** For status messages */
   status?: string;
+  /** Agent name (multi-agent scenarios) */
+  agentName?: string | null;
+  /** Parent agent name (multi-agent scenarios) */
+  parentAgent?: string | null;
+  /** Agent nesting depth (0 = root) */
+  depth?: number;
+  /** Title/label for timeline display */
+  title?: string | null;
   /** For tool_call messages */
   tool?: {
     id: string;
@@ -170,6 +228,8 @@ export const initialAgentResponseState: AgentResponseState = {
   knowledge: [],
   memory: [],
   statusUpdates: [],
+  potentialResponses: [],
+  customTimelineEntries: [],
   response: "",
   thinkingStartTime: null,
   responseCompleteTime: null,