docs(devlog): open the L4 Responses private-field and history-repair plan unit

[lidge-jun]

Summary

• Opens the lane plan unit for Responses private-field handling and conversation-history repair. Documentation only: nothing in src/, tests/, or any gate reads this directory.
• Records what the Codex client actually attaches. access_programs (new in Codex 0.155) is gated on ChatGPT auth alone and never on the destination URL, so loopback injection leaves it attached to third-party Responses traffic, where a strict gateway 400s the whole turn ([Provider compatibility] Codex 0.155 access_programs is forwarded to strict third-party Responses upstreams and 400s every OpenCode Go muse-spark turn #4853).
• Records a correction to the reported fix. codex_output_schema is the name of the JSON-schema text.format object in codex-rs/codex-api/src/common.rs, not a top-level request key, so it is deliberately excluded from the strip table rather than stripped on a guess.
• Fixes the destination boundary and the review contracts for the two contributor pull requests this lane reviews (fix(xai): seed Responses tool-result adjacency for interrupted Codex threads #4871, fix(ollama-native): defer a mid-turn conversational message instead of refusing the replay #4848), including the constraint that repairing interrupted tool-call history must not turn off stateful operation.

Verification

• No code, test, workflow, or configuration path is touched, so no gate applies to the content. devlog/ is excluded from the file-size ratchet and is read by no build, typecheck, or test path.
• Upstream claims were verified by reading the Codex checkout directly rather than from the issue text: codex-rs/core/src/cyber_access_program.rs (the auth-only gate), codex-rs/codex-api/src/common.rs (AccessPrograms on ResponsesApiRequest, CompactionInput and ResponseCreateWsRequest), and codex-rs/core/src/client.rs (the three assignment sites).
• Repository claims were verified by reading this tree: the noncanonical boundary and CANONICAL_ONLY_TOOL_FIELDS in src/adapters/openai-responses/, the src/adapters/ ownership entry for structure/transports/responses.md in structure/manifest.json, and the 4809-line ratchet entry that rules out growing tests/responses/openai-responses-passthrough.test.ts.
• Hosted CI on this head is the only execution evidence for this branch.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed. This PR is the documentation; the implementation it plans updates structure/transports/responses.md in its own change.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults. No auth, credential, workflow, or dependency surface is touched. The document contains no credentials and no pre-disclosure security analysis; the lane keeps that in .tmp/.

Summary by CodeRabbit

• Documentation
  • Added a delivery roadmap covering Responses field handling across supported destinations.
  • Documented validation requirements for HTTP, WebSocket, compaction, custom tools, multimodal content, message ordering, and status preservation.
  • Added guidance for reviewing tool-result adjacency and deferred-boundary handling.
  • Documented hosted-CI evidence, merge procedures, and safeguards for reliable validation.

[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-17T08:51:10.796831Z	a425ffc	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.

[github-actions]

✅ Deterministic PR hygiene checks passed.

[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: f04f5b06-b690-453b-a833-edb4fa62dc50

📥 Commits

Reviewing files that changed from the base of the PR and between f1dfda8 and a425ffc.

📒 Files selected for processing (1)

• devlog/_plan/260917_l4_responses_private_fields_and_history/010_roadmap.md

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

---

📝 Walkthrough

Walkthrough

Changes

The pull request adds a roadmap for R2-L4. It defines access_programs handling for noncanonical Responses destinations, xAI and ollama history reviews, regression coverage, documentation updates, and hosted-CI delivery constraints.

R2-L4 roadmap

Layer / File(s)	Summary
Responses field-handling requirements devlog/_plan/260917_l4_responses_private_fields_and_history/010_roadmap.md	Defines the noncanonical passthrough boundary, field-stripping rules, immutability requirements, and HTTP, WebSocket, compaction, and regression coverage.
Tool-history review scopes devlog/_plan/260917_l4_responses_private_fields_and_history/010_roadmap.md	Defines xAI adjacency and placeholder review requirements, plus ollama ordering, status, multimodal, deferred-boundary, and error-preservation checks.
Delivery and verification constraints devlog/_plan/260917_l4_responses_private_fields_and_history/010_roadmap.md	Records restrictions on local verification and flake masking, hosted-CI evidence requirements, push and merge procedures, and security-analysis scope.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~5 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to a425f

This documentation-only change does not alter runtime behavior and is mergeable.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies this as a devlog documentation change and accurately summarizes the L4 Responses private-field and history-repair plan opened by the pull request.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/l4-responses-private-fields-plan

---

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.}

[lidge-jun]

리뷰 · 우선순위 75 / 80

이 PR은 문서만 추가한다. devlog/_plan/260917_l4_responses_private_fields_and_history/010_roadmap.md 한 파일(161줄)로 R2-L4 배달 레인을 연다. src/, tests/, 워크플로, 설정은 건드리지 않는다. 현재 dev HEAD는 f1dfda8e4(패키지 2.58.0, tip #4876 — Windows CI 배치 다리에 OCX_TEST_NO_QUEUE=1)이고, 이 브랜치 codex/l4-responses-private-fields-plan의 베이스도 그 tip이라 리베이스가 필요 없다. 레인 목표는 세 덩어리다. U1은 #4853을 새로 구현하고, U2는 기여자 Draft #4871(closes #4870)을 리뷰·통합하며, U3는 기여자 #4848(closes #4842)을 리뷰한다. U2/U3는 재구현이 아니라 리뷰이고, 가져갈 때는 원 작성자 Co-authored-by가 필수라고 못 박아 두었다.

U1이 고치려는 문제는 간단하다. Codex 0.155가 Responses 요청 최상위에 access_programs를 붙이는데, 업스트림 cyber_access_program::for_auth는 ChatGPT 인증만 보고 destination URL은 보지 않는다. 루프백 주입은 Codex의 openai 프로바이더 정체성을 유지한 채 프록시로 보내므로, 프록시가 서드파티 Responses로 라우트해도 그 필드가 그대로 남는다. 엄격한 게이트웨이는 알 수 없는 최상위 키로 턴 전체를 400 낸다(#4853, muse-spark). 플랜은 Codex 체크아웃을 직접 읽어 HTTP / compaction / WebSocket response.create 세 모양에 필드가 실린다고 적었고, 공개 스펙이 없으니 서드파티가 거부하는 게 맞다고 정리한다. 지금 dev의 src/adapters/openai-responses/request-strips.ts에는 이미 같은 종류의 표 CANONICAL_ONLY_TOOL_FIELDS와 아이템 레벨 stripInternalChatMessageMetadataPassthrough가 있고, passthrough.ts는 noncanonical일 때 !isCanonicalOpenAiForwardProvider(provider)로 그 스트립을 건다. 플랜이 제안하는 CANONICAL_ONLY_TOP_LEVEL_FIELDS + stripCanonicalOnlyTopLevelFields는 그 패턴을 최상위 키로 올린 것이고, 이슈가 제안한 더 좁은 !isOpenAiOperatedResponsesDestination 대신 기존 sibling과 같은 predicate를 쓰는 이유도 코드와 맞다 — caller credential forward도 같은 canonical 경계다.

이슈가 같이 빼자고 한 codex_output_schema는 플랜이 의도적으로 표에서 뺀다. Codex 쪽에서는 그 문자열이 최상위 키가 아니라 text.format JSON-schema 객체의 name이고, serde 필드도 그 이름을 안 쓴다. 리포터 probe 표에서 totally_made_up_param과 나란히 쓴 “임의 미지 키”였을 뿐이다. 없는 키를 strip 목록에 넣으면 의미 있는 다른 클라이언트의 키까지 조용히 지울 수 있으니 제외하고 표 주석에 이유를 남기겠다는 판단은 타당하다. 커버리지도 passthrough.ts가 finalBody를 한 번 직렬화하고 WebSocket이 그걸 재사용하며, buildRoutedCompactionBody가 이미 스트립된 바디 위에서 돈다는 현재 파이프라인 읽기와 맞다. 테스트는 tests/responses/openai-responses-passthrough.test.ts가 file-size ratchet에 정확히 4809줄로 고정돼 있어 새 파일 + scripts/test-layout/layout.json / tests/fixtures/test-layout-expected.json 두 layout 엔트리를 요구하는 것도 저장소 사실과 일치한다. ownership은 structure/manifest.json이 src/adapters/를 structure/transports/responses.md에 맡기고, 그 문서가 이미 noncanonical private-field 경계와 CANONICAL_ONLY_TOOL_FIELDS를 설명하므로 같은 변경에서 최상위 표를 추가하라는 것도 structure:check 계약과 맞다.

U2(#4871) 리뷰 계약은 custom_tool_call 커버리지, forward-auth 거부 경계 불변, 다른 adjacency 프로바이더(kimi / kimi-code / deepseek) blast radius를 증거로 확인하라고 못 박는다. 하드 제약은 “끊긴 tool-call history를 고친다고 stateful을 끄지 말 것” — xAI Responses는 conversation을 저장하고 previous_response_id를 문서화하므로 statelessResponses는 비워 두고 stripStatefulResponsesParams가 새 조건에서 닿으면 안 된다. 이전에 이 PR에 올린 리뷰(74/80)도 Draft KEEP 쪽이었고, 플랜이 그 제약을 레인 수준으로 올렸다. U3(#4848)는 Responses와 코드 경로를 공유하지 않는 ollama-native 쪽이라 스택하지 말라고 했고, deferred 메시지 순서·멀티모달·orphan/duplicate/mismatch 가드 유지 + “결과 없는 call을 성공으로 꾸미지 말 것”을 리뷰 포인트로 둔다. 운영 제약(로컬 bun test 금지, git push --no-verify, flake 금지, 보안 분석은 .tmp/)은 예전에 로컬 스위트가 ~/.opencodex를 지운 사고에 대한 레인 규율이다.

devlog/_plan/260917_l4_responses_private_fields_and_history/010_roadmap.md - 문서만이고 tip f1dfda8e4에 정확히 올라가 있다. 구현·테스트 게이트는 이 PR 범위 밖이다.
U1 write scope - request-strips.ts / passthrough.ts / structure/transports/responses.md / 새 테스트+layout 두 엔트리. 현재 dev에 그 파일·표·경계가 실제로 있다.
codex_output_schema - strip 표에서 제외한 근거(최상위 키 아님)가 Codex API 모델 설명과 이슈 probe 맥락과 맞다. 구현 PR에서 표 주석에 그 이유를 남겨야 한다.
/Users/jun/Developer/codex/121_openai-codex - 업스트림 검증 경로가 작성자 Mac 로컬이다. CI/다른 머신에서는 재현 불가. 주장 자체는 합리적이지만, U1 구현 PR에는 Codex 쪽 심볼·파일 경로를 저장소에 남는 형태로 다시 적거나 hosted 증거로 고정하는 편이 낫다.
#4871 - 아직 Draft다. 레인이 U2를 “리뷰·통합”으로 잡았으니, Draft가 Ready+exact-head CI가 되기 전에는 U2를 닫지 않는 순서가 안전하다.
#4848 - OPEN이고 Responses와 경로를 안 나눈다. U1과 병렬 리뷰는 가능하지만 같은 머지 트레인에 묶을 이유는 없다.
tests/responses/openai-responses-passthrough.test.ts - ratchet 4809줄 주장이 tests/fixtures/file-size-baseline.json과 줄 수와 일치한다. 새 파일 분리는 필수다.

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

• U1 구현을 이 플랜 머지 직후 같은 세션에서 열지, 플랜만 먼저 dev에 올려 두고 #4853을 별 PR로 둘지
• U2(fix(xai): seed Responses tool-result adjacency for interrupted Codex threads #4871)를 Draft→Ready 전에 레인에 “통합 예정”으로 남겨둘지, Ready+CI 이후에만 U2 체크를 닫을지
• U3(fix(ollama-native): defer a mid-turn conversational message instead of refusing the replay #4848)를 이 L4 레인 완료 조건에 넣을지, Responses 레인과 분리해 별도 리뷰 큐로 둘지
• 업스트림 Codex 근거를 Mac 로컬 경로 인용으로 충분하다고 볼지, U1 PR에 심볼·출처를 저장소 문서로 옮길지

너의 추천
KEEP 후 exact-head CI(docs라 대부분 skip, 이미 changes/hygiene/ci 통과 쪽) 확인되면 머지해도 된다. 이 PR 자체는 구현이 아니라 레인 계약서다. 머지 뒤에 U1(#4853 strip 표)을 바로 열고, U2는 #4871이 Draft를 벗고 tip에 리베이스된 뒤에만 통합 판단하며, U3는 Responses와 경로를 안 나누니 병렬 리뷰하되 같은 스택에 묶지 마라. U1 구현 PR에서는 codex_output_schema를 표에 넣지 말 것과 isCanonicalOpenAiForwardProvider 경계를 쓰는 이유를 코드 주석·structure/transports/responses.md에 남기고, 새 테스트 파일 + layout 두 엔트리 + structure:check를 한 커밋 범위에 넣어라.

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a425ffc168

ℹ️ 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".

[chatgpt-codex-connector]

Permit the mandatory focused checks

When U1 changes the Responses adapter, this blanket prohibition prevents the implementer from running the focused regression file and test:changed checks required for a source behavior change. Hosted CI is useful final evidence, but it does not replace the repository's mandated implementation-time checks; isolate OPENCODEX_HOME or run in a disposable environment instead of forbidding all local verification and bypassing the pre-push gate.

AGENTS.md reference: AGENTS.md:L376-L379

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Cover the native compact forwarding path

When a ChatGPT-authenticated Codex client sends a compaction request that routes to openai-apikey, src/server/responses/compact.ts:701 selects the native /responses/compact branch and lines 795-799 build its body directly from raw, so the passthrough adapter and the proposed strip never run. Consequently access_programs still reaches the strict official endpoint and can reject the compact turn; apply the noncanonical strip in this direct branch as well and add coverage through handleResponsesCompact.

Useful? React with 👍 / 👎.