Merge branch 'main' into fix/realtime-transcript-delta-history-updated

Author: Quratulain-bilal

tests/test_mcp_tool_metadata.py

@@ -0,0 +1,210 @@
+"""Unit tests for src/agents/_mcp_tool_metadata.py pure helpers.
+
+The module resolves MCP tool display metadata (title / description) from
+either dict payloads or attribute-bearing objects. It feeds hosted-MCP
+tool definitions into the model and into traces, but had no direct
+test file.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from agents._mcp_tool_metadata import (
+    MCPToolMetadata,
+    collect_mcp_list_tools_metadata,
+    extract_mcp_tool_metadata,
+    resolve_mcp_tool_description,
+    resolve_mcp_tool_description_for_model,
+    resolve_mcp_tool_title,
+)
+
+
+@dataclass
+class _ToolObj:
+    """Tiny attribute-bearing stand-in for an MCP tool object."""
+
+    name: str | None = None
+    title: str | None = None
+    description: str | None = None
+    annotations: Any = None
+
+
+@dataclass
+class _Annotations:
+    title: str | None = None
+
+
+class TestResolveMCPToolTitle:
+    def test_explicit_title_wins(self) -> None:
+        tool = {"title": "Explicit", "annotations": {"title": "Annotated"}}
+        assert resolve_mcp_tool_title(tool) == "Explicit"
+
+    def test_falls_back_to_annotations_title(self) -> None:
+        tool = {"annotations": {"title": "Annotated"}}
+        assert resolve_mcp_tool_title(tool) == "Annotated"
+
+    def test_returns_none_when_neither_present(self) -> None:
+        assert resolve_mcp_tool_title({}) is None
+
+    def test_skips_empty_explicit_title(self) -> None:
+        tool = {"title": "", "annotations": {"title": "Annotated"}}
+        assert resolve_mcp_tool_title(tool) == "Annotated"
+
+    def test_skips_non_string_explicit_title(self) -> None:
+        tool = {"title": 123, "annotations": {"title": "Annotated"}}
+        assert resolve_mcp_tool_title(tool) == "Annotated"
+
+    def test_works_with_attribute_objects(self) -> None:
+        tool = _ToolObj(title="Explicit")
+        assert resolve_mcp_tool_title(tool) == "Explicit"
+
+    def test_works_with_attribute_annotations(self) -> None:
+        tool = _ToolObj(annotations=_Annotations(title="Annotated"))
+        assert resolve_mcp_tool_title(tool) == "Annotated"
+
+    def test_handles_missing_annotations_attribute(self) -> None:
+        tool = _ToolObj()
+        assert resolve_mcp_tool_title(tool) is None
+
+
+class TestResolveMCPToolDescription:
+    def test_returns_description(self) -> None:
+        assert resolve_mcp_tool_description({"description": "Long form"}) == "Long form"
+
+    def test_returns_none_when_empty(self) -> None:
+        assert resolve_mcp_tool_description({"description": ""}) is None
+
+    def test_returns_none_when_missing(self) -> None:
+        assert resolve_mcp_tool_description({}) is None
+
+    def test_returns_none_when_non_string(self) -> None:
+        assert resolve_mcp_tool_description({"description": 123}) is None
+
+    def test_works_with_attribute_object(self) -> None:
+        assert resolve_mcp_tool_description(_ToolObj(description="Long form")) == "Long form"
+
+
+class TestResolveMCPToolDescriptionForModel:
+    def test_uses_description_when_present(self) -> None:
+        tool = {"description": "Long form", "title": "Short"}
+        assert resolve_mcp_tool_description_for_model(tool) == "Long form"
+
+    def test_falls_back_to_title_when_description_missing(self) -> None:
+        assert resolve_mcp_tool_description_for_model({"title": "Short"}) == "Short"
+
+    def test_falls_back_to_annotations_title(self) -> None:
+        tool = {"annotations": {"title": "Annotated"}}
+        assert resolve_mcp_tool_description_for_model(tool) == "Annotated"
+
+    def test_returns_empty_string_when_nothing_resolvable(self) -> None:
+        assert resolve_mcp_tool_description_for_model({}) == ""
+
+
+class TestExtractMCPToolMetadata:
+    def test_collects_both_fields(self) -> None:
+        tool = {"description": "Long form", "title": "Short"}
+        assert extract_mcp_tool_metadata(tool) == MCPToolMetadata(
+            description="Long form", title="Short"
+        )
+
+    def test_returns_empty_metadata_when_nothing_present(self) -> None:
+        assert extract_mcp_tool_metadata({}) == MCPToolMetadata()
+
+
+class TestCollectMCPListToolsMetadata:
+    def test_collects_from_raw_payload(self) -> None:
+        items = [
+            {
+                "type": "mcp_list_tools",
+                "server_label": "github",
+                "tools": [
+                    {"name": "search", "description": "Search repos", "title": "Search"},
+                    {"name": "create", "description": "Create issue"},
+                ],
+            }
+        ]
+        result = collect_mcp_list_tools_metadata(items)
+        assert result == {
+            ("github", "search"): MCPToolMetadata(description="Search repos", title="Search"),
+            ("github", "create"): MCPToolMetadata(description="Create issue"),
+        }
+
+    def test_unwraps_run_item_with_raw_item(self) -> None:
+        @dataclass
+        class _RunItem:
+            raw_item: Any
+
+        run_item = _RunItem(
+            raw_item={
+                "type": "mcp_list_tools",
+                "server_label": "internal",
+                "tools": [{"name": "ping", "description": "Ping"}],
+            }
+        )
+        result = collect_mcp_list_tools_metadata([run_item])
+        assert result == {("internal", "ping"): MCPToolMetadata(description="Ping")}
+
+    def test_skips_items_without_correct_type(self) -> None:
+        items = [
+            {
+                "type": "mcp_call",
+                "server_label": "github",
+                "tools": [{"name": "ignored"}],
+            }
+        ]
+        assert collect_mcp_list_tools_metadata(items) == {}
+
+    def test_skips_items_without_server_label(self) -> None:
+        items = [
+            {
+                "type": "mcp_list_tools",
+                "tools": [{"name": "search"}],
+            }
+        ]
+        assert collect_mcp_list_tools_metadata(items) == {}
+
+    def test_skips_items_with_non_list_tools(self) -> None:
+        items = [
+            {
+                "type": "mcp_list_tools",
+                "server_label": "github",
+                "tools": "not-a-list",
+            }
+        ]
+        assert collect_mcp_list_tools_metadata(items) == {}
+
+    def test_skips_tools_without_name(self) -> None:
+        items = [
+            {
+                "type": "mcp_list_tools",
+                "server_label": "github",
+                "tools": [
+                    {"description": "no name"},
+                    {"name": "", "description": "empty name"},
+                    {"name": "good", "description": "kept"},
+                ],
+            }
+        ]
+        result = collect_mcp_list_tools_metadata(items)
+        assert result == {("github", "good"): MCPToolMetadata(description="kept")}
+
+    def test_returns_empty_for_empty_input(self) -> None:
+        assert collect_mcp_list_tools_metadata([]) == {}
+
+    def test_later_entry_for_same_key_wins(self) -> None:
+        items = [
+            {
+                "type": "mcp_list_tools",
+                "server_label": "github",
+                "tools": [{"name": "search", "description": "first"}],
+            },
+            {
+                "type": "mcp_list_tools",
+                "server_label": "github",
+                "tools": [{"name": "search", "description": "second"}],
+            },
+        ]
+        result = collect_mcp_list_tools_metadata(items)
+        assert result == {("github", "search"): MCPToolMetadata(description="second")}

tests/test_tool_identity.py

@@ -0,0 +1,167 @@
+"""Unit tests for src/agents/_tool_identity.py pure helpers.
+
+These cover the small, pure functions in `_tool_identity` that build /
+parse function-tool lookup keys and trace names. The module had no
+direct test file even though it's imported across the runner, tracing,
+and tool-output trimmer code paths.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from agents._tool_identity import (
+    deserialize_function_tool_lookup_key,
+    get_function_tool_lookup_key,
+    get_tool_call_name,
+    get_tool_call_namespace,
+    get_tool_call_qualified_name,
+    get_tool_call_trace_name,
+    is_reserved_synthetic_tool_namespace,
+    serialize_function_tool_lookup_key,
+    tool_qualified_name,
+    tool_trace_name,
+)
+from agents.exceptions import UserError
+
+
+class TestToolQualifiedName:
+    def test_returns_name_when_no_namespace(self) -> None:
+        assert tool_qualified_name("search") == "search"
+
+    def test_returns_dotted_when_namespace_provided(self) -> None:
+        assert tool_qualified_name("search", "tools") == "tools.search"
+
+    def test_returns_none_for_empty_name(self) -> None:
+        assert tool_qualified_name("") is None
+        assert tool_qualified_name(None) is None
+
+    def test_returns_none_for_non_string_name(self) -> None:
+        assert tool_qualified_name(123) is None  # type: ignore[arg-type]
+
+    def test_ignores_empty_namespace(self) -> None:
+        assert tool_qualified_name("search", "") == "search"
+        assert tool_qualified_name("search", None) == "search"
+
+
+class TestIsReservedSyntheticToolNamespace:
+    def test_true_when_name_equals_namespace(self) -> None:
+        assert is_reserved_synthetic_tool_namespace("search", "search") is True
+
+    def test_false_when_different(self) -> None:
+        assert is_reserved_synthetic_tool_namespace("search", "tools") is False
+
+    def test_false_when_either_missing(self) -> None:
+        assert is_reserved_synthetic_tool_namespace("", "") is False
+        assert is_reserved_synthetic_tool_namespace("search", None) is False
+        assert is_reserved_synthetic_tool_namespace(None, "search") is False
+
+
+class TestToolTraceName:
+    def test_collapses_synthetic_namespace(self) -> None:
+        # When namespace == name, trace name is just the bare name.
+        assert tool_trace_name("search", "search") == "search"
+
+    def test_qualifies_real_namespace(self) -> None:
+        assert tool_trace_name("search", "tools") == "tools.search"
+
+    def test_returns_bare_when_no_namespace(self) -> None:
+        assert tool_trace_name("search", None) == "search"
+
+
+class TestToolCallExtractors:
+    def test_get_tool_call_name_from_dict(self) -> None:
+        assert get_tool_call_name({"name": "search"}) == "search"
+
+    def test_get_tool_call_name_from_object(self) -> None:
+        class Call:
+            name = "search"
+
+        assert get_tool_call_name(Call()) == "search"
+
+    def test_get_tool_call_name_returns_none_for_empty(self) -> None:
+        assert get_tool_call_name({"name": ""}) is None
+        assert get_tool_call_name({}) is None
+        assert get_tool_call_name({"name": 123}) is None
+
+    def test_get_tool_call_namespace(self) -> None:
+        assert get_tool_call_namespace({"namespace": "tools"}) == "tools"
+        assert get_tool_call_namespace({"namespace": ""}) is None
+        assert get_tool_call_namespace({}) is None
+
+    def test_get_tool_call_qualified_name_with_namespace(self) -> None:
+        call = {"name": "search", "namespace": "tools"}
+        assert get_tool_call_qualified_name(call) == "tools.search"
+
+    def test_get_tool_call_qualified_name_without_namespace(self) -> None:
+        assert get_tool_call_qualified_name({"name": "search"}) == "search"
+
+    def test_get_tool_call_trace_name_collapses_synthetic_namespace(self) -> None:
+        call = {"name": "search", "namespace": "search"}
+        assert get_tool_call_trace_name(call) == "search"
+
+    def test_get_tool_call_trace_name_qualifies_real_namespace(self) -> None:
+        call = {"name": "search", "namespace": "tools"}
+        assert get_tool_call_trace_name(call) == "tools.search"
+
+
+class TestGetFunctionToolLookupKey:
+    def test_bare_when_no_namespace(self) -> None:
+        assert get_function_tool_lookup_key("search") == ("bare", "search")
+
+    def test_namespaced_when_namespace_present(self) -> None:
+        assert get_function_tool_lookup_key("search", "tools") == (
+            "namespaced",
+            "tools",
+            "search",
+        )
+
+    def test_deferred_top_level_when_namespace_equals_name(self) -> None:
+        assert get_function_tool_lookup_key("search", "search") == (
+            "deferred_top_level",
+            "search",
+        )
+
+    def test_returns_none_for_empty_name(self) -> None:
+        assert get_function_tool_lookup_key("") is None
+        assert get_function_tool_lookup_key(None) is None
+
+
+class TestSerializeRoundTrip:
+    @pytest.mark.parametrize(
+        "lookup_key",
+        [
+            ("bare", "search"),
+            ("namespaced", "tools", "search"),
+            ("deferred_top_level", "search"),
+        ],
+    )
+    def test_roundtrip(self, lookup_key) -> None:
+        serialized = serialize_function_tool_lookup_key(lookup_key)
+        assert serialized is not None
+        assert deserialize_function_tool_lookup_key(serialized) == lookup_key
+
+    def test_serialize_none_returns_none(self) -> None:
+        assert serialize_function_tool_lookup_key(None) is None
+
+    def test_deserialize_invalid_returns_none(self) -> None:
+        assert deserialize_function_tool_lookup_key(None) is None
+        assert deserialize_function_tool_lookup_key({}) is None
+        assert deserialize_function_tool_lookup_key({"kind": "bare"}) is None
+        assert deserialize_function_tool_lookup_key({"kind": "bare", "name": ""}) is None
+        assert deserialize_function_tool_lookup_key({"kind": "unknown", "name": "x"}) is None
+        # namespaced kind requires a non-empty namespace
+        assert deserialize_function_tool_lookup_key({"kind": "namespaced", "name": "x"}) is None
+
+
+def test_validate_function_tool_namespace_shape_rejects_synthetic() -> None:
+    """The internal validator must refuse synthetic name==namespace shapes."""
+    from agents._tool_identity import validate_function_tool_namespace_shape
+
+    # Valid shapes don't raise.
+    validate_function_tool_namespace_shape("search", "tools")
+    validate_function_tool_namespace_shape("search", None)
+
+    # The reserved synthetic shape (name == namespace) is rejected.
+    with pytest.raises(UserError, match="reserves the synthetic namespace"):
+        validate_function_tool_namespace_shape("search", "search")