fix: #2776 keep private tool metadata out of persisted session items (#2781)

Author: seratch

src/agents/memory/openai_responses_compaction_session.py

@@ -6,6 +6,7 @@
 from openai import AsyncOpenAI
 
 from ..models._openai_shared import get_default_openai_client
+from ..run_internal.items import normalize_input_items_for_api
 from .openai_conversations_session import OpenAIConversationsSession
 from .session import (
     OpenAIResponsesCompactionArgs,
@@ -270,11 +271,12 @@ def _clear_deferred_compaction(self) -> None:
     async def add_items(self, items: list[TResponseInputItem]) -> None:
         await self.underlying_session.add_items(items)
         if self._compaction_candidate_items is not None:
-            new_candidates = select_compaction_candidate_items(items)
+            new_items = _normalize_compaction_session_items(items)
+            new_candidates = select_compaction_candidate_items(new_items)
             if new_candidates:
                 self._compaction_candidate_items.extend(new_candidates)
         if self._session_items is not None:
-            self._session_items.extend(items)
+            self._session_items.extend(_normalize_compaction_session_items(items))
 
     async def pop_item(self) -> TResponseInputItem | None:
         popped = await self.underlying_session.pop_item()
@@ -296,7 +298,7 @@ async def _ensure_compaction_candidates(
         if self._compaction_candidate_items is not None and self._session_items is not None:
             return (self._compaction_candidate_items[:], self._session_items[:])
 
-        history = await self.underlying_session.get_items()
+        history = _normalize_compaction_session_items(await self.underlying_session.get_items())
         candidates = select_compaction_candidate_items(history)
         self._compaction_candidate_items = candidates
         self._session_items = history
@@ -336,6 +338,13 @@ def _strip_orphaned_assistant_ids(
     return cleaned
 
 
+def _normalize_compaction_session_items(
+    items: list[TResponseInputItem],
+) -> list[TResponseInputItem]:
+    """Normalize compaction input so SDK-only metadata never reaches responses.compact."""
+    return normalize_input_items_for_api(list(items))
+
+
 _ResolvedCompactionMode = Literal["previous_response_id", "input"]
 
 

src/agents/run_internal/items.py

@@ -18,6 +18,8 @@
 from ..tool import DEFAULT_APPROVAL_REJECTION_MESSAGE
 
 REJECTION_MESSAGE = DEFAULT_APPROVAL_REJECTION_MESSAGE
+TOOL_CALL_SESSION_DESCRIPTION_KEY = "_agents_tool_description"
+TOOL_CALL_SESSION_TITLE_KEY = "_agents_tool_title"
 _TOOL_CALL_TO_OUTPUT_TYPE: dict[str, str] = {
     "function_call": "function_call_output",
     "shell_call": "shell_call_output",
@@ -30,6 +32,8 @@
 __all__ = [
     "ReasoningItemIdPolicy",
     "REJECTION_MESSAGE",
+    "TOOL_CALL_SESSION_DESCRIPTION_KEY",
+    "TOOL_CALL_SESSION_TITLE_KEY",
     "copy_input_items",
     "drop_orphan_function_calls",
     "ensure_input_item_format",
@@ -41,6 +45,7 @@
     "fingerprint_input_item",
     "deduplicate_input_items",
     "deduplicate_input_items_preferring_latest",
+    "strip_internal_input_item_metadata",
     "function_rejection_item",
     "shell_rejection_item",
     "apply_patch_rejection_item",
@@ -148,8 +153,8 @@ def normalize_input_items_for_api(items: list[TResponseInputItem]) -> list[TResp
             normalized.append(item)
             continue
 
-        normalized_item = dict(coerced)
-        normalized.append(cast(TResponseInputItem, normalized_item))
+        normalized_item = strip_internal_input_item_metadata(cast(TResponseInputItem, coerced))
+        normalized.append(normalized_item)
     return normalized
 
 
@@ -188,12 +193,25 @@ def fingerprint_input_item(item: Any, *, ignore_ids_for_matching: bool = False)
             payload = _model_dump_without_warnings(item)
             if payload is None:
                 return None
+            if isinstance(payload, dict):
+                payload = cast(
+                    dict[str, Any],
+                    strip_internal_input_item_metadata(cast(TResponseInputItem, payload)),
+                )
         elif isinstance(item, dict):
-            payload = dict(item)
+            payload = cast(
+                dict[str, Any],
+                strip_internal_input_item_metadata(cast(TResponseInputItem, item)),
+            )
             if ignore_ids_for_matching:
                 payload.pop("id", None)
         else:
             payload = ensure_input_item_format(item)
+            if isinstance(payload, dict):
+                payload = cast(
+                    dict[str, Any],
+                    strip_internal_input_item_metadata(cast(TResponseInputItem, payload)),
+                )
             if ignore_ids_for_matching and isinstance(payload, dict):
                 payload.pop("id", None)
 
@@ -231,6 +249,17 @@ def _dedupe_key(item: TResponseInputItem) -> str | None:
     return None
 
 
+def strip_internal_input_item_metadata(item: TResponseInputItem) -> TResponseInputItem:
+    """Remove SDK-only session metadata before sending items back to the model."""
+    if not isinstance(item, dict):
+        return item
+
+    cleaned = dict(item)
+    cleaned.pop(TOOL_CALL_SESSION_DESCRIPTION_KEY, None)
+    cleaned.pop(TOOL_CALL_SESSION_TITLE_KEY, None)
+    return cast(TResponseInputItem, cleaned)
+
+
 def _should_omit_reasoning_item_ids(reasoning_item_id_policy: ReasoningItemIdPolicy | None) -> bool:
     return reasoning_item_id_policy == "omit"
 

src/agents/run_internal/session_persistence.py

@@ -33,6 +33,7 @@
     fingerprint_input_item,
     normalize_input_items_for_api,
     run_item_to_input_item,
+    strip_internal_input_item_metadata,
 )
 from .oai_conversation import OpenAIServerConversationTracker
 from .run_steps import SingleStepResult
@@ -85,7 +86,9 @@ async def prepare_input_with_session(
         history = await session.get_items(limit=resolved_settings.limit)
     else:
         history = await session.get_items()
-    converted_history = [ensure_input_item_format(item) for item in history]
+    converted_history = [
+        strip_internal_input_item_metadata(ensure_input_item_format(item)) for item in history
+    ]
 
     new_input_list = [
         ensure_input_item_format(item) for item in ItemHelpers.input_to_new_input_list(input)
@@ -164,7 +167,8 @@ async def prepare_input_with_session(
     normalized = normalize_input_items_for_api(filtered)
     deduplicated = deduplicate_input_items_preferring_latest(normalized)
 
-    return deduplicated, [ensure_input_item_format(item) for item in appended_items]
+    appended_as_inputs = [ensure_input_item_format(item) for item in appended_items]
+    return deduplicated, normalize_input_items_for_api(appended_as_inputs)
 
 
 async def persist_session_items_for_guardrail_trip(
@@ -262,10 +266,12 @@ async def save_result_to_session(
 
     input_list: list[TResponseInputItem] = []
     if original_input:
-        input_list = [
-            ensure_input_item_format(item)
-            for item in ItemHelpers.input_to_new_input_list(original_input)
-        ]
+        input_list = normalize_input_items_for_api(
+            [
+                ensure_input_item_format(item)
+                for item in ItemHelpers.input_to_new_input_list(original_input)
+            ]
+        )
 
     resolved_reasoning_item_id_policy = (
         reasoning_item_id_policy
@@ -562,7 +568,7 @@ def _ignore_ids_for_matching(session: Session) -> bool:
 def _sanitize_openai_conversation_item(item: TResponseInputItem) -> TResponseInputItem:
     """Remove provider-specific fields before fingerprinting or persistence."""
     if isinstance(item, dict):
-        clean_item = dict(item)
+        clean_item = cast(dict[str, Any], strip_internal_input_item_metadata(item))
         clean_item.pop("id", None)
         clean_item.pop("provider_data", None)
         return cast(TResponseInputItem, clean_item)
@@ -585,6 +591,11 @@ def _session_item_key(item: Any) -> str:
             payload = item
         else:
             payload = ensure_input_item_format(item)
+        if isinstance(payload, dict):
+            payload = cast(
+                dict[str, Any],
+                strip_internal_input_item_metadata(cast(TResponseInputItem, payload)),
+            )
         return json.dumps(payload, sort_keys=True, default=str)
     except Exception:
         return repr(item)

tests/memory/test_openai_responses_compaction_session.py

@@ -20,6 +20,10 @@
     is_openai_model_name,
     select_compaction_candidate_items,
 )
+from agents.run_internal.items import (
+    TOOL_CALL_SESSION_DESCRIPTION_KEY,
+    TOOL_CALL_SESSION_TITLE_KEY,
+)
 from tests.fake_model import FakeModel
 from tests.test_responses import get_function_tool, get_function_tool_call, get_text_message
 from tests.utils.simple_session import SimpleListSession
@@ -215,6 +219,104 @@ async def test_run_compaction_auto_without_response_id_uses_input(self) -> None:
         assert "previous_response_id" not in call_kwargs
         assert call_kwargs.get("input") == items
 
+    @pytest.mark.asyncio
+    async def test_run_compaction_input_mode_strips_internal_tool_call_metadata(self) -> None:
+        mock_session = self.create_mock_session()
+        items: list[TResponseInputItem] = [
+            cast(
+                TResponseInputItem,
+                {
+                    "type": "function_call",
+                    "call_id": "call_123",
+                    "name": "lookup_account",
+                    "arguments": "{}",
+                    TOOL_CALL_SESSION_DESCRIPTION_KEY: "Lookup customer records.",
+                    TOOL_CALL_SESSION_TITLE_KEY: "Lookup Account",
+                },
+            ),
+            cast(
+                TResponseInputItem,
+                {
+                    "type": "function_call_output",
+                    "call_id": "call_123",
+                    "output": "ok",
+                },
+            ),
+        ]
+        mock_session.get_items.return_value = items
+
+        mock_compact_response = MagicMock()
+        mock_compact_response.output = []
+
+        mock_client = MagicMock()
+        mock_client.responses.compact = AsyncMock(return_value=mock_compact_response)
+
+        session = OpenAIResponsesCompactionSession(
+            session_id="test",
+            underlying_session=mock_session,
+            client=mock_client,
+            compaction_mode="input",
+        )
+
+        await session.run_compaction({"force": True})
+
+        call_kwargs = mock_client.responses.compact.call_args.kwargs
+        compact_input = cast(list[dict[str, Any]], call_kwargs["input"])
+        assert compact_input[0]["type"] == "function_call"
+        assert TOOL_CALL_SESSION_DESCRIPTION_KEY not in compact_input[0]
+        assert TOOL_CALL_SESSION_TITLE_KEY not in compact_input[0]
+
+    @pytest.mark.asyncio
+    async def test_run_compaction_uses_sanitized_cached_items_after_add(self) -> None:
+        mock_session = self.create_mock_session()
+        mock_session.get_items.return_value = []
+
+        mock_compact_response = MagicMock()
+        mock_compact_response.output = []
+
+        mock_client = MagicMock()
+        mock_client.responses.compact = AsyncMock(return_value=mock_compact_response)
+
+        session = OpenAIResponsesCompactionSession(
+            session_id="test",
+            underlying_session=mock_session,
+            client=mock_client,
+            compaction_mode="input",
+        )
+
+        await session._ensure_compaction_candidates()
+        await session.add_items(
+            [
+                cast(
+                    TResponseInputItem,
+                    {
+                        "type": "function_call",
+                        "call_id": "call_cached",
+                        "name": "lookup_account",
+                        "arguments": "{}",
+                        TOOL_CALL_SESSION_DESCRIPTION_KEY: "Lookup customer records.",
+                        TOOL_CALL_SESSION_TITLE_KEY: "Lookup Account",
+                    },
+                ),
+                cast(
+                    TResponseInputItem,
+                    {
+                        "type": "function_call_output",
+                        "call_id": "call_cached",
+                        "output": "ok",
+                    },
+                ),
+            ]
+        )
+
+        await session.run_compaction({"force": True})
+
+        call_kwargs = mock_client.responses.compact.call_args.kwargs
+        compact_input = cast(list[dict[str, Any]], call_kwargs["input"])
+        assert compact_input[0]["type"] == "function_call"
+        assert TOOL_CALL_SESSION_DESCRIPTION_KEY not in compact_input[0]
+        assert TOOL_CALL_SESSION_TITLE_KEY not in compact_input[0]
+
     @pytest.mark.asyncio
     async def test_run_compaction_auto_uses_input_when_store_false(self) -> None:
         mock_session = self.create_mock_session()