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 <noreply@anthropic.com>
2026-06-27 05:45:34 -05:00
parent 3cd843072d
commit dc2225d384
2 changed files with 299 additions and 10 deletions
@@ -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/<motif>/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 '<official agy installer from antigravity.google/docs>' && 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
@@ -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).