The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
refactor(providers): generic wire seams for per-model api_mode, endpoint headers, max-tokens param
Tekniumb9712a0c9ff3
diff --git a/agent/agent_init.py b/agent/agent_init.pyindex b7e66eedd83..28bf3b7ebd4 100644--- a/agent/agent_init.py+++ b/agent/agent_init.py@@ -454,9 +454,8 @@ def _finalize_routing(agent, api_mode, credential_pool):_base_lower = str(agent.base_url or "").lower()if (- # GPT-5.x models usually require the Responses API path, but some providers have exceptions (for- # example Copilot's gpt-5-mini still uses chat completions). ACP runtimes are excluded: an ACP- # client handles its own routing and does not implement the Responses API surface. Keyed on the+ # GPT-5.x models usually require the Responses API path; a profile's api_mode_for_model may keep one on+ # chat completions. ACP runtimes are excluded: an ACP client routes itself (no Responses surface). Keyed on the# `acp://` scheme AND the profile's external_process auth_type (an `<X>_ACP_BASE_URL` override# can carry an https marker), not one vendor, so every ACP client is covered. When api_mode was explicitly# provided, respect it — the user knows what their endpoint supports (#10473). Exception: Azure@@ -800,20 +799,22 @@ def _explicit_client_kwargs(agent, api_key, base_url, _provider_timeout) -> dictclient_kwargs["default_query"] = {k: v[0] for k, v in parse_qs(_parsed_url.query).items()}if _provider_timeout is not None:client_kwargs["timeout"] = _provider_timeout- # ACP/subprocess providers take launch kwargs instead of HTTP credentials. Keyed on the- # provider profile's auth_type, not one vendor slug, so out-of-tree external_process- # plugin providers get the same launch path as the built-in copilot-acp (#102421).+ # ACP/subprocess providers take launch kwargs instead of HTTP credentials. Keyed on the profile's+ # auth_type, not a vendor slug: every external_process plugin gets this launch path (#102421).from hermes_cli.runtime_provider_backends import _is_external_process_providerif _is_external_process_provider(agent.provider):client_kwargs["command"] = agent.acp_commandclient_kwargs["args"] = agent.acp_args+ from agent.provider_route_hooks import route_answer_headers_for = _host_default_headers_factory(base_url)if _headers_for is not None:client_kwargs["default_headers"] = _headers_for(api_key, base_url)+ elif _route_headers := route_answer("client_headers", provider=str(agent.provider or ""), base_url=base_url,+ api_key=api_key if isinstance(api_key, str) else ""):+ client_kwargs["default_headers"] = _route_headerselif "default_headers" not in client_kwargs:- # Fall back to profile.default_headers for providers that declare custom headers- # (Vercel AI Gateway attribution, Kimi User-Agent on non-kimi.com endpoints).+ # Static profile.default_headers (Vercel AI Gateway attribution, Kimi UA on non-kimi.com endpoints).with suppress(Exception):from providers import get_provider_profile as _gpf_ph = _gpf(agent.provider)@@ -1037,7 +1038,6 @@ _HOST_DEFAULT_HEADERS: list[tuple[str, Callable[[Any, str], dict[str, str]]]] =("integrate.api.nvidia.com",_lazy_headers("agent.auxiliary_client", "build_nvidia_nim_headers", pass_base=True)),("api.routermint.com", _lazy_headers("agent.client_lifecycle", "_routermint_headers")),- ("githubcopilot.com", _lazy_headers("hermes_cli.models", "copilot_default_headers")),("api.kimi.com", lambda _k, _b: {"User-Agent": "claude-code/0.1.0"}),("portal.qwen.ai", _lazy_headers("agent.client_lifecycle", "_qwen_portal_headers")),("chatgpt.com", _lazy_headers("agent.codex_headers", "codex_cloudflare_headers", pass_key=True)),@@ -2179,7 +2179,7 @@ def _init_usage_state(agent):# Per-session usage accounting._USAGE_STATE: dict[str, Any] = {"_user_turn_count": 0,- "_is_user_initiated_turn": False, # Copilot x-initiator: first call of a user turn = "user"+ "_is_user_initiated_turn": False, # first API call of a user turn (provider request_headers attribution)# Usage anchors (agent/usage_anchor.py): last response's exact usage + transcript# snapshot; invalidated on compaction/session switch so stale anchors never suppress compression."_usage_anchor": None,diff --git a/agent/agent_init_fallback.py b/agent/agent_init_fallback.pyindex ee4a124f549..d7c03f22b4e 100644--- a/agent/agent_init_fallback.py+++ b/agent/agent_init_fallback.py@@ -43,8 +43,9 @@ def _init_fallback_chain(agent, fallback_model):def recompute_init_fallback_api_mode(agent, fb_client) -> None:"""Give an init-time fallback its own api_mode instead of the unreachable primary's.- A Nous primary configured with ``api_mode: codex_responses`` otherwise leaves a Copilot- gpt-5-mini fallback on the Responses API, which silently drops reasoning content (#46527).+ A Nous primary configured with ``api_mode: codex_responses`` otherwise leaves a fallback whose+ profile serves that model on chat completions (``api_mode_for_model``) on the Responses API,+ which silently drops reasoning content (#46527).The per-turn path (``try_activate_fallback``) already recomputes via``_fallback_api_mode_resolved``; this keeps init in agreement, and runs before the``_primary_runtime`` snapshot so ``restore_primary_runtime`` replays the recomputed mode.diff --git a/agent/agent_runtime_helpers.py b/agent/agent_runtime_helpers.pyindex 1d8e485170d..285c190e2c9 100644--- a/agent/agent_runtime_helpers.py+++ b/agent/agent_runtime_helpers.py@@ -1920,8 +1920,8 @@ def _provider_supplied_client(agent, client_kwargs: dict) -> Any | None:def _profile_for_base_url(base_url: str) -> Any | None:"""Registered profile whose own base_url is a prefix of ``base_url`` (provider name did not- resolve). Prefix, not equality: the replaced copilot-acp branch keyed on- ``startswith("acp://copilot")``, so a path or user override under the same root must resolve."""+ resolve). Prefix, not equality: an ACP profile's ``acp://<vendor>`` root must also resolve a+ path or user override under the same root."""try:from providers import list_providerscandidates = list_providers()@@ -1935,21 +1935,21 @@ def _profile_for_base_url(base_url: str) -> Any | None:return None-def _ensure_copilot_headers(client_kwargs: dict) -> None:+def _ensure_route_client_headers(client_kwargs: dict, provider: str) -> None:"""Defense-in-depth: recovery/restore rebuild from a snapshot without re-running header- wiring; a missing Copilot-Integration-Id causes model_not_available_for_integrator 400s.- Only ADD missing keys, never override."""- try:- if base_url_host_matches(str(client_kwargs.get("base_url", "")), "githubcopilot.com"):- from hermes_cli.models import copilot_default_headers- existing = dict(client_kwargs.get("default_headers") or {})- existing_lower = {k.lower() for k in existing}- for hk, hv in copilot_default_headers().items():- if hk.lower() not in existing_lower:- existing[hk] = hv- client_kwargs["default_headers"] = existing- except Exception:- _ra().logger.debug("Copilot default-header guard skipped", exc_info=True)+ wiring, and a route whose provider requires its client headers (integration ids) 400s+ without them. Only ADD missing keys, never override."""+ from agent.provider_route_hooks import route_answer+ required = route_answer("client_headers", provider=provider, base_url=str(client_kwargs.get("base_url", "")),+ api_key=str(client_kwargs.get("api_key", "") or ""))+ if not required:+ return+ existing = dict(client_kwargs.get("default_headers") or {})+ existing_lower = {k.lower() for k in existing}+ for hk, hv in required.items():+ if hk.lower() not in existing_lower:+ existing[hk] = hv+ client_kwargs["default_headers"] = existingdef _gemini_native_client(agent, client_kwargs: dict, httpx_verify, *, reason: str, shared: bool):@@ -2074,7 +2074,7 @@ def create_openai_client(agent, client_kwargs: dict, *, reason: str, shared: boo# (init, switch_model, recovery, restore, request-scoped); auxiliary_client builds its own clients and# keeps SDK retries because it is NOT wrapped by the conversation loop.client_kwargs.setdefault("max_retries", 0)- _ensure_copilot_headers(client_kwargs)+ _ensure_route_client_headers(client_kwargs, str(getattr(agent, "provider", "") or ""))# All primary construction and recovery paths must identify Hermes to the official Codex# endpoint, including snapshots with custom header overrides.from agent.codex_headers import apply_required_codex_headersdiff --git a/agent/auxiliary_client.py b/agent/auxiliary_client.pyindex a2a26784c6b..795107db8f8 100644--- a/agent/auxiliary_client.py+++ b/agent/auxiliary_client.py@@ -2210,13 +2210,10 @@ def _resolve_api_key_provider() -> tuple[Optional[OpenAI], Optional[str]]:return GeminiNativeClient(api_key=api_key, base_url=base_url), modelif base_url_host_matches(base_url, "api.kimi.com"):headers = {"User-Agent": "claude-code/0.1.0"}- elif base_url_host_matches(base_url, "githubcopilot.com"):- from hermes_cli.models import copilot_default_headers- headers = copilot_default_headers()elif base_url_host_matches(base_url, "integrate.api.nvidia.com"):headers = build_nvidia_nim_headers(base_url)else:- headers = _profile_default_headers(provider_id)+ headers = _route_client_headers(base_url, provider_id) or _profile_default_headers(provider_id)extra = {"default_headers": headers} if headers else {}merged = _apply_user_default_headers(extra.get("default_headers"))if merged:@@ -2226,20 +2223,24 @@ def _resolve_api_key_provider() -> tuple[Optional[OpenAI], Optional[str]]:return None, None+def _route_client_headers(base_url: str, provider: str, *, is_vision: bool = False) -> Optional[dict]:+ from agent.provider_route_hooks import route_answer+ headers = route_answer("client_headers", provider=provider or "", base_url=base_url, has_images=is_vision)+ return dict(headers) if headers else None++def _endpoint_default_headers(base_url: str, provider: str, *, is_vision: bool = False, xai: bool = False,) -> Optional[dict]:"""Provider-specific client headers by endpoint host, merged with user ``model.default_headers``.- Kimi Code needs the claude-code User-Agent; Copilot needs its request headers- (``is_vision`` adds Copilot-Vision-Request); NVIDIA NIM and (optionally) xAI have- their own fingerprints; anything else falls back to the provider profile.+ Kimi Code needs the claude-code User-Agent; a profile's ``client_headers`` (``is_vision`` = image+ client), NVIDIA NIM and (optionally) xAI have their own; else the provider profile."""if base_url_host_matches(base_url, "api.kimi.com"):headers: dict = {"User-Agent": "claude-code/0.1.0"}- elif base_url_host_matches(base_url, "githubcopilot.com"):- from hermes_cli.copilot_auth import copilot_request_headers- headers = dict(copilot_request_headers(is_agent_turn=True, is_vision=is_vision))+ elif route := _route_client_headers(base_url, provider, is_vision=is_vision):+ headers = routeelif base_url_host_matches(base_url, "integrate.api.nvidia.com"):headers = dict(build_nvidia_nim_headers(base_url))elif xai and base_url_host_matches(base_url, "x.ai"):@@ -5311,15 +5312,12 @@ def _resolve_api_key_branch(req: _ResolveRequest, pconfig: Any, resolve_creds: Creturn _route_client(req, client, final_model)headers = _endpoint_default_headers(base_url, provider, is_vision=req.is_vision, xai=True)client = _create_openai_client(api_key=api_key, base_url=base_url, **({"default_headers": headers} if headers else {}))- # Copilot GPT-5+ models (except gpt-5-mini) are only reachable via the Responses API;- # wrap so call_llm() transparently routes through responses.stream().- if provider == "copilot" and final_model and not req.raw_codex:- with contextlib.suppress(ImportError):- from hermes_cli.models import _should_use_copilot_responses_api- if _should_use_copilot_responses_api(final_model):- logger.debug("resolve_provider_client: copilot model %s needs "- "Responses API — wrapping with CodexAuxiliaryClient", final_model)- client = CodexAuxiliaryClient(client, final_model)+ # A profile serving this model only on the Responses API: route call_llm() through responses.stream().+ from providers import get_provider_profile+ profile = get_provider_profile(provider) if final_model and not req.raw_codex else None+ if profile is not None and profile.api_mode_for_model(final_model) == "codex_responses":+ logger.debug("resolve_provider_client: %s model %s needs Responses API — wrapping", provider, final_model)+ client = CodexAuxiliaryClient(client, final_model)# api_mode handling for any API-key provider (direct OpenAI + codex model) and Anthropic-wire# endpoints (api.kimi.com/coding, /anthropic gateways) without per-provider branches.client = _wrap_transport(req, client, final_model, raw_base_url, api_key)@@ -5727,13 +5725,13 @@ def get_auxiliary_extra_body() -> dict:def auxiliary_max_tokens_param(value: int, *, model: Optional[str] = None) -> dict:- """Max-tokens kwarg for the auxiliary provider: direct OpenAI/Copilot and newer OpenAI-family- models (by ``model`` name, so custom endpoints fronting gpt-5.x are caught) need max_completion_tokens."""- _custom_host = base_url_hostname(_current_custom_base_url()) or ""- direct_openai_family = (- not _scoped_key_env("OPENROUTER_API_KEY") and _read_nous_auth() is None- and (_custom_host in ("api.openai.com", "api.githubcopilot.com") or _custom_host.endswith(".githubcopilot.com"))- )+ """Max-tokens kwarg for the auxiliary provider: direct OpenAI, a custom endpoint whose profile declares+ it, and newer OpenAI-family models (by ``model`` name: custom endpoints fronting gpt-5.x) need max_completion_tokens."""+ from agent.provider_route_hooks import route_answer+ _custom_base = _current_custom_base_url()+ direct_openai_family = not _scoped_key_env("OPENROUTER_API_KEY") and _read_nous_auth() is None and (+ base_url_hostname(_custom_base) == "api.openai.com"+ or route_answer("max_tokens_param", base_url=_custom_base, model=model or "") == "max_completion_tokens")if direct_openai_family or model_forces_max_completion_tokens(model):return {"max_completion_tokens": value}return {"max_tokens": value}diff --git a/agent/client_lifecycle.py b/agent/client_lifecycle.pyindex 4f4980fb404..1a7bb9050ee 100644--- a/agent/client_lifecycle.py+++ b/agent/client_lifecycle.py@@ -43,7 +43,6 @@ _ROUTE_DEFAULT_HEADERS = (("ai-gateway.vercel.sh", lambda self, url: _lazy_attr("agent.auxiliary_client", "_ai_gateway_headers")()),("integrate.api.nvidia.com", lambda self, url: _lazy_attr("agent.auxiliary_client", "build_nvidia_nim_headers")(url)),("api.routermint.com", lambda self, url: _routermint_headers()),- ("githubcopilot.com", lambda self, url: _lazy_attr("hermes_cli.models", "copilot_default_headers")()),("api.kimi.com", lambda self, url: _lazy_attr("agent.auxiliary_client", "_ai_gateway_headers")()),("portal.qwen.ai", lambda self, url: _qwen_portal_headers()),("chatgpt.com", lambda self, url: _lazy_attr("agent.codex_headers", "codex_cloudflare_headers")(@@ -449,10 +448,14 @@ class ClientLifecycleMixin:# No SDK retry loop: the outer loop owns retries/rotation/fallback, and SDK retries stretch a hung# request ~3x past our stale detector.request_kwargs["max_retries"] = 0- is_copilot = base_url_host_matches(str(request_kwargs.get("base_url", "")), "githubcopilot.com")- if is_copilot and self._api_kwargs_have_image_parts(api_kwargs or {}):- from hermes_cli.copilot_auth import copilot_request_headers- request_kwargs["default_headers"] = copilot_request_headers(is_agent_turn=True, is_vision=True)+ if self._api_kwargs_have_image_parts(api_kwargs or {}):+ # Image requests get the route's image client headers on a request-scoped client (cache-keyed apart).+ from agent.provider_route_hooks import route_answer+ image_headers = route_answer("client_headers", provider=self.provider or "",+ base_url=str(request_kwargs.get("base_url", "")),+ api_key=str(request_kwargs.get("api_key", "") or ""), has_images=True)+ if image_headers:+ request_kwargs["default_headers"] = {**(request_kwargs.get("default_headers") or {}), **image_headers}cached, stale = self._checkout_request_slot(_OPENAI_SLOT, request_kwargs)if cached is not None:return cached@@ -941,12 +944,18 @@ class ClientLifecycleMixin:self._client_kwargs["default_headers"] = build(self, base_url)breakelse:- # No URL-specific headers — fall back to profile.default_headers, else clear.+ # No URL-specific headers — a profile's endpoint headers, else profile.default_headers, else clear.self._client_kwargs.pop("default_headers", None)+ from agent.provider_route_hooks import route_answer+ route_headers = route_answer("client_headers", provider=self.provider or "", base_url=base_url,+ api_key=str(self._client_kwargs.get("api_key", "") or ""))+ if route_headers:+ self._client_kwargs["default_headers"] = dict(route_headers)with suppress(Exception):from providers import get_provider_profileprofile = get_provider_profile(self.provider)- if profile and profile.default_headers and (profile_headers := dict(profile.default_headers)):+ if (not route_headers and profile and profile.default_headers+ and (profile_headers := dict(profile.default_headers))):self._client_kwargs["default_headers"] = profile_headers# User overrides win over URL/profile defaults for the same route; a swap to another endpoint must not# inherit them.diff --git a/agent/moa_loop.py b/agent/moa_loop.pyindex 40e62319ea2..1e62756a765 100644--- a/agent/moa_loop.py+++ b/agent/moa_loop.py@@ -396,6 +396,24 @@ def _price_reference_response(return usage, None, None, None+def _slot_request_headers(runtime: dict[str, Any]) -> dict[str, str] | None:+ """User-initiated request headers of the slot's provider, attributed at that provider's own endpoint+ (MoA attributes by slot provider, whatever account host the slot resolved to)."""+ from agent.auxiliary_client import _normalize_aux_provider+ from providers import get_provider_profile++ provider = _normalize_aux_provider(str(runtime.get("provider") or ""))+ profile = get_provider_profile(provider) if provider else None+ if profile is None:+ return None+ try:+ return profile.request_headers(base_url=profile.base_url, model=str(runtime.get("model") or ""),+ user_initiated=True) or None+ except Exception: # plugin code: a broken hook must not fail the reference call+ logger.debug("MoA slot %s request_headers failed", provider, exc_info=True)+ return None++def _run_reference(slot: dict[str, Any], ref_messages: list[dict[str, Any]], *, temperature: float | None = None,max_tokens: int | None = None, reference_timeout: float | None = None, context_length_cache: Any = None,@@ -421,10 +439,9 @@ def _run_reference()trimmed = _maybe_apply_moa_cache_control(trimmed, _with_cache_disabled(runtime, cache_disabled), cache_ttl=cache_ttl)- # Copilot gates premium models on request attribution; MoA fan-out serves the- # user's current turn, so mirror the main agent's x-initiator header.- from agent.auxiliary_client import _normalize_aux_provider- is_copilot = _normalize_aux_provider(str(runtime.get("provider") or "")) in ("copilot", "copilot-acp")+ # Providers may gate premium models on request attribution; MoA fan-out serves the+ # user's current turn, so mirror the main agent's user-initiated request headers.+ initiator_headers = _slot_request_headers(runtime)if agent is not None:from agent.auxiliary_client import aux_progress_hook@@ -433,14 +450,14 @@ def _run_reference(task="moa_reference", messages=trimmed, temperature=temperature,max_tokens=max_tokens,timeout=reference_timeout, reasoning_config=_slot_reasoning_config(slot),- extra_headers={"x-initiator": "user"} if is_copilot else None, **runtime,+ extra_headers=initiator_headers, **runtime,)else:response = call_llm(task="moa_reference", messages=trimmed, temperature=temperature,max_tokens=max_tokens,timeout=reference_timeout, reasoning_config=_slot_reasoning_config(slot),- extra_headers={"x-initiator": "user"} if is_copilot else None, **runtime,+ extra_headers=initiator_headers, **runtime,)output_text = _extract_text(response) or "(empty response)"acct = _RefAccounting(*_price_reference_response(response, slot, runtime), messages=trimmed, output=output_text, **trace_fields)diff --git a/agent/provider_route_hooks.py b/agent/provider_route_hooks.pynew file mode 100644index 00000000000..02d8acd2547--- /dev/null+++ b/agent/provider_route_hooks.py@@ -0,0 +1,44 @@+"""Ask provider profiles about an endpoint: the named provider first, then any profile serving the host.++Endpoint-keyed ProviderProfile hooks (``client_headers``, ``request_headers``, ``max_tokens_param``)+receive the request's ``base_url`` and answer None / ``{}`` for endpoints that are not theirs, so a+``custom`` route pointed at a plugin provider's host still gets that provider's wire quirks. Only+profiles that override the hook are consulted: the base implementations are no-ops, and hosted+(``plugins.isolation: host``) proxies define only the hooks their plugin overrides.+"""++from __future__ import annotations++import logging+from typing import Any++from providers.base import ProviderProfile++logger = logging.getLogger(__name__)+++def _overrides(profile: Any, hook: str) -> bool:+ return getattr(type(profile), hook, None) is not getattr(ProviderProfile, hook)+++def route_profiles(hook: str, provider: str = "") -> list[Any]:+ """Profiles overriding *hook*: the one registered for *provider* first, then every other."""+ from providers import get_provider_profile, list_providers++ named = get_provider_profile(provider) if provider else None+ ordered = [named] if named is not None and _overrides(named, hook) else []+ ordered.extend(p for p in list_providers() if p is not named and _overrides(p, hook))+ return ordered+++def route_answer(hook: str, *, provider: str = "", **kwargs: Any) -> Any:+ """First truthy answer of *hook* across ``route_profiles``; None when no profile claims the endpoint."""+ for profile in route_profiles(hook, provider):+ try:+ answer = getattr(profile, hook)(**kwargs)+ except Exception: # plugin code: a broken hook degrades to generic behaviour, never fails the request+ logger.debug("provider %s %s hook failed", getattr(profile, "name", "?"), hook, exc_info=True)+ continue+ if answer:+ return answer+ return Nonediff --git a/agent/turn_api_request.py b/agent/turn_api_request.pyindex e4468c52756..e039ae8e303 100644--- a/agent/turn_api_request.py+++ b/agent/turn_api_request.py@@ -1,7 +1,7 @@"""Per-attempt request assembly for the conversation turn's retry loop: re-apply thereasoning echo pad and prompt-cache decoration for the CURRENT provider (a fallback maydiffer from the primary), build ``api_kwargs``, run the surrogate/ASCII chokepoints, Codex-preflight, OpenRouter cache bypass, Copilot ``x-initiator``, the LLM request middleware,+preflight, OpenRouter cache bypass, provider per-request headers, the LLM request middleware,the ``pre_api_request`` hook and the debug dump. Nothing here imports``agent.conversation_loop`` at module level."""@@ -132,11 +132,17 @@ def build_request_payload(# retry must bypass the cache.if agent._empty_content_retries > 0 and agent._is_openrouter_url():_set_extra_header(api_kwargs, "X-OpenRouter-Cache", "false")- # Copilot x-initiator: first call of a user turn is "user" (billed premium);- # tool-loop follow-ups keep the default "agent".- if getattr(agent, "_is_user_initiated_turn", False) and agent._is_copilot_url():- _set_extra_header(api_kwargs, "x-initiator", "user")- agent._is_user_initiated_turn = False+ # Provider per-request headers (turn attribution): the first call of a user turn is consumed+ # by the route that attributes it; tool-loop follow-ups get the route's default.+ if getattr(agent, "_is_user_initiated_turn", False):+ from agent.provider_route_hooks import route_answer+ _request_headers = route_answer(+ "request_headers", provider=agent.provider or "", base_url=agent.base_url or "",+ model=agent.model or "", user_initiated=True)+ if _request_headers:+ for _key, _value in _request_headers.items():+ _set_extra_header(api_kwargs, _key, _value)+ agent._is_user_initiated_turn = Falsetry:from hermes_cli.middleware import apply_llm_request_middlewarediff --git a/hermes_cli/model_switch.py b/hermes_cli/model_switch.pyindex 7e1c683b313..a11eccfc21e 100644--- a/hermes_cli/model_switch.py+++ b/hermes_cli/model_switch.py@@ -1662,11 +1662,6 @@ def _validate_switch(st: _Switch) -> Optional[ModelSwitchResult]:return None-def _copilot_api_mode(provider: str, model: str, api_key: str) -> str:- from hermes_cli.models import copilot_model_api_mode- return copilot_model_api_mode(model, api_key=api_key)--def _opencode_api_mode(provider: str, model: str, api_key: str) -> str:# Re-derive api_mode from the effective model rather than the persisted api_mode: the opencode providers# serve both anthropic_messages and chat_completions models, so the previous session's mode must not@@ -1691,19 +1686,24 @@ def _nous_api_mode(provider: str, model: str, api_key: str) -> str:# Per-provider api_mode overrides applied after validation, keyed on the final target provider# (the key sets are disjoint, so exactly one — or none — fires)._PROVIDER_API_MODE_OVERRIDES: dict[str, Any] = {- **dict.fromkeys(("copilot", "github-copilot"), _copilot_api_mode),**dict.fromkeys(("opencode-zen", "opencode-go", "opencode"), _opencode_api_mode),**dict.fromkeys(("nous", "nous-portal", "nousresearch"), _nous_api_mode)}def model_derived_api_mode(provider: str, model: str, api_key: str = "") -> Optional[str]:"""api_mode re-derived from the FINAL model for providers that serve several wire formats behind one- endpoint (OpenCode Zen/Go and custom providers extending a family slug, Copilot, Nous); None when the- provider's wire is fixed by its endpoint. A persisted api_mode from an earlier model of such a provider- is never authoritative — resume paths must call this instead of honoring the row (#96066)."""+ endpoint (OpenCode Zen/Go and custom providers extending a family slug, Nous, and any provider profile+ declaring ``api_mode_for_model``); None when the provider's wire is fixed by its endpoint. A persisted+ api_mode from an earlier model of such a provider is never authoritative — resume paths must call this+ instead of honoring the row (#96066)."""from hermes_cli.models import opencode_provider_familykey = str(provider or "").strip().lower()override = _PROVIDER_API_MODE_OVERRIDES.get(opencode_provider_family(key) or key)+ if override is None and key:+ from providers import get_provider_profile+ profile = get_provider_profile(key)+ if profile is not None:+ return profile.api_mode_for_model(model, api_key=api_key or "")return override(key, model, api_key) if override is not None else Nonediff --git a/plugins/model-providers/copilot/__init__.py b/plugins/model-providers/copilot/__init__.pyindex 745ee4a2814..8d226af84bf 100644--- a/plugins/model-providers/copilot/__init__.py+++ b/plugins/model-providers/copilot/__init__.py@@ -10,8 +10,10 @@ from typing import Anyfrom providers import register_providerfrom providers.base import ProviderProfile+from .wire import CopilotWireMixin-class CopilotProfile(ProviderProfile):++class CopilotProfile(CopilotWireMixin, ProviderProfile):"""GitHub Copilot / GitHub Models — editor headers + reasoning."""def build_api_kwargs_extras(diff --git a/plugins/model-providers/copilot/wire.py b/plugins/model-providers/copilot/wire.pynew file mode 100644index 00000000000..1aa230ded6c--- /dev/null+++ b/plugins/model-providers/copilot/wire.py@@ -0,0 +1,75 @@+"""GitHub Copilot wire quirks: per-model api_mode, editor/initiator/vision headers, max-tokens param.++Fills the generic ProviderProfile wire seams (``providers/base.py`` L1 block). Every hook here is+pure and answers from the arguments alone, except ``api_mode_for_model`` with an ``api_key``, which+may read the account's cached live catalog to normalize the model id first.+"""++from __future__ import annotations++import re+from typing import Any, Optional++from utils import base_url_host_matches, base_url_hostname++# Copilot's own API host family (individual, business and enterprise subdomains).+_COPILOT_HOST = "githubcopilot.com"+# Hosts that bill a request as premium when it carries ``x-initiator: user``.+_INITIATOR_HOSTS = ("api.githubcopilot.com", "models.github.ai")+++def is_copilot_host(base_url: str) -> bool:+ return base_url_host_matches(str(base_url or ""), _COPILOT_HOST)+++def requires_responses_api(model_id: str) -> bool:+ """opencode's ``shouldUseCopilotResponsesApi``: GPT-5+ uses the Responses API except+ ``gpt-5-mini``; non-GPT models (Claude, Gemini, ...) use Chat Completions."""+ match = re.match(r"^gpt-(\d+)", model_id)+ return bool(match) and int(match.group(1)) >= 5 and not model_id.startswith("gpt-5-mini")+++def model_api_mode(+ model_id: Optional[str], *, catalog: Optional[list[dict[str, Any]]] = None,+ api_key: Optional[str] = None) -> str:+ """API mode for a Copilot model from the id pattern (opencode's approach). Copilot's Claude models+ go through its OpenAI-compatible chat endpoint, not the native Anthropic adapter: the catalog may+ advertise /v1/messages but the Copilot token/header scheme lives in the OpenAI client path."""+ from hermes_cli.models import fetch_github_model_catalog, normalize_copilot_model_id++ if catalog is None and api_key: # fetch once so normalize + endpoint check share it+ catalog = fetch_github_model_catalog(api_key=api_key)+ normalized = normalize_copilot_model_id(model_id, catalog=catalog, api_key=api_key)+ if normalized and requires_responses_api(normalized):+ return "codex_responses"+ return "chat_completions"+++def editor_headers(*, is_vision: bool = False) -> dict[str, str]:+ from hermes_cli.copilot_auth import copilot_request_headers++ return copilot_request_headers(is_agent_turn=True, is_vision=is_vision)+++class CopilotWireMixin:+ """ProviderProfile wire hooks for the Copilot API."""++ def api_mode_for_model(self, model: str, *, api_key: str | None = None) -> str | None:+ if api_key is None:+ return "codex_responses" if requires_responses_api(model) else "chat_completions"+ return model_api_mode(model, api_key=api_key)++ def client_headers(+ self, *, base_url: str, api_key: str = "", has_images: bool = False,+ ) -> dict[str, str] | None:+ return editor_headers(is_vision=has_images) if is_copilot_host(base_url) else None++ def request_headers(self, *, base_url: str, model: str = "", user_initiated: bool = False) -> dict[str, str]:+ # First call of a user turn bills premium; follow-ups keep the client default ``x-initiator: agent``.+ if user_initiated and any(base_url_host_matches(base_url, h) for h in _INITIATOR_HOSTS):+ return {"x-initiator": "user"}+ return {}++ def max_tokens_param(self, *, base_url: str, model: str = "") -> str | None:+ host = base_url_hostname(str(base_url or "")) or ""+ return "max_completion_tokens" if host.endswith("." + _COPILOT_HOST) else Nonediff --git a/providers/base.py b/providers/base.pyindex 90f9f8e15a9..6845389e329 100644--- a/providers/base.py+++ b/providers/base.py@@ -414,6 +414,40 @@ class ProviderProfile:"""return None+ # ── L1 wire seams (per-model wire, endpoint-keyed headers, max-tokens param) ──+ # Endpoint-keyed hooks take the request's ``base_url``: core asks the named provider's profile first,+ # then any registered profile overriding the hook (``agent.provider_route_hooks``), so a ``custom``+ # route pointed at this provider's host is served too. Return None / ``{}`` for an endpoint that is+ # not yours. All four are pure: no I/O unless the docstring says so.++ def api_mode_for_model(self, model: str, *, api_key: str | None = None) -> str | None:+ """Wire (``api_mode``) this provider serves *model* on, or None to keep the static ``api_mode``.++ ``api_key=None`` is the pure hot path (agent init, fallback, aux client builds): answer from the+ id alone. A string ``api_key`` comes from resolution-time callers (``/model``, runtime resolve),+ which may consult a cached live catalog with that credential to normalize the id first.+ """+ return None++ def client_headers(+ self, *, base_url: str, api_key: str = "", has_images: bool = False,+ ) -> dict[str, str] | None:+ """Default headers for an OpenAI client built for *base_url*, or None when this profile has no+ endpoint-specific headers there (core then uses the static ``default_headers``). ``has_images``+ asks for the headers of a request-scoped client carrying native image parts. Core merges user+ ``model.default_headers`` over the result and re-adds missing keys on snapshot rebuilds."""+ return None++ def request_headers(self, *, base_url: str, model: str = "", user_initiated: bool = False) -> dict[str, str]:+ """Per-request headers (``extra_headers``) for *base_url*; ``user_initiated`` is True only on the+ first API call of a user turn (attribution). Hot path: pure and cheap."""+ return {}++ def max_tokens_param(self, *, base_url: str, model: str = "") -> str | None:+ """``"max_completion_tokens"`` / ``"max_tokens"`` for requests to *base_url*, or None for the+ core heuristic (direct OpenAI / Azure host or newer OpenAI model families)."""+ return None+def listed(self) -> bool:"""Whether discovery surfaces may offer this provider.diff --git a/run_agent.py b/run_agent.pyindex b060e185e2d..790c50b01a1 100644--- a/run_agent.py+++ b/run_agent.py@@ -406,7 +406,7 @@ class AIAgent(self._compaction_prompt_drift_logged = False# Who wrote the current turn. build_turn_context() sets it at the start of every turn.self._turn_author = None- # Copilot x-initiator: True for the first API call of a user turn, False for tool-loop follow-ups.+ # True for the first API call of a user turn, False for tool-loop follow-ups (provider request_headers).self._is_user_initiated_turn = Falseself._transition_context_engine_session(@@ -528,11 +528,6 @@ class AIAgent(url = str(base_url).lower() if base_url is not None else (getattr(self, "_base_url_lower", "") or "")return base_url_host_matches(url, "openai.azure.com")- def _is_github_copilot_url(self, base_url: str | None = None) -> bool:- """Return True when a base URL targets GitHub Copilot's OpenAI-compatible API."""- hostname = self._hostname_for(base_url)- return bool(hostname) and (hostname == "api.githubcopilot.com" or hostname.endswith(".githubcopilot.com"))-def _resolved_api_call_timeout(self) -> float:"""Per-call request timeout: per-model ``timeout_seconds`` > provider ``request_timeout_seconds`` >``HERMES_API_TIMEOUT`` > 1800s."""@@ -659,19 +654,25 @@ class AIAgent(from hermes_cli.runtime_provider_backends import _is_external_process_providerif _is_external_process_provider(normalized_provider):return False- if normalized_provider == "copilot":- try:- from hermes_cli.models import _should_use_copilot_responses_api- return _should_use_copilot_responses_api(model)- except Exception:- pass # fall back to the generic GPT-5 rule+ # A provider serving several wires behind one endpoint decides per model (pure, no I/O).+ from providers import get_provider_profile+ profile = get_provider_profile(normalized_provider) if normalized_provider else None+ derived = profile.api_mode_for_model(model) if profile is not None else None+ if derived is not None:+ return derived == "codex_responses"return AIAgent._model_requires_responses_api(model)def _max_tokens_param(self, value: int) -> dict:- """``max_completion_tokens`` for newer OpenAI families (and Azure / Copilot serving them), else- ``max_tokens``. URL-first, then model-name fallback for third-party endpoints fronting those models."""- if (self._is_direct_openai_url() or self._is_azure_openai_url() or self._is_github_copilot_url()- or model_forces_max_completion_tokens(self.model)):+ """``max_completion_tokens`` for newer OpenAI families (and Azure / provider routes declaring it),+ else ``max_tokens``. URL-first, then model-name fallback for third-party endpoints fronting those models."""+ if self._is_direct_openai_url() or self._is_azure_openai_url():+ return {"max_completion_tokens": value}+ from agent.provider_route_hooks import route_answer+ declared = route_answer("max_tokens_param", provider=getattr(self, "provider", "") or "",+ base_url=getattr(self, "base_url", "") or "", model=self.model or "")+ if declared:+ return {declared: value}+ if model_forces_max_completion_tokens(self.model):return {"max_completion_tokens": value}return {"max_tokens": value}diff --git a/tests/agent/test_provider_wire_seams.py b/tests/agent/test_provider_wire_seams.pynew file mode 100644index 00000000000..9f896f56cbb--- /dev/null+++ b/tests/agent/test_provider_wire_seams.py@@ -0,0 +1,137 @@+"""Generic ProviderProfile wire seams, exercised through a fake plugin profile.++``api_mode_for_model`` (per-model wire), ``client_headers`` (endpoint client headers, re-added on+snapshot rebuilds), ``request_headers`` (first-call-of-a-user-turn attribution) and+``max_tokens_param``: a ``custom`` route pointed at the profile's host gets them too.+"""++from unittest.mock import MagicMock, patch++import pytest++HOST = "https://api.wirefake.test/v1"+++def wire_profile():+ import providers+ from providers.base import ProviderProfile+ from utils import base_url_host_matches++ seen_keys = []++ class WireFakeProfile(ProviderProfile):+ def api_mode_for_model(self, model, *, api_key=None):+ seen_keys.append(api_key)+ return "chat_completions" if model.startswith("gpt-5-lite") else None++ def client_headers(self, *, base_url, api_key="", has_images=False):+ if not base_url_host_matches(base_url, "wirefake.test"):+ return None+ return {"X-Wire": "1", **({"X-Wire-Images": "1"} if has_images else {})}++ def request_headers(self, *, base_url, model="", user_initiated=False):+ return {"X-Attr": "user"} if user_initiated and base_url_host_matches(base_url, "wirefake.test") else {}++ def max_tokens_param(self, *, base_url, model=""):+ return "max_completion_tokens" if base_url_host_matches(base_url, "wirefake.test") else None++ providers.list_providers() # discovery first, so the fake survives it+ profile = WireFakeProfile(name="wirefake", base_url=HOST)+ providers.register_provider(profile)+ yield profile, seen_keys+ import hermes_cli.auth+ providers._REGISTRY.pop("wirefake", None)+ providers._SOURCES.pop("wirefake", None)+ providers._PROVIDER_LIST_CACHE = None+ hermes_cli.auth.PROVIDER_REGISTRY.pop("wirefake", None)+++def _agent(provider, base_url, model="gpt-4.1"):+ from run_agent import AIAgent++ with patch("agent.process_bootstrap.OpenAI") as mock_openai:+ mock_openai.return_value = MagicMock()+ return AIAgent(api_key="k", base_url=base_url, provider=provider, model=model, quiet_mode=True,+ skip_context_files=True, skip_memory=True)+++def test_api_mode_for_model_decides_responses_routing_per_model(wire_profile):+ from hermes_cli.model_switch import model_derived_api_mode+ from run_agent import AIAgent++ # The profile keeps this gpt-5 id on chat completions; the generic GPT-5 rule would upgrade it.+ assert AIAgent._provider_model_requires_responses_api("gpt-5-lite", provider="wirefake") is False+ # None defers to the generic rule.+ assert AIAgent._provider_model_requires_responses_api("gpt-5.4", provider="wirefake") is True+ # /model re-derives the wire from the profile, handing it the credential for catalog-aware ids.+ assert model_derived_api_mode("wirefake", "gpt-5-lite", "tok") == "chat_completions"+ _, seen_keys = wire_profile+ assert seen_keys[-1] == "tok"+ assert None in seen_keys # the routing path asked the pure (no-credential) form+++def test_custom_route_to_profile_host_gets_client_headers_and_max_tokens_param(wire_profile):+ from agent.agent_runtime_helpers import _ensure_route_client_headers++ agent = _agent("custom", HOST, model="llama-3.1-8b")+ assert agent._client_kwargs["default_headers"]["X-Wire"] == "1"+ assert agent._max_tokens_param(7) == {"max_completion_tokens": 7}++ # Snapshot rebuilds re-add missing endpoint headers but never override one already set.+ kwargs = {"base_url": HOST, "default_headers": {"x-wire": "user-set"}}+ _ensure_route_client_headers(kwargs, "custom")+ assert kwargs["default_headers"] == {"x-wire": "user-set"}+ kwargs = {"base_url": HOST}+ _ensure_route_client_headers(kwargs, "custom")+ assert kwargs["default_headers"] == {"X-Wire": "1"}+++def test_other_endpoints_keep_generic_behaviour(wire_profile):+ from agent.agent_runtime_helpers import _ensure_route_client_headers++ agent = _agent("custom", "https://llm.example.test/v1", model="llama-3.1-8b")+ assert "X-Wire" not in (agent._client_kwargs.get("default_headers") or {})+ assert agent._max_tokens_param(7) == {"max_tokens": 7}+ kwargs = {"base_url": "https://llm.example.test/v1"}+ _ensure_route_client_headers(kwargs, "custom")+ assert "default_headers" not in kwargs+++def test_image_request_client_carries_image_client_headers(wire_profile):+ agent = _agent("wirefake", HOST)+ built = []+ agent.client = object()+ image_request = {"model": "m", "messages": [{"role": "user", "content": [+ {"type": "text", "text": "x"}, {"type": "image_url", "image_url": {"url": "data:image/png;base64,abc"}}]}]}+ with patch.object(agent, "_is_openai_client_closed", return_value=False), patch.object(+ agent, "_create_openai_client", side_effect=lambda kw, *, reason, shared: built.append(kw) or MagicMock()):+ agent._create_request_openai_client(reason="t", api_kwargs=image_request)+ assert built[-1]["default_headers"]["X-Wire-Images"] == "1"+ assert built[-1]["default_headers"]["X-Wire"] == "1"+++def _payload(agent):+ from agent.turn_api_request import build_request_payload++ agent._empty_content_retries = 0+ build = build_request_payload(+ agent, api_messages=[{"role": "user", "content": "hi"}], _moa_prepared_request=None,+ tools_for_api=agent.tools, system_message="", api_call_count=1, api_request_id="r",+ effective_task_id="t", turn_id="u")+ return build.api_kwargs+++def test_user_turn_attribution_is_consumed_by_the_first_call_only(wire_profile):+ agent = _agent("wirefake", HOST)+ agent._is_user_initiated_turn = True+ assert _payload(agent).get("extra_headers") == {"X-Attr": "user"}+ assert agent._is_user_initiated_turn is False+ assert "X-Attr" not in (_payload(agent).get("extra_headers") or {}) # tool-loop follow-up+++def test_route_without_attribution_leaves_the_turn_flag_set(wire_profile):+ agent = _agent("custom", "https://llm.example.test/v1")+ agent._is_user_initiated_turn = True+ assert "X-Attr" not in (_payload(agent).get("extra_headers") or {})+ assert agent._is_user_initiated_turn is Truediff --git a/tui_gateway/agent_factory.py b/tui_gateway/agent_factory.pyindex 73647e40f66..ecede6cb8e4 100644--- a/tui_gateway/agent_factory.py+++ b/tui_gateway/agent_factory.py@@ -590,7 +590,7 @@ def _resolve_agent_model_runtime(model_override, provider_override) -> tuple[strdef _rederive_per_model_route(model: str, runtime: dict) -> None:"""A row's persisted api_mode/base_url were written for whichever model the session last ran. Providers- that pick the wire per model (OpenCode Zen/Go, Copilot, Nous) must re-derive both from the target model,+ that pick the wire per model (OpenCode Zen/Go, Nous, profiles with api_mode_for_model) must re-derive both from the target model,or a resumed opencode-go session keeps a MiniMax-era anthropic_messages route (and its /v1-stripped orother-family relay URL) for a chat_completions model like deepseek-v4-flash-vision-exp (#96066)."""from hermes_cli.model_switch import model_derived_api_mode