Skip to content

The agent that grows with you

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.py
index 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) -> dict
client_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_provider
if _is_external_process_provider(agent.provider):
client_kwargs["command"] = agent.acp_command
client_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_headers
elif "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.py
index 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.py
index 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_providers
candidates = 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"] = existing
def _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_headers
diff --git a/agent/auxiliary_client.py b/agent/auxiliary_client.py
index 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), model
if 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 = route
elif 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: C
return _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.py
index 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)
break
else:
- # 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_profile
profile = 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.py
index 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.py
new file mode 100644
index 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 None
diff --git a/agent/turn_api_request.py b/agent/turn_api_request.py
index 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 the
reasoning echo pad and prompt-cache decoration for the CURRENT provider (a fallback may
differ 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 = False
try:
from hermes_cli.middleware import apply_llm_request_middleware
diff --git a/hermes_cli/model_switch.py b/hermes_cli/model_switch.py
index 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_family
key = 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 None
diff --git a/plugins/model-providers/copilot/__init__.py b/plugins/model-providers/copilot/__init__.py
index 745ee4a2814..8d226af84bf 100644
--- a/plugins/model-providers/copilot/__init__.py
+++ b/plugins/model-providers/copilot/__init__.py
@@ -10,8 +10,10 @@ from typing import Any
from providers import register_provider
from 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.py
new file mode 100644
index 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 None
diff --git a/providers/base.py b/providers/base.py
index 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.py
index 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 = False
self._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_provider
if _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.py
new file mode 100644
index 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 True
diff --git a/tui_gateway/agent_factory.py b/tui_gateway/agent_factory.py
index 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[str
def _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 or
other-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