fix: summarize tool messages during role reversal in user simulator (Python)

[Aryansharma28]

What this fixes

The user simulator builds its prompt by calling reverse_roles() on the agent's conversation history. Two classes of messages cannot simply have their role flipped:

1. role: "tool" messages — tool result messages. Relabelling them as role: "user" produces an invalid request that both OpenAI and Anthropic APIs reject outright.
2. role: "assistant" messages with tool_calls — tool call messages. Same problem: tool_calls is not valid on a user message.

The old code worked around this by keeping tool-call messages as-is and dropping tool-result messages. That caused two separate bugs:

• Consecutive assistant roles in the reversed history (the user simulator's context) when the agent made tool calls
• Lost tool context — the user simulator had no idea what the agent had just done

What this changes

Both message types are now summarized as plain text and attributed to role: "user" (i.e. the agent's perspective after reversal):

• {"role": "assistant", "tool_calls": [...]} → [Called tool search_products with: {"query": "headphones"}]
• {"role": "tool", "content": "..."} → [Tool result from search_products: [...]]

This is exactly what the JS messageRoleReversal() already does. This PR brings the Python implementation into alignment.

A bare {"role": "assistant"} message with no content key at all is silently dropped — some models emit these and passing them through would produce an invalid {"role": "user"} message (Anthropic rejects it).

Files changed

• python/scenario/_utils/utils.py — rewrites reverse_roles() with three new helper functions (_stringify_value, _has_tool_content, _summarize_tool_message)
• python/tests/test_reverse_roles.py — 31 unit tests covering all message shapes and edge cases
• python/examples/test_multiturn_tool_calls.py — E2E example: 10-turn shopping conversation where the agent makes tool calls on multiple turns, verifying the user simulator handles the full history correctly

[drewdrewthis]

@Aryansharma28 tests

[drewdrewthis]

The title of the PR doesn't not say that it is summarizing tool calls. this is actually a bit concerning and I think needs further justification?

[Aryansharma28]

Hi @drewdrewthis — thanks for the review comments, addressing both below.

Re: tests — unit tests are now included in python/tests/test_reverse_roles.py (31 tests covering all message shapes), and there's also an E2E example in python/examples/test_multiturn_tool_calls.py that runs a 10-turn shopping conversation with real tool calls to verify the user simulator handles the full history end-to-end.

Re: the title / summarization concern — totally fair, the original title was vague. Updated the title and PR body to explain this properly, but here's the reasoning:

The user simulator builds its prompt by calling reverse_roles() on the agent's conversation history. The problem is that two message types cannot be re-labelled with a different role — they have to be converted to plain text:

• role: "tool" (tool result messages) — both OpenAI and Anthropic APIs reject a user message that has the tool role. You can't just flip the role.
• role: "assistant" with tool_calls — same issue, tool_calls is not valid on a user message.

So the options were:

1. Drop them → user simulator loses all tool context and doesn't know what the agent did
2. Keep them as-is → consecutive assistant roles in the history, which confuses the user simulator
3. Summarize as plain text → the user simulator sees [Called tool X with: ...] / [Tool result from X: ...] as ordinary user messages — valid API request, and the simulator has full context

Option 3 is what the JS messageRoleReversal() already does. This PR brings Python into alignment with that.