codex_responses_adapter.py 73 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359
  1. """Codex Responses API adapter: stateless format conversion and normalization for the
  2. OpenAI Responses API (OpenAI Codex, xAI and other compatible endpoints; per-endpoint quirks come from the
  3. provider profile that claims the endpoint, see :func:`responses_endpoint_quirks`)."""
  4. from __future__ import annotations
  5. import hashlib
  6. import json
  7. import logging
  8. import re
  9. import unicodedata
  10. import uuid
  11. from types import SimpleNamespace
  12. from typing import Any, Callable, Dict, Iterator, List, NamedTuple, Optional, TypeGuard
  13. from agent.message_sanitization import coerce_tool_name, deterministic_call_id
  14. from agent.prompt_builder import DEFAULT_AGENT_IDENTITY
  15. from hermes_cli.route_identity import normalize_route_base_url
  16. logger = logging.getLogger(__name__)
  17. class ResponsesEndpointQuirks(NamedTuple):
  18. """Responses wire quirks of the endpoint, from the ``responses_*`` fields of the profile claiming it
  19. (``providers.profile_for_host``). Defaults are the generic wire."""
  20. replay_item_ids: bool = True
  21. prompt_cache_key: bool = True
  22. issuer_kind: str = ""
  23. native_compaction: bool = True
  24. profile_reasoning: bool = False
  25. _GENERIC_ENDPOINT = ResponsesEndpointQuirks()
  26. def responses_endpoint_quirks(base_url: Any) -> ResponsesEndpointQuirks:
  27. """Quirks for *base_url*; the generic wire when no registered profile claims it (or none is installed).
  28. Pure function of the URL and the registry, so every turn replays the same bytes for the same history."""
  29. from providers import profile_for_host
  30. profile = profile_for_host(str(base_url or ""))
  31. if profile is None:
  32. return _GENERIC_ENDPOINT
  33. return ResponsesEndpointQuirks(
  34. replay_item_ids=profile.responses_replay_item_ids, prompt_cache_key=profile.responses_prompt_cache_key,
  35. issuer_kind=profile.responses_issuer_kind, native_compaction=profile.responses_native_compaction,
  36. profile_reasoning=profile.responses_profile_reasoning,
  37. )
  38. def drops_replay_item_ids(base_url: Any) -> bool:
  39. """Preflight flag: True when *base_url*'s endpoint binds replayed message-item ids to a connection."""
  40. return not responses_endpoint_quirks(base_url).replay_item_ids
  41. def _classify_responses_issuer(
  42. *, is_xai_responses: bool = False, is_codex_backend: bool = False, base_url: Optional[str] = None,
  43. endpoint: Optional[ResponsesEndpointQuirks] = None,
  44. ) -> str:
  45. """Stable identifier for the endpoint that mints ``reasoning.encrypted_content``. Blobs are sealed to their
  46. issuer (HTTP 400 ``invalid_encrypted_content``), so stamping lets replay drop foreign blobs after a model switch.
  47. ``endpoint`` contributes the claiming profile's persisted ``responses_issuer_kind``."""
  48. endpoint_kind = endpoint.issuer_kind if endpoint is not None else ""
  49. for flag, kind in ((is_xai_responses, "xai_responses"), (bool(endpoint_kind), endpoint_kind), (is_codex_backend, "codex_backend")):
  50. if flag:
  51. return kind
  52. if not base_url:
  53. return "other"
  54. # The openai SDK appends a trailing slash to ``client.base_url`` and hosts are case-insensitive, so the
  55. # aux adapter and the main transport must canonicalise the same endpoint to one kind or aux calls drop
  56. # every main-minted blob.
  57. return f"other:{normalize_route_base_url(str(base_url).strip())}"
  58. def _canonical_issuer_kind(kind: Any) -> Any:
  59. """Canonicalise a persisted ``other:<url>`` issuer stamp. Items stamped before canonicalisation carry the raw
  60. ``agent.base_url`` (trailing slash / host case) and must still replay on the same endpoint."""
  61. if isinstance(kind, str) and kind.startswith("other:"):
  62. return _classify_responses_issuer(base_url=kind[len("other:"):])
  63. return kind
  64. # Per-process throttle for the cross-issuer skip warning.
  65. _CROSS_ISSUER_WARN_EMITTED = False
  66. def _wire_model_identity(model: Any) -> Optional[str]:
  67. """Canonical Responses wire model stamped on encrypted reasoning: blobs are sealed to the issuing
  68. model too, so a same-endpoint model switch must not replay them (HTTP 400)."""
  69. from agent.model_metadata import strip_codex_context_variant_suffix
  70. return str(strip_codex_context_variant_suffix(model or "")).strip() or None
  71. # api.openai.com model families that accept ``reasoning.context: "all_turns"`` and honour a reasoning blob
  72. # minted by a sibling variant of the same family (LIVE: gpt-5.4<->5.4-mini, 5.5->5.5-pro, 5.6-luna<->terra,
  73. # 6-astra<->6.1-sol all rendered the blob). o-series, base gpt-5-mini/nano and gpt-5.1/5.2/5.3-codex 400 on
  74. # all_turns, so they are deliberately absent; a blob from another family is silently left out (200), so those
  75. # keep exact-model matching.
  76. _OPENAI_ALL_TURNS_FAMILIES = ("gpt-5.4", "gpt-5.5", "gpt-5.6", "gpt-6")
  77. def openai_reasoning_family(model: Any) -> Optional[str]:
  78. """``_OPENAI_ALL_TURNS_FAMILIES`` entry ``model`` belongs to (``gpt-6.1-sol`` -> ``gpt-6``), else None."""
  79. name = str(model or "").strip().lower()
  80. return next((f for f in _OPENAI_ALL_TURNS_FAMILIES if name == f or name.startswith((f + "-", f + "."))), None)
  81. def _is_openai_api_issuer(issuer_kind: Any) -> bool:
  82. from utils import base_url_hostname
  83. return isinstance(issuer_kind, str) and issuer_kind.startswith("other:") and (
  84. base_url_hostname(issuer_kind[len("other:"):]).lower() == "api.openai.com"
  85. )
  86. def _model_can_read_blob(issuer_kind: Optional[str], item_model: Any, current_model: Optional[str]) -> bool:
  87. """Exact model everywhere; same all_turns family on api.openai.com, which accepts sibling-variant blobs."""
  88. if current_model is None or item_model is None or item_model == current_model:
  89. return True
  90. family = openai_reasoning_family(current_model)
  91. return family is not None and family == openai_reasoning_family(item_model) and _is_openai_api_issuer(issuer_kind)
  92. def strip_unverified_reasoning_items(
  93. messages: Any, *, issuer_kind: Optional[str], issuer_model: Optional[str],
  94. ) -> int:
  95. """First ``invalid_encrypted_content`` rung: drop the items the failing request REPLAYED without an exact
  96. issuer+model stamp (unstamped legacy blobs, sibling-variant blobs). Items another issuer or model minted
  97. were never sent (``_replay_reasoning_items`` skips them) and stay in history for a switch back.
  98. Consumes its own precondition (a second call removes nothing), so recovery cannot loop.
  99. Rebinds the filtered list, never mutates a shared one; returns the number of items removed."""
  100. def unverified_but_sent(item: Any) -> bool:
  101. if not isinstance(item, dict) or item.get("type") == "compaction":
  102. return False
  103. kind, model = _canonical_issuer_kind(item.get("_issuer_kind")), item.get("_issuer_model")
  104. if kind == issuer_kind and model == issuer_model:
  105. return False
  106. return (kind is None or kind == issuer_kind) and _model_can_read_blob(issuer_kind, model, issuer_model)
  107. removed = 0
  108. for msg in messages if isinstance(messages, list) else []:
  109. items = msg.get("codex_reasoning_items") if isinstance(msg, dict) and msg.get("role") == "assistant" else None
  110. if not isinstance(items, list) or not items:
  111. continue
  112. kept = [i for i in items if not unverified_but_sent(i)]
  113. removed += len(items) - len(kept)
  114. if kept:
  115. msg["codex_reasoning_items"] = kept
  116. else:
  117. msg.pop("codex_reasoning_items")
  118. return removed
  119. # Codex/Harmony tool-call serialization leaked into assistant text (no structured function_call).
  120. _TOOL_CALL_LEAK_PATTERN = re.compile(r"(?:^|[\s>|])to=functions\.[A-Za-z_][\w.]*", re.IGNORECASE)
  121. # Codex-CLI-style shell call leaked as assistant text (``{"cmd": "..."}`` closing the message, scalar siblings only).
  122. # Only classified as a leak when the previous line is an action lead-in ("Creating the script now.") — a bare or
  123. # explained JSON object is a legitimate answer and must stay a final response.
  124. _SHELL_JSON_LEAK_PATTERN = re.compile(
  125. r'(?:^|\n)\s*\{\s*"cmd"\s*:\s*"(?:\\.|[^"\\])*"'
  126. r'(?:\s*,\s*"[A-Za-z_][\w-]*"\s*:\s*(?:"(?:\\.|[^"\\])*"|true|false|null|-?\d+(?:\.\d+)?))*\s*\}\s*$',
  127. )
  128. _ACTION_VERBS = r"creat(?:e|ing)|writ(?:e|ing)|runn?(?:ing)?|execut(?:e|ing)|check(?:ing)?|verif(?:y|ying)|updat(?:e|ing)|install(?:ing)?|edit(?:ing)?|mak(?:e|ing)"
  129. _SHELL_JSON_LEAK_LEADIN_PATTERN = re.compile(
  130. rf"^(?:(?:next|first|then|okay|ok|alright)\b[\s,—–-]*)?(?:sure,\s*)?(?:now\s+)?"
  131. rf"(?:let\s+me\s+|i(?:'|’)?ll\s+|i\s+will\s+|i(?:'|’)?m\s+|i\s+am\s+)?(?:{_ACTION_VERBS})\b",
  132. re.IGNORECASE,
  133. )
  134. def _leaked_tool_call_text(text: str) -> bool:
  135. """True when assistant text carries a tool call the model failed to emit as a structured ``function_call``."""
  136. if _TOOL_CALL_LEAK_PATTERN.search(text):
  137. return True
  138. match = _SHELL_JSON_LEAK_PATTERN.search(text)
  139. if not match:
  140. return False
  141. lead_in = text[:match.start()].strip().splitlines()
  142. return bool(lead_in) and bool(_SHELL_JSON_LEAK_LEADIN_PATTERN.search(lead_in[-1].strip()))
  143. # The Codex backend rejects literal Harmony wire tokens (``invalid_prompt: Request
  144. # blocked.``). Fullwidth bars survive format-character stripping and stay legible.
  145. _HARMONY_CONTROL_TOKEN_RE = re.compile(r"<\|(start|end|channel|message|constrain|return|call)\|>")
  146. _FULLWIDTH_PIPE = "\uff5c"
  147. _TEXT_PART_TYPES = {"text", "input_text", "output_text"}
  148. _IMAGE_PART_TYPES = {"image_url", "input_image"}
  149. _VIDEO_PART_TYPES = {"video", "video_url", "input_video"}
  150. _OUTPUT_TEXT_TYPES = {"output_text", "text"}
  151. _ASSISTANT_IMAGE_PLACEHOLDER = "[Assistant image omitted during replay]"
  152. # Inline data-URL subtypes the Responses backends accept as ``input_image``. Anything else
  153. # (SVG source, BMP, TIFF, ...) 400s the WHOLE request — and, once baked into history, every
  154. # later turn too — so it is downgraded to a text placeholder at this converging seam (#29711).
  155. _INCOMPLETE_STATUSES = {"queued", "in_progress", "incomplete"}
  156. _RESPONSE_MESSAGE_STATUSES = {"completed", "incomplete", "in_progress"}
  157. # input[].id / function names longer than this are a non-retryable 400 ("string too
  158. # long"). Codex message ids can run 400+ chars; Hermes ``msg_...`` ids stay under the cap.
  159. _MAX_RESPONSES_ITEM_ID_LENGTH = 64
  160. # Provider-executed built-in tools: declared by ``type`` alone, run server-side,
  161. # reported via the ``*_call`` output items below; preflight passes them through.
  162. _RESPONSES_BUILTIN_TOOL_TYPES = {
  163. "web_search", "web_search_preview", "file_search", "code_interpreter", "image_generation", "computer_use_preview",
  164. "local_shell",
  165. }
  166. # Server-side ``*_call`` output items. xAI leaves these ``in_progress`` even when the
  167. # response is ``completed``, so they must NOT flip the incomplete verdict (else every
  168. # server-search turn burns 3 fruitless continuation retries).
  169. _SERVER_SIDE_TOOL_CALL_TYPES = {
  170. "web_search_call", "file_search_call", "code_interpreter_call",
  171. "image_generation_call", "computer_call", "local_shell_call", "mcp_call",
  172. }
  173. def _nonblank(value: Any) -> TypeGuard[str]:
  174. return isinstance(value, str) and bool(value.strip())
  175. def _nonempty_str(value: Any) -> TypeGuard[str]:
  176. return isinstance(value, str) and bool(value)
  177. def _str_or_empty(value: Any) -> str:
  178. return "" if value is None else str(value)
  179. def _lower_or_none(value: Any) -> Optional[str]:
  180. return value.strip().lower() if isinstance(value, str) else None
  181. def _as_list(value: Any) -> list:
  182. return value if isinstance(value, list) else []
  183. def _field(obj: Any, name: str, default: Any = None) -> Any:
  184. """Read ``name`` from a dict or an attribute-style (SDK/SimpleNamespace) object."""
  185. return obj.get(name) if isinstance(obj, dict) else getattr(obj, name, default)
  186. def _part_type(part: dict[str, Any]) -> str:
  187. return str(part.get("type") or "").strip().lower()
  188. def _text_type_for(role: str) -> str:
  189. return "output_text" if role == "assistant" else "input_text"
  190. def _coerce_arguments(arguments: Any) -> str:
  191. """Normalize replayed tool-call arguments to a non-empty JSON string."""
  192. if isinstance(arguments, dict):
  193. arguments = json.dumps(arguments, ensure_ascii=False)
  194. elif not isinstance(arguments, str):
  195. arguments = str(arguments)
  196. return arguments.strip() or "{}"
  197. def _neutralize_harmony_tokens(text: str) -> str:
  198. """Keep Harmony source readable without emitting reserved wire tokens."""
  199. if not text or "<" not in text or "|" not in text:
  200. return text
  201. # No ASCII code point is a Unicode format control (Cf): str.isascii() is an O(1) flag
  202. # check, and other text only needs each distinct non-ASCII character categorised once.
  203. if text.isascii() or not any(
  204. unicodedata.category(char) == "Cf" for char in set(text) if char > "\x7f"
  205. ):
  206. return _HARMONY_CONTROL_TOKEN_RE.sub(rf"<{_FULLWIDTH_PIPE}\1{_FULLWIDTH_PIPE}>", text)
  207. # The backend strips Unicode format controls (e.g. U+200B) before its reserved-token
  208. # check, so match on the visible text and rewrite the original spans.
  209. original_positions = [i for i, char in enumerate(text) if unicodedata.category(char) != "Cf"]
  210. visible_text = "".join(text[i] for i in original_positions)
  211. result, cursor = [], 0
  212. for match in _HARMONY_CONTROL_TOKEN_RE.finditer(visible_text):
  213. start, end = original_positions[match.start()], original_positions[match.end() - 1] + 1
  214. result += [text[cursor:start], f"<{_FULLWIDTH_PIPE}{match.group(1)}{_FULLWIDTH_PIPE}>"]
  215. cursor = end
  216. return "".join(result) + text[cursor:]
  217. def _neutralize_harmony_structure(value: Any) -> Any:
  218. """Neutralize JSON-like values (tuples → lists). A reserved token in an object *key* is
  219. rejected, not rewritten — renaming could desync a tool schema from the executor contract."""
  220. if isinstance(value, str):
  221. return _neutralize_harmony_tokens(value)
  222. if isinstance(value, (list, tuple)):
  223. return [_neutralize_harmony_structure(item) for item in value]
  224. if isinstance(value, dict):
  225. if any(isinstance(key, str) and _neutralize_harmony_tokens(key) != key for key in value):
  226. raise ValueError(
  227. "Reserved Harmony tokens in a JSON object key cannot be "
  228. "neutralized without changing its contract."
  229. )
  230. return {key: _neutralize_harmony_structure(item) for key, item in value.items()}
  231. return value
  232. # --- Multimodal content helpers ---------------------------------------------
  233. def _iter_content_parts(content: list) -> Iterator[tuple[str, Any]]:
  234. """Yield ``("text", str)`` / ``("image", part)`` for recognized chat parts."""
  235. for part in content:
  236. if isinstance(part, str) and part:
  237. yield "text", part
  238. elif isinstance(part, dict):
  239. ptype = _part_type(part)
  240. if ptype in _TEXT_PART_TYPES and _nonempty_str(part.get("text")):
  241. yield "text", part["text"]
  242. elif ptype in _IMAGE_PART_TYPES:
  243. yield "image", part
  244. def _input_image_part(part: dict[str, Any], role: str = "user", *, keep_empty_url: bool) -> Optional[dict[str, Any]]:
  245. """Responses image part from a chat/Responses image part (``image_url`` may be a str or
  246. ``{url, detail}``). Assistant → text placeholder (an assistant ``input_image`` 400s every
  247. replay); user → ``input_image``, None for an empty url unless ``keep_empty_url``; an inline
  248. SVG is rasterized to PNG when a rasterizer is installed, any other unsupported inline
  249. subtype (or an SVG with no rasterizer) → text placeholder."""
  250. if role == "assistant":
  251. return {"type": "output_text", "text": _ASSISTANT_IMAGE_PLACEHOLDER}
  252. url, detail = part.get("image_url"), part.get("detail")
  253. if isinstance(url, dict):
  254. url, detail = url.get("url"), url.get("detail", detail)
  255. if not _nonempty_str(url) and not keep_empty_url:
  256. return None
  257. url = str(url or "")
  258. # Lazy import: the prep module only depends on hermes_constants at import time (no cycle).
  259. from tools.vision_tools_image_prep import rasterize_svg_data_url, unsupported_inline_image_media_type
  260. mime = unsupported_inline_image_media_type(url)
  261. if mime == "image/svg+xml":
  262. # Rasterize so the model still sees the drawing; the placeholder is the fallback only
  263. # when no rasterizer (cairosvg / svglib / rsvg-convert / inkscape) is available.
  264. png_url = rasterize_svg_data_url(url)
  265. if png_url is not None:
  266. url, mime = png_url, None
  267. if mime is not None:
  268. return {"type": "input_text", "text": f"[image omitted: {mime} is not a supported image format]"}
  269. image_part: dict[str, Any] = {"type": "input_image", "image_url": url}
  270. if _nonblank(detail):
  271. image_part["detail"] = detail.strip()
  272. return image_part
  273. def _chat_content_to_responses_parts(content: Any, *, role: str = "user") -> list[dict[str, Any]]:
  274. """Chat-style multimodal content → Responses API input parts ([] if not a list). Text is
  275. ``input_text`` (user) / ``output_text`` (assistant) — the API rejects the wrong type per role;
  276. ``input_image`` is only legal on user messages (see :func:`_input_image_part`). Unsupported
  277. video parts fail closed instead of silently turning a video request into a text-only request."""
  278. for part in _as_list(content):
  279. if isinstance(part, dict) and (ptype := _part_type(part)) in _VIDEO_PART_TYPES:
  280. raise ValueError(
  281. f"Codex Responses does not support {ptype} input; use a video-capable provider."
  282. )
  283. text_type = _text_type_for(role)
  284. converted: list[dict[str, Any]] = []
  285. for kind, payload in _iter_content_parts(_as_list(content)):
  286. if kind == "text":
  287. converted.append({"type": text_type, "text": payload})
  288. elif (part := _input_image_part(payload, role, keep_empty_url=False)) is not None:
  289. converted.append(part)
  290. return converted
  291. def _summarize_user_message_for_log(content: Any, *, sep: str = " ") -> str:
  292. """Flatten message content to plain text: text parts joined with ``sep`` (``" "`` for logs; ``"\\n"`` for memory
  293. providers feeding regexes), images → ``[N image(s)]`` marker, ``""`` for None, ``str(content)`` for other scalars."""
  294. if not isinstance(content, list):
  295. try:
  296. return _str_or_empty(content)
  297. except Exception:
  298. return ""
  299. parts = list(_iter_content_parts(content))
  300. text_bits = [payload for kind, payload in parts if kind == "text"]
  301. image_count = len(parts) - len(text_bits)
  302. note = f"[{image_count} image{'s' if image_count != 1 else ''}]" if image_count else ""
  303. return " ".join(bit for bit in (note, sep.join(text_bits).strip()) if bit)
  304. # --- ID helpers ---------------------------------------------------------------
  305. def _clamp_responses_call_id(call_id: str) -> str:
  306. """Keep ``call_id`` within the API's 64-char cap (the codex app-server namespaces MCP call ids past it). The
  307. surrogate is a pure function of the original so a ``function_call`` and its ``function_call_output`` agree."""
  308. if len(call_id) <= _MAX_RESPONSES_ITEM_ID_LENGTH:
  309. return call_id
  310. return f"call_{hashlib.sha256(call_id.encode('utf-8', errors='replace')).hexdigest()[:32]}"
  311. def _canonical_call_id_from_fc(response_item_id: Any) -> Optional[str]:
  312. """Map an ``fc_…`` item id to its canonical ``call_<suffix>``. Both sides of a replayed
  313. pair must derive the SAME call_id, or an oversized pair clamps to two surrogates."""
  314. if isinstance(response_item_id, str) and response_item_id.startswith("fc_") and len(response_item_id) > 3:
  315. return f"call_{response_item_id[3:]}"
  316. return None
  317. def _split_responses_tool_id(raw_id: Any) -> tuple[Optional[str], Optional[str]]:
  318. """Split a stored tool id into (call_id, response_item_id)."""
  319. value = raw_id.strip() if isinstance(raw_id, str) else ""
  320. if "|" in value:
  321. call_id, response_item_id = value.split("|", 1)
  322. return call_id.strip() or None, response_item_id.strip() or None
  323. if not value:
  324. return None, None
  325. return (None, value) if value.startswith("fc_") else (value, None)
  326. def _resolve_call_id(
  327. raw_call_id: Any, raw_item_id: Any, fn_name: str, arguments: Any, index: int, *, canonicalize_fc: bool,
  328. ) -> str:
  329. """Pick a non-blank call_id: explicit -> embedded in ``call|fc`` id -> (replay only)
  330. canonical ``call_<fc suffix>`` -> deterministic hash of name/arguments/index."""
  331. embedded_call_id, embedded_response_item_id = _split_responses_tool_id(raw_item_id)
  332. call_id = raw_call_id if _nonblank(raw_call_id) else embedded_call_id
  333. if not _nonblank(call_id) and canonicalize_fc:
  334. call_id = _canonical_call_id_from_fc(embedded_response_item_id)
  335. if not _nonblank(call_id):
  336. call_id = deterministic_call_id(fn_name, arguments, index)
  337. return call_id.strip()
  338. def _derive_responses_function_call_id(call_id: str, response_item_id: Optional[str] = None) -> str:
  339. """Build a valid Responses `function_call.id` (must start with `fc_`)."""
  340. if isinstance(response_item_id, str) and response_item_id.strip().startswith("fc_"):
  341. return response_item_id.strip()
  342. source = (call_id or "").strip()
  343. sanitized = re.sub(r"[^A-Za-z0-9_-]", "", source)
  344. for candidate in (source, sanitized):
  345. if candidate.startswith("fc_") or (candidate.startswith("call_") and len(candidate) > len("call_")):
  346. return candidate if candidate.startswith("fc_") else f"fc_{candidate[len('call_'):]}"
  347. if sanitized:
  348. return f"fc_{sanitized[:48]}"
  349. seed = source or str(response_item_id or "") or uuid.uuid4().hex
  350. return f"fc_{hashlib.sha1(seed.encode('utf-8')).hexdigest()[:24]}"
  351. # --- Schema conversion --------------------------------------------------------
  352. def _responses_tools(tools: Optional[list[dict[str, Any]]] = None) -> Optional[list[dict[str, Any]]]:
  353. """Convert chat-completions tool schemas to Responses function-tool schemas."""
  354. fns = [item.get("function", {}) if isinstance(item, dict) else {} for item in tools or []]
  355. converted = [
  356. {
  357. "type": "function", "name": fn["name"], "description": fn.get("description", ""),
  358. "strict": fn.get("strict") if isinstance(fn.get("strict"), bool) else False,
  359. "parameters": fn.get("parameters", {"type": "object", "properties": {}}),
  360. }
  361. for fn in fns if _nonblank(fn.get("name"))
  362. ]
  363. return converted or None
  364. # --- Message format conversion (chat history -> Responses input) --------------
  365. def _normalize_responses_message_status(value: Any, *, default: str = "completed") -> str:
  366. """Normalize a replayed assistant message status, modulo case/hyphen spelling, so incomplete Codex
  367. continuation turns are not falsely marked completed."""
  368. status = value.strip().lower().replace("-", "_").replace(" ", "_") if isinstance(value, str) else None
  369. return status if status in _RESPONSE_MESSAGE_STATUSES else default
  370. def _message_item(
  371. content: list[dict[str, Any]], *, status: str, item_id: Optional[str] = None, phase: Optional[str] = None,
  372. ) -> dict[str, Any]:
  373. """Assistant ``message`` item; ``id``/``phase`` are added only when non-empty."""
  374. item: dict[str, Any] = {"type": "message", "role": "assistant", "status": status, "content": content}
  375. item.update({k: v for k, v in (("id", item_id), ("phase", phase)) if v})
  376. return item
  377. _ROLE_MESSAGE_PHASES = frozenset({"commentary", "final_answer"})
  378. def _role_message_item(role: str, content: Any, phase: Any = None) -> dict[str, Any]:
  379. """Plain ``message`` input item for ``role``. ``type`` is required: llama.cpp's ``/v1/responses``
  380. parser rejects a typeless assistant item ("Cannot determine type of 'item'"). Assistant ``phase``
  381. is forwarded only for values the API accepts on input messages; others would 400."""
  382. item = {"type": "message", "role": role, "content": content}
  383. if role == "assistant" and (cleaned := _lower_or_none(phase)) in _ROLE_MESSAGE_PHASES:
  384. item["phase"] = cleaned
  385. return item
  386. def _assistant_message_item(
  387. raw: dict[str, Any], content: list[dict[str, Any]], *, drop_replay_item_ids: bool,
  388. current_issuer_kind: Optional[str] = None,
  389. ) -> dict[str, Any]:
  390. """Replayable assistant ``message`` item from a stored one. ``id`` is kept only when short enough and never on an
  391. endpoint that binds ids to a backend connection (``drop_replay_item_ids``; stale → 401); ``phase`` is preserved
  392. per OpenAI's cache guidance.
  393. The ChatGPT Codex backend additionally rejects ids that do not begin with ``msg`` (foreign Responses issuers
  394. mint short UUIDs), so those are dropped there while other issuers' policies are unchanged."""
  395. item_id, phase = raw.get("id"), raw.get("phase")
  396. keep_id = not drop_replay_item_ids and _nonblank(item_id) and len(item_id.strip()) <= _MAX_RESPONSES_ITEM_ID_LENGTH
  397. if keep_id and current_issuer_kind == "codex_backend" and not item_id.strip().startswith("msg"):
  398. keep_id = False
  399. return _message_item(
  400. content, status=_normalize_responses_message_status(raw.get("status")),
  401. item_id=item_id.strip() if keep_id else None, phase=phase.strip() if _nonblank(phase) else None,
  402. )
  403. def _replay_reasoning_items(
  404. msg: dict[str, Any], *, seen_item_ids: set, current_issuer_kind: Optional[str],
  405. current_issuer_model: Optional[str] = None, native_compaction_eligible: bool,
  406. ) -> list[dict[str, Any]]:
  407. """Replay persisted encrypted reasoning/compaction items for one assistant turn. Skips duplicate
  408. ids, ``compaction`` checkpoints unless THIS request carries ``context_management`` (else a persisted
  409. checkpoint erases pre-checkpoint history on a model that cannot decrypt it), and items stamped by
  410. another issuer or model (HTTP 400). Items without a model stamp (legacy or unstamped) replay on a
  411. matching issuer. ``id`` (store=False lookups 404) and the Hermes provenance fields are stripped."""
  412. global _CROSS_ISSUER_WARN_EMITTED
  413. replayed: list[dict[str, Any]] = []
  414. for ri in _as_list(msg.get("codex_reasoning_items")):
  415. if not (isinstance(ri, dict) and ri.get("encrypted_content")):
  416. continue
  417. item_id = ri.get("id")
  418. if (item_id and item_id in seen_item_ids) or (ri.get("type") == "compaction" and not native_compaction_eligible):
  419. continue
  420. item_issuer = _canonical_issuer_kind(ri.get("_issuer_kind"))
  421. item_model = ri.get("_issuer_model")
  422. foreign_issuer = current_issuer_kind is not None and item_issuer is not None and item_issuer != current_issuer_kind
  423. # No model stamp → trust the endpoint stamp. Native compaction checkpoints and reasoning persisted
  424. # before model stamping carry none; dropping them would erase every existing session's context
  425. # once. A wrong guess is caught by the invalid_encrypted_content 400 classifier, whose first rung
  426. # strips exactly these unverified (unstamped / sibling-family) items.
  427. foreign_model = not _model_can_read_blob(current_issuer_kind, item_model, current_issuer_model)
  428. if foreign_issuer or foreign_model:
  429. if not _CROSS_ISSUER_WARN_EMITTED:
  430. logger.warning(
  431. "Dropping reasoning item minted by %s/%s while calling %s/%s — encrypted_content is "
  432. "sealed to its issuer and model. This happens when a session switches model mid-conversation.",
  433. item_issuer, item_model, current_issuer_kind, current_issuer_model,
  434. )
  435. _CROSS_ISSUER_WARN_EMITTED = True
  436. continue
  437. replayed.append({k: v for k, v in ri.items() if k not in ("id", "_issuer_kind", "_issuer_model")})
  438. if item_id:
  439. seen_item_ids.add(item_id)
  440. return replayed
  441. def _replay_message_items(
  442. msg: dict[str, Any], *, drop_replay_item_ids: bool, current_issuer_kind: Optional[str] = None,
  443. ) -> list[dict[str, Any]]:
  444. """Replay exact assistant message items (id/phase) for prefix-cache hits.
  445. A ``msg_*`` id minted in the same response as a ``reasoning`` item is bound to that item's ``rs_*`` id,
  446. which ``_replay_reasoning_items`` always strips (store=False). Replaying the message id alone is a
  447. deterministic HTTP 400 ("provided without its required 'reasoning' item", #97427/#97442), so the message
  448. id is dropped whenever its turn carried encrypted reasoning — replayed, suppressed, foreign-issuer or
  449. trimmed by the transport (``codex_reasoning_trimmed``) — and the message goes out as content/status/phase
  450. only. Reasoning-free turns keep their id.
  451. """
  452. replayed: list[dict[str, Any]] = []
  453. linked_to_reasoning = bool(msg.get("codex_reasoning_trimmed")) or any(
  454. isinstance(ri, dict) and ri.get("encrypted_content") for ri in _as_list(msg.get("codex_reasoning_items"))
  455. )
  456. for raw_item in _as_list(msg.get("codex_message_items")):
  457. if not (isinstance(raw_item, dict) and raw_item.get("type") == "message" and raw_item.get("role") == "assistant"):
  458. continue
  459. content = [
  460. {"type": "output_text", "text": _str_or_empty(part.get("text", ""))}
  461. for part in _as_list(raw_item.get("content"))
  462. if isinstance(part, dict) and str(part.get("type") or "").strip() in _OUTPUT_TEXT_TYPES
  463. ]
  464. if content:
  465. if linked_to_reasoning and raw_item.get("id"):
  466. raw_item = {k: v for k, v in raw_item.items() if k != "id"}
  467. replayed.append(_assistant_message_item(
  468. raw_item, content, drop_replay_item_ids=drop_replay_item_ids, current_issuer_kind=current_issuer_kind,
  469. ))
  470. return replayed
  471. class _WireCallIds:
  472. """Per-request wire ids for replayed tool pairs.
  473. Stored call ids are minted per turn (``terminal:0``, ``terminal:1``…), so the same id recurs on
  474. later turns of one session. Replayed verbatim, strict Responses validators reject the whole
  475. request with 400 "Duplicate function_call_output for call_id" and every retry of the turn fails
  476. identically (#102629, #111231). Every occurrence past the first gets a ``_dup<n>`` wire id; the
  477. matching tool output pops the id its ``function_call`` was given, in call order, so pairs stay
  478. intact and the stored history is untouched.
  479. """
  480. def __init__(self) -> None:
  481. self._seen: dict[str, int] = {}
  482. self._queue: dict[str, list[str]] = {}
  483. def for_call(self, call_id: str) -> str:
  484. base = _clamp_responses_call_id(call_id)
  485. n = self._seen.get(base, 0)
  486. self._seen[base] = n + 1
  487. wire = base if n == 0 else _clamp_responses_call_id(f"{base}_dup{n}")
  488. self._queue.setdefault(base, []).append(wire)
  489. return wire
  490. def for_output(self, call_id: str) -> str:
  491. base = _clamp_responses_call_id(call_id)
  492. queue = self._queue.get(base)
  493. return queue.pop(0) if queue else base
  494. def _replay_tool_call_items(
  495. msg: dict[str, Any], *, start_index: int, wire_ids: Optional[_WireCallIds] = None,
  496. ) -> list[dict[str, Any]]:
  497. """Convert an assistant message's ``tool_calls`` into ``function_call`` items."""
  498. replayed: list[dict[str, Any]] = []
  499. for tc in _as_list(msg.get("tool_calls")):
  500. if not isinstance(tc, dict):
  501. continue
  502. fn = tc.get("function", {})
  503. fn_name, arguments = fn.get("name"), fn.get("arguments", "{}")
  504. if not _nonblank(fn_name):
  505. continue
  506. index = start_index + len(replayed)
  507. call_id = _resolve_call_id(tc.get("call_id"), tc.get("id"), fn_name, str(arguments), index, canonicalize_fc=True)
  508. replayed.append({
  509. "type": "function_call",
  510. "call_id": wire_ids.for_call(call_id) if wire_ids else _clamp_responses_call_id(call_id),
  511. "name": coerce_tool_name(fn_name, fallback="fn"), "arguments": _coerce_arguments(arguments),
  512. })
  513. return replayed
  514. def _tool_output_items(msg: dict[str, Any], *, wire_ids: Optional[_WireCallIds] = None) -> list[dict[str, Any]]:
  515. """Convert a tool-role message to ``[function_call_output]`` (``[]`` if unpairable)."""
  516. raw_tool_call_id = msg.get("tool_call_id")
  517. call_id, tool_response_item_id = _split_responses_tool_id(raw_tool_call_id)
  518. if not _nonblank(call_id):
  519. # Legacy fc_-only ids canonicalize to the same ``call_<suffix>`` the
  520. # assistant side synthesizes, so a >64-char pair clamps identically.
  521. call_id = _canonical_call_id_from_fc(tool_response_item_id)
  522. if call_id is None and _nonblank(raw_tool_call_id):
  523. call_id = raw_tool_call_id.strip()
  524. if not _nonblank(call_id):
  525. return []
  526. # ``output`` may be a string or an ``input_text``/``input_image`` array.
  527. tool_content = msg.get("content")
  528. is_parts = isinstance(tool_content, list)
  529. output_value: Any = (_chat_content_to_responses_parts(tool_content) or "") if is_parts else str(tool_content or "")
  530. wire_call_id = wire_ids.for_output(call_id) if wire_ids else _clamp_responses_call_id(call_id)
  531. return [{"type": "function_call_output", "call_id": wire_call_id, "output": output_value}]
  532. def _chat_messages_to_responses_input(
  533. messages: list[dict[str, Any]], *, is_xai_responses: bool = False, drop_replay_item_ids: bool = False,
  534. replay_encrypted_reasoning: bool = True, current_issuer_kind: Optional[str] = None,
  535. current_issuer_model: Optional[str] = None, native_compaction_eligible: bool = False,
  536. ) -> list[dict[str, Any]]:
  537. """Convert internal chat-style messages to Responses input items.
  538. ``is_xai_responses``: signature compatibility only (xAI DOES replay encrypted reasoning).
  539. ``replay_encrypted_reasoning``: per-session kill switch, threaded False by
  540. ``AIAgent._disable_codex_reasoning_replay`` after a repeat ``invalid_encrypted_content`` 400.
  541. ``drop_replay_item_ids``: drops ``id`` from replayed message items (endpoint quirk ``replay_item_ids=False``).
  542. ``current_issuer_kind`` / ``current_issuer_model``: provenance guard; items stamped by another issuer or
  543. model drop. Legacy items carrying only an endpoint stamp replay on a matching issuer.
  544. ``native_compaction_eligible``: THIS request carries ``context_management``; gates both replaying ``compaction``
  545. checkpoints and ``prune_pre_checkpoint_items``. Checkpoints persist across model swaps / compression flips / resume,
  546. so without the gate one checkpoint would erase pre-checkpoint history on a model that cannot decrypt it (lossless:
  547. local history is never truncated).
  548. Earlier (PR #26644, May 2026) we believed xAI's OAuth/SuperGrok ``/v1/responses`` surface rejected
  549. replayed ``encrypted_content`` reasoning items minted by prior turns, and we stripped them. That
  550. decision was wrong — xAI explicitly relies on Hermes threading encrypted reasoning back across turns for
  551. cross-turn coherence (the whole point of their partnership integration). We now replay encrypted
  552. reasoning on every Responses transport (xAI, native Codex, custom relays) and let xAI tell us explicitly
  553. if a specific surface ever rejects a payload.
  554. Some backends bind these ids to a specific backend "connection" — credential-pool rotation, a gateway
  555. restart, or routine load-balancer churn between turns all invalidate it — and reject a stale id with HTTP 401
  556. "input item ID does not belong to this connection" even for short ids (see #32716). ``phase``/``status``/
  557. ``content`` are still replayed there; only ``id`` is unsafe to reuse across such a connection.
  558. ``native_compaction_eligible`` mirrors, for THIS request, the decision made by
  559. ``native_compaction.native_compaction_context_management`` — it is True only when that gate returned a
  560. payload, i.e. when the request actually carries ``context_management``. It controls two things that must
  561. never outlive the gate: replaying ``type: "compaction"`` checkpoint items, and restructuring the wire
  562. around them (``prune_pre_checkpoint_items``). Checkpoints are persisted in the ``codex_reasoning_items``
  563. sidecar and survive a mid-session model swap, a ``compression.enabled: false`` flip, the rejection kill
  564. switch and a resumed session; without this flag a single captured checkpoint would keep deleting every
  565. pre-checkpoint item from every later request, on a model that cannot decrypt the blob (#85914). Default
  566. False = pre-feature wire, which is also correct for every caller that never sends ``context_management``
  567. (auxiliary/compression client, ad-hoc ``convert_messages``). Dropping the checkpoint costs nothing:
  568. Hermes' local history is never truncated by native compaction, so the full conversation is still on the
  569. wire.
  570. """
  571. items: list[dict[str, Any]] = []
  572. # Parallel to ``items``: source chat message per item. Pruning reads a summary
  573. # carrier's provenance from the source; the converted item may be a lossy shape.
  574. # Pruning needs this to read a canonical summary carrier's up-to-date, provenance-tagged content
  575. # directly — the converted `item` can be a lossy shape (stale exact-replay, or a typed
  576. # `function_call_output` wrapper) that no longer carries it (#90976).
  577. item_sources: list[Optional[dict[str, Any]]] = []
  578. seen_item_ids: set = set()
  579. wire_ids = _WireCallIds()
  580. # The ChatGPT Codex backend rejects a role message whose ``content`` is a plain string with
  581. # ``{"detail": "Unsupported content type"}`` (400) — even a single user turn with no replay state
  582. # (#51512). It accepts only typed parts, so string text goes out as ``input_text``/``output_text``
  583. # there; other Responses routes keep the string shorthand they have always received.
  584. typed_text_only = current_issuer_kind == "codex_backend"
  585. def emit(new_items: list[dict[str, Any]], msg: dict[str, Any]) -> None:
  586. items.extend(new_items)
  587. item_sources.extend([msg] * len(new_items))
  588. for msg in messages:
  589. if not isinstance(msg, dict):
  590. continue
  591. role = msg.get("role")
  592. if role == "tool":
  593. emit(_tool_output_items(msg, wire_ids=wire_ids), msg)
  594. continue
  595. if role not in {"user", "assistant"}:
  596. continue
  597. content = msg.get("content", "")
  598. content_parts = _chat_content_to_responses_parts(content, role=role) # [] unless a list
  599. text_type = _text_type_for(role)
  600. content_text = (
  601. "".join(p["text"] for p in content_parts if p["type"] == text_type)
  602. if isinstance(content, list) else _str_or_empty(content)
  603. )
  604. def wire_content(value: Any) -> Any:
  605. return [{"type": text_type, "text": value}] if typed_text_only and isinstance(value, str) else value
  606. if role == "user":
  607. emit([_role_message_item(role, wire_content(content_parts or content_text))], msg)
  608. continue
  609. reasoning_items = [] if not replay_encrypted_reasoning else _replay_reasoning_items(
  610. msg, seen_item_ids=seen_item_ids, current_issuer_kind=current_issuer_kind,
  611. current_issuer_model=current_issuer_model, native_compaction_eligible=native_compaction_eligible,
  612. )
  613. emit(reasoning_items, msg)
  614. message_items = _replay_message_items(
  615. msg, drop_replay_item_ids=drop_replay_item_ids, current_issuer_kind=current_issuer_kind,
  616. )
  617. emit(message_items, msg)
  618. fallback = None
  619. if not message_items:
  620. fallback = content_parts or (content_text if content_text.strip() else "" if reasoning_items else None)
  621. tool_items = _replay_tool_call_items(msg, start_index=len(items) + (fallback is not None), wire_ids=wire_ids)
  622. # A function_call already follows its reasoning. Inventing an empty assistant
  623. # message between them changes the replayed turn (Muse can emit corrupt finals).
  624. # Keep a follower only for reasoning with no other following item, and make it
  625. # non-empty: strict Responses-compatible providers reject "" with 400.
  626. if fallback is not None and not (fallback == "" and tool_items):
  627. follower = " " if fallback == "" else fallback
  628. emit([_role_message_item("assistant", wire_content(follower), msg.get("phase"))], msg)
  629. emit(tool_items, msg)
  630. # The server renders nothing placed before a compaction item, so pre-checkpoint history is
  631. # dead weight and plaintext asks / merged summaries silently vanish. Keep the newest checkpoint
  632. # first, retain pre-checkpoint USER and SUMMARY messages within a token budget, leave the tail.
  633. # Native server-side compaction: when a replayed checkpoint is present, restructure the wire around it.
  634. # Gated on the CURRENT request's native eligibility, not merely on the presence of a checkpoint: a
  635. # persisted checkpoint outlives the gate, and pruning for a request that carries no
  636. # ``context_management`` deletes history the server never compacted. ``item_sources`` (parallel to
  637. # ``items``) carries the raw chat message each converted item came from. A canonical summary carrier's
  638. # content can be lost or gone stale by the time it becomes a Responses item — a merge-into-tail
  639. # tool-result carrier becomes a typed ``function_call_output`` (no ``content``/``role`` at all), and a
  640. # merge-into-tail assistant carrier can be shadowed by a stale exact ``codex_message_items`` replay from
  641. # before the merge rewrote its content. Pruning reads the source message's own up-to-date,
  642. # provenance-tagged content directly instead of trying to recover it from whatever shape the conversion
  643. # produced (#90976).
  644. if not native_compaction_eligible:
  645. return items
  646. from agent.native_compaction import prune_pre_checkpoint_items
  647. return prune_pre_checkpoint_items(items, item_sources=item_sources)
  648. class ResponsesRouteFlags(NamedTuple):
  649. """Which special Responses-API route an agent is talking to. Single owner of the
  650. codex/xai predicates and the endpoint quirks — every site must call :func:`classify_responses_route`.
  651. Every site that needs these flags (request kwargs build, preflight estimation, silent- reject hints)
  652. must call :func:`classify_responses_route` instead of re-implementing the string comparisons inline —
  653. inline copies drift (backend-identity class: #22548/#70893/#59561/#72468).
  654. """
  655. is_codex_backend: bool
  656. is_xai_responses: bool
  657. endpoint: ResponsesEndpointQuirks
  658. def classify_responses_route(agent: Any) -> ResponsesRouteFlags:
  659. """Classify the agent's Responses route from provider + base URL. Host checks are
  660. exact-host-or-subdomain, never substring (``evil.com/chatgpt.com`` is not ChatGPT)."""
  661. from utils import base_url_hostname
  662. provider = getattr(agent, "provider", None)
  663. base_url = str(getattr(agent, "base_url", "") or "")
  664. hostname = str(getattr(agent, "_base_url_hostname", "") or "").lower() or base_url_hostname(base_url)
  665. lower = str(getattr(agent, "_base_url_lower", "") or base_url).lower()
  666. def _host_is(domain: str) -> bool:
  667. return hostname == domain or hostname.endswith("." + domain)
  668. return ResponsesRouteFlags(
  669. is_codex_backend=provider == "openai-codex" or (_host_is("chatgpt.com") and "/backend-api/codex" in lower),
  670. is_xai_responses=provider in {"xai", "xai-oauth"} or hostname == "api.x.ai",
  671. endpoint=responses_endpoint_quirks(base_url),
  672. )
  673. def _native_responses_replay_items(
  674. agent: Any, messages: list[dict[str, Any]]
  675. ) -> Optional[list[dict[str, Any]]]:
  676. """Build the native-compaction-eligible wire items, or ``None`` when ineligible."""
  677. if getattr(agent, "api_mode", None) != "codex_responses" or not isinstance(messages, list):
  678. return None
  679. route = classify_responses_route(agent)._asdict()
  680. from agent.native_compaction import native_compaction_context_management
  681. from agent.fast_mode import effective_request_overrides
  682. if not native_compaction_context_management(agent, **route):
  683. return None
  684. # The wire model may be rewritten per request (fast mode); provenance must match what the transport stamps.
  685. effective_model = effective_request_overrides(agent).get("model", getattr(agent, "model", None))
  686. try:
  687. items = _chat_messages_to_responses_input(
  688. messages, is_xai_responses=route["is_xai_responses"],
  689. drop_replay_item_ids=not route["endpoint"].replay_item_ids,
  690. replay_encrypted_reasoning=bool(getattr(agent, "_codex_reasoning_replay_enabled", True)),
  691. current_issuer_kind=_classify_responses_issuer(base_url=getattr(agent, "base_url", None), **route),
  692. current_issuer_model=_wire_model_identity(effective_model),
  693. native_compaction_eligible=True,
  694. )
  695. except Exception:
  696. logger.debug(
  697. "native Responses replay conversion failed; using the generic fallback",
  698. exc_info=True,
  699. )
  700. return None
  701. return items
  702. def has_replayable_native_compaction_checkpoint(
  703. agent: Any, messages: list[dict[str, Any]]
  704. ) -> bool:
  705. """Whether the current route would replay a persisted native checkpoint."""
  706. items = _native_responses_replay_items(agent, messages)
  707. if items is None:
  708. return False
  709. from agent.native_compaction import has_compaction_checkpoint
  710. return has_compaction_checkpoint(items)
  711. def estimate_native_responses_preflight_tokens(
  712. agent: Any, messages: list[dict[str, Any]], *, system_prompt: str = "", tools: Optional[list[dict[str, Any]]] = None,
  713. ) -> Optional[int]:
  714. """Estimate tokens for the checkpoint-pruned Responses payload (the full transcript overstates a natively compacted
  715. session and fires local compression needlessly). None when native compaction is not proven eligible or conversion fails.
  716. Automatic preflight previously counted the full durable transcript. On a natively compacted Codex
  717. session that overstates the wire by several times and fires local compression against history the main
  718. request will never send (#96155).
  719. """
  720. items = _native_responses_replay_items(agent, messages)
  721. if items is None:
  722. return None
  723. from agent.model_metadata import estimate_request_tokens_rough
  724. return estimate_request_tokens_rough(items, system_prompt=system_prompt or "", tools=tools)
  725. # --- Input preflight / validation --------------------------------------------
  726. class _PreflightCtx(NamedTuple):
  727. sanitize_text: Callable[[str], str]
  728. sanitize_harmony_tokens: bool
  729. drop_replay_item_ids: bool
  730. seen_ids: set
  731. def _preflight_function_call(item: dict[str, Any], idx: int, ctx: _PreflightCtx) -> dict[str, Any]:
  732. call_id, name = item.get("call_id"), item.get("name")
  733. if not _nonblank(call_id):
  734. raise ValueError(f"Codex Responses input[{idx}] function_call is missing call_id.")
  735. if not _nonblank(name):
  736. raise ValueError(f"Codex Responses input[{idx}] function_call is missing name.")
  737. return {
  738. "type": "function_call", "call_id": call_id.strip(), "name": coerce_tool_name(name, fallback="fn"),
  739. "arguments": ctx.sanitize_text(_coerce_arguments(item.get("arguments", "{}"))),
  740. }
  741. def _preflight_function_call_output(item: dict[str, Any], idx: int, ctx: _PreflightCtx) -> dict[str, Any]:
  742. call_id = item.get("call_id")
  743. if not _nonblank(call_id):
  744. raise ValueError(f"Codex Responses input[{idx}] function_call_output is missing call_id.")
  745. output = item.get("output", "")
  746. if isinstance(output, list):
  747. # Multimodal tool result: keep recognised input_text/input_image parts, drop the rest (4xx otherwise).
  748. cleaned: list[dict[str, Any]] = []
  749. for part in output:
  750. ptype = part.get("type") if isinstance(part, dict) else None
  751. if ptype == "input_text" and _nonempty_str(part.get("text")):
  752. cleaned.append({"type": "input_text", "text": ctx.sanitize_text(part["text"])})
  753. elif ptype == "input_image" and _nonempty_str(part.get("image_url")):
  754. cleaned.append(_input_image_part(part, keep_empty_url=False))
  755. output_value: Any = cleaned or ""
  756. else:
  757. output_value = ctx.sanitize_text(_str_or_empty(output))
  758. return {"type": "function_call_output", "call_id": call_id.strip(), "output": output_value}
  759. def _preflight_encrypted(item: dict[str, Any], idx: int, ctx: _PreflightCtx) -> Optional[dict[str, Any]]:
  760. """``reasoning`` / ``compaction`` items: opaque, issuer-sealed; forward only API-defined fields."""
  761. encrypted = item.get("encrypted_content")
  762. if not _nonempty_str(encrypted):
  763. return None
  764. if item["type"] == "compaction":
  765. return {"type": "compaction", "encrypted_content": encrypted}
  766. # ``id`` is used only for local dedup and NOT forwarded (store=False → server-side 404).
  767. item_id = item.get("id")
  768. if _nonempty_str(item_id):
  769. if item_id in ctx.seen_ids:
  770. return None
  771. ctx.seen_ids.add(item_id)
  772. summary = _as_list(item.get("summary"))
  773. return {
  774. "type": "reasoning", "encrypted_content": encrypted,
  775. "summary": _neutralize_harmony_structure(summary) if ctx.sanitize_harmony_tokens else summary,
  776. }
  777. def _preflight_message(item: dict[str, Any], idx: int, ctx: _PreflightCtx) -> dict[str, Any]:
  778. # Only replayed assistant output (a list-content item carrying id/status) takes the strict path
  779. # below. Phase alone is no replay marker: the converter's plain role items carry it too, and
  780. # preflight must not synthesize a status or reject user image parts for them.
  781. content = item.get("content")
  782. is_replayed_assistant = (
  783. item.get("role") == "assistant" and isinstance(content, list)
  784. and any(key in item for key in ("id", "status"))
  785. )
  786. if not is_replayed_assistant:
  787. return _preflight_role_message(item, idx, ctx)
  788. normalized_content = []
  789. for part_idx, part in enumerate(content):
  790. if not isinstance(part, dict):
  791. raise ValueError(f"Codex Responses input[{idx}] message content[{part_idx}] must be an object.")
  792. part_type = part.get("type")
  793. if part_type not in _OUTPUT_TEXT_TYPES:
  794. raise ValueError(
  795. f"Codex Responses input[{idx}] message content[{part_idx}] has unsupported type {part_type!r}."
  796. )
  797. normalized_content.append({"type": "output_text", "text": ctx.sanitize_text(_str_or_empty(part.get("text", "")))})
  798. if not normalized_content:
  799. raise ValueError(f"Codex Responses input[{idx}] message item must contain at least one text part.")
  800. return _assistant_message_item(item, normalized_content, drop_replay_item_ids=ctx.drop_replay_item_ids)
  801. def _preflight_role_message(item: dict[str, Any], idx: int, ctx: _PreflightCtx) -> dict[str, Any]:
  802. """``user``/``assistant`` role message, typed or untyped; string content or Responses parts."""
  803. role = item.get("role")
  804. if role not in {"user", "assistant"}:
  805. raise ValueError(
  806. f"Codex Responses input[{idx}] has unsupported item shape (type={item.get('type')!r}, role={role!r})."
  807. )
  808. content = item.get("content", "")
  809. if not isinstance(content, list):
  810. return _role_message_item(role, ctx.sanitize_text(_str_or_empty(content)), item.get("phase"))
  811. # Parts are already Responses-shaped; validate and re-type text for the role.
  812. # Unlike history conversion, empty text / empty image urls are kept, not dropped.
  813. text_type = _text_type_for(role)
  814. validated: list[dict[str, Any]] = []
  815. for part_idx, part in enumerate(content):
  816. if isinstance(part, str):
  817. if part:
  818. validated.append({"type": text_type, "text": ctx.sanitize_text(part)})
  819. elif not isinstance(part, dict):
  820. raise ValueError(f"Codex Responses input[{idx}].content[{part_idx}] must be an object or string.")
  821. elif (ptype := _part_type(part)) in _TEXT_PART_TYPES:
  822. text = part.get("text", "")
  823. text = text if isinstance(text, str) else str(text or "")
  824. validated.append({"type": text_type, "text": ctx.sanitize_text(text)})
  825. elif ptype in _IMAGE_PART_TYPES:
  826. validated.append(_input_image_part(part, role, keep_empty_url=True))
  827. else:
  828. raise ValueError(
  829. f"Codex Responses input[{idx}].content[{part_idx}] has unsupported type {part.get('type')!r}."
  830. )
  831. return _role_message_item(role, validated, item.get("phase"))
  832. _PREFLIGHT_ITEM_HANDLERS: dict[str, Callable[..., Optional[dict[str, Any]]]] = {
  833. "function_call": _preflight_function_call, "function_call_output": _preflight_function_call_output,
  834. "reasoning": _preflight_encrypted, "compaction": _preflight_encrypted, "message": _preflight_message,
  835. }
  836. def _preflight_codex_input_items(
  837. raw_items: Any, *, drop_replay_item_ids: bool = False, sanitize_harmony_tokens: bool = False,
  838. ) -> list[dict[str, Any]]:
  839. if not isinstance(raw_items, list):
  840. raise ValueError("Codex Responses input must be a list of input items.")
  841. sanitize_text = _neutralize_harmony_tokens if sanitize_harmony_tokens else (lambda text: text)
  842. ctx = _PreflightCtx(sanitize_text, sanitize_harmony_tokens, drop_replay_item_ids, set())
  843. normalized: list[dict[str, Any]] = []
  844. for idx, item in enumerate(raw_items):
  845. if not isinstance(item, dict):
  846. raise ValueError(f"Codex Responses input[{idx}] must be an object.")
  847. item_type = item.get("type")
  848. handler = _PREFLIGHT_ITEM_HANDLERS.get(item_type) if isinstance(item_type, str) else None
  849. normalized_item = (handler or _preflight_role_message)(item, idx, ctx)
  850. if normalized_item is not None:
  851. normalized.append(normalized_item)
  852. return normalized
  853. def _preflight_tool(tool: Any, idx: int) -> dict[str, Any]:
  854. if not isinstance(tool, dict):
  855. raise ValueError(f"Codex Responses tools[{idx}] must be an object.")
  856. tool_type = tool.get("type")
  857. if tool_type in _RESPONSES_BUILTIN_TOOL_TYPES: # provider-executed built-ins carry no name/parameters
  858. return dict(tool)
  859. if tool_type != "function":
  860. raise ValueError(f"Codex Responses tools[{idx}] has unsupported type {tool.get('type')!r}.")
  861. name, parameters = tool.get("name"), tool.get("parameters")
  862. for ok, what in ((_nonblank(name), "a valid name"), (isinstance(parameters, dict), "valid parameters")):
  863. if not ok:
  864. raise ValueError(f"Codex Responses tools[{idx}] is missing {what}.")
  865. return {
  866. "type": "function", "name": name.strip(), "description": _str_or_empty(tool.get("description", "")),
  867. "strict": bool(tool.get("strict", False)), "parameters": parameters,
  868. }
  869. # Optional scalar request fields, in wire order: (key, accept(value), coerce). Values
  870. # failing ``accept`` are silently dropped.
  871. _PREFLIGHT_OPTIONAL_FIELDS: tuple[tuple[str, Callable[[Any], bool], Optional[Callable[[Any], Any]]], ...] = (
  872. ("reasoning", lambda v: isinstance(v, dict), None),
  873. ("include", lambda v: isinstance(v, list), None),
  874. ("service_tier", _nonblank, str.strip),
  875. # Responses text controls (verbosity, structured-output format).
  876. ("text", lambda v: isinstance(v, dict) and bool(v), None),
  877. ("max_output_tokens", lambda v: isinstance(v, (int, float)) and v > 0, int),
  878. ("timeout", lambda v: isinstance(v, (int, float)) and not isinstance(v, bool) and 0 < v < float("inf"), float),
  879. ("temperature", lambda v: isinstance(v, (int, float)), float),
  880. # Cache routing/retention and tool-dispatch hints pass through as-is.
  881. *(
  882. (key, lambda v: v is not None, None)
  883. for key in ("tool_choice", "parallel_tool_calls", "prompt_cache_key", "prompt_cache_retention")
  884. ),
  885. # Native compaction directive; eligibility is resolved in agent/native_compaction.py.
  886. ("context_management", lambda v: isinstance(v, list) and bool(v), None),
  887. )
  888. _PREFLIGHT_ALLOWED_KEYS = {
  889. "model", "instructions", "input", "tools", "store", "extra_headers", "extra_body",
  890. *(key for key, _, _ in _PREFLIGHT_OPTIONAL_FIELDS),
  891. }
  892. def _optional_dict(api_kwargs: dict[str, Any], key: str) -> Optional[dict[str, Any]]:
  893. value = api_kwargs.get(key)
  894. if value is not None and not isinstance(value, dict):
  895. raise ValueError(f"Codex Responses request '{key}' must be an object.")
  896. return value
  897. def _preflight_codex_api_kwargs(
  898. api_kwargs: Any, *, allow_stream: bool = False, drop_replay_item_ids: bool = False,
  899. sanitize_harmony_tokens: bool = False,
  900. ) -> dict[str, Any]:
  901. if not isinstance(api_kwargs, dict):
  902. raise ValueError("Codex Responses request must be a dict.")
  903. if missing := sorted(key for key in ("model", "instructions", "input") if key not in api_kwargs):
  904. raise ValueError(f"Codex Responses request missing required field(s): {', '.join(missing)}.")
  905. model = api_kwargs.get("model")
  906. if not _nonblank(model):
  907. raise ValueError("Codex Responses request 'model' must be a non-empty string.")
  908. instructions = _str_or_empty(api_kwargs.get("instructions")).strip() or DEFAULT_AGENT_IDENTITY
  909. if sanitize_harmony_tokens:
  910. instructions = _neutralize_harmony_tokens(instructions)
  911. input_items = _preflight_codex_input_items(
  912. api_kwargs.get("input"), drop_replay_item_ids=drop_replay_item_ids, sanitize_harmony_tokens=sanitize_harmony_tokens,
  913. )
  914. normalized: dict[str, Any] = {
  915. "model": model.strip(), "instructions": instructions, "input": input_items, "store": False,
  916. }
  917. tools = api_kwargs.get("tools")
  918. if tools is not None:
  919. if not isinstance(tools, list):
  920. raise ValueError("Codex Responses request 'tools' must be a list when provided.")
  921. normalized_tools = [_preflight_tool(tool, idx) for idx, tool in enumerate(tools)]
  922. normalized["tools"] = _neutralize_harmony_structure(normalized_tools) if sanitize_harmony_tokens else normalized_tools
  923. if api_kwargs.get("store", False) is not False:
  924. raise ValueError("Codex Responses contract requires 'store' to be false.")
  925. for key, accept, coerce in _PREFLIGHT_OPTIONAL_FIELDS:
  926. value = api_kwargs.get(key)
  927. if accept(value):
  928. normalized[key] = coerce(value) if coerce else value
  929. extra_headers = _optional_dict(api_kwargs, "extra_headers") or {}
  930. if not all(_nonblank(key) for key in extra_headers):
  931. raise ValueError("Codex Responses request 'extra_headers' keys must be non-empty strings.")
  932. normalized_headers = {key.strip(): str(value) for key, value in extra_headers.items() if value is not None}
  933. if normalized_headers:
  934. normalized["extra_headers"] = normalized_headers
  935. # extra_body is verbatim: xAI carries ``prompt_cache_key`` as a body-level
  936. # field, and the SDK serializes extra_body without per-field checks.
  937. extra_body = _optional_dict(api_kwargs, "extra_body")
  938. if extra_body:
  939. normalized["extra_body"] = dict(extra_body)
  940. stream = api_kwargs.get("stream")
  941. if not allow_stream and "stream" in api_kwargs:
  942. raise ValueError("Codex Responses stream flag is only allowed in fallback streaming requests.")
  943. if allow_stream and stream is not None:
  944. if stream is not True:
  945. raise ValueError("Codex Responses 'stream' must be true when set.")
  946. normalized["stream"] = True
  947. # Defense-in-depth slash-enum strip for xAI (rejects ``Qwen/Qwen3.5`` enum values);
  948. # gated on the model name because native Codex accepts slashes.
  949. is_xai_model = str(api_kwargs.get("model") or "").lower().startswith(("grok-", "x-ai/grok-"))
  950. if is_xai_model and normalized.get("tools"):
  951. try:
  952. from tools.schema_sanitizer import strip_slash_enum
  953. normalized["tools"], _ = strip_slash_enum(normalized["tools"])
  954. except Exception:
  955. pass # Best-effort — the caller-level sanitization should have handled it
  956. allowed_keys = _PREFLIGHT_ALLOWED_KEYS | ({"stream"} if allow_stream else set())
  957. if unexpected := sorted(key for key in api_kwargs if key not in allowed_keys):
  958. raise ValueError(f"Codex Responses request has unsupported field(s): {', '.join(unexpected)}.")
  959. return normalized
  960. # --- Response extraction helpers ----------------------------------------------
  961. def _text_chunks(parts: Any, types: Optional[set] = None) -> list[str]:
  962. """Non-empty ``.text`` of each part (optionally filtered by ``.type``); [] if not a list."""
  963. selected = [part for part in _as_list(parts) if types is None or getattr(part, "type", None) in types]
  964. return [text for text in (getattr(part, "text", None) for part in selected) if _nonempty_str(text)]
  965. def _extract_responses_message_text(item: Any) -> str:
  966. """Assistant text from a Responses message output item. A ``refusal`` part carries the
  967. model's explanation in ``refusal`` instead of ``text``; it is message text too, otherwise a
  968. refusal-only turn reads as an empty response (sibling of chat_completions ``message.refusal``)."""
  969. chunks = []
  970. for part in _as_list(_field(item, "content")):
  971. ptype = _field(part, "type")
  972. text = _field(part, "refusal") if ptype == "refusal" else (_field(part, "text") if ptype in _OUTPUT_TEXT_TYPES else None)
  973. if _nonempty_str(text):
  974. chunks.append(text)
  975. return "".join(chunks).strip()
  976. def _extract_responses_reasoning_text(item: Any) -> str:
  977. """Compact reasoning text from a Responses reasoning item (summary, else ``text``)."""
  978. chunks = _text_chunks(getattr(item, "summary", None))
  979. text = getattr(item, "text", None)
  980. return "\n".join(chunks).strip() if chunks else (text.strip() if isinstance(text, str) else "")
  981. def _format_responses_error(error_obj: Any, response_status: str) -> str:
  982. """``"<code>: <message>"`` for a ``response.error`` payload (dict or object), else whichever
  983. is present, else ``str(error_obj)``, else a status-based default."""
  984. def field(name: str) -> str:
  985. value = _field(error_obj, name)
  986. return str(value).strip() if isinstance(value, str) or value else ""
  987. code_str, message_str = field("code"), field("message")
  988. if code_str and message_str:
  989. return f"{code_str}: {message_str}"
  990. return message_str or code_str or (str(error_obj) if error_obj else f"Responses API returned status '{response_status}'")
  991. # --- Full response normalization ----------------------------------------------
  992. def _response_tool_call(item: Any, item_type: str, index: int) -> SimpleNamespace:
  993. """Build a chat-style tool_call from a ``function_call``/``custom_tool_call`` item."""
  994. fn_name = getattr(item, "name", "") or ""
  995. arguments = getattr(item, "arguments" if item_type == "function_call" else "input", "{}")
  996. if not isinstance(arguments, str):
  997. arguments = json.dumps(arguments, ensure_ascii=False)
  998. raw_item_id = getattr(item, "id", None)
  999. call_id = _resolve_call_id(getattr(item, "call_id", None), raw_item_id, fn_name, arguments, index, canonicalize_fc=False)
  1000. fc_id = _derive_responses_function_call_id(call_id, raw_item_id if isinstance(raw_item_id, str) else None)
  1001. return SimpleNamespace(
  1002. id=call_id, call_id=call_id, response_item_id=fc_id, type="function",
  1003. function=SimpleNamespace(name=fn_name, arguments=arguments),
  1004. )
  1005. def _capture_encrypted_item(
  1006. item: Any, item_type: str, issuer_kind: Optional[str], issuer_model: Optional[str] = None,
  1007. ) -> Optional[dict[str, Any]]:
  1008. """``{type, encrypted_content[, _issuer_kind, _issuer_model]}`` for replay, or None without a blob. Reasoning
  1009. items also carry ``id`` + ``summary`` (required by the API on replay); transient ``rs_tmp_`` skip."""
  1010. encrypted = getattr(item, "encrypted_content", None)
  1011. if not _nonempty_str(encrypted):
  1012. return None
  1013. raw_item: dict[str, Any] = {"type": item_type, "encrypted_content": encrypted}
  1014. if issuer_kind:
  1015. raw_item["_issuer_kind"] = issuer_kind
  1016. if issuer_model:
  1017. raw_item["_issuer_model"] = issuer_model
  1018. if item_type != "reasoning":
  1019. return raw_item
  1020. item_id = getattr(item, "id", None)
  1021. if isinstance(item_id, str) and item_id.startswith("rs_tmp_"):
  1022. logger.debug("Skipping transient Codex reasoning item during normalization: %s", item_id)
  1023. return None
  1024. if _nonempty_str(item_id):
  1025. raw_item["id"] = item_id
  1026. summary = getattr(item, "summary", None)
  1027. if isinstance(summary, list):
  1028. texts = (getattr(part, "text", None) for part in summary)
  1029. raw_item["summary"] = [{"type": "summary_text", "text": text} for text in texts if isinstance(text, str)]
  1030. return raw_item
  1031. class _OutputScan:
  1032. """Accumulated view of one Responses ``output`` list (phase 1 of normalization)."""
  1033. def __init__(self, response_status: Optional[str]) -> None:
  1034. self.content_parts, self.reasoning_parts, self.tool_calls = [], [], []
  1035. self.reasoning_items_raw, self.message_items_raw = [], []
  1036. self.has_incomplete_items = response_status in _INCOMPLETE_STATUSES
  1037. self.saw_streaming_or_item_incomplete = response_status in {"queued", "in_progress"}
  1038. self.saw_commentary_phase = self.saw_final_answer_phase = self.saw_reasoning_item = False
  1039. def scan(self, output: list[Any], issuer_kind: Optional[str], issuer_model: Optional[str] = None) -> None:
  1040. for item in output:
  1041. item_type = getattr(item, "type", None)
  1042. item_status = _lower_or_none(getattr(item, "status", None))
  1043. if item_status in _INCOMPLETE_STATUSES and item_type not in _SERVER_SIDE_TOOL_CALL_TYPES:
  1044. self.has_incomplete_items = True
  1045. self.saw_streaming_or_item_incomplete = True
  1046. if item_type == "message":
  1047. self._message(item, item_status)
  1048. elif item_type in {"reasoning", "compaction"}:
  1049. if item_type == "reasoning":
  1050. self.saw_reasoning_item = True
  1051. reasoning_text = _extract_responses_reasoning_text(item)
  1052. if reasoning_text:
  1053. self.reasoning_parts.append(reasoning_text)
  1054. # Compaction checkpoints ride the codex_reasoning_items sidecar (persistence,
  1055. # replay, cross-issuer guard and kill switch for free).
  1056. raw_item = _capture_encrypted_item(item, item_type, issuer_kind, issuer_model)
  1057. if raw_item is not None:
  1058. self.reasoning_items_raw.append(raw_item)
  1059. if item_type == "compaction":
  1060. logger.info(
  1061. "Native Responses compaction item captured (%d chars encrypted).", len(raw_item["encrypted_content"]),
  1062. )
  1063. elif item_type == "custom_tool_call" or (item_type == "function_call" and item_status not in _INCOMPLETE_STATUSES):
  1064. self.tool_calls.append(_response_tool_call(item, item_type, len(self.tool_calls)))
  1065. def _message(self, item: Any, item_status: Optional[str]) -> None:
  1066. normalized_phase = _lower_or_none(getattr(item, "phase", None))
  1067. is_commentary_phase = normalized_phase in {"commentary", "analysis"}
  1068. self.saw_commentary_phase = self.saw_commentary_phase or is_commentary_phase
  1069. self.saw_final_answer_phase = self.saw_final_answer_phase or normalized_phase in {"final_answer", "final"}
  1070. message_text = _extract_responses_message_text(item)
  1071. if not message_text:
  1072. return
  1073. # commentary/analysis text is mid-turn narration, never the final answer: route it
  1074. # to the reasoning channel; the exact item is still preserved for replay/cache.
  1075. (self.reasoning_parts if is_commentary_phase else self.content_parts).append(message_text)
  1076. item_id = getattr(item, "id", None)
  1077. self.message_items_raw.append(_message_item(
  1078. [{"type": "output_text", "text": message_text}], status=_normalize_responses_message_status(item_status),
  1079. item_id=item_id if isinstance(item_id, str) else None, phase=normalized_phase,
  1080. ))
  1081. def _untrusted_completed_issuers() -> frozenset:
  1082. """Issuer kinds whose reasoning-only ``completed`` status is not final (once per normalized response)."""
  1083. from providers import list_providers
  1084. declared = (p.responses_issuer_kind for p in list_providers()
  1085. if p.responses_issuer_kind and not p.responses_trusts_completed_status)
  1086. return frozenset({"codex_backend", "xai_responses", *declared})
  1087. def _normalize_codex_response(
  1088. response: Any, *, issuer_kind: Optional[str] = None, issuer_model: Optional[str] = None,
  1089. recover_leaked_tool_call: bool = True,
  1090. ) -> tuple[Any, str]:
  1091. """Normalize a Responses API object to ``(assistant_message, finish_reason)``.
  1092. ``issuer_kind`` / ``issuer_model`` are stamped onto captured reasoning items for provenance replay drops.
  1093. ``recover_leaked_tool_call=False`` is for callers with no continuation (aux): tool-call-shaped text is
  1094. then kept as ordinary content and judged by the same phase/completion gates as any other answer."""
  1095. response_status = _lower_or_none(getattr(response, "status", None))
  1096. incomplete_reason = str(_field(getattr(response, "incomplete_details", None), "reason", "") or "").strip().lower()
  1097. response_incomplete_content_filter = response_status == "incomplete" and incomplete_reason == "content_filter"
  1098. output = getattr(response, "output", None)
  1099. if not isinstance(output, list) or not output:
  1100. # Codex can deliver the whole answer via stream events with an empty output.
  1101. out_text = getattr(response, "output_text", None)
  1102. out_text = out_text.strip() if isinstance(out_text, str) else ""
  1103. if out_text:
  1104. msg = "Codex response has empty output but output_text is present (%d chars); synthesizing output item."
  1105. logger.debug(msg, len(out_text))
  1106. content: list[Any] = [SimpleNamespace(type="output_text", text=out_text)]
  1107. elif response_incomplete_content_filter:
  1108. # Provider safety block, not a partial answer: finish content_filter, not incomplete.
  1109. content = []
  1110. else:
  1111. raise RuntimeError("Responses API returned no output items")
  1112. response.output = output = [
  1113. SimpleNamespace(type="message", role="assistant", status="completed", content=content),
  1114. ]
  1115. if response_status in {"failed", "cancelled"}:
  1116. raise RuntimeError(_format_responses_error(getattr(response, "error", None), response_status))
  1117. scan = _OutputScan(response_status)
  1118. scan.scan(output, issuer_kind, issuer_model)
  1119. tool_calls, reasoning_parts = scan.tool_calls, scan.reasoning_parts
  1120. final_text = "\n".join(scan.content_parts).strip()
  1121. if not final_text and (scan.saw_final_answer_phase or not scan.saw_commentary_phase):
  1122. out_text = getattr(response, "output_text", "")
  1123. final_text = out_text.strip() if isinstance(out_text, str) else final_text
  1124. # Tool-call leak recovery: gpt-5.x sometimes emits the intended ``function_call`` as plain Harmony text
  1125. # (``to=functions.foo {json}``) or Codex-CLI shell JSON (``{"cmd": ...}``). Treat as incomplete so the
  1126. # continuation re-elicits a real call; clear the garbage.
  1127. leaked_tool_call_text = bool(
  1128. recover_leaked_tool_call and final_text and not tool_calls and _leaked_tool_call_text(final_text)
  1129. )
  1130. if leaked_tool_call_text:
  1131. logger.warning(
  1132. "Codex response contains leaked tool-call text in assistant content (no structured function_call "
  1133. "items). Treating as incomplete so the continuation path can re-elicit a proper tool call. "
  1134. "Leaked snippet: %r", final_text[:300],
  1135. )
  1136. final_text = ""
  1137. # xAI grok-4.x sometimes puts the final answer inside the reasoning item after a ``<response>`` delimiter; without
  1138. # salvage the reasoning-only rule marks the turn incomplete and every continuation is byte-identical. Promote the tail.
  1139. if issuer_kind == "xai_responses" and not final_text and not tool_calls and reasoning_parts:
  1140. joined_reasoning = "\n\n".join(reasoning_parts)
  1141. marker = joined_reasoning.rfind("<response>")
  1142. salvaged = joined_reasoning[marker + len("<response>"):].split("</response>", 1)[0].strip() if marker != -1 else ""
  1143. if salvaged:
  1144. logger.warning(
  1145. "xAI response delivered its final answer inside the reasoning channel "
  1146. "(<response> delimiter); promoting %d chars to assistant content.", len(salvaged),
  1147. )
  1148. final_text = salvaged
  1149. reasoning_prefix = joined_reasoning[:marker].strip()
  1150. reasoning_parts = [reasoning_prefix] if reasoning_prefix else []
  1151. assistant_message = SimpleNamespace(
  1152. content=final_text, tool_calls=tool_calls,
  1153. reasoning="\n\n".join(reasoning_parts).strip() if reasoning_parts else None,
  1154. reasoning_content=None, reasoning_details=None,
  1155. codex_reasoning_items=scan.reasoning_items_raw or None,
  1156. # Leaked text must not be replayed as a completed assistant message on the continuation.
  1157. codex_message_items=None if leaked_tool_call_text else (scan.message_items_raw or None),
  1158. )
  1159. # Reasoning-only: for Codex/xAI (and endpoints declaring ``responses_trusts_completed_status=False``),
  1160. # status=completed means "still thinking" → incomplete so the continuation retries. Other backends trust
  1161. # response.status — forcing incomplete there stalls for minutes on a final state.
  1162. reasoning_only = (scan.reasoning_items_raw or reasoning_parts or scan.saw_reasoning_item) and not final_text
  1163. trusted_final = (
  1164. response_status == "completed" and issuer_kind not in _untrusted_completed_issuers()
  1165. )
  1166. if tool_calls:
  1167. finish_reason = "tool_calls"
  1168. elif response_incomplete_content_filter:
  1169. finish_reason = "content_filter"
  1170. elif (
  1171. leaked_tool_call_text
  1172. or scan.saw_streaming_or_item_incomplete
  1173. or ((scan.has_incomplete_items or scan.saw_commentary_phase) and not scan.saw_final_answer_phase)
  1174. or (reasoning_only and not trusted_final)
  1175. ):
  1176. finish_reason = "incomplete"
  1177. else:
  1178. finish_reason = "stop"
  1179. return assistant_message, finish_reason