feat(hermes): add current plugin and MCP integration

[CommanderTurtle]

feat(hermes): add current plugin and MCP integration

Summary

This PR revives the intent of #425 as a clean implementation against the
current Context Mode and Hermes Agent APIs.

It adds:

• a standard-library-only Hermes Python plugin;
• proactive routing through current public Hermes hooks;
• bounded fallback for oversized native tool results;
• current mcp__context_mode__ctx_* tool guidance;
• Hermes setup and platform documentation;
• the requested Vitest adapter coverage plus an extended pytest suite.

This is not a cherry-pick of the old PR. Its final head became an orphaned
full-repository snapshot after force-push history changes, and several Hermes
contracts have changed since then.

Motivation

Hermes already supports MCP and a public Python plugin system. Context Mode can
therefore remain the normal MCP execution/indexing server while a small native
plugin enforces routing before high-output terminal calls enter model context.

The split is intentional:

• Context Mode owns execution, indexing, search, statistics, and diagnostics.
• The Hermes plugin owns only routing, bounded fallback, and local metrics.
• No Hermes source patch or private API is required.

Current Hermes Contract Validation

The implementation was checked against current Hermes Agent main at
a41d280f95c69f67380358b305b62345934ecaf3.

• register(ctx) and all six registered hooks are accepted by the current
  PluginManager.
• pre_tool_call returns Hermes' consumed
  {"action":"block","message":"..."} schema.
• pre_llm_call returns {"context":"..."} once per session.
• transform_tool_result returns a replacement string for eligible oversized
  results.
• MCP names follow current Hermes' exact
  mcp__<sanitized_server>__<sanitized_tool> format.
• on_session_end is treated as a per-turn persistence boundary.
• on_session_finalize performs actual teardown and state release.

Reviewer Feedback From #425

From intent in code-review #4233782693

• Link the real Hermes repository and official plugin/hook/MCP docs.
• Verify real hook signatures and runtime block-schema handling.
• Add tests/adapters/hermes.test.ts.
• Test disallowed commands.
• Test allowed commands.
• Test first-turn guidance.
• Test no subsequent reinjection.
• Bound guidance state at approximately 1,000 entries.
• Use pytest for the extended Python test suite.
• Document current installation and verification commands.
• Exercise the adapter through current Hermes and a real Context Mode MCP
  stdio process.

The bounded state is stricter than requested: it is concurrency-safe, evicts
oldest entries, and never exceeds exactly 1,000 session IDs.

Safety and Failure Model

• The plugin has no third-party Python dependencies.
• Metrics writes fail open.
• Oversized output filenames combine nanosecond time and a random suffix.
• UTF-8 output is stored losslessly.
• Preview text and XML attributes are escaped.
• Side-effect tools are never sandboxed by the fallback.
• Full Context Mode pre-compaction/session extraction is not claimed for Hermes.

Verification

Test	Result
Hermes adapter pytest suite	23 passed
Hermes adapter Vitest suite	5 passed
TypeScript typecheck	passed
Current Hermes plugin-manager suite	116 passed
Current Hermes MCP naming/registration subset	16 passed
Current Hermes + real Context Mode MCP harness	passed

The full Context Mode Node/Vitest run produced 4,660 passes, 56 skips, and 34
failures. All failures are pre-existing environment prerequisites on the Windows
test host: no Git Bash for POSIX-shell assertions, no symlink privilege for
symlink security tests, and no npm executable in the isolated Node runtime.
The Hermes adapter tests passed.

Manual Validation Before Merge

• Register the server with
  hermes mcp add context-mode --command npx --args -y context-mode.
• Install and enable .hermes-plugin.
• Run hermes mcp test context-mode.
• Confirm ctx stats dispatches.
• Confirm a high-output terminal request is blocked and rerouted.
• Confirm a bounded command such as git status remains allowed.

Maintenance

I am willing to own Hermes-specific issue triage and keep this adapter aligned
with future public Hermes hook and MCP contract changes.

References

• Original proposal: feat: add Hermes Agent support — configs, plugin, README #425
• Hermes Agent: https://github.com/NousResearch/hermes-agent
• Plugins: https://hermes-agent.nousresearch.com/docs/user-guide/features/plugins
• Hooks: https://hermes-agent.nousresearch.com/docs/user-guide/features/hooks
• MCP: https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp

Table of Contents

Implementation of PR #425 revival against current upstream code.

• CommanderTurtle/context-mode - main (implementation) - Against 1618d97

Full revival report (click to expand)

Details

Context Mode PR 425 Revival Report

Date: 2026-07-20

Executive Finding

The Hermes Agent integration proposed in #425 remains
architecturally sound, but its final branch cannot be safely rebased. The last
PR commit is an orphaned full-repository snapshot after multiple force pushes.
This revival therefore reimplements the intent against current upstream APIs
instead of cherry-picking historical code.

The resulting adapter uses only documented Hermes plugin hooks and the normal
Context Mode MCP server. It has been validated against current checkouts of
both projects, including Hermes' real PluginManager, real block-directive
consumer, and real MCP stdio registration path.

Revisions Under Test

Project	Revision
Context Mode main	1618d9764921c66f3c9cdab8a45d2d8f7f0b0648
Hermes Agent main	a41d280f95c69f67380358b305b62345934ecaf3
Historical PR 425 final head	7555fad47f457b8bff28fe8b7a1c0af4e7d7419b

Both origin/main revisions were fetched and confirmed current immediately
before the final test pass.

Historical Intent Recovered

PR 425 proposed:

• a Python Hermes plugin;
• Context Mode routing instructions for Hermes;
• pre_tool_call blocking and pre_llm_call guidance;
• MCP registration and installation documentation;
• first-turn guidance state;
• Python tests, eventually migrated to pytest.

The owner and reviewers identified the following merge conditions:

Feedback	Revival response
Link the real Hermes repository and official docs.	Added current repository, plugin, hook, and MCP links in all Hermes documentation.
Prove hook signatures and block schema.	Verified from current Hermes source and exercised through get_pre_tool_call_directive().
Add tests/adapters/hermes.test.ts.	Added five Vitest tests, including all four specifically requested behaviors.
Test blocked and allowed commands.	Covered in Vitest, extended pytest tests, and current-Hermes integration.
Inject only on the first turn.	Covered in both test layers and the live compatibility harness.
Bound the guidance dictionary near 1,000 entries.	Implemented a lock-protected OrderedDict with exact 1,000-entry LRU eviction and threaded tests.
Use pytest for Python behavior tests.	Added 23 pytest cases while keeping the required Vitest bridge dependency-free.
Perform manual/runtime validation.	Exercised the plugin through current Hermes and launched the actual Context Mode MCP server over stdio.
Establish future ownership.	The proposed PR text includes an explicit maintainer-ownership statement for the submitter to confirm.

Discussion Chronology

• 2026-05-04: tayuLuc opened the proposal with configuration, plugin, README,
  and a six-step manual test plan.
• 2026-05-05: mksglu asked why the adapter was Python. The author correctly
  tied that choice to Hermes' Python-native plugin loader.
• 2026-05-06: EPPCOM-Solutions requested proof of the real Hermes API, the
  four specific Vitest behaviors, a bounded guidance map, and documentation
  cleanup. The review explicitly called the architecture defensible.
• 2026-05-06: mksglu required the contributor to own future Hermes issues,
  bugs, and improvements because the maintainer does not use Hermes.
• 2026-05-06: the author acknowledged that the plugin was not ready to merge.
• 2026-05-06: SoTHISIsFitness recorded community interest and characterized
  the remaining blockers as tractable.
• 2026-05-07 to 2026-05-08: the maintainer asked for a concrete test process;
  the author selected pytest and moved the historical Python tests to it.
• 2026-05-09: the author reported an accidental incorrect merge/force-push.
  The maintainer then required manual testing before reopening.
• 2026-06-19: dfein38347g asked for the integration to be reopened; GitHub no
  longer allowed reopening the historical PR.

The current README no longer contains the duplicate Linux summary line noted
in the old review, so no historical merge-artifact deletion was carried over.

Current-API Corrections

The old patch is not merely stale source code. Several contracts changed or
were incorrect in the original proposal:

1. Hermes now exposes MCP tools as
   mcp__<sanitized_server>__<sanitized_tool>. The revived guidance uses
   mcp__context_mode__ctx_* exactly.
2. Current MCP CLI syntax is
   hermes mcp add context-mode --command npx --args -y context-mode.
3. on_session_end is a per-turn plugin boundary in the current agent loop.
   The plugin persists a snapshot there without discarding session state.
4. on_session_finalize is the actual CLI/gateway teardown boundary and now
   performs final persistence and state release.
5. Oversized output names use nanosecond time plus a random suffix, preventing
   parallel calls from overwriting one another.
6. The required Vitest tests run on Windows as well as POSIX systems; there is
   no platform skip.

Implemented Surface

File	Purpose
context-mode/.hermes-plugin/plugin.yaml	Current Hermes plugin manifest and six declared hooks.
context-mode/.hermes-plugin/__init__.py	Routing enforcement, output bounding, metrics, and lifecycle handling.
context-mode/.hermes-plugin/README.md	Exact installation, verification, storage, and behavior guide.
context-mode/configs/hermes/AGENTS.md	Optional project-level routing fallback.
context-mode/docs/adapters/hermes-agent.md	Current API contract and failure-model documentation.
context-mode/tests/adapters/hermes.test.ts	Required cross-runtime integration tests.
context-mode/tests/adapters/hermes_probe.py	Dependency-free Python bridge for Vitest.
context-mode/tests/adapters/hermes_test.py	Extended behavioral, concurrency, UTF-8, and lifecycle tests.
context-mode/package.json	Publishes .hermes-plugin in the npm package.
current_hermes_compatibility_test.py	External current-Hermes/current-MCP compatibility harness.

Safety and Resource Invariants

• Plugin implementation uses only the Python standard library.
• Metrics failures fail open and cannot block normal Hermes operation.
• Guidance tracking is lock-protected and capped at exactly 1,000 sessions.
• Output writes are UTF-8, collision-safe, and preserve full content.
• XML-like previews escape untrusted result text and path attributes.
• Destructive or side-effect tools are excluded from fallback sandboxing.
• Context Mode remains the execution/index/search implementation; the Python
  plugin does not duplicate the MCP server.
• Full Context Mode pre-compaction extraction is not claimed for Hermes.

Conclusion

The historical design can be revived cleanly, but only as a current-API
reimplementation. The reviewer blockers are resolved in code and tests. The
remaining work before submission is human policy rather than engineering:
choose the target branch, confirm long-term Hermes-specific issue ownership,
and run the documented manual conversation check in a maintainer-approved
Hermes installation.

---

Test Results (click to expand)

Details

Verification Results

Date: 2026-07-20

Environment

• Windows 11
• Node.js v24.14.0
• Bun 1.3.14
• Python 3.12.10
• uv 0.11.29

Dependencies were resolved in the cloned repository's isolated .venv, and the current Context Mode MCP server was launched only for the compatibility test.

Required and Targeted Tests

Verification	Result
Python syntax compilation	Passed
pytest tests/adapters/hermes_test.py -q	23 passed
vitest run tests/adapters/hermes.test.ts	5 passed
tsc --noEmit	Passed
Current Hermes plugin-manager tests	116 passed
Current Hermes MCP naming/registration tests	16 passed
Current Hermes + real Context Mode MCP harness	Passed
git diff --check	Passed

The live compatibility harness established all of the following through current
Hermes code:

{
  "block_schema": "consumed by current Hermes",
  "ctx_stats": "dispatched",
  "guidance": "first turn only",
  "hooks": 6,
  "mcp_tools_registered": 15,
  "plugin": "loaded"
}

Full Context Mode Suite

The full suite was run through Node.js rather than Bun because Context Mode's
test matrix exercises Node-specific SQLite and shell behavior.

Result	Count
Passed	4,660
Failed assertions	34
Skipped	56

The six affected test files are unrelated to the Hermes adapter. Their failures
are attributable to this Windows host's missing test prerequisites:

• POSIX-shell assertions ran under Windows PowerShell because Git Bash is not
  installed/discoverable.
• Symlink security tests received Windows EPERM because Developer Mode or an
  elevated symlink privilege is unavailable.
• One package-content test could not invoke npm because this isolated Node
  runtime provides node.exe but no npm executable.

The machine-readable full report is full-vitest-results.json. The Hermes
Vitest file passed within the same test environment.

An earlier bun run test attempt was not used as release evidence: Bun cannot
faithfully execute this repository's Node-specific better-sqlite3, Zod, shell,
and symlink assumptions. Its pretest build and bundle assertions did pass.

Manual Check Still Recommended

Before merge, perform one maintainer-approved installed-session check:

1. Register context-mode with the current Hermes MCP CLI syntax.
2. Install and enable .hermes-plugin.
3. Confirm hermes mcp test context-mode succeeds.
4. Ask Hermes for ctx stats.
5. Prompt a high-output curl request and confirm Hermes receives the block
   message and selects the prefixed Context Mode tool instead.
6. Run a short native command such as git status and confirm it is allowed.

---

Source References (click to expand)

Details

Source References

Historical PR

• PR: feat: add Hermes Agent support — configs, plugin, README #425
• Final historical head fetched locally as pr-425-original:
  7555fad47f457b8bff28fe8b7a1c0af4e7d7419b

The PR conversation contains the original architecture, the three blocking
review findings, the pytest recommendation, the owner's maintenance request,
and the requirement for manual validation.

Current Hermes Sources Used

• Repository: https://github.com/NousResearch/hermes-agent
• Plugin manager and hook contracts: hermes-agent/hermes_cli/plugins.py
• CLI lifecycle boundaries: hermes-agent/cli.py
• Per-turn hook dispatch: hermes-agent/agent/turn_finalizer.py
• Gateway finalize boundaries: hermes-agent/gateway/run.py
• MCP naming and registration: hermes-agent/tools/mcp_tool.py
• Plugin tests: hermes-agent/tests/hermes_cli/test_plugins.py
• MCP tests: hermes-agent/tests/tools/test_mcp_tool.py

Official Hermes Documentation

• Documentation root: https://hermes-agent.nousresearch.com/docs/
• Plugins: https://hermes-agent.nousresearch.com/docs/user-guide/features/plugins
• Event hooks: https://hermes-agent.nousresearch.com/docs/user-guide/features/hooks
• MCP: https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp

Current Hermes source and tests are authoritative for the exact MCP tool prefix.
They use double separators: mcp__server__tool. Any older single-underscore
example should not be copied into this integration.

---

Verified

• 23 Hermes pytest cases passed.
• 5 requested Vitest adapter tests passed.
• 116 current Hermes plugin-manager tests passed.
• 16 current Hermes MCP registration/naming tests passed.
• TypeScript typecheck passed.
• Live compatibility harness loaded six hooks, consumed the real block schema, registered 15 Context Mode MCP tools, and dispatched ctx_stats.
• Full Context Mode suite: 4,660 passed, 56 skipped, 34 environment-only failures from missing Git Bash, Windows symlink privilege, and npm.
• No stale single-underscore MCP names or old installation syntax remain.

The implementation addresses every material comment from PR #425, including bounded guidance state, pytest adoption, public API proof, current MCP naming, manual-test guidance, and maintainership language. It is grounded in the current Hermes repository, plugin API, hook contracts, and MCP documentation.

[CommanderTurtle]

LGTM 👍🥳

[CommanderTurtle]

Further references after config. Really appreciate all the work you guys do, as I never knew this was missing from my harness.

It's night and day over the /compact's used by Hermes users. Life changing, ever since my first time running into /compact being my most ran command.

Happy to help out if there is anything else I can do here.