Fix resume reconciliation by treating litellm_extra_body as runtime override (#1115)

Author: enyst

openhands-sdk/openhands/sdk/llm/llm.py

@@ -280,6 +280,9 @@ class LLM(BaseModel, RetryMixin, NonNativeToolCallingMixin):
         "api_key",
         "aws_access_key_id",
         "aws_secret_access_key",
+        # Dynamic runtime metadata for telemetry/routing that can differ across sessions
+        # and should not cause resume-time diffs. Always prefer the runtime value.
+        "litellm_extra_body",
     )
 
     # Runtime-only private attrs

tests/cross/test_agent_reconciliation.py

@@ -211,6 +211,59 @@ def test_conversation_with_same_agent_succeeds():
         assert len(new_conversation.state.events) > 0
 
 
+def test_agent_resolve_diff_from_deserialized():
+    """Test agent's resolve_diff_from_deserialized method.
+
+    Includes tolerance for litellm_extra_body differences injected at CLI load time.
+    """
+    with tempfile.TemporaryDirectory():
+        # Create original agent
+        tools = [Tool(name="TerminalTool")]
+        llm = LLM(
+            model="gpt-4o-mini", api_key=SecretStr("test-key"), usage_id="test-llm"
+        )
+        original_agent = Agent(llm=llm, tools=tools)
+
+        # Serialize and deserialize to simulate persistence
+        serialized = original_agent.model_dump_json()
+        deserialized_agent = AgentBase.model_validate_json(serialized)
+
+        # Create runtime agent with same configuration
+        llm2 = LLM(
+            model="gpt-4o-mini", api_key=SecretStr("test-key"), usage_id="test-llm"
+        )
+        runtime_agent = Agent(llm=llm2, tools=tools)
+
+        # Should resolve successfully
+        resolved = runtime_agent.resolve_diff_from_deserialized(deserialized_agent)
+        # Test model_dump equality
+        assert resolved.model_dump(mode="json") == runtime_agent.model_dump(mode="json")
+        assert resolved.llm.model == runtime_agent.llm.model
+        assert resolved.__class__ == runtime_agent.__class__
+
+        # Now simulate CLI injecting dynamic litellm_extra_body metadata at load time
+        injected = deserialized_agent.model_copy(
+            update={
+                "llm": deserialized_agent.llm.model_copy(
+                    update={
+                        "litellm_extra_body": {
+                            "metadata": {
+                                "session_id": "sess-123",
+                                "tags": ["app:openhands", "model:gpt-4o-mini"],
+                                "trace_version": "1.2.3",
+                            }
+                        }
+                    }
+                )
+            }
+        )
+
+        # Reconcile again: differences in litellm_extra_body should be allowed and
+        # the runtime value should be preferred without raising an error.
+        resolved2 = runtime_agent.resolve_diff_from_deserialized(injected)
+        assert resolved2.llm.litellm_extra_body == runtime_agent.llm.litellm_extra_body
+
+
 @patch("openhands.sdk.llm.llm.litellm_completion")
 def test_conversation_persistence_lifecycle(mock_completion):
     """Test full conversation persistence lifecycle similar to examples/10_persistence.py."""  # noqa: E501
@@ -288,34 +341,6 @@ def test_conversation_persistence_lifecycle(mock_completion):
         assert len(new_conversation.state.events) >= original_event_count + 2
 
 
-def test_agent_resolve_diff_from_deserialized():
-    """Test agent's resolve_diff_from_deserialized method."""
-    with tempfile.TemporaryDirectory():
-        # Create original agent
-        tools = [Tool(name="TerminalTool")]
-        llm = LLM(
-            model="gpt-4o-mini", api_key=SecretStr("test-key"), usage_id="test-llm"
-        )
-        original_agent = Agent(llm=llm, tools=tools)
-
-        # Serialize and deserialize to simulate persistence
-        serialized = original_agent.model_dump_json()
-        deserialized_agent = AgentBase.model_validate_json(serialized)
-
-        # Create runtime agent with same configuration
-        llm2 = LLM(
-            model="gpt-4o-mini", api_key=SecretStr("test-key"), usage_id="test-llm"
-        )
-        runtime_agent = Agent(llm=llm2, tools=tools)
-
-        # Should resolve successfully
-        resolved = runtime_agent.resolve_diff_from_deserialized(deserialized_agent)
-        # Test model_dump equality
-        assert resolved.model_dump(mode="json") == runtime_agent.model_dump(mode="json")
-        assert resolved.llm.model == runtime_agent.llm.model
-        assert resolved.__class__ == runtime_agent.__class__
-
-
 def test_agent_resolve_diff_allows_security_analyzer_change():
     """Test that security_analyzer can differ between runtime and persisted agents."""
     from openhands.sdk.security.llm_analyzer import LLMSecurityAnalyzer

tests/sdk/llm/test_llm_reconciliation.py

@@ -0,0 +1,42 @@
+from pydantic import SecretStr
+
+from openhands.sdk import Agent
+from openhands.sdk.agent import AgentBase
+from openhands.sdk.llm import LLM
+
+
+def test_resolve_diff_ignores_litellm_extra_body_diffs():
+    tools = []
+    llm = LLM(model="gpt-4o-mini", api_key=SecretStr("test-key"), usage_id="test-llm")
+    original_agent = Agent(llm=llm, tools=tools)
+
+    serialized = original_agent.model_dump_json()
+    deserialized_agent = AgentBase.model_validate_json(serialized)
+
+    runtime_agent = Agent(
+        llm=LLM(
+            model="gpt-4o-mini",
+            api_key=SecretStr("test-key"),
+            usage_id="test-llm",
+        ),
+        tools=tools,
+    )
+
+    injected = deserialized_agent.model_copy(
+        update={
+            "llm": deserialized_agent.llm.model_copy(
+                update={
+                    "litellm_extra_body": {
+                        "metadata": {
+                            "session_id": "sess-xyz",
+                            "tags": ["app:openhands", "model:gpt-4o-mini"],
+                            "trace_version": "9.9.9",
+                        }
+                    }
+                }
+            )
+        }
+    )
+
+    resolved = runtime_agent.resolve_diff_from_deserialized(injected)
+    assert resolved.llm.litellm_extra_body == runtime_agent.llm.litellm_extra_body