[WRONG BRANCH] fix(zcode): use openai-compatible provider protocol to restore prefix caching

[leonclab]

Summary

In current OpenCodex versions, ZCode client integration (src/clients/config-export.ts) generates the provider configuration with:

{
  "kind": "anthropic",
  "options": {
    "baseURL": "http://127.0.0.1:10100"
  }
}

This causes two major issues:

1. Severe Prefix Cache Degradation for DeepSeek / LLMs with Prefix Caching:
   When using Anthropic Messages protocol, prompt inlining and dynamic tool results break KV cache prefix alignment. In practice, DeepSeek's KV cache hit rate drops from 99% to ~80% (or lower).
2. Integration Conflict on Manual Switch:
   When users manually switch the protocol to Chat Completions inside ZCode's UI, OpenCodex's fingerprint guard detects an unowned foreign edit (conflict: foreign-edit) and stops managing the client.

Changes

• Updated ZcodeProviderBlock.kind and buildZcodeClientConfig in src/clients/config-export.ts to use openai-compatible.
• Ensured baseURL is exported with the /v1 suffix (i.e. http://127.0.0.1:10100/v1), which matches ZCode's /chat/completions URL concatenation.
• Updated tests/zcode-client.test.ts unit tests to assert the new provider kind and baseURL.

Verification

• Ran test suite with bun test tests/zcode-client.test.ts: 10 pass, 0 fail.
• Live verified in ZCode: DeepSeek prefix KV cache hit rate restored to 97% ~ 99.7%.

Review readiness checklist

This PR stays in draft until every box below is ticked. Tick all four boxes once the requirements are met:

• All CI tests are green on my local testing.

• I pushed my PR to the latest dev commit.

• I resolved all correct Codex and CodeRabbit findings.

• My PR is ready for review.

Summary by CodeRabbit

• Bug Fixes
  • Updated ZCode exports to use the OpenAI-compatible provider format.
  • Preserved the /v1 path in exported base URLs for improved compatibility.

[github-actions]

✅ Deterministic PR hygiene checks passed.

[github-actions]

⏳ DRAFT

• wrong target branch (main); retarget to dev.

What to do

• Retarget this PR to dev — all contributions go to dev.
• Tick all four boxes in the PR description once you're done (currently 0/4).

Review readiness checklist

• ⬜ All CI tests are green on my local testing.
• ⬜ I pushed my PR to the latest dev commit.
• ⬜ I resolved all correct Codex and CodeRabbit findings.
• ⬜ My PR is ready for review.

0/4 boxes ticked.

Its title has been prefixed with [WRONG BRANCH].
This pull request was already a draft. Its draft status will be preserved after every issue above is resolved.
@leon80900 Tick the boxes once your local CI is green, your branch is on the latest dev commit, and every correct Codex and CodeRabbit finding is resolved.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 29621332-5ebb-4c6a-ac13-13505d5954fa

📥 Commits

Reviewing files that changed from the base of the PR and between 5840591 and 4f4ba8f.

📒 Files selected for processing (2)

• src/clients/config-export.ts
• tests/zcode-client.test.ts

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

---

📝 Walkthrough

Walkthrough

ZCode exports now use the openai-compatible provider kind and retain the /v1 path in the configured base URL. The ZCode client test verifies both updated values.

Changes

ZCode provider configuration

Layer / File(s)	Summary
Update provider export and validation src/clients/config-export.ts, tests/zcode-client.test.ts	The ZCode export changes the provider kind from anthropic to openai-compatible at line 911. The generated base URL appends /v1 at lines 1291–1296. The test expects both updated values at lines 46–51.

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

Merge Risk: 🟡 Moderate · up to 4f4ba

The code change is localized, but the PR is not merge-ready because its readiness checklist remains fully unchecked, including confirmation of tests, branch freshness, finding resolution, and review readiness.

Suggested reviewers: ingwannu

🚥 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 the ZCode protocol change and its purpose of restoring prefix caching, although the branch marker adds minor noise.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
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 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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]

리뷰 · 우선순위 60 / 80

제목 [WRONG BRANCH]가 맞음. base가 main임. 릴리즈 헬퍼 패턴이 아니라 기능 패치라서 dev로 바꿔야 함. main에 머지하지 말 것. 리베이스로 살리지 말고 베이스만 dev로 돌리거나 이 PR 닫고 dev에 다시 열면 됨.

지금 dev는 ZCode를 Anthropic Messages로 보냄. src/clients/config-export.ts ZcodeProviderBlock.kind가 "anthropic" 고정 (:909-911). buildZcodeClientConfig가 baseURL에서 /v1을 떼고 내보냄 (:1296). /v1/messages용임. openai-compatible로 바꾸면 /v1을 남겨서 /chat/completions에 붙게 하는 게 맞음.

캐시 이야기는 설득력 있음. Anthropic 메시지로 프롬프트 인라인/툴 결과가 매번 앞에 붙으면 DeepSeek KV prefix가 깨짐. 수동으로 Chat Completions 바꾸면 fingerprint conflict: foreign-edit로 ocx가 손 떼는 것도 그 파일 가드 동작임. export가 처음부터 openai-compatible이면 그 충돌은 사라짐.

전 모델 kind를 한 번에 바꾸는 거라 Claude-on-ZCode가 Messages에 의존하면 깨질 수 있음. 프록시는 두 프로토콜 다 받으니 대체로 괜찮음. 그래도 ZCode 3.7.7에서 anthropic으로 검증해 둔 주석(:897-901)을 같이 고쳐야 함. 테스트 tests/zcode-client.test.ts만 그린 거면 그 주석/타입도 맞춰야 함.

types.ts/config.ts 스플릿이랑 상관 없음. 5줄짜리라 스플릿에 안 씹힘.

해결방안: base를 dev로 돌림. kind openai-compatible + /v1 유지. 주석이랑 ZcodeProviderBlock 리터럴 타입을 같이 수정. 기존 anthropic export를 쓰는 사람이 한 번 재export 하게 문서/릴리즈 노트 한 줄. main에 올리지 말 것.

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

[lidge-jun]

Closing per the [WRONG BRANCH] marker: this targets main, and feature/fix PRs integrate through dev only (AGENTS.md branch policy; enforce-target also rejects main-tip ancestry). The zcode openai-compatible direction itself is welcome — please re-file the same diff against dev and it will ride the normal triage train.