fix: normalize structured LLM content in serialization and memory updater (#1215)

* fix: normalize ToolMessage structured content in serialization

When models return ToolMessage content as a list of content blocks
(e.g. [{"type": "text", "text": "..."}]), the UI previously displayed
the raw Python repr string instead of the extracted text.

Replace str(msg.content) with the existing _extract_text() helper in
both _serialize_message() and stream() to properly normalize
list-of-blocks content to plain text.

Fixes #1149

Also fixes the same root cause as #1188 (characters displayed one per
line when tool response content is returned as structured blocks).

Added 11 regression tests covering string, list-of-blocks, mixed,
empty, and fallback content types.

* fix(memory): extract text from structured LLM responses in memory updater

When LLMs return response content as list of content blocks
(e.g. [{"type": "text", "text": "..."}]) instead of plain strings,
str() produces Python repr which breaks JSON parsing in the memory
updater. This caused memory updates to silently fail.

Changes:
- Add _extract_text() helper in updater.py for safe content normalization
- Use _extract_text() instead of str(response.content) in update_memory()
- Fix format_conversation_for_update() to handle plain strings in list content
- Fix subagent executor fallback path to extract text from list content
- Replace print() with structured logging (logger.info/warning/error)
- Add 13 regression tests covering _extract_text, format_conversation,
  and update_memory with structured LLM responses

* fix: address Copilot review - defensive text extraction + logger.exception

- client.py _extract_text: use block.get('text') + isinstance check (prevent KeyError/TypeError)
- prompt.py format_conversation_for_update: same defensive check for dict text blocks
- executor.py: type-safe text extraction in both code paths, fallback to placeholder instead of str(raw_content)
- updater.py: use logger.exception() instead of logger.error() for traceback preservation

* Apply suggestions from code review

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* fix: preserve chunked structured content without spurious newlines

* fix: restore backend unit test compatibility

---------

Co-authored-by: Exploreunive <Exploreunive@users.noreply.github.com>
Co-authored-by: Willem Jiang <willem.jiang@gmail.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

backend/tests/test_checkpointer.py

@@ -5,6 +5,7 @@ from unittest.mock import MagicMock, patch
 
 import pytest
 
+import deerflow.config.app_config as app_config_module
 from deerflow.agents.checkpointer import get_checkpointer, reset_checkpointer
 from deerflow.config.checkpointer_config import (
     CheckpointerConfig,
@@ -17,9 +18,11 @@ from deerflow.config.checkpointer_config import (
 @pytest.fixture(autouse=True)
 def reset_state():
     """Reset singleton state before each test."""
+    app_config_module._app_config = None
     set_checkpointer_config(None)
     reset_checkpointer()
     yield
+    app_config_module._app_config = None
     set_checkpointer_config(None)
     reset_checkpointer()
 
@@ -75,7 +78,8 @@ class TestGetCheckpointer:
         """get_checkpointer should return InMemorySaver when not configured."""
         from langgraph.checkpoint.memory import InMemorySaver
 
-        cp = get_checkpointer()
+        with patch("deerflow.agents.checkpointer.provider.get_app_config", side_effect=FileNotFoundError):
+            cp = get_checkpointer()
         assert cp is not None
         assert isinstance(cp, InMemorySaver)
 

backend/tests/test_memory_updater.py

@@ -1,6 +1,7 @@
-from unittest.mock import patch
+from unittest.mock import MagicMock, patch
 
-from deerflow.agents.memory.updater import MemoryUpdater
+from deerflow.agents.memory.prompt import format_conversation_for_update
+from deerflow.agents.memory.updater import MemoryUpdater, _extract_text
 from deerflow.config.memory_config import MemoryConfig
 
 
@@ -135,3 +136,153 @@ def test_apply_updates_preserves_threshold_and_max_facts_trimming() -> None:
     ]
     assert all(fact["content"] != "User likes noisy logs" for fact in result["facts"])
     assert result["facts"][1]["source"] == "thread-9"
+
+
+# ---------------------------------------------------------------------------
+# _extract_text — LLM response content normalization
+# ---------------------------------------------------------------------------
+
+
+class TestExtractText:
+    """_extract_text should normalize all content shapes to plain text."""
+
+    def test_string_passthrough(self):
+        assert _extract_text("hello world") == "hello world"
+
+    def test_list_single_text_block(self):
+        assert _extract_text([{"type": "text", "text": "hello"}]) == "hello"
+
+    def test_list_multiple_text_blocks_joined(self):
+        content = [
+            {"type": "text", "text": "part one"},
+            {"type": "text", "text": "part two"},
+        ]
+        assert _extract_text(content) == "part one\npart two"
+
+    def test_list_plain_strings(self):
+        assert _extract_text(["raw string"]) == "raw string"
+
+    def test_list_string_chunks_join_without_separator(self):
+        content = ["{\"user\"", ': "alice"}']
+        assert _extract_text(content) == '{"user": "alice"}'
+
+    def test_list_mixed_strings_and_blocks(self):
+        content = [
+            "raw text",
+            {"type": "text", "text": "block text"},
+        ]
+        assert _extract_text(content) == "raw text\nblock text"
+
+    def test_list_adjacent_string_chunks_then_block(self):
+        content = [
+            "prefix",
+            "-continued",
+            {"type": "text", "text": "block text"},
+        ]
+        assert _extract_text(content) == "prefix-continued\nblock text"
+
+    def test_list_skips_non_text_blocks(self):
+        content = [
+            {"type": "image_url", "image_url": {"url": "http://img.png"}},
+            {"type": "text", "text": "actual text"},
+        ]
+        assert _extract_text(content) == "actual text"
+
+    def test_empty_list(self):
+        assert _extract_text([]) == ""
+
+    def test_list_no_text_blocks(self):
+        assert _extract_text([{"type": "image_url", "image_url": {}}]) == ""
+
+    def test_non_str_non_list(self):
+        assert _extract_text(42) == "42"
+
+
+# ---------------------------------------------------------------------------
+# format_conversation_for_update — handles mixed list content
+# ---------------------------------------------------------------------------
+
+
+class TestFormatConversationForUpdate:
+    def test_plain_string_messages(self):
+        human_msg = MagicMock()
+        human_msg.type = "human"
+        human_msg.content = "What is Python?"
+
+        ai_msg = MagicMock()
+        ai_msg.type = "ai"
+        ai_msg.content = "Python is a programming language."
+
+        result = format_conversation_for_update([human_msg, ai_msg])
+        assert "User: What is Python?" in result
+        assert "Assistant: Python is a programming language." in result
+
+    def test_list_content_with_plain_strings(self):
+        """Plain strings in list content should not be lost."""
+        msg = MagicMock()
+        msg.type = "human"
+        msg.content = ["raw user text", {"type": "text", "text": "structured text"}]
+
+        result = format_conversation_for_update([msg])
+        assert "raw user text" in result
+        assert "structured text" in result
+
+
+# ---------------------------------------------------------------------------
+# update_memory — structured LLM response handling
+# ---------------------------------------------------------------------------
+
+
+class TestUpdateMemoryStructuredResponse:
+    """update_memory should handle LLM responses returned as list content blocks."""
+
+    def _make_mock_model(self, content):
+        model = MagicMock()
+        response = MagicMock()
+        response.content = content
+        model.invoke.return_value = response
+        return model
+
+    def test_string_response_parses(self):
+        updater = MemoryUpdater()
+        valid_json = '{"user": {}, "history": {}, "newFacts": [], "factsToRemove": []}'
+
+        with (
+            patch.object(updater, "_get_model", return_value=self._make_mock_model(valid_json)),
+            patch("deerflow.agents.memory.updater.get_memory_config", return_value=_memory_config(enabled=True)),
+            patch("deerflow.agents.memory.updater.get_memory_data", return_value=_make_memory()),
+            patch("deerflow.agents.memory.updater._save_memory_to_file", return_value=True),
+        ):
+            msg = MagicMock()
+            msg.type = "human"
+            msg.content = "Hello"
+            ai_msg = MagicMock()
+            ai_msg.type = "ai"
+            ai_msg.content = "Hi there"
+            ai_msg.tool_calls = []
+            result = updater.update_memory([msg, ai_msg])
+
+        assert result is True
+
+    def test_list_content_response_parses(self):
+        """LLM response as list-of-blocks should be extracted, not repr'd."""
+        updater = MemoryUpdater()
+        valid_json = '{"user": {}, "history": {}, "newFacts": [], "factsToRemove": []}'
+        list_content = [{"type": "text", "text": valid_json}]
+
+        with (
+            patch.object(updater, "_get_model", return_value=self._make_mock_model(list_content)),
+            patch("deerflow.agents.memory.updater.get_memory_config", return_value=_memory_config(enabled=True)),
+            patch("deerflow.agents.memory.updater.get_memory_data", return_value=_make_memory()),
+            patch("deerflow.agents.memory.updater._save_memory_to_file", return_value=True),
+        ):
+            msg = MagicMock()
+            msg.type = "human"
+            msg.content = "Hello"
+            ai_msg = MagicMock()
+            ai_msg.type = "ai"
+            ai_msg.content = "Hi"
+            ai_msg.tool_calls = []
+            result = updater.update_memory([msg, ai_msg])
+
+        assert result is True

backend/tests/test_serialize_message_content.py

@@ -0,0 +1,129 @@
+"""Regression tests for ToolMessage content normalization in serialization.
+
+Ensures that structured content (list-of-blocks) is properly extracted to
+plain text, preventing raw Python repr strings from reaching the UI.
+
+See: https://github.com/bytedance/deer-flow/issues/1149
+"""
+
+from langchain_core.messages import ToolMessage
+
+from deerflow.client import DeerFlowClient
+
+# ---------------------------------------------------------------------------
+# _serialize_message
+# ---------------------------------------------------------------------------
+
+
+class TestSerializeToolMessageContent:
+    """DeerFlowClient._serialize_message should normalize ToolMessage content."""
+
+    def test_string_content(self):
+        msg = ToolMessage(content="ok", tool_call_id="tc1", name="search")
+        result = DeerFlowClient._serialize_message(msg)
+        assert result["content"] == "ok"
+        assert result["type"] == "tool"
+
+    def test_list_of_blocks_content(self):
+        """List-of-blocks should be extracted, not repr'd."""
+        msg = ToolMessage(
+            content=[{"type": "text", "text": "hello world"}],
+            tool_call_id="tc1",
+            name="search",
+        )
+        result = DeerFlowClient._serialize_message(msg)
+        assert result["content"] == "hello world"
+        # Must NOT contain Python repr artifacts
+        assert "[" not in result["content"]
+        assert "{" not in result["content"]
+
+    def test_multiple_text_blocks(self):
+        """Multiple full text blocks should be joined with newlines."""
+        msg = ToolMessage(
+            content=[
+                {"type": "text", "text": "line 1"},
+                {"type": "text", "text": "line 2"},
+            ],
+            tool_call_id="tc1",
+            name="search",
+        )
+        result = DeerFlowClient._serialize_message(msg)
+        assert result["content"] == "line 1\nline 2"
+
+    def test_string_chunks_are_joined_without_newlines(self):
+        """Chunked string payloads should not get artificial separators."""
+        msg = ToolMessage(
+            content=["{\"a\"", ": \"b\"}"] ,
+            tool_call_id="tc1",
+            name="search",
+        )
+        result = DeerFlowClient._serialize_message(msg)
+        assert result["content"] == '{"a": "b"}'
+
+    def test_mixed_string_chunks_and_blocks(self):
+        """String chunks stay contiguous, but text blocks remain separated."""
+        msg = ToolMessage(
+            content=["prefix", "-continued", {"type": "text", "text": "block text"}],
+            tool_call_id="tc1",
+            name="search",
+        )
+        result = DeerFlowClient._serialize_message(msg)
+        assert result["content"] == "prefix-continued\nblock text"
+
+    def test_mixed_blocks_with_non_text(self):
+        """Non-text blocks (e.g. image) should be skipped gracefully."""
+        msg = ToolMessage(
+            content=[
+                {"type": "text", "text": "found results"},
+                {"type": "image_url", "image_url": {"url": "http://img.png"}},
+            ],
+            tool_call_id="tc1",
+            name="view_image",
+        )
+        result = DeerFlowClient._serialize_message(msg)
+        assert result["content"] == "found results"
+
+    def test_empty_list_content(self):
+        msg = ToolMessage(content=[], tool_call_id="tc1", name="search")
+        result = DeerFlowClient._serialize_message(msg)
+        assert result["content"] == ""
+
+    def test_plain_string_in_list(self):
+        """Bare strings inside a list should be kept."""
+        msg = ToolMessage(
+            content=["plain text block"],
+            tool_call_id="tc1",
+            name="search",
+        )
+        result = DeerFlowClient._serialize_message(msg)
+        assert result["content"] == "plain text block"
+
+    def test_unknown_content_type_falls_back(self):
+        """Unexpected types should not crash — return str()."""
+        msg = ToolMessage(content=42, tool_call_id="tc1", name="calc")
+        result = DeerFlowClient._serialize_message(msg)
+        # int → not str, not list → falls to str()
+        assert result["content"] == "42"
+
+
+# ---------------------------------------------------------------------------
+# _extract_text (already existed, but verify it also covers ToolMessage paths)
+# ---------------------------------------------------------------------------
+
+
+class TestExtractText:
+    """DeerFlowClient._extract_text should handle all content shapes."""
+
+    def test_string_passthrough(self):
+        assert DeerFlowClient._extract_text("hello") == "hello"
+
+    def test_list_text_blocks(self):
+        assert DeerFlowClient._extract_text(
+            [{"type": "text", "text": "hi"}]
+        ) == "hi"
+
+    def test_empty_list(self):
+        assert DeerFlowClient._extract_text([]) == ""
+
+    def test_fallback_non_iterable(self):
+        assert DeerFlowClient._extract_text(123) == "123"