@lobehub/lobehub 2.0.0-next.31 → 2.0.0-next.33

package/packages/conversation-flow/src/transformation/__tests__/MessageCollector.test.ts

@@ -0,0 +1,220 @@
+import { describe, expect, it } from 'vitest';
+
+import type { IdNode, Message } from '../../types';
+import { MessageCollector } from '../MessageCollector';
+
+describe('MessageCollector', () => {
+  describe('collectGroupMembers', () => {
+    it('should collect messages with matching groupId', () => {
+      const messageMap = new Map<string, Message>();
+      const childrenMap = new Map<string | null, string[]>();
+      const collector = new MessageCollector(messageMap, childrenMap);
+
+      const messages: Message[] = [
+        {
+          content: '1',
+          createdAt: 0,
+          groupId: 'group-1',
+          id: 'msg-1',
+          meta: {},
+          role: 'assistant',
+          updatedAt: 0,
+        },
+        {
+          content: '2',
+          createdAt: 0,
+          groupId: 'group-1',
+          id: 'msg-2',
+          meta: {},
+          role: 'assistant',
+          updatedAt: 0,
+        },
+        {
+          content: '3',
+          createdAt: 0,
+          groupId: 'group-2',
+          id: 'msg-3',
+          meta: {},
+          role: 'assistant',
+          updatedAt: 0,
+        },
+      ];
+
+      const result = collector.collectGroupMembers('group-1', messages);
+
+      expect(result).toHaveLength(2);
+      expect(result.map((m) => m.id)).toEqual(['msg-1', 'msg-2']);
+    });
+  });
+
+  describe('collectToolMessages', () => {
+    it('should collect tool messages matching assistant tool call IDs', () => {
+      const messageMap = new Map<string, Message>();
+      const childrenMap = new Map<string | null, string[]>();
+      const collector = new MessageCollector(messageMap, childrenMap);
+
+      const assistant: Message = {
+        content: 'test',
+        createdAt: 0,
+        id: 'msg-1',
+        meta: {},
+        role: 'assistant',
+        tools: [
+          { apiName: 'tool1', arguments: '{}', id: 'tool-1', identifier: 'test', type: 'default' },
+          { apiName: 'tool2', arguments: '{}', id: 'tool-2', identifier: 'test', type: 'default' },
+        ],
+        updatedAt: 0,
+      };
+
+      const messages: Message[] = [
+        {
+          content: 'result1',
+          createdAt: 0,
+          id: 'msg-2',
+          meta: {},
+          parentId: 'msg-1',
+          role: 'tool',
+          tool_call_id: 'tool-1',
+          updatedAt: 0,
+        },
+        {
+          content: 'result2',
+          createdAt: 0,
+          id: 'msg-3',
+          meta: {},
+          parentId: 'msg-1',
+          role: 'tool',
+          tool_call_id: 'tool-2',
+          updatedAt: 0,
+        },
+        {
+          content: 'other',
+          createdAt: 0,
+          id: 'msg-4',
+          meta: {},
+          parentId: 'msg-1',
+          role: 'tool',
+          tool_call_id: 'tool-3',
+          updatedAt: 0,
+        },
+      ];
+
+      const result = collector.collectToolMessages(assistant, messages);
+
+      expect(result).toHaveLength(2);
+      expect(result.map((m) => m.id)).toEqual(['msg-2', 'msg-3']);
+    });
+  });
+
+  describe('findLastNodeInAssistantGroup', () => {
+    it('should return the node itself if no tool children', () => {
+      const messageMap = new Map<string, Message>();
+      const childrenMap = new Map<string | null, string[]>();
+      const collector = new MessageCollector(messageMap, childrenMap);
+
+      const idNode: IdNode = {
+        children: [],
+        id: 'msg-1',
+      };
+
+      const result = collector.findLastNodeInAssistantGroup(idNode);
+
+      expect(result).toEqual(idNode);
+    });
+
+    it('should return last tool node if no assistant children', () => {
+      const messageMap = new Map<string, Message>([
+        [
+          'msg-1',
+          {
+            content: 'test',
+            createdAt: 0,
+            id: 'msg-1',
+            meta: {},
+            role: 'assistant',
+            updatedAt: 0,
+          },
+        ],
+        [
+          'tool-1',
+          {
+            content: 'result',
+            createdAt: 0,
+            id: 'tool-1',
+            meta: {},
+            parentId: 'msg-1',
+            role: 'tool',
+            updatedAt: 0,
+          },
+        ],
+      ]);
+      const childrenMap = new Map<string | null, string[]>();
+      const collector = new MessageCollector(messageMap, childrenMap);
+
+      const idNode: IdNode = {
+        children: [{ children: [], id: 'tool-1' }],
+        id: 'msg-1',
+      };
+
+      const result = collector.findLastNodeInAssistantGroup(idNode);
+
+      expect(result?.id).toBe('tool-1');
+    });
+
+    it('should follow assistant chain recursively', () => {
+      const messageMap = new Map<string, Message>([
+        [
+          'msg-1',
+          {
+            content: 'test1',
+            createdAt: 0,
+            id: 'msg-1',
+            meta: {},
+            role: 'assistant',
+            updatedAt: 0,
+          },
+        ],
+        [
+          'tool-1',
+          {
+            content: 'result1',
+            createdAt: 0,
+            id: 'tool-1',
+            meta: {},
+            parentId: 'msg-1',
+            role: 'tool',
+            updatedAt: 0,
+          },
+        ],
+        [
+          'msg-2',
+          {
+            content: 'test2',
+            createdAt: 0,
+            id: 'msg-2',
+            meta: {},
+            parentId: 'tool-1',
+            role: 'assistant',
+            updatedAt: 0,
+          },
+        ],
+      ]);
+      const childrenMap = new Map<string | null, string[]>();
+      const collector = new MessageCollector(messageMap, childrenMap);
+
+      const idNode: IdNode = {
+        children: [
+          {
+            children: [{ children: [], id: 'msg-2' }],
+            id: 'tool-1',
+          },
+        ],
+        id: 'msg-1',
+      };
+
+      const result = collector.findLastNodeInAssistantGroup(idNode);
+
+      expect(result?.id).toBe('msg-2');
+    });
+  });
+});

package/packages/conversation-flow/src/transformation/__tests__/MessageTransformer.test.ts

@@ -0,0 +1,287 @@
+import { describe, expect, it } from 'vitest';
+
+import type { AssistantContentBlock } from '@/types/index';
+
+import type { Message } from '../../types';
+import { MessageTransformer } from '../MessageTransformer';
+
+describe('MessageTransformer', () => {
+  const transformer = new MessageTransformer();
+
+  describe('messageToContentBlock', () => {
+    it('should convert message to content block', () => {
+      const message: Message = {
+        content: 'Hello',
+        createdAt: 0,
+        id: 'msg-1',
+        meta: {},
+        metadata: {
+          cost: 0.001,
+          duration: 1000,
+          totalInputTokens: 10,
+          totalOutputTokens: 20,
+          totalTokens: 30,
+          tps: 20,
+        },
+        role: 'assistant',
+        updatedAt: 0,
+      };
+
+      const result = transformer.messageToContentBlock(message);
+
+      expect(result).toEqual({
+        content: 'Hello',
+        error: undefined,
+        id: 'msg-1',
+        imageList: undefined,
+        performance: {
+          duration: 1000,
+          tps: 20,
+        },
+        reasoning: undefined,
+        tools: undefined,
+        usage: {
+          cost: 0.001,
+          totalInputTokens: 10,
+          totalOutputTokens: 20,
+          totalTokens: 30,
+        },
+      });
+    });
+
+    it('should handle message without metadata', () => {
+      const message: Message = {
+        content: 'Hello',
+        createdAt: 0,
+        id: 'msg-1',
+        meta: {},
+        role: 'assistant',
+        updatedAt: 0,
+      };
+
+      const result = transformer.messageToContentBlock(message);
+
+      expect(result.usage).toBeUndefined();
+      expect(result.performance).toBeUndefined();
+    });
+  });
+
+  describe('splitMetadata', () => {
+    it('should split metadata into usage and performance', () => {
+      const metadata = {
+        cost: 0.001,
+        duration: 1000,
+        latency: 1100,
+        totalInputTokens: 10,
+        totalOutputTokens: 20,
+        totalTokens: 30,
+        tps: 20,
+        ttft: 100,
+      };
+
+      const result = transformer.splitMetadata(metadata);
+
+      expect(result.usage).toEqual({
+        cost: 0.001,
+        totalInputTokens: 10,
+        totalOutputTokens: 20,
+        totalTokens: 30,
+      });
+
+      expect(result.performance).toEqual({
+        duration: 1000,
+        latency: 1100,
+        tps: 20,
+        ttft: 100,
+      });
+    });
+
+    it('should handle undefined metadata', () => {
+      const result = transformer.splitMetadata(undefined);
+
+      expect(result).toEqual({});
+    });
+
+    it('should handle empty metadata', () => {
+      const result = transformer.splitMetadata({});
+
+      expect(result).toEqual({
+        performance: undefined,
+        usage: undefined,
+      });
+    });
+
+    it('should handle partial metadata', () => {
+      const result = transformer.splitMetadata({
+        cost: 0.001,
+        duration: 1000,
+      });
+
+      expect(result.usage).toEqual({
+        cost: 0.001,
+      });
+
+      expect(result.performance).toEqual({
+        duration: 1000,
+      });
+    });
+  });
+
+  describe('aggregateMetadata', () => {
+    it('should aggregate usage and performance from multiple children', () => {
+      const children: AssistantContentBlock[] = [
+        {
+          content: 'First',
+          id: 'msg-1',
+          performance: {
+            duration: 1000,
+            latency: 1100,
+            tps: 20,
+            ttft: 100,
+          },
+          usage: {
+            cost: 0.001,
+            totalInputTokens: 10,
+            totalOutputTokens: 20,
+            totalTokens: 30,
+          },
+        },
+        {
+          content: 'Second',
+          id: 'msg-2',
+          performance: {
+            duration: 2000,
+            latency: 2100,
+            tps: 30,
+          },
+          usage: {
+            cost: 0.002,
+            totalInputTokens: 15,
+            totalOutputTokens: 25,
+            totalTokens: 40,
+          },
+        },
+      ];
+
+      const result = transformer.aggregateMetadata(children);
+
+      expect(result.usage).toEqual({
+        cost: 0.003,
+        totalInputTokens: 25,
+        totalOutputTokens: 45,
+        totalTokens: 70,
+      });
+
+      expect(result.performance).toEqual({
+        duration: 3000,
+        latency: 3200,
+        tps: 25, // average of 20 and 30
+        ttft: 100, // first value
+      });
+    });
+
+    it('should handle empty children array', () => {
+      const result = transformer.aggregateMetadata([]);
+
+      expect(result).toEqual({
+        performance: undefined,
+        usage: undefined,
+      });
+    });
+
+    it('should handle children without metadata', () => {
+      const children: AssistantContentBlock[] = [
+        {
+          content: 'First',
+          id: 'msg-1',
+        },
+        {
+          content: 'Second',
+          id: 'msg-2',
+        },
+      ];
+
+      const result = transformer.aggregateMetadata(children);
+
+      expect(result).toEqual({
+        performance: undefined,
+        usage: undefined,
+      });
+    });
+
+    it('should handle mixed children (some with metadata, some without)', () => {
+      const children: AssistantContentBlock[] = [
+        {
+          content: 'First',
+          id: 'msg-1',
+          usage: {
+            cost: 0.001,
+            totalTokens: 30,
+          },
+        },
+        {
+          content: 'Second',
+          id: 'msg-2',
+        },
+        {
+          content: 'Third',
+          id: 'msg-3',
+          usage: {
+            cost: 0.002,
+            totalTokens: 40,
+          },
+        },
+      ];
+
+      const result = transformer.aggregateMetadata(children);
+
+      expect(result.usage).toEqual({
+        cost: 0.003,
+        totalTokens: 70,
+      });
+    });
+
+    it('should average tps correctly', () => {
+      const children: AssistantContentBlock[] = [
+        {
+          content: 'First',
+          id: 'msg-1',
+          performance: { tps: 10 },
+        },
+        {
+          content: 'Second',
+          id: 'msg-2',
+          performance: { tps: 20 },
+        },
+        {
+          content: 'Third',
+          id: 'msg-3',
+          performance: { tps: 30 },
+        },
+      ];
+
+      const result = transformer.aggregateMetadata(children);
+
+      expect(result.performance?.tps).toBe(20); // average of 10, 20, 30
+    });
+
+    it('should take first ttft value only', () => {
+      const children: AssistantContentBlock[] = [
+        {
+          content: 'First',
+          id: 'msg-1',
+          performance: { ttft: 100 },
+        },
+        {
+          content: 'Second',
+          id: 'msg-2',
+          performance: { ttft: 200 },
+        },
+      ];
+
+      const result = transformer.aggregateMetadata(children);
+
+      expect(result.performance?.ttft).toBe(100); // first value only
+    });
+  });
+});

package/packages/conversation-flow/src/transformation/index.ts

@@ -0,0 +1,78 @@
+import type { ContextNode, HelperMaps, IdNode, Message } from '../types';
+import { BranchResolver } from './BranchResolver';
+import { ContextTreeBuilder } from './ContextTreeBuilder';
+import { FlatListBuilder } from './FlatListBuilder';
+import { MessageCollector } from './MessageCollector';
+import { MessageTransformer } from './MessageTransformer';
+
+/**
+ * Phase 3: Transformation
+ * Converts structural idTree into semantic contextTree and flatList
+ *
+ * This is the main coordinator that delegates to specialized builders:
+ * - ContextTreeBuilder: Builds the tree structure for UI rendering
+ * - FlatListBuilder: Builds the flat list for API consumption
+ */
+export class Transformer {
+  private messageMap: Map<string, Message>;
+  private nodeIdCounter = 0;
+
+  // Utility classes
+  private branchResolver: BranchResolver;
+  private messageCollector: MessageCollector;
+  private messageTransformer: MessageTransformer;
+
+  // Builder classes
+  private contextTreeBuilder: ContextTreeBuilder;
+  private flatListBuilder: FlatListBuilder;
+
+  constructor(private helperMaps: HelperMaps) {
+    this.messageMap = helperMaps.messageMap;
+
+    // Initialize utility classes
+    this.branchResolver = new BranchResolver();
+    this.messageCollector = new MessageCollector(this.messageMap, helperMaps.childrenMap);
+    this.messageTransformer = new MessageTransformer();
+
+    // Initialize builder classes
+    this.contextTreeBuilder = new ContextTreeBuilder(
+      helperMaps.messageMap,
+      helperMaps.messageGroupMap,
+      this.branchResolver,
+      this.messageCollector,
+      this.generateNodeId.bind(this),
+    );
+
+    this.flatListBuilder = new FlatListBuilder(
+      helperMaps.messageMap,
+      helperMaps.messageGroupMap,
+      helperMaps.childrenMap,
+      this.branchResolver,
+      this.messageCollector,
+      this.messageTransformer,
+    );
+  }
+
+  /**
+   * Generates a unique node ID
+   */
+  private generateNodeId(prefix: string, messageId: string): string {
+    return `${prefix}-${messageId}-${this.nodeIdCounter++}`;
+  }
+
+  /**
+   * Transform all root nodes to contextTree
+   * Returns a linear array of context nodes for UI rendering
+   */
+  transformAll(idNodes: IdNode[]): ContextNode[] {
+    return this.contextTreeBuilder.transformAll(idNodes);
+  }
+
+  /**
+   * Generate flatList from messages array
+   * Only includes messages in the active path for API consumption
+   */
+  flatten(messages: Message[]): Message[] {
+    return this.flatListBuilder.flatten(messages);
+  }
+}

package/packages/conversation-flow/src/types/contextTree.ts

@@ -0,0 +1,65 @@
+/**
+ * Context Tree Types
+ *
+ * Tree structure for understanding conversation flow and navigation.
+ * Used for complex operations like branch switching and context understanding.
+ */
+
+/**
+ * Base interface for all display nodes
+ */
+interface BaseNode {
+  /** Unique identifier for this node */
+  id: string;
+  /** Type discriminator */
+  type: 'message' | 'assistantGroup' | 'compare' | 'branch';
+}
+
+/**
+ * Basic message node - leaf node representing a single message
+ */
+export interface MessageNode extends BaseNode {
+  /** Tool message IDs (for assistant messages with tool calls) */
+  tools?: string[];
+  type: 'message';
+}
+
+/**
+ * Assistant group node - aggregates an assistant message with its tool calls
+ */
+export interface AssistantGroupNode extends BaseNode {
+  /** Child nodes (assistant and tool messages) */
+  children: ContextNode[];
+  type: 'assistantGroup';
+}
+
+/**
+ * Compare node - renders multiple parallel outputs side by side
+ */
+export interface CompareNode extends BaseNode {
+  /** ID of the active column that enters LLM context */
+  activeColumnId?: string;
+  /** Each column represents a parallel output tree */
+  columns: ContextNode[][];
+  /** The message that triggered the comparison */
+  messageId: string;
+  type: 'compare';
+}
+
+/**
+ * Branch node - represents multiple alternate conversation paths
+ */
+export interface BranchNode extends BaseNode {
+  /** Index of the currently active branch */
+  activeBranchIndex: number;
+  /** Each branch is a separate conversation tree */
+  branches: ContextNode[][];
+  /** The parent message that has multiple branches */
+  parentMessageId: string;
+  type: 'branch';
+}
+
+/**
+ * Union type of all display nodes
+ */
+export type ContextNode = MessageNode | AssistantGroupNode | CompareNode | BranchNode;

package/packages/conversation-flow/src/types/flatMessageList.ts

@@ -0,0 +1,66 @@
+import type { UIChatMessage } from '@lobechat/types';
+
+/**
+ * Flat Message List Types
+ *
+ * Flattened array optimized for virtual list rendering.
+ * Contains virtual messages with extended role types for grouped display.
+ */
+
+/**
+ * Extended message role types for flat list rendering
+ *
+ * Standard roles from UIChatMessage:
+ * - 'user': User message
+ * - 'assistant': Assistant message (standalone, without tools)
+ * - 'tool': Tool execution result
+ * - 'system': System message
+ * - 'supervisor': Supervisor message in multi-agent
+ *
+ * Virtual roles created by parse():
+ * - 'assistantGroup': Assistant message + tool calls aggregation
+ * - 'messageGroup': Generic message group (manual/summary)
+ * - 'compare': Compare mode for parallel model outputs
+ */
+export type FlatMessageRole =
+  | 'user'
+  | 'assistant'
+  | 'tool'
+  | 'system'
+  | 'supervisor'
+  | 'assistantGroup'
+  | 'messageGroup'
+  | 'compare';
+
+/**
+ * Message in flat list
+ *
+ * Can be either:
+ * 1. Original message from database
+ * 2. Virtual message created by parse() with extended role and children
+ */
+export type FlatMessage = UIChatMessage;
+
+/**
+ * Branch metadata attached to user messages
+ */
+export interface BranchMetadata {
+  /** Active branch message ID */
+  activeId: string;
+  /** All branch message IDs */
+  branchIds: string[];
+}
+
+/**
+ * Virtual message extra fields for flat list
+ */
+export interface FlatMessageExtra {
+  /** Branch information for user messages with multiple children */
+  branches?: BranchMetadata;
+  /** Optional description for groups */
+  description?: string;
+  /** Group mode for messageGroup and compare virtual messages */
+  groupMode?: 'compare' | 'manual' | 'summary';
+  /** Parent message ID that triggered this group */
+  parentMessageId?: string;
+}