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

package/packages/conversation-flow/src/__tests__/fixtures/outputs/complex-scenario.json

@@ -0,0 +1,239 @@
+{
+  "contextTree": [
+    {
+      "id": "msg-501",
+      "type": "message"
+    },
+    {
+      "children": [
+        {
+          "id": "msg-502",
+          "type": "message",
+          "tools": ["msg-503", "msg-504"]
+        }
+      ],
+      "id": "msg-502",
+      "type": "assistantGroup"
+    },
+    {
+      "id": "msg-505",
+      "type": "message"
+    },
+    {
+      "activeBranchIndex": 0,
+      "branches": [
+        [
+          {
+            "id": "msg-506",
+            "type": "message"
+          }
+        ],
+        [
+          {
+            "id": "msg-507",
+            "type": "message"
+          }
+        ]
+      ],
+      "id": "branch-msg-505-0",
+      "parentMessageId": "msg-505",
+      "type": "branch"
+    }
+  ],
+  "flatList": [
+    {
+      "id": "msg-501",
+      "role": "user",
+      "content": "Help me debug this Python code that's throwing an error",
+      "parentId": null,
+      "createdAt": 1704067200000,
+      "updatedAt": 1704067200000,
+      "meta": {}
+    },
+    {
+      "id": "msg-502",
+      "role": "assistantGroup",
+      "content": "",
+      "parentId": "msg-501",
+      "createdAt": 1704067202000,
+      "updatedAt": 1704067202000,
+      "meta": {},
+      "children": [
+        {
+          "content": "I'll help you debug the code. Let me first check the syntax and run some analysis.",
+          "id": "msg-502",
+          "tools": [
+            {
+              "id": "tool-lint",
+              "identifier": "code-analyzer",
+              "apiName": "analyzePython",
+              "arguments": "{\"action\":\"lint\"}",
+              "type": "default",
+              "result": {
+                "content": "{\"status\":\"success\",\"issues\":[{\"line\":15,\"message\":\"undefined variable 'result'\"}]}",
+                "id": "msg-503",
+                "state": {
+                  "cached": false
+                }
+              },
+              "result_msg_id": "msg-503"
+            },
+            {
+              "id": "tool-test",
+              "identifier": "code-analyzer",
+              "apiName": "runTests",
+              "arguments": "{\"action\":\"test\"}",
+              "type": "default",
+              "result": {
+                "content": "{\"status\":\"failed\",\"error\":\"NameError: name 'result' is not defined\"}",
+                "id": "msg-504",
+                "state": {
+                  "cached": false
+                }
+              },
+              "result_msg_id": "msg-504"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "msg-505",
+      "role": "user",
+      "content": "Here's the code:\n```python\ndef calculate():\n    x = 5\n    y = 10\n    print(result)\n```",
+      "parentId": "msg-504",
+      "createdAt": 1704067210000,
+      "updatedAt": 1704067210000,
+      "meta": {}
+    },
+    {
+      "id": "msg-506",
+      "role": "assistant",
+      "content": "I found the issue! On line 15, you're trying to use `result` but it's never defined. Here's the fix:\n\n```python\ndef calculate():\n    x = 5\n    y = 10\n    result = x + y  # Define result before using it\n    print(result)\n```",
+      "parentId": "msg-505",
+      "createdAt": 1704067213000,
+      "updatedAt": 1704067213000,
+      "meta": {},
+      "usage": {
+        "totalInputTokens": 156,
+        "totalOutputTokens": 89,
+        "totalTokens": 245,
+        "cost": 0.000735
+      }
+    }
+  ],
+  "messageMap": {
+    "msg-501": {
+      "id": "msg-501",
+      "role": "user",
+      "content": "Help me debug this Python code that's throwing an error",
+      "parentId": null,
+      "createdAt": 1704067200000,
+      "updatedAt": 1704067200000,
+      "meta": {}
+    },
+    "msg-502": {
+      "id": "msg-502",
+      "role": "assistant",
+      "content": "I'll help you debug the code. Let me first check the syntax and run some analysis.",
+      "parentId": "msg-501",
+      "tools": [
+        {
+          "id": "tool-lint",
+          "identifier": "code-analyzer",
+          "apiName": "analyzePython",
+          "arguments": "{\"action\":\"lint\"}",
+          "type": "default"
+        },
+        {
+          "id": "tool-test",
+          "identifier": "code-analyzer",
+          "apiName": "runTests",
+          "arguments": "{\"action\":\"test\"}",
+          "type": "default"
+        }
+      ],
+      "createdAt": 1704067202000,
+      "updatedAt": 1704067202000,
+      "meta": {},
+      "usage": {
+        "totalInputTokens": 32,
+        "totalOutputTokens": 48,
+        "totalTokens": 80,
+        "cost": 0.00024
+      },
+      "performance": {
+        "tps": 45
+      }
+    },
+    "msg-503": {
+      "id": "msg-503",
+      "role": "tool",
+      "tool_call_id": "tool-lint",
+      "content": "{\"status\":\"success\",\"issues\":[{\"line\":15,\"message\":\"undefined variable 'result'\"}]}",
+      "pluginState": {
+        "cached": false
+      },
+      "parentId": "msg-502",
+      "createdAt": 1704067203000,
+      "updatedAt": 1704067203000,
+      "meta": {}
+    },
+    "msg-504": {
+      "id": "msg-504",
+      "role": "tool",
+      "tool_call_id": "tool-test",
+      "content": "{\"status\":\"failed\",\"error\":\"NameError: name 'result' is not defined\"}",
+      "pluginState": {
+        "cached": false
+      },
+      "pluginError": {
+        "type": "NameError",
+        "message": "name 'result' is not defined"
+      },
+      "parentId": "msg-502",
+      "createdAt": 1704067203100,
+      "updatedAt": 1704067203100,
+      "meta": {}
+    },
+    "msg-505": {
+      "id": "msg-505",
+      "role": "user",
+      "content": "Here's the code:\n```python\ndef calculate():\n    x = 5\n    y = 10\n    print(result)\n```",
+      "parentId": "msg-504",
+      "createdAt": 1704067210000,
+      "updatedAt": 1704067210000,
+      "meta": {}
+    },
+    "msg-506": {
+      "id": "msg-506",
+      "role": "assistant",
+      "content": "I found the issue! On line 15, you're trying to use `result` but it's never defined. Here's the fix:\n\n```python\ndef calculate():\n    x = 5\n    y = 10\n    result = x + y  # Define result before using it\n    print(result)\n```",
+      "parentId": "msg-505",
+      "createdAt": 1704067213000,
+      "updatedAt": 1704067213000,
+      "meta": {},
+      "usage": {
+        "totalInputTokens": 156,
+        "totalOutputTokens": 89,
+        "totalTokens": 245,
+        "cost": 0.000735
+      }
+    },
+    "msg-507": {
+      "id": "msg-507",
+      "role": "assistant",
+      "content": "Alternatively, you could return the value instead:\n\n```python\ndef calculate():\n    x = 5\n    y = 10\n    return x + y\n\nresult = calculate()\nprint(result)\n```",
+      "parentId": "msg-505",
+      "createdAt": 1704067213100,
+      "updatedAt": 1704067213100,
+      "meta": {},
+      "usage": {
+        "totalInputTokens": 156,
+        "totalOutputTokens": 72,
+        "totalTokens": 228,
+        "cost": 0.000684
+      }
+    }
+  }
+}

package/packages/conversation-flow/src/__tests__/fixtures/outputs/linear-conversation.json

@@ -0,0 +1,138 @@
+{
+  "contextTree": [
+    {
+      "id": "msg-001",
+      "type": "message"
+    },
+    {
+      "id": "msg-002",
+      "type": "message"
+    },
+    {
+      "id": "msg-003",
+      "type": "message"
+    },
+    {
+      "id": "msg-004",
+      "type": "message"
+    }
+  ],
+  "flatList": [
+    {
+      "id": "msg-001",
+      "role": "user",
+      "content": "Can you help me write a Python function to check if a number is prime?",
+      "parentId": null,
+      "createdAt": 1704067200000,
+      "updatedAt": 1704067200000,
+      "meta": {}
+    },
+    {
+      "id": "msg-002",
+      "role": "assistant",
+      "content": "I'd be happy to help you write a function to check if a number is prime. Here's a simple and efficient implementation:\n\n```python\ndef is_prime(n):\n    if n < 2:\n        return False\n    if n == 2:\n        return True\n    if n % 2 == 0:\n        return False\n    \n    for i in range(3, int(n**0.5) + 1, 2):\n        if n % i == 0:\n            return False\n    \n    return True\n```\n\nThis function works by checking divisibility up to the square root of the number.",
+      "parentId": "msg-001",
+      "createdAt": 1704067205000,
+      "updatedAt": 1704067205000,
+      "meta": {},
+      "usage": {
+        "totalInputTokens": 24,
+        "totalOutputTokens": 156,
+        "totalTokens": 180,
+        "cost": 0.00054
+      },
+      "performance": {
+        "tps": 52,
+        "ttft": 234,
+        "duration": 3000,
+        "latency": 3234
+      }
+    },
+    {
+      "id": "msg-003",
+      "role": "user",
+      "content": "Thanks! Can you add some test cases?",
+      "parentId": "msg-002",
+      "createdAt": 1704067210000,
+      "updatedAt": 1704067210000,
+      "meta": {}
+    },
+    {
+      "id": "msg-004",
+      "role": "assistant",
+      "content": "Sure! Here are some test cases:\n\n```python\nprint(is_prime(2))    # True\nprint(is_prime(17))   # True\nprint(is_prime(100))  # False\nprint(is_prime(1))    # False\nprint(is_prime(-5))   # False\n```",
+      "parentId": "msg-003",
+      "createdAt": 1704067213000,
+      "updatedAt": 1704067213000,
+      "meta": {},
+      "usage": {
+        "totalInputTokens": 180,
+        "totalOutputTokens": 89,
+        "totalTokens": 269,
+        "cost": 0.000807
+      },
+      "performance": {
+        "tps": 44.5
+      }
+    }
+  ],
+  "messageMap": {
+    "msg-001": {
+      "id": "msg-001",
+      "role": "user",
+      "content": "Can you help me write a Python function to check if a number is prime?",
+      "parentId": null,
+      "createdAt": 1704067200000,
+      "updatedAt": 1704067200000,
+      "meta": {}
+    },
+    "msg-002": {
+      "id": "msg-002",
+      "role": "assistant",
+      "content": "I'd be happy to help you write a function to check if a number is prime. Here's a simple and efficient implementation:\n\n```python\ndef is_prime(n):\n    if n < 2:\n        return False\n    if n == 2:\n        return True\n    if n % 2 == 0:\n        return False\n    \n    for i in range(3, int(n**0.5) + 1, 2):\n        if n % i == 0:\n            return False\n    \n    return True\n```\n\nThis function works by checking divisibility up to the square root of the number.",
+      "parentId": "msg-001",
+      "createdAt": 1704067205000,
+      "updatedAt": 1704067205000,
+      "meta": {},
+      "usage": {
+        "totalInputTokens": 24,
+        "totalOutputTokens": 156,
+        "totalTokens": 180,
+        "cost": 0.00054
+      },
+      "performance": {
+        "tps": 52,
+        "ttft": 234,
+        "duration": 3000,
+        "latency": 3234
+      }
+    },
+    "msg-003": {
+      "id": "msg-003",
+      "role": "user",
+      "content": "Thanks! Can you add some test cases?",
+      "parentId": "msg-002",
+      "createdAt": 1704067210000,
+      "updatedAt": 1704067210000,
+      "meta": {}
+    },
+    "msg-004": {
+      "id": "msg-004",
+      "role": "assistant",
+      "content": "Sure! Here are some test cases:\n\n```python\nprint(is_prime(2))    # True\nprint(is_prime(17))   # True\nprint(is_prime(100))  # False\nprint(is_prime(1))    # False\nprint(is_prime(-5))   # False\n```",
+      "parentId": "msg-003",
+      "createdAt": 1704067213000,
+      "updatedAt": 1704067213000,
+      "meta": {},
+      "usage": {
+        "totalInputTokens": 180,
+        "totalOutputTokens": 89,
+        "totalTokens": 269,
+        "cost": 0.000807
+      },
+      "performance": {
+        "tps": 44.5
+      }
+    }
+  }
+}

package/packages/conversation-flow/src/__tests__/parse.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from 'vitest';
+
+import { parse } from '../parse';
+import { inputs, outputs } from './fixtures';
+
+function serializeParseResult(result: ReturnType<typeof parse>) {
+  return {
+    contextTree: result.contextTree,
+    flatList: result.flatList,
+    messageMap: result.messageMap,
+  };
+}
+
+describe('parse', () => {
+  describe('Basic Conversations', () => {
+    it('should parse linear conversation correctly', () => {
+      const result = parse(inputs.linearConversation);
+
+      expect(serializeParseResult(result)).toEqual(outputs.linearConversation);
+    });
+  });
+
+  describe('Tool Usage', () => {
+    it('should parse assistant with tools correctly', () => {
+      const result = parse(inputs.assistantWithTools);
+
+      expect(serializeParseResult(result)).toEqual(outputs.assistantWithTools);
+    });
+
+    it('should include follow-up messages after assistant chain', () => {
+      const result = parse(inputs.assistantChainWithFollowup);
+
+      // The critical assertion: flatList should contain all 5 messages
+      // msg-1 (user) + assistantGroup (msg-2+msg-3+tool-1) + msg-4 (user follow-up)
+      expect(result.flatList).toHaveLength(3);
+      expect(result.flatList[0].id).toBe('msg-1');
+      expect(result.flatList[1].role).toBe('assistantGroup');
+      expect(result.flatList[2].id).toBe('msg-4'); // This is the critical one that might be missing
+
+      expect(serializeParseResult(result)).toEqual(outputs.assistantChainWithFollowup);
+    });
+  });
+
+  describe('Branching', () => {
+    it('should parse branched conversation correctly', () => {
+      const result = parse(inputs.branch.conversation);
+
+      expect(serializeParseResult(result)).toEqual(outputs.branch.conversation);
+    });
+
+    it('should respect activeBranchIndex when specified', () => {
+      const result = parse(inputs.branch.activeIndex1);
+
+      expect(serializeParseResult(result)).toEqual(outputs.branch.activeIndex1);
+    });
+
+    it('should handle assistant message with branches', () => {
+      const result = parse(inputs.branch.assistantBranch);
+
+      expect(serializeParseResult(result)).toEqual(outputs.branch.assistantBranch);
+    });
+
+    it('should handle assistant with user branches', () => {
+      const result = parse(inputs.branch.assistantUserBranch);
+
+      expect(serializeParseResult(result)).toEqual(outputs.branch.assistantUserBranch);
+    });
+
+    it('should handle deeply nested branches (4 levels)', () => {
+      const result = parse(inputs.branch.nested);
+
+      expect(serializeParseResult(result)).toEqual(outputs.branch.nested);
+    });
+  });
+
+  describe('Compare Mode', () => {
+    it('should parse simple compare mode correctly', () => {
+      const result = parse(inputs.compare.simple);
+
+      expect(serializeParseResult(result)).toEqual(outputs.compare.simple);
+    });
+
+    it('should parse compare mode with tools correctly', () => {
+      const result = parse(inputs.compare.withTools);
+
+      expect(serializeParseResult(result)).toEqual(outputs.compare.withTools);
+    });
+  });
+
+  describe('Complex Scenarios', () => {
+    it('should handle complex mixed scenarios correctly', () => {
+      const result = parse(inputs.complexScenario);
+
+      expect(serializeParseResult(result)).toEqual(outputs.complexScenario);
+    });
+  });
+});

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

@@ -0,0 +1,17 @@
+// Main parse function
+export { parse } from './parse';
+
+// Context Tree Types - for navigation and context understanding
+export type {
+  AssistantGroupNode,
+  BranchNode,
+  CompareNode,
+  ContextNode,
+  MessageNode,
+} from './types';
+
+// Flat Message List Types - for virtual list rendering
+export type { BranchMetadata, FlatMessage, FlatMessageExtra, FlatMessageRole } from './types';
+
+// Shared Types
+export type { HelperMaps, IdNode, Message, MessageGroupMetadata, ParseResult } from './types';

package/packages/conversation-flow/src/indexing.ts

@@ -0,0 +1,58 @@
+import type { HelperMaps, Message, MessageGroupMetadata } from './types';
+
+/**
+ * Phase 1: Indexing
+ * Builds helper maps for efficient querying during parsing
+ *
+ * @param messages - Flat array of messages from backend
+ * @param messageGroups - Optional array of message group metadata
+ * @returns Helper maps for efficient access
+ */
+export function buildHelperMaps(
+  messages: Message[],
+  messageGroups?: MessageGroupMetadata[],
+): HelperMaps {
+  const messageMap = new Map<string, Message>();
+  const childrenMap = new Map<string | null, string[]>();
+  const threadMap = new Map<string, Message[]>();
+  const messageGroupMap = new Map<string, MessageGroupMetadata>();
+
+  // Single pass through messages to build all maps
+  for (const message of messages) {
+    // 1. Build messageMap for O(1) access
+    messageMap.set(message.id, message);
+
+    // 2. Build childrenMap for parent -> children lookup
+    const parentId = message.parentId ?? null;
+    const siblings = childrenMap.get(parentId);
+    if (siblings) {
+      siblings.push(message.id);
+    } else {
+      childrenMap.set(parentId, [message.id]);
+    }
+
+    // 3. Build threadMap for thread aggregation
+    if (message.threadId) {
+      const threadMessages = threadMap.get(message.threadId);
+      if (threadMessages) {
+        threadMessages.push(message);
+      } else {
+        threadMap.set(message.threadId, [message]);
+      }
+    }
+  }
+
+  // 4. Build messageGroupMap from provided metadata
+  if (messageGroups) {
+    for (const group of messageGroups) {
+      messageGroupMap.set(group.id, group);
+    }
+  }
+
+  return {
+    childrenMap,
+    messageGroupMap,
+    messageMap,
+    threadMap,
+  };
+}

package/packages/conversation-flow/src/parse.ts

@@ -0,0 +1,53 @@
+import { buildHelperMaps } from './indexing';
+import { buildIdTree } from './structuring';
+import { Transformer } from './transformation';
+import type { Message, MessageGroupMetadata, ParseResult } from './types';
+
+/**
+ * Main parse function - the brain of the conversation flow engine
+ *
+ * Converts a flat array of messages into:
+ * 1. messageMap - for O(1) message access
+ * 2. displayTree - semantic tree structure for navigation
+ * 3. flatList - flattened array optimized for virtual list rendering
+ *
+ * Uses a three-phase parsing strategy:
+ * 1. Indexing - build helper maps for efficient querying
+ * 2. Structuring - convert flat data to tree structure
+ * 3. Transformation - apply business logic to create semantic nodes and flat list
+ *
+ * @param messages - Flat array of messages from backend
+ * @param messageGroups - Optional array of message group metadata for compare/manual grouping
+ * @returns ParseResult containing messageMap, displayTree, and flatList
+ */
+export function parse(messages: Message[], messageGroups?: MessageGroupMetadata[]): ParseResult {
+  // Phase 1: Indexing
+  // Build helper maps for O(1) access patterns
+  const helperMaps = buildHelperMaps(messages, messageGroups);
+
+  // Phase 2: Structuring
+  // Convert flat parent-child relationships to tree structure
+  // Separates main flow from threaded conversations
+  const idTree = buildIdTree(helperMaps);
+
+  // Phase 3: Transformation
+  // Apply priority-based pattern matching to create semantic display nodes
+  const transformer = new Transformer(helperMaps);
+  const contextTree = transformer.transformAll(idTree);
+
+  // Phase 3b: Generate flatList for virtual list rendering
+  // Implements RFC priority-based pattern matching
+  const flatList = transformer.flatten(messages);
+
+  // Convert messageMap from Map to plain object for serialization
+  const messageMapObj: Record<string, Message> = {};
+  helperMaps.messageMap.forEach((message, id) => {
+    messageMapObj[id] = message;
+  });
+
+  return {
+    contextTree,
+    flatList,
+    messageMap: messageMapObj,
+  };
+}

package/packages/conversation-flow/src/structuring.ts

@@ -0,0 +1,38 @@
+import type { HelperMaps, IdNode } from './types';
+
+/**
+ * Phase 2: Structuring
+ * Converts flat parent-child relationships into a tree structure
+ * Separates main flow from threaded conversations
+ *
+ * @param helperMaps - Maps built in indexing phase
+ * @returns Root nodes of the main conversation flow (idTree)
+ */
+export function buildIdTree(helperMaps: HelperMaps): IdNode[] {
+  const { childrenMap, messageMap } = helperMaps;
+
+  // Build tree recursively starting from root messages (parentId = null)
+  const buildTree = (messageId: string): IdNode => {
+    const childIds = childrenMap.get(messageId) ?? [];
+
+    // Filter children to only include those in main flow (not in threads)
+    const mainFlowChildIds = childIds.filter((childId) => {
+      const child = messageMap.get(childId);
+      return child && !child.threadId;
+    });
+
+    return {
+      children: mainFlowChildIds.map((childId) => buildTree(childId)),
+      id: messageId,
+    };
+  };
+
+  // Get root message IDs (messages with parentId = null and no threadId)
+  const rootIds = childrenMap.get(null) ?? [];
+  const mainFlowRootIds = rootIds.filter((id) => {
+    const msg = messageMap.get(id);
+    return msg && !msg.threadId;
+  });
+
+  return mainFlowRootIds.map((rootId) => buildTree(rootId));
+}