fix(run): fail fast on incompatible handoff settings with server conversation

[OiPunk]

Summary

This PR adds an early validation guard for server-managed conversations to prevent unsupported handoff combinations from reaching the model API.

When conversation_id, previous_response_id, or auto_previous_response_id is used, the SDK now raises a UserError if handoff settings require local history/tool-state rewriting that the server-managed flow cannot support.

Specifically, it rejects:

• nest_handoff_history=True (when no input filter is set on that handoff)
• remove_all_tools (handoff-local or global run_config.handoff_input_filter)

Why

Issue: #2151

With server-managed conversation, these handoff options can produce invalid or conflicting assumptions about what is sent to downstream turns. The current behavior fails late. This change fails fast with a clear error message before execution starts.

Changes

• Added validate_server_conversation_handoff_settings(...) in agent_runner_helpers.
• Added graph traversal that handles both shorthand Agent handoffs and explicit Handoff entries.
• Invoked validation in both Runner.run and Runner.run_streamed:
  • resumed and non-resumed paths
• Added focused tests for:
  • nested handoff history + server-managed conversation
  • handoff-local remove_all_tools
  • global run_config.handoff_input_filter=remove_all_tools
  • streamed/non-streamed + resumed/non-resumed paths

Validation

• uv run ruff check src/agents/run_internal/agent_runner_helpers.py src/agents/run.py tests/test_agent_runner.py
• uv run mypy src/agents/run_internal/agent_runner_helpers.py src/agents/run.py tests/test_agent_runner.py
• env -u all_proxy -u ALL_PROXY -u http_proxy -u HTTP_PROXY -u https_proxy -u HTTPS_PROXY uv run pytest tests/test_agent_runner.py -k "server_conversation" -q
• env -u all_proxy -u ALL_PROXY -u http_proxy -u HTTP_PROXY -u https_proxy -u HTTPS_PROXY uv run pytest tests/test_agent_runner.py -q
• env -u all_proxy -u ALL_PROXY -u http_proxy -u HTTP_PROXY -u https_proxy -u HTTPS_PROXY uv run python -m trace --count --coverdir /tmp/openai_agents_2151_trace --module pytest tests/test_agent_runner.py -k "server_conversation" -q

Trace output confirms the newly added validation paths in src/agents/run_internal/agent_runner_helpers.py and their call sites in src/agents/run.py are exercised.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2ddabfe993

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[OiPunk]

Thanks, great catch. I updated the validation to skip disabled explicit handoffs (is_enabled=False) when collecting server-conversation constraints, so inactive handoffs no longer trigger false positives.

I also added regression tests covering:

• disabled remove_all_tools handoff with conversation_id
• disabled nest_handoff_history handoff with conversation_id

Local validation after the fix:

• ruff check on modified files passed
• targeted mypy passed
• full make mypy passed (473 files)
• pytest tests/test_agent_runner.py -q passed (98 tests)

Fix commit: 95b4213.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 95b4213ad1

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[OiPunk]

Addressed in commit 482e17a.

What I changed:

• Reduced duplication in AgentRunner.run() by extracting the repeated server-conversation validation into a single local helper (validate_conversation_settings(...)).
• Updated handoff edge collection so handoff-level settings are still validated even when a handoff target is currently unresolved (_agent_ref missing). This keeps the fail-fast behavior consistent for server-managed conversation constraints.
• Added regression coverage for unresolved-handoff validation.

Local verification:

• uv run ruff check src/agents/run.py src/agents/run_internal/agent_runner_helpers.py tests/test_agent_runner.py
• uv run mypy src/agents/run.py src/agents/run_internal/agent_runner_helpers.py
• env -u ALL_PROXY -u all_proxy -u HTTPS_PROXY -u https_proxy -u HTTP_PROXY -u http_proxy -u NO_PROXY -u no_proxy uv run pytest tests/test_agent_runner.py -k "server_conversation_with_nested_handoff_history or server_conversation_with_remove_all_tools_filter or unresolved_remove_all_tools_handoff or global_remove_all_tools_filter" -q (7 passed)