[luvs01]

Summary

• Preserve third-party gateway url_citation annotations during native /responses/compact, including omitted/null titles, nonstandard indices, and provider extension fields. Native compact opt-in declares protocol support; it does not authorize OpenAI-specific citation normalization.
• Keep stripProviderInputItemMetadata() independent from repairUrlCitationAnnotations(). Ordinary HTTP/WS requests still repair citations only for OpenAI-operated destinations.
• Apply native compact citation repair in the final send-body builder using the current sendProvider. A provider may change destinations while waiting for key admission, so the shared body must remain unrepaired until each physical send.
• Add regressions for OpenAI → gateway and gateway → OpenAI refreshes, exact gateway preservation, official API/ChatGPT native repair, helper independence, and input immutability. Both new refresh tests failed on the previous PR head and pass with this correction.
• Update the public adapter reference and structure contracts. The focused citation contract has its own document because the existing owning documents are at their 600-line budgets.
• Supersedes fix(responses): preserve gateway citations during native compact (superseded by #752) #751, whose wrong release-branch target, nonexistent module import, unmatched scope brace, and uncommitted test claims are documented there. This PR remains the single implementation to review.

Verification

Validated content for commit b095b04adaf57c1ef1b853eddeaaba6c62792acc:

• With the pinned Bun 1.4.3 test runner:

  bun test tests/responses/compact-key-selection.test.ts \
    tests/responses/responses-url-citation-title-repair.test.ts \
    tests/responses/responses-native-item-extensions-compact.test.ts

  29 passed, 0 failed, 331 assertions.
• bun run typecheck — passed.
• bun run privacy:scan — passed.
• bun run structure:check — passed; structure index regenerated.
• git diff --check — passed.
• From docs-site/, bun install --frozen-lockfile and bun run build with Bun 1.4.4 — passed; 593 pages built and 84,861 internal links checked. Package manifests and lockfiles are unchanged.
• bun run test:changed resolved the origin/dev merge base and selected 857 of 2,596 test files. It was stopped after more than six minutes without a test-result summary (SIGTERM, exit 143) because the selected set is disproportionate to this narrow change. This is an incomplete run, not a passing result.
• Current-head GitHub Actions: gates, API usage, storage policy, Docker smoke, structure gate, docs site build, keyring Ubuntu, and npm-global Ubuntu passed. All four test shards are still running. Earlier-head results are not substituted for this run.

The full local suite has not been run: for this narrow adapter/compact change, the focused regression tests are used under the documented resource exception, with the wider test shards left to current-head CI. The PR remains draft while broader validation completes.

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.

---

Original Codex task

Summary by CodeRabbit

• Bug Fixes

  • Replayed URL citations sent to OpenAI-operated destinations now receive repaired titles and valid index values, including in HTTP, WebSocket, and native compact requests.
  • Citations sent to custom gateways remain unchanged, and repairs do not modify stored conversation history.

• Documentation

  • Updated the adapter and Responses documentation to describe citation handling across destinations.

[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

No actionable comments were generated in the recent review.

ℹ️ Recent review info

⚙️ Run configuration

• Source mode: Auto
• Repository: luvs01/opencodex
• Branch: codex/fix-citation-rewrite-for-third-party-gateways
• File: .coderabbit.yaml
• Commit: b095b04
• Layers: Repository YAML
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 47a918a4-a88a-4c82-af30-198699a20dc7

📥 Commits

Reviewing files that changed from the base of the PR and between c4d4bb2 and b095b04.

📒 Files selected for processing: 12

• docs-site/src/content/docs/reference/adapters.md
• src/adapters/openai-responses/passthrough.ts
• src/adapters/openai-responses/request-strips.ts
• src/server/responses/compact.ts
• structure/INDEX.md
• structure/manifest.json
• structure/providers-and-adapters.md
• structure/transports/responses-citations.md
• structure/transports/responses.md
• tests/responses/compact-key-selection.test.ts
• tests/responses/responses-native-item-extensions-compact.test.ts
• tests/responses/responses-url-citation-title-repair.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

Walkthrough

The Responses adapter and native compact path now repair replayed URL citations for OpenAI-operated destinations. Custom gateways retain their original citations. The repair applies to outbound request bodies and does not modify client-stored history.

Changes: Responses Citation Projection

Layer / File(s)	Summary
Ordinary Responses projection src/adapters/openai-responses/passthrough.ts, src/adapters/openai-responses/request-strips.ts, tests/responses/responses-url-citation-title-repair.test.ts, structure/providers-and-adapters.md, structure/INDEX.md	The ordinary adapter repairs citations for OpenAI-operated destinations after stripping provider input-item metadata. Metadata stripping no longer repairs citations. Tests verify the two projections remain separate and do not mutate the input.
Native compact projection and validation src/server/responses/compact.ts, tests/responses/compact-key-selection.test.ts, tests/responses/responses-native-item-extensions-compact.test.ts, docs-site/src/content/docs/reference/adapters.md, structure/transports/*, structure/INDEX.md, structure/manifest.json	The direct compact path repairs citations for OpenAI-operated destinations. Tests cover destination refresh, gateway preservation, citation normalization, and unchanged input. Documentation describes the destination-specific behavior across ordinary and compact requests.

Priority: Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Suggested reviewers: lidge-jun, ingwannu

Merge Risk: Minimal · up to b095b

No citation-preservation defect is established in the reviewed send paths. Complete the planned broader validation before merging.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

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

Passed checks: 4 passed

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title accurately and concisely describes the main change: preserving third-party gateway citations during native /responses/compact while limiting citation repair to OpenAI-operated destinations.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

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

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

✨ Finishing Touches: 💡 1

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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.

[luvs01]

No description provided.

[github-actions]

⏳ DRAFT

• UI screenshot required.

What to do

• Add a screenshot of the UI change to the PR description.

This pull request was already a draft. Its draft status will be preserved after every issue above is resolved.

[luvs01]

Closing this duplicate review after preserving the complete fix in integration commit 51e214ebbe8d347b17eb6c39b9f028e91f40f34a. It retains the final-destination citation handling, both provider-refresh regressions, and the documentation contract.

The integrated candidate passed 40 focused tests (401 assertions) on Bun 1.4.4, plus root type and structure checks. Independent source review found no blocking defect. Broader CI remains pending on the continuing draft review; this closure does not mean the change has merged or shipped. The branch is retained.