refactor(llm): use typed access for extra_headers and document intended precedence in tests

- Replace getattr(..., 'extra_headers') with direct typed access
- Add comments in tests to state intended behavior for each case

Co-authored-by: openhands <openhands@all-hands.dev>

Author: enyst

openhands-sdk/openhands/sdk/llm/options/chat_options.py

@@ -29,7 +29,7 @@ def select_chat_options(
             out["max_tokens"] = out.pop("max_completion_tokens")
 
     # If user didn't set extra_headers, propagate from llm config
-    if getattr(llm, "extra_headers", None) and "extra_headers" not in out:
+    if llm.extra_headers is not None and "extra_headers" not in out:
         out["extra_headers"] = dict(llm.extra_headers)
 
     # Reasoning-model quirks

openhands-sdk/openhands/sdk/llm/options/responses_options.py

@@ -26,7 +26,7 @@ def select_responses_options(
     out["tool_choice"] = "auto"
 
     # If user didn't set extra_headers, propagate from llm config
-    if getattr(llm, "extra_headers", None) and "extra_headers" not in out:
+    if llm.extra_headers is not None and "extra_headers" not in out:
         out["extra_headers"] = dict(llm.extra_headers)
 
     # Store defaults to False (stateless) unless explicitly provided

tests/sdk/llm/test_llm.py

@@ -356,9 +356,12 @@ def test_completion_merges_llm_extra_headers_with_extended_thinking_default(
     assert mock_completion.call_count == 1
     _, kwargs = mock_completion.call_args
     headers = kwargs.get("extra_headers") or {}
-    # Should include default interleaved-thinking header
+    # Intended behavior:
+    # - No per-call headers provided.
+    # - LLM.extra_headers should be used.
+    # - Extended thinking default (anthropic-beta) should be merged in.
+    # - Result keeps both the default and configured headers.
     assert headers.get("anthropic-beta") == "interleaved-thinking-2025-05-14"
-    # Should preserve configured headers as well
     assert headers.get("X-Trace") == "1"
 
 
@@ -380,7 +383,10 @@ def test_completion_call_time_extra_headers_override_config_and_defaults(
     )
 
     messages = [Message(role="user", content=[TextContent(text="Hi")])]
-    # Call-time headers should take full precedence
+    # Intended behavior:
+    # - Per-call headers should replace any LLM.extra_headers.
+    # - Extended thinking default should still be merged in.
+    # - On conflicts, per-call headers win (anthropic-beta => custom-beta).
     call_headers = {"anthropic-beta": "custom-beta", "Header-Only": "H"}
     _ = llm.completion(messages=messages, extra_headers=call_headers)
 
@@ -390,6 +396,7 @@ def test_completion_call_time_extra_headers_override_config_and_defaults(
     assert headers.get("anthropic-beta") == "custom-beta"
     assert headers.get("Header-Only") == "H"
     # LLM.config headers should not be merged when user specifies their own
+    # (except defaults we explicitly add)
     assert "X-Trace" not in headers
 
 
@@ -427,6 +434,9 @@ def test_responses_call_time_extra_headers_override_config(mock_responses):
     )
 
     messages = [Message(role="user", content=[TextContent(text="Hi")])]
+    # Intended behavior:
+    # - Per-call headers should replace any LLM.extra_headers for Responses path.
+    # - No Anthropic default is currently added on the Responses path.
     call_headers = {"Header-Only": "H"}
     _ = llm.responses(messages=messages, extra_headers=call_headers)