hermes-action-bridge 0.3.0 → 0.5.0

package/docs/ARCHITECTURE.md

@@ -25,7 +25,12 @@ Hermes skills, tools, browser automation, MCPs, cron jobs, messaging, APIs
 - `src/prompt.ts`: prompt envelope sent to Hermes.
 - `src/context.ts`: context file loading with a per-file cap and an aggregate budget.
 - `src/adapters/hermes-cli.ts`: Hermes CLI adapter (argv or temp-file prompt delivery, child-process timeout).
-- `src/mcp-server.ts`: minimal MCP server.
+- `src/mcp-server.ts`: MCP server factory, delegation tools, jobs, and approval orchestration.
+- `src/http-server.ts`: authenticated, opt-in Streamable HTTP transport.
+- `src/capabilities.ts`: configuration-backed capability inventory.
+- `src/jobs.ts`: bounded process-local asynchronous jobs.
+- `src/approvals.ts`: short-lived, one-shot approval records.
+- `src/audit-log.ts`: privacy-preserving owner-only JSONL audit metadata.
 - `src/status.ts`: runtime availability check.
 - `src/version.ts`: single source of truth for the package version.
 - `src/doctor.ts`: environment checks for `hermes-action doctor`.
@@ -40,9 +45,14 @@ The `install` / `uninstall` commands install an open-standard `SKILL.md` for Cla
 - `src/install/marker-block.ts`: fail-safe marker block for the optional `CLAUDE.md` / `AGENTS.md` hint.
 - `src/install/file-edit.ts`: shared read-edit-write helper used by the hint and the `.mcp.json` writer.
 - `src/install/mcp-config.ts`: MCP snippets and the Claude Code `.mcp.json` merge/unmerge writer.
+- `src/install/mcp-service.ts`: native Codex/Claude MCP registration, inspection, conflict handling, and removal.
 - `src/install/install-service.ts`: per-agent install/uninstall with failure isolation.
 
-Defaults are conservative: never modify `CLAUDE.md` / `AGENTS.md` without `--project-hint`, never overwrite a file the installer did not generate, and stay idempotent.
+The global default is a complete installation: managed skill plus MCP
+registration through each agent's native CLI, using the bridge's absolute
+launcher path. Defaults remain conservative: never modify `CLAUDE.md` /
+`AGENTS.md` without `--project-hint`, never overwrite foreign skills or
+customized MCP entries, and stay idempotent.
 
 ## Config precedence
 
@@ -68,18 +78,22 @@ Project config:
 
 The bridge does not decide how Hermes completes the task. It only labels the requested behavior:
 
-- `plan`: no side effects.
+- `plan`: prompt-level plan-only policy; callers must still treat configured Hermes tools as open-world.
 - `draft`: produce an artifact, no external side effects.
 - `execute`: execute allowed actions.
 - `request-approval`: prepare the action and ask for approval.
 
 ## Policy
 
-Policy is intentionally conservative and transparent.
+Direct CLI and `hermes_run` calls rely on the **host agent's approval prompt**.
+The structured MCP path adds a second deterministic barrier:
+`hermes_prepare` creates a local no-tool summary, stores an immutable short-lived request, and
+`hermes_approve` consumes it exactly once. The bridge never treats its own model
+output as human approval.
 
-When a prompt contains risky intent and `mode=execute`, the bridge changes the effective mode to `request-approval` unless YOLO is enabled.
+The bridge's own guard is a secondary, deterministic net: in `mode=execute` it changes the effective mode to `request-approval` unless the preset/policy is explicitly trusted (empty `require_approval_for`) or YOLO is enabled. This is independent of the prompt's language or wording.
 
-The detected risks are included in the prompt envelope so Hermes knows why the mode changed.
+Keyword risk detection (`detectRisks`) is **informational only**: recognized categories are listed in the prompt envelope to help the human and Hermes decide, but they never drive the mode. Keyword matching is English-biased and easily evaded, so it is not treated as a security control.
 
 ## YOLO
 
@@ -104,13 +118,59 @@ Every child process is bounded by a timeout (per-mode defaults, overridable via
 
 ## MCP design
 
-The MCP server exposes a small delegation surface instead of mirroring every Hermes tool.
+The MCP server exposes orchestration primitives instead of mirroring every
+Hermes tool.
 
 Tools:
 
 - `hermes_run`
 - `hermes_plan`
+- `hermes_capabilities`
 - `hermes_presets`
 - `hermes_status`
-
-This keeps schema drift low and lets Hermes remain the action runtime.
+- `hermes_submit`
+- `hermes_job_status`
+- `hermes_result`
+- `hermes_cancel`
+- `hermes_prepare`
+- `hermes_approve`
+- `hermes_reject`
+
+The server advertises routing instructions that distinguish Hermes-owned
+connected services and automation from ordinary local coding work. Capability
+discovery reports declarative presets and runtime status only; it does not
+claim that a Hermes integration is live without a stable Hermes introspection
+API.
+
+Jobs are memory-only, concurrency-limited, cancellable, output-bounded, and
+expire after 24 hours. Approval records expire after 15 minutes and are
+one-shot. Audit JSONL stores only identifiers, modes, risks, prompt hashes, and
+terminal metadata with `0600` permissions.
+
+## HTTP transport
+
+`hermes-action serve` exposes `/mcp` using Streamable HTTP. It binds loopback by
+default. Direct non-loopback binding requires an explicit address in
+`100.64.0.0/10`, `--allow-tailnet`, and a bearer token read from an environment
+variable. The server validates Host, authenticates in constant time, restricts
+direct peers to Tailscale CGNAT, limits request size and active sessions, and
+never exposes an unauthenticated diagnostics endpoint.
+
+Tailscale Serve in front of a loopback listener remains the preferred remote
+deployment because TLS and tailnet identity stay outside the bridge. Requests
+forwarded with a `*.ts.net` Host still require the bridge bearer token.
+
+### Transitive Hono advisory
+
+MCP SDK 1.29.0 currently depends on `@hono/node-server` 1.x, which npm flags
+under [GHSA-frvp-7c67-39w9](https://github.com/advisories/GHSA-frvp-7c67-39w9).
+That advisory applies only to the package's `serve-static` middleware on
+Windows. The bridge never imports that middleware, serves no static files, and
+rejects every HTTP path except `/mcp`, so the vulnerable code path is not
+reachable here.
+
+Re-evaluate this acceptance when the v1 SDK updates its Hono dependency, or
+before adding static-file serving, a Hono middleware layer, or any HTTP route
+that maps request paths to the filesystem. Do not force Hono 2 through an npm
+override: the current SDK declares `^1.19.9`, and doing so produces an invalid
+dependency tree for global installs.

package/docs/FUNCTIONAL-TESTS.md

@@ -27,13 +27,22 @@ The fake Hermes tests verify:
 
 The installer tests verify (with injected home/cwd and temp `HOME`, no real agents required):
 
-- `install` / `uninstall` are idempotent and never touch `CLAUDE.md` / `AGENTS.md` by default.
+- `install` / `uninstall` manage both skills and native MCP registrations,
+  remain idempotent, preserve customized registrations, and never touch
+  `CLAUDE.md` / `AGENTS.md` by default.
 - `--dry-run` and `--print` write nothing; `--force` replaces a managed skill; a non-managed file is refused.
 - `--project-hint` adds and removes a marker block without losing existing content.
 - `--project` installs a project-local skill without creating the global one.
 - `install mcp --write` merges and `uninstall mcp --write` unmerges the project `.mcp.json`, preserving other servers.
-- `doctor` assembles its checks and JSON report, and `--probe` accepts the sentinel on stdout or stderr.
+- `doctor` verifies skills, registrations, and an in-memory MCP handshake;
+  `--probe` accepts the sentinel on stdout or stderr.
 - The shipped `examples/*/SKILL.md` match the installer template exactly (no drift).
+- asynchronous jobs enforce concurrency, cancellation, TTL, and bounded UTF-8
+  output;
+- approvals are immutable, short-lived, and one-shot, while audit records omit
+  prompt and output content;
+- the Streamable HTTP server completes an MCP handshake on loopback and rejects
+  public binding, weak/missing authentication, and non-Tailscale addresses.
 
 ## Live Hermes smoke test
 
@@ -55,27 +64,30 @@ node dist/cli.js run \
 
 ## Claude Code smoke test
 
-After `npm link`, ask Claude Code to run:
+After `npm link`, install over any existing configuration:
 
 ```bash
-hermes-action run --dry-run --json "Return BRIDGE_OK only."
+hermes-action install all --yes
+claude mcp get hermes-action
+hermes-action doctor
 ```
 
 Expected result:
 
-- The command exits `0`.
-- The JSON output contains a `command` array starting with `hermes chat -Q`.
-- The prompt contains `Mode: plan`.
+- The managed Claude skill is current.
+- The MCP entry points to the absolute linked bridge launcher with argument `mcp`.
+- `doctor` reports `skill:claude-code`, `mcp:claude-code`, and
+  `mcp:handshake` as passing.
 
 ## Codex smoke test
 
-After `npm link`, ask Codex to run:
+Verify the same installation from Codex:
 
 ```bash
-hermes-action run --dry-run --json "Return BRIDGE_OK only."
+codex mcp get hermes-action --json
 ```
 
-Expected result is the same as Claude Code.
+The command and arguments must match the current absolute bridge launcher.
 
 ## MCP smoke test
 
@@ -92,6 +104,9 @@ Configure an MCP client with:
 }
 ```
 
-Call `hermes_status` first. It should report whether the configured Hermes command is available.
+Call `hermes_status` and `hermes_capabilities` first. They should report the
+runtime and declarative presets without spending provider tokens.
 
-Then call `hermes_run` with `dryRun: true` before making real Hermes calls.
+Then call `hermes_plan` before making real side-effecting calls. Validate a
+two-phase action with `hermes_prepare`; call `hermes_reject` unless a human
+explicitly approves the exact request returned in `preview.action`.

package/examples/claude-code/SKILL.md

@@ -1,55 +1,61 @@
 ---
 name: hermes-action-bridge
-description: Delegate external actions, Hermes skills, browser automation, messaging, cron jobs, and integrations to Hermes Agent through hermes-action. Use when a task needs capabilities outside the local coding session.
+description: Use Hermes Agent for Hermes-owned skills, memory, connected services, messaging, browser workflows, schedules, and external automation. Prefer the installed hermes_* MCP tools; use the CLI only as a fallback.
 ---
 
 # Hermes Action Bridge
 
-Use this skill when a task needs capabilities outside the local coding session:
-Hermes skills or memory, messaging platforms, browser automation, scheduled or
-cron automation, external research, or any platform integration already
-configured in Hermes Agent.
+Use this skill when a task needs state or capabilities owned by Hermes Agent:
+Hermes skills or memory, connected services, messaging platforms, browser
+workflows, scheduled automation, or another integration configured in Hermes.
 
-Do not reimplement those integrations here. Delegate them to Hermes through the
-`hermes-action` CLI.
+Do not reimplement a Hermes-owned integration in the coding agent. Prefer the
+installed `hermes_*` MCP tools so the host can discover, approve, and inspect
+the delegation.
 
 ## When to use
 
-- The task requires a Hermes skill, tool, profile, or connected service.
-- The task needs a real-world action that is not local code editing.
-- The task needs research, messaging, browser, or scheduled automation Hermes owns.
+- The task names Hermes, a Hermes skill, memory, preset, or connected service.
+- The task needs messaging, scheduling, browser work, or persistent external automation Hermes owns.
+- The task must continue as a cancellable background job outside the local coding step.
 
-## Safe default
+Do not use Hermes for ordinary local code edits or repository inspection that
+the current agent can perform directly.
 
-Ask Hermes for a plan first; it has no side effects:
+## Discover first
 
-```bash
-hermes-action run --mode plan "<describe what Hermes should do>"
-```
+Call `hermes_capabilities` before assuming an integration is configured. Use
+`hermes_status` to check the runtime without spending provider tokens.
 
-## With context
+## Safe delegation
 
-Write a concise handoff to a file and pass it explicitly:
-
-```bash
-hermes-action run --preset coding --context ./handoff.md "<request>"
-```
+- Use `hermes_plan` for plan-mode analysis, but treat it as open-world and review its output.
+- Use `hermes_submit`, then `hermes_job_status` / `hermes_result`, for a
+  long cancellable plan or draft.
+- Use `hermes_cancel` when a queued or running job is no longer wanted.
 
 ## External side effects
 
-For public posts, outbound email or messages, deletes, payments, credential
-changes, or git pushes, require human approval:
+For public posts, outbound messages, deletes, payments, credential changes, or
+git pushes:
+
+1. Call `hermes_prepare` to produce a local no-tool summary and approval ID.
+2. Show `preview.action` and the rest of the preview to the human.
+3. Call `hermes_approve` only after the human explicitly approves that
+   prepared action; otherwise call `hermes_reject`.
+
+Never treat the model's own decision as human approval.
+
+## CLI fallback
+
+If MCP tools are unavailable, use the local CLI:
 
 ```bash
-hermes-action run --mode request-approval "<request requiring side effects>"
+hermes-action run --mode plan "<describe what Hermes should do>"
 ```
 
-Never use `--yolo` unless the human explicitly asked for trusted local
-execution. It bypasses only the bridge policy, not Hermes' own safety rules.
-
 ## Verify setup
 
 ```bash
-hermes-action status
-hermes-action run --dry-run --json "Return BRIDGE_OK only."
+hermes-action doctor
 ```

package/examples/codex/SKILL.md

@@ -1,55 +1,61 @@
 ---
 name: hermes-action-bridge
-description: Delegate external actions, Hermes skills, browser automation, messaging, cron jobs, and integrations to Hermes Agent through hermes-action. Use when a task needs capabilities outside the local coding session.
+description: Use Hermes Agent for Hermes-owned skills, memory, connected services, messaging, browser workflows, schedules, and external automation. Prefer the installed hermes_* MCP tools; use the CLI only as a fallback.
 ---
 
 # Hermes Action Bridge
 
-Use this skill when a task needs capabilities outside the local coding session:
-Hermes skills or memory, messaging platforms, browser automation, scheduled or
-cron automation, external research, or any platform integration already
-configured in Hermes Agent.
+Use this skill when a task needs state or capabilities owned by Hermes Agent:
+Hermes skills or memory, connected services, messaging platforms, browser
+workflows, scheduled automation, or another integration configured in Hermes.
 
-Do not reimplement those integrations here. Delegate them to Hermes through the
-`hermes-action` CLI.
+Do not reimplement a Hermes-owned integration in the coding agent. Prefer the
+installed `hermes_*` MCP tools so the host can discover, approve, and inspect
+the delegation.
 
 ## When to use
 
-- The task requires a Hermes skill, tool, profile, or connected service.
-- The task needs a real-world action that is not local code editing.
-- The task needs research, messaging, browser, or scheduled automation Hermes owns.
+- The task names Hermes, a Hermes skill, memory, preset, or connected service.
+- The task needs messaging, scheduling, browser work, or persistent external automation Hermes owns.
+- The task must continue as a cancellable background job outside the local coding step.
 
-## Safe default
+Do not use Hermes for ordinary local code edits or repository inspection that
+the current agent can perform directly.
 
-Ask Hermes for a plan first; it has no side effects:
+## Discover first
 
-```bash
-hermes-action run --mode plan "<describe what Hermes should do>"
-```
+Call `hermes_capabilities` before assuming an integration is configured. Use
+`hermes_status` to check the runtime without spending provider tokens.
 
-## With context
+## Safe delegation
 
-Write a concise handoff to a file and pass it explicitly:
-
-```bash
-hermes-action run --preset coding --context ./handoff.md "<request>"
-```
+- Use `hermes_plan` for plan-mode analysis, but treat it as open-world and review its output.
+- Use `hermes_submit`, then `hermes_job_status` / `hermes_result`, for a
+  long cancellable plan or draft.
+- Use `hermes_cancel` when a queued or running job is no longer wanted.
 
 ## External side effects
 
-For public posts, outbound email or messages, deletes, payments, credential
-changes, or git pushes, require human approval:
+For public posts, outbound messages, deletes, payments, credential changes, or
+git pushes:
+
+1. Call `hermes_prepare` to produce a local no-tool summary and approval ID.
+2. Show `preview.action` and the rest of the preview to the human.
+3. Call `hermes_approve` only after the human explicitly approves that
+   prepared action; otherwise call `hermes_reject`.
+
+Never treat the model's own decision as human approval.
+
+## CLI fallback
+
+If MCP tools are unavailable, use the local CLI:
 
 ```bash
-hermes-action run --mode request-approval "<request requiring side effects>"
+hermes-action run --mode plan "<describe what Hermes should do>"
 ```
 
-Never use `--yolo` unless the human explicitly asked for trusted local
-execution. It bypasses only the bridge policy, not Hermes' own safety rules.
-
 ## Verify setup
 
 ```bash
-hermes-action status
-hermes-action run --dry-run --json "Return BRIDGE_OK only."
+hermes-action doctor
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hermes-action-bridge",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Configurable bridge for external agents to delegate actions to Hermes Agent via CLI or MCP.",
   "mcpName": "io.github.TheBlueHouse75/hermes-action-bridge",
   "repository": {
@@ -21,15 +21,17 @@
     "CHANGELOG.md",
     "CONTRIBUTING.md",
     "docs/*.md",
-    "examples"
+    "examples",
+    "plugins"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "postbuild": "node -e \"require('node:fs').chmodSync('dist/cli.js', 0o755)\"",
     "dev": "tsx src/cli.ts",
+    "pretest": "npm run build",
     "test": "vitest run",
     "test:watch": "vitest",
-    "check": "npm run build && npm run test",
+    "check": "npm run test",
     "prepublishOnly": "npm run check"
   },
   "keywords": [

package/plugins/hermes-action/.codex-plugin/plugin.json

@@ -0,0 +1,30 @@
+{
+  "name": "hermes-action",
+  "version": "0.5.0",
+  "description": "Delegate real-world actions (research, browser, messaging, scheduling, Hermes skills/tools) to Hermes Agent.",
+  "author": {
+    "name": "Cyril Guilleminot",
+    "url": "https://github.com/TheBlueHouse75"
+  },
+  "homepage": "https://github.com/TheBlueHouse75/hermes-action-bridge",
+  "repository": "https://github.com/TheBlueHouse75/hermes-action-bridge",
+  "license": "MIT",
+  "keywords": ["hermes-agent", "mcp", "codex", "automation", "delegation"],
+  "mcpServers": "./.mcp.json",
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Hermes Action Bridge",
+    "shortDescription": "Delegate real-world actions to Hermes Agent",
+    "longDescription": "Lets Codex delegate work outside the local coding session — research, browser workflows, messaging, scheduling, and any Hermes skill or tool — to Hermes Agent, instead of reimplementing them. Deterministic safety policy (execute -> request-approval by default unless trusted). Requires Hermes Agent installed locally.",
+    "developerName": "Cyril Guilleminot",
+    "category": "Developer Tools",
+    "capabilities": ["Interactive", "Write"],
+    "websiteURL": "https://github.com/TheBlueHouse75/hermes-action-bridge",
+    "brandColor": "#7C3AED",
+    "defaultPrompt": [
+      "Ask Hermes for a safe plan to handle the next real-world action from this repo's context."
+    ],
+    "composerIcon": "./assets/app-icon.png",
+    "logo": "./assets/app-icon.png"
+  }
+}

package/plugins/hermes-action/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "hermes-action": {
+      "command": "npx",
+      "args": ["-y", "hermes-action-bridge", "mcp"]
+    }
+  }
+}

package/plugins/hermes-action/skills/hermes-action-bridge/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: hermes-action-bridge
+description: Use Hermes Agent for Hermes-owned skills, memory, connected services, messaging, browser workflows, schedules, and external automation. Prefer the installed hermes_* MCP tools; use the CLI only as a fallback.
+---
+
+# Hermes Action Bridge
+
+Use this skill when a task needs state or capabilities owned by Hermes Agent:
+Hermes skills or memory, connected services, messaging platforms, browser
+workflows, scheduled automation, or another integration configured in Hermes.
+
+Do not reimplement a Hermes-owned integration in the coding agent. Prefer the
+installed `hermes_*` MCP tools so the host can discover, approve, and inspect
+the delegation.
+
+## When to use
+
+- The task names Hermes, a Hermes skill, memory, preset, or connected service.
+- The task needs messaging, scheduling, browser work, or persistent external automation Hermes owns.
+- The task must continue as a cancellable background job outside the local coding step.
+
+Do not use Hermes for ordinary local code edits or repository inspection that
+the current agent can perform directly.
+
+## Discover first
+
+Call `hermes_capabilities` before assuming an integration is configured. Use
+`hermes_status` to check the runtime without spending provider tokens.
+
+## Safe delegation
+
+- Use `hermes_plan` for plan-mode analysis, but treat it as open-world and review its output.
+- Use `hermes_submit`, then `hermes_job_status` / `hermes_result`, for a
+  long cancellable plan or draft.
+- Use `hermes_cancel` when a queued or running job is no longer wanted.
+
+## External side effects
+
+For public posts, outbound messages, deletes, payments, credential changes, or
+git pushes:
+
+1. Call `hermes_prepare` to produce a local no-tool summary and approval ID.
+2. Show `preview.action` and the rest of the preview to the human.
+3. Call `hermes_approve` only after the human explicitly approves that
+   prepared action; otherwise call `hermes_reject`.
+
+Never treat the model's own decision as human approval.
+
+## CLI fallback
+
+If MCP tools are unavailable, use the local CLI:
+
+```bash
+hermes-action run --mode plan "<describe what Hermes should do>"
+```
+
+## Verify setup
+
+```bash
+hermes-action doctor
+```