Skip to content

feat: show every Hermes Agent session live with an Agent Guild plugin for Hermes - #395

Merged
oddessentials merged 8 commits into
mainfrom
feat/hermes-plugin
Nov 16, 2026
Merged

oddessentials merged 8 commits into
mainfrom
feat/hermes-plugin

Conversation

@oddessentials

@oddessentials oddessentials commented Nov 15, 2026 •

Copy link
Copy Markdown
Owner

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 Agent card (optional, off by default; Cards → More cards → Nous Research). Its accounts are Hermes's own profiles, selected with 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.
  • Agent Guild plugin for Hermes (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.
  • Agent reporting switch.
    • Turning reporting on installs the plugin with 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.
    • A plugin of another commit, for example after an upgrade, keeps reporting, and the card offers Update plugin. A failed update keeps the plugin that was there. Nothing is reinstalled when Agent Guild starts.
    • Turning reporting off goes through every profile. It revokes each token even when Hermes fails a step, can't list the plugin, or is no longer on PATH, since a gateway that is still running may hold the token. An already-absent setting counts as removed.
    • A token that can't be revoked keeps Turn off on the card, with a note.
    • On and off run one at a time per Hermes home. Cards that share a home show the same state, and a plugin read overtaken by a change is dropped.
  • Report tokens. valid.json is 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.
  • Releases stamp agentGuild.commit in package.json, and check-tarball.mjs --commit verifies it. A build without the stamp installs no plugin unless AGENT_GUILD_HERMES_PLUGIN_COMMIT names a commit.
  • CI. Required checks use local fixtures only. The real-Hermes catalog gates moved to a separate, nonblocking hermes-compat.yml; its results are an early warning of upstream breakage, not release verification.
  • API: reportingUpdate on providers, and { update: true } on POST /providers/:id/reporting. The docs describe these, the card and POST /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:
    • an absent setting, a repeated teardown and a partial failure;
    • a token that can't be revoked;
    • cards sharing a home;
    • a plugin-list failure during teardown;
    • a report in flight across a revocation;
    • a stale plugin read;
    • Hermes missing from PATH;
    • pinned install, update, an install Hermes doesn't record, and a build without the stamp.
  • 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

  • The out-of-date check compares the first 8 characters of the commit, which is all hermes plugins list --json shows.
  • A full check-tarball.mjs pass needs the binaries CI builds, so only the release's pack step proves it.
  • While Hermes is missing from PATH, the card hides the reporting row. Turning off through the API, or once Hermes is back, still revokes the tokens.
  • The fixtures copy Hermes 0.23.1's wording for "Config key not set" and git pinned@…. Nothing runs the real-Hermes lifecycle automatically.

🤖 Generated with Claude Code

oddessentials and others added 3 commits November 15, 2026 01:10
… 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>
oddessentials and others added 3 commits November 15, 2026 11:39
…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>
@oddessentials oddessentials reopened this Nov 15, 2026
oddessentials and others added 2 commits November 15, 2026 13:21
…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>
@oddessentials

Copy link
Copy Markdown
Owner Author

Finding: Hermes profile-root precedence (src/manager/hermes.mjs:41). Not reproducible; resolved by verification, no change.

I tested real Hermes v0.23.1 (3b421578588243f920886e6fe79a6faa87ea026e) in a disposable container as a non-root user. HERMES_HOME was set to ~/.hermes/isolated, and a profile named work existed in both the native root and the isolated home. Agent Guild launched its usual commands through its own API:

Command Agent Guild runs Where it resolved
hermes -p default config env-path ~/.hermes/isolated/.env
hermes -p work config env-path ~/.hermes/isolated/profiles/work/.env
Reporting setup: home check, config set, plugin install HTTP 200; the token setting and the plugin were written under ~/.hermes/isolated
MCP on for work wrote ~/.hermes/isolated/profiles/work/config.yaml
Terminal session for work its hermes process had files open only in ~/.hermes/isolated/profiles/work
Agent Guild profile discovery the same ~/.hermes/isolated root and the same profiles

Nothing touched the native work profile, and reporting setup passed validation.

The resolver the finding cites, get_default_hermes_root in hermes_constants.py, isn't used by these explicit -p commands. They resolve through resolve_profile_env → profile_root_for_env_home, which keeps HERMES_HOME as the profile root. Applying the proposed native-root rule would point Agent Guild at the native work profile while Hermes keeps using isolated/profiles/work, which is the mismatch the finding describes. The resolver and the fixture stay as they are.

@oddessentials
oddessentials merged commit 07d4ad7 into main Nov 16, 2026
35 checks passed
@oddessentials
oddessentials deleted the feat/hermes-plugin branch November 16, 2026 04:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant