Hermes-agent

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,286 @@
+"""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 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 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" and arguments.get("mode", "replace") == "replace":
+        return _proposal_for_patch_replace(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,266 @@
+"""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
+    hermes 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 ``hermes 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
+
+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()
+    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()

acp_adapter/events.py

@@ -0,0 +1,279 @@
+"""Callback factories for bridging AIAgent events to ACP notifications.
+
+Each factory returns a callable with the signature that AIAgent expects
+for its callbacks. Internally, the callbacks push ACP session updates
+to the client via ``conn.session_update()`` using
+``asyncio.run_coroutine_threadsafe()`` (since AIAgent runs in a worker
+thread while the event loop lives on the main thread).
+"""
+
+import asyncio
+import json
+import logging
+from collections import deque
+from typing import Any, Callable, Deque, Dict
+
+import acp
+from acp.schema import AgentPlanUpdate, PlanEntry
+
+from .tools import (
+    build_tool_complete,
+    build_tool_start,
+    make_tool_call_id,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _json_loads_maybe_prefix(value: str) -> Any:
+    """Parse a JSON object even when Hermes appended a human hint after it."""
+    text = value.strip()
+    try:
+        return json.loads(text)
+    except Exception:
+        decoder = json.JSONDecoder()
+        data, _ = decoder.raw_decode(text)
+        return data
+
+
+def _build_plan_update_from_todo_result(result: Any) -> AgentPlanUpdate | None:
+    """Translate Hermes' todo tool result into ACP's native plan update.
+
+    Zed renders ``sessionUpdate: plan`` as its first-class task/todo panel. The
+    Hermes agent already maintains task state through the ``todo`` tool, so the
+    ACP adapter should expose that state natively instead of only as a generic
+    tool-call transcript block.
+    """
+    if not isinstance(result, str) or not result.strip():
+        return None
+
+    try:
+        data = _json_loads_maybe_prefix(result)
+    except Exception:
+        return None
+
+    if not isinstance(data, dict) or not isinstance(data.get("todos"), list):
+        return None
+
+    todos = data["todos"]
+    if not todos:
+        return AgentPlanUpdate(session_update="plan", entries=[])
+
+    status_map = {
+        "pending": "pending",
+        "in_progress": "in_progress",
+        "completed": "completed",
+        # ACP plans only support pending/in_progress/completed. Preserve
+        # cancelled tasks as terminal entries instead of dropping them and
+        # making the client's full-list replacement lose visible context.
+        "cancelled": "completed",
+    }
+    entries: list[PlanEntry] = []
+    for item in todos:
+        if not isinstance(item, dict):
+            continue
+        content = str(item.get("content") or item.get("id") or "").strip()
+        if not content:
+            continue
+        raw_status = str(item.get("status") or "pending").strip()
+        status = status_map.get(raw_status, "pending")
+        if raw_status == "cancelled":
+            content = f"[cancelled] {content}"
+        entries.append(PlanEntry(content=content, priority="medium", status=status))
+
+    return AgentPlanUpdate(session_update="plan", entries=entries)
+
+
+def _send_update(
+    conn: acp.Client,
+    session_id: str,
+    loop: asyncio.AbstractEventLoop,
+    update: Any,
+) -> None:
+    """Fire-and-forget an ACP session update from a worker thread."""
+    from agent.async_utils import safe_schedule_threadsafe
+
+    future = safe_schedule_threadsafe(
+        conn.session_update(session_id, update),
+        loop,
+        logger=logger,
+        log_message="Failed to send ACP update",
+    )
+    if future is None:
+        return
+    try:
+        future.result(timeout=5)
+    except Exception:
+        logger.debug("Failed to send ACP update", exc_info=True)
+
+
+# ------------------------------------------------------------------
+# Tool progress callback
+# ------------------------------------------------------------------
+
+def make_tool_progress_cb(
+    conn: acp.Client,
+    session_id: str,
+    loop: asyncio.AbstractEventLoop,
+    tool_call_ids: Dict[str, Deque[str]],
+    tool_call_meta: Dict[str, Dict[str, Any]],
+    edit_approval_policy_getter: Callable[[], tuple[str, str | None]] | None = None,
+) -> Callable:
+    """Create a ``tool_progress_callback`` for AIAgent.
+
+    Signature expected by AIAgent::
+
+        tool_progress_callback(event_type: str, name: str, preview: str, args: dict, **kwargs)
+
+    Emits ``ToolCallStart`` for ``tool.started`` events and tracks IDs in a FIFO
+    queue per tool name so duplicate/parallel same-name calls still complete
+    against the correct ACP tool call.  Other event types (``tool.completed``,
+    ``reasoning.available``) are silently ignored.
+    """
+
+    def _tool_progress(event_type: str, name: str = None, preview: str = None, args: Any = None, **kwargs) -> None:
+        # Only emit ACP ToolCallStart for tool.started; ignore other event types
+        if event_type != "tool.started":
+            return
+        if isinstance(args, str):
+            try:
+                args = json.loads(args)
+            except (json.JSONDecodeError, TypeError):
+                args = {"raw": args}
+        if not isinstance(args, dict):
+            args = {}
+
+        tc_id = make_tool_call_id()
+        queue = tool_call_ids.get(name)
+        if queue is None:
+            queue = deque()
+            tool_call_ids[name] = queue
+        elif isinstance(queue, str):
+            queue = deque([queue])
+            tool_call_ids[name] = queue
+        queue.append(tc_id)
+
+        snapshot = None
+        if name in {"write_file", "patch", "skill_manage"}:
+            try:
+                from agent.display import capture_local_edit_snapshot
+
+                snapshot = capture_local_edit_snapshot(name, args)
+            except Exception:
+                logger.debug("Failed to capture ACP edit snapshot for %s", name, exc_info=True)
+        tool_call_meta[tc_id] = {"args": args, "snapshot": snapshot}
+
+        edit_diff = None
+        if name in {"write_file", "patch"} and edit_approval_policy_getter is not None:
+            try:
+                from acp_adapter.edit_approval import build_edit_proposal, should_auto_approve_edit
+
+                proposal = build_edit_proposal(name, args)
+                if proposal is not None:
+                    policy, cwd = edit_approval_policy_getter()
+                    if should_auto_approve_edit(proposal, policy, cwd):
+                        edit_diff = proposal
+            except Exception:
+                logger.debug("Failed to prepare auto-approved ACP edit diff for %s", name, exc_info=True)
+
+        update = build_tool_start(tc_id, name, args, edit_diff=edit_diff)
+        _send_update(conn, session_id, loop, update)
+
+    return _tool_progress
+
+
+# ------------------------------------------------------------------
+# Thinking callback
+# ------------------------------------------------------------------
+
+def make_thinking_cb(
+    conn: acp.Client,
+    session_id: str,
+    loop: asyncio.AbstractEventLoop,
+) -> Callable:
+    """Create a ``thinking_callback`` for AIAgent."""
+
+    def _thinking(text: str) -> None:
+        if not text:
+            return
+        update = acp.update_agent_thought_text(text)
+        _send_update(conn, session_id, loop, update)
+
+    return _thinking
+
+
+# ------------------------------------------------------------------
+# Step callback
+# ------------------------------------------------------------------
+
+def make_step_cb(
+    conn: acp.Client,
+    session_id: str,
+    loop: asyncio.AbstractEventLoop,
+    tool_call_ids: Dict[str, Deque[str]],
+    tool_call_meta: Dict[str, Dict[str, Any]],
+) -> Callable:
+    """Create a ``step_callback`` for AIAgent.
+
+    Signature expected by AIAgent::
+
+        step_callback(api_call_count: int, prev_tools: list)
+    """
+
+    def _step(api_call_count: int, prev_tools: Any = None) -> None:
+        if prev_tools and isinstance(prev_tools, list):
+            for tool_info in prev_tools:
+                tool_name = None
+                result = None
+                function_args = None
+
+                if isinstance(tool_info, dict):
+                    tool_name = tool_info.get("name") or tool_info.get("function_name")
+                    result = tool_info.get("result") or tool_info.get("output")
+                    function_args = tool_info.get("arguments") or tool_info.get("args")
+                elif isinstance(tool_info, str):
+                    tool_name = tool_info
+
+                queue = tool_call_ids.get(tool_name or "")
+                if isinstance(queue, str):
+                    queue = deque([queue])
+                    tool_call_ids[tool_name] = queue
+                if tool_name and queue:
+                    tc_id = queue.popleft()
+                    meta = tool_call_meta.pop(tc_id, {})
+                    update = build_tool_complete(
+                        tc_id,
+                        tool_name,
+                        result=str(result) if result is not None else None,
+                        function_args=function_args or meta.get("args"),
+                        snapshot=meta.get("snapshot"),
+                    )
+                    _send_update(conn, session_id, loop, update)
+                    if tool_name == "todo":
+                        plan_update = _build_plan_update_from_todo_result(result)
+                        if plan_update is not None:
+                            _send_update(conn, session_id, loop, plan_update)
+                    if not queue:
+                        tool_call_ids.pop(tool_name, None)
+
+    return _step
+
+
+# ------------------------------------------------------------------
+# Agent message callback
+# ------------------------------------------------------------------
+
+def make_message_cb(
+    conn: acp.Client,
+    session_id: str,
+    loop: asyncio.AbstractEventLoop,
+) -> Callable:
+    """Create a callback that streams agent response text to the editor."""
+
+    def _message(text: str) -> None:
+        if not text:
+            return
+        update = acp.update_agent_message_text(text)
+        _send_update(conn, session_id, loop, update)
+
+    return _message

acp_adapter/permissions.py

@@ -0,0 +1,168 @@
+"""ACP permission bridging for Hermes dangerous-command approvals."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from concurrent.futures import TimeoutError as FutureTimeout
+from itertools import count
+from typing import Callable
+
+from acp.schema import (
+    AllowedOutcome,
+    PermissionOption,
+)
+
+logger = logging.getLogger(__name__)
+
+# Maps ACP permission option ids to Hermes approval result strings.
+# Option ids are stable across both the ``allow_permanent=True`` and
+# ``allow_permanent=False`` paths even though the option list differs.
+_OPTION_ID_TO_HERMES = {
+    "allow_once": "once",
+    "allow_session": "session",
+    "allow_always": "always",
+    "deny": "deny",
+    "deny_always": "deny",
+}
+
+_PERMISSION_REQUEST_IDS = count(1)
+
+
+def _permission_option_supports_kind(kind: str) -> bool:
+    """Return whether the installed ACP SDK accepts a permission option kind."""
+    try:
+        PermissionOption(option_id="__probe__", kind=kind, name="probe")
+    except Exception:
+        return False
+    return True
+
+
+def _build_permission_options(*, allow_permanent: bool) -> list[PermissionOption]:
+    """Return ACP options that match Hermes approval semantics."""
+    options = [
+        PermissionOption(option_id="allow_once", kind="allow_once", name="Allow once"),
+        PermissionOption(
+            option_id="allow_session",
+            # ACP has no session-scoped kind, so use the closest persistent
+            # hint while keeping Hermes semantics in the option id.
+            kind="allow_always",
+            name="Allow for session",
+        ),
+    ]
+    if allow_permanent:
+        options.append(
+            PermissionOption(
+                option_id="allow_always",
+                kind="allow_always",
+                name="Allow always",
+            ),
+        )
+    options.append(PermissionOption(option_id="deny", kind="reject_once", name="Deny"))
+    if _permission_option_supports_kind("reject_always"):
+        options.append(
+            PermissionOption(
+                option_id="deny_always",
+                kind="reject_always",
+                name="Deny always",
+            ),
+        )
+    return options
+
+
+def _build_permission_tool_call(command: str, description: str):
+    """Return the ACP tool-call update attached to a permission request.
+
+    ``request_permission`` expects a ``ToolCallUpdate`` payload — produced
+    by ``_acp.update_tool_call`` — not a ``ToolCallStart``. Each request
+    gets a unique ``perm-check-N`` id so concurrent requests don't collide.
+    """
+    import acp as _acp
+
+    tool_call_id = f"perm-check-{next(_PERMISSION_REQUEST_IDS)}"
+    title = f"{description}: {command}" if description else command
+    content_text = f"{description}\n$ {command}" if description else f"$ {command}"
+    return _acp.update_tool_call(
+        tool_call_id,
+        title=title,
+        kind="execute",
+        status="pending",
+        content=[_acp.tool_content(_acp.text_block(content_text))],
+        raw_input={"command": command, "description": description},
+    )
+
+
+def _map_outcome_to_hermes(outcome: object, *, allowed_option_ids: set[str]) -> str:
+    """Map an ACP permission outcome into Hermes approval strings."""
+    if not isinstance(outcome, AllowedOutcome):
+        return "deny"
+
+    option_id = outcome.option_id
+    if option_id not in allowed_option_ids:
+        logger.warning("Permission request returned unknown option_id: %s", option_id)
+        return "deny"
+    return _OPTION_ID_TO_HERMES.get(option_id, "deny")
+
+
+def make_approval_callback(
+    request_permission_fn: Callable,
+    loop: asyncio.AbstractEventLoop,
+    session_id: str,
+    timeout: float = 60.0,
+) -> Callable[..., str]:
+    """
+    Return a Hermes-compatible approval callback that bridges to ACP.
+
+    The callback accepts ``command`` and ``description`` plus optional
+    keyword arguments such as ``allow_permanent`` used by
+    ``tools.approval.prompt_dangerous_approval()``.
+
+    Args:
+        request_permission_fn: The ACP connection's ``request_permission`` coroutine.
+        loop: The event loop on which the ACP connection lives.
+        session_id: Current ACP session id.
+        timeout: Seconds to wait for a response before auto-denying.
+    """
+
+    def _callback(
+        command: str,
+        description: str,
+        *,
+        allow_permanent: bool = True,
+        **_: object,
+    ) -> str:
+        from agent.async_utils import safe_schedule_threadsafe
+
+        options = _build_permission_options(allow_permanent=allow_permanent)
+
+        tool_call = _build_permission_tool_call(command, description)
+        coro = request_permission_fn(
+            session_id=session_id,
+            tool_call=tool_call,
+            options=options,
+        )
+        future = safe_schedule_threadsafe(
+            coro, loop,
+            logger=logger,
+            log_message="Permission request: failed to schedule on loop",
+        )
+        if future is None:
+            return "deny"
+
+        try:
+            response = future.result(timeout=timeout)
+        except (FutureTimeout, Exception) as exc:
+            future.cancel()
+            logger.warning("Permission request timed out or failed: %s", exc)
+            return "deny"
+
+        if response is None:
+            return "deny"
+
+        allowed_option_ids = {option.option_id for option in options}
+        return _map_outcome_to_hermes(
+            response.outcome,
+            allowed_option_ids=allowed_option_ids,
+        )
+
+    return _callback

acp_adapter/provenance.py

@@ -0,0 +1,127 @@
+"""Derive ACP session-provenance metadata from the existing compression chain.
+
+This is an additive Hermes extension surfaced under ACP ``_meta.hermes`` so
+existing ACP clients ignore it. It carries no new persisted state: everything
+is derived on demand from the ``sessions`` table (``parent_session_id`` /
+``end_reason``), which already models compression-continuation chains.
+
+The ACP/editor ``session_id`` stays the stable public handle. When context
+compression rotates the internal Hermes head, ``build_session_provenance`` lets
+a client see the previous/current internal ids and the lineage root without
+parsing status text, guessing from token drops, or reading ``state.db``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+# Bound defensive walks; compression chains this deep are pathological.
+_MAX_WALK = 100
+
+
+def build_session_provenance(
+    db: Any,
+    acp_session_id: str,
+    current_hermes_session_id: str,
+    *,
+    previous_hermes_session_id: Optional[str] = None,
+) -> Optional[Dict[str, Any]]:
+    """Build ``_meta.hermes.sessionProvenance`` for an ACP session.
+
+    Args:
+        db: A ``SessionDB`` (must expose ``get_session``).
+        acp_session_id: The stable ACP/editor-facing session handle.
+        current_hermes_session_id: The live internal Hermes DB session id
+            (``state.agent.session_id``).
+        previous_hermes_session_id: The internal id from before the most recent
+            turn, when known. Supplied by ``prompt()`` to flag a rotation.
+
+    Returns:
+        A dict suitable for ``{"hermes": {"sessionProvenance": <dict>}}`` under
+        ACP ``_meta``, or ``None`` if the session can't be read.
+    """
+    try:
+        row = db.get_session(current_hermes_session_id)
+    except Exception:
+        return None
+    if not row:
+        return None
+
+    parent_id = row.get("parent_session_id")
+    end_reason = row.get("end_reason")
+
+    # Walk parents to the lineage root and count compression depth. Only
+    # compression-split parents (parent.end_reason == 'compression') count
+    # toward depth — delegate/branch children share the parent_session_id
+    # column but are not compaction boundaries.
+    root_id = current_hermes_session_id
+    compression_depth = 0
+    cursor_parent = parent_id
+    seen = {current_hermes_session_id}
+    for _ in range(_MAX_WALK):
+        if not cursor_parent or cursor_parent in seen:
+            break
+        seen.add(cursor_parent)
+        try:
+            prow = db.get_session(cursor_parent)
+        except Exception:
+            prow = None
+        if not prow:
+            break
+        root_id = cursor_parent
+        if prow.get("end_reason") == "compression":
+            compression_depth += 1
+        cursor_parent = prow.get("parent_session_id")
+
+    # A session is a compression continuation when its parent was ended with
+    # end_reason='compression'. Determine that from the immediate parent.
+    is_continuation = False
+    if parent_id:
+        try:
+            immediate_parent = db.get_session(parent_id)
+        except Exception:
+            immediate_parent = None
+        if immediate_parent and immediate_parent.get("end_reason") == "compression":
+            is_continuation = True
+
+    rotated = bool(
+        previous_hermes_session_id
+        and previous_hermes_session_id != current_hermes_session_id
+    )
+
+    provenance: Dict[str, Any] = {
+        "acpSessionId": acp_session_id,
+        "currentHermesSessionId": current_hermes_session_id,
+        "rootHermesSessionId": root_id,
+        "parentHermesSessionId": parent_id,
+        "sessionKind": "continuation" if is_continuation else "root",
+        "compressionDepth": compression_depth,
+    }
+    if previous_hermes_session_id:
+        provenance["previousHermesSessionId"] = previous_hermes_session_id
+    if rotated:
+        # The head moved during the last turn. The only mechanism that rotates
+        # the internal id mid-turn is compression-driven session splitting.
+        provenance["reason"] = "compression"
+        provenance["creatorKind"] = "compression"
+
+    return provenance
+
+
+def session_provenance_meta(
+    db: Any,
+    acp_session_id: str,
+    current_hermes_session_id: str,
+    *,
+    previous_hermes_session_id: Optional[str] = None,
+) -> Optional[Dict[str, Any]]:
+    """Return a ready ``_meta`` payload: ``{"hermes": {"sessionProvenance": ...}}``."""
+    prov = build_session_provenance(
+        db,
+        acp_session_id,
+        current_hermes_session_id,
+        previous_hermes_session_id=previous_hermes_session_id,
+    )
+    if prov is None:
+        return None
+    return {"hermes": {"sessionProvenance": prov}}

acp_adapter/session.py

@@ -0,0 +1,623 @@
+"""ACP session manager — maps ACP sessions to Hermes AIAgent instances.
+
+Sessions are persisted to the shared SessionDB (``~/.hermes/state.db``) so they
+survive process restarts and appear in ``session_search``.  When the editor
+reconnects after idle/restart, the ``load_session`` / ``resume_session`` calls
+find the persisted session in the database and restore the full conversation
+history.
+"""
+from __future__ import annotations
+
+from hermes_constants import get_hermes_home
+
+import copy
+import json
+import logging
+import os
+import re
+import sys
+import time
+import uuid
+from datetime import datetime, timezone
+from dataclasses import dataclass, field
+from threading import Lock
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+def _win_path_to_wsl(path: str) -> str | None:
+    """Convert a Windows drive path to its WSL /mnt/<drive>/... equivalent."""
+    match = re.match(r"^([A-Za-z]):[\\/](.*)$", path)
+    if not match:
+        return None
+    drive = match.group(1).lower()
+    tail = match.group(2).replace("\\", "/")
+    return f"/mnt/{drive}/{tail}"
+
+
+def _translate_acp_cwd(cwd: str) -> str:
+    """Translate Windows ACP cwd values when Hermes itself is running in WSL.
+
+    Windows ACP clients can launch ``hermes acp`` inside WSL while still sending
+    editor workspaces as Windows drive paths such as ``E:\\Projects``. Store
+    and execute against the WSL mount path so agents, tools, and persisted ACP
+    sessions all agree on the usable workspace. Native Linux/macOS keeps the
+    original cwd unchanged.
+    """
+    from hermes_constants import is_wsl
+
+    if not is_wsl():
+        return cwd
+    translated = _win_path_to_wsl(str(cwd))
+    return translated if translated is not None else cwd
+
+
+def _normalize_cwd_for_compare(cwd: str | None) -> str:
+    raw = str(cwd or ".").strip()
+    if not raw:
+        raw = "."
+    expanded = os.path.expanduser(raw)
+
+    # Normalize Windows drive paths into the equivalent WSL mount form so
+    # ACP history filters match the same workspace across Windows and WSL.
+    translated = _win_path_to_wsl(expanded)
+    if translated is not None:
+        expanded = translated
+    elif re.match(r"^/mnt/[A-Za-z]/", expanded):
+        expanded = f"/mnt/{expanded[5].lower()}/{expanded[7:]}"
+
+    return os.path.normpath(expanded)
+
+
+def _build_session_title(title: Any, preview: Any, cwd: str | None) -> str:
+    explicit = str(title or "").strip()
+    if explicit:
+        return explicit
+    preview_text = str(preview or "").strip()
+    if preview_text:
+        return preview_text
+    leaf = os.path.basename(str(cwd or "").rstrip("/\\"))
+    return leaf or "New thread"
+
+
+def _format_updated_at(value: Any) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, str) and value.strip():
+        return value
+    try:
+        return datetime.fromtimestamp(float(value), tz=timezone.utc).isoformat()
+    except Exception:
+        return None
+
+
+def _updated_at_sort_key(value: Any) -> float:
+    if value is None:
+        return float("-inf")
+    if isinstance(value, (int, float)):
+        return float(value)
+    raw = str(value).strip()
+    if not raw:
+        return float("-inf")
+    try:
+        return datetime.fromisoformat(raw.replace("Z", "+00:00")).timestamp()
+    except Exception:
+        try:
+            return float(raw)
+        except Exception:
+            return float("-inf")
+
+
+def _acp_stderr_print(*args, **kwargs) -> None:
+    """Best-effort human-readable output sink for ACP stdio sessions.
+
+    ACP reserves stdout for JSON-RPC frames, so any incidental CLI/status output
+    from AIAgent must be redirected away from stdout. Route it to stderr instead.
+    """
+    kwargs = dict(kwargs)
+    kwargs.setdefault("file", sys.stderr)
+    print(*args, **kwargs)
+
+
+def _register_task_cwd(task_id: str, cwd: str) -> None:
+    """Bind a task/session id to the editor's working directory for tools.
+
+    Zed can launch Hermes from a Windows workspace while the ACP process runs
+    inside WSL. In that case ACP sends cwd as e.g. ``E:\\Projects\\POTI``;
+    local tools need the WSL mount equivalent or subprocess creation fails
+    before the command can run.
+    """
+    if not task_id:
+        return
+    try:
+        from tools.terminal_tool import register_task_env_overrides
+        register_task_env_overrides(task_id, {"cwd": _translate_acp_cwd(cwd)})
+    except Exception:
+        logger.debug("Failed to register ACP task cwd override", exc_info=True)
+
+
+def _expand_acp_enabled_toolsets(
+    toolsets: List[str] | None = None,
+    mcp_server_names: List[str] | None = None,
+) -> List[str]:
+    """Return ACP toolsets plus explicit MCP server toolsets for this session."""
+    expanded: List[str] = []
+    for name in list(toolsets or ["hermes-acp"]):
+        if name and name not in expanded:
+            expanded.append(name)
+
+    for server_name in list(mcp_server_names or []):
+        toolset_name = f"mcp-{server_name}"
+        if server_name and toolset_name not in expanded:
+            expanded.append(toolset_name)
+
+    return expanded
+
+
+def _clear_task_cwd(task_id: str) -> None:
+    """Remove task-specific cwd overrides for an ACP session."""
+    if not task_id:
+        return
+    try:
+        from tools.terminal_tool import clear_task_env_overrides
+        clear_task_env_overrides(task_id)
+    except Exception:
+        logger.debug("Failed to clear ACP task cwd override", exc_info=True)
+
+
+@dataclass
+class SessionState:
+    """Tracks per-session state for an ACP-managed Hermes agent."""
+
+    session_id: str
+    agent: Any  # AIAgent instance
+    cwd: str = "."
+    model: str = ""
+    history: List[Dict[str, Any]] = field(default_factory=list)
+    cancel_event: Any = None  # threading.Event
+    is_running: bool = False
+    queued_prompts: List[str] = field(default_factory=list)
+    runtime_lock: Any = field(default_factory=Lock)
+    current_prompt_text: str = ""
+    interrupted_prompt_text: str = ""
+
+
+class SessionManager:
+    """Thread-safe manager for ACP sessions backed by Hermes AIAgent instances.
+
+    Sessions are held in-memory for fast access **and** persisted to the
+    shared SessionDB so they survive process restarts and are searchable
+    via ``session_search``.
+    """
+
+    def __init__(self, agent_factory=None, db=None):
+        """
+        Args:
+            agent_factory: Optional callable that creates an AIAgent-like object.
+                           Used by tests. When omitted, a real AIAgent is created
+                           using the current Hermes runtime provider configuration.
+            db:            Optional SessionDB instance. When omitted, the default
+                           SessionDB (``~/.hermes/state.db``) is lazily created.
+        """
+        self._sessions: Dict[str, SessionState] = {}
+        self._lock = Lock()
+        self._agent_factory = agent_factory
+        self._db_instance = db  # None → lazy-init on first use
+
+    # ---- public API ---------------------------------------------------------
+
+    def create_session(self, cwd: str = ".") -> SessionState:
+        """Create a new session with a unique ID and a fresh AIAgent."""
+        import threading
+
+        cwd = _translate_acp_cwd(cwd)
+        session_id = str(uuid.uuid4())
+        agent = self._make_agent(session_id=session_id, cwd=cwd)
+        state = SessionState(
+            session_id=session_id,
+            agent=agent,
+            cwd=cwd,
+            model=getattr(agent, "model", "") or "",
+            cancel_event=threading.Event(),
+        )
+        with self._lock:
+            self._sessions[session_id] = state
+        _register_task_cwd(session_id, cwd)
+        self._persist(state)
+        logger.info("Created ACP session %s (cwd=%s)", session_id, cwd)
+        return state
+
+    def get_session(self, session_id: str) -> Optional[SessionState]:
+        """Return the session for *session_id*, or ``None``.
+
+        If the session is not in memory but exists in the database (e.g. after
+        a process restart), it is transparently restored.
+        """
+        with self._lock:
+            state = self._sessions.get(session_id)
+        if state is not None:
+            return state
+        # Attempt to restore from database.
+        return self._restore(session_id)
+
+    def remove_session(self, session_id: str) -> bool:
+        """Remove a session from memory and database. Returns True if it existed."""
+        with self._lock:
+            existed = self._sessions.pop(session_id, None) is not None
+        db_existed = self._delete_persisted(session_id)
+        if existed or db_existed:
+            _clear_task_cwd(session_id)
+        return existed or db_existed
+
+    def fork_session(self, session_id: str, cwd: str = ".") -> Optional[SessionState]:
+        """Deep-copy a session's history into a new session."""
+        import threading
+
+        cwd = _translate_acp_cwd(cwd)
+        original = self.get_session(session_id)  # checks DB too
+        if original is None:
+            return None
+
+        new_id = str(uuid.uuid4())
+        agent = self._make_agent(
+            session_id=new_id,
+            cwd=cwd,
+            model=original.model or None,
+        )
+        state = SessionState(
+            session_id=new_id,
+            agent=agent,
+            cwd=cwd,
+            model=getattr(agent, "model", original.model) or original.model,
+            history=copy.deepcopy(original.history),
+            cancel_event=threading.Event(),
+        )
+        with self._lock:
+            self._sessions[new_id] = state
+        _register_task_cwd(new_id, cwd)
+        self._persist(state)
+        logger.info("Forked ACP session %s -> %s", session_id, new_id)
+        return state
+
+    def list_sessions(self, cwd: str | None = None) -> List[Dict[str, Any]]:
+        """Return lightweight info dicts for all sessions (memory + database)."""
+        normalized_cwd = _normalize_cwd_for_compare(cwd) if cwd else None
+        db = self._get_db()
+        persisted_rows: dict[str, dict[str, Any]] = {}
+
+        if db is not None:
+            try:
+                for row in db.list_sessions_rich(source="acp", limit=1000):
+                    persisted_rows[str(row["id"])] = dict(row)
+            except Exception:
+                logger.debug("Failed to load ACP sessions from DB", exc_info=True)
+
+        # Collect in-memory sessions first.
+        with self._lock:
+            seen_ids = set(self._sessions.keys())
+            results = []
+            for s in self._sessions.values():
+                history_len = len(s.history)
+                if history_len <= 0:
+                    continue
+                if normalized_cwd and _normalize_cwd_for_compare(s.cwd) != normalized_cwd:
+                    continue
+                persisted = persisted_rows.get(s.session_id, {})
+                preview = next(
+                    (
+                        str(msg.get("content") or "").strip()
+                        for msg in s.history
+                        if msg.get("role") == "user" and str(msg.get("content") or "").strip()
+                    ),
+                    persisted.get("preview") or "",
+                )
+                results.append(
+                    {
+                        "session_id": s.session_id,
+                        "cwd": s.cwd,
+                        "model": s.model,
+                        "history_len": history_len,
+                        "title": _build_session_title(persisted.get("title"), preview, s.cwd),
+                        "updated_at": _format_updated_at(
+                            persisted.get("last_active") or persisted.get("started_at") or time.time()
+                        ),
+                    }
+                )
+
+        # Merge any persisted sessions not currently in memory.
+        for sid, row in persisted_rows.items():
+            if sid in seen_ids:
+                continue
+            message_count = int(row.get("message_count") or 0)
+            if message_count <= 0:
+                continue
+            # Extract cwd from model_config JSON.
+            session_cwd = "."
+            mc = row.get("model_config")
+            if mc:
+                try:
+                    session_cwd = json.loads(mc).get("cwd", ".")
+                except (json.JSONDecodeError, TypeError):
+                    pass
+            if normalized_cwd and _normalize_cwd_for_compare(session_cwd) != normalized_cwd:
+                continue
+            results.append({
+                "session_id": sid,
+                "cwd": session_cwd,
+                "model": row.get("model") or "",
+                "history_len": message_count,
+                "title": _build_session_title(row.get("title"), row.get("preview"), session_cwd),
+                "updated_at": _format_updated_at(row.get("last_active") or row.get("started_at")),
+            })
+
+        results.sort(key=lambda item: _updated_at_sort_key(item.get("updated_at")), reverse=True)
+        return results
+
+    def update_cwd(self, session_id: str, cwd: str) -> Optional[SessionState]:
+        """Update the working directory for a session and its tool overrides."""
+        cwd = _translate_acp_cwd(cwd)
+        state = self.get_session(session_id)  # checks DB too
+        if state is None:
+            return None
+        state.cwd = cwd
+        _register_task_cwd(session_id, cwd)
+        self._persist(state)
+        return state
+
+    def cleanup(self) -> None:
+        """Remove all sessions (memory and database) and clear task-specific cwd overrides."""
+        with self._lock:
+            session_ids = list(self._sessions.keys())
+            self._sessions.clear()
+        for session_id in session_ids:
+            _clear_task_cwd(session_id)
+            self._delete_persisted(session_id)
+        # Also remove any DB-only ACP sessions not currently in memory.
+        db = self._get_db()
+        if db is not None:
+            try:
+                rows = db.search_sessions(source="acp", limit=10000)
+                for row in rows:
+                    sid = row["id"]
+                    _clear_task_cwd(sid)
+                    db.delete_session(sid)
+            except Exception:
+                logger.debug("Failed to cleanup ACP sessions from DB", exc_info=True)
+
+    def save_session(self, session_id: str) -> None:
+        """Persist the current state of a session to the database.
+
+        Called by the server after prompt completion, slash commands that
+        mutate history, and model switches.
+        """
+        with self._lock:
+            state = self._sessions.get(session_id)
+        if state is not None:
+            self._persist(state)
+
+    # ---- persistence via SessionDB ------------------------------------------
+
+    def _get_db(self):
+        """Lazily initialise and return the SessionDB instance.
+
+        Returns ``None`` if the DB is unavailable (e.g. import error in a
+        minimal test environment).
+
+        Note: we resolve ``HERMES_HOME`` dynamically rather than relying on
+        the module-level ``DEFAULT_DB_PATH`` constant, because that constant
+        is evaluated at import time and won't reflect env-var changes made
+        later (e.g. by the test fixture ``_isolate_hermes_home``).
+        """
+        if self._db_instance is not None:
+            return self._db_instance
+        try:
+            from hermes_state import SessionDB
+            hermes_home = get_hermes_home()
+            self._db_instance = SessionDB(db_path=hermes_home / "state.db")
+            return self._db_instance
+        except Exception:
+            logger.debug("SessionDB unavailable for ACP persistence", exc_info=True)
+            return None
+
+    def _persist(self, state: SessionState) -> None:
+        """Write session state to the database.
+
+        Creates the session record if it doesn't exist, then replaces all
+        stored messages with the current in-memory history.
+        """
+        db = self._get_db()
+        if db is None:
+            return
+
+        # Ensure model is a plain string (not a MagicMock or other proxy).
+        model_str = str(state.model) if state.model else None
+        session_meta = {"cwd": state.cwd}
+        provider = getattr(state.agent, "provider", None)
+        base_url = getattr(state.agent, "base_url", None)
+        api_mode = getattr(state.agent, "api_mode", None)
+        if isinstance(provider, str) and provider.strip():
+            session_meta["provider"] = provider.strip()
+        if isinstance(base_url, str) and base_url.strip():
+            session_meta["base_url"] = base_url.strip()
+        if isinstance(api_mode, str) and api_mode.strip():
+            session_meta["api_mode"] = api_mode.strip()
+        cwd_json = json.dumps(session_meta)
+
+        try:
+            # Ensure the session record exists.
+            existing = db.get_session(state.session_id)
+            if existing is None:
+                db.create_session(
+                    session_id=state.session_id,
+                    source="acp",
+                    model=model_str,
+                    model_config={"cwd": state.cwd},
+                )
+            else:
+                # Update model_config (contains cwd) if changed.
+                try:
+                    db.update_session_meta(state.session_id, cwd_json, model_str)
+                except Exception:
+                    logger.debug("Failed to update ACP session metadata", exc_info=True)
+
+            # Replace stored messages with current history atomically so a
+            # mid-rewrite failure rolls back and the previously persisted
+            # conversation is preserved (salvaged from #13675).
+            db.replace_messages(state.session_id, state.history)
+        except Exception:
+            logger.warning("Failed to persist ACP session %s", state.session_id, exc_info=True)
+
+    def _restore(self, session_id: str) -> Optional[SessionState]:
+        """Load a session from the database into memory, recreating the AIAgent."""
+        import threading
+
+        db = self._get_db()
+        if db is None:
+            return None
+
+        try:
+            row = db.get_session(session_id)
+        except Exception:
+            logger.debug("Failed to query DB for ACP session %s", session_id, exc_info=True)
+            return None
+
+        if row is None:
+            return None
+
+        # Only restore ACP sessions.
+        if row.get("source") != "acp":
+            return None
+
+        # Extract cwd from model_config.
+        cwd = "."
+        requested_provider = row.get("billing_provider")
+        restored_base_url = row.get("billing_base_url")
+        restored_api_mode = None
+        mc = row.get("model_config")
+        if mc:
+            try:
+                meta = json.loads(mc)
+                if isinstance(meta, dict):
+                    cwd = meta.get("cwd", ".")
+                    requested_provider = meta.get("provider") or requested_provider
+                    restored_base_url = meta.get("base_url") or restored_base_url
+                    restored_api_mode = meta.get("api_mode") or restored_api_mode
+            except (json.JSONDecodeError, TypeError):
+                pass
+
+        model = row.get("model") or None
+
+        # Load conversation history.
+        try:
+            history = db.get_messages_as_conversation(session_id)
+        except Exception:
+            logger.warning("Failed to load messages for ACP session %s", session_id, exc_info=True)
+            history = []
+
+        try:
+            agent = self._make_agent(
+                session_id=session_id,
+                cwd=cwd,
+                model=model,
+                requested_provider=requested_provider,
+                base_url=restored_base_url,
+                api_mode=restored_api_mode,
+            )
+        except Exception:
+            logger.warning("Failed to recreate agent for ACP session %s", session_id, exc_info=True)
+            return None
+
+        state = SessionState(
+            session_id=session_id,
+            agent=agent,
+            cwd=cwd,
+            model=model or getattr(agent, "model", "") or "",
+            history=history,
+            cancel_event=threading.Event(),
+        )
+        with self._lock:
+            self._sessions[session_id] = state
+        _register_task_cwd(session_id, cwd)
+        logger.info("Restored ACP session %s from DB (%d messages)", session_id, len(history))
+        return state
+
+    def _delete_persisted(self, session_id: str) -> bool:
+        """Delete a session from the database. Returns True if it existed."""
+        db = self._get_db()
+        if db is None:
+            return False
+        try:
+            return db.delete_session(session_id)
+        except Exception:
+            logger.debug("Failed to delete ACP session %s from DB", session_id, exc_info=True)
+            return False
+
+    # ---- internal -----------------------------------------------------------
+
+    def _make_agent(
+        self,
+        *,
+        session_id: str,
+        cwd: str,
+        model: str | None = None,
+        requested_provider: str | None = None,
+        base_url: str | None = None,
+        api_mode: str | None = None,
+    ):
+        if self._agent_factory is not None:
+            return self._agent_factory()
+
+        from run_agent import AIAgent
+        from hermes_cli.config import load_config
+        from hermes_cli.runtime_provider import resolve_runtime_provider
+
+        config = load_config()
+        model_cfg = config.get("model")
+        default_model = ""
+        config_provider = None
+        if isinstance(model_cfg, dict):
+            default_model = str(model_cfg.get("default") or default_model)
+            config_provider = model_cfg.get("provider")
+        elif isinstance(model_cfg, str) and model_cfg.strip():
+            default_model = model_cfg.strip()
+
+        configured_mcp_servers = [
+            name
+            for name, cfg in (config.get("mcp_servers") or {}).items()
+            if not isinstance(cfg, dict) or cfg.get("enabled", True) is not False
+        ]
+
+        kwargs = {
+            "platform": "acp",
+            "enabled_toolsets": _expand_acp_enabled_toolsets(
+                ["hermes-acp"],
+                mcp_server_names=configured_mcp_servers,
+            ),
+            "quiet_mode": True,
+            "session_id": session_id,
+            "session_db": self._get_db(),
+            "model": model or default_model,
+        }
+
+        try:
+            runtime = resolve_runtime_provider(requested=requested_provider or config_provider)
+            kwargs.update(
+                {
+                    "provider": runtime.get("provider"),
+                    "api_mode": api_mode or runtime.get("api_mode"),
+                    "base_url": base_url or runtime.get("base_url"),
+                    "api_key": runtime.get("api_key"),
+                    "command": runtime.get("command"),
+                    "args": list(runtime.get("args") or []),
+                }
+            )
+        except Exception:
+            logger.debug("ACP session falling back to default provider resolution", exc_info=True)
+
+        _register_task_cwd(session_id, cwd)
+        agent = AIAgent(**kwargs)
+        # ACP stdio transport requires stdout to remain protocol-only JSON-RPC.
+        # Route any incidental human-readable agent output to stderr instead.
+        agent._print_fn = _acp_stderr_print
+        return agent