refactor(anthropic): extract idempotent fast-mode kwargs helper

agent/anthropic_adapter.py

@@ -481,6 +481,85 @@ def _supports_fast_mode(model: str) -> bool:
     "oauth-2025-04-20",
 ]
 
+
+def _apply_fast_mode_to_kwargs(
+    kwargs: Dict[str, Any],
+    *,
+    enabled: bool,
+    model: str,
+    base_url: str | None,
+    is_oauth: bool,
+    drop_context_1m_beta: bool = False,
+) -> Dict[str, Any]:
+    """Apply (or revoke) Anthropic Fast Mode request metadata idempotently.
+
+    Fast mode adds ``extra_body["speed"] = "fast"`` plus the ``_FAST_MODE_BETA``
+    token on ``extra_headers["anthropic-beta"]`` for ~2.5x output throughput on
+    Opus 4.6 (native Anthropic endpoints only — third-party providers 400 on the
+    speed parameter and the unknown beta header).
+
+    The helper first STRIPS any fast-mode artifacts it may previously have
+    written — the ``speed`` key and the ``_FAST_MODE_BETA`` token — before
+    deciding. This makes it both **idempotent** (applying twice yields the same
+    kwargs) and **revocable** (applying with ``enabled=False`` cleanly reverts a
+    prior application). Non-fast-mode ``extra_body`` / ``extra_headers`` entries
+    and other beta tokens are preserved through the strip.
+
+    When *enabled* is True and the endpoint/model support fast mode, the
+    resulting kwargs are byte-identical to the historical inline block: fresh
+    base-url/oauth betas plus the fast-mode beta, written as a single
+    ``anthropic-beta`` ``extra_headers`` entry.
+
+    Returns a shallow copy; the caller's dict is not mutated.
+    """
+    kwargs = dict(kwargs)
+
+    # ── Revoke any prior fast-mode artifacts (idempotent + revocable) ──
+    extra_body = dict(kwargs.get("extra_body") or {})
+    extra_body.pop("speed", None)
+    if extra_body:
+        kwargs["extra_body"] = extra_body
+    else:
+        kwargs.pop("extra_body", None)
+
+    extra_headers = dict(kwargs.get("extra_headers") or {})
+    surviving_betas = [
+        beta.strip()
+        for beta in str(extra_headers.get("anthropic-beta") or "").split(",")
+        if beta.strip() and beta.strip() != _FAST_MODE_BETA
+    ]
+    if surviving_betas:
+        extra_headers["anthropic-beta"] = ",".join(surviving_betas)
+    else:
+        extra_headers.pop("anthropic-beta", None)
+    if extra_headers:
+        kwargs["extra_headers"] = extra_headers
+    else:
+        kwargs.pop("extra_headers", None)
+
+    if not (
+        enabled
+        and not _is_third_party_anthropic_endpoint(base_url)
+        and _supports_fast_mode(model)
+    ):
+        return kwargs
+
+    # ── Apply fast mode (byte-identical to the historical inline block) ──
+    kwargs.setdefault("extra_body", {})["speed"] = "fast"
+    # Build extra_headers with ALL applicable betas (the per-request
+    # extra_headers override the client-level anthropic-beta header).
+    betas = list(_common_betas_for_base_url(
+        base_url,
+        drop_context_1m_beta=drop_context_1m_beta,
+    ))
+    if is_oauth:
+        betas.extend(_OAUTH_ONLY_BETAS)
+    betas.append(_FAST_MODE_BETA)
+    kwargs["extra_headers"] = {"anthropic-beta": ",".join(betas)}
+
+    return kwargs
+
+
 # Claude Code identity — required for OAuth requests to be routed correctly.
 # Without these, Anthropic's infrastructure intermittently 500s OAuth traffic.
 # The version must stay reasonably current — Anthropic rejects OAuth requests
@@ -1154,24 +1233,14 @@ def _to_oauth_wire_name(name: str) -> str:
     # Opus 4.6 — Opus 4.7 and other models 400 on the speed parameter.
     # Only for native Anthropic endpoints — third-party providers would
     # reject the unknown beta header and speed parameter.
-    if (
-        fast_mode
-        and not _is_third_party_anthropic_endpoint(base_url)
-        and _supports_fast_mode(model)
-    ):
-        kwargs.setdefault("extra_body", {})["speed"] = "fast"
-        # Build extra_headers with ALL applicable betas (the per-request
-        # extra_headers override the client-level anthropic-beta header).
-        betas = list(_common_betas_for_base_url(
-            base_url,
-            drop_context_1m_beta=drop_context_1m_beta,
-        ))
-        if is_oauth:
-            betas.extend(_OAUTH_ONLY_BETAS)
-        betas.append(_FAST_MODE_BETA)
-        kwargs["extra_headers"] = {"anthropic-beta": ",".join(betas)}
-
-    return kwargs
+    return _apply_fast_mode_to_kwargs(
+        kwargs,
+        enabled=fast_mode,
+        model=model,
+        base_url=base_url,
+        is_oauth=is_oauth,
+        drop_context_1m_beta=drop_context_1m_beta,
+    )
 
 
 # Keys that belong exclusively to the OpenAI Responses / Codex API shape.

tests/agent/test_anthropic_adapter.py

@@ -1076,6 +1076,56 @@ def test_fast_mode_omitted_for_unsupported_model(self):
         beta_header = (kwargs.get("extra_headers") or {}).get("anthropic-beta", "")
         assert "fast-mode-2026-02-01" not in beta_header
 
+    def test_apply_fast_mode_helper_idempotent_revocable_and_byte_identical(self):
+        """``_apply_fast_mode_to_kwargs`` must be byte-identical to the
+        pre-refactor inline block when enabled, idempotent (apply twice is
+        stable), revocable (``enabled=False`` strips the ``speed`` key and the
+        fast-mode beta token, keeping co-bundled common betas), a no-op on fresh
+        kwargs when disabled, and non-mutating of its input.
+        """
+        from agent.anthropic_adapter import (
+            _apply_fast_mode_to_kwargs,
+            _common_betas_for_base_url,
+            _OAUTH_ONLY_BETAS,
+            _FAST_MODE_BETA,
+        )
+
+        model, base_url, is_oauth = "claude-opus-4-6", None, True
+        base = {"model": model, "messages": [{"role": "user", "content": "hi"}],
+                "max_tokens": 1024}
+        apply = lambda kw, on: _apply_fast_mode_to_kwargs(  # noqa: E731
+            kw, enabled=on, model=model, base_url=base_url, is_oauth=is_oauth)
+
+        # Reference: exactly what the historical inline block produced.
+        ref_betas = [*_common_betas_for_base_url(base_url), *_OAUTH_ONLY_BETAS,
+                     _FAST_MODE_BETA]
+        expected = {**base, "extra_body": {"speed": "fast"},
+                    "extra_headers": {"anthropic-beta": ",".join(ref_betas)}}
+
+        # (a) enabled path byte-identical; (b) applying twice is stable.
+        once = apply(base, True)
+        assert once == expected
+        assert apply(once, True) == once == expected
+
+        # (c) revoke strips speed + fast-mode beta, keeps common betas.
+        revoked = apply(once, False)
+        assert "extra_body" not in revoked  # emptied dict dropped, not left {}
+        revoked_beta = revoked["extra_headers"]["anthropic-beta"]
+        assert _FAST_MODE_BETA not in revoked_beta
+        assert all(b in revoked_beta for b in _common_betas_for_base_url(base_url))
+        assert apply(revoked, False) == revoked  # revoke is stable too
+
+        # (d) disabled on fresh kwargs is a no-op; (e) input never mutated.
+        assert apply(base, False) == base
+        assert "extra_body" not in base and "extra_headers" not in base
+
+        # (f) end-to-end: build_anthropic_kwargs delegates to the helper.
+        e2e = build_anthropic_kwargs(
+            model=model, messages=base["messages"], tools=None, max_tokens=1024,
+            reasoning_config=None, fast_mode=True, is_oauth=is_oauth)
+        assert e2e["extra_body"]["speed"] == "fast"
+        assert e2e["extra_headers"]["anthropic-beta"] == ",".join(ref_betas)
+