fix: address PR #89 review feedback on role coercion and fallback messages

Author: clean6378-max-it

tests/test_jsonl_parser.py

@@ -988,16 +988,34 @@ def test_unknown_entry_type_maps_to_system_with_warning(self, caplog):
             ]
         )
         try:
-            with caplog.at_level("WARNING"):
+            with caplog.at_level("WARNING", logger="utils.jsonl_parser"):
                 s = parse_session(path)
             assert len(s["messages"]) == 1
             assert s["messages"][0]["role"] == "system"
+            assert s["messages"][0]["text"] == "forward-compat payload"
             assert s["messages"][0]["content"] == "forward-compat payload"
             assert "Unknown message role" in caplog.text
             assert "mystery_future_type" in caplog.text
         finally:
             os.unlink(path)
 
+    def test_fallback_message_extracts_text_from_structured_content(self):
+        path = _write_jsonl(
+            [
+                {
+                    "type": "result",
+                    "timestamp": "2026-01-01T00:00:00Z",
+                    "content": [{"type": "text", "text": "block body"}],
+                }
+            ]
+        )
+        try:
+            s = parse_session(path)
+            assert s["messages"][0]["text"] == "block body"
+            assert s["messages"][0]["content"] == "block body"
+        finally:
+            os.unlink(path)
+
     def test_valid_unhandled_result_type_emits_result_role(self):
         path = _write_jsonl(
             [
@@ -1014,3 +1032,19 @@ def test_valid_unhandled_result_type_emits_result_role(self):
             assert s["messages"][0]["role"] == "result"
         finally:
             os.unlink(path)
+
+
+class TestCoerceRole:
+    def test_known_roles_returned_unchanged(self):
+        from utils.jsonl_parser import _coerce_role
+
+        for role in ("user", "assistant", "system", "result", "progress"):
+            assert _coerce_role(role) == role
+
+    def test_unknown_role_maps_to_system_with_warning(self, caplog):
+        from utils.jsonl_parser import _coerce_role
+
+        with caplog.at_level("WARNING", logger="utils.jsonl_parser"):
+            result = _coerce_role("totally_unknown")
+        assert result == "system"
+        assert "totally_unknown" in caplog.text

utils/jsonl_parser.py

@@ -24,27 +24,33 @@
 
 __all__ = ["parse_session", "quick_session_info"]
 
-_HANDLED_ENTRY_TYPES = frozenset({"user", "assistant", "system", "progress"})
 _SKIP_ENTRY_TYPES = frozenset({"file-history-snapshot"})
 _VALID_ROLES = frozenset(get_args(RoleLiteral))
+_log = logging.getLogger(__name__)
 
 
 def _coerce_role(raw: str) -> RoleLiteral:
     if raw in _VALID_ROLES:
         return cast(RoleLiteral, raw)
-    logging.warning("Unknown message role %r; mapping to 'system'", raw)
+    _log.warning("Unknown message role %r; mapping to 'system'", raw)
     return "system"
 
 
 def _fallback_message(entry: dict[str, Any], role: RoleLiteral) -> MessageDict:
     """Minimal message for JSONL entry types without a dedicated processor."""
-    content = entry.get("content", "")
-    text = content if isinstance(content, str) else (str(content) if content is not None else "")
+    raw_content = entry.get("content", "")
+    if isinstance(raw_content, str):
+        text = raw_content
+    elif raw_content is not None:
+        text = _extract_text(_normalize_content(raw_content))
+    else:
+        text = ""
     return {
         "role": role,
         "uuid": entry.get("uuid"),
         "parent_uuid": entry.get("parentUuid"),
         "timestamp": entry.get("timestamp"),
+        "text": text,
         "content": text,
         "is_sidechain": entry.get("isSidechain", False),
     }
@@ -155,7 +161,7 @@ def parse_session(filepath: str) -> SessionDict:
                 _process_progress(entry, messages)
             elif entry_type:
                 type_str = entry_type if isinstance(entry_type, str) else str(entry_type)
-                if type_str not in _HANDLED_ENTRY_TYPES and type_str not in _SKIP_ENTRY_TYPES:
+                if type_str not in _SKIP_ENTRY_TYPES:
                     messages.append(_fallback_message(entry, _coerce_role(type_str)))
 
     metadata["models_used"] = sorted(metadata["models_used"])