Skip to content

document responses contract additions #316

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
ndycode wants to merge 2 commits into from
+26 −0
Closed

document responses contract additions #316

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
60106b6
Document responses contract additions
ndycode Mar 22, 2026
7cc6bf6
clarify responses contract docs
ndycode Mar 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/development/CONFIG_FIELDS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@ Used only for host plugin mode through the host runtime config file.
| `reasoningEffort` | string | `none\|minimal\|low\|medium\|high\|xhigh` | Reasoning effort hint |
| `reasoningSummary` | string | `auto\|concise\|detailed` | Summary detail hint |
| `textVerbosity` | string | `low\|medium\|high` | Text verbosity target |
| `promptCacheRetention` | string | `5m\|1h\|24h\|7d` | Default server-side prompt cache retention when the request body omits `prompt_cache_retention` |
| `include` | string[] | `reasoning.encrypted_content` | Extra payload include |
| `store` | boolean | `false` | Required for stateless backend mode |

Expand Down Expand Up @@ -74,6 +75,7 @@ Used only for host plugin mode through the host runtime config file.
| `tokenRefreshSkewMs` | `60000` |
| `sessionRecovery` | `true` |
| `autoResume` | `true` |
| `responseContinuation` | `false` |
| `proactiveRefreshGuardian` | `true` |
| `proactiveRefreshIntervalMs` | `60000` |
| `proactiveRefreshBufferMs` | `300000` |
Expand Down
24 changes: 24 additions & 0 deletions docs/reference/public-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,30 @@ Positional signatures are preserved for backward compatibility.

---

## Responses Contract Notes

The request-transform layer intentionally preserves and/or normalizes modern Responses API fields that callers may already send through the host SDK.

- The plugin preserves `previous_response_id` when explicitly provided and may auto-fill it from plugin continuation state when `pluginConfig.responseContinuation` is enabled, maintains `text.format` when verbosity defaults are applied, and honors `prompt_cache_retention` from the request body before falling back to `providerOptions.openai.promptCacheRetention` or user config defaults.
- Hosted built-in tool definitions are typed and supported for:
- `tool_search`
- remote `mcp`
- `computer` / `computer_use_preview`
- `namespace` bundles containing nested tools
- Unsupported hosted search/computer tools are filtered before the upstream request when the selected model profile does not advertise that capability.
- Semantic SSE parsing synthesizes compatibility fields such as:
- `output_text`
- `reasoning_summary_text`
- `commentary_text`
- `final_answer_text`
- `phase_text`

These SSE compatibility fields are synthesized only when the corresponding content is present in the response stream.

These behaviors are compatibility guarantees for the current release line because they protect caller intent while keeping the plugin stateless against the ChatGPT Codex backend.

---

## Semver Guidance

- Breaking Tier A change: `MAJOR`
Expand Down