Harden tool parameter mapping normalization

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

Author: cursoragent

hyperbrowser/tools/__init__.py

@@ -23,6 +23,24 @@
     CRAWL_TOOL_ANTHROPIC,
 )
 
+_MAX_KEY_DISPLAY_LENGTH = 120
+_TRUNCATED_KEY_DISPLAY_SUFFIX = "... (truncated)"
+
+
+def _format_tool_param_key_for_error(key: str) -> str:
+    normalized_key = "".join(
+        "?" if ord(character) < 32 or ord(character) == 127 else character
+        for character in key
+    ).strip()
+    if not normalized_key:
+        return "<blank key>"
+    if len(normalized_key) <= _MAX_KEY_DISPLAY_LENGTH:
+        return normalized_key
+    available_length = _MAX_KEY_DISPLAY_LENGTH - len(_TRUNCATED_KEY_DISPLAY_SUFFIX)
+    if available_length <= 0:
+        return _TRUNCATED_KEY_DISPLAY_SUFFIX
+    return f"{normalized_key[:available_length]}{_TRUNCATED_KEY_DISPLAY_SUFFIX}"
+
 
 def _prepare_extract_tool_params(params: Mapping[str, Any]) -> Dict[str, Any]:
     normalized_params = _to_param_dict(params)
@@ -41,7 +59,32 @@ def _prepare_extract_tool_params(params: Mapping[str, Any]) -> Dict[str, Any]:
 def _to_param_dict(params: Mapping[str, Any]) -> Dict[str, Any]:
     if not isinstance(params, Mapping):
         raise HyperbrowserError("tool params must be a mapping")
-    return dict(params)
+    try:
+        param_keys = list(params.keys())
+    except HyperbrowserError:
+        raise
+    except Exception as exc:
+        raise HyperbrowserError(
+            "Failed to read tool params keys",
+            original_error=exc,
+        ) from exc
+    for key in param_keys:
+        if isinstance(key, str):
+            continue
+        raise HyperbrowserError("tool params keys must be strings")
+    normalized_params: Dict[str, Any] = {}
+    for key in param_keys:
+        try:
+            normalized_params[key] = params[key]
+        except HyperbrowserError:
+            raise
+        except Exception as exc:
+            key_display = _format_tool_param_key_for_error(key)
+            raise HyperbrowserError(
+                f"Failed to read tool param '{key_display}'",
+                original_error=exc,
+            ) from exc
+    return normalized_params
 
 
 class WebsiteScrapeTool:

tests/test_tools_mapping_inputs.py

@@ -1,6 +1,7 @@
+import asyncio
+from collections.abc import Iterator, Mapping
 from types import MappingProxyType
 
-import asyncio
 import pytest
 
 from hyperbrowser.exceptions import HyperbrowserError
@@ -95,3 +96,75 @@ async def run() -> None:
             )
 
     asyncio.run(run())
+
+
+def test_tool_wrappers_reject_non_string_param_keys():
+    client = _Client()
+
+    with pytest.raises(HyperbrowserError, match="tool params keys must be strings"):
+        WebsiteScrapeTool.runnable(
+            client,
+            {1: "https://example.com"},  # type: ignore[dict-item]
+        )
+
+
+def test_tool_wrappers_wrap_param_key_read_failures():
+    class _BrokenKeyMapping(Mapping[str, object]):
+        def __iter__(self) -> Iterator[str]:
+            raise RuntimeError("cannot iterate keys")
+
+        def __len__(self) -> int:
+            return 1
+
+        def __getitem__(self, key: str) -> object:
+            _ = key
+            return "ignored"
+
+    client = _Client()
+
+    with pytest.raises(HyperbrowserError, match="Failed to read tool params keys") as exc_info:
+        WebsiteScrapeTool.runnable(client, _BrokenKeyMapping())
+
+    assert exc_info.value.original_error is not None
+
+
+def test_tool_wrappers_wrap_param_value_read_failures():
+    class _BrokenValueMapping(Mapping[str, object]):
+        def __iter__(self) -> Iterator[str]:
+            yield "url"
+
+        def __len__(self) -> int:
+            return 1
+
+        def __getitem__(self, key: str) -> object:
+            _ = key
+            raise RuntimeError("cannot read value")
+
+    client = _Client()
+
+    with pytest.raises(HyperbrowserError, match="Failed to read tool param 'url'") as exc_info:
+        WebsiteScrapeTool.runnable(client, _BrokenValueMapping())
+
+    assert exc_info.value.original_error is not None
+
+
+def test_tool_wrappers_preserve_hyperbrowser_param_value_read_failures():
+    class _BrokenValueMapping(Mapping[str, object]):
+        def __iter__(self) -> Iterator[str]:
+            yield "url"
+
+        def __len__(self) -> int:
+            return 1
+
+        def __getitem__(self, key: str) -> object:
+            _ = key
+            raise HyperbrowserError("custom param value read failure")
+
+    client = _Client()
+
+    with pytest.raises(
+        HyperbrowserError, match="custom param value read failure"
+    ) as exc_info:
+        WebsiteScrapeTool.runnable(client, _BrokenValueMapping())
+
+    assert exc_info.value.original_error is None