Repository navigation
Parse converted streams at complete SSE event boundaries #225
Description
Parent
Part of #147. Delivers the migration-and-contract slice that completes #20.
What to build
Migrate protocol-conversion streams to parse JSON only from complete events emitted by the lossless SSE Event Assembler. Transparent Passthrough must remain byte-preserving, while converted routes gain one event-boundary error and termination contract.
Acceptance criteria
- Every converted streaming route consumes complete assembled SSE events rather than transport lines or arbitrary byte chunks.
- Multi-line
data:events are joined according to SSE semantics before JSON parsing, and[DONE]or protocol terminals are handled only at event boundaries. - Transparent Passthrough continues forwarding original bytes and does not enter the conversion parser.
- Malformed complete events produce the target protocol's bounded stream error without corrupting earlier valid output or emitting duplicate terminal output.
- A scope audit and regression matrix cover Official, third-party transparent, and converted routes and demonstrate that no production line-oriented SSE JSON parser remains.
Activity
NOirBRight commentedon Jul 25, 2026
{ "contract": { "acceptance": [ "A static audit proves every converted production stream parses JSON only from complete assembler frames and no line-oriented or arbitrary-chunk SSE JSON parser remains.", "Adversarial fragmentation, multiple data fields, CR/LF/CRLF, metadata/comments, empty frames, and [DONE] fixtures produce the same target events regardless of transport chunking.", "Responses-to-Chat and Chat-to-Responses preserve ordered text, reasoning where representable, tool-call IDs/names/arguments/results, usage, canonical model identity, and their protocol-correct single terminal sequence.", "Transparent routes remain byte-identical and do not enter semantic conversion, including raw invalid UTF-8 and unknown SSE fields.", "Malformed complete converted frames produce one sanitized target-protocol error and exactly one request_complete=502 with no payload echo, retry, fallback, duplicate terminal, or later success output.", "EOF with an incomplete pending frame never becomes a semantic event and follows the existing incomplete-stream failure classification without partial success.", "Official and verified third-party Responses/Chat conversion matrices remain deterministic; unverified generic protocol endpoints retain best-effort behavior without new pre-emptive capability rejection.", "No intermediate 12-case real-client run is performed; the final frozen 0.1.7 candidate validates supported client routes under Issue #227." ], "change_claims": { "paths": [ "src-python/codex_proxy.py", "src-python/protocol_translation.py", "src-python/sse_events.py", "tests/test_routing.py", "tests/test_chat_completions_gateway.py", "tests/test_protocol_translation.py", "tests/test_sse_events.py" ], "resources": [ "gateway-converted-sse", "gateway-protocol-bridge", "gateway-sse-event-assembler", "gateway-downstream-stream-commit" ] }, "dependencies": { "dispatch_after": [ 224 ], "merge_after": [ 224 ] }, "design": [ "Migrate every production Responses-to-Chat and Chat-to-Responses streaming conversion path to consume complete frames from the #224 SSE Event Assembler. Remove route-local line/chunk JSON assembly instead of layering another parser.", "Parse semantic JSON only from the assembler's joined data value. Recognize the exact [DONE] sentinel only at a complete event boundary; comment-only, metadata-only, and empty frames remain non-payload frames.", "Keep Transparent Passthrough outside the conversion parser and forward its original bytes unchanged. Converted routes preserve source event order, canonical model/tool/reasoning/usage identity, and all metadata that the target protocol can represent without inventing fields.", "For a complete converted frame whose data is invalid UTF-8, invalid JSON, or structurally invalid for the source protocol, use the existing request-scoped downstream commit seam to emit one sanitized target-protocol failure and exactly one 502 completion. Never echo source payload, retry, fall back, or emit a success terminal after exposure.", "Preserve normal target-protocol framing, Chat finish-reason followed by DONE, Responses terminal semantics, tool-call argument continuity, keepalive behavior, cancellation, and the reader lifecycle established by #19.", "Keep protocol-specific semantic conversion in protocol_translation.py and event framing in sse_events.py. Do not create a universal planner, provider mapper, or second protocol bridge." ], "difficulty": "heavy", "done_when": [ "Focused RED/GREEN regressions for complete-event assembly, malformed converted events, target terminal uniqueness, tools, transparent byte identity, and the scope audit pass on the exact local candidate.", "python -m pytest -q tests/test_sse_events.py tests/test_protocol_translation.py", "A reviewed explicit pytest node list covering only affected converted-stream tests in tests/test_routing.py and tests/test_chat_completions_gateway.py passes; the delivery record lists every node or bounded -k selector used.", "A static audit proves no production converted route parses SSE JSON from physical lines or arbitrary chunks and no second SSE assembler exists.", "python -m py_compile src-python/codex_proxy.py src-python/protocol_translation.py src-python/sse_events.py tests/test_routing.py tests/test_chat_completions_gateway.py tests/test_protocol_translation.py tests/test_sse_events.py", "git diff --check", "python scripts/report_quality_gates.py (report-only)", "The Worker must not run repository-wide or bare pytest, the synthetic real-client harness, or real-client GUI E2E; reuse prior evidence, reserve complete remote coverage for exact-SHA Actions after freeze, and reserve final real-client qualification for #227.", "Exact-local-SHA Standards and strict Spec reviews report no blocker before the branch is pushed once.", "After local freeze, exactly one push/PR update and exact-SHA GitHub Actions run pass; no intermediate real-client qualification is run." ], "priority": "P1", "risk": "strict", "sha256": "e3edc856bfd3ff0d4a89211c029a3c342c15549e93699a4f18e0d946c0eae790", "unresolved_decisions": [] }, "dispatch": { "accepted_at": "2026-07-26T13:51:43Z", "attempt": 1, "base_sha": "c41fa9fbb2b906e8fe807a777f592b9fa5bfc29a", "branch": "work/issue-225", "candidate_sha": "83c3ecb7f31e5f1c5ebea504b3ecf733303ea2e1", "claimed_at": "2026-07-26T08:44:51.659956Z", "contract_sha256": "e3edc856bfd3ff0d4a89211c029a3c342c15549e93699a4f18e0d946c0eae790", "creator_agent_id": "d81c5928-aff7-4d9d-b6a0-2b9f70ffad21", "generation": 1, "id": "dispatch-issue-225-a1", "integrating_at": "2026-07-26T13:53:49.058920Z", "merged_at": "2026-07-26T13:53:55Z", "pr_number": 234, "status": "merged", "worker_agent_id": "504b451b-8319-4104-98fb-1560a5ca891d", "workspace_id": "wks_8950732fd23a5b5d" } }NOirBRight commentedon Jul 26, 2026
Delivered by merged PR #234.