feat(codex): add agent.text_verbosity config for GPT-5+ response length control

[qxxaa]

Problem

GPT-5+ models are verbose by default. In agent workflows, this has real
cost: every output token is billed, and longer responses increase latency
on subsequent turns by inflating the conversation history that gets
re-sent as input tokens. Over a multi-turn agent session, verbose output
compounds - each turn's excess output becomes the next turn's excess input.

The OpenAI Responses API accepts a text.verbosity parameter ("low",
"medium", "high") that controls output length for GPT-5+ models. There
is currently no way to configure this in Hermes.

I initially explored using agent.request_overrides in config.yaml to
inject the parameter without any code changes. While the SDK accepts text
as a first-class parameter on responses.create(), request_overrides is
an internal runtime dict populated only by fast mode and custom provider
logic - it is never read from config.yaml. Settings placed there are
silently ignored.

Measured impact: setting text.verbosity: "low" on GPT-5.5 reduced output
from 585 words to 369 words (37% reduction) on identical prompts. In a
typical 20-turn agent session, that reduction compounds across every turn -
shorter assistant responses mean fewer input tokens on every subsequent API
call, reducing both cost and time-to-first-token latency.

Fix

New config key agent.text_verbosity:

agent:
  text_verbosity: "low"  # "low" | "medium" | "high" | "" (default, no injection)

Default is empty string - zero behaviour change for anyone who doesn't
set it. No text parameter is sent, and the model uses its own default
verbosity.

When set, injects text: {"verbosity": "<value>"} into the Responses API
payload. Scoped to GPT-5+ models on the codex_responses transport only.

Design decisions

Model guard: Parses gpt-X.Y from the model name, extracts major
version, injects only when >= 5. Strips vendor prefixes (openai/gpt-5.5
-> gpt-5.5) before matching. Non-GPT models (Claude, Grok, Gemini) are
silently skipped - no errors, no injection.

Dict merge: Merges verbosity into any existing text dict rather than
replacing it. If request_overrides sets text.format, both format and
verbosity coexist in the final payload.

Transport scope: Only the codex_responses transport injects it. Chat
completions and Anthropic message transports are untouched - the parameter
is Responses API specific.

No validation: Consistent with reasoning_effort handling. Invalid
values pass through to the API, which returns a clear error. No client-side
allowlist.

Files changed (13)

File	Change
hermes_cli/config.py	Default "" in agent defaults
agent/agent_init.py	Constructor param + agent attribute
run_agent.py	Pass-through
cli.py	Load from config
hermes_cli/cli_agent_setup_mixin.py	Pass to agent init
hermes_cli/cli_commands_mixin.py	Pass to agent init (background tasks)
gateway/run.py	Loader + 3 load sites + 2 init sites + 1 hot-reload
gateway/platforms/api_server.py	Pass to agent init
tui_gateway/server.py	Loader + 2 injection sites
agent/chat_completion_helpers.py	Pass to codex transport
agent/transports/codex.py	GPT-5+ guard + kwargs injection
tests/agent/transports/test_codex_transport.py	19 tests
website/docs/user-guide/configuration.md	Documentation

Regression risk

Low. Default is empty string (no injection). The if text_verbosity and isinstance(text_verbosity, str) guard ensures no injection happens unless
explicitly configured. Existing behaviour is preserved for all users who
don't set the config key.

Tests

19 tests covering:

• Model guard: inject on 6 GPT-5+ variants, skip on 5 non-GPT-5 models
• Bare gpt- prefix (no version): skip
• Empty verbosity: no injection (2 tests)
• Merge preservation: text.format + text.verbosity coexist
• Vendor-prefixed models: inject on 3 prefixed GPT-5+, skip on prefixed GPT-4

scripts/run_tests.sh tests/agent/transports/test_codex_transport.py -q

79/79 passed (60 existing + 19 new). Zero regressions.

[alt-glitch]

This was generated by AI during triage.

Implements the OPEN feature request #20203 (expose the OpenAI Responses API text.verbosity as an agent.text_verbosity config key). Related to that issue — keeping it open as the feature spec/discussion thread.

[qxxaa]

Closing in favour of #29574, which takes a cleaner approach by loading text_verbosity inside init_agent() directly rather than threading it through every caller. Much smaller surface area for the same result.

Two things worth noting from this PR that #29574 could pick up:

• Dict merge: feat(openai): support Responses text verbosity #29574 sets kwargs["text"] = {"verbosity": verbosity} which clobbers any existing text dict (e.g. text.format from request_overrides). A safe merge preserves both fields.
• Model guard: feat(openai): support Responses text verbosity #29574 skips GitHub and xAI by transport flag, but would still inject on non-OpenAI models routed through OpenRouter's Responses API. A model family check (gpt-5+) is more precise.