TypeSafe Jev Gate for Hermes

A fail-closed policy gate for Hermes Agent tool calls.

Let Jev inspect the risky calls. Keep Hermes in control.

TypeSafe Jev Gate adds a second policy signal before Hermes performs side-effecting tool calls. It classifies the action, redacts sensitive arguments, sends bounded structured state to Jev, and routes the result into Hermes's existing approval flow.

This is a safety layer, not an autonomous permission slip. Hermes hardline blocks, normal authorization, and human approval remain authoritative.

Why it exists

Tool-using agents need more than a single yes/no check. A request can be technically valid and still be risky because it:

• sends data outside the machine
• repeats an expensive or destructive action
• changes external state when the user's intent is unclear
• contains secrets or prompt-injection content
• arrives while the agent is already performing too many side effects

Jev gives Hermes a typed decision signal for those cases. When Jev is unavailable or uncertain, this plugin fails closed into Hermes approval.

What it does

• Lets read-only tools and obvious safe terminal commands pass without a network call.
• Evaluates side-effecting tools with redacted, bounded arguments.
• Evaluates paid/external tools such as web search and extraction before they leave the process.
• Escalates repeated calls and excessive side effects in one turn.
• Applies stricter preflight treatment to paid tools.
• Caches Jev decisions briefly to avoid duplicate spend.
• Runs one typed preflight plan before every non-empty main-LLM turn through pre_llm_call, covering route, toolset, context, compression, memory, skills, delegation, and retry choices.
• Gives the main model an advisory decision brief so it can choose the smallest useful context and tool path.
• Sends the bounded, redacted turn context available to Hermes with each decision, including conversation history, current model, platform, user message, tool schema, and eligible tool context.
• Validates every typed response against a versioned decision contract before policy code sees it.
• Supports observe, advise, and enforce_narrowly rollout modes plus an emergency HERMES_JEV_DISABLED=1 network kill switch.
• Blocks clear secret-egress and prompt-injection risks.
• Sends irreversible or uncertain calls to Hermes's normal approval gate.
• Writes metadata-only audit records to $HERMES_HOME/logs/jev-gate.jsonl.

Quick start

1. Configure the API key

Use an existing OpenRouter key or create one at https://openrouter.ai/keys. Store it as the secret OPENROUTER_API_KEY in the active Hermes profile.

The plugin calls the OpenRouter Decisions API at:

https://openrouter.ai/api/alpha/decisions

It uses the ~typesafe/jev-latest model slug. This is not the normal chat-completions endpoint, and Jev does not replace Hermes's conversational model.

2. Enable the plugin

hermes plugins enable typesafe-jev-gate

Restart Hermes or its gateway after enabling it.

Safety model

Hermes hardline blocks
        ↓
TypeSafe Jev Gate
        ↓
Hermes authorization and approval
        ↓
Tool execution

The gate can recommend allow, deny, or approval. It cannot override Hermes's existing authorization rules. A Jev outage, malformed response, or uncertain decision is treated as a reason to ask for approval, not a reason to allow the call.

Architecture

File	Role
config.py	Policy constants, context limits, rollout mode, and kill switch
redaction.py	Tool classification, secret redaction, fingerprints, and safe action summaries
context.py	Bounded, redacted runtime context assembly
decisions.py	Versioned typed-choice and score validation
planner.py	One-call pre-main-LLM route, context, tool, memory, skill, delegation, and retry choices
client.py	OpenRouter Decisions API client and short-lived cache
policy.py	Jev request payloads and validated response parsing
budget.py	Per-turn Jev, repetition, and side-effect budgets

• hooks.py | Hermes hook adapters and approval directives.
• features.py | Bounded deterministic request-feature extraction and route safety checks.
• lifecycle.py | Typed session, context, skill, quality, and audit-sampling decisions.
• evaluation.py | Redacted offline routing corpus and evaluation metrics.
• metrics.py | Privacy-safe p50/p95 latency and reliability report from audit metadata.
• __init__.py | Minimal plugin entry point.

Development

Run the test suite:

uv run pytest

Run linting:

uv run --with 'ruff>=0.16,<0.17' ruff check .

Run the offline routing evaluation and inspect privacy-safe telemetry:

uv run python scripts/jev_report.py

Project status

This plugin is experimental and tracks the deployed Hermes plugin at version 0.4.0. The roadmap contracts are implemented with bounded inputs, typed validation, deterministic fallbacks, offline route evaluation, and metadata-only latency/reliability reporting. Review the policy behavior and audit output before enabling it in a production Hermes profile. The project remains conservative: when in doubt, it asks Hermes to ask you.

Keywords

Hermes Agent, Jev, TypeSafe, AI safety, agent safety, tool authorization, tool calling, policy engine, policy gate, OpenRouter, prompt injection defense, secret redaction, human-in-the-loop, approval workflows, fail closed, autonomous agents, LLM security, Python plugin.

License

This project is licensed under the MIT License.

Hermes catalog submission

This repository is prepared for submission to the Hermes community plugin catalog. The catalog entry must pin an exact reviewed commit SHA and declare the plugin's hooks, environment variables, and other capabilities. See CONTRIBUTING.md for the submission and release workflow.