feat(openai): configure Responses verbosity

[Diaspar4u]

What does this PR do?

Adds first-class agent.text_verbosity configuration for OpenAI Responses requests. Valid values are low, medium, and high; empty, unset, or malformed values preserve the provider default.

The setting is emitted as top-level text.verbosity only for supported GPT-5 requests through the canonical ChatGPT Codex route or exact api.openai.com host. It is stripped from Chat Completions, xAI/Grok, GitHub Models, custom endpoints, non-GPT models, and unsupported effective-model overrides.

No merged upstream implementation provides this behavior. This remains the corrected consolidation of #63543 for #20203; #20258, #29574, #59844, and #63543 are still open competing implementations.

Related Issue

Fixes #20203

Type of Change

• 🐛 Bug fix (non-breaking change that fixes a bug)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• Extends the shared Responses route classifier with exact canonical-Codex and direct-OpenAI identities while preserving the broader Codex backend classification.
• Normalizes agent.text_verbosity once at agent construction and invalidates cached gateway agents when it changes.
• Resolves capability from the effective wire model after request overrides, preserves sibling text, extra_body, and service-tier fields, and keeps explicit supported overrides authoritative.
• Reapplies the route/model boundary after mutable request middleware in the current turn_api_call owner, then rejects malformed explicit values during final Responses preflight without stripping unrelated scalar/list text extensions from Chat Completions.
• Expands environment-backed config before gateway cache signatures are computed.
• Documents the config key and provider boundaries.

How to Test

scripts/run_tests.sh \
  tests/agent/test_text_verbosity.py \
  tests/agent/transports/test_codex_transport.py \
  tests/gateway/test_agent_cache.py \
  tests/hermes_cli/test_config.py \
  tests/run_agent/test_run_agent_codex_responses.py \
  tests/run_agent/test_run_agent.py \
  tests/run_agent/test_provider_parity.py \
  tests/run_agent/test_strict_api_validation.py

Current result on head 70b4a9056d4d against upstream 7dc796463d54: 731 passed, 4 skipped. Focused Ruff, Windows-footgun, plugin-compat, git diff --check, and attribution audits pass.

Checklist

Code

• I've read the Contributing Guide
• My commit follows Conventional Commits
• I searched for and reconciled competing PRs
• My PR contains only changes related to this feature
• Full pytest tests/ -q — focused and impact suites above pass
• I've added tests for my changes
• I've tested on macOS

Documentation & Housekeeping

• Relevant documentation is updated
• cli-config.yaml.example is updated
• CONTRIBUTING.md / AGENTS.md — N/A
• Cross-platform impact considered
• Tool descriptions/schemas — N/A

Screenshots / Logs

N/A — request construction and configuration change only.

[alt-glitch]

This was generated by AI during triage.

Related: #20258, #29574, #63543, and #59844 are open implementations of #20203. This PR uses agent.text_verbosity with stricter OpenAI/Codex routing and validation, so it is a competing policy/contract rather than a duplicate.

[teknium1]

Thanks for preserving the earlier implementation and adding config, transport, preflight, cache, and documentation coverage. The feature remains unimplemented on current main: agent/codex_responses_adapter.py:935-941 still rejects top-level text.

Problems

• agent/text_verbosity.py:38 treats is_codex_backend as sufficient for the Codex branch. Current main sets that flag for any provider == "openai-codex" in agent/chat_completion_helpers.py:1176-1181, while hermes_cli/runtime_provider.py:1506-1524 accepts an arbitrary explicit base URL for that provider. A custom host can therefore receive text.verbosity, contrary to the stated fail-closed routing contract.

Suggested changes

• Require the canonical ChatGPT Codex route for the Codex branch, or otherwise validate route identity, and add a custom-host regression test.
• During salvage, move the default-config hunk to hermes_cli/config_defaults.py; current main extracted DEFAULT_CONFIG there.

This is an automated hermes-sweeper review.

[Diaspar4u]

@greptileai

[Diaspar4u]

@teknium1 This branch has been rebased onto current main; please re-review the new head.

The prior review findings are resolved: text.verbosity is now restricted to GPT-5 requests on the canonical ChatGPT Codex route or exact api.openai.com host, custom/xAI/GitHub/non-GPT targets omit it, and the default lives in hermes_cli/config_defaults.py.

Current-head validation: 662 focused/impact tests passed, focused Ruff passed, all three commits are SSH-signature verified, and range/worktree diff checks passed.

[Diaspar4u]

Rebased onto current upstream main at 1d3d021282; the fail-closed routing contract remains intact: only supported GPT-5 Responses requests on canonical ChatGPT Codex or exact api.openai.com receive text.verbosity.

Validation on head 6c27090cef7c:

• focused/impact suite: 674 passed
• focused Ruff and both diff checks: passed
• all four upstream-range commits SSH-signature verified
• independent security/correctness review: passed

@teknium1 @alt-glitch please review the current head.

[Diaspar4u]

Re-review requested. Rebased onto current main and preserved the fail-closed contract: only supported GPT-5 Responses requests on canonical ChatGPT Codex or exact api.openai.com receive text.verbosity.

Validation: 675 focused/impact tests passed; focused Ruff, diff checks, and all four SSH signatures passed.

@teknium1 @alt-glitch please review the current head.

[Diaspar4u]

Rebased the fail-closed Responses verbosity feature onto current main at head f4103ab3c1; all four upstream-range commits have verified SSH signatures. The resolved routing contract still limits text.verbosity to supported GPT-5 requests on canonical ChatGPT Codex or exact api.openai.com targets.

Validation: 675 focused/impact tests passed; focused Ruff, git diff --check, and upstream-range diff checks passed.

@coderabbitai review

@teknium1 @alt-glitch please re-review the current head.

[Diaspar4u]

@Enough1122 Final disposition on all six points for head 1e5b97cc15ca:

1. No change required. Every explicitly selected openai-codex provider still sets is_codex_backend regardless of base URL, so the existing auth-header, response-parsing, compaction, token-limit, and reasoning-replay consumers retain their behavior. URL-based inference still accepts the canonical path with a trailing slash or query string because it compares urlsplit(...).path.rstrip("/"); only noncanonical prefixed or extra-suffix paths on chatgpt.com are intentionally no longer inferred as Codex.
2. Resolved in this head. The transport comment now documents that malformed configured values are omitted, while malformed explicit overrides that survive merging are deliberately rejected by preflight.
3. Confirmed: explicit override verbosity remains authoritative, sibling text fields are preserved, and non-dict extra_body.text values are ignored.
4. Confirmed: the model-family boundary and unsupported-provider exclusions are intentional and covered by the matrix tests.
5. Confirmed: normalized valid changes participate in the gateway cache signature, while malformed config does not.
6. Confirmed: the docs and canonical public contributor mapping match the implementation.

Validation: 675 focused/impact tests passed, focused Ruff and both diff checks passed, attribution passed, and all six upstream-range SSH signatures verified.

[Diaspar4u]

@alt-glitch Final disposition on the competing implementations: #72638 remains the preferred consolidation. It consolidates #63543 under the current Diaspar4u-owned branch and adds fail-closed exact-host/Codex-route gating, malformed-config handling, override precedence, cache invalidation, documentation, and impact coverage beyond #20258, #29574, and #59844. No additional code change is required for this comparison. Current head: 966a279013ff2d66c4ff3aa94125b7f597b6d0ad.

[Enough1122]

AI code review — thanks for the point-by-point disposition on 1e5b97cc15ca.

The confirmation that no other consumer relied on the looser is_codex_backend match closes the main concern; the intentional asymmetry between build_kwargs (silent drop) and _preflight_codex_api_kwargs (raise) is noted. No new issues from this side.

[Diaspar4u]

@Enough1122 Final disposition: this is informational confirmation, so no code change is required. It confirms the prior routing and validation concerns are resolved; current head 966a279013ff2d66c4ff3aa94125b7f597b6d0ad preserves the same validated patch with normalized public commit identity.

[Enough1122]

AI code review — automated review for reference — not a maintainer.

Understood — thanks for confirming. This closes the loop on the routing and validation concerns; no new issues from this side.

[Diaspar4u]

@Enough1122 Final disposition: informational confirmation; no code change required.

Restored canonical-identity head b5976440e0346c5ca69e2657fe093f7cc730a84e; range-diff confirms the functional patch is unchanged from the prior live head. Validation: 731 focused/impact tests passed, focused Ruff passed, git diff --check passed, and the current-main merge tree is clean.

@teknium1 @alt-glitch Please review this exact head and approve its two pending Actions suites.

[Diaspar4u]

@teknium1 CI run #5519 on head b5976440e0346c5ca69e2657fe093f7cc730a84e failed before GitHub Actions created any jobs, check runs, or logs. The PR remains mergeable with a clean current-main merge tree, so this is a workflow-dispatch failure rather than a test failure. Please rerun CI for this exact head; no branch change is warranted.

[Diaspar4u]

Rebuilt the feature on current main as one focused commit around the shared Responses route classifier. The new patch preserves the existing broader Codex backend identity while gating text.verbosity to the exact canonical Codex or direct OpenAI route, rechecks effective model and route after mutable middleware, preserves supported explicit overrides and sibling fields, and keeps gateway cache invalidation aligned with expanded config values.

Validation on head 0307ce62a1dc4013b15a9f7f06f5a24a72e01973: 690 focused/impact tests passed with 4 platform skips; focused Ruff, git diff --check, attribution, current-main ancestry, and the installed OpenAI SDK request surface all pass.

@teknium1 @alt-glitch Please review this exact head and approve its Actions workflows.

[Diaspar4u]

Resolved the final review gap on the current head: Chat Completions now strips only dict-shaped verbosity fields while preserving unrelated scalar/list text extensions in both the legacy and registered-provider paths.

Validation on head 8346b5882c18ab7cbf60e1b8e6f2387931cb03bd: 696 focused/impact tests passed with 4 platform skips; focused Ruff, git diff --check, attribution, and the current-main merge tree pass.

@teknium1 @alt-glitch Please review this exact head and approve its Actions workflows.

[Diaspar4u]

Resolved the current-main compatibility conflicts: the Responses request now preserves upstream wire-normalized reasoning configuration while adding text.verbosity, and the new fast-mode defaults coexist with the verbosity default.

Validation on head 94aa19aa96cf36adf83ac9ceb1a7154087d2eaf7: 722 focused/impact tests passed with 4 platform skips; focused Ruff, git diff --check, attribution, and current-main merge checks passed.

@teknium1 @alt-glitch please review this exact head. A write-access maintainer: please approve its pending Actions workflows.

[Diaspar4u]

Rebased #72638 onto current upstream main and ported the feature to the current request owners, including turn_api_call and run_agent_cache. The supersession check found no merged implementation; the branch remains the complete fail-closed Responses verbosity implementation.

Validation on head 936948c1165c6f1cda8cfdab11b01f7fe6890407: 732 focused/impact tests passed with 4 platform skips; focused Ruff, git diff --check, and attribution audit passed.

@teknium1 @alt-glitch please review this exact head. A write-access maintainer: please approve its pending Actions workflows.

[Diaspar4u]

Rebased onto current upstream main at head 89611ce. The fail-closed GPT-5 Responses verbosity boundary now composes with the current Astra request sanitizer and budget-warning config without changing unsupported provider, host, model, or Chat Completions behavior. The current Windows footgun gate is satisfied with explicit UTF-8 fixture I/O.

Validation: 731 focused tests passed with 4 platform skips; focused Ruff, Windows-footgun, plugin-compat, attribution, and diff checks passed. All competing implementations remain open and no equivalent behavior is merged on main.

@teknium1 @alt-glitch please review this exact head. A write-access maintainer: please approve its Actions workflows.

[Diaspar4u]

Resolved upstream by #115880, merged as 1285de7bbc7bc559b520eb1647af3def5bffb25b. The merged implementation provides the agent.text_verbosity config surface, emits top-level Responses text.verbosity, preserves text.format, excludes chat-completions and xAI requests, and includes focused transport/preflight regressions. Its broader Responses-route support is the accepted replacement for this branch’s narrower route/model gate, so no residual patch remains here.