docs(providers): describe OpenCode Go session affinity and the Pi compat flag

[lidge-jun]

Summary

Docs-only follow-up to #3880 (carry of #3858 by @makesomethingshit): the OpenCode Go session-affinity paragraph and the Pi compat.sendSessionAffinityHeaders note for docs-site/src/content/docs/guides/providers.md. Lane A handed this hunk off because the file is owned by the main lane in the release train; the patch applied cleanly on the current head.

Verification

• Docs only, no runtime change. git apply --check clean on origin/dev@76436a3ee + fix(responses): make whole-string citation stripping agree with the streaming filter #3882.
• Local checks NOT RUN by maintainer instruction. Base is fix(responses): make whole-string citation stripping agree with the streaming filter #3882's branch so this rides its chain-top CI.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.

Depends on #3882 (base codex/rt-m7-citation-terminal). Review this PR's diff only.

---

Maintainer integration decision (MAINTAINERS.md, dev-only admin integration): @lidge-jun integrates #3882 (+ docs follow-up #3888) into dev. Exact-head evidence for #3882 at e96b5c52e: Cross-platform CI run 34114667385 — Linux test 1/4–4/4, macOS 1/2, 2/2, gates, storage policy, api usage, keyring ×3, npm-global ×3, docker smoke = success; Windows shards and macos control deferred to the final release-train head by maintainer policy. #3888 is docs-only on top of #3882. Independent review PASS at the amended head (see body). Local suites NOT RUN. Maintainer integration, not self-approval.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

🗂️ Base branches to auto review (2)

• ^dev$
• ^preview$

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Team

Run ID: 2a34960f-61ab-425b-988b-75e07399eed7

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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

[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-07T11:07:53.673572Z	413600d	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.

[lidge-jun]

리뷰 · 우선순위 38 / 80

이 PR은 코드가 아니라 문서만 고칩니다. 이미 dev에 들어온 #3880(그리고 그 원본 #3858)이 OpenCode Go 세션 친화성(session affinity)을 네이티브 Chat까지 실어 나르게 바꿨는데, 그 동작을 docs-site/src/content/docs/guides/providers.md에 사람 말로 적어 주는 후속입니다. 지금 HEAD(76436a3ee)에는 src/providers/opencode-go-transport.ts의 deriveOpenCodeGoSessionId / resolveOpenCodeGoTransport가 있고, src/server/chat-completions.ts와 src/server/responses/core.ts가 Codex 스레드·세션 헤더(또는 없을 때 x-opencode-session)로 레인 아이디를 잡은 뒤 Go 전용 헤더를 붙입니다. Pi 쪽은 src/clients/config-export.ts의 compat.sendSessionAffinityHeaders로 생성 설정에 플래그를 켜 줍니다. 가이드 guides/pi.md(및 여러 로케일)에는 이미 Pi 플래그 설명이 있는데, providers 가이드의 제공자 표 바로 아래·OpenCode Zen 문단 앞에 Go 라우팅 설명을 넣는 자리도 맞습니다. 런타임 diff는 없고, 릴리즈 트레인에서 메인 레인이 소유한 providers.md 조각을 레인 A가 넘긴 문서 전용 패치라서 #3880 동작과 문서가 어긋나지 않게 맞추는 일에 가깝습니다.

베이스가 dev가 아니라 아직 열린 #3882 브랜치(codex/rt-m7-citation-terminal)입니다. PR 본문대로 guides/providers.md가 이번 트레인 메인 레인 소유라서 체인에 얹은 것이고, origin/dev@76436a3ee + #3882 위에 apply check가 깨끗하다고 적혀 있습니다. 그래서 이 문서는 #3880 코드와는 이미 맞고, 머지 타이밍만 #3882(및 그 앞 체인)에 묶여 있습니다. 점수 38은 「이미 합쳐진 동작을 정확히 문서화」+「런타임 위험 없음」을 반영하되, 「단독으로 지금 당장 dev에 꽂을 수는 없음」을 깎은 값입니다.

추가된 문단 내용은 HEAD 코드와 대체로 일치합니다. Go는 안정적인 세션 식별자가 필요하고, Codex 스레드/세션 헤더가 없으면 클라이언트의 x-opencode-session을 쓰며, 직접 Chat Completions와 Responses로 브리지된 요청 모두에 적용된다고 적혀 있습니다. ocx_로 시작하는 값이 들어와도 클라이언트 입력으로 보고 다시 해시해 Go affinity를 만든다는 말도 deriveOpenCodeGoSessionId가 레인 문자열을 무조건 ocx_+sha256 조각으로 바꾸는 것과 같습니다. 내부 브리지가 원본 x-opencode-session을 그대로 넘긴다는 설명은 chat-completions.ts에서 해당 헤더를 다시 싣는 부분과 맞습니다. provider 설정에 이미 세션 헤더가 있으면 연산자 오버라이드로 손대지 않는다는 문장도 hasHeaderCaseInsensitive(provider.headers, OPENCODE_GO_SESSION_HEADER) early-return과 같습니다. Pi는 생성 설정에 compat.sendSessionAffinityHeaders를 켜고, 수동 Pi 설정도 같은 옵션을 줄 수 있으며, cacheRetention이 none이면 Pi가 세션을 안 보낼 수 있다는 주의도 guides/pi.md와 같은 방향입니다.

라인 단위로 보면 문장 자체에 코드와 어긋나는 거짓말은 거의 없습니다. 다만 영어 guides/providers.md만 늘어나고 ko/ja/zh-cn 등 로케일 providers.md에는 같은 OpenCode Go 문단이 아직 없습니다. Pi 플래그 설명은 로케일 guides/pi.md에 이미 있어서 완전 공백은 아니지만, providers 가이드만 보면 번역본 사용자는 Go affinity 문단을 못 봅니다. 또한 providers.md 아래쪽(영어 기준 OpenCode Go quota 근처)에 Go 이야기가 또 나오므로, 나중에 문서 정리할 때 세션 친화성과 쿼터 설명을 한곳에 모을지 정도는 판단 여지가 있습니다. 이번 diff 범위 안에서는 표와 Zen 문단 사이 삽입 위치가 자연스럽고, 스코프도 문서 한 파일·+16줄로 깨끗합니다.

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

• #3882가 머지되기 전에 이 PR만 dev로 리타겟할지, 아니면 체인 순서(fix(responses): make whole-string citation stripping agree with the streaming filter #3882 → 이 docs)를 지킬지
• 영어 providers.md만 먼저 넣을지, 같은 문단을 로케일 providers.md에도 같이 넣을지(또는 후속 PR로 미룰지)
• providers.md 하단 Go quota 절과 이번 세션 친화성 문단을 장기적으로 한 섹션으로 묶을지

너의 추천
#3882(및 그 체인)가 dev에 올라간 뒤 이 PR을 그대로 머지하세요. 런타임 위험이 없고 #3880 동작을 정확히 설명합니다. 로케일 providers.md 동기화는 막지 말고 후속 문서 PR로 받아도 됩니다. 리타겟이 필요하면 #3882와 충돌 없는지만 확인하고 dev로 옮겨도 내용은 같습니다.

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