fix(core): resolve infinite recursion in _dereference_refs_helper with mixed $ref objects

Fixes infinite recursion issue in JSON schema dereferencing when objects contain both $ref and other properties (e.g., nullable, description, additionalProperties).

**Problem:**
- Commit fb5da83 changed the condition from `set(obj.keys()) == {"$ref"}` to `"$ref" in set(obj.keys())`
- This caused objects with $ref + other properties to be treated as pure $ref nodes
- Result: other properties were lost and infinite recursion occurred with complex schemas

**Solution:**
- Restore pure $ref detection for objects with only $ref key
- Add proper handling for mixed $ref objects that preserves all properties
- Merge resolved reference content with other properties
- Maintain cycle detection to prevent infinite recursion

**Impact:**
- Fixes Apollo MCP server schema integration (#32511)
- Resolves tool binding infinite recursion with complex GraphQL schemas
- Preserves backward compatibility with existing functionality
- No performance impact - actually improves handling of complex schemas

Fixes #32511

Author: Marcus

libs/core/langchain_core/utils/json_schema.py

@@ -54,8 +54,8 @@ def _dereference_refs_helper(
     if processed_refs is None:
         processed_refs = set()
 
-    # 1) Pure $ref node?
-    if isinstance(obj, dict) and "$ref" in set(obj.keys()):
+    # 1) Pure $ref node (only contains $ref, no other properties)?
+    if isinstance(obj, dict) and set(obj.keys()) == {"$ref"}:
         ref_path = obj["$ref"]
         # cycle?
         if ref_path in processed_refs:
@@ -73,7 +73,48 @@ def _dereference_refs_helper(
         processed_refs.remove(ref_path)
         return result
 
-    # 2) Not a pure-$ref: recurse, skipping any keys in skip_keys
+    # 2) Mixed $ref node (contains $ref plus other properties)?
+    if isinstance(obj, dict) and "$ref" in obj:
+        ref_path = obj["$ref"]
+        # cycle?
+        if ref_path in processed_refs:
+            # For mixed refs, return the non-ref properties to avoid infinite recursion
+            other_props = {k: v for k, v in obj.items() if k != "$ref"}
+            return _dereference_refs_helper(
+                other_props, full_schema, processed_refs, skip_keys, shallow_refs
+            )
+
+        processed_refs.add(ref_path)
+
+        # grab + copy the target
+        target = deepcopy(_retrieve_ref(ref_path, full_schema))
+
+        # Merge the resolved reference with other properties
+        result_dict = {}
+
+        # First, process the resolved reference
+        resolved_ref = _dereference_refs_helper(
+            target, full_schema, processed_refs, skip_keys, shallow_refs
+        )
+        if isinstance(resolved_ref, dict):
+            result_dict.update(resolved_ref)
+
+        # Then add/override with the other properties from the original object
+        other_props = {k: v for k, v in obj.items() if k != "$ref"}
+        for k, v in other_props.items():
+            if k in skip_keys:
+                result_dict[k] = deepcopy(v)
+            elif isinstance(v, (dict, list)):
+                result_dict[k] = _dereference_refs_helper(
+                    v, full_schema, processed_refs, skip_keys, shallow_refs
+                )
+            else:
+                result_dict[k] = v
+
+        processed_refs.remove(ref_path)
+        return result_dict
+
+    # 3) Not a $ref: recurse, skipping any keys in skip_keys
     if isinstance(obj, dict):
         out: dict[str, Any] = {}
         for k, v in obj.items():

libs/core/tests/unit_tests/utils/test_json_schema.py

@@ -444,3 +444,140 @@ def test_dereference_refs_list_index() -> None:
 
     actual_dict_key = dereference_refs(schema_dict_key)
     assert actual_dict_key == expected_dict_key
+
+
+def test_dereference_refs_mixed_ref_with_properties() -> None:
+    """Test dereferencing refs that have $ref plus other properties."""
+    # This pattern can cause infinite recursion if not handled correctly
+    schema = {
+        "type": "object",
+        "properties": {
+            "data": {
+                "$ref": "#/$defs/BaseType",
+                "description": "Additional description",
+                "example": "some example",
+            }
+        },
+        "$defs": {"BaseType": {"type": "string", "minLength": 1}},
+    }
+
+    expected = {
+        "type": "object",
+        "properties": {
+            "data": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Additional description",
+                "example": "some example",
+            }
+        },
+        "$defs": {"BaseType": {"type": "string", "minLength": 1}},
+    }
+
+    actual = dereference_refs(schema)
+    assert actual == expected
+
+
+def test_dereference_refs_complex_apollo_mcp_pattern() -> None:
+    """Test pattern that caused infinite recursion in Apollo MCP server schemas."""
+    # Simplified version of the problematic pattern from the issue
+    schema = {
+        "type": "object",
+        "properties": {
+            "query": {"$ref": "#/$defs/Query", "additionalProperties": False}
+        },
+        "$defs": {
+            "Query": {
+                "type": "object",
+                "properties": {"user": {"$ref": "#/$defs/User"}},
+            },
+            "User": {
+                "type": "object",
+                "properties": {
+                    "id": {"type": "string"},
+                    "profile": {"$ref": "#/$defs/UserProfile", "nullable": True},
+                },
+            },
+            "UserProfile": {
+                "type": "object",
+                "properties": {"bio": {"type": "string"}},
+            },
+        },
+    }
+
+    # This should not cause infinite recursion
+    actual = dereference_refs(schema)
+
+    # The mixed $ref should be properly resolved and merged
+    expected_user_profile = {
+        "type": "object",
+        "properties": {"bio": {"type": "string"}},
+    }
+
+    expected_user = {
+        "type": "object",
+        "properties": {
+            "id": {"type": "string"},
+            "profile": {
+                "type": "object",
+                "properties": {"bio": {"type": "string"}},
+                "nullable": True,
+            },
+        },
+    }
+
+    expected_query = {
+        "type": "object",
+        "properties": {"user": expected_user},
+        "additionalProperties": False,
+    }
+
+    expected = {
+        "type": "object",
+        "properties": {"query": expected_query},
+        "$defs": {
+            "Query": {
+                "type": "object",
+                "properties": {"user": {"$ref": "#/$defs/User"}},
+            },
+            "User": {
+                "type": "object",
+                "properties": {
+                    "id": {"type": "string"},
+                    "profile": {"$ref": "#/$defs/UserProfile", "nullable": True},
+                },
+            },
+            "UserProfile": expected_user_profile,
+        },
+    }
+
+    assert actual == expected
+
+
+def test_dereference_refs_cyclical_mixed_refs() -> None:
+    """Test cyclical references with mixed $ref properties don't cause loops."""
+    schema = {
+        "type": "object",
+        "properties": {"node": {"$ref": "#/$defs/Node"}},
+        "$defs": {
+            "Node": {
+                "type": "object",
+                "properties": {
+                    "id": {"type": "string"},
+                    "parent": {"$ref": "#/$defs/Node", "nullable": True},
+                    "children": {"type": "array", "items": {"$ref": "#/$defs/Node"}},
+                },
+            }
+        },
+    }
+
+    # This should handle cycles gracefully
+    actual = dereference_refs(schema)
+
+    # The self-referencing should be broken with empty objects
+
+    # Verify the structure is correct and doesn't cause infinite recursion
+    assert "properties" in actual
+    assert "node" in actual["properties"]
+    assert isinstance(actual["properties"]["node"], dict)
+    assert "type" in actual["properties"]["node"]