[DZH166]

Fixes #10373

Problem

RawOpenAIChatClient._shell_item_to_contents converts a provider local_shell_call whose action.command list is empty into a shell_tool_call carrying the raw local item, and appends no terminal result. Two things then break:

• stateless replay goes through the managed-item route (_prepare_shell_transcript_item_for_openai expects a ResponseFunctionShellToolCall), so it raises ChatClientInvalidRequestException: Stateless replay cannot reconstruct shell_call ...;
• service-side replay loses the empty shell_call_output because the recorded item never had a matching output.

The sibling managed shell_call branch already records shell_tool_call plus a paired empty shell_tool_result (the orphaned-call fix); the local branch was left behind.

before: contents == ['shell_tool_call']            (expected ['shell_tool_call', 'shell_tool_result'])
        stateless replay raises ChatClientInvalidRequestException
        replay emits 0 shell_call / 0 shell_call_output items
after : contents == ['shell_tool_call', 'shell_tool_result']
        stateless replay emits the empty shell_call plus its shell_call_output
        service-side replay keeps exactly one empty shell_call_output

Fix

Record the paired empty shell_tool_result for an empty local_shell_call, using the same marker as the managed branch, so history stays replayable.

A local shell call that does run commands still converts to a function_call, unchanged.

Tests

tests/openai/test_openai_chat_client.py gains tests for the recorded contents, stateless replay, and service-side replay of an empty local shell call.

pytest tests/openai/test_openai_chat_client.py -k empty_local_shell_call -q    # before: 4 failed   after: 4 passed
pytest tests/openai/test_openai_chat_client.py -k shell -q                     # 78 passed, 1 pre-existing env failure (private openai._make_tools import)

[Copilot]

🟡 Changes recommended

Service-side continuation serializes local-shell results with the wrong output type and identifier, requiring preservation of the native call kind and item ID and test assertions for the correct wire format.

1 open issue

• Preserve the local-shell call kind and ID in continuation output · New

What changed in this PR

This PR updates the Python OpenAI client to record empty provider local_shell_call items as paired shell calls and results, aiming to make their history replayable.

Changes:

• Normalize empty local shell calls to a replayable shell-call representation and append an empty result.
• Add regression cases for stateless replay, service-side continuation, and result serialization round trips.

File	Description
python/​packages/​openai/​tests/​openai/​test_openai_chat_client.py	Adds parameterized empty local-shell replay tests.
python/​packages/​openai/​agent_framework_openai/​_chat_client.py	Normalizes empty local shell calls and records paired empty results.

_{Review effort: Balanced}

[DZH166]

Reading the serializer again, the mismatch you describe is real: the call content keeps the local-shell metadata (local_shell_call_output + the provider item id) that this branch writes before the raw_representation swap, so it still leaves through _prepare_shell_transcript_item_for_openai(..., expected_type="local_shell_call") (line 2353), while the paired result I add carries only _LOCAL_TOOL_RESULT_KEY and therefore leaves through the shell_tool_result arm as shell_call_output keyed by call_id (line 2384). So the pair can come out as local_shell_call + shell_call_output.

That is exactly the inconsistency to fix, but the fix changes what the service-side continuation stores, and the two candidates are not equivalent:

1. give the result the same local metadata as the call (OPENAI_SHELL_OUTPUT_TYPE_KEY / local_shell_call_item_id), so the pair stays local_shell_call + local_shell_call_output keyed by the item id, and drop the raw_representation rewrite; or
2. keep the rewrite, and give both the call and the result the shell_call metadata so the pair is shell_call + shell_call_output keyed by call_id.

Option 1 matches the native item the service already stores; option 2 matches the "an empty call that ran no commands is equivalent to shell_call" comment. My concern with 1 is that it puts back the empty local_shell_call payload that stateless replay rejects today (ChatClientInvalidRequestException), which is what this PR exists to avoid — so 1 only works if the empty action is replayed differently for a continuation than for a stateless request.

I don't want to guess at the wire contract: the repo tests can assert either shape, so whichever one the service actually accepts decides it. I've asked in the thread; if option 1 is the intended contract I'll swap the metadata and update test_empty_local_shell_call_item_replays_with_empty_output to assert local_shell_call_output keyed by the item id, and if option 2 is right the result needs the shell_call metadata instead of the current bare _LOCAL_TOOL_RESULT_KEY. Point me at the expected payload and I'll land it either way.

[Eduard van Valkenburg (eavanvalkenburg)]

DZH166 Thanks for the contribution. This changes function-call history and replay behavior in a stable contract area, so it needs an agreed issue with explicit maintainer direction before implementation review resumes. Please link that issue and confirm the intended replay behavior against the function-calling loop contract. Approval remains blocked until that direction is established.

[DZH166]

Status note after the latest rebase, because the related issue record changed while this PR was open:

• Python: [Bug]: Empty local shell commands produce an orphan shell call on replay #9697 ("Empty local shell commands produce an orphan shell call on replay") was closed as completed on 2026-11-06 by Python: fix empty local shell calls leaving orphaned history #9803 ("fix empty local shell calls leaving orphaned history"). That PR treats an empty command list as a no-op with a matching empty output.
• On current main, _shell_item_to_contents() still records the empty local_shell_call as a bare shell_tool_call with raw_representation=item and appends no paired result (see the else: branch after the local_command_parts check), so the shape this PR changes is still what the client produces.

So the question is whether the remaining gap is in scope after #9803: if it is, I will open a focused issue (state snapshot style, with a reproduction that does not need a live deployment) and link it here; if #9803 is considered to have covered this path, feel free to close this PR as redundant — I would rather not argue the point with a merged fix in the tree.

Everything else is green on the rebased head; the earlier Pre-commit Hooks (3.11) failure was an Unexpected HTTP response: 504 from the action download step, not a lint result.

[Eduard van Valkenburg (eavanvalkenburg)]

DZH166 Persist the reconstructed call for history replay — The reconstructed shell call exists only in raw_representation, which Content.to_dict() omits. After the whole message is serialized and restored, stateless replay raises ChatClientInvalidRequestException because it cannot reconstruct the call. The new round-trip test serializes only the result, so it misses this path. Preserve sufficient call data across message serialization and test the complete message round trip.

[DZH166]

Implemented in dcc0045, on top of the focused issue you asked for (#10373):

• the empty local_shell_call now records the provider item id in additional_properties (which Content.to_dict() does serialize) instead of relying on raw_representation;
• _prepare_shell_transcript_item_for_openai() falls back to _rebuild_shell_call_payload() when raw_representation is None, rebuilding {type, call_id, status, action.commands} plus the item id and environment: {"type": "local"}, i.e. exactly the payload this branch already emits in memory and the provider already validates;
• test_empty_local_shell_call_item_replays_with_empty_output now round-trips the whole message (Message.from_json(message.to_json())) instead of only the result, so it exercises the persisted-conversation path that used to raise ChatClientInvalidRequestException.

The pair still serializes as shell_call + shell_call_output keyed by call_id (option 2 from my earlier note), which is the shape the empty-action path can rebuild from typed fields alone.

[Eduard van Valkenburg (eavanvalkenburg)]

DZH166 The remaining local_shell_call replay gap is in scope, but it is distinct from the completed #9697/#9803 work because current main still has a separate provider-item serialization path that can lose the paired history. Please open the focused issue you proposed with the current-main reproduction and intended wire/replay contract, then link it here. Keep this PR aligned with that issue and the function-calling loop contract.