dsh-hermes-bridge

DSH ↔ WeChat bridge plugin: inbound dispatch (WeChat → DSH agent) + outbound push (DSH → WeChat), powered by the Hermes gateway as the WeChat transport. Zero-LLM outbound push via hermes send, and a persistent per-cwd session pool that reuses DSH agent sessions (15–20× cheaper than one-shot headless invocations).

> Scope: this plugin is a task-queue execution endpoint for DSH — it does not implement the WeChat protocol itself. The WeChat side (both the inbound trigger and the transport) comes from a self-deployed Hermes Agent gateway plus your own inbound script; without those, the WeChat half of the chain will not work.

微信 ↔ DSH 双向桥插件：入站调度（微信消息 → DSH agent 执行）+ 出站推送（任务进度/结果 → 微信）。出站走 hermes send 零 LLM 消耗；按工作目录复用常驻会话，比一次性 headless 调用省 15–20× token。

> ⚠️ Read this first — environment assumptions. This plugin was developed against one specific environment (see Environment assumptions). DSH and Hermes deployments vary wildly between users; this plugin cannot work out-of-the-box everywhere. Please review the assumptions and adapt the configuration to your setup before expecting it to run.
>
> ⚠️ 先读环境假设。 本插件基于特定开发环境编写（见「环境假设」章节）。DSH 与 Hermes 的部署方式千奇百怪，本插件无法开箱即用于所有环境，请先核对假设并适配你的配置。

Why

The one-way manual chain "WeChat → Hermes skill → dsh --profile headless" works but burns tokens on cold starts, loses session context between messages, and cannot notify you when a long task finishes. This plugin productizes the chain as a first-class DSH plugin:

• Session reuse — agents stay alive per working directory (ctx.agents.create/resume + followup), so follow-up messages continue the same conversation.
• Automatic pushback — every task reports 接单 → 开跑 → 完成/失败 to WeChat with structured changes / verification / leftovers.
• Zero-LLM outbound — notifications go through hermes send (iLink REST), no model call, no gateway dependency for bot-token platforms.
• Web UI visible — tasks are registered via ctx.jobs (falls back gracefully when the job controller is absent).

How it works

WeChat ──▶ Hermes gateway ──▶ dsh-run.sh (bridge-first) ──▶ POST 127.0.0.1:8643/v1/tasks
│
▼
persistent session pool (per cwd)
│
DSH agent (full toolset, followup + whenIdle)
│
WeChat ◀── hermes send ──◀── structured result pushback ──◀──┘

Inbound: Hermes (or any HTTP client) POSTs a task to the plugin's loopback endpoint. The plugin dispatches to the per-cwd resident agent session and pushes progress back via hermes send. If the bridge is down, the shell script falls back to one-shot dsh --profile headless.

Crash recovery / overnight hosting (M3)

The task queue is persisted to disk (~/.dsh/hermes-bridge/tasks.jsonl, JSONL append per state change). On startup the plugin reloads it and:

• queued tasks are resumed and run;
• running tasks (interrupted by a restart) are re-queued with their original sessionId, so the agent session is resumed and work continues where it left off — no cold restart, no lost work;
• a task interrupted more than maxRuns times (default 2) is marked failed instead of looping forever;
• done/failed tasks are kept for status queries only, and the file is rewritten to match memory (bounded).

Because the dsh server itself runs under systemd with Restart=always, this closes the loop: submit tasks in the evening (e.g. via WeChat), the server can restart overnight for any reason, and the queue picks right back up — results are pushed to WeChat as each task finishes.

Environment assumptions

Developed and verified on one specific machine (see the deployment notes in DEVELOPMENT.md). Your environment will differ; check each item:

Known limits (not bugs):

• WeChat rate limit: the iLink channel throttles sendmessage (ret=-2 → 30s cooldown, handled by Hermes). Bursts of pushes can be dropped/serialized. Keep push volume low (the plugin pushes once per task state, which is fine).
• No auth layer on the host: dsh web has no authentication by design. Run it loopback-only; do not expose it.
• rc-stage API drift: any DSH upgrade needs a regression pass (see DEVELOPMENT.md for what to re-verify).

Install

From npm (published as @dsh-pulse/dsh-hermes-bridge):

dsh plugin --profile web add @dsh-pulse/dsh-hermes-bridge

Or from GitHub:

git clone https://github.com/dsh-pulse/dsh-hermes-bridge.git
cd dsh-hermes-bridge && npm install   # installs peer deps if missing

# register in your web profile patch
cat >> ~/.dsh/profiles/web/cordis.patch.yml <<'EOF'
- insert:
- id: hermes-bridge
name: 'file:/absolute/path/to/dsh-hermes-bridge/lib/index.js'
config:
port: 8643
authToken: '${env.DSH_BRIDGE_TOKEN}'   # REQUIRED — plugin refuses to start without it
pushTarget: 'weixin:'          # REQUIRED
hermesBin: '/path/to/hermes'            # optional, default 'hermes'
workspaceRoots: ['/path/to/workspace']  # optional cwd whitelist
EOF

Requires @deepseek-ai/cordis (peer dependency) — ships inside DSH. The plugin is designed for the web profile (persistent host); do not install into headless.

Configuration (Config schema)

API (all endpoints require Authorization: Bearer)

Pushback messages (one per state, no spam):

📥 已接单 br-xxxxxxxx
🔧 开跑 br-xxxxxxxx
✅ br-xxxxxxxx（6m12s）
改动：…
验证：…
遗留：…

Security

• Loopback only: server.listen(port, '127.0.0.1') — the host is hardcoded, exposing it requires source changes.
• Auth required: authToken is mandatory; the plugin refuses to activate without it. Token lives in your profile patch (600 perms) or env, never in code.
• cwd whitelist: when workspaceRoots is set, paths outside it are rejected (403) both at ingress and inside executeTask.
• Zero shell: all child processes use spawn(args[]) — task text never passes through a shell.
• Redaction: outbound push strips sk-/sk_tr_/ghp_ token patterns and credentials paths before sending.

> ⚠️ This plugin executes arbitrary DSH agent work with full tool access. Only feed it trusted instructions (keep the WeChat-side discipline in your Hermes skill layer), and never expose the HTTP port beyond loopback.

Troubleshooting

Development

See DEVELOPMENT.md (EN) / DEVELOPMENT.zh-CN.md (中文) — architecture decisions, the problems we hit and how they were solved, test strategy, and what to re-verify after a DSH upgrade.

License

MIT