docs/tests: add Hermes + OMNI integration best practices

[fajarhide]

Summary

• Adds docs/HERMES_OMNI_INTEGRATION.md with prerequisites, install, verification, tuning, pitfalls, decision tree, and ops checklist for Hermes + OMNI.
• Extends src/agents/hermes.rs tests to cover Hermes default config and command patterns.
• Updates README.md with a link to the new integration guide.

Validation

• cargo test --lib agents::hermes::tests passed (7/7).
• cargo test --lib passed (357/357).

Related

• Complements existing feat/hermes-update integration; this branch focuses on operational best practices.

PR Auto Describe

Summary

Added first-class Hermes Agent integration with automated setup (omni init --hermes), comprehensive documentation, and native OMNI MCP tools for autonomous loops. The integration now auto-registers the MCP server, enables Hermes compression, and surfaces startup validation warnings directly into the Hermes system prompt for self-healing.

---

Key Changes

• omni init --hermes fully automated — installs plugin, registers MCP server, enables compression, writes Hermes-optimized OMNI config (no manual steps)
• Startup validation — new validate_startup() function checks MCP registration, compression, plugin files, and OMNI config; injects warnings into Hermes systemPromptAddition
• Context pressure → compaction feedback loop — Hermes plugin now calls ctx.compact() when OMNI emits pressure warnings
• New Hermes signal filter (signals/tools/hermes.toml) — strips Hermes tool wrappers, headers, separators
• Documentation — HERMES_OMNI_INTEGRATION.md (setup, verification, best practices, pitfalls) and hermes-loop.md (Maker-Checker pattern)

---

Detailed Breakdown

Integration (src/agents/hermes.rs)

Function	Purpose
validate_startup()	Checks 4 failure modes; returns formatted warning string for Hermes systemPromptAddition
configured_compression()	Detects compression.enabled: true in Hermes config
hermes_default_config()	Returns mode="efficient", all distillations on, pinned files (AGENTS.md, .omni/CONTEXT.md)
hermes_command_patterns()	Returns Hermes tool names for signal matching

install() enhanced:

• Auto-inserts OMNI MCP server block into ~/.hermes/config.yaml
• Auto-enables Hermes compression (threshold: 0.50, target_ratio: 0.20)
• Appends [agents.hermes] section to ~/.omni/config.toml without overwriting
• Reports all actions/warnings with green ✓ / yellow →

doctor_check() enhanced:

• Reports 4 items: Plugin, MCP Server, Compression, OMNI Config
• Auto-fix mode re-runs install() to repair all gaps
• Warns on missing [agents.hermes] section

Python plugin (__init__.py) enhanced:

• on_post_tool_call checks stdout for [omni:context pressure: WARNING/CRITICAL] → calls ctx.compact()
• Forwards OMNI_LOOP_ID, OMNI_LOOP_GOAL, OMNI_LOOP_BUDGET env vars
• 5-second timeout, fail-open semantics

Hooks (src/hooks/session_start.rs)

• SessionStart now calls validate_startup() when agent_id == "hermes"
• Warnings injected via system_prompt_addition so agent sees them without extra commands

Signals (signals/tools/hermes.toml)

• match_command: terminal, read_file, web_search, browser_*, execute_code, delegate_task
• Strips ANSI, tool headers/trailers (term:, > , Tool Result, Hermes Gateway)
• Priority 150; preserves failure signals

---

Notes

• OMNI config writes are additive only — never overwrites existing user config
• MCP server insertion targets near plugins: block; falls back to EOF if not found
• Compression auto-enable skipped if Hermes config missing (deferred until Hermes init)

---

Breaking Changes

None. All changes are additive or modify only new integration scaffolding. Existing OMNI behavior and configs are preserved.

Last updated: 2026-06-15 04:39:23