Skip to content

AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).

48.6 KB
Raw Blame
"""Anthropic ↔ OpenAI-format request/response translation.

OpenRouter exposes an OpenAI-format ``/api/v1/chat/completions`` endpoint
(no Anthropic-Messages-compatible URL). To avoid rewriting every
Anthropic-shaped call site, we keep the internal request/response shape
Anthropic-native and translate only at the OpenRouter boundary.

The translator is intentionally functional — three pure helpers — so
the matrix of (system blocks, tool use, streaming tool fragments) is
testable in isolation without an HTTP client or an event loop.

What we DO NOT translate:

* ``cache_control`` blocks pass through unchanged when present. We
  preserve them on system content, user-turn content, tool entries, and
  tool-result content (the agent loop's intra-turn breakpoint)
  so OpenRouter can forward the Anthropic cache hints to the upstream
  Anthropic call (see OpenRouter prompt-caching docs:
  https://openrouter.ai/docs/guides/best-practices/prompt-caching).
  For non-Anthropic slugs the feature_gate has already stripped them
  before we get here, so the no-cache_control path falls back to the
  legacy string-flatten form for maximum upstream compatibility.
* Anthropic thinking / output_config blocks are NOT forwarded verbatim —
  OpenRouter has no ``thinking`` field. When feature_gate has preserved
  them (Claude family, or a catalog model that advertises ``reasoning``
  support) ``to_openai_request`` translates their intent into OpenRouter's
  unified ``reasoning`` parameter (``{"effort": ...}`` for adaptive
  thinking, ``{"max_tokens": N}`` for a legacy ``budget_tokens`` request).
  OpenRouter maps that onto each vendor's native form (Anthropic budget /
  effort, OpenAI reasoning effort, Gemini thinkingLevel, …). The
  ``reasoning`` / ``reasoning_details`` fields OpenRouter adds to the
  response are ignored by the response path — only ``content`` and
  ``tool_calls`` are read. See
  https://openrouter.ai/docs/guides/best-practices/reasoning-tokens.
* Web-search server tools — feature_gate strips these only for the local
  OpenAI-compatible backend. For every OpenRouter model the Anthropic
  ``web_search_*`` server tool (which OpenRouter can't execute as-is, and
  which has no ``input_schema``) is replaced in ``tools[]`` by OpenRouter's
  own ``openrouter:web_search`` server tool with the same ``max_uses`` and
  domain lists, so the search cap and filters hold on this path and the
  response's ``usage.web_search_requests`` is recorded. See
  https://openrouter.ai/docs/guides/features/server-tools/web-search.
  OpenRouter's search makes the model cite results with
  ``(cite index="...">…</cite>`` markup; the response path strips that
  markup so it doesn't leak into findings / chat text.
"""
from __future__ import annotations

import json
import logging
import re
from types import SimpleNamespace
from typing import Any


def _any_block_has_cache_control(blocks: Any) -> bool:
    """True iff at least one dict in ``blocks`` carries a real (dict-valued)
    ``cache_control`` marker. We require the value to be a dict because a
    caller setting ``cache_control: None`` should NOT flip us into the
    typed-block path — that would emit an array shape with zero cache
    markers, wasting wire bytes for no benefit."""
    if not isinstance(blocks, list):
        return False
    return any(
        isinstance(b, dict) and isinstance(b.get("cache_control"), dict)
        for b in blocks
    )


def _typed_text_with_cc(text: str, cc: Any) -> dict[str, Any] | None:
    """Build one typed text block, carrying ``cache_control`` when it is real.

    The single place that decides how a cache marker is projected onto the
    wire, shared by the system/user text path (`_typed_text_block`) and the
    tool-result path. Pass the full ``cache_control`` dict through —
    ``ttl: "1h"`` and any future extension fields ride along untouched.
    OpenRouter forwards this to Anthropic verbatim.

    Returns ``None`` for empty text: an empty typed block carries no content
    to cache and risks an upstream 400.
    """
    if not isinstance(text, str) or not text:
        return None
    out: dict[str, Any] = {"type": "text", "text": text}
    if isinstance(cc, dict):
        out["cache_control"] = cc
    return out


def _typed_text_block(block: dict[str, Any]) -> dict[str, Any] | None:
    """Project an Anthropic text block down to the typed-block shape OpenRouter
    forwards to Anthropic. Preserves ``cache_control`` (including the optional
    ``ttl`` extension); drops anything else to keep the wire payload minimal."""
    if block.get("type") != "text":
        return None
    return _typed_text_with_cc(block.get("text", ""), block.get("cache_control"))


def _pdf_filename(title: Any) -> str:
    """A document's ``title`` as a safe wire filename: last path segment,
    printable, at most 100 characters, ending in ``.pdf`` (OpenRouter's
    parser keys on the extension). ``document.pdf`` when there is none."""
    if not isinstance(title, str):
        return "document.pdf"
    name = "".join(c for c in title.replace("\\", "/").rsplit("/", 1)[-1] if c.isprintable())
    name = name.strip()[:96]
    if not name:
        return "document.pdf"
    return name if name.lower().endswith(".pdf") else f"{name}.pdf"


def _file_part(block: dict[str, Any]) -> dict[str, Any] | None:
    """An Anthropic base64 PDF ``document`` block as the OpenAI chat
    ``file`` content part, which OpenAI and OpenRouter both accept. Anything
    else (a URL or text source, another media type) is ``None``: there is no
    faithful OpenAI shape for it, and the caller drops it as before."""
    source = block.get("source")
    if not isinstance(source, dict) or source.get("type") != "base64":
        return None
    if source.get("media_type") != "application/pdf":
        return None
    data = source.get("data")
    if not isinstance(data, str) or not data:
        return None
    filename = _pdf_filename(block.get("title"))
    return {
        "type": "file",
        "file": {"filename": filename, "file_data": f"data:application/pdf;base64,{data}"},
    }


def _translate_system(system: Any) -> str | list[dict[str, Any]] | None:
    """Translate an Anthropic ``system`` argument to the OpenRouter shape.

    Two output forms, picked to maximize compatibility:

    * ``None`` when there's nothing to send (caller omits the system message).
    * A plain ``str`` when system is a string OR a list of blocks where NO
      block carries ``cache_control``. The string form is the broadest
      OpenAI-compatible shape; we use it whenever caching isn't in play.
    * A ``list[dict]`` of typed text blocks (with ``cache_control``
      preserved on the relevant blocks) when at least one block has
      ``cache_control``. This is the shape OpenRouter accepts and forwards
      to Anthropic so prompt caching actually engages. See
      https://openrouter.ai/docs/guides/best-practices/prompt-caching.
    """
    if system is None:
        return None
    if isinstance(system, str):
        return system or None
    if isinstance(system, list):
        if _any_block_has_cache_control(system):
            typed = [b for b in (_typed_text_block(blk) for blk in system if isinstance(blk, dict)) if b is not None]
            return typed or None
        chunks: list[str] = []
        for block in system:
            if isinstance(block, dict) and block.get("type") == "text":
                txt = block.get("text", "")
                if isinstance(txt, str) and txt:
                    chunks.append(txt)
        return "\n\n".join(chunks) or None
    return str(system) or None


def _request_caches_tool_results(messages: list[Any]) -> bool:
    """True iff any ``tool_result`` block in the request carries a marker.

    Drives a UNIFORM tool-message shape for the whole request, which the
    prompt cache depends on. The agent loop's marker moves each iteration,
    so a given tool result is marked on the iteration it is newest and
    unmarked on every later one. If the shape followed the marker, that
    result would serialize as a typed array once and as a flat string
    afterwards — the cached prefix bytes would change under the very
    breakpoint that was supposed to read them, and every iteration would
    miss. (The ``cache_control`` key itself is not an invalidator; a
    content-shape change is.) So the decision is made per request, not per
    block: if anything in this request is cached, every tool message uses
    the typed form.
    """
    for m in messages:
        if not isinstance(m, dict):
            continue
        content = m.get("content")
        if not isinstance(content, list):
            continue
        for block in content:
            if (
                isinstance(block, dict)
                and block.get("type") == "tool_result"
                and isinstance(block.get("cache_control"), dict)
            ):
                return True
    return False


def _request_caches_assistant_text(messages: list[Any]) -> bool:
    """True iff an assistant text block in the request carries a marker.

    That is the history breakpoint (``executive._apply_history_cache_marker``),
    normally on the previous reply. Like ``_request_caches_tool_results`` it
    sets one shape for every assistant turn in the request: the marker moves
    to the newest reply each message, so a reply typed while marked and
    flattened afterwards would change the cached prefix under the breakpoint
    meant to read it.
    """
    for m in messages:
        if not isinstance(m, dict) or m.get("role") != "assistant":
            continue
        content = m.get("content")
        if isinstance(content, list) and any(
            isinstance(b, dict) and b.get("type") == "text" and isinstance(b.get("cache_control"), dict)
            for b in content
        ):
            return True
    return False


def _request_caches_messages(messages: list[Any]) -> bool:
    """True iff any block of any message in the request carries a marker.

    Sets one shape for the text of every user turn sent as blocks, as the two
    checks above do for tool results and replies. The Executive caches the
    question being answered on the loop's first call
    (``executive._mark_turn_message``) and takes that marker off once the
    loop marker moves to the first tool result. If the shape followed the
    marker, the question would go out typed on the first call and flattened
    on the second, and the second call could not read what the first wrote.
    """
    for m in messages:
        if isinstance(m, dict) and _any_block_has_cache_control(m.get("content")):
            return True
    return False


def _anthropic_messages_to_openai(messages: list[Any]) -> list[dict[str, Any]]:
    """Convert Anthropic ``messages`` to OpenAI chat-completions ``messages``.

    Anthropic shape: ``[{"role": "user"|"assistant", "content": str | list[block]}]``.
    OpenAI shape: ``[{"role": "user"|"assistant", "content": str}]`` plus optional
    ``tool_calls`` on assistant turns, with separate ``tool`` role messages for
    tool results.
    """
    out: list[dict[str, Any]] = []
    typed_tool_results = _request_caches_tool_results(messages)
    typed_assistant_text = _request_caches_assistant_text(messages)
    typed_user_text = _request_caches_messages(messages)
    for m in messages:
        role = m.get("role")
        content = m.get("content")
        if role == "user":
            out.extend(_user_content_to_openai(content, typed_tool_results, typed_user_text))
        elif role == "assistant":
            out.append(_assistant_content_to_openai(content, typed_assistant_text))
        else:
            # Unknown role — preserve as best-effort.
            out.append({"role": role, "content": _content_to_text(content)})
    return out


def _content_to_text(content: Any) -> str:
    if isinstance(content, str):
        return content
    if isinstance(content, list):
        chunks: list[str] = []
        for block in content:
            if isinstance(block, dict) and block.get("type") == "text":
                txt = block.get("text", "")
                if isinstance(txt, str):
                    chunks.append(txt)
        return "\n\n".join(chunks)
    return ""


def _user_content_to_openai(
    content: Any, typed_tool_results: bool = False, typed_text: bool = False
) -> list[dict[str, Any]]:
    """User-turn content: emit one user message, plus one ``tool`` role message
    per Anthropic ``tool_result`` block so the OpenAI chat history threads
    correctly through tool-use turns.

    When any text block in ``content`` carries ``cache_control`` (used for
    Anthropic's rolling user-turn cache), the user message's ``content``
    stays as a typed-block array so the cache hint survives translation to
    OpenRouter. So does ``typed_text`` (a marker anywhere in the request, see
    ``_request_caches_messages``), so the text keeps one shape while the
    markers move. Otherwise we flatten to a plain string — broader upstream
    compatibility for non-Anthropic routing and slightly smaller wire bytes.
    A turn sent as a plain string stays one either way.

    A base64 PDF ``document`` block becomes an OpenAI ``file`` part (see
    ``_file_part``) and forces the typed-array form, text and files in their
    original order. Whether the model may receive one at all is decided
    earlier, by ``feature_gate`` (``supports_pdf_input``).
    """
    if isinstance(content, str):
        return [{"role": "user", "content": content}]
    if not isinstance(content, list):
        return [{"role": "user", "content": str(content)}]

    text_blocks: list[dict[str, Any]] = []  # populated when cache_control present
    text_chunks: list[str] = []  # populated for the flat-string fallback
    tool_messages: list[dict[str, Any]] = []
    preserve_typed = typed_text or _any_block_has_cache_control(content)
    # Text and PDF parts in their original order, used only when a PDF is
    # present: a file part cannot ride in the flat-string form.
    ordered_parts: list[dict[str, Any]] = []
    has_file = False

    for block in content:
        if not isinstance(block, dict):
            continue
        btype = block.get("type")
        if btype == "text":
            txt = block.get("text", "")
            if isinstance(txt, str) and txt:
                text_chunks.append(txt)
                typed = _typed_text_block(block)
                if preserve_typed and typed is not None:
                    text_blocks.append(typed)
                if typed is not None:
                    ordered_parts.append(typed if preserve_typed else {"type": "text", "text": txt})
        elif btype == "document":
            part = _file_part(block)
            if part is not None:
                ordered_parts.append(part)
                has_file = True
        elif btype == "tool_result":
            tool_use_id = block.get("tool_use_id")
            inner = block.get("content")
            tool_text = _content_to_text(inner)
            # A cache_control marker on a tool_result is the agent loop's
            # intra-turn breakpoint (executive._apply_loop_cache_marker). It
            # must survive translation or the loop re-pays full input price
            # for its own transcript on every iteration. Carrying it on the
            # tool message keeps it AFTER the tool results in wire order —
            # a marker text block in the user message would be emitted
            # before them (tool messages are appended last, below).
            typed = _typed_text_with_cc(tool_text, block.get("cache_control"))
            # Shape is decided per REQUEST, not per block — see
            # _request_caches_tool_results. Following the marker would flip
            # this result between array and string as the marker moves,
            # changing the cached prefix out from under the breakpoint.
            # Uncached requests keep the flat string they have always sent.
            tool_content: Any = tool_text
            if typed_tool_results and typed is not None:
                tool_content = [typed]
            tool_messages.append(
                {
                    "role": "tool",
                    "tool_call_id": tool_use_id,
                    "content": tool_content,
                }
            )

    msgs: list[dict[str, Any]] = []
    if has_file:
        # A PDF forces the typed-array form. Text keeps its cache marker when
        # the request carries one (the same projection as below).
        msgs.append({"role": "user", "content": ordered_parts})
    elif preserve_typed and text_blocks:
        msgs.append({"role": "user", "content": text_blocks})
    elif text_chunks:
        # Fall back to the flat-string form even when ``preserve_typed`` is
        # True but ``text_blocks`` is empty — that happens when the only
        # cache_control marker rides on a non-text block. A tool_result
        # marker is carried on its own tool message above, so this is not
        # a dropped marker; it just means this user message has no text
        # block of its own to mark. We don't want to drop the user's
        # actual text just because the marker lives elsewhere.
        msgs.append({"role": "user", "content": "\n\n".join(text_chunks)})
    msgs.extend(tool_messages)
    return msgs


def _assistant_content_to_openai(content: Any, typed_text: bool = False) -> dict[str, Any]:
    """Assistant-turn content: collapse text blocks; lift tool_use blocks to
    OpenAI ``tool_calls``.

    ``typed_text`` (the request carries the history breakpoint, see
    ``_request_caches_assistant_text``) keeps the text as typed parts, each
    with its own ``cache_control``, so the marker reaches Anthropic through
    OpenRouter instead of being collapsed away."""
    if isinstance(content, str):
        if typed_text and content:
            return {"role": "assistant", "content": [{"type": "text", "text": content}]}
        return {"role": "assistant", "content": content}
    if not isinstance(content, list):
        return {"role": "assistant", "content": str(content)}

    typed_parts: list[dict[str, Any]] = []
    text_chunks: list[str] = []
    tool_calls: list[dict[str, Any]] = []
    reasoning_details: list[Any] = []
    for block in content:
        if not isinstance(block, dict):
            continue
        btype = block.get("type")
        if btype == "text":
            txt = block.get("text", "")
            if isinstance(txt, str) and txt:
                text_chunks.append(txt)
                part = _typed_text_with_cc(txt, block.get("cache_control"))
                if part is not None:
                    typed_parts.append(part)
        elif btype == OPENROUTER_REASONING_BLOCK:
            details = block.get("reasoning_details")
            if isinstance(details, list):
                reasoning_details.extend(details)
        elif btype == "tool_use":
            tool_calls.append(
                {
                    "id": block.get("id", ""),
                    "type": "function",
                    "function": {
                        "name": block.get("name", ""),
                        "arguments": json.dumps(block.get("input", {})),
                    },
                }
            )

    out: dict[str, Any] = {"role": "assistant"}
    if typed_text and typed_parts:
        out["content"] = typed_parts
    else:
        out["content"] = "\n\n".join(text_chunks) if text_chunks else None
    if reasoning_details:
        out["reasoning_details"] = reasoning_details
    if tool_calls:
        out["tool_calls"] = tool_calls
    return out


def _anthropic_tools_to_openai(tools: list[Any]) -> list[dict[str, Any]]:
    """Anthropic ``tools[]`` (with ``input_schema``) → OpenAI ``tools[]``
    (with ``function.parameters``). Preserves ``cache_control`` on the
    matching translated tool entry so OpenRouter can forward Anthropic's
    tools-prefix cache hint to the upstream Anthropic call. For
    non-Anthropic routing, feature_gate already stripped the marker
    before we ran, so the no-cache_control path is the legacy shape."""
    out: list[dict[str, Any]] = []
    for t in tools:
        if not isinstance(t, dict):
            continue
        # Skip Anthropic server tools (no input_schema, uses 'type' instead).
        if "input_schema" not in t and t.get("type", "").startswith(
            ("web_search_", "computer_", "bash_", "code_execution_")
        ):
            continue
        params = t.get("input_schema") or {"type": "object", "properties": {}}
        entry: dict[str, Any] = {
            "type": "function",
            "function": {
                "name": t.get("name", ""),
                "description": t.get("description", ""),
                "parameters": params,
            },
        }
        cc = t.get("cache_control")
        if isinstance(cc, dict):
            entry["cache_control"] = cc
        out.append(entry)
    return out


# Anthropic native web-search server-tool type prefix (e.g.
# ``web_search_20250305``). OpenRouter cannot execute Anthropic's server tool,
# but its own server tool does the same job, so we translate the intent.
logger = logging.getLogger(__name__)

_WEB_SEARCH_TOOL_PREFIX = "web_search_"
# OpenRouter's own web-search server tool. Like Anthropic's, it runs inside
# the provider request: the model decides when to search (0..N times), the
# search count is capped server-side by ``max_uses``, domain lists apply, and
# the response reports ``usage.web_search_requests``. The engine is left on
# ``auto``: Claude, GPT, Gemini and Grok use their provider's native search,
# everything else Exa. See
# https://openrouter.ai/docs/guides/features/server-tools/web-search.
_OPENROUTER_WEB_SEARCH_TYPE = "openrouter:web_search"
# Tool-call ``type`` prefix of OpenRouter's server-side tools in a response.
# Those calls were executed upstream; they are never surfaced as tool_use
# blocks for the caller to run.
_OPENROUTER_SERVER_TOOL_PREFIX = "openrouter:"


def _is_server_tool_call(call: dict[str, Any]) -> bool:
    call_type = call.get("type")
    return isinstance(call_type, str) and call_type.startswith(_OPENROUTER_SERVER_TOOL_PREFIX)


def _web_search_server_tool(tools: Any) -> dict[str, Any] | None:
    """Return the OpenRouter ``openrouter:web_search`` server tool entry
    when ``tools`` carries an Anthropic native ``web_search_*`` server tool,
    else ``None``.

    OpenRouter's OpenAI-format endpoint can't run Anthropic's server-side
    ``web_search_20250305`` tool — ``_anthropic_tools_to_openai`` drops it
    (no ``input_schema``), which would silently strip web search from a call
    routed via OpenRouter. Its own server tool carries the same controls, so
    ``max_uses`` and the domain lists translate one-to-one
    (``blocked_domains`` → ``excluded_domains``).
    """
    if not isinstance(tools, list):
        return None
    for t in tools:
        if (
            isinstance(t, dict)
            and "input_schema" not in t
            and isinstance(t.get("type"), str)
            and t["type"].startswith(_WEB_SEARCH_TOOL_PREFIX)
        ):
            params: dict[str, Any] = {}
            max_uses = t.get("max_uses")
            # bool is an int subtype, so exclude it explicitly.
            if isinstance(max_uses, int) and not isinstance(max_uses, bool) and max_uses > 0:
                params["max_uses"] = max_uses
            allowed = t.get("allowed_domains")
            if isinstance(allowed, list) and allowed:
                params["allowed_domains"] = [str(d) for d in allowed]
            blocked = t.get("blocked_domains")
            if isinstance(blocked, list) and blocked:
                params["excluded_domains"] = [str(d) for d in blocked]
            tool: dict[str, Any] = {"type": _OPENROUTER_WEB_SEARCH_TYPE}
            if params:
                tool["parameters"] = params
            return tool
    return None


# OpenRouter's accepted ``reasoning.effort`` strings. Anthropic's
# ``output_config.effort`` values (low / medium / high / xhigh / max) are a
# subset, so they pass through unchanged. Anything else (or no effort at
# all) falls back to "low" — the cheapest real tier and this codebase's
# SPECIALIST_EFFORT default — so a typo can never silently escalate to the
# most expensive reasoning budget.
_OPENROUTER_EFFORT_LEVELS = frozenset(
    {"none", "minimal", "low", "medium", "high", "xhigh", "max"}
)
_DEFAULT_REASONING_EFFORT = "low"


def _translate_reasoning(
    anthropic_kwargs: dict[str, Any], *, claude: bool = False
) -> dict[str, Any] | None:
    """Anthropic ``thinking`` + ``output_config.effort`` → OpenRouter ``reasoning``.

    * ``{"type": "adaptive"}`` (current models) → ``{"effort": <level>}`` where
      the level comes from ``output_config.effort``, defaulting to "low".
    * ``{"type": "enabled", "budget_tokens": N}`` (pre-4.6 models) →
      ``{"max_tokens": N}``.
    * ``{"type": "disabled"}`` on a Claude slug → ``{"enabled": False}``, so
      a model that thinks by default (Haiku 5.5) is told not to, as on the
      Anthropic path. Anywhere else → ``None``, as before.
    * Absent or malformed → ``None`` (no field).
    """
    thinking = anthropic_kwargs.get("thinking")
    if not isinstance(thinking, dict):
        return None
    kind = thinking.get("type")
    if kind == "disabled":
        return {"enabled": False} if claude else None
    if kind == "enabled":
        budget = thinking.get("budget_tokens")
        if isinstance(budget, int) and not isinstance(budget, bool) and budget > 0:
            return {"max_tokens": budget}
        # ``enabled`` with no usable budget is malformed — Anthropic itself
        # would reject it — so send no reasoning rather than guessing.
        return None
    if kind != "adaptive":
        return None
    output_config = anthropic_kwargs.get("output_config")
    effort = output_config.get("effort") if isinstance(output_config, dict) else None
    if not isinstance(effort, str) or effort not in _OPENROUTER_EFFORT_LEVELS:
        effort = _DEFAULT_REASONING_EFFORT
    return {"effort": effort}


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] = {
        "model": model_slug,
        "messages": [],
    }

    system_content = _translate_system(anthropic_kwargs.get("system"))
    if system_content is not None:
        body["messages"].append({"role": "system", "content": system_content})

    messages = anthropic_kwargs.get("messages") or []
    body["messages"].extend(_anthropic_messages_to_openai(messages))

    max_tokens = anthropic_kwargs.get("max_tokens")
    if max_tokens is not None:
        body["max_tokens"] = max_tokens

    temperature = anthropic_kwargs.get("temperature")
    if temperature is not None:
        body["temperature"] = temperature

    tools = anthropic_kwargs.get("tools")
    if tools:
        translated = _anthropic_tools_to_openai(tools)
        # Anthropic's web_search server tool is dropped from ``tools`` above
        # (OpenRouter can't execute it); OpenRouter's own server tool takes
        # its place with the same cap and domain lists.
        web_search = _web_search_server_tool(tools)
        if web_search is not None:
            translated.append(web_search)
        if translated:
            body["tools"] = translated

    tool_choice = anthropic_kwargs.get("tool_choice")
    if tool_choice is not None:
        body["tool_choice"] = _translate_tool_choice(tool_choice)

    # Deep reasoning: the Council checkbox sets Anthropic-native ``thinking``
    # + ``output_config.effort``; feature_gate leaves them in place only for
    # models that can reason, and here they become OpenRouter's ``reasoning``.
    reasoning = _translate_reasoning(
        anthropic_kwargs, claude=model_slug.lower().startswith(("anthropic/claude-", "claude-"))
    )
    if reasoning is not None:
        body["reasoning"] = reasoning

    # Ask OpenRouter to report the actual charged cost of this generation in
    # the response `usage` block (and the final usage chunk when streaming).
    # This is a read-only accounting flag — it does not alter the messages,
    # 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.
    #
    # 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


def _translate_tool_choice(tc: Any) -> Any:
    """``{"type":"tool","name":"X"}`` → ``{"type":"function","function":{"name":"X"}}``.
    Pass-through for ``{"type":"any"}``, ``{"type":"auto"}`` and
    ``{"type":"none"}`` (a workflow action step's final, tools-off turn)."""
    if isinstance(tc, dict):
        if tc.get("type") == "tool" and "name" in tc:
            return {"type": "function", "function": {"name": tc["name"]}}
        if tc.get("type") in ("any", "auto", "none"):
            return tc.get("type")
    return tc


# --------------------------------------------------------------------------
# OpenAI response → Anthropic-shape Message
# --------------------------------------------------------------------------


def _block(type_: str, **fields: Any) -> SimpleNamespace:
    """Build a duck-typed Anthropic block (TextBlock / ToolUseBlock). The
    Executive's streaming loop only reads ``.type`` and the type-specific
    attributes; a SimpleNamespace matches the shape without pulling in
    pydantic models from the SDK."""
    return SimpleNamespace(type=type_, **fields)


# Synthetic content-block type carrying OpenRouter's ``reasoning_details``
# through the Anthropic-shaped message so a multi-turn tool loop can echo
# it back. Always the LAST content block, so ``content[0]`` stays whatever
# it was before (text, or tool_use for a text-less turn). OpenRouter requires the array to be replayed verbatim on the
# assistant turn for reasoning continuity (Anthropic 400s a tool_use turn
# whose thinking was dropped; other vendors lose their chain of thought).
# https://openrouter.ai/docs/guides/best-practices/reasoning-tokens#preserving-reasoning-blocks
OPENROUTER_REASONING_BLOCK = "openrouter_reasoning"


def reasoning_replay_block(block: Any) -> dict[str, Any] | None:
    """Dict form of a response ``openrouter_reasoning`` block for the next
    assistant turn, or ``None`` for any other block. Every multi-turn tool
    loop that rebuilds its assistant history block-by-block calls this so
    reasoning continuity is preserved on the OpenRouter path."""
    if getattr(block, "type", None) != OPENROUTER_REASONING_BLOCK:
        return None
    details = getattr(block, "reasoning_details", None)
    if not isinstance(details, list) or not details:
        return None
    return {"type": OPENROUTER_REASONING_BLOCK, "reasoning_details": list(details)}


def _reasoning_details_block(details: Any) -> SimpleNamespace | None:
    if isinstance(details, list) and details:
        return _block(OPENROUTER_REASONING_BLOCK, reasoning_details=list(details))
    return None


def _stop_reason_from_openai(reason: str | None) -> str:
    """Map OpenAI ``finish_reason`` to Anthropic ``stop_reason``."""
    if reason == "tool_calls" or reason == "function_call":
        return "tool_use"
    if reason == "length":
        return "max_tokens"
    if reason == "stop":
        return "end_turn"
    if reason == "content_filter":
        return "refusal"
    return reason or "end_turn"


# OpenRouter's web search makes the model cite sources with inline
# ``<cite index="3-14,3-15">…</cite>`` markup (it appears both in free text and
# inside tool-call argument strings). The wrapper tags are an upstream artifact
# that would otherwise leak into research findings, artifacts, and chat replies,
# so we strip the tags while keeping the cited text and any real URLs intact.
_CITE_TAG_RE = re.compile(r"</?cite\b[^>]*>")
# A trailing, unterminated ``<cite…`` / ``</cite…`` left by a mid-tag
# truncation (or a stream cut between the tag name and its closing ``>``).
# Requires the full ``cite`` word + boundary, so ordinary trailing text — a
# lone ``<`` or a ``<cited`` word — is preserved, not mistaken for a cut tag.
_CITE_OPEN_TAIL_RE = re.compile(r"</?cite\b[^>]*\Z")


def _remove_complete_cite_tags(text: str) -> str:
    """Strip every complete ``<cite …>`` / ``</cite>`` tag, iterating to a
    fixpoint so a tag *formed* by removing an inner one (``<ci`` + removed tag
    + ``te>`` → ``<cite>``) is also caught. Each pass that changes anything
    removes ≥1 tag, so the loop is bounded by the tag count."""
    while True:
        stripped = _CITE_TAG_RE.sub("", text)
        if stripped == text:
            return stripped
        text = stripped


def _parse_tool_arguments(raw_args: Any, tool_name: str) -> Any:
    """Parse a tool call's JSON arguments. OpenRouter search's ``<cite>`` markup
    can land inside argument strings with unescaped quotes; strip it from the
    raw text before parsing so a citation cannot turn a full payload into an
    empty one. A payload that still fails to parse is logged (it would
    otherwise read as "the model returned nothing")."""
    if not isinstance(raw_args, str):
        return raw_args
    try:
        return json.loads(_CITE_TAG_RE.sub("", raw_args))
    except json.JSONDecodeError as exc:
        logger.warning(
            "openrouter: tool call %r carried unparseable JSON arguments (%s) — "
            "treating as empty", tool_name, exc,
        )
        return {}


def _strip_cite_markup(text: str) -> str:
    """Remove ``<cite …>`` / ``</cite>`` wrapper tags, preserving inner text.

    Also drops a trailing *unterminated* ``<cite…`` / ``</cite…`` fragment: a
    message truncated (or a stream ended) mid-tag would otherwise leak raw
    markup. The ``"<" not in`` fast-path skips the common no-markup case while
    still catching an orphan ``</cite>`` (a narrower ``"<cite"`` guard missed
    those)."""
    if not isinstance(text, str) or "<" not in text:
        return text
    out = _remove_complete_cite_tags(text)
    out = _CITE_OPEN_TAIL_RE.sub("", out)
    return out


def _strip_cite_in_value(value: Any) -> Any:
    """Recursively strip ``<cite>`` markup from every string in a parsed tool
    input (dict / list / str). Used on tool-call arguments so OpenRouter's
    citation markup doesn't survive into structured tool output (e.g. a
    research finding's ``summary``)."""
    if isinstance(value, str):
        return _strip_cite_markup(value)
    if isinstance(value, list):
        return [_strip_cite_in_value(v) for v in value]
    if isinstance(value, dict):
        return {k: _strip_cite_in_value(v) for k, v in value.items()}
    return value


def _could_be_cite_prefix(tail: str) -> bool:
    """True if ``tail`` could be the start of a (not-yet-complete) ``<cite>`` /
    ``</cite>`` tag whose ``>`` hasn't streamed in yet. Used to decide what to
    withhold at a chunk boundary so a tag split across SSE deltas is never
    emitted half-stripped. A trailing ``<`` that clearly isn't a cite tag
    (e.g. ``5 < 10``) returns False so ordinary text isn't withheld."""
    return (
        "<cite".startswith(tail)
        or "</cite".startswith(tail)
        or tail.startswith("<cite")
        or tail.startswith("</cite")
    )


def _stream_strip_cite(buf: str) -> tuple[str, str]:
    """Stream-safe ``<cite>`` stripper. Returns ``(emit, pending)``: complete
    cite tags are removed from ``buf``; ``pending`` is a trailing fragment that
    might be the opening of a cite tag still arriving in a later chunk (carried
    forward to the next ``feed`` and flushed at ``finish_reason``). Guarantees
    that the concatenation of all ``emit`` slices equals
    ``_strip_cite_markup`` of the full streamed text."""
    cleaned = _remove_complete_cite_tags(buf)
    lt = cleaned.rfind("<")
    if lt != -1 and ">" not in cleaned[lt:] and _could_be_cite_prefix(cleaned[lt:]):
        return cleaned[:lt], cleaned[lt:]
    return cleaned, ""


def from_openai_response(body: dict[str, Any]) -> SimpleNamespace:
    """OpenAI ``/chat/completions`` non-streaming response →
    Anthropic-shape ``Message`` (duck-typed)."""
    choice = (body.get("choices") or [{}])[0]
    msg = choice.get("message") or {}
    content_blocks: list[SimpleNamespace] = []

    text = msg.get("content")
    if isinstance(text, str) and text:
        content_blocks.append(_block("text", text=_strip_cite_markup(text)))

    skipped_server_calls = 0
    for call in msg.get("tool_calls") or []:
        if _is_server_tool_call(call):
            # OpenRouter executed it already (web search); not for the
            # caller to run.
            skipped_server_calls += 1
            logger.debug("openrouter: skipping server-side tool call %r", call.get("type"))
            continue
        fn = call.get("function") or {}
        raw_args = fn.get("arguments") or "{}"
        parsed = _parse_tool_arguments(raw_args, fn.get("name", ""))
        content_blocks.append(
            _block(
                "tool_use",
                id=call.get("id", ""),
                name=fn.get("name", ""),
                input=_strip_cite_in_value(parsed),
            )
        )
    stop_reason = _stop_reason_from_openai(choice.get("finish_reason"))
    if skipped_server_calls and not any(b.type == "tool_use" for b in content_blocks):
        # Every tool call was server-side: nothing is left for the caller
        # to run, so the turn is complete, not waiting on tool results.
        stop_reason = "end_turn"

    # Reasoning LAST. Several callers read ``content[0].text`` (the SDK
    # itself only ever emits text first for those prompts), so the synthetic
    # block must never displace the text block. Order carries no meaning on
    # the replay side — ``reasoning_details`` is a separate message field.
    reasoning_block = _reasoning_details_block(msg.get("reasoning_details"))
    if reasoning_block is not None:
        content_blocks.append(reasoning_block)

    usage = body.get("usage") or {}
    cache_read, cache_create = _extract_cache_token_counts(usage)
    return SimpleNamespace(
        id=body.get("id", ""),
        type="message",
        role="assistant",
        model=body.get("model", ""),
        content=content_blocks,
        stop_reason=stop_reason,
        stop_sequence=None,
        usage=SimpleNamespace(
            input_tokens=usage.get("prompt_tokens", 0),
            output_tokens=usage.get("completion_tokens", 0),
            cache_creation_input_tokens=cache_create,
            cache_read_input_tokens=cache_read,
            # Actual USD charged for this generation, present when the request
            # set `usage: {include: true}`. None for upstreams that omit it.
            cost=usage.get("cost"),
            server_tool_use=_server_tool_usage(usage),
        ),
    )


def _server_tool_usage(usage: dict[str, Any]) -> SimpleNamespace:
    """Anthropic-shape ``usage.server_tool_use`` from OpenRouter's usage.

    On the wire the count sits under ``usage.server_tool_use_details``
    (``{"web_search_requests": N, "tool_calls_requested": N,
    "tool_calls_executed": N}``, observed on the chat-completions endpoint);
    a flat ``usage.web_search_requests`` (the shape the docs show) is
    accepted too. 0 when neither is present."""
    details = usage.get("server_tool_use_details")
    raw = (
        details.get("web_search_requests", 0)
        if isinstance(details, dict)
        else usage.get("web_search_requests", 0)
    )
    try:
        count = int(raw or 0)
    except (TypeError, ValueError, OverflowError):
        count = 0
    return SimpleNamespace(web_search_requests=count)


def _extract_cache_token_counts(usage: dict[str, Any]) -> tuple[int, int]:
    """Pull cache_read / cache_create token counts out of an OpenAI-format
    usage block, accommodating OpenRouter's nesting shape.

    OpenRouter's documented shape when caching engages
    (https://openrouter.ai/docs/guides/best-practices/prompt-caching):

        "usage": {
          "prompt_tokens": 10339,
          "prompt_tokens_details": {
            "cached_tokens": 10318,        # read from cache (cache HIT)
            "cache_write_tokens": 0        # written to cache (cache MISS that populated)
          }
        }

    We also accept a flat ``usage.cached_tokens`` fallback for upstreams
    that haven't adopted the nested form — the field used to be top-level
    in earlier OpenRouter responses and may still appear that way for
    some models.
    """
    details = usage.get("prompt_tokens_details") or {}
    cache_read = details.get("cached_tokens")
    if cache_read is None:
        cache_read = usage.get("cached_tokens", 0)
    cache_create = details.get("cache_write_tokens", 0)
    return int(cache_read or 0), int(cache_create or 0)


# --------------------------------------------------------------------------
# Streaming: OpenAI SSE chunks → Anthropic-shape stream events
# --------------------------------------------------------------------------


class StreamAccumulator:
    """Stateful translator that turns OpenAI SSE deltas into Anthropic events.

    OpenAI streams ``choices[0].delta`` fragments: a text delta, OR a tool_call
    fragment with ``function.arguments`` arriving in pieces, OR a finish_reason.
    Anthropic's stream is structured as ``content_block_start`` →
    ``content_block_delta`` (one per token chunk) → ``content_block_stop`` →
    ``message_delta`` (with ``stop_reason``) → ``message_stop``.

    The Executive's dispatch only inspects ``event.type == "content_block_delta"``
    + ``event.delta.type == "text_delta"`` for streaming text, and pulls the
    final message at ``await stream.get_final_message()``. We emit text deltas
    inline and stash tool-call fragments to assemble at stream close.
    """

    def __init__(self) -> None:
        # Index 0 = text block (always emitted if any text arrived).
        # Indices ≥1 = tool_use blocks keyed by OpenAI tool_call.index.
        self._text_started = False
        self._text_buf: list[str] = []
        # Withheld trailing fragment that might be the start of a <cite> tag
        # split across SSE chunks; flushed (stripped) at finish_reason.
        self._cite_pending = ""
        # tool_calls[idx] = {"id": ..., "name": ..., "arg_chunks": [..]}
        self._tool_calls: dict[int, dict[str, Any]] = {}
        # Indices of server-side tool calls (typed only on their first
        # delta); their continuation chunks carry only index + arguments
        # and must be dropped too.
        self._server_tool_indices: set[int] = set()
        # OpenRouter streams ``delta.reasoning_details`` chunks; collected
        # verbatim and re-emitted as one block at finalize().
        self._reasoning_details: list[Any] = []
        self._finish_reason: str | None = None
        self._usage: dict[str, Any] = {}
        self._model: str = ""
        self._id: str = ""

    def feed(self, chunk: dict[str, Any]) -> list[SimpleNamespace]:
        """Process one OpenAI SSE chunk. Returns 0+ Anthropic-shape events to
        forward to the consumer."""
        events: list[SimpleNamespace] = []

        if not self._id:
            self._id = chunk.get("id", "")
        if not self._model:
            self._model = chunk.get("model", "")

        usage = chunk.get("usage")
        if isinstance(usage, dict):
            self._usage.update(usage)

        choices = chunk.get("choices") or []
        if not choices:
            return events
        choice = choices[0]
        delta = choice.get("delta") or {}

        text = delta.get("content")
        if isinstance(text, str) and text:
            if not self._text_started:
                self._text_started = True
                events.append(
                    _block(
                        "content_block_start",
                        index=0,
                        content_block=_block("text", text=""),
                    )
                )
            self._text_buf.append(text)
            # Strip cite markup on the live delta stream too — consumers
            # (executive.py chat loop) build the visible reply from these
            # deltas, not from the finalized message. Withhold any trailing
            # fragment that could be a tag split across chunks.
            emit, self._cite_pending = _stream_strip_cite(self._cite_pending + text)
            if emit:
                events.append(
                    _block(
                        "content_block_delta",
                        index=0,
                        delta=_block("text_delta", text=emit),
                    )
                )

        details = delta.get("reasoning_details")
        if isinstance(details, list):
            self._reasoning_details.extend(details)

        for tc in delta.get("tool_calls") or []:
            idx = tc.get("index", 0)
            if _is_server_tool_call(tc):
                self._server_tool_indices.add(idx)
                logger.debug("openrouter: skipping server-side tool call %r", tc.get("type"))
                continue
            if idx in self._server_tool_indices:
                continue  # continuation chunk of a server-side call
            slot = self._tool_calls.setdefault(
                idx, {"id": "", "name": "", "arg_chunks": []}
            )
            if tc.get("id"):
                slot["id"] = tc["id"]
            fn = tc.get("function") or {}
            if fn.get("name"):
                slot["name"] = fn["name"]
            args = fn.get("arguments")
            if isinstance(args, str):
                slot["arg_chunks"].append(args)

        if choice.get("finish_reason"):
            self._finish_reason = choice["finish_reason"]
            # Flush any withheld cite fragment. ``_strip_cite_markup`` drops a
            # still-unterminated ``<cite…`` left by a mid-tag truncation, so a
            # partial tag is never emitted; a non-cite remainder is preserved.
            if self._cite_pending:
                leftover = _strip_cite_markup(self._cite_pending)
                self._cite_pending = ""
                if leftover and self._text_started:
                    events.append(
                        _block(
                            "content_block_delta",
                            index=0,
                            delta=_block("text_delta", text=leftover),
                        )
                    )

        return events

    def finalize(self) -> SimpleNamespace:
        """Build the final Anthropic-shape ``Message`` from accumulated state.

        Called by the OpenRouterProvider stream wrapper when SSE closes,
        before the consumer awaits ``stream.get_final_message()``.
        """
        content_blocks: list[SimpleNamespace] = []
        if self._text_started:
            content_blocks.append(
                _block("text", text=_strip_cite_markup("".join(self._text_buf)))
            )
        for idx in sorted(self._tool_calls):
            slot = self._tool_calls[idx]
            joined_args = "".join(slot["arg_chunks"])
            parsed = _parse_tool_arguments(joined_args or "{}", slot["name"])
            content_blocks.append(
                _block(
                    "tool_use",
                    id=slot["id"],
                    name=slot["name"],
                    input=_strip_cite_in_value(parsed),
                )
            )
        # Reasoning last — see from_openai_response for why.
        reasoning_block = _reasoning_details_block(self._reasoning_details)
        if reasoning_block is not None:
            content_blocks.append(reasoning_block)
        cache_read, cache_create = _extract_cache_token_counts(self._usage)
        return SimpleNamespace(
            id=self._id,
            type="message",
            role="assistant",
            model=self._model,
            content=content_blocks,
            stop_reason=(
                "end_turn"
                if self._server_tool_indices and not self._tool_calls
                else _stop_reason_from_openai(self._finish_reason)
            ),
            stop_sequence=None,
            usage=SimpleNamespace(
                input_tokens=self._usage.get("prompt_tokens", 0),
                output_tokens=self._usage.get("completion_tokens", 0),
                cache_creation_input_tokens=cache_create,
                cache_read_input_tokens=cache_read,
                # Actual USD charged, from the stream's final usage chunk when
                # the request set `usage: {include: true}`. None if absent.
                cost=self._usage.get("cost"),
                server_tool_use=_server_tool_usage(self._usage),
            ),
        )