fix(bridge): classify the terminal stop reason instead of testing it for truthiness

[lidge-jun]

Closes #4855

Summary

Anthropic ends a normal turn with stop_reason: "end_turn" and the adapter forwards that string verbatim. The Responses bridge decided the terminal message phase from the raw truthiness of stopReason, so "end_turn" took the "something went wrong" branch and every successful Anthropic-routed turn shipped its final assistant message with no phase. In Codex App the turn renders without the divider that separates activity from the answer, while native OpenAI turns in the same thread render it normally.

The non-streaming path had the same gap for the same reason: cleanDone = e.stopReason === undefined is false for every Anthropic success, so the buffered final_answer flush never ran.

Both call sites now ask isTruncatedStopReason, which is the classifier built for this and already imported in both files. That makes the phase decision agree with its three neighbours in the same case "done": block — lines 1179, 1184 and 1196 already call it — and with lines 538 and 558 on the buffered side.

This is not "treat every terminal as final". A clean stop and a cut-short stop stay distinguishable, and the distinction is now drawn by the same table that draws it everywhere else. TRUNCATED_STOP_REASONS maps Anthropic's refusal, pause_turn, max_output_tokens and model_context_window_exceeded; it deliberately does not map end_turn, stop_sequence or tool_use, and its header already states that an unknown reason is not truncation. Truncated turns still close without a phase, still fail an open tool call, still mark an in-flight search failed, and still suppress the compaction item. The error and incomplete terminals are untouched, and the buffered cleanDone && !errorEvent && !incompleteEvent conjunction stays as written.

Fixing the bridge rather than the Anthropic adapter also covers command-code, which forwards raw AI SDK finish reasons and so returns a truthy "stop" on a clean turn.

Verification

• No local verification was run for this lane: no bun test in any form, no bun run test, test:changed, typecheck, bun x tsc, bun install, build:gui, or ocx invocation. A past local suite run deleted real ~/.opencodex data, so this lane verifies by static source reading and treats hosted CI at the exact head as the evidence of record.
• The defect and the fix were read at f1dfda8e48: src/bridge/sse.ts:1174, src/bridge/response-json.ts:530, and the TRUNCATED_STOP_REASONS table in src/responses/truncated-stop-reason.ts.
• The consumer contract was checked against the Codex upstream source rather than inferred from the report. codex-rs/rollout-trace/src/reducer/conversation/normalize.rs maps the phase string to ConversationChannel::Final and returns None for a missing phase, and codex-rs/thread-store/src/local/thread_history.rs resolves final_agent_item_id by json_extract(item_json, '$.phase') = 'final_answer' before falling back to the last agent message on a completed turn. That fallback is why this is a display defect rather than an accounting one, which is how the issue describes it.
• Regression coverage lands in the existing tests/adapters/bridge.test.ts, which already drives both bridgeToResponsesSSE and buildResponseJSON, so no new test file and no layout.json entry. Four cases per entry point: end_turn produces final_answer, max_output_tokens produces no phase, refusal produces no phase and still reports content_filter, and an absent stopReason keeps its existing behaviour. The two truncation cases are what would catch an over-broad fix.
• structure/transports/responses.md is updated in this commit because it owns this behaviour.

Checklist

• Scope stays focused and avoids unrelated cleanup. Two predicates and their regressions.
• Docs or release notes were updated when needed. structure/transports/responses.md is updated; no docs-site/ page documents the phase marker.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults. No auth, credential, workflow, or release path is touched, and nothing new is logged.

Summary by CodeRabbit

• Bug Fixes

  • Improved completion status handling for truncated responses, including token limits and refusals.
  • Normal completions are now consistently marked as final answers across streaming, buffered, and Responses-based workflows.
  • Preserved adapter-provided phases while preventing truncated responses from being reported as fully complete.

• Tests

  • Added coverage for normal, truncated, refused, streaming, and buffered response scenarios.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-17T09:06:14.239913Z	809ec74	PR opened

ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 8ac305b4-fa3d-4f0e-8039-3702f4beabc2

📥 Commits

Reviewing files that changed from the base of the PR and between a1fe84b and 809ec74.

📒 Files selected for processing (4)

• src/bridge/response-json.ts
• src/bridge/sse.ts
• structure/transports/responses.md
• tests/adapters/bridge.test.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 2 remain after this review.

---

📝 Walkthrough

Walkthrough

The bridge now classifies terminal stop reasons consistently. Non-truncated reasons produce clean completions and final_answer phases. Truncation reasons preserve incomplete status and inferred phases. Streaming and buffered tests cover these outcomes.

Changes

Stop-reason phase normalization

Layer / File(s)	Summary
Bridge classification and phase handling src/bridge/response-json.ts, src/bridge/sse.ts, structure/transports/responses.md, tests/adapters/bridge.test.ts	done events now use isTruncatedStopReason. Non-truncated reasons, including end_turn, produce clean completions and final_answer phases. Truncated reasons preserve incomplete handling. Tests cover streaming and buffered responses for absent, normal, and truncated stop reasons.

Priority: ➖ Normal

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix · Severity of issue fixed: Medium

Merge Risk: ⚪ Minimal · up to 809ec

The terminal-phase normalization is covered across both response paths, with no actionable merge risk identified.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 3 files. (1 skipped: 1 …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: the bridge now classifies terminal stop reasons instead of testing raw stop-reason truthiness. This applies to the streaming and non-streamin…
Linked Issues check	✅ Passed	The PR satisfies #4855. In src/bridge/sse.ts in the done handler (the former raw-truthiness check near line 1174), message closure now uses isTruncatedStopReason(event.stopReason). Clean reasons…
Out of Scope Changes check	✅ Passed	The changed production code is limited to terminal stop-reason classification in the streaming and buffered Responses bridges. The added tests and the structure/transports/responses.md update docume…

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 3 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/l6-clean-stop-final-answer

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

✅ Deterministic PR hygiene checks passed.

[lidge-jun]

리뷰 · 우선순위 77 / 80

이 PR은 #4855를 닫는 실제 버그 수정이다. Anthropic(그리고 command-code)이 정상 턴을 stopReason: "end_turn" / "stop"처럼 진실값(truthy) 문자열로 끝내면, Responses 브릿지가 그 문자열을 "뭔가 잘못됐다"로 읽어 최종 assistant 메시지에 phase: "final_answer"를 안 붙인다. Codex App에서는 활동과 답을 가르는 divider가 안 나오고, 같은 스레드의 네이티브 OpenAI 턴만 정상으로 보이는 증상이다. 현재 dev HEAD는 a1fe84b31(패키지 2.58.0, tip #4880 — L4 Responses private-field 플랜; 바로 아래는 #4879 L6 contract/quality 플랜)이다. 이 브랜치 codex/l6-clean-stop-final-answer의 베이스도 그 tip이라 리베이스가 필요 없다. L6 플랜 문서 devlog/_plan/260917_l6_contract_quality_fixes/010_4855_terminal_stop_classification.md가 바로 이 U1을 적어 두었고, 이 PR은 그 계약을 코드로 옮긴 것이다.

지금 tip의 src/bridge/sse.ts case "done": 블록을 보면 네 군데가 event.stopReason을 읽는다. 1179(열린 tool fail), 1184(web-search failed/completed), 1196(compaction 억제)는 이미 isTruncatedStopReason을 쓰고, 1174의 closeCurrentMessage(event.stopReason ? undefined : "final_answer")만 원시 진실값 검사다. src/bridge/response-json.ts도 같다. 530의 cleanDone = e.stopReason === undefined만 원시이고, 538/558은 이미 분류기를 탄다. src/responses/truncated-stop-reason.ts 헤더는 "Unknown reasons are deliberately NOT truncated"라고 못 박아 두었고, Anthropic의 end_turn / stop_sequence / tool_use는 표에 없다. 그래서 이 PR의 한 줄 교체—isTruncatedStopReason(...) ? undefined : "final_answer"와 cleanDone = !isTruncatedStopReason(...)—는 이웃 세 결정과 같은 표를 쓰게 만들 뿐, truncation 의미(무 phase, open tool fail, search failed, compaction 억제)는 그대로 둔다. 어댑터를 고치지 않고 브릿지를 고치는 이유도 맞다. command-code가 AI SDK "stop"을 그대로 넘기면 같은 함정에 빠지기 때문이다.

회귀는 기존 tests/adapters/bridge.test.ts에 스트리밍·버퍼 각 4케이스로 들어간다. end_turn → final_answer, max_output_tokens / refusal → phase 없음(+ incomplete 이유), absent stopReason → 기존처럼 final_answer. 잘림 두 케이스가 "모든 터미널을 final로 취급"하는 과한 수정을 잡는다. structure/transports/responses.md도 같은 규칙으로 고쳐 ownership 계약을 맞춘다. 로컬 bun test는 돌리지 않았고(레인 규율: 예전에 ~/.opencodex를 지운 사고), 증거는 exact-head hosted CI다. 지금 head 809ec74bc의 checks는 hygiene in_progress, 나머지 queued 상태라 mergeable은 아직 blocked다.

이 수정은 types.ts/config.ts 스플릿 캠페인과 무관하고, 중복 PR도 아니다. #4855 본문이 제안한 diff와 플랜 U1과 바이트 단위로 거의 같다. 디스플레이 결함이지 accounting 결함이 아닌 이유도 Codex 쪽 phase = final_answer → ConversationChannel::Final / final_agent_item_id 조회와 맞다 — phase가 없으면 fallback으로 마지막 agent message를 쓰므로 숫자는 맞고 divider만 빠진다.

src/bridge/sse.ts:1174 - 지금은 event.stopReason ? 진실값 분기. PR이 isTruncatedStopReason으로 바꿔 이웃 1179/1184/1196과 같은 표를 쓰게 한다. tip에서 import는 이미 있다.
src/bridge/response-json.ts:530 - cleanDone = e.stopReason === undefined가 Anthropic 성공 턴마다 false. PR이 !isTruncatedStopReason으로 바꿔 아래 flushText(cleanDone && ...)가 final_answer를 붙이게 한다.
src/responses/truncated-stop-reason.ts - 표에 end_turn/stop_sequence/tool_use가 없고 unknown은 truncation이 아니다. 이 PR은 표를 안 건드린다(올바름).
tests/adapters/bridge.test.ts - end_turn / max_output_tokens / refusal / absent 네 갈래 × 스트리밍·버퍼. over-broad fix 탐지용 truncation 케이스가 있다. stop_sequence / tool_use / command-code "stop" 문자열은 표에 없지만 테스트 행렬에는 없다(선택).
structure/transports/responses.md - "clean terminal done" 문구를 classifier 기준으로 고친다. structure ownership과 맞다.
CI @ 809ec74 - hygiene in_progress, changes/windows/label/react-doctor/resolve-pr queued. 머지 전에 exact-head green 대기.
베이스 a1fe84b - tip과 동일. 리베이스 불필요.

메인테이너의 판단이 필요한 지점

• L6 플랜 U1을 이 PR로 닫은 뒤 U2([Bug] Z.AI model discovery uses wrong endpoint and rejects models[].slug response #4822 zai discovery)로 바로 갈지, Anthropic clean end_turn is treated as a non-clean stop, so the final assistant message loses phase: "final_answer" #4855 닫힘·릴리즈 노트 한 줄을 먼저 볼지
• 테스트 행렬에 stop_sequence / AI SDK "stop"을 한 줄 더 넣을지, end_turn+absent로 충분하다고 볼지
• truncation 표 확장(새 provider finish reason)은 이 PR 범위 밖으로 둘지, 후속 이슈로 열지

너의 추천
KEEP. exact-head CI(특히 tests/adapters/bridge.test.ts가 도는 changes/windows 다리)가 green이면 머지해도 된다. 스코프가 두 predicate + 회귀 + structure 한 파일이고 tip에 정확히 올라가 있다. 머지되면 #4855는 Closes로 자동 닫히게 두고, L6 플랜 010 체크를 닫은 다음 U2로 넘어가라. 테스트에 "stop" 한 케이스를 더 넣고 싶으면 follow-up으로 충분하고, 이 PR을 막지는 마라.

이 댓글은 grok-bot이 작성했습니다