diff --git a/acp_adapter/entry.py b/acp_adapter/entry.py
index fb9ed95450c3d..7b549006bc274 100644
--- a/acp_adapter/entry.py
+++ b/acp_adapter/entry.py
@@ -247,16 +247,22 @@ def main(argv: list[str] | None = None) -> None:
import acp
from .server import HermesACPAgent
- # MCP tool discovery from config.yaml — run before asyncio.run() so
- # it's safe to use blocking waits. (ACP also registers per-session
- # MCP servers dynamically via asyncio.to_thread inside the event
- # loop; that path is unaffected.) Moved from model_tools.py module
- # scope to avoid freezing the gateway's loop on lazy import (#16856).
+ # MCP tool discovery from config.yaml — fire-and-forget in a
+ # background daemon thread so the ACP server becomes responsive
+ # immediately while MCP servers connect. Previously this blocked
+ # asyncio.run() for 2-5 s. (ACP also registers per-session MCP
+ # servers dynamically via asyncio.to_thread inside the event loop;
+ # that path is unaffected.) Moved from model_tools.py module scope
+ # to avoid freezing the gateway's loop on lazy import (#16856).
# Metadata-only hosts can opt out of unrelated global MCP startup.
if os.environ.get("HERMES_ACP_SKIP_CONFIGURED_MCP", "").strip() != "1":
try:
- from tools.mcp_tool import discover_mcp_tools
- discover_mcp_tools()
+ from hermes_cli.mcp_startup import start_background_mcp_discovery
+
+ start_background_mcp_discovery(
+ logger=logger,
+ thread_name="acp-mcp-discovery",
+ )
except Exception:
logger.debug("MCP tool discovery failed at ACP startup", exc_info=True)
diff --git a/acp_adapter/server.py b/acp_adapter/server.py
index 1b0046fe32c0a..65241f6978dde 100644
--- a/acp_adapter/server.py
+++ b/acp_adapter/server.py
@@ -1037,6 +1037,102 @@ class HermesACPAgent(acp.Agent):
exc_info=True,
)
+ def _schedule_mcp_late_refresh(self, state: SessionState) -> None:
+ """Refresh the agent's tool snapshot when background MCP discovery lands late.
+
+ ACP entry.py starts MCP tool discovery in a background daemon thread so a
+ slow/dead configured server can't block ``asyncio.run()``. ``_make_agent``
+ briefly joins that thread (``wait_for_mcp_discovery``, bounded ~1.5s) so
+ already-spawning fast servers land in the snapshot — but a server slower
+ than the bound lands *after* the agent is built, leaving its tools absent
+ for the whole session.
+
+ This schedules an off-critical-path daemon that waits for discovery to
+ finish (bounded 30s), then rebuilds the snapshot via the shared
+ ``refresh_agent_mcp_tools`` helper — the same rebuild ``/reload-mcp``
+ performs, but automatic. Mirrors the TUI late-refresh (PR #48403).
+
+ Cache safety: the rebuild only runs while the session is still
+ pre-first-turn (no API call made yet → nothing cached to invalidate).
+ Once the user has sent a message we leave the snapshot frozen rather
+ than break the cached prompt prefix mid-conversation; servers that land
+ later are picked up cache-safely by the between-turns prologue refresh
+ (``agent/turn_context.py``) at the next turn boundary. The marginal
+ value of this pre-first-turn daemon is therefore freshness in the
+ window [session created → first message] — e.g. the "Available tools"
+ listing a client may request before the first prompt.
+ No-op when discovery already finished, when the join times out, when the
+ registry was unchanged, or when the session was closed while waiting.
+ """
+ try:
+ from hermes_cli.mcp_startup import mcp_discovery_in_flight
+ except Exception:
+ return
+ if not mcp_discovery_in_flight():
+ return
+
+ import threading
+
+ agent = state.agent
+ session_id = state.session_id
+
+ def _wait_then_refresh() -> None:
+ try:
+ from hermes_cli.mcp_startup import join_mcp_discovery
+
+ if not join_mcp_discovery(timeout=30.0):
+ return
+
+ # Session may have been closed while we waited. In-memory-only
+ # lookup on purpose: ``get_session()`` falls through to a DB
+ # restore that builds a whole new AIAgent as a side effect just
+ # to decide "no-op" here (the TUI equivalent also checks its
+ # in-memory dict only).
+ with self.session_manager._lock:
+ current = self.session_manager._sessions.get(session_id)
+ if current is None or current.agent is not agent:
+ return
+
+ # Cache safety: never rebuild the tool list once the conversation
+ # has started — that would invalidate the cached prompt prefix.
+ # Serialized with turn start: ``prompt()`` flips ``is_running``
+ # under ``runtime_lock`` before dispatching, so holding it here
+ # (and bailing when a turn is already running) closes the window
+ # where the guard passes but the first prompt starts before the
+ # refresh publishes — which would swap ``tools=`` mid-turn and
+ # break the just-created cache prefix.
+ with current.runtime_lock:
+ if current.is_running:
+ return
+ if (
+ int(getattr(agent, "_user_turn_count", 0) or 0) > 0
+ or int(getattr(agent, "_api_call_count", 0) or 0) > 0
+ ):
+ return
+
+ from tools.mcp_tool import refresh_agent_mcp_tools
+
+ added = refresh_agent_mcp_tools(agent, quiet_mode=True)
+ if added:
+ logger.info(
+ "Session %s: late MCP refresh added %d tools: %s",
+ session_id,
+ len(added),
+ ", ".join(sorted(added)),
+ )
+ except Exception:
+ logger.debug(
+ "Session %s: late MCP refresh failed",
+ session_id,
+ exc_info=True,
+ )
+
+ threading.Thread(
+ target=_wait_then_refresh,
+ name=f"acp-mcp-late-refresh-{session_id}",
+ daemon=True,
+ ).start()
+
# ---- ACP lifecycle ------------------------------------------------------
async def initialize(
@@ -1343,6 +1439,7 @@ class HermesACPAgent(acp.Agent):
) -> NewSessionResponse:
state = self.session_manager.create_session(cwd=cwd)
await self._register_session_mcp_servers(state, mcp_servers)
+ self._schedule_mcp_late_refresh(state)
logger.info("New session %s (cwd=%s)", state.session_id, cwd)
self._schedule_available_commands_update(state.session_id)
self._schedule_usage_update(state)
@@ -1367,6 +1464,7 @@ class HermesACPAgent(acp.Agent):
logger.warning("load_session: session %s not found", session_id)
return None
await self._register_session_mcp_servers(state, mcp_servers)
+ self._schedule_mcp_late_refresh(state)
logger.info("Loaded session %s", session_id)
# Per ACP spec, `session/load` must stream the prior conversation back
# to the client via `session/update` notifications BEFORE responding,
@@ -1414,6 +1512,7 @@ class HermesACPAgent(acp.Agent):
logger.warning("resume_session: session %s not found, creating new", session_id)
state = self.session_manager.create_session(cwd=cwd)
await self._register_session_mcp_servers(state, mcp_servers)
+ self._schedule_mcp_late_refresh(state)
logger.info("Resumed session %s", state.session_id)
# See `load_session` above for the spec rationale — replay must
# complete before the response so clients receive the full transcript
diff --git a/acp_adapter/session.py b/acp_adapter/session.py
index 6f1e17a07f57a..6e16016a6b3bb 100644
--- a/acp_adapter/session.py
+++ b/acp_adapter/session.py
@@ -648,6 +648,30 @@ class SessionManager:
logger.debug("ACP session falling back to default provider resolution", exc_info=True)
_register_task_cwd(session_id, cwd)
+
+ # Bounded wait for background MCP discovery so already-spawning fast
+ # servers land in the agent's tool snapshot. ACP entry.py fires
+ # discovery in a background daemon thread (start_background_mcp_discovery);
+ # the agent snapshots tools once at build (run_agent/agent_init) and
+ # never re-reads the registry, so without this join a reachable-but-
+ # slow configured server would be invisible for the whole session.
+ # ``ensure_mcp_discovery_before_agent_build`` also (re)starts discovery
+ # when the entry.py spawn never ran or exited with zero connected
+ # servers (the retry-after-zero-connected allowance), making this
+ # construction site self-sufficient. Bounded by
+ # ``mcp_discovery_timeout`` (config.yaml, default ~1.5s) so a dead
+ # server can't block — servers that miss the bound are picked up by
+ # the automatic late-refresh (see HermesACPAgent._schedule_mcp_late_refresh).
+ try:
+ from hermes_cli.mcp_startup import ensure_mcp_discovery_before_agent_build
+
+ ensure_mcp_discovery_before_agent_build(
+ logger=logger,
+ thread_name="acp-mcp-discovery",
+ )
+ except Exception:
+ logger.debug("ACP: bounded MCP discovery wait failed", exc_info=True)
+
agent = AIAgent(**kwargs)
# Codex app-server sessions are spawned lazily on the first turn. Stamp
# the ACP workspace onto the agent so the Codex runtime starts from the
diff --git a/agent/agent_init.py b/agent/agent_init.py
index ef3199cb83749..f0fbffe17cdb0 100644
--- a/agent/agent_init.py
+++ b/agent/agent_init.py
@@ -834,10 +834,19 @@ def init_agent(
agent._use_prompt_caching, agent._use_native_cache_layout = (
agent._anthropic_prompt_cache_policy()
)
+ agent._cache_disabled = False
# Anthropic supports "5m" (default) and "1h" cache TTL tiers. Read from
# config.yaml under prompt_caching.cache_ttl; unknown values keep "5m".
# 1h tier costs 2x on write vs 1.25x for 5m, but amortizes across long
# sessions with >5-minute pauses between turns (#14971).
+ #
+ # Setting cache_ttl to a falsy value (false / null / "off" / "disabled" /
+ # "no" / "none") disables prompt caching entirely. This is useful for
+ # OAuth subscription users where cache writes bill against "extra usage"
+ # or for third-party proxies that inject their own cache_control markers
+ # (#13477). The disable propagates through anthropic_prompt_cache_policy()
+ # and restore_primary_runtime() so it survives /model switches and
+ # fallback re-derivation (#33555).
agent._cache_ttl = "5m"
try:
from hermes_cli.config import load_config_readonly as _load_pc_cfg
@@ -846,6 +855,15 @@ def init_agent(
_ttl = _pc_cfg.get("cache_ttl", "5m")
if _ttl in {"5m", "1h"}:
agent._cache_ttl = _ttl
+ elif (
+ _ttl is False
+ or _ttl is None
+ or str(_ttl).lower() in ("off", "false", "disabled", "no", "none")
+ ):
+ agent._use_prompt_caching = False
+ agent._use_native_cache_layout = False
+ agent._cache_ttl = None
+ agent._cache_disabled = True
except Exception:
pass
diff --git a/agent/agent_runtime_helpers.py b/agent/agent_runtime_helpers.py
index 5f72bedfb5628..2aba754b5fd7c 100644
--- a/agent/agent_runtime_helpers.py
+++ b/agent/agent_runtime_helpers.py
@@ -1475,6 +1475,12 @@ def restore_primary_runtime(agent) -> bool:
"use_native_cache_layout",
agent.api_mode == "anthropic_messages" and agent.provider == "anthropic",
)
+ # If the operator has disabled caching via config (cache_ttl is
+ # falsy → _cache_disabled flag is set), the disable must survive
+ # runtime snapshot restoration (#33555).
+ if getattr(agent, "_cache_disabled", False):
+ agent._use_prompt_caching = False
+ agent._use_native_cache_layout = False
# ── Rebuild client for the primary provider ──
if agent.provider == "moa":
@@ -1834,6 +1840,23 @@ def dump_api_request_debug(
+def _direct_native_anthropic_tool_cache_capability(
+ agent,
+ *,
+ provider: Optional[str] = None,
+ base_url: Optional[str] = None,
+ api_mode: Optional[str] = None,
+ model: Optional[str] = None,
+) -> bool:
+ """Return whether this resolved destination accepts native tool markers."""
+ eff_base_url = base_url if base_url is not None else (agent.base_url or "")
+ eff_api_mode = api_mode if api_mode is not None else (agent.api_mode or "")
+ return (
+ eff_api_mode == "anthropic_messages"
+ and base_url_hostname(eff_base_url) == "api.anthropic.com"
+ )
+
+
def anthropic_prompt_cache_policy(
agent,
*,
@@ -1866,7 +1889,19 @@ def anthropic_prompt_cache_policy(
documented this for opencode-go Qwen; #24617 reports the same gateway
contract for DeepSeek. Without markers these providers serve zero cache
hits, re-billing the full prompt on every turn.
+
+ If the operator has set ``prompt_caching.cache_ttl`` to a falsy value
+ (``false``, ``null``, ``"off"``, etc.) in config.yaml, prompt caching
+ is fully disabled — this early return ensures the disable survives
+ ``/model`` switches, fallback re-derivation, and runtime snapshot
+ restoration (#33555). We check ``"_cache_disabled"`` (set by
+ init_agent when the disable is detected) rather than ``_cache_ttl``
+ directly, because ``_cache_ttl`` is not yet set when the policy runs
+ during the initial ``init_agent`` call.
"""
+ if getattr(agent, "_cache_disabled", False):
+ return (False, False)
+
eff_provider = (provider if provider is not None else agent.provider) or ""
eff_base_url = base_url if base_url is not None else (agent.base_url or "")
eff_api_mode = api_mode if api_mode is not None else (agent.api_mode or "")
diff --git a/agent/auxiliary_client.py b/agent/auxiliary_client.py
index 88b206be7c373..9d26d1bf611b4 100644
--- a/agent/auxiliary_client.py
+++ b/agent/auxiliary_client.py
@@ -42,6 +42,7 @@ Payment / credit exhaustion fallback:
import contextlib
import contextvars
+import copy
import functools
import hashlib
import inspect
@@ -54,7 +55,7 @@ import time
import uuid
from pathlib import Path # noqa: F401 — used by test mocks
from types import SimpleNamespace
-from typing import Any, Callable, Dict, List, Optional, Tuple, TYPE_CHECKING
+from typing import Any, Callable, Dict, List, NamedTuple, Optional, Tuple, TYPE_CHECKING
from urllib.parse import urlparse, parse_qs, urlunparse
# NOTE: `from openai import OpenAI` is deliberately NOT at module top — the
@@ -4214,6 +4215,133 @@ def _fallback_entry_timeout(task: Optional[str], fb_label: str) -> Optional[floa
return None
+def _fallback_provider_from_label(label: str) -> str:
+ """Recover the provider identifier from a fallback display label."""
+ match = re.match(r"(?:fallback_chain\[\d+\]|main-agent)\(([^)]+)\)$", label or "")
+ return match.group(1).strip() if match else str(label or "").strip()
+
+
+class _FallbackDestination(NamedTuple):
+ provider: str
+ base_url: str
+ api_mode: Optional[str]
+ model: Optional[str]
+
+
+def _complete_fallback_destination(
+ provider: str,
+ base_url: str,
+ api_mode: Optional[str],
+ model: Optional[str],
+) -> _FallbackDestination:
+ if not api_mode:
+ if _endpoint_speaks_anthropic_messages(base_url):
+ api_mode = "anthropic_messages"
+ else:
+ try:
+ from hermes_cli.runtime_provider import resolve_runtime_provider
+
+ runtime = resolve_runtime_provider(
+ requested=provider,
+ explicit_base_url=base_url or None,
+ target_model=model or "",
+ )
+ api_mode = str(runtime.get("api_mode") or "").strip() or None
+ except Exception:
+ pass
+ return _FallbackDestination(provider, base_url, api_mode, model)
+
+
+def _fallback_destination_from_entry(
+ entry: Dict[str, Any],
+ fb_client: Any,
+ fb_model: Optional[str],
+) -> _FallbackDestination:
+ provider = str(entry.get("provider") or "").strip()
+ base_url = str(
+ entry.get("base_url") or getattr(fb_client, "base_url", "") or ""
+ ).strip()
+ api_mode = str(
+ entry.get("api_mode") or entry.get("transport") or ""
+ ).strip() or None
+ model = fb_model or str(entry.get("model") or "").strip() or None
+ return _complete_fallback_destination(provider, base_url, api_mode, model)
+
+
+def _fallback_destination(
+ task: Optional[str],
+ fb_client: Any,
+ fb_model: Optional[str],
+ fb_label: str,
+) -> _FallbackDestination:
+ """Return the resolved route identity used by a fallback request."""
+ attached = getattr(fb_client, "_hermes_fallback_destination", None)
+ if isinstance(attached, _FallbackDestination):
+ return attached
+
+ provider = _fallback_provider_from_label(fb_label)
+ base_url = str(getattr(fb_client, "base_url", "") or "")
+ api_mode = None
+ model = fb_model
+
+ match = re.match(r"fallback_chain\[(\d+)\]", fb_label or "")
+ if match and task:
+ try:
+ chain = _get_auxiliary_task_config(task).get("fallback_chain")
+ entry = chain[int(match.group(1))] if isinstance(chain, list) else None
+ except Exception:
+ entry = None
+ if isinstance(entry, dict):
+ return _fallback_destination_from_entry(entry, fb_client, fb_model)
+
+ return _complete_fallback_destination(provider, base_url, api_mode, model)
+
+
+def _replan_synchronous_cache_sections(
+ messages: list,
+ tools: Optional[list],
+ *,
+ destination: _FallbackDestination,
+) -> tuple[list, list]:
+ """Strip source decoration and plan one synchronous destination locally."""
+ from agent.agent_runtime_helpers import (
+ _direct_native_anthropic_tool_cache_capability,
+ anthropic_prompt_cache_policy,
+ )
+ from agent.prompt_caching import (
+ build_prompt_cache_plan,
+ strip_anthropic_cache_control,
+ strip_anthropic_tool_cache_control,
+ )
+
+ canonical_messages = copy.deepcopy(messages or [])
+ strip_anthropic_cache_control(canonical_messages)
+ canonical_tools = strip_anthropic_tool_cache_control(tools)
+ stub = SimpleNamespace(provider="", base_url="", api_mode="", model="")
+ should_cache, native_layout = anthropic_prompt_cache_policy(
+ stub,
+ provider=destination.provider,
+ base_url=destination.base_url,
+ api_mode=destination.api_mode or "",
+ model=destination.model or "",
+ )
+ if not should_cache:
+ return canonical_messages, canonical_tools
+ plan = build_prompt_cache_plan(
+ canonical_messages,
+ canonical_tools,
+ native_anthropic=native_layout,
+ direct_native_tool_cache=_direct_native_anthropic_tool_cache_capability(
+ stub,
+ provider=destination.provider,
+ base_url=destination.base_url,
+ api_mode=destination.api_mode or "",
+ model=destination.model or "",
+ ),
+ )
+ return plan.messages, plan.tools
+
+
def _call_fallback_candidate_sync(
fb_client: Any,
fb_model: Optional[str],
@@ -4256,36 +4384,70 @@ def _call_fallback_candidate_sync(
task or "call", fb_label, fb_timeout, effective_timeout,
)
effective_timeout = fb_timeout
- fb_base = str(getattr(fb_client, "base_url", "") or "")
+ destination = _fallback_destination(task, fb_client, fb_model, fb_label)
+ fallback_messages, fallback_tools = _replan_synchronous_cache_sections(
+ messages,
+ tools,
+ destination=destination,
+ )
fb_kwargs = _build_call_kwargs(
- fb_label, fb_model, messages,
+ destination.provider, destination.model, fallback_messages,
temperature=temperature, max_tokens=max_tokens,
- tools=tools, timeout=effective_timeout,
+ tools=fallback_tools, timeout=effective_timeout,
extra_body=effective_extra_body, reasoning_config=reasoning_config,
- base_url=fb_base, task=task)
+ base_url=destination.base_url, task=task)
try:
return _validate_llm_response(
- _relay_sync_completion(fb_client, fb_kwargs, provider=fb_label), task)
+ _relay_sync_completion(
+ fb_client,
+ fb_kwargs,
+ provider=destination.provider,
+ api_mode=destination.api_mode,
+ ),
+ task,
+ )
except Exception as fb_err:
if not _is_auth_error(fb_err):
raise
- fb_provider = _auth_refresh_provider_for_route(fb_label, fb_base)
+ fb_provider = _auth_refresh_provider_for_route(
+ destination.provider, destination.base_url
+ )
if fb_provider not in {"auto", "", None} and _refresh_provider_credentials(fb_provider):
- retry_client, retry_model = _get_cached_client(fb_provider, fb_model)
+ retry_client, retry_model = _get_cached_client(
+ fb_provider,
+ destination.model,
+ base_url=destination.base_url or None,
+ api_mode=destination.api_mode,
+ )
if retry_client is not None:
+ retry_destination = _FallbackDestination(
+ fb_provider,
+ destination.base_url
+ or str(getattr(retry_client, "base_url", "") or ""),
+ destination.api_mode,
+ retry_model or destination.model,
+ )
+ retry_messages, retry_tools = _replan_synchronous_cache_sections(
+ messages,
+ tools,
+ destination=retry_destination,
+ )
retry_kwargs = _build_call_kwargs(
- fb_provider, retry_model or fb_model, messages,
+ retry_destination.provider,
+ retry_destination.model,
+ retry_messages,
temperature=temperature, max_tokens=max_tokens,
- tools=tools, timeout=effective_timeout,
+ tools=retry_tools, timeout=effective_timeout,
extra_body=effective_extra_body,
reasoning_config=reasoning_config,
- base_url=str(getattr(retry_client, "base_url", "") or fb_base), task=task)
+ base_url=retry_destination.base_url, task=task)
try:
return _validate_llm_response(
_relay_sync_completion(
retry_client,
retry_kwargs,
- provider=fb_provider,
+ provider=retry_destination.provider,
+ api_mode=retry_destination.api_mode,
),
task,
)
@@ -4761,13 +4923,21 @@ def _resolve_fallback_entry(entry: Dict[str, Any]) -> Tuple[Optional[Any], Optio
base_url = str(entry.get("base_url") or "").strip() or None
api_key = _fallback_entry_api_key(entry)
api_mode = str(entry.get("api_mode") or entry.get("transport") or "").strip() or None
- return resolve_provider_client(
+ client, resolved_model = resolve_provider_client(
provider,
model=model,
explicit_base_url=base_url,
explicit_api_key=api_key,
api_mode=api_mode,
)
+ if client is not None:
+ try:
+ client._hermes_fallback_destination = _fallback_destination_from_entry(
+ entry, client, resolved_model
+ )
+ except Exception:
+ pass
+ return client, resolved_model
def _try_main_fallback_chain(
diff --git a/agent/chat_completion_helpers.py b/agent/chat_completion_helpers.py
index a025f58f5a2d9..e40333f0e601b 100644
--- a/agent/chat_completion_helpers.py
+++ b/agent/chat_completion_helpers.py
@@ -1120,9 +1120,10 @@ def interruptible_api_call(agent, api_kwargs: dict):
-def build_api_kwargs(agent, api_messages: list) -> dict:
+def build_api_kwargs(agent, api_messages: list, tools_for_api: list | None = None) -> dict:
"""Build the keyword arguments dict for the active API mode."""
- tools_for_api = agent.tools
+ if tools_for_api is None:
+ tools_for_api = agent.tools
if agent.api_mode == "anthropic_messages":
_transport = agent._get_transport()
diff --git a/agent/conversation_loop.py b/agent/conversation_loop.py
index 9da3b3e2d5fb0..b7e3f9afc1c7b 100644
--- a/agent/conversation_loop.py
+++ b/agent/conversation_loop.py
@@ -70,8 +70,9 @@ from agent.model_metadata import (
)
from agent.process_bootstrap import _install_safe_stdio
from agent.prompt_caching import (
- apply_anthropic_cache_control,
+ build_prompt_cache_plan,
strip_anthropic_cache_control,
+ strip_anthropic_tool_cache_control,
)
from agent.retry_utils import (
adaptive_rate_limit_backoff,
@@ -941,7 +942,8 @@ def _redecorate_prompt_cache_for_provider(
*,
system_message=None,
moa_prepared: Optional[Dict[str, Any]] = None,
-) -> tuple[List[Dict[str, Any]], Optional[Dict[str, Any]]]:
+ tools_for_api: Optional[List[Dict[str, Any]]] = None,
+) -> tuple[List[Dict[str, Any]], Optional[Dict[str, Any]]] | tuple[List[Dict[str, Any]], Optional[Dict[str, Any]], List[Dict[str, Any]]]:
"""Strip and re-apply cache_control for the *current* provider policy.
Decoration runs once per call block before the retry loop for the primary
@@ -951,10 +953,9 @@ def _redecorate_prompt_cache_for_provider(
by reshaping at the top of each retry attempt.
The source list is the mutated in-flight request (image shrink / ASCII /
- reasoning_details recoveries already applied) — never a pristine
- pre-decoration snapshot. MoA guidance is peeled, the base is redecorated,
- then ``rebase_prepared_request`` re-attaches guidance outside the cached
- span.
+ reasoning_details recoveries already applied), never a pristine
+ pre-decoration snapshot. MoA guidance is peeled and rebased without
+ decoration; the acting aggregator plans its resolved destination later.
"""
messages: List[Dict[str, Any]] = [
dict(m) if isinstance(m, dict) else m for m in (api_messages or [])
@@ -965,6 +966,21 @@ def _redecorate_prompt_cache_for_provider(
messages = _peel_moa_guidance(messages, guidance)
strip_anthropic_cache_control(messages)
+ planned_tools = strip_anthropic_tool_cache_control(
+ tools_for_api if tools_for_api is not None else getattr(agent, "tools", [])
+ )
+
+ if prepared is not None and getattr(agent, "provider", None) == "moa":
+ # Prepared MoA state is canonical: the synchronous acting-aggregator
+ # sender owns its destination-local cache plan after it resolves the slot.
+ completions = getattr(getattr(agent.client, "chat", None), "completions", None)
+ rebase = getattr(completions, "rebase_prepared_request", None)
+ if callable(rebase):
+ prepared = rebase(prepared, messages)
+ messages = prepared["messages"]
+ if tools_for_api is None:
+ return messages, prepared
+ return messages, prepared, planned_tools
# Direct attribute access matches the call-block decoration site — the
# flags are unconditionally initialized on AIAgent, and a getattr
@@ -972,31 +988,25 @@ def _redecorate_prompt_cache_for_provider(
if agent._use_prompt_caching:
_ensure_cached_system_prompt_static(agent, system_message=system_message)
static = getattr(agent, "_cached_system_prompt_static", None)
- messages = apply_anthropic_cache_control(
+ direct_tool_cache = getattr(
+ agent,
+ "_direct_native_anthropic_tool_cache_capability",
+ lambda: False,
+ )()
+ plan = build_prompt_cache_plan(
messages,
+ planned_tools,
cache_ttl=agent._cache_ttl,
native_anthropic=agent._use_native_cache_layout,
static_system_prefix=static if isinstance(static, str) else None,
+ direct_native_tool_cache=direct_tool_cache,
)
+ messages = plan.messages
+ planned_tools = plan.tools
- if (
- prepared is not None
- and getattr(agent, "provider", None) == "moa"
- ):
- # No `and guidance` here: guidance=None is a real prepared shape
- # (all-references-failed / silent degraded policy builds the
- # prepared request without attaching guidance), and the MoA facade
- # sends prepared["messages"] — not api_kwargs["messages"] — so the
- # rebase must refresh the prepared object even when there is no
- # guidance to re-attach. rebase_prepared_request handles falsy
- # guidance by copying the messages and skipping the attach.
- completions = getattr(getattr(agent.client, "chat", None), "completions", None)
- rebase = getattr(completions, "rebase_prepared_request", None)
- if callable(rebase):
- prepared = rebase(prepared, messages)
- messages = prepared["messages"]
-
- return messages, prepared
+ if tools_for_api is None:
+ return messages, prepared
+ return messages, prepared, planned_tools
def _apply_context_engine_selection(
@@ -1748,12 +1758,8 @@ def run_conversation(
# regardless of ordering (a single-space pad here previously had to
# be sequenced after normalization to survive, forking the concept).
- # Apply Anthropic prompt caching for Claude models on native
- # Anthropic, OpenRouter, and third-party Anthropic-compatible
- # gateways. Auto-detected: if ``_use_prompt_caching`` is set, inject
- # cache_control breakpoints for the static system prefix, full system
- # prompt, and last two messages (or the legacy system-and-3 layout
- # when no static prefix is available).
+ # Build the request-local cache sections only after every transcript
+ # mutation. The canonical tool registry stays undecorated.
#
# Runs LAST, after every message mutation above. Marking earlier
# defeats the prefix stability the mutations exist to create:
@@ -1768,10 +1774,12 @@ def run_conversation(
# exactly the point the breakpoints were meant to protect. Marking
# last also keeps breakpoints off messages that the orphan sweep or
# the thinking-only drop is about to remove or merge away.
- if agent._use_prompt_caching:
+ tools_for_api = agent.tools
+ if agent._use_prompt_caching and agent.provider != "moa":
_static_system_prefix = getattr(agent, "_cached_system_prompt_static", None)
- api_messages = apply_anthropic_cache_control(
+ _initial_cache_plan = build_prompt_cache_plan(
api_messages,
+ tools_for_api,
cache_ttl=agent._cache_ttl,
native_anthropic=agent._use_native_cache_layout,
static_system_prefix=(
@@ -1779,7 +1787,10 @@ def run_conversation(
if isinstance(_static_system_prefix, str)
else None
),
+ direct_native_tool_cache=agent._direct_native_anthropic_tool_cache_capability(),
)
+ api_messages = _initial_cache_plan.messages
+ tools_for_api = _initial_cache_plan.tools
# Build a persistent-MoA request before measuring compression pressure.
# MoA reference output is injected into the aggregator prompt, but it
@@ -2115,15 +2126,22 @@ def run_conversation(
# fallback refreshes the policy flags, but the decorated list
# still carries the primary's breakpoints (or none). Strip and
# re-render for the current provider before building kwargs.
- api_messages, _moa_prepared_request = (
+ api_messages, _moa_prepared_request, tools_for_api = (
_redecorate_prompt_cache_for_provider(
agent,
api_messages,
system_message=system_message,
moa_prepared=_moa_prepared_request,
+ tools_for_api=tools_for_api,
)
)
- api_kwargs = agent._build_api_kwargs(api_messages)
+ if tools_for_api == agent.tools:
+ api_kwargs = agent._build_api_kwargs(api_messages)
+ else:
+ api_kwargs = agent._build_api_kwargs(
+ api_messages,
+ tools_for_api=tools_for_api,
+ )
if agent._force_ascii_payload:
_sanitize_structure_non_ascii(api_kwargs)
if agent.api_mode == "codex_responses":
diff --git a/agent/moa_loop.py b/agent/moa_loop.py
index 42d0c29bca520..671827e7fd81e 100644
--- a/agent/moa_loop.py
+++ b/agent/moa_loop.py
@@ -8,6 +8,7 @@ iteration.
from __future__ import annotations
+import copy
import hashlib
import logging
import re
@@ -1657,6 +1658,59 @@ class MoAChatCompletions:
max_tokens: Any = agg_kwargs.get("max_tokens")
tools: Any = agg_kwargs.get("tools")
extra_body: Any = agg_kwargs.get("extra_body")
+ agg_runtime = _slot_runtime(aggregator)
+ try:
+ from types import SimpleNamespace
+
+ from agent.agent_runtime_helpers import (
+ _direct_native_anthropic_tool_cache_capability,
+ anthropic_prompt_cache_policy,
+ )
+ from agent.prompt_caching import (
+ build_prompt_cache_plan,
+ strip_anthropic_cache_control,
+ strip_anthropic_tool_cache_control,
+ )
+
+ guidance = prepared.get("guidance")
+ canonical_messages = copy.deepcopy(agg_messages)
+ if guidance:
+ canonical_messages = peel_reference_guidance(
+ canonical_messages,
+ str(guidance),
+ )
+ strip_anthropic_cache_control(canonical_messages)
+ canonical_tools = strip_anthropic_tool_cache_control(tools)
+ cache_stub = SimpleNamespace(provider="", base_url="", api_mode="", model="")
+ should_cache, native_layout = anthropic_prompt_cache_policy(
+ cache_stub,
+ provider=agg_runtime.get("provider") or "",
+ base_url=agg_runtime.get("base_url") or "",
+ api_mode=agg_runtime.get("api_mode") or "",
+ model=agg_runtime.get("model") or "",
+ )
+ if should_cache:
+ plan = build_prompt_cache_plan(
+ canonical_messages,
+ canonical_tools,
+ native_anthropic=native_layout,
+ direct_native_tool_cache=_direct_native_anthropic_tool_cache_capability(
+ cache_stub,
+ provider=agg_runtime.get("provider") or "",
+ base_url=agg_runtime.get("base_url") or "",
+ api_mode=agg_runtime.get("api_mode") or "",
+ model=agg_runtime.get("model") or "",
+ ),
+ )
+ agg_messages = plan.messages
+ tools = plan.tools
+ else:
+ agg_messages = canonical_messages
+ tools = canonical_tools
+ if guidance:
+ _attach_reference_guidance(agg_messages, str(guidance))
+ except Exception as exc: # pragma: no cover - cache planning must not block MoA
+ logger.debug("MoA aggregator cache plan skipped: %s", exc)
# Record the exact aggregator INPUT (incl. the injected reference
# context) into the pending trace so a trace captures what the
# aggregator actually saw, not a reconstruction. Traces are a
@@ -1697,7 +1751,6 @@ class MoAChatCompletions:
# actually governs the aggregator stream, not just call_llm's default.
if api_kwargs.get("timeout") is not None:
stream_kwargs["timeout"] = api_kwargs["timeout"]
- agg_runtime = _slot_runtime(aggregator)
# _slot_runtime may carry the provider's request_overrides.extra_body;
# pop it and merge with the caller's extra_body (caller wins) so the
# explicit kwarg below never collides with **agg_runtime.
diff --git a/agent/model_metadata.py b/agent/model_metadata.py
index e47a10eb07ce4..42d841009fa3d 100644
--- a/agent/model_metadata.py
+++ b/agent/model_metadata.py
@@ -273,6 +273,27 @@ CONTEXT_PROBE_TIERS = [
# Default context length when no detection method succeeds.
DEFAULT_FALLBACK_CONTEXT = CONTEXT_PROBE_TIERS[0]
+# (model, base_url) pairs that already emitted the fallback warning.
+# The fallback result itself is deliberately never cached, so without this
+# the warning would repeat on every resolution for the same unknown model.
+_FALLBACK_WARNED: set = set()
+
+
+def _warn_context_length_fallback(model: str, base_url: str) -> None:
+ """Warn (once per model+endpoint) that context detection failed and the
+ hard default is being used, so small-context models (8K, 32K) don't
+ silently get 256K and cause hard-to-debug API failures."""
+ key = (model, base_url or "")
+ if key in _FALLBACK_WARNED:
+ return
+ _FALLBACK_WARNED.add(key)
+ logger.warning(
+ "Could not determine context length for model %r (base_url=%s) "
+ "— falling back to %s tokens. Set model.context_length in "
+ "config.yaml to override.",
+ model, base_url or "default", f"{DEFAULT_FALLBACK_CONTEXT:,}",
+ )
+
# Minimum context length required to run Hermes Agent. Models with fewer
# tokens cannot maintain enough working memory for tool-calling workflows.
# Sessions, model switches, and cron jobs should reject models below this.
@@ -2599,6 +2620,9 @@ def get_model_context_length(
f"{length:,}", model, default_model,
)
return length
+ # Same silent-256K bug class as the step-9 fallback below —
+ # warn here too so custom/local endpoints aren't left invisible.
+ _warn_context_length_fallback(model, base_url)
return DEFAULT_FALLBACK_CONTEXT
# 4. Anthropic /v1/models API (only for regular API keys, not OAuth)
@@ -2771,7 +2795,10 @@ def get_model_context_length(
if default_model in model_lower:
return length
- # 9. Default fallback — 256K
+ # 9. Default fallback — warn (deduped per model+endpoint) so
+ # small-context models don't silently get 256K. See
+ # _warn_context_length_fallback for rationale.
+ _warn_context_length_fallback(model, base_url)
return DEFAULT_FALLBACK_CONTEXT
diff --git a/agent/prompt_caching.py b/agent/prompt_caching.py
index 1a0326c79df33..719bd58e4afaa 100644
--- a/agent/prompt_caching.py
+++ b/agent/prompt_caching.py
@@ -11,9 +11,19 @@ Pure functions -- no class state, no AIAgent dependency.
"""
import copy
+from dataclasses import dataclass
from typing import Any, Dict, List
+@dataclass(frozen=True)
+class PromptCachePlan:
+ """Request-local message and tool sections with their cache markers."""
+
+ messages: List[Dict[str, Any]]
+ tools: List[Dict[str, Any]]
+ marker_count: int
+
+
def _apply_cache_marker(msg: dict, cache_marker: dict, native_anthropic: bool = False) -> None:
"""Add cache_control to a single message, handling all format variations."""
role = msg.get("role", "")
@@ -172,6 +182,152 @@ def strip_anthropic_cache_control(
return api_messages
+def strip_anthropic_tool_cache_control(tools: List[Dict[str, Any]] | None) -> List[Dict[str, Any]]:
+ """Return copied tools without request-local Anthropic cache markers."""
+ cleaned = copy.deepcopy(tools or [])
+ for tool in cleaned:
+ if isinstance(tool, dict):
+ tool.pop("cache_control", None)
+ return cleaned
+
+
+def _count_cache_markers(messages: List[Dict[str, Any]], tools: List[Dict[str, Any]]) -> int:
+ """Count the wire-visible cache markers in a request-local plan."""
+ count = sum(
+ 1
+ for message in messages
+ if isinstance(message, dict) and "cache_control" in message
+ )
+ count += sum(
+ 1
+ for message in messages
+ if isinstance(message, dict) and isinstance(message.get("content"), list)
+ for part in message["content"]
+ if isinstance(part, dict) and "cache_control" in part
+ )
+ return count + sum(
+ 1 for tool in tools if isinstance(tool, dict) and "cache_control" in tool
+ )
+
+
+def _completed_transaction_endpoint_indexes(
+ messages: List[Dict[str, Any]], *, native_anthropic: bool,
+) -> List[int]:
+ """Select legal ends of completed tool runs and ordinary turns."""
+ endpoints: List[int] = []
+ index = 0
+ while index < len(messages):
+ message = messages[index]
+ if not isinstance(message, dict) or message.get("role") == "system":
+ index += 1
+ continue
+
+ if message.get("role") == "assistant" and message.get("tool_calls"):
+ result_start = index + 1
+ result_end = result_start
+ while result_end < len(messages):
+ result = messages[result_end]
+ if not isinstance(result, dict) or result.get("role") != "tool":
+ break
+ result_end += 1
+ if result_end > result_start:
+ endpoint = result_end - 1
+ if _can_carry_marker(messages[endpoint], native_anthropic):
+ endpoints.append(endpoint)
+ index = result_end
+ continue
+
+ if message.get("role") == "tool":
+ while index < len(messages):
+ result = messages[index]
+ if not isinstance(result, dict) or result.get("role") != "tool":
+ break
+ index += 1
+ continue
+
+ if message.get("role") == "user" and index + 1 < len(messages):
+ index += 1
+ continue
+
+ if (
+ message.get("role") == "assistant"
+ and message.get("content") in (None, "")
+ ):
+ index += 1
+ continue
+
+ if _can_carry_marker(message, native_anthropic):
+ endpoints.append(index)
+ index += 1
+ return endpoints
+
+
+def _apply_static_prefix_marker(
+ messages: List[Dict[str, Any]],
+ cache_marker: Dict[str, str],
+ static_system_prefix: str | None,
+) -> None:
+ """Mark only the reusable static system prefix for a tool-cache plan."""
+ if not messages or not isinstance(static_system_prefix, str) or not static_system_prefix:
+ return
+ system = messages[0]
+ if not isinstance(system, dict):
+ return
+ content = system.get("content")
+ if system.get("role") != "system" or not isinstance(content, str):
+ return
+ if not content.startswith(static_system_prefix):
+ return
+ suffix = content[len(static_system_prefix):]
+ system["content"] = [
+ {"type": "text", "text": static_system_prefix, "cache_control": cache_marker},
+ {"type": "text", "text": suffix},
+ ]
+
+
+def build_prompt_cache_plan(
+ api_messages: List[Dict[str, Any]],
+ tools: List[Dict[str, Any]] | None,
+ *,
+ cache_ttl: str = "5m",
+ native_anthropic: bool = False,
+ static_system_prefix: str | None = None,
+ direct_native_tool_cache: bool = False,
+) -> PromptCachePlan:
+ """Build isolated cache sections for one resolved request destination."""
+ messages = copy.deepcopy(api_messages or [])
+ strip_anthropic_cache_control(messages)
+ planned_tools = strip_anthropic_tool_cache_control(tools)
+
+ if not direct_native_tool_cache or not planned_tools:
+ planned_messages = apply_anthropic_cache_control(
+ messages,
+ cache_ttl=cache_ttl,
+ native_anthropic=native_anthropic,
+ static_system_prefix=static_system_prefix,
+ )
+ return PromptCachePlan(
+ messages=planned_messages,
+ tools=planned_tools,
+ marker_count=_count_cache_markers(planned_messages, planned_tools),
+ )
+
+ marker = _build_marker(cache_ttl)
+ _apply_static_prefix_marker(messages, marker, static_system_prefix)
+ planned_tools[-1]["cache_control"] = dict(marker)
+ for endpoint in _completed_transaction_endpoint_indexes(
+ messages,
+ native_anthropic=True,
+ )[-2:]:
+ _apply_cache_marker(messages[endpoint], marker, native_anthropic=True)
+
+ return PromptCachePlan(
+ messages=messages,
+ tools=planned_tools,
+ marker_count=_count_cache_markers(messages, planned_tools),
+ )
+
+
def apply_anthropic_cache_control(
api_messages: List[Dict[str, Any]],
cache_ttl: str = "5m",
diff --git a/apps/desktop/src/app/chat/composer/status-stack/coding-row.tsx b/apps/desktop/src/app/chat/composer/status-stack/coding-row.tsx
index 1296b3fb18037..32b21952db9bb 100644
--- a/apps/desktop/src/app/chat/composer/status-stack/coding-row.tsx
+++ b/apps/desktop/src/app/chat/composer/status-stack/coding-row.tsx
@@ -15,6 +15,7 @@ import { Codicon } from '@/components/ui/codicon'
import { DiffCount } from '@/components/ui/diff-count'
import type { HermesGitBranch } from '@/global'
import { useI18n } from '@/i18n'
+import { displayPath } from '@/lib/display-path'
import { registerRepoStatusCwd, repoStatusForCwd, repoWorktreesForCwd } from '@/store/coding-status'
import { notifyError } from '@/store/notifications'
import { $newWorktreeRequest } from '@/store/projects'
@@ -237,6 +238,18 @@ export const CodingStatusRow = memo(function CodingStatusRow({
+ {/* Worktree path — plain muted text, not a chip. Always in the flex
+ so hover doesn't reflow the row; opacity alone reveals it.
+ `displayPath` collapses home → ~ (shell / VS Code convention). */}
+ {resolvedRepoPath && (
+
+ {displayPath(resolvedRepoPath)}
+
+ )}
+
{/* Branch actions kebab — same pattern as the session/worktree rows.
ALWAYS laid out; only its opacity flips on hover/focus/open, so
revealing it never reflows the row (no layout shift). pointer-events
diff --git a/apps/desktop/src/app/chat/sidebar/projects/entered-content.tsx b/apps/desktop/src/app/chat/sidebar/projects/entered-content.tsx
index 9d32259316378..6b09788157b70 100644
--- a/apps/desktop/src/app/chat/sidebar/projects/entered-content.tsx
+++ b/apps/desktop/src/app/chat/sidebar/projects/entered-content.tsx
@@ -15,6 +15,7 @@ import {
import type { HermesGitWorktree } from '@/global'
import type { SessionInfo } from '@/hermes'
import { useI18n } from '@/i18n'
+import { displayPath } from '@/lib/display-path'
import { $dismissedWorktreeIds, dismissWorktree, setWorkspaceNodeOpen } from '@/store/layout'
import { notifyError } from '@/store/notifications'
import { removeWorktreePath } from '@/store/projects'
@@ -277,7 +278,7 @@ function RepoFlatSection({
label={repo.label}
onToggle={toggleOpen}
open={open}
- title={repo.path ?? undefined}
+ title={repo.path ? displayPath(repo.path) : undefined}
/>
{open &&
- {profile.path} +
+ {displayPath(profile.path)}
diff --git a/apps/desktop/src/app/right-sidebar/files/remote-picker.tsx b/apps/desktop/src/app/right-sidebar/files/remote-picker.tsx index b502c014c7dd9..3374348e20fb1 100644 --- a/apps/desktop/src/app/right-sidebar/files/remote-picker.tsx +++ b/apps/desktop/src/app/right-sidebar/files/remote-picker.tsx @@ -5,6 +5,7 @@ import { Codicon } from '@/components/ui/codicon' import { Dialog, DialogContent, DialogDescription, DialogTitle } from '@/components/ui/dialog' import { useI18n } from '@/i18n' import { readDesktopDir, setDesktopFsRemotePicker } from '@/lib/desktop-fs' +import { displayPath, pathLeaf } from '@/lib/display-path' import { cn } from '@/lib/utils' function clean(path: string) { @@ -24,7 +25,7 @@ function parentDir(path: string) { } function pathName(path: string) { - return path.split('/').filter(Boolean).pop() || path + return pathLeaf(path) || path } interface PendingSelection { @@ -167,7 +168,7 @@ export function RemoteFolderPicker() {