document responses contract additions

[ndycode]

Summary

• document continuation, compaction, hosted tools, and semantic SSE compatibility fields
• record GPT-5.4 capability-gating behavior for maintainers
• align the docs with the shipped request transformer and CLI behavior

Stack

• base: #315

[chatgpt-codex-connector]

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

[coderabbitai]

📝 Walkthrough

Walkthrough

two documentation files updated with new configuration and api contract information. docs/development/CONFIG_FIELDS.md documents two new configuration fields: promptCacheRetention for openai provider options and responseContinuation for plugin config. docs/reference/public-api.md adds responses api compatibility guarantee notes.

Changes

Cohort / File(s)	Summary
Config Field Documentation docs/development/CONFIG_FIELDS.md	Added promptCacheRetention (string) to provider.openai.options with values 5m|1h|24h|7d, and responseContinuation (boolean, default false) to pluginConfig "Token / Recovery" section.
API Contract Documentation docs/reference/public-api.md	Added "Responses Contract Notes" section detailing compatibility guarantees for request-transform and sse parsing layers, including field preservation behavior (previous_response_id, text.format, prompt_cache_retention), typed hosted built-in tool support, and synthesized sse compatibility fields (output_text, reasoning_summary_text, commentary_text, final_answer_text, phase_text).

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	the pr description provides a clear summary of changes but lacks the required validation checklist and docs/governance sections from the template.	add the validation checklist (lint, typecheck, test, build), docs governance checklist (readme, docs updates), and risk/rollback section. document test execution results and any validation gaps.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	title follows conventional commits format with lowercase imperative mood and is 37 characters, well under the 72-char limit.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/openai-parity-pr8

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch feat/openai-parity-pr8

---

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 and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/reference/public-api.md`:
- Around line 79-84: Update the docs entry that lists the SSE compatibility
fields to state they are conditionally synthesized: change the description in
public-api.md so it notes that output_text and reasoning_summary_text are only
emitted when outputText and reasoningSummaryText contain content (see the
outputText.length and reasoningSummaryText.length checks in
lib/request/response-handler.ts), and that commentary_text, final_answer_text
and phase_text are only added when state.phaseText has entries (see
state.phaseText.size check); add a brief sentence such as "these fields are
synthesized only when the corresponding content is present in the response
stream."
- Line 72: Combine and rephrase the three repetitive sentences that begin with
"is preserved" into a single clearer sentence: state that the plugin preserves
previous_response_id when explicitly provided, maintains text.format when
verbosity defaults are applied, and honors prompt_cache_retention from the
request body while falling back to providerOptions.openai or
provider.openai.options user config defaults; update the sentence that mentions
previous_response_id, text.format, and prompt_cache_retention accordingly to
improve readability.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: f8b26e02-871e-48e5-99a9-ba866b179e96

📥 Commits

Reviewing files that changed from the base of the PR and between 5d39a59 and 60106b6.

📒 Files selected for processing (2)

• docs/development/CONFIG_FIELDS.md
• docs/reference/public-api.md

📜 Review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Greptile Review

🧰 Additional context used

📓 Path-based instructions (1)

docs/**

⚙️ CodeRabbit configuration file

keep README, SECURITY, and docs consistent with actual CLI flags and workflows. whenever behavior changes, require updated upgrade notes and mention new npm scripts.

Files:

• docs/development/CONFIG_FIELDS.md
• docs/reference/public-api.md

🪛 LanguageTool

docs/reference/public-api.md

[style] ~72-~72: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...h untouched. - prompt_cache_retention is preserved from the request body and can...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

🔇 Additional comments (5)

docs/development/CONFIG_FIELDS.md (2)

34-34: lgtm - promptCacheRetention documented correctly.

the entry matches the guideline spec and aligns with lib/request/request-transformer.ts:206-216 fallback resolution logic. the common values 5m|1h|24h|7d are appropriate server-side cache duration strings.

---

78-78: lgtm - responseContinuation documented correctly.

the default false matches lib/config.ts:925-937 where normalizeBoolean falls back to false, and the schema in lib/schemas.ts:50-54 confirms it's z.boolean().optional().

docs/reference/public-api.md (3)

73-78: lgtm - hosted tool support documented correctly.

the enumeration of supported hosted tools matches the implementation in lib/request/request-transformer.ts:307-368:

• tool_search filtered when !capabilities.toolSearch
• computer / computer_use_preview filtered when !capabilities.computerUse
• namespace bundles with recursive nested tool filtering

the filtering behavior is accurately described.

---

71-71: verify the text.format preservation claim.

the documentation states text.format is preserved when verbosity defaults are applied, but the provided context snippets don't show this preservation logic. we need evidence that the request transformer handles text.format correctly.

run the following script to find text.format handling:

#!/bin/bash
# description: search for text.format preservation logic in request transformation

# search for text.format handling
rg -nP --type=ts -C5 'text\.format|text\[.format.\]' lib/request/

# search for verbosity default application
rg -nP --type=ts -C5 'textVerbosity|text.*verbosity' lib/request/

---

70-70: documentation claims are accurate – all verified in code.

the auto-fill behavior at index.ts:1354-1359 correctly implements the documented statement: previous_response_id gets auto-filled from stored session state when both getResponseContinuation(pluginConfig) returns true and the field isn't already set in the request body. test case at test/index.test.ts:1323-1380 confirms the follow-up request receives the stored value.

text.format preservation at request-transformer.ts:989 happens through the spread operator (...body.text) which leaves any existing format field untouched. prompt_cache_retention fallback correctly chains body.prompt_cache_retention → body.providerOptions?.openai?.promptCacheRetention → modelConfig.promptCacheRetention at request-transformer.ts:210-214. all four hosted tool types (tool_search, mcp, computer/computer_use_preview, namespace) have type definitions in lib/types.ts and filtering logic in request-transformer.ts:305-352. all five sse synthesis fields (output_text, reasoning_summary_text, commentary_text, final_answer_text, phase_text) are assigned in lib/request/response-handler.ts:199-322.

the section is ready as written.

[ndycode]

@coderabbitai review
@greptile @cubic review

[coderabbitai]

@ndycode, on it — triggering a review of PR #316 now.

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

All review threads are resolved and later commits addressed this stale automated change request.