From b630dd9a7611b56e0f364d6da16198ddfd529e8a Mon Sep 17 00:00:00 2001 From: DZH166 <248446924+DZH166@users.noreply.github.com> Date: Sat, 7 Nov 2026 00:34:37 +0800 Subject: [PATCH 1/3] Python: replay an empty local_shell_call with its matching shell output A local_shell_call with an empty command list was converted to a lone shell_tool_call with no matching result, so stateless replay raised ChatClientInvalidRequestException and service-side replay lost the empty shell_call_output. Record the paired empty shell_tool_result, as the managed shell_call branch already does. --- .../agent_framework_openai/_chat_client.py | 36 +++++++++++++++++-- .../tests/openai/test_openai_chat_client.py | 36 +++++++++++++++++++ 2 files changed, 70 insertions(+), 2 deletions(-) diff --git a/python/packages/openai/agent_framework_openai/_chat_client.py b/python/packages/openai/agent_framework_openai/_chat_client.py index f9580bf4093..c085edd4235 100644 --- a/python/packages/openai/agent_framework_openai/_chat_client.py +++ b/python/packages/openai/agent_framework_openai/_chat_client.py @@ -2824,15 +2824,47 @@ def _shell_item_to_contents(self, item: Any, local_shell_tool_name: str | None) ) ) else: + provider_status = _provider_status(getattr(item, "status", None)) + empty_local_call = bool( + local_shell_tool_name + and local_call_id + and local_call_item_id + and isinstance(raw_local_command_parts, list) + and not raw_local_command_parts + ) contents.append( Content.from_shell_tool_call( call_id=local_call_id, commands=[local_command] if local_command else [], timeout_ms=getattr(getattr(item, "action", None), "timeout_ms", None), - status=_provider_status(getattr(item, "status", None)), - raw_representation=item, + status=provider_status, + # An empty ``local_shell_call`` has no replayable local form: its provider + # payload only validates as ``local_shell_call``, which this client never + # emits on replay. A call that ran no commands is equivalent to a + # ``shell_call`` with an empty action, so record that shape and pair it with + # the terminal output below instead of leaving an orphaned shell call. + raw_representation=( + { + "id": local_call_item_id, + "type": "shell_call", + "call_id": local_call_id, + "status": provider_status or "completed", + "environment": {"type": "local"}, + "action": {"commands": []}, + } + if empty_local_call + else item + ), ) ) + if empty_local_call: + contents.append( + Content.from_shell_tool_result( + call_id=local_call_id, + outputs=[], + additional_properties={_LOCAL_TOOL_RESULT_KEY: True}, + ) + ) elif item_type == "shell_call_output": shell_output_call_id = getattr(item, "call_id", None) or "" shell_outputs: list[Content] = [] diff --git a/python/packages/openai/tests/openai/test_openai_chat_client.py b/python/packages/openai/tests/openai/test_openai_chat_client.py index 4f664a1d50c..4372dfa0412 100644 --- a/python/packages/openai/tests/openai/test_openai_chat_client.py +++ b/python/packages/openai/tests/openai/test_openai_chat_client.py @@ -67,6 +67,7 @@ ResponseOutputTextAnnotationAddedEvent, ResponseStreamEvent, ) +from openai.types.responses.response_output_item import LocalShellCall, LocalShellCallAction from openai.types.responses.response_reasoning_item import ResponseReasoningItem, Summary from openai.types.responses.response_reasoning_summary_text_delta_event import ( ResponseReasoningSummaryTextDeltaEvent, @@ -2958,6 +2959,41 @@ def test_empty_local_shell_call_replays_with_empty_output( assert shell_outputs == [expected_output] +@pytest.mark.parametrize("round_trip", [False, True]) +@pytest.mark.parametrize("service_storage", [False, True]) +def test_empty_local_shell_call_item_replays_with_empty_output(round_trip: bool, service_storage: bool) -> None: + """An empty provider ``local_shell_call`` must replay as a matched empty shell pair.""" + client = OpenAIChatClient(model="test-model", api_key="test-key") + item = LocalShellCall( + id="sh_local_empty", + call_id="call_local_empty", + status="completed", + type="local_shell_call", + action=LocalShellCallAction(command=[], env={}, type="exec"), + ) + + contents = client._shell_item_to_contents(item, "run_shell") + + assert [content.type for content in contents] == ["shell_tool_call", "shell_tool_result"] + message = Message("assistant", contents) + if round_trip: + restored_result = Message.from_json(Message("assistant", [contents[1]]).to_json()).contents[0] + message = Message("assistant", [contents[0], restored_result]) + replay = client._prepare_messages_for_openai( + [message, Message("user", ["Continue"])], + request_uses_service_side_storage=service_storage, + ) + + shell_calls = [entry for entry in replay if entry["type"] == "shell_call"] + assert len(shell_calls) == (0 if service_storage else 1) + if not service_storage: + assert shell_calls[0]["call_id"] == "call_local_empty" + assert shell_calls[0]["action"]["commands"] == [] + assert [entry for entry in replay if entry["type"] == "shell_call_output"] == [ + {"type": "shell_call_output", "call_id": "call_local_empty", "output": []} + ] + + @pytest.mark.parametrize("streaming", [False, True]) def test_empty_local_shell_call_parsing_emits_pair_without_execution(streaming: bool) -> None: client = OpenAIChatClient(model="test-model", api_key="test-key") From 1e949dc2735469229272fb47403e3f4ce7c84a4d Mon Sep 17 00:00:00 2001 From: DZH166 <248446924+DZH166@users.noreply.github.com> Date: Sun, 15 Nov 2026 19:00:59 +0800 Subject: [PATCH 2/3] fix(openai): keep the reconstructed empty local shell call across serialization `Content.to_dict()` drops `raw_representation`, so a call rebuilt for an empty `local_shell_call` vanished once the message was persisted: replaying the restored message raised `ChatClientInvalidRequestException: Stateless replay cannot reconstruct shell_call`. Record the provider item id in the serialized metadata and rebuild the payload from the typed fields when `raw_representation` is gone. The round-trip test now serializes the whole message instead of only the result, which is the path a checkpoint takes. Addresses the review note on #10155; tracked by #10373. --- .../agent_framework_openai/_chat_client.py | 44 +++++++++++++++++++ .../tests/openai/test_openai_chat_client.py | 5 ++- 2 files changed, 47 insertions(+), 2 deletions(-) diff --git a/python/packages/openai/agent_framework_openai/_chat_client.py b/python/packages/openai/agent_framework_openai/_chat_client.py index 8a8a8fb3f8f..9d8b12074bc 100644 --- a/python/packages/openai/agent_framework_openai/_chat_client.py +++ b/python/packages/openai/agent_framework_openai/_chat_client.py @@ -2844,6 +2844,22 @@ def _shell_item_to_contents(self, item: Any, local_shell_tool_name: str | None) # emits on replay. A call that ran no commands is equivalent to a # ``shell_call`` with an empty action, so record that shape and pair it with # the terminal output below instead of leaving an orphaned shell call. + # The item id also goes into the serialized metadata, because + # ``raw_representation`` does not survive ``Content.to_dict()``. + additional_properties=( + _openai_additional_properties( + { + _OPENAI_SHELL_OUTPUT_TYPE_NAMESPACE_KEY: OPENAI_SHELL_OUTPUT_TYPE_SHELL_CALL, + _OPENAI_LOCAL_SHELL_CALL_ITEM_ID_NAMESPACE_KEY: local_call_item_id, + }, + legacy={ + OPENAI_SHELL_OUTPUT_TYPE_KEY: OPENAI_SHELL_OUTPUT_TYPE_SHELL_CALL, + OPENAI_LOCAL_SHELL_CALL_ITEM_ID_KEY: local_call_item_id, + }, + ) + if empty_local_call + else None + ), raw_representation=( { "id": local_call_item_id, @@ -3104,6 +3120,8 @@ def _prepare_shell_transcript_item_for_openai( output["max_output_length"] = content.max_output_length return output payload = cls._serialize_provider_payload(content.raw_representation) + if payload is None: + payload = cls._rebuild_shell_call_payload(content, expected_type) if isinstance(payload, Mapping): typed_payload = cast("Mapping[str, Any]", payload) raw_call_id = typed_payload.get("call_id") @@ -3124,6 +3142,32 @@ def _prepare_shell_transcript_item_for_openai( "Use service-side continuation or preserve the original provider response item." ) + @classmethod + def _rebuild_shell_call_payload(cls, content: Content, expected_type: str) -> dict[str, Any] | None: + """Rebuild a shell call payload from the fields ``Content.to_dict()`` keeps. + + ``raw_representation`` is dropped on serialization, so a call restored from a checkpoint + only carries its typed fields. An empty local shell call has everything needed to rebuild + the wire payload, which is what keeps a restored conversation replayable. + """ + if expected_type != "shell_call" or not content.call_id: + return None + item_id = _get_openai_metadata( + content.additional_properties, + _OPENAI_LOCAL_SHELL_CALL_ITEM_ID_NAMESPACE_KEY, + OPENAI_LOCAL_SHELL_CALL_ITEM_ID_KEY, + ) + action: dict[str, Any] = {"commands": list(content.commands or [])} + if content.timeout_ms is not None: + action["timeout_ms"] = content.timeout_ms + payload: dict[str, Any] = {"type": "shell_call", "call_id": content.call_id, "action": action} + if isinstance(item_id, str) and item_id: + payload["id"] = item_id + payload["environment"] = {"type": "local"} + if content.status: + payload["status"] = content.status + return payload + @staticmethod def _serialize_provider_payload(value: Any) -> Any: """Convert OpenAI SDK objects into JSON-serializable Python values.""" diff --git a/python/packages/openai/tests/openai/test_openai_chat_client.py b/python/packages/openai/tests/openai/test_openai_chat_client.py index b61ef109a98..eb5af54921d 100644 --- a/python/packages/openai/tests/openai/test_openai_chat_client.py +++ b/python/packages/openai/tests/openai/test_openai_chat_client.py @@ -2998,8 +2998,9 @@ def test_empty_local_shell_call_item_replays_with_empty_output(round_trip: bool, assert [content.type for content in contents] == ["shell_tool_call", "shell_tool_result"] message = Message("assistant", contents) if round_trip: - restored_result = Message.from_json(Message("assistant", [contents[1]]).to_json()).contents[0] - message = Message("assistant", [contents[0], restored_result]) + # Round-trip the whole message, not only the result: ``Content.to_dict()`` drops + # ``raw_representation``, so this is the shape a persisted conversation takes. + message = Message.from_json(message.to_json()) replay = client._prepare_messages_for_openai( [message, Message("user", ["Continue"])], request_uses_service_side_storage=service_storage, From dcc004590d7d995c3d28bd2a83428e8ba1f3daa3 Mon Sep 17 00:00:00 2001 From: DZH166 <248446924+DZH166@users.noreply.github.com> Date: Sun, 15 Nov 2026 19:02:02 +0800 Subject: [PATCH 3/3] fix(openai): mirror the validated shell_call payload when rebuilding it Keep only the fields the provider payload this branch already emits carries, so a rebuilt call and the in-memory one serialize identically. --- .../openai/agent_framework_openai/_chat_client.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/python/packages/openai/agent_framework_openai/_chat_client.py b/python/packages/openai/agent_framework_openai/_chat_client.py index 9d8b12074bc..5a824dc05e5 100644 --- a/python/packages/openai/agent_framework_openai/_chat_client.py +++ b/python/packages/openai/agent_framework_openai/_chat_client.py @@ -3157,15 +3157,15 @@ def _rebuild_shell_call_payload(cls, content: Content, expected_type: str) -> di _OPENAI_LOCAL_SHELL_CALL_ITEM_ID_NAMESPACE_KEY, OPENAI_LOCAL_SHELL_CALL_ITEM_ID_KEY, ) - action: dict[str, Any] = {"commands": list(content.commands or [])} - if content.timeout_ms is not None: - action["timeout_ms"] = content.timeout_ms - payload: dict[str, Any] = {"type": "shell_call", "call_id": content.call_id, "action": action} + payload: dict[str, Any] = { + "type": "shell_call", + "call_id": content.call_id, + "status": content.status or "completed", + "action": {"commands": list(content.commands or [])}, + } if isinstance(item_id, str) and item_id: payload["id"] = item_id payload["environment"] = {"type": "local"} - if content.status: - payload["status"] = content.status return payload @staticmethod