Python: Align Responses hosting parser semantics

[Eduard van Valkenburg (eavanvalkenburg)]

Motivation & Context

The hosting Responses helpers accepted a nonstandard continuation field, silently chose between conflicting continuation mechanisms, and defaulted malformed message input. Final conversion also merged message boundaries, emitted fixed response fields even when AgentResponse carried real values, and represented ordinary media as fabricated function-call output.

This aligns the helper-first hosting surface with the official OpenAI Responses request and output schemas while keeping the existing lightweight streaming design.

Description & Review Guide

• What are the major changes?
  • Accept official conversation string/object requests, reject conflicting continuation mechanisms, and retain conversation_id only as a warned compatibility fallback.
  • Validate required text, role, and message content instead of producing empty/defaulted messages.
  • Preserve assistant message boundaries, tool-role function results, and response status, metadata, and usage; reject only non-assistant content that would be relabeled as an assistant message, plus standalone media that lacks a valid Responses output representation.
  • Update focused parser/HTTP coverage, the hosting specification, package documentation, and local Responses sample terminology.
• What is the impact of these changes?
  • Standards-compliant callers can use conversation directly. Existing standalone conversation_id callers continue to work with a deprecation warning.
  • Conflicting or malformed requests now fail clearly, and final payloads reflect available AgentResponse fields instead of fixed defaults.
• What do you want reviewers to focus on?
  • The continuation compatibility boundary and the final-output choices for roles, message boundaries, usage, and unsupported standalone media.

Related Issue

N/A

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and the title prefix in sync automatically.

[Copilot]

Pull request overview

Aligns Python Responses hosting helpers with OpenAI request and output semantics.

Changes:

• Adds official conversation handling and stricter request validation.
• Preserves output boundaries, status, metadata, and usage while rejecting unsupported output.
• Updates tests, specifications, and samples.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
python/samples/04-hosting/af-hosting/local_responses/README.md	Updates continuation terminology.
python/samples/04-hosting/af-hosting/local_responses/app.py	Updates conversation documentation.
python/samples/04-hosting/af-hosting/local_responses_workflow/README.md	Documents unsupported conversation continuation.
python/samples/04-hosting/af-hosting/local_responses_workflow/call_server.py	Updates client comments.
python/samples/04-hosting/af-hosting/local_responses_workflow/app.py	Updates rejection messaging.
python/samples/04-hosting/af-hosting/local_responses_harness/README.md	Updates continuation terminology.
python/samples/04-hosting/af-hosting/local_responses_harness/app.py	Updates conversation documentation.
python/packages/hosting-responses/tests/hosting_responses/test_parsing.py	Expands parser and conversion coverage.
python/packages/hosting-responses/tests/hosting_responses/test_http_round_trip.py	Adds HTTP validation and conversation tests.
python/packages/hosting-responses/README.md	Documents official conversation semantics.
python/packages/hosting-responses/agent_framework_hosting_responses/_parsing.py	Implements validation and response conversion changes.
docs/specs/002-python-hosting-channels.md	Updates the hosting contract and example.

Suppressed comments (1)

python/packages/hosting-responses/agent_framework_hosting_responses/_parsing.py:395

• The raw-field fallback does not work for finalized streams. AgentResponse.from_updates stores raw updates in a list, and agent updates wrap the provider event in another raw_representation; this code only inspects the list object itself. Consequently a real streamed terminal response can lose its status and metadata (for example, an upstream failed response is converted as completed). Traverse sequences and nested raw_representation/response objects from the last update backward.

    raw = result.raw_representation
    for source in (raw, getattr(raw, "raw_representation", None)):
        if isinstance(source, Mapping):
            value = cast("Mapping[str, Any]", source).get(key)
        else:

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/hosting-responses/agent_framework_hosting_responses
_parsing.py	630	199	68%	90, 95, 121, 152, 311, 318, 327, 339, 385, 393, 405, 431–433, 461, 465, 480–483, 485–490, 492–495, 499–509, 517–518, 549–551, 553–557, 561–564, 566–569, 571–574, 589–590, 592–593, 595–596, 598–599, 601–602, 604–605, 607–608, 610–611, 616–620, 684, 698, 718, 721–724, 726, 745–752, 754, 770–772, 786, 798, 810, 825–832, 834, 845–846, 860, 870, 879, 883, 887–888, 893–896, 903, 907–915, 919–924, 928–935, 939–943, 947–949, 953–955, 959–961, 966, 968, 973–979, 985–988, 996–1000, 1008–1010, 1015–1021, 1025–1028, 1109
TOTAL	48546	4496	90%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
9906	36 💤	0 ❌	0 🔥	2m 42s ⏱️

[github-actions]

MAF Automated Review — Iteration 1

Result: Findings reported
Scope: full PR (2 commit(s)): 278735180f9f, 31505a4331ab
Model: gpt-5.6-sol

Overview

The review found 3 verified inline finding(s).

Reviewed the supplied pull-request change set across correctness, security/reliability, architecture, and failure behavior.
3 verified findings remained after source verification (1 high, 2 medium) across 1 file. Details are attached to the affected lines below.

Affected areas: python/packages/hosting-responses/agent_framework_hosting_responses/_parsing.py

[github-actions]

MAF Automated Review — Iteration 2

Result: Findings reported
Scope: 1 net-new commit(s): 32b856f7b8cb
Model: gpt-5.6-sol

Overview

This incremental update correctly separates raw transport status from flattened user metadata, accepts partial top-level usage counters, and aligns streaming terminal event types with final response status. The traversal and terminal-status tests provide strong coverage for the prior findings. One remaining usage edge case can serialize internally inconsistent token accounting when detail counters are present without their optional parent counters.

Reviewed the supplied incremental change set across correctness, security/reliability, architecture, and failure behavior.
1 verified finding remained after source verification (1 medium) across 1 file. Details are attached to the affected lines below.

Affected areas: python/packages/hosting-responses/agent_framework_hosting_responses/_parsing.py