codex.py 50 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976
  1. """OpenAI Responses API (Codex) transport.
  2. Owns format conversion/normalization on top of agent/codex_responses_adapter.py —
  3. NOT client lifecycle, streaming, or the _run_codex_stream() call path.
  4. """
  5. import hashlib
  6. import json
  7. import logging
  8. import re
  9. from typing import Any, Callable, Optional
  10. from agent.reasoning_effort import (
  11. CODEX_ASTRA_EFFORTS, CODEX_LEGACY_EFFORTS,
  12. grok_supported_efforts, clamp_effort, is_astra_model,
  13. # Same declared vocabulary + shared clamp as the main Codex transport (agent.reasoning_effort):
  14. # per-model — "max" availability varies; "minimal"/"ultra" clamp to a listed level.
  15. codex_supported_efforts,
  16. )
  17. from agent.transports.base import ProviderTransport
  18. from agent.transports.types import NormalizedResponse, ToolCall
  19. logger = logging.getLogger(__name__)
  20. # Cron fires use ``cron_<job_id>_<YYYYMMDD_HHMMSS>``; the per-fire timestamp is
  21. # stripped so repeat fires of one job share a cache scope.
  22. # See #51395, #52295.
  23. _CRON_SESSION_ID_RE = re.compile(r"^(cron_.+)_\d{8}_\d{6}$")
  24. def _cache_scope_from_session_id(session_id: Optional[str]) -> str:
  25. """Normalize a physical session_id into a stable logical cache scope."""
  26. sid = str(session_id or "")
  27. match = _CRON_SESSION_ID_RE.match(sid)
  28. if match:
  29. return match.group(1)
  30. # The unified scheduler admits cron fires into a ``local-*`` session. Its
  31. # physical id is intentionally opaque and changes on every fire, so recover
  32. # the stable job scope from the bound scheduler admission instead.
  33. from gateway.session_cron import current_execution
  34. execution = current_execution()
  35. if execution is not None and str(execution[1]) == sid:
  36. job_id = str(execution[2] or "").strip()
  37. if job_id:
  38. return f"cron_{job_id}"
  39. return sid
  40. def _bounded_prompt_cache_key(value: Any) -> Optional[str]:
  41. """Return a provider-safe (<=64 char) cache key without changing session identity."""
  42. key = "" if value is None else str(value).strip()
  43. if not key:
  44. return None
  45. return key if len(key) <= 64 else "pck_" + hashlib.sha256(key.encode("utf-8", errors="replace")).hexdigest()[:24]
  46. def _bound_prompt_cache_key_field(container: Any) -> None:
  47. """Bound (or drop, when empty) an in-place ``prompt_cache_key`` entry."""
  48. if isinstance(container, dict) and "prompt_cache_key" in container:
  49. bounded = _bounded_prompt_cache_key(container["prompt_cache_key"])
  50. if bounded:
  51. container["prompt_cache_key"] = bounded
  52. else:
  53. container.pop("prompt_cache_key", None)
  54. def _merge_extra_headers(kwargs: dict[str, Any], **headers: str) -> None:
  55. """Merge ``headers`` into a str-coerced copy of ``kwargs['extra_headers']`` (SDK kwarg -> HTTP headers)."""
  56. existing = kwargs.get("extra_headers")
  57. merged = {str(k): str(v) for k, v in existing.items() if k and v is not None} if isinstance(existing, dict) else {}
  58. merged.update(headers)
  59. kwargs["extra_headers"] = merged
  60. # Client-side ``web_search`` on xAI Responses collides with Grok's native tool
  61. # (incomplete hang / HTTP 400); it goes on the wire under this alias.
  62. _XAI_CLIENT_WEB_SEARCH_ALIAS = "hermes_web_search"
  63. # Responses providers reject client functions whose names collide with native
  64. # tools (HTTP 400 "custom function name 'X' is reserved"). Alias them as
  65. # hermes_<name> and map them back before local dispatch.
  66. # OpenCode's /v1/responses endpoints (Zen and Go, including custom providers pointing at opencode.ai)
  67. # reserve certain function names server-side and reject client tools that use them with HTTP 400 ("custom
  68. # function name 'X' is reserved"). Same treatment as the xAI web_search collision: rename on the wire
  69. # (hermes_<name>), map back in normalize_response so Hermes dispatch is unaffected. See #85589.
  70. _OPENCODE_RESERVED_TOOL_NAMES = ("web_search", "search_files")
  71. _PERPLEXITY_RESERVED_TOOL_NAMES = (
  72. "web_search",
  73. "search_files",
  74. "fetch_url",
  75. "people_search",
  76. "finance_search",
  77. )
  78. # xAI and OpenAI Responses (api.openai.com and the ChatGPT Codex backend) reserve ``tool_search``
  79. # for their native Tool Search ("Function 'tool_search.tool_search' not allowed in reserved
  80. # namespace 'tool_search'", #83122 / #95003).
  81. _XAI_RESERVED_TOOL_NAMES = ("tool_search",)
  82. _OPENAI_RESPONSES_HOSTS = frozenset({"api.openai.com", "chatgpt.com"})
  83. _RESERVED_TOOL_ALIAS_PREFIX = "hermes_"
  84. # Reverse map used ONLY when normalize_response runs on a transport that never
  85. # built a request; real requests carry request-local ``_last_wire_aliases``.
  86. _LEGACY_ALIAS_FALLBACK = {
  87. f"{_RESERVED_TOOL_ALIAS_PREFIX}{name}": name
  88. for name in (*_OPENCODE_RESERVED_TOOL_NAMES, *_PERPLEXITY_RESERVED_TOOL_NAMES, *_XAI_RESERVED_TOOL_NAMES)
  89. }
  90. _LEGACY_ALIAS_FALLBACK[_XAI_CLIENT_WEB_SEARCH_ALIAS] = "web_search"
  91. def _is_opencode_responses_backend(params: dict[str, Any]) -> bool:
  92. """True for opencode-zen/go providers, ``opencode-*`` families, or opencode.ai hosts."""
  93. try:
  94. from hermes_cli.models import opencode_provider_family
  95. if opencode_provider_family(params.get("provider")) is not None:
  96. return True
  97. except Exception:
  98. pass
  99. try:
  100. from utils import base_url_hostname
  101. return base_url_hostname(str(params.get("base_url") or "")).lower() == "opencode.ai"
  102. except Exception:
  103. return False
  104. def _is_perplexity_responses_backend(params: dict[str, Any]) -> bool:
  105. """True for Perplexity's Responses-compatible Agent API endpoint."""
  106. try:
  107. from utils import base_url_hostname
  108. return base_url_hostname(str(params.get("base_url") or "")).lower() == "api.perplexity.ai"
  109. except Exception:
  110. return False
  111. def _alias_reserved_tools(
  112. response_tools: list[dict[str, Any]], reserved_names: tuple[str, ...],
  113. name_of: Callable[[dict], Any] = lambda t: t.get("name"),
  114. rename: Callable[[dict, str], dict] = lambda t, alias: {**t, "name": alias},
  115. ) -> tuple[list[dict[str, Any]], dict[str, str]]:
  116. """Alias provider-reserved function names on the wire; returns ``(tools, {alias: original_name})``.
  117. An alias already taken by a real tool gets a ``_2``/``_3`` suffix. ``name_of``/``rename``
  118. adapt the tool shape (Responses ``{name}`` by default; chat_completions passes ``function.name``).
  119. """
  120. rewritten: list[dict[str, Any]] = []
  121. alias_map: dict[str, str] = {}
  122. taken = {name_of(tool) for tool in response_tools if isinstance(tool, dict) and name_of(tool)}
  123. for tool in response_tools:
  124. name = name_of(tool) if isinstance(tool, dict) else None
  125. if name not in reserved_names:
  126. rewritten.append(tool)
  127. continue
  128. base = alias = f"{_RESERVED_TOOL_ALIAS_PREFIX}{name}"
  129. suffix = 2
  130. while alias in taken:
  131. alias, suffix = f"{base}_{suffix}", suffix + 1
  132. taken.add(alias)
  133. alias_map[alias] = name
  134. rewritten.append(rename(tool, alias))
  135. return rewritten, alias_map
  136. def _xai_prefers_native_web_search() -> bool:
  137. """True when xAI Responses should use Grok's native ``web_search`` built-in.
  138. Web-search registry first, then the legacy ``_get_search_backend`` probe; fails closed to native (True).
  139. Delegates to the web-search registry's provider resolution (which reads ``web.search_backend`` /
  140. ``web.backend`` from config) and checks whether the resolved provider is xAI. On any resolution failure,
  141. returns True (fail-closed to native — preserves the #48108 incomplete-hang fix rather than risk
  142. reintroducing it).
  143. """
  144. try:
  145. from agent.web_search_registry import get_active_search_provider
  146. provider = get_active_search_provider()
  147. if provider is not None:
  148. return getattr(provider, "name", None) == "xai"
  149. from tools.web_tools import _get_search_backend
  150. return (_get_search_backend() or "").strip().lower() == "xai"
  151. except Exception:
  152. return True
  153. def _reserves_tool_search(params: dict[str, Any], is_xai_responses: bool) -> bool:
  154. """True when the Responses endpoint owns the ``tool_search`` namespace (xAI, OpenAI, ChatGPT Codex)."""
  155. if is_xai_responses or params.get("is_codex_backend") is True:
  156. return True
  157. try:
  158. from utils import base_url_hostname
  159. return base_url_hostname(str(params.get("base_url") or "")).lower() in _OPENAI_RESPONSES_HOSTS
  160. except Exception:
  161. return False
  162. def _openai_prefers_native_web_search() -> bool:
  163. """True when the active web-search backend selects OpenAI's server-side ``web_search``.
  164. Same contract as :func:`_xai_prefers_native_web_search` with one deliberate
  165. difference: it fails CLOSED (False). A resolution failure must leave the client-side
  166. Hermes tool in place rather than swap in a built-in the endpoint might reject.
  167. Only consulted for the Codex backend (``chatgpt.com/backend-api/codex``); a custom
  168. OpenAI-compatible endpoint does not implement the server-side tool.
  169. """
  170. try:
  171. from agent.web_search_registry import get_active_search_provider
  172. provider = get_active_search_provider()
  173. if provider is not None:
  174. return getattr(provider, "name", None) == "openai-native"
  175. from tools.web_tools import _get_search_backend
  176. return (_get_search_backend() or "").strip().lower() == "openai-native"
  177. except Exception:
  178. return False
  179. def _alias_wire_tools(
  180. response_tools: Any, params: dict[str, Any], is_xai_responses: bool, is_codex_backend: bool = False,
  181. ) -> tuple[Any, dict[str, str]]:
  182. """Apply provider-reserved tool-name aliasing; returns ``(tools, {alias: original})`` for THIS request.
  183. xAI: a client ``web_search`` collides with Grok's native search — native mode
  184. swaps it 1:1 for the built-in, client mode keeps Hermes dispatch under an alias.
  185. OpenAI Codex: the Responses endpoint carries the same collision, so the backend
  186. selection drives the same 1:1 swap (``web.search_backend: openai-native``).
  187. """
  188. wire_aliases: dict[str, str] = {}
  189. def is_client_web_search(t: Any) -> bool:
  190. return isinstance(t, dict) and t.get("name") == "web_search"
  191. if is_xai_responses and response_tools and any(is_client_web_search(t) for t in response_tools):
  192. if _xai_prefers_native_web_search():
  193. response_tools = [t for t in response_tools if not is_client_web_search(t)] + [{"type": "web_search"}]
  194. else:
  195. response_tools = [
  196. {**t, "name": _XAI_CLIENT_WEB_SEARCH_ALIAS} if is_client_web_search(t) else t for t in response_tools
  197. ]
  198. wire_aliases[_XAI_CLIENT_WEB_SEARCH_ALIAS] = "web_search"
  199. # OpenAI Codex: the Responses endpoint exposes the same server-executed ``web_search``,
  200. # and a client-side function of that name collides with it the same way. Unlike xAI there
  201. # is no alias fallback: when the user has not selected ``openai-native`` we leave the
  202. # client tool untouched, so an endpoint that cannot host the built-in never breaks.
  203. if is_codex_backend and response_tools and any(is_client_web_search(t) for t in response_tools):
  204. if _openai_prefers_native_web_search():
  205. response_tools = [t for t in response_tools if not is_client_web_search(t)] + [{"type": "web_search"}]
  206. # OpenCode Responses backends reserve web_search / search_files as function names (HTTP 400 "custom
  207. # function name 'X' is reserved", #85589). Alias them on the wire; normalize_response maps them back.
  208. if response_tools and _is_opencode_responses_backend(params):
  209. response_tools, _oc_aliases = _alias_reserved_tools(response_tools, _OPENCODE_RESERVED_TOOL_NAMES)
  210. wire_aliases.update(_oc_aliases)
  211. # Perplexity's Agent API reserves the same names as server-side tools.
  212. # Keep Hermes's client-side functions available under wire aliases.
  213. if response_tools and _is_perplexity_responses_backend(params):
  214. response_tools, _pplx_aliases = _alias_reserved_tools(response_tools, _PERPLEXITY_RESERVED_TOOL_NAMES)
  215. wire_aliases.update(_pplx_aliases)
  216. # xAI server-side web search vs Hermes web providers. grok models on xAI's /v1/responses surface have a
  217. # *native*, server-executed web search. A client-side function literally named ``web_search`` collides
  218. # with that engine: declared as a plain ``function`` rather than ``{"type": "web_search"}``, the search
  219. # dispatches but never reconciles → incomplete turn + 3 retries. Verified live against
  220. # grok-composer-2.5-fast (2026-06); see #48108. Two modes, chosen by the user's web-search backend
  221. # config: 1. **Native** (active/configured backend is ``xai``, or resolution fails): drop the client
  222. # ``web_search`` function and declare xAI's built-in instead. 1:1 swap only when client ``web_search``
  223. # was already present — never an additive grant. 2. **Client** (Firecrawl / Tavily / Exa / … configured
  224. # or resolved): keep Hermes dispatch so ``web.backend`` / ``web.search_backend`` is honored, but rename
  225. # the wire tool to ``hermes_web_search`` so Grok cannot hijack the name. The alias is mapped back to
  226. # ``web_search`` in ``normalize_response``. Request-local alias provenance: every wire alias THIS
  227. # request emits is recorded here and stashed on the transport, so the reverse rewrite in
  228. # ``normalize_response`` applies only to aliases that were actually sent (never to a real tool that
  229. # merely shares an alias-shaped name).
  230. if response_tools and _reserves_tool_search(params, is_xai_responses):
  231. response_tools, _xai_aliases = _alias_reserved_tools(response_tools, _XAI_RESERVED_TOOL_NAMES)
  232. wire_aliases.update(_xai_aliases)
  233. return response_tools, wire_aliases
  234. # Models already warned that an explicit disable has no wire form on their route (one warning per process).
  235. _UNPROJECTABLE_DISABLE_WARNED: set[str] = set()
  236. # request_overrides is static config: warn about a dropped prompt_cache_options once, not every turn.
  237. _PROMPT_CACHE_OPTIONS_DROP_WARNED = False
  238. def _resolve_reasoning(model: str, params: dict[str, Any]) -> tuple[Any, bool]:
  239. """``(effort, enabled)`` for the request, effort clamped (never escalated) to the endpoint's vocabulary.
  240. A profile-declared ``()`` (or a model that takes no ``reasoning`` field on its route) means "no
  241. reasoning parameters accepted" (400 on any reasoning field) and disables reasoning outright:
  242. ``(None, False)``. An explicit ``reasoning_effort: none`` on a route whose vocabulary has ``none``
  243. resolves to ``("none", False)`` so the disable goes on the wire instead of being omitted — omitting
  244. it re-enables the model's default effort (gpt-5.6 defaults to ``medium``, #75227).
  245. """
  246. reasoning_effort, reasoning_enabled = "medium", True
  247. reasoning_config = params.get("reasoning_config")
  248. if reasoning_config and isinstance(reasoning_config, dict):
  249. if reasoning_config.get("enabled") is False:
  250. reasoning_enabled = False
  251. elif reasoning_config.get("effort"):
  252. reasoning_effort = reasoning_config["effort"]
  253. # Wire vocabularies are declared in agent.reasoning_effort; the shared clamp policy (nearest weaker
  254. # supported level, never escalate, never invert the ladder) replaces the per-backend hand maps that
  255. # repeatedly leaked internal levels like "ultra" to the wire (#89503 class) or clamped one rung below a
  256. # model's real ceiling (#87279).
  257. if params.get("is_xai_responses", False):
  258. supported = grok_supported_efforts(model)
  259. if not supported:
  260. return None, False
  261. else:
  262. base_url = params.get("base_url")
  263. is_codex_backend = params.get("is_codex_backend") is True
  264. # OpenAI's own origins have a known per-model ladder; a profile declaration speaks for
  265. # endpoints the transport cannot know (a custom relay, a catalog-driven router), never
  266. # for a ``custom:`` entry that merely points at api.openai.com.
  267. declared = None
  268. if not (is_codex_backend or _is_openai_api_origin(base_url)):
  269. declared = _profile_declared_efforts(params.get("provider"), model, base_url)
  270. supported = declared if declared is not None else _codex_efforts_for_route(
  271. model, base_url, is_codex_backend=is_codex_backend)
  272. if not supported:
  273. return None, False
  274. if not reasoning_enabled:
  275. has_none = any(str(level).strip().lower() == "none" for level in supported)
  276. if not has_none and model not in _UNPROJECTABLE_DISABLE_WARNED:
  277. # #75227: report the unsupported configuration instead of silently falling back.
  278. _UNPROJECTABLE_DISABLE_WARNED.add(model)
  279. logger.warning(
  280. "reasoning_effort: none cannot be sent for %s — its route accepts only %s, so the model's "
  281. "default effort stays on (an omitted reasoning field does not disable it).",
  282. model, ", ".join(str(level) for level in supported),
  283. )
  284. return ("none" if has_none else None), False
  285. return clamp_effort(reasoning_effort, supported), reasoning_enabled
  286. _EXTENDED_PROMPT_CACHE_MODELS = (
  287. "gpt-5.5-pro", "gpt-5.5", "gpt-5.4", "gpt-5.2",
  288. "gpt-5.1-codex-max", "gpt-5.1-codex-mini", "gpt-5.1-chat-latest", "gpt-5.1-codex", "gpt-5.1",
  289. "gpt-5-codex", "gpt-5", "gpt-4.1",
  290. )
  291. _EXTENDED_PROMPT_CACHE_MODEL_RE = re.compile(
  292. rf"(?:^|[./:])(?:{'|'.join(re.escape(name) for name in _EXTENDED_PROMPT_CACHE_MODELS)})"
  293. r"(?:-\d{4}-\d{2}-\d{2})?$"
  294. )
  295. def _default_prompt_cache_retention_for_request(model: str, base_url: Any) -> Optional[str]:
  296. """Return ``24h`` for supported hosts/models (Bedrock Mantle, Meta)."""
  297. from utils import base_url_hostname
  298. hostname = base_url_hostname(str(base_url or "")).lower()
  299. # Meta Model API: caching is opt-in via prompt_cache_retention (0% hits without).
  300. # Meta Model API (api.meta.ai) only achieves prompt-cache hits on the Responses API with
  301. # prompt_cache_retention; chat/completions stays cache-cold (0% vs 93-99% measured). Exact-hostname
  302. # match per #32243.
  303. # Meta Model API: prompt caching only on Responses API (0% on chat/completions vs 93-99% on /responses
  304. # with retention). See #32243.
  305. if hostname == "api.meta.ai":
  306. return "24h"
  307. parts = hostname.split(".")
  308. is_bedrock_mantle = len(parts) == 4 and parts[0] == "bedrock-mantle" and bool(parts[1]) and parts[2:] == ["api", "aws"]
  309. if not is_bedrock_mantle:
  310. return None
  311. normalized = str(model or "").strip().lower().replace("_", "-")
  312. return "24h" if _EXTENDED_PROMPT_CACHE_MODEL_RE.search(normalized) else None
  313. def _is_openai_api_origin(base_url: Any) -> bool:
  314. """Exact host, so a Responses-compatible proxy or a lookalike subdomain keeps the generic contract."""
  315. from utils import base_url_hostname
  316. return base_url_hostname(str(base_url or "")).lower() == "api.openai.com"
  317. def _is_official_openai_responses_route(model: Any, base_url: Any) -> bool:
  318. """Astra on the canonical API origin only."""
  319. return is_astra_model(model) and _is_openai_api_origin(base_url)
  320. def _codex_efforts_for_route(model: Any, base_url: Any, *, is_codex_backend: bool = False) -> tuple[str, ...]:
  321. """Effort vocabulary for a Responses route; ``()`` when the model takes no ``reasoning`` field at all.
  322. Keeps Astra's new vocabulary off unrelated Responses-compatible endpoints, and sends nothing for the
  323. chat-era OpenAI families (gpt-4o, gpt-4.1, ...) on api.openai.com, which 400 on any ``reasoning``
  324. key (#76255). Only the exact OpenAI origin is judged: a relay serving those ids may translate.
  325. """
  326. if not is_codex_backend and _is_openai_api_origin(base_url):
  327. from agent.model_metadata import openai_model_rejects_reasoning
  328. if openai_model_rejects_reasoning(str(model or "")):
  329. return ()
  330. if is_astra_model(model) and not (
  331. is_codex_backend or _is_official_openai_responses_route(model, base_url)
  332. ):
  333. return CODEX_LEGACY_EFFORTS
  334. return codex_supported_efforts(str(model or ""))
  335. def _sanitize_astra_request_kwargs(kwargs: dict[str, Any], model: Any, base_url: Any) -> None:
  336. """Astra's official-API contract, applied AFTER ``request_overrides`` so an override can't put a
  337. rejected field back on the wire: ``reasoning.effort`` is ``low..max`` only (``none``/``minimal``
  338. 400), sampling and logprob knobs are rejected, and cache lifetime is fixed server-side (the
  339. pre-5.6 ``prompt_cache_retention`` knob is dropped here; ``prompt_cache_options`` is already
  340. stripped on every route by ``build_kwargs``)."""
  341. if not _is_official_openai_responses_route(model, base_url):
  342. return
  343. reasoning = kwargs.get("reasoning")
  344. if isinstance(reasoning, dict):
  345. requested = str(reasoning.get("effort") or "").strip().lower()
  346. reasoning["effort"] = clamp_effort(requested, CODEX_ASTRA_EFFORTS) if requested else "low"
  347. for key in ("temperature", "top_p", "top_logprobs", "logprobs", "prompt_cache_retention"):
  348. kwargs.pop(key, None)
  349. include = kwargs.get("include")
  350. if isinstance(include, list):
  351. kwargs["include"] = [item for item in include if "logprob" not in str(item).lower()]
  352. def _content_cache_key(instructions: str, tools: Optional[list[dict[str, Any]]], scope_id: str = "") -> Optional[str]:
  353. """``pck_<sha256[:24]>`` of (scope_id, instructions, name-sorted tools), or None if nothing static.
  354. Routing hint only; ``scope_id`` keeps unrelated sessions off one bucket.
  355. ``scope_id`` (pass ``_cache_scope_from_session_id(session_id)``) keeps unrelated sessions — independent
  356. conversations, main vs. child/subagent, sibling children — from concentrating onto the same bucket
  357. merely because their static prefix matches (see #78941), while still letting recurring cron fires of one
  358. job share a stable key across their timestamped session_ids (the original #51395/#52295 fix this built
  359. on). Sorting tools by name keeps the hash insertion-order independent.
  360. """
  361. if not instructions and not tools:
  362. return None
  363. tools_part = ""
  364. if tools:
  365. sorted_tools = sorted(
  366. (t for t in tools if isinstance(t, dict)), key=lambda t: str(t.get("name") or t.get("type") or ""),
  367. )
  368. tools_part = json.dumps(sorted_tools, sort_keys=True, ensure_ascii=False, separators=(",", ":"))
  369. # \x00 separators so a boundary can't be forged by content containing the same bytes.
  370. content = f"{scope_id}\x00{instructions or ''}\x00{tools_part}"
  371. return "pck_" + hashlib.sha256(content.encode("utf-8", errors="replace")).hexdigest()[:24]
  372. def _profile_declared_efforts(provider: Any, model: Optional[str], base_url: Any = None) -> Optional[tuple]:
  373. """Provider-profile-declared reasoning-effort vocabulary, or None (fail-open).
  374. Resolves by endpoint host first, then by provider name: a ``custom:<name>`` entry pointed
  375. at a host with a registered profile must follow that host's vocabulary, not the generic
  376. custom declaration. Lazy import: provider plugins import this transport during registry
  377. discovery.
  378. """
  379. try:
  380. from providers import get_provider_profile
  381. name = str(provider or "").strip().lower()
  382. declared = None
  383. if base_url:
  384. from agent.model_metadata import _infer_provider_from_url
  385. inferred = _infer_provider_from_url(str(base_url))
  386. if inferred and inferred != name:
  387. inferred_profile = get_provider_profile(inferred)
  388. if inferred_profile is not None:
  389. declared = inferred_profile.supported_reasoning_efforts(model)
  390. if declared is None:
  391. profile = get_provider_profile(name) if name else None
  392. declared = profile.supported_reasoning_efforts(model) if profile is not None else None
  393. except Exception as exc:
  394. logger.debug("profile-declared efforts lookup failed: %s", exc)
  395. return None
  396. return None if declared is None else tuple(declared)
  397. def _is_azure_foundry_responses(params: dict[str, Any]) -> bool:
  398. """True for Microsoft Foundry's Responses API (provider id, else host match — not substring)."""
  399. from utils import base_url_host_matches
  400. if str(params.get("provider") or "").strip().lower() == "azure-foundry":
  401. return True
  402. return base_url_host_matches(str(params.get("base_url") or ""), "services.ai.azure.com")
  403. def _is_post_tool_replay(messages: Optional[list[dict[str, Any]]]) -> bool:
  404. """True when ``messages`` end on a tool-result run issued by the preceding assistant turn.
  405. Azure Foundry rejects only this post-tool shape when encrypted reasoning is
  406. replayed, so only the *trailing* messages are checked (a whole-history scan
  407. would make suppression sticky). Call ids resolve like ``_chat_messages_to_responses_input``.
  408. """
  409. from agent.codex_responses_adapter import _canonical_call_id_from_fc, _split_responses_tool_id
  410. def _pair_ids(raw: Any, explicit: Any = None) -> set:
  411. embedded_call_id, item_id = _split_responses_tool_id(raw)
  412. ids = {embedded_call_id} if embedded_call_id else set()
  413. if isinstance(explicit, str) and explicit.strip():
  414. ids.add(explicit.strip())
  415. if not ids and isinstance(raw, str) and raw.strip():
  416. ids.add(raw.strip())
  417. canonical = _canonical_call_id_from_fc(item_id)
  418. if canonical:
  419. ids.add(canonical)
  420. return ids
  421. trailing = set()
  422. for msg in reversed(messages or ()):
  423. role = msg.get("role") if isinstance(msg, dict) else None
  424. if role == "system":
  425. continue
  426. if role == "tool":
  427. ids = _pair_ids(msg.get("tool_call_id"))
  428. if not ids:
  429. return False
  430. trailing |= ids
  431. continue
  432. # First non-tool message must be the assistant turn that issued the run.
  433. if role != "assistant":
  434. return False
  435. return any(
  436. trailing & _pair_ids(call.get("id"), call.get("call_id"))
  437. for call in msg.get("tool_calls") or []
  438. if isinstance(call, dict)
  439. )
  440. return False
  441. def _is_azure_responses(params: dict[str, Any]) -> bool:
  442. """True for any Azure-hosted Responses endpoint: the ``azure-foundry`` provider, a resource-level
  443. ``*.openai.azure.com`` host, or the project-scoped ``*.services.ai.azure.com`` gateway."""
  444. from utils import base_url_host_matches
  445. if str(params.get("provider") or "").strip().lower() == "azure-foundry":
  446. return True
  447. base_url = str(params.get("base_url") or "")
  448. return base_url_host_matches(base_url, "openai.azure.com") or base_url_host_matches(base_url, "services.ai.azure.com")
  449. def _newest_reasoning_only(messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
  450. """Copy of ``messages`` keeping ``codex_reasoning_items`` only on the newest assistant row that has any.
  451. Foundry rejects a request that replays encrypted reasoning from more than one prior response (HTTP 400
  452. "Conflicting authenticated continuation identities", #105369). ``compaction`` checkpoints stay everywhere.
  453. A trimmed row is marked ``codex_reasoning_trimmed`` so the converter still drops its ``msg_*`` id (#97427)."""
  454. out: list[dict[str, Any]] = []
  455. newest_kept = False
  456. for msg in reversed(messages):
  457. items = msg.get("codex_reasoning_items") if isinstance(msg, dict) and msg.get("role") == "assistant" else None
  458. if isinstance(items, list) and any(isinstance(i, dict) and i.get("type") != "compaction" for i in items):
  459. if newest_kept:
  460. checkpoints = [i for i in items if isinstance(i, dict) and i.get("type") == "compaction"]
  461. msg = dict(msg, codex_reasoning_trimmed=True)
  462. if checkpoints:
  463. msg["codex_reasoning_items"] = checkpoints
  464. else:
  465. msg.pop("codex_reasoning_items")
  466. newest_kept = True
  467. out.append(msg)
  468. out.reverse()
  469. return out
  470. def _native_compaction_active(context_management: Any) -> bool:
  471. """True only when the caller's eligibility gate produced a non-empty payload.
  472. Every native-compaction wire effect hangs off this predicate, so a persisted
  473. checkpoint cannot keep reshaping requests after the gate closes.
  474. """
  475. return isinstance(context_management, list) and bool(context_management)
  476. def _coerce_timeout(timeout: Any) -> Optional[float]:
  477. """Finite positive number -> float; anything else (None, bool, str, inf) -> None."""
  478. if isinstance(timeout, (int, float)) and not isinstance(timeout, bool) and 0 < float(timeout) < float("inf"):
  479. return float(timeout)
  480. return None
  481. def _sends_all_turns(model: Any, params: dict[str, Any]) -> bool:
  482. """``reasoning.context: "all_turns"`` goes only to api.openai.com models in the live-verified family
  483. table (gpt-5.4/5.5 default to ``current_turn`` and discard replayed earlier-turn blobs without it;
  484. o-series and gpt-5.1-5.3 400 on it). Never the ChatGPT Codex backend: acceptance there is unverified."""
  485. from agent.codex_responses_adapter import openai_reasoning_family
  486. return (
  487. params.get("is_codex_backend") is not True and _is_openai_api_origin(params.get("base_url"))
  488. and openai_reasoning_family(model) is not None
  489. )
  490. def _reasoning_fields(
  491. model: str, params: dict[str, Any], *, effort: Any, enabled: bool, replay_encrypted_reasoning: bool,
  492. is_xai_responses: bool, profile_reasoning: bool, all_turns: bool = False,
  493. ) -> dict[str, Any]:
  494. """``reasoning`` / ``include`` request fields for the endpoint family.
  495. xAI 400s on ``reasoning.effort`` outside its allowlist; a ``profile_reasoning`` endpoint
  496. (``ProviderProfile.responses_profile_reasoning``) takes the verbatim ``profile_reasoning``
  497. payload plus ``summary: "auto"`` and never ``include``. A disabled ask resolved to
  498. ``effort="none"`` is sent as ``{"effort": "none"}`` — the wire has no other way to switch
  499. a reasoning model's default effort off (#75227). ``all_turns`` adds ``context: "all_turns"``
  500. so the model renders replayed reasoning from earlier user turns (``_sends_all_turns``).
  501. """
  502. include = ["reasoning.encrypted_content"] if replay_encrypted_reasoning else []
  503. fields: dict[str, Any] = {}
  504. if enabled and is_xai_responses:
  505. from agent.model_metadata import grok_supports_reasoning_effort
  506. fields["include"] = include
  507. if grok_supports_reasoning_effort(model):
  508. fields["reasoning"] = {"effort": effort}
  509. elif enabled:
  510. if profile_reasoning:
  511. if params.get("profile_reasoning") is not None:
  512. # Request a reasoning summary so the Responses API actually returns reasoning text:
  513. # without ``summary: "auto"`` such endpoints return reasoning items with no summary and
  514. # Hermes persists empty reasoning/thinking content — the same loss the generic branch
  515. # below avoids (#46527).
  516. fields["reasoning"] = {**params["profile_reasoning"], "summary": "auto"}
  517. else:
  518. fields["reasoning"] = {"effort": effort, "summary": "auto", **({"context": "all_turns"} if all_turns else {})}
  519. fields["include"] = include
  520. elif not profile_reasoning and not is_xai_responses:
  521. fields["include"] = []
  522. if effort == "none":
  523. fields["reasoning"] = {"effort": "none"}
  524. return fields
  525. class ResponsesApiTransport(ProviderTransport):
  526. """Transport for api_mode='codex_responses'."""
  527. # Codex response.status -> OpenAI finish_reason (caller checks incomplete_details).
  528. _STOP_REASON_MAP = {"completed": "stop", "incomplete": "length", "failed": "stop", "cancelled": "stop"}
  529. # Issuer kind of the most recent build_kwargs/convert_messages call (normalize_response fallback).
  530. _last_issuer_kind: Optional[str] = None
  531. _last_issuer_model: Optional[str] = None
  532. # ``{wire_alias: original}`` of the most recent build_kwargs. None = no request built (legacy map).
  533. _last_wire_aliases: Optional[dict[str, str]] = None
  534. # Wire models that 400'd on ``reasoning.context`` this session (the transport is cached per agent).
  535. _all_turns_rejected: frozenset = frozenset()
  536. _last_sent_all_turns: bool = False
  537. def reject_all_turns(self, error: Any) -> bool:
  538. """400 naming ``reasoning.context``/``all_turns`` on a request that carried the opt-in: omit it for that
  539. model for the rest of the session. False otherwise, so it buys at most one retry per model."""
  540. text = str(error).lower()
  541. if not self._last_sent_all_turns or getattr(error, "status_code", None) not in (400, None) or not (
  542. "reasoning.context" in text or "all_turns" in text
  543. ):
  544. return False
  545. self._all_turns_rejected = self._all_turns_rejected | {self._last_issuer_model}
  546. self._last_sent_all_turns = False
  547. logger.warning("reasoning.context rejected by %s; omitting it for this session", self._last_issuer_model)
  548. return True
  549. def drop_unverified_replay(self, *message_lists: Any) -> int:
  550. """First ``invalid_encrypted_content`` rung: drop the replayed blobs the failing request could not vouch
  551. for (not stamped by exactly its endpoint + model), keeping the session's own continuity. Returns the
  552. count removed from the first list; 0 means only the route's own blobs were sent."""
  553. from agent.codex_responses_adapter import strip_unverified_reasoning_items
  554. if self._last_issuer_kind is None or self._last_issuer_model is None:
  555. return 0
  556. removed = [
  557. strip_unverified_reasoning_items(msgs, issuer_kind=self._last_issuer_kind, issuer_model=self._last_issuer_model)
  558. for msgs in message_lists
  559. ]
  560. return removed[0] if removed else 0
  561. @property
  562. def api_mode(self) -> str:
  563. return "codex_responses"
  564. def _resolve_issuer_kind(self, params: dict[str, Any], endpoint: Any = None) -> str:
  565. """Classify the current Responses endpoint from transport params (stashed for normalize_response)."""
  566. from agent.codex_responses_adapter import _classify_responses_issuer, responses_endpoint_quirks
  567. base_url = params.get("base_url")
  568. self._last_issuer_kind = _classify_responses_issuer(
  569. is_xai_responses=params.get("is_xai_responses") is True,
  570. is_codex_backend=params.get("is_codex_backend") is True,
  571. base_url=base_url,
  572. endpoint=endpoint if endpoint is not None else responses_endpoint_quirks(base_url),
  573. )
  574. return self._last_issuer_kind
  575. def convert_messages(self, messages: list[dict[str, Any]], **kwargs) -> Any:
  576. """Convert OpenAI chat messages to Responses API input items."""
  577. from agent.codex_responses_adapter import (
  578. _chat_messages_to_responses_input, _wire_model_identity, responses_endpoint_quirks,
  579. )
  580. self._last_issuer_model = _wire_model_identity(kwargs.get("model"))
  581. endpoint = kwargs.get("endpoint") or responses_endpoint_quirks(kwargs.get("base_url"))
  582. return _chat_messages_to_responses_input(
  583. messages, is_xai_responses=kwargs.get("is_xai_responses") is True,
  584. drop_replay_item_ids=not endpoint.replay_item_ids,
  585. replay_encrypted_reasoning=bool(kwargs.get("replay_encrypted_reasoning", True)),
  586. current_issuer_kind=self._resolve_issuer_kind(kwargs, endpoint),
  587. current_issuer_model=self._last_issuer_model,
  588. native_compaction_eligible=_native_compaction_active(kwargs.get("context_management")),
  589. )
  590. def convert_tools(self, tools: Optional[list[dict[str, Any]]]) -> Any:
  591. """Convert OpenAI tool schemas to Responses API function definitions."""
  592. from agent.codex_responses_adapter import _responses_tools
  593. return _responses_tools(tools)
  594. def build_kwargs(
  595. self, model: str, messages: list[dict[str, Any]], tools: Optional[list[dict[str, Any]]] = None, **params,
  596. ) -> dict[str, Any]:
  597. """Build Responses API kwargs (calls convert_messages/convert_tools internally).
  598. params: instructions, reasoning_config ({effort, enabled}), session_id (transcript id;
  599. Codex header; cache-scope fallback), cache_scope_id (rotation-stable scope for the
  600. cache key / xAI conv header), max_tokens, timeout, request_overrides, provider, base_url,
  601. is_codex_backend, is_xai_responses, profile_reasoning, context_management,
  602. replay_encrypted_reasoning. Endpoint quirks (item-id replay, cache key, issuer stamp, reasoning
  603. shape) are resolved from ``base_url`` via ``responses_endpoint_quirks``.
  604. params: instructions: str — system prompt (extracted from messages[0] if not given)
  605. reasoning_config: dict | None — {effort, enabled} session_id: str | None — transcript/session id;
  606. drives the Codex ``session_id`` header, and is the cache-scope fallback when no ``cache_scope_id``
  607. is given cache_scope_id: str | None — rotation-stable logical scope id (compression-lineage root;
  608. see agent/prompt_cache_scope.py). Preferred over session_id when deriving the prompt_cache_key
  609. content hash and the xAI x-grok-conv-id header; the Codex x-client-request-id header mirrors the
  610. resulting body key. Keeps the cache warm across context-compression session rotation (#79017)
  611. max_tokens: int | None — max_output_tokens timeout: float | None — per-request timeout forwarded to
  612. the SDK request_overrides: dict | None — extra kwargs merged in provider: str | None — provider name
  613. for backend-specific logic base_url: str | None — endpoint URL base_url_hostname: str | None —
  614. hostname for backend detection is_codex_backend: bool — chatgpt.com/backend-api/codex
  615. is_xai_responses: bool — xAI/Grok backend profile_reasoning: dict | None — the claiming profile's
  616. ``reasoning_payload`` (sent verbatim on ``responses_profile_reasoning`` endpoints)
  617. """
  618. from agent.prompt_builder import DEFAULT_AGENT_IDENTITY
  619. instructions = params.get("instructions", "")
  620. payload_messages = messages
  621. if not instructions and messages and messages[0].get("role") == "system":
  622. instructions = str(messages[0].get("content") or "").strip()
  623. payload_messages = messages[1:]
  624. instructions = instructions or DEFAULT_AGENT_IDENTITY
  625. from agent.codex_responses_adapter import responses_endpoint_quirks
  626. endpoint = responses_endpoint_quirks(params.get("base_url"))
  627. is_codex_backend = params.get("is_codex_backend") is True
  628. is_xai_responses = params.get("is_xai_responses") is True
  629. # Foundry 400s on encrypted-reasoning replay only in the post-tool follow-up turn.
  630. replay_encrypted_reasoning = bool(params.get("replay_encrypted_reasoning", True)) and not (
  631. _is_azure_foundry_responses(params) and _is_post_tool_replay(payload_messages)
  632. )
  633. # Own predicate: #101243 may narrow _is_azure_foundry_responses to the project gateway, and the
  634. # multi-item rejection happens on resource-level hosts too.
  635. if replay_encrypted_reasoning and _is_azure_responses(params):
  636. payload_messages = _newest_reasoning_only(payload_messages)
  637. # One predicate decides whether context_management goes out AND whether the converter may replay a checkpoint.
  638. context_management = params.get("context_management")
  639. native_compaction_active = _native_compaction_active(context_management)
  640. reasoning_effort, reasoning_enabled = _resolve_reasoning(model, params)
  641. response_tools, self._last_wire_aliases = _alias_wire_tools(
  642. self.convert_tools(tools), params, is_xai_responses, is_codex_backend,
  643. )
  644. # Lazy: provider plugins import this transport during model_metadata init.
  645. from agent.model_metadata import strip_codex_context_variant_suffix as _strip_ctx_variant
  646. request_overrides = params.get("request_overrides") or {}
  647. # An override may rewrite the wire model; provenance must be stamped with what actually goes out.
  648. wire_model = _strip_ctx_variant(request_overrides.get("model", model))
  649. kwargs = {
  650. # ``-900k`` picker variants are Hermes-side aliases; the backend knows only the base slug.
  651. "model": wire_model,
  652. "instructions": instructions,
  653. "input": self.convert_messages(
  654. payload_messages, is_xai_responses=is_xai_responses, endpoint=endpoint,
  655. replay_encrypted_reasoning=replay_encrypted_reasoning, base_url=params.get("base_url"),
  656. is_codex_backend=is_codex_backend, context_management=context_management, model=wire_model,
  657. ),
  658. "store": False,
  659. }
  660. # ``tools`` MUST be omitted when empty: the openai SDK iterates it without a None guard.
  661. if response_tools:
  662. kwargs["tools"] = response_tools
  663. kwargs["tool_choice"] = "auto"
  664. kwargs["parallel_tool_calls"] = True
  665. if native_compaction_active:
  666. kwargs["context_management"] = context_management
  667. session_id = params.get("session_id")
  668. # Content-addressed (instructions + tools) within a logical scope that survives
  669. # compression rotation; session_id itself stays untouched for transcript isolation.
  670. _cache_scope = _cache_scope_from_session_id(params.get("cache_scope_id") or session_id)
  671. cache_key = _content_cache_key(instructions, response_tools, _cache_scope) or _cache_scope
  672. # xAI takes prompt_cache_key in extra_body (below); endpoints declaring
  673. # ``responses_prompt_cache_key=False`` opt out entirely.
  674. if endpoint.prompt_cache_key and not is_xai_responses and cache_key:
  675. kwargs["prompt_cache_key"] = cache_key
  676. cache_retention = _default_prompt_cache_retention_for_request(model, params.get("base_url"))
  677. if cache_retention:
  678. kwargs.setdefault("prompt_cache_retention", cache_retention)
  679. self._last_sent_all_turns = (
  680. reasoning_enabled and _sends_all_turns(wire_model, params) and wire_model not in self._all_turns_rejected
  681. )
  682. kwargs.update(_reasoning_fields(
  683. model, params, effort=reasoning_effort, enabled=reasoning_enabled,
  684. replay_encrypted_reasoning=replay_encrypted_reasoning,
  685. is_xai_responses=is_xai_responses, profile_reasoning=endpoint.profile_reasoning,
  686. all_turns=self._last_sent_all_turns,
  687. ))
  688. # agent.text_verbosity -> top-level ``text.verbosity`` (#20203). Unset sends nothing;
  689. # xAI's /responses rejects unknown top-level fields, same as service_tier below.
  690. text_verbosity = params.get("text_verbosity")
  691. if text_verbosity and not is_xai_responses:
  692. kwargs["text"] = {"verbosity": text_verbosity}
  693. if request_overrides:
  694. kwargs.update(request_overrides)
  695. kwargs["model"] = wire_model
  696. # ``prompt_cache_options`` is not a Responses.create() kwarg in the OpenAI SDK, so a
  697. # top-level copy (e.g. from request_overrides) fails the call with TypeError before any
  698. # request is sent, on every route. Endpoints that manage cache lifetime own it
  699. # server-side; a proxy that accepts the field gets it via request_overrides
  700. # ``extra_body``, which the SDK merges into the body post-transform.
  701. if kwargs.pop("prompt_cache_options", None) is not None:
  702. global _PROMPT_CACHE_OPTIONS_DROP_WARNED
  703. if not _PROMPT_CACHE_OPTIONS_DROP_WARNED:
  704. _PROMPT_CACHE_OPTIONS_DROP_WARNED = True
  705. logger.warning(
  706. "Dropped prompt_cache_options: not a Responses.create() kwarg "
  707. "(use request_overrides={'extra_body': ...} for wire-only fields)."
  708. )
  709. _sanitize_astra_request_kwargs(kwargs, model, params.get("base_url"))
  710. _bound_prompt_cache_key_field(kwargs)
  711. # Older xAI models reject ``service_tier`` (HTTP 400); only Grok 4.6 accepts Priority Processing.
  712. # Grok 4.6 accepts Priority Processing, but continue stripping stale or unsupported tier values on
  713. # every other xAI path. See #28490 and #84799.
  714. if is_xai_responses:
  715. from agent.model_metadata import is_grok_46_family
  716. if not (is_grok_46_family(model) and kwargs.get("service_tier") == "priority"):
  717. kwargs.pop("service_tier", None)
  718. # Forward per-request timeout to the SDK (providers.<id>.request_timeout_seconds).
  719. timeout = _coerce_timeout(kwargs.get("timeout", params.get("timeout")))
  720. if timeout is not None:
  721. kwargs["timeout"] = timeout
  722. else:
  723. kwargs.pop("timeout", None)
  724. if is_codex_backend:
  725. # SDK kwarg -> HTTP headers. ``session_id`` = raw physical id (transcript
  726. # identity); ``x-client-request-id`` mirrors the body cache key so both agree.
  727. headers = {
  728. "session_id": str(session_id) if session_id else None,
  729. "x-client-request-id": kwargs.get("prompt_cache_key") or _bounded_prompt_cache_key(_cache_scope),
  730. }
  731. headers = {k: v for k, v in headers.items() if v}
  732. if headers:
  733. _merge_extra_headers(kwargs, **headers)
  734. elif params.get("max_tokens") is not None:
  735. kwargs["max_output_tokens"] = params["max_tokens"]
  736. if is_xai_responses and session_id:
  737. # Scoped like the body key so cron fires don't each pin a different xAI backend server.
  738. _merge_extra_headers(kwargs, **{"x-grok-conv-id": _cache_scope})
  739. # xAI reads prompt_cache_key from the body; extra_body survives SDK builds whose
  740. # Responses.stream() dropped the typed kwarg. An explicit request_overrides value wins.
  741. # Scoped like the body cache key below — otherwise cron's per-fire timestamp in session_id
  742. # (cron_<id>_<ts>) pins every fire of the same job to a different xAI backend server (#78941).
  743. # xAI Responses cache-routing — body-level field per
  744. # https://docs.x.ai/developers/advanced-api-usage/prompt-caching/maximizing-cache-hits. A
  745. # caller's request_overrides={"prompt_cache_key": ...} lands on the top-level kwarg set above —
  746. # read it back here so an explicit override actually governs the field xAI reads, instead of
  747. # being silently outrun by the auto-derived cache_key (#78941).
  748. existing_extra_body = kwargs.get("extra_body")
  749. kwargs["extra_body"] = dict(existing_extra_body) if isinstance(existing_extra_body, dict) else {}
  750. kwargs["extra_body"].setdefault("prompt_cache_key", kwargs.get("prompt_cache_key", cache_key))
  751. _bound_prompt_cache_key_field(kwargs.get("extra_body"))
  752. return kwargs
  753. def normalize_response(self, response: Any, **kwargs) -> NormalizedResponse:
  754. """Normalize Codex Responses API response to NormalizedResponse."""
  755. from agent.codex_responses_adapter import _normalize_codex_response
  756. msg, finish_reason = _normalize_codex_response(
  757. response, issuer_kind=kwargs.get("issuer_kind") or self._last_issuer_kind,
  758. issuer_model=kwargs.get("issuer_model") or self._last_issuer_model,
  759. )
  760. tool_calls = None
  761. if msg and msg.tool_calls:
  762. tool_calls = []
  763. alias_map = self._last_wire_aliases
  764. for tc in msg.tool_calls:
  765. provider_data = {
  766. key: getattr(tc, key) for key in ("call_id", "response_item_id") if getattr(tc, key, None)
  767. }
  768. has_fn = hasattr(tc, "function")
  769. name = tc.function.name if has_fn else getattr(tc, "name", "")
  770. # Undo only aliases THIS request emitted; the legacy map is for normalize-only call sites.
  771. if alias_map is None:
  772. name = _LEGACY_ALIAS_FALLBACK.get(name, name)
  773. elif name in alias_map:
  774. name = alias_map[name]
  775. tool_calls.append(ToolCall(
  776. id=tc.id if hasattr(tc, "id") else (name or None), name=name,
  777. arguments=tc.function.arguments if has_fn else getattr(tc, "arguments", "{}"),
  778. provider_data=provider_data or None,
  779. ))
  780. provider_data = {
  781. key: getattr(msg, key, None)
  782. for key in ("codex_reasoning_items", "codex_message_items", "reasoning_details")
  783. if msg and getattr(msg, key, None)
  784. }
  785. return NormalizedResponse(
  786. content=msg.content if msg else None, tool_calls=tool_calls, finish_reason=finish_reason or "stop",
  787. reasoning=getattr(msg, "reasoning", None) if msg else None,
  788. usage=None, # Codex usage is extracted separately in normalize_usage()
  789. provider_data=provider_data or None,
  790. )
  791. def validate_response(self, response: Any) -> bool:
  792. """True if response.output is a non-empty list, or a terminal content_filter refusal.
  793. An incomplete/content_filter response with no output must reach normalization,
  794. not a retry. Does NOT check output_text fallback — the caller handles that.
  795. """
  796. if response is None:
  797. return False
  798. output = getattr(response, "output", None)
  799. if isinstance(output, list) and output:
  800. return True
  801. status = str(getattr(response, "status", "") or "").strip().lower()
  802. details = getattr(response, "incomplete_details", None)
  803. raw_reason = details.get("reason") if isinstance(details, dict) else getattr(details, "reason", "")
  804. return status == "incomplete" and str(raw_reason or "").strip().lower() == "content_filter"
  805. def preflight_kwargs(
  806. self, api_kwargs: Any, *, allow_stream: bool = False, drop_replay_item_ids: bool = False,
  807. sanitize_harmony_tokens: bool = False,
  808. ) -> dict:
  809. """Validate and sanitize Codex API kwargs before the call.
  810. ``drop_replay_item_ids`` mirrors the endpoint quirk (``not responses_endpoint_quirks(url).replay_item_ids``).
  811. ``sanitize_harmony_tokens`` is for the ChatGPT Codex backend only (rejects literal Harmony tokens).
  812. """
  813. from agent.codex_responses_adapter import _preflight_codex_api_kwargs
  814. normalized = _preflight_codex_api_kwargs(
  815. api_kwargs, allow_stream=allow_stream, drop_replay_item_ids=drop_replay_item_ids,
  816. sanitize_harmony_tokens=sanitize_harmony_tokens,
  817. )
  818. _bound_prompt_cache_key_field(normalized)
  819. _bound_prompt_cache_key_field(normalized.get("extra_body"))
  820. return normalized
  821. # Auto-register on import
  822. from agent.transports import register_transport
  823. register_transport("codex_responses", ResponsesApiTransport)