Skip to content

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.example
index 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.py
index 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")
@classmethod
diff --git a/packages/core/openexecutive/providers/openai_compatible.py b/packages/core/openexecutive/providers/openai_compatible.py
index 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_key
self._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"] = True
return _OpenAICompatibleStream(
diff --git a/packages/core/openexecutive/providers/openrouter_provider.py b/packages/core/openexecutive/providers/openrouter_provider.py
index 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.py
index 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_provider
diff --git a/packages/core/openexecutive/providers/translator.py b/packages/core/openexecutive/providers/translator.py
index 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] | N
return {"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 body
diff --git a/packages/core/tests/unit/test_openrouter_provider_lifecycle.py b/packages/core/tests/unit/test_openrouter_provider_lifecycle.py
index 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.py
index 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.py
index 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: