anthropic_adapter.py 49 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885
  1. """Anthropic Messages API adapter: client construction + the Messages call for Hermes's
  2. OpenAI-style internals. Auth: Console API keys (``sk-ant-api*``/``-usr*``/``-svc*``/``-admin*``) ->
  3. x-api-key; OAuth setup-tokens (``sk-ant-oat*``) and Claude Code credentials -> Bearer + beta header.
  4. Endpoint predicates, payload conversion and credentials live in ``agent/anthropic_{endpoints,
  5. message_convert,credentials}.py``; import them from there."""
  6. from pm import install_hint
  7. import logging
  8. import math
  9. import os
  10. import re
  11. import shutil
  12. import subprocess
  13. from contextlib import suppress
  14. from typing import Any, Dict, List, Optional
  15. from utils import normalize_proxy_env_vars
  16. from agent.anthropic_credentials import _is_oauth_token, anthropic_route_is_oauth, is_native_anthropic_host
  17. from agent.anthropic_endpoints import (
  18. _base_url_needs_context_1m_beta, _is_azure_anthropic_endpoint, _is_kimi_coding_endpoint,
  19. _is_minimax_anthropic_endpoint, _is_nous_portal_endpoint, _is_opencode_endpoint,
  20. _is_third_party_anthropic_endpoint, _model_name_is_kimi_family, _normalize_base_url_text,
  21. _requires_bearer_auth,
  22. )
  23. from agent.anthropic_message_convert import (
  24. convert_messages_to_anthropic, convert_tools_to_anthropic, normalize_model_name,
  25. )
  26. from agent.errors import EmptyStreamError
  27. from hermes_cli.version_info import get_version_info
  28. # ``import anthropic`` is deliberately NOT at module top: the SDK costs ~220 ms of imports and
  29. # every usage site is a cold user-triggered path. ``...`` = not yet tried; None = tried, missing.
  30. _anthropic_sdk: Any = ...
  31. # Why the lazy install did not make the SDK importable. A completed install that needs a restart
  32. # (PM activates a new dependency environment only at boot) must not be reported as "install it".
  33. _anthropic_install_error: Optional[Exception] = None
  34. def _get_anthropic_sdk():
  35. """Return the ``anthropic`` SDK module, importing lazily. None if not installed."""
  36. global _anthropic_sdk, _anthropic_install_error
  37. if _anthropic_sdk is ...:
  38. try:
  39. from pm import ensure_import
  40. ensure_import("anthropic")
  41. except Exception as exc: # the import below decides; exc explains a miss
  42. _anthropic_install_error = exc
  43. try:
  44. import anthropic as _sdk
  45. _anthropic_sdk = _sdk
  46. except ImportError:
  47. _anthropic_sdk = None
  48. return _anthropic_sdk
  49. def _require_sdk(purpose: str, verb: str = "Install it with"):
  50. """``_get_anthropic_sdk()`` or ImportError naming the feature that needs it."""
  51. sdk = _get_anthropic_sdk()
  52. if sdk is None and _anthropic_install_error is not None:
  53. raise ImportError(f"The 'anthropic' package is required for {purpose}: "
  54. f"{_anthropic_install_error}") from _anthropic_install_error
  55. if sdk is None:
  56. raise ImportError(f"The 'anthropic' package is required for {purpose}. {verb}: "
  57. f"{install_hint('anthropic')}")
  58. return sdk
  59. logger = logging.getLogger(__name__)
  60. THINKING_BUDGET = {"xhigh": 32000, "high": 16000, "medium": 8000, "low": 4000}
  61. # Hermes effort -> Anthropic adaptive-thinking effort (output_config.effort). 4.7+ exposes
  62. # low/medium/high/xhigh/max; Opus/Sonnet 4.6 have no xhigh, so callers downgrade xhigh->max
  63. # there (see _supports_xhigh_effort). "minimal" is a legacy alias for low on every model.
  64. ADAPTIVE_EFFORT_MAP = {
  65. "ultra": "max", "max": "max", "xhigh": "xhigh", "high": "high", "medium": "medium", "low": "low",
  66. "minimal": "low",
  67. }
  68. # Thinking-mode classification. Claude 4.6 replaced budget-based extended thinking with *adaptive*
  69. # thinking; 4.7 additionally forbids the manual ``thinking`` block and drops temperature/top_p/
  70. # top_k. Newer releases share no common version substring, so an allowlist of "modern" versions
  71. # would go stale and silently route a new model down the legacy path: unknown Claude models
  72. # DEFAULT to the modern contract and only explicit *legacy* lists are kept (mirroring
  73. # _get_anthropic_max_output's default-to-newest). Non-Claude Anthropic-Messages models (minimax,
  74. # qwen3, GLM, ...) fall through to the legacy manual-thinking path, which they need.
  75. # Older Claude families that need manual thinking (budget_tokens only); ``claude-3`` covers
  76. # 3/3.5/3.7 and the ``-2025`` entries are date-stamped 4.0 ids.
  77. _LEGACY_MANUAL_THINKING_CLAUDE_SUBSTRINGS = (
  78. "claude-3", "claude-opus-4-0", "claude-opus-4.0", "claude-opus-4-1", "claude-opus-4.1",
  79. "claude-sonnet-4-0", "claude-sonnet-4.0", "claude-opus-4-2025", "claude-sonnet-4-2025",
  80. "claude-opus-4-5", "claude-opus-4.5", "claude-sonnet-4-5", "claude-sonnet-4.5", "claude-haiku-4-5",
  81. "claude-haiku-4.5",
  82. )
  83. # Adaptive families that reject the "xhigh" effort (arrived with Opus 4.7) and still accept
  84. # sampling params.
  85. _NO_XHIGH_CLAUDE_SUBSTRINGS = ("claude-opus-4-6", "claude-opus-4.6", "claude-sonnet-4-6", "claude-sonnet-4.6")
  86. # Adaptive families where thinking is mandatory: ``thinking: {"type": "disabled"}`` answers HTTP
  87. # 400 (Portal flags them ``reasoning.mandatory``). The failure is asymmetric — a missing entry
  88. # 400s the turn, a spurious one only leaves thinking on — so when in doubt, add the family.
  89. _MANDATORY_THINKING_CLAUDE_SUBSTRINGS = ("claude-fable", "claude-mythos", "claude-opus-5-5", "claude-opus-5.5")
  90. # Families whose documented "off" is ``thinking: {"type": "between_tools"}`` (no up-front thinking,
  91. # short notes between tool calls): ``disabled`` 400s there with a message pointing at it.
  92. _BETWEEN_TOOLS_OFF_CLAUDE_SUBSTRINGS = ("claude-sonnet-5-5", "claude-sonnet-5.5")
  93. def _is_claude_model(model: str | None) -> bool:
  94. return "claude" in (model or "").lower()
  95. def _model_matches(model: str, substrings) -> bool:
  96. """Case-insensitive substring match of ``model`` against a family list."""
  97. m = model.lower()
  98. return any(v in m for v in substrings)
  99. # Max output tokens per model (Anthropic docs + Cline catalog). Anthropic requires max_tokens; a
  100. # fixed 16384 starved thinking-enabled models (thinking tokens count toward the limit).
  101. # ``claude-fable`` = Mythos-class named models (1M context); ``minimax`` is a third-party
  102. # Anthropic-compatible endpoint; DashScope enforces ``qwen3`` max_tokens in [1, 65536].
  103. _ANTHROPIC_OUTPUT_LIMITS = {
  104. "claude-fable": 128_000, "claude-sonnet-5": 128_000, "claude-opus-4-8": 128_000,
  105. "claude-opus-4-7": 128_000, "claude-opus-4-6": 128_000, "claude-sonnet-4-6": 64_000,
  106. "claude-opus-4-5": 64_000, "claude-sonnet-4-5": 64_000, "claude-haiku-4-5": 64_000,
  107. "claude-opus-4": 32_000, "claude-sonnet-4": 64_000, "claude-3-7-sonnet": 128_000,
  108. "claude-3-5-sonnet": 8_192, "claude-3-5-haiku": 8_192, "claude-3-opus": 4_096,
  109. "claude-3-sonnet": 4_096, "claude-3-haiku": 4_096, "minimax": 131_072, "qwen3": 65_536,
  110. }
  111. # Unknown models get the highest current limit: future models are unlikely to have *less*.
  112. _ANTHROPIC_DEFAULT_OUTPUT_LIMIT = 128_000
  113. def _get_anthropic_max_output(model: str) -> int:
  114. """Max output tokens for ``model`` via longest substring match against
  115. ``_ANTHROPIC_OUTPUT_LIMITS`` (so date-stamped ids and ``:1m``/``:fast`` suffixes resolve, and
  116. ``claude-3-5-sonnet`` beats ``claude-3-5``). Dots normalize to hyphens (``claude-opus-4.6``)."""
  117. m = model.lower().replace(".", "-")
  118. best_key = max((key for key in _ANTHROPIC_OUTPUT_LIMITS if key in m), key=len, default=None)
  119. return _ANTHROPIC_OUTPUT_LIMITS[best_key] if best_key else _ANTHROPIC_DEFAULT_OUTPUT_LIMIT
  120. def _resolve_positive_anthropic_max_tokens(value) -> Optional[int]:
  121. """``value`` floored to a positive int, or None when it is not a finite positive number.
  122. Anthropic 400s on max_tokens that are 0, negative, fractional or non-finite; the ``max_tokens
  123. or fallback`` idiom catches 0 but lets ``-1``/``0.5`` through. Booleans are excluded (they
  124. subclass int)."""
  125. if isinstance(value, bool) or not isinstance(value, (int, float)):
  126. return None
  127. try:
  128. if not math.isfinite(value):
  129. return None
  130. except Exception: # e.g. OverflowError for ints too large for float
  131. return None
  132. return int(value) if int(value) > 0 else None # int() truncates toward zero for floats
  133. def _resolve_anthropic_messages_max_tokens(requested, model: str, context_length: Optional[int] = None) -> int:
  134. """``requested`` when it is a positive finite number, else the model's output ceiling. Raises
  135. ValueError if neither is positive. The context-window clamp is the caller's job so the
  136. positive-value contract stays endpoint-agnostic."""
  137. resolved = _resolve_positive_anthropic_max_tokens(requested) or _get_anthropic_max_output(model)
  138. if resolved > 0:
  139. return resolved
  140. raise ValueError(
  141. f"Anthropic Messages adapter requires a positive max_tokens value for "
  142. f"model {model!r}; got {requested!r} and no model default resolved."
  143. )
  144. def _supports_adaptive_thinking(model: str) -> bool:
  145. """True for Claude models using adaptive thinking (4.6+): unknown Claude models default to
  146. adaptive, the explicit legacy list stays manual, and non-Claude models return False — except
  147. Kimi/Moonshot, whose Anthropic-compatible endpoints implement the adaptive contract."""
  148. return _model_name_is_kimi_family(model) or (
  149. _is_claude_model(model) and not _model_matches(model, _LEGACY_MANUAL_THINKING_CLAUDE_SUBSTRINGS)
  150. )
  151. def _supports_xhigh_effort(model: str) -> bool:
  152. """True for models accepting the 'xhigh' effort (Opus 4.7+). Opus/Sonnet 4.6 400 on it —
  153. callers downgrade xhigh->max when this returns False."""
  154. return _supports_adaptive_thinking(model) and not _model_matches(model, _NO_XHIGH_CLAUDE_SUBSTRINGS)
  155. def _accepts_thinking_disable(model: str) -> bool:
  156. """True when ``model`` accepts an explicit ``thinking: {"type": "disabled"}``. Adaptive Claude
  157. thinks by default, so "off" only works if the disable is sent; mandatory-thinking families
  158. 400 on it and keep the omit behavior. Legacy manual-thinking models are opt-in via
  159. budget_tokens, so omission is already off. Scoped to Claude: Kimi's documented disable is
  160. omission, and sending it a new parameter on the strength of Claude's contract is a guess."""
  161. return (
  162. _is_claude_model(model)
  163. and _supports_adaptive_thinking(model)
  164. and not _model_matches(model, _MANDATORY_THINKING_CLAUDE_SUBSTRINGS + _BETWEEN_TOOLS_OFF_CLAUDE_SUBSTRINGS)
  165. )
  166. def _is_pre_thinking_haiku(model: str) -> bool:
  167. """Haiku generations that never get a thinking request (through 4.5). Haiku 5.5+ uses adaptive thinking."""
  168. from agent.anthropic_thinking_policy import claude_family_version
  169. if "haiku" not in model.lower():
  170. return False
  171. parsed = claude_family_version(model)
  172. return parsed is None or parsed[0] != "haiku" or parsed[1] < (5, 5)
  173. def _forbids_sampling_params(model: str) -> bool:
  174. """True for models that 400 on any non-default temperature/top_p/top_k (Opus 4.7 and later;
  175. unknown Claude defaults to forbidding). The 4.6 family and the legacy manual-thinking families
  176. still accept them. Callers omit the fields entirely — the API rejects anything non-null."""
  177. return _is_claude_model(model) and not _model_matches(
  178. model, _NO_XHIGH_CLAUDE_SUBSTRINGS + _LEGACY_MANUAL_THINKING_CLAUDE_SUBSTRINGS
  179. )
  180. def _supports_fast_mode(model: str) -> bool:
  181. """True for models accepting ``speed: "fast"`` (Opus 4.8 / Opus 5 / Opus 5.5, Claude API only).
  182. The list lives in ``agent.model_metadata`` so the wire gate and the ``/fast`` toggle agree."""
  183. from agent.model_metadata import is_anthropic_fast_mode_model
  184. return is_anthropic_fast_mode_model(model)
  185. # Beta headers safe on ordinary/native Anthropic requests. GA on Claude 4.6+ (harmless no-op
  186. # there) but older Claude and compatible endpoints still gate on them. Do NOT add
  187. # ``context-1m-2025-08-07``: accounts without the long-context beta get HTTP 400, breaking short
  188. # auxiliary calls. Bedrock/Azure still need it for 1M context and opt in on their own paths.
  189. # MiniMax's Anthropic-compatible endpoints fail tool-use requests when the tool-streaming beta is
  190. # present. ``_FAST_MODE_BETA`` enables the ``speed: "fast"`` request parameter.
  191. _TOOL_STREAMING_BETA = "fine-grained-tool-streaming-2025-05-14"
  192. _COMMON_BETAS = ["interleaved-thinking-2025-05-14", _TOOL_STREAMING_BETA]
  193. _CONTEXT_1M_BETA = "context-1m-2025-08-07"
  194. _FAST_MODE_BETA = "fast-mode-2026-02-01"
  195. # Required for OAuth/subscription auth; matches Claude Code / pi-ai / OpenCode.
  196. _OAUTH_ONLY_BETAS = ["claude-code-20250219", "oauth-2025-04-20"]
  197. # Claude Code identity — OAuth requests without it intermittently 500. Anthropic rejects OAuth
  198. # requests whose user-agent version is too far behind the actual release, so the installed
  199. # version is detected and this fallback kept current.
  200. _CLAUDE_CODE_VERSION_FALLBACK = "2.1.74"
  201. _claude_code_version_cache: Optional[str] = None
  202. # Install prefixes probed in addition to PATH. GUI launches (the Electron desktop app, macOS
  203. # LaunchAgents) inherit the bare ``/usr/bin:/bin:/usr/sbin:/sbin``, which carries none of these,
  204. # so a PATH-only lookup finds nothing there even with the CLI installed — detection then returns
  205. # the stale fallback and Anthropic 400s with "Claude Code X does not support this model".
  206. # These are additive: on Windows none resolve to a file and detection falls back to the PATH
  207. # lookup (which handles PATHEXT), leaving current behaviour there unchanged.
  208. _CLAUDE_CODE_PREFIXES = (
  209. "~/.local/bin", "~/.claude/local", "~/bin", "~/.npm-global/bin", "~/.bun/bin",
  210. "~/.volta/bin", "/opt/homebrew/bin", "/usr/local/bin",
  211. )
  212. _CLAUDE_CODE_NAMES = ("claude", "claude-code")
  213. def _claude_code_candidates() -> list[str]:
  214. """Executable paths to try, deduped and filtered to files that exist.
  215. Two passes: every PATH hit first (what the user's shell would run), then the
  216. well-known install prefixes. A single nested loop would probe a stale prefix
  217. ``claude`` before a current PATH ``claude-code``.
  218. """
  219. seen: dict[str, None] = {}
  220. for name in _CLAUDE_CODE_NAMES:
  221. hit = shutil.which(name)
  222. if hit:
  223. seen.setdefault(hit)
  224. for prefix in _CLAUDE_CODE_PREFIXES:
  225. for name in _CLAUDE_CODE_NAMES:
  226. path = os.path.join(os.path.expanduser(prefix), name)
  227. if os.path.isfile(path):
  228. seen.setdefault(path)
  229. return list(seen)
  230. def find_claude_code_cli(command: str) -> Optional[str]:
  231. """Path of a bare Claude Code command name on PATH, else in an install prefix; None for any other command.
  232. Core's own presence checks (external-process providers, ``claude setup-token``) ask this so they
  233. agree with version detection about whether the CLI is installed under a GUI/service PATH."""
  234. if command not in _CLAUDE_CODE_NAMES:
  235. return None
  236. from hermes_platform.resolver import locate_command
  237. found = locate_command(command, known_dirs=_CLAUDE_CODE_PREFIXES).command
  238. return found[0] if found else None
  239. def _detect_claude_code_version() -> str:
  240. """Installed Claude Code version (``claude --version``), else the static fallback."""
  241. for cmd in _claude_code_candidates():
  242. with suppress(Exception):
  243. result = subprocess.run(
  244. [cmd, "--version"],
  245. stdin=subprocess.DEVNULL, capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=5,
  246. check=False,
  247. )
  248. if result.returncode == 0 and result.stdout.strip():
  249. version = result.stdout.strip().split()[0] # "2.1.74 (Claude Code)" or "2.1.74"
  250. if version and version[0].isdigit():
  251. return version
  252. return _CLAUDE_CODE_VERSION_FALLBACK
  253. def _get_claude_code_version() -> str:
  254. """Detect lazily (only OAuth headers need it) and cache for the process."""
  255. global _claude_code_version_cache
  256. if _claude_code_version_cache is None:
  257. _claude_code_version_cache = _detect_claude_code_version()
  258. return _claude_code_version_cache
  259. _CLAUDE_CODE_SYSTEM_PREFIX = "You are Claude Code, Anthropic's official CLI for Claude."
  260. _MCP_TOOL_PREFIX = "mcp__"
  261. # Anthropic's OAuth billing classifier fingerprints certain Hermes tool schemas/prose as a
  262. # third-party app and reroutes to the metered extra-usage lane (HTTP 400 "You're out of extra
  263. # usage" on a valid subscription). Live A/B repros isolated two independent triggers — the
  264. # ``session_search`` tool (schema/name/prose) and the ``memory`` tool (schema/name) — so both are
  265. # aliased on the OAuth wire only; normalize_response reverses the mapping.
  266. _OAUTH_TOOL_NAME_ALIASES = {"session_search": "chat_history_lookup", "memory": "context_notes"}
  267. _OAUTH_TOOL_NAME_REVERSE_ALIASES = {wire_name: name for name, wire_name in _OAUTH_TOOL_NAME_ALIASES.items()}
  268. # Aliases ALSO safe to substitute in free-form prose (system prompt, tool descriptions). "memory"
  269. # is ordinary English throughout the prompt and inside the memory tool's own parameter docs (an
  270. # enum the model must emit verbatim), so rewriting it would corrupt guidance; a model that calls
  271. # bare ``memory`` still dispatches, since normalize_response resolves it through the registry.
  272. _OAUTH_PROSE_ALIAS_NAMES = frozenset({"session_search"})
  273. # Word-boundary matchers so a longer identifier containing the token (e.g.
  274. # ``tools/session_search_tool.py`` in AGENTS.md) is left alone; ``\b`` treats ``_`` as a word char.
  275. _OAUTH_PROSE_ALIAS_PATTERNS = tuple(
  276. (re.compile(rf"\b{re.escape(name)}\b"), _OAUTH_TOOL_NAME_ALIASES[name])
  277. for name in sorted(_OAUTH_PROSE_ALIAS_NAMES)
  278. )
  279. def _apply_oauth_prose_aliases(text: str) -> str:
  280. """Rewrite prose-safe tool-name tokens to their OAuth wire aliases."""
  281. for pattern, wire_name in _OAUTH_PROSE_ALIAS_PATTERNS:
  282. text = pattern.sub(wire_name, text)
  283. return text
  284. def _common_betas_for_base_url(base_url: str | None, *, drop_context_1m_beta: bool = False) -> list[str]:
  285. """Beta headers safe for the configured endpoint. MiniMax (Bearer-auth) rejects both the
  286. fine-grained-tool-streaming beta (every tool-use message errors) and the 1M-context beta.
  287. Azure AI Foundry also uses Bearer auth but keeps both — it needs the 1M beta for 1M context,
  288. which native Anthropic does not get by default (some subscriptions reject it; Bedrock opts in
  289. via its own client helper). ``drop_context_1m_beta`` strips the 1M beta after a
  290. subscription/endpoint rejected it."""
  291. betas = list(_COMMON_BETAS)
  292. if _base_url_needs_context_1m_beta(base_url) and not drop_context_1m_beta:
  293. betas.append(_CONTEXT_1M_BETA)
  294. if _is_minimax_anthropic_endpoint(base_url):
  295. return [b for b in betas if b not in (_TOOL_STREAMING_BETA, _CONTEXT_1M_BETA)]
  296. return betas
  297. def _beta_header(betas: list) -> dict[str, str]:
  298. """``{"anthropic-beta": ...}`` when there are betas, else ``{}``."""
  299. return {"anthropic-beta": ",".join(betas)} if betas else {}
  300. def _attribution_headers() -> dict[str, str]:
  301. """Same client-attribution set sent to OpenRouter / Vercel AI Gateway / Fireworks."""
  302. return {
  303. "HTTP-Referer": "https://hermes-agent.nousresearch.com", "X-Title": "Hermes Agent",
  304. "User-Agent": f"HermesAgent/{get_version_info().base_version}",
  305. }
  306. def _client_timeout(timeout):
  307. """httpx.Timeout with the caller's read timeout (default 900s) and a 10s connect."""
  308. from httpx import Timeout
  309. read = timeout if (isinstance(timeout, (int, float)) and timeout > 0) else 900.0
  310. return Timeout(timeout=float(read), connect=10.0)
  311. def _base_client_kwargs(base_url, timeout) -> tuple[str, dict[str, Any]]:
  312. """Shared SDK constructor kwargs -> ``(normalized_base_url, kwargs)``. Retry is delegated to
  313. hermes's outer loop (``max_retries=0``): the SDK default of 2 uses its own backoff that ignores
  314. Retry-After and double-retries inside our loop. Any trailing ``/v1`` is stripped because the
  315. SDK appends ``/v1/messages``. Azure's ``api-version`` goes through ``default_query`` so the
  316. base_url is not corrupted into ``/anthropic?api-version=.../v1/messages``."""
  317. kwargs: dict[str, Any] = {"timeout": _client_timeout(timeout), "max_retries": 0}
  318. normalized = re.sub(r"/v1/?$", "", _normalize_base_url_text(base_url).rstrip("/"))
  319. if normalized:
  320. kwargs["base_url"] = normalized
  321. if _is_azure_anthropic_endpoint(normalized) and "api-version" not in normalized:
  322. kwargs["default_query"] = {"api-version": "2025-04-15"}
  323. return normalized, kwargs
  324. def _build_anthropic_client_with_bearer_hook(
  325. token_provider, base_url: str | None = None, timeout: float | None = None, *, drop_context_1m_beta: bool = False
  326. ):
  327. """Anthropic-on-Foundry Entra ID variant of :func:`build_anthropic_client`. The SDK stores
  328. ``api_key``/``auth_token`` as static strings, so per-request bearer refresh (Microsoft's
  329. documented Foundry pattern) uses a custom ``httpx.Client`` whose request hook mints a fresh JWT
  330. and rewrites ``Authorization``; the SDK skips its own auth when ``http_client`` is given. The
  331. placeholder ``auth_token`` is still required at construction and makes any leak diagnosable."""
  332. sdk = _require_sdk("Azure Foundry Anthropic-style endpoints with Entra ID auth", verb="Install with")
  333. normalize_proxy_env_vars()
  334. from agent.azure_identity_adapter import build_bearer_http_client
  335. normalized_base_url, kwargs = _base_client_kwargs(base_url, timeout)
  336. # A key_cmd on the native host can print a Console API key, which (as in the static path's
  337. # _auth_style) belongs in x-api-key; OAuth tokens and Azure/third-party routes keep Bearer. The
  338. # auth header follows each mint, the OAuth identity below the first one: a key_cmd switching
  339. # between OAuth and a Console key mid-session needs a client rebuild.
  340. kwargs["http_client"] = build_bearer_http_client(
  341. token_provider, timeout=kwargs["timeout"],
  342. sends_as_api_key=(lambda token: not _is_oauth_token(token)) if is_native_anthropic_host(base_url) else None,
  343. )
  344. kwargs["auth_token"] = "entra-id-bearer-via-http-hook"
  345. betas = _common_betas_for_base_url(normalized_base_url, drop_context_1m_beta=drop_context_1m_beta)
  346. if anthropic_route_is_oauth(base_url, token_provider):
  347. # key_cmd-sourced Claude Code OAuth on the native host: a bare bearer without the Claude Code
  348. # identity is answered with 429 rate_limit_error "Error" (#114967) — same headers as the
  349. # static "oauth" style in build_anthropic_client.
  350. headers = _beta_header(betas + _OAUTH_ONLY_BETAS)
  351. headers["user-agent"] = f"claude-code/{_get_claude_code_version()} (external, cli)"
  352. headers["x-app"] = "cli"
  353. else:
  354. headers = _beta_header(betas)
  355. return _new_sdk_client(sdk, kwargs, headers, route=base_url)
  356. def _new_sdk_client(sdk, kwargs: dict[str, Any], headers: dict[str, str], route: str | None = None):
  357. """``sdk.Anthropic(**kwargs)`` with ``headers`` attached, sending exactly ONE credential.
  358. ``route`` is the caller's un-normalized base_url (the ``/v1`` form ``custom_providers`` entries are
  359. keyed by; ``kwargs["base_url"]`` has it stripped) for the per-provider ``extra_headers`` lookup.
  360. The SDK fills whichever of ``api_key`` / ``auth_token`` we left unset from ANTHROPIC_API_KEY /
  361. ANTHROPIC_AUTH_TOKEN in the environment (both loaded from ~/.hermes/.env) and then sends dual
  362. auth — x-api-key *and* Authorization: Bearer — shipping a foreign credential to Portal / MiniMax
  363. / OAuth / Entra / third-party endpoints (#26970, #105774). An ``Omit()`` default header is the
  364. SDK-sanctioned way to drop the other header, and unlike an attribute clear it survives
  365. ``with_options()``, which re-runs the constructor and re-reads the environment."""
  366. merged = dict(headers)
  367. if "api_key" in kwargs and "auth_token" not in kwargs:
  368. merged["Authorization"] = sdk.Omit()
  369. elif "auth_token" in kwargs and "api_key" not in kwargs:
  370. merged["X-Api-Key"] = sdk.Omit()
  371. # Per-provider ``custom_providers[].extra_headers`` last: the most specific config level wins
  372. # over the SDK User-Agent and the attribution/beta sets above, on every builder path (init,
  373. # /model switch, rebuild, auxiliary) — the OpenAI-wire clients already do this (#24293, #9721).
  374. merged.update(_custom_provider_extra_headers(route or kwargs.get("base_url")))
  375. if merged:
  376. kwargs["default_headers"] = merged
  377. return sdk.Anthropic(**kwargs)
  378. def _custom_provider_extra_headers(base_url) -> dict[str, str]:
  379. """``extra_headers`` of the ``custom_providers`` entry routed at *base_url*, else ``{}``.
  380. SECURITY: values routinely carry credentials (Cloudflare Access tokens) — never log them."""
  381. if not base_url:
  382. return {}
  383. try:
  384. from hermes_cli.config import get_custom_provider_extra_headers
  385. return get_custom_provider_extra_headers(str(base_url))
  386. except Exception:
  387. logger.debug("custom-provider extra_headers skipped for Anthropic client", exc_info=True)
  388. return {}
  389. def _auth_style(api_key, base_url, normalized_base_url) -> str:
  390. """Order-sensitive endpoint/key classification for :func:`build_anthropic_client`. ``kimi``:
  391. Kimi's /coding endpoint 403s without a User-Agent (the Kimi team asked for proper attribution).
  392. ``bearer``: MiniMax & co. want Authorization: Bearer — checked before the OAuth shape test
  393. because their secrets lack the sk-ant-api prefix and would be misread as OAuth/setup tokens.
  394. ``api_key``: third-party proxies use their own x-api-key keys (skip OAuth detection). ``oauth``:
  395. Bearer auth + Claude Code identity (Anthropic routes OAuth by user-agent; without it, 500s)."""
  396. if _is_kimi_coding_endpoint(base_url):
  397. return "kimi"
  398. if _requires_bearer_auth(normalized_base_url):
  399. return "bearer"
  400. if _is_third_party_anthropic_endpoint(base_url):
  401. return "api_key"
  402. if _is_oauth_token(api_key):
  403. return "oauth"
  404. return "api_key"
  405. def build_anthropic_client(api_key, base_url: str | None = None, timeout: float | None = None, *, drop_context_1m_beta: bool = False):
  406. """Create an Anthropic client, auto-detecting setup-tokens vs API keys. ``api_key`` is a static
  407. ``str`` or a ``Callable[[], str]`` Entra ID bearer provider (routed through
  408. :func:`_build_anthropic_client_with_bearer_hook`). ``timeout`` overrides the 900s read timeout
  409. (connect stays 10s). ``drop_context_1m_beta`` strips ``context-1m-2025-08-07`` from the
  410. client-level beta header — the reactive OAuth retry in run_agent uses it after a subscription
  411. rejects it; fresh clients keep the default so 1M-capable subscriptions keep the capability."""
  412. sdk = _require_sdk("the Anthropic provider")
  413. if callable(api_key) and not isinstance(api_key, str):
  414. return _build_anthropic_client_with_bearer_hook(
  415. api_key, base_url, timeout, drop_context_1m_beta=drop_context_1m_beta
  416. )
  417. normalize_proxy_env_vars()
  418. normalized_base_url, kwargs = _base_client_kwargs(base_url, timeout)
  419. if "default_query" in kwargs: # historical: this path also strips a stray trailing slash on Azure
  420. kwargs["base_url"] = normalized_base_url.rstrip("/")
  421. common_betas = _common_betas_for_base_url(normalized_base_url, drop_context_1m_beta=drop_context_1m_beta)
  422. style = _auth_style(api_key, base_url, normalized_base_url)
  423. kwargs["auth_token" if style in ("bearer", "oauth") else "api_key"] = api_key
  424. headers = _beta_header(common_betas + _OAUTH_ONLY_BETAS if style == "oauth" else common_betas)
  425. if style == "kimi":
  426. headers = {**_attribution_headers(), **headers}
  427. elif style == "oauth":
  428. headers["user-agent"] = f"claude-code/{_get_claude_code_version()} (external, cli)"
  429. headers["x-app"] = "cli"
  430. if _is_opencode_endpoint(base_url):
  431. # OpenCode identifies clients by request headers (like OpenRouter). The OpenAI-wire paths
  432. # get these from profile.default_headers, but this route never sees the profile.
  433. for k, v in _attribution_headers().items():
  434. headers.setdefault(k, v)
  435. return _new_sdk_client(sdk, kwargs, headers, route=base_url)
  436. def build_anthropic_bedrock_client(region: str, timeout: float | None = None):
  437. """AnthropicBedrock client for Bedrock Claude models (boto3 default credential chain). The
  438. SDK's native Bedrock adapter gives full Claude feature parity (prompt caching, thinking
  439. budgets, adaptive thinking, fast mode) that Converse lacks. The common betas plus
  440. ``context-1m-2025-08-07`` are attached: without the latter Bedrock caps Opus 4.6/4.7 at 200K.
  441. A configured ``bedrock.guardrail`` rides as InvokeModel headers so every client built here
  442. (primary, auxiliary, per-request rebuild) enforces it. ``timeout`` is the resolved
  443. ``providers.bedrock`` request timeout; None keeps the 900s read / 10s connect default."""
  444. from agent.bedrock_adapter import bedrock_guardrail_headers, scoped_aws_session_kwargs
  445. sdk = _require_sdk("the Bedrock provider")
  446. if not hasattr(sdk, "AnthropicBedrock"):
  447. raise ImportError("anthropic.AnthropicBedrock not available. Run: hermes pm repair")
  448. # Routed multiplex profile: its own AWS_* from the secret scope (the SDK would otherwise read the
  449. # launch profile's process env); unscoped passes nothing and keeps the default chain.
  450. scoped = scoped_aws_session_kwargs()
  451. aws_kwargs = {"aws_access_key": scoped.get("aws_access_key_id"), "aws_secret_key": scoped.get("aws_secret_access_key"),
  452. "aws_session_token": scoped.get("aws_session_token"), "aws_profile": scoped.get("profile_name")}
  453. return sdk.AnthropicBedrock(
  454. aws_region=region, timeout=_client_timeout(timeout), **{k: v for k, v in aws_kwargs.items() if v},
  455. max_retries=0, # retry belongs to hermes's outer loop (honors Retry-After)
  456. default_headers={**_beta_header([*_COMMON_BETAS, _CONTEXT_1M_BETA]), **bedrock_guardrail_headers()},
  457. )
  458. def _normalize_to_mcp_wire(name: str) -> str:
  459. """OAuth wire form of a tool name (no aliasing): ``mcp__<...>``. Anthropic's OAuth billing
  460. classifier treats a single-underscore ``mcp_`` tool name as a third-party-app fingerprint
  461. (HTTP 400 "Third-party apps now draw from extra usage"); ``mcp__foo`` is accepted. Both bare
  462. Hermes tools (``read_file``) and native MCP tools registered as ``mcp_<server>_<tool>`` must
  463. land on the double-underscore form. normalize_response reverses both via registry lookup."""
  464. if name.startswith("mcp__"):
  465. return name # already correct, don't double-prefix
  466. return _MCP_TOOL_PREFIX + name.removeprefix("mcp_")
  467. def _oauth_wire_namer(anthropic_tools: list[dict[str, Any]]):
  468. """Return ``name -> OAuth wire name`` for this request's tool set. An alias must never collide
  469. with a wire name owned by a non-alias tool: two identical tool names in one request is a hard
  470. 400, strictly worse than the bug being fixed. Mirrors normalize_response's "registered tool
  471. wins" so outbound and inbound agree on who owns a contested name."""
  472. claimed = {
  473. _normalize_to_mcp_wire(tool["name"])
  474. for tool in (anthropic_tools or [])
  475. if isinstance(tool.get("name"), str) and tool["name"] not in _OAUTH_TOOL_NAME_ALIASES
  476. }
  477. def to_wire(name: str) -> str:
  478. aliased = _OAUTH_TOOL_NAME_ALIASES.get(name)
  479. if aliased and _MCP_TOOL_PREFIX + aliased not in claimed:
  480. name = aliased
  481. return _normalize_to_mcp_wire(name)
  482. return to_wire
  483. _OAUTH_SYSTEM_REPLACEMENTS = (
  484. ("Hermes Agent", "Claude Code"), ("Hermes agent", "Claude Code"), ("Nous Research", "Anthropic"),
  485. )
  486. # The slug is rewritten only as a standalone prose word. Joined to a host, path, repo, mailbox
  487. # or quoted as an identifier (``hermes-agent.nousresearch.com``, ``~/.hermes/hermes-agent/venv``,
  488. # ``NousResearch/hermes-agent``, ``skill_view(name='hermes-agent')``) it is an address the model
  489. # dereferences, and the rewritten form does not exist (#48860). The OPENING quote marks an
  490. # identifier; a sentence-final ``.`` or a possessive ``'s`` is prose.
  491. _OAUTH_SLUG_PATTERN = re.compile(r"""(?<![\w./:@'"`-])hermes-agent(?![\w/@-]|\.\w)""")
  492. def _apply_claude_code_identity(system, anthropic_tools, anthropic_messages, to_wire):
  493. """OAuth transforms: Claude Code system prefix, product-name sanitizing (avoids server-side
  494. content filters), tool/description aliasing, and the same tool renames on replayed tool_use
  495. blocks so history matches ``tools[]``. Returns the new ``system``; tools and messages are
  496. mutated in place."""
  497. cc_block = {"type": "text", "text": _CLAUDE_CODE_SYSTEM_PREFIX}
  498. if isinstance(system, str) and system:
  499. system = [{"type": "text", "text": system}]
  500. system = [cc_block] + (system if isinstance(system, list) else [])
  501. for block in system:
  502. if isinstance(block, dict) and block.get("type") == "text":
  503. text = block.get("text", "")
  504. for old, new in _OAUTH_SYSTEM_REPLACEMENTS:
  505. text = text.replace(old, new)
  506. text = _OAUTH_SLUG_PATTERN.sub("claude-code", text)
  507. block["text"] = _apply_oauth_prose_aliases(text)
  508. for tool in anthropic_tools or []:
  509. if "name" in tool:
  510. tool["name"] = to_wire(tool["name"])
  511. if isinstance(tool.get("description"), str):
  512. tool["description"] = _apply_oauth_prose_aliases(tool["description"]) # prose-safe aliases only
  513. for msg in anthropic_messages:
  514. for block in msg.get("content") if isinstance(msg.get("content"), list) else []:
  515. if isinstance(block, dict) and block.get("type") == "tool_use" and "name" in block:
  516. block["name"] = to_wire(block["name"]) # tool_result pairs by id, not name
  517. return system
  518. def _thinking_kwargs(reasoning_config: dict[str, Any], model: str, effective_max_tokens: int) -> dict[str, Any]:
  519. """Map ``reasoning_config`` to Anthropic thinking kwargs. Adaptive models (Claude 4.6+,
  520. Kimi/Moonshot) get ``thinking.type=adaptive`` + ``output_config.effort``; older models and
  521. manual-only compat endpoints (MiniMax) get budget_tokens. Haiku through 4.5 gets none. On
  522. 4.7+ ``thinking.display`` defaults to "omitted", hiding the reasoning Hermes shows in its CLI,
  523. so "summarized" is requested to keep the activity feed populated."""
  524. if reasoning_config.get("enabled") is False:
  525. # Adaptive models think by DEFAULT, so omitting the parameter is not a disable — the user
  526. # silently keeps paying. Mandatory-thinking models 400 on the disable, so they keep the
  527. # omission: a silently-ignored disable beats a dead turn.
  528. if _model_matches(model, _BETWEEN_TOOLS_OFF_CLAUDE_SUBSTRINGS):
  529. return {"thinking": {"type": "between_tools"}}
  530. return {"thinking": {"type": "disabled"}} if _accepts_thinking_disable(model) else {}
  531. if _is_pre_thinking_haiku(model):
  532. return {}
  533. effort = str(reasoning_config.get("effort", "medium")).lower()
  534. if _supports_adaptive_thinking(model):
  535. adaptive_effort = ADAPTIVE_EFFORT_MAP.get(effort, "medium")
  536. if adaptive_effort == "xhigh" and not _supports_xhigh_effort(model):
  537. adaptive_effort = "max"
  538. return {"thinking": {"type": "adaptive", "display": "summarized"}, "output_config": {"effort": adaptive_effort}}
  539. budget = THINKING_BUDGET.get(effort, 8000)
  540. return {
  541. "thinking": {"type": "enabled", "budget_tokens": budget},
  542. "temperature": 1, # required when thinking is enabled on older models
  543. "max_tokens": max(effective_max_tokens, budget + 4096),
  544. }
  545. # OpenAI tool_choice -> Anthropic; any other string is a forced tool name.
  546. _TOOL_CHOICE_MAP = {None: {"type": "auto"}, "auto": {"type": "auto"}, "required": {"type": "any"}}
  547. def build_anthropic_kwargs(
  548. model: str, messages: list[dict], tools: Optional[list[dict]], max_tokens: Optional[int],
  549. reasoning_config: Optional[dict[str, Any]], tool_choice: Optional[str] = None,
  550. is_oauth: bool = False, preserve_dots: bool = False, context_length: Optional[int] = None,
  551. base_url: str | None = None, fast_mode: bool = False, drop_context_1m_beta: bool = False,
  552. ) -> dict[str, Any]:
  553. """Build kwargs for anthropic.messages.create(). ``max_tokens`` is the OUTPUT cap for one
  554. response; ``context_length`` is the TOTAL window (input + output). ``max_tokens=None`` uses the
  555. model's native output ceiling; if that exceeds ``context_length`` (small local endpoints) it is
  556. clamped to ``context_length - 1``. The clamp ignores prompt size — callers must catch
  557. "max_tokens too large given prompt" and retry smaller (parse_available_output_tokens_from_error).
  558. ``is_oauth`` applies Claude Code compatibility transforms; ``preserve_dots`` keeps model-name
  559. dots (DashScope: qwen3.5-plus); a third-party ``base_url`` strips thinking signatures;
  560. ``fast_mode`` adds ``extra_body.speed="fast"`` plus the fast-mode beta on native Anthropic only."""
  561. system, anthropic_messages = convert_messages_to_anthropic(messages, base_url=base_url, model=model)
  562. anthropic_tools = convert_tools_to_anthropic(tools) if tools else []
  563. # Nous Portal routes on its own catalog ids (``anthropic/claude-opus-4.8``); normalizing would
  564. # make the model unresolvable there (prefix AND dots kept).
  565. if not _is_nous_portal_endpoint(base_url):
  566. model = normalize_model_name(model, preserve_dots=preserve_dots)
  567. # Non-positive/non-finite values fail locally instead of 400-ing upstream.
  568. effective_max_tokens = _resolve_anthropic_messages_max_tokens(max_tokens, model, context_length=context_length)
  569. if context_length and effective_max_tokens > context_length:
  570. effective_max_tokens = max(context_length - 1, 1)
  571. to_wire = _oauth_wire_namer(anthropic_tools) if is_oauth else None
  572. if to_wire:
  573. system = _apply_claude_code_identity(system, anthropic_tools, anthropic_messages, to_wire)
  574. kwargs: dict[str, Any] = {"model": model, "messages": anthropic_messages, "max_tokens": effective_max_tokens}
  575. if system:
  576. kwargs["system"] = system
  577. if anthropic_tools:
  578. kwargs["tools"] = anthropic_tools
  579. if tool_choice == "none":
  580. kwargs.pop("tools", None) # no Anthropic "none" — omit tools to prevent use
  581. elif tool_choice is None or isinstance(tool_choice, str):
  582. # A forced tool name goes through the OAuth normalizer too: every tools[] entry is
  583. # mcp__-prefixed/aliased there, so the literal would leak and name a nonexistent tool.
  584. kwargs["tool_choice"] = _TOOL_CHOICE_MAP.get(tool_choice) or {
  585. "type": "tool", "name": to_wire(tool_choice) if to_wire else tool_choice
  586. }
  587. # Map reasoning_config to Anthropic's thinking parameter. Claude 4.6+ models use adaptive thinking +
  588. # output_config.effort. Older models use manual thinking with budget_tokens. MiniMax Anthropic-compat
  589. # endpoints support thinking (manual mode only, not adaptive). Haiku through 4.5 gets no thinking
  590. # request; Haiku 5.5+ is adaptive. Kimi / Moonshot models also use adaptive thinking: their Anthropic-compatible
  591. # endpoints (api.moonshot.cn/anthropic, api.kimi.com/coding) accept ``thinking.type="adaptive"`` +
  592. # ``output_config.effort``, and the replay-validation 400s that originally motivated dropping the
  593. # parameter (#13848) no longer occur. (Kimi on chat_completions enables thinking via extra_body in the
  594. # ChatCompletionsTransport — see #13503.) On 4.7+ the `thinking.display` field defaults to "omitted",
  595. # which silently hides reasoning text that Hermes surfaces in its CLI. We request "summarized" so the
  596. # reasoning blocks stay populated — matching 4.6 behavior and preserving the activity-feed UX during
  597. # long tool runs.
  598. if reasoning_config and isinstance(reasoning_config, dict):
  599. kwargs.update(_thinking_kwargs(reasoning_config, model, effective_max_tokens))
  600. # Safety net so upstream 4.6 -> 4.7 migrations don't need coordinated edits everywhere callers
  601. # (auxiliary_client, ...) set sampling params.
  602. if _forbids_sampling_params(model):
  603. for key in ("temperature", "top_p", "top_k"):
  604. kwargs.pop(key, None)
  605. # Fast mode: native Anthropic only — third-party providers reject the unknown beta/param and
  606. # Anthropic scopes it to the Claude API (not Bedrock/Vertex/Foundry). Per-request extra_headers
  607. # OVERRIDE the client-level anthropic-beta header, so rebuild the full beta list.
  608. if fast_mode and not _is_third_party_anthropic_endpoint(base_url) and _supports_fast_mode(model):
  609. kwargs.setdefault("extra_body", {})["speed"] = "fast"
  610. betas = _common_betas_for_base_url(base_url, drop_context_1m_beta=drop_context_1m_beta)
  611. kwargs["extra_headers"] = _beta_header(betas + (_OAUTH_ONLY_BETAS if is_oauth else []) + [_FAST_MODE_BETA])
  612. return kwargs
  613. # Keys exclusive to the OpenAI Responses / Codex shape; the Messages SDK raises ``TypeError: ...
  614. # unexpected keyword argument`` on any of them.
  615. _RESPONSES_ONLY_KWARGS = frozenset({"instructions", "input", "store", "parallel_tool_calls"})
  616. def sanitize_anthropic_kwargs(api_kwargs: Any, *, log_prefix: str = "") -> Any:
  617. """Drop Responses-API-only keys before an Anthropic Messages SDK call. Boundary guard for
  618. api_mode-flip races (a concurrent auxiliary call mutating a shared agent between kwargs build
  619. and dispatch): a Responses-shaped payload reaching ``messages.stream()`` dies with a
  620. non-retryable TypeError that takes the whole turn and fallback chain with it. Mutates and
  621. returns ``api_kwargs``; logs a WARNING so the race stays visible."""
  622. leaked = _RESPONSES_ONLY_KWARGS.intersection(api_kwargs) if isinstance(api_kwargs, dict) else ()
  623. if leaked:
  624. for key in leaked:
  625. del api_kwargs[key]
  626. logger.warning(
  627. "%sStripped Responses-only kwarg(s) %s from an Anthropic Messages "
  628. "call (api_mode flip race — see #31673). The call will proceed; "
  629. "this breadcrumb means a kwargs build ran under a Responses "
  630. "api_mode while dispatch ran under anthropic_messages.",
  631. log_prefix,
  632. sorted(leaked),
  633. )
  634. return api_kwargs
  635. def buffer_anthropic_tool_input(api_kwargs: dict[str, Any], base_url: str | None) -> None:
  636. """Retry knob for a malformed fine-grained tool-JSON stream (#107830): the beta streams tool
  637. args unvalidated, so a model that emits ``{"names": cronjob_manage}`` breaks the SDK parser
  638. and an identical retry breaks identically. ``eager_input_streaming: false`` per tool restores
  639. Anthropic's buffered, validated args for the rest of this turn (the flag lives on the turn's
  640. kwargs, so a later retry of the same turn keeps it; the changed ``tools`` block costs one
  641. prompt-cache miss, cheaper than a dead turn). Off the happy path on purpose:
  642. buffering a large payload is a zero-event gap the stale-stream detector kills. No-op on
  643. endpoints that never get the beta (MiniMax) rather than sending them an unknown field."""
  644. if _TOOL_STREAMING_BETA not in _common_betas_for_base_url(base_url):
  645. return
  646. for tool in api_kwargs.get("tools") or ():
  647. tool["eager_input_streaming"] = False
  648. class _UsageNormalizingStream:
  649. """Raw SSE iterator proxy that fills ``usage: null`` before the SDK accumulates it (#60683)."""
  650. def __init__(self, inner):
  651. self._inner = inner
  652. def __getattr__(self, name):
  653. return getattr(self._inner, name)
  654. def __iter__(self):
  655. # Lazy: the SDK import is deliberately kept off module import (see _anthropic_sdk).
  656. from anthropic.types import MessageDeltaUsage, Usage
  657. output_tokens = 0
  658. for event in self._inner:
  659. etype = getattr(event, "type", None)
  660. if etype == "message_start":
  661. message = getattr(event, "message", None)
  662. usage = getattr(message, "usage", None)
  663. if message is not None and usage is None:
  664. message.usage = Usage(input_tokens=0, output_tokens=0)
  665. elif usage is not None:
  666. output_tokens = getattr(usage, "output_tokens", 0) or 0
  667. elif etype == "message_delta" and getattr(event, "usage", None) is None:
  668. # accumulate_event() assigns delta output_tokens unconditionally; carry
  669. # message_start's count forward instead of clobbering it with 0.
  670. event.usage = MessageDeltaUsage(output_tokens=output_tokens)
  671. yield event
  672. def normalize_stream_usage(message_stream: Any) -> Any:
  673. """Patch ``usage: null`` on raw SSE events before the SDK accumulates them.
  674. Anthropic-compatible providers (MiniMax) send ``usage: null`` on message_start and/or
  675. message_delta; the SDK's accumulate_event() then dies on ``usage.output_tokens`` mid-
  676. iteration (#60683). Wraps ``MessageStream._raw_stream`` in place; no-op for other shapes."""
  677. raw = getattr(message_stream, "_raw_stream", None)
  678. if raw is None or not hasattr(raw, "__iter__"):
  679. return message_stream
  680. message_stream._raw_stream = _UsageNormalizingStream(raw)
  681. return message_stream
  682. def _is_stream_unavailable_error(exc: Exception) -> bool:
  683. """True when an Anthropic stream call should fall back to create()."""
  684. err_lower = str(exc).lower()
  685. if "stream" in err_lower and "not supported" in err_lower:
  686. return True
  687. if "unexpected event order" in err_lower:
  688. return True
  689. if "invokemodelwithresponsestream" not in err_lower:
  690. return False
  691. from agent.bedrock_adapter import is_streaming_access_denied_error
  692. return is_streaming_access_denied_error(exc)
  693. def _stream_final_message(stream_fn, api_kwargs, log_prefix, on_stream_event, on_response):
  694. """``messages.stream()`` -> final Message, ticking the best-effort callbacks."""
  695. with stream_fn(**{k: v for k, v in api_kwargs.items() if k != "stream"}) as stream:
  696. stream = normalize_stream_usage(stream) # MiniMax usage:null (#60683), same as the main turn
  697. if callable(on_response):
  698. try:
  699. on_response(getattr(stream, "response", None))
  700. except Exception:
  701. logger.debug("%son_response callback failed", log_prefix, exc_info=True)
  702. # Consume manually so each event ticks the progress callback; get_final_message then
  703. # returns the accumulated snapshot. TimeoutError is the caller's deadline seam: the host
  704. # has given up, so abandon the stream (``with`` closes it) instead of streaming an answer
  705. # nobody reads.
  706. # Some SDK versions drop optional message_delta metadata from the final snapshot.
  707. # The stream must end in message_stop; anything else is a retryable incomplete response.
  708. stop_details = None
  709. saw_message_stop = False
  710. for event in stream:
  711. if getattr(event, "type", None) == "message_stop":
  712. saw_message_stop = True
  713. if getattr(event, "type", None) == "message_delta":
  714. details = getattr(getattr(event, "delta", None), "stop_details", None)
  715. if details is not None:
  716. stop_details = details
  717. if not callable(on_stream_event):
  718. continue
  719. try:
  720. on_stream_event(event)
  721. except TimeoutError:
  722. # The callback is the caller's deadline seam (#99692: the host waiting on this summary has
  723. # already given up). Abandon the stream — the ``with`` closes it — instead of streaming an
  724. # answer nobody will read.
  725. raise
  726. except Exception:
  727. logger.debug("%son_stream_event callback failed", log_prefix, exc_info=True)
  728. if not saw_message_stop:
  729. raise EmptyStreamError(
  730. "Anthropic Messages stream ended before message_stop (possible upstream stream drop)."
  731. )
  732. message = stream.get_final_message()
  733. if stop_details is not None:
  734. message.stop_details = stop_details
  735. return message
  736. def create_anthropic_message(
  737. client: Any, api_kwargs: dict, *, log_prefix: str = "", prefer_stream: bool = True,
  738. on_stream_event=None, on_response=None,
  739. ) -> Any:
  740. """Create an Anthropic message, aggregating via stream when available. Some Anthropic-compatible
  741. gateways are SSE-only and answer ``create()`` with ``text/event-stream``, which the SDK surfaces
  742. as raw text (callers then crash on ``.content``), so prefer ``messages.stream()`` like the main
  743. turn path and fall back to ``create()`` only for providers that explicitly don't support
  744. streaming (restricted Bedrock roles). Both callbacks are best-effort and fire only on the
  745. streaming path: ``on_stream_event(event)`` lets liveness watchdogs see forward progress;
  746. ``on_response(httpx_response)`` exposes headers the parsed Message drops (Nous Portal's
  747. ``x-nous-credits-*`` balance family)."""
  748. sanitize_anthropic_kwargs(api_kwargs, log_prefix=log_prefix)
  749. messages_api = getattr(client, "messages", None)
  750. stream_fn = getattr(messages_api, "stream", None)
  751. if prefer_stream and callable(stream_fn):
  752. try:
  753. return _stream_final_message(stream_fn, api_kwargs, log_prefix, on_stream_event, on_response)
  754. except TimeoutError:
  755. raise
  756. except Exception as exc:
  757. if not _is_stream_unavailable_error(exc):
  758. raise
  759. logger.debug(
  760. "%sAnthropic Messages stream unavailable; falling back to messages.create(): %s", log_prefix, exc
  761. )
  762. return messages_api.create(**{k: v for k, v in api_kwargs.items() if k != "stream"})