hermes-action-bridge 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-06-30
+
+### Added
+
+- Native agent skills installer: `hermes-action install|uninstall <claude-code|codex|all|mcp>`.
+  Installs the open-standard `SKILL.md` to `~/.claude/skills` and `~/.codex/skills`.
+- `hermes-action doctor` (`--json`, `--probe`): checks Node, configuration, Hermes availability,
+  Claude Code / Codex availability, and installed-skill state.
+- Opt-in project hints (`--project-hint`): a marker-managed block in `CLAUDE.md` / `AGENTS.md`.
+- Project-scoped skills (`--project`) and MCP config help: `install mcp` prints per-client snippets
+  (JSON for Claude Code / Cursor / VS Code, TOML for Codex); `install mcp --write` merges the
+  project `.mcp.json`, preserving other servers.
+- `--dry-run` and `--print` (write nothing) and `--force` (replace a managed skill).
+
+### Changed
+
+- The MCP server reports failed Hermes runs as errors (`isError`) and surfaces both stdout and
+  stderr instead of hiding failure detail.
+- The package version is sourced from `package.json` in one place; build and packaging hardened so
+  local drafts never ship in the npm tarball.
+
+### Security
+
+- The installer never modifies `CLAUDE.md` / `AGENTS.md` without `--project-hint`, refuses to
+  overwrite a file it did not generate, stays idempotent, and resolves paths cross-platform.
+
+## [0.1.0]
+
+### Added
+
+- Initial Hermes Action Bridge: `run`, `presets`, `status`, `mcp`, and `init` commands.
+- Configurable presets, a conservative risk policy (downgrade risky `execute` to `request-approval`),
+  an explicit `--yolo` escape hatch, context-file injection with size limits, dry-run mode, and a
+  minimal MCP server exposing `hermes_run`, `hermes_plan`, `hermes_presets`, and `hermes_status`.

package/CONTRIBUTING.md

@@ -0,0 +1,28 @@
+# Contributing
+
+Thanks for considering a contribution.
+
+## Local setup
+
+```bash
+npm install
+npm run check
+```
+
+## Development rules
+
+- Keep the bridge generic. Do not add project-specific presets to the default package.
+- Prefer configuration over hardcoded workflows.
+- Do not add provider or platform secrets to examples or tests.
+- Keep the MCP surface small and stable.
+- Add tests for any policy, config, adapter, or prompt-envelope change.
+
+## Release checklist
+
+```bash
+npm run check
+npm pack --dry-run
+git diff --check
+```
+
+Verify the package from the packed tarball before publishing to npm.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cyril Guilleminot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,323 @@
+# Hermes Action Bridge
+
+[![CI](https://github.com/TheBlueHouse75/hermes-action-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/TheBlueHouse75/hermes-action-bridge/actions/workflows/ci.yml)
+
+A configurable bridge that lets external agents delegate real-world actions to [Hermes Agent](https://hermes-agent.nousresearch.com/docs) without reimplementing Hermes skills, tools, platform integrations, browser automation, cron jobs, or messaging flows.
+
+Use it from Claude Code, Codex, Cursor, CI jobs, shell scripts, or any MCP-capable client.
+
+```text
+external agent -> hermes-action -> Hermes Agent -> skills/tools/integrations
+```
+
+## Why this exists
+
+Coding agents are good at understanding a repository. They should not duplicate your automation stack.
+
+If an agent needs to do something outside its local coding session — research, schedule a job, open a browser workflow, send a message, prepare a social post, use a Hermes skill, or coordinate with a messaging gateway — it can delegate that request to Hermes through this bridge.
+
+## Features
+
+- Generic `hermes-action run` command for one-shot delegation.
+- Configurable presets for skills, toolsets, provider/model, profile, source, and max turns.
+- Safety policy that can downgrade risky `execute` requests to `request-approval`.
+- Explicit `--yolo` mode for users who intentionally want to bypass bridge-level policy.
+- Context file injection with size limits.
+- Dry-run mode for debugging the exact Hermes command and prompt.
+- Minimal MCP server exposing delegation tools: `hermes_run`, `hermes_plan`, `hermes_presets`, and `hermes_status`.
+- No project-specific assumptions. All behavior is configured through YAML and CLI flags.
+
+## Requirements
+
+- Node.js 20 or newer.
+- Hermes Agent installed and available as `hermes`, or configured with a custom command path.
+
+Check Hermes:
+
+```bash
+hermes --version
+```
+
+## Installation
+
+From a local checkout:
+
+```bash
+npm install
+npm run build
+npm link
+```
+
+Then:
+
+```bash
+hermes-action --version
+hermes-action status
+```
+
+When published to npm, installation will be:
+
+```bash
+npm install -g hermes-action-bridge
+```
+
+## Quick start
+
+Create a config file in your project:
+
+```bash
+hermes-action init
+```
+
+Ask Hermes for a safe plan:
+
+```bash
+hermes-action run --mode plan "Find the best next action from this repository context."
+```
+
+Delegate with a context file:
+
+```bash
+hermes-action run \
+  --preset research \
+  --context ./notes.md \
+  "Analyze this and return the next concrete action."
+```
+
+Run a dry-run to inspect what will be sent to Hermes:
+
+```bash
+hermes-action run --dry-run --json "Summarize this project."
+```
+
+## Execution modes
+
+- `plan`: Hermes returns a plan only. No side effects.
+- `draft`: Hermes produces an artifact only. No external side effects.
+- `execute`: Hermes may execute allowed actions, while still following Hermes' own safety rules.
+- `request-approval`: Hermes prepares the action and asks the human for approval before irreversible external effects.
+
+If the bridge detects a risky request in `execute` mode, it can automatically switch to `request-approval` unless YOLO is enabled.
+
+Risk categories:
+
+- `publish_external`
+- `send_message`
+- `send_email`
+- `delete`
+- `payment`
+- `git_push`
+- `credential_change`
+
+## YOLO mode
+
+YOLO mode is off by default.
+
+```bash
+hermes-action run --yolo --mode execute "Do the task now."
+```
+
+YOLO only bypasses the bridge policy. It does not remove Hermes Agent's own safety rules, provider/tool approval prompts, or platform constraints.
+
+Use it only when the caller and environment are trusted.
+
+## Configuration
+
+`hermes-action` loads config in this order:
+
+```text
+CLI flags > project .hermes-action.yaml > user config > built-in defaults
+```
+
+User config path:
+
+```text
+~/.config/hermes-action/config.yaml
+```
+
+Project config path:
+
+```text
+.hermes-action.yaml
+```
+
+Example:
+
+```yaml
+runtime:
+  adapter: hermes-cli
+  command: hermes
+
+defaults:
+  mode: plan
+  source: external-agent
+  max_turns: 30
+  preset: default
+
+presets:
+  default:
+    description: No extra skills or toolsets. Uses the active Hermes profile.
+    skills: []
+    toolsets: []
+
+  research:
+    description: General research and synthesis.
+    skills: []
+    toolsets: [web, terminal, file]
+
+  coding:
+    description: Repository inspection and runtime validation.
+    skills: [developer-assurance-and-validation, runtime-debugging]
+    toolsets: [terminal, file]
+
+policy:
+  yolo: false
+  require_approval_for:
+    - publish_external
+    - send_message
+    - send_email
+    - delete
+    - payment
+    - git_push
+    - credential_change
+```
+
+## CLI reference
+
+```bash
+hermes-action init [--file .hermes-action.yaml] [--force]
+hermes-action run [options] "request"
+hermes-action presets [--json]
+hermes-action status [--json]
+hermes-action mcp
+hermes-action install <claude-code|codex|all|mcp> [options]
+hermes-action uninstall <claude-code|codex|all|mcp> [options]
+hermes-action doctor [--json] [--probe]
+```
+
+Common `run` options:
+
+```bash
+--mode <plan|draft|execute|request-approval>
+--preset <name>
+--context <path...>
+--config <path>
+--profile <name>
+--provider <name>
+--model <name>
+--max-turns <number>
+--source <name>
+--yolo
+--dry-run
+--json
+```
+
+## Native agent skills
+
+Instead of pasting instructions by hand, install a native skill so Claude Code and Codex know when to delegate to Hermes. The skill is the same open-standard `SKILL.md` for both agents; the CLI stays the deterministic execution layer.
+
+```bash
+hermes-action doctor                 # check Node, Hermes, agents, and installed skills
+hermes-action install all            # ~/.claude/skills and ~/.codex/skills
+hermes-action install claude-code --print     # preview, write nothing
+hermes-action install codex --project-hint     # also add a marker block to AGENTS.md
+hermes-action uninstall all
+```
+
+Install behavior is safe by default: it never modifies `CLAUDE.md` / `AGENTS.md` unless you pass `--project-hint`, refuses to overwrite a file it did not generate, and is idempotent. Use `--project` for a project-local skill and `--dry-run` to preview operations.
+
+The generated skill is shown in [`examples/claude-code/SKILL.md`](examples/claude-code/SKILL.md). Project-hint usage is documented in [`examples/claude-code/CLAUDE.md`](examples/claude-code/CLAUDE.md) and [`examples/codex/AGENTS.md`](examples/codex/AGENTS.md).
+
+## MCP configuration
+
+Print the config snippet for your client (Claude Code / Cursor / VS Code use JSON; Codex uses TOML):
+
+```bash
+hermes-action install mcp
+```
+
+For Claude Code, write or merge the project `.mcp.json` directly (preserving other servers):
+
+```bash
+hermes-action install mcp --write
+```
+
+Or configure it by hand:
+
+```json
+{
+  "mcpServers": {
+    "hermes-action": {
+      "command": "hermes-action",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+## Direct delegation
+
+You can always call the bridge directly, without a skill:
+
+```bash
+hermes-action run --mode plan "Ask Hermes what should happen next."
+
+hermes-action run \
+  --preset coding \
+  --context ./codex-notes.md \
+  "Use Hermes to validate this plan and identify missing runtime checks."
+```
+
+## MCP tools
+
+Run:
+
+```bash
+hermes-action mcp
+```
+
+Exposed tools:
+
+- `hermes_run`: delegate a request to Hermes.
+- `hermes_plan`: shortcut for `hermes_run` with `mode=plan`.
+- `hermes_presets`: list configured presets.
+- `hermes_status`: check the configured Hermes runtime command.
+
+The MCP surface is intentionally small. The bridge delegates to Hermes instead of exposing every Hermes tool one by one.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm run test
+npm run check
+```
+
+Functional tests use a fake Hermes binary to verify command construction, prompt wrapping, risk policy, and YOLO behavior without spending LLM credits.
+
+## Documentation
+
+- [Architecture](docs/ARCHITECTURE.md): module map, config precedence, modes, policy, and MCP design.
+- [Functional testing](docs/FUNCTIONAL-TESTS.md): automated tests and live smoke-test procedures.
+- [Contributing](CONTRIBUTING.md): local setup, development rules, and release checklist.
+- [Changelog](CHANGELOG.md): release history.
+- [Security policy](SECURITY.md): how to report a vulnerability.
+
+## Security notes
+
+- Do not put secrets in `.hermes-action.yaml`.
+- Keep provider credentials in Hermes Agent, your OS keychain, or the relevant platform's secure store.
+- Use `request-approval` for public posting, outbound email/messages, deletes, payments, credential changes, and git pushes.
+- Treat `--yolo` as a trusted-local-mode escape hatch, not as a default.
+
+## Also by the author
+
+Built by Cyril Guilleminot, who also makes offline-first voice tools:
+
+- [Weesper Neon Flow](https://weesperneonflow.ai) — speak text into any app at 3× typing speed, fully offline (macOS & Windows).
+- [Weesper Transcribe](https://apps.apple.com/app/id6778776535) — offline transcription on the macOS App Store.
+
+## License
+
+MIT

package/dist/adapters/hermes-cli.d.ts

@@ -0,0 +1,3 @@
+import type { AdapterResult, BridgeConfig, EffectiveRun } from "../types.js";
+export declare function buildHermesCliArgs(run: EffectiveRun, prompt?: string): string[];
+export declare function runHermesCli(config: BridgeConfig, run: EffectiveRun, dryRun: boolean): Promise<AdapterResult>;

package/dist/adapters/hermes-cli.js

@@ -0,0 +1,48 @@
+import { spawn } from "node:child_process";
+import { buildHermesPrompt } from "../prompt.js";
+export function buildHermesCliArgs(run, prompt = buildHermesPrompt(run)) {
+    const args = ["chat", "-Q", "--source", run.source, "--max-turns", String(run.maxTurns)];
+    if (run.profile)
+        args.unshift("--profile", run.profile);
+    if (run.provider)
+        args.push("--provider", run.provider);
+    if (run.model)
+        args.push("--model", run.model);
+    if (run.preset.skills.length)
+        args.push("--skills", run.preset.skills.join(","));
+    if (run.preset.toolsets.length)
+        args.push("--toolsets", run.preset.toolsets.join(","));
+    if (run.yolo)
+        args.push("--yolo");
+    args.push("-q", prompt);
+    return args;
+}
+export async function runHermesCli(config, run, dryRun) {
+    const prompt = buildHermesPrompt(run);
+    const args = buildHermesCliArgs(run, prompt);
+    const command = [config.runtime.command, ...args];
+    if (dryRun) {
+        return { ok: true, exitCode: 0, stdout: JSON.stringify({ command, prompt }, null, 2), stderr: "", command, prompt, dryRun: true };
+    }
+    return new Promise((resolve) => {
+        const child = spawn(config.runtime.command, args, { stdio: ["ignore", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        child.on("error", (error) => {
+            resolve({ ok: false, exitCode: 127, stdout, stderr: `${stderr}${error.message}`, command, prompt, dryRun: false });
+        });
+        child.on("close", (code) => {
+            const exitCode = code ?? 1;
+            resolve({ ok: exitCode === 0, exitCode, stdout, stderr, command, prompt, dryRun: false });
+        });
+    });
+}
+//# sourceMappingURL=hermes-cli.js.map

package/dist/adapters/hermes-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hermes-cli.js","sourceRoot":"","sources":["../../src/adapters/hermes-cli.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};