hud-python 0.4.45__py3-none-any.whl → 0.5.13__py3-none-any.whl

hud/server/tests/test_mcp_server_integration.py

@@ -84,7 +84,7 @@ async def test_initialize_runs_once_and_tools_work() -> None:
 
     async def connect_and_check() -> None:
         cfg = {"srv": {"url": f"http://127.0.0.1:{port}/mcp"}}
-        client = MCPClient(mcp_config=cfg, auto_trace=False, verbose=False)
+        client = MCPClient(mcp_config=cfg, verbose=False)
         await client.initialize()
         tools = await client.list_tools()
         names = sorted(t.name for t in tools)
@@ -123,7 +123,7 @@ async def test_shutdown_handler_only_on_sigterm_flag() -> None:
     try:
         # sanity connect so lifespan actually ran
         cfg = {"srv": {"url": f"http://127.0.0.1:{port}/mcp"}}
-        c = MCPClient(mcp_config=cfg, auto_trace=False, verbose=False)
+        c = MCPClient(mcp_config=cfg, verbose=False)
         await c.initialize()
         await c.shutdown()
     finally:
@@ -140,7 +140,7 @@ async def test_shutdown_handler_only_on_sigterm_flag() -> None:
     server_task2 = await _start_http_server(mcp, port=port2)
     try:
         cfg = {"srv": {"url": f"http://127.0.0.1:{port2}/mcp"}}
-        c = MCPClient(mcp_config=cfg, auto_trace=False, verbose=False)
+        c = MCPClient(mcp_config=cfg, verbose=False)
         await c.initialize()
         await c.shutdown()
 
@@ -170,7 +170,7 @@ async def test_initializer_exception_propagates_to_client() -> None:
     server_task = await _start_http_server(mcp, port)
 
     cfg = {"srv": {"url": f"http://127.0.0.1:{port}/mcp"}}
-    client = MCPClient(mcp_config=cfg, auto_trace=False, verbose=False)
+    client = MCPClient(mcp_config=cfg, verbose=False)
 
     try:
         with pytest.raises(Exception):
@@ -211,7 +211,7 @@ async def test_init_after_tools_preserves_handlers_and_runs_once() -> None:
 
     async def connect_and_check() -> None:
         cfg = {"srv": {"url": f"http://127.0.0.1:{port}/mcp"}}
-        c = MCPClient(mcp_config=cfg, auto_trace=False, verbose=False)
+        c = MCPClient(mcp_config=cfg, verbose=False)
         await c.initialize()
         tools = await c.list_tools()
         names = sorted(t.name for t in tools)
@@ -244,7 +244,7 @@ async def test_tool_default_argument_used_when_omitted() -> None:
     server_task = await _start_http_server(mcp, port)
     try:
         cfg = {"srv": {"url": f"http://127.0.0.1:{port}/mcp"}}
-        c = MCPClient(mcp_config=cfg, auto_trace=False, verbose=False)
+        c = MCPClient(mcp_config=cfg, verbose=False)
         await c.initialize()
         # Call with no args → default should kick in
         res = await c.call_tool(name="echo", arguments={})
@@ -273,7 +273,7 @@ async def test_shutdown_handler_runs_once_when_both_paths_fire() -> None:
     try:
         # Ensure lifespan started
         cfg = {"srv": {"url": f"http://127.0.0.1:{port}/mcp"}}
-        c = MCPClient(mcp_config=cfg, auto_trace=False, verbose=False)
+        c = MCPClient(mcp_config=cfg, verbose=False)
         await c.initialize()
         await c.shutdown()
 
@@ -315,7 +315,7 @@ async def test_initialize_ctx_exposes_client_info() -> None:
     server_task = await _start_http_server(mcp, port)
     try:
         cfg = {"srv": {"url": f"http://127.0.0.1:{port}/mcp"}}
-        c = MCPClient(mcp_config=cfg, auto_trace=False, verbose=False)
+        c = MCPClient(mcp_config=cfg, verbose=False)
         await c.initialize()
         await c.shutdown()
     finally:
@@ -344,7 +344,7 @@ async def test_initialize_redirects_stdout_to_stderr(capsys) -> None:
 
     try:
         cfg = {"srv": {"url": f"http://127.0.0.1:{port}/mcp"}}
-        c = MCPClient(mcp_config=cfg, auto_trace=False, verbose=False)
+        c = MCPClient(mcp_config=cfg, verbose=False)
         await c.initialize()
         await c.shutdown()
     finally:
@@ -373,11 +373,11 @@ async def test_initialize_callable_form_runs_once() -> None:
     server_task = await _start_http_server(mcp, port)
     try:
         cfg = {"srv": {"url": f"http://127.0.0.1:{port}/mcp"}}
-        c1 = MCPClient(mcp_config=cfg, auto_trace=False, verbose=False)
+        c1 = MCPClient(mcp_config=cfg, verbose=False)
         await c1.initialize()
         await c1.shutdown()
 
-        c2 = MCPClient(mcp_config=cfg, auto_trace=False, verbose=False)
+        c2 = MCPClient(mcp_config=cfg, verbose=False)
         await c2.initialize()
         await c2.shutdown()
     finally:

hud/server/tests/test_mcp_server_more.py

@@ -142,7 +142,7 @@ async def test_last_initialize_handler_wins_and_ctx_shape_exists() -> None:
 
     try:
         cfg = {"srv": {"url": f"http://127.0.0.1:{port}/mcp"}}
-        c = MCPClient(mcp_config=cfg, auto_trace=False, verbose=False)
+        c = MCPClient(mcp_config=cfg, verbose=False)
         await c.initialize()
 
         # Call a tool to ensure init didn't break anything

hud/server/tests/test_server_extra.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 import asyncio
+import sys
 from contextlib import asynccontextmanager, suppress
 
 import anyio
@@ -98,6 +99,7 @@ async def test_last_shutdown_handler_wins(patch_stdio):
     server_mod._sigterm_received = False  # type: ignore[attr-defined]
 
 
+@pytest.mark.skipif(sys.platform == "win32", reason="asyncio.add_signal_handler is Unix-only")
 def test__run_with_sigterm_registers_handlers_when_enabled(monkeypatch: pytest.MonkeyPatch):
     """
     Verify that _run_with_sigterm attempts to register SIGTERM/SIGINT handlers

hud/settings.py

@@ -53,23 +53,35 @@ class Settings(BaseSettings):
         )
 
     hud_telemetry_url: str = Field(
-        default="https://telemetry.hud.so/v3/api",
+        default="https://telemetry.hud.ai/v3/api",
         description="Base URL for the HUD API",
         validation_alias="HUD_TELEMETRY_URL",
     )
 
     hud_mcp_url: str = Field(
-        default="https://mcp.hud.so/v3/mcp",
+        default="https://mcp.hud.ai/v3/mcp",
         description="Base URL for the MCP Server",
         validation_alias="HUD_MCP_URL",
     )
 
     hud_rl_url: str = Field(
-        default="https://rl.hud.so/v1",
+        default="https://rl.hud.ai/v1",
         description="Base URL for the HUD RL API server",
         validation_alias="HUD_RL_URL",
     )
 
+    hud_api_url: str = Field(
+        default="https://api.hud.ai",
+        description="Base URL for the HUD API server",
+        validation_alias="HUD_API_URL",
+    )
+
+    hud_gateway_url: str = Field(
+        default="https://inference.hud.ai",
+        description="Base URL for the HUD inference gateway",
+        validation_alias="HUD_GATEWAY_URL",
+    )
+
     api_key: str | None = Field(
         default=None,
         description="API key for authentication with the HUD API",
@@ -82,12 +94,36 @@ class Settings(BaseSettings):
         validation_alias="ANTHROPIC_API_KEY",
     )
 
+    aws_access_key_id: str | None = Field(
+        default=None,
+        description="AWS access key ID for Bedrock",
+        validation_alias="AWS_ACCESS_KEY_ID",
+    )
+
+    aws_secret_access_key: str | None = Field(
+        default=None,
+        description="AWS secret access key for Bedrock",
+        validation_alias="AWS_SECRET_ACCESS_KEY",
+    )
+
+    aws_region: str | None = Field(
+        default=None,
+        description="AWS region for Bedrock (e.g., us-east-1)",
+        validation_alias="AWS_REGION",
+    )
+
     openai_api_key: str | None = Field(
         default=None,
         description="API key for OpenAI models",
         validation_alias="OPENAI_API_KEY",
     )
 
+    gemini_api_key: str | None = Field(
+        default=None,
+        description="API key for Google Gemini models",
+        validation_alias="GEMINI_API_KEY",
+    )
+
     openrouter_api_key: str | None = Field(
         default=None,
         description="API key for OpenRouter models",
@@ -124,6 +160,12 @@ class Settings(BaseSettings):
         validation_alias="HUD_LOG_STREAM",
     )
 
+    client_timeout: int = Field(
+        default=900,
+        description="Timeout in seconds for MCP client operations (default: 900 = 15 minutes)",
+        validation_alias="HUD_CLIENT_TIMEOUT",
+    )
+
 
 # Create a singleton instance
 settings = Settings()

hud/shared/exceptions.py

@@ -69,11 +69,6 @@ class HudException(Exception):
             elif isinstance(exc_value, Exception):
                 # Try to convert to a specific HudException
                 result = cls._analyze_exception(exc_value, message or str(exc_value))
-                # If we couldn't categorize it (still base HudException),
-                # just re-raise the original exception
-                if type(result) is HudException:
-                    # Re-raise the original exception unchanged
-                    raise exc_value from None
                 return result
 
         # Normal creation
@@ -136,7 +131,7 @@ class HudException(Exception):
             ),
             (
                 lambda: ("api key" in error_msg or "authorization" in error_msg)
-                and ("hud" in error_msg or "mcp.hud.so" in error_msg),
+                and ("hud" in error_msg or "mcp.hud.ai" in error_msg),
                 HudAuthenticationError,
             ),
             (
@@ -190,11 +185,42 @@ class HudRequestError(HudException):
         self.response_text = response_text
         self.response_headers = response_headers
         # Compute default hints from status code if none provided
-        if hints is None and status_code in (401, 403, 429):
+        if hints is None and status_code in (401, 402, 403, 429):
             try:
-                from hud.shared.hints import HUD_API_KEY_MISSING, RATE_LIMIT_HIT  # type: ignore
-
-                if status_code in (401, 403):
+                from hud.shared.hints import (  # type: ignore
+                    CREDITS_EXHAUSTED,
+                    HUD_API_KEY_MISSING,
+                    PRO_PLAN_REQUIRED,
+                    RATE_LIMIT_HIT,
+                )
+
+                if status_code == 402:
+                    hints = [CREDITS_EXHAUSTED]
+                elif status_code == 403:
+                    # Default 403 to auth unless the message clearly indicates Pro plan
+                    combined_text = (message or "").lower()
+                    try:
+                        if response_text:
+                            combined_text += "\n" + str(response_text).lower()
+                    except Exception:  # noqa: S110
+                        pass
+                    try:
+                        if response_json and isinstance(response_json, dict):
+                            detail = response_json.get("detail")
+                            if isinstance(detail, str):
+                                combined_text += "\n" + detail.lower()
+                    except Exception:  # noqa: S110
+                        pass
+
+                    mentions_pro = (
+                        "pro plan" in combined_text
+                        or "requires pro" in combined_text
+                        or "pro mode" in combined_text
+                        or combined_text.strip().startswith("pro ")
+                    )
+
+                    hints = [PRO_PLAN_REQUIRED] if mentions_pro else [HUD_API_KEY_MISSING]
+                elif status_code == 401:
                     hints = [HUD_API_KEY_MISSING]
                 elif status_code == 429:
                     hints = [RATE_LIMIT_HIT]

hud/shared/hints.py

@@ -38,7 +38,7 @@ HUD_API_KEY_MISSING = Hint(
     message="Missing or invalid HUD_API_KEY.",
     tips=[
         "Set HUD_API_KEY in your environment or run: hud set HUD_API_KEY=your-key-here",
-        "Get a key at https://hud.so",
+        "Get a key at https://hud.ai",
         "Check for whitespace or truncation",
     ],
     docs_url=None,
@@ -61,6 +61,31 @@ RATE_LIMIT_HIT = Hint(
     context=["network"],
 )
 
+# Billing / plan upgrade
+PRO_PLAN_REQUIRED = Hint(
+    title="Pro plan required",
+    message="This feature requires Pro.",
+    tips=[
+        "Upgrade your plan to continue",
+    ],
+    docs_url="https://hud.ai/project/billing",
+    command_examples=None,
+    code="PRO_PLAN_REQUIRED",
+    context=["billing", "plan"],
+)
+
+CREDITS_EXHAUSTED = Hint(
+    title="Credits exhausted",
+    message="Your credits are exhausted.",
+    tips=[
+        "Top up credits or upgrade your plan",
+    ],
+    docs_url="https://hud.ai/project/billing",
+    command_examples=None,
+    code="CREDITS_EXHAUSTED",
+    context=["billing", "credits"],
+)
+
 TOOL_NOT_FOUND = Hint(
     title="Tool not found",
     message="Requested tool doesn't exist.",

hud/shared/requests.py

@@ -18,7 +18,11 @@ from hud.shared.exceptions import (
     HudRequestError,
     HudTimeoutError,
 )
-from hud.shared.hints import HUD_API_KEY_MISSING, RATE_LIMIT_HIT
+from hud.shared.hints import (
+    CREDITS_EXHAUSTED,
+    HUD_API_KEY_MISSING,
+    RATE_LIMIT_HIT,
+)
 
 # Set up logger
 logger = logging.getLogger("hud.http")
@@ -137,9 +141,13 @@ async def make_request(
                 raise HudTimeoutError(f"Request timed out: {e!s}") from None
             except httpx.HTTPStatusError as e:
                 err = HudRequestError.from_httpx_error(e)
-                if getattr(err, "status_code", None) == 429 and RATE_LIMIT_HIT not in err.hints:
+                code = getattr(err, "status_code", None)
+                if code == 429 and RATE_LIMIT_HIT not in err.hints:
                     logger.debug("Attaching RATE_LIMIT hint to 429 error")
                     err.hints.append(RATE_LIMIT_HIT)
+                elif code == 402 and CREDITS_EXHAUSTED not in err.hints:
+                    logger.debug("Attaching CREDITS_EXHAUSTED hint to 402 error")
+                    err.hints.append(CREDITS_EXHAUSTED)
                 raise err from None
             except httpx.RequestError as e:
                 if attempt <= max_retries:
@@ -234,9 +242,13 @@ def make_request_sync(
                 raise HudTimeoutError(f"Request timed out: {e!s}") from None
             except httpx.HTTPStatusError as e:
                 err = HudRequestError.from_httpx_error(e)
-                if getattr(err, "status_code", None) == 429 and RATE_LIMIT_HIT not in err.hints:
+                code = getattr(err, "status_code", None)
+                if code == 429 and RATE_LIMIT_HIT not in err.hints:
                     logger.debug("Attaching RATE_LIMIT hint to 429 error")
                     err.hints.append(RATE_LIMIT_HIT)
+                elif code == 402 and CREDITS_EXHAUSTED not in err.hints:
+                    logger.debug("Attaching CREDITS_EXHAUSTED hint to 402 error")
+                    err.hints.append(CREDITS_EXHAUSTED)
                 raise err from None
             except httpx.RequestError as e:
                 if attempt <= max_retries:

hud/shared/tests/test_exceptions.py

@@ -7,7 +7,7 @@ classification and helpful hints for users.
 from __future__ import annotations
 
 import json
-from unittest.mock import Mock, patch
+from unittest.mock import Mock
 
 import httpx
 import pytest
@@ -26,6 +26,7 @@ from hud.shared.hints import (
     CLIENT_NOT_INITIALIZED,
     HUD_API_KEY_MISSING,
     INVALID_CONFIG,
+    PRO_PLAN_REQUIRED,
     RATE_LIMIT_HIT,
     TOOL_NOT_FOUND,
 )
@@ -98,7 +99,7 @@ class TestHudExceptionAutoConversion:
     def test_hud_api_key_error(self):
         """Test that HUD API key errors become HudAuthenticationError."""
         try:
-            raise ValueError("API key missing for mcp.hud.so")
+            raise ValueError("API key missing for mcp.hud.ai")
         except Exception as e:
             with pytest.raises(HudAuthenticationError) as exc_info:
                 raise HudException from e
@@ -156,25 +157,23 @@ class TestHudExceptionAutoConversion:
             assert str(exc_info.value) == "Async operation timed out"
 
     def test_generic_error_remains_hudexception(self):
-        """Test that unmatched errors remain as base HudException."""
+        """Uncategorized errors become base HudException with original message."""
         try:
             raise ValueError("Some random error")
         except Exception as e:
             with pytest.raises(HudException) as exc_info:
                 raise HudException from e
-
-            # Should be base HudException, not a subclass
+            # Should be base HudException, not subclass
             assert type(exc_info.value) is HudException
-            assert exc_info.value.hints == []
+            assert str(exc_info.value) == "Some random error"
 
     def test_custom_message_override(self):
-        """Test that custom message overrides the original."""
+        """Custom message should be used for categorized errors."""
         try:
-            raise ValueError("Original error")
+            raise ValueError("Client not initialized - call initialize() first")
         except Exception as e:
-            with pytest.raises(HudException) as exc_info:
+            with pytest.raises(HudClientError) as exc_info:
                 raise HudException("Custom error message") from e
-
             assert str(exc_info.value) == "Custom error message"
 
     def test_already_hud_exception_passthrough(self):
@@ -204,6 +203,22 @@ class TestHudRequestError:
         error = HudRequestError("Forbidden", status_code=403)
         assert HUD_API_KEY_MISSING in error.hints
 
+    def test_403_pro_plan_message_sets_pro_hint(self):
+        """403 with Pro wording should map to PRO_PLAN_REQUIRED, not auth."""
+        error = HudRequestError("Feature requires Pro plan", status_code=403)
+        assert PRO_PLAN_REQUIRED in error.hints
+        assert HUD_API_KEY_MISSING not in error.hints
+
+    def test_403_pro_plan_detail_sets_pro_hint(self):
+        """403 with detail indicating Pro should map to PRO_PLAN_REQUIRED."""
+        error = HudRequestError(
+            "Forbidden",
+            status_code=403,
+            response_json={"detail": "Requires Pro plan"},
+        )
+        assert PRO_PLAN_REQUIRED in error.hints
+        assert HUD_API_KEY_MISSING not in error.hints
+
     def test_429_adds_rate_limit_hint(self):
         """Test that 429 status adds rate limit hint."""
         error = HudRequestError("Too Many Requests", status_code=429)
@@ -243,23 +258,19 @@ class TestMCPErrorHandling:
     @pytest.mark.asyncio
     async def test_mcp_error_handling(self):
         """Test that McpError is handled appropriately."""
-        # Since McpError is imported dynamically, we'll mock it
-        with patch("hud.clients.mcp_use.McpError") as MockMcpError:
-            MockMcpError.side_effect = Exception
+        # Create a dynamic class named "McpError" to trigger name-based detection
+        McpError = type("McpError", (Exception,), {})
 
-            # Create a mock MCP error
-            mcp_error = Exception("MCP protocol error: Unknown method")
-            mcp_error.__class__.__name__ = "McpError"
-
-            try:
-                raise mcp_error
-            except Exception as e:
-                # This would typically be caught in the client code
-                # and re-raised as HudException
-                with pytest.raises(HudException) as exc_info:
-                    raise HudException from e
+        try:
+            raise McpError("MCP protocol error: Unknown method")
+        except Exception as e:
+            # This would typically be caught in the client code
+            # and re-raised as HudException
+            with pytest.raises(HudException) as exc_info:
+                raise HudException from e
 
-                assert "MCP protocol error" in str(exc_info.value)
+            assert "MCP protocol error" in str(exc_info.value)
+            assert "MCP protocol error" in str(exc_info.value)
 
     def test_mcp_tool_error_result(self):
         """Test handling of MCP tool execution errors (isError: true)."""
@@ -352,7 +363,8 @@ class TestExceptionRendering:
         assert len(error.hints) == 1
         assert error.hints[0] == HUD_API_KEY_MISSING
         assert error.hints[0].title == "HUD API key required"
-        assert "Set HUD_API_KEY environment variable" in error.hints[0].tips[0]
+        # Hint copy evolved; keep the assertion robust to minor copy changes
+        assert "Set HUD_API_KEY" in error.hints[0].tips[0]
 
     def test_exception_type_preservation(self):
         """Test that exception types are preserved through conversion."""
@@ -396,16 +408,13 @@ class TestEdgeCases:
             assert type(error) is HudException
 
     def test_empty_error_message(self):
-        """Test handling of empty error messages."""
+        """Empty message still results in a HudException instance."""
         try:
             raise ValueError("")
         except Exception as e:
-            with pytest.raises(HudException) as exc_info:
+            with pytest.raises(HudException):
                 raise HudException from e
 
-            # Should still have some message
-            assert str(exc_info.value) != ""
-
     def test_circular_exception_chain(self):
         """Test that we don't create circular exception chains."""
         original = HudAuthenticationError("Original")

hud/shared/tests/test_hints.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+from hud.shared.hints import (
+    CLIENT_NOT_INITIALIZED,
+    ENV_VAR_MISSING,
+    HUD_API_KEY_MISSING,
+    INVALID_CONFIG,
+    MCP_SERVER_ERROR,
+    RATE_LIMIT_HIT,
+    TOOL_NOT_FOUND,
+    Hint,
+    render_hints,
+)
+
+
+def test_hint_objects_basic():
+    assert HUD_API_KEY_MISSING.title and isinstance(HUD_API_KEY_MISSING.tips, list)
+    assert RATE_LIMIT_HIT.code == "RATE_LIMIT"
+    assert TOOL_NOT_FOUND.title.startswith("Tool")
+    assert CLIENT_NOT_INITIALIZED.message
+    assert ENV_VAR_MISSING.command_examples is not None
+
+
+def test_all_hint_constants():
+    """Test that all predefined hint constants have required fields."""
+    hints = [
+        HUD_API_KEY_MISSING,
+        RATE_LIMIT_HIT,
+        TOOL_NOT_FOUND,
+        CLIENT_NOT_INITIALIZED,
+        INVALID_CONFIG,
+        ENV_VAR_MISSING,
+        MCP_SERVER_ERROR,
+    ]
+
+    for hint in hints:
+        assert hint.title
+        assert hint.message
+        assert hint.code
+
+
+def test_hint_creation():
+    """Test creating a custom Hint."""
+    hint = Hint(
+        title="Test Hint",
+        message="This is a test",
+        tips=["Tip 1", "Tip 2"],
+        docs_url="https://example.com",
+        command_examples=["command 1"],
+        code="TEST_CODE",
+        context=["test", "custom"],
+    )
+
+    assert hint.title == "Test Hint"
+    assert hint.message == "This is a test"
+    assert hint.tips and len(hint.tips) == 2
+    assert hint.docs_url == "https://example.com"
+    assert hint.command_examples and len(hint.command_examples) == 1
+    assert hint.code == "TEST_CODE"
+    assert hint.context and "test" in hint.context
+
+
+def test_hint_minimal():
+    """Test creating a minimal Hint with only required fields."""
+    hint = Hint(title="Minimal", message="Just basics")
+
+    assert hint.title == "Minimal"
+    assert hint.message == "Just basics"
+    assert hint.tips is None
+    assert hint.docs_url is None
+    assert hint.command_examples is None
+    assert hint.code is None
+    assert hint.context is None
+
+
+def test_render_hints_none():
+    """Test that render_hints handles None gracefully."""
+    # Should not raise
+    render_hints(None)
+
+
+def test_render_hints_empty_list():
+    """Test that render_hints handles empty list gracefully."""
+    # Should not raise
+    render_hints([])
+
+
+@patch("hud.utils.hud_console.hud_console")
+def test_render_hints_with_tips(mock_console):
+    """Test rendering hints with tips."""
+    render_hints([HUD_API_KEY_MISSING])
+
+    # Should call warning for title/message
+    mock_console.warning.assert_called()
+    # Should call info for tips
+    assert mock_console.info.call_count >= 1
+
+
+@patch("hud.utils.hud_console.hud_console")
+def test_render_hints_with_command_examples(mock_console):
+    """Test rendering hints with command examples."""
+    render_hints([ENV_VAR_MISSING])
+
+    # Should call command_example
+    mock_console.command_example.assert_called()
+
+
+@patch("hud.utils.hud_console.hud_console")
+def test_render_hints_with_docs_url(mock_console):
+    """Test rendering hints with documentation URL."""
+    hint = Hint(
+        title="Test",
+        message="Test message",
+        docs_url="https://docs.example.com",
+    )
+
+    render_hints([hint])
+
+    # Should call link for docs URL
+    mock_console.link.assert_called_with("https://docs.example.com")
+
+
+@patch("hud.utils.hud_console.hud_console")
+def test_render_hints_same_title_and_message(mock_console):
+    """Test rendering hints when title equals message."""
+    hint = Hint(title="Same", message="Same")
+
+    render_hints([hint])
+
+    # Should only call warning once with just the message
+    mock_console.warning.assert_called_once_with("Same")
+
+
+@patch("hud.utils.hud_console.hud_console")
+def test_render_hints_different_title_and_message(mock_console):
+    """Test rendering hints when title differs from message."""
+    hint = Hint(title="Title", message="Different message")
+
+    render_hints([hint])
+
+    # Should call warning with both title and message
+    mock_console.warning.assert_called_once()
+    call_args = mock_console.warning.call_args[0][0]
+    assert "Title" in call_args
+    assert "Different message" in call_args
+
+
+def test_render_hints_with_custom_design():
+    """Test rendering hints with custom design object."""
+    custom_design = MagicMock()
+
+    hint = Hint(title="Test", message="Message")
+    # Should not raise when custom design is provided
+    render_hints([hint], design=custom_design)
+
+
+@patch("hud.utils.hud_console.hud_console")
+def test_render_hints_handles_exception(mock_console):
+    """Test that render_hints handles exceptions gracefully."""
+    mock_console.warning.side_effect = Exception("Test error")
+
+    hint = Hint(title="Test", message="Message")
+
+    # Should not raise, just log warning
+    render_hints([hint])