Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

fix(proxy/openai): translate max_tokens -> max_completion_tokens on chat path (#1774)

Tejas Chopra285808b90ea5
diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.py
index c66c4ae4a..962847423 100644
--- a/headroom/proxy/handlers/openai.py
+++ b/headroom/proxy/handlers/openai.py
@@ -84,6 +84,24 @@ _OPENAI_BASE_URL_HEADER = "x-headroom-base-url"
_OPENCODE_ZEN_HOSTS = {"opencode.ai", "www.opencode.ai"}
+def _normalize_openai_max_tokens(body: dict[str, Any]) -> None:
+ """Rename the legacy ``max_tokens`` to ``max_completion_tokens`` in-place.
+
+ GPT-5 / o-series chat models reject ``max_tokens`` and require
+ ``max_completion_tokens``; gpt-4o/4.1 accept the latter too. So translating
+ is a safe, one-way shim for current OpenAI models that lets openai-compatible
+ clients (opencode, older SDKs) which still send ``max_tokens`` work unchanged.
+ No-op when there is no ``max_tokens``; keeps an already-set
+ ``max_completion_tokens`` and just drops the rejected legacy key.
+ """
+ if not isinstance(body, dict) or "max_tokens" not in body:
+ return
+ legacy = body.get("max_tokens")
+ if legacy is not None and body.get("max_completion_tokens") is None:
+ body["max_completion_tokens"] = legacy
+ body.pop("max_tokens", None)
+
+
def _header_get(headers: dict[str, str], name: str) -> str | None:
"""Case-insensitive header lookup for plain dicts."""
lowered = name.lower()
@@ -2593,6 +2611,15 @@ class OpenAIHandlerMixin:
optimized_tokens = tokenizer.count_messages(body["messages"])
tokens_saved = original_tokens - optimized_tokens
+ # Compatibility shim: GPT-5 / o-series chat models REJECT the legacy
+ # `max_tokens` ("Unsupported parameter … Use 'max_completion_tokens'
+ # instead"); gpt-4o/4.1 accept `max_completion_tokens` too. openai-
+ # compatible clients (opencode, older SDKs) still send `max_tokens`, so
+ # translate it here — the proxy already owns the outbound body — and
+ # those requests work unchanged. No-op when the caller already set
+ # `max_completion_tokens`.
+ _normalize_openai_max_tokens(body)
+
# Route through LiteLLM/any-llm backend if configured
if self.anthropic_backend is not None:
try:
diff --git a/tests/test_openai_max_completion_tokens.py b/tests/test_openai_max_completion_tokens.py
new file mode 100644
index 000000000..91c795712
--- /dev/null
+++ b/tests/test_openai_max_completion_tokens.py
@@ -0,0 +1,51 @@
+"""OpenAI chat-path compatibility shim: max_tokens -> max_completion_tokens.
+
+GPT-5 / o-series chat models reject the legacy ``max_tokens`` and require
+``max_completion_tokens`` ("Unsupported parameter: 'max_tokens' is not supported
+with this model. Use 'max_completion_tokens' instead."). openai-compatible
+clients (opencode, older SDKs) still send ``max_tokens``, so the proxy — which
+already owns the outbound request body — translates it.
+"""
+
+from __future__ import annotations
+
+from headroom.proxy.handlers.openai import _normalize_openai_max_tokens
+
+
+def test_renames_legacy_max_tokens():
+ body = {"model": "gpt-5.3-chat-latest", "max_tokens": 256, "messages": []}
+ _normalize_openai_max_tokens(body)
+ assert "max_tokens" not in body
+ assert body["max_completion_tokens"] == 256
+
+
+def test_preserves_existing_max_completion_tokens_and_drops_legacy():
+ body = {"max_tokens": 256, "max_completion_tokens": 100}
+ _normalize_openai_max_tokens(body)
+ assert "max_tokens" not in body
+ assert body["max_completion_tokens"] == 100 # explicit value wins
+
+
+def test_noop_when_only_max_completion_tokens():
+ body = {"max_completion_tokens": 128}
+ _normalize_openai_max_tokens(body)
+ assert body == {"max_completion_tokens": 128}
+
+
+def test_noop_when_neither_present():
+ body = {"model": "gpt-4o", "messages": []}
+ _normalize_openai_max_tokens(body)
+ assert "max_completion_tokens" not in body
+ assert "max_tokens" not in body
+
+
+def test_null_max_tokens_is_dropped_without_setting_completion():
+ body = {"max_tokens": None}
+ _normalize_openai_max_tokens(body)
+ assert "max_tokens" not in body
+ assert body.get("max_completion_tokens") is None
+
+
+def test_non_dict_is_safe():
+ _normalize_openai_max_tokens(None) # type: ignore[arg-type]
+ _normalize_openai_max_tokens("nope") # type: ignore[arg-type]