ory-hermes 1.3.0__tar.gz

ory_hermes-1.3.0/.gitignore

@@ -0,0 +1,49 @@
+node_modules/
+dist/
+*.tsbuildinfo
+.env
+.env.local
+
+# Python (uv workspace under python/)
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+build/
+*.pyc
+
+# Debug logs
+*.log
+
+# Standalone deployment CLI state and decrypted credentials
+.ory/deployment.json
+.ory/credentials.env
+
+# Harness sandbox dirs
+.sandbox/
+
+# Staged install-surface repo contents (see scripts/sync-install-surfaces.mjs)
+.install-surfaces/
+
+# Local dev environment (local Ory stack + Verdaccio registry)
+.ory-dev/
+
+# Worktrees for changes
+.worktrees/
+.claude/worktrees/
+
+# Gemini CLI extension assets — materialized at install time from
+# @ory/argus templates. The repo source is the canonical templates;
+# these subdirs are generated wherever the install runs. The manifest and
+# hook wiring embed absolute paths resolved on the installing machine, so
+# they must never be committed. `GEMINI.md` is tracked source, so the
+# extension dir itself is deliberately not ignored wholesale.
+packages/gemini-cli/gemini-extension/skills/
+packages/gemini-cli/gemini-extension/commands/
+packages/gemini-cli/gemini-extension/hooks/
+packages/gemini-cli/gemini-extension/gemini-extension.json
+
+# Antigravity plugin bundle — same story, but the whole directory is
+# generated (skills, commands, hooks.json, mcp_config.json, plugin.json).
+packages/antigravity/antigravity-plugin/

ory_hermes-1.3.0/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.5
+Name: ory-hermes
+Version: 1.3.0
+Summary: Ory Agent Security for the Hermes agent framework — per-tool authorization, activity logging, and identity propagation by wrapping the tool registry. Built on ory-argus.
+Author: Ory
+License-Expression: Apache-2.0
+Keywords: agent,ai,authorization,hermes,hermes-agent,nous,ory,permissions
+Requires-Python: >=3.10
+Requires-Dist: ory-argus<2,>=1
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ory-hermes
+
+Ory Agent Security for the [Hermes agent framework](https://github.com/NousResearch/hermes-agent).
+
+Wraps your Hermes tool registry so every call is authorized against Ory Permissions,
+audited, and tied to the user → agent identity — built on
+[`ory-argus`](https://pypi.org/project/ory-argus/).
+
+```bash
+pip install ory-hermes
+```
+
+Hermes drives its loop from a `{name: callable}` tool registry (`model_tools`).
+Gate it before handing it to the agent:
+
+```python
+from ory_hermes import guard_function_map
+
+tools = guard_function_map(model_tools)   # returns a gated copy of the registry
+```
+
+Tool objects (with a `run` / `_run` method) work too:
+
+```python
+from ory_hermes import guard_tools
+
+tools = guard_tools([search_tool, shell_tool])
+```
+
+In **enforce** mode a denied tool raises `OryDenialError`
+before the tool body runs; Hermes surfaces the denial and the tool never executes. In
+**observe** mode (default) the tool runs and a `permission.observe_deny` activity event is recorded.
+Network / rate-limit errors fail open.
+
+> The integration is SDK-free: it wraps Hermes' plain Python registry by duck typing.
+> Hermes is installed through its own bootstrap process and does not publish an
+> installable Python SDK, so this package intentionally has no Hermes dependency or
+> external real-SDK compatibility test.
+
+Credentials come from the shared `~/.config/ory-agent-plugins/config.json`, so a login
+performed by any other Ory harness plugin or SDK integration is reused here.

ory_hermes-1.3.0/README.md

@@ -0,0 +1,41 @@
+# ory-hermes
+
+Ory Agent Security for the [Hermes agent framework](https://github.com/NousResearch/hermes-agent).
+
+Wraps your Hermes tool registry so every call is authorized against Ory Permissions,
+audited, and tied to the user → agent identity — built on
+[`ory-argus`](https://pypi.org/project/ory-argus/).
+
+```bash
+pip install ory-hermes
+```
+
+Hermes drives its loop from a `{name: callable}` tool registry (`model_tools`).
+Gate it before handing it to the agent:
+
+```python
+from ory_hermes import guard_function_map
+
+tools = guard_function_map(model_tools)   # returns a gated copy of the registry
+```
+
+Tool objects (with a `run` / `_run` method) work too:
+
+```python
+from ory_hermes import guard_tools
+
+tools = guard_tools([search_tool, shell_tool])
+```
+
+In **enforce** mode a denied tool raises `OryDenialError`
+before the tool body runs; Hermes surfaces the denial and the tool never executes. In
+**observe** mode (default) the tool runs and a `permission.observe_deny` activity event is recorded.
+Network / rate-limit errors fail open.
+
+> The integration is SDK-free: it wraps Hermes' plain Python registry by duck typing.
+> Hermes is installed through its own bootstrap process and does not publish an
+> installable Python SDK, so this package intentionally has no Hermes dependency or
+> external real-SDK compatibility test.
+
+Credentials come from the shared `~/.config/ory-agent-plugins/config.json`, so a login
+performed by any other Ory harness plugin or SDK integration is reused here.

ory_hermes-1.3.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ory-hermes"
+version = "1.3.0"
+description = "Ory Agent Security for the Hermes agent framework — per-tool authorization, activity logging, and identity propagation by wrapping the tool registry. Built on ory-argus."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [{ name = "Ory" }]
+keywords = ["ory", "hermes", "hermes-agent", "nous", "authorization", "agent", "ai", "permissions"]
+dependencies = [
+    "ory-argus>=1,<2",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ory_hermes"]

ory_hermes-1.3.0/src/ory_hermes/__init__.py

@@ -0,0 +1,27 @@
+"""Ory Agent Security for the Hermes agent framework.
+
+    from ory_hermes import guard_function_map
+
+    tools = guard_function_map(model_tools)   # {name: callable} registry
+"""
+
+from __future__ import annotations
+
+from .tools import (
+    guard_callable,
+    guard_function_map,
+    guard_tools,
+    guarded_acall,
+    guarded_call,
+)
+
+__version__ = "1.3.0"
+
+__all__ = [
+    "guard_function_map",
+    "guard_tools",
+    "guard_callable",
+    "guarded_call",
+    "guarded_acall",
+    "__version__",
+]

ory_hermes-1.3.0/src/ory_hermes/tools.py

@@ -0,0 +1,300 @@
+"""Ory Agent Security for the Hermes agent framework.
+
+Hermes (``NousResearch/hermes-agent``) drives its conversation loop by resolving a
+tool **registry** — a ``{name: callable}`` map built in ``model_tools.py`` — and
+executing entries via ``handle_function_call``. Its approval hooks
+(``pre_approval_request`` / ``post_approval_response``) and ``_smart_approve`` are
+observation/approval-lifecycle points, not a reliable programmatic veto, so the
+integration gates at the **tool-execution** boundary instead: it wraps each
+callable in the registry so every call is authorized against Ory Permissions,
+logged, and (on first call) preceded by the Ory session gates.
+
+  - allow / observe / fail-open / interactive → run the tool and record ``tool.complete``.
+  - deny (enforce) → raise ``OryDenialError`` so Hermes surfaces the denial and the
+    tool never runs.
+
+Gate logic lives in ``ory_argus``; no Hermes import is required (the registry is
+duck-typed), so this package installs SDK-free.
+"""
+
+from __future__ import annotations
+
+import inspect
+import sys
+from collections.abc import Callable
+from typing import Any
+
+from ory_argus import (
+    GateResult,
+    OryAgentClient,
+    complete,
+    create_session_starter,
+    fail,
+    gate,
+)
+from ory_argus.adapters import denial_error
+
+HARNESS = "hermes"
+
+
+def _gate_or_deny(
+    client: OryAgentClient,
+    *,
+    tool_name: str,
+    args: tuple,
+    kwargs: dict,
+    can_block: bool,
+    ensure_session_started: Callable[[], None],
+) -> None:
+    """Run session-start (once) + the permission gate; raise OryDenialError on enforce-deny."""
+    ensure_session_started()
+
+    result: GateResult = gate(
+        client,
+        harness=HARNESS,
+        tool_name=tool_name,
+        tool_args={"args": args, "kwargs": kwargs},
+        can_block=can_block,
+    )
+    if result.blocked:
+        raise denial_error(result, tool_name)
+
+
+def guarded_call(
+    client: OryAgentClient,
+    *,
+    tool_name: str,
+    fn: Callable,
+    args: tuple,
+    kwargs: dict,
+    can_block: bool = True,
+    project_url: str | None = None,
+    _session_starter: Callable[[], None] | None = None,
+) -> Any:
+    """SDK-free gate-then-run for a single synchronous tool call."""
+    ensure_session_started = _session_starter or create_session_starter(
+        client, harness=HARNESS, project_url=project_url
+    )
+    _gate_or_deny(
+        client, tool_name=tool_name, args=args, kwargs=kwargs,
+        can_block=can_block, ensure_session_started=ensure_session_started,
+    )
+    tool_input = {"args": args, "kwargs": kwargs}
+    try:
+        output = fn(*args, **kwargs)
+        complete(client, tool_name=tool_name, input=tool_input, output=output)
+        return output
+    except Exception as error:
+        fail(client, tool_name=tool_name, input=tool_input, error=error)
+        raise
+
+
+async def guarded_acall(
+    client: OryAgentClient,
+    *,
+    tool_name: str,
+    fn: Callable,
+    args: tuple,
+    kwargs: dict,
+    can_block: bool = True,
+    project_url: str | None = None,
+    _session_starter: Callable[[], None] | None = None,
+) -> Any:
+    """SDK-free gate-then-run for a single async tool call.
+
+    Same semantics as :func:`guarded_call` — the gate runs (and an enforce-deny raises
+    ``OryDenialError``) BEFORE the tool body executes; observe/fail-open proceed with activity logging.
+    """
+    ensure_session_started = _session_starter or create_session_starter(
+        client, harness=HARNESS, project_url=project_url
+    )
+    _gate_or_deny(
+        client, tool_name=tool_name, args=args, kwargs=kwargs,
+        can_block=can_block, ensure_session_started=ensure_session_started,
+    )
+    tool_input = {"args": args, "kwargs": kwargs}
+    try:
+        output = fn(*args, **kwargs)
+        if inspect.isawaitable(output):
+            output = await output
+        complete(client, tool_name=tool_name, input=tool_input, output=output)
+        return output
+    except Exception as error:
+        fail(client, tool_name=tool_name, input=tool_input, error=error)
+        raise
+
+
+def guard_callable(
+    fn: Callable,
+    *,
+    name: str | None = None,
+    client: OryAgentClient,
+    can_block: bool = True,
+    project_url: str | None = None,
+    _session_starter: Callable[[], None] | None = None,
+) -> Callable:
+    """Return a gated wrapper around a single tool callable (sync or async preserved)."""
+    tool_name = name or getattr(fn, "__name__", None) or "unknown"
+    ensure_session_started = _session_starter or create_session_starter(
+        client, harness=HARNESS, project_url=project_url
+    )
+
+    if inspect.iscoroutinefunction(fn):
+        async def _awrapped(*args, **kwargs):
+            return await guarded_acall(
+                client, tool_name=tool_name, fn=fn, args=args, kwargs=kwargs,
+                can_block=can_block, project_url=project_url,
+                _session_starter=ensure_session_started,
+            )
+        return _awrapped
+
+    def _wrapped(*args, **kwargs):
+        return guarded_call(
+            client, tool_name=tool_name, fn=fn, args=args, kwargs=kwargs,
+            can_block=can_block, project_url=project_url,
+            _session_starter=ensure_session_started,
+        )
+    return _wrapped
+
+
+def guard_function_map(
+    function_map: dict[str, Callable],
+    *,
+    client: OryAgentClient | None = None,
+    can_block: bool = True,
+    project_url: str | None = None,
+) -> dict[str, Callable]:
+    """Gate every callable in a Hermes tool registry (``{name: callable}``).
+
+    Returns a NEW dict with each callable wrapped; the session gates run once and are
+    shared across every tool in the map. This is the primary Hermes seam — pass the
+    ``model_tools`` registry through it before handing it to the agent.
+    """
+    c = client or OryAgentClient.from_env(HARNESS)
+    ensure_session_started = create_session_starter(
+        c, harness=HARNESS, project_url=project_url
+    )
+    return {
+        name: guard_callable(
+            fn, name=name, client=c, can_block=can_block,
+            project_url=project_url, _session_starter=ensure_session_started,
+        )
+        for name, fn in function_map.items()
+    }
+
+
+def _warn_wrap_failed(client: OryAgentClient, event: str, tool_name: str, err: Exception) -> None:
+    """Wrapping failed: the tool will run UNGATED. Log + always warn on stderr (never stdout)."""
+    client.logger.warn(event, {"tool": tool_name, "message": str(err)})
+    print(
+        f"[ory] WARNING: failed to wrap tool '{tool_name}' ({err}); "
+        "it will run UNGATED by Ory permission checks.",
+        file=sys.stderr,
+    )
+
+
+# Method names Hermes-style tool objects execute through, in priority order.
+_SYNC_METHODS = ("run", "_run", "execute", "__call__")
+_ASYNC_METHODS = ("arun", "_arun", "aexecute")
+
+
+def guard_tools(
+    tools: list,
+    *,
+    client: OryAgentClient | None = None,
+    can_block: bool = True,
+    project_url: str | None = None,
+) -> list:
+    """Gate a list of Hermes tool objects (or bare callables).
+
+    For each item: an object exposing a ``run`` / ``_run`` (and optional async
+    ``arun`` / ``_arun``) method is monkeypatched in place; a bare callable is
+    replaced with a gated wrapper in the returned list. The session gates run once,
+    shared across every tool. Returns the (possibly re-populated) list.
+    """
+    c = client or OryAgentClient.from_env(HARNESS)
+    ensure_session_started = create_session_starter(
+        c, harness=HARNESS, project_url=project_url
+    )
+    out: list = []
+    for tool in tools:
+        # Bare callable (plain function tool): can't patch in place — wrap it.
+        if not _has_method(tool, _SYNC_METHODS + _ASYNC_METHODS) and callable(tool):
+            out.append(
+                guard_callable(
+                    tool, client=c, can_block=can_block,
+                    project_url=project_url, _session_starter=ensure_session_started,
+                )
+            )
+            continue
+
+        tool_name = getattr(tool, "name", None) or type(tool).__name__
+        _patch_methods(
+            c, tool, tool_name, _SYNC_METHODS, ensure_session_started,
+            can_block, project_url, is_async=False,
+        )
+        _patch_methods(
+            c, tool, tool_name, _ASYNC_METHODS, ensure_session_started,
+            can_block, project_url, is_async=True,
+        )
+        out.append(tool)
+    return out
+
+
+def _has_method(tool: Any, names: tuple) -> bool:
+    return any(callable(getattr(tool, n, None)) for n in names if n != "__call__")
+
+
+def _patch_methods(
+    client: OryAgentClient,
+    tool: Any,
+    tool_name: str,
+    names: tuple,
+    ensure_session_started: Callable[[], None],
+    can_block: bool,
+    project_url: str | None,
+    *,
+    is_async: bool,
+) -> None:
+    for method_name in names:
+        if method_name == "__call__":
+            continue
+        original = getattr(tool, method_name, None)
+        if not callable(original):
+            continue
+
+        if is_async:
+            def _make(run):
+                async def _awrapped(*args, **kwargs):
+                    return await guarded_acall(
+                        client, tool_name=tool_name, fn=run, args=args, kwargs=kwargs,
+                        can_block=can_block, project_url=project_url,
+                        _session_starter=ensure_session_started,
+                    )
+                return _awrapped
+        else:
+            def _make(run):
+                def _wrapped(*args, **kwargs):
+                    return guarded_call(
+                        client, tool_name=tool_name, fn=run, args=args, kwargs=kwargs,
+                        can_block=can_block, project_url=project_url,
+                        _session_starter=ensure_session_started,
+                    )
+                return _wrapped
+
+        try:
+            setattr(tool, method_name, _make(original))
+        except Exception as err:  # noqa: BLE001 — some tool models are frozen
+            _warn_wrap_failed(client, "hermes.wrap_tool.failed", tool_name, err)
+        # Only wrap the first execution method that exists (highest priority).
+        return
+
+
+__all__ = [
+    "HARNESS",
+    "guard_callable",
+    "guard_function_map",
+    "guard_tools",
+    "guarded_acall",
+    "guarded_call",
+]

ory_hermes-1.3.0/tests/test_tools.py

@@ -0,0 +1,195 @@
+"""Hermetic tests for the Hermes tool-wrap gate (SDK-free).
+
+Covers the native veto shape (``OryDenialError`` raised from the wrapped tool) and
+request-shape delegation (registry name + verbatim args) for both the function-map
+seam and tool objects, plus the shared session sequence. The full permission
+decision matrix is core-owned (``ory-argus/tests/test_adapters.py``) and re-run here
+through ``run_gate_matrix``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from ory_argus.client import PrincipalIdentity
+from ory_argus.denial import OryDenialError
+from ory_argus.testing import (
+    GateCase,
+    connect_security,
+    create_mock_client,
+    get_activity_events,
+    run_gate_matrix,
+    stub_permission_allowed,
+    stub_permission_denied,
+)
+from ory_hermes import guard_function_map, guard_tools
+
+
+@pytest.fixture(autouse=True)
+def _isolate(monkeypatch, tmp_path):
+    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path))
+    connect_security(monkeypatch)
+    monkeypatch.delenv("ORY_PERMISSION_MODE", raising=False)
+
+
+def client_with_user():
+    c = create_mock_client(harness="hermes")
+    c.set_user_principal(PrincipalIdentity(subject="user:alice"))
+    return c
+
+
+# ── function-map seam ──
+
+
+def test_function_map_allow_runs_and_completes():
+    c = client_with_user()
+    stub_permission_allowed(c)
+    ran = []
+
+    def search(*args, **kwargs):
+        ran.append((args, kwargs))
+        return "hit"
+
+    tools = guard_function_map({"search": search}, client=c)
+    assert tools["search"]("q", k=1) == "hit"
+    assert ran == [(("q",), {"k": 1})]
+    invoke = get_activity_events(c, "tool.invoke")[0]
+    assert invoke.attributes["allowed"] is True
+    assert invoke.attributes["toolName"] == "search"
+    assert get_activity_events(c, "tool.complete")
+
+
+def test_function_map_enforce_raises_and_skips(monkeypatch):
+    monkeypatch.setenv("ORY_PERMISSION_MODE", "enforce")
+    c = client_with_user()
+    stub_permission_denied(c)
+    ran = []
+
+    def rm(*args, **kwargs):
+        ran.append(True)
+        return "gone"
+
+    tools = guard_function_map({"rm": rm}, client=c)
+    with pytest.raises(OryDenialError):
+        tools["rm"]()
+    assert ran == []  # underlying tool never invoked
+    assert get_activity_events(c, "tool.block")[0].attributes["blocked"] is True
+
+
+def test_function_map_async(monkeypatch):
+    monkeypatch.setenv("ORY_PERMISSION_MODE", "enforce")
+    c = client_with_user()
+    stub_permission_denied(c)
+    ran = []
+
+    async def fetch(*args, **kwargs):
+        ran.append(True)
+        return "data"
+
+    tools = guard_function_map({"fetch": fetch}, client=c)
+    with pytest.raises(OryDenialError):
+        asyncio.run(tools["fetch"]())
+    assert ran == []
+
+
+def test_function_map_observe_runs_tool():
+    c = client_with_user()
+    stub_permission_denied(c)  # observe mode (default) → tool still runs
+    tools = guard_function_map({"rm": lambda: "gone"}, client=c)
+    assert tools["rm"]() == "gone"
+    assert get_activity_events(c, "permission.block_observed")
+
+
+def test_session_start_once_across_map():
+    c = client_with_user()
+    stub_permission_allowed(c)
+    tools = guard_function_map({"a": lambda: 1, "b": lambda: 2}, client=c)
+    tools["a"]()
+    tools["b"]()
+    assert len(get_activity_events(c, "tool.invoke")) == 2
+
+
+# ── tool objects seam ──
+
+
+class FakeTool:
+    def __init__(self, name):
+        self.name = name
+        self.ran = []
+
+    def run(self, *args, **kwargs):
+        self.ran.append((args, kwargs))
+        return f"ran:{self.name}"
+
+
+def test_tool_object_enforce_raises_and_skips(monkeypatch):
+    monkeypatch.setenv("ORY_PERMISSION_MODE", "enforce")
+    c = client_with_user()
+    stub_permission_denied(c)
+    tool = FakeTool("shell")
+    guard_tools([tool], client=c)
+    with pytest.raises(OryDenialError):
+        tool.run("rm -rf /")
+    assert tool.ran == []
+    assert get_activity_events(c, "tool.block")[0].attributes["blocked"] is True
+
+
+def test_tool_object_allow_runs():
+    c = client_with_user()
+    stub_permission_allowed(c)
+    tool = FakeTool("search")
+    guard_tools([tool], client=c)
+    assert tool.run("q") == "ran:search"
+    assert get_activity_events(c, "tool.invoke")[0].attributes["toolName"] == "search"
+
+
+def test_bare_callable_in_list_is_wrapped():
+    c = client_with_user()
+    stub_permission_allowed(c)
+
+    def lookup(*args, **kwargs):
+        return "ok"
+
+    gated = guard_tools([lookup], client=c)
+    assert gated[0]("x") == "ok"
+    assert get_activity_events(c, "tool.invoke")[0].attributes["toolName"] == "lookup"
+
+
+def test_wrap_failure_warns_on_stderr(capsys):
+    c = client_with_user()
+    stub_permission_allowed(c)
+
+    class FrozenTool:
+        name = "frozen"
+
+        @property
+        def run(self):
+            return lambda: "x"
+
+    guard_tools([FrozenTool()], client=c)
+    err = capsys.readouterr().err
+    assert "UNGATED" in err
+    assert "frozen" in err
+
+
+# ── full decision matrix (core-owned, re-run through this integration) ──
+
+
+def test_gate_matrix():
+    def make(client):
+        ran = {}
+
+        def target(*args, **kwargs):
+            ran["yes"] = True
+            return "ran"
+
+        tools = guard_function_map({"target": target}, client=client)
+        return GateCase(
+            invoke=lambda: tools["target"](),
+            tool_ran=lambda: ran.get("yes", False),
+            vetoed=lambda out: isinstance(out, OryDenialError),
+        )
+
+    run_gate_matrix(make, harness="hermes")