message_sanitization.py 51 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026
  1. """Message and tool-payload sanitization helpers (pure; documented in-place mutation).
  2. Walk OpenAI-format message lists and structured payloads, repairing or stripping
  3. characters that would crash ``json.dumps`` in the OpenAI SDK or be rejected upstream.
  4. ``run_agent`` re-exports them for old imports.
  5. """
  6. from __future__ import annotations
  7. import hashlib
  8. import json
  9. import logging
  10. import re
  11. from functools import partial
  12. from typing import Any, Callable, Iterable, NamedTuple
  13. from agent.agent_runtime_helpers_placeholders import _INTERRUPTED_PLACEHOLDER, hidden_interrupt_placeholder_row
  14. from agent.message_metadata import DB_ROW_SNAPSHOT
  15. from agent.vision_message_prep import _provider_model_key
  16. logger = logging.getLogger(__name__)
  17. # Lone surrogates are invalid UTF-8 and crash json.dumps in the OpenAI SDK; also used for
  18. # CLI paste scrubbing.
  19. _SURROGATE_RE = re.compile(r'[\ud800-\udfff]')
  20. # Keys handled explicitly by _sanitize_messages; every OTHER key is swept generically.
  21. # The durable snapshot is an immutable compare-and-swap version, not message payload.
  22. _MESSAGE_CORE_KEYS = frozenset({"content", "name", "tool_calls", "role", DB_ROW_SNAPSHOT})
  23. def _sanitize_surrogates(text: str) -> str:
  24. """Replace lone surrogate code points with U+FFFD; no-op when none present."""
  25. # ``str.isascii`` is an O(1) flag check; surrogates are never ASCII, so the
  26. # regex scan only runs for the (rare) non-ASCII leaf.
  27. if text.isascii():
  28. return text
  29. return _SURROGATE_RE.sub('\ufffd', text)
  30. # OpenAI / Anthropic / Responses all bound ``function.name`` to this; one poisoned stored name
  31. # (``multi_tool_use.parallel``, a shell command a weak model put in ``name``) 400s every later
  32. # request on a strict endpoint (#51944).
  33. _VALID_TOOL_NAME_RE = re.compile(r"[A-Za-z0-9_-]{1,64}")
  34. def coerce_tool_name(name: Any, fallback: str = "invalid_tool_call") -> str:
  35. """Coerce a *replayed* tool/function name to ``^[A-Za-z0-9_-]{1,64}$``. Valid names are returned
  36. as-is (identity — prompt-cache safe); invalid runs collapse to ``_`` and the result is cut at 64;
  37. empty/all-invalid → ``fallback``. Deterministic, so the same stored name always renders the same
  38. bytes. Never apply to live tool definitions (schema names must match the dispatch registry)."""
  39. if not isinstance(name, str):
  40. return fallback
  41. if _VALID_TOOL_NAME_RE.fullmatch(name):
  42. return name
  43. coerced = re.sub(r"_+", "_", re.sub(r"[^A-Za-z0-9_-]", "_", name.strip())).strip("_")
  44. return coerced[:64] or fallback
  45. def _strip_non_ascii(text: str) -> str:
  46. """Drop non-ASCII characters — last resort for ASCII-only system encodings (LANG=C)."""
  47. if text.isascii():
  48. return text
  49. return text.encode('ascii', errors='ignore').decode('ascii')
  50. def _fix_str_field(container: Any, key: Any, fix: Callable[[str], str]) -> bool:
  51. """Apply ``fix`` to ``container[key]`` if it is a str; True if it changed."""
  52. value = container.get(key) if isinstance(container, dict) else container[key]
  53. fixed = fix(value) if isinstance(value, str) else value
  54. if fixed == value:
  55. return False
  56. container[key] = fixed
  57. return True
  58. def _sanitize_structure(payload: Any, fix: Callable[[str], str]) -> bool:
  59. """Apply ``fix`` to every str inside nested dict/list ``payload`` in-place."""
  60. found = False
  61. stack = [payload]
  62. while stack:
  63. node = stack.pop()
  64. items = node.items() if isinstance(node, dict) else enumerate(node) if isinstance(node, list) else ()
  65. for key, value in list(items):
  66. if isinstance(value, str):
  67. found |= _fix_str_field(node, key, fix)
  68. elif isinstance(value, (dict, list)):
  69. stack.append(value)
  70. return found
  71. def _sanitize_messages(messages: list, fix: Callable[[str], str], *, deep: bool) -> bool:
  72. """Apply ``fix`` to the string fields of every message dict in-place (content / part text,
  73. name, tool_call arguments, non-core top-level str fields). ``deep=True`` adds tool_call ids,
  74. function names, and NESTED non-core fields (``reasoning_details`` from byte-level models)."""
  75. from agent.context_compressor import _DB_PERSISTED_MARKER
  76. found = False
  77. for msg in messages:
  78. if not isinstance(msg, dict):
  79. continue
  80. msg_found = False
  81. content = msg.get("content")
  82. parts = [(p, "text") for p in content if isinstance(p, dict)] if isinstance(content, list) else None
  83. fields = parts if parts is not None else [(msg, "content")]
  84. fields.append((msg, "name"))
  85. tool_calls = msg.get("tool_calls")
  86. for tc in tool_calls if isinstance(tool_calls, list) else ():
  87. fn = tc.get("function") if isinstance(tc, dict) else None
  88. fields += [(tc, "id")] if deep and isinstance(tc, dict) else []
  89. fields += ([(fn, "name")] if deep else []) + [(fn, "arguments")] if isinstance(fn, dict) else []
  90. for container, key in fields:
  91. msg_found |= _fix_str_field(container, key, fix)
  92. for key, value in [kv for kv in msg.items() if kv[0] not in _MESSAGE_CORE_KEYS]:
  93. if isinstance(value, str):
  94. msg_found |= _fix_str_field(msg, key, fix)
  95. elif deep and isinstance(value, (dict, list)):
  96. msg_found |= _sanitize_structure(value, fix)
  97. if msg_found:
  98. # In-place repair of a live dict stales its persisted row; pop the marker so the
  99. # flush rewrites it (no-op on api_messages wire copies).
  100. msg.pop(_DB_PERSISTED_MARKER, None)
  101. found = True
  102. return found
  103. # In-place sanitizers; each returns True when anything changed. Surrogate repair is deep
  104. # (tool_call ids, nested reasoning_details); the ASCII-only-locale strip is shallow.
  105. _sanitize_structure_surrogates = partial(_sanitize_structure, fix=_sanitize_surrogates)
  106. _sanitize_messages_surrogates = partial(_sanitize_messages, fix=_sanitize_surrogates, deep=True)
  107. _sanitize_structure_non_ascii = partial(_sanitize_structure, fix=_strip_non_ascii)
  108. _sanitize_messages_non_ascii = partial(_sanitize_messages, fix=_strip_non_ascii, deep=False)
  109. _sanitize_tools_non_ascii = _sanitize_structure_non_ascii
  110. def sanitize_outbound_kwargs(agent: Any, api_kwargs: dict) -> None:
  111. """Outbound-request chokepoint for every built kwargs dict (main loop and iteration summary).
  112. Tool descriptions, extra_body and kwargs strings can carry invalid code points that
  113. providers reject with a non-retryable 400 (#50959); one in-place walk makes the whole
  114. payload json.dumps()-safe. The ASCII strip is opt-in via the recovery flag set after an
  115. ASCII-codec rejection.
  116. """
  117. _sanitize_structure_surrogates(api_kwargs)
  118. if agent._force_ascii_payload:
  119. # ``tools`` is built from ``agent.tools`` per attempt and usually aliases it; detach
  120. # before the in-place strip so the retry never rewrites the canonical tool schemas.
  121. # A structural clone suffices: ``_sanitize_structure`` only rebinds str leaves
  122. # inside dict/list containers.
  123. if api_kwargs.get("tools") is not None and api_kwargs["tools"] is getattr(agent, "tools", None):
  124. # Lazy: conversation_loop imports this module (cycle).
  125. from agent.conversation_loop import _clone_message_for_send
  126. api_kwargs["tools"] = _clone_message_for_send(api_kwargs["tools"])
  127. _sanitize_structure_non_ascii(api_kwargs)
  128. def _escape_invalid_chars_in_json_strings(raw: str) -> str:
  129. """Escape literal control chars (0x00-0x1F) inside JSON string values as ``\\uXXXX``
  130. (for llama.cpp-style output mixing control chars with other malformations)."""
  131. out: list[str] = []
  132. in_string = False
  133. i = 0
  134. while i < len(raw):
  135. ch = raw[i]
  136. if in_string and ch == "\\" and i + 1 < len(raw):
  137. out.append(raw[i:i + 2])
  138. i += 2
  139. continue
  140. if ch == '"':
  141. in_string = not in_string
  142. out.append(f"\\u{ord(ch):04x}" if in_string and ord(ch) < 0x20 else ch)
  143. i += 1
  144. return "".join(out)
  145. # When a repair rewrites arguments to "{}", the WARNING log is the last surviving copy of
  146. # content that can hold real user data (a truncated write_file), so bound it generously.
  147. _FULL_ARGS_LOG_BOUND = 100_000
  148. def _loads_ok(text: str) -> bool:
  149. try:
  150. json.loads(text)
  151. return True
  152. except json.JSONDecodeError:
  153. return False
  154. _JSON_CLOSERS = {"{": "}", "[": "]"}
  155. def _rebalance_json_closers(raw: str) -> str | None:
  156. """Close a JSON prefix's open braces/brackets in stack order, ignoring delimiters
  157. inside string values (``{"code": "}"}`` keeps one open brace, not a balanced
  158. document). A closer that does not match the stack top but does match a deeper opener
  159. gets the missing inner closers inserted BEFORE it: ``{"a": [{"b": 1}}`` → the model
  160. dropped the ``]`` and let the neighbouring ``}`` close in its place, so the counts
  161. balance and nothing can be appended. ``None`` when the text ends inside an
  162. unterminated string — that content is unrecoverable and must not be guessed.
  163. """
  164. out: list[str] = []
  165. stack: list[str] = []
  166. in_string = False
  167. i, n = 0, len(raw)
  168. while i < n:
  169. ch = raw[i]
  170. if in_string:
  171. if ch == "\\":
  172. out.append(raw[i:i + 2])
  173. i += 2
  174. continue
  175. if ch == '"':
  176. in_string = False
  177. elif ch == '"':
  178. in_string = True
  179. elif ch in _JSON_CLOSERS:
  180. stack.append(ch)
  181. elif ch in "}]" and ch in (_JSON_CLOSERS[o] for o in stack):
  182. while _JSON_CLOSERS[stack[-1]] != ch:
  183. out.append(_JSON_CLOSERS[stack.pop()])
  184. stack.pop()
  185. out.append(ch)
  186. i += 1
  187. if in_string:
  188. return None
  189. return "".join(out) + "".join(_JSON_CLOSERS[ch] for ch in reversed(stack))
  190. def _repair_tool_call_arguments(raw_args: str, tool_name: str = "?") -> str:
  191. """Repair malformed tool_call argument JSON (truncation, trailing commas, Python ``None``,
  192. control chars); ``"{}"`` if unrepairable so the request succeeds. Repairs log at WARNING."""
  193. raw_stripped = raw_args.strip() if isinstance(raw_args, str) else ""
  194. if not raw_stripped:
  195. logger.warning("Sanitized empty tool_call arguments for %s", tool_name)
  196. return "{}"
  197. if raw_stripped == "None":
  198. logger.warning("Sanitized Python-None tool_call arguments for %s", tool_name)
  199. return "{}"
  200. # Pass 0: strict=False accepts literal control chars inside strings (the most common
  201. # local-model case) and re-serialises to wire-valid JSON.
  202. try:
  203. reserialised = json.dumps(json.loads(raw_stripped, strict=False), separators=(",", ":"))
  204. if reserialised != raw_stripped:
  205. logger.warning("Repaired unescaped control chars in tool_call arguments for %s", tool_name)
  206. return reserialised
  207. except (json.JSONDecodeError, TypeError, ValueError):
  208. pass
  209. # Passes 2-4: strip trailing commas, close unclosed structures, trim excess closers
  210. # (bounded). Bracket counting is string-aware: delimiters inside string values
  211. # ({"code": "}"}) are not structure, and the closers land in stack order — a truncated
  212. # {"items": [{"n": 1}, {"n": 2 needs "}]}" appended, and a misnested
  213. # {"a": [{"b": 1}, {"c": 2}} needs "]" inserted before the misplaced "}".
  214. fixed = re.sub(r",\s*([}\]])", r"\1", raw_stripped)
  215. fixed = _rebalance_json_closers(fixed) or fixed
  216. for _ in range(50):
  217. if _loads_ok(fixed) or not (
  218. (fixed.endswith('}') and fixed.count('}') > fixed.count('{'))
  219. or (fixed.endswith(']') and fixed.count(']') > fixed.count('['))
  220. ):
  221. break
  222. fixed = fixed[:-1]
  223. if _loads_ok(fixed):
  224. logger.warning("Repaired malformed tool_call arguments for %s: %s → %s", tool_name, raw_stripped[:80], fixed[:80])
  225. return fixed
  226. # Pass 5: escape control chars inside strings (strict=False alone fails when other
  227. # malformations are present too), then retry.
  228. escaped = _escape_invalid_chars_in_json_strings(fixed)
  229. if escaped != fixed and _loads_ok(escaped):
  230. logger.warning(
  231. "Repaired control-char-laced tool_call arguments for %s: %s → %s", tool_name, raw_stripped[:80], escaped[:80],
  232. )
  233. return escaped
  234. logger.warning(
  235. "Unrepairable tool_call arguments for %s — replaced with empty object (was: %s)",
  236. tool_name, raw_stripped[:_FULL_ARGS_LOG_BOUND],
  237. )
  238. return "{}"
  239. def close_interrupted_tool_sequence(messages: list, final_response: Any = None, *, stopped: bool = False) -> bool:
  240. """Append a synthetic assistant turn when an interrupted tail is a tool result: a transcript
  241. ending on a raw ``tool`` message makes the next user message land as ``tool → user``, an
  242. alternation violation strict providers (Gemini, Claude) answer by hallucinating a
  243. continuation. Mutates in place; True if a closing turn was appended.
  244. Only the placeholder closes silently: with no real text (or just the bare interrupt
  245. placeholder) the row is hidden from the user — ``api_content`` carries the LLM-visible
  246. text (substituted at API-build time by ``substitute_api_content``), ``content=""`` +
  247. ``display_kind="hidden"`` keep it out of rendered transcripts, matching the
  248. ``_INTERRUPTED_PLACEHOLDER`` shape in ``turn_api_call.py``. A caller-supplied banner
  249. (truncation notices, partial-delivery text) stays visible: it is the turn's only
  250. user-facing explanation.
  251. ``stopped`` (an interrupted turn: a user stop or any other interrupt, not a truncation or
  252. overflow exit) puts the stopped mark on the closing row, as ``turn_api_call.py`` does on every
  253. interrupted partial reply: it is the turn's last stored row, so a reopened transcript still says
  254. the turn was stopped."""
  255. last = messages[-1] if messages else None
  256. if not isinstance(last, dict) or last.get("role") != "tool":
  257. return False
  258. text = final_response if isinstance(final_response, str) else ""
  259. from agent.message_metadata import append_message
  260. stripped = text.strip()
  261. if not stripped or stripped == _INTERRUPTED_PLACEHOLDER:
  262. row = hidden_interrupt_placeholder_row()
  263. else:
  264. row = {"role": "assistant", "content": stripped}
  265. if stopped:
  266. row["display_metadata"] = {"interrupted": True}
  267. append_message(messages, row)
  268. return True
  269. # finish_reason wire normalization. Some OpenAI-compatible gateways fronting
  270. # Gemini backends emit the native uppercase reasons (STOP, MAX_TOKENS); every
  271. # downstream comparison uses the lowercase OpenAI literals, so an uppercase
  272. # reason silently skips stop handling and length recovery. Single owner —
  273. # call at wire intake (transport normalize_response, stream chunk capture),
  274. # never re-fold at comparison sites.
  275. _FINISH_REASON_ALIASES = {
  276. "max_tokens": "length", # Gemini-native / Anthropic-style cap reason
  277. "end": "stop", # some gateways' clean-completion spelling
  278. "function_call": "tool_calls", # OpenAI legacy pre-tools spelling
  279. }
  280. def normalize_finish_reason(raw: Any) -> Any:
  281. """Fold a wire ``finish_reason`` to the lowercase OpenAI contract value.
  282. Non-string and empty values pass through unchanged (callers keep their
  283. ``or "stop"`` defaults and the Poolside int-reason path); contract values
  284. are returned byte-identical.
  285. """
  286. if not isinstance(raw, str) or not raw:
  287. return raw
  288. lowered = raw.lower()
  289. return _FINISH_REASON_ALIASES.get(lowered, lowered)
  290. def serialized_messages_bytes(messages: list) -> int:
  291. """Exact serialized byte size of ``messages`` (HTTP 413 is a BYTE-size error the token
  292. estimator, pricing images flat, cannot score). Non-serializable values fall back to
  293. ``str()`` so a malformed message can never crash recovery."""
  294. if not isinstance(messages, list) or not messages:
  295. return 0
  296. try:
  297. return len(json.dumps(messages, ensure_ascii=False, separators=(",", ":"), default=str).encode("utf-8"))
  298. except (TypeError, ValueError):
  299. return sum(len(str(m)) for m in messages)
  300. _IMAGE_PART_TYPES = {"image_url", "image", "input_image"}
  301. def _strip_images_from_messages(messages: list) -> bool:
  302. """Remove image content parts from all messages in-place (server rejected images).
  303. ``tool`` / ``tool_calls`` messages left empty get a placeholder, NOT deleted (deleting
  304. orphans the paired ``tool_call_id`` → HTTP 400); other now-empty messages are dropped.
  305. Rewritten messages lose their ``api_content`` sidecar (it carries the removed images):
  306. a caller rewriting a persisted row must not leave bytes that replay them next turn. The
  307. current callers pass per-call clones, where this is a no-op.
  308. """
  309. from agent.context_compressor import _DB_PERSISTED_MARKER
  310. from agent.turn_context import drop_stale_api_content
  311. found = False
  312. to_delete = []
  313. for i, msg in enumerate(messages):
  314. content = msg.get("content") if isinstance(msg, dict) else None
  315. if not isinstance(content, list):
  316. continue
  317. new_parts = [p for p in content if not (isinstance(p, dict) and p.get("type") in _IMAGE_PART_TYPES)]
  318. if len(new_parts) < len(content):
  319. found = True
  320. if new_parts:
  321. msg["content"] = new_parts
  322. # Rewriting a stamped live dict stales its persisted row; pop the marker.
  323. msg.pop(_DB_PERSISTED_MARKER, None)
  324. elif msg.get("role") == "tool" or msg.get("tool_calls"):
  325. msg["content"] = "[image content removed — server does not support images]"
  326. msg.pop(_DB_PERSISTED_MARKER, None)
  327. else:
  328. to_delete.append(i)
  329. drop_stale_api_content(msg)
  330. for i in reversed(to_delete):
  331. del messages[i]
  332. return found
  333. # Provider error bodies (lowercased substring match) meaning "image/multimodal input
  334. # unsupported" — the loop then strips images and retries text-only instead of cascading
  335. # into compression / context-too-large recovery or wedging on retries.
  336. _IMAGE_REJECTION_PHRASES = (
  337. "only 'text' content type is supported", "only text content type is supported",
  338. "image_url is not supported", "image content is not supported",
  339. "multimodal is not supported", "multimodal content is not supported", "multimodal input is not supported",
  340. "vision is not supported", "vision input is not supported",
  341. "does not support images", "does not support image input", "does not support multimodal",
  342. "does not support vision", "model does not support image",
  343. # DashScope-style gateways reject non-text blocks with this generic body.
  344. # Some OpenAI-compatible endpoints (e.g. (issue #57948)
  345. "unexpected item type in content",
  346. # ChatGPT-account Codex backend rejects data:image URLs in input_image; keyed on the
  347. # field-path apostrophe so other URL errors don't false-trip.
  348. "image_url'. expected",
  349. # DeepSeek's text-only request-body variant error.
  350. "unknown variant `image_url`, expected `text`", "unknown variant image_url, expected text",
  351. # OpenRouter HTTP 404 when no upstream endpoint accepts image input (passes the 4xx
  352. # gate; without this the gateway queue wedges behind the stuck turn).
  353. # Without this phrase the agent never strips the images, the retry loop re-sends the same rejected
  354. # request until exhaustion, and the gateway leaves every subsequent message queued behind the stuck turn
  355. # — the P1 in issue #21160.
  356. "no endpoints found that support image input",
  357. # vLLM and other text-only OpenAI-compatible hosts answer imaged history with HTTP 400
  358. # "<model-id> is not a multimodal model"; unmatched, every retry re-sends the image and fails.
  359. "is not a multimodal model",
  360. )
  361. # Provider error bodies meaning "this particular image payload is bad" — the model CAN see, it
  362. # just could not decode what it was sent. Disjoint from ``_IMAGE_REJECTION_PHRASES``: the turn
  363. # recovers the same way (strip and retry) but must NOT remember the model as image-rejecting,
  364. # or the next request with a good image would be needlessly stripped for the rest of the session.
  365. _IMAGE_CORRUPT_PHRASES = (
  366. # ChatGPT-account Codex backend's wording for corrupt/unsupported native image payloads.
  367. "image data you provided does not represent a valid image",
  368. # Kimi/Moonshot et al. reject truncated/corrupt image bytes baked into history.
  369. # Kimi / Moonshot / other OpenAI-compatible Chinese providers reject truncated or corrupt image bytes
  370. # with HTTP 400 "Invalid request: prepare image failed ... failed to decode image: invalid or
  371. # unsupported image format". Like the Codex case above, the bad bytes are baked into immutable
  372. # conversation history and re-sent on every retry, wedging the session. Strip the images so the turn
  373. # recovers instead of exhausting retries. (issue #76884; complements the proactive full-decode
  374. # validation in tools/vision_tools._normalize_to_supported_image)
  375. "failed to decode image",
  376. )
  377. def strip_images_for_rejecting_model(agent: Any, api_messages: Any) -> bool:
  378. """Send-path image strip for a model that rejected image content (see turn_recovery).
  379. Runs on the per-call ``api_messages`` copy in Hermes's own message format, BEFORE the
  380. provider-specific conversion: the part types this stripper knows are that format's, and a
  381. converted payload (Bedrock Converse ``{"image": ...}`` blocks carry no ``type``) would slip
  382. past it. History is never touched. Keyed on each rejecting (provider, model), so a model
  383. that accepts images gets them again.
  384. """
  385. if _provider_model_key(agent) not in agent._image_rejecting_models:
  386. return False
  387. return isinstance(api_messages, list) and _strip_images_from_messages(api_messages)
  388. def _messages_carry_images(messages: Any) -> bool:
  389. """True when any message holds an image part in Hermes's own message format."""
  390. return isinstance(messages, list) and any(
  391. isinstance(m, dict) and isinstance(m.get("content"), list)
  392. and any(isinstance(p, dict) and p.get("type") in _IMAGE_PART_TYPES for p in m["content"])
  393. for m in messages
  394. )
  395. def _looks_like_image_content_rejection(error_body: str) -> bool:
  396. """Return True when a provider error says image/multimodal input is unsupported."""
  397. body = str(error_body or "").lower()
  398. return any(phrase in body for phrase in _IMAGE_REJECTION_PHRASES)
  399. def _looks_like_corrupt_image_rejection(error_body: str) -> bool:
  400. """Return True when the rejection is about a bad image payload, not the model's capability."""
  401. body = str(error_body or "").lower()
  402. return any(phrase in body for phrase in _IMAGE_CORRUPT_PHRASES)
  403. __all__ = [
  404. "_SURROGATE_RE", "_escape_invalid_chars_in_json_strings", "_messages_carry_images", "_repair_tool_call_arguments",
  405. "_sanitize_messages_non_ascii", "_sanitize_messages_surrogates", "_sanitize_structure_non_ascii",
  406. "_sanitize_structure_surrogates", "_sanitize_surrogates", "_sanitize_tools_non_ascii",
  407. "_strip_images_from_messages", "_strip_non_ascii", "apply_reasoning_content_policy",
  408. "close_interrupted_tool_sequence", "coalesce_tool_call_id", "coerce_tool_name",
  409. "deterministic_call_id", "matches_reasoning_echo_family", "needs_reasoning_echo",
  410. "normalize_provider_tool_call_ids", "reapply_reasoning_echo", "reasoning_echo_family",
  411. "reasoning_replay_route", "record_reasoning_field_rejection", "rejected_reasoning_carriers",
  412. "route_reasoning_carriers",
  413. "sanitize_outbound_kwargs", "stale_thinking_reaches_wire", "strip_images_for_rejecting_model",
  414. "tool_call_id_variants", "tool_result_id_variants", "uniquify_tool_call_ids",
  415. ]
  416. # -- call_id policy: hash synthesis, ``call_id or id`` coalescing, duplicate-id repair ----
  417. # NOT merged with codex_event_projector._deterministic_call_id (maps app-server ITEM ids,
  418. # not chat tool-call content; merging would change ids and invalidate caches).
  419. # HARD INVARIANT: deterministic (never uuid4) and byte-identical for existing inputs —
  420. # these ids feed prompt-cache prefixes.
  421. def _tc_field(tc: Any, key: str) -> Any:
  422. """Read ``key`` from a tool-call entry that may be a dict or an SDK object."""
  423. return tc.get(key) if isinstance(tc, dict) else getattr(tc, key, None)
  424. def _tc_set(tc: Any, key: str, value: Any) -> None:
  425. tc.__setitem__(key, value) if isinstance(tc, dict) else setattr(tc, key, value)
  426. # --------------------------------------------------------------------------- call_id policy — single owner
  427. # (audit F4, incident chain I4) ---------------------------------------------------------------------------
  428. # Three forked policy sites converged here: * agent/codex_responses_adapter.py `_deterministic_call_id` —
  429. # hash synthesis when a provider omits call_id (fa3ab2ffd0 → e45f2b39e2). *
  430. # run_agent.AIAgent._get_tool_call_id_static — `call_id or id` coalescing for dicts and SDK objects. *
  431. # run_agent.AIAgent._uniquify_tool_call_ids — duplicate-id repair with deterministic `_d<n>` suffixes
  432. # (#58327 loss class). NOT consolidated (different scheme on purpose):
  433. # agent/transports/codex_event_projector._deterministic_call_id maps codex app-server ITEM ids
  434. # (`codex_<type>_<item_id>`), not chat tool-call content; merging the two would change ids and invalidate
  435. # prompt caches. HARD INVARIANT: everything here must stay deterministic (never uuid4) and byte-identical
  436. # for existing inputs — these ids feed prompt-cache prefixes.
  437. def deterministic_call_id(fn_name: str, arguments: str, index: int = 0) -> str:
  438. """Deterministic call_id fallback when the API omits one (random ids would break caching)."""
  439. seed = f"{fn_name}:{arguments}:{index}"
  440. return f"call_{hashlib.sha256(seed.encode('utf-8', errors='replace')).hexdigest()[:12]}"
  441. def _expand_tool_id_variants(values: tuple[Any, ...]) -> frozenset[str]:
  442. """Every wire spelling of one tool-call identifier: Responses bridges may expose the pairing
  443. id and response-item id separately or as ``call_id|response_item_id``; all alias ONE call."""
  444. variants: set[str] = set()
  445. for raw in values:
  446. value = raw.strip() if isinstance(raw, str) else ""
  447. if value:
  448. variants.add(value)
  449. variants.update(p for p in (part.strip() for part in value.split("|")) if p)
  450. return frozenset(variants)
  451. def tool_call_id_variants(tc: Any) -> frozenset[str]:
  452. """Return all pairing-id variants carried by a tool-call entry."""
  453. return _expand_tool_id_variants(tuple(_tc_field(tc, k) for k in ("call_id", "id", "response_item_id")))
  454. def tool_result_id_variants(tool_call_id: Any) -> frozenset[str]:
  455. """Return all matching variants for a role=tool ``tool_call_id``."""
  456. return _expand_tool_id_variants((tool_call_id,))
  457. def coalesce_tool_call_id(tc: Any) -> str:
  458. """Effective call id of a tool_call entry (dict or object); ``""`` when none. Codex Responses
  459. carry ``call_id`` (authoritative pairing key), Chat Completions ``id`` only, and bridge ids
  460. may be ``call_id|response_item_id``."""
  461. for raw in (_tc_field(tc, "call_id"), _tc_field(tc, "id")):
  462. value = raw.strip() if isinstance(raw, str) else ""
  463. if value:
  464. return value.split("|", 1)[0].strip() or value
  465. return ""
  466. def uniquify_tool_call_ids(tool_calls: list, taken: Iterable[str] = ()) -> list:
  467. """Ensure every tool call in one assistant turn has an id no other call in the session has.
  468. Some providers reuse one id across a batch, and some name every call ``call_0`` turn after
  469. turn; the pre-API sanitizer then keeps only the first call/result pair per id, strict
  470. providers reject duplicates, and the desktop binds a tool card to the wrong call. ``taken``
  471. is the ids already in this session's history: they are never rewritten (prompt cache), so
  472. the incoming call is renamed instead. Collisions get a deterministic ``<id>_d<n>`` suffix
  473. (never uuid4 — cache-prefix stability). Mutates entries (SDK models / SimpleNamespace /
  474. dicts) in place. Blank ids are left for the deterministic fallback in
  475. ``build_assistant_message``.
  476. """
  477. seen: set = set(taken)
  478. for tc in tool_calls or []:
  479. # Same coalescing rule as coalesce_tool_call_id, tolerant of non-string ids.
  480. raw = _tc_field(tc, "call_id") or _tc_field(tc, "id") or ""
  481. raw = raw.strip() if isinstance(raw, str) else ""
  482. # Composite Responses ids ("call_x|fc_y") collide on the call half — the pairing key.
  483. cid = raw.split("|", 1)[0]
  484. if not cid:
  485. continue
  486. if cid not in seen:
  487. seen.add(cid)
  488. continue
  489. # range is bounded: at most len(seen) suffixes can already be taken.
  490. new_id = next(f"{cid}_d{n}" for n in range(2, len(seen) + 3) if f"{cid}_d{n}" not in seen)
  491. seen.add(new_id)
  492. try:
  493. # Keep a composite id's response-item half so the provider's fc_/item id survives.
  494. old = _tc_field(tc, "id")
  495. _tc_set(tc, "id", f"{new_id}|{old.split('|', 1)[1]}" if isinstance(old, str) and "|" in old else new_id)
  496. if _tc_field(tc, "call_id"):
  497. _tc_set(tc, "call_id", new_id)
  498. except Exception:
  499. logger.warning("Could not uniquify duplicate tool call id %s", cid)
  500. continue
  501. _fn_name = _tc_field(_tc_field(tc, "function"), "name") or "?"
  502. logger.warning(
  503. "Model reused tool call id %s; renamed the duplicate to %s (tool=%s) to keep call/result "
  504. "pairing lossless.", cid, new_id, _fn_name,
  505. )
  506. return tool_calls
  507. _PROVIDER_TOOL_ID_PREFIXES = ("chatcmpl-tool-",)
  508. def normalize_provider_tool_call_ids(tool_calls: list) -> list:
  509. """Rewrite known provider ids when a parallel batch would be rejected on replay.
  510. The digest is deterministic so persisted messages and prompt-cache prefixes remain
  511. stable. Composite Responses ids retain their response-item half.
  512. """
  513. if len(tool_calls or []) < 2:
  514. return tool_calls
  515. # Gate on the effective id serialization and result pairing use (stripped, blank call_id
  516. # falls back to id), not on raw fields.
  517. if not all(coalesce_tool_call_id(tc).startswith(_PROVIDER_TOOL_ID_PREFIXES) for tc in tool_calls):
  518. return tool_calls
  519. logger.warning("Normalized provider-minted parallel tool-call ids for replay compatibility")
  520. for tc in tool_calls:
  521. # Rewrite each field's call half separately: ``id`` may carry the response-item
  522. # half while ``call_id`` is bare, and that half must survive.
  523. for key in ("id", "call_id"):
  524. value = _tc_field(tc, key)
  525. if not isinstance(value, str):
  526. continue
  527. primary, sep, item = value.strip().partition("|")
  528. primary = primary.strip()
  529. if not primary.startswith(_PROVIDER_TOOL_ID_PREFIXES):
  530. continue
  531. # surrogatepass: provider JSON can carry lone surrogates; strict utf-8 would raise,
  532. # and errors=replace would collapse distinct ids onto one digest.
  533. digest = hashlib.sha256(primary.encode("utf-8", "surrogatepass")).hexdigest()[:12]
  534. _set_provider_tool_id(tc, key, f"call_{digest}{sep}{item}")
  535. return tool_calls
  536. def _set_provider_tool_id(tc: Any, key: str, value: str) -> None:
  537. # transports.types.ToolCall exposes call_id as a read-only view of provider_data;
  538. # write the backing value so id and call_id stay in agreement.
  539. if isinstance(getattr(type(tc), key, None), property) and isinstance(getattr(tc, "provider_data", None), dict):
  540. tc.provider_data[key] = value
  541. else:
  542. _tc_set(tc, key, value)
  543. # -- reasoning replay policy: single owner; adapters keep only SYNTAX ----------------------
  544. # Every model reasons and intends that reasoning to be replayed, so every chat-completions
  545. # route gets its stored reasoning back BY DEFAULT, on the carrier(s) that route reads. Two
  546. # tables own the decision:
  547. # * ``_REASONING_ECHO_RULES`` — the MUST-ECHO tier: a tool-call turn without a non-empty
  548. # ``reasoning_content`` is an HTTP 400 there, so a missing value is padded with " " (never
  549. # "": DeepSeek V4 rejects it, #17341). Kimi is host-driven on purpose (aggregators
  550. # re-exporting kimi do not need the pad).
  551. # * ``_REASONING_CARRIER_ROUTES`` — which carriers a route reads (first match wins). Strict
  552. # hosts come first: their schemas reject unknown message keys with 400/422 ("Extra inputs
  553. # are not permitted" / "property X is unsupported" / "no such field", #45655, #70233).
  554. # Every other route defaults to ``reasoning_content``, which is the de-facto standard.
  555. # A route that still rejects a field is learned at runtime (``record_reasoning_field_rejection``)
  556. # and the field is dropped for that (provider, host, model) only. Stored history keeps every
  557. # carrier; only wire copies are shaped here.
  558. _REASONING_ECHO_RULES: tuple = (
  559. # (family, exact providers (raw), exact providers (lowered), model substrings (lowered), hosts)
  560. ("kimi", frozenset({"kimi-coding", "kimi-coding-cn"}), frozenset(), (), ("api.kimi.com", "moonshot.ai", "moonshot.cn")),
  561. ("deepseek", frozenset(), frozenset({"deepseek"}), ("deepseek",), ("api.deepseek.com",)),
  562. ("mimo", frozenset(), frozenset({"xiaomi"}), ("mimo",), ("api.xiaomimimo.com", "xiaomimimo.com")),
  563. # Portal stealth model that 400s on a tool-call turn without reasoning_content (f86276d2ebc).
  564. ("missingno", frozenset(), frozenset(), ("stealth/missingno",), ()),
  565. )
  566. _REASONING_ECHO_RULE_BY_FAMILY = {rule[0]: rule for rule in _REASONING_ECHO_RULES}
  567. RC, R, RD = "reasoning_content", "reasoning", "reasoning_details"
  568. REASONING_CARRIERS = (RC, R, RD)
  569. _ALL_CARRIERS = frozenset(REASONING_CARRIERS)
  570. _DEFAULT_CARRIERS = frozenset({RC})
  571. _LOCAL_CARRIERS = frozenset({RC, R}) # llama.cpp/SGLang read reasoning_content, vLLM/Ollama read reasoning
  572. _REASONING_CARRIER_ROUTES: tuple = (
  573. # (carriers, providers (lowered), hosts) — evidence per row in the PR body / FINDINGS.
  574. (frozenset(), frozenset({"mistral", "groq", "cerebras", "sambanova"}),
  575. ("mistral.ai", "groq.com", "cerebras.ai", "sambanova.ai", "hunyuan.cloud.tencent.com")),
  576. # Fireworks' ChatMessage schema is additionalProperties:false with reasoning_content only.
  577. (frozenset({RC}), frozenset({"fireworks"}), ("fireworks.ai",)),
  578. # OpenRouter-format gateways read the unified array, the string and the alias.
  579. (_ALL_CARRIERS, frozenset({"openrouter", "kilocode", "ai-gateway", "nous"}),
  580. ("openrouter.ai", "kilo.ai", "ai-gateway.vercel.sh", "nousresearch.com")),
  581. # Vendors that document reasoning_details replay next to reasoning_content.
  582. (frozenset({RC, RD}), frozenset({"novita", "tencent-tokenhub", "minimax", "minimax-cn"}),
  583. ("novita.ai", "tokenhub.tencentmaas.com", "tokenhub-intl.tencentcloudmaas.com", "minimax.io", "minimaxi.com")),
  584. (_LOCAL_CARRIERS, frozenset({"ollama-cloud", "custom", "lmstudio", "upstage"}), ("ollama.com", "upstage.ai")),
  585. )
  586. class ReasoningReplayRoute(NamedTuple):
  587. """``pad``: must-echo tier (missing reasoning_content -> " "). ``carriers``: the reasoning
  588. keys an assistant wire copy carries; ``None`` outside chat_completions, where the native
  589. adapters own reasoning replay (only the must-echo pad is applied, details are untouched)."""
  590. pad: bool
  591. carriers: frozenset | None
  592. def matches_reasoning_echo_family(family: str, provider: Any, model: Any, base_url: Any) -> bool:
  593. """True when (provider, model, base_url) matches one echo-back family (families can overlap;
  594. membership is tested independently). Raises KeyError for an unknown family."""
  595. from utils import base_url_host_matches
  596. _, raw_providers, lowered_providers, model_subs, hosts = _REASONING_ECHO_RULE_BY_FAMILY[family]
  597. model_lower = (model or "").lower()
  598. return (
  599. provider in raw_providers or (provider or "").lower() in lowered_providers
  600. or any(sub in model_lower for sub in model_subs) or any(base_url_host_matches(base_url, host) for host in hosts)
  601. )
  602. def reasoning_echo_family(provider: Any, model: Any, base_url: Any) -> str | None:
  603. """``"kimi"`` / ``"deepseek"`` / ``"mimo"`` (first match in table order) when the endpoint
  604. enforces reasoning_content echo-back on tool-call turns, else ``None``."""
  605. families = (rule[0] for rule in _REASONING_ECHO_RULES)
  606. return next((f for f in families if matches_reasoning_echo_family(f, provider, model, base_url)), None)
  607. def needs_reasoning_echo(provider: Any, model: Any, base_url: Any) -> bool:
  608. """True when the endpoint requires reasoning_content echo-back (the must-echo tier)."""
  609. return reasoning_echo_family(provider, model, base_url) is not None
  610. def route_reasoning_carriers(provider: Any, base_url: Any) -> frozenset:
  611. """Reasoning carriers the chat-completions route reads (before any runtime rejection)."""
  612. from utils import base_url_host_matches
  613. provider_lower = (provider or "").strip().lower()
  614. carriers = next(
  615. (c for c, providers, hosts in _REASONING_CARRIER_ROUTES
  616. if provider_lower in providers or any(base_url_host_matches(base_url, h) for h in hosts)),
  617. None,
  618. )
  619. if carriers is None:
  620. from agent.model_metadata import is_local_endpoint
  621. carriers = _LOCAL_CARRIERS if base_url and is_local_endpoint(str(base_url)) else _DEFAULT_CARRIERS
  622. if RD not in carriers and carriers and _profile_declares_native_details(provider_lower):
  623. carriers = carriers | {RD}
  624. return carriers
  625. def _profile_declares_native_details(provider_lower: str) -> bool:
  626. """A profile declaring ``native_reasoning_details_type`` consumes replayed details by contract."""
  627. if not provider_lower:
  628. return False
  629. from providers import get_provider_profile
  630. return bool(getattr(get_provider_profile(provider_lower), "native_reasoning_details_type", None))
  631. def reasoning_replay_route(
  632. api_mode: Any, provider: Any, model: Any, base_url: Any, *, echo_opt_in: bool = False,
  633. rejected: Iterable[str] = (),
  634. ) -> ReasoningReplayRoute:
  635. """Replay decision for one route. Deterministic in its inputs, so the wire prefix is byte-stable
  636. across turns and changes only on a route switch or a recorded rejection (``rejected``)."""
  637. pad = bool(echo_opt_in) or needs_reasoning_echo(provider, model, base_url)
  638. if (api_mode or "chat_completions") != "chat_completions":
  639. return ReasoningReplayRoute(pad, None)
  640. carriers = route_reasoning_carriers(provider, base_url) - frozenset(rejected)
  641. # A strict route never gets a reasoning key, not even the must-echo pad.
  642. return ReasoningReplayRoute(pad and RC in carriers, carriers)
  643. def stale_thinking_reaches_wire(api_mode: Any, provider: Any, model: Any, base_url: Any) -> bool:
  644. """True when stale assistant reasoning text is actually replayed on the wire for the route.
  645. The single wire-truth predicate the compaction TRIGGER estimator and the tail-budget
  646. walks must share: if they disagree, a reasoning-heavy session can look over-threshold
  647. to preflight yet fully tail-protected to the walk — an infinite compaction loop.
  648. ``codex_responses`` never reads the text keys (continuity rides the encrypted sidecar).
  649. A runtime rejection is not visible here; both sides then over-charge identically.
  650. """
  651. if (api_mode or "") == "anthropic_messages":
  652. from agent.anthropic_thinking_policy import native_anthropic_preserves_prior_thinking
  653. if native_anthropic_preserves_prior_thinking(base_url, model):
  654. return True
  655. if not api_mode:
  656. # No route facts (a bare compressor): only the must-echo tier is known to replay.
  657. return needs_reasoning_echo(provider, model, base_url)
  658. route = reasoning_replay_route(api_mode, provider, model, base_url)
  659. if route.carriers is None:
  660. return (api_mode or "") != "codex_responses" and route.pad
  661. return bool(route.carriers & {RC, R})
  662. def native_anthropic_accounting_projection(messages: Any) -> tuple[Any, tuple[str, ...]]:
  663. """Return the native Anthropic wire shadow plus readable replay thinking out-of-band.
  664. Canonical history may retain storage-only reasoning alongside signed replay carriers.
  665. Native conversion prefers ordered anthropic_content_blocks over reasoning_details and
  666. never sends reasoning itself. The generic message estimator therefore receives only
  667. ordinary wire-shaped fields, while readable thinking is returned separately for the
  668. explicit Anthropic accounting seam. Opaque signature/data bytes are never priced.
  669. """
  670. if not isinstance(messages, list):
  671. return messages, ()
  672. from agent.anthropic_message_convert import assistant_replay_carrier
  673. projected = []
  674. replayed_thinking: list[str] = []
  675. for message in messages:
  676. if not isinstance(message, dict) or message.get("role") != "assistant":
  677. projected.append(message)
  678. continue
  679. # Mirror _convert_assistant_message's actual inputs instead of starting
  680. # from canonical storage. Context selection is allowed to return canonical
  681. # rows, which can contain timestamp/finish_reason/api_content and other
  682. # local metadata that native Anthropic never sees.
  683. shadow = {"role": "assistant"}
  684. for key in ("content", "tool_calls", "reasoning_content", "cache_control"):
  685. if key in message:
  686. shadow[key] = message[key]
  687. # Canonical input (preflight, tail walk) still holds the api_content sidecar that
  688. # build_api_messages substitutes into content; post-build input already carries it in
  689. # content. Charge it either way: an ordered turn, or a context-selection clone the
  690. # converter reads raw, then overcounts, never undercounts.
  691. sidecar = message.get("api_content")
  692. if isinstance(sidecar, str) and sidecar:
  693. shadow["content"] = sidecar
  694. _, carrier = assistant_replay_carrier(message)
  695. # The converter ignores reasoning_content for an ordered turn and only injects it when the
  696. # details carrier holds no thinking, so it must not be charged in addition to the carrier.
  697. if carrier:
  698. shadow.pop("reasoning_content", None)
  699. replayed_thinking.extend(
  700. block["thinking"]
  701. for block in carrier
  702. if block.get("type") == "thinking" and isinstance(block.get("thinking"), str) and block["thinking"]
  703. )
  704. projected.append(shadow)
  705. return projected, tuple(replayed_thinking)
  706. def _replayable_reasoning_text(msg: dict) -> str | None:
  707. """The turn's reasoning text: a non-blank ``reasoning_content`` wins over ``reasoning``."""
  708. for key in (RC, R):
  709. value = msg.get(key)
  710. if isinstance(value, str) and value.strip():
  711. return value
  712. return None
  713. def _apply_legacy_must_echo_pad(source_msg: dict, api_msg: dict) -> None:
  714. """Native-adapter wires (``carriers=None``): the pre-replay contract, byte-for-byte. An explicit
  715. value is kept verbatim (legacy "" upgraded to " "); a tool-call turn holding only another
  716. provider's ``reasoning`` is padded instead of converted into a native thinking block."""
  717. existing, reasoning = source_msg.get(RC), source_msg.get(R)
  718. if isinstance(existing, str):
  719. api_msg[RC] = existing or " "
  720. elif isinstance(reasoning, str) and reasoning and not source_msg.get("tool_calls"):
  721. api_msg[RC] = reasoning
  722. else:
  723. api_msg[RC] = " "
  724. def apply_reasoning_content_policy(
  725. source_msg: dict, api_msg: dict, needs_thinking_pad: bool, carriers: frozenset | None = None,
  726. ) -> None:
  727. """Shape an assistant replay message's reasoning keys for the active route (mutates ``api_msg``).
  728. ``needs_thinking_pad`` is the must-echo flag; ``carriers`` the keys the route reads
  729. (``reasoning_replay_route``). ``carriers=None`` is a non-chat-completions wire: only the
  730. must-echo ``reasoning_content`` rides there and ``reasoning_details`` is left to the adapter.
  731. Keys the route does not read are removed, so a strict host never sees one (#45655, #70233).
  732. """
  733. if source_msg.get("role") != "assistant":
  734. return
  735. text = _replayable_reasoning_text(source_msg)
  736. effective = carriers if carriers is not None else (frozenset({RC}) if needs_thinking_pad else frozenset())
  737. if carriers is None and needs_thinking_pad:
  738. _apply_legacy_must_echo_pad(source_msg, api_msg)
  739. elif RC in effective and (text is not None or needs_thinking_pad):
  740. # Must-echo tier: every assistant turn carries the field; " " (not "") when there is no
  741. # text, because DeepSeek V4 rejects empty string (#17341) and a legacy "" pad upgrades.
  742. api_msg[RC] = text if text is not None else " "
  743. else:
  744. # Also drops a non-string value (None after compaction) and a whitespace pad written
  745. # for a must-echo provider: never pass null, never replay a pad as reasoning.
  746. api_msg.pop(RC, None)
  747. if R in effective and text is not None:
  748. api_msg[R] = text
  749. else:
  750. api_msg.pop(R, None)
  751. if carriers is not None and RD not in carriers:
  752. # Private ``*.native_assistant`` records (Gemini / profile-declared carriers) survive: the transport lifts
  753. # them onto the route that reads them and filters them from every other wire.
  754. private = [d for d in api_msg.pop(RD, None) or () if isinstance(d, dict)
  755. and str(d.get("type") or "").endswith(".native_assistant")]
  756. if private:
  757. api_msg[RD] = private
  758. def _reasoning_shape(msg: dict) -> tuple:
  759. return tuple(msg.get(key) for key in REASONING_CARRIERS)
  760. def reapply_reasoning_echo(api_messages: list, needs_thinking_pad: bool, carriers: frozenset | None = None) -> int:
  761. """Reconcile already-built assistant turns with the ACTIVE route.
  762. ``api_messages`` is built once under the primary; a mid-conversation fallback or a recorded
  763. field rejection changes the route, so baked-in keys are reconciled both ways: TO a must-echo
  764. provider the pad is re-applied (else 400), TO a strict one the keys are stripped (else 422),
  765. and a carrier the new route reads is restored from the text that is still present.
  766. Idempotent. Returns the number of assistant turns changed.
  767. """
  768. changed = 0
  769. for api_msg in api_messages:
  770. if api_msg.get("role") != "assistant":
  771. continue
  772. before = _reasoning_shape(api_msg)
  773. if carriers is None and needs_thinking_pad and api_msg.get(RC):
  774. continue
  775. apply_reasoning_content_policy(api_msg, api_msg, needs_thinking_pad, carriers)
  776. changed += _reasoning_shape(api_msg) != before
  777. return changed
  778. # Provider error bodies (lowercased) for "this request carries a key my schema does not know".
  779. _UNKNOWN_FIELD_PHRASES = (
  780. "extra inputs are not permitted", "is unsupported", "no such field", "unknown field",
  781. "unrecognized request argument", "unrecognized field", "unknown parameter", "unexpected field",
  782. "additional propert", "unknown key",
  783. )
  784. _NAMED_FIELD_RES = {
  785. RC: re.compile(r"(?<![\w])reasoning_content(?![\w])"),
  786. RD: re.compile(r"(?<![\w])reasoning_details(?![\w])"),
  787. # The bare word is also a top-level request param; only a message-path mention counts.
  788. R: re.compile(r"messages[^\n]{0,80}?(?<![\w])reasoning(?![\w])"),
  789. }
  790. def rejected_reasoning_fields(error_body: Any, sent_messages: Any) -> frozenset:
  791. """Reasoning keys to drop after an unknown-field rejection that names one this request carried.
  792. Strict schemas report one offending key per error, so the drop is widened to the keys the
  793. same schema will reject next: a rejected ``reasoning_details`` / ``reasoning`` takes the
  794. other non-standard carrier too (``reasoning_content`` still carries the text); a rejected
  795. ``reasoning_content`` (the most widely accepted alias) takes all three. One retry, not three.
  796. """
  797. body = str(error_body or "").lower()
  798. if not any(phrase in body for phrase in _UNKNOWN_FIELD_PHRASES):
  799. return frozenset()
  800. sent = {
  801. key for msg in (sent_messages if isinstance(sent_messages, list) else ())
  802. if isinstance(msg, dict) and msg.get("role") == "assistant" for key in REASONING_CARRIERS if key in msg
  803. }
  804. named = {key for key in sent if _NAMED_FIELD_RES[key].search(body)}
  805. if not named:
  806. return frozenset()
  807. return frozenset(sent & (_ALL_CARRIERS if RC in named else {R, RD}))
  808. def reasoning_route_key(agent: Any) -> tuple[str, str, str]:
  809. """``(provider, base_url host, model)``: one gateway serves models on different upstream lanes,
  810. so a rejection learned for one model must not strip carriers from its siblings."""
  811. from utils import base_url_hostname
  812. return (
  813. (getattr(agent, "provider", "") or "").strip().lower(),
  814. base_url_hostname(getattr(agent, "base_url", "") or "") or "",
  815. (getattr(agent, "model", "") or "").strip(),
  816. )
  817. _REJECTION_MODEL_CONFIG_KEY = "reasoning_rejected_carriers"
  818. def rejected_reasoning_carriers(agent: Any) -> frozenset:
  819. """Reasoning keys the active (provider, host, model) rejected in this session.
  820. Persisted in the session's ``model_config`` so a resumed process (``--resume``, a gateway
  821. restart) never re-learns a rejection with another 400. Loaded once per ``session_id``.
  822. """
  823. routes = agent.__dict__.setdefault("_reasoning_rejecting_routes", {})
  824. session_id = getattr(agent, "session_id", None)
  825. if session_id and getattr(agent, "_reasoning_rejections_loaded_for", None) != session_id:
  826. agent._reasoning_rejections_loaded_for = session_id
  827. getter = getattr(getattr(agent, "_session_db", None), "get_session_model_config_value", None)
  828. stored = getter(session_id, _REJECTION_MODEL_CONFIG_KEY, []) if callable(getter) else []
  829. for entry in stored if isinstance(stored, list) else ():
  830. if isinstance(entry, list) and len(entry) == 4 and isinstance(entry[3], list):
  831. routes.setdefault(tuple(entry[:3]), set()).update(k for k in entry[3] if k in _ALL_CARRIERS)
  832. return frozenset(routes.get(reasoning_route_key(agent), ()))
  833. def record_reasoning_field_rejection(agent: Any, error_body: Any, sent_messages: Any) -> frozenset:
  834. """Remember the reasoning keys this route rejected; returns the NEW ones (empty = no retry).
  835. The next ``build_api_request`` re-shapes ``api_messages`` without them for this
  836. (provider, host, model) for the rest of the session. A repeat rejection of an already
  837. recorded key returns empty, so recovery can never loop. History is never touched.
  838. """
  839. if getattr(agent, "api_mode", "chat_completions") != "chat_completions":
  840. return frozenset()
  841. fields = rejected_reasoning_fields(error_body, sent_messages)
  842. if needs_reasoning_echo(getattr(agent, "provider", ""), getattr(agent, "model", ""), getattr(agent, "base_url", "")):
  843. # Must-echo routes 400 on any tool turn WITHOUT reasoning_content; a body naming it is a
  844. # value complaint ("must not be empty"), never a schema that lacks the field.
  845. fields -= {RC}
  846. if not fields:
  847. return frozenset()
  848. new = fields - rejected_reasoning_carriers(agent)
  849. if not new:
  850. return frozenset()
  851. routes = agent._reasoning_rejecting_routes
  852. routes.setdefault(reasoning_route_key(agent), set()).update(new)
  853. patcher = getattr(getattr(agent, "_session_db", None), "patch_session_model_config", None)
  854. if callable(patcher) and getattr(agent, "session_id", None) and not getattr(agent, "_persist_disabled", False):
  855. patcher(agent.session_id, {_REJECTION_MODEL_CONFIG_KEY: [[*key, sorted(v)] for key, v in sorted(routes.items())]})
  856. return frozenset(new)
  857. # Image / multimodal parts are deliberately NOT consolidated here: per-adapter handling is
  858. # format-specific SYNTAX. The one shared image POLICY is ``_strip_images_from_messages``.