Repository navigation
feat: show every Hermes Agent session live with an Agent Guild plugin for Hermes - #395
Conversation
… for Hermes Adds the Agent Guild plugin for Hermes and an optional Hermes Agent card. The plugin observes Hermes's hooks and reports every session, subagent, shell command and approval. The card lists them per profile, with working and waiting counts, whether or not every profile has reporting on. Hermes runs every terminal's turns in one shared gateway process, so none of it is shown on a terminal's card. The card's accounts are Hermes's own profiles: Default is the base home and each named account an existing profile, selected with hermes -p and discovered where -p resolves them, including custom HERMES_HOME values. Every Hermes command an account runs, for reporting setup, MCP or a terminal, gets the absolute home discovery resolved, so a relative HERMES_HOME reaches the same home wherever the command runs. Turning reporting on installs and configures the plugin with Hermes's own commands and shows progress. When one profile fails, the error names it and the profiles that report, the failed profile keeps no accepted token, and the card offers Turn off while any profile reports. Off clears the live state at once and restores it if switching off fails. Turning reporting on or off runs one request at a time per Hermes home, so a failed request never undoes another's setup. The tokens the manager accepts are kept in one record of its own, valid.json, and every change to it is saved before it counts; a change that cannot be saved fails and changes nothing. A record that cannot be read accepts no token and the card says why. Each profile's plugin reads its token and the manager's address from an owner-only copy, before every report, so no token is on a command line or in Hermes's settings, and a copy left behind is never accepted. A token is refused as soon as its last card goes or its reporting is turned off, also after a restart. The plugin reports straight to the manager on this machine, never through an HTTP proxy from the environment, while Hermes's own requests keep their proxy settings. Commands and subagent goals pass through Hermes's secret redaction and are left out when it fails. Heartbeats rebuild open sessions, waits and shells after lost events or a manager restart, and an unloaded plugin clears its state. The MCP switch writes mcp_servers.agent-guild in the profile's config.yaml with the manager's own launcher and data folder. CI checks the plugin against Hermes Agent v0.23.1 and the card in a browser. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…hecks out of CI Node 22's rmSync reports a deletion another process blocks as EBUSY, not EPERM, so the held-file precondition failed on Windows. Its folder cleanup then ran before the Python reader was killed, threw, and skipped the kill, leaving the test process running until the step timed out. Both held-file tests now accept EPERM or EBUSY, and stop and wait for their readers before any temporary file is removed, even when an assertion fails. The Hermes catalog gates download and install Hermes Agent, so they move from CI to a separate Hermes compatibility workflow (main, weekly and on demand) that no required check depends on. Pull requests test the plugin with local fixtures only. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…from Turning on Hermes reporting installed the plugin from GitHub main, so a manager could get a plugin of another version, and a build made before the plugin reached main could not install it at all. A release now names the commit it was built from (agentGuild.commit, stamped in the pack step and checked in the tarball) and installs the plugin with `hermes plugins install --ref <commit>`, through Hermes's own install and its checks. An install counts only once Hermes records that commit. A plugin of another commit keeps reporting: whether it is current and whether it reports are apart. The card offers Update plugin, which re-installs this release's commit with --force in the profiles that report, and no other; Hermes swaps a plugin in only once the new one is installed, so a profile whose update fails keeps the plugin it had, and the error says so. Nothing is reinstalled when Agent Guild starts. A build that names no commit installs no plugin and says why; AGENT_GUILD_HERMES_PLUGIN_COMMIT names one for development. It still turns on a plugin Hermes already has. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ate per Hermes home Turning Hermes reporting off revoked a profile's token last, behind two Hermes commands that both had to succeed. Hermes answers `config unset` for a setting that is not there with "Config key not set" and exit 1, so a setting removed by hand, or by a teardown before, failed every later attempt before the token was revoked, and the first profile that failed stopped the others from being turned off. Now every step is tried and the token is revoked whatever Hermes answers; Hermes's "Config key not set" counts as already removed; turning off goes on through every profile, and the error names each failure. A token that still cannot be revoked keeps the card from showing reporting off: Turn off stays on offer, with a note that says the token is still accepted, so it can be tried again. The plugin's state was cached by card while tokens and live activity are by Hermes home, so a second card of the same home kept showing reporting off, and a stale Update plugin. It is cached by home now, and every card of a home that changed is described again. fake-hermes answers `config set` and `config unset` as Hermes does. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ith each other Three races let what Agent Guild shows or accepts drift from what was last changed for a Hermes home. Turning off read every profile's plugins first, so a profile Hermes could not list stopped the switch-off before any token was revoked. A teardown now goes on without that read: it asks Hermes to turn the plugin off all the same, revokes the token, and names the failed read with the rest. A report was checked as it arrived and applied once its body was read, so one whose token was revoked in between was still accepted and restored activity. The token is checked again just before the report is applied. A plugin read that started before a change and finished after it wrote the older state over the newer one, showing an enabled plugin as off with a false warning that its token was still accepted. Each home's change, in its setup turn, now makes a read that started before it obsolete, and that read is dropped. Each race has a regression test that failed before this change. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
_hermesRun threw at once when Hermes could not be found, before a caller's .catch() was attached, so turning off left the disable and setting steps by throwing past them and never revoked the token. A gateway that is still running may hold that token, so its revocation must not depend on finding the executable. _hermesRun is async now, so that failure arrives like any other, and the teardown names each distinct failure once. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…confirms it After a failed update, Agent Guild re-read Hermes's plugins, ignored a read that failed, and compared its cached state instead, so it could say "It keeps reporting with the plugin it had" when Hermes had in fact replaced the plugin. A real Hermes did exactly that: its update published the new commit, then failed in its own cleanup and refused every command after. Now the profile is asked again at once: the error names the plugin Hermes has only as that answer gives it, and says the state is unknown when Hermes cannot be asked. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Each token file names the home its token was issued for, but the plugin read only the token and the address. Cloning a profile that reports, with its settings and plugins, gives the clone the source's AGENT_GUILD_HERMES_TOKEN_FILE, so the clone reported with the source's token, and its sessions and approvals showed under the source profile though reporting was never turned on for it. The plugin now takes its profile's home from Hermes's get_hermes_home() in the hook, where Hermes sets the profile (its reporting thread starts with no profile context), and sends only when the token file names that home. When it does not, or Hermes cannot name the home, it sends nothing and says once why. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Finding: Hermes profile-root precedence ( I tested real Hermes v0.23.1 (
Nothing touched the native The resolver the finding cites, |
What
Hermes Agent runs much of its work outside terminals: its gateway serves CLI, Telegram and cron sessions. This adds Hermes as an optional provider and makes that gateway activity visible, read-only, next to the coding agents.
hermes -p. Every Hermes command (reporting setup, MCP, terminals) runs with the absolute home that discovery resolved. Terminal sessions stay separate: gateway activity is never shown on a terminal's card.plugins/hermes/agent-guild). It reports sessions, subagents, shell commands and approvals to the local manager, with heartbeats that rebuild what lost events or a manager restart dropped. Commands and subagent goals pass through Hermes's secret redaction, and are left out when it fails. It reports straight to the manager, never through an HTTP proxy. Existing profiles keep their configuration, and a running gateway loads the plugin without a restart.hermes plugins install --ref <commit>at the commit this release was built from. That goes through Hermes's own install and checks, and an install counts only once Hermes records that commit.valid.jsonis the single record of accepted tokens; every change is saved before it counts. A report is accepted only if its token is still valid when the report is applied. An unreadable record accepts nothing, and the card says why. No token appears on a command line or in Hermes's settings.agentGuild.commitinpackage.json, andcheck-tarball.mjs --commitverifies it. A build without the stamp installs no plugin unlessAGENT_GUILD_HERMES_PLUGIN_COMMITnames a commit.hermes-compat.yml; its results are an early warning of upstream breakage, not release verification.reportingUpdateon providers, and{ update: true }onPOST /providers/:id/reporting. The docs describe these, the card andPOST /hermes/hook.Verification
tests/hermes.test.mjs(50 tests), on Node 22 and 24. It covers the plugin against a real manager, redaction, heartbeats, profiles, and token durability and restart. It also has deterministic regression tests for each lifecycle defect found in review:tests/browser/hermes-reporting.mjs: the switch, partial failure, Update plugin, and live activity kept off terminal cards.tests/package.test.mjs: the release commit check. The release pack steps were reproduced locally in Linux: the stamp lands in the tarball, and a wrong or missing stamp fails the check.Before merge: CI on this branch, and a check against a real Hermes v0.23.1 in a disposable environment. The check covers a pinned install recording the commit, a failed update keeping the old plugin (failing in Hermes's replacement step), and a successful update. It uses this branch's commit. The release's own merge commit is a different commit with identical plugin files, so its stamp and its first pinned install establish the final link. This check does not verify it.
Known limitations
hermes plugins list --jsonshows.check-tarball.mjspass needs the binaries CI builds, so only the release's pack step proves it.git pinned@…. Nothing runs the real-Hermes lifecycle automatically.🤖 Generated with Claude Code