feat(debug): add content-free adapter and bridge stream diagnostics

[yansigit]

Summary

Extract the stream diagnostics slice from the closed oversized #2516 proposal. Opt-in debug lines correlate adapter and bridge stages, attempts, and sidecar rounds. Payload text, reasoning, tool identifiers, arguments, queries, and error strings become lengths and process-local HMAC fingerprints; raw content and provider state are excluded. This is separate from the local telemetry ledger in #3748.

Updated CLI debug documentation. Maintainer privacy/security review remains required before advancing this draft.

Verification

Root bun run typecheck, bun run privacy:scan, and the core/Lab boundary tests passed. Five focused files combined: 180 passed, two web-search failures; unchanged upstream runtime reproduces those same two failures (172 passed). The web-search file alone passes all 62 tests. Documentation frozen install and build passed. Static privacy review covered field selection, random request ids, debug gating, and the process-local random HMAC key.

All runtime checks used a fresh temporary OPENCODEX_HOME and alternate port; production config fingerprint and backup inventory remained unchanged. Full root-suite and review-readiness gates have not been completed for this head; this is intentionally a draft.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Added/updated regression coverage or verified existing coverage for the affected behavior.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.

Review readiness

• Local CI green.
• Branch on the latest dev commit.
• All correct Codex and CodeRabbit findings fixed.
• Ready-for-review confirmation.

Co-authored-by: SB Yoon 44089734+yansigit@users.noreply.github.com
Co-authored-by: Yumi automation@sbyoon.com

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.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

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.

[github-actions]

⏳ DRAFT

• review readiness checklist open (0/4 boxes ticked).

What to do

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

This PR stays in draft until every box above is ticked.

[lidge-jun]

리뷰 · 우선순위 57 / 80

이 PR은 provider debug가 켜졌을 때만 내용 없는(stream 구조만) 진단을 남기게 합니다. 지금 dev HEAD c15662855의 src/lib/debug.ts는 짧은 usage/provider diagnostic 헬퍼 수준입니다. 이 변경은 debugFingerprint(프로세스 로컬 HMAC)와 debugStreamDiagnostic을 추가하고, src/bridge.ts에서 adapter/bridge 이벤트마다 sequence·byteLength·fingerprint·status 같은 메타만 기록합니다. 텍스트·reasoning·tool 인자·query 본문은 넣지 않는다고 docs(docs-site/.../cli/agents.md)에 명시합니다. src/server/responses/core.ts, src/images/loop.ts, src/web-search/loop.ts에도 같은 opt-in 배선을 잇고, bridge/web-search/images/debug 테스트가 fingerprint 비노출과 sequence 연속을 고정합니다. 방향은 #3968 sideband privacy 계열과 잘 맞습니다. “재현용으로 구조만 보고, 프록시 재시작 후 fingerprint는 바뀐다”는 운영 문구도 맞습니다. 다만 draft이고 표면이 bridge+responses core+sidecar loop로 넓어서, debug off 경로의 할당/시퀀스 비용과 core.ts 핫패스 삽입을 머지 전에 한 번 더 봐야 합니다. types/config 분할과 무관합니다.

라인 src/lib/debug.ts · debugFingerprint - debug off면 undefined, on이면 프로세스 로컬 키로 HMAC hex만 돌립니다. 본문을 로그에 안 남기는 핵심입니다.
라인 src/bridge.ts · adapterEventDiagnosticDetails / diagnoseAdapterEvent - 이벤트 타입별 byteLength·fingerprint·status만 추립니다. default는 빈 객체라 새 이벤트 타입이 생겨도 내용 유출 경로는 기본적으로 닫혀 있습니다.
라인 src/bridge.ts · bridgeToResponsesSSE diagnostic 옵션 - shared sequence가 있으면 그걸 쓰고, 없으면 bridge 로컬 카운터를 씁니다. sidecar 재시도와 한 요청 correlation을 맞추려는 설계입니다.
라인 src/server/responses/core.ts - diagnostic context를 만들어 bridge/adapter 경로에 넘깁니다. 핫패스라 debug off short-circuit이 실제 비용 없는지 확인이 필요합니다.
경로 tests/lib/debug.test.ts · tests/adapters/bridge.test.ts - 내용 미포함·sequence·fingerprint 회전을 잠급니다. 이 테스트가 없으면 privacy 주장이 문서만 됩니다.
경로 draft / 전체 게이트 미완 - 본문이 root-suite·review-readiness 미완이라고 명시합니다. ready 전에 hygiene·포커스 테스트 증거를 채우세요.

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

• responses/core 핫패스에 진단 배선을 지금 넣을지, bridge+sidecar만 먼저 넣을지
• fingerprint 키를 요청 단위로 돌릴지(지금은 프로세스 로컬) — 재시작 전후 비교 UX와 메모리 중 무엇을 우선할지
• OCX_DEBUG 기본 on 환경(개발자 머신)에서 로그 볼륨이 과도하면 샘플링이 필요한지

너의 추천
방향은 좋습니다. privacy 경계(본문 미기록)와 테스트가 있으면 draft 해제 후보입니다. 머지 전에 debug off일 때 core/bridge 추가 할당이 없는지와 CI 초록을 확인하세요. 핫패스 비용이 보이면 bridge 쪽만 먼저 랜딩하는 축소안을 권합니다.

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