Message Rendering System

Relevant source files

• backend/packages/harness/deerflow/agents/middlewares/todo_middleware.py
• backend/tests/test_todo_middleware.py
• frontend/package.json
• frontend/pnpm-lock.yaml
• frontend/src/app/layout.tsx
• frontend/src/components/ai-elements/artifact.tsx
• frontend/src/components/ai-elements/chain-of-thought.tsx
• frontend/src/components/ai-elements/code-block.tsx
• frontend/src/components/ai-elements/suggestion.tsx
• frontend/src/components/ui/select.tsx
• frontend/src/components/workspace/artifacts/artifact-file-detail.tsx
• frontend/src/components/workspace/artifacts/artifact-file-list.tsx
• frontend/src/components/workspace/artifacts/context.tsx
• frontend/src/components/workspace/flip-display.tsx
• frontend/src/components/workspace/messages/context.ts
• frontend/src/components/workspace/messages/index.ts
• frontend/src/components/workspace/messages/markdown-content.tsx
• frontend/src/components/workspace/messages/message-group.tsx
• frontend/src/components/workspace/messages/message-list-item.tsx
• frontend/src/components/workspace/messages/message-list.tsx
• frontend/src/components/workspace/messages/skeleton.tsx
• frontend/src/components/workspace/messages/subtask-card.tsx
• frontend/src/components/workspace/token-usage-indicator.tsx
• frontend/src/core/messages/usage.ts
• frontend/src/core/messages/utils.ts
• frontend/src/core/skills/api.ts
• frontend/src/core/streamdown/plugins.ts
• frontend/src/core/utils/files.tsx
• frontend/src/styles/globals.css
• frontend/tests/e2e/branch-thread.spec.ts
• frontend/tests/unit/components/workspace/messages/markdown-content.test.ts
• frontend/tests/unit/core/messages/usage.test.ts
• frontend/tests/unit/core/messages/utils.test.ts
• frontend/tests/unit/core/streamdown/plugins.test.ts
• frontend/tests/unit/core/threads/token-usage.test.ts

This page documents how chat messages are classified, grouped, and rendered in the DeerFlow workspace UI. It covers the message grouping logic, the rendering dispatch in MessageList, the MessageListItem and MessageGroup components, the Chain of Thought (CoT) visualization system, and the tool call visualization.

---

Message Grouping

All rendering starts in MessageList, which receives a flat array of Message objects from the LangGraph stream. Before any rendering occurs, the array is passed through getMessageGroups. frontend/src/components/workspace/messages/message-list.tsx169-186

getMessageGroups utility — frontend/src/core/messages/utils.ts

getMessageGroups walks the flat message array and emits typed group objects. The logic filters out hidden control messages and aggregates tool calls with their parent AI messages. frontend/src/core/messages/utils.ts36-155

Group Types

Group type	Source messages	Rendered by
human	message.type === "human"	MessageListItem frontend/src/components/workspace/messages/message-list.tsx298-311
assistant	AI message with content, no tool calls	MessageListItem frontend/src/components/workspace/messages/message-list.tsx298-311
assistant:processing	AI message with reasoning or tool calls	MessageGroup frontend/src/components/workspace/messages/message-list.tsx350-354
assistant:clarification	Tool message where isClarificationToolMessage is true	MarkdownContent frontend/src/components/workspace/messages/message-list.tsx312-328
assistant:present-files	AI message containing present_files tool calls	MarkdownContent + ArtifactFileList frontend/src/components/workspace/messages/message-list.tsx330-348
assistant:subagent	AI message containing task tool calls	SubtaskCard frontend/src/components/workspace/messages/message-list.tsx355-366

Tool response messages (message.type === "tool") are never rendered as standalone groups — they are appended to the preceding assistant:processing group to preserve tool-call association. frontend/src/core/messages/utils.ts68-105

Sources: frontend/src/core/messages/utils.ts3-155 frontend/src/components/workspace/messages/message-list.tsx162-187

---

Diagram: Message grouping and rendering dispatch

Sources: frontend/src/components/workspace/messages/message-list.tsx298-366 frontend/src/core/messages/utils.ts36-155

---

MessageList

MessageList in frontend/src/components/workspace/messages/message-list.tsx is the top-level rendering component for a conversation thread.

1. State Management: It accepts a thread object and uses useStableMessageGroups to prevent unnecessary re-renders during streaming updates. frontend/src/components/workspace/messages/message-list.tsx162-187
2. History Loading: Implements LoadMoreHistoryIndicator which uses an IntersectionObserver to trigger loadMore when the user scrolls to the top of the chat. frontend/src/components/workspace/messages/message-list.tsx206-259
3. Dispatch: Iterates over groupedMessages and renders the appropriate UI component based on the group.type. frontend/src/components/workspace/messages/message-list.tsx294-368
4. Token Usage: Renders inline token usage summaries via MessageTokenUsageList or MessageTokenUsageDebugList based on the tokenUsageInlineMode setting. frontend/src/components/workspace/messages/message-list.tsx371-383

Sources: frontend/src/components/workspace/messages/message-list.tsx1-400

---

MessageListItem

MessageListItem in frontend/src/components/workspace/messages/message-list-item.tsx renders human messages and final assistant responses.

Content Handling

The component extracts content using extractContentFromMessage and extractReasoningContentFromMessage. frontend/src/components/workspace/messages/message-list-item.tsx41-42 It uses MarkdownContent for rendering.

• Feedback: Provides FeedbackButtons for assistant messages to trigger upsertFeedback or deleteFeedback. frontend/src/components/workspace/messages/message-list-item.tsx66-131
• Copying: Includes a CopyButton using getMessageCopyData to facilitate text extraction. frontend/src/components/workspace/messages/message-list-item.tsx179

MessageImage and Links

The component handles specialized rendering for artifacts. It uses resolveMessageImageURL to handle paths that may point to artifacts generated within the thread. frontend/src/components/workspace/messages/message-list-item.tsx226 frontend/src/core/artifacts/utils.ts36

Sources: frontend/src/components/workspace/messages/message-list-item.tsx133-240 frontend/src/core/messages/utils.ts41-47

---

MessageGroup and Chain of Thought

MessageGroup in frontend/src/components/workspace/messages/message-group.tsx visualizes the "thinking" process, including internal reasoning and tool calls.

Display Logic

The component organizes steps into a collapsible hierarchy using the ChainOfThought component family:

• Collapsible Reasoning: Tracks internal thought steps using ChainOfThoughtStep. frontend/src/components/workspace/messages/message-group.tsx242-255
• Step Partitioning: Steps are partitioned into aboveLastToolCallSteps (usually collapsed) and the most recent lastToolCallStep which remains visible. frontend/src/components/workspace/messages/message-group.tsx105-111

Tool Call Visualization

ToolCall renders specific UI for different tools:

• Search Results: Renders ChainOfThoughtSearchResults with clickable badges for each search result. frontend/src/components/workspace/messages/message-group.tsx204-212
• Token Debugging: Integrates TokenDebugStep data to show token counts per tool call or reasoning step via renderDebugSummary. frontend/src/components/workspace/messages/message-group.tsx169-216

Sources: frontend/src/components/workspace/messages/message-group.tsx52-258 frontend/src/components/ai-elements/chain-of-thought.tsx1-239

---

Diagram: CoT step conversion and rendering pipeline

Sources: frontend/src/components/workspace/messages/message-group.tsx78 frontend/src/core/messages/utils.ts36-155

---

Artifact and Code Rendering

Specialized components handle non-text content:

Artifact Content

The ArtifactFileDetail component handles detailed file viewing. It supports code editing via CodeEditor and preview modes for HTML/Markdown using SafeStreamdown. frontend/src/components/workspace/artifacts/artifact-file-detail.tsx31-50 It also includes a skill installation flow for .skill files via installSkill. frontend/src/components/workspace/artifacts/artifact-file-detail.tsx195-218

Artifact List

ArtifactFileList renders a list of files as cards, allowing users to download files via urlOfArtifact or install them if they are skills. frontend/src/components/workspace/artifacts/artifact-file-list.tsx83-133

Sources: frontend/src/components/workspace/artifacts/artifact-file-detail.tsx71-218 frontend/src/components/workspace/artifacts/artifact-file-list.tsx26-135

---

Subtask Tracking

When the agent uses the task tool, the rendering system switches to a subtask-centric view using SubtaskCard.

1. Subtask Identification: getMessageGroups identifies assistant:subagent groups when an AI message contains task tool calls. frontend/src/core/messages/utils.ts125-130
2. SubtaskCard: MessageList renders a SubtaskCard for each delegated task, providing a dedicated timeline for the subagent's execution. frontend/src/components/workspace/messages/message-list.tsx355-366
3. Step Backfilling: On expansion, SubtaskCard fetches historical steps for a task via fetchSubtaskSteps. frontend/src/components/workspace/messages/subtask-card.tsx85-103
4. Token Usage: Displays subagent-specific token usage and model labels. frontend/src/components/workspace/messages/subtask-card.tsx64-74

Sources: frontend/src/components/workspace/messages/subtask-card.tsx46-195 frontend/src/core/messages/utils.ts125-130

---

Internal Control Messages

The system uses special control messages to manage state (e.g., thread summaries or reminders), which are explicitly hidden from the UI by the getMessageGroups logic using the HIDDEN_CONTROL_MESSAGE_NAMES set. frontend/src/core/messages/utils.ts29-34

Hidden messages include:

• summary
• loop_warning
• todo_reminder
• todo_completion_reminder

Sources: frontend/src/core/messages/utils.ts29-62