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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optilogic/chat",
-  "version": "1.0.0-beta.10",
+  "version": "1.0.0-beta.11",
   "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.10",
-    "@optilogic/editor": "1.0.0-beta.10"
+    "@optilogic/core": "1.0.0-beta.11",
+    "@optilogic/editor": "1.0.0-beta.11"
   },
   "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 */
@@ -147,6 +149,9 @@ const AgentResponse = React.forwardRef<HTMLDivElement, AgentResponseProps>(
     },
     ref
   ) => {
+    // Ref-backed timeline UI state (survives remounts during streaming)
+    const timelineUIStateRef = useRef<TimelineUIState>(createTimelineUIState());
+
     // Uncontrolled thinking expanded state
     const [uncontrolledExpanded, setUncontrolledExpanded] = useState(defaultThinkingExpanded);
 
@@ -182,9 +187,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;
@@ -245,16 +251,28 @@ const AgentResponse = React.forwardRef<HTMLDivElement, AgentResponseProps>(
                 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="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}
+                />
+              )}
             </>
           )}
 

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

@@ -110,7 +110,7 @@ const ThinkingSection = React.forwardRef<HTMLDivElement, ThinkingSectionProps>(
         className={cn("px-3 pb-3 border-t border-border", className)}
         {...props}
       >
-        <div className="mt-2 max-h-[200px] overflow-y-auto">
+        <div className="mt-2 max-h-[200px] overflow-y-auto scrollbar-thin">
           {isStructured ? (
             <div className="space-y-0">
               {content.map((step) => (

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

@@ -16,6 +16,7 @@ import {
   type StatusItem,
   type ThinkingStep,
 } from "../types";
+import { buildTimelineEntries } from "../../agent-timeline/utils";
 
 export interface UseAgentResponseAccumulatorOptions {
   /** WebSocket topic to filter messages (optional, for convenience) */
@@ -94,33 +95,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 +150,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 +174,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 +198,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 +230,17 @@ 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 };
           }

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

@@ -53,3 +53,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,12 @@ 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;
 }
 
 /**
@@ -53,6 +73,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 +95,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;
 }
 
 /**
@@ -98,6 +130,8 @@ export interface AgentResponseState {
   statusUpdates: StatusItem[];
   /** 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) */
@@ -117,6 +151,14 @@ export interface AgentMessage {
   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;

package/src/components/agent-timeline/AgentTimeline.tsx

@@ -0,0 +1,256 @@
+import { useMemo, useRef, useState, useCallback, type ReactNode } from "react";
+import {
+  Brain,
+  Wrench,
+  BookOpen,
+  HardDrive,
+  Activity,
+  MessageSquare,
+  AlertCircle,
+  ChevronsDownUp,
+  ChevronsUpDown,
+} from "lucide-react";
+import type { TimelineEntry, TimelineEntryType } from "./types";
+import { groupIntoAgentRuns } from "./utils";
+import { TimelineAgentBlock } from "./TimelineAgentBlock";
+
+/** Externalized UI state that survives component remounts */
+export interface TimelineUIState {
+  expandedItems: Set<string>;
+  collapsedRuns: Set<string>;
+  activeFilters: Set<TimelineEntryType>;
+}
+
+export function createTimelineUIState(): TimelineUIState {
+  return {
+    expandedItems: new Set(),
+    collapsedRuns: new Set(),
+    activeFilters: new Set(),
+  };
+}
+
+/** Icon + label config for each entry type */
+const TYPE_CONFIG: {
+  type: TimelineEntryType;
+  icon: typeof Brain;
+  label: string;
+}[] = [
+  { type: "status_update", icon: Activity, label: "Status" },
+  { type: "thinking", icon: Brain, label: "Thinking" },
+  { type: "tool_call", icon: Wrench, label: "Tools" },
+  { type: "knowledge", icon: BookOpen, label: "Knowledge" },
+  { type: "memory", icon: HardDrive, label: "Memory" },
+  { type: "ai_response", icon: MessageSquare, label: "AI" },
+  { type: "error", icon: AlertCircle, label: "Errors" },
+];
+
+interface AgentTimelineProps {
+  entries: TimelineEntry[];
+  renderMarkdown?: (content: string) => ReactNode;
+  /**
+   * External UI state store. When provided, expand/collapse/filter state
+   * is read from and written to this object (which should be ref-backed
+   * in the parent) so it survives component remounts during streaming.
+   */
+  uiState?: TimelineUIState;
+  /**
+   * Maximum height of the scrollable timeline container.
+   * Defaults to "300px". Set to "none" to disable.
+   */
+  maxHeight?: string;
+}
+
+export function AgentTimeline({ entries, renderMarkdown, uiState, maxHeight = "300px" }: AgentTimelineProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  // Render tick: forces re-renders AND invalidates useMemo deps when we mutate Sets in-place
+  const [renderTick, setRenderTick] = useState(0);
+  const forceRender = useCallback(() => setRenderTick((t) => t + 1), []);
+
+  // Resolve state: prefer external uiState (ref-backed, survives remounts)
+  // Fall back to internal state if no external store provided
+  const [internalExpandedItems] = useState<Set<string>>(() => new Set());
+  const [internalCollapsedRuns] = useState<Set<string>>(() => new Set());
+  const [internalActiveFilters] = useState<Set<TimelineEntryType>>(() => new Set());
+
+  const expandedItems = uiState?.expandedItems ?? internalExpandedItems;
+  const collapsedRuns = uiState?.collapsedRuns ?? internalCollapsedRuns;
+  const activeFilters = uiState?.activeFilters ?? internalActiveFilters;
+
+  // Compute which types actually exist in the entries
+  const availableTypes = useMemo(() => {
+    const types = new Set<TimelineEntryType>();
+    for (const entry of entries) {
+      types.add(entry.type);
+    }
+    return types;
+  }, [entries]);
+
+  // Filter entries, then group into runs
+  // eslint-disable-next-line react-hooks/exhaustive-deps -- renderTick invalidates when mutated Sets change
+  const filteredEntries = useMemo(
+    () =>
+      activeFilters.size === 0
+        ? entries
+        : entries.filter((e) => activeFilters.has(e.type)),
+    [entries, activeFilters, renderTick],
+  );
+
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const agentRuns = useMemo(() => groupIntoAgentRuns(filteredEntries), [filteredEntries, renderTick]);
+
+  // --- Mutators (mutate the set in-place + trigger re-render) ---
+
+  const toggleFilter = useCallback((type: TimelineEntryType) => {
+    if (activeFilters.has(type)) {
+      activeFilters.delete(type);
+    } else {
+      activeFilters.add(type);
+    }
+    forceRender();
+  }, [activeFilters, forceRender]);
+
+  const clearFilters = useCallback(() => {
+    activeFilters.clear();
+    forceRender();
+  }, [activeFilters, forceRender]);
+
+  const toggleItemExpanded = useCallback((entryId: string) => {
+    if (expandedItems.has(entryId)) {
+      expandedItems.delete(entryId);
+    } else {
+      expandedItems.add(entryId);
+    }
+    forceRender();
+  }, [expandedItems, forceRender]);
+
+  const collapseAll = useCallback(() => {
+    collapsedRuns.clear();
+    agentRuns.forEach((run, i) => {
+      collapsedRuns.add(`${run.agentName}-${i}`);
+    });
+    expandedItems.clear();
+    forceRender();
+  }, [agentRuns, collapsedRuns, expandedItems, forceRender]);
+
+  const expandAll = useCallback(() => {
+    collapsedRuns.clear();
+    agentRuns.forEach((run, i) => {
+      collapsedRuns.add(`${run.agentName}-${i}:expanded`);
+    });
+    forceRender();
+  }, [agentRuns, collapsedRuns, forceRender]);
+
+  if (entries.length === 0) return null;
+
+  const isSingle = agentRuns.length === 1;
+  const hasActiveFilter = activeFilters.size > 0;
+
+  const scrollStyle = maxHeight !== "none" ? { maxHeight } : undefined;
+
+  return (
+    <div
+      ref={containerRef}
+      className={`-mt-1 ${maxHeight !== "none" ? "overflow-y-auto scrollbar-thin" : ""}`}
+      style={scrollStyle}
+    >
+      {/* Filter + controls bar (sticky within scroll container) */}
+      <div className="sticky top-0 z-10 bg-background flex items-center gap-1 py-1.5 mb-1 border-b border-border/50 flex-wrap">
+        {/* Type filter chips */}
+        {TYPE_CONFIG.filter((tc) => availableTypes.has(tc.type)).map((tc) => {
+          const isActive = activeFilters.has(tc.type);
+          const count = entries.filter((e) => e.type === tc.type).length;
+          return (
+            <button
+              key={tc.type}
+              onClick={() => toggleFilter(tc.type)}
+              className={`inline-flex items-center gap-1 px-1.5 py-0.5 rounded text-[10px] transition-colors ${
+                isActive
+                  ? "bg-accent text-accent-foreground ring-1 ring-accent-foreground/20"
+                  : "text-muted-foreground/60 hover:text-muted-foreground hover:bg-muted/50"
+              }`}
+              title={`${isActive ? "Hide" : "Show only"} ${tc.label}`}
+            >
+              <tc.icon className="w-3 h-3" />
+              <span>{count}</span>
+            </button>
+          );
+        })}
+
+        {/* Clear filter button */}
+        {hasActiveFilter && (
+          <button
+            onClick={clearFilters}
+            className="text-[10px] text-muted-foreground/60 hover:text-muted-foreground px-1"
+          >
+            Clear
+          </button>
+        )}
+
+        {/* Spacer */}
+        <div className="flex-1" />
+
+        {/* Collapse/expand all */}
+        {!isSingle && (
+          <>
+            <button
+              onClick={collapseAll}
+              className="inline-flex items-center gap-0.5 text-[10px] text-muted-foreground/60 hover:text-muted-foreground px-1 py-0.5 rounded hover:bg-muted/50 transition-colors"
+              title="Collapse all"
+            >
+              <ChevronsDownUp className="w-3 h-3" />
+            </button>
+            <button
+              onClick={expandAll}
+              className="inline-flex items-center gap-0.5 text-[10px] text-muted-foreground/60 hover:text-muted-foreground px-1 py-0.5 rounded hover:bg-muted/50 transition-colors"
+              title="Expand all"
+            >
+              <ChevronsUpDown className="w-3 h-3" />
+            </button>
+          </>
+        )}
+      </div>
+
+      {/* Timeline content */}
+      {filteredEntries.length === 0 ? (
+        <div className="text-[10px] text-muted-foreground/50 py-2 text-center">
+          No entries match the selected filters
+        </div>
+      ) : (
+        <div className="space-y-0.5">
+          {agentRuns.map((run, i) => {
+            const runKey = `${run.agentName}-${i}`;
+            const defaultCollapsed = run.depth > 0;
+            const isCollapsed = collapsedRuns.has(runKey)
+              ? true
+              : collapsedRuns.has(`${runKey}:expanded`)
+                ? false
+                : defaultCollapsed;
+
+            return (
+              <TimelineAgentBlock
+                key={runKey}
+                block={run}
+                renderMarkdown={renderMarkdown}
+                isSingleAgent={isSingle}
+                isCollapsed={isCollapsed}
+                onToggleCollapsed={() => {
+                  if (isCollapsed) {
+                    collapsedRuns.delete(runKey);
+                    collapsedRuns.add(`${runKey}:expanded`);
+                  } else {
+                    collapsedRuns.delete(`${runKey}:expanded`);
+                    collapsedRuns.add(runKey);
+                  }
+                  forceRender();
+                }}
+                expandedItems={expandedItems}
+                onToggleItemExpanded={toggleItemExpanded}
+              />
+            );
+          })}
+        </div>
+      )}
+    </div>
+  );
+}