The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
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.pyindex 991449c2f35..82f10cbc1ed 100644--- a/gateway/run_turn.py+++ b/gateway/run_turn.py@@ -2325,13 +2325,10 @@ class GatewayTurnMixin(GatewayTurnPrepareMixin, GatewayTurnHygieneMixin, Gatewayif 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.pyindex 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.pyindex 13bb65776cf..805acf10356 100644--- a/gateway/turn_context.py+++ b/gateway/turn_context.py@@ -72,6 +72,8 @@ class TurnContext:enabled_toolsets: Any = Nonedisabled_toolsets: Any = Nonelog_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 = Falseneeds_progress_queue: bool = FalseAIAgent: Any = Nonediff --git a/tests/gateway/test_gateway_delegation_mode.py b/tests/gateway/test_gateway_delegation_mode.pyindex 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, tassert 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.pyindex 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 = depthdiff --git a/tools/delegate_tool.py b/tools/delegate_tool.pyindex 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_errordiff --git a/tools/delegate_tool_config.py b/tools/delegate_tool_config.pyindex 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@contextmanagerdef 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.pyindex 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_backendadopt_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 onif not same_code or merged != list(pinned):persist_agent_tool_names(agent)return changeddiff --git a/website/docs/user-guide/features/delegation.md b/website/docs/user-guide/features/delegation.mdindex 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 thebehaves like any long tool call. `/stop` stops the children, and so does a follow-upmessage under the default `busy_input_mode: interrupt` (each child returns an interruptedresult 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. Achange 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