Skip to content

The agent that grows with you

fix(left-core): only a turn someone sees claims kept migration notices

Teknium49f5de617e26
diff --git a/agent/agent_init.py b/agent/agent_init.py
index f6328ce054d..4343cf5ecb1 100644
--- a/agent/agent_init.py
+++ b/agent/agent_init.py
@@ -1069,10 +1069,10 @@ def _client_kwargs_from_routed(client, timeout) -> dict[str, Any]:
def _load_tools(agent, enabled_toolsets, disabled_toolsets):
- # A feature that left core for a catalog plugin (Home Assistant) is installed for a home that
- # used it, once per process, before discovery so its tools are in this agent's snapshot.
+ # A feature that left core (Home Assistant) is installed once per process before discovery, so its tools
+ # are in this snapshot; outcomes wait for a turn someone sees (deliver_kept_startup_notices), maybe not ours.
from hermes_cli.left_core_migration import recover_at_startup
- recover_at_startup(say=getattr(agent, "_emit_startup_warning", None))
+ recover_at_startup()
# A multiplexed gateway may have switched HERMES_HOME since model_tools was imported;
# make sure this profile's plugins are discovered before the tool snapshot.
try:
diff --git a/agent/side_question_lease.py b/agent/side_question_lease.py
index 42e8c88a4a1..b544619b713 100644
--- a/agent/side_question_lease.py
+++ b/agent/side_question_lease.py
@@ -64,7 +64,7 @@ def _purge_locked(now: float, agent: Any = None) -> None:
del _leases[stale]
-def _unattended(agent: Any) -> bool:
+def is_unattended_turn(agent: Any) -> bool:
"""A turn nobody is waiting on: a persistence-detached fork, a cron run, a delegated child."""
return (getattr(agent, "_persist_disabled", False) or getattr(agent, "platform", None) == "cron"
or getattr(agent, "_delegate_depth", 0) > 0)
@@ -76,7 +76,7 @@ def issue_side_question_token(agent: Any, messages: list[dict[str, Any]], turn_i
only: the captured context and profile are the turn's."""
from hermes_constants import hermes_home_key
- if _unattended(agent) or not _consented_plugin_loaded():
+ if is_unattended_turn(agent) or not _consented_plugin_loaded():
return None
capture = SideQuestionCapture(
parent_ref=weakref.ref(agent),
diff --git a/agent/status_output.py b/agent/status_output.py
index 7ed88543d92..bb54b76db84 100644
--- a/agent/status_output.py
+++ b/agent/status_output.py
@@ -14,6 +14,21 @@ from agent.session_activity import ActivityProvenance
logger = logging.getLogger("run_agent")
+def deliver_kept_startup_notices(agent) -> None:
+ """Hand *agent*'s turn the notices a migration kept for the home (a gateway start, a CLI resolution, an
+ agent's own start, in any process) when someone sees them: the CLI's print sink or a driver's
+ ``notice_callback``. A cron run, subagent, curator, kanban worker or background fork leaves them in the
+ home for the next such turn: claiming them there would drop them."""
+ from agent.side_question_lease import is_unattended_turn
+ if getattr(agent, "suppress_status_output", False) or is_unattended_turn(agent):
+ return
+ if (getattr(agent, "platform", None) or "cli") != "cli" and not getattr(agent, "notice_callback", None):
+ return
+ from hermes_cli.left_core_migration import claim_kept_notices
+ for message in claim_kept_notices():
+ agent._emit_startup_warning(message)
+
+
class StatusOutputMixin:
"""Status/warning/notice emission and retry-chatter buffering (see module docstring)."""
diff --git a/agent/turn_context.py b/agent/turn_context.py
index 83d29da847d..28d9183293d 100644
--- a/agent/turn_context.py
+++ b/agent/turn_context.py
@@ -651,6 +651,8 @@ def _reset_per_turn_agent_state(agent: Any) -> None:
if agent._compression_warning:
agent._replay_compression_warning()
agent._compression_warning = None # send once
+ from agent.status_output import deliver_kept_startup_notices
+ deliver_kept_startup_notices(agent)
if getattr(agent, "_pending_startup_notices", None) or getattr(agent, "_pending_startup_prints", None):
# gateway: init ran before this turn's callbacks / viewer print sink
agent._replay_startup_warnings()
diff --git a/gateway/run_startup.py b/gateway/run_startup.py
index e0f8460c0b2..212fd1b73c2 100644
--- a/gateway/run_startup.py
+++ b/gateway/run_startup.py
@@ -44,7 +44,7 @@ def recover_left_core_in(home: Path, *, hydrate_secrets: bool = True) -> None:
from gateway.run import _profile_runtime_scope
from hermes_cli.left_core_migration import recover_at_startup
with _profile_runtime_scope(Path(home), hydrate_secrets=hydrate_secrets):
- recover_at_startup()
+ recover_at_startup(gateway_start=True)
def recover_left_core_at_gateway_start() -> None:
@@ -54,7 +54,7 @@ def recover_left_core_at_gateway_start() -> None:
so a platform plugin it gets starts its adapter in the same gateway start."""
from hermes_cli.left_core_migration import recover_at_startup
from hermes_constants import get_default_hermes_root, get_hermes_home
- recover_at_startup()
+ recover_at_startup(gateway_start=True)
root = Path(get_default_hermes_root())
if root.resolve() != Path(get_hermes_home()).resolve():
recover_left_core_in(root)
diff --git a/hermes_cli/left_core_migration.py b/hermes_cli/left_core_migration.py
index b201b355006..2434638cfe3 100644
--- a/hermes_cli/left_core_migration.py
+++ b/hermes_cli/left_core_migration.py
@@ -20,8 +20,8 @@ Installs go through the normal catalog install path at the reviewed pin (kill li
constraints, enable). Unattended dependency consent covers only these rows: the feature shipped in
core, so its users already accepted its dependencies. Agent/gateway start always installs with it
(nothing can answer a prompt there); ``hermes update`` in a terminal still asks. Every outcome
-reaches the user (terminal, Desktop, chat); a gateway-start outcome waits for the home's first agent
-to deliver it.
+reaches the user (terminal, Desktop, chat); an outcome no terminal shows waits in the home for its next
+turn someone sees (:func:`claim_kept_notices`).
"""
from __future__ import annotations
@@ -592,7 +592,7 @@ def recover_for_provider(name: Optional[str]) -> None:
the plugin: run :func:`recover_at_startup` now. The CLI and Desktop resolve the provider before the agent
(whose start runs the migration) exists, so they would otherwise stop at "unknown provider" on a home no
``hermes update`` migrated. Outcomes print in a declared terminal front end (:func:`serve_notices_on_stderr`),
- else wait for the home's first agent."""
+ else wait for the home's next turn someone sees."""
feature = _provider_feature(name or "")
if feature is None or _installs_held.get(): # held: a read-only diagnostic consumes no kept notice either
return
@@ -600,7 +600,7 @@ def recover_for_provider(name: Optional[str]) -> None:
from providers import get_provider_profile
home = Path(get_hermes_home())
# A terminal front end shows outcomes now, also those another process (the gateway this CLI started) kept;
- # otherwise (Desktop, gateway, a detached turn) the home's first agent in any process delivers them. Never
+ # otherwise (Desktop, gateway, a detached turn) the home's next watched turn in any process gets them. Never
# inferred from a TTY: a foreground `hermes gateway run` has one, and its resolutions serve the chat user.
say = (lambda message: print(message, file=sys.stderr)) if _terminal_front_end else None
if say is not None:
@@ -705,8 +705,8 @@ def installs_held():
def defer_startup_notice(message: str) -> None:
- """Hand *message* to the active home's first agent (its startup-warning sink, through
- :func:`recover_at_startup`), once. For boot-path work that runs before any agent exists."""
+ """Hand *message* to the active home's next turn someone sees (:func:`claim_kept_notices`), once.
+ For boot-path work that runs before any agent exists."""
from hermes_constants import get_hermes_home
logger.warning(message)
_queue_notice(Path(get_hermes_home()), message)
@@ -730,7 +730,7 @@ def _notices_locked(home: Path):
def _queue_notice(home: Path, message: str) -> None:
- """Keep *message* for *home*'s first agent in ANY process (:func:`_claim_notices`): the process that
+ """Keep *message* for *home*'s next watched turn in ANY process (:func:`_claim_notices`): the process that
produced it (a CLI resolving the provider, a gateway start) often runs no agent for that home itself.
A line already kept is not kept again: every start with ``allow_lazy_installs`` off reports the same row."""
import json
@@ -767,6 +767,12 @@ def _claim_notices(home: Path) -> list[str]:
return messages
+def claim_kept_notices() -> list[str]:
+ """Every notice kept for the active home in any process, for a turn someone sees (exactly once)."""
+ from hermes_constants import get_hermes_home
+ return _claim_notices(Path(get_hermes_home()))
+
+
def plugin_present(plugin: str, home: Path) -> bool:
"""Installed in *home* (enabled or not: a user who disabled it chose to). Read-only."""
return (home / "plugins" / plugin).is_dir()
@@ -1086,12 +1092,13 @@ def _gateway_serves(home: Path) -> bool:
return False
-def recover_at_startup(*, say: Optional[Callable[[str], None]] = None) -> list[str]:
- """Agent/gateway start hook for the active home: one attempt per process per home. With *say*
- (an agent's startup-warning sink) outcomes are delivered now, together with any an earlier attempt or
- boot maintenance (:func:`defer_startup_notice`) kept for this home in any process; without it they are
- logged and kept in the home (:func:`_queue_notice`) for its first agent, in whichever process.
- Returns installed plugin names."""
+def recover_at_startup(*, say: Optional[Callable[[str], None]] = None, gateway_start: bool = False) -> list[str]:
+ """Agent/gateway start hook for the active home: one attempt per process per home. With *say* (a
+ terminal's sink) outcomes are delivered now, together with any an earlier attempt or boot maintenance
+ (:func:`defer_startup_notice`) kept for this home in any process; without it they are logged and kept in
+ the home (:func:`_queue_notice`) for its next turn someone sees (:func:`claim_kept_notices`), in
+ whichever process. *gateway_start*: the gateway itself, which needs no restart hint. Returns installed
+ plugin names."""
from agent.safe_worker_policy import worker_config_snapshot
if _installs_held.get():
return []
@@ -1148,7 +1155,7 @@ def recover_at_startup(*, say: Optional[Callable[[str], None]] = None) -> list[s
for feature in features:
if _install_one(home, feature, install=_install_into(home, consent=True), say=report, process_env=True):
installed.append(feature.plugin)
- if say is not None and feature.platform and _gateway_serves(home):
+ if not gateway_start and feature.platform and _gateway_serves(home):
report(f"Restart the gateway (`hermes gateway restart`) so it serves {feature.label}.")
return installed
except Exception as exc: # never take agent/gateway start down
diff --git a/tests/agent/test_left_core_kept_notice_delivery.py b/tests/agent/test_left_core_kept_notice_delivery.py
new file mode 100644
index 00000000000..c2a92ace934
--- /dev/null
+++ b/tests/agent/test_left_core_kept_notice_delivery.py
@@ -0,0 +1,70 @@
+"""Notices a left-core migration kept for a home (a gateway start, a CLI resolution) reach the first turn
+someone sees: an agent nobody watches (cron run, subagent, background fork) starts and runs without
+claiming them, so they are not dropped on an agent that has no way to show them."""
+from types import SimpleNamespace
+
+import pytest
+
+import hermes_cli.left_core_migration as lcm
+from agent.agent_init import _load_tools
+from agent.status_output import StatusOutputMixin
+from agent.turn_context import _reset_per_turn_agent_state
+
+KEPT = "✓ GitHub Copilot moved out of core — installed the 'github-copilot' plugin from the catalog."
+
+
+class Agent(StatusOutputMixin):
+ log_prefix = ""
+ quiet_mode = save_trajectories = _use_prompt_caching = False
+ ephemeral_system_prompt = _compression_warning = _memory_store = None
+ status_callback = notice_callback = tool_progress_callback = None
+ api_mode = "anthropic_messages"
+ max_iterations = 1
+
+ def __init__(self, platform, **attrs):
+ self.platform, self.printed = platform, []
+ self._tool_guardrails = SimpleNamespace(reset_for_turn=lambda: None)
+ self._warning_presentation_enabled = lambda: True
+ self.__dict__.update(attrs)
+
+ def _vprint(self, message, **kwargs):
+ self.printed.append(message)
+
+
+def home(tmp_path, monkeypatch):
+ import model_tools
+ monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+ monkeypatch.setattr(lcm, "_attempted", set())
+ monkeypatch.setattr("hermes_cli.plugins.discover_plugins", lambda: None)
+ monkeypatch.setattr(model_tools, "get_tool_definitions", lambda **kw: [])
+ monkeypatch.setattr(model_tools, "check_toolset_requirements", dict)
+ lcm._queue_notice(tmp_path, KEPT) # kept by the gateway's start
+ return tmp_path
+
+
+def _start_and_run_a_turn(agent):
+ _load_tools(agent, None, None)
+ _reset_per_turn_agent_state(agent)
+ return agent
+
+
+def test_unwatched_agents_leave_kept_notices_for_the_chat_agent(home):
+ notices = []
+ _start_and_run_a_turn(Agent("cron"))
+ _start_and_run_a_turn(Agent("subagent", _delegate_depth=1, notice_callback=notices.append))
+ _start_and_run_a_turn(Agent("telegram", _persist_disabled=True, suppress_status_output=True,
+ notice_callback=notices.append)) # a background-review fork
+ assert notices == []
+ chat = Agent("telegram")
+ _load_tools(chat, None, None)
+ chat.notice_callback = notices.append # the gateway wires it per turn, after __init__
+ _reset_per_turn_agent_state(chat)
+ _reset_per_turn_agent_state(chat)
+ assert [notice.text for notice in notices] == [KEPT]
+
+
+def test_a_cli_turn_prints_what_another_process_kept(home):
+ agent = _start_and_run_a_turn(Agent("cli"))
+ assert agent.printed == [KEPT]
+ assert lcm._claim_notices(home) == []
diff --git a/tests/hermes_cli/test_left_core_migration.py b/tests/hermes_cli/test_left_core_migration.py
index 189e71d7054..0e645ae2165 100644
--- a/tests/hermes_cli/test_left_core_migration.py
+++ b/tests/hermes_cli/test_left_core_migration.py
@@ -250,6 +250,22 @@ def test_gateway_start_outcome_waits_for_the_first_agent(tmp_path, monkeypatch):
assert lcm.recover_at_startup(say=said.append) == [] and len(said) == 1
[email protected]("gateway_start", [False, True])
+def test_an_agent_start_install_of_a_platform_keeps_the_restart_hint(tmp_path, monkeypatch, gateway_start):
+ """An agent start keeps its outcome for the next turn someone sees, with the hint to restart the gateway
+ serving the home; the gateway's own start loads the platform right after, so it needs none."""
+ home = _home(tmp_path, env="HASS_TOKEN=abc\n")
+ monkeypatch.setenv("HERMES_HOME", str(home))
+ import pm.install
+ monkeypatch.setattr(pm.install, "lazy_installs_allowed", lambda: True)
+ monkeypatch.setattr(lcm, "_install_into", lambda h, consent=None: lambda name: {"ok": True})
+ monkeypatch.setattr(lcm, "_gateway_serves", lambda h: True)
+ assert lcm.recover_at_startup(gateway_start=gateway_start) == ["homeassistant"]
+ kept = lcm._claim_notices(home)
+ assert kept[0].startswith("✓ Home Assistant moved out of core")
+ assert any("hermes gateway restart" in message for message in kept) is not gateway_start
+
+
def test_the_migration_installs_once_so_a_removal_sticks(tmp_path, monkeypatch):
"""At most one automatic install per home: after `hermes plugins remove`, neither `hermes update`