From 54e24ae1fa09a172ccafb517719de07707185853 Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Sun, 6 Sep 2026 05:45:44 -0700 Subject: [PATCH 1/2] fix(nous): route anthropic/* over chat/completions by default (nous.anthropic_wire) Portal serves anthropic/* on two routes. The native /v1/messages wire, which Hermes has used since 02d5e230858, re-writes the previous turn's prompt cache on 14-20% of consecutive calls in concurrent tool loops; the chat/completions route does not. Measured 2026-09-06, 20 concurrent sessions x 6 tool calls on Fable 5.1, same account, same hour, same first-party pin: Nous /v1/messages 180 pairs, 25 stuck (13.9%); 3 earlier 40-session runs 15.0 / 17.3 / 20.2%; unchanged by the pin Nous /v1/chat/completions 320 pairs (2 runs), 0 stuck OpenRouter direct, pinned 161 pairs, 0 stuck "stuck" = cache_read on call k+1 equals cache_read on call k instead of call k's prompt size: the last write was not visible, the turn (~28K) was written twice. Every stuck pair had byte-identical system, tools and per-message shas, so it is not client-side mutation. At $10-20/M for cache writes that is 15-20% of a fan-out's write bill. The cause is inside the portal's native route (every element of its outgoing request reproduces clean from outside; NousResearch/api#227 carries the diagnostics). Until it is fixed, anthropic/* rides chat/completions. nous.anthropic_wire: native opts back in. Cost of chat: prior-turn thinking travels as OpenAI-style reasoning fields, and cache_control scopes are translated by the portal's adapter. Tests: new test_nous_anthropic_wire_default.py reads the knob through the real config loader in a temp HERMES_HOME and through resolve_runtime_provider (both settings); the existing native-wire contract suite selects native via an autouse fixture so the wire keeps working for the flip-back. Live: a real AIAgent on this branch, provider=nous + anthropic/claude-fable-5.1, dispatches to chat/completions with the session_id intact. --- hermes_cli/config_defaults.py | 7 +++ hermes_cli/providers.py | 27 ++++++++-- .../agent/test_nous_portal_anthropic_wire.py | 10 ++++ .../test_nous_anthropic_wire_default.py | 54 +++++++++++++++++++ website/docs/user-guide/configuring-models.md | 11 ++++ 5 files changed, 105 insertions(+), 4 deletions(-) create mode 100644 tests/hermes_cli/test_nous_anthropic_wire_default.py diff --git a/hermes_cli/config_defaults.py b/hermes_cli/config_defaults.py index 1f98ab6024..12e08a5ecb 100644 --- a/hermes_cli/config_defaults.py +++ b/hermes_cli/config_defaults.py @@ -2284,6 +2284,13 @@ DEFAULT_CONFIG = { # server-issued credential lifetime (raising above it has no effect). 0 disables the # keepalive thread. "keepalive_interval_seconds": 900, + # anthropic_wire: which Portal route carries anthropic/* models. "chat" = + # /v1/chat/completions (default for now); "native" = /v1/messages, the Anthropic + # Messages wire (signed thinking passthrough, native cache_control scopes). Native is the + # better wire but re-writes the previous turn's cache on 14-20% of consecutive calls in + # concurrent tool loops (measured 2026-09-06; NousResearch/api#227), so chat is the + # default until that is fixed. + "anthropic_wire": "chat", }, # Google Vertex AI (Gemini). Auth is OAuth2 from a service-account JSON or ADC, NOT an API key; # the credential path lives in .env (VERTEX_CREDENTIALS_PATH / GOOGLE_APPLICATION_CREDENTIALS). diff --git a/hermes_cli/providers.py b/hermes_cli/providers.py index 20edd8837a..dbec5d698a 100644 --- a/hermes_cli/providers.py +++ b/hermes_cli/providers.py @@ -309,14 +309,33 @@ def host_mandated_api_mode(base_url: str = "") -> Optional[str]: def nous_api_mode(model: str = "") -> str: - """Wire protocol for a Nous Portal model: Portal serves its ``anthropic/*`` catalog on a native - Messages route alongside OpenAI-compatible chat/completions for everything else. Empty/unknown - model defaults to ``chat_completions`` (the historical Nous transport) as the safer path.""" + """Wire protocol for a Nous Portal model. Portal serves its ``anthropic/*`` catalog on a native + Messages route alongside OpenAI-compatible chat/completions for everything else. + + ``anthropic/*`` rides chat/completions by default for now (``nous.anthropic_wire``). Measured + 2026-09-06, 20 concurrent sessions x 6 tool calls on Fable 5.1, same account and hour: the + native route re-wrote the previous turn on 14-20% of consecutive calls (4 runs; the cache read + stopped at the prior breakpoint with byte-identical prefixes), chat/completions 0 of 320 pairs. + That is 15-20% of a fan-out's cache-write bill. The cause is inside the portal's native route + (NousResearch/api#227 carries the diagnostics); flip the default back to ``native`` when it is + fixed. Cost of ``chat``: prior-turn thinking travels as OpenAI-style reasoning fields instead of + signed native blocks, and cache_control scopes are translated by the portal's adapter. + Empty/unknown model defaults to ``chat_completions`` (the historical Nous transport).""" if str(model or "").strip().lower().startswith("anthropic/"): - return "anthropic_messages" + return "anthropic_messages" if _nous_anthropic_wire() == "native" else "chat_completions" return "chat_completions" +def _nous_anthropic_wire() -> str: + """``nous.anthropic_wire``: ``"chat"`` (default) or ``"native"``. Anything else reads as ``chat``.""" + try: + from hermes_cli.config import load_config_readonly + value = str(((load_config_readonly().get("nous") or {}).get("anthropic_wire")) or "chat").strip().lower() + except Exception: + return "chat" + return "native" if value == "native" else "chat" + + def determine_api_mode(provider: str, base_url: str = "", model: str = "") -> str: """API mode (wire protocol) for a provider/endpoint: host-mandated mode, then Nous dual-wire (model-derived — the overlay alone says openai_chat and would pin Claude on the wrong wire), diff --git a/tests/agent/test_nous_portal_anthropic_wire.py b/tests/agent/test_nous_portal_anthropic_wire.py index af85a6003e..32f9eb756e 100644 --- a/tests/agent/test_nous_portal_anthropic_wire.py +++ b/tests/agent/test_nous_portal_anthropic_wire.py @@ -21,8 +21,18 @@ from unittest.mock import MagicMock, patch import pytest from hermes_cli import runtime_provider as rp +from hermes_cli import providers as _providers from hermes_cli.providers import nous_api_mode + +@pytest.fixture(autouse=True) +def _native_wire_selected(monkeypatch): + """These contracts describe the native wire, which is now opt-in (``nous.anthropic_wire: + native``; default ``chat`` since 2026-09-06, see ``nous_api_mode``). Select it here so the + wire keeps working for the flip-back; the default's own contract is in + ``test_nous_anthropic_wire_default.py``.""" + monkeypatch.setattr(_providers, "_nous_anthropic_wire", lambda: "native") + PORTAL_URL = "https://inference-api.nousresearch.com/v1" # Staging / preview hosts used via NOUS_INFERENCE_BASE_URL — not the prod # hostname, so Portal behaviour must key off provider=nous. diff --git a/tests/hermes_cli/test_nous_anthropic_wire_default.py b/tests/hermes_cli/test_nous_anthropic_wire_default.py new file mode 100644 index 0000000000..907f6ade16 --- /dev/null +++ b/tests/hermes_cli/test_nous_anthropic_wire_default.py @@ -0,0 +1,54 @@ +"""``nous.anthropic_wire`` selects the Portal route for ``anthropic/*``: ``chat`` (default) rides +/v1/chat/completions, ``native`` rides /v1/messages. Read through the real config loader against a +temp HERMES_HOME (the loader is keyed on config path + mtime, so a fresh home is a fresh read), and +through ``resolve_runtime_provider`` so the api_mode a live agent gets is what is asserted.""" +from __future__ import annotations + +import pytest + +from hermes_cli import providers as _providers +from hermes_cli import runtime_provider as rp + +PORTAL = "https://inference-api.nousresearch.com/v1" + + +def _cfg(tmp_path, body: str, monkeypatch): + monkeypatch.setenv("HERMES_HOME", str(tmp_path)) + (tmp_path / "config.yaml").write_text(body, encoding="utf-8") + + +def _portal_creds(monkeypatch): + monkeypatch.setattr(rp, "resolve_nous_runtime_credentials", + lambda **kw: {"base_url": PORTAL, "api_key": "jwt", "source": "portal", "expires_at": None}) + monkeypatch.setattr(rp, "_get_model_config", lambda: {"provider": "nous"}) + + +def test_default_is_chat_for_anthropic_and_unchanged_for_everything_else(tmp_path, monkeypatch): + _cfg(tmp_path, "model:\n default: anthropic/claude-fable-5.1\n", monkeypatch) + assert _providers.nous_api_mode("anthropic/claude-fable-5.1") == "chat_completions" + assert _providers.nous_api_mode("openai/gpt-5.6-sol") == "chat_completions" + assert _providers.determine_api_mode("nous", PORTAL, "anthropic/claude-fable-5.1") == "chat_completions" + + +def test_native_opt_in_restores_the_messages_wire_for_anthropic_only(tmp_path, monkeypatch): + _cfg(tmp_path, "nous:\n anthropic_wire: native\n", monkeypatch) + assert _providers.nous_api_mode("anthropic/claude-fable-5.1") == "anthropic_messages" + assert _providers.nous_api_mode("openai/gpt-5.6-sol") == "chat_completions" + + +@pytest.mark.parametrize("raw", ["''", "CHAT", "messages", "true", "1"]) +def test_anything_but_native_reads_as_chat(tmp_path, monkeypatch, raw): + _cfg(tmp_path, f"nous:\n anthropic_wire: {raw}\n", monkeypatch) + assert _providers.nous_api_mode("anthropic/claude-fable-5.1") == "chat_completions" + + +def test_runtime_resolution_hands_a_live_agent_the_selected_wire(tmp_path, monkeypatch): + """The path an AIAgent takes: provider=nous + anthropic model -> api_mode, both settings.""" + _portal_creds(monkeypatch) + _cfg(tmp_path, "model:\n provider: nous\n", monkeypatch) + resolved = rp.resolve_runtime_provider(requested="nous", target_model="anthropic/claude-fable-5.1") + assert (resolved["api_mode"], resolved["base_url"]) == ("chat_completions", PORTAL) + + _cfg(tmp_path, "model:\n provider: nous\nnous:\n anthropic_wire: native\n", monkeypatch) + resolved = rp.resolve_runtime_provider(requested="nous", target_model="anthropic/claude-fable-5.1") + assert resolved["api_mode"] == "anthropic_messages" diff --git a/website/docs/user-guide/configuring-models.md b/website/docs/user-guide/configuring-models.md index 0456c391e4..b9683f2826 100644 --- a/website/docs/user-guide/configuring-models.md +++ b/website/docs/user-guide/configuring-models.md @@ -234,6 +234,17 @@ omitted, Hermes keeps its normal provider and model capability detection. Older configs used a top-level `custom_providers:` list (with `base_url` instead of `api`). It still works and is auto-migrated to the `providers:` dict on `hermes update` (config v12). ::: +### Nous Portal: which wire carries Claude + +Nous Portal serves its `anthropic/*` models on two routes: OpenAI-compatible `/v1/chat/completions` and the native Anthropic Messages wire `/v1/messages`. `nous.anthropic_wire` picks one: + +```yaml +nous: + anthropic_wire: chat # default. "native" = the Anthropic Messages wire +``` + +`chat` is the default for now. The native wire is the better transport (signed thinking blocks pass through unchanged, native `cache_control` scopes), but in concurrent tool loops it currently re-writes the previous turn's prompt cache on 14–20% of consecutive calls, which is 15–20% of a fan-out's cache-write bill; the chat route measured 0 on the same test. Set `native` to opt back in (for example once the portal-side fix has shipped). Only `anthropic/*` models are affected; everything else on Nous already uses chat/completions. + ## When does it take effect? - **CLI** (`hermes chat`): next `hermes chat` invocation. From 335ecf9f4a0f056d170a661d33245c1769fd230a Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Sun, 6 Sep 2026 05:55:18 -0700 Subject: [PATCH 2/2] test: the two remaining native-wire contracts select nous.anthropic_wire=native explicitly test_nous_anthropic_fallback_uses_the_messages_wire and test_nous_child_rederives_api_mode_from_model describe the native wire, which is now opt-in; select it in the test the same way the wire-contract suite does, so both keep guarding the flip-back. --- tests/run_agent/test_provider_fallback.py | 9 ++++++--- tests/tools/test_delegate.py | 7 ++++++- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/tests/run_agent/test_provider_fallback.py b/tests/run_agent/test_provider_fallback.py index 434ee306e6..8fffe2dda7 100644 --- a/tests/run_agent/test_provider_fallback.py +++ b/tests/run_agent/test_provider_fallback.py @@ -215,13 +215,16 @@ class TestFallbackChainAdvancement: assert mock_rpc.call_args.kwargs["explicit_api_key"] == "env-secret" - def test_nous_anthropic_fallback_uses_the_messages_wire(self): - """Portal Claude fallbacks must not stay on chat_completions. + def test_nous_anthropic_fallback_uses_the_messages_wire(self, monkeypatch): + """Portal Claude fallbacks must not stay on chat_completions when the native wire is selected. ``resolve_provider_client`` still returns an OpenAI client for Nous; activation has to re-derive api_mode from the model and rebuild the - Anthropic client — otherwise the turn POSTs /chat/completions. + Anthropic client — otherwise the turn POSTs /chat/completions. The wire + is opt-in since 2026-09-06 (``nous.anthropic_wire``, see ``nous_api_mode``). """ + from hermes_cli import providers as _providers + monkeypatch.setattr(_providers, "_nous_anthropic_wire", lambda: "native") portal = "https://inference-api.nousresearch.com/v1" fbs = [ { diff --git a/tests/tools/test_delegate.py b/tests/tools/test_delegate.py index 63d28cc121..58cb77fdc8 100644 --- a/tests/tools/test_delegate.py +++ b/tests/tools/test_delegate.py @@ -423,7 +423,12 @@ class TestDelegateTask(unittest.TestCase): def test_nous_child_rederives_api_mode_from_model(self): """Portal is dual-wire — same provider + different model prefix must - not inherit the parent's Messages/chat_completions mode verbatim.""" + not inherit the parent's Messages/chat_completions mode verbatim. + Native wire selected (opt-in since 2026-09-06, ``nous.anthropic_wire``).""" + with patch("hermes_cli.providers._nous_anthropic_wire", return_value="native"): + self._nous_child_rederives_api_mode_from_model() + + def _nous_child_rederives_api_mode_from_model(self): parent = _make_mock_parent(depth=0) parent.base_url = "https://inference-api.nousresearch.com/v1" parent.api_key = "portal-jwt"