opencode_affinity.py 6.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150
  1. """Conversation-affinity request headers for session-aware relays and proxies.
  2. Two sources, one merge point:
  3. * ``x-opencode-session`` — OpenCode (opencode.ai Zen/Go relay) pins requests that share this
  4. value to the same upstream backend, which keeps its prompt cache warm across the turns of one
  5. conversation. Always sent to OpenCode targets.
  6. * ``providers.<name>.session_affinity_header`` — an opt-in header NAME on a custom provider entry
  7. (default off). Session-aware proxies fronting a stateful backend (LiteLLM's ``x-litellm-session-id``,
  8. self-hosted Claude/OpenAI gateways) otherwise classify an agent-loop request whose last message is
  9. a ``tool_result`` as a new conversation and replay the whole history upstream (#86241, #104449).
  10. The value only has to be opaque and consistent per conversation, so it is derived the same way as
  11. the other affinity hints Hermes already sends (OpenRouter's sticky ``session_id``, xAI's
  12. ``x-grok-conv-id``): the host-declared routing scope first (a host that names its own conversation,
  13. #96811), then the ambient conversation ROOT (stable across compaction rotation and delegate trees),
  14. then the physical session id — normalized through ``_cache_scope_from_session_id`` so cron fires of
  15. one job share a scope. Auxiliary calls (compression, titles, vision, MoA) have no session handle and
  16. resolve the ambient value, so they stay on the conversation's backend too (#70820).
  17. Every request — main turn on any transport, auxiliary calls — goes through
  18. :func:`merge_session_affinity_headers` so the headers cannot drift per code path.
  19. """
  20. from __future__ import annotations
  21. import uuid
  22. from typing import Any, Optional
  23. OPENCODE_SESSION_HEADER = "x-opencode-session"
  24. def opencode_transport(provider: Optional[str], model: Optional[str], base_url: Optional[str]) -> tuple[Optional[str], str]:
  25. """``(api_mode, base_url)`` re-derived per model for an OpenCode relay target; ``(None, base_url)`` otherwise.
  26. OpenCode Zen/Go serve Responses-only (``gpt-*``, ``grok-*``, ``muse-spark``), Anthropic-wire
  27. (``minimax-*``, ``qwen*``, ``claude-*``) and chat/completions models behind one provider, so a
  28. provider-level or persisted ``api_mode`` is wrong for every model but the one it was saved for.
  29. The main runtime (``hermes_cli/runtime_provider.py``) always re-derives from the effective model;
  30. auxiliary resolution must agree or ``gpt-5.6-luna`` compression 500s on /chat/completions (#98799).
  31. Built-in families, custom entries named after one (``opencode-go-bridge``, #85589) and opencode.ai
  32. hosts all count.
  33. """
  34. from hermes_cli.models import normalize_opencode_base_url, normalize_opencode_model_id, opencode_model_api_mode
  35. from hermes_cli.runtime_provider_custom import _get_named_custom_provider, _opencode_family_for_custom
  36. url = str(base_url or "")
  37. family = _opencode_family_for_custom(str(provider or ""), url)
  38. if family is None:
  39. return None, url
  40. # A custom entry that declares its own api_mode keeps it, exactly like the main runtime
  41. # (_resolve_named_custom_runtime only re-derives when the entry has none).
  42. if (_get_named_custom_provider(str(provider or "")) or {}).get("api_mode"):
  43. return None, url
  44. # ``<provider>/<model>`` config ids are stripped against the entry name before the family lookup.
  45. api_mode = opencode_model_api_mode(family, normalize_opencode_model_id(provider, model))
  46. return api_mode, normalize_opencode_base_url(provider, api_mode, url)
  47. def is_opencode_target(provider: Optional[str], base_url: Optional[str]) -> bool:
  48. """True when *provider* or *base_url* addresses the OpenCode relay.
  49. Matches the built-in opencode-zen/go providers, custom
  50. ``opencode-<family>-*`` providers, and any base_url hosted on opencode.ai.
  51. """
  52. try:
  53. from hermes_cli.models import opencode_provider_family
  54. if opencode_provider_family(provider) is not None:
  55. return True
  56. except Exception:
  57. pass
  58. try:
  59. from agent.anthropic_endpoints import _is_opencode_endpoint
  60. return _is_opencode_endpoint(str(base_url or ""))
  61. except Exception:
  62. return False
  63. def resolve_affinity_key(session_id: Optional[str] = None) -> str:
  64. """Return the normalized rotation-stable conversation affinity key ("" when unknown)."""
  65. try:
  66. from agent.portal_tags import get_affinity_scope, get_conversation_context
  67. from agent.transports.codex import _cache_scope_from_session_id
  68. return _cache_scope_from_session_id(get_affinity_scope() or get_conversation_context() or session_id)
  69. except Exception:
  70. return str(session_id or "")
  71. def opencode_session_headers(
  72. provider: Optional[str],
  73. base_url: Optional[str],
  74. session_id: Optional[str] = None,
  75. ) -> dict[str, str]:
  76. """Return ``{"x-opencode-session": <key>}`` for OpenCode targets, else ``{}``.
  77. OpenCode targets always get a key: when no conversation/session key resolves, an
  78. ephemeral ``oneshot-<hex>`` value is generated (OpenCode Go rejects requests without
  79. the header, #105841)."""
  80. if not is_opencode_target(provider, base_url):
  81. return {}
  82. key = resolve_affinity_key(session_id)
  83. if not key:
  84. # Stateless one-shot requests (commit messages, summaries, standalone prompts outside
  85. # a session) lack an ambient conversation or session id. OpenCode Go strictly requires
  86. # x-opencode-session on every request (HTTP 400 MissingSessionID if absent, #105841)
  87. # so generate an ephemeral session id fallback.
  88. key = f"oneshot-{uuid.uuid4().hex[:16]}"
  89. return {OPENCODE_SESSION_HEADER: key}
  90. def custom_provider_session_affinity_headers(
  91. base_url: Optional[str],
  92. session_id: Optional[str] = None,
  93. ) -> dict[str, str]:
  94. """Return ``{<session_affinity_header>: <key>}`` when the route's provider entry declares one, else ``{}``."""
  95. try:
  96. from hermes_cli.config import get_custom_provider_session_affinity_header
  97. header = get_custom_provider_session_affinity_header(str(base_url or ""))
  98. except Exception:
  99. return {}
  100. if not header:
  101. return {}
  102. key = resolve_affinity_key(session_id)
  103. return {header: key} if key else {}
  104. def merge_session_affinity_headers(
  105. kwargs: dict[str, Any],
  106. provider: Optional[str],
  107. base_url: Optional[str],
  108. session_id: Optional[str] = None,
  109. ) -> dict[str, Any]:
  110. """Merge the affinity header(s) into ``kwargs["extra_headers"]`` (in place).
  111. Existing per-request headers win, so a caller-pinned value is preserved.
  112. Targets with neither source configured are left untouched.
  113. """
  114. headers = opencode_session_headers(provider, base_url, session_id)
  115. headers.update(custom_provider_session_affinity_headers(base_url, session_id))
  116. if headers:
  117. existing = kwargs.get("extra_headers")
  118. merged = dict(existing) if isinstance(existing, dict) else {}
  119. for key, value in headers.items():
  120. merged.setdefault(key, value)
  121. kwargs["extra_headers"] = merged
  122. return kwargs