The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
fix(agent): bounded per-request profile hooks and one deterministic failure policy
Teknium356202330008
diff --git a/agent/agent_init.py b/agent/agent_init.pyindex e509e168ba0..e311afa1407 100644--- a/agent/agent_init.py+++ b/agent/agent_init.py@@ -810,7 +810,7 @@ def _explicit_client_kwargs(agent, api_key, base_url, _provider_timeout) -> dict_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,+ elif _route_headers := route_answer("client_headers", provider=str(agent.provider or ""), base_url=base_url, scope=agent,api_key=api_key if isinstance(api_key, str) else ""):client_kwargs["default_headers"] = _route_headerselif "default_headers" not in client_kwargs:diff --git a/agent/chat_completion_helpers.py b/agent/chat_completion_helpers.pyindex 0788f37bd45..b7ee890b31a 100644--- a/agent/chat_completion_helpers.py+++ b/agent/chat_completion_helpers.py@@ -1464,7 +1464,7 @@ def _build_chat_completions_kwargs(agent, api_messages, tools_for_api, reasoning_ephemeral_out = _consume_ephemeral_max_output(agent)from agent.reasoning_carriers import shape_wire_carriers- api_messages = shape_wire_carriers(api_messages, model=agent.model, base_url=agent.base_url)+ api_messages = shape_wire_carriers(api_messages, model=agent.model, base_url=agent.base_url, scope=agent)# Strip image parts for non-vision models on BOTH paths (registered# providers with profiles used to bypass it)._common = dict(model=agent.model, messages=agent._prepare_messages_for_non_vision_model(api_messages),diff --git a/agent/client_lifecycle.py b/agent/client_lifecycle.pyindex dbef342416c..f18a100727a 100644--- a/agent/client_lifecycle.py+++ b/agent/client_lifecycle.py@@ -451,7 +451,7 @@ class ClientLifecycleMixin: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 "",+ image_headers = route_answer("client_headers", provider=self.provider or "", scope=self,base_url=str(request_kwargs.get("base_url", "")),api_key=str(request_kwargs.get("api_key", "") or ""), has_images=True)if image_headers:@@ -892,7 +892,7 @@ class ClientLifecycleMixin:# 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,+ route_headers = route_answer("client_headers", provider=self.provider or "", base_url=base_url, scope=self,api_key=str(self._client_kwargs.get("api_key", "") or ""))if route_headers:self._client_kwargs["default_headers"] = dict(route_headers)diff --git a/agent/provider_route_hooks.py b/agent/provider_route_hooks.pyindex 2b36db673c0..614e033da23 100644--- a/agent/provider_route_hooks.py+++ b/agent/provider_route_hooks.py@@ -11,6 +11,7 @@ their plugin overrides.from __future__ import annotations+import copyimport loggingfrom typing import Any@@ -20,10 +21,13 @@ logger = logging.getLogger(__name__)# Per-request hooks documented pure in providers/base.py: one answer per argument set, so a hosted# plugin pays one IPC round trip per distinct request shape instead of one per API call.-_PURE_HOOKS = frozenset({"request_headers", "max_tokens_param"})+_PURE_HOOKS = frozenset({"request_headers", "max_tokens_param", "reasoning_payload",+ "replays_function_thought_signature"})_PURE_MEMO: dict[tuple, Any] = {}_PURE_MEMO_MAX = 512_MISSING = object()+# (profile name, hook) pairs whose failure was already logged: one warning per pair per process.+_WARNED: set[tuple] = set()def _overrides(profile: Any, hook: str) -> bool:@@ -42,30 +46,81 @@ def route_profiles(hook: str, provider: str = "", base_url: str = "") -> list[Anreturn ordered-def _ask(profile: Any, hook: str, kwargs: dict[str, Any]) -> Any:+def _freeze(value: Any) -> Any:+ if isinstance(value, dict):+ return tuple(sorted((str(k), _freeze(v)) for k, v in value.items()))+ if isinstance(value, (list, tuple)):+ return tuple(_freeze(v) for v in value)+ return value+++def _ask(profile: Any, hook: str, args: tuple, kwargs: dict[str, Any]) -> Any:if hook not in _PURE_HOOKS:- return getattr(profile, hook)(**kwargs)+ return getattr(profile, hook)(*args, **kwargs)from providers import registry_generation- key = (registry_generation(), id(profile), type(profile), hook, tuple(sorted(kwargs.items())))+ key = (registry_generation(), id(profile), type(profile), hook, _freeze(args), _freeze(kwargs))+ try:+ hash(key)+ except TypeError: # an argument with no stable value (e.g. a set): ask every time+ return getattr(profile, hook)(*args, **kwargs)# One read into a local: another thread may clear() the memo between a check and a re-read.answer = _PURE_MEMO.get(key, _MISSING)if answer is _MISSING:- answer = getattr(profile, hook)(**kwargs)+ answer = getattr(profile, hook)(*args, **kwargs)if len(_PURE_MEMO) >= _PURE_MEMO_MAX:_PURE_MEMO.clear()_PURE_MEMO[key] = answer- return dict(answer) if isinstance(answer, dict) else answer---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."""+ return copy.deepcopy(answer) if isinstance(answer, (dict, list)) else answer+++def _failures(scope: Any) -> set[tuple]:+ if scope is None: # one-shot caller (auxiliary request): no later turn to keep stable+ return set()+ failed = getattr(scope, "_provider_hook_failures", None)+ if failed is None:+ failed = set()+ scope._provider_hook_failures = failed+ return failed+++def _sticky_key(profile: Any, hook: str) -> tuple:+ return (id(profile), type(profile), getattr(profile, "name", "?"), hook)+++def hook_failed(profile: Any, hook: str, scope: Any = None) -> bool:+ """True once *profile*'s *hook* failed in *scope* (``ask_profile`` then answers the fallback)."""+ return _sticky_key(profile, hook) in _failures(scope)+++def ask_profile(profile: Any, hook: str, fallback: Any, *args: Any, scope: Any = None, **kwargs: Any) -> Any:+ """*profile*'s answer to the per-request *hook* (documented-pure hooks are memoized).++ ONE failure policy for every per-request profile hook: a failure is logged once per (profile, hook)+ per process and answers *fallback* (the generic answer); *scope* (the agent) then keeps answering+ *fallback* without asking again, so a session's request bytes never flip between turns after a+ plugin bug or a lost plugin host. ``scope=None`` (one-shot auxiliary calls) asks again next call.+ """+ failed = _failures(scope)+ sticky = _sticky_key(profile, hook)+ if sticky in failed:+ return fallback+ try:+ return _ask(profile, hook, args, kwargs)+ except Exception as exc: # plugin code: a broken hook degrades to generic behaviour, never fails the request+ failed.add(sticky)+ if sticky[2:] not in _WARNED:+ _WARNED.add(sticky[2:])+ logger.warning("provider %s: %s hook failed (%s: %s); using the generic answer for the rest of "+ "the session", sticky[2], hook, type(exc).__name__, exc, exc_info=True)+ return fallback+++def route_answer(hook: str, *, provider: str = "", scope: Any = None, **kwargs: Any) -> Any:+ """First truthy answer of *hook* across ``route_profiles``; None when no profile claims the endpoint.+ Failures follow ``ask_profile``'s policy (*scope* = the agent, when there is one)."""for profile in route_profiles(hook, provider, str(kwargs.get("base_url") or "")):- try:- answer = _ask(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+ answer = ask_profile(profile, hook, None, scope=scope, **kwargs)if answer:return answerreturn Nonediff --git a/agent/reasoning_carriers.py b/agent/reasoning_carriers.pyindex 18cdd63352a..e853eb244a3 100644--- a/agent/reasoning_carriers.py+++ b/agent/reasoning_carriers.py@@ -115,17 +115,67 @@ class _WireRoute(NamedTuple):profile: Any # profile serving the host (``providers.profile_for_host``) or Nonekeep_fn_sig: bool # replayed tool calls keep ``function.thought_signature``keys: tuple[str, ...] # every message-level carrier key core knows about+ scope: Any # who remembers a failed hook (``provider_route_hooks.ask_profile``): the agent, or None-def _wire_route(model: Any, base_url: Any) -> _WireRoute:+def _wire_route(model: Any, base_url: Any, scope: Any = None) -> _WireRoute:from providers import profile_for_host+ from agent.provider_route_hooks import ask_profilefrom agent.transports.chat_completions import _model_consumes_thought_signatureurl = str(base_url or "")profile = profile_for_host(url)- keep_fn_sig = profile is not None and profile.replays_function_thought_signature(model=model, base_url=url)+ keep_fn_sig = profile is not None and bool(ask_profile(+ profile, "replays_function_thought_signature", False, model=model, base_url=url, scope=scope))# Same gate as tool-call extra_content, so the two signature carriers can never disagree.- return _WireRoute(model, url, _model_consumes_thought_signature(model), profile, keep_fn_sig, _message_keys())+ return _WireRoute(model, url, _model_consumes_thought_signature(model), profile, keep_fn_sig, _message_keys(),+ scope)+++# ``replay_message_carriers`` answers by which carrier keys are present (providers/base.py), so its answer+# for one key set is kept as a key mapping and applied to every message with that key set: one hook call+# per (route, key set) instead of one per carrier-bearing message per request.+_REPLAY_PLANS: dict[tuple, Any] = {}+_REPLAY_PLANS_MAX = 512+_REWRITES = object() # the hook rewrites values: ask it per message+_FAILED = object()+++def _replay_plan(answer: Any, values: dict) -> Any:+ """``((out key, source key), ...)`` reproducing *answer* from *values*; None when ambiguous."""+ if not isinstance(answer, dict):+ return _REWRITES+ plan = []+ for out_key, out_value in answer.items():+ sources = [k for k, v in values.items() if v == out_value]+ if not sources:+ return _REWRITES+ if len(sources) > 1:+ return None+ plan.append((out_key, sources[0]))+ return tuple(plan)+++def _replay_carriers(route: _WireRoute, values: dict) -> dict:+ from providers import registry_generation+ from agent.provider_route_hooks import ask_profile, hook_failed++ if hook_failed(route.profile, "replay_message_carriers", route.scope):+ return {}+ key = (registry_generation(), id(route.profile), type(route.profile), route.model, route.base_url,+ tuple(sorted(values)))+ plan = _REPLAY_PLANS.get(key)+ if plan is not None and plan is not _REWRITES:+ return {out: values[src] for out, src in plan}+ answer = ask_profile(route.profile, "replay_message_carriers", _FAILED, values, model=route.model,+ base_url=route.base_url, scope=route.scope)+ if answer is _FAILED:+ return {}+ if plan is None and (plan := _replay_plan(answer, values)) is not None:+ if len(_REPLAY_PLANS) >= _REPLAY_PLANS_MAX:+ _REPLAY_PLANS.clear()+ _REPLAY_PLANS[key] = plan+ return dict(answer or {})def _strip_function_signature(tool_calls: list) -> list:@@ -164,15 +214,22 @@ def _shape(msg: Any, route: _WireRoute) -> Any:if route.gemini and values.get(_GEMINI_KEY):out[_GEMINI_KEY] = values[_GEMINI_KEY]if route.profile is not None:- out.update(route.profile.replay_message_carriers(values, model=route.model, base_url=route.base_url))+ out.update(_replay_carriers(route, values))if fn_sig:out["tool_calls"] = _strip_function_signature(tool_calls)return out-def shape_wire_carriers(messages: list, *, model: Any, base_url: Any) -> list:+def shape_wire_carriers(messages: list, *, model: Any, base_url: Any, scope: Any = None) -> list:"""Wire copy of ``messages`` with each carrier on the route that reads it and nowhere else.- Never mutates the input; unchanged messages are returned by identity."""- route = _wire_route(model, base_url)+ Never mutates the input; unchanged messages are returned by identity. *scope* is the agent (failed+ profile hooks stay failed for it; see ``provider_route_hooks.ask_profile``)."""+ from agent.provider_route_hooks import hook_failed++ route = _wire_route(model, base_url, scope)+ failed_before = route.profile is None or hook_failed(route.profile, "replay_message_carriers", scope)shaped = [_shape(m, route) for m in messages]+ if not failed_before and hook_failed(route.profile, "replay_message_carriers", scope):+ # Failed mid-request: reshape so every message takes the fallback, as every later request will.+ shaped = [_shape(m, route) for m in messages]return messages if all(a is b for a, b in zip(shaped, messages)) else shapeddiff --git a/agent/reasoning_params.py b/agent/reasoning_params.pyindex 73abe897e4a..5cc06ce1949 100644--- a/agent/reasoning_params.py+++ b/agent/reasoning_params.py@@ -96,10 +96,9 @@ class ReasoningParamsMixin:if (profile := profile_for_host(str(getattr(self, "base_url", None) or ""))) is not None:# A claimed endpoint gates on its own catalog: reasoning goes out iff it declares a payload.- try:- return profile.reasoning_payload(self.model, None, base_url=self.base_url) is not None- except Exception:- return False+ from agent.provider_route_hooks import ask_profile+ return ask_profile(profile, "reasoning_payload", None, self.model, None,+ base_url=self.base_url, scope=self) is not Noneif (self.provider or "").strip().lower() == "lmstudio":# "off-only" (or absent) means no real reasoning capability.return any(opt and opt != "off" for opt in self._lmstudio_reasoning_options_cached())@@ -147,7 +146,9 @@ class ReasoningParamsMixin:profile = profile_for_host(str(base_url or ""))if profile is None:return None- return profile.reasoning_payload(self.model, self.reasoning_config, base_url=str(base_url))+ from agent.provider_route_hooks import ask_profile+ return ask_profile(profile, "reasoning_payload", None, self.model, self.reasoning_config,+ base_url=str(base_url), scope=self)def _build_assistant_message(self, assistant_message, finish_reason: str) -> dict:"""``build_assistant_message``; a held turn's row with visible text comes back typed hiddendiff --git a/agent/turn_api_request.py b/agent/turn_api_request.pyindex 9f0021ea9ff..26fa1f79998 100644--- a/agent/turn_api_request.py+++ b/agent/turn_api_request.py@@ -53,7 +53,7 @@ def _apply_user_turn_request_headers(agent: Any, api_kwargs: Any, api_call_countfrom 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)+ model=agent.model or "", user_initiated=True, scope=agent)for _key, _value in (_request_headers or {}).items():_set_extra_header(api_kwargs, _key, _value)diff --git a/providers/base.py b/providers/base.pyindex f92135ba3e6..e166f4b391e 100644--- a/providers/base.py+++ b/providers/base.py@@ -663,7 +663,8 @@ class ProviderProfile:# ── Lane L3: Responses-route quirks and message-level reasoning carriers ───# Every field and hook below applies only on hosts the profile declares in ``hostnames``;- # the defaults are the generic wire. Hot path: answers must be pure and cheap (no I/O).+ # the defaults are the generic wire. Hot path: answers must be pure and cheap (no I/O). A hook that+ # raises is logged once and answers the default for the rest of the session (provider_route_hooks).responses_replay_item_ids: bool = True # replayed Responses ``message`` items keep their ``id``responses_prompt_cache_key: bool = True # the Responses body carries ``prompt_cache_key``responses_issuer_kind: str = "" # persisted stamp for encrypted reasoning minted here ("" = URL-derived)@@ -675,15 +676,20 @@ class ProviderProfile:replays_tool_call_signatures: bool = False # tool calls keep Gemini ``extra_content`` signatures (by provider name)def reasoning_payload(self, model: str | None, reasoning_config: dict | None, *, base_url: str) -> dict | None:- """Verbatim ``reasoning`` object the endpoint takes for *model* (catalog-clamped), or None for none."""+ """Verbatim ``reasoning`` object the endpoint takes for *model* (catalog-clamped), or None for none.+ Pure: memoized per arguments."""return Nonedef replay_message_carriers(self, values: dict[str, Any], *, model: str | None, base_url: str) -> dict[str, Any]:- """Captured message carriers (``message_carrier_*`` keys) to put back on a replayed assistant message."""+ """Captured message carriers (``message_carrier_*`` keys) to put back on a replayed assistant message.+ Decide from which keys are present, not their content: core asks once per (model, base_url, key set)+ and replays the same keys for every message with that key set (an answer whose values are not+ copies of input values is asked per message)."""return {}def replays_function_thought_signature(self, *, model: str | None, base_url: str) -> bool:- """True when replayed tool calls keep ``function.thought_signature`` (stripped everywhere else)."""+ """True when replayed tool calls keep ``function.thought_signature`` (stripped everywhere else).+ Pure: memoized per arguments."""return False# --- I2-cat: provider-owned catalog sources ---diff --git a/run_agent.py b/run_agent.pyindex 5c3070a0a6a..643cf274455 100644--- a/run_agent.py+++ b/run_agent.py@@ -659,7 +659,7 @@ class AIAgent(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 "",+ declared = route_answer("max_tokens_param", provider=getattr(self, "provider", "") or "", scope=self,base_url=getattr(self, "base_url", "") or "", model=self.model or "")if declared:return {declared: value}diff --git a/tests/agent/test_provider_hook_policy.py b/tests/agent/test_provider_hook_policy.pynew file mode 100644index 00000000000..58701fd95f4--- /dev/null+++ b/tests/agent/test_provider_hook_policy.py@@ -0,0 +1,140 @@+"""Per-request ProviderProfile hooks on the request-build hot path: bounded calls, one failure policy.++A host-claiming plugin profile is asked about every request (under ``plugins.isolation: host`` each+ask is an IPC round trip). Its answers must not cost O(history) per request, and a hook that raises+must leave the session on the generic answer from then on, so request bytes never flip between turns.+"""++import copy+import json+import logging+from unittest.mock import MagicMock, patch++import pytest++HOST = "https://api.hookpolicy.test/v1"+CARRIER = "hermes.native_assistant"+++def make_profile(request, monkeypatch):+ import providers+ from agent import provider_route_hooks+ from providers.base import ProviderProfile++ monkeypatch.setattr(provider_route_hooks, "_WARNED", set(), raising=False)++ def make(**hooks):+ cls = type("HookPolicyProfile", (ProviderProfile,), hooks)+ profile = cls(name="hookpolicy", base_url=HOST, hostnames=("hookpolicy.test",),+ message_carrier_opaque="hp_opaque", message_carrier_text="hp_text")+ providers.list_providers() # discovery first, so the fake survives it+ providers.register_provider(profile)+ return profile++ def _cleanup():+ providers._REGISTRY.pop("hookpolicy", None)+ providers._SOURCES.pop("hookpolicy", None)+ providers._PROVIDER_LIST_CACHE = None++ request.addfinalizer(_cleanup)+ return make+++def _agent():+ 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=HOST, provider="custom", api_mode="chat_completions", model="m1",+ quiet_mode=True, skip_context_files=True, skip_memory=True, enabled_toolsets=[],+ reasoning_config={"enabled": True, "effort": "high"})+++def _history(turns, *, text_every=0, text_at=()):+ hist = [{"role": "system", "content": "s"}]+ for i in range(turns):+ record = {"type": CARRIER, "hp_opaque": f"OPQ{i}"}+ if (text_every and i % text_every == 0) or i in text_at:+ record["hp_text"] = f"T{i}"+ hist += [{"role": "user", "content": f"u{i}"},+ {"role": "assistant", "content": f"a{i}", "reasoning_details": [record]}]+ return hist + [{"role": "user", "content": "next"}]+++def _wire(agent, hist):+ kwargs = agent._build_api_kwargs(copy.deepcopy(hist))+ return kwargs["messages"], kwargs.get("extra_body", {}).get("reasoning")+++def _replay(self, values, *, model, base_url):+ return {k: values[k] for k in ("hp_opaque", "hp_text") if values.get(k)}+++def test_long_history_asks_the_replay_hook_once_per_carrier_key_set(make_profile):+ calls = []++ def replay_message_carriers(self, values, *, model, base_url):+ calls.append(tuple(sorted(values)))+ return _replay(self, values, model=model, base_url=base_url)++ make_profile(replay_message_carriers=replay_message_carriers)+ agent = _agent()+ hist = _history(50, text_every=5)+ messages, _ = _wire(agent, hist)+ assert len(calls) == 2 # two key sets ({opaque}, {opaque, text}), not 50 messages+ replayed = [(m.get("hp_opaque"), m.get("hp_text")) for m in messages if m["role"] == "assistant"]+ assert replayed == [(f"OPQ{i}", f"T{i}" if i % 5 == 0 else None) for i in range(50)]+ _wire(agent, hist)+ assert len(calls) == 2 # the next request asks nothing new+++def test_failing_reasoning_hook_keeps_the_session_on_the_generic_answer(make_profile, caplog):+ state = {"fail": True, "calls": 0}++ def reasoning_payload(self, model, reasoning_config, *, base_url):+ state["calls"] += 1+ if state["fail"]:+ raise RuntimeError("plugin host went away")+ return {"effort": "high"}++ make_profile(reasoning_payload=reasoning_payload, replay_message_carriers=_replay)+ agent = _agent()+ hist = _history(3)+ def request(): # the wire plus the two reasoning gates built from this hook+ return _wire(agent, hist), agent._supports_reasoning_extra_body(), agent._endpoint_reasoning_payload()++ with caplog.at_level(logging.WARNING, logger="agent.provider_route_hooks"):+ first = request()+ state["fail"] = False # the hook recovers; the session must not flip back mid-conversation+ later = [request() for _ in range(2)]+ assert first[1:] == (False, None)+ assert first[0][0][2]["hp_opaque"] == "OPQ0" # the other hooks of the profile keep working+ assert all(json.dumps(r, sort_keys=True) == json.dumps(first, sort_keys=True) for r in later)+ assert state["calls"] == 1+ assert len([r for r in caplog.records if "reasoning_payload" in r.getMessage()]) == 1+ # A new session asks again (the failure is the agent's, not the process's).+ assert _agent()._endpoint_reasoning_payload() == {"effort": "high"}+++def test_replay_hook_failing_on_a_later_call_never_flips_bytes_after_that_turn(make_profile, caplog):+ calls = []++ def replay_message_carriers(self, values, *, model, base_url):+ calls.append(1)+ if len(calls) >= 2:+ raise RuntimeError("plugin bug")+ return _replay(self, values, model=model, base_url=base_url)++ make_profile(replay_message_carriers=replay_message_carriers)+ agent = _agent()+ hist = _history(4)+ first, _ = _wire(agent, hist)+ assert first[2]["hp_opaque"] == "OPQ0"+ hist = _history(4, text_at=(3,)) # a new key set late in history: the hook is asked again and fails+ with caplog.at_level(logging.WARNING, logger="agent.provider_route_hooks"):+ second, _ = _wire(agent, hist)+ third, _ = _wire(agent, hist)+ assert second == third+ assert not any("hp_opaque" in m or "hp_text" in m for m in second) # generic: carriers stripped+ assert len([r for r in caplog.records if "replay_message_carriers" in r.getMessage()]) == 1