Hermes dsh_tools — LSP Code Navigation, Sandboxed Execution & Loop Guard for Hermes Agent

AI-agent-native Hermes plugin bringing three production agent-harness capabilities — semantic code navigation over language servers (LSP), fail-closed bubblewrap (bwrap) command sandboxing, and an advisory repeat-tool loop guard — to Hermes Agent. Modeled on the architecture of DeepSeek Harness (@deepseek-ai/dsh-lsp, dsh-sandbox-local, dsh-repeat-tool-reminder).

Keywords: hermes plugin · LSP tool · language server · code navigation · go-to-definition · find references · hover · diagnostics · bubblewrap sandbox · bwrap · confined execution · loop guard · agent loop detection · AI agent · agent harness · DeepSeek Harness · Hermes Agent · code intelligence · semantic navigation

---

What is this?

A single Hermes Agent plugin (dsh_tools) that installs three capabilities Hermes lacks out of the box:

Tool / Hook	Toolset	What it does	Modeled on
lsp	lsp	Semantic code navigation over stdio language servers: definitions, references, implementations, hover, document symbols, diagnostics — cross-file, precise, live. Pure-stdlib JSON-RPC client, zero extra dependencies.	@deepseek-ai/dsh-lsp
sandbox	sandbox	Run commands inside a bubblewrap sandbox: read-only root, private /tmp, no network by default. Fail-closed — never executes unconfined if bwrap is missing.	@deepseek-ai/dsh-sandbox-local
loop-guard (hook)	—	Advisory repeat-tool reminder: escalates at 3/5/8 identical consecutive calls by appending a nudge to the tool result. Never blocks, cache-safe, configurable.	@deepseek-ai/dsh-repeat-tool-reminder

No core Hermes files are modified — everything lives in the plugin directory (plugin policy), so hermes update cannot wipe it.

Install

Requires Linux (sandbox) / macOS (LSP; sandbox is Linux-only), Hermes Agent, and Node.js ≥ 22 (not required — any Hermes install works).

git clone https://github.com/lesterppo/hermes-dsh-tools.git
cd hermes-dsh-tools
./install.sh          # copies plugin to ~/.hermes/plugins/dsh_tools/ and enables it
hermes plugins list   # confirm: dsh_tools | enabled

Then restart your Hermes session — the lsp and sandbox toolsets load at startup.

Optional: install language servers (see AGENTS.md for the full table):

pipx install python-lsp-server            # Python  (.py)
npm i -g typescript-language-server       # TypeScript (.ts/.tsx/.js/.jsx) — also needs typescript@5 in the project
sudo apt install clangd                   # C/C++

Verify:

# LSP: list installed language servers
lsp {"action": "servers"}
# Sandbox: functional probe
sandbox {"action": "check"}

Tools

lsp — semantic code navigation

Positions are 1-based; results use compact short keys (f=file, l/c=line/col, el/ec=end, n=name, k=kind, sev=e/w/i/h).

{"action": "symbols", "file": "/repo/app/main.py"}
{"action": "definitions", "file": "/repo/app/main.py", "line": 42, "col": 9}
{"action": "references", "file": "/repo/app/main.py", "line": 42, "col": 9, "include_declaration": true}
{"action": "implementations", "file": "/repo/app/iface.go", "line": 10, "col": 5}
{"action": "hover", "file": "/repo/app/main.py", "line": 42, "col": 9}
{"action": "diagnostics", "file": "/repo/app/main.py"}
{"action": "servers"}

• Pure-stdlib JSON-RPC (LSP) client — no pip/npm dependencies in the tool itself.
• Servers spawn lazily per (server, workspace), cached in a pool with 600 s idle reaping (max 6).
• Workspace auto-resolves to the nearest project root (package.json, tsconfig.json, pyproject.toml, go.mod, Cargo.toml, .git, …); servers run with the workspace as cwd.
• Per-server locking serializes queries (LSP is a sequential protocol).
• Structured errors: LSP_UNAVAILABLE / LSP_SPAWN / LSP_TIMEOUT / LSP_ERROR. No generic JSON-RPC escape hatch.

Custom server mappings: copy plugin/providers.json.example → ~/.hermes/plugins/dsh_tools/providers.json.

sandbox — fail-closed bwrap confinement

{"action": "run", "cmd": "curl -fsSL https://example.com/install.sh | head -50", "mode": "ro", "timeout": 30}
{"action": "run", "cmd": "make test", "mode": "rw-workspace", "workspace": "/home/user/proj", "cwd": "/home/user/proj", "timeout": 300}
{"action": "run", "cmd": ["python3", "-c", "import os; print(os.listdir('/tmp'))"], "mode": "ro"}
{"action": "check"}

• --ro-bind / / — entire host read-only. rw-workspace bind-mounts one workspace dir writable.
• Private tmpfs on /tmp, /run, /var/tmp — ephemeral, discarded. systemd-resolved stub re-bound so network: true DNS works.
• Network off by default (--unshare-net); network: true shares the host stack.
• String cmd runs via /bin/sh -c inside the sandbox; list cmd execs directly (no shell).
• Fail-closed: missing bwrap → SANDBOX_UNAVAILABLE, never an unconfined fallback.
• Timeouts (max 600 s) kill the whole sandbox; output capped (default 100 000 chars).

loop-guard — advisory repeat-tool reminder

• Watches each session's consecutive identical tool calls (canonical args = deep key-sort + JSON, so key order doesn't defeat detection).
• Escalating advisory at thresholds 3, 5, 8 (default) appended to the tool result via the transform_tool_result hook — cache-safe (only the fresh result is extended), never blocks.
• Env overrides: DSH_GUARD_THRESHOLDS, DSH_GUARD_EXCLUDE (* wildcards, default todo), DSH_GUARD_ARG_PREVIEW.

Skills

Five companion skills are included under skills/ — copy them into ~/.hermes/skills/<category>/<name>/:

Skill	Category	Purpose
lsp-code-navigation	software-development	Using the lsp tool; per-language server install table; pitfalls (TS 5.x, positions, -32601).
sandboxed-execution	devops	Isolation guarantees, honest limits, when to sandbox.
agent-loop-guard	autonomous-ai-agents	Guard design + loop-hygiene practices for agent developers.
fresh-agent-orchestration	autonomous-ai-agents	Ralph-style fresh-subagent loop pattern (immutable objective, structured handoff, round caps).
harness-architecture-patterns	hermes-agent	7 transferable agent-harness design patterns (capability seams, fail-closed, advisory-over-veto…).

Design

All three capabilities follow DeepSeek Harness architecture principles:

1. Capability seams — the lsp tool's schema is stable across providers; provider selection lives behind providers.json.
2. Fail-closed availability — sandbox never degrades to unconfined execution; missing prerequisite = structured error.
3. Advisory over veto — the loop guard nudges, never blocks; a legitimate repeating call is never delayed.
4. Cache-safe injection — context rides on the fresh tool result, never past messages or the system prompt.
5. No core modifications — plugin policy; survives hermes update.

FAQ

Is this safe to run? Yes — it is a standalone plugin, no core files touched. The sandbox fails closed; the guard is advisory-only.

Does lsp need a language server for every file type? No — unconfigured extensions return LSP_UNAVAILABLE with an install hint; lsp servers lists what's available vs missing.

Why typescript@5 for TypeScript? typescript-language-server resolves tsserver from the project's node_modules; TypeScript 6/7 (the native Go port) ships no tsserver, so projects must pin typescript@5 (standard for any TS project).

Does the sandbox allow writing anywhere? Only the workspace dir in rw-workspace mode (and private tmpfs that is discarded). Everything else is read-only.

Does loop-guard slow down the agent? No — the detection is a dict lookup + canonicalize per call; the no-threshold path returns None immediately.

Does this overlap with other Hermes plugins? No hard overlaps — agel-safety blocks dangerous patterns pre-execution (content-based); the loop guard nudges on behavior loops (advisory). runtime_exoskeleton halts at budget limits; the guard is the soft first line. codebase-graph answers architecture questions; lsp answers precise symbol questions.

Contributing

PRs welcome — see CONTRIBUTING. Please run the E2E check (python3 tests/e2e_plugin_check.py) before submitting.

License

MIT — see LICENSE.