Hermes-agent

agent/transports/__init__.py

@@ -0,0 +1,68 @@
+"""Transport layer types and registry for provider response normalization.
+
+Usage:
+    from agent.transports import get_transport
+    transport = get_transport("anthropic_messages")
+    result = transport.normalize_response(raw_response)
+"""
+
+from agent.transports.types import (
+    NormalizedResponse,
+    ToolCall,
+    Usage,
+    build_tool_call,
+    map_finish_reason,
+)  # noqa: F401
+
+_REGISTRY: dict = {}
+_discovered: bool = False
+
+
+def register_transport(api_mode: str, transport_cls: type) -> None:
+    """Register a transport class for an api_mode string."""
+    _REGISTRY[api_mode] = transport_cls
+
+
+def get_transport(api_mode: str):
+    """Get a transport instance for the given api_mode.
+
+    Returns None if no transport is registered for this api_mode.
+    This allows gradual migration — call sites can check for None
+    and fall back to the legacy code path.
+    """
+    global _discovered
+    if not _discovered:
+        _discover_transports()
+    cls = _REGISTRY.get(api_mode)
+    if cls is None:
+        # The registry can be partially populated when a specific transport
+        # module was imported directly (for example chat_completions before
+        # codex).  Discover on misses, not only when the registry is empty, so
+        # test/order-dependent imports do not make valid api_modes unavailable.
+        _discover_transports()
+        cls = _REGISTRY.get(api_mode)
+    if cls is None:
+        return None
+    return cls()
+
+
+def _discover_transports() -> None:
+    """Import all transport modules to trigger auto-registration."""
+    global _discovered
+    _discovered = True
+    try:
+        import agent.transports.anthropic  # noqa: F401
+    except ImportError:
+        pass
+    try:
+        import agent.transports.codex  # noqa: F401
+    except ImportError:
+        pass
+    try:
+        import agent.transports.chat_completions  # noqa: F401
+    except ImportError:
+        pass
+    try:
+        import agent.transports.bedrock  # noqa: F401
+    except ImportError:
+        pass

agent/transports/anthropic.py

@@ -0,0 +1,243 @@
+"""Anthropic Messages API transport.
+
+Delegates to the existing adapter functions in agent/anthropic_adapter.py.
+This transport owns format conversion and normalization — NOT client lifecycle.
+"""
+
+from typing import Any, Dict, List, Optional
+
+from agent.transports.base import ProviderTransport
+from agent.transports.types import NormalizedResponse
+
+
+class AnthropicTransport(ProviderTransport):
+    """Transport for api_mode='anthropic_messages'.
+
+    Wraps the existing functions in anthropic_adapter.py behind the
+    ProviderTransport ABC.  Each method delegates — no logic is duplicated.
+    """
+
+    @property
+    def api_mode(self) -> str:
+        return "anthropic_messages"
+
+    def convert_messages(self, messages: List[Dict[str, Any]], **kwargs) -> Any:
+        """Convert OpenAI messages to Anthropic (system, messages) tuple.
+
+        kwargs:
+            base_url: Optional[str] — affects thinking signature handling.
+        """
+        from agent.anthropic_adapter import convert_messages_to_anthropic
+
+        base_url = kwargs.get("base_url")
+        return convert_messages_to_anthropic(messages, base_url=base_url)
+
+    def convert_tools(self, tools: List[Dict[str, Any]]) -> Any:
+        """Convert OpenAI tool schemas to Anthropic input_schema format."""
+        from agent.anthropic_adapter import convert_tools_to_anthropic
+
+        return convert_tools_to_anthropic(tools)
+
+    def build_kwargs(
+        self,
+        model: str,
+        messages: List[Dict[str, Any]],
+        tools: Optional[List[Dict[str, Any]]] = None,
+        **params,
+    ) -> Dict[str, Any]:
+        """Build Anthropic messages.create() kwargs.
+
+        Calls convert_messages and convert_tools internally.
+
+        params (all optional):
+            max_tokens: int
+            reasoning_config: dict | None
+            tool_choice: str | None
+            is_oauth: bool
+            preserve_dots: bool
+            context_length: int | None
+            base_url: str | None
+            fast_mode: bool
+            drop_context_1m_beta: bool
+        """
+        from agent.anthropic_adapter import build_anthropic_kwargs
+
+        return build_anthropic_kwargs(
+            model=model,
+            messages=messages,
+            tools=tools,
+            max_tokens=params.get("max_tokens", 16384),
+            reasoning_config=params.get("reasoning_config"),
+            tool_choice=params.get("tool_choice"),
+            is_oauth=params.get("is_oauth", False),
+            preserve_dots=params.get("preserve_dots", False),
+            context_length=params.get("context_length"),
+            base_url=params.get("base_url"),
+            fast_mode=params.get("fast_mode", False),
+            drop_context_1m_beta=params.get("drop_context_1m_beta", False),
+        )
+
+    def normalize_response(self, response: Any, **kwargs) -> NormalizedResponse:
+        """Normalize Anthropic response to NormalizedResponse.
+
+        Parses content blocks (text, thinking, tool_use), maps stop_reason
+        to OpenAI finish_reason, and collects reasoning_details in provider_data.
+        """
+        import json
+        from agent.anthropic_adapter import _to_plain_data, _sanitize_replay_block
+        from agent.transports.types import ToolCall
+
+        strip_tool_prefix = kwargs.get("strip_tool_prefix", False)
+        _MCP_PREFIX = "mcp_"
+
+        text_parts = []
+        reasoning_parts = []
+        reasoning_details = []
+        tool_calls = []
+        # Verbatim, order-preserving copy of every content block in the turn.
+        # Anthropic signs each thinking block against the turn content that
+        # PRECEDES it at its position; when a turn interleaves thinking and
+        # tool_use (adaptive/interleaved thinking, Claude 4.6+), the parallel
+        # reasoning_details + tool_calls lists below lose that cross-type
+        # ordering. Replaying the latest assistant message in the wrong order
+        # invalidates the signatures -> HTTP 400 "thinking ... blocks in the
+        # latest assistant message cannot be modified". Preserve the exact
+        # block sequence here so the adapter can replay it unchanged. See
+        # tests/agent/test_anthropic_thinking_block_order.py.
+        ordered_blocks = []
+
+        for block in response.content:
+            block_dict = _to_plain_data(block)
+            clean_block = None
+            if isinstance(block_dict, dict):
+                # Sanitize at capture so output-only SDK fields (parsed_output,
+                # caller, citations=None, …) never persist to state.db and leak
+                # back as request input on replay → HTTP 400 "Extra inputs are
+                # not permitted". Defence-in-depth with the replay-side sanitize.
+                clean_block = _sanitize_replay_block(block_dict)
+                if clean_block is not None:
+                    ordered_blocks.append(clean_block)
+            if block.type == "text":
+                text_parts.append(block.text)
+            elif block.type in ("thinking", "redacted_thinking"):
+                if block.type == "thinking":
+                    reasoning_parts.append(block.thinking)
+                # Use the sanitized block (clean_block) for reasoning_details too,
+                # since _extract_preserved_thinking_blocks replays these on the
+                # non-ordered path. Falls back to raw only if sanitize dropped it.
+                if isinstance(clean_block, dict):
+                    reasoning_details.append(clean_block)
+                elif isinstance(block_dict, dict):
+                    reasoning_details.append(block_dict)
+            elif block.type == "tool_use":
+                name = block.name
+                if strip_tool_prefix and name.startswith(_MCP_PREFIX):
+                    stripped = name[len(_MCP_PREFIX):]
+                    # Only strip the mcp_ prefix for OAuth-injected tools
+                    # (where Hermes adds the prefix when sending to Anthropic
+                    # and must remove it on the way back).  Native MCP server
+                    # tools (from mcp_servers: in config.yaml) are registered
+                    # in the tool registry under their FULL mcp_<server>_<tool>
+                    # name and must NOT be stripped.  GH-25255.
+                    from tools.registry import registry as _tool_registry
+                    if (_tool_registry.get_entry(stripped)
+                            and not _tool_registry.get_entry(name)):
+                        name = stripped
+                tool_calls.append(
+                    ToolCall(
+                        id=block.id,
+                        name=name,
+                        arguments=json.dumps(block.input),
+                    )
+                )
+
+        finish_reason = self._STOP_REASON_MAP.get(response.stop_reason, "stop")
+
+        provider_data = {}
+        if reasoning_details:
+            provider_data["reasoning_details"] = reasoning_details
+        # Only worth carrying the ordered-blocks channel when the turn
+        # actually interleaves signed thinking with tool_use — that's the
+        # only shape the parallel lists reconstruct incorrectly. A turn that
+        # is purely text, or thinking-then-tools with a single leading
+        # thinking block, replays correctly without it.
+        _has_signed_thinking = any(
+            isinstance(b, dict)
+            and b.get("type") in ("thinking", "redacted_thinking")
+            and (b.get("signature") or b.get("data"))
+            for b in ordered_blocks
+        )
+        _has_tool_use = any(
+            isinstance(b, dict) and b.get("type") == "tool_use"
+            for b in ordered_blocks
+        )
+        if _has_signed_thinking and _has_tool_use:
+            provider_data["anthropic_content_blocks"] = ordered_blocks
+
+        return NormalizedResponse(
+            content="\n".join(text_parts) if text_parts else None,
+            tool_calls=tool_calls or None,
+            finish_reason=finish_reason,
+            reasoning="\n\n".join(reasoning_parts) if reasoning_parts else None,
+            usage=None,
+            provider_data=provider_data or None,
+        )
+
+    def validate_response(self, response: Any) -> bool:
+        """Check Anthropic response structure is valid.
+
+        An empty content list is legitimate for terminal stop reasons that
+        carry no text payload:
+
+        - ``end_turn`` — the model's canonical "nothing more to add" after a
+          tool turn that already delivered the user-facing text.
+        - ``refusal`` — the model declined to respond (Claude 4.5+). The
+          Messages API returns an empty ``content`` list with this stop
+          reason. Treating it as invalid sends a deterministic refusal into
+          the invalid-response retry loop, which reproduces the refusal on
+          every attempt and surfaces a misleading "rate limited / invalid
+          response" error instead of the refusal. ``normalize_response`` maps
+          ``refusal`` → ``content_filter`` so the agent loop's refusal handler
+          can surface it.
+
+        Treating either as invalid falsely retries a completed response.
+        """
+        if response is None:
+            return False
+        content_blocks = getattr(response, "content", None)
+        if not isinstance(content_blocks, list):
+            return False
+        if not content_blocks:
+            return getattr(response, "stop_reason", None) in {"end_turn", "refusal"}
+        return True
+
+    def extract_cache_stats(self, response: Any) -> Optional[Dict[str, int]]:
+        """Extract Anthropic cache_read and cache_creation token counts."""
+        usage = getattr(response, "usage", None)
+        if usage is None:
+            return None
+        cached = getattr(usage, "cache_read_input_tokens", 0) or 0
+        written = getattr(usage, "cache_creation_input_tokens", 0) or 0
+        if cached or written:
+            return {"cached_tokens": cached, "creation_tokens": written}
+        return None
+
+    # Promote the adapter's canonical mapping to module level so it's shared
+    _STOP_REASON_MAP = {
+        "end_turn": "stop",
+        "tool_use": "tool_calls",
+        "max_tokens": "length",
+        "stop_sequence": "stop",
+        "refusal": "content_filter",
+        "model_context_window_exceeded": "length",
+    }
+
+    def map_finish_reason(self, raw_reason: str) -> str:
+        """Map Anthropic stop_reason to OpenAI finish_reason."""
+        return self._STOP_REASON_MAP.get(raw_reason, "stop")
+
+
+# Auto-register on import
+from agent.transports import register_transport  # noqa: E402
+
+register_transport("anthropic_messages", AnthropicTransport)

agent/transports/base.py

@@ -0,0 +1,89 @@
+"""Abstract base for provider transports.
+
+A transport owns the data path for one api_mode:
+  convert_messages → convert_tools → build_kwargs → normalize_response
+
+It does NOT own: client construction, streaming, credential refresh,
+prompt caching, interrupt handling, or retry logic.  Those stay on AIAgent.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+
+from agent.transports.types import NormalizedResponse
+
+
+class ProviderTransport(ABC):
+    """Base class for provider-specific format conversion and normalization."""
+
+    @property
+    @abstractmethod
+    def api_mode(self) -> str:
+        """The api_mode string this transport handles (e.g. 'anthropic_messages')."""
+        ...
+
+    @abstractmethod
+    def convert_messages(self, messages: List[Dict[str, Any]], **kwargs) -> Any:
+        """Convert OpenAI-format messages to provider-native format.
+
+        Returns provider-specific structure (e.g. (system, messages) for Anthropic,
+        or the messages list unchanged for chat_completions).
+        """
+        ...
+
+    @abstractmethod
+    def convert_tools(self, tools: List[Dict[str, Any]]) -> Any:
+        """Convert OpenAI-format tool definitions to provider-native format.
+
+        Returns provider-specific tool list (e.g. Anthropic input_schema format).
+        """
+        ...
+
+    @abstractmethod
+    def build_kwargs(
+        self,
+        model: str,
+        messages: List[Dict[str, Any]],
+        tools: Optional[List[Dict[str, Any]]] = None,
+        **params,
+    ) -> Dict[str, Any]:
+        """Build the complete API call kwargs dict.
+
+        This is the primary entry point — it typically calls convert_messages()
+        and convert_tools() internally, then adds model-specific config.
+
+        Returns a dict ready to be passed to the provider's SDK client.
+        """
+        ...
+
+    @abstractmethod
+    def normalize_response(self, response: Any, **kwargs) -> NormalizedResponse:
+        """Normalize a raw provider response to the shared NormalizedResponse type.
+
+        This is the only method that returns a transport-layer type.
+        """
+        ...
+
+    def validate_response(self, response: Any) -> bool:
+        """Optional: check if the raw response is structurally valid.
+
+        Returns True if valid, False if the response should be treated as invalid.
+        Default implementation always returns True.
+        """
+        return True
+
+    def extract_cache_stats(self, response: Any) -> Optional[Dict[str, int]]:
+        """Optional: extract provider-specific cache hit/creation stats.
+
+        Returns dict with 'cached_tokens' and 'creation_tokens', or None.
+        Default returns None.
+        """
+        return None
+
+    def map_finish_reason(self, raw_reason: str) -> str:
+        """Optional: map provider-specific stop reason to OpenAI equivalent.
+
+        Default returns the raw reason unchanged.  Override for providers
+        with different stop reason vocabularies.
+        """
+        return raw_reason

agent/transports/bedrock.py

@@ -0,0 +1,154 @@
+"""AWS Bedrock Converse API transport.
+
+Delegates to the existing adapter functions in agent/bedrock_adapter.py.
+Bedrock uses its own boto3 client (not the OpenAI SDK), so the transport
+owns format conversion and normalization, while client construction and
+boto3 calls stay on AIAgent.
+"""
+
+from typing import Any, Dict, List, Optional
+
+from agent.transports.base import ProviderTransport
+from agent.transports.types import NormalizedResponse, ToolCall, Usage
+
+
+class BedrockTransport(ProviderTransport):
+    """Transport for api_mode='bedrock_converse'."""
+
+    @property
+    def api_mode(self) -> str:
+        return "bedrock_converse"
+
+    def convert_messages(self, messages: List[Dict[str, Any]], **kwargs) -> Any:
+        """Convert OpenAI messages to Bedrock Converse format."""
+        from agent.bedrock_adapter import convert_messages_to_converse
+        return convert_messages_to_converse(messages)
+
+    def convert_tools(self, tools: List[Dict[str, Any]]) -> Any:
+        """Convert OpenAI tool schemas to Bedrock Converse toolConfig."""
+        from agent.bedrock_adapter import convert_tools_to_converse
+        return convert_tools_to_converse(tools)
+
+    def build_kwargs(
+        self,
+        model: str,
+        messages: List[Dict[str, Any]],
+        tools: Optional[List[Dict[str, Any]]] = None,
+        **params,
+    ) -> Dict[str, Any]:
+        """Build Bedrock converse() kwargs.
+
+        Calls convert_messages and convert_tools internally.
+
+        params:
+            max_tokens: int — output token limit (default 4096)
+            temperature: float | None
+            guardrail_config: dict | None — Bedrock guardrails
+            region: str — AWS region (default 'us-east-1')
+        """
+        from agent.bedrock_adapter import build_converse_kwargs
+
+        region = params.get("region", "us-east-1")
+        guardrail = params.get("guardrail_config")
+
+        kwargs = build_converse_kwargs(
+            model=model,
+            messages=messages,
+            tools=tools,
+            max_tokens=params.get("max_tokens", 4096),
+            temperature=params.get("temperature"),
+            guardrail_config=guardrail,
+        )
+        # Sentinel keys for dispatch — agent pops these before the boto3 call
+        kwargs["__bedrock_converse__"] = True
+        kwargs["__bedrock_region__"] = region
+        return kwargs
+
+    def normalize_response(self, response: Any, **kwargs) -> NormalizedResponse:
+        """Normalize Bedrock response to NormalizedResponse.
+
+        Handles two shapes:
+        1. Raw boto3 dict (from direct converse() calls)
+        2. Already-normalized SimpleNamespace with .choices (from dispatch site)
+        """
+        from agent.bedrock_adapter import normalize_converse_response
+
+        # Normalize to OpenAI-compatible SimpleNamespace
+        if hasattr(response, "choices") and response.choices:
+            # Already normalized at dispatch site
+            ns = response
+        else:
+            # Raw boto3 dict
+            ns = normalize_converse_response(response)
+
+        choice = ns.choices[0]
+        msg = choice.message
+        finish_reason = choice.finish_reason or "stop"
+
+        tool_calls = None
+        if msg.tool_calls:
+            tool_calls = [
+                ToolCall(
+                    id=tc.id,
+                    name=tc.function.name,
+                    arguments=tc.function.arguments,
+                )
+                for tc in msg.tool_calls
+            ]
+
+        usage = None
+        if hasattr(ns, "usage") and ns.usage:
+            u = ns.usage
+            usage = Usage(
+                prompt_tokens=getattr(u, "prompt_tokens", 0) or 0,
+                completion_tokens=getattr(u, "completion_tokens", 0) or 0,
+                total_tokens=getattr(u, "total_tokens", 0) or 0,
+            )
+
+        reasoning = getattr(msg, "reasoning", None) or getattr(msg, "reasoning_content", None)
+
+        return NormalizedResponse(
+            content=msg.content,
+            tool_calls=tool_calls,
+            finish_reason=finish_reason,
+            reasoning=reasoning,
+            usage=usage,
+        )
+
+    def validate_response(self, response: Any) -> bool:
+        """Check Bedrock response structure.
+
+        After normalize_converse_response, the response has OpenAI-compatible
+        .choices — same check as chat_completions.
+        """
+        if response is None:
+            return False
+        # Raw Bedrock dict response — check for 'output' key
+        if isinstance(response, dict):
+            return "output" in response
+        # Already-normalized SimpleNamespace
+        if hasattr(response, "choices"):
+            return bool(response.choices)
+        return False
+
+    def map_finish_reason(self, raw_reason: str) -> str:
+        """Map Bedrock stop reason to OpenAI finish_reason.
+
+        The adapter already does this mapping inside normalize_converse_response,
+        so this is only used for direct access to raw responses.
+        """
+        _MAP = {
+            "end_turn": "stop",
+            "tool_use": "tool_calls",
+            "max_tokens": "length",
+            "stop_sequence": "stop",
+            "guardrail_intervened": "content_filter",
+            "content_filtered": "content_filter",
+        }
+        return _MAP.get(raw_reason, "stop")
+
+
+# Auto-register on import
+from agent.transports import register_transport  # noqa: E402
+
+register_transport("bedrock_converse", BedrockTransport)

agent/transports/chat_completions.py

@@ -0,0 +1,738 @@
+"""OpenAI Chat Completions transport.
+
+Handles the default api_mode ('chat_completions') used by ~16 OpenAI-compatible
+providers (OpenRouter, Nous, NVIDIA, Qwen, Ollama, DeepSeek, xAI, Kimi, etc.).
+
+Messages and tools are already in OpenAI format — convert_messages and
+convert_tools are near-identity.  The complexity lives in build_kwargs
+which has provider-specific conditionals for max_tokens defaults,
+reasoning configuration, temperature handling, and extra_body assembly.
+"""
+
+import copy
+from typing import Any, Dict
+
+from agent.lmstudio_reasoning import resolve_lmstudio_effort
+from agent.moonshot_schema import is_moonshot_model, sanitize_moonshot_tools
+from agent.prompt_builder import DEVELOPER_ROLE_MODELS
+from agent.transports.base import ProviderTransport
+from agent.transports.types import NormalizedResponse, ToolCall, Usage
+
+
+def _build_gemini_thinking_config(model: str, reasoning_config: dict | None) -> dict | None:
+    """Translate Hermes/OpenRouter-style reasoning config to Gemini thinkingConfig."""
+    if reasoning_config is None or not isinstance(reasoning_config, dict):
+        return None
+
+    normalized_model = (model or "").strip().lower()
+    if normalized_model.startswith("google/"):
+        normalized_model = normalized_model.split("/", 1)[1]
+
+    # ``thinking_config`` is a Gemini-only request parameter. The same
+    # ``gemini`` provider also serves Gemma (and historically PaLM/Bard);
+    # those reject the field with HTTP 400 "Unknown name 'thinking_config':
+    # Cannot find field" — including the polite ``{"includeThoughts": False}``
+    # form. Omit the field entirely on non-Gemini models. (#17426)
+    if not normalized_model.startswith("gemini"):
+        return None
+
+    if reasoning_config.get("enabled") is False:
+        # Gemini can hide thought parts even when internal thinking still
+        # happens; omit thinkingLevel to avoid model-specific validation quirks.
+        return {"includeThoughts": False}
+
+    effort = str(reasoning_config.get("effort", "medium") or "medium").strip().lower()
+    if effort == "none":
+        return {"includeThoughts": False}
+
+    thinking_config: Dict[str, Any] = {"includeThoughts": True}
+
+    # Gemini 2.5 accepts thinkingBudget; don't guess a budget from Hermes'
+    # coarse effort levels. ``includeThoughts`` alone is enough to surface
+    # thought parts without risking request validation errors.
+    if normalized_model.startswith("gemini-2.5-"):
+        return thinking_config
+
+    if effort not in {"minimal", "low", "medium", "high", "xhigh"}:
+        effort = "medium"
+
+    # Gemini 3 Flash documents low/medium/high thinking levels; Gemini 3 Pro
+    # is stricter (low/high). Clamp Hermes' wider effort set to what each
+    # family accepts so we never forward an undocumented level verbatim.
+    if normalized_model.startswith(("gemini-3", "gemini-3.1")):
+        if "flash" in normalized_model:
+            if effort in {"minimal", "low"}:
+                thinking_config["thinkingLevel"] = "low"
+            elif effort in {"high", "xhigh"}:
+                thinking_config["thinkingLevel"] = "high"
+            else:
+                thinking_config["thinkingLevel"] = "medium"
+        elif "pro" in normalized_model:
+            thinking_config["thinkingLevel"] = (
+                "high" if effort in {"high", "xhigh"} else "low"
+            )
+
+    return thinking_config
+
+
+def _snake_case_gemini_thinking_config(config: dict | None) -> dict | None:
+    """Convert Gemini thinking config keys to the OpenAI-compat field names."""
+    if not isinstance(config, dict) or not config:
+        return None
+
+    translated: Dict[str, Any] = {}
+    if isinstance(config.get("includeThoughts"), bool):
+        translated["include_thoughts"] = config["includeThoughts"]
+    if isinstance(config.get("thinkingLevel"), str) and config["thinkingLevel"].strip():
+        translated["thinking_level"] = config["thinkingLevel"].strip().lower()
+    if isinstance(config.get("thinkingBudget"), (int, float)):
+        translated["thinking_budget"] = int(config["thinkingBudget"])
+    return translated or None
+
+
+def _is_gemini_openai_compat_base_url(base_url: Any) -> bool:
+    normalized = str(base_url or "").strip().rstrip("/").lower()
+    if not normalized:
+        return False
+    if "generativelanguage.googleapis.com" not in normalized:
+        return False
+    return normalized.endswith("/openai")
+
+
+def _model_consumes_thought_signature(model: Any) -> bool:
+    """True when the outgoing model is a Gemini family model that requires
+    ``extra_content`` (thought_signature) to be replayed on tool calls.
+
+    Gemini 3 thinking models attach ``extra_content`` to each tool call and
+    reject subsequent requests with HTTP 400 if it is missing. Every other
+    strict OpenAI-compatible provider (Fireworks, Mistral, ...) rejects the
+    request with 400 if ``extra_content`` *is* present. So the field must be
+    kept only when the target model is itself Gemini-family, and stripped
+    otherwise — including when a non-Gemini model inherits stale Gemini
+    ``extra_content`` from earlier in a mixed-provider session.
+    """
+    m = str(model or "").lower()
+    return "gemini" in m or "gemma" in m
+
+
+class ChatCompletionsTransport(ProviderTransport):
+    """Transport for api_mode='chat_completions'.
+
+    The default path for OpenAI-compatible providers.
+    """
+
+    @property
+    def api_mode(self) -> str:
+        return "chat_completions"
+
+    def convert_messages(
+        self, messages: list[dict[str, Any]], **kwargs
+    ) -> list[dict[str, Any]]:
+        """Messages are already in OpenAI format — strip internal fields
+        that strict chat-completions providers reject with HTTP 400/422
+        (or, in the case of some OpenAI-compatible gateways, 5xx):
+
+        - Codex Responses API fields: ``codex_reasoning_items`` /
+          ``codex_message_items`` on the message, ``call_id`` /
+          ``response_item_id`` on ``tool_calls`` entries.
+        - ``extra_content`` on ``tool_calls`` (Gemini thought_signature) —
+          stripped unless the outgoing ``model`` is itself Gemini-family.
+          Gemini 3 thinking models attach it for replay, but strict providers
+          (Fireworks, Mistral) reject any payload containing it with
+          ``Extra inputs are not permitted, field: 'messages[N].tool_calls[M].extra_content'``.
+          It must be kept for Gemini targets (replay required) and dropped for
+          everyone else, including non-Gemini models that inherited stale
+          Gemini ``extra_content`` earlier in a mixed-provider session.
+        - ``tool_name`` on tool-result messages — written by
+          ``make_tool_result_message()`` for the SQLite FTS index, but not
+          part of the Chat Completions schema. Strict providers (Fireworks,
+          Moonshot/Kimi) reject any payload containing it with
+          ``Extra inputs are not permitted, field: 'messages[N].tool_name'``.
+          Permissive providers (OpenRouter, MiniMax) silently ignore the
+          field, which masked the bug for months.
+        - Hermes-internal scaffolding markers — any top-level message key
+          starting with ``_`` (e.g. ``_empty_recovery_synthetic``,
+          ``_empty_terminal_sentinel``, ``_thinking_prefill``). These are
+          bookkeeping flags the agent loop attaches to messages so the
+          persistence layer can later strip its own scaffolding; they must
+          never reach the wire. Permissive providers (real OpenAI,
+          Anthropic) silently drop unknown message keys, but strict
+          gateways (e.g. opencode-go, codex.nekos.me) reject with
+          ``Extra inputs are not permitted, field: 'messages[N]._empty_recovery_synthetic'``,
+          which then poisons every subsequent request in the session.
+        """
+        strip_extra_content = not _model_consumes_thought_signature(
+            kwargs.get("model")
+        )
+        needs_sanitize = False
+        for msg in messages:
+            if not isinstance(msg, dict):
+                continue
+            if (
+                "codex_reasoning_items" in msg
+                or "codex_message_items" in msg
+                or "tool_name" in msg
+            ):
+                needs_sanitize = True
+                break
+            if any(isinstance(k, str) and k.startswith("_") for k in msg):
+                needs_sanitize = True
+                break
+            tool_calls = msg.get("tool_calls")
+            if isinstance(tool_calls, list):
+                for tc in tool_calls:
+                    if isinstance(tc, dict) and (
+                        "call_id" in tc
+                        or "response_item_id" in tc
+                        or (strip_extra_content and "extra_content" in tc)
+                    ):
+                        needs_sanitize = True
+                        break
+                if needs_sanitize:
+                    break
+
+        if not needs_sanitize:
+            return messages
+
+        sanitized = copy.deepcopy(messages)
+        for msg in sanitized:
+            if not isinstance(msg, dict):
+                continue
+            msg.pop("codex_reasoning_items", None)
+            msg.pop("codex_message_items", None)
+            msg.pop("tool_name", None)
+            # Drop all Hermes-internal scaffolding markers (``_``-prefixed).
+            # OpenAI's message schema has no ``_``-prefixed fields, so this
+            # is safe and future-proofs against new markers being added.
+            for key in [k for k in msg if isinstance(k, str) and k.startswith("_")]:
+                msg.pop(key, None)
+            tool_calls = msg.get("tool_calls")
+            if isinstance(tool_calls, list):
+                for tc in tool_calls:
+                    if isinstance(tc, dict):
+                        tc.pop("call_id", None)
+                        tc.pop("response_item_id", None)
+                        if strip_extra_content:
+                            tc.pop("extra_content", None)
+        return sanitized
+
+    def convert_tools(self, tools: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        """Tools are already in OpenAI format — identity."""
+        return tools
+
+    def build_kwargs(
+        self,
+        model: str,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]] | None = None,
+        **params,
+    ) -> dict[str, Any]:
+        """Build chat.completions.create() kwargs.
+
+        params (all optional):
+            timeout: float — API call timeout
+            max_tokens: int | None — user-configured max tokens
+            ephemeral_max_output_tokens: int | None — one-shot override
+            max_tokens_param_fn: callable — returns {max_tokens: N} or {max_completion_tokens: N}
+            reasoning_config: dict | None
+            request_overrides: dict | None
+            session_id: str | None
+            model_lower: str — lowercase model name for pattern matching
+            # Provider profile path (all per-provider quirks live in providers/)
+            provider_profile: ProviderProfile | None — when present, delegates to
+                _build_kwargs_from_profile(); all flag params below are bypassed.
+            # Legacy-path flags — only used when provider_profile is None
+            # (i.e. custom / unregistered providers). Known providers all go
+            # through provider_profile.
+            is_openrouter: bool
+            is_nous: bool
+            is_qwen_portal: bool
+            is_github_models: bool
+            is_nvidia_nim: bool
+            is_kimi: bool
+            is_tokenhub: bool
+            is_lmstudio: bool
+            is_custom_provider: bool
+            ollama_num_ctx: int | None
+            # Provider routing
+            provider_preferences: dict | None
+            # Qwen-specific
+            qwen_prepare_fn: callable | None — runs AFTER codex sanitization
+            qwen_prepare_inplace_fn: callable | None — in-place variant for deepcopied lists
+            qwen_session_metadata: dict | None
+            # Temperature
+            fixed_temperature: Any — from _fixed_temperature_for_model()
+            omit_temperature: bool
+            # Reasoning
+            supports_reasoning: bool
+            github_reasoning_extra: dict | None
+            lmstudio_reasoning_options: list[str] | None  # raw allowed_options from /api/v1/models
+            # Claude on OpenRouter/Nous max output
+            anthropic_max_output: int | None
+            extra_body_additions: dict | None
+        """
+        # Codex sanitization: drop reasoning_items / call_id / response_item_id.
+        # Pass model so the Gemini thought_signature (extra_content) is kept for
+        # Gemini targets and stripped for strict non-Gemini providers.
+        sanitized = self.convert_messages(messages, model=model)
+
+        # ── Provider profile: single-path when present ──────────────────
+        _profile = params.get("provider_profile")
+        if _profile:
+            return self._build_kwargs_from_profile(
+                _profile, model, sanitized, tools, params
+            )
+
+        # ── Legacy fallback (unregistered / unknown provider) ───────────
+        # Reached only when get_provider_profile() returned None.
+        # Known providers always go through the profile path above.
+
+        # Developer role swap for GPT-5/Codex models
+        model_lower = params.get("model_lower", (model or "").lower())
+        if (
+            sanitized
+            and isinstance(sanitized[0], dict)
+            and sanitized[0].get("role") == "system"
+            and any(p in model_lower for p in DEVELOPER_ROLE_MODELS)
+        ):
+            sanitized = list(sanitized)
+            sanitized[0] = {**sanitized[0], "role": "developer"}
+
+        api_kwargs: dict[str, Any] = {
+            "model": model,
+            "messages": sanitized,
+        }
+
+        timeout = params.get("timeout")
+        if timeout is not None:
+            api_kwargs["timeout"] = timeout
+
+        # Tools
+        if tools:
+            # Moonshot/Kimi uses a stricter flavored JSON Schema.  Rewriting
+            # tool parameters here keeps aggregator routes (Nous, OpenRouter,
+            # etc.) compatible, in addition to direct moonshot.ai endpoints.
+            if is_moonshot_model(model):
+                tools = sanitize_moonshot_tools(tools)
+            api_kwargs["tools"] = tools
+
+        # max_tokens resolution — priority: ephemeral > user > provider default
+        max_tokens_fn = params.get("max_tokens_param_fn")
+        ephemeral = params.get("ephemeral_max_output_tokens")
+        max_tokens = params.get("max_tokens")
+        anthropic_max_out = params.get("anthropic_max_output")
+        is_nvidia_nim = params.get("is_nvidia_nim", False)
+        is_kimi = params.get("is_kimi", False)
+        is_tokenhub = params.get("is_tokenhub", False)
+        reasoning_config = params.get("reasoning_config")
+
+        if ephemeral is not None and max_tokens_fn:
+            api_kwargs.update(max_tokens_fn(ephemeral))
+        elif max_tokens is not None and max_tokens_fn:
+            api_kwargs.update(max_tokens_fn(max_tokens))
+        elif anthropic_max_out is not None:
+            api_kwargs["max_tokens"] = anthropic_max_out
+
+        # Kimi: top-level reasoning_effort (unless thinking disabled)
+        if is_kimi:
+            _kimi_thinking_off = bool(
+                reasoning_config
+                and isinstance(reasoning_config, dict)
+                and reasoning_config.get("enabled") is False
+            )
+            if not _kimi_thinking_off:
+                _kimi_effort = "medium"
+                if reasoning_config and isinstance(reasoning_config, dict):
+                    _e = (reasoning_config.get("effort") or "").strip().lower()
+                    if _e in {"low", "medium", "high"}:
+                        _kimi_effort = _e
+                api_kwargs["reasoning_effort"] = _kimi_effort
+
+        # Tencent TokenHub: top-level reasoning_effort (unless thinking disabled)
+        if is_tokenhub:
+            _tokenhub_thinking_off = bool(
+                reasoning_config
+                and isinstance(reasoning_config, dict)
+                and reasoning_config.get("enabled") is False
+            )
+            if not _tokenhub_thinking_off:
+                _tokenhub_effort = "high"
+                if reasoning_config and isinstance(reasoning_config, dict):
+                    _e = (reasoning_config.get("effort") or "").strip().lower()
+                    if _e in {"low", "medium", "high"}:
+                        _tokenhub_effort = _e
+                api_kwargs["reasoning_effort"] = _tokenhub_effort
+
+        # LM Studio: top-level reasoning_effort. Only emit when the model
+        # declares reasoning support via /api/v1/models capabilities (gated
+        # upstream by params["supports_reasoning"]). resolve_lmstudio_effort
+        # is shared with run_agent's summary path so both stay in sync.
+        if params.get("is_lmstudio", False) and params.get("supports_reasoning", False):
+            _lm_effort = resolve_lmstudio_effort(
+                reasoning_config,
+                params.get("lmstudio_reasoning_options"),
+            )
+            if _lm_effort is not None:
+                api_kwargs["reasoning_effort"] = _lm_effort
+
+        # extra_body assembly
+        extra_body: dict[str, Any] = {}
+
+        is_openrouter = params.get("is_openrouter", False)
+        is_nous = params.get("is_nous", False)
+        is_github_models = params.get("is_github_models", False)
+        provider_name = str(params.get("provider_name") or "").strip().lower()
+        base_url = params.get("base_url")
+
+        provider_prefs = params.get("provider_preferences")
+        if provider_prefs and is_openrouter:
+            extra_body["provider"] = provider_prefs
+
+        # Pareto Code router plugin — model-gated. Same shape as the
+        # profile path in plugins/model-providers/openrouter/__init__.py;
+        # this branch only runs when the OpenRouter profile isn't loaded.
+        if is_openrouter and model == "openrouter/pareto-code":
+            _pareto_score = params.get("openrouter_min_coding_score")
+            if _pareto_score is not None and _pareto_score != "":
+                try:
+                    _pareto_score_f = float(_pareto_score)
+                except (TypeError, ValueError):
+                    _pareto_score_f = None
+                if _pareto_score_f is not None and 0.0 <= _pareto_score_f <= 1.0:
+                    extra_body["plugins"] = [
+                        {"id": "pareto-router", "min_coding_score": _pareto_score_f}
+                    ]
+
+        # Kimi extra_body.thinking
+        if is_kimi:
+            _kimi_thinking_enabled = True
+            if reasoning_config and isinstance(reasoning_config, dict):
+                if reasoning_config.get("enabled") is False:
+                    _kimi_thinking_enabled = False
+            extra_body["thinking"] = {
+                "type": "enabled" if _kimi_thinking_enabled else "disabled",
+            }
+
+        # Reasoning. LM Studio is handled above via top-level reasoning_effort,
+        # so skip emitting extra_body.reasoning for it.
+        if params.get("supports_reasoning", False) and not params.get("is_lmstudio", False):
+            if is_github_models:
+                gh_reasoning = params.get("github_reasoning_extra")
+                if gh_reasoning is not None:
+                    extra_body["reasoning"] = gh_reasoning
+            else:
+                extra_body["reasoning"] = {"enabled": True, "effort": "medium"}
+
+        if provider_name == "gemini":
+            raw_thinking_config = _build_gemini_thinking_config(model, reasoning_config)
+            if _is_gemini_openai_compat_base_url(base_url):
+                thinking_config = _snake_case_gemini_thinking_config(raw_thinking_config)
+                if thinking_config:
+                    openai_compat_extra = extra_body.get("extra_body", {})
+                    google_extra = openai_compat_extra.get("google", {})
+                    google_extra["thinking_config"] = thinking_config
+                    openai_compat_extra["google"] = google_extra
+                    extra_body["extra_body"] = openai_compat_extra
+            elif raw_thinking_config:
+                extra_body["thinking_config"] = raw_thinking_config
+        elif provider_name == "google-gemini-cli":
+            thinking_config = _build_gemini_thinking_config(model, reasoning_config)
+            if thinking_config:
+                extra_body["thinking_config"] = thinking_config
+
+        # Merge any pre-built extra_body additions
+        additions = params.get("extra_body_additions")
+        if additions:
+            extra_body.update(additions)
+
+        if extra_body:
+            api_kwargs["extra_body"] = extra_body
+
+        # Request overrides last (service_tier etc.)
+        overrides = params.get("request_overrides")
+        if overrides:
+            api_kwargs.update(overrides)
+
+        return api_kwargs
+
+    def _build_kwargs_from_profile(self, profile, model, sanitized, tools, params):
+        """Build API kwargs using a ProviderProfile — single path, no legacy flags.
+
+        This method replaces the entire flag-based kwargs assembly when a
+        provider_profile is passed. Every quirk comes from the profile object.
+        """
+        from providers.base import OMIT_TEMPERATURE
+
+        # Message preprocessing
+        sanitized = profile.prepare_messages(sanitized)
+
+        # Developer role swap — model-name-based, applies to all providers
+        _model_lower = (model or "").lower()
+        if (
+            sanitized
+            and isinstance(sanitized[0], dict)
+            and sanitized[0].get("role") == "system"
+            and any(p in _model_lower for p in DEVELOPER_ROLE_MODELS)
+        ):
+            sanitized = list(sanitized)
+            sanitized[0] = {**sanitized[0], "role": "developer"}
+
+        api_kwargs: dict[str, Any] = {
+            "model": model,
+            "messages": sanitized,
+        }
+
+        # Temperature
+        if profile.fixed_temperature is OMIT_TEMPERATURE:
+            pass  # Don't include temperature at all
+        elif profile.fixed_temperature is not None:
+            api_kwargs["temperature"] = profile.fixed_temperature
+        else:
+            # Use caller's temperature if provided
+            temp = params.get("temperature")
+            if temp is not None:
+                api_kwargs["temperature"] = temp
+
+        # Timeout
+        timeout = params.get("timeout")
+        if timeout is not None:
+            api_kwargs["timeout"] = timeout
+
+        # Tools — apply Moonshot/Kimi schema sanitization regardless of path
+        if tools:
+            if is_moonshot_model(model):
+                tools = sanitize_moonshot_tools(tools)
+            api_kwargs["tools"] = tools
+
+        # max_tokens resolution — priority: ephemeral > user > profile default
+        max_tokens_fn = params.get("max_tokens_param_fn")
+        ephemeral = params.get("ephemeral_max_output_tokens")
+        user_max = params.get("max_tokens")
+        anthropic_max = params.get("anthropic_max_output")
+        # Per-model default cap — profiles override get_max_tokens() when
+        # they front several backends with different completion-token limits
+        # (e.g. opencode-go: mimo-v2.5-pro = 131072).
+        profile_max = profile.get_max_tokens(model)
+
+        if ephemeral is not None and max_tokens_fn:
+            api_kwargs.update(max_tokens_fn(ephemeral))
+        elif user_max is not None and max_tokens_fn:
+            api_kwargs.update(max_tokens_fn(user_max))
+        elif profile_max and max_tokens_fn:
+            api_kwargs.update(max_tokens_fn(profile_max))
+        elif anthropic_max is not None:
+            api_kwargs["max_tokens"] = anthropic_max
+
+        # Provider-specific api_kwargs extras (reasoning_effort, metadata, etc.)
+        reasoning_config = params.get("reasoning_config")
+        extra_body_from_profile, top_level_from_profile = (
+            profile.build_api_kwargs_extras(
+                reasoning_config=reasoning_config,
+                supports_reasoning=params.get("supports_reasoning", False),
+                qwen_session_metadata=params.get("qwen_session_metadata"),
+                model=model,
+                ollama_num_ctx=params.get("ollama_num_ctx"),
+                session_id=params.get("session_id"),
+            )
+        )
+        api_kwargs.update(top_level_from_profile)
+
+        # extra_body assembly
+        extra_body: dict[str, Any] = {}
+
+        # Profile's extra_body (tags, provider prefs, vl_high_resolution, etc.)
+        profile_body = profile.build_extra_body(
+            session_id=params.get("session_id"),
+            provider_preferences=params.get("provider_preferences"),
+            model=model,
+            base_url=params.get("base_url"),
+            reasoning_config=reasoning_config,
+            openrouter_min_coding_score=params.get("openrouter_min_coding_score"),
+        )
+        if profile_body:
+            extra_body.update(profile_body)
+
+        # Profile's reasoning/thinking extra_body entries
+        if extra_body_from_profile:
+            extra_body.update(extra_body_from_profile)
+
+        # Merge any pre-built extra_body additions from the caller
+        additions = params.get("extra_body_additions")
+        if additions:
+            extra_body.update(additions)
+
+        # Request overrides (user config)
+        overrides = params.get("request_overrides")
+        if overrides:
+            for k, v in overrides.items():
+                if k == "extra_body" and isinstance(v, dict):
+                    extra_body.update(v)
+                else:
+                    api_kwargs[k] = v
+
+        if extra_body:
+            # Native Gemini (generativelanguage.googleapis.com, non-/openai)
+            # speaks Google's REST schema, not OpenAI's. OpenAI-style extra_body
+            # keys (tags, reasoning, provider, plugins, …) are unknown fields
+            # there and Gemini rejects the whole request with a non-retryable
+            # HTTP 400 ("Invalid JSON payload received. Unknown name 'tags'").
+            # This happens when a profile that emits extra_body (e.g. the Nous
+            # profile's portal `tags`) is active but the resolved endpoint is a
+            # Gemini base_url — typical when only Google credentials are set and
+            # a fallback/aux call lands on Gemini. The native client only reads
+            # thinking_config from extra_body, so drop everything else here.
+            try:
+                from agent.gemini_native_adapter import is_native_gemini_base_url
+                _native_gemini = is_native_gemini_base_url(params.get("base_url"))
+            except Exception:
+                _native_gemini = False
+            if _native_gemini:
+                extra_body = {
+                    k: v for k, v in extra_body.items()
+                    if k in ("thinking_config", "thinkingConfig")
+                }
+            if extra_body:
+                api_kwargs["extra_body"] = extra_body
+
+        return api_kwargs
+
+    def normalize_response(self, response: Any, **kwargs) -> NormalizedResponse:
+        """Normalize OpenAI ChatCompletion to NormalizedResponse.
+
+        For chat_completions, this is near-identity — the response is already
+        in OpenAI format.  extra_content on tool_calls (Gemini thought_signature)
+        is preserved via ToolCall.provider_data.  reasoning_details (OpenRouter
+        unified format) and reasoning_content (DeepSeek/Moonshot) are also
+        preserved for downstream replay.
+        """
+        choice = response.choices[0]
+        msg = choice.message
+        finish_reason = choice.finish_reason or "stop"
+
+        tool_calls = None
+        if msg.tool_calls:
+            tool_calls = []
+            for tc in msg.tool_calls:
+                # Preserve provider-specific extras on the tool call.
+                # Gemini 3 thinking models attach extra_content with
+                # thought_signature — without replay on the next turn the API
+                # rejects the request with 400.
+                tc_provider_data: dict[str, Any] = {}
+                extra = getattr(tc, "extra_content", None)
+                if extra is None and hasattr(tc, "model_extra"):
+                    extra = (tc.model_extra or {}).get("extra_content")
+                if extra is not None:
+                    if hasattr(extra, "model_dump"):
+                        try:
+                            extra = extra.model_dump()
+                        except Exception:
+                            pass
+                    tc_provider_data["extra_content"] = extra
+                tool_calls.append(
+                    ToolCall(
+                        id=tc.id,
+                        name=tc.function.name,
+                        arguments=tc.function.arguments,
+                        provider_data=tc_provider_data or None,
+                    )
+                )
+
+        usage = None
+        if hasattr(response, "usage") and response.usage:
+            u = response.usage
+            usage = Usage(
+                prompt_tokens=getattr(u, "prompt_tokens", 0) or 0,
+                completion_tokens=getattr(u, "completion_tokens", 0) or 0,
+                total_tokens=getattr(u, "total_tokens", 0) or 0,
+            )
+
+        # Preserve reasoning fields separately.  DeepSeek/Moonshot use
+        # ``reasoning_content``; others use ``reasoning``.  Downstream code
+        # (_extract_reasoning, thinking-prefill retry) reads both distinctly,
+        # so keep them apart in provider_data rather than merging.
+        reasoning = getattr(msg, "reasoning", None)
+        reasoning_content = getattr(msg, "reasoning_content", None)
+        if reasoning_content is None and hasattr(msg, "model_extra"):
+            model_extra = getattr(msg, "model_extra", None) or {}
+            if isinstance(model_extra, dict) and "reasoning_content" in model_extra:
+                reasoning_content = model_extra["reasoning_content"]
+
+        provider_data: Dict[str, Any] = {}
+        if reasoning_content is not None:
+            provider_data["reasoning_content"] = reasoning_content
+        rd = getattr(msg, "reasoning_details", None)
+        if rd:
+            provider_data["reasoning_details"] = rd
+
+        # OpenAI structured-refusal field. When a model declines, the SDK
+        # populates ``message.refusal`` with the explanation and leaves
+        # ``content`` empty. OpenAI-compatible proxies that front Anthropic /
+        # Bedrock (e.g. Nous Portal) surface a Claude refusal this way — or via
+        # ``finish_reason="content_filter"`` — instead of the native
+        # ``stop_reason="refusal"``. Without capturing it the refusal looks
+        # like an empty response, so the agent loop retries a deterministic
+        # refusal three times and gives up with "no content after retries".
+        # Promote it to content + a ``content_filter`` finish reason so the
+        # loop's refusal handler surfaces it clearly and stops. ``refusal`` is
+        # ``None`` for normal responses, so this is a no-op in the common case.
+        content = msg.content
+        refusal = getattr(msg, "refusal", None)
+        if refusal is None and hasattr(msg, "model_extra"):
+            _msg_extra = getattr(msg, "model_extra", None) or {}
+            if isinstance(_msg_extra, dict):
+                refusal = _msg_extra.get("refusal")
+        if isinstance(refusal, str) and refusal.strip():
+            # Record the refusal explanation regardless — it's useful provider
+            # metadata even when the model also returned a usable payload.
+            provider_data["refusal"] = refusal
+            _has_text = isinstance(content, str) and content.strip()
+            _has_tool_calls = bool(tool_calls)
+            # Only promote to a terminal ``content_filter`` when the refusal is
+            # the *sole* payload — no visible text and no tool calls. A response
+            # that carries real content (or tool calls) alongside a refusal note
+            # is a normal, usable turn: surfacing it as a failed safety refusal
+            # would discard the model's actual work. In the empty-payload case,
+            # adopt the refusal as content so the loop has something to show.
+            if not _has_text and not _has_tool_calls:
+                content = refusal
+                if finish_reason in (None, "stop"):
+                    finish_reason = "content_filter"
+
+        return NormalizedResponse(
+            content=content,
+            tool_calls=tool_calls,
+            finish_reason=finish_reason,
+            reasoning=reasoning,
+            usage=usage,
+            provider_data=provider_data or None,
+        )
+
+    def validate_response(self, response: Any) -> bool:
+        """Check that response has valid choices."""
+        if response is None:
+            return False
+        if not hasattr(response, "choices") or response.choices is None:
+            return False
+        if not response.choices:
+            return False
+        return True
+
+    def extract_cache_stats(self, response: Any) -> dict[str, int] | None:
+        """Extract OpenRouter/OpenAI cache stats from prompt_tokens_details."""
+        usage = getattr(response, "usage", None)
+        if usage is None:
+            return None
+        details = getattr(usage, "prompt_tokens_details", None)
+        if details is None:
+            return None
+        cached = getattr(details, "cached_tokens", 0) or 0
+        written = getattr(details, "cache_write_tokens", 0) or 0
+        if cached or written:
+            return {"cached_tokens": cached, "creation_tokens": written}
+        return None
+
+
+# Auto-register on import
+from agent.transports import register_transport  # noqa: E402
+
+register_transport("chat_completions", ChatCompletionsTransport)

agent/transports/codex.py

@@ -0,0 +1,347 @@
+"""OpenAI Responses API (Codex) transport.
+
+Delegates to the existing adapter functions in agent/codex_responses_adapter.py.
+This transport owns format conversion and normalization — NOT client lifecycle,
+streaming, or the _run_codex_stream() call path.
+"""
+
+from typing import Any, Dict, List, Optional
+
+from agent.transports.base import ProviderTransport
+from agent.transports.types import NormalizedResponse, ToolCall
+
+
+class ResponsesApiTransport(ProviderTransport):
+    """Transport for api_mode='codex_responses'.
+
+    Wraps the functions extracted into codex_responses_adapter.py (PR 1).
+    """
+
+    # Issuer kind of the most recent build_kwargs / convert_messages call.
+    # Used as a fallback when normalize_response is invoked without an
+    # explicit ``issuer_kind`` kwarg, so reasoning items captured from a
+    # response are stamped with the endpoint that minted them. Plain class
+    # attribute default; mutated on the instance, not the class.
+    _last_issuer_kind: Optional[str] = None
+
+    @property
+    def api_mode(self) -> str:
+        return "codex_responses"
+
+    def _resolve_issuer_kind(self, params: Dict[str, Any]) -> str:
+        """Classify the current Responses endpoint from transport params."""
+        from agent.codex_responses_adapter import _classify_responses_issuer
+        return _classify_responses_issuer(
+            is_xai_responses=bool(params.get("is_xai_responses")),
+            is_github_responses=bool(params.get("is_github_responses")),
+            is_codex_backend=bool(params.get("is_codex_backend")),
+            base_url=params.get("base_url"),
+        )
+
+    def convert_messages(self, messages: List[Dict[str, Any]], **kwargs) -> Any:
+        """Convert OpenAI chat messages to Responses API input items."""
+        from agent.codex_responses_adapter import _chat_messages_to_responses_input
+        issuer = self._resolve_issuer_kind(kwargs)
+        self._last_issuer_kind = issuer
+        return _chat_messages_to_responses_input(
+            messages,
+            is_xai_responses=bool(kwargs.get("is_xai_responses")),
+            replay_encrypted_reasoning=bool(
+                kwargs.get("replay_encrypted_reasoning", True)
+            ),
+            current_issuer_kind=issuer,
+        )
+
+    def convert_tools(self, tools: List[Dict[str, Any]]) -> Any:
+        """Convert OpenAI tool schemas to Responses API function definitions."""
+        from agent.codex_responses_adapter import _responses_tools
+        return _responses_tools(tools)
+
+    def build_kwargs(
+        self,
+        model: str,
+        messages: List[Dict[str, Any]],
+        tools: Optional[List[Dict[str, Any]]] = None,
+        **params,
+    ) -> Dict[str, Any]:
+        """Build Responses API kwargs.
+
+        Calls convert_messages and convert_tools internally.
+
+        params:
+            instructions: str — system prompt (extracted from messages[0] if not given)
+            reasoning_config: dict | None — {effort, enabled}
+            session_id: str | None — used for prompt_cache_key + xAI conv header
+            max_tokens: int | None — max_output_tokens
+            timeout: float | None — per-request timeout forwarded to the SDK
+            request_overrides: dict | None — extra kwargs merged in
+            provider: str | None — provider name for backend-specific logic
+            base_url: str | None — endpoint URL
+            base_url_hostname: str | None — hostname for backend detection
+            is_github_responses: bool — Copilot/GitHub models backend
+            is_codex_backend: bool — chatgpt.com/backend-api/codex
+            is_xai_responses: bool — xAI/Grok backend
+            github_reasoning_extra: dict | None — Copilot reasoning params
+        """
+        from agent.codex_responses_adapter import (
+            _chat_messages_to_responses_input,
+            _responses_tools,
+        )
+
+        from run_agent import DEFAULT_AGENT_IDENTITY
+
+        instructions = params.get("instructions", "")
+        payload_messages = messages
+        if not instructions:
+            if messages and messages[0].get("role") == "system":
+                instructions = str(messages[0].get("content") or "").strip()
+                payload_messages = messages[1:]
+        if not instructions:
+            instructions = DEFAULT_AGENT_IDENTITY
+
+        is_github_responses = params.get("is_github_responses", False)
+        is_codex_backend = params.get("is_codex_backend", False)
+        is_xai_responses = params.get("is_xai_responses", False)
+        replay_encrypted_reasoning = bool(
+            params.get("replay_encrypted_reasoning", True)
+        )
+
+        # Resolve the issuing endpoint for this call. Stashed on the
+        # transport so normalize_response can stamp it onto reasoning
+        # items captured from the response, and passed to the input
+        # converter so foreign-issuer reasoning blocks in history are
+        # dropped before the API rejects them.
+        issuer_kind = self._resolve_issuer_kind(params)
+        self._last_issuer_kind = issuer_kind
+
+        # Resolve reasoning effort
+        reasoning_effort = "medium"
+        reasoning_enabled = True
+        reasoning_config = params.get("reasoning_config")
+        if reasoning_config and isinstance(reasoning_config, dict):
+            if reasoning_config.get("enabled") is False:
+                reasoning_enabled = False
+            elif reasoning_config.get("effort"):
+                reasoning_effort = reasoning_config["effort"]
+
+        _effort_clamp = {"minimal": "low"}
+        reasoning_effort = _effort_clamp.get(reasoning_effort, reasoning_effort)
+
+        response_tools = _responses_tools(tools)
+        # ``tools`` MUST be omitted entirely when there are no functions to
+        # expose: the openai SDK's ``responses.stream()`` / ``responses.parse()``
+        # eagerly call ``_make_tools(tools)`` which does ``for tool in tools``
+        # without a None guard, so passing ``tools=None`` raises
+        # ``TypeError: 'NoneType' object is not iterable`` before any HTTP
+        # request is issued (openai==2.24.0).  Reported for the
+        # ``openai-codex`` / ``gpt-5.5`` combo on chatgpt.com/backend-api/codex
+        # (#32892) when the agent runs without external tools registered.
+        kwargs = {
+            "model": model,
+            "instructions": instructions,
+            "input": _chat_messages_to_responses_input(
+                payload_messages,
+                is_xai_responses=is_xai_responses,
+                replay_encrypted_reasoning=replay_encrypted_reasoning,
+                current_issuer_kind=issuer_kind,
+            ),
+            "store": False,
+        }
+        if response_tools:
+            kwargs["tools"] = response_tools
+            kwargs["tool_choice"] = "auto"
+            kwargs["parallel_tool_calls"] = True
+
+        session_id = params.get("session_id")
+        # xAI Responses takes prompt_cache_key in extra_body (set further
+        # down); GitHub Models opts out of cache-key routing entirely.
+        if not is_github_responses and not is_xai_responses and session_id:
+            kwargs["prompt_cache_key"] = session_id
+
+        if reasoning_enabled and is_xai_responses:
+            from agent.model_metadata import grok_supports_reasoning_effort
+
+            # Ask xAI to echo back encrypted reasoning items so we can
+            # replay them on subsequent turns for cross-turn coherence.
+            # See agent/codex_responses_adapter._chat_messages_to_responses_input
+            # for the May 2026 reversal of the earlier suppression gate.
+            kwargs["include"] = (
+                ["reasoning.encrypted_content"] if replay_encrypted_reasoning else []
+            )
+            # xAI rejects `reasoning.effort` on grok-4 / grok-4-fast / grok-3
+            # / grok-code-fast / grok-4.20-0309-* with HTTP 400 even though
+            # those models reason natively. Only send the effort dial when
+            # the target model is on the allowlist; otherwise send no
+            # `reasoning` key at all and let the model reason on its own.
+            if grok_supports_reasoning_effort(model):
+                kwargs["reasoning"] = {"effort": reasoning_effort}
+        elif reasoning_enabled:
+            if is_github_responses:
+                github_reasoning = params.get("github_reasoning_extra")
+                if github_reasoning is not None:
+                    kwargs["reasoning"] = github_reasoning
+            else:
+                kwargs["reasoning"] = {"effort": reasoning_effort, "summary": "auto"}
+                kwargs["include"] = (
+                    ["reasoning.encrypted_content"] if replay_encrypted_reasoning else []
+                )
+        elif not is_github_responses and not is_xai_responses:
+            kwargs["include"] = []
+
+        request_overrides = params.get("request_overrides")
+        if request_overrides:
+            kwargs.update(request_overrides)
+
+        # xAI Responses API rejects ``service_tier`` (HTTP 400 "Argument not
+        # supported: service_tier") — hit when ``/fast`` priority-processing
+        # mode lingers from a prior model in the same session, or when a
+        # user explicitly sets ``agent.service_tier`` in config.yaml.  The
+        # main-loop guard (``resolve_fast_mode_overrides`` only returns
+        # ``service_tier`` for OpenAI fast-eligible models) doesn't cover
+        # those leak paths, so strip defensively when targeting xAI.  See
+        # #28490 for the original report.
+        if is_xai_responses:
+            kwargs.pop("service_tier", None)
+
+        # Forward per-request timeout to the SDK so OpenAI/Anthropic clients
+        # honor it.  Without this, ``providers.<id>.request_timeout_seconds``
+        # is silently dropped on the main agent Codex path while the
+        # chat_completions path and auxiliary Codex adapter both forward it.
+        timeout = kwargs.get("timeout", params.get("timeout"))
+        if (
+            isinstance(timeout, (int, float))
+            and not isinstance(timeout, bool)
+            and 0 < float(timeout) < float("inf")
+        ):
+            kwargs["timeout"] = float(timeout)
+        else:
+            kwargs.pop("timeout", None)
+
+        if is_codex_backend:
+            # chatgpt.com/backend-api/codex rejects body-level
+            # ``extra_headers`` with HTTP 400. Correlation/cache routing for
+            # this backend must not be sent through the Responses payload.
+            kwargs.pop("extra_headers", None)
+
+        max_tokens = params.get("max_tokens")
+        if max_tokens is not None and not is_codex_backend:
+            kwargs["max_output_tokens"] = max_tokens
+
+        if is_xai_responses and session_id:
+            existing_extra_headers = kwargs.get("extra_headers")
+            merged_extra_headers: Dict[str, str] = {}
+            if isinstance(existing_extra_headers, dict):
+                merged_extra_headers.update(
+                    {
+                        str(key): str(value)
+                        for key, value in existing_extra_headers.items()
+                        if key and value is not None
+                    }
+                )
+            merged_extra_headers["x-grok-conv-id"] = session_id
+            kwargs["extra_headers"] = merged_extra_headers
+
+            # xAI Responses cache-routing — body-level field per
+            # https://docs.x.ai/developers/advanced-api-usage/prompt-caching/maximizing-cache-hits.
+            # Sent via extra_body (not the typed kwarg) so it survives openai
+            # SDK builds whose Responses.stream() signature has dropped the field.
+            existing_extra_body = kwargs.get("extra_body")
+            merged_extra_body: Dict[str, Any] = {}
+            if isinstance(existing_extra_body, dict):
+                merged_extra_body.update(existing_extra_body)
+            merged_extra_body.setdefault("prompt_cache_key", session_id)
+            kwargs["extra_body"] = merged_extra_body
+
+        return kwargs
+
+    def normalize_response(self, response: Any, **kwargs) -> NormalizedResponse:
+        """Normalize Codex Responses API response to NormalizedResponse."""
+        from agent.codex_responses_adapter import (
+            _normalize_codex_response,
+        )
+
+        # Issuer for this response = explicit kwarg if the caller knows it,
+        # otherwise the stash from the matching build_kwargs/convert_messages
+        # call. Either way it gets stamped onto reasoning items so future
+        # turns can detect a model swap and drop foreign-issuer blobs.
+        issuer_kind = kwargs.get("issuer_kind") or self._last_issuer_kind
+        # _normalize_codex_response returns (SimpleNamespace, finish_reason_str)
+        msg, finish_reason = _normalize_codex_response(response, issuer_kind=issuer_kind)
+
+        tool_calls = None
+        if msg and msg.tool_calls:
+            tool_calls = []
+            for tc in msg.tool_calls:
+                provider_data = {}
+                if hasattr(tc, "call_id") and tc.call_id:
+                    provider_data["call_id"] = tc.call_id
+                if hasattr(tc, "response_item_id") and tc.response_item_id:
+                    provider_data["response_item_id"] = tc.response_item_id
+                tool_calls.append(ToolCall(
+                    id=tc.id if hasattr(tc, "id") else (tc.function.name if hasattr(tc, "function") else None),
+                    name=tc.function.name if hasattr(tc, "function") else getattr(tc, "name", ""),
+                    arguments=tc.function.arguments if hasattr(tc, "function") else getattr(tc, "arguments", "{}"),
+                    provider_data=provider_data or None,
+                ))
+
+        # Extract reasoning items for provider_data
+        provider_data = {}
+        if msg and hasattr(msg, "codex_reasoning_items") and msg.codex_reasoning_items:
+            provider_data["codex_reasoning_items"] = msg.codex_reasoning_items
+        if msg and hasattr(msg, "codex_message_items") and msg.codex_message_items:
+            provider_data["codex_message_items"] = msg.codex_message_items
+        if msg and hasattr(msg, "reasoning_details") and msg.reasoning_details:
+            provider_data["reasoning_details"] = msg.reasoning_details
+
+        return NormalizedResponse(
+            content=msg.content if msg else None,
+            tool_calls=tool_calls,
+            finish_reason=finish_reason or "stop",
+            reasoning=msg.reasoning if msg and hasattr(msg, "reasoning") else None,
+            usage=None,  # Codex usage is extracted separately in normalize_usage()
+            provider_data=provider_data or None,
+        )
+
+    def validate_response(self, response: Any) -> bool:
+        """Check Codex Responses API response has valid output structure.
+
+        Returns True only if response.output is a non-empty list.
+        Does NOT check output_text fallback — the caller handles that
+        with diagnostic logging for stream backfill recovery.
+        """
+        if response is None:
+            return False
+        output = getattr(response, "output", None)
+        if not isinstance(output, list) or not output:
+            return False
+        return True
+
+    def preflight_kwargs(self, api_kwargs: Any, *, allow_stream: bool = False) -> dict:
+        """Validate and sanitize Codex API kwargs before the call.
+
+        Normalizes input items, strips unsupported fields, validates structure.
+        """
+        from agent.codex_responses_adapter import _preflight_codex_api_kwargs
+        return _preflight_codex_api_kwargs(api_kwargs, allow_stream=allow_stream)
+
+    def map_finish_reason(self, raw_reason: str) -> str:
+        """Map Codex response.status to OpenAI finish_reason.
+
+        Codex uses response.status ('completed', 'incomplete') +
+        response.incomplete_details.reason for granular mapping.
+        This method handles the simple status string; the caller
+        should check incomplete_details separately for 'max_output_tokens'.
+        """
+        _MAP = {
+            "completed": "stop",
+            "incomplete": "length",
+            "failed": "stop",
+            "cancelled": "stop",
+        }
+        return _MAP.get(raw_reason, "stop")
+
+
+# Auto-register on import
+from agent.transports import register_transport  # noqa: E402
+
+register_transport("codex_responses", ResponsesApiTransport)

agent/transports/codex_app_server.py

@@ -0,0 +1,400 @@
+"""Codex app-server JSON-RPC client.
+
+Speaks the protocol documented in codex-rs/app-server/README.md (codex 0.125+).
+Transport is newline-delimited JSON-RPC 2.0 over stdio: spawn `codex app-server`,
+do an `initialize` handshake, then drive `thread/start` + `turn/start` and
+consume streaming `item/*` notifications until `turn/completed`.
+
+This module is the wire-level speaker only. Higher-level concerns (event
+projection into Hermes' display, approval bridging, transcript projection into
+AIAgent.messages, plugin migration) live in sibling modules.
+
+Status: optional opt-in runtime gated behind `model.openai_runtime ==
+"codex_app_server"`. Hermes' default tool dispatch is unchanged when this
+runtime is not selected.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import queue
+import subprocess
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+# Default minimum codex version we test against. The PR sets this from the
+# `codex --version` parsed at install time; bumping is a one-line change here.
+MIN_CODEX_VERSION = (0, 125, 0)
+
+
+@dataclass
+class CodexAppServerError(RuntimeError):
+    """Raised on JSON-RPC errors from the app-server."""
+
+    code: int
+    message: str
+    data: Optional[Any] = None
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        return f"codex app-server error {self.code}: {self.message}"
+
+
+@dataclass
+class _Pending:
+    queue: queue.Queue
+    method: str
+    sent_at: float = field(default_factory=time.time)
+
+
+class CodexAppServerClient:
+    """Minimal JSON-RPC 2.0 client for `codex app-server` over stdio.
+
+    Threading model:
+      - Spawning thread (caller) drives request/response pairs synchronously.
+      - One reader thread parses stdout, dispatches replies to the right
+        pending future, and routes notifications + server-initiated requests
+        to bounded queues that the caller drains on their own cadence.
+      - One reader thread captures stderr for diagnostics; codex emits
+        tracing logs there at RUST_LOG-controlled levels.
+
+    Intentionally NOT async. AIAgent.run_conversation() is synchronous and
+    runs on the main thread; layering asyncio just to drive a stdio child
+    creates surprising interrupt semantics. We use blocking queues with
+    timeouts and rely on `turn/interrupt` for cancellation.
+    """
+
+    def __init__(
+        self,
+        codex_bin: str = "codex",
+        codex_home: Optional[str] = None,
+        extra_args: Optional[list[str]] = None,
+        env: Optional[dict[str, str]] = None,
+    ) -> None:
+        self._codex_bin = codex_bin
+        spawn_env = os.environ.copy()
+        if env:
+            spawn_env.update(env)
+        if codex_home:
+            spawn_env["CODEX_HOME"] = codex_home
+
+        app_server_args = list(extra_args or [])
+        # Kanban workers must be able to write their handoff/status back to
+        # the board DB, which lives outside the per-task workspace. Keep the
+        # Codex sandbox on, but add the Kanban root as the only extra writable
+        # root. Without this, codex-runtime workers finish their actual work
+        # but crash/block when kanban_complete/kanban_block writes SQLite.
+        if spawn_env.get("HERMES_KANBAN_TASK"):
+            kanban_db = spawn_env.get("HERMES_KANBAN_DB")
+            kanban_root = (
+                os.path.dirname(kanban_db)
+                if kanban_db
+                else spawn_env.get(
+                    "HERMES_KANBAN_ROOT",
+                    os.path.join(
+                        spawn_env.get("HERMES_HOME", os.path.expanduser("~/.hermes")),
+                        "kanban",
+                    ),
+                )
+            )
+            app_server_args.extend(
+                [
+                    "-c",
+                    'sandbox_mode="workspace-write"',
+                    "-c",
+                    f'sandbox_workspace_write.writable_roots=["{kanban_root}"]',
+                    "-c",
+                    "sandbox_workspace_write.network_access=false",
+                ]
+            )
+
+        cmd = [codex_bin, "app-server"] + app_server_args
+        # Codex emits tracing to stderr; default WARN keeps it quiet for users.
+        spawn_env.setdefault("RUST_LOG", "warn")
+
+        self._proc = subprocess.Popen(
+            cmd,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            bufsize=0,
+            env=spawn_env,
+        )
+        self._next_id = 1
+        self._pending: dict[int, _Pending] = {}
+        self._pending_lock = threading.Lock()
+        self._notifications: queue.Queue = queue.Queue()
+        self._server_requests: queue.Queue = queue.Queue()
+        self._stderr_lines: list[str] = []
+        self._stderr_lock = threading.Lock()
+        self._closed = False
+        self._initialized = False
+
+        self._reader = threading.Thread(target=self._read_stdout, daemon=True)
+        self._reader.start()
+        self._stderr_reader = threading.Thread(target=self._read_stderr, daemon=True)
+        self._stderr_reader.start()
+
+    # ---------- lifecycle ----------
+
+    def initialize(
+        self,
+        client_name: str = "hermes",
+        client_title: str = "Hermes Agent",
+        client_version: str = "0.1",
+        capabilities: Optional[dict] = None,
+        timeout: float = 10.0,
+    ) -> dict:
+        """Send `initialize` + `initialized` handshake. Returns the server's
+        InitializeResponse (userAgent, codexHome, platformFamily, platformOs)."""
+        if self._initialized:
+            raise RuntimeError("already initialized")
+        params = {
+            "clientInfo": {
+                "name": client_name,
+                "title": client_title,
+                "version": client_version,
+            },
+            "capabilities": capabilities or {},
+        }
+        result = self.request("initialize", params, timeout=timeout)
+        self.notify("initialized")
+        self._initialized = True
+        return result
+
+    def close(self, timeout: float = 3.0) -> None:
+        """Close stdin and wait for the subprocess to exit, escalating to kill."""
+        if self._closed:
+            return
+        self._closed = True
+        try:
+            if self._proc.stdin and not self._proc.stdin.closed:
+                self._proc.stdin.close()
+        except Exception:
+            pass
+        try:
+            self._proc.terminate()
+            self._proc.wait(timeout=timeout)
+        except subprocess.TimeoutExpired:
+            try:
+                self._proc.kill()
+                self._proc.wait(timeout=1.0)
+            except Exception:
+                pass
+
+    def __enter__(self) -> "CodexAppServerClient":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    # ---------- send/receive ----------
+
+    def request(
+        self,
+        method: str,
+        params: Optional[dict] = None,
+        timeout: float = 30.0,
+    ) -> dict:
+        """Send a JSON-RPC request and block on the response. Returns `result`,
+        raises CodexAppServerError on `error`."""
+        rid = self._take_id()
+        q: queue.Queue = queue.Queue(maxsize=1)
+        with self._pending_lock:
+            self._pending[rid] = _Pending(queue=q, method=method)
+        self._send({"id": rid, "method": method, "params": params or {}})
+        try:
+            msg = q.get(timeout=timeout)
+        except queue.Empty:
+            with self._pending_lock:
+                self._pending.pop(rid, None)
+            raise TimeoutError(
+                f"codex app-server method {method!r} timed out after {timeout}s"
+            )
+        if "error" in msg:
+            err = msg["error"]
+            raise CodexAppServerError(
+                code=err.get("code", -1),
+                message=err.get("message", ""),
+                data=err.get("data"),
+            )
+        return msg.get("result", {})
+
+    def notify(self, method: str, params: Optional[dict] = None) -> None:
+        """Send a JSON-RPC notification (no id, no response expected)."""
+        self._send({"method": method, "params": params or {}})
+
+    def respond(self, request_id: Any, result: dict) -> None:
+        """Reply to a server-initiated request (e.g. approval prompts)."""
+        self._send({"id": request_id, "result": result})
+
+    def respond_error(
+        self, request_id: Any, code: int, message: str, data: Optional[Any] = None
+    ) -> None:
+        """Reply to a server-initiated request with an error."""
+        err: dict[str, Any] = {"code": code, "message": message}
+        if data is not None:
+            err["data"] = data
+        self._send({"id": request_id, "error": err})
+
+    def take_notification(self, timeout: float = 0.0) -> Optional[dict]:
+        """Pop the next streaming notification, or return None on timeout.
+
+        timeout=0.0 means non-blocking. Use small positive timeouts inside the
+        AIAgent turn loop to interleave reads with interrupt checks."""
+        try:
+            if timeout <= 0:
+                return self._notifications.get_nowait()
+            return self._notifications.get(timeout=timeout)
+        except queue.Empty:
+            return None
+
+    def take_server_request(self, timeout: float = 0.0) -> Optional[dict]:
+        """Pop the next server-initiated request (e.g. exec/applyPatch approval)."""
+        try:
+            if timeout <= 0:
+                return self._server_requests.get_nowait()
+            return self._server_requests.get(timeout=timeout)
+        except queue.Empty:
+            return None
+
+    # ---------- diagnostics ----------
+
+    def stderr_tail(self, n: int = 20) -> list[str]:
+        """Return last n lines of codex's stderr (for error reports)."""
+        with self._stderr_lock:
+            return list(self._stderr_lines[-n:])
+
+    def is_alive(self) -> bool:
+        return self._proc.poll() is None
+
+    # ---------- internals ----------
+
+    def _take_id(self) -> int:
+        # JSON-RPC ids only need to be unique per-connection. A simple
+        # monotonically increasing int is the common choice and matches what
+        # codex's own clients use.
+        rid = self._next_id
+        self._next_id += 1
+        return rid
+
+    def _send(self, obj: dict) -> None:
+        if self._closed:
+            raise RuntimeError("codex app-server client is closed")
+        if self._proc.stdin is None:
+            raise RuntimeError("codex app-server stdin not available")
+        try:
+            self._proc.stdin.write((json.dumps(obj) + "\n").encode("utf-8"))
+            self._proc.stdin.flush()
+        except (BrokenPipeError, ValueError) as exc:
+            raise RuntimeError(
+                f"codex app-server stdin closed unexpectedly: {exc}"
+            ) from exc
+
+    def _read_stdout(self) -> None:
+        if self._proc.stdout is None:
+            return
+        try:
+            for line in iter(self._proc.stdout.readline, b""):
+                if not line:
+                    break
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    msg = json.loads(line)
+                except json.JSONDecodeError:
+                    # Non-JSON output is unexpected on stdout; tracing belongs
+                    # on stderr. Surface it via stderr buffer for diagnostics.
+                    with self._stderr_lock:
+                        self._stderr_lines.append(
+                            f"<non-json on stdout> {line[:200]!r}"
+                        )
+                    continue
+                self._dispatch(msg)
+        except Exception as exc:
+            with self._stderr_lock:
+                self._stderr_lines.append(f"<stdout reader error> {exc}")
+
+    def _dispatch(self, msg: dict) -> None:
+        # Reply (has id + result/error, no method)
+        if "id" in msg and ("result" in msg or "error" in msg):
+            with self._pending_lock:
+                pending = self._pending.pop(msg["id"], None)
+            if pending is not None:
+                try:
+                    pending.queue.put_nowait(msg)
+                except queue.Full:  # pragma: no cover - defensive
+                    pass
+            return
+        # Server-initiated request (has id + method)
+        if "id" in msg and "method" in msg:
+            self._server_requests.put(msg)
+            return
+        # Notification (no id)
+        if "method" in msg:
+            self._notifications.put(msg)
+
+    def _read_stderr(self) -> None:
+        if self._proc.stderr is None:
+            return
+        try:
+            for line in iter(self._proc.stderr.readline, b""):
+                if not line:
+                    break
+                with self._stderr_lock:
+                    self._stderr_lines.append(
+                        line.decode("utf-8", "replace").rstrip()
+                    )
+                    # Bound memory: keep last 500 lines.
+                    if len(self._stderr_lines) > 500:
+                        self._stderr_lines = self._stderr_lines[-500:]
+        except Exception:  # pragma: no cover
+            pass
+
+
+def parse_codex_version(output: str) -> Optional[tuple[int, int, int]]:
+    """Parse `codex --version` output. Returns (major, minor, patch) or None."""
+    # Output format: "codex-cli 0.130.0" possibly followed by metadata.
+    import re
+
+    match = re.search(r"(\d+)\.(\d+)\.(\d+)", output or "")
+    if not match:
+        return None
+    return (int(match.group(1)), int(match.group(2)), int(match.group(3)))
+
+
+def check_codex_binary(
+    codex_bin: str = "codex", min_version: tuple[int, int, int] = MIN_CODEX_VERSION
+) -> tuple[bool, str]:
+    """Verify codex CLI is installed and meets minimum version.
+
+    Returns (ok, message). Used by setup wizard and runtime startup."""
+    try:
+        proc = subprocess.run(
+            [codex_bin, "--version"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+            stdin=subprocess.DEVNULL,
+        )
+    except FileNotFoundError:
+        return False, (
+            f"codex CLI not found at {codex_bin!r}. Install with: "
+            f"npm i -g @openai/codex"
+        )
+    except subprocess.TimeoutExpired:
+        return False, "codex --version timed out"
+    if proc.returncode != 0:
+        return False, f"codex --version exited {proc.returncode}: {proc.stderr.strip()}"
+    version = parse_codex_version(proc.stdout)
+    if version is None:
+        return False, f"could not parse codex version from: {proc.stdout!r}"
+    if version < min_version:
+        return False, (
+            f"codex {'.'.join(map(str, version))} is older than required "
+            f"{'.'.join(map(str, min_version))}. Run: npm i -g @openai/codex"
+        )
+    return True, ".".join(map(str, version))

agent/transports/codex_app_server_session.py

@@ -0,0 +1,876 @@
+"""Session adapter for codex app-server runtime.
+
+Owns one Codex thread per Hermes session. Drives `turn/start`, consumes
+streaming notifications via CodexEventProjector, handles server-initiated
+approval requests (apply_patch, exec command), translates cancellation,
+and returns a clean turn result that AIAgent.run_conversation() can splice
+into its `messages` list.
+
+Lifecycle:
+    session = CodexAppServerSession(cwd="/home/x/proj")
+    session.ensure_started()                              # spawns + handshake + thread/start
+    result = session.run_turn(user_input="hello")         # blocks until turn/completed
+    # result.final_text          → assistant text returned to caller
+    # result.projected_messages  → list of {role, content, ...} for messages list
+    # result.tool_iterations     → how many tool-shaped items completed (skill nudge counter)
+    # result.interrupted         → True if Ctrl+C / interrupt_requested fired mid-turn
+    session.close()                                       # tears down subprocess
+
+Threading model: the adapter is single-threaded from the caller's perspective.
+The underlying CodexAppServerClient owns its own reader threads but exposes
+blocking-with-timeout queues that this adapter polls in a loop, so the run_turn
+call is synchronous and behaves like AIAgent's existing chat_completions loop.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable, Optional
+
+from agent.codex_responses_adapter import _format_responses_error
+from agent.redact import redact_sensitive_text
+from agent.transports.codex_app_server import (
+    CodexAppServerClient,
+    CodexAppServerError,
+)
+from agent.transports.codex_event_projector import CodexEventProjector
+
+logger = logging.getLogger(__name__)
+
+
+# How many tailing stderr lines from the codex subprocess to attach to a
+# user-facing error when we don't have a more specific classification (OAuth,
+# wedge watchdog, etc.). Small enough to keep error messages legible, large
+# enough to surface a config/provider/auth diagnostic.
+_STDERR_TAIL_LINES = 12
+
+
+# Permission profile mapping mirrors the docstring in PR proposal:
+# Hermes' tools.terminal.security_mode → Codex's permissions profile id.
+# Defaults if config is missing → workspace-write (matches Codex's own default).
+_HERMES_TO_CODEX_PERMISSION_PROFILE = {
+    "auto": "workspace-write",
+    "approval-required": "read-only-with-approval",
+    "unrestricted": "full-access",
+    # Backstop alias used by some skills/tests.
+    "yolo": "full-access",
+}
+
+
+@dataclass
+class TurnResult:
+    """Result of one user→assistant→tool turn through the codex app-server."""
+
+    final_text: str = ""
+    projected_messages: list[dict] = field(default_factory=list)
+    tool_iterations: int = 0
+    interrupted: bool = False
+    error: Optional[str] = None  # Set if turn ended in a non-recoverable error
+    turn_id: Optional[str] = None
+    thread_id: Optional[str] = None
+    token_usage_last: Optional[dict[str, Any]] = None
+    token_usage_total: Optional[dict[str, Any]] = None
+    model_context_window: Optional[int] = None
+    # Hint to the caller that the underlying codex subprocess is likely
+    # wedged (turn-level timeout fired, post-tool watchdog tripped, or
+    # token-refresh failure killed the child). The caller should retire
+    # the session so the next turn respawns codex from scratch instead
+    # of riding a CPU-spinning or auth-broken process. Mirrors openclaw
+    # beta.8's "retire timed-out app-server clients" fix.
+    should_retire: bool = False
+
+
+# Markers we accept as terminal even when codex never emits turn/completed.
+# Some codex versions stream `<turn_aborted>` as raw text in agentMessage
+# items when an interrupt or upstream error tears the turn down before the
+# normal completion path fires. Mirrors openclaw beta.8 fix.
+_TURN_ABORTED_MARKERS = ("<turn_aborted>", "<turn_aborted/>")
+
+
+def _coerce_turn_input_text(user_input: Any) -> str:
+    """Collapse Hermes/OpenAI rich content into app-server text input.
+
+    The current `turn/start` path sends text items only. TUI image attachment
+    can hand us OpenAI-style content parts, so keep the text/path hints and
+    replace opaque image payloads with a small marker instead of putting a
+    Python list into the `text` field.
+    """
+    if isinstance(user_input, str):
+        return user_input
+    if isinstance(user_input, list):
+        parts: list[str] = []
+        for item in user_input:
+            if isinstance(item, str):
+                if item.strip():
+                    parts.append(item)
+                continue
+            if not isinstance(item, dict):
+                if item is not None:
+                    parts.append(str(item))
+                continue
+            item_type = item.get("type")
+            if item_type in {"text", "input_text"}:
+                text = item.get("text") or item.get("content") or ""
+                if text:
+                    parts.append(str(text))
+            elif item_type in {"image", "image_url", "input_image"}:
+                parts.append("[image attached]")
+        text = "\n\n".join(p for p in parts if p).strip()
+        return text or "What do you see in this image?"
+    return "" if user_input is None else str(user_input)
+
+
+# Substrings in codex stderr / JSON-RPC error messages that signal the
+# subprocess died because its OAuth credentials are no longer valid.
+# Kept conservative: we only redirect users to `codex login` when we're
+# reasonably sure that's the actual failure, otherwise we surface the
+# original error verbatim. Mirrors openclaw beta.8's auth-refresh
+# classification.
+_OAUTH_REFRESH_FAILURE_HINTS = (
+    "invalid_grant",
+    "invalid grant",
+    "refresh token",
+    "refresh_token",
+    "token refresh",
+    "token_refresh",
+    "token has expired",
+    "expired_token",
+    "expired token",
+    "not authenticated",
+    "unauthenticated",
+    "unauthorized",
+    "401 unauthorized",
+    "re-authenticate",
+    "reauthenticate",
+    "please log in",
+    "please login",
+    "auth profile",
+    "no auth profile",
+    "oauth",
+)
+
+
+def _classify_oauth_failure(*parts: str) -> Optional[str]:
+    """Return a user-friendly re-auth hint if any of the provided strings
+    look like a codex OAuth/token-refresh failure; otherwise None.
+
+    Used for both `turn/start` JSON-RPC errors and post-mortem stderr
+    inspection when the subprocess exits unexpectedly. Conservative on
+    purpose — we only redirect users to `codex login` when the signal
+    is strong, so unrelated runtime failures still surface verbatim.
+    """
+    haystack = " ".join(p for p in parts if p).lower()
+    if not haystack:
+        return None
+    for needle in _OAUTH_REFRESH_FAILURE_HINTS:
+        if needle in haystack:
+            return (
+                "Codex authentication failed — your ChatGPT/Codex login "
+                "looks expired or invalid. Run `codex login` to refresh, "
+                "then retry. (Fall back to default runtime with "
+                "`/codex-runtime auto` if the issue persists.)"
+            )
+    return None
+
+
+@dataclass
+class _ServerRequestRouting:
+    """Default policies for codex-side approval requests when no interactive
+    callback is wired in. These are only used by tests + cron / non-interactive
+    contexts; the live CLI path passes an approval_callback that defers to
+    tools.approval.prompt_dangerous_approval()."""
+
+    auto_approve_exec: bool = False
+    auto_approve_apply_patch: bool = False
+
+
+class CodexAppServerSession:
+    """One Codex thread per Hermes session, lifetime owned by AIAgent.
+
+    Not thread-safe — one caller drives it at a time, matching how AIAgent's
+    run_conversation() loop is structured today. The codex client itself can
+    handle interleaved reads/writes via its own threads, but the adapter's
+    state (projector, thread_id, turn counter) is owned by the caller thread.
+    """
+
+    def __init__(
+        self,
+        *,
+        cwd: Optional[str] = None,
+        codex_bin: str = "codex",
+        codex_home: Optional[str] = None,
+        permission_profile: Optional[str] = None,
+        approval_callback: Optional[Callable[..., str]] = None,
+        on_event: Optional[Callable[[dict], None]] = None,
+        request_routing: Optional[_ServerRequestRouting] = None,
+        client_factory: Optional[Callable[..., CodexAppServerClient]] = None,
+    ) -> None:
+        self._cwd = cwd or os.getcwd()
+        self._codex_bin = codex_bin
+        self._codex_home = codex_home
+        self._permission_profile = (
+            permission_profile or _HERMES_TO_CODEX_PERMISSION_PROFILE.get(
+                os.environ.get("HERMES_TERMINAL_SECURITY_MODE", "auto"),
+                "workspace-write",
+            )
+        )
+        self._approval_callback = approval_callback
+        self._on_event = on_event  # Display hook (kawaii spinner ticks etc.)
+        self._routing = request_routing or _ServerRequestRouting()
+        self._client_factory = client_factory or CodexAppServerClient
+
+        self._client: Optional[CodexAppServerClient] = None
+        self._thread_id: Optional[str] = None
+        self._interrupt_event = threading.Event()
+        # Pending file-change items, keyed by item id. Populated on
+        # item/started for fileChange items; consumed by the approval
+        # bridge when codex sends item/fileChange/requestApproval. The
+        # approval params don't carry the changeset, so we cache here
+        # to surface a real summary in the approval prompt (quirk #4).
+        self._pending_file_changes: dict[str, str] = {}
+        self._closed = False
+
+    # ---------- lifecycle ----------
+
+    def ensure_started(self) -> str:
+        """Spawn the subprocess, do the initialize handshake, and start a
+        thread. Returns the codex thread id. Idempotent — repeated calls
+        return the same thread id."""
+        if self._thread_id is not None:
+            return self._thread_id
+        if self._client is None:
+            self._client = self._client_factory(
+                codex_bin=self._codex_bin, codex_home=self._codex_home
+            )
+        self._client.initialize(
+            client_name="hermes",
+            client_title="Hermes Agent",
+            client_version=_get_hermes_version(),
+        )
+        # Permission selection is intentionally NOT sent on thread/start.
+        # Two reasons (live-tested against codex 0.130.0):
+        #   1. `thread/start.permissions` is gated behind the experimentalApi
+        #      capability on this codex version — we'd have to opt in during
+        #      initialize and accept the unstable surface.
+        #   2. Even with experimentalApi declared and the correct shape
+        #      (`{"type": "profile", "id": "..."}`, not `{"profileId": ...}`),
+        #      codex requires a matching `[permissions]` table in
+        #      ~/.codex/config.toml or it fails the request with
+        #      'default_permissions requires a [permissions] table'.
+        # Letting codex pick its default (`:read-only` unless the user has
+        # configured otherwise in their codex config.toml) is the standard
+        # codex CLI workflow and avoids fighting codex's own validation.
+        # Users who want a write-capable profile configure it in their
+        # ~/.codex/config.toml the same way they would for any codex usage.
+        params: dict[str, Any] = {"cwd": self._cwd}
+        result = self._client.request("thread/start", params, timeout=15)
+        # Cross-fill thread.id/sessionId — different codex versions have
+        # serialized this under either key. Mirrors openclaw beta.8's
+        # tolerance fix so future codex drops/renames don't KeyError us
+        # at handshake time.
+        thread_obj = result.get("thread") or {}
+        thread_id = (
+            thread_obj.get("id")
+            or thread_obj.get("sessionId")
+            or result.get("sessionId")
+            or result.get("threadId")
+        )
+        if not thread_id:
+            raise CodexAppServerError(
+                code=-32603,
+                message=(
+                    "codex thread/start returned no thread id "
+                    f"(payload keys: {sorted(result.keys())})"
+                ),
+            )
+        self._thread_id = thread_id
+        logger.info(
+            "codex app-server thread started: id=%s profile=%s cwd=%s",
+            self._thread_id[:8],
+            self._permission_profile,
+            self._cwd,
+        )
+        return self._thread_id
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        if self._client is not None:
+            try:
+                self._client.close()
+            except Exception:  # pragma: no cover - best-effort cleanup
+                pass
+            self._client = None
+        self._thread_id = None
+
+    def __enter__(self) -> "CodexAppServerSession":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    # ---------- interrupt ----------
+
+    def request_interrupt(self) -> None:
+        """Idempotent: signal the active turn loop to issue turn/interrupt
+        and unwind. Called by AIAgent's _interrupt_requested path."""
+        self._interrupt_event.set()
+
+    # ---------- diagnostics ----------
+
+    def _format_error_with_stderr(
+        self,
+        prefix: str,
+        exc: Any = "",
+        *,
+        tail_lines: int = _STDERR_TAIL_LINES,
+    ) -> str:
+        """Build a user-facing error string for codex failures.
+
+        Appends the last few lines of codex's stderr buffer when available,
+        passed through agent.redact with force=True so secrets in provider
+        error responses (auth headers, query-string tokens, sk-* keys) never
+        leak into chat output or trajectories. The codex CLI's own error
+        text ('Internal error', 'turn/start failed: ...') is otherwise
+        opaque and forces users to re-run with verbose flags to diagnose
+        config / provider / auth-bridge problems.
+
+        Use this for the generic / catch-all branches. Specific
+        classifications (OAuth via _classify_oauth_failure, post-tool wedge
+        watchdog) already produce a clean hint and should be used instead.
+        """
+        exc_str = str(exc) if exc != "" and exc is not None else ""
+        base = f"{prefix}: {exc_str}" if exc_str else prefix
+        if self._client is None:
+            return base
+        try:
+            tail = self._client.stderr_tail(tail_lines)
+        except Exception:  # pragma: no cover - diagnostic best-effort
+            return base
+        if not tail:
+            return base
+        joined = "\n".join(line.rstrip() for line in tail if line)
+        if not joined.strip():
+            return base
+        redacted = redact_sensitive_text(joined, force=True)
+        return f"{base}\ncodex stderr (last {len(tail)} lines):\n{redacted}"
+
+    # ---------- per-turn ----------
+
+    def run_turn(
+        self,
+        user_input: Any,
+        *,
+        turn_timeout: float = 600.0,
+        notification_poll_timeout: float = 0.25,
+        post_tool_quiet_timeout: float = 90.0,
+    ) -> TurnResult:
+        """Send a user message and block until turn/completed, while
+        forwarding server-initiated approval requests and projecting items
+        into Hermes' messages shape.
+
+        post_tool_quiet_timeout: if codex emits a tool completion and then
+        goes quiet for this many seconds without emitting another item or
+        `turn/completed`, fast-fail and mark the session for retirement.
+        Mirrors openclaw beta.8's post-tool completion watchdog (#81697)
+        so a wedged codex doesn't burn the full turn deadline.
+        """
+        # Pre-create the result so startup failures (codex subprocess can't
+        # spawn, initialize handshake rejects, thread/start blows up) surface
+        # the same way per-turn failures do — with a TurnResult.error string
+        # the caller can render — instead of bubbling raw codex exceptions
+        # up to AIAgent.run_conversation.
+        result = TurnResult()
+        try:
+            self.ensure_started()
+        except (CodexAppServerError, TimeoutError) as exc:
+            result.error = self._format_error_with_stderr(
+                "codex app-server startup failed", exc
+            )
+            # Subprocess almost certainly unhealthy — retire so the next
+            # turn re-spawns cleanly.
+            result.should_retire = True
+            return result
+        assert self._client is not None and self._thread_id is not None
+        result.thread_id = self._thread_id
+
+        self._interrupt_event.clear()
+        projector = CodexEventProjector()
+
+        user_input_text = _coerce_turn_input_text(user_input)
+
+        # Send turn/start with the user input. Text-only for now (codex
+        # supports rich content but Hermes' text path is the common case).
+        try:
+            ts = self._client.request(
+                "turn/start",
+                {
+                    "threadId": self._thread_id,
+                    "input": [{"type": "text", "text": user_input_text}],
+                },
+                timeout=10,
+            )
+        except CodexAppServerError as exc:
+            # Classify auth/refresh failures so the user gets a clear
+            # `codex login` pointer instead of a raw RPC error string.
+            stderr_blob = "\n".join(self._client.stderr_tail(40))
+            hint = _classify_oauth_failure(exc.message, stderr_blob)
+            if hint is not None:
+                result.error = hint
+                # Subprocess is fine on a JSON-RPC level here, but the
+                # token store is broken — retire so the next turn does a
+                # clean handshake (and the user has a chance to re-auth
+                # via `codex login` between turns).
+                result.should_retire = True
+            else:
+                result.error = self._format_error_with_stderr(
+                    "turn/start failed", exc
+                )
+            return result
+        except TimeoutError as exc:
+            # turn/start hanging is a strong signal the subprocess is wedged.
+            stderr_blob = "\n".join(self._client.stderr_tail(40))
+            hint = _classify_oauth_failure(stderr_blob)
+            result.error = hint or self._format_error_with_stderr(
+                "turn/start timed out", exc
+            )
+            result.should_retire = True
+            return result
+
+        result.turn_id = (ts.get("turn") or {}).get("id")
+        deadline = time.monotonic() + turn_timeout
+        turn_complete = False
+        # Post-tool watchdog state. last_tool_completion_at is set whenever
+        # a tool-shaped item completes; if no further notification arrives
+        # within post_tool_quiet_timeout and the turn hasn't completed, we
+        # fast-fail and retire the session.
+        last_tool_completion_at: Optional[float] = None
+
+        while time.monotonic() < deadline and not turn_complete:
+            if self._interrupt_event.is_set():
+                self._issue_interrupt(result.turn_id)
+                result.interrupted = True
+                break
+
+            # Detect a dead subprocess between iterations. If codex exited
+            # (e.g. crashed, segfaulted, or its auth refresh thread killed
+            # the process), we won't get any more notifications — bail out
+            # rather than waiting for the full turn deadline.
+            if not self._client.is_alive():
+                stderr_blob = "\n".join(self._client.stderr_tail(60))
+                hint = _classify_oauth_failure(stderr_blob)
+                if hint is not None:
+                    result.error = hint
+                else:
+                    result.error = self._format_error_with_stderr(
+                        "codex app-server subprocess exited unexpectedly",
+                        tail_lines=20,
+                    )
+                result.should_retire = True
+                break
+
+            # Post-tool watchdog: if a tool completion was the most recent
+            # signal and codex has been silent past the quiet timeout, give
+            # up on this turn instead of waiting for the outer deadline.
+            if (
+                last_tool_completion_at is not None
+                and (time.monotonic() - last_tool_completion_at)
+                    > post_tool_quiet_timeout
+            ):
+                self._issue_interrupt(result.turn_id)
+                result.interrupted = True
+                result.error = (
+                    f"codex went silent for "
+                    f"{post_tool_quiet_timeout:.0f}s after a tool result; "
+                    f"retiring app-server session."
+                )
+                result.should_retire = True
+                break
+
+            # Drain any server-initiated requests (approvals) before
+            # reading notifications, so the codex side isn't blocked.
+            sreq = self._client.take_server_request(timeout=0)
+            if sreq is not None:
+                # Drain any pending notifications first so per-turn state
+                # (e.g. _pending_file_changes for fileChange approvals) is
+                # up to date when we make the approval decision. Bounded
+                # to avoid starving the server-request response.
+                for _ in range(8):
+                    pending = self._client.take_notification(timeout=0)
+                    if pending is None:
+                        break
+                    _apply_token_usage_notification(result, pending)
+                    self._track_pending_file_change(pending)
+                    proj = projector.project(pending)
+                    if proj.messages:
+                        result.projected_messages.extend(proj.messages)
+                    if proj.is_tool_iteration:
+                        result.tool_iterations += 1
+                        last_tool_completion_at = time.monotonic()
+                    if proj.final_text is not None:
+                        result.final_text = proj.final_text
+                        if _has_turn_aborted_marker(proj.final_text):
+                            turn_complete = True
+                            result.interrupted = True
+                            result.error = (
+                                result.error
+                                or "codex reported turn_aborted"
+                            )
+                self._handle_server_request(sreq)
+                # Activity counts as live signal — reset the post-tool
+                # quiet timer so an approval round-trip doesn't trip it.
+                last_tool_completion_at = None
+                continue
+
+            note = self._client.take_notification(
+                timeout=notification_poll_timeout
+            )
+            if note is None:
+                continue
+
+            method = note.get("method", "")
+            if self._on_event is not None:
+                try:
+                    self._on_event(note)
+                except Exception:  # pragma: no cover - display callback
+                    logger.debug("on_event callback raised", exc_info=True)
+
+            _apply_token_usage_notification(result, note)
+
+            # Track in-progress fileChange items so the approval bridge
+            # can surface a real change summary when codex requests
+            # approval (the approval params themselves don't carry the
+            # changeset). Quirk #4 fix.
+            self._track_pending_file_change(note)
+
+            # Project into messages
+            projection = projector.project(note)
+            if projection.messages:
+                result.projected_messages.extend(projection.messages)
+            if projection.is_tool_iteration:
+                result.tool_iterations += 1
+                # Arm/refresh the post-tool quiet watchdog whenever a
+                # tool-shaped item completes.
+                last_tool_completion_at = time.monotonic()
+            else:
+                # Any non-tool projected activity (assistant message,
+                # status update, etc.) means codex is still producing
+                # output — clear the quiet timer so we don't fast-fail.
+                if projection.messages or projection.final_text is not None:
+                    last_tool_completion_at = None
+            if projection.final_text is not None:
+                # Codex can emit multiple agentMessage items in one turn
+                # (e.g. partial then final). Take the last one as canonical.
+                result.final_text = projection.final_text
+                # Some codex builds tear a turn down by emitting a
+                # `<turn_aborted>` marker in the agent message text and
+                # never sending turn/completed. Treat the marker itself
+                # as terminal so we don't burn the full deadline.
+                if _has_turn_aborted_marker(projection.final_text):
+                    turn_complete = True
+                    result.interrupted = True
+                    result.error = (
+                        result.error or "codex reported turn_aborted"
+                    )
+
+            if method == "turn/completed":
+                turn_complete = True
+                turn_status = (
+                    (note.get("params") or {}).get("turn") or {}
+                ).get("status")
+                if turn_status and turn_status not in {"completed", "interrupted"}:
+                    err_obj = (
+                        (note.get("params") or {}).get("turn") or {}
+                    ).get("error")
+                    if err_obj:
+                        err_msg = _format_responses_error(err_obj, str(turn_status))
+                        # If the turn failed for an auth/refresh reason,
+                        # rewrite the error into a re-auth hint AND mark
+                        # the session for retirement.
+                        stderr_blob = "\n".join(
+                            self._client.stderr_tail(40)
+                        )
+                        hint = _classify_oauth_failure(err_msg, stderr_blob)
+                        if hint is not None:
+                            result.error = hint
+                            result.should_retire = True
+                        else:
+                            result.error = self._format_error_with_stderr(
+                                f"turn ended status={turn_status}", err_msg
+                            )
+
+        if not turn_complete and not result.interrupted:
+            # Hit the deadline. Issue interrupt to stop wasted compute, and
+            # tell the caller to retire the session — a turn that never
+            # finished is a strong sign codex is wedged in a way the next
+            # turn shouldn't inherit.
+            self._issue_interrupt(result.turn_id)
+            result.interrupted = True
+            if not result.error:
+                result.error = self._format_error_with_stderr(
+                    f"turn timed out after {turn_timeout}s"
+                )
+            result.should_retire = True
+
+        return result
+
+    # ---------- internals ----------
+
+    def _issue_interrupt(self, turn_id: Optional[str]) -> None:
+        if self._client is None or self._thread_id is None or turn_id is None:
+            return
+        try:
+            self._client.request(
+                "turn/interrupt",
+                {"threadId": self._thread_id, "turnId": turn_id},
+                timeout=5,
+            )
+        except CodexAppServerError as exc:
+            # "no active turn to interrupt" is fine — already done.
+            logger.debug("turn/interrupt non-fatal: %s", exc)
+        except TimeoutError:
+            logger.warning("turn/interrupt timed out")
+
+    def _handle_server_request(self, req: dict) -> None:
+        """Translate a codex server request (approval) into Hermes' approval
+        flow, then send the response.
+
+        Method names verified live against codex 0.130.0 (Apr 2026):
+          item/commandExecution/requestApproval — exec approvals
+          item/fileChange/requestApproval       — apply_patch approvals
+          item/permissions/requestApproval      — permissions changes
+                                                  (we decline; user controls
+                                                  permission profile in
+                                                  ~/.codex/config.toml).
+        """
+        if self._client is None:
+            return
+        method = req.get("method", "")
+        rid = req.get("id")
+        params = req.get("params") or {}
+
+        if method == "item/commandExecution/requestApproval":
+            decision = self._decide_exec_approval(params)
+            self._client.respond(rid, {"decision": decision})
+        elif method == "item/fileChange/requestApproval":
+            decision = self._decide_apply_patch_approval(params)
+            self._client.respond(rid, {"decision": decision})
+        elif method == "item/permissions/requestApproval":
+            # Codex sometimes asks to escalate permissions mid-turn. We
+            # always decline — the user already chose their permission
+            # profile in ~/.codex/config.toml and surprise escalations
+            # shouldn't be silently accepted.
+            self._client.respond(rid, {"decision": "decline"})
+        elif method == "mcpServer/elicitation/request":
+            # Codex's MCP layer asks the user for structured input on
+            # behalf of an MCP server (e.g. tool-call confirmation,
+            # OAuth, form data). For our own hermes-tools callback we
+            # auto-accept — the user already approved Hermes' tools
+            # by enabling the runtime, and we never expose anything
+            # codex's built-in shell can't already do. For other MCP
+            # servers we decline so the user explicitly opts in via
+            # codex's own auth flow.
+            server_name = params.get("serverName") or ""
+            if server_name == "hermes-tools":
+                self._client.respond(
+                    rid,
+                    {"action": "accept", "content": None, "_meta": None},
+                )
+            else:
+                self._client.respond(
+                    rid,
+                    {"action": "decline", "content": None, "_meta": None},
+                )
+        else:
+            # Unknown server request — codex can extend this surface. Reject
+            # cleanly so codex doesn't hang waiting for us.
+            logger.warning("Unknown codex server request: %s", method)
+            self._client.respond_error(
+                rid, code=-32601, message=f"Unsupported method: {method}"
+            )
+
+    def _decide_exec_approval(self, params: dict) -> str:
+        if self._routing.auto_approve_exec:
+            return "accept"
+        command = params.get("command") or ""
+        # Codex's CommandExecutionRequestApprovalParams has cwd as Optional —
+        # fall back to the session's cwd when codex doesn't include it so the
+        # approval prompt is never empty (quirk #10 fix).
+        cwd = params.get("cwd") or self._cwd or "<unknown>"
+        reason = params.get("reason")
+        description = f"Codex requests exec in {cwd}"
+        if reason:
+            description += f" — {reason}"
+        if self._approval_callback is not None:
+            try:
+                choice = self._approval_callback(
+                    command, description, allow_permanent=False
+                )
+                return _approval_choice_to_codex_decision(choice)
+            except Exception:
+                logger.exception("approval_callback raised on exec request")
+                return "decline"
+        return "decline"  # fail-closed when no callback wired
+
+    def _decide_apply_patch_approval(self, params: dict) -> str:
+        if self._routing.auto_approve_apply_patch:
+            return "accept"
+        if self._approval_callback is not None:
+            # FileChangeRequestApprovalParams gives us reason + grantRoot.
+            # The actual changeset lives on the corresponding fileChange
+            # item which the projector has already cached for us — look it
+            # up by item_id so the user sees what's actually changing.
+            reason = params.get("reason")
+            grant_root = params.get("grantRoot")
+            item_id = params.get("itemId") or ""
+            change_summary = self._lookup_pending_file_change(item_id)
+            description_parts = []
+            if reason:
+                description_parts.append(reason)
+            if change_summary:
+                description_parts.append(change_summary)
+            if grant_root:
+                description_parts.append(f"grants write to {grant_root}")
+            description = (
+                "; ".join(description_parts)
+                if description_parts
+                else "Codex requests to apply a patch"
+            )
+            command_label = (
+                f"apply_patch: {change_summary}" if change_summary
+                else f"apply_patch: {reason}" if reason
+                else "apply_patch"
+            )
+            try:
+                choice = self._approval_callback(
+                    command_label,
+                    description,
+                    allow_permanent=False,
+                )
+                return _approval_choice_to_codex_decision(choice)
+            except Exception:
+                logger.exception("approval_callback raised on apply_patch")
+                return "decline"
+        return "decline"
+
+    def _track_pending_file_change(self, note: dict) -> None:
+        """Maintain self._pending_file_changes from item/started + item/completed
+        notifications. Lets the apply_patch approval prompt show what's
+        actually changing — codex's approval params don't carry the data."""
+        method = note.get("method", "")
+        params = note.get("params") or {}
+        item = params.get("item") or {}
+        if item.get("type") != "fileChange":
+            return
+        item_id = item.get("id") or ""
+        if not item_id:
+            return
+        if method == "item/started":
+            changes = item.get("changes") or []
+            if not changes:
+                self._pending_file_changes[item_id] = "1 change pending"
+                return
+            kinds: dict[str, int] = {}
+            paths: list[str] = []
+            for ch in changes:
+                if not isinstance(ch, dict):
+                    continue
+                kind = (ch.get("kind") or {}).get("type") or "update"
+                kinds[kind] = kinds.get(kind, 0) + 1
+                p = ch.get("path") or ""
+                if p:
+                    paths.append(p)
+            counts = ", ".join(f"{n} {k}" for k, n in sorted(kinds.items()))
+            preview = ", ".join(paths[:3])
+            if len(paths) > 3:
+                preview += f", +{len(paths) - 3} more"
+            self._pending_file_changes[item_id] = (
+                f"{counts}: {preview}" if preview else counts
+            )
+        elif method == "item/completed":
+            self._pending_file_changes.pop(item_id, None)
+
+    def _lookup_pending_file_change(self, item_id: str) -> Optional[str]:
+        """Look up an in-progress fileChange item by id and summarize its
+        changes for the approval prompt. Returns None when we don't have
+        the item cached (e.g. approval arrived before item/started, or
+        fileChange item content not tracked yet)."""
+        if not item_id:
+            return None
+        cached = self._pending_file_changes.get(item_id)
+        if not cached:
+            return None
+        return cached
+
+
+def _apply_token_usage_notification(result: TurnResult, note: dict) -> None:
+    """Capture Codex app-server token usage updates for caller accounting.
+
+    Codex does not put token usage on turn/completed. It emits a separate
+    thread/tokenUsage/updated notification containing cumulative totals and
+    the latest turn breakdown.
+    """
+    if not isinstance(note, dict) or note.get("method") != "thread/tokenUsage/updated":
+        return
+    params = note.get("params") or {}
+    token_usage = params.get("tokenUsage") or {}
+    if not isinstance(token_usage, dict):
+        return
+    last = token_usage.get("last")
+    total = token_usage.get("total")
+    if isinstance(last, dict):
+        result.token_usage_last = dict(last)
+    if isinstance(total, dict):
+        result.token_usage_total = dict(total)
+    window = token_usage.get("modelContextWindow")
+    if isinstance(window, int) and window > 0:
+        result.model_context_window = window
+
+
+def _approval_choice_to_codex_decision(choice: str) -> str:
+    """Map Hermes approval choices onto codex's CommandExecutionApprovalDecision
+    / FileChangeApprovalDecision wire values.
+
+    Hermes returns 'once', 'session', 'always', or 'deny'.
+    Codex expects 'accept', 'acceptForSession', 'decline', or 'cancel'
+    (verified against codex-rs/app-server-protocol/src/protocol/v2/item.rs
+    on codex 0.130.0).
+    """
+    if choice in {"once",}:
+        return "accept"
+    if choice in {"session", "always"}:
+        return "acceptForSession"
+    return "decline"
+
+
+def _has_turn_aborted_marker(text: str) -> bool:
+    """Return True if `text` contains any of the raw markers codex uses
+    to signal a turn was aborted without emitting `turn/completed`.
+
+    Codex emits `<turn_aborted>` (and sometimes `<turn_aborted/>`) as raw
+    text inside agentMessage items when an interrupt or upstream error
+    tears the turn down before the normal completion path fires. Mirrors
+    openclaw beta.8's terminal-marker fix so we don't burn the full turn
+    deadline waiting for a turn/completed that never comes.
+    """
+    if not text:
+        return False
+    for marker in _TURN_ABORTED_MARKERS:
+        if marker in text:
+            return True
+    return False
+
+
+def _get_hermes_version() -> str:
+    """Best-effort Hermes version string for codex's userAgent line."""
+    try:
+        from importlib.metadata import version
+
+        return version("hermes-agent")
+    except Exception:  # pragma: no cover
+        return "0.0.0"

agent/transports/codex_event_projector.py

@@ -0,0 +1,312 @@
+"""Projects codex app-server events into Hermes' messages list.
+
+The translator that lets Hermes' memory/skill review keep working under the
+Codex runtime: it converts Codex `item/*` notifications into the standard
+OpenAI-shaped `{role, content, tool_calls, tool_call_id}` entries that
+`agent/curator.py` already knows how to read.
+
+Codex emits items with a discriminator field `type`:
+  - userMessage         → {role: "user", content}
+  - agentMessage        → {role: "assistant", content}
+  - reasoning           → stashed in the assistant's "reasoning" field
+  - commandExecution    → assistant tool_call(name="exec") + tool result
+  - fileChange          → assistant tool_call(name="apply_patch") + tool result
+  - mcpToolCall         → assistant tool_call(name=f"mcp.{server}.{tool}") + tool result
+  - dynamicToolCall     → assistant tool_call(name=tool) + tool result
+  - plan/hookPrompt/collabAgentToolCall → recorded as opaque assistant notes
+
+Each item maps to AT MOST one assistant entry + one tool entry, preserving
+Hermes' message-alternation invariants (system → user → assistant → user/tool
+→ assistant → ...). Multiple Codex tool calls within one Codex turn produce
+multiple consecutive (assistant, tool) pairs, which is the same shape Hermes
+already produces for parallel tool calls.
+
+Counters tracked alongside projection:
+  - tool_iterations: ticks once per completed tool-shaped item. Used by
+    AIAgent._iters_since_skill (skill nudge gate, default threshold 10).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+
+def _deterministic_call_id(item_type: str, item_id: str) -> str:
+    """Stable id for tool_call message correlation.
+
+    Uses the codex item id directly when present (already a uuid); falls back
+    to a content hash so replay produces the same id across sessions and
+    prefix caches stay valid. See AGENTS.md Pitfall #16 (deterministic IDs in
+    tool call history)."""
+    if item_id:
+        return f"codex_{item_type}_{item_id}"
+    digest = hashlib.sha256(f"{item_type}".encode()).hexdigest()[:16]
+    return f"codex_{item_type}_{digest}"
+
+
+def _format_tool_args(d: dict) -> str:
+    """Format a dict as JSON the way Hermes' existing tool_calls path does."""
+    return json.dumps(d, ensure_ascii=False, sort_keys=True)
+
+
+@dataclass
+class ProjectionResult:
+    """Output of projecting one Codex item.
+
+    `messages` is a list because some Codex items produce two messages
+    (assistant tool_call + tool result). Empty list = item ignored (e.g. a
+    streaming `outputDelta` that doesn't materialize into messages until the
+    `item/completed` event)."""
+
+    messages: list[dict] = field(default_factory=list)
+    is_tool_iteration: bool = False
+    final_text: Optional[str] = None  # Set when an agentMessage completes
+
+
+class CodexEventProjector:
+    """Stateful projector consuming Codex notifications in arrival order.
+
+    Owns the in-progress reasoning content (codex emits reasoning as separate
+    items but Hermes stashes it on the next assistant message)."""
+
+    def __init__(self) -> None:
+        self._pending_reasoning: list[str] = []
+
+    def project(self, notification: dict) -> ProjectionResult:
+        """Project a single notification. Idempotent for non-completion events;
+        only `item/completed` and `turn/completed` materialize messages."""
+        method = notification.get("method", "")
+        params = notification.get("params", {}) or {}
+
+        # We only materialize messages on `item/completed`. Streaming deltas
+        # (`item/<type>/outputDelta`, `item/<type>/delta`) are display-only and
+        # don't enter the messages list — same way Hermes already only writes
+        # the assistant message after the streaming completion event.
+        if method != "item/completed":
+            return ProjectionResult()
+
+        item = params.get("item") or {}
+        item_type = item.get("type") or ""
+        item_id = item.get("id") or ""
+
+        if item_type == "agentMessage":
+            return self._project_agent_message(item)
+        if item_type == "reasoning":
+            self._pending_reasoning.extend(item.get("summary") or [])
+            self._pending_reasoning.extend(item.get("content") or [])
+            return ProjectionResult()
+        if item_type == "commandExecution":
+            return self._project_command(item, item_id)
+        if item_type == "fileChange":
+            return self._project_file_change(item, item_id)
+        if item_type == "mcpToolCall":
+            return self._project_mcp_tool_call(item, item_id)
+        if item_type == "dynamicToolCall":
+            return self._project_dynamic_tool_call(item, item_id)
+        if item_type == "userMessage":
+            return self._project_user_message(item)
+
+        # Unknown / rare items (plan, hookPrompt, collabAgentToolCall, etc.)
+        # — record as opaque assistant note so memory review can still see
+        # *something* happened, but don't fabricate tool_call structure.
+        return self._project_opaque(item, item_type)
+
+    # ---------- per-type projections ----------
+
+    def _project_agent_message(self, item: dict) -> ProjectionResult:
+        text = item.get("text") or ""
+        msg: dict[str, Any] = {"role": "assistant", "content": text}
+        if self._pending_reasoning:
+            msg["reasoning"] = "\n".join(self._pending_reasoning)
+            self._pending_reasoning = []
+        return ProjectionResult(messages=[msg], final_text=text)
+
+    def _project_user_message(self, item: dict) -> ProjectionResult:
+        # codex's userMessage content is a list of UserInput variants. For
+        # projection purposes we flatten any text fragments and ignore
+        # non-text parts (images, etc.) — Hermes' messages store text only.
+        text_parts: list[str] = []
+        for fragment in item.get("content") or []:
+            if isinstance(fragment, dict):
+                if fragment.get("type") == "text":
+                    text_parts.append(fragment.get("text") or "")
+                elif "text" in fragment:
+                    text_parts.append(str(fragment["text"]))
+        return ProjectionResult(
+            messages=[{"role": "user", "content": "\n".join(text_parts)}]
+        )
+
+    def _project_command(self, item: dict, item_id: str) -> ProjectionResult:
+        call_id = _deterministic_call_id("exec", item_id)
+        args = {
+            "command": item.get("command") or "",
+            "cwd": item.get("cwd") or "",
+        }
+        assistant_msg = {
+            "role": "assistant",
+            "content": None,
+            "tool_calls": [
+                {
+                    "id": call_id,
+                    "type": "function",
+                    "function": {
+                        "name": "exec_command",
+                        "arguments": _format_tool_args(args),
+                    },
+                }
+            ],
+        }
+        if self._pending_reasoning:
+            assistant_msg["reasoning"] = "\n".join(self._pending_reasoning)
+            self._pending_reasoning = []
+        output = item.get("aggregatedOutput") or ""
+        exit_code = item.get("exitCode")
+        if exit_code is not None and exit_code != 0:
+            output = f"[exit {exit_code}]\n{output}"
+        tool_msg = {
+            "role": "tool",
+            "tool_call_id": call_id,
+            "content": output,
+        }
+        return ProjectionResult(
+            messages=[assistant_msg, tool_msg], is_tool_iteration=True
+        )
+
+    def _project_file_change(self, item: dict, item_id: str) -> ProjectionResult:
+        call_id = _deterministic_call_id("apply_patch", item_id)
+        # Reduce the codex changes array to a digest the agent loop will
+        # find readable. We record per-file change kinds (Add/Update/Delete)
+        # without inlining full file contents — those can be huge.
+        changes_summary = []
+        for change in item.get("changes") or []:
+            kind = (change.get("kind") or {}).get("type") or "update"
+            path = change.get("path") or ""
+            changes_summary.append({"kind": kind, "path": path})
+        args = {"changes": changes_summary}
+        assistant_msg = {
+            "role": "assistant",
+            "content": None,
+            "tool_calls": [
+                {
+                    "id": call_id,
+                    "type": "function",
+                    "function": {
+                        "name": "apply_patch",
+                        "arguments": _format_tool_args(args),
+                    },
+                }
+            ],
+        }
+        if self._pending_reasoning:
+            assistant_msg["reasoning"] = "\n".join(self._pending_reasoning)
+            self._pending_reasoning = []
+        status = item.get("status") or "unknown"
+        n = len(changes_summary)
+        tool_msg = {
+            "role": "tool",
+            "tool_call_id": call_id,
+            "content": f"apply_patch status={status}, {n} change(s)",
+        }
+        return ProjectionResult(
+            messages=[assistant_msg, tool_msg], is_tool_iteration=True
+        )
+
+    def _project_mcp_tool_call(self, item: dict, item_id: str) -> ProjectionResult:
+        server = item.get("server") or "mcp"
+        tool = item.get("tool") or "unknown"
+        call_id = _deterministic_call_id(f"mcp_{server}_{tool}", item_id)
+        args = item.get("arguments") or {}
+        if not isinstance(args, dict):
+            args = {"arguments": args}
+        assistant_msg = {
+            "role": "assistant",
+            "content": None,
+            "tool_calls": [
+                {
+                    "id": call_id,
+                    "type": "function",
+                    "function": {
+                        "name": f"mcp.{server}.{tool}",
+                        "arguments": _format_tool_args(args),
+                    },
+                }
+            ],
+        }
+        if self._pending_reasoning:
+            assistant_msg["reasoning"] = "\n".join(self._pending_reasoning)
+            self._pending_reasoning = []
+        result = item.get("result")
+        error = item.get("error")
+        if error:
+            content = f"[error] {json.dumps(error, ensure_ascii=False)[:1000]}"
+        elif result is not None:
+            content = json.dumps(result, ensure_ascii=False)[:4000]
+        else:
+            content = ""
+        tool_msg = {
+            "role": "tool",
+            "tool_call_id": call_id,
+            "content": content,
+        }
+        return ProjectionResult(
+            messages=[assistant_msg, tool_msg], is_tool_iteration=True
+        )
+
+    def _project_dynamic_tool_call(
+        self, item: dict, item_id: str
+    ) -> ProjectionResult:
+        tool = item.get("tool") or "unknown"
+        call_id = _deterministic_call_id(f"dyn_{tool}", item_id)
+        args = item.get("arguments") or {}
+        if not isinstance(args, dict):
+            args = {"arguments": args}
+        assistant_msg = {
+            "role": "assistant",
+            "content": None,
+            "tool_calls": [
+                {
+                    "id": call_id,
+                    "type": "function",
+                    "function": {
+                        "name": tool,
+                        "arguments": _format_tool_args(args),
+                    },
+                }
+            ],
+        }
+        if self._pending_reasoning:
+            assistant_msg["reasoning"] = "\n".join(self._pending_reasoning)
+            self._pending_reasoning = []
+        content_items = item.get("contentItems") or []
+        if isinstance(content_items, list) and content_items:
+            content = json.dumps(content_items, ensure_ascii=False)[:4000]
+        else:
+            success = item.get("success")
+            content = f"success={success}"
+        tool_msg = {
+            "role": "tool",
+            "tool_call_id": call_id,
+            "content": content,
+        }
+        return ProjectionResult(
+            messages=[assistant_msg, tool_msg], is_tool_iteration=True
+        )
+
+    def _project_opaque(self, item: dict, item_type: str) -> ProjectionResult:
+        # Record the existence of the item without inventing tool_calls.
+        # Memory review will see this and may or may not save anything.
+        try:
+            payload = json.dumps(item, ensure_ascii=False)[:1500]
+        except (TypeError, ValueError):
+            payload = repr(item)[:1500]
+        return ProjectionResult(
+            messages=[
+                {
+                    "role": "assistant",
+                    "content": f"[codex {item_type}] {payload}",
+                }
+            ]
+        )

agent/transports/hermes_tools_mcp_server.py

@@ -0,0 +1,233 @@
+"""Hermes-tools-as-MCP server for the codex_app_server runtime.
+
+When the user runs `openai/*` turns through the codex app-server, codex
+owns the loop and builds its own tool list. By default, that means
+Hermes' richer tool surface — web search, browser automation,
+delegate_task subagents, vision analysis, persistent memory, skills,
+cross-session search, image generation, TTS — is unreachable.
+
+This module exposes a curated subset of those Hermes tools to the
+spawned codex subprocess via stdio MCP. Codex registers it as a normal
+MCP server (per `~/.codex/config.toml [mcp_servers.hermes-tools]`) and
+the user gets full Hermes capability inside a Codex turn.
+
+Scope (what we expose):
+  - web_search, web_extract              — Firecrawl, no codex equivalent
+  - browser_navigate / _click / _type /  — Camofox/Browserbase automation
+    _snapshot / _scroll / _back / _press /
+    _get_images / _console / _vision
+  - vision_analyze                       — image inspection by vision model
+  - image_generate                       — image generation
+  - skill_view, skills_list              — Hermes' skill library
+  - text_to_speech                       — TTS
+  - kanban_* (complete/block/comment/    — kanban worker + orchestrator
+    heartbeat/show/list/create/            handoff (stateless: read env var,
+    unblock/link)                          write ~/.hermes/kanban.db)
+
+What we DO NOT expose:
+  - terminal / shell                     — codex's own shell tool
+  - read_file / write_file / patch       — codex's apply_patch + shell
+  - search_files / process               — codex's shell
+  - clarify                              — codex's own UX
+  - delegate_task / memory /             — `_AGENT_LOOP_TOOLS` in Hermes
+    session_search / todo                  (model_tools.py). They require
+                                           the running AIAgent context to
+                                           dispatch (mid-loop state), so a
+                                           stateless MCP callback can't
+                                           drive them. See the inline
+                                           comment on EXPOSED_TOOLS below.
+
+Run with: python -m agent.transports.hermes_tools_mcp_server
+Spawned by: CodexAppServerSession.ensure_started() when the runtime is
+            active and config opts in.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+
+# Tools we expose. Each name MUST match a registered Hermes tool that
+# `model_tools.handle_function_call()` can dispatch.
+#
+# What we deliberately DO NOT expose:
+#   - terminal / shell / read_file / write_file / patch / search_files /
+#     process — codex's built-ins cover these and approval routes through
+#     codex's own UI.
+#   - delegate_task / memory / session_search / todo — these are
+#     `_AGENT_LOOP_TOOLS` in Hermes (model_tools.py:493). They require
+#     the running AIAgent context to dispatch (mid-loop state), so a
+#     stateless MCP callback can't drive them. Hermes' default runtime
+#     keeps these working; the codex_app_server runtime cannot.
+EXPOSED_TOOLS: tuple[str, ...] = (
+    "web_search",
+    "web_extract",
+    "browser_navigate",
+    "browser_click",
+    "browser_type",
+    "browser_press",
+    "browser_snapshot",
+    "browser_scroll",
+    "browser_back",
+    "browser_get_images",
+    "browser_console",
+    "browser_vision",
+    "vision_analyze",
+    "image_generate",
+    "skill_view",
+    "skills_list",
+    "text_to_speech",
+    # Kanban worker handoff tools — gated on HERMES_KANBAN_TASK env var
+    # (set by the kanban dispatcher when spawning a worker). Without these
+    # in the callback, a worker spawned with openai_runtime=codex_app_server
+    # could do the work but couldn't report completion back to the kernel,
+    # making it hang until timeout. Stateless dispatch — they just read
+    # the env var and write to ~/.hermes/kanban.db.
+    "kanban_complete",
+    "kanban_block",
+    "kanban_comment",
+    "kanban_heartbeat",
+    "kanban_show",
+    "kanban_list",
+    # NOTE: kanban_create / kanban_unblock / kanban_link are orchestrator-
+    # only — the kanban tool gates them on HERMES_KANBAN_TASK being unset.
+    # They're exposed here for orchestrator agents running on the codex
+    # runtime that need to dispatch new tasks.
+    "kanban_create",
+    "kanban_unblock",
+    "kanban_link",
+)
+
+
+def _build_server() -> Any:
+    """Create the FastMCP server with Hermes tools attached. Lazy imports
+    so the module can be imported without the mcp package installed
+    (we degrade to a clear error only when actually run)."""
+    try:
+        from mcp.server.fastmcp import FastMCP
+    except ImportError as exc:  # pragma: no cover - install hint
+        raise ImportError(
+            f"hermes-tools MCP server requires the 'mcp' package: {exc}"
+        ) from exc
+
+    # Discover Hermes tools so dispatch works.
+    from model_tools import (
+        get_tool_definitions,
+        handle_function_call,
+    )
+
+    mcp = FastMCP(
+        "hermes-tools",
+        instructions=(
+            "Hermes Agent's tool surface, exposed for use inside a Codex "
+            "session. Use these for capabilities Codex's built-in toolset "
+            "doesn't cover: web search/extract, browser automation, "
+            "subagent delegation, vision, image generation, persistent "
+            "memory, skills, and cross-session search."
+        ),
+    )
+
+    # Pull authoritative Hermes tool schemas for the ones we expose, so
+    # MCP clients see the same parameter docs Hermes gives the model.
+    all_defs = {
+        td["function"]["name"]: td["function"]
+        for td in (get_tool_definitions(quiet_mode=True) or [])
+        if isinstance(td, dict) and td.get("type") == "function"
+    }
+
+    exposed_count = 0
+
+    for name in EXPOSED_TOOLS:
+        spec = all_defs.get(name)
+        if spec is None:
+            logger.debug(
+                "skipping %s — not registered in this Hermes process", name
+            )
+            continue
+
+        description = spec.get("description") or f"Hermes {name} tool"
+        params_schema = spec.get("parameters") or {"type": "object", "properties": {}}
+
+        # FastMCP wants a Python callable. Build a closure that takes the
+        # arguments dict, dispatches via handle_function_call, and returns
+        # the result string. We use add_tool() for full control over the
+        # input schema (FastMCP's @tool() decorator inspects type hints,
+        # which we can't get from a JSON schema at runtime).
+        def _make_handler(tool_name: str):
+            def _dispatch(**kwargs: Any) -> str:
+                try:
+                    return handle_function_call(tool_name, kwargs or {})
+                except Exception as exc:
+                    logger.exception("tool %s raised", tool_name)
+                    return json.dumps({"error": str(exc), "tool": tool_name})
+            _dispatch.__name__ = tool_name
+            _dispatch.__doc__ = description
+            return _dispatch
+
+        try:
+            mcp.add_tool(
+                _make_handler(name),
+                name=name,
+                description=description,
+                # FastMCP accepts JSON schema directly via the
+                # input_schema parameter on newer versions; older
+                # versions use parameters_schema. Try both for compat.
+            )
+        except TypeError:
+            # Older mcp SDK signature — fall back to decorator-style.
+            handler = _make_handler(name)
+            handler = mcp.tool(name=name, description=description)(handler)
+
+        exposed_count += 1
+
+    logger.info(
+        "hermes-tools MCP server registered %d/%d tools",
+        exposed_count,
+        len(EXPOSED_TOOLS),
+    )
+    return mcp
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    """Entry point for `python -m agent.transports.hermes_tools_mcp_server`."""
+    argv = argv or sys.argv[1:]
+    verbose = "--verbose" in argv or "-v" in argv
+
+    log_level = logging.INFO if verbose else logging.WARNING
+    logging.basicConfig(
+        level=log_level,
+        stream=sys.stderr,  # MCP uses stdio for protocol — logs MUST go to stderr
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    )
+
+    # Quiet mode: keep Hermes' own banners off stdout (which is the MCP wire).
+    os.environ.setdefault("HERMES_QUIET", "1")
+    os.environ.setdefault("HERMES_REDACT_SECRETS", "true")
+
+    try:
+        server = _build_server()
+    except ImportError as exc:
+        sys.stderr.write(f"hermes-tools MCP server cannot start: {exc}\n")
+        return 2
+
+    # FastMCP runs with stdio transport by default when launched as a
+    # subprocess.
+    try:
+        server.run()
+    except KeyboardInterrupt:
+        return 0
+    except Exception as exc:
+        logger.exception("hermes-tools MCP server crashed")
+        sys.stderr.write(f"hermes-tools MCP server error: {exc}\n")
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agent/transports/types.py

@@ -0,0 +1,174 @@
+"""Shared types for normalized provider responses.
+
+These dataclasses define the canonical shape that all provider adapters
+normalize responses to.  The shared surface is intentionally minimal —
+only fields that every downstream consumer reads are top-level.
+Protocol-specific state goes in ``provider_data`` dicts (response-level
+and per-tool-call) so that protocol-aware code paths can access it
+without polluting the shared type.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ToolCall:
+    """A normalized tool call from any provider.
+
+    ``id`` is the protocol's canonical identifier — what gets used in
+    ``tool_call_id`` / ``tool_use_id`` when constructing tool result
+    messages.  May be ``None`` when the provider omits it; the agent
+    fills it via ``_deterministic_call_id()`` before storing in history.
+
+    ``provider_data`` carries per-tool-call protocol metadata that only
+    protocol-aware code reads:
+
+    * Codex: ``{"call_id": "call_XXX", "response_item_id": "fc_XXX"}``
+    * Gemini: ``{"extra_content": {"google": {"thought_signature": "..."}}}``
+    * Others: ``None``
+    """
+
+    id: str | None
+    name: str
+    arguments: str  # JSON string
+    provider_data: dict[str, Any] | None = field(default=None, repr=False)
+
+    # ── Backward compatibility ──────────────────────────────────
+    # The agent loop reads tc.function.name / tc.function.arguments
+    # throughout run_agent.py (45+ sites).  These properties let
+    # NormalizedResponse pass through without the _nr_to_assistant_message
+    # shim, while keeping ToolCall's canonical fields flat.
+    @property
+    def type(self) -> str:
+        return "function"
+
+    @property
+    def function(self) -> ToolCall:
+        """Return self so tc.function.name / tc.function.arguments work."""
+        return self
+
+    @property
+    def call_id(self) -> str | None:
+        """Codex call_id from provider_data, accessed via getattr by _build_assistant_message."""
+        return (self.provider_data or {}).get("call_id")
+
+    @property
+    def response_item_id(self) -> str | None:
+        """Codex response_item_id from provider_data."""
+        return (self.provider_data or {}).get("response_item_id")
+
+    @property
+    def extra_content(self) -> dict[str, Any] | None:
+        """Gemini extra_content (thought_signature) from provider_data.
+
+        Gemini 3 thinking models attach ``extra_content`` with a
+        ``thought_signature`` to each tool call.  This signature must be
+        replayed on subsequent API calls — without it the API rejects the
+        request with HTTP 400.  The chat_completions transport stores this
+        in ``provider_data["extra_content"]``; this property exposes it so
+        ``_build_assistant_message`` can ``getattr(tc, "extra_content")``
+        uniformly.
+        """
+        return (self.provider_data or {}).get("extra_content")
+
+
+@dataclass
+class Usage:
+    """Token usage from an API response."""
+
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    total_tokens: int = 0
+    cached_tokens: int = 0
+
+
+@dataclass
+class NormalizedResponse:
+    """Normalized API response from any provider.
+
+    Shared fields are truly cross-provider — every caller can rely on
+    them without branching on api_mode.  Protocol-specific state goes in
+    ``provider_data`` so that only protocol-aware code paths read it.
+
+    Response-level ``provider_data`` examples:
+
+    * Anthropic: ``{"reasoning_details": [...]}``
+    * Codex: ``{"codex_reasoning_items": [...], "codex_message_items": [...]}``
+    * Others: ``None``
+    """
+
+    content: str | None
+    tool_calls: list[ToolCall] | None
+    finish_reason: str  # "stop", "tool_calls", "length", "content_filter"
+    reasoning: str | None = None
+    usage: Usage | None = None
+    provider_data: dict[str, Any] | None = field(default=None, repr=False)
+
+    # ── Backward compatibility ──────────────────────────────────
+    # The shim _nr_to_assistant_message() mapped these from provider_data.
+    # These properties let NormalizedResponse pass through directly.
+    @property
+    def reasoning_content(self) -> str | None:
+        pd = self.provider_data or {}
+        return pd.get("reasoning_content")
+
+    @property
+    def reasoning_details(self):
+        pd = self.provider_data or {}
+        return pd.get("reasoning_details")
+
+    @property
+    def anthropic_content_blocks(self):
+        """Verbatim, order-preserving Anthropic content blocks for a turn.
+
+        Present only when an Anthropic turn interleaves signed thinking with
+        tool_use — the one shape the parallel reasoning_details + tool_calls
+        lists reconstruct in the wrong order, invalidating thinking-block
+        signatures on replay. See agent/transports/anthropic.py.
+        """
+        pd = self.provider_data or {}
+        return pd.get("anthropic_content_blocks")
+
+    @property
+    def codex_reasoning_items(self):
+        pd = self.provider_data or {}
+        return pd.get("codex_reasoning_items")
+
+    @property
+    def codex_message_items(self):
+        pd = self.provider_data or {}
+        return pd.get("codex_message_items")
+
+
+# ---------------------------------------------------------------------------
+# Factory helpers
+# ---------------------------------------------------------------------------
+
+
+def build_tool_call(
+    id: str | None,
+    name: str,
+    arguments: Any,
+    **provider_fields: Any,
+) -> ToolCall:
+    """Build a ``ToolCall``, auto-serialising *arguments* if it's a dict.
+
+    Any extra keyword arguments are collected into ``provider_data``.
+    """
+    args_str = json.dumps(arguments) if isinstance(arguments, dict) else str(arguments)
+    pd = dict(provider_fields) if provider_fields else None
+    return ToolCall(id=id, name=name, arguments=args_str, provider_data=pd)
+
+
+def map_finish_reason(reason: str | None, mapping: dict[str, str]) -> str:
+    """Translate a provider-specific stop reason to the normalised set.
+
+    Falls back to ``"stop"`` for unknown or ``None`` reasons.
+    """
+    if reason is None:
+        return "stop"
+    return mapping.get(reason, "stop")