@agentikos/omega-os 0.2.0 → 0.19.5

package/omega/Agentik_Engine/omega_engine/hermes.py

@@ -0,0 +1,426 @@
+"""Hermes Agent bridge — Layer 2 companion using the same Claude Max OAuth.
+
+What this is
+------------
+
+Hermes is a self-improving open-source AI agent by Nous Research
+(https://github.com/NousResearch/hermes-agent). It runs its own loop,
+its own skills system, its own messaging gateway. We integrate it as
+the "Layer 2" autonomous companion ABOVE AISB:
+
+  Layer 1   Human (Telegram, CLI, web)
+  Layer 2   Hermes        ← autonomous, self-improving, cross-platform gateway
+  Layer 3   AISB          ← OmegaOS intake / orchestrator
+  Layer 4   Oracle        ← planner / dispatcher
+  Layer 5   Worker        ← executor with .done.json verification
+
+Hermes is NOT a Claude Code subprocess wrapper — it runs its own Python
+runtime making direct Anthropic API calls. BUT it natively supports the
+``CLAUDE_CODE_OAUTH_TOKEN`` env var, so we can hand it the SAME OAuth
+token that ``claude`` CLI uses. No API key. No new credential.
+
+Confirmed in upstream source
+----------------------------
+
+``plugins/model-providers/anthropic/__init__.py``::
+
+    anthropic = AnthropicProfile(
+        name="anthropic",
+        aliases=("claude", "claude-oauth", "claude-code"),
+        env_vars=("ANTHROPIC_API_KEY", "ANTHROPIC_TOKEN",
+                   "CLAUDE_CODE_OAUTH_TOKEN"),
+        ...
+    )
+
+The token lives at ``~/.claude/.credentials.json`` →
+``claudeAiOauth.accessToken``. We read it there each call so refresh
+rotations propagate naturally — Hermes always sees the latest access
+token without storing its own copy.
+
+What this module exposes
+------------------------
+
+  * :func:`claude_oauth_token` — read + return the live access token.
+  * :func:`is_installed` — is ``hermes`` on PATH?
+  * :func:`install` — run upstream ``install.sh`` (idempotent).
+  * :func:`link` — write Hermes config to point at the OAuth provider.
+  * :func:`status` — installed + linked + token-valid + binary-version.
+  * :func:`ask` — convenience: invoke ``hermes`` with a one-shot prompt
+                  and return stdout.
+  * :func:`build_env` — build the env dict that injects the OAuth token
+                        + sane provider defaults for any Hermes call.
+
+The CLI surface ``omega hermes {install,link,status,ask}`` lives in
+``cli.py``.
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+_CLAUDE_CREDS = Path.home() / ".claude" / ".credentials.json"
+_HERMES_HOME_ENV = "HERMES_HOME"
+_DEFAULT_HERMES_HOME = Path.home() / ".hermes"
+
+# Upstream installer (verified against the repo on 2026-05-25)
+_INSTALL_URL = (
+    "https://raw.githubusercontent.com/"
+    "NousResearch/hermes-agent/main/scripts/install.sh"
+)
+_REPO_URL = "https://github.com/NousResearch/hermes-agent"
+
+
+# ---------------------------------------------------------------------------
+# Errors
+# ---------------------------------------------------------------------------
+
+
+class HermesError(RuntimeError):
+    """Raised when a Hermes bridge operation can't proceed safely."""
+
+
+# ---------------------------------------------------------------------------
+# OAuth token — read from the live Claude credentials store
+# ---------------------------------------------------------------------------
+
+
+def claude_oauth_token(creds_path: str | Path | None = None) -> str:
+    """Return the live Claude Code Max OAuth access token.
+
+    Reads ``~/.claude/.credentials.json``, extracts
+    ``claudeAiOauth.accessToken``. We read on EVERY call so token
+    refreshes done by ``claude`` propagate naturally — no stale copy
+    cached anywhere.
+
+    Raises :class:`HermesError` with a friendly message if the token
+    isn't available (no creds file, malformed JSON, missing field).
+    """
+    p = Path(creds_path) if creds_path else _CLAUDE_CREDS
+    if not p.exists():
+        raise HermesError(
+            f"Claude credentials not found at {p} — log in with "
+            "`claude` first (`claude` on first launch does OAuth)."
+        )
+    try:
+        data = json.loads(p.read_text())
+    except (OSError, json.JSONDecodeError) as exc:
+        raise HermesError(f"failed to parse {p}: {exc}") from exc
+    token = (
+        data.get("claudeAiOauth", {}).get("accessToken")
+        if isinstance(data, dict) else None
+    )
+    if not token:
+        raise HermesError(
+            f"{p} has no claudeAiOauth.accessToken — run `claude` "
+            "to re-do OAuth, then retry."
+        )
+    return str(token)
+
+
+def token_expires_at(creds_path: str | Path | None = None) -> int | None:
+    """Return the OAuth token expiry epoch (ms) — None if not present."""
+    p = Path(creds_path) if creds_path else _CLAUDE_CREDS
+    if not p.exists():
+        return None
+    try:
+        data = json.loads(p.read_text())
+    except (OSError, json.JSONDecodeError):
+        return None
+    v = data.get("claudeAiOauth", {}).get("expiresAt")
+    return int(v) if isinstance(v, (int, float, str)) and str(v).isdigit() \
+        else None
+
+
+def subscription_type(creds_path: str | Path | None = None) -> str:
+    """Return the Claude subscription type ('max', 'free', etc.) or ''."""
+    p = Path(creds_path) if creds_path else _CLAUDE_CREDS
+    if not p.exists():
+        return ""
+    try:
+        data = json.loads(p.read_text())
+    except (OSError, json.JSONDecodeError):
+        return ""
+    return str(data.get("claudeAiOauth", {}).get("subscriptionType") or "")
+
+
+# ---------------------------------------------------------------------------
+# Install / link
+# ---------------------------------------------------------------------------
+
+
+def is_installed(bin_name: str = "hermes") -> bool:
+    """True iff the ``hermes`` binary is on PATH."""
+    return shutil.which(bin_name) is not None
+
+
+def hermes_home() -> Path:
+    """Return ``$HERMES_HOME`` or the default ``~/.hermes``."""
+    return Path(os.environ.get(_HERMES_HOME_ENV, str(_DEFAULT_HERMES_HOME)))
+
+
+@dataclass
+class InstallResult:
+    ok: bool
+    elapsed_s: float
+    method: str          # "curl-pipe" | "skipped-already-installed"
+    detail: str = ""
+    error: str = ""
+
+
+def install(
+    *,
+    skip_browser: bool = True,
+    skip_setup: bool = True,
+    timeout_s: int = 900,
+    yes: bool = False,
+    dry_run: bool = False,
+) -> InstallResult:
+    """Install Hermes via the upstream ``install.sh``.
+
+    Default flags mirror the OmegaOS philosophy: SKIP the interactive
+    setup wizard (we configure Hermes ourselves via ``link()``) and SKIP
+    the heavy Playwright/Chromium download (operators turn it on only
+    if they need the browser tool).
+
+    ``dry_run=True`` returns the command that WOULD run, no side effects.
+    ``yes=False`` aborts when Hermes is already installed unless the
+    caller explicitly opts into re-install.
+    """
+    started = time.time()
+    if is_installed() and not yes and not dry_run:
+        return InstallResult(
+            ok=True, elapsed_s=0.0,
+            method="skipped-already-installed",
+            detail=f"hermes on PATH at {shutil.which('hermes')}",
+        )
+
+    # `curl -fsSL <url> | bash -s -- <flags>`
+    flags: list[str] = []
+    if skip_browser: flags.append("--skip-browser")
+    if skip_setup:   flags.append("--skip-setup")
+    cmd_str = (
+        f"curl -fsSL {_INSTALL_URL} | bash -s --"
+        + (" " + " ".join(flags) if flags else "")
+    )
+    if dry_run:
+        return InstallResult(
+            ok=True, elapsed_s=round(time.time() - started, 2),
+            method="dry-run", detail=cmd_str,
+        )
+    try:
+        proc = subprocess.run(
+            ["bash", "-c", cmd_str],
+            check=False, capture_output=True, text=True, timeout=timeout_s,
+        )
+    except subprocess.TimeoutExpired:
+        return InstallResult(
+            ok=False, elapsed_s=round(time.time() - started, 2),
+            method="curl-pipe",
+            error=f"install.sh timed out after {timeout_s}s",
+        )
+    except OSError as exc:
+        return InstallResult(
+            ok=False, elapsed_s=round(time.time() - started, 2),
+            method="curl-pipe", error=f"exec failed: {exc}",
+        )
+    if proc.returncode != 0:
+        tail = (proc.stdout + "\n" + proc.stderr).strip()[-400:]
+        return InstallResult(
+            ok=False, elapsed_s=round(time.time() - started, 2),
+            method="curl-pipe",
+            error=f"install.sh exited {proc.returncode}\n{tail}",
+        )
+    return InstallResult(
+        ok=True, elapsed_s=round(time.time() - started, 2),
+        method="curl-pipe",
+        detail=f"hermes installed; bin={shutil.which('hermes') or '(re-source shell)'}",
+    )
+
+
+def build_env(
+    *,
+    extra: dict[str, str] | None = None,
+    creds_path: str | Path | None = None,
+) -> dict[str, str]:
+    """Build the env dict for every Hermes invocation.
+
+    Injects ``CLAUDE_CODE_OAUTH_TOKEN`` from the live credentials file +
+    a few sane defaults (``HERMES_PROVIDER=anthropic``,
+    ``HERMES_MODEL=claude-opus-4-7``). Caller env wins via ``extra``.
+    """
+    token = claude_oauth_token(creds_path)
+    env = {**os.environ}
+    env["CLAUDE_CODE_OAUTH_TOKEN"] = token
+    # If the operator had stale anthropic env vars set, the OAuth token
+    # takes precedence. We do NOT clear them — operators may have legit
+    # API key setups for other tools.
+    env.setdefault("HERMES_PROVIDER", "anthropic")
+    env.setdefault("HERMES_MODEL", "claude-opus-4-7")
+    if extra:
+        env.update(extra)
+    return env
+
+
+@dataclass
+class LinkResult:
+    ok: bool
+    config_path: str = ""
+    provider: str = ""
+    model: str = ""
+    expires_at_ms: int | None = None
+    subscription: str = ""
+    error: str = ""
+
+
+def link(
+    *,
+    provider: str = "anthropic",
+    model: str = "claude-opus-4-7",
+    hermes_cmd: str = "hermes",
+    dry_run: bool = False,
+) -> LinkResult:
+    """Wire Hermes to use the Claude Code OAuth token.
+
+    Two steps:
+      1. Validate the OAuth token is present + reasonably fresh.
+      2. Write a small config file at ``$HERMES_HOME/omega.env`` that
+         exports the env vars Hermes needs. Operator sources it (or
+         the daemon launcher reads it) before invoking ``hermes``.
+
+    Why a file instead of running ``hermes config set``: the daemon
+    needs the token at start-up, and the token rotates. Writing the
+    file (and refreshing it before each Hermes invocation via
+    ``build_env``) is the simplest path that survives rotation.
+    """
+    try:
+        token = claude_oauth_token()
+    except HermesError as exc:
+        return LinkResult(ok=False, error=str(exc))
+
+    home = hermes_home()
+    cfg = home / "omega.env"
+    expires = token_expires_at()
+    sub = subscription_type()
+
+    if dry_run:
+        return LinkResult(
+            ok=True, config_path=str(cfg), provider=provider,
+            model=model, expires_at_ms=expires, subscription=sub,
+        )
+    home.mkdir(parents=True, exist_ok=True)
+    # We intentionally write a HEAD that points readers at the live
+    # credentials file rather than the token literal — never persist
+    # the access token. ``build_env`` is the live-read path.
+    cfg.write_text(
+        "# Omega bridge — sources the live Claude OAuth token at runtime.\n"
+        "# DO NOT copy a token literal in here; the live file is at\n"
+        f"# {_CLAUDE_CREDS}\n"
+        f"#\n"
+        f"# Default provider + model when the omega bridge invokes hermes:\n"
+        f"export HERMES_PROVIDER='{provider}'\n"
+        f"export HERMES_MODEL='{model}'\n"
+        f"export CLAUDE_CODE_OAUTH_TOKEN=\"$(python3 -c \"import json,pathlib;print(json.loads(pathlib.Path('{_CLAUDE_CREDS}').read_text())['claudeAiOauth']['accessToken'])\")\"\n"
+    )
+    try:
+        os.chmod(cfg, 0o600)
+    except OSError:
+        pass
+    return LinkResult(
+        ok=True, config_path=str(cfg), provider=provider, model=model,
+        expires_at_ms=expires, subscription=sub,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Status / ask
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class StatusReport:
+    installed: bool
+    hermes_bin: str = ""
+    hermes_version: str = ""
+    hermes_home: str = ""
+    omega_env_present: bool = False
+    oauth_token_present: bool = False
+    oauth_subscription: str = ""
+    oauth_expires_at_ms: int | None = None
+    oauth_expires_in_s: int | None = None
+
+
+def status() -> StatusReport:
+    """Snapshot of every surface we care about."""
+    bin_path = shutil.which("hermes") or ""
+    ver = ""
+    if bin_path:
+        try:
+            proc = subprocess.run(
+                [bin_path, "--version"],
+                check=False, capture_output=True, text=True, timeout=10,
+            )
+            ver = (proc.stdout or proc.stderr).strip().splitlines()[0:1]
+            ver = ver[0] if ver else ""
+        except (OSError, subprocess.SubprocessError):
+            pass
+    home = hermes_home()
+    cfg = home / "omega.env"
+    sub = subscription_type()
+    expires = token_expires_at()
+    in_s = (int(expires / 1000) - int(time.time())) if expires else None
+    return StatusReport(
+        installed=bool(bin_path),
+        hermes_bin=bin_path,
+        hermes_version=ver,
+        hermes_home=str(home),
+        omega_env_present=cfg.exists(),
+        oauth_token_present=_CLAUDE_CREDS.exists() and bool(
+            (json.loads(_CLAUDE_CREDS.read_text())
+             if _CLAUDE_CREDS.exists() else {})
+            .get("claudeAiOauth", {}).get("accessToken")
+        ) if _CLAUDE_CREDS.exists() else False,
+        oauth_subscription=sub,
+        oauth_expires_at_ms=expires,
+        oauth_expires_in_s=in_s,
+    )
+
+
+def ask(
+    prompt: str,
+    *,
+    hermes_cmd: str = "hermes",
+    timeout_s: int = 600,
+    extra_env: dict[str, str] | None = None,
+) -> tuple[int, str, str]:
+    """Run ``hermes`` once with the prompt, returns (rc, stdout, stderr).
+
+    Hermes's one-shot mode is ``hermes <prompt>`` or ``hermes run <prompt>``
+    depending on version. We try ``hermes`` first (most documented),
+    fall back to ``hermes run`` if the binary rejects positional args.
+    """
+    if not is_installed(hermes_cmd):
+        raise HermesError(
+            f"`{hermes_cmd}` not on PATH — run `omega hermes install`"
+        )
+    if not prompt or not prompt.strip():
+        raise HermesError("ask() requires a non-empty prompt")
+    try:
+        env = build_env(extra=extra_env)
+    except HermesError:
+        raise
+    try:
+        proc = subprocess.run(
+            [hermes_cmd, prompt],
+            check=False, capture_output=True, text=True,
+            timeout=timeout_s, env=env,
+        )
+    except subprocess.TimeoutExpired:
+        return 124, "", f"hermes timed out after {timeout_s}s"
+    return proc.returncode, proc.stdout or "", proc.stderr or ""