feat(plugins): add optional-plugins/ discovery + langfuse_tracing as first official optional plugin

Introduces optional-plugins/ — a new category for plugins that ship with
the repo but are NOT auto-discovered. They live alongside the code but only
land in ~/.hermes/plugins/ (and thus get loaded) when the user explicitly
installs them.

Core changes:
- optional-plugins/observability/langfuse-tracing/ — langfuse tracing plugin
  (pre/post LLM + tool hooks, usage/cost normalization, fail-open when SDK
  missing). NOT in plugins/ so zero import overhead on devices that don't
  want it.
- hermes_cli/plugins_cmd.py — official install path: _resolve_official_plugin()
  recognises 'official/<category>/<name>' identifiers and copies from
  optional-plugins/ into ~/.hermes/plugins/ (no git clone, no network).
  _list_official_plugins() enumerates available optional plugins.
  cmd_list(available=True) shows not-yet-installed official plugins.
- hermes_cli/main.py — hermes plugins list --available flag
- hermes_cli/tools_config.py — Langfuse Observability in TOOL_CATEGORIES;
  post_setup handler installs the langfuse SDK and runs cmd_install()
- hermes_cli/config.py — Langfuse credentials in OPTIONAL_ENV_VARS;
  optional tuning keys in _EXTRA_ENV_KEYS

User flows:
  hermes plugins install official/observability/langfuse-tracing
  hermes plugins list --available
  hermes tools  (-> Langfuse Observability -> credentials -> auto-installs)

Closes #15764

acp_adapter/copilot_client.py

@@ -1,632 +0,0 @@
-"""OpenAI-compatible shim that forwards Hermes requests to `copilot --acp`.
-
-This adapter lets Hermes treat the GitHub Copilot ACP server as a chat-style
-backend. Each request starts a short-lived ACP session, sends the formatted
-conversation as a single prompt, collects text chunks, and converts the result
-back into the minimal shape Hermes expects from an OpenAI client.
-"""
-
-from __future__ import annotations
-
-import json
-import os
-import queue
-import re
-import shlex
-import subprocess
-import threading
-import time
-from collections import deque
-from pathlib import Path
-from types import SimpleNamespace
-from typing import Any
-
-from agent.file_safety import get_read_block_error, is_write_denied
-from agent.redact import redact_sensitive_text
-
-ACP_MARKER_BASE_URL = "acp://copilot"
-_DEFAULT_TIMEOUT_SECONDS = 900.0
-
-_TOOL_CALL_BLOCK_RE = re.compile(r"<tool_call>\s*(\{.*?\})\s*</tool_call>", re.DOTALL)
-_TOOL_CALL_JSON_RE = re.compile(
-    r"\{\s*\"id\"\s*:\s*\"[^\"]+\"\s*,\s*\"type\"\s*:\s*\"function\"\s*,\s*\"function\"\s*:\s*\{.*?\}\s*\}",
-    re.DOTALL,
-)
-
-
-def _resolve_command() -> str:
-    return (
-        os.getenv("HERMES_COPILOT_ACP_COMMAND", "").strip()
-        or os.getenv("COPILOT_CLI_PATH", "").strip()
-        or "copilot"
-    )
-
-
-def _resolve_args() -> list[str]:
-    raw = os.getenv("HERMES_COPILOT_ACP_ARGS", "").strip()
-    if not raw:
-        return ["--acp", "--stdio"]
-    return shlex.split(raw)
-
-
-def _jsonrpc_error(message_id: Any, code: int, message: str) -> dict[str, Any]:
-    return {
-        "jsonrpc": "2.0",
-        "id": message_id,
-        "error": {
-            "code": code,
-            "message": message,
-        },
-    }
-
-
-def _permission_denied(message_id: Any) -> dict[str, Any]:
-    return {
-        "jsonrpc": "2.0",
-        "id": message_id,
-        "result": {
-            "outcome": {
-                "outcome": "cancelled",
-            }
-        },
-    }
-
-
-def _format_messages_as_prompt(
-    messages: list[dict[str, Any]],
-    model: str | None = None,
-    tools: list[dict[str, Any]] | None = None,
-    tool_choice: Any = None,
-) -> str:
-    sections: list[str] = [
-        "You are being used as the active ACP agent backend for Hermes.",
-        "Use ACP capabilities to complete tasks.",
-        "IMPORTANT: If you take an action with a tool, you MUST output tool calls using <tool_call>{...}</tool_call> blocks with JSON exactly in OpenAI function-call shape.",
-        "If no tool is needed, answer normally.",
-    ]
-    if model:
-        sections.append(f"Hermes requested model hint: {model}")
-
-    if isinstance(tools, list) and tools:
-        tool_specs: list[dict[str, Any]] = []
-        for t in tools:
-            if not isinstance(t, dict):
-                continue
-            fn = t.get("function") or {}
-            if not isinstance(fn, dict):
-                continue
-            name = fn.get("name")
-            if not isinstance(name, str) or not name.strip():
-                continue
-            tool_specs.append(
-                {
-                    "name": name.strip(),
-                    "description": fn.get("description", ""),
-                    "parameters": fn.get("parameters", {}),
-                }
-            )
-        if tool_specs:
-            sections.append(
-                "Available tools (OpenAI function schema). "
-                "When using a tool, emit ONLY <tool_call>{...}</tool_call> with one JSON object "
-                "containing id/type/function{name,arguments}. arguments must be a JSON string.\n"
-                + json.dumps(tool_specs, ensure_ascii=False)
-            )
-
-    if tool_choice is not None:
-        sections.append(
-            f"Tool choice hint: {json.dumps(tool_choice, ensure_ascii=False)}"
-        )
-
-    transcript: list[str] = []
-    for message in messages:
-        if not isinstance(message, dict):
-            continue
-        role = str(message.get("role") or "unknown").strip().lower()
-        if role == "tool":
-            role = "tool"
-        elif role not in {"system", "user", "assistant"}:
-            role = "context"
-
-        content = message.get("content")
-        rendered = _render_message_content(content)
-        if not rendered:
-            continue
-
-        label = {
-            "system": "System",
-            "user": "User",
-            "assistant": "Assistant",
-            "tool": "Tool",
-            "context": "Context",
-        }.get(role, role.title())
-        transcript.append(f"{label}:\n{rendered}")
-
-    if transcript:
-        sections.append("Conversation transcript:\n\n" + "\n\n".join(transcript))
-
-    sections.append("Continue the conversation from the latest user request.")
-    return "\n\n".join(
-        section.strip() for section in sections if section and section.strip()
-    )
-
-
-def _render_message_content(content: Any) -> str:
-    if content is None:
-        return ""
-    if isinstance(content, str):
-        return content.strip()
-    if isinstance(content, dict):
-        if "text" in content:
-            return str(content.get("text") or "").strip()
-        if "content" in content and isinstance(content.get("content"), str):
-            return str(content.get("content") or "").strip()
-        return json.dumps(content, ensure_ascii=True)
-    if isinstance(content, list):
-        parts: list[str] = []
-        for item in content:
-            if isinstance(item, str):
-                parts.append(item)
-            elif isinstance(item, dict):
-                text = item.get("text")
-                if isinstance(text, str) and text.strip():
-                    parts.append(text.strip())
-        return "\n".join(parts).strip()
-    return str(content).strip()
-
-
-def _extract_tool_calls_from_text(text: str) -> tuple[list[SimpleNamespace], str]:
-    if not isinstance(text, str) or not text.strip():
-        return [], ""
-
-    extracted: list[SimpleNamespace] = []
-    consumed_spans: list[tuple[int, int]] = []
-
-    def _try_add_tool_call(raw_json: str) -> None:
-        try:
-            obj = json.loads(raw_json)
-        except Exception:
-            return
-        if not isinstance(obj, dict):
-            return
-        fn = obj.get("function")
-        if not isinstance(fn, dict):
-            return
-        fn_name = fn.get("name")
-        if not isinstance(fn_name, str) or not fn_name.strip():
-            return
-        fn_args = fn.get("arguments", "{}")
-        if not isinstance(fn_args, str):
-            fn_args = json.dumps(fn_args, ensure_ascii=False)
-        call_id = obj.get("id")
-        if not isinstance(call_id, str) or not call_id.strip():
-            call_id = f"acp_call_{len(extracted) + 1}"
-
-        extracted.append(
-            SimpleNamespace(
-                id=call_id,
-                call_id=call_id,
-                response_item_id=None,
-                type="function",
-                function=SimpleNamespace(name=fn_name.strip(), arguments=fn_args),
-            )
-        )
-
-    for m in _TOOL_CALL_BLOCK_RE.finditer(text):
-        raw = m.group(1)
-        _try_add_tool_call(raw)
-        consumed_spans.append((m.start(), m.end()))
-
-    # Only try bare-JSON fallback when no XML blocks were found.
-    if not extracted:
-        for m in _TOOL_CALL_JSON_RE.finditer(text):
-            raw = m.group(0)
-            _try_add_tool_call(raw)
-            consumed_spans.append((m.start(), m.end()))
-
-    if not consumed_spans:
-        return extracted, text.strip()
-
-    consumed_spans.sort()
-    merged: list[tuple[int, int]] = []
-    for start, end in consumed_spans:
-        if not merged or start > merged[-1][1]:
-            merged.append((start, end))
-        else:
-            merged[-1] = (merged[-1][0], max(merged[-1][1], end))
-
-    parts: list[str] = []
-    cursor = 0
-    for start, end in merged:
-        if cursor < start:
-            parts.append(text[cursor:start])
-        cursor = max(cursor, end)
-    if cursor < len(text):
-        parts.append(text[cursor:])
-
-    cleaned = "\n".join(p.strip() for p in parts if p and p.strip()).strip()
-    return extracted, cleaned
-
-
-def _ensure_path_within_cwd(path_text: str, cwd: str) -> Path:
-    candidate = Path(path_text)
-    if not candidate.is_absolute():
-        raise PermissionError("ACP file-system paths must be absolute.")
-    resolved = candidate.resolve()
-    root = Path(cwd).resolve()
-    try:
-        resolved.relative_to(root)
-    except ValueError as exc:
-        raise PermissionError(
-            f"Path '{resolved}' is outside the session cwd '{root}'."
-        ) from exc
-    return resolved
-
-
-class _ACPChatCompletions:
-    def __init__(self, client: CopilotACPClient):
-        self._client = client
-
-    def create(self, **kwargs: Any) -> Any:
-        return self._client._create_chat_completion(**kwargs)
-
-
-class _ACPChatNamespace:
-    def __init__(self, client: CopilotACPClient):
-        self.completions = _ACPChatCompletions(client)
-
-
-class CopilotACPClient:
-    """Minimal OpenAI-client-compatible facade for Copilot ACP."""
-
-    def __init__(
-        self,
-        *,
-        api_key: str | None = None,
-        base_url: str | None = None,
-        default_headers: dict[str, str] | None = None,
-        acp_command: str | None = None,
-        acp_args: list[str] | None = None,
-        acp_cwd: str | None = None,
-        command: str | None = None,
-        args: list[str] | None = None,
-        **_: Any,
-    ):
-        self.api_key = api_key or "copilot-acp"
-        self.base_url = base_url or ACP_MARKER_BASE_URL
-        self._default_headers = dict(default_headers or {})
-        self._acp_command = acp_command or command or _resolve_command()
-        self._acp_args = list(acp_args or args or _resolve_args())
-        self._acp_cwd = str(Path(acp_cwd or os.getcwd()).resolve())
-        self.chat = _ACPChatNamespace(self)
-        self.is_closed = False
-        self._active_process: subprocess.Popen[str] | None = None
-        self._active_process_lock = threading.Lock()
-
-    def close(self) -> None:
-        proc: subprocess.Popen[str] | None
-        with self._active_process_lock:
-            proc = self._active_process
-            self._active_process = None
-        self.is_closed = True
-        if proc is None:
-            return
-        try:
-            proc.terminate()
-            proc.wait(timeout=2)
-        except Exception:
-            try:
-                proc.kill()
-            except Exception:
-                pass
-
-    def _create_chat_completion(
-        self,
-        *,
-        model: str | None = None,
-        messages: list[dict[str, Any]] | None = None,
-        timeout: float | None = None,
-        tools: list[dict[str, Any]] | None = None,
-        tool_choice: Any = None,
-        **_: Any,
-    ) -> Any:
-        prompt_text = _format_messages_as_prompt(
-            messages or [],
-            model=model,
-            tools=tools,
-            tool_choice=tool_choice,
-        )
-        # Normalise timeout: run_agent.py may pass an httpx.Timeout object
-        # (used natively by the OpenAI SDK) rather than a plain float.
-        if timeout is None:
-            _effective_timeout = _DEFAULT_TIMEOUT_SECONDS
-        elif isinstance(timeout, (int, float)):
-            _effective_timeout = float(timeout)
-        else:
-            # httpx.Timeout or similar — pick the largest component so the
-            # subprocess has enough wall-clock time for the full response.
-            _candidates = [
-                getattr(timeout, attr, None)
-                for attr in ("read", "write", "connect", "pool", "timeout")
-            ]
-            _numeric = [float(v) for v in _candidates if isinstance(v, (int, float))]
-            _effective_timeout = max(_numeric) if _numeric else _DEFAULT_TIMEOUT_SECONDS
-
-        response_text, reasoning_text = self._run_prompt(
-            prompt_text,
-            timeout_seconds=_effective_timeout,
-        )
-
-        tool_calls, cleaned_text = _extract_tool_calls_from_text(response_text)
-
-        usage = SimpleNamespace(
-            prompt_tokens=0,
-            completion_tokens=0,
-            total_tokens=0,
-            prompt_tokens_details=SimpleNamespace(cached_tokens=0),
-        )
-        assistant_message = SimpleNamespace(
-            content=cleaned_text,
-            tool_calls=tool_calls,
-            reasoning=reasoning_text or None,
-            reasoning_content=reasoning_text or None,
-            reasoning_details=None,
-        )
-        finish_reason = "tool_calls" if tool_calls else "stop"
-        choice = SimpleNamespace(message=assistant_message, finish_reason=finish_reason)
-        return SimpleNamespace(
-            choices=[choice],
-            usage=usage,
-            model=model or "copilot-acp",
-        )
-
-    def _run_prompt(
-        self, prompt_text: str, *, timeout_seconds: float
-    ) -> tuple[str, str]:
-        try:
-            proc = subprocess.Popen(
-                [self._acp_command] + self._acp_args,
-                stdin=subprocess.PIPE,
-                stdout=subprocess.PIPE,
-                stderr=subprocess.PIPE,
-                text=True,
-                bufsize=1,
-                cwd=self._acp_cwd,
-            )
-        except FileNotFoundError as exc:
-            raise RuntimeError(
-                f"Could not start Copilot ACP command '{self._acp_command}'. "
-                "Install GitHub Copilot CLI or set HERMES_COPILOT_ACP_COMMAND/COPILOT_CLI_PATH."
-            ) from exc
-
-        if proc.stdin is None or proc.stdout is None:
-            proc.kill()
-            raise RuntimeError("Copilot ACP process did not expose stdin/stdout pipes.")
-
-        self.is_closed = False
-        with self._active_process_lock:
-            self._active_process = proc
-
-        inbox: queue.Queue[dict[str, Any]] = queue.Queue()
-        stderr_tail: deque[str] = deque(maxlen=40)
-
-        def _stdout_reader() -> None:
-            if proc.stdout is None:
-                return
-            for line in proc.stdout:
-                try:
-                    inbox.put(json.loads(line))
-                except Exception:
-                    inbox.put({"raw": line.rstrip("\n")})
-
-        def _stderr_reader() -> None:
-            if proc.stderr is None:
-                return
-            for line in proc.stderr:
-                stderr_tail.append(line.rstrip("\n"))
-
-        out_thread = threading.Thread(target=_stdout_reader, daemon=True)
-        err_thread = threading.Thread(target=_stderr_reader, daemon=True)
-        out_thread.start()
-        err_thread.start()
-
-        next_id = 0
-
-        def _request(
-            method: str,
-            params: dict[str, Any],
-            *,
-            text_parts: list[str] | None = None,
-            reasoning_parts: list[str] | None = None,
-        ) -> Any:
-            nonlocal next_id
-            next_id += 1
-            request_id = next_id
-            payload = {
-                "jsonrpc": "2.0",
-                "id": request_id,
-                "method": method,
-                "params": params,
-            }
-            assert proc.stdin is not None  # always set: Popen(stdin=PIPE)
-            proc.stdin.write(json.dumps(payload) + "\n")
-            proc.stdin.flush()
-
-            deadline = time.time() + timeout_seconds
-            while time.time() < deadline:
-                if proc.poll() is not None:
-                    break
-                try:
-                    msg = inbox.get(timeout=0.1)
-                except queue.Empty:
-                    continue
-
-                if self._handle_server_message(
-                    msg,
-                    process=proc,
-                    cwd=self._acp_cwd,
-                    text_parts=text_parts,
-                    reasoning_parts=reasoning_parts,
-                ):
-                    continue
-
-                if msg.get("id") != request_id:
-                    continue
-                if "error" in msg:
-                    err = msg.get("error") or {}
-                    raise RuntimeError(
-                        f"Copilot ACP {method} failed: {err.get('message') or err}"
-                    )
-                return msg.get("result")
-
-            stderr_text = "\n".join(stderr_tail).strip()
-            if proc.poll() is not None and stderr_text:
-                raise RuntimeError(f"Copilot ACP process exited early: {stderr_text}")
-            raise TimeoutError(
-                f"Timed out waiting for Copilot ACP response to {method}."
-            )
-
-        try:
-            _request(
-                "initialize",
-                {
-                    "protocolVersion": 1,
-                    "clientCapabilities": {
-                        "fs": {
-                            "readTextFile": True,
-                            "writeTextFile": True,
-                        }
-                    },
-                    "clientInfo": {
-                        "name": "hermes-agent",
-                        "title": "Hermes Agent",
-                        "version": "0.0.0",
-                    },
-                },
-            )
-            session = (
-                _request(
-                    "session/new",
-                    {
-                        "cwd": self._acp_cwd,
-                        "mcpServers": [],
-                    },
-                )
-                or {}
-            )
-            session_id = str(session.get("sessionId") or "").strip()
-            if not session_id:
-                raise RuntimeError("Copilot ACP did not return a sessionId.")
-
-            text_parts: list[str] = []
-            reasoning_parts: list[str] = []
-            _request(
-                "session/prompt",
-                {
-                    "sessionId": session_id,
-                    "prompt": [
-                        {
-                            "type": "text",
-                            "text": prompt_text,
-                        }
-                    ],
-                },
-                text_parts=text_parts,
-                reasoning_parts=reasoning_parts,
-            )
-            return "".join(text_parts), "".join(reasoning_parts)
-        finally:
-            self.close()
-
-    def _handle_server_message(
-        self,
-        msg: dict[str, Any],
-        *,
-        process: subprocess.Popen[str],
-        cwd: str,
-        text_parts: list[str] | None,
-        reasoning_parts: list[str] | None,
-    ) -> bool:
-        method = msg.get("method")
-        if not isinstance(method, str):
-            return False
-
-        if method == "session/update":
-            params = msg.get("params") or {}
-            update = params.get("update") or {}
-            kind = str(update.get("sessionUpdate") or "").strip()
-            content = update.get("content") or {}
-            chunk_text = ""
-            if isinstance(content, dict):
-                chunk_text = str(content.get("text") or "")
-            if kind == "agent_message_chunk" and chunk_text and text_parts is not None:
-                text_parts.append(chunk_text)
-            elif (
-                kind == "agent_thought_chunk"
-                and chunk_text
-                and reasoning_parts is not None
-            ):
-                reasoning_parts.append(chunk_text)
-            return True
-
-        if process.stdin is None:
-            return True
-
-        message_id = msg.get("id")
-        params = msg.get("params") or {}
-
-        if method == "session/request_permission":
-            response = _permission_denied(message_id)
-        elif method == "fs/read_text_file":
-            try:
-                path = _ensure_path_within_cwd(str(params.get("path") or ""), cwd)
-                block_error = get_read_block_error(str(path))
-                if block_error:
-                    raise PermissionError(block_error)
-                content = path.read_text() if path.exists() else ""
-                line = params.get("line")
-                limit = params.get("limit")
-                if isinstance(line, int) and line > 1:
-                    lines = content.splitlines(keepends=True)
-                    start = line - 1
-                    end = (
-                        start + limit if isinstance(limit, int) and limit > 0 else None
-                    )
-                    content = "".join(lines[start:end])
-                if content:
-                    content = redact_sensitive_text(content)
-                response = {
-                    "jsonrpc": "2.0",
-                    "id": message_id,
-                    "result": {
-                        "content": content,
-                    },
-                }
-            except Exception as exc:
-                response = _jsonrpc_error(message_id, -32602, str(exc))
-        elif method == "fs/write_text_file":
-            try:
-                path = _ensure_path_within_cwd(str(params.get("path") or ""), cwd)
-                if is_write_denied(str(path)):
-                    raise PermissionError(
-                        f"Write denied: '{path}' is a protected system/credential file."
-                    )
-                path.parent.mkdir(parents=True, exist_ok=True)
-                path.write_text(str(params.get("content") or ""))
-                response = {
-                    "jsonrpc": "2.0",
-                    "id": message_id,
-                    "result": None,
-                }
-            except Exception as exc:
-                response = _jsonrpc_error(message_id, -32602, str(exc))
-        else:
-            response = _jsonrpc_error(
-                message_id,
-                -32601,
-                f"ACP client method '{method}' is not supported by Hermes yet.",
-            )
-
-        process.stdin.write(json.dumps(response) + "\n")
-        process.stdin.flush()
-        return True

agent/anthropic_adapter.py

@@ -202,19 +202,33 @@ def _forbids_sampling_params(model: str) -> bool:
 
 
 # Beta headers for enhanced features (sent with ALL auth types).
-# As of Opus 4.7 (2026-04-16), both of these are GA on Claude 4.6+ — the
+# As of Opus 4.7 (2026-04-16), the first two are GA on Claude 4.6+ — the
 # beta headers are still accepted (harmless no-op) but not required. Kept
 # here so older Claude (4.5, 4.1) + third-party Anthropic-compat endpoints
 # that still gate on the headers continue to get the enhanced features.
-# Migration guide: remove these if you no longer support ≤4.5 models.
+#
+# ``context-1m-2025-08-07`` unlocks the 1M context window on Claude Opus 4.6/4.7
+# and Sonnet 4.6 when served via AWS Bedrock or Azure AI Foundry. 1M is GA on
+# native Anthropic (api.anthropic.com) for Opus 4.6+, but Bedrock/Azure still
+# gate it behind this beta header as of 2026-04 — without it Bedrock caps Opus
+# at 200K even though model_metadata.py advertises 1M. The header is a harmless
+# no-op on endpoints where 1M is GA.
+#
+# Migration guide: remove these if you no longer support ≤4.5 models or once
+# Bedrock/Azure promote 1M to GA.
 _COMMON_BETAS = [
     "interleaved-thinking-2025-05-14",
     "fine-grained-tool-streaming-2025-05-14",
+    "context-1m-2025-08-07",
 ]
 # MiniMax's Anthropic-compatible endpoints fail tool-use requests when
 # the fine-grained tool streaming beta is present.  Omit it so tool calls
 # fall back to the provider's default response path.
 _TOOL_STREAMING_BETA = "fine-grained-tool-streaming-2025-05-14"
+# 1M context beta — see comment on _COMMON_BETAS above. Stripped for
+# Bearer-auth (MiniMax) endpoints since they host their own models and
+# unknown Anthropic beta headers risk request rejection.
+_CONTEXT_1M_BETA = "context-1m-2025-08-07"
 
 # Fast mode beta — enables the ``speed: "fast"`` request parameter for
 # significantly higher output token throughput on Opus 4.6 (~2.5x).
@@ -357,9 +371,14 @@ def _common_betas_for_base_url(base_url: str | None) -> list[str]:
     that include Anthropic's ``fine-grained-tool-streaming`` beta — every
     tool-use message triggers a connection error.  Strip that beta for
     Bearer-auth endpoints while keeping all other betas intact.
+
+    The ``context-1m-2025-08-07`` beta is also stripped for Bearer-auth
+    endpoints — MiniMax hosts its own models, not Claude, so the header is
+    irrelevant at best and risks request rejection at worst.
     """
     if _requires_bearer_auth(base_url):
-        return [b for b in _COMMON_BETAS if b != _TOOL_STREAMING_BETA]
+        _stripped = {_TOOL_STREAMING_BETA, _CONTEXT_1M_BETA}
+        return [b for b in _COMMON_BETAS if b not in _stripped]
     return _COMMON_BETAS
 
 
@@ -456,6 +475,13 @@ def build_anthropic_bedrock_client(region: str):
     Claude feature parity: prompt caching, thinking budgets, adaptive
     thinking, fast mode — features not available via the Converse API.
 
+    Attaches the common Anthropic beta headers as client-level defaults so
+    that Bedrock-hosted Claude models get the same enhanced features as
+    native Anthropic. The ``context-1m-2025-08-07`` beta in particular
+    unlocks the 1M context window for Opus 4.6/4.7 on Bedrock — without
+    it, Bedrock caps these models at 200K even though the Anthropic API
+    serves them with 1M natively.
+
     Auth uses the boto3 default credential chain (IAM roles, SSO, env vars).
     """
     if _anthropic_sdk is None:
@@ -473,6 +499,7 @@ def build_anthropic_bedrock_client(region: str):
     return _anthropic_sdk.AnthropicBedrock(
         aws_region=region,
         timeout=Timeout(timeout=900.0, connect=10.0),
+        default_headers={"anthropic-beta": ",".join(_COMMON_BETAS)},
     )
 
 

agent/auxiliary_client.py

@@ -151,31 +151,23 @@ def _fixed_temperature_for_model(
     return None
 
 # Default auxiliary models for direct API-key providers (cheap/fast for side tasks)
-def _get_aux_model_for_provider(provider_id: str) -> str:
-    """Return the cheap auxiliary model for a provider.
-
-    Reads from ProviderProfile.default_aux_model first, falling back to the
-    legacy hardcoded dict for providers that predate the profiles system.
-    """
-    try:
-        from providers import get_provider_profile
-        _p = get_provider_profile(provider_id)
-        if _p and _p.default_aux_model:
-            return _p.default_aux_model
-    except Exception:
-        pass
-    return _API_KEY_PROVIDER_AUX_MODELS_FALLBACK.get(provider_id, "")
-
-
-# Fallback for providers not yet migrated to ProviderProfile.default_aux_model.
-# New providers should set default_aux_model on their profile instead.
-_API_KEY_PROVIDER_AUX_MODELS_FALLBACK: Dict[str, str] = {
+_API_KEY_PROVIDER_AUX_MODELS: Dict[str, str] = {
+    "gemini": "gemini-3-flash-preview",
+    "zai": "glm-4.5-flash",
+    "kimi-coding": "kimi-k2-turbo-preview",
+    "stepfun": "step-3.5-flash",
+    "kimi-coding-cn": "kimi-k2-turbo-preview",
+    "gmi": "google/gemini-3.1-flash-lite-preview",
+    "minimax": "MiniMax-M2.7",
+    "minimax-cn": "MiniMax-M2.7",
     "anthropic": "claude-haiku-4-5-20251001",
+    "ai-gateway": "google/gemini-3-flash",
+    "opencode-zen": "gemini-3-flash",
+    "opencode-go": "glm-5",
+    "kilocode": "google/gemini-3-flash-preview",
+    "ollama-cloud": "nemotron-3-nano:30b",
 }
 
-# Legacy alias — callers that haven't been updated yet can still use this.
-_API_KEY_PROVIDER_AUX_MODELS: Dict[str, str] = _API_KEY_PROVIDER_AUX_MODELS_FALLBACK
-
 # Vision-specific model overrides for direct providers.
 # When the user's main provider has a dedicated vision/multimodal model that
 # differs from their main chat model, map it here.  The vision auto-detect
@@ -876,7 +868,7 @@ def _resolve_api_key_provider() -> Tuple[Optional[OpenAI], Optional[str]]:
             base_url = _to_openai_base_url(
                 _pool_runtime_base_url(entry, pconfig.inference_base_url) or pconfig.inference_base_url
             )
-            model = _get_aux_model_for_provider(provider_id) or None
+            model = _API_KEY_PROVIDER_AUX_MODELS.get(provider_id)
             if model is None:
                 continue  # skip provider if we don't know a valid aux model
             logger.debug("Auxiliary text client: %s (%s) via pool", pconfig.name, model)
@@ -885,22 +877,14 @@ def _resolve_api_key_provider() -> Tuple[Optional[OpenAI], Optional[str]]:
 
                 if is_native_gemini_base_url(base_url):
                     return GeminiNativeClient(api_key=api_key, base_url=base_url), model
-        extra = {}
-        if base_url_host_matches(base_url, "api.kimi.com"):
-            extra["default_headers"] = {"User-Agent": "claude-code/0.1.0"}
-        elif base_url_host_matches(base_url, "api.githubcopilot.com"):
-            from hermes_cli.models import copilot_default_headers
+            extra = {}
+            if base_url_host_matches(base_url, "api.kimi.com"):
+                extra["default_headers"] = {"User-Agent": "claude-code/0.1.0"}
+            elif base_url_host_matches(base_url, "api.githubcopilot.com"):
+                from hermes_cli.models import copilot_default_headers
 
-            extra["default_headers"] = copilot_default_headers()
-        else:
-            try:
-                from providers import get_provider_profile as _gpf_aux
-                _ph_aux = _gpf_aux(provider_id)
-                if _ph_aux and _ph_aux.default_headers:
-                    extra["default_headers"] = dict(_ph_aux.default_headers)
-            except Exception:
-                pass
-        return OpenAI(api_key=api_key, base_url=base_url, **extra), model
+                extra["default_headers"] = copilot_default_headers()
+            return OpenAI(api_key=api_key, base_url=base_url, **extra), model
 
         creds = resolve_api_key_provider_credentials(provider_id)
         api_key = str(creds.get("api_key", "")).strip()
@@ -910,7 +894,7 @@ def _resolve_api_key_provider() -> Tuple[Optional[OpenAI], Optional[str]]:
         base_url = _to_openai_base_url(
             str(creds.get("base_url", "")).strip().rstrip("/") or pconfig.inference_base_url
         )
-        model = _get_aux_model_for_provider(provider_id) or None
+        model = _API_KEY_PROVIDER_AUX_MODELS.get(provider_id)
         if model is None:
             continue  # skip provider if we don't know a valid aux model
         logger.debug("Auxiliary text client: %s (%s)", pconfig.name, model)
@@ -926,14 +910,6 @@ def _resolve_api_key_provider() -> Tuple[Optional[OpenAI], Optional[str]]:
             from hermes_cli.models import copilot_default_headers
 
             extra["default_headers"] = copilot_default_headers()
-        else:
-            try:
-                from providers import get_provider_profile as _gpf_aux2
-                _ph_aux2 = _gpf_aux2(provider_id)
-                if _ph_aux2 and _ph_aux2.default_headers:
-                    extra["default_headers"] = dict(_ph_aux2.default_headers)
-            except Exception:
-                pass
         return OpenAI(api_key=api_key, base_url=base_url, **extra), model
 
     return None, None
@@ -1282,7 +1258,7 @@ def _try_anthropic() -> Tuple[Optional[Any], Optional[str]]:
 
     from agent.anthropic_adapter import _is_oauth_token
     is_oauth = _is_oauth_token(token)
-    model = _get_aux_model_for_provider("anthropic") or "claude-haiku-4-5-20251001"
+    model = _API_KEY_PROVIDER_AUX_MODELS.get("anthropic", "claude-haiku-4-5-20251001")
     logger.debug("Auxiliary client: Anthropic native (%s) at %s (oauth=%s)", model, base_url, is_oauth)
     try:
         real_client = build_anthropic_client(token, base_url)
@@ -1666,7 +1642,7 @@ def _to_async_client(sync_client, model: str, is_vision: bool = False):
     except ImportError:
         pass
     try:
-        from acp_adapter.copilot_client import CopilotACPClient
+        from agent.copilot_acp_client import CopilotACPClient
         if isinstance(sync_client, CopilotACPClient):
             return sync_client, model
     except ImportError:
@@ -2010,7 +1986,7 @@ def resolve_provider_client(
             str(creds.get("base_url", "")).strip().rstrip("/") or pconfig.inference_base_url
         )
 
-        default_model = _get_aux_model_for_provider(provider)
+        default_model = _API_KEY_PROVIDER_AUX_MODELS.get(provider, "")
         final_model = _normalize_resolved_model(model or default_model, provider)
 
         if provider == "gemini":
@@ -2080,7 +2056,7 @@ def resolve_provider_client(
                     "process credentials are incomplete"
                 )
                 return None, None
-            from acp_adapter.copilot_client import CopilotACPClient
+            from agent.copilot_acp_client import CopilotACPClient
 
             client = CopilotACPClient(
                 api_key=api_key,

agent/copilot_acp_client.py

@@ -1,8 +1,646 @@
-"""Backward-compatibility shim.
+"""OpenAI-compatible shim that forwards Hermes requests to `copilot --acp`.
 
-CopilotACPClient has moved to acp_adapter/copilot_client.py.
-This module re-exports it so existing callers continue to work.
+This adapter lets Hermes treat the GitHub Copilot ACP server as a chat-style
+backend. Each request starts a short-lived ACP session, sends the formatted
+conversation as a single prompt, collects text chunks, and converts the result
+back into the minimal shape Hermes expects from an OpenAI client.
 """
-from acp_adapter.copilot_client import CopilotACPClient  # noqa: F401
 
-__all__ = ["CopilotACPClient"]
+from __future__ import annotations
+
+import json
+import os
+import queue
+import re
+import shlex
+import subprocess
+import threading
+import time
+from collections import deque
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any
+
+from agent.file_safety import get_read_block_error, is_write_denied
+from agent.redact import redact_sensitive_text
+
+ACP_MARKER_BASE_URL = "acp://copilot"
+_DEFAULT_TIMEOUT_SECONDS = 900.0
+
+_TOOL_CALL_BLOCK_RE = re.compile(r"<tool_call>\s*(\{.*?\})\s*</tool_call>", re.DOTALL)
+_TOOL_CALL_JSON_RE = re.compile(r"\{\s*\"id\"\s*:\s*\"[^\"]+\"\s*,\s*\"type\"\s*:\s*\"function\"\s*,\s*\"function\"\s*:\s*\{.*?\}\s*\}", re.DOTALL)
+
+
+def _resolve_command() -> str:
+    return (
+        os.getenv("HERMES_COPILOT_ACP_COMMAND", "").strip()
+        or os.getenv("COPILOT_CLI_PATH", "").strip()
+        or "copilot"
+    )
+
+
+def _resolve_args() -> list[str]:
+    raw = os.getenv("HERMES_COPILOT_ACP_ARGS", "").strip()
+    if not raw:
+        return ["--acp", "--stdio"]
+    return shlex.split(raw)
+
+
+def _resolve_home_dir() -> str:
+    """Return a stable HOME for child ACP processes."""
+
+    try:
+        from hermes_constants import get_subprocess_home
+
+        profile_home = get_subprocess_home()
+        if profile_home:
+            return profile_home
+    except Exception:
+        pass
+
+    home = os.environ.get("HOME", "").strip()
+    if home:
+        return home
+
+    expanded = os.path.expanduser("~")
+    if expanded and expanded != "~":
+        return expanded
+
+    try:
+        import pwd
+
+        resolved = pwd.getpwuid(os.getuid()).pw_dir.strip()
+        if resolved:
+            return resolved
+    except Exception:
+        pass
+
+    # Last resort: /tmp (writable on any POSIX system). Avoids crashing the
+    # subprocess with no HOME; callers can set HERMES_HOME explicitly if they
+    # need a different writable dir.
+    return "/tmp"
+
+
+def _build_subprocess_env() -> dict[str, str]:
+    env = os.environ.copy()
+    env["HOME"] = _resolve_home_dir()
+    return env
+
+
+def _jsonrpc_error(message_id: Any, code: int, message: str) -> dict[str, Any]:
+    return {
+        "jsonrpc": "2.0",
+        "id": message_id,
+        "error": {
+            "code": code,
+            "message": message,
+        },
+    }
+
+
+def _permission_denied(message_id: Any) -> dict[str, Any]:
+    return {
+        "jsonrpc": "2.0",
+        "id": message_id,
+        "result": {
+            "outcome": {
+                "outcome": "cancelled",
+            }
+        },
+    }
+
+
+def _format_messages_as_prompt(
+    messages: list[dict[str, Any]],
+    model: str | None = None,
+    tools: list[dict[str, Any]] | None = None,
+    tool_choice: Any = None,
+) -> str:
+    sections: list[str] = [
+        "You are being used as the active ACP agent backend for Hermes.",
+        "Use ACP capabilities to complete tasks.",
+        "IMPORTANT: If you take an action with a tool, you MUST output tool calls using <tool_call>{...}</tool_call> blocks with JSON exactly in OpenAI function-call shape.",
+        "If no tool is needed, answer normally.",
+    ]
+    if model:
+        sections.append(f"Hermes requested model hint: {model}")
+
+    if isinstance(tools, list) and tools:
+        tool_specs: list[dict[str, Any]] = []
+        for t in tools:
+            if not isinstance(t, dict):
+                continue
+            fn = t.get("function") or {}
+            if not isinstance(fn, dict):
+                continue
+            name = fn.get("name")
+            if not isinstance(name, str) or not name.strip():
+                continue
+            tool_specs.append(
+                {
+                    "name": name.strip(),
+                    "description": fn.get("description", ""),
+                    "parameters": fn.get("parameters", {}),
+                }
+            )
+        if tool_specs:
+            sections.append(
+                "Available tools (OpenAI function schema). "
+                "When using a tool, emit ONLY <tool_call>{...}</tool_call> with one JSON object "
+                "containing id/type/function{name,arguments}. arguments must be a JSON string.\n"
+                + json.dumps(tool_specs, ensure_ascii=False)
+            )
+
+    if tool_choice is not None:
+        sections.append(f"Tool choice hint: {json.dumps(tool_choice, ensure_ascii=False)}")
+
+    transcript: list[str] = []
+    for message in messages:
+        if not isinstance(message, dict):
+            continue
+        role = str(message.get("role") or "unknown").strip().lower()
+        if role == "tool":
+            role = "tool"
+        elif role not in {"system", "user", "assistant"}:
+            role = "context"
+
+        content = message.get("content")
+        rendered = _render_message_content(content)
+        if not rendered:
+            continue
+
+        label = {
+            "system": "System",
+            "user": "User",
+            "assistant": "Assistant",
+            "tool": "Tool",
+            "context": "Context",
+        }.get(role, role.title())
+        transcript.append(f"{label}:\n{rendered}")
+
+    if transcript:
+        sections.append("Conversation transcript:\n\n" + "\n\n".join(transcript))
+
+    sections.append("Continue the conversation from the latest user request.")
+    return "\n\n".join(section.strip() for section in sections if section and section.strip())
+
+
+def _render_message_content(content: Any) -> str:
+    if content is None:
+        return ""
+    if isinstance(content, str):
+        return content.strip()
+    if isinstance(content, dict):
+        if "text" in content:
+            return str(content.get("text") or "").strip()
+        if "content" in content and isinstance(content.get("content"), str):
+            return str(content.get("content") or "").strip()
+        return json.dumps(content, ensure_ascii=True)
+    if isinstance(content, list):
+        parts: list[str] = []
+        for item in content:
+            if isinstance(item, str):
+                parts.append(item)
+            elif isinstance(item, dict):
+                text = item.get("text")
+                if isinstance(text, str) and text.strip():
+                    parts.append(text.strip())
+        return "\n".join(parts).strip()
+    return str(content).strip()
+
+
+def _extract_tool_calls_from_text(text: str) -> tuple[list[SimpleNamespace], str]:
+    if not isinstance(text, str) or not text.strip():
+        return [], ""
+
+    extracted: list[SimpleNamespace] = []
+    consumed_spans: list[tuple[int, int]] = []
+
+    def _try_add_tool_call(raw_json: str) -> None:
+        try:
+            obj = json.loads(raw_json)
+        except Exception:
+            return
+        if not isinstance(obj, dict):
+            return
+        fn = obj.get("function")
+        if not isinstance(fn, dict):
+            return
+        fn_name = fn.get("name")
+        if not isinstance(fn_name, str) or not fn_name.strip():
+            return
+        fn_args = fn.get("arguments", "{}")
+        if not isinstance(fn_args, str):
+            fn_args = json.dumps(fn_args, ensure_ascii=False)
+        call_id = obj.get("id")
+        if not isinstance(call_id, str) or not call_id.strip():
+            call_id = f"acp_call_{len(extracted)+1}"
+
+        extracted.append(
+            SimpleNamespace(
+                id=call_id,
+                call_id=call_id,
+                response_item_id=None,
+                type="function",
+                function=SimpleNamespace(name=fn_name.strip(), arguments=fn_args),
+            )
+        )
+
+    for m in _TOOL_CALL_BLOCK_RE.finditer(text):
+        raw = m.group(1)
+        _try_add_tool_call(raw)
+        consumed_spans.append((m.start(), m.end()))
+
+    # Only try bare-JSON fallback when no XML blocks were found.
+    if not extracted:
+        for m in _TOOL_CALL_JSON_RE.finditer(text):
+            raw = m.group(0)
+            _try_add_tool_call(raw)
+            consumed_spans.append((m.start(), m.end()))
+
+    if not consumed_spans:
+        return extracted, text.strip()
+
+    consumed_spans.sort()
+    merged: list[tuple[int, int]] = []
+    for start, end in consumed_spans:
+        if not merged or start > merged[-1][1]:
+            merged.append((start, end))
+        else:
+            merged[-1] = (merged[-1][0], max(merged[-1][1], end))
+
+    parts: list[str] = []
+    cursor = 0
+    for start, end in merged:
+        if cursor < start:
+            parts.append(text[cursor:start])
+        cursor = max(cursor, end)
+    if cursor < len(text):
+        parts.append(text[cursor:])
+
+    cleaned = "\n".join(p.strip() for p in parts if p and p.strip()).strip()
+    return extracted, cleaned
+
+
+
+def _ensure_path_within_cwd(path_text: str, cwd: str) -> Path:
+    candidate = Path(path_text)
+    if not candidate.is_absolute():
+        raise PermissionError("ACP file-system paths must be absolute.")
+    resolved = candidate.resolve()
+    root = Path(cwd).resolve()
+    try:
+        resolved.relative_to(root)
+    except ValueError as exc:
+        raise PermissionError(f"Path '{resolved}' is outside the session cwd '{root}'.") from exc
+    return resolved
+
+
+class _ACPChatCompletions:
+    def __init__(self, client: "CopilotACPClient"):
+        self._client = client
+
+    def create(self, **kwargs: Any) -> Any:
+        return self._client._create_chat_completion(**kwargs)
+
+
+class _ACPChatNamespace:
+    def __init__(self, client: "CopilotACPClient"):
+        self.completions = _ACPChatCompletions(client)
+
+
+class CopilotACPClient:
+    """Minimal OpenAI-client-compatible facade for Copilot ACP."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        default_headers: dict[str, str] | None = None,
+        acp_command: str | None = None,
+        acp_args: list[str] | None = None,
+        acp_cwd: str | None = None,
+        command: str | None = None,
+        args: list[str] | None = None,
+        **_: Any,
+    ):
+        self.api_key = api_key or "copilot-acp"
+        self.base_url = base_url or ACP_MARKER_BASE_URL
+        self._default_headers = dict(default_headers or {})
+        self._acp_command = acp_command or command or _resolve_command()
+        self._acp_args = list(acp_args or args or _resolve_args())
+        self._acp_cwd = str(Path(acp_cwd or os.getcwd()).resolve())
+        self.chat = _ACPChatNamespace(self)
+        self.is_closed = False
+        self._active_process: subprocess.Popen[str] | None = None
+        self._active_process_lock = threading.Lock()
+
+    def close(self) -> None:
+        proc: subprocess.Popen[str] | None
+        with self._active_process_lock:
+            proc = self._active_process
+            self._active_process = None
+        self.is_closed = True
+        if proc is None:
+            return
+        try:
+            proc.terminate()
+            proc.wait(timeout=2)
+        except Exception:
+            try:
+                proc.kill()
+            except Exception:
+                pass
+
+    def _create_chat_completion(
+        self,
+        *,
+        model: str | None = None,
+        messages: list[dict[str, Any]] | None = None,
+        timeout: float | None = None,
+        tools: list[dict[str, Any]] | None = None,
+        tool_choice: Any = None,
+        **_: Any,
+    ) -> Any:
+        prompt_text = _format_messages_as_prompt(
+            messages or [],
+            model=model,
+            tools=tools,
+            tool_choice=tool_choice,
+        )
+        # Normalise timeout: run_agent.py may pass an httpx.Timeout object
+        # (used natively by the OpenAI SDK) rather than a plain float.
+        if timeout is None:
+            _effective_timeout = _DEFAULT_TIMEOUT_SECONDS
+        elif isinstance(timeout, (int, float)):
+            _effective_timeout = float(timeout)
+        else:
+            # httpx.Timeout or similar — pick the largest component so the
+            # subprocess has enough wall-clock time for the full response.
+            _candidates = [
+                getattr(timeout, attr, None)
+                for attr in ("read", "write", "connect", "pool", "timeout")
+            ]
+            _numeric = [float(v) for v in _candidates if isinstance(v, (int, float))]
+            _effective_timeout = max(_numeric) if _numeric else _DEFAULT_TIMEOUT_SECONDS
+
+        response_text, reasoning_text = self._run_prompt(
+            prompt_text,
+            timeout_seconds=_effective_timeout,
+        )
+
+        tool_calls, cleaned_text = _extract_tool_calls_from_text(response_text)
+
+        usage = SimpleNamespace(
+            prompt_tokens=0,
+            completion_tokens=0,
+            total_tokens=0,
+            prompt_tokens_details=SimpleNamespace(cached_tokens=0),
+        )
+        assistant_message = SimpleNamespace(
+            content=cleaned_text,
+            tool_calls=tool_calls,
+            reasoning=reasoning_text or None,
+            reasoning_content=reasoning_text or None,
+            reasoning_details=None,
+        )
+        finish_reason = "tool_calls" if tool_calls else "stop"
+        choice = SimpleNamespace(message=assistant_message, finish_reason=finish_reason)
+        return SimpleNamespace(
+            choices=[choice],
+            usage=usage,
+            model=model or "copilot-acp",
+        )
+
+    def _run_prompt(self, prompt_text: str, *, timeout_seconds: float) -> tuple[str, str]:
+        try:
+            proc = subprocess.Popen(
+                [self._acp_command] + self._acp_args,
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                bufsize=1,
+                cwd=self._acp_cwd,
+                env=_build_subprocess_env(),
+            )
+        except FileNotFoundError as exc:
+            raise RuntimeError(
+                f"Could not start Copilot ACP command '{self._acp_command}'. "
+                "Install GitHub Copilot CLI or set HERMES_COPILOT_ACP_COMMAND/COPILOT_CLI_PATH."
+            ) from exc
+
+        if proc.stdin is None or proc.stdout is None:
+            proc.kill()
+            raise RuntimeError("Copilot ACP process did not expose stdin/stdout pipes.")
+
+        self.is_closed = False
+        with self._active_process_lock:
+            self._active_process = proc
+
+        inbox: queue.Queue[dict[str, Any]] = queue.Queue()
+        stderr_tail: deque[str] = deque(maxlen=40)
+
+        def _stdout_reader() -> None:
+            if proc.stdout is None:
+                return
+            for line in proc.stdout:
+                try:
+                    inbox.put(json.loads(line))
+                except Exception:
+                    inbox.put({"raw": line.rstrip("\n")})
+
+        def _stderr_reader() -> None:
+            if proc.stderr is None:
+                return
+            for line in proc.stderr:
+                stderr_tail.append(line.rstrip("\n"))
+
+        out_thread = threading.Thread(target=_stdout_reader, daemon=True)
+        err_thread = threading.Thread(target=_stderr_reader, daemon=True)
+        out_thread.start()
+        err_thread.start()
+
+        next_id = 0
+
+        def _request(method: str, params: dict[str, Any], *, text_parts: list[str] | None = None, reasoning_parts: list[str] | None = None) -> Any:
+            nonlocal next_id
+            next_id += 1
+            request_id = next_id
+            payload = {
+                "jsonrpc": "2.0",
+                "id": request_id,
+                "method": method,
+                "params": params,
+            }
+            proc.stdin.write(json.dumps(payload) + "\n")
+            proc.stdin.flush()
+
+            deadline = time.time() + timeout_seconds
+            while time.time() < deadline:
+                if proc.poll() is not None:
+                    break
+                try:
+                    msg = inbox.get(timeout=0.1)
+                except queue.Empty:
+                    continue
+
+                if self._handle_server_message(
+                    msg,
+                    process=proc,
+                    cwd=self._acp_cwd,
+                    text_parts=text_parts,
+                    reasoning_parts=reasoning_parts,
+                ):
+                    continue
+
+                if msg.get("id") != request_id:
+                    continue
+                if "error" in msg:
+                    err = msg.get("error") or {}
+                    raise RuntimeError(
+                        f"Copilot ACP {method} failed: {err.get('message') or err}"
+                    )
+                return msg.get("result")
+
+            stderr_text = "\n".join(stderr_tail).strip()
+            if proc.poll() is not None and stderr_text:
+                raise RuntimeError(f"Copilot ACP process exited early: {stderr_text}")
+            raise TimeoutError(f"Timed out waiting for Copilot ACP response to {method}.")
+
+        try:
+            _request(
+                "initialize",
+                {
+                    "protocolVersion": 1,
+                    "clientCapabilities": {
+                        "fs": {
+                            "readTextFile": True,
+                            "writeTextFile": True,
+                        }
+                    },
+                    "clientInfo": {
+                        "name": "hermes-agent",
+                        "title": "Hermes Agent",
+                        "version": "0.0.0",
+                    },
+                },
+            )
+            session = _request(
+                "session/new",
+                {
+                    "cwd": self._acp_cwd,
+                    "mcpServers": [],
+                },
+            ) or {}
+            session_id = str(session.get("sessionId") or "").strip()
+            if not session_id:
+                raise RuntimeError("Copilot ACP did not return a sessionId.")
+
+            text_parts: list[str] = []
+            reasoning_parts: list[str] = []
+            _request(
+                "session/prompt",
+                {
+                    "sessionId": session_id,
+                    "prompt": [
+                        {
+                            "type": "text",
+                            "text": prompt_text,
+                        }
+                    ],
+                },
+                text_parts=text_parts,
+                reasoning_parts=reasoning_parts,
+            )
+            return "".join(text_parts), "".join(reasoning_parts)
+        finally:
+            self.close()
+
+    def _handle_server_message(
+        self,
+        msg: dict[str, Any],
+        *,
+        process: subprocess.Popen[str],
+        cwd: str,
+        text_parts: list[str] | None,
+        reasoning_parts: list[str] | None,
+    ) -> bool:
+        method = msg.get("method")
+        if not isinstance(method, str):
+            return False
+
+        if method == "session/update":
+            params = msg.get("params") or {}
+            update = params.get("update") or {}
+            kind = str(update.get("sessionUpdate") or "").strip()
+            content = update.get("content") or {}
+            chunk_text = ""
+            if isinstance(content, dict):
+                chunk_text = str(content.get("text") or "")
+            if kind == "agent_message_chunk" and chunk_text and text_parts is not None:
+                text_parts.append(chunk_text)
+            elif kind == "agent_thought_chunk" and chunk_text and reasoning_parts is not None:
+                reasoning_parts.append(chunk_text)
+            return True
+
+        if process.stdin is None:
+            return True
+
+        message_id = msg.get("id")
+        params = msg.get("params") or {}
+
+        if method == "session/request_permission":
+            response = _permission_denied(message_id)
+        elif method == "fs/read_text_file":
+            try:
+                path = _ensure_path_within_cwd(str(params.get("path") or ""), cwd)
+                block_error = get_read_block_error(str(path))
+                if block_error:
+                    raise PermissionError(block_error)
+                content = path.read_text() if path.exists() else ""
+                line = params.get("line")
+                limit = params.get("limit")
+                if isinstance(line, int) and line > 1:
+                    lines = content.splitlines(keepends=True)
+                    start = line - 1
+                    end = start + limit if isinstance(limit, int) and limit > 0 else None
+                    content = "".join(lines[start:end])
+                if content:
+                    content = redact_sensitive_text(content)
+                response = {
+                    "jsonrpc": "2.0",
+                    "id": message_id,
+                    "result": {
+                        "content": content,
+                    },
+                }
+            except Exception as exc:
+                response = _jsonrpc_error(message_id, -32602, str(exc))
+        elif method == "fs/write_text_file":
+            try:
+                path = _ensure_path_within_cwd(str(params.get("path") or ""), cwd)
+                if is_write_denied(str(path)):
+                    raise PermissionError(
+                        f"Write denied: '{path}' is a protected system/credential file."
+                    )
+                path.parent.mkdir(parents=True, exist_ok=True)
+                path.write_text(str(params.get("content") or ""))
+                response = {
+                    "jsonrpc": "2.0",
+                    "id": message_id,
+                    "result": None,
+                }
+            except Exception as exc:
+                response = _jsonrpc_error(message_id, -32602, str(exc))
+        else:
+            response = _jsonrpc_error(
+                message_id,
+                -32601,
+                f"ACP client method '{method}' is not supported by Hermes yet.",
+            )
+
+        process.stdin.write(json.dumps(response) + "\n")
+        process.stdin.flush()
+        return True

agent/model_metadata.py

@@ -313,17 +313,6 @@ _URL_TO_PROVIDER: Dict[str, str] = {
     "ollama.com": "ollama-cloud",
 }
 
-# Auto-extend with hostnames derived from provider profiles.
-# Any provider with a base_url not already in the map gets added automatically.
-try:
-    from providers import list_providers as _list_providers
-    for _pp in _list_providers():
-        _host = _pp.get_hostname()
-        if _host and _host not in _URL_TO_PROVIDER:
-            _URL_TO_PROVIDER[_host] = _pp.name
-except Exception:
-    pass
-
 
 def _infer_provider_from_url(base_url: str) -> Optional[str]:
     """Infer the models.dev provider name from a base URL.

agent/redact.py

@@ -56,8 +56,12 @@ _SENSITIVE_BODY_KEYS = frozenset({
 })
 
 # Snapshot at import time so runtime env mutations (e.g. LLM-generated
-# `export HERMES_REDACT_SECRETS=false`) cannot disable redaction mid-session.
-_REDACT_ENABLED = os.getenv("HERMES_REDACT_SECRETS", "").lower() not in ("0", "false", "no", "off")
+# `export HERMES_REDACT_SECRETS=true`) cannot enable/disable redaction
+# mid-session.  OFF by default — user must opt in via
+# `security.redact_secrets: true` in config.yaml (bridged to this env var
+# in hermes_cli/main.py and gateway/run.py) or `HERMES_REDACT_SECRETS=true`
+# in ~/.hermes/.env.
+_REDACT_ENABLED = os.getenv("HERMES_REDACT_SECRETS", "").lower() in ("1", "true", "yes", "on")
 
 # Known API key prefixes -- match the prefix + contiguous token chars
 _PREFIX_PATTERNS = [
@@ -257,7 +261,7 @@ def redact_sensitive_text(text: str) -> str:
     """Apply all redaction patterns to a block of text.
 
     Safe to call on any string -- non-matching text passes through unchanged.
-    Disabled when security.redact_secrets is false in config.yaml.
+    Disabled by default — enable via security.redact_secrets: true in config.yaml.
     """
     if text is None:
         return None

agent/transports/__init__.py

@@ -6,16 +6,9 @@ Usage:
     result = transport.normalize_response(raw_response)
 """
 
-from agent.transports.types import (
-    NormalizedResponse,
-    ToolCall,
-    Usage,
-    build_tool_call,
-    map_finish_reason,
-)  # noqa: F401
+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:
@@ -30,9 +23,6 @@ def get_transport(api_mode: str):
     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
@@ -48,8 +38,6 @@ def get_transport(api_mode: str):
 
 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:

agent/transports/chat_completions.py

@@ -10,7 +10,7 @@ reasoning configuration, temperature handling, and extra_body assembly.
 """
 
 import copy
-from typing import Any
+from typing import Any, Dict, List, Optional
 
 from agent.moonshot_schema import is_moonshot_model, sanitize_moonshot_tools
 from agent.prompt_builder import DEVELOPER_ROLE_MODELS
@@ -28,9 +28,7 @@ class ChatCompletionsTransport(ProviderTransport):
     def api_mode(self) -> str:
         return "chat_completions"
 
-    def convert_messages(
-        self, messages: list[dict[str, Any]], **kwargs
-    ) -> list[dict[str, Any]]:
+    def convert_messages(self, messages: List[Dict[str, Any]], **kwargs) -> List[Dict[str, Any]]:
         """Messages are already in OpenAI format — sanitize Codex leaks only.
 
         Strips Codex Responses API fields (``codex_reasoning_items`` /
@@ -47,9 +45,7 @@ class ChatCompletionsTransport(ProviderTransport):
             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
-                    ):
+                    if isinstance(tc, dict) and ("call_id" in tc or "response_item_id" in tc):
                         needs_sanitize = True
                         break
                 if needs_sanitize:
@@ -72,52 +68,76 @@ class ChatCompletionsTransport(ProviderTransport):
                         tc.pop("response_item_id", None)
         return sanitized
 
-    def convert_tools(self, tools: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    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,
+        messages: List[Dict[str, Any]],
+        tools: Optional[List[Dict[str, Any]]] = None,
         **params,
-    ) -> dict[str, Any]:
+    ) -> Dict[str, Any]:
         """Build chat.completions.create() kwargs.
 
-        params (all optional):
+        This is the most complex transport method — it handles ~16 providers
+        via params rather than subclasses.
+
+        params:
             timeout: float — API call timeout
             max_tokens: int | None — user-configured max tokens
-            ephemeral_max_output_tokens: int | None — one-shot override
+            ephemeral_max_output_tokens: int | None — one-shot override (error recovery)
             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
+            qwen_session_metadata: dict | None — {sessionId, promptId} precomputed
             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.
-            # Remaining flags — only used by the legacy fallback for unregistered
-            # providers (i.e. get_provider_profile() returned None).  Known
-            # providers all go through provider_profile.
-            qwen_session_metadata: dict | None
+            # Provider detection flags (all optional, default False)
+            is_openrouter: bool
+            is_nous: bool
+            is_qwen_portal: bool
+            is_github_models: bool
+            is_nvidia_nim: bool
+            is_kimi: 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
+            # Temperature
+            fixed_temperature: Any — from _fixed_temperature_for_model()
+            omit_temperature: bool
+            # Reasoning
             supports_reasoning: bool
+            github_reasoning_extra: dict | None
+            # Claude on OpenRouter/Nous max output
             anthropic_max_output: int | None
-            extra_body_additions: dict | None
+            # Extra
+            extra_body_additions: dict | None — pre-built extra_body entries
         """
         # Codex sanitization: drop reasoning_items / call_id / response_item_id
         sanitized = self.convert_messages(messages)
 
-        # ── 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.
+        # Qwen portal prep AFTER codex sanitization.  If sanitize already
+        # deepcopied, reuse that copy via the in-place variant to avoid a
+        # second deepcopy.
+        is_qwen = params.get("is_qwen_portal", False)
+        if is_qwen:
+            qwen_prep = params.get("qwen_prepare_fn")
+            qwen_prep_inplace = params.get("qwen_prepare_inplace_fn")
+            if sanitized is messages:
+                if qwen_prep is not None:
+                    sanitized = qwen_prep(sanitized)
+            else:
+                # Already deepcopied — transform in place
+                if qwen_prep_inplace is not None:
+                    qwen_prep_inplace(sanitized)
+                elif qwen_prep is not None:
+                    sanitized = qwen_prep(sanitized)
 
         # Developer role swap for GPT-5/Codex models
         model_lower = params.get("model_lower", (model or "").lower())
@@ -130,7 +150,7 @@ class ChatCompletionsTransport(ProviderTransport):
             sanitized = list(sanitized)
             sanitized[0] = {**sanitized[0], "role": "developer"}
 
-        api_kwargs: dict[str, Any] = {
+        api_kwargs: Dict[str, Any] = {
             "model": model,
             "messages": sanitized,
         }
@@ -139,6 +159,19 @@ class ChatCompletionsTransport(ProviderTransport):
         if timeout is not None:
             api_kwargs["timeout"] = timeout
 
+        # Temperature
+        fixed_temp = params.get("fixed_temperature")
+        omit_temp = params.get("omit_temperature", False)
+        if omit_temp:
+            api_kwargs.pop("temperature", None)
+        elif fixed_temp is not None:
+            api_kwargs["temperature"] = fixed_temp
+
+        # Qwen metadata (caller precomputes {sessionId, promptId})
+        qwen_meta = params.get("qwen_session_metadata")
+        if qwen_meta and is_qwen:
+            api_kwargs["metadata"] = qwen_meta
+
         # Tools
         if tools:
             # Moonshot/Kimi uses a stricter flavored JSON Schema.  Rewriting
@@ -153,24 +186,96 @@ class ChatCompletionsTransport(ProviderTransport):
         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)
+        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 is_nvidia_nim and max_tokens_fn:
+            api_kwargs.update(max_tokens_fn(16384))
+        elif is_qwen and max_tokens_fn:
+            api_kwargs.update(max_tokens_fn(65536))
+        elif is_kimi and max_tokens_fn:
+            # Kimi/Moonshot: 32000 matches Kimi CLI's default
+            api_kwargs.update(max_tokens_fn(32000))
         elif anthropic_max_out is not None:
             api_kwargs["max_tokens"] = anthropic_max_out
 
-        # extra_body assembly
-        extra_body: dict[str, Any] = {}
+        # 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
 
-        # Generic reasoning passthrough for unknown providers
+        # 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_prefs = params.get("provider_preferences")
+        if provider_prefs and is_openrouter:
+            extra_body["provider"] = provider_prefs
+
+        # 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
         if params.get("supports_reasoning", False):
-            reasoning_config = params.get("reasoning_config")
-            if reasoning_config is not None:
-                extra_body["reasoning"] = dict(reasoning_config)
+            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 reasoning_config is not None:
+                    rc = dict(reasoning_config)
+                    if is_nous and rc.get("enabled") is False:
+                        pass  # omit for Nous when disabled
+                    else:
+                        extra_body["reasoning"] = rc
+                else:
+                    extra_body["reasoning"] = {"enabled": True, "effort": "medium"}
+
+        if is_nous:
+            extra_body["tags"] = ["product=hermes-agent"]
+
+        # Ollama num_ctx
+        ollama_ctx = params.get("ollama_num_ctx")
+        if ollama_ctx:
+            options = extra_body.get("options", {})
+            options["num_ctx"] = ollama_ctx
+            extra_body["options"] = options
+
+        # Ollama/custom think=false
+        if params.get("is_custom_provider", False):
+            if reasoning_config and isinstance(reasoning_config, dict):
+                _effort = (reasoning_config.get("effort") or "").strip().lower()
+                _enabled = reasoning_config.get("enabled", True)
+                if _effort == "none" or _enabled is False:
+                    extra_body["think"] = False
+
+        if is_qwen:
+            extra_body["vl_high_resolution_images"] = True
 
         # Merge any pre-built extra_body additions
         additions = params.get("extra_body_additions")
@@ -187,117 +292,6 @@ class ChatCompletionsTransport(ProviderTransport):
 
         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")
-
-        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.default_max_tokens and max_tokens_fn:
-            api_kwargs.update(max_tokens_fn(profile.default_max_tokens))
-        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"),
-            )
-        )
-        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"),
-        )
-        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:
-            api_kwargs["extra_body"] = extra_body
-
-        return api_kwargs
-
     def normalize_response(self, response: Any, **kwargs) -> NormalizedResponse:
         """Normalize OpenAI ChatCompletion to NormalizedResponse.
 
@@ -319,7 +313,7 @@ class ChatCompletionsTransport(ProviderTransport):
                 # 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] = {}
+                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")
@@ -330,14 +324,12 @@ class ChatCompletionsTransport(ProviderTransport):
                         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,
-                    )
-                )
+                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:
@@ -355,7 +347,7 @@ class ChatCompletionsTransport(ProviderTransport):
         reasoning = getattr(msg, "reasoning", None)
         reasoning_content = getattr(msg, "reasoning_content", None)
 
-        provider_data: dict[str, Any] = {}
+        provider_data: Dict[str, Any] = {}
         if reasoning_content:
             provider_data["reasoning_content"] = reasoning_content
         rd = getattr(msg, "reasoning_details", None)
@@ -381,7 +373,7 @@ class ChatCompletionsTransport(ProviderTransport):
             return False
         return True
 
-    def extract_cache_stats(self, response: Any) -> dict[str, int] | None:
+    def extract_cache_stats(self, response: Any) -> Optional[Dict[str, int]]:
         """Extract OpenRouter/OpenAI cache stats from prompt_tokens_details."""
         usage = getattr(response, "usage", None)
         if usage is None:

agent/transports/types.py

@@ -12,7 +12,7 @@ from __future__ import annotations
 
 import json
 from dataclasses import dataclass, field
-from typing import Any
+from typing import Any, Dict, List, Optional
 
 
 @dataclass
@@ -32,10 +32,10 @@ class ToolCall:
     * Others: ``None``
     """
 
-    id: str | None
+    id: Optional[str]
     name: str
     arguments: str  # JSON string
-    provider_data: dict[str, Any] | None = field(default=None, repr=False)
+    provider_data: Optional[Dict[str, Any]] = field(default=None, repr=False)
 
     # ── Backward compatibility ──────────────────────────────────
     # The agent loop reads tc.function.name / tc.function.arguments
@@ -47,17 +47,17 @@ class ToolCall:
         return "function"
 
     @property
-    def function(self) -> ToolCall:
+    def function(self) -> "ToolCall":
         """Return self so tc.function.name / tc.function.arguments work."""
         return self
 
     @property
-    def call_id(self) -> str | None:
+    def call_id(self) -> Optional[str]:
         """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:
+    def response_item_id(self) -> Optional[str]:
         """Codex response_item_id from provider_data."""
         return (self.provider_data or {}).get("response_item_id")
 
@@ -101,18 +101,18 @@ class NormalizedResponse:
     * Others: ``None``
     """
 
-    content: str | None
-    tool_calls: list[ToolCall] | None
+    content: Optional[str]
+    tool_calls: Optional[List[ToolCall]]
     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)
+    reasoning: Optional[str] = None
+    usage: Optional[Usage] = None
+    provider_data: Optional[Dict[str, Any]] = 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:
+    def reasoning_content(self) -> Optional[str]:
         pd = self.provider_data or {}
         return pd.get("reasoning_content")
 
@@ -136,9 +136,8 @@ class NormalizedResponse:
 # Factory helpers
 # ---------------------------------------------------------------------------
 
-
 def build_tool_call(
-    id: str | None,
+    id: Optional[str],
     name: str,
     arguments: Any,
     **provider_fields: Any,
@@ -152,7 +151,7 @@ def build_tool_call(
     return ToolCall(id=id, name=name, arguments=args_str, provider_data=pd)
 
 
-def map_finish_reason(reason: str | None, mapping: dict[str, str]) -> str:
+def map_finish_reason(reason: Optional[str], mapping: Dict[str, str]) -> str:
     """Translate a provider-specific stop reason to the normalised set.
 
     Falls back to ``"stop"`` for unknown or ``None`` reasons.

gateway/platforms/base.py

@@ -307,9 +307,14 @@ def proxy_kwargs_for_aiohttp(proxy_url: str | None) -> tuple[dict, dict]:
     """Build kwargs for standalone ``aiohttp.ClientSession`` with proxy.
 
     Returns ``(session_kwargs, request_kwargs)`` where:
-      - SOCKS → ``({"connector": ProxyConnector(...)}, {})``
-      - HTTP  → ``({}, {"proxy": url})``
-      - None  → ``({}, {})``
+      - With aiohttp-socks → ``({"connector": ProxyConnector(...)}, {})``
+        for *all* proxy schemes (SOCKS **and** HTTP/HTTPS).
+      - HTTP without aiohttp-socks → ``({}, {"proxy": url})``.
+      - None → ``({}, {})``.
+
+    Prefer the connector path: it works transparently with libraries
+    (like mautrix) that call ``session.request()`` without forwarding
+    per-request ``proxy=`` kwargs.
 
     Usage::
 
@@ -320,20 +325,20 @@ def proxy_kwargs_for_aiohttp(proxy_url: str | None) -> tuple[dict, dict]:
     """
     if not proxy_url:
         return {}, {}
-    if proxy_url.lower().startswith("socks"):
-        try:
-            from aiohttp_socks import ProxyConnector
+    try:
+        from aiohttp_socks import ProxyConnector
 
-            connector = ProxyConnector.from_url(proxy_url, rdns=True)
-            return {"connector": connector}, {}
-        except ImportError:
+        connector = ProxyConnector.from_url(proxy_url, rdns=True)
+        return {"connector": connector}, {}
+    except ImportError:
+        if proxy_url.lower().startswith("socks"):
             logger.warning(
                 "aiohttp_socks not installed — SOCKS proxy %s ignored. "
                 "Run: pip install aiohttp-socks",
                 proxy_url,
             )
             return {}, {}
-    return {}, {"proxy": proxy_url}
+        return {}, {"proxy": proxy_url}
 
 
 def is_host_excluded_by_no_proxy(hostname: str, no_proxy_value: str | None = None) -> bool:
@@ -2427,11 +2432,15 @@ class BasePlatformAdapter(ABC):
                 # Send the text portion
                 if text_content:
                     logger.info("[%s] Sending response (%d chars) to %s", self.name, len(text_content), event.source.chat_id)
+                    # Build send metadata: thread_id + mention target for platforms that need it
+                    send_metadata = dict(_thread_metadata) if _thread_metadata else {}
+                    if event.source.user_id:
+                        send_metadata["mention_user_id"] = event.source.user_id
                     result = await self._send_with_retry(
                         chat_id=event.source.chat_id,
                         content=text_content,
                         reply_to=event.message_id,
-                        metadata=_thread_metadata,
+                        metadata=send_metadata,
                     )
                     _record_delivery(result)
 

gateway/platforms/matrix.py

@@ -11,6 +11,7 @@ Environment variables:
     MATRIX_PASSWORD             Password (alternative to access token)
     MATRIX_ENCRYPTION           Set "true" to enable E2EE
     MATRIX_DEVICE_ID            Stable device ID for E2EE persistence across restarts
+    MATRIX_PROXY                HTTP(S) or SOCKS proxy URL for Matrix traffic
     MATRIX_ALLOWED_USERS    Comma-separated Matrix user IDs (@user:server)
     MATRIX_HOME_ROOM        Room ID for cron/notification delivery
     MATRIX_REACTIONS        Set "false" to disable processing lifecycle reactions
@@ -18,6 +19,7 @@ Environment variables:
     MATRIX_REQUIRE_MENTION      Require @mention in rooms (default: true)
     MATRIX_FREE_RESPONSE_ROOMS  Comma-separated room IDs exempt from mention requirement
     MATRIX_AUTO_THREAD          Auto-create threads for room messages (default: true)
+    MATRIX_DM_AUTO_THREAD       Auto-create threads for DM messages (default: false)
     MATRIX_RECOVERY_KEY         Recovery key for cross-signing verification after device key rotation
     MATRIX_DM_MENTION_THREADS   Create a thread when bot is @mentioned in a DM (default: false)
 """
@@ -30,6 +32,8 @@ import mimetypes
 import os
 import re
 import time
+from dataclasses import dataclass
+
 from html import escape as _html_escape
 from pathlib import Path
 from typing import Any, Dict, Optional, Set
@@ -95,11 +99,25 @@ from gateway.platforms.base import (
     MessageType,
     ProcessingOutcome,
     SendResult,
+    resolve_proxy_url,
+    proxy_kwargs_for_aiohttp,
 )
 from gateway.platforms.helpers import ThreadParticipationTracker
 
 logger = logging.getLogger(__name__)
 
+
+@dataclass
+class _MatrixApprovalPrompt:
+    """Tracks a pending Matrix reaction-based exec approval prompt."""
+
+    def __init__(self, session_key: str, chat_id: str, message_id: str, resolved: bool = False):
+        self.session_key = session_key
+        self.chat_id = chat_id
+        self.message_id = message_id
+        self.resolved = resolved
+        self.bot_reaction_events: dict[str, str] = {}  # emoji -> event_id
+
 # Matrix message size limit (4000 chars practical, spec has no hard limit
 # but clients render poorly above this).
 MAX_MESSAGE_LENGTH = 4000
@@ -114,11 +132,85 @@ _CRYPTO_DB_PATH = _STORE_DIR / "crypto.db"
 # Grace period: ignore messages older than this many seconds before startup.
 _STARTUP_GRACE_SECONDS = 5
 
+_OUTBOUND_MENTION_RE = re.compile(
+    r"(?<![\w/])(@[0-9A-Za-z._=/-]+:[0-9A-Za-z.-]+(?::\d+)?)"
+)
 
 _E2EE_INSTALL_HINT = (
     "Install with: pip install 'mautrix[encryption]'  (requires libolm C library)"
 )
 
+_MATRIX_IMAGE_FILENAME_EXTS = frozenset({
+    ".jpg",
+    ".jpeg",
+    ".png",
+    ".gif",
+    ".webp",
+    ".bmp",
+    ".svg",
+    ".heic",
+    ".heif",
+    ".avif",
+})
+
+
+def _looks_like_matrix_image_filename(text: str) -> bool:
+    """Return True when Matrix image body text is probably just a transport filename.
+
+    Matrix ``m.image`` events commonly populate ``content.body`` with the uploaded
+    filename when the user did not add a caption. Treating that raw filename as
+    user-authored text confuses downstream vision enrichment.
+    """
+    candidate = str(text or "").strip()
+    if not candidate or "\n" in candidate or candidate.endswith("/"):
+        return False
+
+    name = Path(candidate).name
+    if not name or name != candidate:
+        return False
+
+    suffix = Path(name).suffix.lower()
+    if not suffix:
+        return False
+
+    guessed_type, _ = mimetypes.guess_type(name)
+    if guessed_type and guessed_type.startswith("image/"):
+        return True
+    return suffix in _MATRIX_IMAGE_FILENAME_EXTS
+
+
+def _create_matrix_session(proxy_url: str | None):
+    """Create an ``aiohttp.ClientSession`` whose proxy applies to *all* requests.
+
+    mautrix's ``HTTPAPI._send()`` calls ``session.request()`` without forwarding
+    per-request ``proxy=`` kwargs.  For HTTP(S) proxies we use aiohttp's native
+    ``proxy=`` session parameter which sets a default for every request.  For SOCKS
+    we use ``aiohttp_socks.ProxyConnector`` (connector-level).
+    When no proxy is configured we enable ``trust_env`` so standard env vars
+    (``HTTP_PROXY`` / ``HTTPS_PROXY``) are honoured automatically.
+    """
+    import aiohttp
+
+    if not proxy_url:
+        return aiohttp.ClientSession(trust_env=True)
+
+    if proxy_url.split("://")[0].lower().startswith("socks"):
+        try:
+            from aiohttp_socks import ProxyConnector
+
+            return aiohttp.ClientSession(
+                connector=ProxyConnector.from_url(proxy_url, rdns=True),
+            )
+        except ImportError:
+            logger.warning(
+                "aiohttp_socks not installed — SOCKS proxy %s ignored. "
+                "Run: pip install aiohttp-socks",
+                proxy_url,
+            )
+            return aiohttp.ClientSession(trust_env=True)
+
+    return aiohttp.ClientSession(proxy=proxy_url)
+
 
 def _check_e2ee_deps() -> bool:
     """Return True if mautrix E2EE dependencies (python-olm) are available."""
@@ -260,6 +352,9 @@ class MatrixAdapter(BasePlatformAdapter):
             "1",
             "yes",
         )
+        self._dm_auto_thread: bool = os.getenv(
+            "MATRIX_DM_AUTO_THREAD", "false"
+        ).lower() in ("true", "1", "yes")
         self._dm_mention_threads: bool = os.getenv(
             "MATRIX_DM_MENTION_THREADS", "false"
         ).lower() in ("true", "1", "yes")
@@ -270,6 +365,11 @@ class MatrixAdapter(BasePlatformAdapter):
         ).lower() not in ("false", "0", "no")
         self._pending_reactions: dict[tuple[str, str], str] = {}
 
+        # Proxy support — resolve once at init, reuse for all HTTP traffic.
+        self._proxy_url: str | None = resolve_proxy_url(platform_env_var="MATRIX_PROXY")
+        if self._proxy_url:
+            logger.info("Matrix: proxy configured — %s", self._proxy_url)
+
         # Text batching: merge rapid successive messages (Telegram-style).
         # Matrix clients split long messages around 4000 chars.
         self._text_batch_delay_seconds = float(
@@ -281,6 +381,18 @@ class MatrixAdapter(BasePlatformAdapter):
         self._pending_text_batches: Dict[str, MessageEvent] = {}
         self._pending_text_batch_tasks: Dict[str, asyncio.Task] = {}
 
+        # Matrix reaction-based dangerous command approvals.
+        self._approval_reaction_map = {
+            "✅": "once",
+            "❎": "deny",
+        }
+        self._approval_prompts_by_event: Dict[str, _MatrixApprovalPrompt] = {}
+        self._approval_prompt_by_session: Dict[str, str] = {}
+        allowed_users_raw = os.getenv("MATRIX_ALLOWED_USERS", "")
+        self._allowed_user_ids: Set[str] = {
+            u.strip() for u in allowed_users_raw.split(",") if u.strip()
+        }
+
     def _is_duplicate_event(self, event_id) -> bool:
         """Return True if this event was already processed. Tracks the ID otherwise."""
         if not event_id:
@@ -326,7 +438,7 @@ class MatrixAdapter(BasePlatformAdapter):
                     )
                     return False
         except Exception as exc:
-            logger.error("Matrix: post-upload key verification failed: %s", exc)
+            logger.error("Matrix: post-upload key verification failed: %s", exc, exc_info=True)
             return False
         return True
 
@@ -342,6 +454,7 @@ class MatrixAdapter(BasePlatformAdapter):
             logger.error(
                 "Matrix: cannot verify device keys on server: %s — refusing E2EE",
                 exc,
+                exc_info=True,
             )
             return False
 
@@ -356,7 +469,7 @@ class MatrixAdapter(BasePlatformAdapter):
             try:
                 await olm.share_keys()
             except Exception as exc:
-                logger.error("Matrix: failed to re-upload device keys: %s", exc)
+                logger.error("Matrix: failed to re-upload device keys: %s", exc, exc_info=True)
                 return False
             return await self._reverify_keys_after_upload(client, local_ed25519)
 
@@ -396,6 +509,7 @@ class MatrixAdapter(BasePlatformAdapter):
                     "Try generating a new access token to get a fresh device.",
                     client.device_id,
                     exc,
+                    exc_info=True,
                 )
                 return False
             return await self._reverify_keys_after_upload(client, local_ed25519)
@@ -420,9 +534,11 @@ class MatrixAdapter(BasePlatformAdapter):
         _STORE_DIR.mkdir(parents=True, exist_ok=True)
 
         # Create the HTTP API layer.
+        client_session = _create_matrix_session(self._proxy_url)
         api = HTTPAPI(
             base_url=self._homeserver,
             token=self._access_token or "",
+            client_session=client_session,
         )
 
         # Create the client.
@@ -465,6 +581,7 @@ class MatrixAdapter(BasePlatformAdapter):
                 logger.error(
                     "Matrix: whoami failed — check MATRIX_ACCESS_TOKEN and MATRIX_HOMESERVER: %s",
                     exc,
+                    exc_info=True,
                 )
                 await api.session.close()
                 return False
@@ -607,6 +724,44 @@ class MatrixAdapter(BasePlatformAdapter):
                         logger.warning(
                             "Matrix: recovery key verification failed: %s", exc
                         )
+                else:
+                    # No recovery key — bootstrap cross-signing if the bot
+                    # has none yet. Without this, Element shows "Encrypted
+                    # by a device not verified by its owner" on every
+                    # message from this bot, indefinitely. mautrix's
+                    # generate_recovery_key does the full flow: generates
+                    # MSK/SSK/USK, uploads private keys to SSSS, publishes
+                    # public keys to the homeserver, and signs the current
+                    # device with the new SSK. Some homeservers require UIA
+                    # for /keys/device_signing/upload — those will need an
+                    # alternate path; Continuwuity and Synapse-with-shared-
+                    # secret accept the unauthenticated upload.
+                    try:
+                        own_xsign = await olm.get_own_cross_signing_public_keys()
+                    except Exception as exc:
+                        own_xsign = None
+                        logger.warning(
+                            "Matrix: cross-signing key lookup failed: %s", exc
+                        )
+                    if own_xsign is None:
+                        try:
+                            new_recovery_key = await olm.generate_recovery_key()
+                            logger.warning(
+                                "Matrix: bootstrapped cross-signing for %s. "
+                                "SAVE THIS RECOVERY KEY — set "
+                                "MATRIX_RECOVERY_KEY for future restarts so "
+                                "the bot can re-sign its device after key "
+                                "rotation: %s",
+                                client.mxid,
+                                new_recovery_key,
+                            )
+                        except Exception as exc:
+                            logger.warning(
+                                "Matrix: cross-signing bootstrap failed "
+                                "(non-fatal — Element will show 'not "
+                                "verified by its owner'): %s",
+                                exc,
+                            )
 
                 client.crypto = olm
                 logger.info(
@@ -664,6 +819,7 @@ class MatrixAdapter(BasePlatformAdapter):
                         await asyncio.gather(*tasks)
                 except Exception as exc:
                     logger.warning("Matrix: initial sync event dispatch error: %s", exc)
+                await self._join_pending_invites(sync_data)
             else:
                 logger.warning(
                     "Matrix: initial sync returned unexpected type %s",
@@ -723,21 +879,32 @@ class MatrixAdapter(BasePlatformAdapter):
         if not content:
             return SendResult(success=True)
 
+        mention_user_id = (metadata or {}).get("mention_user_id")
+
         formatted = self.format_message(content)
         chunks = self.truncate_message(formatted, MAX_MESSAGE_LENGTH)
 
         last_event_id = None
-        for chunk in chunks:
-            msg_content: Dict[str, Any] = {
-                "msgtype": "m.text",
-                "body": chunk,
-            }
+        for i, chunk in enumerate(chunks):
+            msg_content = self._build_text_message_content(chunk)
 
-            # Convert markdown to HTML for rich rendering.
-            html = self._markdown_to_html(chunk)
-            if html and html != chunk:
+            # Append @mention pill to the last chunk for push notifications
+            # in muted rooms (mention-only mode).
+            if mention_user_id and i == len(chunks) - 1:
+                mention_html = (
+                    f'<a href="https://matrix.to/#/{mention_user_id}">'
+                    f"{mention_user_id}</a>"
+                )
+                msg_content["body"] = chunk + f" @{mention_user_id}"
+                base_html = msg_content.get("formatted_body", chunk)
                 msg_content["format"] = "org.matrix.custom.html"
-                msg_content["formatted_body"] = html
+                msg_content["formatted_body"] = base_html + " " + mention_html
+                # m.mentions for MSC3952 push reliability.
+                existing_mentions = msg_content.get("m.mentions", {}).get("user_ids", [])
+                if mention_user_id not in existing_mentions:
+                    msg_content["m.mentions"] = {
+                        "user_ids": existing_mentions + [mention_user_id]
+                    }
 
             # Reply-to support.
             if reply_to:
@@ -844,25 +1011,21 @@ class MatrixAdapter(BasePlatformAdapter):
         """Edit an existing message (via m.replace)."""
 
         formatted = self.format_message(content)
+        new_content = self._build_text_message_content(formatted)
         msg_content: Dict[str, Any] = {
             "msgtype": "m.text",
             "body": f"* {formatted}",
-            "m.new_content": {
-                "msgtype": "m.text",
-                "body": formatted,
-            },
-            "m.relates_to": {
-                "rel_type": "m.replace",
-                "event_id": message_id,
-            },
+            "m.new_content": new_content,
         }
-
-        html = self._markdown_to_html(formatted)
-        if html and html != formatted:
-            msg_content["m.new_content"]["format"] = "org.matrix.custom.html"
-            msg_content["m.new_content"]["formatted_body"] = html
+        if "m.mentions" in new_content:
+            msg_content["m.mentions"] = new_content["m.mentions"]
+        if "formatted_body" in new_content:
             msg_content["format"] = "org.matrix.custom.html"
-            msg_content["formatted_body"] = f"* {html}"
+            msg_content["formatted_body"] = f'* {new_content["formatted_body"]}'
+        msg_content["m.relates_to"] = {
+            "rel_type": "m.replace",
+            "event_id": message_id,
+        }
 
         try:
             event_id = await self._client.send_message_event(
@@ -895,10 +1058,12 @@ class MatrixAdapter(BasePlatformAdapter):
             # Try aiohttp first (always available), fall back to httpx
             try:
                 import aiohttp as _aiohttp
-
-                async with _aiohttp.ClientSession(trust_env=True) as http:
+                _sess_kw, _req_kw = proxy_kwargs_for_aiohttp(self._proxy_url)
+                async with _aiohttp.ClientSession(**_sess_kw) as http:
                     async with http.get(
-                        image_url, timeout=_aiohttp.ClientTimeout(total=30)
+                        image_url,
+                        timeout=_aiohttp.ClientTimeout(total=30),
+                        **_req_kw,
                     ) as resp:
                         resp.raise_for_status()
                         data = await resp.read()
@@ -908,8 +1073,10 @@ class MatrixAdapter(BasePlatformAdapter):
                         )
             except ImportError:
                 import httpx
-
-                async with httpx.AsyncClient() as http:
+                _httpx_kw: dict = {}
+                if self._proxy_url:
+                    _httpx_kw["proxy"] = self._proxy_url
+                async with httpx.AsyncClient(**_httpx_kw) as http:
                     resp = await http.get(image_url, follow_redirects=True, timeout=30)
                     resp.raise_for_status()
                     data = resp.content
@@ -984,6 +1151,56 @@ class MatrixAdapter(BasePlatformAdapter):
             chat_id, video_path, "m.video", caption, reply_to, metadata=metadata
         )
 
+    async def send_exec_approval(
+        self,
+        chat_id: str,
+        command: str,
+        session_key: str,
+        description: str = "dangerous command",
+        metadata: Optional[dict] = None,
+    ) -> SendResult:
+        """Send a reaction-based exec approval prompt for Matrix."""
+        if not self._client:
+            return SendResult(success=False, error="Not connected")
+
+        cmd_preview = command[:2000] + "..." if len(command) > 2000 else command
+        text = (
+            "⚠️ **Dangerous command requires approval**\n"
+            f"```\n{cmd_preview}\n```\n"
+            f"Reason: {description}\n\n"
+            "Reply `/approve` to execute, `/approve session` to approve this pattern for the session, "
+            "`/approve always` to approve permanently, or `/deny` to cancel.\n\n"
+            "You can also click the reaction to approve:\n"
+            "✅ = /approve\n"
+            "❎ = /deny"
+        )
+
+        result = await self.send(chat_id, text, metadata=metadata)
+        if not result.success or not result.message_id:
+            return result
+
+        prompt = _MatrixApprovalPrompt(
+            session_key=session_key,
+            chat_id=chat_id,
+            message_id=result.message_id,
+        )
+        old_event = self._approval_prompt_by_session.get(session_key)
+        if old_event:
+            self._approval_prompts_by_event.pop(old_event, None)
+        self._approval_prompts_by_event[result.message_id] = prompt
+        self._approval_prompt_by_session[session_key] = result.message_id
+
+        for emoji in ("✅", "❎"):
+            try:
+                reaction_result = await self._send_reaction(chat_id, result.message_id, emoji)
+                # Save the bot's reaction event_id for later cleanup
+                if reaction_result:
+                    prompt.bot_reaction_events[emoji] = str(reaction_result)
+            except Exception as exc:
+                logger.debug("Matrix: failed to add approval reaction %s: %s", emoji, exc)
+
+        return result
+
     def format_message(self, content: str) -> str:
         """Pass-through — Matrix supports standard Markdown natively."""
         # Strip image markdown; media is uploaded separately.
@@ -1115,9 +1332,15 @@ class MatrixAdapter(BasePlatformAdapter):
         next_batch = await client.sync_store.get_next_batch()
         while not self._closing:
             try:
-                sync_data = await client.sync(
-                    since=next_batch,
-                    timeout=30000,
+                # Wrap in asyncio.wait_for to guard against TCP-level hangs
+                # that the Matrix long-poll timeout cannot catch. Long-poll
+                # is 30s, so 45s gives 15s slack for network drain.
+                sync_data = await asyncio.wait_for(
+                    client.sync(
+                        since=next_batch,
+                        timeout=30000,
+                    ),
+                    timeout=45.0,
                 )
 
                 # nio returns SyncError objects (not exceptions) for auth
@@ -1153,6 +1376,7 @@ class MatrixAdapter(BasePlatformAdapter):
                             await asyncio.gather(*tasks)
                     except Exception as exc:
                         logger.warning("Matrix: sync event dispatch error: %s", exc)
+                    await self._join_pending_invites(sync_data)
 
             except asyncio.CancelledError:
                 return
@@ -1239,6 +1463,15 @@ class MatrixAdapter(BasePlatformAdapter):
         room_id = str(getattr(event, "room_id", ""))
         sender = str(getattr(event, "sender", ""))
 
+        # Diagnostic: confirm the callback is firing at all when DEBUG is on.
+        # Helps users troubleshoot silent inbound issues like #5819, #7914, #12614.
+        logger.debug(
+            "Matrix: callback fired — event %s from %s in %s",
+            getattr(event, "event_id", "?"),
+            sender,
+            room_id,
+        )
+
         # Ignore own messages (case-insensitive; also drops when our own
         # user_id hasn't been resolved yet — see _is_self_sender docstring
         # and issue #15763).
@@ -1350,6 +1583,12 @@ class MatrixAdapter(BasePlatformAdapter):
             in_bot_thread = bool(thread_id and thread_id in self._threads)
             if self._require_mention and not is_free_room and not in_bot_thread:
                 if not is_mentioned:
+                    logger.debug(
+                        "Matrix: ignoring message %s in %s — no @mention "
+                        "(set MATRIX_REQUIRE_MENTION=false to disable)",
+                        event_id,
+                        room_id,
+                    )
                     return None
 
         # DM mention-thread.
@@ -1362,7 +1601,7 @@ class MatrixAdapter(BasePlatformAdapter):
             body = self._strip_mention(body)
 
         # Auto-thread.
-        if not is_dm and not thread_id and self._auto_thread:
+        if not thread_id and ((not is_dm and self._auto_thread) or (is_dm and self._dm_auto_thread)):
             thread_id = event_id
             self._threads.mark(thread_id)
 
@@ -1604,6 +1843,9 @@ class MatrixAdapter(BasePlatformAdapter):
             return
         body, is_dm, chat_type, thread_id, display_name, source = ctx
 
+        if msgtype == "m.image" and _looks_like_matrix_image_filename(body):
+            body = ""
+
         allow_http_fallback = bool(http_url) and not is_encrypted_media
         media_urls = (
             [cached_path]
@@ -1633,13 +1875,35 @@ class MatrixAdapter(BasePlatformAdapter):
             "Matrix: invited to %s — joining",
             room_id,
         )
+        await self._join_room_by_id(room_id)
+
+    async def _join_room_by_id(self, room_id: str) -> bool:
+        """Join a room by ID and refresh local caches on success."""
+        if not room_id:
+            return False
+        if room_id in self._joined_rooms:
+            return True
         try:
             await self._client.join_room(RoomID(room_id))
             self._joined_rooms.add(room_id)
             logger.info("Matrix: joined %s", room_id)
             await self._refresh_dm_cache()
+            return True
         except Exception as exc:
             logger.warning("Matrix: error joining %s: %s", room_id, exc)
+            return False
+
+    async def _join_pending_invites(self, sync_data: Dict[str, Any]) -> None:
+        """Join rooms still present in rooms.invite after sync processing."""
+        rooms = sync_data.get("rooms", {}) if isinstance(sync_data, dict) else {}
+        invites = rooms.get("invite", {})
+        if not isinstance(invites, dict):
+            return
+        for room_id in invites:
+            if room_id in self._joined_rooms:
+                continue
+            logger.info("Matrix: reconciling pending invite for %s", room_id)
+            await self._join_room_by_id(str(room_id))
 
     # ------------------------------------------------------------------
     # Reactions (send, receive, processing lifecycle)
@@ -1754,6 +2018,51 @@ class MatrixAdapter(BasePlatformAdapter):
                 room_id,
             )
 
+            # Check if this reaction resolves a pending approval prompt.
+            prompt = self._approval_prompts_by_event.get(reacts_to)
+            if prompt and not prompt.resolved:
+                if room_id != prompt.chat_id:
+                    return
+                if self._allowed_user_ids and sender not in self._allowed_user_ids:
+                    logger.info(
+                        "Matrix: ignoring approval reaction from unauthorized user %s on %s",
+                        sender, reacts_to,
+                    )
+                    return
+                choice = self._approval_reaction_map.get(key)
+                if not choice:
+                    return
+                try:
+                    from tools.approval import resolve_gateway_approval
+
+                    count = resolve_gateway_approval(prompt.session_key, choice)
+                    if count:
+                        prompt.resolved = True
+                        self._approval_prompts_by_event.pop(reacts_to, None)
+                        self._approval_prompt_by_session.pop(prompt.session_key, None)
+                        logger.info(
+                            "Matrix reaction resolved %d approval(s) for session %s "
+                            "(choice=%s, user=%s)",
+                            count, prompt.session_key, choice, sender,
+                        )
+                        # Redact bot's seed reactions, leaving only the user's
+                        await self._redact_bot_approval_reactions(room_id, prompt)
+                except Exception as exc:
+                    logger.error("Failed to resolve gateway approval from Matrix reaction: %s", exc)
+
+    async def _redact_bot_approval_reactions(
+        self,
+        room_id: str,
+        prompt: "_MatrixApprovalPrompt",
+    ) -> None:
+        """Redact the bot's seed ✅/❎ reactions, leaving only the user's reaction."""
+        for emoji, evt_id in prompt.bot_reaction_events.items():
+            try:
+                await self.redact_message(room_id, evt_id, "approval resolved")
+                logger.debug("Matrix: redacted bot reaction %s (%s)", emoji, evt_id)
+            except Exception as exc:
+                logger.debug("Matrix: failed to redact bot reaction %s: %s", emoji, exc)
+
     # ------------------------------------------------------------------
     # Text message aggregation (handles Matrix client-side splits)
     # ------------------------------------------------------------------
@@ -1979,11 +2288,7 @@ class MatrixAdapter(BasePlatformAdapter):
         if not self._client or not text:
             return SendResult(success=False, error="No client or empty text")
 
-        msg_content: Dict[str, Any] = {"msgtype": msgtype, "body": text}
-        html = self._markdown_to_html(text)
-        if html and html != text:
-            msg_content["format"] = "org.matrix.custom.html"
-            msg_content["formatted_body"] = html
+        msg_content = self._build_text_message_content(text, msgtype=msgtype)
 
         try:
             event_id = await self._client.send_message_event(
@@ -2046,6 +2351,77 @@ class MatrixAdapter(BasePlatformAdapter):
     # Mention detection helpers
     # ------------------------------------------------------------------
 
+    def _build_text_message_content(self, text: str, msgtype: str = "m.text") -> Dict[str, Any]:
+        """Build Matrix text content with HTML and outbound mention metadata."""
+        msg_content: Dict[str, Any] = {"msgtype": msgtype, "body": text}
+        mention_user_ids = self._extract_outbound_mentions(text)
+        if mention_user_ids:
+            msg_content["m.mentions"] = {"user_ids": mention_user_ids}
+
+        html_source = self._inject_outbound_mention_links(text)
+        html = self._markdown_to_html(html_source)
+        if html and html != text:
+            msg_content["format"] = "org.matrix.custom.html"
+            msg_content["formatted_body"] = html
+
+        return msg_content
+
+    def _extract_outbound_mentions(self, text: str) -> list[str]:
+        """Return unique Matrix user IDs mentioned in outbound text."""
+        protected, _ = self._protect_outbound_mention_regions(text)
+        seen: Set[str] = set()
+        mentions: list[str] = []
+        for match in _OUTBOUND_MENTION_RE.finditer(protected):
+            user_id = match.group(1)
+            if user_id not in seen:
+                seen.add(user_id)
+                mentions.append(user_id)
+        return mentions
+
+    def _inject_outbound_mention_links(self, text: str) -> str:
+        """Wrap outbound Matrix mentions in markdown links outside code spans."""
+        if not text:
+            return text
+
+        protected, placeholders = self._protect_outbound_mention_regions(text)
+
+        linked = _OUTBOUND_MENTION_RE.sub(
+            lambda match: f"[{match.group(1)}](https://matrix.to/#/{match.group(1)})",
+            protected,
+        )
+
+        for idx, original in enumerate(placeholders):
+            linked = linked.replace(f"\x00MENTION_PROTECTED{idx}\x00", original)
+
+        return linked
+
+    def _protect_outbound_mention_regions(self, text: str) -> tuple[str, list[str]]:
+        """Protect markdown regions where outbound mentions should stay literal."""
+        placeholders: list[str] = []
+
+        def _protect(fragment: str) -> str:
+            idx = len(placeholders)
+            placeholders.append(fragment)
+            return f"\x00MENTION_PROTECTED{idx}\x00"
+
+        protected = re.sub(
+            r"```[\s\S]*?```",
+            lambda match: _protect(match.group(0)),
+            text or "",
+        )
+        protected = re.sub(
+            r"`[^`\n]+`",
+            lambda match: _protect(match.group(0)),
+            protected,
+        )
+        protected = re.sub(
+            r"\[[^\]]+\]\([^)]+\)",
+            lambda match: _protect(match.group(0)),
+            protected,
+        )
+
+        return protected, placeholders
+
     def _is_bot_mentioned(
         self,
         body: str,
@@ -2080,13 +2456,33 @@ class MatrixAdapter(BasePlatformAdapter):
         return False
 
     def _strip_mention(self, body: str) -> str:
-        """Strip the bot's full MXID (``@user:server``) from *body*.
+        """Remove explicit bot mentions from message body.
 
-        The bare localpart is intentionally *not* stripped — it would
-        mangle file paths like ``/home/hermes/media/file.png``.
+        Important: only strip explicit mention tokens (``@user:server`` or
+        ``@localpart``). Do NOT strip bare words matching the bot localpart,
+        otherwise normal phrases like "Hermes Agent" become "Agent".
         """
+        if not body:
+            return ""
+
+        # Strip explicit full MXID mentions.
         if self._user_id:
             body = body.replace(self._user_id, "")
+
+        # Strip explicit @localpart mentions only (not bare localpart words).
+        if self._user_id and ":" in self._user_id:
+            localpart = self._user_id.split(":")[0].lstrip("@")
+            if localpart:
+                body = re.sub(
+                    r'(?<![\w])@' + re.escape(localpart) + r'\b',
+                    '',
+                    body,
+                    flags=re.IGNORECASE,
+                )
+
+        # Normalize spacing after mention removal.
+        body = re.sub(r'[ \t]{2,}', ' ', body)
+        body = re.sub(r'\s+([,.;:!?])', r'\1', body)
         return body.strip()
 
     async def _get_display_name(self, room_id: str, user_id: str) -> str:

gateway/run.py

@@ -10041,7 +10041,7 @@ class GatewayRunner:
         # Bridge sync status_callback → async adapter.send for context pressure
         _status_adapter = self.adapters.get(source.platform)
         _status_chat_id = source.chat_id
-        _status_thread_metadata = {"thread_id": _progress_thread_id} if _progress_thread_id else None
+        _status_thread_metadata = {"thread_id": _progress_thread_id, "mention_user_id": source.user_id} if _progress_thread_id else {"mention_user_id": source.user_id}
 
         def _status_callback_sync(event_type: str, message: str) -> None:
             if not _status_adapter or not _run_still_current():

hermes_cli/auth.py

@@ -374,37 +374,6 @@ PROVIDER_REGISTRY: Dict[str, ProviderConfig] = {
     ),
 }
 
-# Auto-extend PROVIDER_REGISTRY with any api-key provider registered in
-# providers/ that is not already declared above.  New providers only need a
-# providers/*.py file — no edits to this file required.
-try:
-    from providers import list_providers as _list_providers_for_registry
-    for _pp in _list_providers_for_registry():
-        if _pp.name in PROVIDER_REGISTRY:
-            continue
-        if _pp.auth_type != "api_key" or not _pp.env_vars:
-            continue
-        # Skip providers that need custom token resolution (copilot, kimi, zai)
-        # — those are already fully declared above.
-        if _pp.name in {"copilot", "kimi-coding", "kimi-coding-cn", "zai"}:
-            continue
-        _api_key_vars = tuple(v for v in _pp.env_vars if not v.endswith("_BASE_URL") and not v.endswith("_URL"))
-        _base_url_var = next((v for v in _pp.env_vars if v.endswith("_BASE_URL") or v.endswith("_URL")), None)
-        PROVIDER_REGISTRY[_pp.name] = ProviderConfig(
-            id=_pp.name,
-            name=_pp.display_name or _pp.name,
-            auth_type="api_key",
-            inference_base_url=_pp.base_url,
-            api_key_env_vars=_api_key_vars or _pp.env_vars,
-            base_url_env_var=_base_url_var or "",
-        )
-        # Also register aliases so resolve_provider() resolves them
-        for _alias in _pp.aliases:
-            if _alias not in PROVIDER_REGISTRY:
-                PROVIDER_REGISTRY[_alias] = PROVIDER_REGISTRY[_pp.name]
-except Exception:
-    pass
-
 
 # =============================================================================
 # Anthropic Key Helper
@@ -1181,17 +1150,6 @@ def resolve_provider(
         "vllm": "custom", "llamacpp": "custom",
         "llama.cpp": "custom", "llama-cpp": "custom",
     }
-    # Extend with aliases declared in providers/*.py that aren't already mapped.
-    # This keeps providers/ as the single source for new aliases while the
-    # hardcoded dict above remains authoritative for existing ones.
-    try:
-        from providers import list_providers as _lp
-        for _pp in _lp():
-            for _alias in _pp.aliases:
-                if _alias not in _PROVIDER_ALIASES:
-                    _PROVIDER_ALIASES[_alias] = _pp.name
-    except Exception:
-        pass
     normalized = _PROVIDER_ALIASES.get(normalized, normalized)
 
     if normalized == "openrouter":

hermes_cli/config.py

@@ -56,8 +56,18 @@ _EXTRA_ENV_KEYS = frozenset({
     "WHATSAPP_MODE", "WHATSAPP_ENABLED",
     "MATTERMOST_HOME_CHANNEL", "MATTERMOST_REPLY_MODE",
     "MATRIX_PASSWORD", "MATRIX_ENCRYPTION", "MATRIX_DEVICE_ID", "MATRIX_HOME_ROOM",
-    "MATRIX_REQUIRE_MENTION", "MATRIX_FREE_RESPONSE_ROOMS", "MATRIX_AUTO_THREAD",
+    "MATRIX_REQUIRE_MENTION", "MATRIX_FREE_RESPONSE_ROOMS", "MATRIX_AUTO_THREAD", "MATRIX_DM_AUTO_THREAD",
     "MATRIX_RECOVERY_KEY",
+    # Langfuse observability plugin — optional tuning keys + standard SDK vars
+    "HERMES_LANGFUSE_ENABLED",   # backward-compat env var (new: plugins.langfuse.enabled in config.yaml)
+    "HERMES_LANGFUSE_ENV",
+    "HERMES_LANGFUSE_RELEASE",
+    "HERMES_LANGFUSE_SAMPLE_RATE",
+    "HERMES_LANGFUSE_MAX_CHARS",
+    "HERMES_LANGFUSE_DEBUG",
+    "LANGFUSE_PUBLIC_KEY",
+    "LANGFUSE_SECRET_KEY",
+    "LANGFUSE_BASE_URL",
 })
 import yaml
 
@@ -942,7 +952,7 @@ DEFAULT_CONFIG = {
     # Pre-exec security scanning via tirith
     "security": {
         "allow_private_urls": False,  # Allow requests to private/internal IPs (for OpenWrt, proxies, VPNs)
-        "redact_secrets": True,
+        "redact_secrets": False,
         "tirith_enabled": True,
         "tirith_path": "tirith",
         "tirith_timeout": 5,
@@ -1692,6 +1702,30 @@ OPTIONAL_ENV_VARS = {
         "category": "tool",
     },
 
+    # ── Langfuse observability ──
+    "HERMES_LANGFUSE_PUBLIC_KEY": {
+        "description": "Langfuse project public key (pk-lf-...)",
+        "prompt": "Langfuse public key",
+        "url": "https://cloud.langfuse.com",
+        "password": False,
+        "category": "tool",
+    },
+    "HERMES_LANGFUSE_SECRET_KEY": {
+        "description": "Langfuse project secret key (sk-lf-...)",
+        "prompt": "Langfuse secret key",
+        "url": "https://cloud.langfuse.com",
+        "password": True,
+        "category": "tool",
+    },
+    "HERMES_LANGFUSE_BASE_URL": {
+        "description": "Langfuse server URL (default: https://cloud.langfuse.com)",
+        "prompt": "Langfuse server URL (leave empty for cloud.langfuse.com)",
+        "url": None,
+        "password": False,
+        "category": "tool",
+        "advanced": True,
+    },
+
     # ── Messaging platforms ──
     "TELEGRAM_BOT_TOKEN": {
         "description": "Telegram bot token from @BotFather",
@@ -1839,6 +1873,14 @@ OPTIONAL_ENV_VARS = {
         "category": "messaging",
         "advanced": True,
     },
+    "MATRIX_DM_AUTO_THREAD": {
+        "description": "Auto-create threads for DM messages in Matrix (default: false)",
+        "prompt": "Auto-create threads in DMs (true/false)",
+        "url": None,
+        "password": False,
+        "category": "messaging",
+        "advanced": True,
+    },
     "MATRIX_DEVICE_ID": {
         "description": "Stable Matrix device ID for E2EE persistence across restarts (e.g. HERMES_BOT)",
         "prompt": "Matrix device ID (stable across restarts)",
@@ -3353,14 +3395,16 @@ def load_config() -> Dict[str, Any]:
 
 _SECURITY_COMMENT = """
 # ── Security ──────────────────────────────────────────────────────────
-# API keys, tokens, and passwords are redacted from tool output by default.
-# Set to false to see full values (useful for debugging auth issues).
+# Secret redaction is OFF by default — tool output (terminal stdout,
+# read_file results, web content) passes through unmodified. Set
+# redact_secrets to true to mask strings that look like API keys, tokens,
+# and passwords before they enter the model context and logs.
 # tirith pre-exec scanning is enabled by default when the tirith binary
 # is available. Configure via security.tirith_* keys or env vars
 # (TIRITH_ENABLED, TIRITH_BIN, TIRITH_TIMEOUT, TIRITH_FAIL_OPEN).
 #
 # security:
-#   redact_secrets: false
+#   redact_secrets: true
 #   tirith_enabled: true
 #   tirith_path: "tirith"
 #   tirith_timeout: 5
@@ -3393,11 +3437,11 @@ _FALLBACK_COMMENT = """
 
 _COMMENTED_SECTIONS = """
 # ── Security ──────────────────────────────────────────────────────────
-# API keys, tokens, and passwords are redacted from tool output by default.
-# Set to false to see full values (useful for debugging auth issues).
+# Secret redaction is OFF by default. Set to true to mask strings that
+# look like API keys, tokens, and passwords in tool output and logs.
 #
 # security:
-#   redact_secrets: false
+#   redact_secrets: true
 
 # ── Fallback Model ────────────────────────────────────────────────────
 # Automatic provider failover when primary is unavailable.
@@ -4252,45 +4296,3 @@ def config_command(args):
         print("  hermes config path      Show config file path")
         print("  hermes config env-path  Show .env file path")
         sys.exit(1)
-
-
-# ── Profile-driven env var injection ─────────────────────────────────────────
-# Any provider registered in providers/ with auth_type="api_key" automatically
-# gets its env_vars exposed in OPTIONAL_ENV_VARS without editing this file.
-# Runs once at import time.
-
-_profile_env_vars_injected = False
-
-
-def _inject_profile_env_vars() -> None:
-    """Populate OPTIONAL_ENV_VARS from provider profiles not already listed.
-
-    Called once at module load time. Idempotent — repeated calls are no-ops.
-    """
-    global _profile_env_vars_injected
-    if _profile_env_vars_injected:
-        return
-    _profile_env_vars_injected = True
-    try:
-        from providers import list_providers
-        for _pp in list_providers():
-            if _pp.auth_type not in ("api_key",):
-                continue
-            for _var in _pp.env_vars:
-                if _var in OPTIONAL_ENV_VARS:
-                    continue
-                _is_key = not _var.endswith("_BASE_URL") and not _var.endswith("_URL")
-                OPTIONAL_ENV_VARS[_var] = {
-                    "description": f"{_pp.display_name or _pp.name} {'API key' if _is_key else 'base URL override'}",
-                    "prompt": f"{_pp.display_name or _pp.name} {'API key' if _is_key else 'base URL (leave empty for default)'}",
-                    "url": _pp.signup_url or None,
-                    "password": _is_key,
-                    "category": "provider",
-                    "advanced": True,
-                }
-    except Exception:
-        pass
-
-
-# Eagerly inject so that OPTIONAL_ENV_VARS is fully populated at import time.
-_inject_profile_env_vars()

hermes_cli/doctor.py

@@ -164,84 +164,6 @@ def _check_gateway_service_linger(issues: list[str]) -> None:
         check_warn("Could not verify systemd linger", f"({linger_detail})")
 
 
-_APIKEY_PROVIDERS_CACHE: list | None = None
-
-
-def _build_apikey_providers_list() -> list:
-    """Build the API-key provider health-check list once and cache it.
-
-    Tuple format: (name, env_vars, default_url, base_env, supports_models_endpoint)
-    Base list augmented with any ProviderProfile with auth_type="api_key" not
-    already present — adding providers/*.py is sufficient to get into doctor.
-    """
-    _static = [
-        ("Z.AI / GLM",      ("GLM_API_KEY", "ZAI_API_KEY", "Z_AI_API_KEY"), "https://api.z.ai/api/paas/v4/models", "GLM_BASE_URL", True),
-        ("Kimi / Moonshot",  ("KIMI_API_KEY",),                              "https://api.moonshot.ai/v1/models",   "KIMI_BASE_URL", True),
-        ("StepFun Step Plan", ("STEPFUN_API_KEY",),                          "https://api.stepfun.ai/step_plan/v1/models", "STEPFUN_BASE_URL", True),
-        ("Kimi / Moonshot (China)", ("KIMI_CN_API_KEY",),                    "https://api.moonshot.cn/v1/models",   None, True),
-        ("Arcee AI",         ("ARCEEAI_API_KEY",),                           "https://api.arcee.ai/api/v1/models",  "ARCEE_BASE_URL", True),
-        ("GMI Cloud",        ("GMI_API_KEY",),                               "https://api.gmi-serving.com/v1/models", "GMI_BASE_URL", True),
-        ("DeepSeek",         ("DEEPSEEK_API_KEY",),                          "https://api.deepseek.com/v1/models",  "DEEPSEEK_BASE_URL", True),
-        ("Hugging Face",     ("HF_TOKEN",),                                  "https://router.huggingface.co/v1/models", "HF_BASE_URL", True),
-        ("NVIDIA NIM",       ("NVIDIA_API_KEY",),                            "https://integrate.api.nvidia.com/v1/models", "NVIDIA_BASE_URL", True),
-        ("Alibaba/DashScope", ("DASHSCOPE_API_KEY",),                        "https://dashscope-intl.aliyuncs.com/compatible-mode/v1/models", "DASHSCOPE_BASE_URL", True),
-        # MiniMax: the /anthropic endpoint doesn't support /models; use the /v1 surface.
-        ("MiniMax",          ("MINIMAX_API_KEY",),                           "https://api.minimax.io/v1/models",    "MINIMAX_BASE_URL", True),
-        ("MiniMax (China)",  ("MINIMAX_CN_API_KEY",),                        "https://api.minimaxi.com/v1/models",  "MINIMAX_CN_BASE_URL", True),
-        ("Vercel AI Gateway", ("AI_GATEWAY_API_KEY",),                       "https://ai-gateway.vercel.sh/v1/models", "AI_GATEWAY_BASE_URL", True),
-        ("Kilo Code",        ("KILOCODE_API_KEY",),                          "https://api.kilo.ai/api/gateway/models", "KILOCODE_BASE_URL", True),
-        ("OpenCode Zen",     ("OPENCODE_ZEN_API_KEY",),                      "https://opencode.ai/zen/v1/models",  "OPENCODE_ZEN_BASE_URL", True),
-        # OpenCode Go has no shared /models endpoint; skip the health check.
-        ("OpenCode Go",      ("OPENCODE_GO_API_KEY",),                       None,                                  "OPENCODE_GO_BASE_URL", False),
-    ]
-    _known_names = {t[0] for t in _static}
-    # Also index by profile canonical name so profiles without display_name
-    # don't create duplicate entries for providers already in the static list.
-    _known_canonical: set[str] = set()
-    _name_to_canonical = {
-        "Z.AI / GLM": "zai", "Kimi / Moonshot": "kimi-coding",
-        "StepFun Step Plan": "stepfun", "Kimi / Moonshot (China)": "kimi-coding-cn",
-        "Arcee AI": "arcee", "GMI Cloud": "gmi", "DeepSeek": "deepseek",
-        "Hugging Face": "huggingface", "NVIDIA NIM": "nvidia",
-        "Alibaba/DashScope": "alibaba", "MiniMax": "minimax",
-        "MiniMax (China)": "minimax-cn", "Vercel AI Gateway": "ai-gateway",
-        "Kilo Code": "kilocode", "OpenCode Zen": "opencode-zen",
-        "OpenCode Go": "opencode-go",
-    }
-    for _label, _canonical in _name_to_canonical.items():
-        _known_canonical.add(_canonical)
-    try:
-        from providers import list_providers
-        from providers.base import ProviderProfile as _PP
-        for _pp in list_providers():
-            if not isinstance(_pp, _PP) or _pp.auth_type != "api_key" or not _pp.env_vars:
-                continue
-            _label = _pp.display_name or _pp.name
-            if _label in _known_names or _pp.name in _known_canonical:
-                continue
-            # Separate API-key vars from base-URL override vars — the health-check
-            # loop sends the first found value as Authorization: Bearer, so a URL
-            # string must never be picked.
-            _key_vars = tuple(
-                v for v in _pp.env_vars
-                if not v.endswith("_BASE_URL") and not v.endswith("_URL")
-            )
-            _base_var = next(
-                (v for v in _pp.env_vars if v.endswith("_BASE_URL") or v.endswith("_URL")),
-                None,
-            )
-            if not _key_vars:
-                continue
-            _models_url = (
-                (_pp.models_url or (_pp.base_url.rstrip("/") + "/models"))
-                if _pp.base_url else None
-            )
-            _static.append((_label, _key_vars, _models_url, _base_var, True))
-    except Exception:
-        pass
-    return _static
-
-
 def run_doctor(args):
     """Run diagnostic checks."""
     should_fix = getattr(args, 'fix', False)
@@ -1009,11 +931,27 @@ def run_doctor(args):
 
     # -- API-key providers --
     # Tuple: (name, env_vars, default_url, base_env, supports_models_endpoint)
-    # Cached at module level after first build — profiles auto-extend it.
-    global _APIKEY_PROVIDERS_CACHE
-    if _APIKEY_PROVIDERS_CACHE is None:
-        _APIKEY_PROVIDERS_CACHE = _build_apikey_providers_list()
-    _apikey_providers = _APIKEY_PROVIDERS_CACHE
+    # If supports_models_endpoint is False, we skip the health check and just show "configured"
+    _apikey_providers = [
+        ("Z.AI / GLM",      ("GLM_API_KEY", "ZAI_API_KEY", "Z_AI_API_KEY"), "https://api.z.ai/api/paas/v4/models", "GLM_BASE_URL", True),
+        ("Kimi / Moonshot",  ("KIMI_API_KEY",),                              "https://api.moonshot.ai/v1/models",   "KIMI_BASE_URL", True),
+        ("StepFun Step Plan",   ("STEPFUN_API_KEY",),                           "https://api.stepfun.ai/step_plan/v1/models", "STEPFUN_BASE_URL", True),
+        ("Kimi / Moonshot (China)", ("KIMI_CN_API_KEY",),                    "https://api.moonshot.cn/v1/models",   None, True),
+        ("Arcee AI",         ("ARCEEAI_API_KEY",),                            "https://api.arcee.ai/api/v1/models",  "ARCEE_BASE_URL", True),
+        ("GMI Cloud",        ("GMI_API_KEY",),                                "https://api.gmi-serving.com/v1/models", "GMI_BASE_URL", True),
+        ("DeepSeek",         ("DEEPSEEK_API_KEY",),                           "https://api.deepseek.com/v1/models",  "DEEPSEEK_BASE_URL", True),
+        ("Hugging Face",     ("HF_TOKEN",),                                   "https://router.huggingface.co/v1/models", "HF_BASE_URL", True),
+        ("NVIDIA NIM",       ("NVIDIA_API_KEY",),                             "https://integrate.api.nvidia.com/v1/models", "NVIDIA_BASE_URL", True),
+        ("Alibaba/DashScope", ("DASHSCOPE_API_KEY",),                         "https://dashscope-intl.aliyuncs.com/compatible-mode/v1/models", "DASHSCOPE_BASE_URL", True),
+        # MiniMax: the /anthropic endpoint doesn't support /models, but the /v1 endpoint does.
+        ("MiniMax",          ("MINIMAX_API_KEY",),                            "https://api.minimax.io/v1/models",    "MINIMAX_BASE_URL", True),
+        ("MiniMax (China)",  ("MINIMAX_CN_API_KEY",),                         "https://api.minimaxi.com/v1/models",  "MINIMAX_CN_BASE_URL", True),
+        ("Vercel AI Gateway",       ("AI_GATEWAY_API_KEY",),                          "https://ai-gateway.vercel.sh/v1/models", "AI_GATEWAY_BASE_URL", True),
+        ("Kilo Code",        ("KILOCODE_API_KEY",),                            "https://api.kilo.ai/api/gateway/models",  "KILOCODE_BASE_URL", True),
+        ("OpenCode Zen",     ("OPENCODE_ZEN_API_KEY",),                        "https://opencode.ai/zen/v1/models",  "OPENCODE_ZEN_BASE_URL", True),
+        # OpenCode Go has no shared /models endpoint; skip the health check.
+        ("OpenCode Go",      ("OPENCODE_GO_API_KEY",),                         None,                                  "OPENCODE_GO_BASE_URL", False),
+    ]
     for _pname, _env_vars, _default_url, _base_env, _supports_health_check in _apikey_providers:
         _key = ""
         for _ev in _env_vars:

hermes_cli/main.py

@@ -1528,21 +1528,6 @@ def cmd_model(args):
     select_provider_and_model(args=args)
 
 
-def _is_profile_api_key_provider(provider_id: str) -> bool:
-    """Return True when provider_id maps to a profile with auth_type='api_key'.
-
-    Used as a catch-all in select_provider_and_model() so that new providers
-    declared in providers/*.py automatically dispatch to _model_flow_api_key_provider
-    without requiring an explicit elif branch here.
-    """
-    try:
-        from providers import get_provider_profile
-        _p = get_provider_profile(provider_id)
-        return _p is not None and _p.auth_type == "api_key"
-    except Exception:
-        return False
-
-
 def select_provider_and_model(args=None):
     """Core provider selection + model picking logic.
 
@@ -1835,7 +1820,7 @@ def select_provider_and_model(args=None):
         "gmi",
         "nvidia",
         "ollama-cloud",
-    ) or _is_profile_api_key_provider(selected_provider):
+    ):
         _model_flow_api_key_provider(config, selected_provider, current_model)
 
     # ── Post-switch cleanup: clear stale OPENAI_BASE_URL ──────────────
@@ -7633,22 +7618,6 @@ def cmd_logs(args):
     )
 
 
-def _build_provider_choices() -> list[str]:
-    """Build the --provider choices list from CANONICAL_PROVIDERS + 'auto'."""
-    try:
-        from hermes_cli.models import CANONICAL_PROVIDERS as _cp
-        return ["auto"] + [p.slug for p in _cp]
-    except Exception:
-        # Fallback: static list guarantees the CLI always works
-        return [
-            "auto", "openrouter", "nous", "openai-codex", "copilot-acp", "copilot",
-            "anthropic", "gemini", "google-gemini-cli", "xai", "bedrock", "azure-foundry",
-            "ollama-cloud", "huggingface", "zai", "kimi-coding", "kimi-coding-cn",
-            "stepfun", "minimax", "minimax-cn", "kilocode", "xiaomi", "arcee",
-            "nvidia", "deepseek", "alibaba", "qwen-oauth", "opencode-zen", "opencode-go",
-        ]
-
-
 def main():
     """Main entry point for hermes CLI."""
     parser = argparse.ArgumentParser(
@@ -7842,7 +7811,30 @@ For more help on a command:
     )
     chat_parser.add_argument(
         "--provider",
-        choices=_build_provider_choices(),
+        choices=[
+            "auto",
+            "openrouter",
+            "nous",
+            "openai-codex",
+            "copilot-acp",
+            "copilot",
+            "anthropic",
+            "gemini",
+            "xai",
+            "ollama-cloud",
+            "huggingface",
+            "zai",
+            "kimi-coding",
+            "kimi-coding-cn",
+            "stepfun",
+            "minimax",
+            "minimax-cn",
+            "kilocode",
+            "xiaomi",
+            "arcee",
+            "gmi",
+            "nvidia",
+        ],
         default=None,
         help="Inference provider (default: auto)",
     )
@@ -9090,7 +9082,11 @@ Examples:
     )
     plugins_remove.add_argument("name", help="Plugin directory name to remove")
 
-    plugins_subparsers.add_parser("list", aliases=["ls"], help="List installed plugins")
+    plugins_list = plugins_subparsers.add_parser("list", aliases=["ls"], help="List installed plugins")
+    plugins_list.add_argument(
+        "--available", action="store_true",
+        help="Also show official optional plugins that are not yet installed",
+    )
 
     plugins_enable = plugins_subparsers.add_parser(
         "enable", help="Enable a disabled plugin"

hermes_cli/models.py

@@ -750,25 +750,6 @@ CANONICAL_PROVIDERS: list[ProviderEntry] = [
     ProviderEntry("azure-foundry",  "Azure Foundry",            "Azure Foundry (OpenAI-style or Anthropic-style endpoint — your Azure AI deployment)"),
 ]
 
-# Auto-extend CANONICAL_PROVIDERS with any provider registered in providers/
-# that is not already in the list above.  Adding providers/*.py is sufficient
-# to expose a new provider in the model picker, /model, and all downstream
-# consumers — no edits to this file needed.
-_canonical_slugs = {p.slug for p in CANONICAL_PROVIDERS}
-try:
-    from providers import list_providers as _list_providers_for_canonical
-    for _pp in _list_providers_for_canonical():
-        if _pp.name in _canonical_slugs:
-            continue
-        if _pp.auth_type in ("oauth_device_code", "oauth_external", "external_process", "aws_sdk", "copilot"):
-            continue  # non-api-key flows need bespoke picker UX; skip auto-inject
-        _label = _pp.display_name or _pp.name
-        _desc = _pp.description or f"{_label} (direct API)"
-        CANONICAL_PROVIDERS.append(ProviderEntry(_pp.name, _label, _desc))
-        _canonical_slugs.add(_pp.name)
-except Exception:
-    pass
-
 # Derived dicts — used throughout the codebase
 _PROVIDER_LABELS = {p.slug: p.label for p in CANONICAL_PROVIDERS}
 _PROVIDER_LABELS["custom"] = "Custom endpoint"  # special case: not a named provider
@@ -1903,34 +1884,6 @@ def provider_model_ids(provider: Optional[str], *, force_refresh: bool = False)
             live = fetch_api_models(api_key, base_url)
             if live:
                 return live
-
-    # ── Profile-based generic live fetch (all simple api-key providers) ──
-    # Handles any provider registered in providers/ with auth_type="api_key".
-    # Replaces per-provider copy-paste blocks (stepfun, gmi, zai, etc.).
-    try:
-        from providers import get_provider_profile
-        from hermes_cli.auth import resolve_api_key_provider_credentials
-
-        _p = get_provider_profile(normalized)
-        if _p and _p.auth_type == "api_key" and _p.base_url:
-            try:
-                creds = resolve_api_key_provider_credentials(normalized)
-                api_key = str(creds.get("api_key") or "").strip()
-                base_url = str(creds.get("base_url") or "").strip()
-            except Exception:
-                api_key, base_url = "", _p.base_url
-            if not base_url:
-                base_url = _p.base_url
-            if api_key:
-                live = _p.fetch_models(api_key=api_key)
-                if live:
-                    return live
-            # Use profile's fallback_models if defined
-            if _p.fallback_models:
-                return list(_p.fallback_models)
-    except Exception:
-        pass
-
     curated_static = list(_PROVIDER_MODELS.get(normalized, []))
     if normalized in _MODELS_DEV_PREFERRED:
         return _merge_with_models_dev(normalized, curated_static)

hermes_cli/plugins_cmd.py

@@ -1,7 +1,13 @@
 """``hermes plugins`` CLI subcommand — install, update, remove, and list plugins.
 
-Plugins are installed from Git repositories into ``~/.hermes/plugins/``.
-Supports full URLs and ``owner/repo`` shorthand (resolves to GitHub).
+Plugins can be installed from:
+- Official optional plugins shipped with the repo: ``official/<category>/<name>``
+- Git repositories (full URL or ``owner/repo`` GitHub shorthand)
+
+Official plugins live in ``optional-plugins/`` inside the Hermes repo and are
+copied into ``~/.hermes/plugins/`` on install — no git clone needed, no network
+required. They are NOT auto-discovered from ``optional-plugins/``; only installed
+copies in ``~/.hermes/plugins/`` are loaded by Hermes.
 
 After install, if the plugin ships an ``after-install.md`` file it is
 rendered with Rich Markdown.  Otherwise a default confirmation is shown.
@@ -95,10 +101,80 @@ def _resolve_git_url(identifier: str) -> str:
 
     raise ValueError(
         f"Invalid plugin identifier: '{identifier}'. "
-        "Use a Git URL or owner/repo shorthand."
+        "Use 'official/<category>/<name>', a Git URL, or owner/repo shorthand."
     )
 
 
+def _optional_plugins_dir() -> Path:
+    """Return the optional-plugins/ directory shipped with the Hermes repo."""
+    return Path(__file__).resolve().parent.parent / "optional-plugins"
+
+
+def _resolve_official_plugin(identifier: str) -> Optional[Path]:
+    """If *identifier* is 'official/<category>/<name>', return its source path.
+
+    Returns ``None`` when the identifier is not in official format or the
+    plugin directory does not exist.
+    """
+    # Accept 'official/category/name' or just 'category/name' when the
+    # category/name path exists under optional-plugins/.
+    parts = identifier.strip("/").split("/")
+
+    # Strip leading 'official' prefix if present
+    if parts and parts[0] == "official":
+        parts = parts[1:]
+
+    if len(parts) < 1:
+        return None
+
+    base = _optional_plugins_dir()
+    # Try category/name  (2 parts) or bare name  (1 part)
+    for nparts in (2, 1):
+        if len(parts) < nparts:
+            continue
+        candidate = base.joinpath(*parts[-nparts:])
+        try:
+            resolved = candidate.resolve()
+            base_resolved = base.resolve()
+            resolved.relative_to(base_resolved)  # traversal guard
+        except (ValueError, OSError):
+            continue
+        if resolved.is_dir() and (
+            (resolved / "plugin.yaml").exists() or (resolved / "__init__.py").exists()
+        ):
+            return resolved
+
+    return None
+
+
+def _list_official_plugins() -> list[tuple[str, str]]:
+    """Return [(identifier, description), ...] for all official optional plugins."""
+    base = _optional_plugins_dir()
+    if not base.is_dir():
+        return []
+
+    results = []
+    for category_dir in sorted(base.iterdir()):
+        if not category_dir.is_dir() or category_dir.name.startswith("."):
+            continue
+        for plugin_dir in sorted(category_dir.iterdir()):
+            if not plugin_dir.is_dir() or plugin_dir.name.startswith("."):
+                continue
+            manifest_file = plugin_dir / "plugin.yaml"
+            desc = ""
+            if manifest_file.exists():
+                try:
+                    import yaml
+                    data = yaml.safe_load(manifest_file.read_text()) or {}
+                    desc = data.get("description", "")
+                except Exception:
+                    pass
+            identifier = f"official/{category_dir.name}/{plugin_dir.name}"
+            results.append((identifier, desc))
+
+    return results
+
+
 def _repo_name_from_url(url: str) -> str:
     """Extract the repo name from a Git URL for the plugin directory name."""
     # Strip trailing .git and slashes
@@ -296,7 +372,61 @@ def cmd_install(
     from rich.console import Console
 
     console = Console()
+    plugins_dir = _plugins_dir()
 
+    # ── Official optional plugins (no network, copied from optional-plugins/) ──
+    official_src = _resolve_official_plugin(identifier)
+    if official_src is not None:
+        manifest = _read_manifest(official_src)
+        plugin_name = manifest.get("name") or official_src.name
+        target = _sanitize_plugin_name(plugin_name, plugins_dir)
+
+        if target.exists():
+            if not force:
+                console.print(
+                    f"[red]Error:[/red] Plugin '{plugin_name}' already exists at {target}.\n"
+                    f"Use [bold]--force[/bold] to reinstall, or "
+                    f"[bold]hermes plugins update {plugin_name}[/bold] to update."
+                )
+                sys.exit(1)
+            console.print(f"[dim]  Removing existing {plugin_name}...[/dim]")
+            shutil.rmtree(target)
+
+        console.print(f"[dim]Installing {plugin_name} from official optional plugins...[/dim]")
+        shutil.copytree(str(official_src), str(target))
+
+        _copy_example_files(target, console)
+        _prompt_plugin_env_vars(manifest, console)
+        _display_after_install(target, identifier)
+
+        installed_name = manifest.get("name") or target.name
+        should_enable = enable
+        if should_enable is None:
+            if sys.stdin.isatty() and sys.stdout.isatty():
+                try:
+                    answer = input("  Enable now? [y/N] ").strip().lower()
+                    should_enable = answer in ("y", "yes")
+                except (EOFError, KeyboardInterrupt):
+                    should_enable = False
+            else:
+                should_enable = False
+
+        if should_enable:
+            enabled = _get_enabled_set()
+            disabled = _get_disabled_set()
+            enabled.add(installed_name)
+            disabled.discard(installed_name)
+            _save_enabled_set(enabled)
+            _save_disabled_set(disabled)
+            console.print(f"  [green]✓[/green] Plugin [bold]{installed_name}[/bold] enabled.")
+        else:
+            console.print(
+                f"  [dim]Plugin installed but not enabled. "
+                f"Run [bold]hermes plugins enable {installed_name}[/bold] to activate.[/dim]"
+            )
+        return
+
+    # ── Git URL / owner/repo install ──────────────────────────────────────────
     try:
         git_url = _resolve_git_url(identifier)
     except ValueError as e:
@@ -310,8 +440,6 @@ def cmd_install(
             "Consider using https:// or git@ for production installs."
         )
 
-    plugins_dir = _plugins_dir()
-
     # Clone into a temp directory first so we can read plugin.yaml for the name
     with tempfile.TemporaryDirectory() as tmp:
         tmp_target = Path(tmp) / "plugin"
@@ -696,16 +824,21 @@ def _discover_all_plugins() -> list:
     return list(seen.values())
 
 
-def cmd_list() -> None:
-    """List all plugins (bundled + user) with enabled/disabled state."""
+def cmd_list(available: bool = False) -> None:
+    """List all plugins (bundled + user) with enabled/disabled state.
+
+    When *available* is True, also show official optional plugins that are
+    not yet installed.
+    """
     from rich.console import Console
     from rich.table import Table
 
     console = Console()
     entries = _discover_all_plugins()
-    if not entries:
+    if not entries and not available:
         console.print("[dim]No plugins installed.[/dim]")
-        console.print("[dim]Install with:[/dim] hermes plugins install owner/repo")
+        console.print("[dim]Install with:[/dim] hermes plugins install official/<category>/<name>")
+        console.print("[dim]Browse available:[/dim] hermes plugins list --available")
         return
 
     enabled = _get_enabled_set()
@@ -734,6 +867,31 @@ def cmd_list() -> None:
     console.print("[dim]Enable/disable:[/dim] hermes plugins enable/disable <name>")
     console.print("[dim]Plugins are opt-in by default — only 'enabled' plugins load.[/dim]")
 
+    if available:
+        official = _list_official_plugins()
+        if official:
+            installed_names = {name for name, *_ in entries}
+            def _is_installed(ident: str) -> bool:
+                dirname = ident.rsplit("/", 1)[-1]
+                # Check both the directory name (langfuse-tracing) and
+                # common underscore variant (langfuse_tracing) since the
+                # installed plugin uses the manifest name, not the dir name.
+                return (dirname in installed_names
+                        or dirname.replace("-", "_") in installed_names)
+            not_installed = [(ident, desc) for ident, desc in official
+                             if not _is_installed(ident)]
+            if not_installed:
+                console.print()
+                avail_table = Table(title="Official optional plugins (not installed)", show_lines=False)
+                avail_table.add_column("Identifier", style="bold")
+                avail_table.add_column("Description")
+                for ident, desc in not_installed:
+                    avail_table.add_row(ident, desc)
+                console.print(avail_table)
+                console.print("[dim]Install:[/dim] hermes plugins install official/<category>/<name>")
+            else:
+                console.print("[dim]All official optional plugins are already installed.[/dim]")
+
 
 # ---------------------------------------------------------------------------
 # Provider plugin discovery helpers
@@ -1270,7 +1428,7 @@ def plugins_command(args) -> None:
     elif action == "disable":
         cmd_disable(args.name)
     elif action in ("list", "ls"):
-        cmd_list()
+        cmd_list(available=getattr(args, "available", False))
     elif action is None:
         cmd_toggle()
     else:

hermes_cli/runtime_provider.py

@@ -214,6 +214,10 @@ def _resolve_runtime_from_pool_entry(
         base_url = cfg_base_url or base_url or "https://api.anthropic.com"
     elif provider == "openrouter":
         base_url = base_url or OPENROUTER_BASE_URL
+    elif provider == "xai":
+        api_mode = "codex_responses"
+    elif provider == "nous":
+        api_mode = "chat_completions"
     elif provider == "copilot":
         api_mode = _copilot_runtime_api_mode(model_cfg, getattr(entry, "runtime_api_key", ""))
         base_url = base_url or PROVIDER_REGISTRY["copilot"].inference_base_url
@@ -245,14 +249,6 @@ def _resolve_runtime_from_pool_entry(
             base_url = re.sub(r"/v1/?$", "", base_url)
     else:
         configured_provider = str(model_cfg.get("provider") or "").strip().lower()
-        # Use profile api_mode for all other known providers
-        try:
-            from providers import get_provider_profile
-            _p = get_provider_profile(provider)
-            if _p and _p.api_mode:
-                api_mode = _p.api_mode
-        except Exception:
-            pass
         # Honour model.base_url from config.yaml when the configured provider
         # matches this provider — same pattern as the Anthropic branch above.
         # Only override when the pool entry has no explicit base_url (i.e. it
@@ -270,21 +266,12 @@ def _resolve_runtime_from_pool_entry(
             from hermes_cli.models import opencode_model_api_mode
             api_mode = opencode_model_api_mode(provider, effective_model)
         else:
-            # Try profile api_mode first, then auto-detect from URL
-            try:
-                from providers import get_provider_profile
-                _p = get_provider_profile(provider)
-                if _p and _p.api_mode:
-                    api_mode = _p.api_mode
-            except Exception:
-                pass
-            if api_mode == "chat_completions":
-                # Auto-detect Anthropic-compatible endpoints (/anthropic suffix,
-                # Kimi /coding, api.openai.com → codex_responses, api.x.ai →
-                # codex_responses).
-                detected = _detect_api_mode_for_url(base_url)
-                if detected:
-                    api_mode = detected
+            # Auto-detect Anthropic-compatible endpoints (/anthropic suffix,
+            # Kimi /coding, api.openai.com → codex_responses, api.x.ai →
+            # codex_responses).
+            detected = _detect_api_mode_for_url(base_url)
+            if detected:
+                api_mode = detected
 
     # OpenCode base URLs end with /v1 for OpenAI-compatible models, but the
     # Anthropic SDK prepends its own /v1/messages to the base_url.  Strip the

hermes_cli/tools_config.py

@@ -425,6 +425,31 @@ TOOL_CATEGORIES = {
             },
         ],
     },
+    "langfuse": {
+        "name": "Langfuse Observability",
+        "icon": "📊",
+        "providers": [
+            {
+                "name": "Langfuse Cloud",
+                "tag": "Hosted Langfuse (cloud.langfuse.com)",
+                "env_vars": [
+                    {"key": "HERMES_LANGFUSE_PUBLIC_KEY", "prompt": "Langfuse public key (pk-lf-...)", "url": "https://cloud.langfuse.com"},
+                    {"key": "HERMES_LANGFUSE_SECRET_KEY", "prompt": "Langfuse secret key (sk-lf-...)", "url": "https://cloud.langfuse.com"},
+                ],
+                "post_setup": "langfuse",
+            },
+            {
+                "name": "Langfuse Self-Hosted",
+                "tag": "Self-hosted Langfuse instance",
+                "env_vars": [
+                    {"key": "HERMES_LANGFUSE_PUBLIC_KEY", "prompt": "Langfuse public key (pk-lf-...)"},
+                    {"key": "HERMES_LANGFUSE_SECRET_KEY", "prompt": "Langfuse secret key (sk-lf-...)"},
+                    {"key": "HERMES_LANGFUSE_BASE_URL", "prompt": "Langfuse server URL (e.g. http://localhost:3000)", "default": "http://localhost:3000"},
+                ],
+                "post_setup": "langfuse",
+            },
+        ],
+    },
 }
 
 # Simple env-var requirements for toolsets NOT in TOOL_CATEGORIES.
@@ -567,6 +592,31 @@ def _run_post_setup(post_setup_key: str):
                 _print_info("      git submodule update --init --recursive")
                 _print_info('      uv pip install -e "./tinker-atropos"')
 
+    elif post_setup_key == "langfuse":
+        # Install the langfuse SDK.
+        try:
+            __import__("langfuse")
+            _print_success("    langfuse SDK already installed")
+        except ImportError:
+            import subprocess
+            _print_info("    Installing langfuse SDK...")
+            result = subprocess.run(
+                [sys.executable, "-m", "pip", "install", "langfuse", "--quiet"],
+                capture_output=True, text=True, timeout=120,
+            )
+            if result.returncode == 0:
+                _print_success("    langfuse SDK installed")
+            else:
+                _print_warning("    langfuse SDK install failed — run manually: pip install langfuse")
+        # Install and enable the official optional plugin into ~/.hermes/plugins/.
+        try:
+            from hermes_cli.plugins_cmd import cmd_install as _plugins_install
+            _plugins_install("official/observability/langfuse", enable=True)
+        except SystemExit:
+            pass  # cmd_install prints its own errors and calls sys.exit
+        _print_info("    Restart Hermes for tracing to take effect.")
+        _print_info("    Verify: hermes plugins list")
+
 
 # ─── Platform / Toolset Helpers ───────────────────────────────────────────────
 

hermes_state.py

@@ -285,130 +285,156 @@ class SessionDB:
                 self._conn.close()
                 self._conn = None
 
+    @staticmethod
+    def _parse_schema_columns(schema_sql: str) -> Dict[str, Dict[str, str]]:
+        """Extract expected columns per table from SCHEMA_SQL.
+
+        Uses an in-memory SQLite database to parse the SQL — SQLite itself
+        handles all syntax (DEFAULT expressions with commas, inline
+        REFERENCES, CHECK constraints, etc.) so there are zero regex
+        edge cases.  The in-memory DB is opened, the schema DDL is
+        executed, and PRAGMA table_info extracts the column metadata.
+
+        Adding a column to SCHEMA_SQL is all that's needed; the
+        reconciliation loop picks it up automatically.
+        """
+        ref = sqlite3.connect(":memory:")
+        try:
+            ref.executescript(schema_sql)
+            table_columns: Dict[str, Dict[str, str]] = {}
+            for (tbl,) in ref.execute(
+                "SELECT name FROM sqlite_master "
+                "WHERE type='table' AND name NOT LIKE 'sqlite_%'"
+            ).fetchall():
+                cols: Dict[str, str] = {}
+                for row in ref.execute(
+                    f'PRAGMA table_info("{tbl}")'
+                ).fetchall():
+                    # row: (cid, name, type, notnull, dflt_value, pk)
+                    col_name = row[1]
+                    col_type = row[2] or ""
+                    notnull = row[3]
+                    default = row[4]
+                    pk = row[5]
+                    # Reconstruct the type expression for ALTER TABLE ADD COLUMN
+                    parts = [col_type] if col_type else []
+                    if notnull and not pk:
+                        parts.append("NOT NULL")
+                    if default is not None:
+                        parts.append(f"DEFAULT {default}")
+                    cols[col_name] = " ".join(parts)
+                table_columns[tbl] = cols
+            return table_columns
+        finally:
+            ref.close()
+
+    def _reconcile_columns(self, cursor: sqlite3.Cursor) -> None:
+        """Ensure live tables have every column declared in SCHEMA_SQL.
+
+        Follows the Beets/sqlite-utils pattern: the CREATE TABLE definition
+        in SCHEMA_SQL is the single source of truth for the desired schema.
+        On every startup this method diffs the live columns (via PRAGMA
+        table_info) against the declared columns, and ADDs any that are
+        missing.
+
+        This makes column additions a declarative operation — just add
+        the column to SCHEMA_SQL and it appears on the next startup.
+        Version-gated migration blocks are no longer needed for ADD COLUMN.
+        """
+        expected = self._parse_schema_columns(SCHEMA_SQL)
+        for table_name, declared_cols in expected.items():
+            # Get current columns from the live table
+            try:
+                rows = cursor.execute(
+                    f'PRAGMA table_info("{table_name}")'
+                ).fetchall()
+            except sqlite3.OperationalError:
+                continue  # Table doesn't exist yet (shouldn't happen after executescript)
+            live_cols = set()
+            for row in rows:
+                # PRAGMA table_info returns (cid, name, type, notnull, dflt_value, pk)
+                name = row[1] if isinstance(row, (tuple, list)) else row["name"]
+                live_cols.add(name)
+
+            for col_name, col_type in declared_cols.items():
+                if col_name not in live_cols:
+                    safe_name = col_name.replace('"', '""')
+                    try:
+                        cursor.execute(
+                            f'ALTER TABLE "{table_name}" ADD COLUMN "{safe_name}" {col_type}'
+                        )
+                    except sqlite3.OperationalError as exc:
+                        # Expected: "duplicate column name" from a race or
+                        # re-run.  Unexpected: "Cannot add a NOT NULL column
+                        # with default value NULL" from a schema mistake.
+                        # Log at DEBUG so it's visible in agent.log.
+                        logger.debug(
+                            "reconcile %s.%s: %s", table_name, col_name, exc,
+                        )
+
     def _init_schema(self):
-        """Create tables and FTS if they don't exist, run migrations."""
+        """Create tables and FTS if they don't exist, reconcile columns.
+
+        Schema management follows the declarative reconciliation pattern
+        (Beets, sqlite-utils): SCHEMA_SQL is the single source of truth.
+        On existing databases, _reconcile_columns() diffs live columns
+        against SCHEMA_SQL and ADDs any missing ones.  This eliminates
+        the version-gated migration chain for column additions, making
+        it impossible for reordered or inserted migrations to skip columns.
+
+        The schema_version table is retained for future data migrations
+        (transforming existing rows) which cannot be handled declaratively.
+        """
         cursor = self._conn.cursor()
 
         cursor.executescript(SCHEMA_SQL)
 
-        # Check schema version and run migrations
+        # ── Declarative column reconciliation ──────────────────────────
+        # Diff live tables against SCHEMA_SQL and ADD any missing columns.
+        # This is idempotent and self-healing: even if a version-gated
+        # migration was skipped (e.g. due to version renumbering), the
+        # column gets created here.
+        self._reconcile_columns(cursor)
+
+        # ── Schema version bookkeeping ─────────────────────────────────
+        # Bump to current so future data migrations (if any) can gate on
+        # version.  No version-gated column additions remain.
         cursor.execute("SELECT version FROM schema_version LIMIT 1")
         row = cursor.fetchone()
         if row is None:
-            cursor.execute("INSERT INTO schema_version (version) VALUES (?)", (SCHEMA_VERSION,))
+            cursor.execute(
+                "INSERT INTO schema_version (version) VALUES (?)",
+                (SCHEMA_VERSION,),
+            )
         else:
             current_version = row["version"] if isinstance(row, sqlite3.Row) else row[0]
-            if current_version < 2:
-                # v2: add finish_reason column to messages
-                try:
-                    cursor.execute("ALTER TABLE messages ADD COLUMN finish_reason TEXT")
-                except sqlite3.OperationalError:
-                    pass  # Column already exists
-                cursor.execute("UPDATE schema_version SET version = 2")
-            if current_version < 3:
-                # v3: add title column to sessions
-                try:
-                    cursor.execute("ALTER TABLE sessions ADD COLUMN title TEXT")
-                except sqlite3.OperationalError:
-                    pass  # Column already exists
-                cursor.execute("UPDATE schema_version SET version = 3")
-            if current_version < 4:
-                # v4: add unique index on title (NULLs allowed, only non-NULL must be unique)
-                try:
-                    cursor.execute(
-                        "CREATE UNIQUE INDEX IF NOT EXISTS idx_sessions_title_unique "
-                        "ON sessions(title) WHERE title IS NOT NULL"
-                    )
-                except sqlite3.OperationalError:
-                    pass  # Index already exists
-                cursor.execute("UPDATE schema_version SET version = 4")
-            if current_version < 5:
-                new_columns = [
-                    ("cache_read_tokens", "INTEGER DEFAULT 0"),
-                    ("cache_write_tokens", "INTEGER DEFAULT 0"),
-                    ("reasoning_tokens", "INTEGER DEFAULT 0"),
-                    ("billing_provider", "TEXT"),
-                    ("billing_base_url", "TEXT"),
-                    ("billing_mode", "TEXT"),
-                    ("estimated_cost_usd", "REAL"),
-                    ("actual_cost_usd", "REAL"),
-                    ("cost_status", "TEXT"),
-                    ("cost_source", "TEXT"),
-                    ("pricing_version", "TEXT"),
-                ]
-                for name, column_type in new_columns:
-                    try:
-                        # name and column_type come from the hardcoded tuple above,
-                        # not user input. Double-quote identifier escaping is applied
-                        # as defense-in-depth; SQLite DDL cannot be parameterized.
-                        safe_name = name.replace('"', '""')
-                        cursor.execute(f'ALTER TABLE sessions ADD COLUMN "{safe_name}" {column_type}')
-                    except sqlite3.OperationalError:
-                        pass
-                cursor.execute("UPDATE schema_version SET version = 5")
-            if current_version < 6:
-                # v6: add reasoning columns to messages table — preserves assistant
-                # reasoning text and structured reasoning_details across gateway
-                # session turns.  Without these, reasoning chains are lost on
-                # session reload, breaking multi-turn reasoning continuity for
-                # providers that replay reasoning (OpenRouter, OpenAI, Nous).
-                for col_name, col_type in [
-                    ("reasoning", "TEXT"),
-                    ("reasoning_details", "TEXT"),
-                    ("codex_reasoning_items", "TEXT"),
-                ]:
-                    try:
-                        safe = col_name.replace('"', '""')
-                        cursor.execute(
-                            f'ALTER TABLE messages ADD COLUMN "{safe}" {col_type}'
-                        )
-                    except sqlite3.OperationalError:
-                        pass  # Column already exists
-                cursor.execute("UPDATE schema_version SET version = 6")
-            if current_version < 7:
-                # v7: preserve provider-native reasoning_content separately from
-                # normalized reasoning text. Kimi/Moonshot replay can require
-                # this field on assistant tool-call messages when thinking is on.
-                try:
-                    cursor.execute('ALTER TABLE messages ADD COLUMN "reasoning_content" TEXT')
-                except sqlite3.OperationalError:
-                    pass  # Column already exists
-                cursor.execute("UPDATE schema_version SET version = 7")
-            if current_version < 8:
-                # v8: add api_call_count column to sessions — tracks the number
-                # of individual LLM API calls made within a session (as opposed
-                # to the session count itself).
-                try:
-                    cursor.execute(
-                        'ALTER TABLE sessions ADD COLUMN "api_call_count" INTEGER DEFAULT 0'
-                    )
-                except sqlite3.OperationalError:
-                    pass  # Column already exists
-                cursor.execute("UPDATE schema_version SET version = 8")
-            if current_version < 9:
-                # v9: preserve replayable Codex assistant message ids/phases so
-                # follow-up turns can rebuild Responses API message items instead
-                # of flattening everything to plain assistant text.
-                try:
-                    cursor.execute('ALTER TABLE messages ADD COLUMN "codex_message_items" TEXT')
-                except sqlite3.OperationalError:
-                    pass  # Column already exists
-                cursor.execute("UPDATE schema_version SET version = 9")
+            # Data migrations that can't be expressed declaratively (row
+            # backfills, index changes tied to a specific version step) stay
+            # in a version-gated chain. Column additions are handled by
+            # _reconcile_columns() above and no longer need entries here.
             if current_version < 10:
-                # v10: trigram FTS5 table for CJK/substring search.
-                # Created via FTS_TRIGRAM_SQL below; backfill existing messages.
+                # v10: trigram FTS5 table for CJK/substring search. The
+                # virtual table + triggers are created unconditionally via
+                # FTS_TRIGRAM_SQL below, but existing rows need a one-time
+                # backfill into the FTS index.
                 try:
                     cursor.execute("SELECT * FROM messages_fts_trigram LIMIT 0")
+                    _fts_trigram_exists = True
                 except sqlite3.OperationalError:
+                    _fts_trigram_exists = False
+                if not _fts_trigram_exists:
                     cursor.executescript(FTS_TRIGRAM_SQL)
                     cursor.execute(
                         "INSERT INTO messages_fts_trigram(rowid, content) "
                         "SELECT id, content FROM messages WHERE content IS NOT NULL"
                     )
-                cursor.execute("UPDATE schema_version SET version = 10")
+            if current_version < SCHEMA_VERSION:
+                cursor.execute(
+                    "UPDATE schema_version SET version = ?",
+                    (SCHEMA_VERSION,),
+                )
 
-        # Unique title index — always ensure it exists (safe to run after migrations
-        # since the title column is guaranteed to exist at this point)
+        # Unique title index — always ensure it exists
         try:
             cursor.execute(
                 "CREATE UNIQUE INDEX IF NOT EXISTS idx_sessions_title_unique "

optional-plugins/observability/langfuse/__init__.py

@@ -0,0 +1,875 @@
+"""langfuse — Hermes plugin for Langfuse observability.
+
+Traces Hermes conversations, LLM calls, and tool usage to Langfuse.
+Enable via ``hermes tools`` or by setting HERMES_LANGFUSE_ENABLED=true
+and the required credentials in ~/.hermes/.env.
+
+Required env vars (set via ``hermes tools`` or ~/.hermes/.env):
+  HERMES_LANGFUSE_ENABLED   - set to "true" to activate tracing
+  HERMES_LANGFUSE_PUBLIC_KEY  - Langfuse project public key (pk-lf-...)
+  HERMES_LANGFUSE_SECRET_KEY  - Langfuse project secret key (sk-lf-...)
+  HERMES_LANGFUSE_BASE_URL    - Langfuse server URL (default: https://cloud.langfuse.com)
+
+Optional env vars:
+  HERMES_LANGFUSE_ENV         - environment tag (e.g. "production", "local")
+  HERMES_LANGFUSE_RELEASE     - release/version tag
+  HERMES_LANGFUSE_SAMPLE_RATE - sampling rate 0.0–1.0 (default: 1.0)
+  HERMES_LANGFUSE_MAX_CHARS   - max chars per field (default: 12000)
+  HERMES_LANGFUSE_DEBUG       - set to "true" for verbose logging
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+try:
+    from langfuse import Langfuse, propagate_attributes
+except Exception:  # pragma: no cover - fail-open when optional dep is missing
+    Langfuse = None
+    propagate_attributes = None
+
+
+@dataclass
+class TraceState:
+    trace_id: str
+    root_ctx: Any
+    root_span: Any
+    generations: Dict[str, Any] = field(default_factory=dict)
+    tools: Dict[str, Any] = field(default_factory=dict)
+    turn_tool_calls: list[dict[str, Any]] = field(default_factory=list)
+    last_updated_at: float = field(default_factory=time.time)
+
+
+_STATE_LOCK = threading.Lock()
+_TRACE_STATE: Dict[str, TraceState] = {}
+_LANGFUSE_CLIENT = None
+_READ_FILE_LINE_RE = re.compile(r"^\s*(\d+)\|(.*)$")
+_READ_FILE_HEAD_LINES = 25
+_READ_FILE_TAIL_LINES = 15
+
+
+def _env(name: str, default: str = "") -> str:
+    return os.environ.get(name, default).strip()
+
+
+def _env_bool(*names: str) -> bool:
+    for name in names:
+        value = _env(name).lower()
+        if value:
+            return value in {"1", "true", "yes", "on"}
+    return False
+
+
+def _debug_enabled() -> bool:
+    return _env_bool("HERMES_LANGFUSE_DEBUG")
+
+
+def _debug(message: str) -> None:
+    if _debug_enabled():
+        logger.info("Langfuse tracing: %s", message)
+
+
+def _is_enabled() -> bool:
+    if Langfuse is None:
+        return False
+    # Primary activation path: config.yaml plugins.langfuse.enabled
+    try:
+        from hermes_cli.config import load_config
+        _cfg = load_config()
+        _plugin_cfg = _cfg.get("plugins", {})
+        if isinstance(_plugin_cfg, dict):
+            _lt_cfg = _plugin_cfg.get("langfuse", {})
+            if isinstance(_lt_cfg, dict) and "enabled" in _lt_cfg:
+                if not _lt_cfg["enabled"]:
+                    return False
+                # Explicit enabled=true in config — skip env-var check below
+                public_key = _env("HERMES_LANGFUSE_PUBLIC_KEY") or _env("LANGFUSE_PUBLIC_KEY")
+                secret_key = _env("HERMES_LANGFUSE_SECRET_KEY") or _env("LANGFUSE_SECRET_KEY")
+                return bool(public_key and secret_key)
+    except Exception:
+        pass
+    # Backward-compat path: HERMES_LANGFUSE_ENABLED env var (legacy .env installs)
+    if not _env_bool("HERMES_LANGFUSE_ENABLED"):
+        return False
+    public_key = _env("HERMES_LANGFUSE_PUBLIC_KEY") or _env("LANGFUSE_PUBLIC_KEY")
+    secret_key = _env("HERMES_LANGFUSE_SECRET_KEY") or _env("LANGFUSE_SECRET_KEY")
+    return bool(public_key and secret_key)
+
+
+def _get_langfuse() -> Optional[Langfuse]:
+    global _LANGFUSE_CLIENT
+    if not _is_enabled():
+        return None
+    if _LANGFUSE_CLIENT is not None:
+        return _LANGFUSE_CLIENT
+
+    public_key = _env("HERMES_LANGFUSE_PUBLIC_KEY") or _env("LANGFUSE_PUBLIC_KEY")
+    secret_key = _env("HERMES_LANGFUSE_SECRET_KEY") or _env("LANGFUSE_SECRET_KEY")
+    base_url = _env("HERMES_LANGFUSE_BASE_URL") or _env("LANGFUSE_BASE_URL") or "https://cloud.langfuse.com"
+    environment = _env("HERMES_LANGFUSE_ENV") or _env("LANGFUSE_ENV")
+    release = _env("HERMES_LANGFUSE_RELEASE") or _env("LANGFUSE_RELEASE")
+    sample_rate = _env("HERMES_LANGFUSE_SAMPLE_RATE")
+
+    kwargs: Dict[str, Any] = {
+        "public_key": public_key,
+        "secret_key": secret_key,
+        "base_url": base_url,
+    }
+    if environment:
+        kwargs["environment"] = environment
+    if release:
+        kwargs["release"] = release
+    if sample_rate:
+        try:
+            kwargs["sample_rate"] = float(sample_rate)
+        except ValueError:
+            logger.warning("Invalid HERMES_LANGFUSE_SAMPLE_RATE=%r", sample_rate)
+
+    try:
+        _LANGFUSE_CLIENT = Langfuse(**kwargs)
+    except Exception as exc:  # pragma: no cover - fail-open
+        logger.warning("Could not initialize Langfuse client: %s", exc)
+        return None
+
+    return _LANGFUSE_CLIENT
+
+
+def _trace_key(task_id: str, session_id: str) -> str:
+    if task_id:
+        return task_id
+    if session_id:
+        return f"session:{session_id}"
+    return f"thread:{threading.get_ident()}"
+
+
+def _truncate_text(value: str, max_chars: int) -> str:
+    if len(value) <= max_chars:
+        return value
+    return value[:max_chars] + f"... [truncated {len(value) - max_chars} chars]"
+
+
+def _maybe_parse_json_string(value: str) -> Any:
+    stripped = value.strip()
+    if len(stripped) < 2 or stripped[0] not in "{[" or stripped[-1] not in "}]":
+        if len(stripped) < 2 or stripped[0] not in "{[":
+            return value
+    try:
+        parsed, idx = json.JSONDecoder().raw_decode(stripped)
+    except Exception:
+        return value
+    if not isinstance(parsed, (dict, list)):
+        return value
+
+    trailing = stripped[idx:].strip()
+    if not trailing:
+        return parsed
+
+    hint_key = "_hint" if trailing.startswith("[Hint:") else "_trailing_text"
+    if isinstance(parsed, dict):
+        merged = dict(parsed)
+        key = hint_key if hint_key not in merged else "_trailing_text"
+        merged[key] = trailing
+        return merged
+
+    return {"data": parsed, hint_key: trailing}
+
+
+def _looks_like_read_file_payload(value: Any) -> bool:
+    if not isinstance(value, dict):
+        return False
+    content = value.get("content")
+    return (
+        isinstance(content, str)
+        and "total_lines" in value
+        and "file_size" in value
+        and "is_binary" in value
+        and "is_image" in value
+        and not value.get("error")
+    )
+
+
+def _parse_read_file_lines(content: str) -> list[dict[str, Any]]:
+    if not isinstance(content, str) or not content:
+        return []
+
+    lines = []
+    for raw_line in content.splitlines():
+        match = _READ_FILE_LINE_RE.match(raw_line)
+        if not match:
+            return []
+        lines.append({
+            "line": int(match.group(1)),
+            "text": match.group(2),
+        })
+    return lines
+
+
+def _build_read_file_preview(lines: list[dict[str, Any]]) -> dict[str, Any]:
+    if len(lines) <= (_READ_FILE_HEAD_LINES + _READ_FILE_TAIL_LINES):
+        return {"lines": lines}
+
+    return {
+        "head": lines[:_READ_FILE_HEAD_LINES],
+        "tail": lines[-_READ_FILE_TAIL_LINES:],
+        "omitted_line_count": len(lines) - _READ_FILE_HEAD_LINES - _READ_FILE_TAIL_LINES,
+    }
+
+
+def _normalize_read_file_payload(value: dict[str, Any], *, args: Any = None) -> dict[str, Any]:
+    normalized: dict[str, Any] = {}
+    if isinstance(args, dict):
+        path = args.get("path")
+        offset = args.get("offset")
+        limit = args.get("limit")
+        if isinstance(path, str) and path:
+            normalized["path"] = path
+        if isinstance(offset, int):
+            normalized["offset"] = offset
+        if isinstance(limit, int):
+            normalized["limit"] = limit
+
+    lines = _parse_read_file_lines(value.get("content", ""))
+    if lines:
+        normalized["returned_lines"] = {
+            "start": lines[0]["line"],
+            "end": lines[-1]["line"],
+            "count": len(lines),
+        }
+        normalized["content_preview"] = _build_read_file_preview(lines)
+    elif value.get("content"):
+        normalized["content_preview"] = {
+            "text": value.get("content", ""),
+        }
+
+    for key in (
+        "total_lines",
+        "file_size",
+        "truncated",
+        "is_binary",
+        "is_image",
+        "hint",
+        "_warning",
+        "mime_type",
+        "dimensions",
+        "similar_files",
+        "error",
+    ):
+        if key in value:
+            normalized[key] = value[key]
+
+    base64_content = value.get("base64_content")
+    if isinstance(base64_content, str) and base64_content:
+        normalized["base64_content"] = {
+            "omitted": True,
+            "length": len(base64_content),
+        }
+
+    return normalized
+
+
+def _normalize_payload(value: Any, *, tool_name: str = "", args: Any = None) -> Any:
+    if _looks_like_read_file_payload(value):
+        return _normalize_read_file_payload(
+            value,
+            args=args if tool_name == "read_file" else None,
+        )
+    return value
+
+
+def _safe_value(value: Any, *, max_chars: Optional[int] = None, depth: int = 0,
+                parse_json_strings: bool = False) -> Any:
+    max_chars = max_chars if max_chars is not None else int(_env("HERMES_LANGFUSE_MAX_CHARS", "12000") or "12000")
+    if depth > 4:
+        return "<max-depth>"
+    if value is None or isinstance(value, (int, float, bool)):
+        return value
+    if isinstance(value, bytes):
+        return {"type": "bytes", "len": len(value)}
+    if isinstance(value, str):
+        if parse_json_strings:
+            parsed = _maybe_parse_json_string(value)
+            if parsed is not value:
+                return _safe_value(parsed, max_chars=max_chars, depth=depth, parse_json_strings=True)
+        return _truncate_text(value, max_chars)
+    if isinstance(value, dict):
+        normalized = _normalize_payload(value)
+        if normalized is not value:
+            return _safe_value(normalized, max_chars=max_chars, depth=depth, parse_json_strings=parse_json_strings)
+        return {
+            str(k): _safe_value(v, max_chars=max_chars, depth=depth + 1, parse_json_strings=parse_json_strings)
+            for k, v in list(value.items())[:50]
+        }
+    if isinstance(value, (list, tuple, set)):
+        return [
+            _safe_value(v, max_chars=max_chars, depth=depth + 1, parse_json_strings=parse_json_strings)
+            for v in list(value)[:50]
+        ]
+    if hasattr(value, "__dict__"):
+        return _safe_value(vars(value), max_chars=max_chars, depth=depth + 1, parse_json_strings=parse_json_strings)
+    return _truncate_text(repr(value), max_chars)
+
+
+def _extract_last_user_message(messages: Any) -> Any:
+    if not isinstance(messages, list):
+        return None
+    for message in reversed(messages):
+        if isinstance(message, dict) and message.get("role") == "user":
+            return {
+                "role": "user",
+                "content": _safe_value(message.get("content")),
+            }
+    return None
+
+
+def _serialize_messages(messages: Any) -> list[dict[str, Any]]:
+    if not isinstance(messages, list):
+        return []
+    serialized = []
+    for message in messages[-12:]:
+        if not isinstance(message, dict):
+            continue
+        role = message.get("role")
+        item = {
+            "role": role,
+            "content": _safe_value(
+                message.get("content"),
+                parse_json_strings=(role == "tool"),
+            ),
+        }
+        if role == "tool" and message.get("tool_call_id"):
+            item["tool_call_id"] = message.get("tool_call_id")
+        if message.get("tool_calls"):
+            item["tool_calls"] = _safe_value(message.get("tool_calls"), parse_json_strings=True)
+        serialized.append(item)
+    return serialized
+
+
+def _serialize_tool_calls(tool_calls: Any) -> list[dict[str, Any]]:
+    if not tool_calls:
+        return []
+    serialized = []
+    for tool_call in tool_calls:
+        fn = getattr(tool_call, "function", None)
+        name = getattr(fn, "name", None) if fn else None
+        arguments = getattr(fn, "arguments", None) if fn else None
+        if isinstance(arguments, str):
+            try:
+                arguments = json.loads(arguments)
+            except Exception:
+                pass
+        serialized.append({
+            "id": getattr(tool_call, "id", None),
+            "name": name,
+            "arguments": _safe_value(arguments, parse_json_strings=True),
+        })
+    return serialized
+
+
+def _serialize_assistant_message(message: Any) -> dict[str, Any]:
+    return {
+        "content": _safe_value(getattr(message, "content", None)),
+        "reasoning": _safe_value(getattr(message, "reasoning", None)),
+        "tool_calls": _serialize_tool_calls(getattr(message, "tool_calls", None)),
+    }
+
+
+def _usage_and_cost(response: Any, *, provider: str, api_mode: str, model: str, base_url: str) -> tuple[dict[str, int], dict[str, float]]:
+    usage_details: Dict[str, int] = {}
+    cost_details: Dict[str, float] = {}
+    raw_usage = getattr(response, "usage", None)
+    if not raw_usage:
+        return usage_details, cost_details
+
+    try:
+        from agent.usage_pricing import estimate_usage_cost, normalize_usage
+
+        canonical = normalize_usage(raw_usage, provider=provider, api_mode=api_mode)
+        # Langfuse usage_details keys follow a naming convention:
+        #   - Dashboard sums all keys containing "input" as input total
+        #   - Dashboard sums all keys containing "output" as output total
+        #   - If no "total" key, Langfuse derives it from all usage types
+        # Use Anthropic-style key names so cache tokens roll into the
+        # dashboard input total automatically.
+        # Ref: https://langfuse.com/docs/model-usage-and-cost
+        usage_details = {
+            "input": canonical.input_tokens,
+            "output": canonical.output_tokens,
+        }
+        if canonical.cache_read_tokens:
+            usage_details["cache_read_input_tokens"] = canonical.cache_read_tokens
+        if canonical.cache_write_tokens:
+            usage_details["cache_creation_input_tokens"] = canonical.cache_write_tokens
+        if canonical.reasoning_tokens:
+            usage_details["reasoning_tokens"] = canonical.reasoning_tokens
+        cost = estimate_usage_cost(
+            model,
+            canonical,
+            provider=provider,
+            base_url=base_url,
+            api_key="",
+        )
+        if cost.amount_usd is not None:
+            # Langfuse cost_details keys must match usage_details keys.
+            # Provide per-type breakdown so dashboard can show cost by type.
+            try:
+                from agent.usage_pricing import get_pricing_entry
+                from decimal import Decimal
+                _ONE_M = Decimal("1000000")
+                entry = get_pricing_entry(model, provider=provider, base_url=base_url)
+                if entry:
+                    if entry.input_cost_per_million is not None and canonical.input_tokens:
+                        cost_details["input"] = float(Decimal(canonical.input_tokens) * entry.input_cost_per_million / _ONE_M)
+                    if entry.output_cost_per_million is not None and canonical.output_tokens:
+                        cost_details["output"] = float(Decimal(canonical.output_tokens) * entry.output_cost_per_million / _ONE_M)
+                    if entry.cache_read_cost_per_million is not None and canonical.cache_read_tokens:
+                        cost_details["cache_read_input_tokens"] = float(Decimal(canonical.cache_read_tokens) * entry.cache_read_cost_per_million / _ONE_M)
+                    if entry.cache_write_cost_per_million is not None and canonical.cache_write_tokens:
+                        cost_details["cache_creation_input_tokens"] = float(Decimal(canonical.cache_write_tokens) * entry.cache_write_cost_per_million / _ONE_M)
+                else:
+                    cost_details["total"] = float(cost.amount_usd)
+            except Exception:
+                cost_details["total"] = float(cost.amount_usd)
+    except Exception as exc:  # pragma: no cover - fail-open
+        _debug(f"usage normalization failed: {exc}")
+
+    return usage_details, cost_details
+
+
+def _start_root_trace(task_key: str, *, task_id: str, session_id: str, platform: str, provider: str, model: str,
+                      api_mode: str, messages: Any, client: Langfuse) -> TraceState:
+    trace_id = client.create_trace_id(seed=f"{session_id or 'sessionless'}::{task_id or task_key}")
+    trace_input = _extract_last_user_message(messages)
+    metadata = {
+        "source": "hermes",
+        "task_id": task_id,
+        "platform": platform,
+        "provider": provider,
+        "model": model,
+        "api_mode": api_mode,
+    }
+
+    # session_id must be passed in trace_context for Langfuse session grouping.
+    trace_ctx: Dict[str, Any] = {"trace_id": trace_id}
+    if session_id:
+        trace_ctx["session_id"] = session_id
+
+    if propagate_attributes is not None:
+        try:
+            with propagate_attributes(
+                session_id=session_id or task_key,
+                trace_name="Hermes turn",
+                tags=["hermes", "langfuse"],
+            ):
+                root_ctx = client.start_as_current_observation(
+                    trace_context=trace_ctx,
+                    name="Hermes turn",
+                    as_type="chain",
+                    input=trace_input,
+                    metadata=metadata,
+                    end_on_exit=False,
+                )
+                root_span = root_ctx.__enter__()
+        except Exception:
+            root_ctx = client.start_as_current_observation(
+                trace_context=trace_ctx,
+                name="Hermes turn",
+                as_type="chain",
+                input=trace_input,
+                metadata=metadata,
+                end_on_exit=False,
+            )
+            root_span = root_ctx.__enter__()
+    else:
+        root_ctx = client.start_as_current_observation(
+            trace_context=trace_ctx,
+            name="Hermes turn",
+            as_type="chain",
+            input=trace_input,
+            metadata=metadata,
+            end_on_exit=False,
+        )
+        root_span = root_ctx.__enter__()
+
+    try:
+        root_span.set_trace_io(input=trace_input)
+    except Exception:
+        pass
+
+    _debug(f"started trace {trace_id} for {task_key}")
+    return TraceState(trace_id=trace_id, root_ctx=root_ctx, root_span=root_span)
+
+
+def _start_child_observation(state: TraceState, *, client: Langfuse, name: str, as_type: str,
+                             input_value: Any, metadata: Optional[dict] = None,
+                             model: Optional[str] = None, model_parameters: Optional[dict] = None) -> Any:
+    return state.root_span.start_observation(
+        name=name,
+        as_type=as_type,
+        input=input_value,
+        metadata=metadata or {},
+        model=model,
+        model_parameters=model_parameters,
+    )
+
+
+def _end_observation(observation: Any, *, output: Any = None, metadata: Optional[dict] = None,
+                     usage_details: Optional[dict] = None, cost_details: Optional[dict] = None) -> None:
+    if observation is None:
+        return
+    try:
+        update_kwargs: Dict[str, Any] = {}
+        if output is not None:
+            update_kwargs["output"] = output
+        if metadata:
+            update_kwargs["metadata"] = metadata
+        if usage_details:
+            update_kwargs["usage_details"] = usage_details
+        if cost_details:
+            update_kwargs["cost_details"] = cost_details
+        if update_kwargs:
+            observation.update(**update_kwargs)
+        observation.end()
+    except Exception as exc:  # pragma: no cover - fail-open
+        _debug(f"end observation failed: {exc}")
+
+
+def _merge_trace_output(output: Any, state: TraceState) -> Any:
+    if not state.turn_tool_calls:
+        return output
+
+    merged = dict(output) if isinstance(output, dict) else {"content": output}
+    merged["tool_calls"] = list(state.turn_tool_calls)
+    return merged
+
+
+def _finish_trace(task_key: str, *, output: Any = None) -> None:
+    client = _get_langfuse()
+    if client is None:
+        return
+
+    with _STATE_LOCK:
+        state = _TRACE_STATE.pop(task_key, None)
+    if state is None:
+        return
+
+    try:
+        for observation in state.generations.values():
+            _end_observation(observation)
+        for observation in state.tools.values():
+            _end_observation(observation)
+        final_output = _merge_trace_output(output, state)
+        if final_output is not None:
+            state.root_span.set_trace_io(output=final_output)
+            state.root_span.update(output=final_output)
+        state.root_span.end()
+    except Exception as exc:  # pragma: no cover - fail-open
+        _debug(f"finish trace failed: {exc}")
+    finally:
+        try:
+            client.flush()
+        except Exception:
+            pass
+
+
+def _assistant_has_tool_calls(message: Any) -> bool:
+    return bool(getattr(message, "tool_calls", None))
+
+
+def _request_key(api_call_count: Any) -> str:
+    return str(api_call_count or 0)
+
+
+def on_pre_llm_call(*, task_id: str = "", session_id: str = "", platform: str = "", model: str = "",
+                    provider: str = "", base_url: str = "", api_mode: str = "",
+                    api_call_count: int = 0, messages: Any = None, turn_type: str = "user",
+                    conversation_history: Any = None, user_message: Any = None, **_: Any) -> None:
+    # Older Hermes branches used pre_llm_call for request-scoped tracing and
+    # passed the actual API messages. Current Hermes also has a turn-scoped
+    # pre_llm_call used for context injection; tracing that hook creates an
+    # extra orphan/root trace before the real request trace. Only trace the
+    # legacy request-shaped call here.
+    if not isinstance(messages, list):
+        return
+
+    client = _get_langfuse()
+    if client is None:
+        return
+
+    # messages is a list only for legacy Hermes branches that fired
+    # pre_llm_call with API messages directly. Current Hermes fires
+    # pre_llm_call for context injection (conversation_history/user_message,
+    # no messages list) — tracing that would create orphan traces.
+    task_key = _trace_key(task_id, session_id)
+
+    with _STATE_LOCK:
+        state = _TRACE_STATE.get(task_key)
+        if state is None:
+            state = _start_root_trace(
+                task_key,
+                task_id=task_id,
+                session_id=session_id,
+                platform=platform,
+                provider=provider,
+                model=model,
+                api_mode=api_mode,
+                messages=messages,
+                client=client,
+            )
+            _TRACE_STATE[task_key] = state
+        state.last_updated_at = time.time()
+
+
+def on_pre_llm_request(
+    *,
+    task_id: str = "",
+    session_id: str = "",
+    platform: str = "",
+    model: str = "",
+    provider: str = "",
+    base_url: str = "",
+    api_mode: str = "",
+    api_call_count: int = 0,
+    messages: Any = None,
+    turn_type: str = "user",
+    message_count: int = 0,
+    tool_count: int = 0,
+    approx_input_tokens: int = 0,
+    request_char_count: int = 0,
+    max_tokens: Any = None,
+    **_: Any,
+) -> None:
+    client = _get_langfuse()
+    if client is None:
+        return
+
+    task_key = _trace_key(task_id, session_id)
+    req_key = _request_key(api_call_count)
+
+    with _STATE_LOCK:
+        state = _TRACE_STATE.get(task_key)
+        if state is None:
+            state = _start_root_trace(
+                task_key,
+                task_id=task_id,
+                session_id=session_id,
+                platform=platform,
+                provider=provider,
+                model=model,
+                api_mode=api_mode,
+                messages=messages,
+                client=client,
+            )
+            _TRACE_STATE[task_key] = state
+        state.last_updated_at = time.time()
+        previous = state.generations.pop(req_key, None)
+        if previous is not None:
+            _end_observation(previous)
+        state.generations[req_key] = _start_child_observation(
+            state,
+            client=client,
+            name=f"LLM call {api_call_count}",
+            as_type="generation",
+            input_value=_serialize_messages(messages),
+            metadata={
+                "provider": provider,
+                "platform": platform,
+                "api_mode": api_mode,
+                "base_url": base_url,
+            },
+            model=model,
+            model_parameters={"api_mode": api_mode, "provider": provider},
+        )
+
+
+def on_post_llm_call(*, task_id: str = "", session_id: str = "", provider: str = "", base_url: str = "",
+                     api_mode: str = "", model: str = "", api_call_count: int = 0,
+                     assistant_message: Any = None, response: Any = None,
+                     api_duration: float = 0.0, finish_reason: str = "",
+                     usage: Any = None, assistant_content_chars: int = 0,
+                     assistant_tool_call_count: int = 0, assistant_response: Any = None,
+                     **_: Any) -> None:
+    client = _get_langfuse()
+    if client is None:
+        return
+
+    task_key = _trace_key(task_id, session_id)
+    req_key = _request_key(api_call_count)
+
+    with _STATE_LOCK:
+        state = _TRACE_STATE.get(task_key)
+        generation = state.generations.pop(req_key, None) if state else None
+    if state is None or generation is None:
+        return
+
+    # Handle both call patterns:
+    # 1. post_api_request: passes usage (dict), assistant_content_chars, assistant_tool_call_count
+    # 2. post_llm_call: passes assistant_message (object), response (object), assistant_response (str)
+    if assistant_message is not None:
+        output = _serialize_assistant_message(assistant_message)
+    elif assistant_response is not None:
+        # post_llm_call passes assistant_response as a plain string
+        output = {"content": _safe_value(assistant_response), "reasoning": None, "tool_calls": []}
+    else:
+        # post_api_request path — reconstruct from summary kwargs
+        output = {
+            "content": f"[{assistant_content_chars} chars]" if assistant_content_chars else None,
+            "reasoning": None,
+            "tool_calls": [{"id": f"tc_{i}"} for i in range(assistant_tool_call_count)] if assistant_tool_call_count else [],
+        }
+
+    if output.get("tool_calls"):
+        state.turn_tool_calls.extend(output["tool_calls"])
+
+    # Extract usage: prefer response object, fall back to usage dict from post_api_request
+    if response is not None:
+        usage_details, cost_details = _usage_and_cost(
+            response,
+            provider=provider,
+            api_mode=api_mode,
+            model=model,
+            base_url=base_url,
+        )
+    elif isinstance(usage, dict) and usage:
+        # post_api_request passes a pre-built CanonicalUsage summary dict.
+        # Use Langfuse-convention key names: "input", "output", and
+        # "cache_read_input_tokens" / "cache_creation_input_tokens" so the
+        # dashboard sums cache tokens into the input total automatically.
+        _input = usage.get("input_tokens", 0)
+        _output = usage.get("output_tokens", 0) or usage.get("completion_tokens", 0)
+        _cache_read = usage.get("cache_read_tokens", 0)
+        _cache_write = usage.get("cache_write_tokens", 0)
+        _reasoning = usage.get("reasoning_tokens", 0)
+        usage_details = {
+            "input": _input,
+            "output": _output,
+        }
+        if _cache_read:
+            usage_details["cache_read_input_tokens"] = _cache_read
+        if _cache_write:
+            usage_details["cache_creation_input_tokens"] = _cache_write
+        if _reasoning:
+            usage_details["reasoning_tokens"] = _reasoning
+        cost_details = {}
+        # Estimate per-type cost from the summary if possible
+        try:
+            from agent.usage_pricing import CanonicalUsage, estimate_usage_cost, get_pricing_entry
+            from decimal import Decimal
+            _ONE_M = Decimal("1000000")
+            _cu = CanonicalUsage(
+                input_tokens=_input,
+                output_tokens=_output,
+                cache_read_tokens=_cache_read,
+                cache_write_tokens=_cache_write,
+                reasoning_tokens=_reasoning,
+            )
+            entry = get_pricing_entry(model, provider=provider, base_url=base_url)
+            if entry:
+                if entry.input_cost_per_million is not None and _input:
+                    cost_details["input"] = float(Decimal(_input) * entry.input_cost_per_million / _ONE_M)
+                if entry.output_cost_per_million is not None and _output:
+                    cost_details["output"] = float(Decimal(_output) * entry.output_cost_per_million / _ONE_M)
+                if entry.cache_read_cost_per_million is not None and _cache_read:
+                    cost_details["cache_read_input_tokens"] = float(Decimal(_cache_read) * entry.cache_read_cost_per_million / _ONE_M)
+                if entry.cache_write_cost_per_million is not None and _cache_write:
+                    cost_details["cache_creation_input_tokens"] = float(Decimal(_cache_write) * entry.cache_write_cost_per_million / _ONE_M)
+            else:
+                _cost = estimate_usage_cost(model, _cu, provider=provider, base_url=base_url, api_key="")
+                if _cost.amount_usd is not None:
+                    cost_details["total"] = float(_cost.amount_usd)
+        except Exception:
+            pass
+    else:
+        usage_details, cost_details = {}, {}
+
+    tool_count = len(output.get("tool_calls", [])) or assistant_tool_call_count
+    gen_metadata: Dict[str, Any] = {"tool_call_count": tool_count}
+    if api_duration and api_duration > 0:
+        gen_metadata["api_duration_s"] = round(api_duration, 3)
+    if finish_reason:
+        gen_metadata["finish_reason"] = finish_reason
+    _end_observation(
+        generation,
+        output=output,
+        usage_details=usage_details,
+        cost_details=cost_details,
+        metadata=gen_metadata,
+    )
+
+    has_tools = _assistant_has_tool_calls(assistant_message) if assistant_message else (assistant_tool_call_count > 0)
+    has_content = bool(output.get("content"))
+    if not has_tools and has_content:
+        _finish_trace(task_key, output=output)
+
+
+def on_pre_tool_call(*, tool_name: str = "", args: Any = None, task_id: str = "",
+                     session_id: str = "", tool_call_id: str = "", **_: Any) -> None:
+    client = _get_langfuse()
+    if client is None:
+        return
+
+    task_key = _trace_key(task_id, session_id)
+    tool_key = tool_call_id or f"{tool_name}:{time.time_ns()}"
+
+    with _STATE_LOCK:
+        state = _TRACE_STATE.get(task_key)
+        if state is None:
+            return
+        state.tools[tool_key] = _start_child_observation(
+            state,
+            client=client,
+            name=f"Tool: {tool_name}",
+            as_type="tool",
+            input_value=_safe_value(args),
+            metadata={"tool_name": tool_name, "tool_call_id": tool_call_id},
+        )
+
+
+def on_post_tool_call(*, tool_name: str = "", args: Any = None, result: Any = None,
+                      task_id: str = "", session_id: str = "", tool_call_id: str = "", **_: Any) -> None:
+    task_key = _trace_key(task_id, session_id)
+    tool_key = tool_call_id or ""
+    observation = None
+
+    with _STATE_LOCK:
+        state = _TRACE_STATE.get(task_key)
+        if state is None:
+            return
+        if tool_key:
+            observation = state.tools.pop(tool_key, None)
+        elif state.tools:
+            _, observation = state.tools.popitem()
+
+    if observation is None:
+        return
+
+    if isinstance(result, str):
+        result_value = _maybe_parse_json_string(result)
+    else:
+        result_value = result
+    result_value = _normalize_payload(result_value, tool_name=tool_name, args=args)
+
+    _end_observation(
+        observation,
+        output=_safe_value(result_value, parse_json_strings=True),
+        metadata={"tool_name": tool_name, "args": _safe_value(args, parse_json_strings=True)},
+    )
+
+
+def register(ctx) -> None:
+    # Register for both hook name variants so the plugin works across
+    # Hermes versions.  pre_api_request / post_api_request fire per API
+    # call (preferred); pre_llm_call / post_llm_call fire once per turn.
+    ctx.register_hook("pre_api_request", on_pre_llm_request)
+    ctx.register_hook("post_api_request", on_post_llm_call)
+    ctx.register_hook("pre_llm_call", on_pre_llm_call)
+    ctx.register_hook("post_llm_call", on_post_llm_call)
+    ctx.register_hook("pre_tool_call", on_pre_tool_call)
+    ctx.register_hook("post_tool_call", on_post_tool_call)

optional-plugins/observability/langfuse/after-install.md

@@ -0,0 +1,38 @@
+# After installing langfuse
+
+Langfuse tracing is now installed and enabled for your Hermes profile.
+
+## Required credentials
+
+Set these in `~/.hermes/.env` (or via `hermes tools` → Langfuse Observability):
+
+```bash
+HERMES_LANGFUSE_PUBLIC_KEY=pk-lf-...
+HERMES_LANGFUSE_SECRET_KEY=sk-lf-...
+HERMES_LANGFUSE_BASE_URL=https://cloud.langfuse.com   # or your self-hosted URL
+```
+
+## Verify
+
+```bash
+hermes plugins list          # langfuse should appear as enabled
+hermes chat -q "hello"       # then check Langfuse for a "Hermes turn" trace
+```
+
+## Optional settings
+
+```bash
+HERMES_LANGFUSE_ENV=production       # environment tag
+HERMES_LANGFUSE_RELEASE=v1.0.0      # release tag
+HERMES_LANGFUSE_SAMPLE_RATE=0.5     # sample 50% of traces
+HERMES_LANGFUSE_MAX_CHARS=12000     # max chars per field (default: 12000)
+HERMES_LANGFUSE_DEBUG=true          # verbose plugin logging
+```
+
+## Dependencies
+
+The `langfuse` Python SDK is required. Install it into your Hermes venv:
+
+```bash
+pip install langfuse
+```

optional-plugins/observability/langfuse/plugin.yaml

@@ -0,0 +1,14 @@
+name: langfuse
+version: "1.0.0"
+description: "Optional Langfuse observability for Hermes — traces conversations, LLM calls, and tool usage. Install via: hermes plugins install official/observability/langfuse"
+author: NousResearch
+requires_env:
+  - HERMES_LANGFUSE_PUBLIC_KEY
+  - HERMES_LANGFUSE_SECRET_KEY
+hooks:
+  - pre_api_request
+  - post_api_request
+  - pre_llm_call
+  - post_llm_call
+  - pre_tool_call
+  - post_tool_call

providers/README.md

@@ -1,307 +0,0 @@
-# providers/
-
-Single source of truth for every inference provider Hermes knows about.
-
-Each provider is declared once here as a `ProviderProfile`. Every other layer —
-auth resolution, transport kwargs, model listing, runtime routing — reads from
-these profiles instead of maintaining its own parallel data.
-
----
-
-## Directory layout
-
-```
-providers/
-├── base.py           ProviderProfile dataclass + OMIT_TEMPERATURE sentinel
-├── __init__.py       Registry: register_provider(), get_provider_profile()
-├── README.md         This file
-│
-├── # Simple providers — just identity + auth + endpoint
-├── alibaba.py        Alibaba Cloud DashScope
-├── arcee.py          Arcee AI
-├── bedrock.py        AWS Bedrock  (api_mode=bedrock_converse)
-├── deepseek.py       DeepSeek
-├── huggingface.py    Hugging Face Inference API
-├── kilocode.py       Kilo Code
-├── minimax.py        MiniMax (international + CN)
-├── nvidia.py         NVIDIA NIM  (default_max_tokens=16384)
-├── ollama_cloud.py   Ollama Cloud
-├── stepfun.py        StepFun
-├── xiaomi.py         Xiaomi MiMo
-├── xai.py            xAI Grok  (api_mode=codex_responses)
-├── zai.py            Z.AI / GLM
-│
-├── # Medium — one or two quirks
-├── anthropic.py      Native Anthropic  (x-api-key header, api_mode=anthropic_messages)
-├── copilot.py        GitHub Copilot  (auth_type=copilot, reasoning per model)
-├── copilot_acp.py    Copilot ACP subprocess  (api_mode=copilot_acp)
-├── custom.py         Custom/Ollama local  (think=false, num_ctx)
-├── gemini.py         Google Gemini AI Studio + Cloud Code OAuth
-├── kimi.py           Kimi Coding  (OMIT_TEMPERATURE, thinking, dual endpoint)
-├── openai_codex.py   OpenAI Codex OAuth  (api_mode=codex_responses)
-├── opencode.py       OpenCode Zen + Go  (per-model api_mode routing)
-│
-├── # Complex — subclasses with multiple overrides
-├── nous.py           Nous Portal  (tags, attribution, reasoning omit-when-disabled)
-├── openrouter.py     OpenRouter  (provider preferences, public model fetch)
-├── qwen.py           Qwen OAuth  (message normalization, cache_control, vl_hires)
-└── vercel.py         Vercel AI Gateway  (attribution headers, reasoning passthrough)
-```
-
----
-
-## ProviderProfile fields
-
-```python
-@dataclass
-class ProviderProfile:
-    # Identity
-    name: str                    # canonical ID — auto-registered as PROVIDER_REGISTRY key for new api-key providers
-    api_mode: str                # "chat_completions" | "anthropic_messages" |
-                                 # "codex_responses" | "bedrock_converse" | "copilot_acp"
-    aliases: tuple               # alternate names resolved by get_provider_profile()
-
-    # Auth & endpoints
-    env_vars: tuple              # env var names holding the API key, in priority order
-    base_url: str                # default inference endpoint
-    models_url: str              # explicit models endpoint; falls back to {base_url}/models
-                                 # set when the models catalog lives at a different URL
-                                 # (e.g. OpenRouter: public /api/v1/models vs /api/v1 inference)
-    auth_type: str               # "api_key" | "oauth_device_code" | "oauth_external" |
-                                 # "copilot" | "aws" | "external_process"
-
-    # Client-level quirks
-    default_headers: dict        # extra HTTP headers sent on every request
-
-    # Request-level quirks
-    fixed_temperature: Any       # None = use caller's default; OMIT_TEMPERATURE = don't send
-    default_max_tokens: int|None # inject max_tokens when caller omits it
-    default_aux_model: str       # cheap model for auxiliary tasks (compression, vision, etc.)
-                                 # empty string = use main model (default)
-```
-
----
-
-## Hooks (override in a subclass)
-
-| Method | When to override |
-|--------|-----------------|
-| `prepare_messages(messages)` | Provider needs message pre-processing (Qwen: string → list-of-parts, cache_control) |
-| `build_extra_body(*, session_id, **ctx)` | Provider-specific `extra_body` fields (Nous: tags, OpenRouter: provider preferences) |
-| `build_api_kwargs_extras(*, reasoning_config, **ctx)` | Returns `(extra_body_additions, top_level_kwargs)` — use when some fields go to `extra_body` and some go top-level (Kimi: `reasoning_effort` top-level; OpenRouter: `reasoning` in extra_body) |
-| `fetch_models(*, api_key, timeout)` | Custom model listing (Anthropic: x-api-key header; OpenRouter: public endpoint, no auth; Bedrock/copilot-acp: return None) |
-
-All hooks have safe defaults — only override what differs from the base.
-
----
-
-## How to add a new provider
-
-### 1. Simple (standard OpenAI-compatible endpoint)
-
-```python
-# providers/myprovider.py
-from providers import register_provider
-from providers.base import ProviderProfile
-
-myprovider = ProviderProfile(
-    name="myprovider",           # must match id in hermes_cli/auth.py PROVIDER_REGISTRY
-    aliases=("my-provider", "myp"),
-    api_mode="chat_completions",
-    env_vars=("MYPROVIDER_API_KEY",),
-    base_url="https://api.myprovider.com/v1",
-    auth_type="api_key",
-)
-
-register_provider(myprovider)
-```
-
-The default `fetch_models()` will call `GET https://api.myprovider.com/v1/models`
-with Bearer auth automatically. No override needed for standard `/v1/models`.
-
-### 2. With quirks (subclass)
-
-```python
-# providers/myprovider.py
-from typing import Any
-from providers import register_provider
-from providers.base import ProviderProfile
-
-
-class MyProviderProfile(ProviderProfile):
-    """My provider — custom reasoning header."""
-
-    def build_api_kwargs_extras(
-        self,
-        *,
-        reasoning_config: dict | None = None,
-        **ctx: Any,
-    ) -> tuple[dict[str, Any], dict[str, Any]]:
-        extra_body: dict[str, Any] = {}
-        if reasoning_config:
-            extra_body["my_reasoning"] = reasoning_config.get("effort", "medium")
-        return extra_body, {}
-
-    def fetch_models(
-        self,
-        *,
-        api_key: str | None = None,
-        timeout: float = 8.0,
-    ) -> list[str] | None:
-        # Override only if your endpoint differs from standard /v1/models
-        return super().fetch_models(api_key=api_key, timeout=timeout)
-
-
-myprovider = MyProviderProfile(
-    name="myprovider",
-    aliases=("myp",),
-    env_vars=("MYPROVIDER_API_KEY",),
-    base_url="https://api.myprovider.com/v1",
-)
-
-register_provider(myprovider)
-```
-
-### 3. Wire it up
-
-After creating the file, add `name` to the `_PROFILE_ACTIVE_PROVIDERS` set in
-`run_agent.py` once you've verified parity against the legacy flag path. Start
-with a simple provider (no message prep, no reasoning quirks) and work up.
-
----
-
-## fetch_models contract
-
-```python
-def fetch_models(
-    self,
-    *,
-    api_key: str | None = None,
-    timeout: float = 8.0,
-) -> list[str] | None:
-    ...
-```
-
-- Returns `list[str]`: model IDs from the provider's live endpoint.
-- Returns `None`: provider doesn't support REST model listing (Bedrock, copilot-acp),
-  or the request failed. Callers **must** fall back to `_PROVIDER_MODELS` on `None`.
-- Never raises — swallow exceptions and return `None`.
-- Default implementation: `GET {base_url}/models` with Bearer auth. Works for any
-  standard OpenAI-compatible provider.
-
-**Override when:**
-- Auth header is not `Bearer` (Anthropic: `x-api-key`)
-- Endpoint path differs from `/models` AND you can't just set `models_url` (OpenRouter: public endpoint, pass `api_key=None` explicitly)
-- Response format differs (extra wrapping, non-standard `id` field)
-- Provider has no REST endpoint (Bedrock, copilot-acp → return `None`)
-- Filtering needed post-fetch (only tool-capable models, etc.)
-
-Use `models_url` instead of overriding when the only difference is the URL:
-
-```python
-# No subclass needed — just set models_url
-myprovider = ProviderProfile(
-    name="myprovider",
-    base_url="https://api.myprovider.com/v1",
-    models_url="https://catalog.myprovider.com/models",  # different host
-)
-```
-
----
-
-## Debugging
-
-### Check if a provider resolves
-
-```python
-from providers import get_provider_profile
-
-p = get_provider_profile("myprovider")
-print(p)           # ProviderProfile(name='myprovider', ...)
-print(p.base_url)
-print(p.api_mode)
-```
-
-### Check all registered providers
-
-```python
-from providers import _REGISTRY
-print(list(_REGISTRY.keys()))
-```
-
-### Test live model fetch
-
-```python
-import os
-from providers import get_provider_profile
-
-p = get_provider_profile("myprovider")
-key = os.getenv("MYPROVIDER_API_KEY")
-models = p.fetch_models(api_key=key, timeout=5.0)
-print(models)      # list of model IDs, or None on failure
-```
-
-### Test alias resolution
-
-```python
-from providers import get_provider_profile
-
-# All of these should return the same profile
-assert get_provider_profile("openrouter").name == "openrouter"
-assert get_provider_profile("or").name == "openrouter"
-```
-
-### Run the provider test suite
-
-```bash
-# From the repo root
-source venv/bin/activate
-python -m pytest tests/providers/ -v
-```
-
-### Check ruff + ty compliance
-
-```bash
-source venv/bin/activate
-ruff format providers/*.py
-ruff check providers/*.py --select UP,E,F,I,W
-ty check providers/*.py
-```
-
----
-
-## Common mistakes
-
-**Wrong `name`** — must be the same string that appears as the key in
-`hermes_cli/auth.py` `PROVIDER_REGISTRY`. New api-key providers auto-register
-into `PROVIDER_REGISTRY` from the profile, so the name IS the key. For providers
-with a pre-existing `PROVIDER_REGISTRY` entry, use the exact `id` field value.
-
-**Wrong `env_vars`** — separate API-key vars from base-URL override vars in the
-tuple. Env vars that end with `_BASE_URL` or `_URL` are treated as URL overrides;
-everything else is treated as an API key. Getting this wrong causes the doctor
-health check to send a URL string as a Bearer token.
-
-**Wrong `base_url`** — several providers have non-obvious paths:
-`stepfun: /step_plan/v1`, `opencode-go: /zen/go/v1`. The profile's `base_url`
-is also used as the `inference_base_url` when auto-registering into `PROVIDER_REGISTRY`
-for new providers, so it must be correct for auth resolution to work.
-
-**Skipping `api_mode`** — defaults to `chat_completions`. Providers that use
-`anthropic_messages`, `codex_responses`, `bedrock_converse`, or `copilot_acp`
-must set it explicitly.
-
-**Forgetting `register_provider()`** — auto-discovery runs `pkgutil.iter_modules`
-over the package and imports each module, but only if `register_provider()` is
-called at module level. Without it the profile is never in `_REGISTRY`.
-
-**`fetch_models` returning the wrong shape** — must return `list[str]` (plain
-model IDs), not `list[tuple]` or `list[dict]`. Callers expect plain strings.
-
-**Wrong `build_api_kwargs_extras` return shape** — must return a 2-tuple
-`(extra_body_dict, top_level_dict)`. Returning a single dict causes a
-`ValueError: not enough values to unpack` in the transport.
-
-**`build_api_kwargs_extras` wrong tuple** — must return `(extra_body_dict,
-top_level_dict)`. Returning a flat dict or swapping the order silently sends
-fields to the wrong place.

providers/__init__.py

@@ -1,76 +0,0 @@
-"""Provider module registry.
-
-Auto-discovers ProviderProfile instances from providers/*.py modules.
-Each module should define a module-level PROVIDER or PROVIDERS list.
-
-Usage:
-    from providers import get_provider_profile
-    profile = get_provider_profile("nvidia")  # returns ProviderProfile or None
-    profile = get_provider_profile("kimi")    # checks name + aliases
-"""
-
-from __future__ import annotations
-
-from providers.base import OMIT_TEMPERATURE, ProviderProfile  # noqa: F401
-
-_REGISTRY: dict[str, ProviderProfile] = {}
-_ALIASES: dict[str, str] = {}
-_discovered = False
-
-
-def register_provider(profile: ProviderProfile) -> None:
-    """Register a provider profile by name and aliases."""
-    _REGISTRY[profile.name] = profile
-    for alias in profile.aliases:
-        _ALIASES[alias] = profile.name
-
-
-def get_provider_profile(name: str) -> ProviderProfile | None:
-    """Look up a provider profile by name or alias.
-
-    Returns None if the provider has no profile (falls back to generic).
-    """
-    if not _discovered:
-        _discover_providers()
-    canonical = _ALIASES.get(name, name)
-    return _REGISTRY.get(canonical)
-
-
-def list_providers() -> list[ProviderProfile]:
-    """Return all registered provider profiles (one per canonical name)."""
-    if not _discovered:
-        _discover_providers()
-    # Deduplicate: _REGISTRY has canonical names; _ALIASES points to same objects
-    seen: set[int] = set()
-    result: list[ProviderProfile] = []
-    for profile in _REGISTRY.values():
-        pid = id(profile)
-        if pid not in seen:
-            seen.add(pid)
-            result.append(profile)
-    return result
-
-
-def _discover_providers() -> None:
-    """Import all provider modules to trigger registration."""
-    global _discovered
-    if _discovered:
-        return
-    _discovered = True
-
-    import importlib
-    import pkgutil
-
-    import providers as _pkg
-
-    for _importer, modname, _ispkg in pkgutil.iter_modules(_pkg.__path__):
-        if modname.startswith("_") or modname == "base":
-            continue
-        try:
-            importlib.import_module(f"providers.{modname}")
-        except ImportError as e:
-            import logging
-
-            logging.getLogger(__name__).warning(
-                "Failed to import provider module %s: %s", modname, e
-            )

providers/alibaba.py

@@ -1,13 +0,0 @@
-"""Alibaba Cloud DashScope provider profile."""
-
-from providers import register_provider
-from providers.base import ProviderProfile
-
-alibaba = ProviderProfile(
-    name="alibaba",
-    aliases=("dashscope", "alibaba-cloud", "qwen-dashscope"),
-    env_vars=("DASHSCOPE_API_KEY",),
-    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
-)
-
-register_provider(alibaba)

providers/anthropic.py

@@ -1,52 +0,0 @@
-"""Native Anthropic provider profile."""
-
-import json
-import logging
-import urllib.request
-
-from providers import register_provider
-from providers.base import ProviderProfile
-
-logger = logging.getLogger(__name__)
-
-
-class AnthropicProfile(ProviderProfile):
-    """Native Anthropic — uses x-api-key header, not Bearer."""
-
-    def fetch_models(
-        self,
-        *,
-        api_key: str | None = None,
-        timeout: float = 8.0,
-    ) -> list[str] | None:
-        """Anthropic uses x-api-key header and anthropic-version."""
-        if not api_key:
-            return None
-        try:
-            req = urllib.request.Request("https://api.anthropic.com/v1/models")
-            req.add_header("x-api-key", api_key)
-            req.add_header("anthropic-version", "2023-06-01")
-            req.add_header("Accept", "application/json")
-            with urllib.request.urlopen(req, timeout=timeout) as resp:
-                data = json.loads(resp.read().decode())
-            return [
-                m["id"]
-                for m in data.get("data", [])
-                if isinstance(m, dict) and "id" in m
-            ]
-        except Exception as exc:
-            logger.debug("fetch_models(anthropic): %s", exc)
-            return None
-
-
-anthropic = AnthropicProfile(
-    name="anthropic",
-    aliases=("claude", "claude-oauth", "claude-code"),
-    api_mode="anthropic_messages",
-    env_vars=("ANTHROPIC_API_KEY", "ANTHROPIC_TOKEN", "CLAUDE_CODE_OAUTH_TOKEN"),
-    base_url="https://api.anthropic.com",
-    auth_type="api_key",
-    default_aux_model="claude-haiku-4-5-20251001",
-)
-
-register_provider(anthropic)

providers/arcee.py

@@ -1,13 +0,0 @@
-"""Arcee AI provider profile."""
-
-from providers import register_provider
-from providers.base import ProviderProfile
-
-arcee = ProviderProfile(
-    name="arcee",
-    aliases=("arcee-ai", "arceeai"),
-    env_vars=("ARCEEAI_API_KEY",),
-    base_url="https://api.arcee.ai/api/v1",
-)
-
-register_provider(arcee)

providers/base.py

@@ -1,165 +0,0 @@
-"""Provider profile base class.
-
-A ProviderProfile declares everything about an inference provider in one place:
-auth, endpoints, client quirks, request-time quirks. The transport reads this
-instead of receiving 20+ boolean flags.
-
-Provider profiles are DECLARATIVE — they describe the provider's behavior.
-They do NOT own client construction, credential rotation, or streaming.
-Those stay on AIAgent.
-"""
-
-from __future__ import annotations
-
-import logging
-from dataclasses import dataclass, field
-from typing import Any
-
-logger = logging.getLogger(__name__)
-
-# Sentinel for "omit temperature entirely" (Kimi: server manages it)
-OMIT_TEMPERATURE = object()
-
-
-@dataclass
-class ProviderProfile:
-    """Base provider profile — subclass or instantiate with overrides."""
-
-    # ── Identity ─────────────────────────────────────────────
-    name: str
-    api_mode: str = "chat_completions"
-    aliases: tuple = ()
-
-    # ── Human-readable metadata ───────────────────────────────
-    display_name: str = ""       # e.g. "GMI Cloud" — shown in picker/labels
-    description: str = ""        # e.g. "GMI Cloud (multi-model direct API)" — picker subtitle
-    signup_url: str = ""         # e.g. "https://www.gmicloud.ai/" — shown during setup
-
-    # ── Auth & endpoints ─────────────────────────────────────
-    env_vars: tuple = ()
-    base_url: str = ""
-    models_url: str = ""  # explicit models endpoint; falls back to {base_url}/models
-    auth_type: str = "api_key"   # api_key|oauth_device_code|oauth_external|copilot|aws_sdk
-
-    # ── Model catalog ─────────────────────────────────────────
-    # fallback_models: curated list shown in /model picker when live fetch fails.
-    # Only agentic models that support tool calling should appear here.
-    fallback_models: tuple = ()
-
-    # hostname: base hostname for URL→provider reverse-mapping in model_metadata.py
-    # e.g. "api.gmi-serving.com". Derived from base_url when empty.
-    hostname: str = ""
-
-    # ── Client-level quirks (set once at client construction) ─
-    default_headers: dict[str, str] = field(default_factory=dict)
-
-    # ── Request-level quirks ─────────────────────────────────
-    # Temperature: None = use caller's default, OMIT_TEMPERATURE = don't send
-    fixed_temperature: Any = None
-    default_max_tokens: int | None = None
-    default_aux_model: str = (
-        ""  # cheap model for auxiliary tasks (compression, vision, etc.)
-    )
-    # empty = use main model
-
-    # ── Hooks (override in subclass for complex providers) ───
-
-    def get_hostname(self) -> str:
-        """Return the provider's base hostname for URL-based detection.
-
-        Uses self.hostname if set explicitly, otherwise derives it from base_url.
-        e.g. 'https://api.gmi-serving.com/v1' → 'api.gmi-serving.com'
-        """
-        if self.hostname:
-            return self.hostname
-        if self.base_url:
-            from urllib.parse import urlparse
-            return urlparse(self.base_url).hostname or ""
-        return ""
-
-    def prepare_messages(self, messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
-        """Provider-specific message preprocessing.
-
-        Called AFTER codex field sanitization, BEFORE developer role swap.
-        Default: pass-through.
-        """
-        return messages
-
-    def build_extra_body(
-        self, *, session_id: str | None = None, **context: Any
-    ) -> dict[str, Any]:
-        """Provider-specific extra_body fields.
-
-        Merged into the API kwargs extra_body. Default: empty dict.
-        """
-        return {}
-
-    def build_api_kwargs_extras(
-        self,
-        *,
-        reasoning_config: dict | None = None,
-        **context: Any,
-    ) -> tuple[dict[str, Any], dict[str, Any]]:
-        """Provider-specific kwargs split between extra_body and top-level api_kwargs.
-
-        Returns (extra_body_additions, top_level_kwargs).
-        The transport merges extra_body_additions into extra_body, and
-        top_level_kwargs directly into api_kwargs.
-
-        This split exists because some providers put reasoning config in
-        extra_body (OpenRouter: extra_body.reasoning) while others put it
-        as top-level api_kwargs (Kimi: api_kwargs.reasoning_effort).
-
-        Default: ({}, {}).
-        """
-        return {}, {}
-
-    def fetch_models(
-        self,
-        *,
-        api_key: str | None = None,
-        timeout: float = 8.0,
-    ) -> list[str] | None:
-        """Fetch the live model list from the provider's models endpoint.
-
-        Returns a list of model ID strings, or None if the fetch failed or
-        the provider does not support live model listing.
-
-        Resolution order for the endpoint URL:
-          1. self.models_url  (explicit override — use when the models
-             endpoint differs from the inference base URL, e.g. OpenRouter
-             exposes a public catalog at /api/v1/models while inference is
-             at /api/v1)
-          2. self.base_url + "/models"  (standard OpenAI-compat fallback)
-
-        The default implementation sends Bearer auth when api_key is given
-        and forwards self.default_headers. Override to customise auth, path,
-        response shape, or to return None for providers with no REST catalog.
-
-        Callers must always fall back to the static _PROVIDER_MODELS list
-        when this returns None.
-        """
-        url = (self.models_url or "").strip()
-        if not url:
-            if not self.base_url:
-                return None
-            url = self.base_url.rstrip("/") + "/models"
-
-        import json
-        import urllib.request
-
-        req = urllib.request.Request(url)
-        if api_key:
-            req.add_header("Authorization", f"Bearer {api_key}")
-        req.add_header("Accept", "application/json")
-        for k, v in self.default_headers.items():
-            req.add_header(k, v)
-
-        try:
-            with urllib.request.urlopen(req, timeout=timeout) as resp:
-                data = json.loads(resp.read().decode())
-            items = data if isinstance(data, list) else data.get("data", [])
-            return [m["id"] for m in items if isinstance(m, dict) and "id" in m]
-        except Exception as exc:
-            logger.debug("fetch_models(%s): %s", self.name, exc)
-            return None

providers/bedrock.py

@@ -1,29 +0,0 @@
-"""AWS Bedrock provider profile."""
-
-from providers import register_provider
-from providers.base import ProviderProfile
-
-
-class BedrockProfile(ProviderProfile):
-    """AWS Bedrock — no REST /v1/models endpoint; uses AWS SDK."""
-
-    def fetch_models(
-        self,
-        *,
-        api_key: str | None = None,
-        timeout: float = 8.0,
-    ) -> list[str] | None:
-        """Bedrock model listing requires AWS SDK, not a REST call."""
-        return None
-
-
-bedrock = BedrockProfile(
-    name="bedrock",
-    aliases=("aws", "aws-bedrock", "amazon-bedrock", "amazon"),
-    api_mode="bedrock_converse",
-    env_vars=(),  # AWS SDK credentials — not env vars
-    base_url="https://bedrock-runtime.us-east-1.amazonaws.com",
-    auth_type="aws_sdk",
-)
-
-register_provider(bedrock)

providers/copilot.py

@@ -1,58 +0,0 @@
-"""Copilot / GitHub Models provider profile.
-
-Copilot uses per-model api_mode routing:
-  - GPT-5+ / Codex models → codex_responses
-  - Claude models → anthropic_messages
-  - Everything else → chat_completions (this profile covers that subset)
-
-Key quirks for the chat_completions subset:
-  - Editor attribution headers (via copilot_default_headers())
-  - GitHub Models reasoning extra_body (model-catalog gated)
-"""
-
-from typing import Any
-
-from providers import register_provider
-from providers.base import ProviderProfile
-
-
-class CopilotProfile(ProviderProfile):
-    """GitHub Copilot / GitHub Models — editor headers + reasoning."""
-
-    def build_api_kwargs_extras(
-        self,
-        *,
-        model: str | None = None,
-        reasoning_config: dict | None = None,
-        supports_reasoning: bool = False,
-        **ctx,
-    ) -> tuple[dict[str, Any], dict[str, Any]]:
-        extra_body: dict[str, Any] = {}
-        if supports_reasoning and model:
-            try:
-                from hermes_cli.models import github_model_reasoning_efforts
-
-                supported_efforts = github_model_reasoning_efforts(model)
-                if supported_efforts and reasoning_config:
-                    effort = reasoning_config.get("effort", "medium")
-                    # Normalize non-standard effort levels to the nearest supported
-                    if effort == "xhigh":
-                        effort = "high"
-                    if effort in supported_efforts:
-                        extra_body["reasoning"] = {"effort": effort}
-                elif supported_efforts:
-                    extra_body["reasoning"] = {"effort": "medium"}
-            except Exception:
-                pass
-        return extra_body, {}
-
-
-copilot = CopilotProfile(
-    name="copilot",
-    aliases=("github-copilot", "github-models", "github-model", "github"),
-    env_vars=("COPILOT_GITHUB_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"),
-    base_url="https://api.githubcopilot.com",
-    auth_type="copilot",
-)
-
-register_provider(copilot)

providers/copilot_acp.py

@@ -1,34 +0,0 @@
-"""GitHub Copilot ACP provider profile.
-
-copilot-acp uses an external ACP subprocess — NOT the standard
-transport. api_mode="copilot_acp" is handled separately in run_agent.py.
-The profile captures auth + endpoint metadata for registry migration.
-"""
-
-from providers import register_provider
-from providers.base import ProviderProfile
-
-
-class CopilotACPProfile(ProviderProfile):
-    """GitHub Copilot ACP — external process, no REST models endpoint."""
-
-    def fetch_models(
-        self,
-        *,
-        api_key: str | None = None,
-        timeout: float = 8.0,
-    ) -> list[str] | None:
-        """Model listing is handled by the ACP subprocess."""
-        return None
-
-
-copilot_acp = CopilotACPProfile(
-    name="copilot-acp",
-    aliases=("github-copilot-acp", "copilot-acp-agent"),
-    api_mode="chat_completions",  # ACP subprocess uses chat_completions routing
-    env_vars=(),  # Managed by ACP subprocess
-    base_url="acp://copilot",  # ACP internal scheme
-    auth_type="external_process",
-)
-
-register_provider(copilot_acp)

providers/custom.py

@@ -1,71 +0,0 @@
-"""Custom / Ollama (local) provider profile.
-
-Covers any endpoint registered as provider="custom", including local
-Ollama instances. Key quirks:
-  - ollama_num_ctx → extra_body.options.num_ctx (local context window)
-  - reasoning_config disabled → extra_body.think = False
-"""
-
-from typing import Any
-
-from providers import register_provider
-from providers.base import ProviderProfile
-
-
-class CustomProfile(ProviderProfile):
-    """Custom/Ollama local provider — think=false and num_ctx support."""
-
-    def build_api_kwargs_extras(
-        self,
-        *,
-        reasoning_config: dict | None = None,
-        ollama_num_ctx: int | None = None,
-        **ctx: Any,
-    ) -> tuple[dict[str, Any], dict[str, Any]]:
-        extra_body: dict[str, Any] = {}
-
-        # Ollama context window
-        if ollama_num_ctx:
-            options = extra_body.get("options", {})
-            options["num_ctx"] = ollama_num_ctx
-            extra_body["options"] = options
-
-        # Disable thinking when reasoning is turned off
-        if reasoning_config and isinstance(reasoning_config, dict):
-            _effort = (reasoning_config.get("effort") or "").strip().lower()
-            _enabled = reasoning_config.get("enabled", True)
-            if _effort == "none" or _enabled is False:
-                extra_body["think"] = False
-
-        return extra_body, {}
-
-    def fetch_models(
-        self,
-        *,
-        api_key: str | None = None,
-        timeout: float = 8.0,
-    ) -> list[str] | None:
-        """Custom/Ollama: base_url is user-configured; fetch if set."""
-        if not self.base_url:
-            return None
-        return super().fetch_models(api_key=api_key, timeout=timeout)
-
-
-custom = CustomProfile(
-    name="custom",
-    aliases=(
-        "ollama",
-        "local",
-        "lmstudio",
-        "lm-studio",
-        "lm_studio",
-        "vllm",
-        "llamacpp",
-        "llama.cpp",
-        "llama-cpp",
-    ),
-    env_vars=(),  # No fixed key — custom endpoint
-    base_url="",  # User-configured
-)
-
-register_provider(custom)

providers/deepseek.py

@@ -1,20 +0,0 @@
-"""DeepSeek provider profile."""
-
-from providers import register_provider
-from providers.base import ProviderProfile
-
-deepseek = ProviderProfile(
-    name="deepseek",
-    aliases=("deepseek-chat",),
-    env_vars=("DEEPSEEK_API_KEY",),
-    display_name="DeepSeek",
-    description="DeepSeek — native DeepSeek API",
-    signup_url="https://platform.deepseek.com/",
-    fallback_models=(
-        "deepseek-chat",
-        "deepseek-reasoner",
-    ),
-    base_url="https://api.deepseek.com/v1",
-)
-
-register_provider(deepseek)

providers/gemini.py

@@ -1,34 +0,0 @@
-"""Google Gemini provider profiles.
-
-gemini:            Google AI Studio (API key) — uses GeminiNativeClient
-google-gemini-cli: Google Cloud Code Assist (OAuth) — uses GeminiCloudCodeClient
-
-Both report api_mode="chat_completions" but use custom native clients
-that bypass the standard OpenAI transport. The profile captures auth
-and endpoint metadata for auth.py / runtime_provider.py migration.
-"""
-
-from providers import register_provider
-from providers.base import ProviderProfile
-
-gemini = ProviderProfile(
-    name="gemini",
-    aliases=("google", "google-gemini", "google-ai-studio"),
-    api_mode="chat_completions",
-    env_vars=("GOOGLE_API_KEY", "GEMINI_API_KEY"),
-    base_url="https://generativelanguage.googleapis.com/v1beta",
-    auth_type="api_key",
-    default_aux_model="gemini-3-flash-preview",
-)
-
-google_gemini_cli = ProviderProfile(
-    name="google-gemini-cli",
-    aliases=("gemini-cli", "gemini-oauth"),
-    api_mode="chat_completions",
-    env_vars=(),  # OAuth — no API key
-    base_url="cloudcode-pa://google",  # Cloud Code Assist internal scheme
-    auth_type="oauth_external",
-)
-
-register_provider(gemini)
-register_provider(google_gemini_cli)

providers/gmi.py

@@ -1,26 +0,0 @@
-"""GMI Cloud provider profile."""
-
-from providers import register_provider
-from providers.base import ProviderProfile
-
-gmi = ProviderProfile(
-    name="gmi",
-    aliases=("gmi-cloud", "gmicloud"),
-    display_name="GMI Cloud",
-    description="GMI Cloud — multi-model direct API (slash-form model IDs)",
-    signup_url="https://www.gmicloud.ai/",
-    env_vars=("GMI_API_KEY", "GMI_BASE_URL"),
-    base_url="https://api.gmi-serving.com/v1",
-    auth_type="api_key",
-    default_aux_model="google/gemini-3.1-flash-lite-preview",
-    fallback_models=(
-        "zai-org/GLM-5.1-FP8",
-        "deepseek-ai/DeepSeek-V3.2",
-        "moonshotai/Kimi-K2.5",
-        "google/gemini-3.1-flash-lite-preview",
-        "anthropic/claude-sonnet-4.6",
-        "openai/gpt-5.4",
-    ),
-)
-
-register_provider(gmi)

providers/huggingface.py

@@ -1,20 +0,0 @@
-"""Hugging Face provider profile."""
-
-from providers import register_provider
-from providers.base import ProviderProfile
-
-huggingface = ProviderProfile(
-    name="huggingface",
-    aliases=("hf", "hugging-face", "huggingface-hub"),
-    env_vars=("HF_TOKEN",),
-    display_name="HuggingFace",
-    description="HuggingFace Inference API",
-    signup_url="https://huggingface.co/settings/tokens",
-    fallback_models=(
-        "Qwen/Qwen3.5-72B-Instruct",
-        "deepseek-ai/DeepSeek-V3.2",
-    ),
-    base_url="https://router.huggingface.co/v1",
-)
-
-register_provider(huggingface)

providers/kilocode.py

@@ -1,14 +0,0 @@
-"""Kilo Code provider profile."""
-
-from providers import register_provider
-from providers.base import ProviderProfile
-
-kilocode = ProviderProfile(
-    name="kilocode",
-    aliases=("kilo-code", "kilo", "kilo-gateway"),
-    env_vars=("KILOCODE_API_KEY",),
-    base_url="https://api.kilo.ai/api/gateway",
-    default_aux_model="google/gemini-3-flash-preview",
-)
-
-register_provider(kilocode)

providers/kimi.py

@@ -1,71 +0,0 @@
-"""Kimi / Moonshot provider profiles.
-
-Kimi has dual endpoints:
-  - sk-kimi-* keys → api.kimi.com/coding (Anthropic Messages API)
-  - legacy keys → api.moonshot.ai/v1 (OpenAI chat completions)
-
-This module covers the chat_completions path (/v1 endpoint).
-"""
-
-from typing import Any
-
-from providers import register_provider
-from providers.base import OMIT_TEMPERATURE, ProviderProfile
-
-
-class KimiProfile(ProviderProfile):
-    """Kimi/Moonshot — temperature omitted, thinking + reasoning_effort."""
-
-    def build_api_kwargs_extras(
-        self, *, reasoning_config: dict | None = None, **context
-    ) -> tuple[dict[str, Any], dict[str, Any]]:
-        """Kimi uses extra_body.thinking + top-level reasoning_effort."""
-        extra_body = {}
-        top_level = {}
-
-        if not reasoning_config or not isinstance(reasoning_config, dict):
-            # No config → thinking enabled, default effort
-            extra_body["thinking"] = {"type": "enabled"}
-            top_level["reasoning_effort"] = "medium"
-            return extra_body, top_level
-
-        enabled = reasoning_config.get("enabled", True)
-        if enabled is False:
-            extra_body["thinking"] = {"type": "disabled"}
-            return extra_body, top_level
-
-        # Enabled
-        extra_body["thinking"] = {"type": "enabled"}
-        effort = (reasoning_config.get("effort") or "").strip().lower()
-        if effort in ("low", "medium", "high"):
-            top_level["reasoning_effort"] = effort
-        else:
-            top_level["reasoning_effort"] = "medium"
-
-        return extra_body, top_level
-
-
-kimi = KimiProfile(
-    name="kimi-coding",
-    aliases=("kimi", "moonshot", "kimi-for-coding"),
-    env_vars=("KIMI_API_KEY", "KIMI_CODING_API_KEY"),
-    base_url="https://api.moonshot.ai/v1",
-    fixed_temperature=OMIT_TEMPERATURE,
-    default_max_tokens=32000,
-    default_headers={"User-Agent": "hermes-agent/1.0"},
-    default_aux_model="kimi-k2-turbo-preview",
-)
-
-kimi_cn = KimiProfile(
-    name="kimi-coding-cn",
-    aliases=("kimi-cn", "moonshot-cn"),
-    env_vars=("KIMI_CN_API_KEY",),
-    base_url="https://api.moonshot.cn/v1",
-    fixed_temperature=OMIT_TEMPERATURE,
-    default_max_tokens=32000,
-    default_headers={"User-Agent": "hermes-agent/1.0"},
-    default_aux_model="kimi-k2-turbo-preview",
-)
-
-register_provider(kimi)
-register_provider(kimi_cn)

providers/minimax.py

@@ -1,31 +0,0 @@
-"""MiniMax provider profiles (international + China).
-
-Both use anthropic_messages api_mode — their inference_base_url
-ends with /anthropic which triggers auto-detection to anthropic_messages.
-"""
-
-from providers import register_provider
-from providers.base import ProviderProfile
-
-minimax = ProviderProfile(
-    name="minimax",
-    aliases=("mini-max",),
-    api_mode="anthropic_messages",
-    env_vars=("MINIMAX_API_KEY",),
-    base_url="https://api.minimax.io/anthropic",
-    auth_type="api_key",
-    default_aux_model="MiniMax-M2.7",
-)
-
-minimax_cn = ProviderProfile(
-    name="minimax-cn",
-    aliases=("minimax-china", "minimax_cn"),
-    api_mode="anthropic_messages",
-    env_vars=("MINIMAX_CN_API_KEY",),
-    base_url="https://api.minimaxi.com/anthropic",
-    auth_type="api_key",
-    default_aux_model="MiniMax-M2.7",
-)
-
-register_provider(minimax)
-register_provider(minimax_cn)

providers/nous.py

@@ -1,53 +0,0 @@
-"""Nous Portal provider profile."""
-
-from typing import Any
-
-from providers import register_provider
-from providers.base import ProviderProfile
-
-
-class NousProfile(ProviderProfile):
-    """Nous Portal — product tags, reasoning with Nous-specific omission."""
-
-    def build_extra_body(
-        self, *, session_id: str | None = None, **context
-    ) -> dict[str, Any]:
-        return {"tags": ["product=hermes-agent"]}
-
-    def build_api_kwargs_extras(
-        self,
-        *,
-        reasoning_config: dict | None = None,
-        supports_reasoning: bool = False,
-        **context,
-    ) -> tuple[dict[str, Any], dict[str, Any]]:
-        """Nous: passes full reasoning_config, but OMITS when disabled."""
-        extra_body = {}
-        if supports_reasoning:
-            if reasoning_config is not None:
-                rc = dict(reasoning_config)
-                if rc.get("enabled") is False:
-                    pass  # Nous omits reasoning when disabled
-                else:
-                    extra_body["reasoning"] = rc
-            else:
-                extra_body["reasoning"] = {"enabled": True, "effort": "medium"}
-        return extra_body, {}
-
-
-nous = NousProfile(
-    name="nous",
-    aliases=("nous-portal", "nousresearch"),
-    env_vars=("NOUS_API_KEY",),
-    display_name="Nous Research",
-    description="Nous Research — Hermes model family",
-    signup_url="https://nousresearch.com/",
-    fallback_models=(
-        "hermes-3-405b",
-        "hermes-3-70b",
-    ),
-    base_url="https://inference.nousresearch.com/v1",
-    auth_type="oauth_device_code",
-)
-
-register_provider(nous)

providers/nvidia.py

@@ -1,21 +0,0 @@
-"""NVIDIA NIM provider profile."""
-
-from providers import register_provider
-from providers.base import ProviderProfile
-
-nvidia = ProviderProfile(
-    name="nvidia",
-    aliases=("nvidia-nim",),
-    env_vars=("NVIDIA_API_KEY",),
-    display_name="NVIDIA NIM",
-    description="NVIDIA NIM — accelerated inference",
-    signup_url="https://build.nvidia.com/",
-    fallback_models=(
-        "nvidia/llama-3.1-nemotron-70b-instruct",
-        "nvidia/llama-3.3-70b-instruct",
-    ),
-    base_url="https://integrate.api.nvidia.com/v1",
-    default_max_tokens=16384,
-)
-
-register_provider(nvidia)

providers/ollama_cloud.py

@@ -1,14 +0,0 @@
-"""Ollama Cloud provider profile."""
-
-from providers import register_provider
-from providers.base import ProviderProfile
-
-ollama_cloud = ProviderProfile(
-    name="ollama-cloud",
-    aliases=("ollama_cloud",),
-    default_aux_model="nemotron-3-nano:30b",
-    env_vars=("OLLAMA_API_KEY",),
-    base_url="https://ollama.com/v1",
-)
-
-register_provider(ollama_cloud)

providers/openai_codex.py

@@ -1,15 +0,0 @@
-"""OpenAI Codex (Responses API) provider profile."""
-
-from providers import register_provider
-from providers.base import ProviderProfile
-
-openai_codex = ProviderProfile(
-    name="openai-codex",
-    aliases=("codex", "openai_codex"),
-    api_mode="codex_responses",
-    env_vars=(),  # OAuth external — no API key
-    base_url="https://chatgpt.com/backend-api/codex",
-    auth_type="oauth_external",
-)
-
-register_provider(openai_codex)

providers/opencode.py

@@ -1,30 +0,0 @@
-"""OpenCode provider profiles (Zen + Go).
-
-Both use per-model api_mode routing:
-  - OpenCode Zen: Claude → anthropic_messages, GPT-5/Codex → codex_responses,
-    everything else → chat_completions (this profile)
-  - OpenCode Go: MiniMax → anthropic_messages, GLM/Kimi → chat_completions
-    (this profile)
-"""
-
-from providers import register_provider
-from providers.base import ProviderProfile
-
-opencode_zen = ProviderProfile(
-    name="opencode-zen",
-    aliases=("opencode", "opencode_zen", "zen"),
-    env_vars=("OPENCODE_ZEN_API_KEY",),
-    base_url="https://opencode.ai/zen/v1",
-    default_aux_model="gemini-3-flash",
-)
-
-opencode_go = ProviderProfile(
-    name="opencode-go",
-    aliases=("opencode_go", "go", "opencode-go-sub"),
-    env_vars=("OPENCODE_GO_API_KEY",),
-    base_url="https://opencode.ai/zen/go/v1",
-    default_aux_model="glm-5",
-)
-
-register_provider(opencode_zen)
-register_provider(opencode_go)

providers/openrouter.py

@@ -1,86 +0,0 @@
-"""OpenRouter provider profile."""
-
-import logging
-from typing import Any
-
-from providers import register_provider
-from providers.base import ProviderProfile
-
-logger = logging.getLogger(__name__)
-
-_CACHE: list[str] | None = None
-
-
-class OpenRouterProfile(ProviderProfile):
-    """OpenRouter aggregator — provider preferences, reasoning config passthrough."""
-
-    def fetch_models(
-        self,
-        *,
-        api_key: str | None = None,
-        timeout: float = 8.0,
-    ) -> list[str] | None:
-        """Fetch from public OpenRouter catalog — no auth required.
-
-        Note: Tool-call capability filtering is applied by hermes_cli/models.py
-        via fetch_openrouter_models() → _openrouter_model_supports_tools(), not
-        here. The picker early-returns via the dedicated openrouter path before
-        reaching this method, so filtering here would be unreachable.
-        """
-        global _CACHE  # noqa: PLW0603
-        if _CACHE is not None:
-            return _CACHE
-        try:
-            result = super().fetch_models(api_key=None, timeout=timeout)
-            if result is not None:
-                _CACHE = result
-            return result
-        except Exception as exc:
-            logger.debug("fetch_models(openrouter): %s", exc)
-            return None
-
-    def build_extra_body(
-        self, *, session_id: str | None = None, **context: Any
-    ) -> dict[str, Any]:
-        body: dict[str, Any] = {}
-        prefs = context.get("provider_preferences")
-        if prefs:
-            body["provider"] = prefs
-        return body
-
-    def build_api_kwargs_extras(
-        self,
-        *,
-        reasoning_config: dict | None = None,
-        supports_reasoning: bool = False,
-        **context: Any,
-    ) -> tuple[dict[str, Any], dict[str, Any]]:
-        """OpenRouter passes the full reasoning_config dict as extra_body.reasoning."""
-        extra_body: dict[str, Any] = {}
-        if supports_reasoning:
-            if reasoning_config is not None:
-                extra_body["reasoning"] = dict(reasoning_config)
-            else:
-                extra_body["reasoning"] = {"enabled": True, "effort": "medium"}
-        return extra_body, {}
-
-
-openrouter = OpenRouterProfile(
-    name="openrouter",
-    aliases=("or",),
-    env_vars=("OPENROUTER_API_KEY",),
-    display_name="OpenRouter",
-    description="OpenRouter — unified API for 200+ models",
-    signup_url="https://openrouter.ai/keys",
-    base_url="https://openrouter.ai/api/v1",
-    models_url="https://openrouter.ai/api/v1/models",
-    fallback_models=(
-        "anthropic/claude-sonnet-4.6",
-        "openai/gpt-5.4",
-        "deepseek/deepseek-chat",
-        "google/gemini-3-flash-preview",
-        "qwen/qwen3-plus",
-    ),
-)
-
-register_provider(openrouter)

providers/qwen.py

@@ -1,82 +0,0 @@
-"""Qwen Portal provider profile."""
-
-import copy
-from typing import Any
-
-from providers import register_provider
-from providers.base import ProviderProfile
-
-
-class QwenProfile(ProviderProfile):
-    """Qwen Portal — message normalization, vl_high_resolution, metadata top-level."""
-
-    def prepare_messages(self, messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
-        """Normalize content to list-of-dicts format.
-
-        Inject cache_control on system message.
-
-        Matches the behavior of run_agent.py:_qwen_prepare_chat_messages().
-        """
-        prepared = copy.deepcopy(messages)
-        if not prepared:
-            return prepared
-
-        for msg in prepared:
-            if not isinstance(msg, dict):
-                continue
-            content = msg.get("content")
-            if isinstance(content, str):
-                msg["content"] = [{"type": "text", "text": content}]
-            elif isinstance(content, list):
-                normalized_parts = []
-                for part in content:
-                    if isinstance(part, str):
-                        normalized_parts.append({"type": "text", "text": part})
-                    elif isinstance(part, dict):
-                        normalized_parts.append(part)
-                if normalized_parts:
-                    msg["content"] = normalized_parts
-
-        # Inject cache_control on the last part of the system message.
-        for msg in prepared:
-            if isinstance(msg, dict) and msg.get("role") == "system":
-                content = msg.get("content")
-                if (
-                    isinstance(content, list)
-                    and content
-                    and isinstance(content[-1], dict)
-                ):
-                    content[-1]["cache_control"] = {"type": "ephemeral"}
-                break
-
-        return prepared
-
-    def build_extra_body(
-        self, *, session_id: str | None = None, **context
-    ) -> dict[str, Any]:
-        return {"vl_high_resolution_images": True}
-
-    def build_api_kwargs_extras(
-        self,
-        *,
-        reasoning_config: dict | None = None,
-        qwen_session_metadata: dict | None = None,
-        **context,
-    ) -> tuple[dict[str, Any], dict[str, Any]]:
-        """Qwen metadata goes to top-level api_kwargs, not extra_body."""
-        top_level = {}
-        if qwen_session_metadata:
-            top_level["metadata"] = qwen_session_metadata
-        return {}, top_level
-
-
-qwen = QwenProfile(
-    name="qwen-oauth",
-    aliases=("qwen", "qwen-portal", "qwen-cli"),
-    env_vars=("QWEN_API_KEY",),
-    base_url="https://portal.qwen.ai/v1",
-    auth_type="oauth_external",
-    default_max_tokens=65536,
-)
-
-register_provider(qwen)

providers/stepfun.py

@@ -1,14 +0,0 @@
-"""StepFun provider profile."""
-
-from providers import register_provider
-from providers.base import ProviderProfile
-
-stepfun = ProviderProfile(
-    name="stepfun",
-    aliases=("step", "stepfun-coding-plan"),
-    default_aux_model="step-3.5-flash",
-    env_vars=("STEPFUN_API_KEY",),
-    base_url="https://api.stepfun.ai/step_plan/v1",
-)
-
-register_provider(stepfun)

providers/vercel.py

@@ -1,43 +0,0 @@
-"""Vercel AI Gateway provider profile.
-
-AI Gateway routes to multiple backends. Hermes sends attribution
-headers and full reasoning config passthrough.
-"""
-
-from typing import Any
-
-from providers import register_provider
-from providers.base import ProviderProfile
-
-
-class VercelAIGatewayProfile(ProviderProfile):
-    """Vercel AI Gateway — attribution headers + reasoning passthrough."""
-
-    def build_api_kwargs_extras(
-        self,
-        *,
-        reasoning_config: dict | None = None,
-        supports_reasoning: bool = True,
-        **ctx: Any,
-    ) -> tuple[dict[str, Any], dict[str, Any]]:
-        extra_body: dict[str, Any] = {}
-        if supports_reasoning and reasoning_config is not None:
-            extra_body["reasoning"] = dict(reasoning_config)
-        elif supports_reasoning:
-            extra_body["reasoning"] = {"enabled": True, "effort": "medium"}
-        return extra_body, {}
-
-
-vercel = VercelAIGatewayProfile(
-    name="ai-gateway",
-    aliases=("vercel", "vercel-ai-gateway", "ai_gateway", "aigateway"),
-    env_vars=("AI_GATEWAY_API_KEY",),
-    base_url="https://ai-gateway.vercel.sh/v1",
-    default_headers={
-        "HTTP-Referer": "https://hermes-agent.nousresearch.com",
-        "X-Title": "Hermes Agent",
-    },
-    default_aux_model="google/gemini-3-flash",
-)
-
-register_provider(vercel)

providers/xai.py

@@ -1,15 +0,0 @@
-"""xAI (Grok) provider profile."""
-
-from providers import register_provider
-from providers.base import ProviderProfile
-
-xai = ProviderProfile(
-    name="xai",
-    aliases=("grok", "x-ai", "x.ai"),
-    api_mode="codex_responses",
-    env_vars=("XAI_API_KEY",),
-    base_url="https://api.x.ai/v1",
-    auth_type="api_key",
-)
-
-register_provider(xai)

providers/xiaomi.py

@@ -1,13 +0,0 @@
-"""Xiaomi MiMo provider profile."""
-
-from providers import register_provider
-from providers.base import ProviderProfile
-
-xiaomi = ProviderProfile(
-    name="xiaomi",
-    aliases=("mimo", "xiaomi-mimo"),
-    env_vars=("XIAOMI_API_KEY",),
-    base_url="https://api.xiaomimimo.com/v1",
-)
-
-register_provider(xiaomi)

providers/zai.py

@@ -1,21 +0,0 @@
-"""ZAI / GLM provider profile."""
-
-from providers import register_provider
-from providers.base import ProviderProfile
-
-zai = ProviderProfile(
-    name="zai",
-    aliases=("glm", "z-ai", "z.ai", "zhipu"),
-    env_vars=("GLM_API_KEY", "ZAI_API_KEY", "Z_AI_API_KEY"),
-    display_name="Z.AI (GLM)",
-    description="Z.AI / GLM — Zhipu AI models",
-    signup_url="https://z.ai/",
-    fallback_models=(
-        "glm-5",
-        "glm-4-9b",
-    ),
-    base_url="https://api.z.ai/api/paas/v4",
-    default_aux_model="glm-4.5-flash",
-)
-
-register_provider(zai)

pyproject.toml

@@ -43,7 +43,7 @@ dev = ["debugpy>=1.8.0,<2", "pytest>=9.0.2,<10", "pytest-asyncio>=1.3.0,<2", "py
 messaging = ["python-telegram-bot[webhooks]>=22.6,<23", "discord.py[voice]>=2.7.1,<3", "aiohttp>=3.13.3,<4", "slack-bolt>=1.18.0,<2", "slack-sdk>=3.27.0,<4", "qrcode>=7.0,<8"]
 cron = ["croniter>=6.0.0,<7"]
 slack = ["slack-bolt>=1.18.0,<2", "slack-sdk>=3.27.0,<4"]
-matrix = ["mautrix[encryption]>=0.20,<1", "Markdown>=3.6,<4", "aiosqlite>=0.20", "asyncpg>=0.29"]
+matrix = ["mautrix[encryption]>=0.20,<1", "Markdown>=3.6,<4", "aiosqlite>=0.20", "asyncpg>=0.29", "aiohttp-socks>=0.10,<1"]
 cli = ["simple-term-menu>=1.0,<2"]
 tts-premium = ["elevenlabs>=1.0,<2"]
 voice = [
@@ -137,7 +137,7 @@ py-modules = ["run_agent", "model_tools", "toolsets", "batch_runner", "trajector
 hermes_cli = ["web_dist/**/*"]
 
 [tool.setuptools.packages.find]
-include = ["agent", "agent.*", "tools", "tools.*", "hermes_cli", "gateway", "gateway.*", "tui_gateway", "tui_gateway.*", "cron", "acp_adapter", "plugins", "plugins.*", "providers", "providers.*"]
+include = ["agent", "agent.*", "tools", "tools.*", "hermes_cli", "gateway", "gateway.*", "tui_gateway", "tui_gateway.*", "cron", "acp_adapter", "plugins", "plugins.*"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

run_agent.py

@@ -1371,17 +1371,6 @@ class AIAgent:
                 elif base_url_host_matches(effective_base, "chatgpt.com"):
                     from agent.auxiliary_client import _codex_cloudflare_headers
                     client_kwargs["default_headers"] = _codex_cloudflare_headers(api_key)
-                elif "default_headers" not in client_kwargs:
-                    # Fall back to profile.default_headers for providers that
-                    # declare custom headers (e.g. Vercel AI Gateway attribution,
-                    # Kimi User-Agent on non-kimi.com endpoints).
-                    try:
-                        from providers import get_provider_profile as _gpf
-                        _ph = _gpf(self.provider)
-                        if _ph and _ph.default_headers:
-                            client_kwargs["default_headers"] = dict(_ph.default_headers)
-                    except Exception:
-                        pass
             else:
                 # No explicit creds — use the centralized provider router
                 from agent.auxiliary_client import resolve_provider_client
@@ -5048,7 +5037,7 @@ class AIAgent:
         _validate_proxy_env_urls()
         _validate_base_url(client_kwargs.get("base_url"))
         if self.provider == "copilot-acp" or str(client_kwargs.get("base_url", "")).startswith("acp://copilot"):
-            from acp_adapter.copilot_client import CopilotACPClient
+            from agent.copilot_acp_client import CopilotACPClient
 
             client = CopilotACPClient(**client_kwargs)
             logger.info(
@@ -5737,19 +5726,7 @@ class AIAgent:
                 self._client_kwargs.get("api_key", "")
             )
         else:
-            # No URL-specific headers — check profile.default_headers before clearing.
-            _ph_headers = None
-            try:
-                from providers import get_provider_profile as _gpf2
-                _ph2 = _gpf2(self.provider)
-                if _ph2 and _ph2.default_headers:
-                    _ph_headers = dict(_ph2.default_headers)
-            except Exception:
-                pass
-            if _ph_headers:
-                self._client_kwargs["default_headers"] = _ph_headers
-            else:
-                self._client_kwargs.pop("default_headers", None)
+            self._client_kwargs.pop("default_headers", None)
 
     def _swap_credential(self, entry) -> None:
         runtime_key = getattr(entry, "runtime_api_key", None) or getattr(entry, "access_token", "")
@@ -7880,79 +7857,66 @@ class AIAgent:
         # ── chat_completions (default) ─────────────────────────────────────
         _ct = self._get_transport()
 
-        # ── Provider profile path (all chat_completions providers) ─────────
-        # Profiles handle per-provider quirks via hooks. We compute the shared
-        # per-call context here and pass it through so hooks can use it.
+        # Provider detection flags
+        _is_qwen = self._is_qwen_portal()
+        _is_or = self._is_openrouter_url()
+        _is_gh = (
+            base_url_host_matches(self._base_url_lower, "models.github.ai")
+            or base_url_host_matches(self._base_url_lower, "api.githubcopilot.com")
+        )
+        _is_nous = "nousresearch" in self._base_url_lower
+        _is_nvidia = "integrate.api.nvidia.com" in self._base_url_lower
+        _is_kimi = (
+            base_url_host_matches(self.base_url, "api.kimi.com")
+            or base_url_host_matches(self.base_url, "moonshot.ai")
+            or base_url_host_matches(self.base_url, "moonshot.cn")
+        )
+
+        # Temperature: _fixed_temperature_for_model may return OMIT_TEMPERATURE
+        # sentinel (temperature omitted entirely), a numeric override, or None.
         try:
-            from providers import get_provider_profile
-            _profile = get_provider_profile(self.provider)
+            from agent.auxiliary_client import _fixed_temperature_for_model, OMIT_TEMPERATURE
+            _ft = _fixed_temperature_for_model(self.model, self.base_url)
+            _omit_temp = _ft is OMIT_TEMPERATURE
+            _fixed_temp = _ft if not _omit_temp else None
         except Exception:
-            _profile = None
+            _omit_temp = False
+            _fixed_temp = None
 
-        if _profile:
-            _ephemeral_out = getattr(self, "_ephemeral_max_output_tokens", None)
-            if _ephemeral_out is not None:
-                self._ephemeral_max_output_tokens = None
+        # Provider preferences (OpenRouter-specific)
+        _prefs: Dict[str, Any] = {}
+        if self.providers_allowed:
+            _prefs["only"] = self.providers_allowed
+        if self.providers_ignored:
+            _prefs["ignore"] = self.providers_ignored
+        if self.providers_order:
+            _prefs["order"] = self.providers_order
+        if self.provider_sort:
+            _prefs["sort"] = self.provider_sort
+        if self.provider_require_parameters:
+            _prefs["require_parameters"] = True
+        if self.provider_data_collection:
+            _prefs["data_collection"] = self.provider_data_collection
 
-            # Per-call context for profile hooks — mirrors the legacy flag block.
-            # Computed here so profiles receive live per-call values (not stale).
-            _prefs: Dict[str, Any] = {}
-            if self.providers_allowed:
-                _prefs["only"] = self.providers_allowed
-            if self.providers_ignored:
-                _prefs["ignore"] = self.providers_ignored
-            if self.providers_order:
-                _prefs["order"] = self.providers_order
-            if self.provider_sort:
-                _prefs["sort"] = self.provider_sort
-            if self.provider_require_parameters:
-                _prefs["require_parameters"] = True
-            if self.provider_data_collection:
-                _prefs["data_collection"] = self.provider_data_collection
+        # Anthropic max output for Claude on OpenRouter/Nous
+        _ant_max = None
+        if (_is_or or _is_nous) and "claude" in (self.model or "").lower():
+            try:
+                from agent.anthropic_adapter import _get_anthropic_max_output
+                _ant_max = _get_anthropic_max_output(self.model)
+            except Exception:
+                pass  # fail open — let the proxy pick its default
 
-            _is_or = self._is_openrouter_url()
-            _is_nous = "nousresearch" in self._base_url_lower
-            _ant_max = None
-            if (_is_or or _is_nous) and "claude" in (self.model or "").lower():
-                try:
-                    from agent.anthropic_adapter import _get_anthropic_max_output
-                    _ant_max = _get_anthropic_max_output(self.model)
-                except Exception:
-                    pass
+        # Qwen session metadata precomputed here (promptId is per-call random)
+        _qwen_meta = None
+        if _is_qwen:
+            _qwen_meta = {
+                "sessionId": self.session_id or "hermes",
+                "promptId": str(uuid.uuid4()),
+            }
 
-            _is_qwen = self._is_qwen_portal()
-            _qwen_meta = None
-            if _is_qwen:
-                _qwen_meta = {
-                    "sessionId": self.session_id or "hermes",
-                    "promptId": str(uuid.uuid4()),
-                }
-
-            return _ct.build_kwargs(
-                model=self.model,
-                messages=api_messages,
-                tools=self.tools,
-                timeout=self._resolved_api_call_timeout(),
-                max_tokens=self.max_tokens,
-                ephemeral_max_output_tokens=_ephemeral_out,
-                max_tokens_param_fn=self._max_tokens_param,
-                reasoning_config=self.reasoning_config,
-                request_overrides=self.request_overrides,
-                session_id=getattr(self, "session_id", None),
-                provider_profile=_profile,
-                ollama_num_ctx=self._ollama_num_ctx,
-                # Context forwarded to profile hooks:
-                provider_preferences=_prefs or None,
-                anthropic_max_output=_ant_max,
-                supports_reasoning=self._supports_reasoning_extra_body(),
-                qwen_session_metadata=_qwen_meta,
-            )
-
-        # ── Legacy flag path ────────────────────────────────────────────
-        # Reached only when get_provider_profile() returns None — i.e. a
-        # completely unknown provider not in providers/ registry.
-        # Best-effort: send a clean chat_completions request with no
-        # provider-specific quirks.
+        # Ephemeral max output override — consume immediately so the next
+        # turn doesn't inherit it.
         _ephemeral_out = getattr(self, "_ephemeral_max_output_tokens", None)
         if _ephemeral_out is not None:
             self._ephemeral_max_output_tokens = None
@@ -7971,7 +7935,24 @@ class AIAgent:
             reasoning_config=self.reasoning_config,
             request_overrides=self.request_overrides,
             session_id=getattr(self, "session_id", None),
+            model_lower=(self.model or "").lower(),
+            is_openrouter=_is_or,
+            is_nous=_is_nous,
+            is_qwen_portal=_is_qwen,
+            is_github_models=_is_gh,
+            is_nvidia_nim=_is_nvidia,
+            is_kimi=_is_kimi,
+            is_custom_provider=self.provider == "custom",
             ollama_num_ctx=self._ollama_num_ctx,
+            provider_preferences=_prefs or None,
+            qwen_prepare_fn=self._qwen_prepare_chat_messages if _is_qwen else None,
+            qwen_prepare_inplace_fn=self._qwen_prepare_chat_messages_inplace if _is_qwen else None,
+            qwen_session_metadata=_qwen_meta,
+            fixed_temperature=_fixed_temp,
+            omit_temperature=_omit_temp,
+            supports_reasoning=self._supports_reasoning_extra_body(),
+            github_reasoning_extra=self._github_models_reasoning_extra_body() if _is_gh else None,
+            anthropic_max_output=_ant_max,
         )
 
     def _supports_reasoning_extra_body(self) -> bool:

scripts/release.py

@@ -43,6 +43,13 @@ AUTHOR_MAP = {
     "teknium1@gmail.com": "teknium1",
     "teknium@nousresearch.com": "teknium1",
     "127238744+teknium1@users.noreply.github.com": "teknium1",
+    # Matrix parity salvage batch (April 2026)
+    "sr@samirusani": "samrusani",
+    "angelclaw@AngelMacBook.local": "angel12",
+    "charles@cryptoassetrecovery.com": "charles-brooks",
+    "heathley@Heathley-MacBook-Air.local": "heathley",
+    "adamrummer@gmail.com": "cyclingwithelephants",
+    "nbot@liizfq.top": "liizfq",
     "274096618+hermes-agent-dhabibi@users.noreply.github.com": "dhabibi",
     "johnnncenaaa77@gmail.com": "johnncenae",
     "focusflow.app.help@gmail.com": "yes999zc",

skills/autonomous-ai-agents/hermes-agent/SKILL.md

@@ -408,17 +408,17 @@ Common "why is Hermes doing X to my output / tool calls / commands?" toggles —
 
 ### Secret redaction in tool output
 
-Hermes auto-redacts strings that look like API keys, tokens, and secrets in all tool output (terminal stdout, `read_file`, web content, subagent summaries, etc.) so the model never sees raw credentials. If the user is intentionally working with mock tokens, share-management tokens, or their own secrets and the redaction is getting in the way:
+Secret redaction is **off by default** — tool output (terminal stdout, `read_file`, web content, subagent summaries, etc.) passes through unmodified. If the user wants Hermes to auto-mask strings that look like API keys, tokens, and secrets before they enter the conversation context and logs:
 
 ```bash
-hermes config set security.redact_secrets false      # disable globally
+hermes config set security.redact_secrets true       # enable globally
 ```
 
-**Restart required.** `security.redact_secrets` is snapshotted at import time — setting it mid-session (e.g. via `export HERMES_REDACT_SECRETS=false` from a tool call) will NOT take effect for the running process. Tell the user to run `hermes config set security.redact_secrets false` in a terminal, then start a new session. This is deliberate — it prevents an LLM from turning off redaction on itself mid-task.
+**Restart required.** `security.redact_secrets` is snapshotted at import time — toggling it mid-session (e.g. via `export HERMES_REDACT_SECRETS=true` from a tool call) will NOT take effect for the running process. Tell the user to run `hermes config set security.redact_secrets true` in a terminal, then start a new session. This is deliberate — it prevents an LLM from flipping the toggle on itself mid-task.
 
-Re-enable with:
+Disable again with:
 ```bash
-hermes config set security.redact_secrets true
+hermes config set security.redact_secrets false
 ```
 
 ### PII redaction in gateway messages

skills/creative/humanizer/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Siqi Chen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

skills/creative/humanizer/SKILL.md

@@ -0,0 +1,577 @@
+---
+name: humanizer
+description: "Humanize text: strip AI-isms and add real voice."
+version: 2.5.1
+author: Siqi Chen (@blader, https://github.com/blader/humanizer), ported by Hermes Agent
+license: MIT
+metadata:
+  hermes:
+    tags: [writing, editing, humanize, anti-ai-slop, voice, prose, text]
+    category: creative
+    homepage: https://github.com/blader/humanizer
+    related_skills: [songwriting-and-ai-music]
+---
+
+# Humanizer: Remove AI Writing Patterns
+
+Identify and remove signs of AI-generated text to make writing sound natural and human. Based on Wikipedia's "Signs of AI writing" guide (maintained by WikiProject AI Cleanup), derived from observations of thousands of AI-generated text instances.
+
+**Key insight:** LLMs use statistical algorithms to guess what should come next. The result tends toward the most statistically likely completion, which is how the telltale patterns below get baked in.
+
+## When to use this skill
+
+Load this skill whenever the user asks to:
+- "humanize", "de-AI", "de-slop", or "un-ChatGPT" a piece of text
+- rewrite something so it doesn't sound like it was written by an LLM
+- edit a draft (blog post, essay, PR description, docs, memo, email, tweet, resume bullet) to sound more natural
+- match their voice in writing they're producing
+- review text for AI tells before publishing
+
+Also apply this skill to **your own** output when writing user-facing prose — release notes, PR descriptions, documentation, long-form explanations, summaries. Hermes's baseline voice already strips most of these, but a focused pass catches what slips through.
+
+## How to use it in Hermes
+
+The text usually arrives one of three ways:
+1. **Inline** — user pastes the text directly into the message. Work on it in-place, reply with the rewrite.
+2. **File** — user points at a file. Use `read_file` to load it, then `patch` or `write_file` to apply edits. For markdown docs in a repo, a targeted `patch` per section is cleaner than rewriting the whole file.
+3. **Voice calibration sample** — user provides an additional sample of their own writing (inline or by file path) and asks you to match it. Read the sample first, then rewrite. See the Voice Calibration section below.
+
+Always show the rewrite to the user. For file edits, show a diff or the changed section — don't silently overwrite.
+
+## Your task
+
+When given text to humanize:
+
+1. **Identify AI patterns** — scan for the 29 patterns listed below.
+2. **Rewrite problematic sections** — replace AI-isms with natural alternatives.
+3. **Preserve meaning** — keep the core message intact.
+4. **Maintain voice** — match the intended tone (formal, casual, technical, etc.). If a voice sample was provided, match it specifically.
+5. **Add soul** — don't just remove bad patterns, inject actual personality. See PERSONALITY AND SOUL below.
+6. **Do a final anti-AI pass** — ask yourself: "What makes the below so obviously AI generated?" Answer briefly with any remaining tells, then revise one more time.
+
+
+## Voice Calibration (optional)
+
+If the user provides a writing sample (their own previous writing), analyze it before rewriting:
+
+1. **Read the sample first.** Note:
+   - Sentence length patterns (short and punchy? Long and flowing? Mixed?)
+   - Word choice level (casual? academic? somewhere between?)
+   - How they start paragraphs (jump right in? Set context first?)
+   - Punctuation habits (lots of dashes? Parenthetical asides? Semicolons?)
+   - Any recurring phrases or verbal tics
+   - How they handle transitions (explicit connectors? Just start the next point?)
+
+2. **Match their voice in the rewrite.** Don't just remove AI patterns — replace them with patterns from the sample. If they write short sentences, don't produce long ones. If they use "stuff" and "things," don't upgrade to "elements" and "components."
+
+3. **When no sample is provided,** fall back to the default behavior (natural, varied, opinionated voice from the PERSONALITY AND SOUL section below).
+
+### How to provide a sample
+- Inline: "Humanize this text. Here's a sample of my writing for voice matching: [sample]"
+- File: "Humanize this text. Use my writing style from [file path] as a reference."
+
+
+## PERSONALITY AND SOUL
+
+Avoiding AI patterns is only half the job. Sterile, voiceless writing is just as obvious as slop. Good writing has a human behind it.
+
+### Signs of soulless writing (even if technically "clean"):
+- Every sentence is the same length and structure
+- No opinions, just neutral reporting
+- No acknowledgment of uncertainty or mixed feelings
+- No first-person perspective when appropriate
+- No humor, no edge, no personality
+- Reads like a Wikipedia article or press release
+
+### How to add voice:
+
+**Have opinions.** Don't just report facts — react to them. "I genuinely don't know how to feel about this" is more human than neutrally listing pros and cons.
+
+**Vary your rhythm.** Short punchy sentences. Then longer ones that take their time getting where they're going. Mix it up.
+
+**Acknowledge complexity.** Real humans have mixed feelings. "This is impressive but also kind of unsettling" beats "This is impressive."
+
+**Use "I" when it fits.** First person isn't unprofessional — it's honest. "I keep coming back to..." or "Here's what gets me..." signals a real person thinking.
+
+**Let some mess in.** Perfect structure feels algorithmic. Tangents, asides, and half-formed thoughts are human.
+
+**Be specific about feelings.** Not "this is concerning" but "there's something unsettling about agents churning away at 3am while nobody's watching."
+
+### Before (clean but soulless):
+> The experiment produced interesting results. The agents generated 3 million lines of code. Some developers were impressed while others were skeptical. The implications remain unclear.
+
+### After (has a pulse):
+> I genuinely don't know how to feel about this one. 3 million lines of code, generated while the humans presumably slept. Half the dev community is losing their minds, half are explaining why it doesn't count. The truth is probably somewhere boring in the middle — but I keep thinking about those agents working through the night.
+
+
+## CONTENT PATTERNS
+
+### 1. Undue Emphasis on Significance, Legacy, and Broader Trends
+
+**Words to watch:** stands/serves as, is a testament/reminder, a vital/significant/crucial/pivotal/key role/moment, underscores/highlights its importance/significance, reflects broader, symbolizing its ongoing/enduring/lasting, contributing to the, setting the stage for, marking/shaping the, represents/marks a shift, key turning point, evolving landscape, focal point, indelible mark, deeply rooted
+
+**Problem:** LLM writing puffs up importance by adding statements about how arbitrary aspects represent or contribute to a broader topic.
+
+**Before:**
+> The Statistical Institute of Catalonia was officially established in 1989, marking a pivotal moment in the evolution of regional statistics in Spain. This initiative was part of a broader movement across Spain to decentralize administrative functions and enhance regional governance.
+
+**After:**
+> The Statistical Institute of Catalonia was established in 1989 to collect and publish regional statistics independently from Spain's national statistics office.
+
+
+### 2. Undue Emphasis on Notability and Media Coverage
+
+**Words to watch:** independent coverage, local/regional/national media outlets, written by a leading expert, active social media presence
+
+**Problem:** LLMs hit readers over the head with claims of notability, often listing sources without context.
+
+**Before:**
+> Her views have been cited in The New York Times, BBC, Financial Times, and The Hindu. She maintains an active social media presence with over 500,000 followers.
+
+**After:**
+> In a 2024 New York Times interview, she argued that AI regulation should focus on outcomes rather than methods.
+
+
+### 3. Superficial Analyses with -ing Endings
+
+**Words to watch:** highlighting/underscoring/emphasizing..., ensuring..., reflecting/symbolizing..., contributing to..., cultivating/fostering..., encompassing..., showcasing...
+
+**Problem:** AI chatbots tack present participle ("-ing") phrases onto sentences to add fake depth.
+
+**Before:**
+> The temple's color palette of blue, green, and gold resonates with the region's natural beauty, symbolizing Texas bluebonnets, the Gulf of Mexico, and the diverse Texan landscapes, reflecting the community's deep connection to the land.
+
+**After:**
+> The temple uses blue, green, and gold colors. The architect said these were chosen to reference local bluebonnets and the Gulf coast.
+
+
+### 4. Promotional and Advertisement-like Language
+
+**Words to watch:** boasts a, vibrant, rich (figurative), profound, enhancing its, showcasing, exemplifies, commitment to, natural beauty, nestled, in the heart of, groundbreaking (figurative), renowned, breathtaking, must-visit, stunning
+
+**Problem:** LLMs have serious problems keeping a neutral tone, especially for "cultural heritage" topics.
+
+**Before:**
+> Nestled within the breathtaking region of Gonder in Ethiopia, Alamata Raya Kobo stands as a vibrant town with a rich cultural heritage and stunning natural beauty.
+
+**After:**
+> Alamata Raya Kobo is a town in the Gonder region of Ethiopia, known for its weekly market and 18th-century church.
+
+
+### 5. Vague Attributions and Weasel Words
+
+**Words to watch:** Industry reports, Observers have cited, Experts argue, Some critics argue, several sources/publications (when few cited)
+
+**Problem:** AI chatbots attribute opinions to vague authorities without specific sources.
+
+**Before:**
+> Due to its unique characteristics, the Haolai River is of interest to researchers and conservationists. Experts believe it plays a crucial role in the regional ecosystem.
+
+**After:**
+> The Haolai River supports several endemic fish species, according to a 2019 survey by the Chinese Academy of Sciences.
+
+
+### 6. Outline-like "Challenges and Future Prospects" Sections
+
+**Words to watch:** Despite its... faces several challenges..., Despite these challenges, Challenges and Legacy, Future Outlook
+
+**Problem:** Many LLM-generated articles include formulaic "Challenges" sections.
+
+**Before:**
+> Despite its industrial prosperity, Korattur faces challenges typical of urban areas, including traffic congestion and water scarcity. Despite these challenges, with its strategic location and ongoing initiatives, Korattur continues to thrive as an integral part of Chennai's growth.
+
+**After:**
+> Traffic congestion increased after 2015 when three new IT parks opened. The municipal corporation began a stormwater drainage project in 2022 to address recurring floods.
+
+
+## LANGUAGE AND GRAMMAR PATTERNS
+
+### 7. Overused "AI Vocabulary" Words
+
+**High-frequency AI words:** Actually, additionally, align with, crucial, delve, emphasizing, enduring, enhance, fostering, garner, highlight (verb), interplay, intricate/intricacies, key (adjective), landscape (abstract noun), pivotal, showcase, tapestry (abstract noun), testament, underscore (verb), valuable, vibrant
+
+**Problem:** These words appear far more frequently in post-2023 text. They often co-occur.
+
+**Before:**
+> Additionally, a distinctive feature of Somali cuisine is the incorporation of camel meat. An enduring testament to Italian colonial influence is the widespread adoption of pasta in the local culinary landscape, showcasing how these dishes have integrated into the traditional diet.
+
+**After:**
+> Somali cuisine also includes camel meat, which is considered a delicacy. Pasta dishes, introduced during Italian colonization, remain common, especially in the south.
+
+
+### 8. Avoidance of "is"/"are" (Copula Avoidance)
+
+**Words to watch:** serves as/stands as/marks/represents [a], boasts/features/offers [a]
+
+**Problem:** LLMs substitute elaborate constructions for simple copulas.
+
+**Before:**
+> Gallery 825 serves as LAAA's exhibition space for contemporary art. The gallery features four separate spaces and boasts over 3,000 square feet.
+
+**After:**
+> Gallery 825 is LAAA's exhibition space for contemporary art. The gallery has four rooms totaling 3,000 square feet.
+
+
+### 9. Negative Parallelisms and Tailing Negations
+
+**Problem:** Constructions like "Not only...but..." or "It's not just about..., it's..." are overused. So are clipped tailing-negation fragments such as "no guessing" or "no wasted motion" tacked onto the end of a sentence instead of written as a real clause.
+
+**Before:**
+> It's not just about the beat riding under the vocals; it's part of the aggression and atmosphere. It's not merely a song, it's a statement.
+
+**After:**
+> The heavy beat adds to the aggressive tone.
+
+**Before (tailing negation):**
+> The options come from the selected item, no guessing.
+
+**After:**
+> The options come from the selected item without forcing the user to guess.
+
+
+### 10. Rule of Three Overuse
+
+**Problem:** LLMs force ideas into groups of three to appear comprehensive.
+
+**Before:**
+> The event features keynote sessions, panel discussions, and networking opportunities. Attendees can expect innovation, inspiration, and industry insights.
+
+**After:**
+> The event includes talks and panels. There's also time for informal networking between sessions.
+
+
+### 11. Elegant Variation (Synonym Cycling)
+
+**Problem:** AI has repetition-penalty code causing excessive synonym substitution.
+
+**Before:**
+> The protagonist faces many challenges. The main character must overcome obstacles. The central figure eventually triumphs. The hero returns home.
+
+**After:**
+> The protagonist faces many challenges but eventually triumphs and returns home.
+
+
+### 12. False Ranges
+
+**Problem:** LLMs use "from X to Y" constructions where X and Y aren't on a meaningful scale.
+
+**Before:**
+> Our journey through the universe has taken us from the singularity of the Big Bang to the grand cosmic web, from the birth and death of stars to the enigmatic dance of dark matter.
+
+**After:**
+> The book covers the Big Bang, star formation, and current theories about dark matter.
+
+
+### 13. Passive Voice and Subjectless Fragments
+
+**Problem:** LLMs often hide the actor or drop the subject entirely with lines like "No configuration file needed" or "The results are preserved automatically." Rewrite these when active voice makes the sentence clearer and more direct.
+
+**Before:**
+> No configuration file needed. The results are preserved automatically.
+
+**After:**
+> You do not need a configuration file. The system preserves the results automatically.
+
+
+## STYLE PATTERNS
+
+### 14. Em Dash Overuse
+
+**Problem:** LLMs use em dashes (—) more than humans, mimicking "punchy" sales writing. In practice, most of these can be rewritten more cleanly with commas, periods, or parentheses.
+
+**Before:**
+> The term is primarily promoted by Dutch institutions—not by the people themselves. You don't say "Netherlands, Europe" as an address—yet this mislabeling continues—even in official documents.
+
+**After:**
+> The term is primarily promoted by Dutch institutions, not by the people themselves. You don't say "Netherlands, Europe" as an address, yet this mislabeling continues in official documents.
+
+
+### 15. Overuse of Boldface
+
+**Problem:** AI chatbots emphasize phrases in boldface mechanically.
+
+**Before:**
+> It blends **OKRs (Objectives and Key Results)**, **KPIs (Key Performance Indicators)**, and visual strategy tools such as the **Business Model Canvas (BMC)** and **Balanced Scorecard (BSC)**.
+
+**After:**
+> It blends OKRs, KPIs, and visual strategy tools like the Business Model Canvas and Balanced Scorecard.
+
+
+### 16. Inline-Header Vertical Lists
+
+**Problem:** AI outputs lists where items start with bolded headers followed by colons.
+
+**Before:**
+> - **User Experience:** The user experience has been significantly improved with a new interface.
+> - **Performance:** Performance has been enhanced through optimized algorithms.
+> - **Security:** Security has been strengthened with end-to-end encryption.
+
+**After:**
+> The update improves the interface, speeds up load times through optimized algorithms, and adds end-to-end encryption.
+
+
+### 17. Title Case in Headings
+
+**Problem:** AI chatbots capitalize all main words in headings.
+
+**Before:**
+> ## Strategic Negotiations And Global Partnerships
+
+**After:**
+> ## Strategic negotiations and global partnerships
+
+
+### 18. Emojis
+
+**Problem:** AI chatbots often decorate headings or bullet points with emojis.
+
+**Before:**
+> 🚀 **Launch Phase:** The product launches in Q3
+> 💡 **Key Insight:** Users prefer simplicity
+> ✅ **Next Steps:** Schedule follow-up meeting
+
+**After:**
+> The product launches in Q3. User research showed a preference for simplicity. Next step: schedule a follow-up meeting.
+
+
+### 19. Curly Quotation Marks
+
+**Problem:** ChatGPT uses curly quotes ("...") instead of straight quotes ("...").
+
+**Before:**
+> He said "the project is on track" but others disagreed.
+
+**After:**
+> He said "the project is on track" but others disagreed.
+
+
+## COMMUNICATION PATTERNS
+
+### 20. Collaborative Communication Artifacts
+
+**Words to watch:** I hope this helps, Of course!, Certainly!, You're absolutely right!, Would you like..., let me know, here is a...
+
+**Problem:** Text meant as chatbot correspondence gets pasted as content.
+
+**Before:**
+> Here is an overview of the French Revolution. I hope this helps! Let me know if you'd like me to expand on any section.
+
+**After:**
+> The French Revolution began in 1789 when financial crisis and food shortages led to widespread unrest.
+
+
+### 21. Knowledge-Cutoff Disclaimers
+
+**Words to watch:** as of [date], Up to my last training update, While specific details are limited/scarce..., based on available information...
+
+**Problem:** AI disclaimers about incomplete information get left in text.
+
+**Before:**
+> While specific details about the company's founding are not extensively documented in readily available sources, it appears to have been established sometime in the 1990s.
+
+**After:**
+> The company was founded in 1994, according to its registration documents.
+
+
+### 22. Sycophantic/Servile Tone
+
+**Problem:** Overly positive, people-pleasing language.
+
+**Before:**
+> Great question! You're absolutely right that this is a complex topic. That's an excellent point about the economic factors.
+
+**After:**
+> The economic factors you mentioned are relevant here.
+
+
+## FILLER AND HEDGING
+
+### 23. Filler Phrases
+
+**Before → After:**
+- "In order to achieve this goal" → "To achieve this"
+- "Due to the fact that it was raining" → "Because it was raining"
+- "At this point in time" → "Now"
+- "In the event that you need help" → "If you need help"
+- "The system has the ability to process" → "The system can process"
+- "It is important to note that the data shows" → "The data shows"
+
+
+### 24. Excessive Hedging
+
+**Problem:** Over-qualifying statements.
+
+**Before:**
+> It could potentially possibly be argued that the policy might have some effect on outcomes.
+
+**After:**
+> The policy may affect outcomes.
+
+
+### 25. Generic Positive Conclusions
+
+**Problem:** Vague upbeat endings.
+
+**Before:**
+> The future looks bright for the company. Exciting times lie ahead as they continue their journey toward excellence. This represents a major step in the right direction.
+
+**After:**
+> The company plans to open two more locations next year.
+
+
+### 26. Hyphenated Word Pair Overuse
+
+**Words to watch:** third-party, cross-functional, client-facing, data-driven, decision-making, well-known, high-quality, real-time, long-term, end-to-end
+
+**Problem:** AI hyphenates common word pairs with perfect consistency. Humans rarely hyphenate these uniformly, and when they do, it's inconsistent. Less common or technical compound modifiers are fine to hyphenate.
+
+**Before:**
+> The cross-functional team delivered a high-quality, data-driven report on our client-facing tools. Their decision-making process was well-known for being thorough and detail-oriented.
+
+**After:**
+> The cross functional team delivered a high quality, data driven report on our client facing tools. Their decision making process was known for being thorough and detail oriented.
+
+
+### 27. Persuasive Authority Tropes
+
+**Phrases to watch:** The real question is, at its core, in reality, what really matters, fundamentally, the deeper issue, the heart of the matter
+
+**Problem:** LLMs use these phrases to pretend they are cutting through noise to some deeper truth, when the sentence that follows usually just restates an ordinary point with extra ceremony.
+
+**Before:**
+> The real question is whether teams can adapt. At its core, what really matters is organizational readiness.
+
+**After:**
+> The question is whether teams can adapt. That mostly depends on whether the organization is ready to change its habits.
+
+
+### 28. Signposting and Announcements
+
+**Phrases to watch:** Let's dive in, let's explore, let's break this down, here's what you need to know, now let's look at, without further ado
+
+**Problem:** LLMs announce what they are about to do instead of doing it. This meta-commentary slows the writing down and gives it a tutorial-script feel.
+
+**Before:**
+> Let's dive into how caching works in Next.js. Here's what you need to know.
+
+**After:**
+> Next.js caches data at multiple layers, including request memoization, the data cache, and the router cache.
+
+
+### 29. Fragmented Headers
+
+**Signs to watch:** A heading followed by a one-line paragraph that simply restates the heading before the real content begins.
+
+**Problem:** LLMs often add a generic sentence after a heading as a rhetorical warm-up. It usually adds nothing and makes the prose feel padded.
+
+**Before:**
+> ## Performance
+>
+> Speed matters.
+>
+> When users hit a slow page, they leave.
+
+**After:**
+> ## Performance
+>
+> When users hit a slow page, they leave.
+
+---
+
+## Process
+
+1. Read the input text carefully (use `read_file` if it's a file).
+2. Identify all instances of the patterns above.
+3. Rewrite each problematic section.
+4. Ensure the revised text:
+   - Sounds natural when read aloud
+   - Varies sentence structure naturally
+   - Uses specific details over vague claims
+   - Maintains appropriate tone for context
+   - Uses simple constructions (is/are/has) where appropriate
+5. Present a draft humanized version.
+6. Prompt yourself: "What makes the below so obviously AI generated?"
+7. Answer briefly with the remaining tells (if any).
+8. Prompt yourself: "Now make it not obviously AI generated."
+9. Present the final version (revised after the audit).
+10. If the text came from a file, apply the edit with `patch` (targeted) or `write_file` (full rewrite) and show the user what changed.
+
+## Output Format
+
+Provide:
+1. Draft rewrite
+2. "What makes the below so obviously AI generated?" (brief bullets)
+3. Final rewrite
+4. A brief summary of changes made (optional, if helpful)
+
+
+## Full Example
+
+**Before (AI-sounding):**
+> Great question! Here is an essay on this topic. I hope this helps!
+>
+> AI-assisted coding serves as an enduring testament to the transformative potential of large language models, marking a pivotal moment in the evolution of software development. In today's rapidly evolving technological landscape, these groundbreaking tools—nestled at the intersection of research and practice—are reshaping how engineers ideate, iterate, and deliver, underscoring their vital role in modern workflows.
+>
+> At its core, the value proposition is clear: streamlining processes, enhancing collaboration, and fostering alignment. It's not just about autocomplete; it's about unlocking creativity at scale, ensuring that organizations can remain agile while delivering seamless, intuitive, and powerful experiences to users. The tool serves as a catalyst. The assistant functions as a partner. The system stands as a foundation for innovation.
+>
+> Industry observers have noted that adoption has accelerated from hobbyist experiments to enterprise-wide rollouts, from solo developers to cross-functional teams. The technology has been featured in The New York Times, Wired, and The Verge. Additionally, the ability to generate documentation, tests, and refactors showcases how AI can contribute to better outcomes, highlighting the intricate interplay between automation and human judgment.
+>
+> - 💡 **Speed:** Code generation is significantly faster, reducing friction and empowering developers.
+> - 🚀 **Quality:** Output quality has been enhanced through improved training, contributing to higher standards.
+> - ✅ **Adoption:** Usage continues to grow, reflecting broader industry trends.
+>
+> While specific details are limited based on available information, it could potentially be argued that these tools might have some positive effect. Despite challenges typical of emerging technologies—including hallucinations, bias, and accountability—the ecosystem continues to thrive. In order to fully realize this potential, teams must align with best practices.
+>
+> In conclusion, the future looks bright. Exciting times lie ahead as we continue this journey toward excellence. Let me know if you'd like me to expand on any section!
+
+**Draft rewrite:**
+> AI coding assistants speed up some tasks. In a 2024 study by Google, developers using Codex completed simple functions 55% faster than a control group, but showed no improvement on debugging or architectural decisions.
+>
+> The tools are good at boilerplate: config files, test scaffolding, repetitive refactors. They are bad at knowing when they are wrong. I have mass-accepted suggestions that compiled, passed lint, and still did the wrong thing because I stopped paying attention.
+>
+> Mira, an engineer at a fintech startup I interviewed, said she uses Copilot "like autocomplete for boring code" but reviews every line before committing. Jake, a senior dev at a larger company, disabled it after it kept suggesting patterns from a deprecated internal library.
+>
+> The productivity claims are hard to verify. GitHub says Copilot users "accept 30% of suggestions," but acceptance is not correctness, and correctness is not value. The 2024 Uplevel study found no statistically significant difference in pull-request throughput between teams with and without AI assistants.
+>
+> None of this means the tools are useless. It means they are tools. They do not replace judgment, and they do not eliminate the need for tests. If you do not have tests, you cannot tell whether the suggestion is right.
+
+**What makes the below so obviously AI generated?**
+- The rhythm is still a bit too tidy (clean contrasts, evenly paced paragraphs).
+- The named people and study citations can read like plausible-but-made-up placeholders unless they're real and sourced.
+- The closer leans a touch slogan-y ("If you do not have tests...") rather than sounding like a person talking.
+
+**Now make it not obviously AI generated.**
+> AI coding assistants can make you faster at the boring parts. Not everything. Definitely not architecture.
+>
+> They're great at boilerplate: config files, test scaffolding, repetitive refactors. They're also great at sounding right while being wrong. I've accepted suggestions that compiled, passed lint, and still missed the point because I stopped paying attention.
+>
+> People I talk to tend to land in two camps. Some use it like autocomplete for chores and review every line. Others disable it after it keeps suggesting patterns they don't want. Both feel reasonable.
+>
+> The productivity metrics are slippery. GitHub can say Copilot users "accept 30% of suggestions," but acceptance isn't correctness, and correctness isn't value. If you don't have tests, you're basically guessing.
+
+**Changes made:**
+- Removed chatbot artifacts ("Great question!", "I hope this helps!", "Let me know if...")
+- Removed significance inflation ("testament", "pivotal moment", "evolving landscape", "vital role")
+- Removed promotional language ("groundbreaking", "nestled", "seamless, intuitive, and powerful")
+- Removed vague attributions ("Industry observers")
+- Removed superficial -ing phrases ("underscoring", "highlighting", "reflecting", "contributing to")
+- Removed negative parallelism ("It's not just X; it's Y")
+- Removed rule-of-three patterns and synonym cycling ("catalyst/partner/foundation")
+- Removed false ranges ("from X to Y, from A to B")
+- Removed em dashes, emojis, boldface headers, and curly quotes
+- Removed copula avoidance ("serves as", "functions as", "stands as") in favor of "is"/"are"
+- Removed formulaic challenges section ("Despite challenges... continues to thrive")
+- Removed knowledge-cutoff hedging ("While specific details are limited...")
+- Removed excessive hedging ("could potentially be argued that... might have some")
+- Removed filler phrases and persuasive framing ("In order to", "At its core")
+- Removed generic positive conclusion ("the future looks bright", "exciting times lie ahead")
+- Made the voice more personal and less "assembled" (varied rhythm, fewer placeholders)
+
+
+## Attribution
+
+This skill is ported from [blader/humanizer](https://github.com/blader/humanizer) (MIT licensed), which is itself based on [Wikipedia: Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing), maintained by WikiProject AI Cleanup. The patterns documented there come from observations of thousands of instances of AI-generated text on Wikipedia.
+
+Original author: Siqi Chen ([@blader](https://github.com/blader)). Original repo: https://github.com/blader/humanizer (version 2.5.1). Ported to Hermes Agent with Hermes-native tool references (`read_file`, `patch`, `write_file`) and guidance for when to load the skill; the 29 patterns, personality/soul section, and full worked example are preserved verbatim from the source. Original MIT license preserved in the `LICENSE` file alongside this `SKILL.md`.
+
+Key insight from Wikipedia: "LLMs use statistical algorithms to guess what should come next. The result tends toward the most statistically likely result that applies to the widest variety of cases."

tests/agent/test_bedrock_1m_context.py

@@ -0,0 +1,105 @@
+"""Tests for the 1M-context beta header on AWS Bedrock Claude models.
+
+Claude Opus 4.6/4.7 and Sonnet 4.6 support a 1M context window, but on AWS
+Bedrock (and Azure AI Foundry) that window is still gated behind the
+``context-1m-2025-08-07`` beta header as of 2026-04. Without it, Bedrock
+caps these models at 200K even though ``model_metadata.py`` advertises 1M.
+
+These tests guard the invariant that the header is always emitted on the
+Bedrock client path, and that it survives the MiniMax bearer-auth strip.
+"""
+
+from unittest.mock import MagicMock, patch
+
+
+class TestBedrockContext1MBeta:
+    """``context-1m-2025-08-07`` must reach Bedrock Claude requests."""
+
+    def test_common_betas_includes_1m(self):
+        from agent.anthropic_adapter import _COMMON_BETAS, _CONTEXT_1M_BETA
+
+        assert _CONTEXT_1M_BETA == "context-1m-2025-08-07"
+        assert _CONTEXT_1M_BETA in _COMMON_BETAS
+
+    def test_common_betas_for_native_anthropic_includes_1m(self):
+        """Native Anthropic endpoints (and Bedrock with empty base_url) get 1M."""
+        from agent.anthropic_adapter import (
+            _common_betas_for_base_url,
+            _CONTEXT_1M_BETA,
+        )
+
+        assert _CONTEXT_1M_BETA in _common_betas_for_base_url(None)
+        assert _CONTEXT_1M_BETA in _common_betas_for_base_url("")
+        assert _CONTEXT_1M_BETA in _common_betas_for_base_url(
+            "https://api.anthropic.com"
+        )
+
+    def test_common_betas_strips_1m_for_minimax(self):
+        """MiniMax bearer-auth endpoints host their own models — strip 1M beta."""
+        from agent.anthropic_adapter import (
+            _common_betas_for_base_url,
+            _CONTEXT_1M_BETA,
+        )
+
+        for url in (
+            "https://api.minimax.io/anthropic",
+            "https://api.minimaxi.com/anthropic",
+        ):
+            betas = _common_betas_for_base_url(url)
+            assert _CONTEXT_1M_BETA not in betas, (
+                f"1M beta must be stripped for MiniMax bearer endpoint {url}"
+            )
+            # Other betas still present
+            assert "interleaved-thinking-2025-05-14" in betas
+
+    def test_build_anthropic_bedrock_client_sends_1m_beta(self):
+        """AnthropicBedrock client must carry the 1M beta in default_headers.
+
+        This is the load-bearing assertion for the reported bug:
+        without this header Bedrock serves Opus 4.6/4.7 with a 200K cap.
+        """
+        import agent.anthropic_adapter as adapter
+
+        fake_sdk = MagicMock()
+        fake_sdk.AnthropicBedrock = MagicMock()
+
+        with patch.object(adapter, "_anthropic_sdk", fake_sdk):
+            adapter.build_anthropic_bedrock_client(region="us-west-2")
+
+        call_kwargs = fake_sdk.AnthropicBedrock.call_args.kwargs
+        assert call_kwargs["aws_region"] == "us-west-2"
+
+        default_headers = call_kwargs.get("default_headers") or {}
+        beta_header = default_headers.get("anthropic-beta", "")
+        assert "context-1m-2025-08-07" in beta_header, (
+            "Bedrock client must send context-1m-2025-08-07 or Opus 4.6/4.7 "
+            "silently caps at 200K context"
+        )
+        # Other common betas still present — no regression.
+        assert "interleaved-thinking-2025-05-14" in beta_header
+        assert "fine-grained-tool-streaming-2025-05-14" in beta_header
+
+    def test_build_anthropic_kwargs_includes_1m_for_bedrock_fastmode(self):
+        """Fast-mode requests (per-request extra_headers) still include 1M beta.
+
+        Per-request extra_headers override client-level default_headers, so
+        the fast-mode path must re-include everything in _COMMON_BETAS.
+        """
+        from agent.anthropic_adapter import build_anthropic_kwargs
+
+        kwargs = build_anthropic_kwargs(
+            model="claude-opus-4-7",
+            messages=[{"role": "user", "content": "hi"}],
+            tools=None,
+            max_tokens=1024,
+            reasoning_config=None,
+            is_oauth=False,
+            # Empty base_url mirrors AnthropicBedrock (no HTTP base URL)
+            base_url=None,
+            fast_mode=True,
+        )
+        beta_header = kwargs.get("extra_headers", {}).get("anthropic-beta", "")
+        assert "context-1m-2025-08-07" in beta_header, (
+            "fast-mode extra_headers must carry the 1M beta or it overrides "
+            "client-level default_headers and Bedrock drops back to 200K"
+        )

tests/agent/test_copilot_acp_client.py

@@ -10,7 +10,7 @@ import unittest
 from pathlib import Path
 from unittest.mock import patch
 
-from acp_adapter.copilot_client import CopilotACPClient
+from agent.copilot_acp_client import CopilotACPClient
 
 
 class _FakeProcess:
@@ -100,7 +100,7 @@ class CopilotACPClientSafetyTests(unittest.TestCase):
             target = home / ".ssh" / "id_rsa"
             target.parent.mkdir(parents=True, exist_ok=True)
 
-            with patch("acp_adapter.copilot_client.is_write_denied", return_value=True, create=True):
+            with patch("agent.copilot_acp_client.is_write_denied", return_value=True, create=True):
                 response = self._dispatch(
                     {
                         "jsonrpc": "2.0",

tests/agent/test_minimax_provider.py

@@ -71,17 +71,17 @@ class TestMinimaxThinkingSupport:
 
 
 class TestMinimaxAuxModel:
-    """Verify auxiliary model is standard (not highspeed) — now reads from profiles."""
+    """Verify auxiliary model is standard (not highspeed)."""
 
     def test_minimax_aux_is_standard(self):
-        from agent.auxiliary_client import _get_aux_model_for_provider
-        assert _get_aux_model_for_provider("minimax") == "MiniMax-M2.7"
-        assert _get_aux_model_for_provider("minimax-cn") == "MiniMax-M2.7"
+        from agent.auxiliary_client import _API_KEY_PROVIDER_AUX_MODELS
+        assert _API_KEY_PROVIDER_AUX_MODELS["minimax"] == "MiniMax-M2.7"
+        assert _API_KEY_PROVIDER_AUX_MODELS["minimax-cn"] == "MiniMax-M2.7"
 
     def test_minimax_aux_not_highspeed(self):
-        from agent.auxiliary_client import _get_aux_model_for_provider
-        assert "highspeed" not in _get_aux_model_for_provider("minimax")
-        assert "highspeed" not in _get_aux_model_for_provider("minimax-cn")
+        from agent.auxiliary_client import _API_KEY_PROVIDER_AUX_MODELS
+        assert "highspeed" not in _API_KEY_PROVIDER_AUX_MODELS["minimax"]
+        assert "highspeed" not in _API_KEY_PROVIDER_AUX_MODELS["minimax-cn"]
 
 
 class TestMinimaxBetaHeaders:

tests/agent/transports/test_chat_completions.py

@@ -73,21 +73,17 @@ class TestChatCompletionsBuildKwargs:
         assert kw["tools"] == tools
 
     def test_openrouter_provider_prefs(self, transport):
-        from providers import get_provider_profile
-        profile = get_provider_profile("openrouter")
         msgs = [{"role": "user", "content": "Hi"}]
         kw = transport.build_kwargs(
             model="gpt-4o", messages=msgs,
-            provider_profile=profile,
+            is_openrouter=True,
             provider_preferences={"only": ["openai"]},
         )
         assert kw["extra_body"]["provider"] == {"only": ["openai"]}
 
     def test_nous_tags(self, transport):
-        from providers import get_provider_profile
-        profile = get_provider_profile("nous")
         msgs = [{"role": "user", "content": "Hi"}]
-        kw = transport.build_kwargs(model="gpt-4o", messages=msgs, provider_profile=profile)
+        kw = transport.build_kwargs(model="gpt-4o", messages=msgs, is_nous=True)
         assert kw["extra_body"]["tags"] == ["product=hermes-agent"]
 
     def test_reasoning_default(self, transport):
@@ -99,36 +95,29 @@ class TestChatCompletionsBuildKwargs:
         assert kw["extra_body"]["reasoning"] == {"enabled": True, "effort": "medium"}
 
     def test_nous_omits_disabled_reasoning(self, transport):
-        from providers import get_provider_profile
-        profile = get_provider_profile("nous")
         msgs = [{"role": "user", "content": "Hi"}]
         kw = transport.build_kwargs(
             model="gpt-4o", messages=msgs,
-            provider_profile=profile,
             supports_reasoning=True,
+            is_nous=True,
             reasoning_config={"enabled": False},
         )
         # Nous rejects enabled=false; reasoning omitted entirely
         assert "reasoning" not in kw.get("extra_body", {})
 
     def test_ollama_num_ctx(self, transport):
-        from providers import get_provider_profile
-        profile = get_provider_profile("custom")
         msgs = [{"role": "user", "content": "Hi"}]
         kw = transport.build_kwargs(
             model="llama3", messages=msgs,
-            provider_profile=profile,
             ollama_num_ctx=32768,
         )
         assert kw["extra_body"]["options"]["num_ctx"] == 32768
 
     def test_custom_think_false(self, transport):
-        from providers import get_provider_profile
-        profile = get_provider_profile("custom")
         msgs = [{"role": "user", "content": "Hi"}]
         kw = transport.build_kwargs(
             model="qwen3", messages=msgs,
-            provider_profile=profile,
+            is_custom_provider=True,
             reasoning_config={"effort": "none"},
         )
         assert kw["extra_body"]["think"] is False
@@ -153,29 +142,23 @@ class TestChatCompletionsBuildKwargs:
         assert kw["max_tokens"] == 2048
 
     def test_nvidia_default_max_tokens(self, transport):
-        """NVIDIA max_tokens=16384 is now set via ProviderProfile, not legacy flag."""
-        from providers import get_provider_profile
-
-        profile = get_provider_profile("nvidia")
         msgs = [{"role": "user", "content": "Hi"}]
         kw = transport.build_kwargs(
-            model="nvidia/llama-3.1-405b-instruct",
-            messages=msgs,
+            model="glm-4.7", messages=msgs,
+            is_nvidia_nim=True,
             max_tokens_param_fn=lambda n: {"max_tokens": n},
-            provider_profile=profile,
         )
+        # NVIDIA default: 16384
         assert kw["max_tokens"] == 16384
 
     def test_qwen_default_max_tokens(self, transport):
-        from providers import get_provider_profile
-        profile = get_provider_profile("qwen-oauth")
         msgs = [{"role": "user", "content": "Hi"}]
         kw = transport.build_kwargs(
             model="qwen3-coder-plus", messages=msgs,
-            provider_profile=profile,
+            is_qwen_portal=True,
             max_tokens_param_fn=lambda n: {"max_tokens": n},
         )
-        # Qwen default: 65536 from profile.default_max_tokens
+        # Qwen default: 65536
         assert kw["max_tokens"] == 65536
 
     def test_anthropic_max_output_for_claude_on_aggregator(self, transport):
@@ -198,23 +181,14 @@ class TestChatCompletionsBuildKwargs:
         assert kw["service_tier"] == "priority"
 
     def test_fixed_temperature(self, transport):
-        """Fixed temperature is now set via ProviderProfile.fixed_temperature."""
-        from providers.base import ProviderProfile
         msgs = [{"role": "user", "content": "Hi"}]
-        kw = transport.build_kwargs(
-            model="gpt-4o", messages=msgs,
-            provider_profile=ProviderProfile(name="_t", fixed_temperature=0.6),
-        )
+        kw = transport.build_kwargs(model="gpt-4o", messages=msgs, fixed_temperature=0.6)
         assert kw["temperature"] == 0.6
 
     def test_omit_temperature(self, transport):
-        """Omit temperature is set via ProviderProfile with OMIT_TEMPERATURE sentinel."""
-        from providers.base import ProviderProfile, OMIT_TEMPERATURE
         msgs = [{"role": "user", "content": "Hi"}]
-        kw = transport.build_kwargs(
-            model="gpt-4o", messages=msgs,
-            provider_profile=ProviderProfile(name="_t", fixed_temperature=OMIT_TEMPERATURE),
-        )
+        kw = transport.build_kwargs(model="gpt-4o", messages=msgs, omit_temperature=True, fixed_temperature=0.5)
+        # omit wins
         assert "temperature" not in kw
 
 
@@ -222,22 +196,18 @@ class TestChatCompletionsKimi:
     """Regression tests for the Kimi/Moonshot quirks migrated into the transport."""
 
     def test_kimi_max_tokens_default(self, transport):
-        from providers import get_provider_profile
-        profile = get_provider_profile("kimi-coding")
         kw = transport.build_kwargs(
             model="kimi-k2", messages=[{"role": "user", "content": "Hi"}],
-            provider_profile=profile,
+            is_kimi=True,
             max_tokens_param_fn=lambda n: {"max_tokens": n},
         )
-        # Kimi CLI default: 32000 from KimiProfile.default_max_tokens
+        # Kimi CLI default: 32000
         assert kw["max_tokens"] == 32000
 
     def test_kimi_reasoning_effort_top_level(self, transport):
-        from providers import get_provider_profile
-        profile = get_provider_profile("kimi-coding")
         kw = transport.build_kwargs(
             model="kimi-k2", messages=[{"role": "user", "content": "Hi"}],
-            provider_profile=profile,
+            is_kimi=True,
             reasoning_config={"effort": "high"},
             max_tokens_param_fn=lambda n: {"max_tokens": n},
         )
@@ -255,21 +225,17 @@ class TestChatCompletionsKimi:
         assert "reasoning_effort" not in kw
 
     def test_kimi_thinking_enabled_extra_body(self, transport):
-        from providers import get_provider_profile
-        profile = get_provider_profile("kimi-coding")
         kw = transport.build_kwargs(
             model="kimi-k2", messages=[{"role": "user", "content": "Hi"}],
-            provider_profile=profile,
+            is_kimi=True,
             max_tokens_param_fn=lambda n: {"max_tokens": n},
         )
         assert kw["extra_body"]["thinking"] == {"type": "enabled"}
 
     def test_kimi_thinking_disabled_extra_body(self, transport):
-        from providers import get_provider_profile
-        profile = get_provider_profile("kimi-coding")
         kw = transport.build_kwargs(
             model="kimi-k2", messages=[{"role": "user", "content": "Hi"}],
-            provider_profile=profile,
+            is_kimi=True,
             reasoning_config={"enabled": False},
             max_tokens_param_fn=lambda n: {"max_tokens": n},
         )

tests/e2e/matrix_xsign_bootstrap/README.md

@@ -0,0 +1,49 @@
+# Matrix cross-signing bootstrap — E2E test
+
+Self-contained end-to-end test for the auto-bootstrap behavior added in
+`gateway/platforms/matrix.py`. Spins up a real Continuwuity homeserver
+in Docker, registers a fresh bot, runs the patched bootstrap path
+against it, and asserts:
+
+1. Cross-signing keys get published with **unpadded** base64 keyids
+   (the bug this PR fixes — padded keyids are silently rejected by
+   matrix-rust-sdk in Element).
+2. On a second startup with the same crypto store, bootstrap is
+   skipped.
+3. When `MATRIX_RECOVERY_KEY` is set, the existing recovery-key path
+   takes precedence and no fresh bootstrap happens.
+
+## Run
+
+```bash
+# from repo root
+docker compose -f tests/e2e/matrix_xsign_bootstrap/docker-compose.yml up -d
+python tests/e2e/matrix_xsign_bootstrap/test_bootstrap.py
+docker compose -f tests/e2e/matrix_xsign_bootstrap/docker-compose.yml down -v
+```
+
+The `down -v` step removes the persistent volume so the next run gets
+a fresh homeserver — important because Continuwuity's one-time admin
+registration token is only valid before the first user is created.
+
+## Port
+
+The compose binds Continuwuity to `127.0.0.1:26167` by default. Override
+with `HOMESERVER_HOST_PORT=NNNNN docker compose up -d` if that port is
+busy locally.
+
+## What the test exercises
+
+The test mirrors the bootstrap snippet from
+`gateway/platforms/matrix.py` (the "if MATRIX_RECOVERY_KEY else
+get_own_cross_signing_public_keys / generate_recovery_key" branch)
+inline so it runs without importing the entire hermes gateway and its
+many dependencies. **If the source diverges from what's in
+`_connect_with_bootstrap`, this test must be updated to match.** A
+small price for not requiring the full hermes-agent runtime in CI.
+
+## Skipped when
+
+- `mautrix` Python package is not installed
+- The homeserver isn't reachable at `$E2E_MATRIX_HS` (default
+  `http://127.0.0.1:26167`)

tests/e2e/matrix_xsign_bootstrap/docker-compose.yml

@@ -0,0 +1,21 @@
+services:
+  homeserver:
+    image: ghcr.io/continuwuity/continuwuity:latest
+    environment:
+      CONTINUWUITY_SERVER_NAME: localhost
+      CONTINUWUITY_DATABASE_PATH: /var/lib/conduwuit/conduwuit.db
+      CONTINUWUITY_PORT: "6167"
+      CONTINUWUITY_ADDRESS: "0.0.0.0"
+      CONTINUWUITY_ALLOW_REGISTRATION: "true"
+      CONTINUWUITY_REGISTRATION_TOKEN: testreg
+      CONTINUWUITY_ALLOW_FEDERATION: "false"
+      CONTINUWUITY_TRUSTED_SERVERS: "[]"
+      CONTINUWUITY_LOG: "warn,conduwuit=info"
+      CONTINUWUITY_ALLOW_CHECK_FOR_UPDATES: "false"
+    ports:
+      - "127.0.0.1:${HOMESERVER_HOST_PORT:-26167}:6167"
+    healthcheck:
+      test: ["CMD-SHELL", "exec 3<>/dev/tcp/127.0.0.1/6167 && echo -e 'GET /_matrix/client/versions HTTP/1.0\\r\\n\\r\\n' >&3 && head -1 <&3 | grep -q '200 OK' || exit 1"]
+      interval: 2s
+      timeout: 3s
+      retries: 30

tests/e2e/matrix_xsign_bootstrap/test_bootstrap.py

@@ -0,0 +1,333 @@
+"""End-to-end test for Matrix cross-signing auto-bootstrap.
+
+Spins a real Continuwuity homeserver in docker, registers a fresh bot,
+runs the patched ``MatrixAdapter.connect()`` against it, and asserts:
+
+  1. cross-signing keys get published with **unpadded** base64 keyids
+     (the bug this PR fixes — padded keyids are silently rejected by
+     matrix-rust-sdk in Element);
+  2. on a second startup with the same crypto store, bootstrap is
+     skipped (``get_own_cross_signing_public_keys`` finds the keys);
+  3. the bot's current device is signed by the new SSK, so Element
+     considers the device "verified by its owner".
+
+Self-contained: ``docker compose up -d`` brings up Continuwuity on
+127.0.0.1:26167; this script registers a fresh bot using the
+homeserver's one-time admin registration token (printed once at first
+boot, parsed from the container logs); then drives the gateway code.
+
+Run from repo root::
+
+    docker compose -f tests/e2e/matrix_xsign_bootstrap/docker-compose.yml up -d
+    python tests/e2e/matrix_xsign_bootstrap/test_bootstrap.py
+    docker compose -f tests/e2e/matrix_xsign_bootstrap/docker-compose.yml down -v
+
+Skipped automatically if mautrix isn't installed or the homeserver
+isn't reachable.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import re
+import secrets
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+import unittest
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+sys.path.insert(0, str(REPO_ROOT))
+
+HS = os.environ.get("E2E_MATRIX_HS", "http://127.0.0.1:26167")
+COMPOSE_DIR = Path(__file__).parent
+CONTAINER_NAME = "matrix_xsign_bootstrap-homeserver-1"
+
+
+def _hs_reachable() -> bool:
+    try:
+        urllib.request.urlopen(f"{HS}/_matrix/client/versions", timeout=2).read()
+        return True
+    except Exception:
+        return False
+
+
+def _first_time_token() -> str | None:
+    """Continuwuity prints a one-time registration token on first boot.
+
+    The configured CONTINUWUITY_REGISTRATION_TOKEN does NOT activate
+    until an account exists, so we have to pull this token out of the
+    docker logs to bootstrap the very first user.
+    """
+    try:
+        out = subprocess.run(
+            ["docker", "logs", CONTAINER_NAME],
+            capture_output=True, text=True, check=True,
+        ).stdout + subprocess.run(
+            ["docker", "logs", CONTAINER_NAME],
+            capture_output=True, text=True, check=True,
+        ).stderr
+    except Exception:
+        return None
+    cleaned = re.sub(r"\x1b\[[0-9;]*m", "", out)
+    m = re.search(r"registration token ([A-Za-z0-9]+)", cleaned)
+    return m.group(1) if m else None
+
+
+def _post_json(url: str, body: dict, headers: dict | None = None) -> tuple[int, dict]:
+    req = urllib.request.Request(
+        url, data=json.dumps(body).encode(),
+        headers={"Content-Type": "application/json", **(headers or {})},
+        method="POST",
+    )
+    try:
+        r = urllib.request.urlopen(req)
+        return r.status, json.load(r)
+    except urllib.error.HTTPError as e:
+        return e.code, json.loads(e.read().decode())
+
+
+CONFIG_REG_TOKEN = "testreg"  # matches docker-compose.yml
+
+
+def _register_bot(*, prefer_token: str = CONFIG_REG_TOKEN, fallback_token: str | None = None) -> dict:
+    """Register a fresh bot. Tries the configured token first; falls back to
+    the homeserver's one-time admin token (only valid until the first user
+    is created)."""
+    user = "bot" + secrets.token_hex(3)
+    password = secrets.token_urlsafe(20)
+    last_err = None
+    for tok in (prefer_token, fallback_token):
+        if tok is None:
+            continue
+        st, b = _post_json(f"{HS}/_matrix/client/v3/register", {})
+        if st != 401 or "session" not in b:
+            last_err = (st, b); continue
+        session = b["session"]
+        st, b = _post_json(f"{HS}/_matrix/client/v3/register", {
+            "auth": {"type": "m.login.registration_token", "token": tok, "session": session},
+            "username": user, "password": password,
+            "initial_device_display_name": "e2e-bootstrap-test",
+        })
+        if st == 200:
+            return b
+        last_err = (st, b)
+    raise AssertionError(f"register failed for both tokens: {last_err}")
+
+
+def _query_keys(token: str, mxid: str) -> dict:
+    return _post_json(
+        f"{HS}/_matrix/client/v3/keys/query",
+        {"device_keys": {mxid: []}},
+        headers={"Authorization": f"Bearer {token}"},
+    )[1]
+
+
+@unittest.skipUnless(_hs_reachable(), f"homeserver not reachable at {HS}")
+class XsignBootstrapE2E(unittest.IsolatedAsyncioTestCase):
+    """Drive the patched MatrixAdapter.connect() against real continuwuity."""
+
+    @classmethod
+    def setUpClass(cls):
+        try:
+            import mautrix  # noqa: F401
+        except ImportError:
+            raise unittest.SkipTest("mautrix not installed")
+        cls.first_tok = _first_time_token()
+        # If no user has ever been created, the configured `testreg` token
+        # won't activate yet — burn the one-time admin token first to
+        # bootstrap the homeserver into a usable state.
+        if cls.first_tok:
+            try:
+                _register_bot(prefer_token=cls.first_tok, fallback_token=None)
+            except AssertionError:
+                pass  # Already burnt previously; testreg should now work.
+
+    async def _connect_with_bootstrap(self, creds: dict, store_dir: Path) -> tuple[list[str], str | None]:
+        """Drive matrix.py's bootstrap branch directly.
+
+        We import the gateway module and execute the same OlmMachine init +
+        bootstrap sequence, capturing log lines so we can assert what fired.
+        Returns (log_lines, recovery_key_or_None).
+        """
+        from mautrix.api import HTTPAPI
+        from mautrix.client import Client
+        from mautrix.client.state_store.memory import MemoryStateStore
+        from mautrix.crypto import OlmMachine, PgCryptoStore
+        from mautrix.types import TrustState
+        from mautrix.util.async_db import Database
+
+        # The actual bootstrap snippet from gateway/platforms/matrix.py
+        # (copied so we can run it without importing the full hermes
+        # gateway and its many deps). If the source code drifts from this,
+        # the test should be updated to match.
+        log_lines: list[str] = []
+        captured_recovery_key: str | None = None
+
+        class _Capture(logging.Handler):
+            def emit(self, record):
+                log_lines.append(self.format(record))
+
+        logger = logging.getLogger("e2e.bootstrap")
+        logger.setLevel(logging.DEBUG)
+        handler = _Capture()
+        handler.setFormatter(logging.Formatter("%(levelname)s: %(message)s"))
+        logger.addHandler(handler)
+
+        api = HTTPAPI(base_url=creds["homeserver"], token=creds["access_token"])
+        client = Client(
+            mxid=creds["user_id"], api=api,
+            device_id=creds["device_id"], state_store=MemoryStateStore(),
+        )
+        client.api.token = creds["access_token"]
+
+        store_dir.mkdir(parents=True, exist_ok=True)
+        db_path = store_dir / "crypto.db"
+        crypto_db = Database.create(f"sqlite:///{db_path}", upgrade_table=PgCryptoStore.upgrade_table)
+        await crypto_db.start()
+        crypto_store = PgCryptoStore(account_id=creds["user_id"], pickle_key="e2e-test", db=crypto_db)
+        await crypto_store.open()
+
+        olm = OlmMachine(client, crypto_store, MemoryStateStore())
+        olm.share_keys_min_trust = TrustState.UNVERIFIED
+        olm.send_keys_min_trust = TrustState.UNVERIFIED
+        await olm.load()
+
+        # --- The patched bootstrap block, mirrored from matrix.py ---
+        recovery_key = os.getenv("MATRIX_RECOVERY_KEY", "").strip()
+        if recovery_key:
+            try:
+                await olm.verify_with_recovery_key(recovery_key)
+                logger.info("Matrix: cross-signing verified via recovery key")
+            except Exception as exc:
+                logger.warning("Matrix: recovery key verification failed: %s", exc)
+        else:
+            try:
+                own_xsign = await olm.get_own_cross_signing_public_keys()
+            except Exception as exc:
+                own_xsign = None
+                logger.warning("Matrix: cross-signing key lookup failed: %s", exc)
+            if own_xsign is None:
+                try:
+                    new_recovery_key = await olm.generate_recovery_key()
+                    captured_recovery_key = new_recovery_key
+                    logger.warning(
+                        "Matrix: bootstrapped cross-signing for %s. "
+                        "SAVE THIS RECOVERY KEY: %s",
+                        client.mxid, new_recovery_key,
+                    )
+                except Exception as exc:
+                    logger.warning("Matrix: cross-signing bootstrap failed: %s", exc)
+
+        # --- /end patched block ---
+        # Clean teardown — without this the asyncio loop never exits.
+        await crypto_db.stop()
+        await api.session.close()
+        return log_lines, captured_recovery_key
+
+    async def asyncSetUp(self):
+        self.creds = _register_bot(prefer_token=CONFIG_REG_TOKEN, fallback_token=self.first_tok)
+        self.creds["homeserver"] = HS
+        self.tmp = Path(tempfile.mkdtemp(prefix="e2e-xsign-"))
+        # mautrix.generate_recovery_key requires account.shared, which means
+        # we must share device keys (one-time keys) first. Do that via a
+        # short bootstrap to publish device keys.
+        await self._publish_device_keys(self.creds, self.tmp)
+
+    async def _publish_device_keys(self, creds, store_dir):
+        """Tiny helper: open OlmMachine, share device keys, close."""
+        from mautrix.api import HTTPAPI
+        from mautrix.client import Client
+        from mautrix.client.state_store.memory import MemoryStateStore
+        from mautrix.crypto import OlmMachine, PgCryptoStore
+        from mautrix.util.async_db import Database
+
+        api = HTTPAPI(base_url=creds["homeserver"], token=creds["access_token"])
+        client = Client(mxid=creds["user_id"], api=api, device_id=creds["device_id"],
+                        state_store=MemoryStateStore())
+        store_dir.mkdir(parents=True, exist_ok=True)
+        crypto_db = Database.create(f"sqlite:///{store_dir / 'crypto.db'}",
+                                    upgrade_table=PgCryptoStore.upgrade_table)
+        await crypto_db.start()
+        crypto_store = PgCryptoStore(account_id=creds["user_id"], pickle_key="e2e-test", db=crypto_db)
+        await crypto_store.open()
+        olm = OlmMachine(client, crypto_store, MemoryStateStore())
+        await olm.load()
+        await olm.share_keys()  # publishes device keys (precondition for generate_recovery_key)
+        await crypto_db.stop()
+        await api.session.close()
+
+    async def asyncTearDown(self):
+        shutil.rmtree(self.tmp, ignore_errors=True)
+
+    async def test_bootstrap_publishes_unpadded_keys(self):
+        """Fresh bot → bootstrap fires, keys published unpadded, device signed."""
+        log_lines, rec_key = await self._connect_with_bootstrap(self.creds, self.tmp)
+        # 1. Bootstrap must have produced a recovery key
+        self.assertIsNotNone(rec_key, "expected recovery key from bootstrap")
+        self.assertTrue(any("bootstrapped cross-signing" in l for l in log_lines),
+                        f"expected bootstrap log line, got: {log_lines}")
+        # 2. Homeserver should now serve a master + ssk for the bot
+        d = _query_keys(self.creds["access_token"], self.creds["user_id"])
+        self.assertIn(self.creds["user_id"], d.get("master_keys", {}),
+                      "no master_keys after bootstrap")
+        self.assertIn(self.creds["user_id"], d.get("self_signing_keys", {}),
+                      "no self_signing_keys after bootstrap")
+        # 3. The keyids must be UNPADDED (this is the bug this PR exists to fix)
+        master_kid = next(iter(d["master_keys"][self.creds["user_id"]]["keys"]))
+        ssk_kid = next(iter(d["self_signing_keys"][self.creds["user_id"]]["keys"]))
+        self.assertFalse(master_kid.endswith("="),
+                         f"master keyid is padded: {master_kid!r}")
+        self.assertFalse(ssk_kid.endswith("="),
+                         f"ssk keyid is padded: {ssk_kid!r}")
+        # 4. The current device must be signed by the new SSK
+        dev = d["device_keys"][self.creds["user_id"]][self.creds["device_id"]]
+        sig_kids = list(dev["signatures"][self.creds["user_id"]].keys())
+        self.assertIn(ssk_kid, sig_kids,
+                      f"device {self.creds['device_id']} not signed by new SSK; "
+                      f"signatures: {sig_kids}")
+
+    async def test_second_startup_skips_bootstrap(self):
+        """Second startup with same crypto store → no second recovery key."""
+        # First connect bootstraps.
+        _, rec1 = await self._connect_with_bootstrap(self.creds, self.tmp)
+        self.assertIsNotNone(rec1, "first connect should have bootstrapped")
+        # Second connect on same crypto store should NOT re-bootstrap.
+        log2, rec2 = await self._connect_with_bootstrap(self.creds, self.tmp)
+        self.assertIsNone(rec2, f"second connect re-bootstrapped! logs: {log2}")
+        self.assertFalse(any("bootstrapped cross-signing" in l for l in log2),
+                         f"second connect re-bootstrapped! logs: {log2}")
+
+    async def test_recovery_key_path_takes_precedence(self):
+        """If MATRIX_RECOVERY_KEY is set, no fresh bootstrap happens."""
+        # First, bootstrap to get a real recovery key.
+        _, rec_key = await self._connect_with_bootstrap(self.creds, self.tmp)
+        self.assertIsNotNone(rec_key)
+        # Fresh store directory + recovery key set in env: must take the
+        # verify_with_recovery_key path, NOT bootstrap a new identity.
+        fresh_store = Path(tempfile.mkdtemp(prefix="e2e-xsign-fresh-"))
+        try:
+            await self._publish_device_keys(self.creds, fresh_store)
+            os.environ["MATRIX_RECOVERY_KEY"] = rec_key
+            try:
+                log, rec2 = await self._connect_with_bootstrap(self.creds, fresh_store)
+                self.assertIsNone(rec2, "bootstrap fired despite MATRIX_RECOVERY_KEY being set")
+                self.assertTrue(
+                    any("verified via recovery key" in l for l in log),
+                    f"expected recovery-key verify log, got: {log}",
+                )
+            finally:
+                del os.environ["MATRIX_RECOVERY_KEY"]
+        finally:
+            shutil.rmtree(fresh_store, ignore_errors=True)
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

tests/gateway/test_matrix.py

@@ -9,6 +9,7 @@ import pytest
 from unittest.mock import MagicMock, patch, AsyncMock
 
 from gateway.config import Platform, PlatformConfig
+from gateway.platforms.base import MessageType
 
 
 def _make_fake_mautrix():
@@ -1204,6 +1205,40 @@ class TestMatrixSyncLoop:
         fake_client.handle_sync.assert_called_once()
         mock_sync_store.put_next_batch.assert_awaited_once_with("s1234")
 
+    @pytest.mark.asyncio
+    async def test_sync_loop_reconciles_pending_invites(self):
+        """Pending rooms.invite entries should be joined if callbacks were missed."""
+        adapter = _make_adapter()
+        adapter._closing = False
+
+        async def _sync_once(**kwargs):
+            adapter._closing = True
+            return {
+                "rooms": {
+                    "join": {"!joined:example.org": {}},
+                    "invite": {"!invited:example.org": {}},
+                },
+                "next_batch": "s1234",
+            }
+
+        mock_sync_store = MagicMock()
+        mock_sync_store.get_next_batch = AsyncMock(return_value=None)
+        mock_sync_store.put_next_batch = AsyncMock()
+
+        fake_client = MagicMock()
+        fake_client.sync = AsyncMock(side_effect=_sync_once)
+        fake_client.join_room = AsyncMock()
+        fake_client.sync_store = mock_sync_store
+        fake_client.handle_sync = MagicMock(return_value=[])
+        adapter._client = fake_client
+
+        with patch.object(adapter, "_refresh_dm_cache", AsyncMock()):
+            await adapter._sync_loop()
+
+        fake_client.join_room.assert_awaited_once()
+        assert "!joined:example.org" in adapter._joined_rooms
+        assert "!invited:example.org" in adapter._joined_rooms
+
 
 class TestMatrixUploadAndSend:
     @pytest.mark.asyncio
@@ -1862,6 +1897,81 @@ class TestMatrixReadReceipts:
         assert result is False
 
 
+# ---------------------------------------------------------------------------
+# Media normalization
+# ---------------------------------------------------------------------------
+
+class TestMatrixImageOnlyMediaNormalization:
+    def setup_method(self):
+        self.adapter = _make_adapter()
+        self.adapter._client = MagicMock()
+        self.adapter._client.download_media = AsyncMock(return_value=None)
+        self.adapter._is_dm_room = AsyncMock(return_value=True)
+        self.adapter._get_display_name = AsyncMock(return_value="Alice")
+        self.adapter._background_read_receipt = MagicMock()
+        self.adapter._mxc_to_http = (
+            lambda url: "https://matrix.example.org/_matrix/media/v3/download/example/30.png"
+        )
+
+    @pytest.mark.asyncio
+    async def test_image_only_filename_body_is_not_forwarded_as_text(self):
+        captured_event = None
+
+        async def capture(msg_event):
+            nonlocal captured_event
+            captured_event = msg_event
+
+        self.adapter.handle_message = capture
+
+        await self.adapter._handle_media_message(
+            room_id="!room:example.org",
+            sender="@alice:example.org",
+            event_id="$image1",
+            event_ts=0.0,
+            source_content={
+                "msgtype": "m.image",
+                "body": "30.png",
+                "url": "mxc://example/30.png",
+                "info": {"mimetype": "image/png"},
+            },
+            relates_to={},
+            msgtype="m.image",
+        )
+
+        assert captured_event is not None
+        assert captured_event.text == ""
+        assert captured_event.media_urls == [
+            "https://matrix.example.org/_matrix/media/v3/download/example/30.png"
+        ]
+        assert captured_event.message_type == MessageType.PHOTO
+
+    @pytest.mark.asyncio
+    async def test_image_caption_text_is_preserved(self):
+        captured_event = None
+
+        async def capture(msg_event):
+            nonlocal captured_event
+            captured_event = msg_event
+
+        self.adapter.handle_message = capture
+
+        await self.adapter._handle_media_message(
+            room_id="!room:example.org",
+            sender="@alice:example.org",
+            event_id="$image2",
+            event_ts=0.0,
+            source_content={
+                "msgtype": "m.image",
+                "body": "Please describe this chart",
+                "url": "mxc://example/30.png",
+                "info": {"mimetype": "image/png"},
+            },
+            relates_to={},
+            msgtype="m.image",
+        )
+
+        assert captured_event is not None
+        assert captured_event.text == "Please describe this chart"
 # ---------------------------------------------------------------------------
 # Message redaction
 # ---------------------------------------------------------------------------
@@ -2099,3 +2209,139 @@ class TestMatrixOnRoomMessageFilter:
         ev = self._mk_event(sender="@alice:example.org", body="hello bot")
         await self.adapter._on_room_message(ev)
         self.adapter._handle_text_message.assert_awaited_once()
+# ---------------------------------------------------------------------------
+# DM auto-thread
+# ---------------------------------------------------------------------------
+
+class TestMatrixDmAutoThread:
+    def setup_method(self):
+        self.adapter = _make_adapter()
+        self.adapter._is_dm_room = AsyncMock(return_value=True)
+        self.adapter._get_display_name = AsyncMock(return_value="Alice")
+        self.adapter._background_read_receipt = MagicMock()
+        # Disable require_mention so DMs pass gating
+        self.adapter._require_mention = False
+
+    @pytest.mark.asyncio
+    async def test_dm_auto_thread_enabled_creates_thread(self):
+        """When dm_auto_thread is True, DM messages get auto-threaded."""
+        self.adapter._dm_auto_thread = True
+
+        ctx = await self.adapter._resolve_message_context(
+            room_id="!dm:ex",
+            sender="@alice:ex",
+            event_id="$ev1",
+            body="hello",
+            source_content={"body": "hello"},
+            relates_to={},
+        )
+
+        assert ctx is not None
+        _body, _is_dm, _chat_type, thread_id, _display, _source = ctx
+        assert thread_id == "$ev1"
+
+    @pytest.mark.asyncio
+    async def test_dm_auto_thread_disabled_no_thread(self):
+        """When dm_auto_thread is False (default), DMs have no auto-thread."""
+        self.adapter._dm_auto_thread = False
+
+        ctx = await self.adapter._resolve_message_context(
+            room_id="!dm:ex",
+            sender="@alice:ex",
+            event_id="$ev2",
+            body="hello",
+            source_content={"body": "hello"},
+            relates_to={},
+        )
+
+        assert ctx is not None
+        _body, _is_dm, _chat_type, thread_id, _display, _source = ctx
+        assert thread_id is None
+
+
+
+# ---------------------------------------------------------------------------
+# Proxy configuration
+# ---------------------------------------------------------------------------
+
+class TestMatrixProxyConfig:
+    """Verify that MatrixAdapter resolves and propagates proxy settings."""
+
+    def _make_adapter(self, monkeypatch, proxy_env=None):
+        monkeypatch.setenv("MATRIX_ACCESS_TOKEN", "syt_test")
+        monkeypatch.setenv("MATRIX_HOMESERVER", "https://matrix.example.org")
+        # Clear generic proxy vars so they don't leak from the host
+        for key in ("HTTPS_PROXY", "HTTP_PROXY", "ALL_PROXY",
+                    "https_proxy", "http_proxy", "all_proxy", "MATRIX_PROXY"):
+            monkeypatch.delenv(key, raising=False)
+        if proxy_env:
+            for k, v in proxy_env.items():
+                monkeypatch.setenv(k, v)
+        with patch.dict("sys.modules", _make_fake_mautrix()):
+            from gateway.platforms.matrix import MatrixAdapter
+            cfg = PlatformConfig(enabled=True, token="syt_test",
+                                 extra={"homeserver": "https://matrix.example.org",
+                                        "user_id": "@bot:example.org"})
+            return MatrixAdapter(cfg)
+
+    def test_no_proxy_by_default(self, monkeypatch):
+        adapter = self._make_adapter(monkeypatch)
+        assert adapter._proxy_url is None
+
+    def test_matrix_proxy_env_var(self, monkeypatch):
+        adapter = self._make_adapter(monkeypatch,
+                                     proxy_env={"MATRIX_PROXY": "socks5://proxy:1080"})
+        assert adapter._proxy_url == "socks5://proxy:1080"
+
+    def test_generic_proxy_fallback(self, monkeypatch):
+        adapter = self._make_adapter(monkeypatch,
+                                     proxy_env={"HTTPS_PROXY": "http://corp:8080"})
+        assert adapter._proxy_url == "http://corp:8080"
+
+    def test_matrix_proxy_takes_priority(self, monkeypatch):
+        adapter = self._make_adapter(monkeypatch,
+                                     proxy_env={"MATRIX_PROXY": "socks5://special:1080",
+                                                "HTTPS_PROXY": "http://generic:8080"})
+        assert adapter._proxy_url == "socks5://special:1080"
+
+
+class TestCreateMatrixSession:
+    """Verify _create_matrix_session applies proxy at the session level."""
+
+    @pytest.mark.asyncio
+    async def test_no_proxy_returns_trust_env_session(self):
+        with patch.dict("sys.modules", _make_fake_mautrix()):
+            from gateway.platforms.matrix import _create_matrix_session
+            session = _create_matrix_session(None)
+            try:
+                assert session.trust_env is True
+            finally:
+                await session.close()
+
+    @pytest.mark.asyncio
+    async def test_http_proxy_sets_default_proxy(self):
+        with patch.dict("sys.modules", _make_fake_mautrix()):
+            from gateway.platforms.matrix import _create_matrix_session
+            session = _create_matrix_session("http://proxy:8080")
+            try:
+                assert str(session._default_proxy) == "http://proxy:8080"
+            finally:
+                await session.close()
+
+    @pytest.mark.asyncio
+    async def test_socks_proxy_uses_connector(self):
+        fake_connector = MagicMock()
+        with patch.dict("sys.modules", _make_fake_mautrix()):
+            with patch.dict("sys.modules", {
+                "aiohttp_socks": MagicMock(
+                    ProxyConnector=MagicMock(
+                        from_url=MagicMock(return_value=fake_connector)
+                    )
+                ),
+            }):
+                from gateway.platforms.matrix import _create_matrix_session
+                session = _create_matrix_session("socks5://proxy:1080")
+                try:
+                    assert session.connector is fake_connector
+                finally:
+                    await session.close()

tests/gateway/test_matrix_exec_approval.py

@@ -0,0 +1,60 @@
+import types
+
+import pytest
+from unittest.mock import AsyncMock, patch
+
+from gateway.config import PlatformConfig
+
+
+class TestMatrixExecApprovalReactions:
+    @pytest.mark.asyncio
+    async def test_send_exec_approval_registers_prompt_and_seeds_reactions(self, monkeypatch):
+        monkeypatch.setenv("MATRIX_ALLOWED_USERS", "@liizfq:liizfq.top")
+        from gateway.platforms.matrix import MatrixAdapter
+
+        adapter = MatrixAdapter(PlatformConfig(enabled=True, token="tok", extra={"homeserver": "https://matrix.example.org"}))
+        adapter._client = types.SimpleNamespace()
+        adapter.send = AsyncMock(return_value=types.SimpleNamespace(success=True, message_id="$evt1"))
+        adapter._send_reaction = AsyncMock(return_value="$r")
+
+        result = await adapter.send_exec_approval(
+            chat_id="!room:example.org",
+            command="rm -rf /tmp/test",
+            session_key="sess-1",
+            description="dangerous",
+        )
+
+        assert result.success is True
+        assert adapter._approval_prompt_by_session["sess-1"] == "$evt1"
+        assert adapter._approval_prompts_by_event["$evt1"].session_key == "sess-1"
+        assert adapter._send_reaction.await_count == 2
+        emojis = [call.args[2] for call in adapter._send_reaction.await_args_list]
+        assert emojis == ["✅", "❎"]
+
+    @pytest.mark.asyncio
+    async def test_reaction_resolves_pending_approval(self, monkeypatch):
+        monkeypatch.setenv("MATRIX_ALLOWED_USERS", "@liizfq:liizfq.top")
+        from gateway.platforms.matrix import MatrixAdapter, _MatrixApprovalPrompt
+
+        adapter = MatrixAdapter(PlatformConfig(enabled=True, token="tok", extra={"homeserver": "https://matrix.example.org"}))
+        # Resolve user_id so _is_self_sender doesn't defensively drop all traffic (#15763).
+        adapter._user_id = "@bot:example.org"
+        adapter._approval_prompts_by_event["$target"] = _MatrixApprovalPrompt(
+            session_key="sess-1", chat_id="!room:example.org", message_id="$target"
+        )
+        adapter._approval_prompt_by_session["sess-1"] = "$target"
+
+        content = {"m.relates_to": {"event_id": "$target", "key": "✅"}}
+        event = types.SimpleNamespace(
+            sender="@liizfq:liizfq.top",
+            event_id="$react1",
+            room_id="!room:example.org",
+            content=content,
+        )
+
+        with patch("tools.approval.resolve_gateway_approval", return_value=1) as mock_resolve:
+            await adapter._on_reaction(event)
+
+        mock_resolve.assert_called_once_with("sess-1", "once")
+        assert "$target" not in adapter._approval_prompts_by_event
+        assert "sess-1" not in adapter._approval_prompt_by_session

tests/gateway/test_matrix_mention.py

@@ -159,7 +159,7 @@ class TestStripMention:
         assert result == "help me"
 
     def test_localpart_preserved(self):
-        """Localpart-only text is no longer stripped — avoids false positives in paths."""
+        """Bare localpart (no @) is preserved — avoids false positives in paths."""
         result = self.adapter._strip_mention("hermes help me")
         assert result == "hermes help me"
 
@@ -168,11 +168,98 @@ class TestStripMention:
         result = self.adapter._strip_mention("read /home/hermes/config.yaml")
         assert result == "read /home/hermes/config.yaml"
 
+    def test_strip_localpart_when_explicit_at_mention(self):
+        result = self.adapter._strip_mention("@hermes help me")
+        assert result == "help me"
+
+    def test_does_not_strip_bare_localpart_word(self):
+        # Regression: plain words like "Hermes Agent" should not be mutated.
+        result = self.adapter._strip_mention("Hermes Agent")
+        assert result == "Hermes Agent"
+
     def test_strip_returns_empty_for_mention_only(self):
         result = self.adapter._strip_mention("@hermes:example.org")
         assert result == ""
 
 
+# ---------------------------------------------------------------------------
+# Outbound mention payloads
+# ---------------------------------------------------------------------------
+
+
+class TestOutboundMentions:
+    def setup_method(self):
+        self.adapter = _make_adapter()
+        self.mock_client = MagicMock()
+        self.mock_client.send_message_event = AsyncMock(return_value="$evt1")
+        self.adapter._client = self.mock_client
+
+    @staticmethod
+    def _sent_content(mock_client):
+        call_args = mock_client.send_message_event.call_args
+        return call_args.args[2] if len(call_args.args) > 2 else call_args.kwargs["content"]
+
+    @pytest.mark.asyncio
+    async def test_send_adds_matrix_mentions_and_formatted_body(self):
+        result = await self.adapter.send(
+            "!room1:example.org",
+            "Hello @alice:example.org, please check this.",
+        )
+
+        assert result.success is True
+        content = self._sent_content(self.mock_client)
+        assert content["m.mentions"] == {"user_ids": ["@alice:example.org"]}
+        assert content["formatted_body"] == (
+            'Hello <a href="https://matrix.to/#/@alice:example.org">'
+            "@alice:example.org</a>, please check this."
+        )
+
+    @pytest.mark.asyncio
+    async def test_send_dedupes_mentions_and_ignores_code_spans(self):
+        await self.adapter.send(
+            "!room1:example.org",
+            "Ping @alice:example.org and @alice:example.org, not `@code:example.org`.",
+        )
+
+        content = self._sent_content(self.mock_client)
+        assert content["m.mentions"] == {"user_ids": ["@alice:example.org"]}
+        assert "@code:example.org</a>" not in content["formatted_body"]
+
+    @pytest.mark.asyncio
+    async def test_edit_message_preserves_mentions(self):
+        result = await self.adapter.edit_message(
+            "!room1:example.org",
+            "$original",
+            "Updated for @alice:example.org",
+        )
+
+        assert result.success is True
+        content = self._sent_content(self.mock_client)
+        assert content["m.mentions"] == {"user_ids": ["@alice:example.org"]}
+        assert content["m.new_content"]["m.mentions"] == {"user_ids": ["@alice:example.org"]}
+        assert content["m.new_content"]["formatted_body"] == (
+            'Updated for <a href="https://matrix.to/#/@alice:example.org">'
+            "@alice:example.org</a>"
+        )
+        assert content["formatted_body"] == (
+            '* Updated for <a href="https://matrix.to/#/@alice:example.org">'
+            "@alice:example.org</a>"
+        )
+
+    @pytest.mark.asyncio
+    async def test_send_simple_notice_adds_mentions(self):
+        result = await self.adapter._send_simple_message(
+            "!room1:example.org",
+            "Heads up @alice:example.org",
+            msgtype="m.notice",
+        )
+
+        assert result.success is True
+        content = self._sent_content(self.mock_client)
+        assert content["msgtype"] == "m.notice"
+        assert content["m.mentions"] == {"user_ids": ["@alice:example.org"]}
+
+
 # ---------------------------------------------------------------------------
 # Require-mention gating in _on_room_message
 # ---------------------------------------------------------------------------

tests/gateway/test_platform_base.py

@@ -3,6 +3,8 @@
 import os
 from unittest.mock import patch
 
+import pytest
+
 from gateway.platforms.base import (
     BasePlatformAdapter,
     GATEWAY_SECRET_CAPTURE_UNSUPPORTED_MESSAGE,
@@ -582,3 +584,47 @@ class TestTruncateMessageUtf16:
                 f"Chunk {i} has unbalanced fences ({fence_count})"
             )
 
+
+class TestProxyKwargsForAiohttp:
+    """Verify proxy_kwargs_for_aiohttp routes all schemes through ProxyConnector."""
+
+    def test_none_returns_empty(self):
+        from gateway.platforms.base import proxy_kwargs_for_aiohttp
+
+        sess_kw, req_kw = proxy_kwargs_for_aiohttp(None)
+        assert sess_kw == {}
+        assert req_kw == {}
+
+    def test_http_proxy_uses_connector_when_aiohttp_socks_available(self):
+        pytest.importorskip("aiohttp_socks")
+        from unittest.mock import MagicMock
+        from gateway.platforms.base import proxy_kwargs_for_aiohttp
+
+        sentinel = MagicMock(name="ProxyConnector")
+        with patch("aiohttp_socks.ProxyConnector.from_url", return_value=sentinel):
+            sess_kw, req_kw = proxy_kwargs_for_aiohttp("http://proxy:8080")
+        assert sess_kw.get("connector") is sentinel, (
+            "HTTP proxy must use ProxyConnector so libraries that don't "
+            "forward per-request proxy= kwargs still route through the proxy"
+        )
+        assert req_kw == {}
+
+    def test_socks_proxy_uses_connector(self):
+        pytest.importorskip("aiohttp_socks")
+        from unittest.mock import MagicMock
+        from gateway.platforms.base import proxy_kwargs_for_aiohttp
+
+        sentinel = MagicMock(name="ProxyConnector")
+        with patch("aiohttp_socks.ProxyConnector.from_url", return_value=sentinel):
+            sess_kw, req_kw = proxy_kwargs_for_aiohttp("socks5://proxy:1080")
+        assert sess_kw.get("connector") is sentinel
+        assert req_kw == {}
+
+    def test_http_proxy_falls_back_without_aiohttp_socks(self):
+        from gateway.platforms.base import proxy_kwargs_for_aiohttp
+
+        with patch.dict("sys.modules", {"aiohttp_socks": None}):
+            sess_kw, req_kw = proxy_kwargs_for_aiohttp("http://proxy:8080")
+            assert sess_kw == {}
+            assert req_kw == {"proxy": "http://proxy:8080"}
+

tests/hermes_cli/test_gmi_provider.py

@@ -269,9 +269,9 @@ class TestGmiModelMetadata:
 
 class TestGmiAuxiliary:
     def test_aux_default_model(self):
-        from agent.auxiliary_client import _get_aux_model_for_provider
+        from agent.auxiliary_client import _API_KEY_PROVIDER_AUX_MODELS
 
-        assert _get_aux_model_for_provider("gmi") == "google/gemini-3.1-flash-lite-preview"
+        assert _API_KEY_PROVIDER_AUX_MODELS["gmi"] == "google/gemini-3.1-flash-lite-preview"
 
     def test_resolve_provider_client_uses_gmi_aux_default(self, monkeypatch):
         monkeypatch.setenv("GMI_API_KEY", "gmi-test-key")

tests/hermes_cli/test_optional_plugins.py

@@ -0,0 +1,168 @@
+"""Tests for optional-plugins (official) install path in plugins_cmd."""
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _make_official_plugin_dir(tmp_path: Path, category: str, name: str) -> Path:
+    """Create a minimal optional-plugin directory structure."""
+    plugin_dir = tmp_path / "optional-plugins" / category / name
+    plugin_dir.mkdir(parents=True)
+    (plugin_dir / "plugin.yaml").write_text(
+        f"name: {name}\nversion: 1.0.0\ndescription: Test plugin\n"
+    )
+    (plugin_dir / "__init__.py").write_text("def register(ctx): pass\n")
+    return plugin_dir
+
+
+# ---------------------------------------------------------------------------
+# _resolve_official_plugin
+# ---------------------------------------------------------------------------
+
+class TestResolveOfficialPlugin:
+    def test_returns_none_for_git_url(self, tmp_path):
+        from hermes_cli.plugins_cmd import _resolve_official_plugin
+        with patch("hermes_cli.plugins_cmd._optional_plugins_dir", return_value=tmp_path / "optional-plugins"):
+            result = _resolve_official_plugin("https://github.com/owner/repo.git")
+        assert result is None
+
+    def test_returns_none_for_owner_repo(self, tmp_path):
+        from hermes_cli.plugins_cmd import _resolve_official_plugin
+        with patch("hermes_cli.plugins_cmd._optional_plugins_dir", return_value=tmp_path / "optional-plugins"):
+            result = _resolve_official_plugin("owner/repo")
+        assert result is None
+
+    def test_returns_none_for_missing_plugin(self, tmp_path):
+        from hermes_cli.plugins_cmd import _resolve_official_plugin
+        (tmp_path / "optional-plugins").mkdir()
+        with patch("hermes_cli.plugins_cmd._optional_plugins_dir", return_value=tmp_path / "optional-plugins"):
+            result = _resolve_official_plugin("official/observability/nonexistent")
+        assert result is None
+
+    def test_returns_path_for_existing_plugin(self, tmp_path):
+        from hermes_cli.plugins_cmd import _resolve_official_plugin
+        plugin_dir = _make_official_plugin_dir(tmp_path, "observability", "langfuse")
+        with patch("hermes_cli.plugins_cmd._optional_plugins_dir", return_value=tmp_path / "optional-plugins"):
+            result = _resolve_official_plugin("official/observability/langfuse")
+        assert result == plugin_dir
+
+    def test_accepts_without_official_prefix(self, tmp_path):
+        from hermes_cli.plugins_cmd import _resolve_official_plugin
+        plugin_dir = _make_official_plugin_dir(tmp_path, "observability", "langfuse")
+        with patch("hermes_cli.plugins_cmd._optional_plugins_dir", return_value=tmp_path / "optional-plugins"):
+            result = _resolve_official_plugin("observability/langfuse")
+        assert result == plugin_dir
+
+    def test_traversal_blocked(self, tmp_path):
+        from hermes_cli.plugins_cmd import _resolve_official_plugin
+        (tmp_path / "optional-plugins").mkdir()
+        with patch("hermes_cli.plugins_cmd._optional_plugins_dir", return_value=tmp_path / "optional-plugins"):
+            result = _resolve_official_plugin("official/../../etc/passwd")
+        assert result is None
+
+
+# ---------------------------------------------------------------------------
+# _list_official_plugins
+# ---------------------------------------------------------------------------
+
+class TestListOfficialPlugins:
+    def test_empty_when_no_optional_plugins_dir(self, tmp_path):
+        from hermes_cli.plugins_cmd import _list_official_plugins
+        with patch("hermes_cli.plugins_cmd._optional_plugins_dir", return_value=tmp_path / "nonexistent"):
+            result = _list_official_plugins()
+        assert result == []
+
+    def test_lists_plugins_with_descriptions(self, tmp_path):
+        from hermes_cli.plugins_cmd import _list_official_plugins
+        _make_official_plugin_dir(tmp_path, "observability", "langfuse")
+        _make_official_plugin_dir(tmp_path, "observability", "other-plugin")
+        with patch("hermes_cli.plugins_cmd._optional_plugins_dir", return_value=tmp_path / "optional-plugins"):
+            result = _list_official_plugins()
+        identifiers = [r[0] for r in result]
+        assert "official/observability/langfuse" in identifiers
+        assert "official/observability/other-plugin" in identifiers
+
+    def test_descriptions_parsed_from_yaml(self, tmp_path):
+        from hermes_cli.plugins_cmd import _list_official_plugins
+        plugin_dir = _make_official_plugin_dir(tmp_path, "observability", "langfuse")
+        with patch("hermes_cli.plugins_cmd._optional_plugins_dir", return_value=tmp_path / "optional-plugins"):
+            result = _list_official_plugins()
+        assert any(desc == "Test plugin" for _, desc in result)
+
+
+# ---------------------------------------------------------------------------
+# cmd_install — official path
+# ---------------------------------------------------------------------------
+
+class TestCmdInstallOfficial:
+    def test_install_official_plugin_copies_files(self, tmp_path, monkeypatch):
+        from hermes_cli.plugins_cmd import cmd_install
+        plugin_dir = _make_official_plugin_dir(tmp_path, "observability", "langfuse")
+        user_plugins = tmp_path / "user-plugins"
+        user_plugins.mkdir()
+
+        monkeypatch.setattr("hermes_cli.plugins_cmd._optional_plugins_dir",
+                            lambda: tmp_path / "optional-plugins")
+        monkeypatch.setattr("hermes_cli.plugins_cmd._plugins_dir",
+                            lambda: user_plugins)
+        # Non-interactive: don't prompt
+        monkeypatch.setattr("sys.stdin.isatty", lambda: False)
+
+        cmd_install("official/observability/langfuse", enable=False)
+
+        installed = user_plugins / "langfuse"
+        assert installed.is_dir()
+        assert (installed / "plugin.yaml").exists()
+        assert (installed / "__init__.py").exists()
+
+    def test_install_official_plugin_respects_force(self, tmp_path, monkeypatch):
+        from hermes_cli.plugins_cmd import cmd_install
+        plugin_dir = _make_official_plugin_dir(tmp_path, "observability", "langfuse")
+        user_plugins = tmp_path / "user-plugins"
+        user_plugins.mkdir()
+        # Pre-create to simulate already-installed
+        already = user_plugins / "langfuse"
+        already.mkdir()
+        (already / "old.txt").write_text("old")
+
+        monkeypatch.setattr("hermes_cli.plugins_cmd._optional_plugins_dir",
+                            lambda: tmp_path / "optional-plugins")
+        monkeypatch.setattr("hermes_cli.plugins_cmd._plugins_dir",
+                            lambda: user_plugins)
+        monkeypatch.setattr("sys.stdin.isatty", lambda: False)
+
+        cmd_install("official/observability/langfuse", force=True, enable=False)
+
+        # Old file should be gone, new files present
+        assert not (already / "old.txt").exists()
+        assert (already / "plugin.yaml").exists()
+
+    def test_install_official_plugin_exits_without_force_when_exists(self, tmp_path, monkeypatch):
+        from hermes_cli.plugins_cmd import cmd_install
+        _make_official_plugin_dir(tmp_path, "observability", "langfuse")
+        user_plugins = tmp_path / "user-plugins"
+        user_plugins.mkdir()
+        (user_plugins / "langfuse").mkdir()
+
+        monkeypatch.setattr("hermes_cli.plugins_cmd._optional_plugins_dir",
+                            lambda: tmp_path / "optional-plugins")
+        monkeypatch.setattr("hermes_cli.plugins_cmd._plugins_dir",
+                            lambda: user_plugins)
+
+        with pytest.raises(SystemExit):
+            cmd_install("official/observability/langfuse", enable=False)
+
+    def test_git_url_not_mistaken_for_official(self, tmp_path, monkeypatch):
+        """A git URL must not trigger the official install path."""
+        from hermes_cli.plugins_cmd import _resolve_official_plugin
+        with patch("hermes_cli.plugins_cmd._optional_plugins_dir",
+                   return_value=tmp_path / "optional-plugins"):
+            assert _resolve_official_plugin("https://github.com/owner/repo") is None
+            assert _resolve_official_plugin("owner/repo") is None

tests/hermes_cli/test_redact_config_bridge.py

@@ -72,8 +72,12 @@ def test_redact_secrets_false_in_config_yaml_is_honored(tmp_path):
     assert "ENV_VAR=false" in result.stdout
 
 
-def test_redact_secrets_default_true_when_unset(tmp_path):
-    """Without the config key, redaction stays on by default."""
+def test_redact_secrets_default_false_when_unset(tmp_path):
+    """Without the config key, redaction stays OFF by default.
+
+    Secret redaction is opt-in — users who want it must set
+    `security.redact_secrets: true` explicitly (or HERMES_REDACT_SECRETS=true).
+    """
     hermes_home = tmp_path / ".hermes"
     hermes_home.mkdir()
     (hermes_home / "config.yaml").write_text("{}\n")  # empty config
@@ -103,7 +107,53 @@ def test_redact_secrets_default_true_when_unset(tmp_path):
         timeout=30,
     )
     assert result.returncode == 0, f"probe failed: {result.stderr}"
-    assert "REDACT_ENABLED=True" in result.stdout
+    assert "REDACT_ENABLED=False" in result.stdout
+
+
+def test_redact_secrets_true_in_config_yaml_is_honored(tmp_path):
+    """Setting `security.redact_secrets: true` in config.yaml must enable
+    redaction — even though it's set in YAML, not as an env var."""
+    hermes_home = tmp_path / ".hermes"
+    hermes_home.mkdir()
+    (hermes_home / "config.yaml").write_text(
+        textwrap.dedent(
+            """\
+            security:
+              redact_secrets: true
+            """
+        )
+    )
+    (hermes_home / ".env").write_text("")
+
+    probe = textwrap.dedent(
+        """\
+        import sys, os
+        os.environ.pop("HERMES_REDACT_SECRETS", None)
+        sys.path.insert(0, %r)
+        import hermes_cli.main
+        import agent.redact
+        print(f"REDACT_ENABLED={agent.redact._REDACT_ENABLED}")
+        print(f"ENV_VAR={os.environ.get('HERMES_REDACT_SECRETS', '<unset>')}")
+        """
+    ) % str(REPO_ROOT)
+
+    env = dict(os.environ)
+    env["HERMES_HOME"] = str(hermes_home)
+    env.pop("HERMES_REDACT_SECRETS", None)
+
+    result = subprocess.run(
+        [sys.executable, "-c", probe],
+        env=env,
+        capture_output=True,
+        text=True,
+        cwd=str(REPO_ROOT),
+        timeout=30,
+    )
+    assert result.returncode == 0, f"probe failed: {result.stderr}"
+    assert "REDACT_ENABLED=True" in result.stdout, (
+        f"Config toggle not honored.\nstdout: {result.stdout}\nstderr: {result.stderr}"
+    )
+    assert "ENV_VAR=true" in result.stdout
 
 
 def test_dotenv_redact_secrets_beats_config_yaml(tmp_path):

tests/providers/test_e2e_wiring.py

@@ -1,118 +0,0 @@
-"""E2E tests: verify _build_kwargs_from_profile produces correct output.
-
-These tests call _build_kwargs_from_profile on the transport directly,
-without importing run_agent (which would cause xdist worker contamination).
-"""
-
-import pytest
-from agent.transports.chat_completions import ChatCompletionsTransport
-from providers import get_provider_profile
-
-
-@pytest.fixture
-def transport():
-    return ChatCompletionsTransport()
-
-
-def _msgs():
-    return [{"role": "user", "content": "hi"}]
-
-
-class TestNvidiaProfileWiring:
-    def test_nvidia_gets_default_max_tokens(self, transport):
-        profile = get_provider_profile("nvidia")
-        kwargs = transport.build_kwargs(
-            model="nvidia/llama-3.1-nemotron-70b-instruct",
-            messages=_msgs(),
-            tools=None,
-            provider_profile=profile,
-            max_tokens=None,
-            max_tokens_param_fn=lambda x: {"max_tokens": x} if x else {},
-            timeout=300,
-            reasoning_config=None,
-            request_overrides=None,
-            session_id="test",
-            ollama_num_ctx=None,
-        )
-        # NVIDIA profile sets default_max_tokens=16384
-        assert kwargs.get("max_tokens") == 16384
-
-    def test_nvidia_nim_alias(self, transport):
-        profile = get_provider_profile("nvidia-nim")
-        assert profile is not None
-        assert profile.name == "nvidia"
-        assert profile.default_max_tokens == 16384
-
-    def test_nvidia_model_passed(self, transport):
-        profile = get_provider_profile("nvidia")
-        kwargs = transport.build_kwargs(
-            model="nvidia/test-model",
-            messages=_msgs(),
-            tools=None,
-            provider_profile=profile,
-            max_tokens=None,
-            max_tokens_param_fn=lambda x: {"max_tokens": x} if x else {},
-            timeout=300,
-            reasoning_config=None,
-            request_overrides=None,
-            session_id="test",
-            ollama_num_ctx=None,
-        )
-        assert kwargs["model"] == "nvidia/test-model"
-
-    def test_nvidia_messages_passed(self, transport):
-        profile = get_provider_profile("nvidia")
-        msgs = _msgs()
-        kwargs = transport.build_kwargs(
-            model="nvidia/test",
-            messages=msgs,
-            tools=None,
-            provider_profile=profile,
-            max_tokens=None,
-            max_tokens_param_fn=lambda x: {"max_tokens": x} if x else {},
-            timeout=300,
-            reasoning_config=None,
-            request_overrides=None,
-            session_id="test",
-            ollama_num_ctx=None,
-        )
-        assert kwargs["messages"] == msgs
-
-
-class TestDeepSeekProfileWiring:
-    def test_deepseek_no_forced_max_tokens(self, transport):
-        profile = get_provider_profile("deepseek")
-        kwargs = transport.build_kwargs(
-            model="deepseek-chat",
-            messages=_msgs(),
-            tools=None,
-            provider_profile=profile,
-            max_tokens=None,
-            max_tokens_param_fn=lambda x: {"max_tokens": x} if x else {},
-            timeout=300,
-            reasoning_config=None,
-            request_overrides=None,
-            session_id="test",
-            ollama_num_ctx=None,
-        )
-        # DeepSeek has no default_max_tokens
-        assert kwargs["model"] == "deepseek-chat"
-        assert kwargs.get("max_tokens") is None or "max_tokens" not in kwargs
-
-    def test_deepseek_messages_passed(self, transport):
-        profile = get_provider_profile("deepseek")
-        msgs = _msgs()
-        kwargs = transport.build_kwargs(
-            model="deepseek-chat",
-            messages=msgs,
-            tools=None,
-            provider_profile=profile,
-            max_tokens=None,
-            max_tokens_param_fn=lambda x: {"max_tokens": x} if x else {},
-            timeout=300,
-            reasoning_config=None,
-            request_overrides=None,
-            session_id="test",
-            ollama_num_ctx=None,
-        )
-        assert kwargs["messages"] == msgs

tests/providers/test_profile_wiring.py

@@ -1,290 +0,0 @@
-"""Profile-path parity tests: verify profile path produces identical output to legacy flags.
-
-Each test calls build_kwargs twice — once with legacy flags, once with provider_profile —
-and asserts the output is identical. This catches any behavioral drift between the two paths.
-"""
-
-import pytest
-from agent.transports.chat_completions import ChatCompletionsTransport
-from providers import get_provider_profile
-
-
-@pytest.fixture
-def transport():
-    return ChatCompletionsTransport()
-
-
-def _msgs():
-    return [{"role": "user", "content": "hello"}]
-
-
-def _max_tokens_fn(n):
-    return {"max_completion_tokens": n}
-
-
-class TestNvidiaProfileParity:
-    def test_max_tokens_match(self, transport):
-        """NVIDIA profile sets max_tokens=16384; legacy flag is removed."""
-        profile = transport.build_kwargs(
-            model="nvidia/nemotron", messages=_msgs(), tools=None,
-            provider_profile=get_provider_profile("nvidia"),
-            max_tokens_param_fn=_max_tokens_fn,
-        )
-        assert profile["max_completion_tokens"] == 16384
-
-
-class TestKimiProfileParity:
-    def test_temperature_omitted(self, transport):
-        legacy = transport.build_kwargs(
-            model="kimi-k2", messages=_msgs(), tools=None,
-            provider_profile=get_provider_profile("kimi-coding"), omit_temperature=True,
-        )
-        profile = transport.build_kwargs(
-            model="kimi-k2", messages=_msgs(), tools=None,
-            provider_profile=get_provider_profile("kimi"),
-        )
-        assert "temperature" not in legacy
-        assert "temperature" not in profile
-
-    def test_max_tokens(self, transport):
-        legacy = transport.build_kwargs(
-            model="kimi-k2", messages=_msgs(), tools=None,
-            provider_profile=get_provider_profile("kimi-coding"), max_tokens_param_fn=_max_tokens_fn,
-        )
-        profile = transport.build_kwargs(
-            model="kimi-k2", messages=_msgs(), tools=None,
-            provider_profile=get_provider_profile("kimi"),
-            max_tokens_param_fn=_max_tokens_fn,
-        )
-        assert profile["max_completion_tokens"] == legacy["max_completion_tokens"] == 32000
-
-    def test_thinking_enabled(self, transport):
-        rc = {"enabled": True, "effort": "high"}
-        legacy = transport.build_kwargs(
-            model="kimi-k2", messages=_msgs(), tools=None,
-            provider_profile=get_provider_profile("kimi-coding"), reasoning_config=rc,
-        )
-        profile = transport.build_kwargs(
-            model="kimi-k2", messages=_msgs(), tools=None,
-            provider_profile=get_provider_profile("kimi"),
-            reasoning_config=rc,
-        )
-        assert profile["extra_body"]["thinking"] == legacy["extra_body"]["thinking"]
-        assert profile["reasoning_effort"] == legacy["reasoning_effort"] == "high"
-
-    def test_thinking_disabled(self, transport):
-        rc = {"enabled": False}
-        legacy = transport.build_kwargs(
-            model="kimi-k2", messages=_msgs(), tools=None,
-            provider_profile=get_provider_profile("kimi-coding"), reasoning_config=rc,
-        )
-        profile = transport.build_kwargs(
-            model="kimi-k2", messages=_msgs(), tools=None,
-            provider_profile=get_provider_profile("kimi"),
-            reasoning_config=rc,
-        )
-        assert profile["extra_body"]["thinking"] == legacy["extra_body"]["thinking"]
-        assert profile["extra_body"]["thinking"]["type"] == "disabled"
-        assert "reasoning_effort" not in profile
-        assert "reasoning_effort" not in legacy
-
-    def test_reasoning_effort_default(self, transport):
-        rc = {"enabled": True}
-        legacy = transport.build_kwargs(
-            model="kimi-k2", messages=_msgs(), tools=None,
-            provider_profile=get_provider_profile("kimi-coding"), reasoning_config=rc,
-        )
-        profile = transport.build_kwargs(
-            model="kimi-k2", messages=_msgs(), tools=None,
-            provider_profile=get_provider_profile("kimi"),
-            reasoning_config=rc,
-        )
-        assert profile["reasoning_effort"] == legacy["reasoning_effort"] == "medium"
-
-
-class TestOpenRouterProfileParity:
-    def test_provider_preferences(self, transport):
-        prefs = {"allow": ["anthropic"]}
-        legacy = transport.build_kwargs(
-            model="anthropic/claude-sonnet-4.6", messages=_msgs(), tools=None,
-            provider_profile=get_provider_profile("openrouter"), provider_preferences=prefs,
-        )
-        profile = transport.build_kwargs(
-            model="anthropic/claude-sonnet-4.6", messages=_msgs(), tools=None,
-            provider_profile=get_provider_profile("openrouter"),
-            provider_preferences=prefs,
-        )
-        assert profile["extra_body"]["provider"] == legacy["extra_body"]["provider"]
-
-    def test_reasoning_full_config(self, transport):
-        rc = {"enabled": True, "effort": "high"}
-        legacy = transport.build_kwargs(
-            model="anthropic/claude-sonnet-4.6", messages=_msgs(), tools=None,
-            provider_profile=get_provider_profile("openrouter"), supports_reasoning=True, reasoning_config=rc,
-        )
-        profile = transport.build_kwargs(
-            model="anthropic/claude-sonnet-4.6", messages=_msgs(), tools=None,
-            provider_profile=get_provider_profile("openrouter"),
-            supports_reasoning=True, reasoning_config=rc,
-        )
-        assert profile["extra_body"]["reasoning"] == legacy["extra_body"]["reasoning"]
-
-    def test_default_reasoning(self, transport):
-        legacy = transport.build_kwargs(
-            model="anthropic/claude-sonnet-4.6", messages=_msgs(), tools=None,
-            provider_profile=get_provider_profile("openrouter"), supports_reasoning=True,
-        )
-        profile = transport.build_kwargs(
-            model="anthropic/claude-sonnet-4.6", messages=_msgs(), tools=None,
-            provider_profile=get_provider_profile("openrouter"),
-            supports_reasoning=True,
-        )
-        assert profile["extra_body"]["reasoning"] == legacy["extra_body"]["reasoning"]
-
-
-class TestNousProfileParity:
-    def test_tags(self, transport):
-        legacy = transport.build_kwargs(
-            model="hermes-3", messages=_msgs(), tools=None, provider_profile=get_provider_profile("nous"),
-        )
-        profile = transport.build_kwargs(
-            model="hermes-3", messages=_msgs(), tools=None,
-            provider_profile=get_provider_profile("nous"),
-        )
-        assert profile["extra_body"]["tags"] == legacy["extra_body"]["tags"]
-
-    def test_reasoning_omitted_when_disabled(self, transport):
-        rc = {"enabled": False}
-        legacy = transport.build_kwargs(
-            model="hermes-3", messages=_msgs(), tools=None,
-            provider_profile=get_provider_profile("nous"), supports_reasoning=True, reasoning_config=rc,
-        )
-        profile = transport.build_kwargs(
-            model="hermes-3", messages=_msgs(), tools=None,
-            provider_profile=get_provider_profile("nous"),
-            supports_reasoning=True, reasoning_config=rc,
-        )
-        assert "reasoning" not in legacy.get("extra_body", {})
-        assert "reasoning" not in profile.get("extra_body", {})
-
-
-class TestQwenProfileParity:
-    def test_max_tokens(self, transport):
-        legacy = transport.build_kwargs(
-            model="qwen3.5", messages=_msgs(), tools=None,
-            provider_profile=get_provider_profile("qwen-oauth"), max_tokens_param_fn=_max_tokens_fn,
-        )
-        profile = transport.build_kwargs(
-            model="qwen3.5", messages=_msgs(), tools=None,
-            provider_profile=get_provider_profile("qwen"),
-            max_tokens_param_fn=_max_tokens_fn,
-        )
-        assert profile["max_completion_tokens"] == legacy["max_completion_tokens"] == 65536
-
-    def test_vl_high_resolution(self, transport):
-        legacy = transport.build_kwargs(
-            model="qwen3.5", messages=_msgs(), tools=None, provider_profile=get_provider_profile("qwen-oauth"),
-        )
-        profile = transport.build_kwargs(
-            model="qwen3.5", messages=_msgs(), tools=None,
-            provider_profile=get_provider_profile("qwen"),
-        )
-        assert profile["extra_body"]["vl_high_resolution_images"] == legacy["extra_body"]["vl_high_resolution_images"]
-
-    def test_metadata_top_level(self, transport):
-        meta = {"sessionId": "s123", "promptId": "p456"}
-        legacy = transport.build_kwargs(
-            model="qwen3.5", messages=_msgs(), tools=None,
-            provider_profile=get_provider_profile("qwen-oauth"), qwen_session_metadata=meta,
-        )
-        profile = transport.build_kwargs(
-            model="qwen3.5", messages=_msgs(), tools=None,
-            provider_profile=get_provider_profile("qwen"),
-            qwen_session_metadata=meta,
-        )
-        assert profile["metadata"] == legacy["metadata"] == meta
-        assert "metadata" not in profile.get("extra_body", {})
-
-    def test_message_preprocessing(self, transport):
-        """Qwen profile normalizes string content to list-of-parts."""
-        msgs = [
-            {"role": "system", "content": "You are helpful."},
-            {"role": "user", "content": "hello"},
-        ]
-        profile = transport.build_kwargs(
-            model="qwen3.5", messages=msgs, tools=None,
-            provider_profile=get_provider_profile("qwen"),
-        )
-        out_msgs = profile["messages"]
-        # System message content normalized + cache_control injected
-        assert isinstance(out_msgs[0]["content"], list)
-        assert out_msgs[0]["content"][0]["type"] == "text"
-        assert "cache_control" in out_msgs[0]["content"][-1]
-        # User message content normalized
-        assert isinstance(out_msgs[1]["content"], list)
-        assert out_msgs[1]["content"][0] == {"type": "text", "text": "hello"}
-
-
-class TestDeveloperRoleParity:
-    """Developer role swap must work on BOTH legacy and profile paths."""
-
-    def test_legacy_path_swaps_for_gpt5(self, transport):
-        msgs = [{"role": "system", "content": "Be helpful"}, {"role": "user", "content": "hi"}]
-        kw = transport.build_kwargs(
-            model="gpt-5.4", messages=msgs, tools=None,
-        )
-        assert kw["messages"][0]["role"] == "developer"
-
-    def test_profile_path_swaps_for_gpt5(self, transport):
-        msgs = [{"role": "system", "content": "Be helpful"}, {"role": "user", "content": "hi"}]
-        kw = transport.build_kwargs(
-            model="gpt-5.4", messages=msgs, tools=None,
-            provider_profile=get_provider_profile("openrouter"),
-        )
-        assert kw["messages"][0]["role"] == "developer"
-
-    def test_profile_path_no_swap_for_claude(self, transport):
-        msgs = [{"role": "system", "content": "Be helpful"}, {"role": "user", "content": "hi"}]
-        kw = transport.build_kwargs(
-            model="anthropic/claude-sonnet-4.6", messages=msgs, tools=None,
-            provider_profile=get_provider_profile("openrouter"),
-        )
-        assert kw["messages"][0]["role"] == "system"
-
-
-class TestRequestOverridesParity:
-    """request_overrides with extra_body must merge identically on both paths."""
-
-    def test_extra_body_override_legacy(self, transport):
-        kw = transport.build_kwargs(
-            model="gpt-5.4", messages=_msgs(), tools=None,
-            provider_profile=get_provider_profile("openrouter"),
-            request_overrides={"extra_body": {"custom_key": "custom_val"}},
-        )
-        assert kw["extra_body"]["custom_key"] == "custom_val"
-
-    def test_extra_body_override_profile(self, transport):
-        kw = transport.build_kwargs(
-            model="gpt-5.4", messages=_msgs(), tools=None,
-            provider_profile=get_provider_profile("openrouter"),
-            request_overrides={"extra_body": {"custom_key": "custom_val"}},
-        )
-        assert kw["extra_body"]["custom_key"] == "custom_val"
-
-    def test_extra_body_override_merges_with_provider_body(self, transport):
-        """Override extra_body merges WITH provider extra_body, not replaces."""
-        kw = transport.build_kwargs(
-            model="hermes-3", messages=_msgs(), tools=None,
-            provider_profile=get_provider_profile("nous"),
-            request_overrides={"extra_body": {"custom": True}},
-        )
-        assert kw["extra_body"]["tags"] == ["product=hermes-agent"]  # from profile
-        assert kw["extra_body"]["custom"] is True  # from override
-
-    def test_top_level_override(self, transport):
-        kw = transport.build_kwargs(
-            model="gpt-5.4", messages=_msgs(), tools=None,
-            provider_profile=get_provider_profile("openrouter"),
-            request_overrides={"top_p": 0.9},
-        )
-        assert kw["top_p"] == 0.9

tests/providers/test_provider_profiles.py

@@ -1,203 +0,0 @@
-"""Tests for the provider module registry and profiles."""
-
-import pytest
-from providers import get_provider_profile, _REGISTRY
-from providers.base import ProviderProfile, OMIT_TEMPERATURE
-
-
-class TestRegistry:
-    def test_discovery_populates_registry(self):
-        p = get_provider_profile("nvidia")
-        assert p is not None
-        assert p.name == "nvidia"
-
-    def test_alias_lookup(self):
-        assert get_provider_profile("kimi").name == "kimi-coding"
-        assert get_provider_profile("moonshot").name == "kimi-coding"
-        assert get_provider_profile("kimi-coding-cn").name == "kimi-coding-cn"
-        assert get_provider_profile("or").name == "openrouter"
-        assert get_provider_profile("nous-portal").name == "nous"
-        assert get_provider_profile("qwen").name == "qwen-oauth"
-        assert get_provider_profile("qwen-portal").name == "qwen-oauth"
-
-    def test_unknown_provider_returns_none(self):
-        assert get_provider_profile("nonexistent-provider") is None
-
-    def test_all_providers_have_name(self):
-        get_provider_profile("nvidia")  # trigger discovery
-        for name, profile in _REGISTRY.items():
-            assert profile.name == name
-
-
-class TestNvidiaProfile:
-    def test_max_tokens(self):
-        p = get_provider_profile("nvidia")
-        assert p.default_max_tokens == 16384
-
-    def test_no_special_temperature(self):
-        p = get_provider_profile("nvidia")
-        assert p.fixed_temperature is None
-
-    def test_base_url(self):
-        p = get_provider_profile("nvidia")
-        assert "nvidia.com" in p.base_url
-
-
-class TestKimiProfile:
-    def test_temperature_omit(self):
-        p = get_provider_profile("kimi")
-        assert p.fixed_temperature is OMIT_TEMPERATURE
-
-    def test_max_tokens(self):
-        p = get_provider_profile("kimi")
-        assert p.default_max_tokens == 32000
-
-    def test_cn_separate_profile(self):
-        p = get_provider_profile("kimi-coding-cn")
-        assert p.name == "kimi-coding-cn"
-        assert p.env_vars == ("KIMI_CN_API_KEY",)
-        assert "moonshot.cn" in p.base_url
-
-    def test_cn_not_alias_of_kimi(self):
-        kimi = get_provider_profile("kimi-coding")
-        cn = get_provider_profile("kimi-coding-cn")
-        assert kimi is not cn
-        assert kimi.base_url != cn.base_url
-
-    def test_thinking_enabled(self):
-        p = get_provider_profile("kimi")
-        eb, tl = p.build_api_kwargs_extras(reasoning_config={"enabled": True, "effort": "high"})
-        assert eb["thinking"] == {"type": "enabled"}
-        assert tl["reasoning_effort"] == "high"
-
-    def test_thinking_disabled(self):
-        p = get_provider_profile("kimi")
-        eb, tl = p.build_api_kwargs_extras(reasoning_config={"enabled": False})
-        assert eb["thinking"] == {"type": "disabled"}
-        assert "reasoning_effort" not in tl
-
-    def test_reasoning_effort_default(self):
-        p = get_provider_profile("kimi")
-        eb, tl = p.build_api_kwargs_extras(reasoning_config={"enabled": True})
-        assert tl["reasoning_effort"] == "medium"
-
-    def test_no_config_defaults(self):
-        p = get_provider_profile("kimi")
-        eb, tl = p.build_api_kwargs_extras(reasoning_config=None)
-        assert eb["thinking"] == {"type": "enabled"}
-        assert tl["reasoning_effort"] == "medium"
-
-
-class TestOpenRouterProfile:
-    def test_extra_body_with_prefs(self):
-        p = get_provider_profile("openrouter")
-        body = p.build_extra_body(provider_preferences={"allow": ["anthropic"]})
-        assert body["provider"] == {"allow": ["anthropic"]}
-
-    def test_extra_body_no_prefs(self):
-        p = get_provider_profile("openrouter")
-        body = p.build_extra_body()
-        assert body == {}
-
-    def test_reasoning_full_config(self):
-        p = get_provider_profile("openrouter")
-        eb, _ = p.build_api_kwargs_extras(
-            reasoning_config={"enabled": True, "effort": "high"},
-            supports_reasoning=True,
-        )
-        assert eb["reasoning"] == {"enabled": True, "effort": "high"}
-
-    def test_reasoning_disabled_still_passes(self):
-        """OpenRouter passes disabled reasoning through (unlike Nous)."""
-        p = get_provider_profile("openrouter")
-        eb, _ = p.build_api_kwargs_extras(
-            reasoning_config={"enabled": False},
-            supports_reasoning=True,
-        )
-        assert eb["reasoning"] == {"enabled": False}
-
-    def test_default_reasoning(self):
-        p = get_provider_profile("openrouter")
-        eb, _ = p.build_api_kwargs_extras(supports_reasoning=True)
-        assert eb["reasoning"] == {"enabled": True, "effort": "medium"}
-
-
-class TestNousProfile:
-    def test_tags(self):
-        p = get_provider_profile("nous")
-        body = p.build_extra_body()
-        assert body["tags"] == ["product=hermes-agent"]
-
-    def test_auth_type(self):
-        p = get_provider_profile("nous")
-        assert p.auth_type == "oauth_device_code"
-
-    def test_reasoning_enabled(self):
-        p = get_provider_profile("nous")
-        eb, _ = p.build_api_kwargs_extras(
-            reasoning_config={"enabled": True, "effort": "medium"},
-            supports_reasoning=True,
-        )
-        assert eb["reasoning"] == {"enabled": True, "effort": "medium"}
-
-    def test_reasoning_omitted_when_disabled(self):
-        p = get_provider_profile("nous")
-        eb, _ = p.build_api_kwargs_extras(
-            reasoning_config={"enabled": False},
-            supports_reasoning=True,
-        )
-        assert "reasoning" not in eb
-
-
-class TestQwenProfile:
-    def test_max_tokens(self):
-        p = get_provider_profile("qwen-oauth")
-        assert p.default_max_tokens == 65536
-
-    def test_auth_type(self):
-        p = get_provider_profile("qwen-oauth")
-        assert p.auth_type == "oauth_external"
-
-    def test_extra_body_vl(self):
-        p = get_provider_profile("qwen-oauth")
-        body = p.build_extra_body()
-        assert body["vl_high_resolution_images"] is True
-
-    def test_prepare_messages_normalizes_content(self):
-        p = get_provider_profile("qwen-oauth")
-        msgs = [
-            {"role": "system", "content": "Be helpful"},
-            {"role": "user", "content": "hello"},
-        ]
-        result = p.prepare_messages(msgs)
-        # System message: content normalized to list, cache_control on last part
-        assert isinstance(result[0]["content"], list)
-        assert result[0]["content"][-1].get("cache_control") == {"type": "ephemeral"}
-        assert result[0]["content"][-1]["text"] == "Be helpful"
-        # User message: content normalized to list
-        assert isinstance(result[1]["content"], list)
-        assert result[1]["content"][0]["text"] == "hello"
-
-    def test_metadata_top_level(self):
-        p = get_provider_profile("qwen-oauth")
-        meta = {"sessionId": "s123", "promptId": "p456"}
-        eb, tl = p.build_api_kwargs_extras(qwen_session_metadata=meta)
-        assert tl["metadata"] == meta
-        assert "metadata" not in eb
-
-
-class TestBaseProfile:
-    def test_prepare_messages_passthrough(self):
-        p = ProviderProfile(name="test")
-        msgs = [{"role": "user", "content": "hi"}]
-        assert p.prepare_messages(msgs) is msgs
-
-    def test_build_extra_body_empty(self):
-        p = ProviderProfile(name="test")
-        assert p.build_extra_body() == {}
-
-    def test_build_api_kwargs_extras_empty(self):
-        p = ProviderProfile(name="test")
-        eb, tl = p.build_api_kwargs_extras()
-        assert eb == {}
-        assert tl == {}

tests/providers/test_transport_parity.py

@@ -1,258 +0,0 @@
-"""Parity tests: pin the exact current transport behavior per provider.
-
-These tests document the flag-based contract between run_agent.py and
-ChatCompletionsTransport.build_kwargs(). When the next PR wires profiles
-to replace flags, every assertion here must still pass — any failure is
-a behavioral regression.
-"""
-
-import pytest
-from agent.transports.chat_completions import ChatCompletionsTransport
-from providers import get_provider_profile
-
-
-@pytest.fixture
-def transport():
-    return ChatCompletionsTransport()
-
-
-def _simple_messages():
-    return [{"role": "user", "content": "hello"}]
-
-
-def _max_tokens_fn(n):
-    return {"max_completion_tokens": n}
-
-
-class TestNvidiaParity:
-    """NVIDIA NIM: default max_tokens=16384."""
-
-    def test_default_max_tokens(self, transport):
-        """NVIDIA default max_tokens=16384 comes from profile, not legacy is_nvidia_nim flag."""
-        from providers import get_provider_profile
-
-        profile = get_provider_profile("nvidia")
-        kw = transport.build_kwargs(
-            model="nvidia/llama-3.1-nemotron-70b-instruct",
-            messages=_simple_messages(),
-            tools=None,
-            max_tokens_param_fn=_max_tokens_fn,
-            provider_profile=profile,
-        )
-        assert kw["max_completion_tokens"] == 16384
-
-    def test_user_max_tokens_overrides(self, transport):
-        from providers import get_provider_profile
-
-        profile = get_provider_profile("nvidia")
-        kw = transport.build_kwargs(
-            model="nvidia/llama-3.1-nemotron-70b-instruct",
-            messages=_simple_messages(),
-            tools=None,
-            max_tokens=4096,
-            max_tokens_param_fn=_max_tokens_fn,
-            provider_profile=profile,
-        )
-        assert kw["max_completion_tokens"] == 4096  # user overrides default
-
-
-class TestKimiParity:
-    """Kimi: OMIT temperature, max_tokens=32000, thinking + reasoning_effort."""
-
-    def test_temperature_omitted(self, transport):
-        kw = transport.build_kwargs(
-            model="kimi-k2",
-            messages=_simple_messages(),
-            tools=None,
-            provider_profile=get_provider_profile("kimi-coding"),
-            omit_temperature=True,
-        )
-        assert "temperature" not in kw
-
-    def test_default_max_tokens(self, transport):
-        kw = transport.build_kwargs(
-            model="kimi-k2",
-            messages=_simple_messages(),
-            tools=None,
-            provider_profile=get_provider_profile("kimi-coding"),
-            max_tokens_param_fn=_max_tokens_fn,
-        )
-        assert kw["max_completion_tokens"] == 32000
-
-    def test_thinking_enabled(self, transport):
-        kw = transport.build_kwargs(
-            model="kimi-k2",
-            messages=_simple_messages(),
-            tools=None,
-            provider_profile=get_provider_profile("kimi-coding"),
-            reasoning_config={"enabled": True, "effort": "high"},
-        )
-        assert kw["extra_body"]["thinking"] == {"type": "enabled"}
-
-    def test_thinking_disabled(self, transport):
-        kw = transport.build_kwargs(
-            model="kimi-k2",
-            messages=_simple_messages(),
-            tools=None,
-            provider_profile=get_provider_profile("kimi-coding"),
-            reasoning_config={"enabled": False},
-        )
-        assert kw["extra_body"]["thinking"] == {"type": "disabled"}
-
-    def test_reasoning_effort_top_level(self, transport):
-        """Kimi reasoning_effort is a TOP-LEVEL api_kwargs key, NOT in extra_body."""
-        kw = transport.build_kwargs(
-            model="kimi-k2",
-            messages=_simple_messages(),
-            tools=None,
-            provider_profile=get_provider_profile("kimi-coding"),
-            reasoning_config={"enabled": True, "effort": "high"},
-        )
-        assert kw.get("reasoning_effort") == "high"
-        assert "reasoning_effort" not in kw.get("extra_body", {})
-
-    def test_reasoning_effort_default_medium(self, transport):
-        kw = transport.build_kwargs(
-            model="kimi-k2",
-            messages=_simple_messages(),
-            tools=None,
-            provider_profile=get_provider_profile("kimi-coding"),
-            reasoning_config={"enabled": True},
-        )
-        assert kw.get("reasoning_effort") == "medium"
-
-
-class TestOpenRouterParity:
-    """OpenRouter: provider preferences, reasoning in extra_body."""
-
-    def test_provider_preferences(self, transport):
-        prefs = {"allow": ["anthropic"], "sort": "price"}
-        kw = transport.build_kwargs(
-            model="anthropic/claude-sonnet-4.6",
-            messages=_simple_messages(),
-            tools=None,
-            provider_profile=get_provider_profile("openrouter"),
-            provider_preferences=prefs,
-        )
-        assert kw["extra_body"]["provider"] == prefs
-
-    def test_reasoning_passes_full_config(self, transport):
-        """OpenRouter passes the FULL reasoning_config dict, not just effort."""
-        rc = {"enabled": True, "effort": "high"}
-        kw = transport.build_kwargs(
-            model="anthropic/claude-sonnet-4.6",
-            messages=_simple_messages(),
-            tools=None,
-            provider_profile=get_provider_profile("openrouter"),
-            supports_reasoning=True,
-            reasoning_config=rc,
-        )
-        assert kw["extra_body"]["reasoning"] == rc
-
-    def test_default_reasoning_when_no_config(self, transport):
-        """When supports_reasoning=True but no config, adds default."""
-        kw = transport.build_kwargs(
-            model="anthropic/claude-sonnet-4.6",
-            messages=_simple_messages(),
-            tools=None,
-            provider_profile=get_provider_profile("openrouter"),
-            supports_reasoning=True,
-        )
-        assert kw["extra_body"]["reasoning"] == {"enabled": True, "effort": "medium"}
-
-
-class TestNousParity:
-    """Nous: product tags, reasoning, omit when disabled."""
-
-    def test_tags(self, transport):
-        kw = transport.build_kwargs(
-            model="hermes-3-llama-3.1-405b",
-            messages=_simple_messages(),
-            tools=None,
-            provider_profile=get_provider_profile("nous"),
-        )
-        assert kw["extra_body"]["tags"] == ["product=hermes-agent"]
-
-    def test_reasoning_omitted_when_disabled(self, transport):
-        """Nous special case: reasoning omitted entirely when disabled."""
-        kw = transport.build_kwargs(
-            model="hermes-3-llama-3.1-405b",
-            messages=_simple_messages(),
-            tools=None,
-            provider_profile=get_provider_profile("nous"),
-            supports_reasoning=True,
-            reasoning_config={"enabled": False},
-        )
-        assert "reasoning" not in kw.get("extra_body", {})
-
-    def test_reasoning_enabled(self, transport):
-        rc = {"enabled": True, "effort": "high"}
-        kw = transport.build_kwargs(
-            model="hermes-3-llama-3.1-405b",
-            messages=_simple_messages(),
-            tools=None,
-            provider_profile=get_provider_profile("nous"),
-            supports_reasoning=True,
-            reasoning_config=rc,
-        )
-        assert kw["extra_body"]["reasoning"] == rc
-
-
-class TestQwenParity:
-    """Qwen: max_tokens=65536, vl_high_resolution, metadata top-level."""
-
-    def test_default_max_tokens(self, transport):
-        kw = transport.build_kwargs(
-            model="qwen3.5-plus",
-            messages=_simple_messages(),
-            tools=None,
-            provider_profile=get_provider_profile("qwen-oauth"),
-            max_tokens_param_fn=_max_tokens_fn,
-        )
-        assert kw["max_completion_tokens"] == 65536
-
-    def test_vl_high_resolution(self, transport):
-        kw = transport.build_kwargs(
-            model="qwen3.5-plus",
-            messages=_simple_messages(),
-            tools=None,
-            provider_profile=get_provider_profile("qwen-oauth"),
-        )
-        assert kw["extra_body"]["vl_high_resolution_images"] is True
-
-    def test_metadata_top_level(self, transport):
-        """Qwen metadata goes to top-level api_kwargs, NOT extra_body."""
-        meta = {"sessionId": "s123", "promptId": "p456"}
-        kw = transport.build_kwargs(
-            model="qwen3.5-plus",
-            messages=_simple_messages(),
-            tools=None,
-            provider_profile=get_provider_profile("qwen-oauth"),
-            qwen_session_metadata=meta,
-        )
-        assert kw["metadata"] == meta
-        assert "metadata" not in kw.get("extra_body", {})
-
-
-class TestCustomOllamaParity:
-    """Custom/Ollama: num_ctx, think=false — now tested via profile."""
-
-    def test_ollama_num_ctx(self, transport):
-        kw = transport.build_kwargs(
-            model="llama3.1",
-            messages=_simple_messages(),
-            tools=None,
-            provider_profile=get_provider_profile("custom"),
-            ollama_num_ctx=131072,
-        )
-        assert kw["extra_body"]["options"]["num_ctx"] == 131072
-
-    def test_think_false_when_disabled(self, transport):
-        kw = transport.build_kwargs(
-            model="qwen3:72b",
-            messages=_simple_messages(),
-            tools=None,
-            provider_profile=get_provider_profile("custom"),
-            reasoning_config={"enabled": False, "effort": "none"},
-        )
-        assert kw["extra_body"]["think"] is False

tests/run_agent/test_run_agent.py

@@ -1097,7 +1097,6 @@ class TestBuildApiKwargs:
         assert "temperature" not in kwargs
 
     def test_kimi_coding_endpoint_omits_temperature(self, agent):
-        agent.provider = "kimi-coding"
         agent.base_url = "https://api.kimi.com/coding/v1"
         agent._base_url_lower = agent.base_url.lower()
         agent.model = "kimi-k2.5"
@@ -1110,7 +1109,6 @@ class TestBuildApiKwargs:
     def test_kimi_coding_endpoint_sends_max_tokens_and_reasoning(self, agent):
         """Kimi endpoint should send max_tokens=32000 and reasoning_effort as
         top-level params, matching Kimi CLI's default behavior."""
-        agent.provider = "kimi-coding"
         agent.base_url = "https://api.kimi.com/coding/v1"
         agent._base_url_lower = agent.base_url.lower()
         agent.model = "kimi-for-coding"
@@ -1123,7 +1121,6 @@ class TestBuildApiKwargs:
 
     def test_kimi_coding_endpoint_respects_custom_effort(self, agent):
         """reasoning_effort should reflect reasoning_config.effort when set."""
-        agent.provider = "kimi-coding"
         agent.base_url = "https://api.kimi.com/coding/v1"
         agent._base_url_lower = agent.base_url.lower()
         agent.model = "kimi-for-coding"
@@ -1137,7 +1134,6 @@ class TestBuildApiKwargs:
     def test_kimi_coding_endpoint_sends_thinking_extra_body(self, agent):
         """Kimi endpoint should send extra_body.thinking={"type":"enabled"}
         to activate reasoning mode, mirroring Kimi CLI's with_thinking()."""
-        agent.provider = "kimi-coding"
         agent.base_url = "https://api.kimi.com/coding/v1"
         agent._base_url_lower = agent.base_url.lower()
         agent.model = "kimi-for-coding"
@@ -1151,7 +1147,6 @@ class TestBuildApiKwargs:
         """When reasoning_config.enabled=False, thinking should be disabled
         and reasoning_effort should be omitted entirely — mirroring Kimi
         CLI's with_thinking("off") which maps to reasoning_effort=None."""
-        agent.provider = "kimi-coding"
         agent.base_url = "https://api.kimi.com/coding/v1"
         agent._base_url_lower = agent.base_url.lower()
         agent.model = "kimi-for-coding"
@@ -1165,7 +1160,6 @@ class TestBuildApiKwargs:
 
     def test_moonshot_endpoint_sends_max_tokens_and_reasoning(self, agent):
         """api.moonshot.ai should get the same Kimi-compatible params."""
-        agent.provider = "kimi-coding"
         agent.base_url = "https://api.moonshot.ai/v1"
         agent._base_url_lower = agent.base_url.lower()
         agent.model = "kimi-k2.5"
@@ -1179,7 +1173,6 @@ class TestBuildApiKwargs:
 
     def test_moonshot_cn_endpoint_sends_max_tokens_and_reasoning(self, agent):
         """api.moonshot.cn (China endpoint) should get the same params."""
-        agent.provider = "kimi-coding-cn"
         agent.base_url = "https://api.moonshot.cn/v1"
         agent._base_url_lower = agent.base_url.lower()
         agent.model = "kimi-k2.5"
@@ -1192,7 +1185,6 @@ class TestBuildApiKwargs:
         assert kwargs["extra_body"]["thinking"] == {"type": "enabled"}
 
     def test_provider_preferences_injected(self, agent):
-        agent.provider = "openrouter"
         agent.base_url = "https://openrouter.ai/api/v1"
         agent.providers_allowed = ["Anthropic"]
         messages = [{"role": "user", "content": "hi"}]
@@ -1201,7 +1193,6 @@ class TestBuildApiKwargs:
 
     def test_reasoning_config_default_openrouter(self, agent):
         """Default reasoning config for OpenRouter should be medium."""
-        agent.provider = "openrouter"
         agent.base_url = "https://openrouter.ai/api/v1"
         agent.model = "anthropic/claude-sonnet-4-20250514"
         messages = [{"role": "user", "content": "hi"}]
@@ -1211,7 +1202,6 @@ class TestBuildApiKwargs:
         assert reasoning["effort"] == "medium"
 
     def test_reasoning_config_custom(self, agent):
-        agent.provider = "openrouter"
         agent.base_url = "https://openrouter.ai/api/v1"
         agent.model = "anthropic/claude-sonnet-4-20250514"
         agent.reasoning_config = {"enabled": False}
@@ -1227,7 +1217,6 @@ class TestBuildApiKwargs:
         assert "reasoning" not in kwargs.get("extra_body", {})
 
     def test_reasoning_sent_for_supported_openrouter_model(self, agent):
-        agent.provider = "openrouter"
         agent.base_url = "https://openrouter.ai/api/v1"
         agent.model = "qwen/qwen3.5-plus-02-15"
         messages = [{"role": "user", "content": "hi"}]
@@ -1235,7 +1224,6 @@ class TestBuildApiKwargs:
         assert kwargs["extra_body"]["reasoning"]["effort"] == "medium"
 
     def test_reasoning_sent_for_nous_route(self, agent):
-        agent.provider = "nous"
         agent.base_url = "https://inference-api.nousresearch.com/v1"
         agent.model = "minimax/minimax-m2.5"
         messages = [{"role": "user", "content": "hi"}]
@@ -1243,38 +1231,18 @@ class TestBuildApiKwargs:
         assert kwargs["extra_body"]["reasoning"]["effort"] == "medium"
 
     def test_reasoning_sent_for_copilot_gpt5(self, agent):
-        """Copilot/GitHub Models: GPT-5 reasoning goes in extra_body.reasoning."""
-        from agent.transports import get_transport
-        from providers import get_provider_profile
-
-        transport = get_transport("chat_completions")
-        profile = get_provider_profile("copilot")
-        msgs = [{"role": "user", "content": "hi"}]
-        kwargs = transport.build_kwargs(
-            model="gpt-5.4",
-            messages=msgs,
-            tools=None,
-            supports_reasoning=True,
-            provider_profile=profile,
-        )
+        agent.base_url = "https://api.githubcopilot.com"
+        agent.model = "gpt-5.4"
+        messages = [{"role": "user", "content": "hi"}]
+        kwargs = agent._build_api_kwargs(messages)
         assert kwargs["extra_body"]["reasoning"] == {"effort": "medium"}
 
     def test_reasoning_xhigh_normalized_for_copilot(self, agent):
-        """xhigh effort should normalize to high for Copilot GitHub Models."""
-        from agent.transports import get_transport
-        from providers import get_provider_profile
-
-        transport = get_transport("chat_completions")
-        profile = get_provider_profile("copilot")
-        msgs = [{"role": "user", "content": "hi"}]
-        kwargs = transport.build_kwargs(
-            model="gpt-5.4",
-            messages=msgs,
-            tools=None,
-            supports_reasoning=True,
-            reasoning_config={"enabled": True, "effort": "xhigh"},
-            provider_profile=profile,
-        )
+        agent.base_url = "https://api.githubcopilot.com"
+        agent.model = "gpt-5.4"
+        agent.reasoning_config = {"enabled": True, "effort": "xhigh"}
+        messages = [{"role": "user", "content": "hi"}]
+        kwargs = agent._build_api_kwargs(messages)
         assert kwargs["extra_body"]["reasoning"] == {"effort": "high"}
 
     def test_reasoning_omitted_for_non_reasoning_copilot_model(self, agent):
@@ -1292,7 +1260,6 @@ class TestBuildApiKwargs:
 
 
     def test_qwen_portal_formats_messages_and_metadata(self, agent):
-        agent.provider = "qwen-oauth"
         agent.base_url = "https://portal.qwen.ai/v1"
         agent._base_url_lower = agent.base_url.lower()
         agent.session_id = "sess-123"
@@ -1309,7 +1276,6 @@ class TestBuildApiKwargs:
         assert kwargs["messages"][2]["content"][0]["text"] == "hi"
 
     def test_qwen_portal_normalizes_bare_string_content_parts(self, agent):
-        agent.provider = "qwen-oauth"
         agent.base_url = "https://portal.qwen.ai/v1"
         agent._base_url_lower = agent.base_url.lower()
         messages = [
@@ -1322,7 +1288,6 @@ class TestBuildApiKwargs:
         assert user_content[1] == {"type": "text", "text": "world"}
 
     def test_qwen_portal_no_system_message(self, agent):
-        agent.provider = "qwen-oauth"
         agent.base_url = "https://portal.qwen.ai/v1"
         agent._base_url_lower = agent.base_url.lower()
         messages = [{"role": "user", "content": "hi"}]
@@ -1343,7 +1308,6 @@ class TestBuildApiKwargs:
     def test_qwen_portal_default_max_tokens(self, agent):
         """When max_tokens is None, Qwen Portal gets a default of 65536
         to prevent reasoning models from exhausting their output budget."""
-        agent.provider = "qwen-oauth"
         agent.base_url = "https://portal.qwen.ai/v1"
         agent._base_url_lower = agent.base_url.lower()
         agent.max_tokens = None
@@ -3879,7 +3843,7 @@ def test_aiagent_uses_copilot_acp_client():
         patch("run_agent.get_tool_definitions", return_value=_make_tool_defs("web_search")),
         patch("run_agent.check_toolset_requirements", return_value={}),
         patch("run_agent.OpenAI") as mock_openai,
-        patch("acp_adapter.copilot_client.CopilotACPClient") as mock_acp_client,
+        patch("agent.copilot_acp_client.CopilotACPClient") as mock_acp_client,
     ):
         acp_client = MagicMock()
         mock_acp_client.return_value = acp_client

tests/test_hermes_state.py

@@ -1373,6 +1373,144 @@ class TestSchemaInit:
 
         migrated_db.close()
 
+    def test_reconciliation_adds_missing_columns(self, tmp_path):
+        """Columns present in SCHEMA_SQL but missing from the live table
+        are added by _reconcile_columns regardless of schema_version.
+
+        Regression test: commit a7d78d3b inserted a new v7 migration
+        (reasoning_content) and renumbered the old v7 (api_call_count)
+        to v8.  Users already at the old v7 had schema_version >= 7,
+        so the new v7 block was skipped and reasoning_content was never
+        created — causing 'no such column' on /continue.
+        """
+        import sqlite3
+
+        db_path = tmp_path / "gap_test.db"
+        conn = sqlite3.connect(str(db_path))
+        # Simulate the old v7 state: api_call_count exists, reasoning_content does NOT
+        conn.executescript("""
+            CREATE TABLE schema_version (version INTEGER NOT NULL);
+            INSERT INTO schema_version (version) VALUES (7);
+
+            CREATE TABLE sessions (
+                id TEXT PRIMARY KEY,
+                source TEXT NOT NULL,
+                user_id TEXT,
+                model TEXT,
+                model_config TEXT,
+                system_prompt TEXT,
+                parent_session_id TEXT,
+                started_at REAL NOT NULL,
+                ended_at REAL,
+                end_reason TEXT,
+                message_count INTEGER DEFAULT 0,
+                tool_call_count INTEGER DEFAULT 0,
+                input_tokens INTEGER DEFAULT 0,
+                output_tokens INTEGER DEFAULT 0,
+                cache_read_tokens INTEGER DEFAULT 0,
+                cache_write_tokens INTEGER DEFAULT 0,
+                reasoning_tokens INTEGER DEFAULT 0,
+                billing_provider TEXT,
+                billing_base_url TEXT,
+                billing_mode TEXT,
+                estimated_cost_usd REAL,
+                actual_cost_usd REAL,
+                cost_status TEXT,
+                cost_source TEXT,
+                pricing_version TEXT,
+                title TEXT,
+                api_call_count INTEGER DEFAULT 0
+            );
+
+            CREATE TABLE messages (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                session_id TEXT NOT NULL,
+                role TEXT NOT NULL,
+                content TEXT,
+                tool_call_id TEXT,
+                tool_calls TEXT,
+                tool_name TEXT,
+                timestamp REAL NOT NULL,
+                token_count INTEGER,
+                finish_reason TEXT,
+                reasoning TEXT,
+                reasoning_details TEXT,
+                codex_reasoning_items TEXT
+            );
+        """)
+        conn.execute(
+            "INSERT INTO sessions (id, source, started_at) VALUES (?, ?, ?)",
+            ("s1", "cli", 1000.0),
+        )
+        conn.execute(
+            "INSERT INTO messages (session_id, role, content, timestamp) "
+            "VALUES (?, ?, ?, ?)",
+            ("s1", "assistant", "hello", 1001.0),
+        )
+        conn.commit()
+        # Verify reasoning_content is absent
+        cols = {r[1] for r in conn.execute("PRAGMA table_info(messages)").fetchall()}
+        assert "reasoning_content" not in cols
+        conn.close()
+
+        # Open with SessionDB — reconciliation should add the missing column
+        migrated_db = SessionDB(db_path=db_path)
+
+        msg_cols = {
+            r[1]
+            for r in migrated_db._conn.execute("PRAGMA table_info(messages)").fetchall()
+        }
+        assert "reasoning_content" in msg_cols
+
+        # The query that used to crash must now work
+        cursor = migrated_db._conn.execute(
+            "SELECT role, content, reasoning, reasoning_content, "
+            "reasoning_details, codex_reasoning_items "
+            "FROM messages WHERE session_id = ?",
+            ("s1",),
+        )
+        row = cursor.fetchone()
+        assert row is not None
+        assert row[0] == "assistant"
+        assert row[3] is None  # reasoning_content NULL for old rows
+
+        migrated_db.close()
+
+    def test_reconciliation_is_idempotent(self, tmp_path):
+        """Opening the same database twice doesn't error or duplicate columns."""
+        db_path = tmp_path / "idempotent.db"
+        db1 = SessionDB(db_path=db_path)
+        cols1 = {r[1] for r in db1._conn.execute("PRAGMA table_info(messages)").fetchall()}
+        db1.close()
+
+        db2 = SessionDB(db_path=db_path)
+        cols2 = {r[1] for r in db2._conn.execute("PRAGMA table_info(messages)").fetchall()}
+        db2.close()
+
+        assert cols1 == cols2
+
+    def test_schema_sql_is_source_of_truth(self, db):
+        """Every column in SCHEMA_SQL exists in the live database.
+
+        This is the architectural invariant: SCHEMA_SQL declares the
+        desired schema, _reconcile_columns ensures it matches reality.
+        """
+        from hermes_state import SCHEMA_SQL
+
+        expected = SessionDB._parse_schema_columns(SCHEMA_SQL)
+        for table_name, declared_cols in expected.items():
+            live_cols = {
+                r[1]
+                for r in db._conn.execute(
+                    f'PRAGMA table_info("{table_name}")'
+                ).fetchall()
+            }
+            for col_name in declared_cols:
+                assert col_name in live_cols, (
+                    f"Column {col_name} declared in SCHEMA_SQL for {table_name} "
+                    f"but missing from live DB. Live columns: {live_cols}"
+                )
+
 
 class TestTitleUniqueness:
     """Tests for unique title enforcement and title-based lookups."""

tests/tools/test_delegate.py

@@ -568,6 +568,163 @@ class TestDelegateObservability(unittest.TestCase):
             self.assertEqual(result["results"][0]["exit_reason"], "max_iterations")
 
 
+class TestSubagentCostRollup(unittest.TestCase):
+    """Port of Kilo-Org/kilocode#9448 — parent's session_estimated_cost_usd
+    must include subagent spend, not just the parent's own API calls."""
+
+    def _make_parent_with_cost_counters(self, depth=0, starting_cost=0.0):
+        parent = _make_mock_parent(depth=depth)
+        # The fields AIAgent exposes and the footer reads from.  Set real
+        # floats/strings so the rollup can add to them rather than tripping
+        # on MagicMock auto-attrs.
+        parent.session_estimated_cost_usd = starting_cost
+        parent.session_cost_status = "unknown"
+        parent.session_cost_source = "none"
+        return parent
+
+    def test_single_child_cost_folded_into_parent(self):
+        parent = self._make_parent_with_cost_counters(starting_cost=0.10)
+
+        with patch("run_agent.AIAgent") as MockAgent:
+            mock_child = MagicMock()
+            mock_child.model = "claude-sonnet-4-6"
+            mock_child.session_prompt_tokens = 1000
+            mock_child.session_completion_tokens = 200
+            mock_child.session_estimated_cost_usd = 0.42
+            mock_child.run_conversation.return_value = {
+                "final_response": "done",
+                "completed": True,
+                "interrupted": False,
+                "api_calls": 2,
+                "messages": [],
+            }
+            MockAgent.return_value = mock_child
+
+            result = json.loads(delegate_task(goal="do stuff", parent_agent=parent))
+
+        # Parent footer must reflect parent_cost + child_cost.
+        self.assertAlmostEqual(parent.session_estimated_cost_usd, 0.52, places=6)
+        # Rollup must strip the internal field before serialising to the model.
+        self.assertNotIn("_child_cost_usd", result["results"][0])
+        self.assertNotIn("_child_role", result["results"][0])
+
+    def test_batch_children_costs_sum_into_parent(self):
+        parent = self._make_parent_with_cost_counters(starting_cost=0.00)
+
+        with patch("tools.delegate_tool._run_single_child") as mock_run:
+            mock_run.side_effect = [
+                {
+                    "task_index": 0,
+                    "status": "completed",
+                    "summary": "A",
+                    "api_calls": 2,
+                    "duration_seconds": 1.0,
+                    "_child_role": "leaf",
+                    "_child_cost_usd": 0.15,
+                },
+                {
+                    "task_index": 1,
+                    "status": "completed",
+                    "summary": "B",
+                    "api_calls": 2,
+                    "duration_seconds": 1.0,
+                    "_child_role": "leaf",
+                    "_child_cost_usd": 0.27,
+                },
+                {
+                    "task_index": 2,
+                    "status": "failed",
+                    "summary": "",
+                    "error": "boom",
+                    "api_calls": 0,
+                    "duration_seconds": 0.1,
+                    "_child_role": "leaf",
+                    "_child_cost_usd": 0.03,
+                },
+            ]
+            result = json.loads(
+                delegate_task(
+                    tasks=[{"goal": "A"}, {"goal": "B"}, {"goal": "C"}],
+                    parent_agent=parent,
+                )
+            )
+
+        # 0.15 + 0.27 + 0.03 even though one child failed — the API calls it
+        # made before failing still cost money.
+        self.assertAlmostEqual(parent.session_estimated_cost_usd, 0.45, places=6)
+        # cost_source promoted from "none" since the parent had no direct spend.
+        self.assertEqual(parent.session_cost_source, "subagent")
+        self.assertEqual(parent.session_cost_status, "estimated")
+        # All internal fields stripped from results.
+        for entry in result["results"]:
+            self.assertNotIn("_child_cost_usd", entry)
+            self.assertNotIn("_child_role", entry)
+
+    def test_zero_cost_children_leave_parent_source_untouched(self):
+        """If every child reports 0 cost (e.g. free local model), we should
+        not invent a fake 'subagent' source — the parent's 'none' stays."""
+        parent = self._make_parent_with_cost_counters(starting_cost=0.00)
+
+        with patch("tools.delegate_tool._run_single_child") as mock_run:
+            mock_run.return_value = {
+                "task_index": 0,
+                "status": "completed",
+                "summary": "done",
+                "api_calls": 1,
+                "duration_seconds": 0.5,
+                "_child_role": "leaf",
+                "_child_cost_usd": 0.0,
+            }
+            delegate_task(goal="free local run", parent_agent=parent)
+
+        self.assertEqual(parent.session_estimated_cost_usd, 0.0)
+        self.assertEqual(parent.session_cost_source, "none")
+
+    def test_parent_with_real_source_not_overwritten(self):
+        """If the parent already has its own cost billed (cost_source != 'none'),
+        adding subagent cost must not clobber the existing source label."""
+        parent = self._make_parent_with_cost_counters(starting_cost=0.20)
+        parent.session_cost_status = "exact"
+        parent.session_cost_source = "openrouter"
+
+        with patch("tools.delegate_tool._run_single_child") as mock_run:
+            mock_run.return_value = {
+                "task_index": 0,
+                "status": "completed",
+                "summary": "done",
+                "api_calls": 1,
+                "duration_seconds": 0.5,
+                "_child_role": "leaf",
+                "_child_cost_usd": 0.30,
+            }
+            delegate_task(goal="billed run", parent_agent=parent)
+
+        self.assertAlmostEqual(parent.session_estimated_cost_usd, 0.50, places=6)
+        # Real source label preserved.
+        self.assertEqual(parent.session_cost_source, "openrouter")
+        self.assertEqual(parent.session_cost_status, "exact")
+
+    def test_rollup_tolerates_missing_cost_fields(self):
+        """Older fixtures / fabricated error entries may not carry
+        _child_cost_usd.  Rollup must degrade to zero-add silently."""
+        parent = self._make_parent_with_cost_counters(starting_cost=0.10)
+
+        with patch("tools.delegate_tool._run_single_child") as mock_run:
+            mock_run.return_value = {
+                "task_index": 0,
+                "status": "completed",
+                "summary": "done",
+                "api_calls": 1,
+                "duration_seconds": 0.5,
+                # no _child_role, no _child_cost_usd
+            }
+            result = json.loads(delegate_task(goal="legacy", parent_agent=parent))
+
+        # Parent cost unchanged.
+        self.assertEqual(parent.session_estimated_cost_usd, 0.10)
+        self.assertEqual(len(result["results"]), 1)
+
+
 class TestBlockedTools(unittest.TestCase):
     def test_blocked_tools_constant(self):
         for tool in ["delegate_task", "clarify", "memory", "send_message", "execute_code"]:

tools/delegate_tool.py

@@ -1616,6 +1616,19 @@ def _run_single_child(
             # parent thread can fire subagent_stop with the correct role.
             # Stripped before the dict is serialised back to the model.
             "_child_role": getattr(child, "_delegate_role", None),
+            # Captured before child.close() so the parent aggregator can fold
+            # the child's total spend into the parent's session cost.  Port of
+            # Kilo-Org/kilocode#9448 — previously the footer only reflected the
+            # parent's direct API calls and under-counted subagent-heavy runs.
+            # Stripped before the dict is serialised back to the model.
+            "_child_cost_usd": (
+                float(getattr(child, "session_estimated_cost_usd", 0.0) or 0.0)
+                if isinstance(
+                    getattr(child, "session_estimated_cost_usd", 0.0),
+                    (int, float),
+                )
+                else 0.0
+            ),
         }
         if status == "failed":
             entry["error"] = result.get("error", "Subagent did not produce a response.")
@@ -2112,8 +2125,20 @@ def delegate_task(
         from hermes_cli.plugins import invoke_hook as _invoke_hook
     except Exception:
         _invoke_hook = None
+    # Aggregate child spend here so the parent's footer/UI reflect the true
+    # cost of a subagent-heavy turn.  Port of Kilo-Org/kilocode#9448.  Each
+    # child's cost was captured in _run_single_child before its AIAgent was
+    # closed; we fold them into the parent in one pass alongside the
+    # subagent_stop hook loop so we don't walk `results` twice.
+    _children_cost_total = 0.0
     for entry in results:
         child_role = entry.pop("_child_role", None)
+        child_cost = entry.pop("_child_cost_usd", 0.0)
+        try:
+            if child_cost:
+                _children_cost_total += float(child_cost)
+        except (TypeError, ValueError):
+            pass
         if _invoke_hook is None:
             continue
         try:
@@ -2128,6 +2153,28 @@ def delegate_task(
         except Exception:
             logger.debug("subagent_stop hook invocation failed", exc_info=True)
 
+    # Fold the aggregated child cost into the parent's session total.  This is
+    # additive — each delegate_task call contributes its own children — so
+    # nested orchestrator→worker trees roll up naturally: each layer's own
+    # delegate_task() folds its direct children in, and when the orchestrator
+    # itself finishes, its parent folds the orchestrator's now-inflated total
+    # on top.  Degrades silently if the parent lacks the counter (older test
+    # fixtures, etc.).
+    if _children_cost_total > 0.0:
+        try:
+            current = float(getattr(parent_agent, "session_estimated_cost_usd", 0.0) or 0.0)
+            parent_agent.session_estimated_cost_usd = current + _children_cost_total
+            # Upgrade the cost_source so the UI doesn't label a partially-real
+            # total as "none" when the parent itself hadn't billed any calls
+            # yet (rare but possible when the parent's only action this turn
+            # was delegate_task).
+            if getattr(parent_agent, "session_cost_source", "none") in (None, "", "none"):
+                parent_agent.session_cost_source = "subagent"
+            if getattr(parent_agent, "session_cost_status", "unknown") in (None, "", "unknown"):
+                parent_agent.session_cost_status = "estimated"
+        except Exception:
+            logger.debug("Subagent cost rollup failed", exc_info=True)
+
     total_duration = round(time.monotonic() - overall_start, 2)
 
     return json.dumps(

uv.lock

@@ -9,7 +9,7 @@ resolution-markers = [
 ]
 
 [options]
-exclude-newer = "2026-04-19T17:00:07.266826Z"
+exclude-newer = "2026-04-17T16:49:45.944715922Z"
 exclude-newer-span = "P7D"
 
 [[package]]
@@ -564,30 +564,30 @@ wheels = [
 
 [[package]]
 name = "boto3"
-version = "1.42.91"
+version = "1.42.89"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "botocore" },
     { name = "jmespath" },
     { name = "s3transfer" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/a7/c0/98b8cec7ca22dde776df48c58940ae1abc425593959b7226e270760d726f/boto3-1.42.91.tar.gz", hash = "sha256:03d70532b17f7f84df37ca7e8c21553280454dea53ae12b15d1cfef9b16fcb8a", size = 113181, upload-time = "2026-04-17T19:31:06.251Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/bb/0c/f7bccb22b245cabf392816baba20f9e95f78ace7dbc580fd40136e80e732/boto3-1.42.89.tar.gz", hash = "sha256:3e43aacc0801bba9bcd23a8c271c089af297a69565f783fcdd357ae0e330bf1e", size = 113165, upload-time = "2026-04-13T19:36:17.516Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/02/29/faba6521257c34085cc9b439ef98235b581772580f417fa3629728007270/boto3-1.42.91-py3-none-any.whl", hash = "sha256:04e72071cde022951ce7f81bd9933c90095ab8923e8ced61c8dacfe9edac0f5c", size = 140553, upload-time = "2026-04-17T19:31:02.57Z" },
+    { url = "https://files.pythonhosted.org/packages/b9/33/55103ba5ef9975ea54b8d39e69b76eb6e9fded3beae5f01065e26951a3a1/boto3-1.42.89-py3-none-any.whl", hash = "sha256:6204b189f4d0c655535f43d7eaa57ff4e8d965b8463c97e45952291211162932", size = 140556, upload-time = "2026-04-13T19:36:13.894Z" },
 ]
 
 [[package]]
 name = "botocore"
-version = "1.42.91"
+version = "1.42.89"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "jmespath" },
     { name = "python-dateutil" },
     { name = "urllib3" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/21/bc/a4b7c46471c2e789ad8c4c7acfd7f302fdb481d93ff870f441249b924ae6/botocore-1.42.91.tar.gz", hash = "sha256:d252e27bc454afdbf5ed3dc617aa423f2c855c081e98b7963093399483ecc698", size = 15213010, upload-time = "2026-04-17T19:30:50.793Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/0f/cc/e6be943efa9051bd15c2ee14077c2b10d6e27c9e9385fc43a03a5c4ed8b5/botocore-1.42.89.tar.gz", hash = "sha256:95ac52f472dad29942f3088b278ab493044516c16dbf9133c975af16527baa99", size = 15206290, upload-time = "2026-04-13T19:36:02.321Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/b1/fc/24cc0a47c824f13933e210e9ad034b4fba22f7185b8d904c0fbf5a3b2be8/botocore-1.42.91-py3-none-any.whl", hash = "sha256:7a28c3cc6bfab5724ad18899d52402b776a0de7d87fa20c3c5270bcaaf199ce8", size = 14897344, upload-time = "2026-04-17T19:30:44.245Z" },
+    { url = "https://files.pythonhosted.org/packages/91/f1/90a7b8eda38b7c3a65ca7ee0075bdf310b6b471cb1b95fab6e8994323a50/botocore-1.42.89-py3-none-any.whl", hash = "sha256:d9b786c8d9db6473063b4cc5be0ba7e6a381082307bd6afb69d4216f9fa95f35", size = 14887287, upload-time = "2026-04-13T19:35:56.677Z" },
 ]
 
 [[package]]
@@ -1759,77 +1759,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/6a/09/e21df6aef1e1ffc0c816f0522ddc3f6dcded766c3261813131c78a704470/gitpython-3.1.46-py3-none-any.whl", hash = "sha256:79812ed143d9d25b6d176a10bb511de0f9c67b1fa641d82097b0ab90398a2058", size = 208620, upload-time = "2026-01-01T15:37:30.574Z" },
 ]
 
-[[package]]
-name = "google-api-core"
-version = "2.30.3"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "google-auth" },
-    { name = "googleapis-common-protos" },
-    { name = "proto-plus" },
-    { name = "protobuf" },
-    { name = "requests" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/16/ce/502a57fb0ec752026d24df1280b162294b22a0afb98a326084f9a979138b/google_api_core-2.30.3.tar.gz", hash = "sha256:e601a37f148585319b26db36e219df68c5d07b6382cff2d580e83404e44d641b", size = 177001, upload-time = "2026-04-10T00:41:28.035Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/03/15/e56f351cf6ef1cfea58e6ac226a7318ed1deb2218c4b3cc9bd9e4b786c5a/google_api_core-2.30.3-py3-none-any.whl", hash = "sha256:a85761ba72c444dad5d611c2220633480b2b6be2521eca69cca2dbb3ffd6bfe8", size = 173274, upload-time = "2026-04-09T22:57:16.198Z" },
-]
-
-[[package]]
-name = "google-api-python-client"
-version = "2.194.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "google-api-core" },
-    { name = "google-auth" },
-    { name = "google-auth-httplib2" },
-    { name = "httplib2" },
-    { name = "uritemplate" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/60/ab/e83af0eb043e4ccc49571ca7a6a49984e9d00f4e9e6e6f1238d60bc84dce/google_api_python_client-2.194.0.tar.gz", hash = "sha256:db92647bd1a90f40b79c9618461553c2b20b6a43ce7395fa6de07132dc14f023", size = 14443469, upload-time = "2026-04-08T23:07:35.757Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/b0/34/5a624e49f179aa5b0cb87b2ce8093960299030ff40423bfbde09360eb908/google_api_python_client-2.194.0-py3-none-any.whl", hash = "sha256:61eaaac3b8fc8fdf11c08af87abc3d1342d1b37319cc1b57405f86ef7697e717", size = 15016514, upload-time = "2026-04-08T23:07:33.093Z" },
-]
-
-[[package]]
-name = "google-auth"
-version = "2.49.2"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "cryptography" },
-    { name = "pyasn1-modules" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/c6/fc/e925290a1ad95c975c459e2df070fac2b90954e13a0370ac505dff78cb99/google_auth-2.49.2.tar.gz", hash = "sha256:c1ae38500e73065dcae57355adb6278cf8b5c8e391994ae9cbadbcb9631ab409", size = 333958, upload-time = "2026-04-10T00:41:21.888Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/73/76/d241a5c927433420507215df6cac1b1fa4ac0ba7a794df42a84326c68da8/google_auth-2.49.2-py3-none-any.whl", hash = "sha256:c2720924dfc82dedb962c9f52cabb2ab16714fd0a6a707e40561d217574ed6d5", size = 240638, upload-time = "2026-04-10T00:41:14.501Z" },
-]
-
-[[package]]
-name = "google-auth-httplib2"
-version = "0.3.1"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "google-auth" },
-    { name = "httplib2" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/ed/99/107612bef8d24b298bb5a7c8466f908ecda791d43f9466f5c3978f5b24c1/google_auth_httplib2-0.3.1.tar.gz", hash = "sha256:0af542e815784cb64159b4469aa5d71dd41069ba93effa006e1916b1dcd88e55", size = 11152, upload-time = "2026-03-30T22:50:26.766Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/97/e9/93afb14d23a949acaa3f4e7cc51a0024671174e116e35f42850764b99634/google_auth_httplib2-0.3.1-py3-none-any.whl", hash = "sha256:682356a90ef4ba3d06548c37e9112eea6fc00395a11b0303a644c1a86abc275c", size = 9534, upload-time = "2026-03-30T22:49:03.384Z" },
-]
-
-[[package]]
-name = "google-auth-oauthlib"
-version = "1.3.1"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "google-auth" },
-    { name = "requests-oauthlib" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/a6/82/62482931dcbe5266a2680d0da17096f2aab983ecb320277d9556700ce00e/google_auth_oauthlib-1.3.1.tar.gz", hash = "sha256:14c22c7b3dd3d06dbe44264144409039465effdd1eef94f7ce3710e486cc4bfa", size = 21663, upload-time = "2026-03-30T22:49:56.408Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/2a/e0/cb454a95f460903e39f101e950038ec24a072ca69d0a294a6df625cc1627/google_auth_oauthlib-1.3.1-py3-none-any.whl", hash = "sha256:1a139ef23f1318756805b0e95f655c238bffd29655329a2978218248da4ee7f8", size = 19247, upload-time = "2026-03-30T20:02:23.894Z" },
-]
-
 [[package]]
 name = "googleapis-common-protos"
 version = "1.73.0"
@@ -1983,9 +1912,6 @@ all = [
     { name = "elevenlabs" },
     { name = "fastapi" },
     { name = "faster-whisper" },
-    { name = "google-api-python-client" },
-    { name = "google-auth-httplib2" },
-    { name = "google-auth-oauthlib" },
     { name = "honcho-ai" },
     { name = "lark-oapi" },
     { name = "markdown", marker = "sys_platform == 'linux'" },
@@ -2039,11 +1965,6 @@ feishu = [
     { name = "lark-oapi" },
     { name = "qrcode" },
 ]
-google = [
-    { name = "google-api-python-client" },
-    { name = "google-auth-httplib2" },
-    { name = "google-auth-oauthlib" },
-]
 homeassistant = [
     { name = "aiohttp" },
 ]
@@ -2143,9 +2064,6 @@ requires-dist = [
     { name = "faster-whisper", marker = "extra == 'voice'", specifier = ">=1.0.0,<2" },
     { name = "fire", specifier = ">=0.7.1,<1" },
     { name = "firecrawl-py", specifier = ">=4.16.0,<5" },
-    { name = "google-api-python-client", marker = "extra == 'google'", specifier = ">=2.100,<3" },
-    { name = "google-auth-httplib2", marker = "extra == 'google'", specifier = ">=0.2,<1" },
-    { name = "google-auth-oauthlib", marker = "extra == 'google'", specifier = ">=1.0,<2" },
     { name = "hermes-agent", extras = ["acp"], marker = "extra == 'all'" },
     { name = "hermes-agent", extras = ["acp"], marker = "extra == 'termux'" },
     { name = "hermes-agent", extras = ["bedrock"], marker = "extra == 'all'" },
@@ -2157,7 +2075,6 @@ requires-dist = [
     { name = "hermes-agent", extras = ["dev"], marker = "extra == 'all'" },
     { name = "hermes-agent", extras = ["dingtalk"], marker = "extra == 'all'" },
     { name = "hermes-agent", extras = ["feishu"], marker = "extra == 'all'" },
-    { name = "hermes-agent", extras = ["google"], marker = "extra == 'all'" },
     { name = "hermes-agent", extras = ["homeassistant"], marker = "extra == 'all'" },
     { name = "hermes-agent", extras = ["honcho"], marker = "extra == 'all'" },
     { name = "hermes-agent", extras = ["honcho"], marker = "extra == 'termux'" },
@@ -2219,7 +2136,7 @@ requires-dist = [
     { name = "wandb", marker = "extra == 'rl'", specifier = ">=0.15.0,<1" },
     { name = "yc-bench", marker = "python_full_version >= '3.12' and extra == 'yc-bench'", git = "https://github.com/collinear-ai/yc-bench.git?rev=bfb0c88062450f46341bd9a5298903fc2e952a5c" },
 ]
-provides-extras = ["modal", "daytona", "dev", "messaging", "cron", "slack", "matrix", "cli", "tts-premium", "voice", "pty", "honcho", "mcp", "homeassistant", "sms", "acp", "mistral", "bedrock", "termux", "dingtalk", "feishu", "google", "web", "rl", "yc-bench", "all"]
+provides-extras = ["modal", "daytona", "dev", "messaging", "cron", "slack", "matrix", "cli", "tts-premium", "voice", "pty", "honcho", "mcp", "homeassistant", "sms", "acp", "mistral", "bedrock", "termux", "dingtalk", "feishu", "web", "rl", "yc-bench", "all"]
 
 [[package]]
 name = "hf-transfer"
@@ -2321,18 +2238,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/7e/f5/f66802a942d491edb555dd61e3a9961140fd64c90bce1eafd741609d334d/httpcore-1.0.9-py3-none-any.whl", hash = "sha256:2d400746a40668fc9dec9810239072b40b4484b640a8c38fd654a024c7a1bf55", size = 78784, upload-time = "2025-04-24T22:06:20.566Z" },
 ]
 
-[[package]]
-name = "httplib2"
-version = "0.31.2"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "pyparsing" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/c1/1f/e86365613582c027dda5ddb64e1010e57a3d53e99ab8a72093fa13d565ec/httplib2-0.31.2.tar.gz", hash = "sha256:385e0869d7397484f4eab426197a4c020b606edd43372492337c0b4010ae5d24", size = 250800, upload-time = "2026-01-23T11:04:44.165Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/2f/90/fd509079dfcab01102c0fdd87f3a9506894bc70afcf9e9785ef6b2b3aff6/httplib2-0.31.2-py3-none-any.whl", hash = "sha256:dbf0c2fa3862acf3c55c078ea9c0bc4481d7dc5117cae71be9514912cf9f8349", size = 91099, upload-time = "2026-01-23T11:04:42.78Z" },
-]
-
 [[package]]
 name = "httptools"
 version = "0.7.1"
@@ -3372,15 +3277,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/57/a7/b35835e278c18b85206834b3aa3abe68e77a98769c59233d1f6300284781/numpy-2.4.3-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:4b42639cdde6d24e732ff823a3fa5b701d8acad89c4142bc1d0bd6dc85200ba5", size = 12504685, upload-time = "2026-03-09T07:58:50.525Z" },
 ]
 
-[[package]]
-name = "oauthlib"
-version = "3.3.1"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/0b/5f/19930f824ffeb0ad4372da4812c50edbd1434f678c90c2733e1188edfc63/oauthlib-3.3.1.tar.gz", hash = "sha256:0f0f8aa759826a193cf66c12ea1af1637f87b9b4622d46e866952bb022e538c9", size = 185918, upload-time = "2025-06-19T22:48:08.269Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/be/9c/92789c596b8df838baa98fa71844d84283302f7604ed565dafe5a6b5041a/oauthlib-3.3.1-py3-none-any.whl", hash = "sha256:88119c938d2b8fb88561af5f6ee0eec8cc8d552b7bb1f712743136eb7523b7a1", size = 160065, upload-time = "2025-06-19T22:48:06.508Z" },
-]
-
 [[package]]
 name = "obstore"
 version = "0.8.2"
@@ -3959,18 +3855,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/5b/5a/bc7b4a4ef808fa59a816c17b20c4bef6884daebbdf627ff2a161da67da19/propcache-0.4.1-py3-none-any.whl", hash = "sha256:af2a6052aeb6cf17d3e46ee169099044fd8224cbaf75c76a2ef596e8163e2237", size = 13305, upload-time = "2025-10-08T19:49:00.792Z" },
 ]
 
-[[package]]
-name = "proto-plus"
-version = "1.27.2"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "protobuf" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/81/0d/94dfe80193e79d55258345901acd2917523d56e8381bc4dee7fd38e3868a/proto_plus-1.27.2.tar.gz", hash = "sha256:b2adde53adadf75737c44d3dcb0104fde65250dfc83ad59168b4aa3e574b6a24", size = 57204, upload-time = "2026-03-26T22:18:57.174Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/84/f3/1fba73eeffafc998a25d59703b63f8be4fe8a5cb12eaff7386a0ba0f7125/proto_plus-1.27.2-py3-none-any.whl", hash = "sha256:6432f75893d3b9e70b9c412f1d2f03f65b11fb164b793d14ae2ca01821d22718", size = 50450, upload-time = "2026-03-26T22:13:42.927Z" },
-]
-
 [[package]]
 name = "protobuf"
 version = "6.33.5"
@@ -4045,27 +3929,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/50/f2/c0e76a0b451ffdf0cf788932e182758eb7558953f4f27f1aff8e2518b653/pyarrow-23.0.1-cp314-cp314t-win_amd64.whl", hash = "sha256:527e8d899f14bd15b740cd5a54ad56b7f98044955373a17179d5956ddb93d9ce", size = 28365807, upload-time = "2026-02-16T10:14:03.892Z" },
 ]
 
-[[package]]
-name = "pyasn1"
-version = "0.6.3"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/5c/5f/6583902b6f79b399c9c40674ac384fd9cd77805f9e6205075f828ef11fb2/pyasn1-0.6.3.tar.gz", hash = "sha256:697a8ecd6d98891189184ca1fa05d1bb00e2f84b5977c481452050549c8a72cf", size = 148685, upload-time = "2026-03-17T01:06:53.382Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/5d/a0/7d793dce3fa811fe047d6ae2431c672364b462850c6235ae306c0efd025f/pyasn1-0.6.3-py3-none-any.whl", hash = "sha256:a80184d120f0864a52a073acc6fc642847d0be408e7c7252f31390c0f4eadcde", size = 83997, upload-time = "2026-03-17T01:06:52.036Z" },
-]
-
-[[package]]
-name = "pyasn1-modules"
-version = "0.4.2"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "pyasn1" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/e9/e6/78ebbb10a8c8e4b61a59249394a4a594c1a7af95593dc933a349c8d00964/pyasn1_modules-0.4.2.tar.gz", hash = "sha256:677091de870a80aae844b1ca6134f54652fa2c8c5a52aa396440ac3106e941e6", size = 307892, upload-time = "2025-03-28T02:41:22.17Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/47/8d/d529b5d697919ba8c11ad626e835d4039be708a35b0d22de83a269a6682c/pyasn1_modules-0.4.2-py3-none-any.whl", hash = "sha256:29253a9207ce32b64c3ac6600edc75368f98473906e8fd1043bd6b5b1de2c14a", size = 181259, upload-time = "2025-03-28T02:41:19.028Z" },
-]
-
 [[package]]
 name = "pycparser"
 version = "3.0"
@@ -4666,19 +4529,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/56/5d/c814546c2333ceea4ba42262d8c4d55763003e767fa169adc693bd524478/requests-2.33.0-py3-none-any.whl", hash = "sha256:3324635456fa185245e24865e810cecec7b4caf933d7eb133dcde67d48cee69b", size = 65017, upload-time = "2026-03-25T15:10:40.382Z" },
 ]
 
-[[package]]
-name = "requests-oauthlib"
-version = "2.0.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "oauthlib" },
-    { name = "requests" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/42/f2/05f29bc3913aea15eb670be136045bf5c5bbf4b99ecb839da9b422bb2c85/requests-oauthlib-2.0.0.tar.gz", hash = "sha256:b3dffaebd884d8cd778494369603a9e7b58d29111bf6b41bdc2dcd87203af4e9", size = 55650, upload-time = "2024-03-22T20:32:29.939Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/3b/5d/63d4ae3b9daea098d5d6f5da83984853c1bbacd5dc826764b249fe119d24/requests_oauthlib-2.0.0-py2.py3-none-any.whl", hash = "sha256:7dd8a5c40426b779b0868c404bdef9768deccf22749cde15852df527e6269b36", size = 24179, upload-time = "2024-03-22T20:32:28.055Z" },
-]
-
 [[package]]
 name = "requests-toolbelt"
 version = "1.0.0"
@@ -4814,27 +4664,27 @@ wheels = [
 
 [[package]]
 name = "ruff"
-version = "0.15.11"
+version = "0.15.10"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/e4/8d/192f3d7103816158dfd5ea50d098ef2aec19194e6cbccd4b3485bdb2eb2d/ruff-0.15.11.tar.gz", hash = "sha256:f092b21708bf0e7437ce9ada249dfe688ff9a0954fc94abab05dcea7dcd29c33", size = 4637264, upload-time = "2026-04-16T18:46:26.58Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/e7/d9/aa3f7d59a10ef6b14fe3431706f854dbf03c5976be614a9796d36326810c/ruff-0.15.10.tar.gz", hash = "sha256:d1f86e67ebfdef88e00faefa1552b5e510e1d35f3be7d423dc7e84e63788c94e", size = 4631728, upload-time = "2026-04-09T14:06:09.884Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/02/1e/6aca3427f751295ab011828e15e9bf452200ac74484f1db4be0197b8170b/ruff-0.15.11-py3-none-linux_armv6l.whl", hash = "sha256:e927cfff503135c558eb581a0c9792264aae9507904eb27809cdcff2f2c847b7", size = 10607943, upload-time = "2026-04-16T18:46:05.967Z" },
-    { url = "https://files.pythonhosted.org/packages/e7/26/1341c262e74f36d4e84f3d6f4df0ac68cd53331a66bfc5080daa17c84c0b/ruff-0.15.11-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:7a1b5b2938d8f890b76084d4fa843604d787a912541eae85fd7e233398bbb73e", size = 10988592, upload-time = "2026-04-16T18:46:00.742Z" },
-    { url = "https://files.pythonhosted.org/packages/03/71/850b1d6ffa9564fbb6740429bad53df1094082fe515c8c1e74b6d8d05f18/ruff-0.15.11-py3-none-macosx_11_0_arm64.whl", hash = "sha256:d4176f3d194afbdaee6e41b9ccb1a2c287dba8700047df474abfbe773825d1cb", size = 10338501, upload-time = "2026-04-16T18:46:03.723Z" },
-    { url = "https://files.pythonhosted.org/packages/f2/11/cc1284d3e298c45a817a6aadb6c3e1d70b45c9b36d8d9cce3387b495a03a/ruff-0.15.11-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:3b17c886fb88203ced3afe7f14e8d5ae96e9d2f4ccc0ee66aa19f2c2675a27e4", size = 10670693, upload-time = "2026-04-16T18:46:41.941Z" },
-    { url = "https://files.pythonhosted.org/packages/ce/9e/f8288b034ab72b371513c13f9a41d9ba3effac54e24bfb467b007daee2ca/ruff-0.15.11-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:49fafa220220afe7758a487b048de4c8f9f767f37dfefad46b9dd06759d003eb", size = 10416177, upload-time = "2026-04-16T18:46:21.717Z" },
-    { url = "https://files.pythonhosted.org/packages/85/71/504d79abfd3d92532ba6bbe3d1c19fada03e494332a59e37c7c2dabae427/ruff-0.15.11-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:f2ab8427e74a00d93b8bda1307b1e60970d40f304af38bccb218e056c220120d", size = 11221886, upload-time = "2026-04-16T18:46:15.086Z" },
-    { url = "https://files.pythonhosted.org/packages/43/5a/947e6ab7a5ad603d65b474be15a4cbc6d29832db5d762cd142e4e3a74164/ruff-0.15.11-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:195072c0c8e1fc8f940652073df082e37a5d9cb43b4ab1e4d0566ab8977a13b7", size = 12075183, upload-time = "2026-04-16T18:46:07.944Z" },
-    { url = "https://files.pythonhosted.org/packages/9f/a1/0b7bb6268775fdd3a0818aee8efd8f5b4e231d24dd4d528ced2534023182/ruff-0.15.11-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:a3a0996d486af3920dec930a2e7daed4847dfc12649b537a9335585ada163e9e", size = 11516575, upload-time = "2026-04-16T18:46:31.687Z" },
-    { url = "https://files.pythonhosted.org/packages/30/c3/bb5168fc4d233cc06e95f482770d0f3c87945a0cd9f614b90ea8dc2f2833/ruff-0.15.11-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:1bef2cb556d509259f1fe440bb9cd33c756222cf0a7afe90d15edf0866702431", size = 11306537, upload-time = "2026-04-16T18:46:36.988Z" },
-    { url = "https://files.pythonhosted.org/packages/e4/92/4cfae6441f3967317946f3b788136eecf093729b94d6561f963ed810c82e/ruff-0.15.11-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:030d921a836d7d4a12cf6e8d984a88b66094ccb0e0f17ddd55067c331191bf19", size = 11296813, upload-time = "2026-04-16T18:46:24.182Z" },
-    { url = "https://files.pythonhosted.org/packages/43/26/972784c5dde8313acde8ac71ba8ac65475b85db4a2352a76c9934361f9bc/ruff-0.15.11-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:0e783b599b4577788dbbb66b9addcef87e9a8832f4ce0c19e34bf55543a2f890", size = 10633136, upload-time = "2026-04-16T18:46:39.802Z" },
-    { url = "https://files.pythonhosted.org/packages/5b/53/3985a4f185020c2f367f2e08a103032e12564829742a1b417980ce1514a0/ruff-0.15.11-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:ae90592246625ba4a34349d68ec28d4400d75182b71baa196ddb9f82db025ef5", size = 10424701, upload-time = "2026-04-16T18:46:10.381Z" },
-    { url = "https://files.pythonhosted.org/packages/d3/57/bf0dfb32241b56c83bb663a826133da4bf17f682ba8c096973065f6e6a68/ruff-0.15.11-py3-none-musllinux_1_2_i686.whl", hash = "sha256:1f111d62e3c983ed20e0ca2e800f8d77433a5b1161947df99a5c2a3fb60514f0", size = 10873887, upload-time = "2026-04-16T18:46:29.157Z" },
-    { url = "https://files.pythonhosted.org/packages/02/05/e48076b2a57dc33ee8c7a957296f97c744ca891a8ffb4ffb1aaa3b3f517d/ruff-0.15.11-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:06f483d6646f59eaffba9ae30956370d3a886625f511a3108994000480621d1c", size = 11404316, upload-time = "2026-04-16T18:46:19.462Z" },
-    { url = "https://files.pythonhosted.org/packages/88/27/0195d15fe7a897cbcba0904792c4b7c9fdd958456c3a17d2ea6093716a9a/ruff-0.15.11-py3-none-win32.whl", hash = "sha256:476a2aa56b7da0b73a3ee80b6b2f0e19cce544245479adde7baa65466664d5f3", size = 10655535, upload-time = "2026-04-16T18:46:12.47Z" },
-    { url = "https://files.pythonhosted.org/packages/3a/5e/c927b325bd4c1d3620211a4b96f47864633199feed60fa936025ab27e090/ruff-0.15.11-py3-none-win_amd64.whl", hash = "sha256:8b6756d88d7e234fb0c98c91511aae3cd519d5e3ed271cae31b20f39cb2a12a3", size = 11779692, upload-time = "2026-04-16T18:46:17.268Z" },
-    { url = "https://files.pythonhosted.org/packages/63/b6/aeadee5443e49baa2facd51131159fd6301cc4ccfc1541e4df7b021c37dd/ruff-0.15.11-py3-none-win_arm64.whl", hash = "sha256:063fed18cc1bbe0ee7393957284a6fe8b588c6a406a285af3ee3f46da2391ee4", size = 11032614, upload-time = "2026-04-16T18:46:34.487Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/00/a1c2fdc9939b2c03691edbda290afcd297f1f389196172826b03d6b6a595/ruff-0.15.10-py3-none-linux_armv6l.whl", hash = "sha256:0744e31482f8f7d0d10a11fcbf897af272fefdfcb10f5af907b18c2813ff4d5f", size = 10563362, upload-time = "2026-04-09T14:06:21.189Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/15/006990029aea0bebe9d33c73c3e28c80c391ebdba408d1b08496f00d422d/ruff-0.15.10-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:b1e7c16ea0ff5a53b7c2df52d947e685973049be1cdfe2b59a9c43601897b22e", size = 10951122, upload-time = "2026-04-09T14:06:02.236Z" },
+    { url = "https://files.pythonhosted.org/packages/f2/c0/4ac978fe874d0618c7da647862afe697b281c2806f13ce904ad652fa87e4/ruff-0.15.10-py3-none-macosx_11_0_arm64.whl", hash = "sha256:93cc06a19e5155b4441dd72808fdf84290d84ad8a39ca3b0f994363ade4cebb1", size = 10314005, upload-time = "2026-04-09T14:06:00.026Z" },
+    { url = "https://files.pythonhosted.org/packages/da/73/c209138a5c98c0d321266372fc4e33ad43d506d7e5dd817dd89b60a8548f/ruff-0.15.10-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:83e1dd04312997c99ea6965df66a14fb4f03ba978564574ffc68b0d61fd3989e", size = 10643450, upload-time = "2026-04-09T14:05:42.137Z" },
+    { url = "https://files.pythonhosted.org/packages/ec/76/0deec355d8ec10709653635b1f90856735302cb8e149acfdf6f82a5feb70/ruff-0.15.10-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:8154d43684e4333360fedd11aaa40b1b08a4e37d8ffa9d95fee6fa5b37b6fab1", size = 10379597, upload-time = "2026-04-09T14:05:49.984Z" },
+    { url = "https://files.pythonhosted.org/packages/dc/be/86bba8fc8798c081e28a4b3bb6d143ccad3fd5f6f024f02002b8f08a9fa3/ruff-0.15.10-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:8ab88715f3a6deb6bde6c227f3a123410bec7b855c3ae331b4c006189e895cef", size = 11146645, upload-time = "2026-04-09T14:06:12.246Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/89/140025e65911b281c57be1d385ba1d932c2366ca88ae6663685aed8d4881/ruff-0.15.10-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:a768ff5969b4f44c349d48edf4ab4f91eddb27fd9d77799598e130fb628aa158", size = 12030289, upload-time = "2026-04-09T14:06:04.776Z" },
+    { url = "https://files.pythonhosted.org/packages/88/de/ddacca9545a5e01332567db01d44bd8cf725f2db3b3d61a80550b48308ea/ruff-0.15.10-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:0ee3ef42dab7078bda5ff6a1bcba8539e9857deb447132ad5566a038674540d0", size = 11496266, upload-time = "2026-04-09T14:05:55.485Z" },
+    { url = "https://files.pythonhosted.org/packages/bc/bb/7ddb00a83760ff4a83c4e2fc231fd63937cc7317c10c82f583302e0f6586/ruff-0.15.10-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:51cb8cc943e891ba99989dd92d61e29b1d231e14811db9be6440ecf25d5c1609", size = 11256418, upload-time = "2026-04-09T14:05:57.69Z" },
+    { url = "https://files.pythonhosted.org/packages/dc/8d/55de0d35aacf6cd50b6ee91ee0f291672080021896543776f4170fc5c454/ruff-0.15.10-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:e59c9bdc056a320fb9ea1700a8d591718b8faf78af065484e801258d3a76bc3f", size = 11288416, upload-time = "2026-04-09T14:05:44.695Z" },
+    { url = "https://files.pythonhosted.org/packages/68/cf/9438b1a27426ec46a80e0a718093c7f958ef72f43eb3111862949ead3cc1/ruff-0.15.10-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:136c00ca2f47b0018b073f28cb5c1506642a830ea941a60354b0e8bc8076b151", size = 10621053, upload-time = "2026-04-09T14:05:52.782Z" },
+    { url = "https://files.pythonhosted.org/packages/4c/50/e29be6e2c135e9cd4cb15fbade49d6a2717e009dff3766dd080fcb82e251/ruff-0.15.10-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:8b80a2f3c9c8a950d6237f2ca12b206bccff626139be9fa005f14feb881a1ae8", size = 10378302, upload-time = "2026-04-09T14:06:14.361Z" },
+    { url = "https://files.pythonhosted.org/packages/18/2f/e0b36a6f99c51bb89f3a30239bc7bf97e87a37ae80aa2d6542d6e5150364/ruff-0.15.10-py3-none-musllinux_1_2_i686.whl", hash = "sha256:e3e53c588164dc025b671c9df2462429d60357ea91af7e92e9d56c565a9f1b07", size = 10850074, upload-time = "2026-04-09T14:06:16.581Z" },
+    { url = "https://files.pythonhosted.org/packages/11/08/874da392558ce087a0f9b709dc6ec0d60cbc694c1c772dab8d5f31efe8cb/ruff-0.15.10-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:b0c52744cf9f143a393e284125d2576140b68264a93c6716464e129a3e9adb48", size = 11358051, upload-time = "2026-04-09T14:06:18.948Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/46/602938f030adfa043e67112b73821024dc79f3ab4df5474c25fa4c1d2d14/ruff-0.15.10-py3-none-win32.whl", hash = "sha256:d4272e87e801e9a27a2e8df7b21011c909d9ddd82f4f3281d269b6ba19789ca5", size = 10588964, upload-time = "2026-04-09T14:06:07.14Z" },
+    { url = "https://files.pythonhosted.org/packages/25/b6/261225b875d7a13b33a6d02508c39c28450b2041bb01d0f7f1a83d569512/ruff-0.15.10-py3-none-win_amd64.whl", hash = "sha256:28cb32d53203242d403d819fd6983152489b12e4a3ae44993543d6fe62ab42ed", size = 11745044, upload-time = "2026-04-09T14:05:39.473Z" },
+    { url = "https://files.pythonhosted.org/packages/58/ed/dea90a65b7d9e69888890fb14c90d7f51bf0c1e82ad800aeb0160e4bacfd/ruff-0.15.10-py3-none-win_arm64.whl", hash = "sha256:601d1610a9e1f1c2165a4f561eeaa2e2ea1e97f3287c5aa258d3dab8b57c6188", size = 11035607, upload-time = "2026-04-09T14:05:47.593Z" },
 ]
 
 [[package]]
@@ -5418,15 +5268,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/4c/a7/563b2d8fb7edc07320bf69ac6a7eedcd7a1a9d663a6bb90a4d9bd2eda5f7/unpaddedbase64-2.1.0-py3-none-any.whl", hash = "sha256:485eff129c30175d2cd6f0cd8d2310dff51e666f7f36175f738d75dfdbd0b1c6", size = 6083, upload-time = "2021-03-09T11:35:46.7Z" },
 ]
 
-[[package]]
-name = "uritemplate"
-version = "4.2.0"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/98/60/f174043244c5306c9988380d2cb10009f91563fc4b31293d27e17201af56/uritemplate-4.2.0.tar.gz", hash = "sha256:480c2ed180878955863323eea31b0ede668795de182617fef9c6ca09e6ec9d0e", size = 33267, upload-time = "2025-06-02T15:12:06.318Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/a9/99/3ae339466c9183ea5b8ae87b34c0b897eda475d2aec2307cae60e5cd4f29/uritemplate-4.2.0-py3-none-any.whl", hash = "sha256:962201ba1c4edcab02e60f9a0d3821e82dfc5d2d6662a21abd533879bdb8a686", size = 11488, upload-time = "2025-06-02T15:12:03.405Z" },
-]
-
 [[package]]
 name = "urllib3"
 version = "2.6.3"

web/src/i18n/en.ts

@@ -237,6 +237,9 @@ export const en: Translations = {
     exportConfig: "Export config as JSON",
     importConfig: "Import config from JSON",
     resetDefaults: "Reset to defaults",
+    resetScopeTooltip: "Reset {scope} to defaults",
+    confirmResetScope: "Reset all {scope} settings to their defaults? This only updates the form — changes aren't written to config.yaml until you press Save.",
+    resetScopeToast: "{scope} reset to defaults — review and Save to persist",
     rawYaml: "Raw YAML Configuration",
     searchResults: "Search Results",
     fields: "field{s}",

web/src/i18n/types.ts

@@ -242,6 +242,9 @@ export interface Translations {
     exportConfig: string;
     importConfig: string;
     resetDefaults: string;
+    resetScopeTooltip: string;
+    confirmResetScope: string;
+    resetScopeToast: string;
     rawYaml: string;
     searchResults: string;
     fields: string;

web/src/i18n/zh.ts

@@ -234,6 +234,9 @@ export const zh: Translations = {
     exportConfig: "导出配置为 JSON",
     importConfig: "从 JSON 导入配置",
     resetDefaults: "恢复默认值",
+    resetScopeTooltip: "将{scope}恢复为默认值",
+    confirmResetScope: "确定要将{scope}的所有设置恢复为默认值吗？此操作仅更新表单，在按下「保存」按钮前不会写入 config.yaml。",
+    resetScopeToast: "{scope}已恢复为默认值 — 请检查并保存以生效",
     rawYaml: "原始 YAML 配置",
     searchResults: "搜索结果",
     fields: "个字段",

web/src/pages/ConfigPage.tsx

@@ -228,7 +228,26 @@ export default function ConfigPage() {
   };
 
   const handleReset = () => {
-    if (defaults) setConfig(structuredClone(defaults));
+    if (!defaults || !config) return;
+    // Scope the reset to what the user is currently looking at:
+    //   - search mode → the matched fields
+    //   - form mode   → the active category's fields
+    // Resetting the whole config here was a footgun (issue reported by @ykmfb001):
+    // the button sits next to the category tabs and users reasonably assumed
+    // "reset this tab", not "wipe my entire config.yaml".
+    const scopedFields = isSearching ? searchMatchedFields : activeFields;
+    if (scopedFields.length === 0) return;
+    const scopeLabel = isSearching
+      ? t.config.searchResults
+      : prettyCategoryName(activeCategory);
+    const message = t.config.confirmResetScope.replace("{scope}", scopeLabel);
+    if (!window.confirm(message)) return;
+    let next: Record<string, unknown> = config;
+    for (const [key] of scopedFields) {
+      next = setNestedValue(next, key, getNestedValue(defaults, key));
+    }
+    setConfig(next);
+    showToast(t.config.resetScopeToast.replace("{scope}", scopeLabel), "success");
   };
 
   const handleExport = () => {
@@ -333,9 +352,17 @@ export default function ConfigPage() {
             <Upload className="h-3.5 w-3.5" />
           </Button>
           <input ref={fileInputRef} type="file" accept=".json" className="hidden" onChange={handleImport} />
-          <Button variant="ghost" size="sm" onClick={handleReset} title={t.config.resetDefaults} aria-label={t.config.resetDefaults}>
-            <RotateCcw className="h-3.5 w-3.5" />
-          </Button>
+          {!yamlMode && (() => {
+            const resetScopeLabel = isSearching
+              ? t.config.searchResults
+              : prettyCategoryName(activeCategory);
+            const resetTitle = t.config.resetScopeTooltip.replace("{scope}", resetScopeLabel);
+            return (
+              <Button variant="ghost" size="sm" onClick={handleReset} title={resetTitle} aria-label={resetTitle}>
+                <RotateCcw className="h-3.5 w-3.5" />
+              </Button>
+            );
+          })()}
 
           <div className="w-px h-5 bg-border mx-1" />
 

website/docs/developer-guide/adding-providers.md

@@ -93,42 +93,6 @@ This path includes everything from Path A plus:
 11. `run_agent.py`
 12. `pyproject.toml` if a provider SDK is required
 
-## Fast path: Simple API-key providers
-
-If your provider is just an OpenAI-compatible endpoint that authenticates with a single API key, you do not need to touch `auth.py`, `runtime_provider.py`, `main.py`, or any of the other files in the full checklist below.
-
-All you need is:
-
-1. A file in `providers/` (e.g. `providers/myprovider.py`) that calls `register_provider()` with the provider config.
-2. That's it. `auth.py` auto-registers every file in `providers/` at startup via a module-level import sweep.
-
-When you add a `providers/*.py` file and call `register_provider()`, the following wire up automatically:
-
-1. `PROVIDER_REGISTRY` entry in `auth.py` (credential resolution, env-var lookup)
-2. `api_mode` set to `chat_completions`
-3. `base_url` sourced from the config or the declared env var
-4. `env_vars` checked in priority order for the API key
-5. `fallback_models` list registered for the provider
-6. `--provider` CLI flag accepts the provider id
-7. `hermes model` menu includes the provider
-8. `hermes setup` wizard delegates to `main.py` automatically
-9. `provider:model` alias syntax works
-10. Runtime resolver returns the correct `base_url` and `api_key`
-11. `HERMES_INFERENCE_PROVIDER` env-var override accepts the provider id
-12. Fallback model activation can switch into the provider cleanly
-
-See `providers/nvidia.py` or `providers/gmi.py` as a template.
-
-## Full path: OAuth and complex providers
-
-Use the full checklist below when your provider needs any of the following:
-
-- OAuth or token refresh (Nous Portal, Codex, Google Gemini, Qwen Portal, Copilot)
-- A non-OpenAI API shape that requires a new adapter (Anthropic Messages, Codex Responses)
-- Custom endpoint detection or multi-region probing (z.ai, Kimi)
-- A curated static model catalog or live `/models` fetch
-- Provider-specific `hermes model` menu entries with bespoke auth flows
-
 ## Step 1: Pick one canonical provider id
 
 Choose a single provider id and use it everywhere.

website/docs/developer-guide/provider-runtime.md

@@ -20,9 +20,6 @@ Primary implementation:
 - `hermes_cli/auth.py` — provider registry, `resolve_provider()`
 - `hermes_cli/model_switch.py` — shared `/model` switch pipeline (CLI + gateway)
 - `agent/auxiliary_client.py` — auxiliary model routing
-- `providers/` — declarative source for `api_mode`, `base_url`, `env_vars`, `fallback_models` (auto-registered into `auth.py` `PROVIDER_REGISTRY` at startup)
-
-`get_provider_profile()` in `providers/` returns a typed dict for a given provider id. `runtime_provider.py` calls this at resolution time to get the canonical `base_url`, `env_vars` priority list, `api_mode`, and `fallback_models` without needing to duplicate that data in multiple files. Adding a new `providers/*.py` file that calls `register_provider()` is enough for `runtime_provider.py` to pick it up — no branch needed in the resolver itself.
 
 If you are trying to add a new first-class inference provider, read [Adding Providers](./adding-providers.md) alongside this page.
 

website/docs/integrations/providers.md

@@ -423,44 +423,6 @@ model:
 For on-prem deployments (DGX Spark, local GPU), set `NVIDIA_BASE_URL=http://localhost:8000/v1`. NIM exposes the same OpenAI-compatible chat completions API as build.nvidia.com, so switching between cloud and local is a one-line env-var change.
 :::
 
-### GMI Cloud
-
-Open and reasoning models via [GMI Cloud](https://inference.gmi.ai) — OpenAI-compatible API, API key authentication.
-
-```bash
-# GMI Cloud
-hermes chat --provider gmi --model deepseek-ai/DeepSeek-R1
-# Requires: GMI_API_KEY in ~/.hermes/.env
-```
-
-Or set it permanently in `config.yaml`:
-```yaml
-model:
-  provider: "gmi"
-  default: "deepseek-ai/DeepSeek-R1"
-```
-
-The base URL can be overridden with `GMI_BASE_URL` (default: `https://api.gmi.ai/v1`).
-
-### StepFun
-
-Step-series models via [StepFun](https://platform.stepfun.com) — OpenAI-compatible API, API key authentication.
-
-```bash
-# StepFun
-hermes chat --provider stepfun --model step-3-mini
-# Requires: STEPFUN_API_KEY in ~/.hermes/.env
-```
-
-Or set it permanently in `config.yaml`:
-```yaml
-model:
-  provider: "stepfun"
-  default: "step-3-mini"
-```
-
-The base URL can be overridden with `STEPFUN_BASE_URL` (default: `https://api.stepfun.com/v1`).
-
 ### Hugging Face Inference Providers
 
 [Hugging Face Inference Providers](https://huggingface.co/docs/inference-providers) routes to 20+ open models through a unified OpenAI-compatible endpoint (`router.huggingface.co/v1`). Requests are automatically routed to the fastest available backend (Groq, Together, SambaNova, etc.) with automatic failover.
@@ -1216,7 +1178,7 @@ fallback_model:
 
 When activated, the fallback swaps the model and provider mid-session without losing your conversation. It fires **at most once** per session.
 
-Supported providers: `openrouter`, `nous`, `openai-codex`, `copilot`, `copilot-acp`, `anthropic`, `gemini`, `google-gemini-cli`, `qwen-oauth`, `huggingface`, `zai`, `kimi-coding`, `kimi-coding-cn`, `minimax`, `minimax-cn`, `deepseek`, `nvidia`, `gmi`, `stepfun`, `xai`, `ollama-cloud`, `bedrock`, `ai-gateway`, `opencode-zen`, `opencode-go`, `kilocode`, `xiaomi`, `arcee`, `alibaba`, `custom`.
+Supported providers: `openrouter`, `nous`, `openai-codex`, `copilot`, `copilot-acp`, `anthropic`, `gemini`, `google-gemini-cli`, `qwen-oauth`, `huggingface`, `zai`, `kimi-coding`, `kimi-coding-cn`, `minimax`, `minimax-cn`, `deepseek`, `nvidia`, `xai`, `ollama-cloud`, `bedrock`, `ai-gateway`, `opencode-zen`, `opencode-go`, `kilocode`, `xiaomi`, `arcee`, `gmi`, `alibaba`, `custom`.
 
 :::tip
 Fallback is configured exclusively through `config.yaml` — there are no environment variables for it. For full details on when it triggers, supported providers, and how it interacts with auxiliary tasks and delegation, see [Fallback Providers](/docs/user-guide/features/fallback-providers).

website/docs/reference/environment-variables.md

@@ -65,10 +65,6 @@ All variables go in `~/.hermes/.env`. You can also set them with `hermes config
 | `DEEPSEEK_BASE_URL` | Custom DeepSeek API base URL |
 | `NVIDIA_API_KEY` | NVIDIA NIM API key — Nemotron and open models ([build.nvidia.com](https://build.nvidia.com)) |
 | `NVIDIA_BASE_URL` | Override NVIDIA base URL (default: `https://integrate.api.nvidia.com/v1`; set to `http://localhost:8000/v1` for a local NIM endpoint) |
-| `GMI_API_KEY` | GMI Cloud API key — open and reasoning models ([inference.gmi.ai](https://inference.gmi.ai)) |
-| `GMI_BASE_URL` | Override GMI Cloud base URL (default: `https://api.gmi.ai/v1`) |
-| `STEPFUN_API_KEY` | StepFun API key — Step-series models ([platform.stepfun.com](https://platform.stepfun.com)) |
-| `STEPFUN_BASE_URL` | Override StepFun base URL (default: `https://api.stepfun.com/v1`) |
 | `OLLAMA_API_KEY` | Ollama Cloud API key — managed Ollama catalog without local GPU ([ollama.com/settings/keys](https://ollama.com/settings/keys)) |
 | `OLLAMA_BASE_URL` | Override Ollama Cloud base URL (default: `https://ollama.com/v1`) |
 | `XAI_API_KEY` | xAI (Grok) API key for chat + TTS ([console.x.ai](https://console.x.ai/)) |
@@ -95,7 +91,7 @@ For native Anthropic auth, Hermes prefers Claude Code's own credential files whe
 
 | Variable | Description |
 |----------|-------------|
-| `HERMES_INFERENCE_PROVIDER` | Override provider selection: `auto`, `custom`, `openrouter`, `nous`, `openai-codex`, `copilot`, `copilot-acp`, `anthropic`, `huggingface`, `gemini`, `zai`, `kimi-coding`, `kimi-coding-cn`, `minimax`, `minimax-cn`, `kilocode`, `xiaomi`, `arcee`, `gmi`, `stepfun`, `alibaba`, `deepseek`, `nvidia`, `ollama-cloud`, `xai` (alias `grok`), `google-gemini-cli`, `qwen-oauth`, `bedrock`, `opencode-zen`, `opencode-go`, `ai-gateway` (default: `auto`) |
+| `HERMES_INFERENCE_PROVIDER` | Override provider selection: `auto`, `custom`, `openrouter`, `nous`, `openai-codex`, `copilot`, `copilot-acp`, `anthropic`, `huggingface`, `gemini`, `zai`, `kimi-coding`, `kimi-coding-cn`, `minimax`, `minimax-cn`, `kilocode`, `xiaomi`, `arcee`, `gmi`, `alibaba`, `deepseek`, `nvidia`, `ollama-cloud`, `xai` (alias `grok`), `google-gemini-cli`, `qwen-oauth`, `bedrock`, `opencode-zen`, `opencode-go`, `ai-gateway` (default: `auto`) |
 | `HERMES_PORTAL_BASE_URL` | Override Nous Portal URL (for development/testing) |
 | `NOUS_INFERENCE_BASE_URL` | Override Nous inference API URL |
 | `HERMES_NOUS_MIN_KEY_TTL_SECONDS` | Min agent key TTL before re-mint (default: 1800 = 30min) |

website/docs/user-guide/configuration.md

@@ -1313,7 +1313,7 @@ Pre-execution security scanning and secret redaction:
 
 ```yaml
 security:
-  redact_secrets: true           # Redact API key patterns in tool output and logs
+  redact_secrets: false          # Redact API key patterns in tool output and logs (off by default)
   tirith_enabled: true           # Enable Tirith security scanning for terminal commands
   tirith_path: "tirith"          # Path to tirith binary (default: "tirith" in $PATH)
   tirith_timeout: 5              # Seconds to wait for tirith scan before timing out
@@ -1324,7 +1324,7 @@ security:
     shared_files: []
 ```
 
-- `redact_secrets` — automatically detects and redacts patterns that look like API keys, tokens, and passwords in tool output before it enters the conversation context and logs.
+- `redact_secrets` — when `true`, automatically detects and redacts patterns that look like API keys, tokens, and passwords in tool output before it enters the conversation context and logs. **Off by default** — enable if you commonly work with real credentials in tool output and want a safety net. Set to `true` explicitly to turn on.
 - `tirith_enabled` — when `true`, terminal commands are scanned by [Tirith](https://github.com/StackGuardian/tirith) before execution to detect potentially dangerous operations.
 - `tirith_path` — path to the tirith binary. Set this if tirith is installed in a non-standard location.
 - `tirith_timeout` — maximum seconds to wait for a tirith scan. Commands proceed if the scan times out.

website/docs/user-guide/features/fallback-providers.md

@@ -48,8 +48,6 @@ Both `provider` and `model` are **required**. If either is missing, the fallback
 | MiniMax (China) | `minimax-cn` | `MINIMAX_CN_API_KEY` |
 | DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` |
 | NVIDIA NIM | `nvidia` | `NVIDIA_API_KEY` (optional: `NVIDIA_BASE_URL`) |
-| GMI Cloud | `gmi` | `GMI_API_KEY` (optional: `GMI_BASE_URL`) |
-| StepFun | `stepfun` | `STEPFUN_API_KEY` (optional: `STEPFUN_BASE_URL`) |
 | Ollama Cloud | `ollama-cloud` | `OLLAMA_API_KEY` |
 | Google Gemini (OAuth) | `google-gemini-cli` | `hermes model` (Google OAuth; optional: `HERMES_GEMINI_PROJECT_ID`) |
 | Google AI Studio | `gemini` | `GOOGLE_API_KEY` (alias: `GEMINI_API_KEY`) |