From dc2225d3842ad02e7e009dc93ff06f19ae12e9d3 Mon Sep 17 00:00:00 2001 From: ginnoir Date: Sat, 27 Jun 2026 05:45:34 -0500 Subject: [PATCH] docs: fold ecosystem expansion + delegation fabric into Hermes plan Add hermes-motif (skill discovery; complementary to curator, not a rival), hermes-web-search-plus (mature multi-provider search, pairs with camofox), optional llmtrim/rtk context efficiency, and the claude/codex/cursor/antigravity delegation fabric. Record that Claude Code + Codex are now installed on valhalla. Co-Authored-By: Claude Opus 4.8 --- ...2026-06-27-hermes-ecosystem-integration.md | 217 +++++++++++++++++- ...-27-hermes-ecosystem-integration-design.md | 92 ++++++++ 2 files changed, 299 insertions(+), 10 deletions(-) diff --git a/docs/superpowers/plans/2026-06-27-hermes-ecosystem-integration.md b/docs/superpowers/plans/2026-06-27-hermes-ecosystem-integration.md index 5d3c485..f050e88 100644 --- a/docs/superpowers/plans/2026-06-27-hermes-ecosystem-integration.md +++ b/docs/superpowers/plans/2026-06-27-hermes-ecosystem-integration.md @@ -55,13 +55,20 @@ ssh -o BatchMode=yes ginnoir@valhalla "cp ~/.hermes/config.yaml ~/.hermes/config ``` Expected: a backup is created; directory listings print (note whether `~/.hermes/plugins` exists yet); `hermes` prints a version (≈ v0.17.0). Record the skills-dir path — confirms `~/.hermes/skills` is correct for later tasks. -- [ ] **Step 3: Confirm Codex and Claude Code are invocable from the host as ginnoir** +- [x] **Step 3: Confirm Codex and Claude Code are invocable — DONE 2026-06-27 (installed this session)** -Run: +Both delegation CLIs were installed on valhalla this session: +- `claude` → `~/.local/bin/claude` **v2.1.195** (login pending) +- `codex` → `/usr/bin/codex` **v0.142.3** (login pending; harmless PATH-alias warning at install) + +**Gotcha recorded:** `/home/ginnoir/.claude` existed as an empty **root-owned** dir (created Jun 17, +likely a prior sudo op) and blocked the installer until `sudo chown ginnoir:ginnoir ~/.claude`. Codex +global install needs `sudo` (npm global prefix is `/usr`). Re-verify any time with: ```bash -ssh -o BatchMode=yes ginnoir@valhalla "bash -lc 'which codex; which claude; codex --version 2>&1 | head -1; claude --version 2>&1 | head -1'" +ssh -o BatchMode=yes ginnoir@valhalla "bash -lc 'claude --version; codex --version'" ``` -Expected: paths for both `codex` and `claude`, and a version line each. (Uses `-lc` to get the login PATH.) **If either is missing**, the ACP delegation skill (Task 2) can still install but its `codex`/`claude-code` targets will be non-functional until they're on the service PATH — note this for ginnoir. +**ginnoir must log in** to each (`claude`, then `codex login`) before Task 2's external delegation +smoke-tests will succeed. Cursor + Antigravity targets are added later in **Task 10**. - [ ] **Step 4: Checkpoint** @@ -184,6 +191,52 @@ No git commit. Record: plugin at `~/.hermes/plugins/curator-evolver`, DB at `... --- +## Task 3b: Install `hermes-motif` (skill DISCOVERY, proposal-only) + +> Complements curator-evolver — does **not** compete with it (spec §7.1). motif *discovers new* +> skills by mining repeated tool sequences; curator *refines existing* ones. **Zero P100 cost** +> (makes no LLM calls). Together with eagle-eye (routing) they form a skill factory: +> motif creates → curator refines → eagle-eye routes. + +**Files:** +- Host: `~/.hermes/plugins/` (motif plugin), `~/.hermes/plugins//plugin/plugin.yaml`. + +- [ ] **Step 1: Clone and read; confirm proposal-only config** + +Run: +```bash +ssh -o BatchMode=yes ginnoir@valhalla "git -C /storage1/hermes/workspace/clones clone https://github.com/Saurav0989/hermes-motif && sed -n '1,160p' /storage1/hermes/workspace/clones/hermes-motif/README.md && cat /storage1/hermes/workspace/clones/hermes-motif/plugin/plugin.yaml 2>&1" +``` +Expected: README + `plugin.yaml` print. **Confirm `auto_install: false`** (proposal-only) and note +`min_occurrences` / sequence-length thresholds. Note the referenced Hermes trace bug (#12922) that +can affect trace completeness — acceptable for a proposal-only trial. + +- [ ] **Step 2: Install the plugin** + +Run (per its README — clone + pip + `scripts/install_plugin.sh`): +```bash +ssh -o BatchMode=yes ginnoir@valhalla "cd /storage1/hermes/workspace/clones/hermes-motif && bash scripts/install_plugin.sh 2>&1 | tail -20" +``` +Expected: the plugin lands under `~/.hermes/plugins/` and registers. (If the script expects a +different layout, follow the README's exact steps.) + +- [ ] **Step 3: Verify it mines and PROPOSES without modifying skills** + +Restart the gateway, run the agent through a couple of repeated multi-tool workflows, then check for +proposals (drafts), confirming nothing under `~/.hermes/skills` was auto-written: +```bash +ssh -o BatchMode=yes ginnoir@valhalla "sudo systemctl restart hermes-gateway.service && sleep 5 && find ~/.hermes/plugins -iname '*propos*' -o -iname '*draft*' 2>/dev/null | head && find ~/.hermes/skills -newermt '-10 minutes' -type f 2>/dev/null" +``` +Expected: proposal/draft artifacts may appear under the plugin dir; the second `find` is **empty** +(no skill files auto-modified) — proves `auto_install: false` safety. + +- [ ] **Step 4: Checkpoint** + +No repo commit (host-side). **Rollback** = remove the motif plugin dir + restart gateway. Record in +`memory/hermes-extensions.md` alongside curator (skill factory: motif=create, curator=refine). + +--- + ## Task 4: Document Phase 1 in memory + vault (durable knowledge) **Files:** @@ -192,7 +245,7 @@ No git commit. Record: plugin at `~/.hermes/plugins/curator-evolver`, DB at `... - [ ] **Step 1: Write the memory file** -Create `memory/hermes-extensions.md` (frontmatter `type: project`) recording: acp-skill installed (delegation to hermes/codex/claude-code, 900s/24k caps), curator-evolver installed **report-only** (CPU ranking, no `--semantic`, no auto-apply flags), exact paths and rollback commands, and the host-vs-repo boundary. Link `[[llm-stack-hermes]]`, `[[multi-agent-tool-configs]]`, `[[obsidian-app-on-valhalla]]`. +Create `memory/hermes-extensions.md` (frontmatter `type: project`) recording: acp-skill installed (delegation to hermes/codex/claude-code/cursor/antigravity, 900s/24k caps); curator-evolver installed **report-only** (CPU ranking, no `--semantic`, no auto-apply flags); **motif** installed proposal-only (skill factory: motif creates → curator refines → eagle-eye routes); **claude v2.1.195 + codex v0.142.3 installed on valhalla 2026-06-27** (login pending; `~/.claude` was root-owned → chowned); exact paths and rollback commands; the host-vs-repo boundary. Link `[[llm-stack-hermes]]`, `[[multi-agent-tool-configs]]`, `[[obsidian-app-on-valhalla]]`. - [ ] **Step 2: Add the MEMORY.md index pointer** @@ -333,6 +386,47 @@ Repo changes are committed (Step 5). Update `memory/hermes-extensions.md` + the --- +## Task 5b: Install `hermes-web-search-plus` (multi-provider search; pairs with camofox) + +> Mature (v2.6.1, MIT, stdlib-only). Complements camofox (spec §7.2): search-plus *finds* via cheap +> provider APIs, camofox *browses/renders*. Lighter and higher-frequency — good default reach-for. + +**Files:** +- Host: `~/.hermes/plugins/` (plugin), provider key(s) in `~/.hermes/config.yaml` (or the plugin's config). + +- [ ] **Step 1: Install the plugin** + +Run: +```bash +ssh -o BatchMode=yes ginnoir@valhalla "bash -lc '~/.local/bin/hermes plugins install robbyczgw-cla/hermes-web-search-plus --enable'" +``` +Expected: plugin installs and enables. + +- [ ] **Step 2: Configure at least one provider key (free tier)** + +All provider keys are optional but ≥1 is needed to function. Pick a free-tier provider (e.g. Tavily, +Exa, or self-hosted SearXNG; Keenable has a keyless public tier). Add the key per the plugin's README +(read `/storage1/hermes/workspace/clones/...` or the plugin docs for the exact env/config key), then: +```bash +ssh -o BatchMode=yes ginnoir@valhalla "sudo systemctl restart hermes-gateway.service && sleep 5 && systemctl is-active hermes-gateway.service" +``` +Expected: gateway `active`. **Mind the tool-budget rule** — if it exposes both `web_search_plus` + +extract, that's fine (2 tools); don't also enable redundant search MCPs. + +- [ ] **Step 3: Smoke-test a search** + +Run: +```bash +ssh -o BatchMode=yes ginnoir@valhalla "~/.local/bin/hermes run 'search the web for the latest Hermes Agent release version and cite the source' 2>&1 | tail -20" +``` +Expected: the agent calls the search tool, returns a current result with a source URL. + +- [ ] **Step 4: Checkpoint** + +No repo commit (host-side). Document the chosen provider + key location in `memory/hermes-extensions.md`. + +--- + ## Task 6: Trial `eagle-eye` skill pre-filter (Class A, behind a switch) > Confirmed the chosen tool: eagle-eye is the **only** direct skill-router in the Hermes ecosystem @@ -382,6 +476,106 @@ No repo commit (host-side). Document the A/B result and final state (kept/cut) i --- +# PHASE 2b — Delegation fabric & context efficiency + +> Extends acp-skill (Task 2) from 3 targets to 4 external agents, and adds optional token-trimming. + +## Task 10: Wire Cursor + Antigravity into the delegation fabric + +**Files:** +- Host: Cursor + `agy` binaries; acp-skill config or a generic shell-agent skill in `~/.hermes/skills/`. + +- [ ] **Step 1: Install the Cursor CLI (official cursor.com)** + +Run: +```bash +ssh -o BatchMode=yes ginnoir@valhalla "bash -lc 'curl https://cursor.com/install -fsS | bash' && ssh -o BatchMode=yes ginnoir@valhalla 'bash -lc \"command -v cursor-agent && cursor-agent --version\"'" +``` +Expected: `cursor-agent` installs and prints a version. ginnoir logs in later. + +- [ ] **Step 2: Install the Antigravity CLI (`agy`) from the OFFICIAL Google source** + +Do **not** use blog-derived URLs. Get the exact installer from the official pages first: +`https://antigravity.google/download` and `https://antigravity.google/docs/gcli-migration`. Then run +the official one-line installer they document, e.g.: +```bash +ssh -o BatchMode=yes ginnoir@valhalla "bash -lc '' && ssh -o BatchMode=yes ginnoir@valhalla 'bash -lc \"command -v agy && agy --version\"'" +``` +Expected: `agy` (Go binary, ideal for headless SSH) installs and prints a version. Auth later via +keyring/Google sign-in or `ANTIGRAVITY_TOKEN`. + +- [ ] **Step 3: Confirm each agent answers in headless mode (after ginnoir logs in)** + +Run: +```bash +ssh -o BatchMode=yes ginnoir@valhalla "bash -lc 'claude -p \"say PONG\"; codex exec \"say PONG\"; cursor-agent -p --output-format json --trust \"say PONG\"; agy -p \"say PONG\"'" +``` +Expected: each prints PONG-ish output. **Cursor caveat:** `-p` has a known hang bug — always pass +`--output-format json` and wrap with a timeout (`timeout 120 cursor-agent ...`). + +- [ ] **Step 4: Extend acp-skill routing (or add a generic shell-agent skill)** + +Read `~/.hermes/skills/hermes-acp-orchestrator/SKILL.md` to see if `agent=` routing is extensible. +- **If extensible:** add `cursor` and `antigravity` targets mapping to the Step 3 invocations + (with the cursor timeout + json flags), honoring the `delegation:` `external_timeout_seconds: 900` + / `external_max_output_chars: 24000` caps. +- **If not:** add `~/.hermes/skills/shell-agent/SKILL.md` exposing **one** tool + `delegate(agent, goal)` that shells out to claude/codex/cursor/agy with the caps + cursor guard. + One tool keeps the surface within the tool-budget. +Then restart the gateway: +```bash +ssh -o BatchMode=yes ginnoir@valhalla "sudo systemctl restart hermes-gateway.service && sleep 5 && systemctl is-active hermes-gateway.service" +``` + +- [ ] **Step 5: End-to-end smoke-test each delegation target** + +Run one delegated task per agent (e.g. `agent=cursor`, `agent=antigravity`) and confirm output is +captured under the cap. Record any that hang/auth-fail for follow-up. + +- [ ] **Step 6: Checkpoint** + +No repo commit (host-side). Document the four-target fabric + cursor caveat in `memory/hermes-extensions.md`. + +--- + +## Task 11: (OPTIONAL) Context efficiency — llmtrim on the cloud-delegation path + +> Opt-in. Start where the win is unambiguous and local-risk-free: trimming the **cloud** delegation +> agents' traffic (Claude Code/Codex/Cursor → Anthropic/OpenAI). Defer the llama-swap-fronting idea +> until validated. `rtk-hermes` (shell-output trimming) is a separate lighter opt-in. + +**Files:** +- Host: llmtrim service + `HTTPS_PROXY` env for the delegation agents. + +- [ ] **Step 1: Install llmtrim and run setup** + +Run: +```bash +ssh -o BatchMode=yes ginnoir@valhalla "bash -lc 'npm install -g @llmtrim/cli@latest && llmtrim setup' 2>&1 | tail -20" +``` +Expected: installs; `setup` installs the name-constrained CA + background proxy. **Review the MITM-CA +trust implication first** — it's name-constrained to LLM API domains, but it's still a CA on the host. + +- [ ] **Step 2: Point the cloud delegation agents through it; measure** + +Ensure the delegation agents inherit `HTTPS_PROXY` (llmtrim sets this). Run a representative delegated +task via Claude Code/Codex and compare token counts / cost before vs after (llmtrim reports savings). +Keep only if the reduction is real with no quality loss. + +- [ ] **Step 3: (Later, separate) Evaluate llama-swap fronting + rtk-hermes** + +Document — do not implement here — the two deferred ideas: (a) llmtrim in front of `172.20.0.1:8090` +via `LLMTRIM_EXTRA_HOSTS` to shrink prompts and speed Pascal prefill (needs validation; unproven for +local OpenAI-compatible backends); (b) `rtk-hermes` (`pre_tool_call` shell rewrite) if the `rtk` +binary is available on Ubuntu. + +- [ ] **Step 4: Checkpoint** + +No repo commit. Record the decision + measured savings (or rejection) in `memory/hermes-extensions.md`. +`llmtrim uninstall` fully reverses the proxy + CA if rejected. + +--- + # PHASE 3 — UI trial: stand up BOTH, keep the winner > Decision resolved (spec §6.1): trial `hermes-ui` (Task 7) **and** `hermes-workspace` (Task 8) in @@ -570,11 +764,14 @@ One UI kept and documented in memory + vault; losers fully removed; repo reflect ## Self-Review (completed) -- **Spec coverage:** All 7 repos map to tasks — acp-skill (T2), curator-evolver (T3), camofox (T5), - eagle-eye (T6), hermes-ui (T7), hermes-workspace (T8 deploy), with the head-to-head keep-one - decision in T9; mission-control (explicitly skipped per spec §2.5/§5, no task — intentional). - Phase ordering, single-P100 discipline, host-vs-repo boundary, provenance/reversibility, and the - §6 decisions (all resolved 2026-06-27) are reflected. +- **Spec coverage:** Original 7 repos — acp-skill (T2), curator-evolver (T3), camofox (T5), + eagle-eye (T6), hermes-ui (T7), hermes-workspace (T8 deploy) + keep-one decision (T9); + mission-control (skipped per spec §2.5/§5, intentional). **Ecosystem expansion (spec §7)** — + hermes-motif (T3b), hermes-web-search-plus (T5b), delegation fabric for cursor+antigravity (T10), + optional llmtrim/rtk context efficiency (T11). Claude Code + Codex install is **done** (T1 Step 3). + Phase ordering, single-P100 discipline, host-vs-repo boundary, provenance (official installers + only — Antigravity URL verified to `antigravity.google`), reversibility, and the §6 decisions are + all reflected. - **Placeholders:** None of the prohibited kinds. Where a third-party command form can't be verified remotely (e.g. exact `hermes` subcommand spelling, acp-skill install mechanism, response field names), the plan's **first step is a concrete "clone + read the README/SKILL.md" command** that diff --git a/docs/superpowers/specs/2026-06-27-hermes-ecosystem-integration-design.md b/docs/superpowers/specs/2026-06-27-hermes-ecosystem-integration-design.md index 92fd481..7b66fa9 100644 --- a/docs/superpowers/specs/2026-06-27-hermes-ecosystem-integration-design.md +++ b/docs/superpowers/specs/2026-06-27-hermes-ecosystem-integration-design.md @@ -252,3 +252,95 @@ Each phase is independently shippable and independently reversible. Stop after a All four resolved ⇒ **Phases 1, 2, and 3 are all actionable.** The implementation plan that follows details every phase. + +**Ecosystem expansion (added 2026-06-27, per ginnoir):** while researching eagle-eye alternatives I +surveyed the wider Hermes ecosystem and the external-agent landscape. The worthwhile additions and +the motif-vs-curator verdict are in **§7**. Claude Code + Codex are **already installed on valhalla** +(this session); Cursor + Antigravity are scoped for the delegation fabric. + +--- + +## 7. Ecosystem expansion & the delegation fabric (added 2026-06-27) + +### 7.1 `hermes-motif` vs `hermes-curator-evolver` — verdict: **complementary, run both** + +I earlier mis-framed these as rivals. They do **different halves of one loop**: + +- **`hermes-motif` (Saurav0989) — skill DISCOVERY.** Watches tool calls live, finds repeated + sequences (same tools, varying args → `{variable}`), and proposes them as **new** `SKILL.md` + drafts. **Makes no LLM calls** — pure pattern-mining, so **zero P100 cost**. `auto_install: false` + = proposal-only. Zero-to-one skill creation. +- **`hermes-curator-evolver` (pingchesu) — skill REFINEMENT.** Improves **existing** agent-created + skills from session evidence; bounded, reviewable edits; report-only default; more mature + (CI, systemd scheduler, backup/rollback). + +**Fit for you:** your stated goal (eagle-eye rationale) is a *large* skill library without per-turn +weight. That's a **skill factory**: **motif manufactures** new skills from what you already do +repeatedly → **curator refines** them → **eagle-eye routes** among them at call time. They compose. +**Recommendation: run both in proposal/report-only mode.** If you insist on only one to start, +**motif** is the lower-risk, higher-immediate-value pick for *growing* a library (no model cost, no +edits to existing files) — but there's no reason to drop curator; it's already Phase 1 and free to +leave in report-only. Plan adds motif as **Task 3b**. + +### 7.2 `hermes-web-search-plus` — **ADOPT** (pairs with camofox) + +Mature (v2.6.1, MIT, stdlib-only) Hermes plugin: multi-provider web **search** + extraction with +intent-aware routing (news/shopping/docs/GitHub/academic/security) and a `research` mode. 14 +providers, **all keys optional** — works with a single configured provider (free tiers exist: Tavily, +Exa, SearXNG self-host, Keenable keyless). **Complements camofox**, doesn't overlap it: search-plus +*finds* (cheap API calls), camofox *browses/interacts* (heavy headless Firefox). For a P100-limited +local agent, search-plus is the lighter, higher-frequency tool — arguably the one to reach for first; +camofox for when a page needs real rendering/interaction. Plan adds it as **Task 5b**, before/with +camofox. Install: `hermes plugins install robbyczgw-cla/hermes-web-search-plus --enable`. + +### 7.3 Context-efficiency layer — **OPTIONAL**, helps the Pascal bottleneck + +Your memory notes prefill is the P100 differentiator and context bloat is the enemy. Two opt-in tools: + +- **`llmtrim` (fkiene, MPL-2.0)** — HTTPS-proxy / MCP / CLI that compresses **tool schemas + history + + tool output** before requests (claims −31% input / −74% output tokens, BM25+ context ranking, + log-templating). Works with anything honoring `HTTPS_PROXY` (Claude Code, Cursor, Aider). **Two + distinct payoffs:** (a) in front of the **cloud delegation agents** (Claude Code/Codex/Cursor → + Anthropic/OpenAI) it cuts real $ cost; (b) potentially in front of **llama-swap** (via + `LLMTRIM_EXTRA_HOSTS`) to shrink prompts and speed Pascal prefill — needs validation, it's not + documented for local OpenAI-compatible backends. Caveat: it installs a name-constrained MITM CA; + acceptable but a real trust decision. +- **`rtk-hermes` (ogallotti, MIT)** — `pre_tool_call` hook that rewrites shell commands through the + `rtk` binary so terminal output arrives pre-filtered (cache-safe; preserves tool schema). Lighter, + shell-only. Needs the `rtk` binary on the host (`brew`/Linux build — verify availability). + +**Recommendation:** defer both to an **opt-in Task 11**. Start llmtrim on the *cloud-delegation* path +(clear cost win, no local risk) before considering it in front of llama-swap. + +### 7.4 The delegation fabric — claude-code · codex · cursor · antigravity + +Your acp-skill (Task 2) natively routes to `codex`, `claude-code`, and `hermes` subagents. You also +want **Cursor** and **Antigravity** in the mix. All four have real **headless** CLIs usable as +delegation targets from the valhalla host: + +| Agent | CLI | Headless invocation | Install (official) | Status on valhalla | +|---|---|---|---|---| +| Claude Code | `claude` | `claude -p` | `curl -fsSL https://claude.ai/install.sh \| bash` → `~/.local/bin/claude` | **Installed** v2.1.195 (login pending) | +| Codex | `codex` | `codex exec` / non-interactive | `npm i -g @openai/codex` (Node 22+) | **Installed** v0.142.3 (login pending) | +| Cursor | `cursor-agent` | `cursor-agent -p --output-format json --trust` | `curl https://cursor.com/install -fsS \| bash` | Scoped (Task 10) — note: known `-p` hang bug, set `--output-format json` + timeout | +| Antigravity | `agy` (ex-Gemini CLI, Go binary, **best for headless SSH**) | `agy -p` / `--headless --approve` | from **official** `antigravity.google/download` + `/docs/gcli-migration` (auth via keyring/Google sign-in or `ANTIGRAVITY_TOKEN`) | Scoped (Task 10) | + +**Wiring approach (Task 10):** acp-skill supports `codex`/`claude-code`/`hermes` out of the box — +verify whether its `agent=` routing is **extensible** (read `SKILL.md`). If yes, add `cursor` and +`antigravity` targets pointing at the headless invocations above. If not, add a **thin generic +"shell-agent" skill** that shells out to any of the four with the timeout/output caps from the +`delegation:` config — keeping the exposed tool surface minimal (your standing tool-budget rule). +**Alternatives noted, not adopted:** `42-evey/hermes-plugins` ships `evey-bridge` (file inbox/outbox ++ MCP bridge to Claude Code) and `evey-delegate-model` (model routing w/ fallback) — heavier, +opinionated, unknown maturity; acp-skill is the simpler purpose-built choice. `evey-cost-guard` +(Langfuse budget enforcement) becomes worth a look **once cloud delegation is live** and spend +matters. + +### 7.5 Updated rollout placement + +- **Phase 1:** + **Task 3b `hermes-motif`** (proposal-only, zero P100 cost). +- **Phase 2:** + **Task 5b `hermes-web-search-plus`** (light search, pairs with camofox). +- **Phase 2b (new):** **Task 10 delegation fabric** (install cursor + agy, wire all four into + acp-skill) and **Task 11 (optional) context efficiency** (llmtrim on the cloud-delegation path; + rtk for shell). +- **Phase 3:** unchanged (both UIs → keep one).