Skip to content

The agent that grows with you

fix(gateway): resolve delegation mode from configured interim and keep the pinned mode across refreshes

Victor Kyriazakoscf6623e43359
diff --git a/gateway/run_turn.py b/gateway/run_turn.py
index 991449c2f35..82f10cbc1ed 100644
--- a/gateway/run_turn.py
+++ b/gateway/run_turn.py
@@ -2325,13 +2325,10 @@ class GatewayTurnMixin(GatewayTurnPrepareMixin, GatewayTurnHygieneMixin, Gateway
if scheduled_heartbeat:
# A heartbeat is proactive work: tool chrome, drafts, thinking and periodic
# liveness notices would create a user-visible ping before its final result is known.
- # Keep status callbacks intact for approvals and actionable failures.
+ # Keep status callbacks intact for approvals and actionable failures. Interim messages keep the chat's
+ # setting (TurnRunner drops them for a heartbeat): an agent this turn builds takes its mode from it.
disp = dataclasses.replace(
- disp,
- tool_progress_enabled=False,
- interim_assistant_messages_enabled=False,
- _thinking_enabled=False,
- _native_slack_task_cards=False,
+ disp, tool_progress_enabled=False, _thinking_enabled=False, _native_slack_task_cards=False,
needs_progress_queue=False,
)
turn_ctx, turn_runner, _cleanup_adapter = self._run_agent_build_turn_context(
diff --git a/gateway/session_execution.py b/gateway/session_execution.py
index 7c550889619..5732fb60ab1 100644
--- a/gateway/session_execution.py
+++ b/gateway/session_execution.py
@@ -222,7 +222,8 @@ class GatewaySessionAgentMixin:
self._release_evicted_agent(found.evicted)
if agent is None:
from tools.delegate_tool_config import gateway_delegation_inline, gateway_delegation_inline_scope
- # delegation.gateway_mode from this turn's own (profile-scoped) config and resolved interim setting;
+ # delegation.gateway_mode from this turn's own (profile-scoped) config and the chat's resolved interim
+ # setting (never muted for a heartbeat turn, which shares the user's session and its cached agent);
# read once, by the agent's first tool build, then carried by its delegate_task schema and pin.
inline = gateway_delegation_inline(
ctx.user_config, platform_key, interim_enabled=ctx.interim_assistant_messages_enabled)
diff --git a/gateway/turn_context.py b/gateway/turn_context.py
index 13bb65776cf..805acf10356 100644
--- a/gateway/turn_context.py
+++ b/gateway/turn_context.py
@@ -72,6 +72,8 @@ class TurnContext:
enabled_toolsets: Any = None
disabled_toolsets: Any = None
log_mode_enabled: bool = False
+ # The chat's resolved display.interim_assistant_messages. Turn-shaped gates (scheduled heartbeat, hold_stream,
+ # finite viewer) apply in TurnRunner; a fresh agent's delegation.gateway_mode reads this session-shaped value.
interim_assistant_messages_enabled: bool = False
needs_progress_queue: bool = False
AIAgent: Any = None
diff --git a/tests/gateway/test_gateway_delegation_mode.py b/tests/gateway/test_gateway_delegation_mode.py
index 633bd9027c9..d9ddb2a7ad2 100644
--- a/tests/gateway/test_gateway_delegation_mode.py
+++ b/tests/gateway/test_gateway_delegation_mode.py
@@ -309,6 +309,92 @@ def test_each_profile_resolves_its_own_mode_under_the_multiplexer(monkeypatch, t
assert seen == [True, False, True]
+async def _two_turns(monkeypatch, config: dict, *, first_heartbeat: bool, restart_between=False):
+ """Two turns on one Telegram chat through a runner WITH an agent cache (the second turn reuses the first turn's
+ agent) and a real SessionDB in the temp HERMES_HOME (the tools[] pin is persisted). ``restart_between`` drops
+ the cache between the turns, so the second turn builds a fresh agent that restores the session's pin.
+ Returns (chat, the delegate_task definition of each parent request, the persisted pin)."""
+ import json
+
+ import gateway.run as gateway_run
+ from hermes_state import SessionDB
+ from tools import async_delegation
+
+ home = Path(os.environ["HERMES_HOME"])
+ platform = Platform.TELEGRAM
+ chat = _Chat(platform)
+ source = SessionSource(platform=platform, chat_id="c1", chat_type="dm", user_id="u1")
+ session_key = f"agent:main:{platform.value}:dm:c1"
+ respond, aux = _model(Text(f"Audit finished: {FINDING}"))
+ merged = {"tools": {"tool_search": {"enabled": "off"}}, "platform_toolsets": {platform.value: ["delegation", "todo"]},
+ **config, "display": {"tool_progress": "off", **config.get("display", {})}}
+ with FakeLLMServer(respond, aux=aux) as srv:
+ write_hermes_home(home, srv.base_url, extra_config=OFFLINE_CONFIG + NO_BACKGROUND_REVIEW
+ + yaml.safe_dump(merged))
+ monkeypatch.setattr(gateway_run, "_hermes_home", home)
+ monkeypatch.setattr(gateway_run, "_resolve_runtime_agent_kwargs", lambda: {
+ "api_key": "sk-fake-e2e", "base_url": srv.base_url, "provider": "custom", "api_mode": "chat_completions"})
+ runner = _make_runner(chat)
+ runner.config.streaming = StreamingConfig(enabled=False)
+ runner._session_db = SessionDB(home / "state.db")
+ runner._session_db.create_session("s1", source=platform.value) # the session store creates the row first
+ runner._agent_cache, runner._agent_cache_lock = {}, threading.Lock()
+ heartbeats, history = [first_heartbeat, False], []
+
+ async def handler(ev):
+ # The second turn continues the session (a fresh agent reads the session row, and its pin, only then).
+ result = await runner._run_agent(message=ev.text, context_prompt="", history=list(history), source=source,
+ session_id="s1", session_key=session_key,
+ scheduled_heartbeat=heartbeats.pop(0))
+ history.extend([{"role": "user", "content": ev.text},
+ {"role": "assistant", "content": result["final_response"]}])
+ return None if result.get("already_sent") else result["final_response"]
+
+ chat.set_message_handler(handler)
+ for i in range(2):
+ if i and restart_between:
+ runner._agent_cache.clear()
+ event = MessageEvent(text=f"How is billing doing? ({i})", source=source, message_type=MessageType.TEXT)
+ await asyncio.wait_for(chat._process_message_background(event, session_key), timeout=60)
+ await asyncio.to_thread(wait_until, lambda: async_delegation.active_count() == 0, 30, 0.02, "async units")
+ row = runner._session_db.get_session("s1") or {}
+ pin = json.loads(row["tool_names"]) if row.get("tool_names") else None
+ schemas = [_delegate_def(r["body"]) for r in srv.requests if r["kind"] == "main" and GOAL not in _first_user_text(r)]
+ return chat, schemas, pin
+
+
[email protected](("config", "first_heartbeat", "inline"), [
+ ({}, True, False),
+ ({}, False, False),
+ (_interim(False), True, True),
+], ids=["interim-on-heartbeat-first", "interim-on-control", "interim-off-heartbeat-first"])
+async def test_a_heartbeat_turn_does_not_decide_the_chats_mode(monkeypatch, dispatches, config, first_heartbeat, inline):
+ """A scheduled heartbeat mutes interim messages for its own turn, and it runs under the user's session key: when
+ it is the turn that builds the session's (cached) agent, the mode must still come from the chat's configured
+ interim setting, or an interim-on chat runs inline for the rest of the session."""
+ chat, schemas, _ = await _two_turns(monkeypatch, config, first_heartbeat=first_heartbeat)
+
+ assert len(schemas) >= 2
+ assert all((END_TURN in schema["description"]) is not inline for schema in schemas)
+ assert len(dispatches) == (0 if inline else 2)
+ assert chat.sent[-1] == (ANSWER if inline else PAUSE)
+
+
+async def test_a_heartbeat_built_agent_pins_the_configured_mode_across_a_restart(monkeypatch, dispatches):
+ """Composed: agent cache + persisted tools[] pin + heartbeat. The heartbeat builds the session's agent on a cold
+ cache, the gateway restarts, the user's next turn builds a fresh agent that restores the pin: it is the
+ background schema an interim-on chat configured."""
+ chat, schemas, pin = await _two_turns(monkeypatch, {}, first_heartbeat=True, restart_between=True)
+
+ assert pin is not None
+ delegate = next(t["function"] for t in pin["tools"] if t["function"]["name"] == "delegate_task")
+ assert END_TURN in delegate["description"]
+ assert all(END_TURN in schema["description"] for schema in schemas)
+ assert len(dispatches) == 2 and chat.sent[-1] == PAUSE
+
+
@pytest.mark.parametrize("platform_key", ["api_server", "local", "webhook"])
def test_auto_never_joins_on_a_surface_that_is_not_a_chat(platform_key):
"""``auto`` is about a pause message reaching a person: API, local and webhook turns keep today's path."""
diff --git a/tests/tools/test_delegate_gateway_inline.py b/tests/tools/test_delegate_gateway_inline.py
index 8b8c457acf9..285ef6dd51a 100644
--- a/tests/tools/test_delegate_gateway_inline.py
+++ b/tests/tools/test_delegate_gateway_inline.py
@@ -93,6 +93,28 @@ def test_a_session_keeps_its_mode_until_a_new_session():
assert session_joins_delegation(rebuilt) is False
[email protected]("refresh", [
+ {"content_aware": True}, # the compaction boundary (agent/conversation_compression.py)
+ {}, # /reload-mcp over the cached agents (gateway/run_turn.py)
+], ids=["compaction-refresh", "reload-mcp"])
[email protected]("pinned_inline", [True, False], ids=["pinned-inline", "pinned-background"])
+def test_a_restored_mode_survives_a_later_tools_refresh(refresh, pinned_inline):
+ """The pin is authoritative: a fresh agent built for the other mode restores the session's variant, and a later
+ rebuild from fresh definitions (which reads the agent's frozen decision) keeps it instead of flipping the chat
+ mid-conversation to whatever the current config says."""
+ from tools.delegate_tool import session_joins_delegation
+ from tools.mcp_tool_agent import refresh_agent_mcp_tools, restore_agent_tool_prefix, tool_pin_version
+
+ first = _built(inline=pinned_inline)
+ fresh = _built(inline=not pinned_inline)
+ restore_agent_tool_prefix(fresh, {"version": tool_pin_version(), "tools": first.tools})
+ assert session_joins_delegation(fresh) is pinned_inline
+
+ refresh_agent_mcp_tools(fresh, quiet_mode=True, **refresh)
+ assert session_joins_delegation(fresh) is pinned_inline
+ assert _delegate(fresh) == _delegate(first)
+
+
def _parent(tools, depth=0):
parent = MagicMock()
parent._delegate_depth = depth
diff --git a/tools/delegate_tool.py b/tools/delegate_tool.py
index e057e7e0187..8c431f3aad2 100644
--- a/tools/delegate_tool.py
+++ b/tools/delegate_tool.py
@@ -886,6 +886,16 @@ def session_joins_delegation(agent: Any) -> bool:
return False
+def adopt_session_delegation_mode(agent: Any) -> None:
+ """Re-freeze *agent*'s inline decision (``agent_joins_delegation``) from the ``delegate_task`` it carries once a
+ fresh agent has restored its session's tools[] pin, so the pin is authoritative: a later rebuild from fresh
+ definitions (compaction boundary, ``/reload-mcp``, Bot Chat refresh) derives the session's variant, not the one
+ the current config would build."""
+ tools = getattr(agent, "tools", None) or ()
+ if any(isinstance(tool, dict) and (tool.get("function") or {}).get("name") == "delegate_task" for tool in tools):
+ agent._delegation_inline = session_joins_delegation(agent)
+
+
# --- Registry ---
from tools.registry import registry, tool_error
diff --git a/tools/delegate_tool_config.py b/tools/delegate_tool_config.py
index 96c9c0ef826..7e55c0b18a6 100644
--- a/tools/delegate_tool_config.py
+++ b/tools/delegate_tool_config.py
@@ -137,7 +137,8 @@ _GATEWAY_DELEGATION_INLINE: ContextVar[bool] = ContextVar("hermes_gateway_delega
@contextmanager
def gateway_delegation_inline_scope(inline: bool) -> Iterator[None]:
- """Build an agent whose session joins its delegations in the call (see :func:`agent_joins_delegation`)."""
+ """Build an agent whose tools carry the joined ``delegate_task`` variant (frozen on the agent by
+ :func:`agent_joins_delegation`). Dispatch reads the variant the session carries, not this flag."""
token = _GATEWAY_DELEGATION_INLINE.set(bool(inline))
try:
yield
@@ -145,9 +146,10 @@ def gateway_delegation_inline_scope(inline: bool) -> Iterator[None]:
_GATEWAY_DELEGATION_INLINE.reset(token)
def agent_joins_delegation(agent: Any) -> bool:
- """The gateway's inline decision, frozen on *agent* at its first tool build (like ``agent_is_oneshot``), so
- later rebuilds outside the build scope keep the same ``delegate_task`` bytes. Dispatch does not read this: it
- follows the schema the session carries (``tools.delegate_tool.session_joins_delegation``)."""
+ """The gateway's inline decision, frozen on *agent* at its first tool build (like ``agent_is_oneshot``) and
+ re-frozen from a restored tools[] pin (``tools.delegate_tool.adopt_session_delegation_mode``), so later rebuilds
+ outside the build scope keep the session's ``delegate_task`` bytes. Dispatch does not read this: it follows the
+ schema the session carries (``tools.delegate_tool.session_joins_delegation``)."""
cached = getattr(agent, "_delegation_inline", None)
if not isinstance(cached, bool):
cached = _GATEWAY_DELEGATION_INLINE.get()
diff --git a/tools/mcp_tool_agent.py b/tools/mcp_tool_agent.py
index f8e3142e670..4ac8c2fffd2 100644
--- a/tools/mcp_tool_agent.py
+++ b/tools/mcp_tool_agent.py
@@ -290,6 +290,8 @@ def restore_agent_tool_prefix(agent, saved) -> bool:
if isinstance(saved, dict) and saved.get("delegation_backend"):
from agent.delegation_backends import adopt_built_backend
adopt_built_backend(agent, pinned, saved["delegation_backend"])
+ from tools.delegate_tool import adopt_session_delegation_mode
+ adopt_session_delegation_mode(agent) # the restored delegate_task decides joined vs background from here on
if not same_code or merged != list(pinned):
persist_agent_tool_names(agent)
return changed
diff --git a/website/docs/user-guide/features/delegation.md b/website/docs/user-guide/features/delegation.md
index 29a4c5595b1..bbfb81aef84 100644
--- a/website/docs/user-guide/features/delegation.md
+++ b/website/docs/user-guide/features/delegation.md
@@ -651,12 +651,33 @@ schema as a one-shot run. While it waits, the typing indicator stays on and the
behaves like any long tool call. `/stop` stops the children, and so does a follow-up
message under the default `busy_input_mode: interrupt` (each child returns an interrupted
result with its partial output); under `queue` the follow-up waits for the turn.
-`display.long_running_notifications` still governs the periodic "still working" notice.
Nested delegation is unchanged.
-The mode is part of a session's tool schema, which is cached with the conversation. A
+Inline turns that run past `agent.gateway_notify_interval` (180 seconds by default) still
+get the periodic "still working" notice, which `display.long_running_notifications`
+controls separately and which is on by default for Telegram, Slack, Discord and WhatsApp.
+For a single message per turn, also set it to `off` for that platform (`generic` only
+changes the notice's wording):
+
+```yaml
+display:
+ interim_assistant_messages: false
+ platforms:
+ telegram:
+ long_running_notifications: false
+```
+
+The mode is part of a session's tool schema, which is pinned with the conversation. A
change to `gateway_mode` or to `interim_assistant_messages` applies from the next session
-(`/new`); a running chat keeps the mode it started with, also across gateway restarts.
+(`/new`). A running chat keeps the mode it started with across gateway restarts, agent
+cache evictions, context compaction and `/reload-mcp`. A scheduled heartbeat turn mutes
+interim messages only for itself and does not change the chat's mode. One exception: the
+first turn after a Hermes update rebuilds the session's tool definitions from the new
+code, so the chat adopts the current setting at that turn.
+
+Listing `delegate_task` in `tools.tool_search.defer` turns inline off for that session:
+the model loads the regular (background) `delegate_task` schema through `tool_describe`,
+and delegation follows the schema the model sees.
## Lifetime and Durability