Decode bytes-like tool response text fields safely

Co-authored-by: Shri Sukhani <shrisukhani@users.noreply.github.com>

Author: cursoragent

hyperbrowser/tools/__init__.py

@@ -163,6 +163,26 @@ def _serialize_extract_tool_data(data: Any) -> str:
         ) from exc
 
 
+def _normalize_optional_text_field_value(
+    field_value: Any,
+    *,
+    error_message: str,
+) -> str:
+    if field_value is None:
+        return ""
+    if isinstance(field_value, str):
+        return field_value
+    if isinstance(field_value, (bytes, bytearray, memoryview)):
+        try:
+            return memoryview(field_value).tobytes().decode("utf-8")
+        except (TypeError, ValueError, UnicodeDecodeError) as exc:
+            raise HyperbrowserError(
+                error_message,
+                original_error=exc,
+            ) from exc
+    raise HyperbrowserError(error_message)
+
+
 def _read_tool_response_data(response: Any, *, tool_name: str) -> Any:
     if isinstance(response, MappingABC):
         try:
@@ -232,11 +252,12 @@ def _read_optional_tool_response_field(
             ) from exc
     if field_value is None:
         return ""
-    if not isinstance(field_value, str):
-        raise HyperbrowserError(
-            f"{tool_name} response field '{field_name}' must be a string"
-        )
-    return field_value
+    return _normalize_optional_text_field_value(
+        field_value,
+        error_message=(
+            f"{tool_name} response field '{field_name}' must be a UTF-8 string"
+        ),
+    )
 
 
 def _read_crawl_page_field(page: Any, *, field_name: str, page_index: int) -> Any:
@@ -290,20 +311,25 @@ def _render_crawl_markdown_output(response_data: Any) -> str:
         )
         if page_markdown is None:
             continue
-        if not isinstance(page_markdown, str):
-            raise HyperbrowserError(
-                f"crawl tool page field 'markdown' must be a string at index {index}"
-            )
+        page_markdown = _normalize_optional_text_field_value(
+            page_markdown,
+            error_message=(
+                "crawl tool page field 'markdown' must be a UTF-8 string "
+                f"at index {index}"
+            ),
+        )
         if not page_markdown:
             continue
         page_url = _read_crawl_page_field(page, field_name="url", page_index=index)
         if page_url is None:
             page_url_display = "<unknown url>"
-        elif not isinstance(page_url, str):
-            raise HyperbrowserError(
-                f"crawl tool page field 'url' must be a string at index {index}"
-            )
         else:
+            page_url = _normalize_optional_text_field_value(
+                page_url,
+                error_message=(
+                    f"crawl tool page field 'url' must be a UTF-8 string at index {index}"
+                ),
+            )
             page_url_display = page_url if page_url.strip() else "<unknown url>"
         markdown_sections.append(
             f"\n{'-' * 50}\nUrl: {page_url_display}\nMarkdown:\n{page_markdown}\n"

tests/test_tools_response_handling.py

@@ -269,11 +269,33 @@ def test_scrape_tool_rejects_non_string_markdown_field():
 
     with pytest.raises(
         HyperbrowserError,
-        match="scrape tool response field 'markdown' must be a string",
+        match="scrape tool response field 'markdown' must be a UTF-8 string",
     ):
         WebsiteScrapeTool.runnable(client, {"url": "https://example.com"})
 
 
+def test_scrape_tool_decodes_utf8_bytes_markdown_field():
+    client = _SyncScrapeClient(_Response(data=SimpleNamespace(markdown=b"hello")))
+
+    output = WebsiteScrapeTool.runnable(client, {"url": "https://example.com"})
+
+    assert output == "hello"
+
+
+def test_scrape_tool_wraps_invalid_utf8_markdown_bytes():
+    client = _SyncScrapeClient(
+        _Response(data=SimpleNamespace(markdown=b"\xff\xfe\xfd"))
+    )
+
+    with pytest.raises(
+        HyperbrowserError,
+        match="scrape tool response field 'markdown' must be a UTF-8 string",
+    ) as exc_info:
+        WebsiteScrapeTool.runnable(client, {"url": "https://example.com"})
+
+    assert exc_info.value.original_error is not None
+
+
 def test_scrape_tool_supports_mapping_response_data():
     client = _SyncScrapeClient(_Response(data={"markdown": "from mapping"}))
 
@@ -318,11 +340,19 @@ def test_screenshot_tool_rejects_non_string_screenshot_field():
 
     with pytest.raises(
         HyperbrowserError,
-        match="screenshot tool response field 'screenshot' must be a string",
+        match="screenshot tool response field 'screenshot' must be a UTF-8 string",
     ):
         WebsiteScreenshotTool.runnable(client, {"url": "https://example.com"})
 
 
+def test_screenshot_tool_decodes_utf8_bytes_field():
+    client = _SyncScrapeClient(_Response(data=SimpleNamespace(screenshot=b"image-data")))
+
+    output = WebsiteScreenshotTool.runnable(client, {"url": "https://example.com"})
+
+    assert output == "image-data"
+
+
 def test_crawl_tool_rejects_non_list_response_data():
     client = _SyncCrawlClient(_Response(data={"invalid": "payload"}))
 
@@ -407,11 +437,36 @@ def test_crawl_tool_rejects_non_string_page_urls():
 
     with pytest.raises(
         HyperbrowserError,
-        match="crawl tool page field 'url' must be a string at index 0",
+        match="crawl tool page field 'url' must be a UTF-8 string at index 0",
     ):
         WebsiteCrawlTool.runnable(client, {"url": "https://example.com"})
 
 
+def test_crawl_tool_decodes_utf8_bytes_page_fields():
+    client = _SyncCrawlClient(
+        _Response(data=[SimpleNamespace(url=b"https://example.com", markdown=b"page")])
+    )
+
+    output = WebsiteCrawlTool.runnable(client, {"url": "https://example.com"})
+
+    assert "Url: https://example.com" in output
+    assert "page" in output
+
+
+def test_crawl_tool_wraps_invalid_utf8_page_field_bytes():
+    client = _SyncCrawlClient(
+        _Response(data=[SimpleNamespace(url=b"\xff", markdown="body")])
+    )
+
+    with pytest.raises(
+        HyperbrowserError,
+        match="crawl tool page field 'url' must be a UTF-8 string at index 0",
+    ) as exc_info:
+        WebsiteCrawlTool.runnable(client, {"url": "https://example.com"})
+
+    assert exc_info.value.original_error is not None
+
+
 def test_crawl_tool_uses_unknown_url_for_blank_page_urls():
     client = _SyncCrawlClient(
         _Response(data=[SimpleNamespace(url="   ", markdown="page body")])
@@ -443,11 +498,19 @@ def test_browser_use_tool_rejects_non_string_final_result():
 
     with pytest.raises(
         HyperbrowserError,
-        match="browser-use tool response field 'final_result' must be a string",
+        match="browser-use tool response field 'final_result' must be a UTF-8 string",
     ):
         BrowserUseTool.runnable(client, {"task": "search docs"})
 
 
+def test_browser_use_tool_decodes_utf8_bytes_final_result():
+    client = _SyncBrowserUseClient(_Response(data=SimpleNamespace(final_result=b"done")))
+
+    output = BrowserUseTool.runnable(client, {"task": "search docs"})
+
+    assert output == "done"
+
+
 def test_browser_use_tool_supports_mapping_response_data():
     client = _SyncBrowserUseClient(_Response(data={"final_result": "mapping output"}))
 
@@ -520,7 +583,7 @@ async def run() -> None:
         )
         with pytest.raises(
             HyperbrowserError,
-            match="browser-use tool response field 'final_result' must be a string",
+            match="browser-use tool response field 'final_result' must be a UTF-8 string",
         ):
             await BrowserUseTool.async_runnable(client, {"task": "search docs"})
 
@@ -539,6 +602,18 @@ async def run() -> None:
     asyncio.run(run())
 
 
+def test_async_scrape_tool_decodes_utf8_bytes_markdown_field():
+    async def run() -> None:
+        client = _AsyncScrapeClient(_Response(data=SimpleNamespace(markdown=b"async")))
+        output = await WebsiteScrapeTool.async_runnable(
+            client,
+            {"url": "https://example.com"},
+        )
+        assert output == "async"
+
+    asyncio.run(run())
+
+
 def test_async_crawl_tool_supports_mapping_page_items():
     async def run() -> None:
         client = _AsyncCrawlClient(