AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
fix(providers): stop sending OpenRouter-only usage field to local gateways
sierracarloslma485b273ef43
diff --git a/.env.example b/.env.exampleindex 46d570d9..fd078f9e 100644--- a/.env.example+++ b/.env.example@@ -95,6 +95,16 @@ LOCAL_API_KEY=LOCAL_MODELS=# Local generation (especially on CPU) can be slow — generous timeout (seconds).LOCAL_TIMEOUT_S=300+# Off by default. The `usage: {include: true}` request field is an+# OpenRouter-only cost-accounting extension, not part of the OpenAI or+# Anthropic request schema — a plain self-hosted server (Ollama, vLLM) or a+# strict gateway that forwards nearly verbatim to real Anthropic rejects an+# unrecognized top-level field outright instead of ignoring it (every local+# call returns 400). Only enable this if you've confirmed your LOCAL_BASE_URL+# backend actually speaks OpenRouter's request format — some hosted, billed+# gateways do, and then this restores real USD cost tracking on the+# /audit cache_event rows for those calls.+LOCAL_INCLUDE_USAGE_ACCOUNTING=false## To run with NO Anthropic key, configure the three lines above AND point the# model settings at local slugs:diff --git a/packages/core/openexecutive/config.py b/packages/core/openexecutive/config.pyindex 209b859b..9a7ab6c8 100644--- a/packages/core/openexecutive/config.py+++ b/packages/core/openexecutive/config.py@@ -224,6 +224,17 @@ class Settings(BaseSettings):# Local generation (especially CPU inference) can be far slower than a# hosted API. Default generous so a slow first token doesn't time out.local_timeout_s: float = Field(300.0, alias="LOCAL_TIMEOUT_S")+ # Off by default: the `usage: {include: true}` request field is an+ # OpenRouter-only accounting extension, not part of the OpenAI or+ # Anthropic request schema. A plain self-hosted server (Ollama, vLLM) or+ # a strict gateway that forwards nearly verbatim to real Anthropic will+ # reject an unrecognized top-level field outright instead of ignoring+ # it. Only turn this on if you've confirmed your LOCAL_BASE_URL backend+ # actually understands OpenRouter's request format (some hosted, billed+ # gateways do) — otherwise every local-model call 400s.+ local_include_usage_accounting: bool = Field(+ False, alias="LOCAL_INCLUDE_USAGE_ACCOUNTING"+ )@field_validator("local_models", mode="before")@classmethoddiff --git a/packages/core/openexecutive/providers/openai_compatible.py b/packages/core/openexecutive/providers/openai_compatible.pyindex e97c1930..996b5653 100644--- a/packages/core/openexecutive/providers/openai_compatible.py+++ b/packages/core/openexecutive/providers/openai_compatible.py@@ -81,6 +81,7 @@ class OpenAICompatibleProvider:slug_lookup: dict[str, str] | None = None,spec_lookup: dict[str, FeatureSpec] | None = None,model_resolver: Callable[[str], tuple[str, FeatureSpec] | None] | None = None,+ include_usage_accounting: bool = False,) -> None:self._api_key = api_keyself._base_url = base_url.rstrip("/")@@ -99,6 +100,12 @@ class OpenAICompatibleProvider:# without enumerating them, so a catalog refresh after construction# needs no provider rebuild. Returning None defers to the lookups.self._model_resolver = model_resolver+ # OpenRouter-only request extension (see to_openai_request). Off by+ # default: a generic self-hosted/gateway backend may forward the+ # request nearly verbatim to a stricter upstream (e.g. real Anthropic+ # behind a LiteLLM gateway), which rejects an unrecognized top-level+ # `usage` field outright rather than ignoring it.+ self._include_usage_accounting = include_usage_accounting# ------------------------------------------------------------------# internal helpers@@ -145,7 +152,9 @@ class OpenAICompatibleProvider:model = kwargs.pop("model", "")slug, spec = self._resolve(model)gated = apply_feature_gates(spec, kwargs)- body = to_openai_request(slug, gated)+ body = to_openai_request(+ slug, gated, include_usage=self._include_usage_accounting+ )_announce_reasoning(slug, body)try:@@ -171,7 +180,9 @@ class OpenAICompatibleProvider:model = kwargs.pop("model", "")slug, spec = self._resolve(model)gated = apply_feature_gates(spec, kwargs)- body = to_openai_request(slug, gated)+ body = to_openai_request(+ slug, gated, include_usage=self._include_usage_accounting+ )_announce_reasoning(slug, body)body["stream"] = Truereturn _OpenAICompatibleStream(diff --git a/packages/core/openexecutive/providers/openrouter_provider.py b/packages/core/openexecutive/providers/openrouter_provider.pyindex 6e09ddc4..86e803a2 100644--- a/packages/core/openexecutive/providers/openrouter_provider.py+++ b/packages/core/openexecutive/providers/openrouter_provider.py@@ -51,4 +51,13 @@ class OpenRouterProvider(OpenAICompatibleProvider):slug_lookup=slug_lookup,spec_lookup=spec_lookup,model_resolver=model_resolver,+ # OpenRouter-format request extension (see+ # translator.to_openai_request). Also correct for OPENROUTER_BASE_URL+ # pointed at a third-party gateway, as long as it actually speaks+ # OpenRouter's request format — that's the documented contract for+ # this class, unlike the generic OpenAICompatibleProvider base+ # (used for LOCAL_MODELS), which defaults this off because it may+ # front a plain OpenAI-compatible server or a strict pass-through+ # to real Anthropic that rejects the field outright.+ include_usage_accounting=True,)diff --git a/packages/core/openexecutive/providers/registry.py b/packages/core/openexecutive/providers/registry.pyindex 10020722..f4b4a831 100644--- a/packages/core/openexecutive/providers/registry.py+++ b/packages/core/openexecutive/providers/registry.py@@ -298,6 +298,9 @@ def _local() -> OpenAICompatibleProvider:api_key=getattr(settings, "local_api_key", None),timeout_s=getattr(settings, "local_timeout_s", 300.0),spec_lookup=spec_lookup,+ include_usage_accounting=getattr(+ settings, "local_include_usage_accounting", False+ ),)return _local_providerdiff --git a/packages/core/openexecutive/providers/translator.py b/packages/core/openexecutive/providers/translator.pyindex 7eca1474..c65c251b 100644--- a/packages/core/openexecutive/providers/translator.py+++ b/packages/core/openexecutive/providers/translator.py@@ -375,7 +375,9 @@ def _translate_reasoning(anthropic_kwargs: dict[str, Any]) -> dict[str, Any] | Nreturn {"effort": effort}-def to_openai_request(model_slug: str, anthropic_kwargs: dict[str, Any]) -> dict[str, Any]:+def to_openai_request(+ model_slug: str, anthropic_kwargs: dict[str, Any], *, include_usage: bool = False+) -> dict[str, Any]:"""Translate an Anthropic ``messages.create`` kwargs dict to an OpenAI``/chat/completions`` body. ``model_slug`` is the OpenRouter model id."""body: dict[str, Any] = {@@ -427,7 +429,15 @@ def to_openai_request(model_slug: str, anthropic_kwargs: dict[str, Any]) -> dict# the cached system blocks, or the cache key, so prompt caching is# unaffected. The cost surfaces as `usage.cost` (USD) and is captured into# the per-call `cache_event` audit row downstream.- body["usage"] = {"include": True}+ #+ # OpenRouter-only: it's not part of the OpenAI or Anthropic request+ # schema. A generic self-hosted/gateway backend (Ollama, vLLM, or a+ # LiteLLM gateway fronting real Anthropic) may forward the request+ # nearly verbatim to a stricter upstream that rejects an unrecognized+ # top-level field outright instead of ignoring it — so only set it when+ # the caller has confirmed the backend is actually OpenRouter.+ if include_usage:+ body["usage"] = {"include": True}return bodydiff --git a/packages/core/tests/unit/test_openrouter_provider_lifecycle.py b/packages/core/tests/unit/test_openrouter_provider_lifecycle.pyindex d848c0ba..54c438c6 100644--- a/packages/core/tests/unit/test_openrouter_provider_lifecycle.py+++ b/packages/core/tests/unit/test_openrouter_provider_lifecycle.py@@ -160,6 +160,74 @@ def test_messages_create_sends_authorization_header_and_translates_body() -> Non"role": "system","content": "You are a helpful assistant.",}+ # OpenRouterProvider opts into the cost-accounting request field — this+ # is really OpenRouter, unlike a generic local/gateway backend.+ assert captured["json"]["usage"] == {"include": True}+++def test_local_provider_omits_usage_accounting_field() -> None:+ """Regression: a generic OpenAICompatibleProvider (e.g. a self-hosted+ server, or a LiteLLM gateway aliased under a Claude-family name) must+ NOT send the OpenRouter-only `usage` request field. A gateway that+ forwards nearly verbatim to real Anthropic rejects an unrecognized+ top-level field outright, breaking every call for that model."""+ from openexecutive.providers.openai_compatible import OpenAICompatibleProvider++ provider = OpenAICompatibleProvider(+ base_url="https://litellm.example.com/v1",+ slug_lookup={},+ spec_lookup={"claude-sonnet-4-6": FeatureSpec()},+ )+ captured: dict[str, Any] = {}++ async def _fake_post(url: str, **kwargs: Any) -> Any:+ captured["json"] = kwargs.get("json", {})+ fake = MagicMock()+ fake.json.return_value = {+ "id": "x",+ "choices": [{"message": {"role": "assistant", "content": "ok"}, "finish_reason": "stop"}],+ }+ fake.raise_for_status = MagicMock()+ return fake++ provider._client.post = AsyncMock(side_effect=_fake_post) # type: ignore[method-assign]+ asyncio.run(+ provider.messages_create(+ model="claude-sonnet-4-6",+ max_tokens=64,+ messages=[{"role": "user", "content": "hi"}],+ )+ )+ assert "usage" not in captured["json"]+++def test_local_provider_omits_usage_accounting_field_on_stream_path() -> None:+ """Same regression as test_local_provider_omits_usage_accounting_field,+ but for messages_stream — a separate call site into to_openai_request+ that the non-streaming test does not exercise. _OpenAICompatibleStream+ stores the assembled body on ``._body``, readable without ever entering+ the context manager or opening a connection."""+ from openexecutive.providers.openai_compatible import OpenAICompatibleProvider++ provider = OpenAICompatibleProvider(+ base_url="https://litellm.example.com/v1",+ slug_lookup={},+ spec_lookup={"claude-sonnet-4-6": FeatureSpec()},+ )+ stream = provider.messages_stream(+ model="claude-sonnet-4-6", max_tokens=64, messages=[{"role": "user", "content": "hi"}]+ )+ assert "usage" not in stream._body # type: ignore[attr-defined]+++def test_openrouter_provider_includes_usage_accounting_on_stream_path() -> None:+ """OpenRouterProvider must keep opting in on the streaming path too —+ the non-streaming test above only covers messages_create."""+ provider = _provider()+ stream = provider.messages_stream(+ model="claude-sonnet-4-6", max_tokens=64, messages=[{"role": "user", "content": "hi"}]+ )+ assert stream._body["usage"] == {"include": True} # type: ignore[attr-defined]def test_messages_create_strips_anthropic_only_fields_for_non_claude() -> None:diff --git a/packages/core/tests/unit/test_openrouter_translator.py b/packages/core/tests/unit/test_openrouter_translator.pyindex 537e69e9..773df631 100644--- a/packages/core/tests/unit/test_openrouter_translator.py+++ b/packages/core/tests/unit/test_openrouter_translator.py@@ -360,17 +360,30 @@ def test_request_lifts_assistant_tool_use_blocks_to_tool_calls() -> None:# ---------------------------------------------------------------------------def test_request_enables_usage_accounting() -> None:- """Every request asks OpenRouter to report the charged cost so the- per-call cache_event audit row can store it. This is a read-only flag and- must not disturb messages / cache_control blocks."""+def test_request_enables_usage_accounting_when_opted_in() -> None:+ """An OpenRouter call (include_usage=True) asks OpenRouter to report the+ charged cost so the per-call cache_event audit row can store it. This is+ a read-only flag and must not disturb messages / cache_control blocks."""body = to_openai_request("anthropic/claude-opus-4.8",{"max_tokens": 64, "messages": [{"role": "user", "content": "hi"}]},+ include_usage=True,)assert body["usage"] == {"include": True}+def test_request_omits_usage_accounting_by_default() -> None:+ """A generic self-hosted/gateway backend (the default) must NOT get the+ OpenRouter-only `usage` field — some upstreams (e.g. a LiteLLM gateway+ fronting real Anthropic) reject an unrecognized top-level field outright+ instead of ignoring it. Regression test for that exact failure."""+ body = to_openai_request(+ "claude-sonnet-4-6",+ {"max_tokens": 64, "messages": [{"role": "user", "content": "hi"}]},+ )+ assert "usage" not in body++def test_response_synthesizes_text_block() -> None:msg = from_openai_response({diff --git a/packages/core/tests/unit/test_provider_registry.py b/packages/core/tests/unit/test_provider_registry.pyindex 1cf09e2d..98758982 100644--- a/packages/core/tests/unit/test_provider_registry.py+++ b/packages/core/tests/unit/test_provider_registry.py@@ -166,6 +166,7 @@ def _settings_stub(local_models: list[str] | None = None,local_api_key: str | None = None,local_timeout_s: float = 300.0,+ local_include_usage_accounting: bool = False,) -> Any:return SimpleNamespace(anthropic_api_key=anthropic_key,@@ -180,6 +181,7 @@ def _settings_stub(local_models=local_models or [],local_api_key=local_api_key,local_timeout_s=local_timeout_s,+ local_include_usage_accounting=local_include_usage_accounting,)@@ -325,6 +327,25 @@ def test_local_model_routes_to_local_provider(monkeypatch: pytest.MonkeyPatch) -assert get_provider("qwen2.5") is provider+def test_local_provider_omits_usage_accounting_by_default(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ _local_stub(monkeypatch, enabled=False)+ provider = get_provider("llama3.3")+ assert provider._include_usage_accounting is False # type: ignore[attr-defined]+++def test_local_provider_respects_usage_accounting_opt_in(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """LOCAL_INCLUDE_USAGE_ACCOUNTING=true lets an operator who has confirmed+ their LOCAL_BASE_URL backend actually speaks OpenRouter's request format+ (e.g. a hosted, billed gateway) restore cost tracking."""+ _local_stub(monkeypatch, enabled=False, local_include_usage_accounting=True)+ provider = get_provider("llama3.3")+ assert provider._include_usage_accounting is True # type: ignore[attr-defined]++def test_local_provider_distinct_from_openrouter_singleton(monkeypatch: pytest.MonkeyPatch,) -> None: