simplicio-agent 0.25.0__py3-none-any.whl

acp_adapter/__init__.py

@@ -0,0 +1 @@
+"""ACP (Agent Communication Protocol) adapter for hermes-agent."""

acp_adapter/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running the ACP adapter as ``python -m acp_adapter``."""
+
+from .entry import main
+
+main()

acp_adapter/auth.py

@@ -0,0 +1,79 @@
+"""ACP auth helpers — detect and advertise Hermes authentication methods."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+TERMINAL_SETUP_AUTH_METHOD_ID = "hermes-setup"
+
+
+def detect_provider() -> Optional[str]:
+    """Resolve the active Hermes runtime provider, or None if unavailable.
+
+    Treats a ``Callable`` ``api_key`` (Azure Foundry Entra ID bearer
+    token provider — see :mod:`agent.azure_identity_adapter`) as a valid
+    credential. Without this, ACP sessions for Entra-configured Foundry
+    deployments silently default to ``"openrouter"`` and the ACP auth
+    handshake rejects the legitimate provider.
+    """
+    try:
+        from hermes_cli.runtime_provider import resolve_runtime_provider
+        runtime = resolve_runtime_provider()
+        api_key = runtime.get("api_key")
+        provider = runtime.get("provider")
+        if not isinstance(provider, str) or not provider.strip():
+            return None
+        is_string_key = isinstance(api_key, str) and api_key.strip()
+        is_callable_provider = callable(api_key) and not isinstance(api_key, str)
+        if is_string_key or is_callable_provider:
+            return provider.strip().lower()
+    except Exception:
+        return None
+    return None
+
+
+def has_provider() -> bool:
+    """Return True if Hermes can resolve any runtime provider credentials."""
+    return detect_provider() is not None
+
+
+def build_auth_methods() -> list[Any]:
+    """Return registry-compatible ACP auth methods for Hermes.
+
+    The official ACP registry validates that agents advertise at least one
+    usable auth method during the initial handshake. A fresh Zed install may
+    not have Hermes provider credentials configured yet, so Hermes always
+    advertises a terminal setup method. When credentials are already present,
+    it also advertises the resolved provider as the default agent-managed
+    runtime credential method.
+    """
+    from acp.schema import AuthMethodAgent, TerminalAuthMethod
+
+    methods: list[Any] = []
+    provider = detect_provider()
+    if provider:
+        methods.append(
+            AuthMethodAgent(
+                id=provider,
+                name=f"{provider} runtime credentials",
+                description=(
+                    "Authenticate Hermes using the currently configured "
+                    f"{provider} runtime credentials."
+                ),
+            )
+        )
+
+    methods.append(
+        TerminalAuthMethod(
+            id=TERMINAL_SETUP_AUTH_METHOD_ID,
+            name="Configure Hermes provider",
+            description=(
+                "Open Hermes' interactive model/provider setup in a terminal. "
+                "Use this when Hermes has not been configured on this machine yet."
+            ),
+            type="terminal",
+            args=["--setup"],
+        )
+    )
+    return methods

acp_adapter/edit_approval.py

@@ -0,0 +1,338 @@
+"""Pre-execution ACP edit approval helpers.
+
+This module is intentionally isolated from the generic tool registry.  ACP binds
+an edit approval requester in a ContextVar for the duration of one ACP agent run;
+CLI, gateway, and other sessions leave it unset and therefore bypass this guard.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import re
+import tempfile
+from concurrent.futures import TimeoutError as FutureTimeout
+from contextvars import ContextVar, Token
+from dataclasses import dataclass
+from itertools import count
+from pathlib import Path
+from typing import Any, Callable
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class EditProposal:
+    """A proposed single-file edit that can be shown to an ACP client."""
+
+    tool_name: str
+    path: str
+    old_text: str | None
+    new_text: str
+    arguments: dict[str, Any]
+
+
+EditApprovalRequester = Callable[[EditProposal], bool]
+
+_EDIT_APPROVAL_REQUESTER: ContextVar[EditApprovalRequester | None] = ContextVar(
+    "ACP_EDIT_APPROVAL_REQUESTER",
+    default=None,
+)
+_PERMISSION_REQUEST_IDS = count(1)
+
+
+SENSITIVE_AUTO_APPROVE_NAMES = {".env", ".env.local", ".env.production", "id_rsa", "id_ed25519"}
+AUTO_APPROVE_ASK = "ask"
+AUTO_APPROVE_WORKSPACE = "workspace_session"
+AUTO_APPROVE_SESSION = "session"
+
+
+def set_edit_approval_requester(requester: EditApprovalRequester | None) -> Token:
+    """Bind an ACP edit approval requester for the current context."""
+
+    return _EDIT_APPROVAL_REQUESTER.set(requester)
+
+
+def reset_edit_approval_requester(token: Token) -> None:
+    """Restore a previous edit approval requester binding."""
+
+    _EDIT_APPROVAL_REQUESTER.reset(token)
+
+
+def clear_edit_approval_requester() -> None:
+    """Clear the current requester; primarily used by tests."""
+
+    _EDIT_APPROVAL_REQUESTER.set(None)
+
+
+def get_edit_approval_requester() -> EditApprovalRequester | None:
+    return _EDIT_APPROVAL_REQUESTER.get()
+
+
+def _read_text_if_exists(path: str) -> str | None:
+    p = Path(path).expanduser()
+    if not p.exists():
+        return None
+    if not p.is_file():
+        raise OSError(f"Cannot edit non-file path: {path}")
+    return p.read_text(encoding="utf-8", errors="replace")
+
+
+def _proposal_for_write_file(arguments: dict[str, Any]) -> EditProposal:
+    path = str(arguments.get("path") or "")
+    if not path:
+        raise ValueError("path required")
+    content = arguments.get("content")
+    if content is None:
+        raise ValueError("content required")
+    return EditProposal(
+        tool_name="write_file",
+        path=path,
+        old_text=_read_text_if_exists(path),
+        new_text=str(content),
+        arguments=dict(arguments),
+    )
+
+
+def _proposal_for_patch_replace(arguments: dict[str, Any]) -> EditProposal:
+    path = str(arguments.get("path") or "")
+    if not path:
+        raise ValueError("path required")
+    old_string = arguments.get("old_string")
+    new_string = arguments.get("new_string")
+    if old_string is None or new_string is None:
+        raise ValueError("old_string and new_string required")
+
+    old_text = _read_text_if_exists(path)
+    if old_text is None:
+        raise ValueError(f"Failed to read file: {path}")
+
+    from tools.fuzzy_match import fuzzy_find_and_replace
+
+    new_text, match_count, _strategy, error = fuzzy_find_and_replace(
+        old_text,
+        str(old_string),
+        str(new_string),
+        bool(arguments.get("replace_all", False)),
+    )
+    if error or match_count == 0:
+        raise ValueError(error or f"Could not find match for old_string in {path}")
+
+    return EditProposal(
+        tool_name="patch",
+        path=path,
+        old_text=old_text,
+        new_text=new_text,
+        arguments=dict(arguments),
+    )
+
+
+def _extract_v4a_patch_paths(patch_body: str) -> list[str]:
+    paths: list[str] = []
+    for match in re.finditer(
+        r'^\*\*\*\s+(?:Update|Add|Delete)\s+File:\s*(.+)$',
+        patch_body,
+        re.MULTILINE,
+    ):
+        path = match.group(1).strip()
+        if path:
+            paths.append(path)
+    for match in re.finditer(
+        r'^\*\*\*\s+Move\s+File:\s*(.+?)\s*->\s*(.+)$',
+        patch_body,
+        re.MULTILINE,
+    ):
+        src = match.group(1).strip()
+        dst = match.group(2).strip()
+        if src:
+            paths.append(src)
+        if dst:
+            paths.append(dst)
+    return paths
+
+
+def _proposal_for_patch_v4a(arguments: dict[str, Any]) -> EditProposal:
+    patch_body = arguments.get("patch")
+    if not isinstance(patch_body, str) or not patch_body:
+        raise ValueError("patch content required")
+
+    paths = _extract_v4a_patch_paths(patch_body)
+    if not paths:
+        raise ValueError("no file paths found in V4A patch")
+
+    proposal_path = paths[0] if len(paths) == 1 else ", ".join(paths)
+    old_text = _read_text_if_exists(paths[0]) if len(paths) == 1 else None
+    return EditProposal(
+        tool_name="patch",
+        path=proposal_path,
+        old_text=old_text,
+        # ACP only supports a single diff payload here.  Surface the exact V4A
+        # patch content before execution so patch-mode calls are permissioned
+        # and denied patches cannot mutate.
+        new_text=patch_body,
+        arguments=dict(arguments),
+    )
+
+
+def build_edit_proposal(tool_name: str, arguments: dict[str, Any]) -> EditProposal | None:
+    """Return an edit proposal for supported file mutation calls."""
+
+    if tool_name == "write_file":
+        return _proposal_for_write_file(arguments)
+    if tool_name == "patch":
+        mode = arguments.get("mode", "replace")
+        if mode == "replace":
+            return _proposal_for_patch_replace(arguments)
+        if mode == "patch":
+            return _proposal_for_patch_v4a(arguments)
+    return None
+
+
+def _is_sensitive_auto_approve_path(path: str) -> bool:
+    parts = Path(path).expanduser().parts
+    lowered = {part.lower() for part in parts}
+    if ".git" in lowered or ".ssh" in lowered:
+        return True
+    return Path(path).name.lower() in SENSITIVE_AUTO_APPROVE_NAMES
+
+
+def should_auto_approve_edit(proposal: EditProposal, policy: str, cwd: str | None = None) -> bool:
+    """Return whether an ACP edit proposal may bypass the prompt for this session.
+
+    This is intentionally session-scoped and conservative: sensitive paths still
+    ask even under autonomous policies.
+    """
+
+    policy = str(policy or AUTO_APPROVE_ASK).strip()
+    if policy == AUTO_APPROVE_ASK or _is_sensitive_auto_approve_path(proposal.path):
+        return False
+    path = Path(proposal.path).expanduser().resolve(strict=False)
+    if policy == AUTO_APPROVE_SESSION:
+        return True
+    if policy == AUTO_APPROVE_WORKSPACE:
+        # `/tmp` is the POSIX path but tempfile.gettempdir() is the real one on
+        # every platform: `/private/tmp` on macOS (because `/tmp` is a symlink
+        # and Path.resolve() follows it) and the per-user Temp dir on Windows.
+        tmp_root = Path(tempfile.gettempdir()).resolve(strict=False)
+        try:
+            path.relative_to(tmp_root)
+            return True
+        except ValueError:
+            pass
+        if cwd:
+            root = Path(cwd).expanduser().resolve(strict=False)
+            try:
+                path.relative_to(root)
+                return True
+            except ValueError:
+                return False
+    return False
+
+
+def maybe_require_edit_approval(tool_name: str, arguments: dict[str, Any]) -> str | None:
+    """Run ACP edit approval if bound.
+
+    Returns a JSON tool-error string when the edit must be blocked, otherwise
+    ``None`` so dispatch can continue.  Requester exceptions deny by default.
+    """
+
+    requester = get_edit_approval_requester()
+    if requester is None:
+        return None
+
+    try:
+        proposal = build_edit_proposal(tool_name, arguments)
+    except Exception as exc:
+        logger.warning("Could not build ACP edit approval proposal for %s: %s", tool_name, exc)
+        return json.dumps({"error": f"Edit approval denied: could not prepare diff ({exc})"}, ensure_ascii=False)
+
+    if proposal is None:
+        return None
+
+    try:
+        approved = bool(requester(proposal))
+    except Exception as exc:
+        logger.warning("ACP edit approval requester failed: %s", exc)
+        approved = False
+
+    if approved:
+        return None
+    return json.dumps({"error": "Edit approval denied by ACP client; file was not modified."}, ensure_ascii=False)
+
+
+def build_acp_edit_tool_call(proposal: EditProposal):
+    """Build the ToolCallUpdate payload for ACP request_permission."""
+
+    import acp
+
+    tool_call_id = f"edit-approval-{next(_PERMISSION_REQUEST_IDS)}"
+    return acp.update_tool_call(
+        tool_call_id,
+        title=f"Approve edit: {proposal.path}",
+        kind="edit",
+        status="pending",
+        content=[
+            acp.tool_diff_content(
+                path=proposal.path,
+                old_text=proposal.old_text,
+                new_text=proposal.new_text,
+            )
+        ],
+        raw_input={"tool": proposal.tool_name, "arguments": proposal.arguments},
+    )
+
+
+def make_acp_edit_approval_requester(
+    request_permission_fn: Callable,
+    loop: asyncio.AbstractEventLoop,
+    session_id: str,
+    timeout: float = 60.0,
+    auto_approve_getter: Callable[[], tuple[str, str | None]] | None = None,
+) -> EditApprovalRequester:
+    """Return a sync requester that bridges edit proposals to ACP permissions."""
+
+    def _requester(proposal: EditProposal) -> bool:
+        from acp.schema import PermissionOption
+        from agent.async_utils import safe_schedule_threadsafe
+
+        if auto_approve_getter is not None:
+            try:
+                policy, cwd = auto_approve_getter()
+                if should_auto_approve_edit(proposal, policy, cwd):
+                    logger.info("Auto-approved ACP edit under policy %s: %s", policy, proposal.path)
+                    return True
+            except Exception:
+                logger.debug("ACP edit auto-approval policy check failed", exc_info=True)
+
+        options = [
+            PermissionOption(option_id="allow_once", kind="allow_once", name="Allow edit"),
+            PermissionOption(option_id="deny", kind="reject_once", name="Deny"),
+        ]
+        tool_call = build_acp_edit_tool_call(proposal)
+        coro = request_permission_fn(
+            session_id=session_id,
+            tool_call=tool_call,
+            options=options,
+        )
+        future = safe_schedule_threadsafe(
+            coro,
+            loop,
+            logger=logger,
+            log_message="Edit approval request: failed to schedule on loop",
+        )
+        if future is None:
+            return False
+        try:
+            response = future.result(timeout=timeout)
+        except (FutureTimeout, Exception) as exc:
+            future.cancel()
+            logger.warning("Edit approval request timed out or failed: %s", exc)
+            return False
+        outcome = getattr(response, "outcome", None)
+        return (
+            getattr(outcome, "outcome", None) == "selected"
+            and getattr(outcome, "option_id", None) == "allow_once"
+        )
+
+    return _requester

acp_adapter/entry.py

@@ -0,0 +1,280 @@
+"""CLI entry point for the hermes-agent ACP adapter.
+
+Loads environment variables from ``~/.hermes/.env``, configures logging
+to write to stderr (so stdout is reserved for ACP JSON-RPC transport),
+and starts the ACP agent server.
+
+Usage::
+
+    python -m acp_adapter.entry
+    # or
+    simplicio-agent acp
+    # or
+    hermes-acp
+"""
+
+# IMPORTANT: hermes_bootstrap must be the very first import — UTF-8 stdio
+# on Windows.  No-op on POSIX.  See hermes_bootstrap.py for full rationale.
+try:
+    import hermes_bootstrap  # noqa: F401
+except ModuleNotFoundError:
+    # Graceful fallback when hermes_bootstrap isn't registered in the venv
+    # yet — happens during partial ``simplicio-agent update`` where git-reset landed
+    # new code but ``uv pip install -e .`` didn't finish.  Missing bootstrap
+    # means UTF-8 stdio setup is skipped on Windows; POSIX is unaffected.
+    pass
+else:
+    # Stop a ``utils/``/``proxy/``/``ui/`` package in the launch directory from
+    # shadowing Hermes's own modules — ``simplicio-agent acp`` can be started from any
+    # cwd, including a project that has same-named packages on its path.
+    hermes_bootstrap.harden_import_path()
+
+import argparse
+import asyncio
+import logging
+import sys
+from pathlib import Path
+from hermes_constants import get_hermes_home
+
+
+# Methods clients send as periodic liveness probes. They are not part of the
+# ACP schema, so the acp router correctly returns JSON-RPC -32601 to the
+# caller — but the supervisor task that dispatches the request then surfaces
+# the raised RequestError via ``logging.exception("Background task failed")``,
+# which dumps a traceback to stderr every probe interval. Clients like
+# acp-bridge already treat the -32601 response as "agent alive", so the
+# traceback is pure noise. We keep the protocol response intact and only
+# silence the stderr noise for this specific benign case.
+_BENIGN_PROBE_METHODS = frozenset({"ping", "health", "healthcheck"})
+
+
+class _BenignProbeMethodFilter(logging.Filter):
+    """Suppress acp 'Background task failed' tracebacks caused by unknown
+    liveness-probe methods (e.g. ``ping``) while leaving every other
+    background-task error — including method_not_found for any non-probe
+    method — visible in stderr.
+    """
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        if record.getMessage() != "Background task failed":
+            return True
+        exc_info = record.exc_info
+        if not exc_info:
+            return True
+        exc = exc_info[1]
+        # Imported lazily so this module stays importable when the optional
+        # ``agent-client-protocol`` dependency is not installed.
+        try:
+            from acp.exceptions import RequestError
+        except ImportError:
+            return True
+        if not isinstance(exc, RequestError):
+            return True
+        if getattr(exc, "code", None) != -32601:
+            return True
+        data = getattr(exc, "data", None)
+        method = data.get("method") if isinstance(data, dict) else None
+        return method not in _BENIGN_PROBE_METHODS
+
+
+def _setup_logging() -> None:
+    """Route all logging to stderr so stdout stays clean for ACP stdio."""
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(
+        logging.Formatter(
+            "%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S",
+        )
+    )
+    handler.addFilter(_BenignProbeMethodFilter())
+    root = logging.getLogger()
+    root.handlers.clear()
+    root.addHandler(handler)
+    root.setLevel(logging.INFO)
+
+    # Quiet down noisy libraries
+    logging.getLogger("httpx").setLevel(logging.WARNING)
+    logging.getLogger("httpcore").setLevel(logging.WARNING)
+    logging.getLogger("openai").setLevel(logging.WARNING)
+
+
+def _load_env() -> None:
+    """Load .env from HERMES_HOME (default ``~/.hermes``)."""
+    from hermes_cli.env_loader import load_hermes_dotenv
+
+    hermes_home = get_hermes_home()
+    loaded = load_hermes_dotenv(hermes_home=hermes_home)
+    if loaded:
+        for env_file in loaded:
+            logging.getLogger(__name__).info("Loaded env from %s", env_file)
+    else:
+        logging.getLogger(__name__).info(
+            "No .env found at %s, using system env", hermes_home / ".env"
+        )
+
+
+def _parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="hermes-acp",
+        description="Run Hermes Agent as an ACP stdio server.",
+    )
+    parser.add_argument("--version", action="store_true", help="Print Hermes version and exit")
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Verify ACP dependencies and adapter imports, then exit",
+    )
+    parser.add_argument(
+        "--setup",
+        action="store_true",
+        help="Run interactive Hermes provider/model setup for ACP terminal auth",
+    )
+    parser.add_argument(
+        "--setup-browser",
+        action="store_true",
+        help="Install agent-browser + Playwright Chromium into ~/.hermes/node/ "
+             "for browser tool support. Idempotent.",
+    )
+    parser.add_argument(
+        "--yes",
+        "-y",
+        action="store_true",
+        dest="assume_yes",
+        help="Accept all prompts (currently used by --setup-browser to skip the "
+             "~400 MB Chromium download confirmation).",
+    )
+    return parser.parse_args(argv)
+
+
+def _print_version() -> None:
+    from hermes_cli import __version__ as hermes_version
+
+    print(hermes_version)
+
+
+def _run_check() -> None:
+    import acp  # noqa: F401
+    from acp_adapter.server import HermesACPAgent  # noqa: F401
+
+    print("Hermes ACP check OK")
+
+
+def _run_setup() -> None:
+    from hermes_cli.main import main as hermes_main
+
+    old_argv = sys.argv[:]
+    try:
+        sys.argv = [old_argv[0] if old_argv else "hermes", "model"]
+        hermes_main()
+    finally:
+        sys.argv = old_argv
+
+    # Offer browser-tools install as a follow-up. The terminal auth method
+    # is the one supported first-run UX for registry installs, so this is
+    # the natural moment to ask. Skip silently if stdin isn't a TTY (the
+    # answer can't be collected anyway).
+    if not sys.stdin.isatty():
+        return
+    try:
+        reply = input(
+            "\nInstall browser tools? Downloads agent-browser (npm) and "
+            "optionally Playwright Chromium (~400 MB). [y/N] "
+        ).strip().lower()
+    except (EOFError, KeyboardInterrupt):
+        return
+    if reply in {"y", "yes"}:
+        _run_setup_browser(assume_yes=False)
+
+
+def _run_setup_browser(assume_yes: bool = False) -> int:
+    """Bootstrap agent-browser + Chromium.
+
+    Routes through dep_ensure -> install.{sh,ps1} --ensure, sharing code
+    with ``hermes postinstall`` and the runtime lazy installer.
+
+    Returns 0 on success, 1 on failure.
+    """
+    from hermes_cli.dep_ensure import ensure_dependency
+
+    try:
+        node_ok = ensure_dependency("node", interactive=not assume_yes)
+        if not node_ok:
+            print("Node.js installation failed — cannot proceed with browser tools.",
+                  file=sys.stderr)
+            return 1
+
+        browser_ok = ensure_dependency("browser", interactive=not assume_yes)
+        if not browser_ok:
+            print("Browser tools installation failed.", file=sys.stderr)
+            return 1
+
+        return 0
+    except OSError as exc:
+        print(f"Browser bootstrap failed: {exc}", file=sys.stderr)
+        return 1
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Entry point: load env, configure logging, run the ACP agent."""
+    args = _parse_args(argv)
+    if args.version:
+        _print_version()
+        return
+    if args.check:
+        _run_check()
+        return
+    if args.setup:
+        _run_setup()
+        return
+    if args.setup_browser:
+        rc = _run_setup_browser(assume_yes=args.assume_yes)
+        if rc != 0:
+            sys.exit(rc)
+        return
+
+    _setup_logging()
+    _load_env()
+
+    logger = logging.getLogger(__name__)
+    logger.info("Starting hermes-agent ACP adapter")
+
+    # Ensure the project root is on sys.path so ``from run_agent import AIAgent`` works
+    project_root = str(Path(__file__).resolve().parent.parent)
+    if project_root not in sys.path:
+        sys.path.insert(0, project_root)
+
+    import acp
+    from .server import HermesACPAgent
+
+    # MCP tool discovery from config.yaml — run before asyncio.run() so
+    # it's safe to use blocking waits.  (ACP also registers per-session
+    # MCP servers dynamically via asyncio.to_thread inside the event
+    # loop; that path is unaffected.)  Moved from model_tools.py module
+    # scope to avoid freezing the gateway's loop on lazy import (#16856).
+    try:
+        from tools.mcp_tool import discover_mcp_tools
+        discover_mcp_tools()
+    except Exception:
+        logger.debug("MCP tool discovery failed at ACP startup", exc_info=True)
+
+    agent = HermesACPAgent()
+    # Install the faster uvloop event-loop policy when available (no-op on
+    # Windows or when the optional dep isn't installed). Must run before the
+    # loop is created by asyncio.run(). See agent/uvloop_utils.py.
+    try:
+        from agent.uvloop_utils import install_uvloop_policy
+
+        install_uvloop_policy()
+    except Exception:
+        pass
+    try:
+        asyncio.run(acp.run_agent(agent, use_unstable_protocol=True))
+    except KeyboardInterrupt:
+        logger.info("Shutting down (KeyboardInterrupt)")
+    except Exception:
+        logger.exception("ACP agent crashed")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()