native_compaction.py 20 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423
  1. """Native OpenAI Responses server-side compaction on supported OpenAI routes.
  2. ``context_management=[{"type": "compaction", "compact_threshold": N}]`` makes the server
  3. summarize older context into an opaque ``compaction`` item once the input crosses N tokens.
  4. Deliberately narrow: gpt-5.6 on api.openai.com or the ChatGPT Codex backend, plus gpt-6-astra
  5. (and its ``-900k`` picker alias) on official Codex OAuth. The local compressor
  6. stays armed as fallback (native threshold clamped below the local trigger); compaction items
  7. ride the ``codex_reasoning_items`` sidecar. No transport imports (shared gate, no cycles).
  8. """
  9. from __future__ import annotations
  10. import logging
  11. from typing import Any, Dict, List, Optional
  12. from urllib.parse import urlsplit
  13. from agent.codex_headers import is_official_codex_base_url
  14. from agent.context_compressor import is_compaction_summary_message
  15. from agent.message_content import flatten_message_text
  16. from agent.reasoning_effort import is_astra_model
  17. logger = logging.getLogger(__name__)
  18. # Native compaction fires this far below the local trigger so the server gets the first shot.
  19. LOCAL_TRIGGER_SAFETY_MARGIN = 8_192
  20. # Fallback when automatic mode has no local trigger to follow.
  21. DEFAULT_COMPACT_THRESHOLD = 200_000
  22. # Substring match so dated snapshots and variants (gpt-5.6-mini) stay eligible.
  23. _ELIGIBLE_MODEL_MARKER = "gpt-5.6"
  24. def is_native_compaction_model(
  25. model: Optional[str], *, provider: Optional[str] = None, base_url: Optional[str] = None,
  26. ) -> bool:
  27. """Preserve gpt-5.6 eligibility; Astra (``-900k`` is a picker alias of the same wire slug)
  28. additionally requires official Codex OAuth."""
  29. return _ELIGIBLE_MODEL_MARKER in (model or "").lower() or (
  30. is_astra_model(model)
  31. and (provider or "").strip().lower() == "openai-codex"
  32. and is_official_codex_base_url(base_url or "")
  33. )
  34. def resolve_native_compaction_capabilities(
  35. *, model: Optional[str], base_url: Optional[str], provider: Optional[str] = None, is_codex_backend: bool = False,
  36. ) -> dict[str, bool]:
  37. """Resolve the native-compaction capability for a runtime destination (a resolved ``False``
  38. is distinct from "unresolved" and must survive model switches unchanged)."""
  39. direct_default = (provider or "").strip().lower() == "openai" and not base_url
  40. return {"native_compaction": is_native_compaction_model(model, provider=provider, base_url=base_url) and (
  41. direct_default or is_direct_openai_route(base_url, is_codex_backend=is_codex_backend))}
  42. def is_direct_openai_route(base_url: Optional[str], *, is_codex_backend: bool = False) -> bool:
  43. """True for api.openai.com or the ChatGPT Codex backend — nothing else."""
  44. if is_codex_backend:
  45. return True
  46. try:
  47. hostname = (urlsplit(base_url or "").hostname or "").lower()
  48. except ValueError:
  49. return False
  50. return hostname == "api.openai.com"
  51. def _positive_int(value: Any, *, reject: tuple = (bool,)) -> Optional[int]:
  52. """``int(value)`` when it is a positive integer-like (never a bool), else None."""
  53. if value is None or isinstance(value, reject):
  54. return None
  55. try:
  56. parsed = int(value)
  57. except (TypeError, ValueError):
  58. return None
  59. return parsed if parsed > 0 else None
  60. def resolve_compact_threshold(configured_threshold: Any, local_trigger_tokens: Any = None) -> int:
  61. """Resolve automatic mode or clamp an explicit native threshold.
  62. Omitted/invalid follows the local compressor trigger minus the safety margin. An
  63. explicit positive integer is absolute unless it must be clamped so native compaction
  64. fires first. Booleans are never thresholds.
  65. """
  66. local = _positive_int(local_trigger_tokens)
  67. upper = None if local is None else max(
  68. 1_024, local - LOCAL_TRIGGER_SAFETY_MARGIN if local > LOCAL_TRIGGER_SAFETY_MARGIN else int(local * 0.8))
  69. configured = _positive_int(configured_threshold, reject=(bool, float))
  70. if configured is None:
  71. return upper if upper is not None else DEFAULT_COMPACT_THRESHOLD
  72. if upper is None:
  73. return configured
  74. return max(1_024, min(configured, upper))
  75. _checkpoint_suppression_logged = False
  76. def _warn_native_compaction_suppressed_by_checkpoint_gate() -> None:
  77. """Log once per process; the suppression itself is re-evaluated per request."""
  78. global _checkpoint_suppression_logged
  79. if not _checkpoint_suppression_logged:
  80. _checkpoint_suppression_logged = True
  81. logger.warning(
  82. "compression.checkpoint_required is enabled: server-side native "
  83. "compaction (context_management) is disabled for this agent so the "
  84. "checkpoint-aware Hermes compressor stays authoritative."
  85. )
  86. def native_compaction_context_management(agent: Any, *, is_codex_backend: bool, is_xai_responses: bool = False,
  87. endpoint: Any = None) -> Optional[list[dict[str, Any]]]:
  88. """Return the ``context_management`` payload for this request, or None ("do not send").
  89. ``endpoint`` is the route's ``ResponsesEndpointQuirks``; ``native_compaction=False`` never sends.
  90. Every gate is re-checked per request so a mid-session model switch or the in-session
  91. kill switch (``agent.codex_responses_native_compaction = False``) takes effect next call.
  92. """
  93. capabilities = getattr(agent, "runtime_capabilities", None)
  94. if isinstance(capabilities, dict) and not capabilities.get("native_compaction", False):
  95. return None
  96. # compression.enabled: false disables ALL automatic compaction, native included.
  97. if not getattr(agent, "codex_responses_native_compaction", False) or not getattr(agent, "compression_enabled", True):
  98. return None
  99. # Server-side compaction is a lossy boundary the provider owns (no pre-compress checkpoint
  100. # can run first), so the checkpoint-aware compressor stays authoritative. Explicit-True
  101. # matches compress_context().
  102. if getattr(agent, "compression_checkpoint_required", False) is True:
  103. _warn_native_compaction_suppressed_by_checkpoint_gate()
  104. return None
  105. if is_xai_responses or (endpoint is not None and not endpoint.native_compaction) or not is_native_compaction_model(
  106. getattr(agent, "model", None), provider=getattr(agent, "provider", None),
  107. base_url=getattr(agent, "base_url", None),
  108. ):
  109. return None
  110. trusted_proxy = bool(getattr(agent, "capabilities", {}).get("openai_native_compaction", False))
  111. if not trusted_proxy and not is_direct_openai_route(getattr(agent, "base_url", None), is_codex_backend=is_codex_backend):
  112. return None
  113. compressor = getattr(agent, "context_compressor", None)
  114. local_trigger = getattr(compressor, "threshold_tokens", None) if compressor is not None else None
  115. threshold = resolve_compact_threshold(getattr(agent, "codex_responses_compact_threshold", None), local_trigger)
  116. return [{"type": "compaction", "compact_threshold": threshold}]
  117. # Retention budgets for plaintext user messages / local summaries carried across a native
  118. # compaction boundary (mirrors Codex CLI's RETAINED_MESSAGE_TOKEN_BUDGET).
  119. RETAINED_USER_MESSAGE_TOKEN_BUDGET = 64_000
  120. RETAINED_SUMMARY_TOKEN_BUDGET = 32_000
  121. def _approx_tokens(text: str) -> int:
  122. """Retention cost of one carried-over text; never 0 so an empty item still consumes budget."""
  123. from agent.model_metadata import estimate_tokens_rough
  124. return max(1, estimate_tokens_rough(text))
  125. def _head_within_budget(text: str, budget: int) -> str:
  126. """Longest prefix of ``text`` whose ``_approx_tokens`` fits ``budget``. A plain ``budget * CHARS_PER_TOKEN``
  127. char slice would keep ~2x the budget of Cyrillic and ~4x of CJK; ASCII still gets that many chars."""
  128. from agent.model_metadata import CHARS_PER_TOKEN
  129. head = text[:max(0, budget) * CHARS_PER_TOKEN] # every char costs >= 1/CHARS_PER_TOKEN token
  130. if head.isascii(): # ASCII costs exactly ceil(len / CHARS_PER_TOKEN): the cap already fits
  131. return head
  132. lo, hi = 0, len(head)
  133. while lo < hi:
  134. mid = (lo + hi + 1) // 2
  135. if _approx_tokens(text[:mid]) <= budget:
  136. lo = mid
  137. else:
  138. hi = mid - 1
  139. return text[:lo]
  140. def _extract_item_text(item: Any) -> Optional[str]:
  141. """Measurable text from a Responses item (string/multipart/metadata), or None."""
  142. if not isinstance(item, dict):
  143. return None
  144. content = item.get("content")
  145. if content is None and "output_text" in item:
  146. content = item.get("output_text")
  147. if isinstance(content, str):
  148. return content if content.strip() else None
  149. if not isinstance(content, list):
  150. return None
  151. parts = []
  152. for part in content:
  153. candidates: tuple = (part,) # non-str, non-dict parts filter out below
  154. if isinstance(part, dict):
  155. part_meta = part.get("metadata")
  156. candidates = (part.get("text") or part.get("input_text") or part.get("output_text"),
  157. part_meta.get("text") if isinstance(part_meta, dict) else None)
  158. parts.extend(c.strip() for c in candidates if isinstance(c, str) and c.strip())
  159. text = " ".join(parts)
  160. return text if text.strip() else None
  161. def _input_text_parts_cost(content: Any) -> Optional[int]:
  162. """Measure only the adapter-owned text-only shape, including whitespace and empty parts."""
  163. if not isinstance(content, list) or not content or not all(
  164. isinstance(part, dict) and part.get("type") == "input_text"
  165. and isinstance(part.get("text"), str) for part in content
  166. ):
  167. return None
  168. return sum(_approx_tokens(part["text"]) for part in content)
  169. def _truncate_input_text_parts(content: list[dict[str, Any]], budget: int) -> list[dict[str, Any]]:
  170. """Copy the head of validated input_text parts without flattening their metadata."""
  171. head = []
  172. for part in content:
  173. text = part["text"]
  174. cost = _approx_tokens(text)
  175. if cost > budget:
  176. kept = _head_within_budget(text, budget)
  177. if kept:
  178. head.append({**part, "text": kept})
  179. break
  180. head.append(part)
  181. budget -= cost
  182. return head
  183. def _has_retainable_image_content(item: Any) -> bool:
  184. """True for a converted Responses message with a valid ``input_image`` part (only the
  185. adapter-owned shape counts, so empty multipart placeholders never become durable history)."""
  186. content = item.get("content") if isinstance(item, dict) else None
  187. return isinstance(content, list) and any(
  188. isinstance(part, dict) and str(part.get("type") or "").strip().lower() == "input_image"
  189. and isinstance(part.get("image_url"), str) and part["image_url"].strip() for part in content
  190. )
  191. # Canonical provenance check. Deliberately NOT a second heuristic (no underscore-key scan,
  192. # no ad-hoc headings) — either could promote adversarial content to durable history.
  193. _is_summary_item = is_compaction_summary_message
  194. def _is_compaction_item(item: Any) -> bool:
  195. return isinstance(item, dict) and item.get("type") == "compaction"
  196. def prune_pre_checkpoint_items(
  197. items: list[dict[str, Any]],
  198. retained_user_token_budget: int = RETAINED_USER_MESSAGE_TOKEN_BUDGET,
  199. retained_summary_token_budget: int = RETAINED_SUMMARY_TOKEN_BUDGET,
  200. enable_summary_retention: bool = True, item_sources: Optional[list[Any]] = None,
  201. ) -> list[dict[str, Any]]:
  202. """Restructure Responses input around the newest compaction checkpoint.
  203. The server drops every input item preceding a replayed ``compaction`` item, erasing the
  204. user's plaintext asks and any local-compression summary. Rebuild as::
  205. [checkpoint run] + [retained user & summary messages (newest-first budget)] + [post]
  206. - The NEWEST contiguous run of checkpoints wins; relative order is preserved.
  207. - User messages are kept verbatim within ``retained_user_token_budget``; the boundary
  208. message is head-truncated when it only partially fits (strings or text-only typed
  209. ``input_text`` parts, preserving part metadata). An oversized unsupported/mixed-content
  210. boundary stops older user retention rather than substituting an older ask. A recognized
  211. image-only user message is retained whole at one-token cost.
  212. - Summaries are retained whole within ``retained_summary_token_budget``, never sliced
  213. (framing would corrupt) and never duplicated.
  214. - ``item_sources`` (parallel to ``items``) is the raw chat message each item came from.
  215. Conversion can be lossy for summaries (merge-into-tail carrier → typed
  216. ``function_call_output``; assistant carrier shadowed by a stale replay), so a source
  217. that is itself a canonical summary carrier is read from the SOURCE and retained as a
  218. synthesized ``role="assistant"`` message.
  219. - ``enable_summary_retention`` is a test override, not a config surface.
  220. The server drops every input item that precedes a replayed ``compaction`` item (live-verified Aug 2026),
  221. so sending pre-checkpoint history is dead weight AND silently erases the user's plaintext asks —
  222. including any local-compression summary the agent already produced, which previously vanished here
  223. because it carries ``role="assistant"``, not ``"user"`` (#90975).
  224. A summary is never byte/character-sliced: Hermes summaries carry structural framing (handoff prefix, end
  225. marker, merge-into-tail delimiters) that a blind slice can corrupt, so one that doesn't fit whole is
  226. dropped instead. A summary already retained once (identical text) is never duplicated, so repeated
  227. checkpoints stay idempotent. - ``enable_summary_retention`` is a function-level override (used by tests
  228. and callers that need the pre-#90975 behavior back); it is not wired to a user-facing config surface.
  229. Without ``item_sources`` (default), retention only sees what survived conversion, matching pre-#90976
  230. behavior (#90976).
  231. """
  232. if not isinstance(items, list) or not items:
  233. return items
  234. last_cp = max((i for i, item in enumerate(items) if _is_compaction_item(item)), default=None)
  235. if last_cp is None:
  236. return items
  237. first_cp = last_cp
  238. while first_cp > 0 and _is_compaction_item(items[first_cp - 1]):
  239. first_cp -= 1
  240. pre = items[:first_cp]
  241. has_sources = isinstance(item_sources, list) and len(item_sources) == len(items)
  242. pre_sources: list[Any] = item_sources[:first_cp] if has_sources else [None] * len(pre)
  243. retained_reversed: list[dict[str, Any]] = []
  244. user_remaining = max(0, int(retained_user_token_budget))
  245. summary_remaining = max(0, int(retained_summary_token_budget))
  246. seen_summary_texts: set = set()
  247. def _retain_summary(text: Optional[str], retained_item: dict[str, Any]) -> None:
  248. """Retain a summary whole when it fits the budget and is not a duplicate (never sliced)."""
  249. nonlocal summary_remaining
  250. if not text or summary_remaining <= 0 or text in seen_summary_texts:
  251. return
  252. cost = _approx_tokens(text)
  253. if cost <= summary_remaining:
  254. seen_summary_texts.add(text)
  255. retained_reversed.append(retained_item)
  256. summary_remaining -= cost
  257. for item, source in zip(reversed(pre), reversed(pre_sources)):
  258. if not isinstance(item, dict):
  259. continue
  260. # Source-based detection sees past a lossy conversion; it only fires
  261. # when the source itself is a provenance-tagged summary carrier.
  262. # Canonical source-based summary detection: reads the ORIGINAL chat message's own content, so it
  263. # sees past a lossy conversion (a typed `function_call_output` wrapper, or a stale exact-replay
  264. # message) that erased the summary from `item` itself (#90976).
  265. if enable_summary_retention and isinstance(source, dict) and _is_summary_item(source):
  266. text = flatten_message_text(source.get("content"))
  267. _src_role = source.get("role")
  268. _retain_summary(text if text.strip() else None,
  269. {"type": "message", "role": _src_role if _src_role in ("user", "assistant") else "assistant",
  270. "content": text})
  271. continue
  272. # Typed non-message items never carry role=user or a summary flag.
  273. if "type" in item and item.get("type") != "message":
  274. continue
  275. is_summary = enable_summary_retention and _is_summary_item(item)
  276. is_user = item.get("role") == "user"
  277. if not is_user and not is_summary:
  278. continue
  279. text = _extract_item_text(item)
  280. if text is None:
  281. if not (is_user and _has_retainable_image_content(item)):
  282. continue
  283. text = ""
  284. if is_summary:
  285. _retain_summary(text, item)
  286. elif user_remaining > 0:
  287. content = item.get("content")
  288. parts_cost = _input_text_parts_cost(content)
  289. cost = parts_cost if parts_cost is not None else _approx_tokens(text)
  290. if cost <= user_remaining:
  291. retained_reversed.append(item)
  292. user_remaining -= cost
  293. else:
  294. if isinstance(content, str):
  295. head = _head_within_budget(content, user_remaining)
  296. keep = bool(head.strip())
  297. elif parts_cost is not None:
  298. head = _truncate_input_text_parts(content, user_remaining)
  299. keep = any(part["text"].strip() for part in head)
  300. else:
  301. keep = False
  302. if keep:
  303. retained_reversed.append({**item, "content": head})
  304. # A non-truncatable boundary (e.g. text + image) must not let
  305. # an older completed ask replace the newer oversized ask.
  306. user_remaining = 0
  307. result = items[first_cp : last_cp + 1] + list(reversed(retained_reversed)) + items[last_cp + 1 :]
  308. logger.debug("Pruned pre-checkpoint items: %d input -> %d retained (user_rem=%d, summary_rem=%d)",
  309. len(items), len(result), user_remaining, summary_remaining)
  310. return result
  311. _REJECTION_MARKERS = (
  312. "unknown", "unsupported", "invalid", "unexpected", "not permitted",
  313. "not allowed", "unrecognized", "extra field", "no such", "bad request",
  314. "not supported",
  315. )
  316. def is_native_compaction_rejection(error: Any, status_code: Any = None) -> bool:
  317. """True when a provider error is a STRUCTURED rejection of ``context_management``.
  318. Drives one-shot recovery (strip, disable for the session, retry), so matching is narrow:
  319. a transient 5xx that merely ECHOES the request must not downgrade native compaction.
  320. Requires ``status_code`` 400 (or unknown) AND the field name with rejection language.
  321. See #82777.
  322. * ``status_code`` is 400 (or unknown/None — some transports surface only a message string; field-name
  323. matching alone is then the best available signal, preserving pre-#82777 behavior for them), and * the
  324. error text names ``context_management`` / ``compact_threshold`` alongside rejection language ("unknown",
  325. "unsupported", "invalid", "unexpected", "not permitted"...). A bare field-name echo without rejection
  326. language does not match.
  327. """
  328. text = str(error or "").lower()
  329. if "context_management" not in text and "compact_threshold" not in text:
  330. return False
  331. try:
  332. if status_code is not None and int(status_code) != 400:
  333. return False
  334. except (TypeError, ValueError):
  335. pass
  336. return any(marker in text for marker in _REJECTION_MARKERS)
  337. def has_compaction_checkpoint(items: Any) -> bool:
  338. """Does this ``codex_reasoning_items`` sidecar carry a compaction checkpoint? A checkpoint is
  339. cumulative context living in exactly one place: rewrite/discard the sidecar only after asking."""
  340. return isinstance(items, list) and any(
  341. _is_compaction_item(item)
  342. and isinstance(item.get("encrypted_content"), str)
  343. and bool(item["encrypted_content"].strip())
  344. for item in items
  345. )
  346. def merge_interim_reasoning_items(prior_items: Any, new_items: Any) -> list[dict[str, Any]]:
  347. """Merge ``codex_reasoning_items`` across Codex incomplete-continuation dedup.
  348. A checkpoint on the EARLIER response is not re-emitted by the continuation, so a blind
  349. overwrite drops the only copy: newer items win, prior checkpoints are prepended unless
  350. the newer payload has its own.
  351. """
  352. prior = prior_items if isinstance(prior_items, list) else []
  353. kept_checkpoints = [item for item in prior if _is_compaction_item(item)]
  354. new_list = list(new_items) if isinstance(new_items, list) else []
  355. if has_compaction_checkpoint(new_list) or not kept_checkpoints:
  356. return new_list
  357. return kept_checkpoints + new_list