@nextclaw/nextclaw-hermes-acp-bridge 0.1.1 → 0.1.3

package/README.md

@@ -5,3 +5,33 @@ This package contains Hermes-specific ACP bridge helpers.
 It is intentionally separate from the generic
 `@nextclaw/nextclaw-ncp-runtime-stdio-client` package so the stdio runtime stays
 protocol-generic while Hermes keeps its own integration layer.
+
+## Boundary
+
+- This package exists to adapt Hermes into NextClaw. It is the primary place
+  for NextClaw-side bridge logic, launch-time injection, and compatibility
+  handling around Hermes ACP integration.
+- Do not directly modify Hermes upstream source code when fixing NextClaw
+  integration issues. In this repo, Hermes should be treated as an upstream
+  dependency boundary.
+- If Hermes behavior needs to be adjusted for NextClaw, prefer one of these
+  layers instead:
+  - bridge logic inside `packages/nextclaw-hermes-acp-bridge`
+  - NextClaw runtime adapter logic
+  - startup environment injection / wrapper behavior
+  - repo-local documentation and guardrails
+
+## Execution Model
+
+- Hermes ACP execution in NextClaw is request-scoped, not session-agent-scoped.
+- The long-lived ACP session keeps conversation history, cwd, selected model
+  snapshot, lightweight session metadata, and the current execution agent.
+- Each prompt treats `nextclaw_narp.providerRoute` as execution truth. When the
+  prompt route changes, NextClaw rebuilds the Hermes execution agent for that
+  request and replaces the session's current execution agent with the new one.
+- `providerRoute` is the execution truth for Hermes ACP requests. NextClaw does
+  not rely on ACP `setSessionModel(modelId)` to perform real cross-provider
+  switching for Hermes.
+- Request-scoped execution agents must rebuild Hermes's cached system prompt
+  from the current route. They must not inherit a previous model/provider
+  prompt cache across cross-provider switches.

package/dist/hermes-acp-route-bridge/nextclaw-hermes-acp-runtime-route.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import Any, Dict, Optional
+
+LOGGER = logging.getLogger("nextclaw.hermes_acp_route_bridge")
+API_MODE_HEADER = "x-nextclaw-narp-api-mode"
+NARP_PROMPT_META_KEY = "nextclaw_narp"
+_SESSION_ROUTE_OVERRIDES: Dict[str, Dict[str, Any]] = {}
+
+
+def read_text_env(name: str) -> Optional[str]:
+    value = os.environ.get(name)
+    if not isinstance(value, str):
+        return None
+    trimmed = value.strip()
+    return trimmed or None
+
+
+def _read_headers_env() -> Dict[str, str]:
+    raw = read_text_env("NEXTCLAW_HEADERS_JSON")
+    if not raw:
+        return {}
+    try:
+        parsed = json.loads(raw)
+    except Exception:
+        LOGGER.debug("Failed to parse NEXTCLAW_HEADERS_JSON", exc_info=True)
+        return {}
+    if not isinstance(parsed, dict):
+        return {}
+    normalized: Dict[str, str] = {}
+    for key, value in parsed.items():
+        if isinstance(key, str) and isinstance(value, str) and key.strip() and value.strip():
+            normalized[key] = value
+    return normalized
+
+
+def _normalize_route_headers(raw_headers: Any) -> Dict[str, str]:
+    if not isinstance(raw_headers, dict):
+        return {}
+    normalized: Dict[str, str] = {}
+    for key, value in raw_headers.items():
+        if isinstance(key, str) and isinstance(value, str):
+            trimmed_key = key.strip()
+            trimmed_value = value.strip()
+            if trimmed_key and trimmed_value:
+                normalized[trimmed_key] = trimmed_value
+    return normalized
+
+
+def _normalize_route_payload(raw_route: Any) -> Optional[Dict[str, Any]]:
+    if not isinstance(raw_route, dict):
+        return None
+    model = raw_route.get("model")
+    api_base = raw_route.get("apiBase")
+    if api_base is None:
+        api_base = raw_route.get("api_base")
+    api_key = raw_route.get("apiKey")
+    if api_key is None:
+        api_key = raw_route.get("api_key")
+    api_mode = raw_route.get("apiMode")
+    if api_mode is None:
+        api_mode = raw_route.get("api_mode")
+    provider = raw_route.get("provider")
+    headers = (
+        _normalize_route_headers(raw_route.get("headers"))
+        or _normalize_route_headers(raw_route.get("extraHeaders"))
+        or _normalize_route_headers(raw_route.get("extra_headers"))
+    )
+    api_mode_from_headers = headers.pop(API_MODE_HEADER, None)
+
+    normalized_model = model.strip() if isinstance(model, str) else None
+    normalized_api_base = api_base.strip() if isinstance(api_base, str) else None
+    normalized_api_key = api_key.strip() if isinstance(api_key, str) else None
+    normalized_api_mode = api_mode.strip() if isinstance(api_mode, str) else None
+    normalized_provider = provider.strip() if isinstance(provider, str) else None
+
+    if not any(
+        [
+            normalized_model,
+            normalized_api_base,
+            normalized_api_key,
+            headers,
+            normalized_api_mode,
+            normalized_provider,
+        ]
+    ):
+        return None
+
+    return {
+        "model": normalized_model,
+        "api_base": normalized_api_base,
+        "api_key": normalized_api_key or "",
+        "headers": headers,
+        "api_mode": normalized_api_mode or api_mode_from_headers or "chat_completions",
+        "provider": normalized_provider,
+    }
+
+
+def _merge_route_payloads(
+    base_route: Optional[Dict[str, Any]],
+    override_route: Optional[Dict[str, Any]],
+) -> Optional[Dict[str, Any]]:
+    if base_route is None:
+        return dict(override_route) if override_route is not None else None
+    if override_route is None:
+        return dict(base_route)
+
+    return {
+        "model": override_route.get("model") or base_route.get("model"),
+        "api_base": override_route.get("api_base") or base_route.get("api_base"),
+        "api_key": override_route.get("api_key")
+        if override_route.get("api_key") is not None
+        else base_route.get("api_key"),
+        "headers": dict(override_route.get("headers") or {}),
+        "api_mode": override_route.get("api_mode") or base_route.get("api_mode"),
+        "provider": override_route.get("provider") or base_route.get("provider"),
+    }
+
+
+def read_nextclaw_route(
+    session_id: Optional[str] = None,
+    explicit_model: Optional[str] = None,
+    explicit_base_url: Optional[str] = None,
+    explicit_api_mode: Optional[str] = None,
+    explicit_provider: Optional[str] = None,
+) -> Optional[Dict[str, Any]]:
+    model = explicit_model or read_text_env("NEXTCLAW_MODEL")
+    api_base = read_text_env("NEXTCLAW_API_BASE")
+    api_key = read_text_env("NEXTCLAW_API_KEY")
+    headers = _read_headers_env()
+    api_mode = headers.pop(API_MODE_HEADER, None) or "chat_completions"
+    route = _normalize_route_payload(
+        {
+            "model": model,
+            "api_base": api_base,
+            "api_key": api_key,
+            "headers": headers,
+            "api_mode": explicit_api_mode or api_mode,
+            "provider": explicit_provider,
+        }
+    )
+    if session_id:
+        route = _merge_route_payloads(route, _SESSION_ROUTE_OVERRIDES.get(session_id))
+    if route is None:
+        return None
+    if explicit_model:
+        route["model"] = explicit_model
+    if explicit_base_url:
+        route["api_base"] = explicit_base_url
+    if explicit_api_mode:
+        route["api_mode"] = explicit_api_mode
+    if explicit_provider:
+        route["provider"] = explicit_provider
+    return route
+
+
+def read_nextclaw_prompt_route(kwargs: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    nextclaw_meta = kwargs.get(NARP_PROMPT_META_KEY)
+    if not isinstance(nextclaw_meta, dict):
+        meta = kwargs.get("_meta")
+        if not isinstance(meta, dict):
+            return None
+        nextclaw_meta = meta.get(NARP_PROMPT_META_KEY)
+        if not isinstance(nextclaw_meta, dict):
+            return None
+    return _normalize_route_payload(nextclaw_meta.get("providerRoute"))
+
+
+def remember_session_route(session_id: str, route: Dict[str, Any]) -> None:
+    _SESSION_ROUTE_OVERRIDES[session_id] = dict(route)
+
+
+def read_session_route(session_id: str) -> Optional[Dict[str, Any]]:
+    route = _SESSION_ROUTE_OVERRIDES.get(session_id)
+    return dict(route) if route is not None else None
+
+
+def pop_session_route(session_id: str) -> None:
+    _SESSION_ROUTE_OVERRIDES.pop(session_id, None)
+
+
+def clear_session_routes() -> None:
+    _SESSION_ROUTE_OVERRIDES.clear()

package/dist/hermes-acp-route-bridge/sitecustomize.py

@@ -7,57 +7,29 @@ NextClaw RuntimeRoute instead of resolving its own provider config first.
 
 from __future__ import annotations
 
-import json
+import importlib.util
 import logging
-import os
-from typing import Any, Dict, Optional
+from pathlib import Path
+from typing import Any, Dict
 
 LOGGER = logging.getLogger("nextclaw.hermes_acp_route_bridge")
 ROUTE_ENABLE_ENV = "NEXTCLAW_HERMES_ACP_ROUTE_BRIDGE"
-API_MODE_HEADER = "x-nextclaw-narp-api-mode"
-
-
-def _read_text_env(name: str) -> Optional[str]:
-    value = os.environ.get(name)
-    if not isinstance(value, str):
-        return None
-    trimmed = value.strip()
-    return trimmed or None
-
-
-def _read_headers_env() -> Dict[str, str]:
-    raw = _read_text_env("NEXTCLAW_HEADERS_JSON")
-    if not raw:
-        return {}
-    try:
-        parsed = json.loads(raw)
-    except Exception:
-        LOGGER.debug("Failed to parse NEXTCLAW_HEADERS_JSON", exc_info=True)
-        return {}
-    if not isinstance(parsed, dict):
-        return {}
-    normalized: Dict[str, str] = {}
-    for key, value in parsed.items():
-        if isinstance(key, str) and isinstance(value, str) and key.strip() and value.strip():
-            normalized[key] = value
-    return normalized
-
-
-def _read_nextclaw_route(explicit_model: Optional[str] = None) -> Optional[Dict[str, Any]]:
-    model = explicit_model or _read_text_env("NEXTCLAW_MODEL")
-    api_base = _read_text_env("NEXTCLAW_API_BASE")
-    api_key = _read_text_env("NEXTCLAW_API_KEY")
-    headers = _read_headers_env()
-    api_mode = headers.pop(API_MODE_HEADER, None) or "chat_completions"
-    if not any([model, api_base, api_key, headers]):
-        return None
-    return {
-      "model": model,
-      "api_base": api_base,
-      "api_key": api_key or "",
-      "headers": headers,
-      "api_mode": api_mode,
-    }
+CREATE_EXECUTION_AGENT = None
+
+_ROUTE_HELPER_SPEC = importlib.util.spec_from_file_location(
+    "nextclaw_hermes_acp_runtime_route",
+    Path(__file__).with_name("nextclaw-hermes-acp-runtime-route.py"),
+)
+if _ROUTE_HELPER_SPEC is None or _ROUTE_HELPER_SPEC.loader is None:
+    raise ImportError("Failed to load nextclaw Hermes ACP runtime route helper.")
+_ROUTE_HELPER_MODULE = importlib.util.module_from_spec(_ROUTE_HELPER_SPEC)
+_ROUTE_HELPER_SPEC.loader.exec_module(_ROUTE_HELPER_MODULE)
+clear_session_routes = _ROUTE_HELPER_MODULE.clear_session_routes
+pop_session_route = _ROUTE_HELPER_MODULE.pop_session_route
+read_nextclaw_prompt_route = _ROUTE_HELPER_MODULE.read_nextclaw_prompt_route
+read_nextclaw_route = _ROUTE_HELPER_MODULE.read_nextclaw_route
+read_text_env = _ROUTE_HELPER_MODULE.read_text_env
+remember_session_route = _ROUTE_HELPER_MODULE.remember_session_route
 
 
 def _merge_openai_headers(agent: Any, headers: Dict[str, str]) -> None:
@@ -103,7 +75,7 @@ def _patch_acp_auth() -> None:
     original_detect_provider = auth_module.detect_provider
 
     def detect_provider():
-        route = _read_nextclaw_route()
+        route = read_nextclaw_route()
         if route is not None:
             return "nextclaw"
         return original_detect_provider()
@@ -116,6 +88,7 @@ def _patch_acp_auth() -> None:
 
 
 def _patch_session_manager() -> None:
+    global CREATE_EXECUTION_AGENT
     try:
         from acp_adapter import session as session_module
     except Exception:
@@ -124,6 +97,56 @@ def _patch_session_manager() -> None:
 
     original_make_agent = session_module.SessionManager._make_agent
 
+    def create_execution_agent(
+        *,
+        session_id: str,
+        cwd: str,
+        model: str | None,
+        requested_provider: str | None,
+        base_url: str | None,
+        api_mode: str | None,
+    ):
+        route = read_nextclaw_route(
+            session_id=session_id,
+            explicit_model=model,
+            explicit_base_url=base_url,
+            explicit_api_mode=api_mode,
+            explicit_provider=requested_provider,
+        )
+        if route is None:
+            raise RuntimeError(
+                "Missing NextClaw providerRoute for Hermes ACP request-scoped execution."
+            )
+
+        from run_agent import AIAgent
+
+        kwargs = {
+            "platform": "acp",
+            "enabled_toolsets": ["hermes-acp"],
+            "quiet_mode": True,
+            "session_id": session_id,
+            "model": route["model"] or "",
+            "provider": route.get("provider") or requested_provider or "custom",
+            "api_mode": route["api_mode"],
+            "base_url": route["api_base"] or "",
+            "api_key": route["api_key"],
+        }
+
+        session_module._register_task_cwd(session_id, cwd)
+        agent = AIAgent(**kwargs)
+        agent._print_fn = session_module._acp_stderr_print
+        _merge_openai_headers(agent, route["headers"])
+        _merge_anthropic_headers(agent, route["headers"])
+        LOGGER.info(
+            "Hermes ACP execution agent route resolved: session_id=%s model=%s provider=%s api_mode=%s base_url=%s",
+            session_id,
+            getattr(agent, "model", ""),
+            getattr(agent, "provider", ""),
+            getattr(agent, "api_mode", ""),
+            getattr(agent, "base_url", ""),
+        )
+        return agent
+
     def bridged_make_agent(
         self,
         *,
@@ -134,7 +157,13 @@ def _patch_session_manager() -> None:
         base_url: str | None = None,
         api_mode: str | None = None,
     ):
-        route = _read_nextclaw_route(explicit_model=model)
+        route = read_nextclaw_route(
+            session_id=session_id,
+            explicit_model=model,
+            explicit_base_url=base_url,
+            explicit_api_mode=api_mode,
+            explicit_provider=requested_provider,
+        )
         if route is None:
             return original_make_agent(
                 self,
@@ -149,28 +178,89 @@ def _patch_session_manager() -> None:
         if self._agent_factory is not None:
             return self._agent_factory()
 
-        from run_agent import AIAgent
+        return create_execution_agent(
+            session_id=session_id,
+            cwd=cwd,
+            model=(route or {}).get("model") or model,
+            requested_provider=(route or {}).get("provider") or requested_provider,
+            base_url=(route or {}).get("api_base") or base_url,
+            api_mode=(route or {}).get("api_mode") or api_mode,
+        )
 
-        kwargs = {
-            "platform": "acp",
-            "enabled_toolsets": ["hermes-acp"],
-            "quiet_mode": True,
-            "session_id": session_id,
-            "model": route["model"] or "",
-            "provider": requested_provider or "custom",
-            "api_mode": api_mode or route["api_mode"],
-            "base_url": base_url or route["api_base"] or "",
-            "api_key": route["api_key"],
-        }
+    session_module.SessionManager._make_agent = bridged_make_agent
 
-        session_module._register_task_cwd(session_id, cwd)
-        agent = AIAgent(**kwargs)
-        agent._print_fn = session_module._acp_stderr_print
-        _merge_openai_headers(agent, route["headers"])
-        _merge_anthropic_headers(agent, route["headers"])
-        return agent
+    original_remove_session = session_module.SessionManager.remove_session
 
-    session_module.SessionManager._make_agent = bridged_make_agent
+    def bridged_remove_session(self, session_id: str) -> bool:
+        pop_session_route(session_id)
+        return original_remove_session(self, session_id)
+
+    session_module.SessionManager.remove_session = bridged_remove_session
+
+    original_cleanup = session_module.SessionManager.cleanup
+
+    def bridged_cleanup(self) -> None:
+        clear_session_routes()
+        return original_cleanup(self)
+
+    session_module.SessionManager.cleanup = bridged_cleanup
+    CREATE_EXECUTION_AGENT = create_execution_agent
+
+
+def _patch_prompt_execution() -> None:
+    try:
+        from acp_adapter import server as server_module
+        from acp_adapter import session as session_module
+    except Exception:
+        LOGGER.debug("Failed to import Hermes ACP server/session modules", exc_info=True)
+        return
+
+    original_prompt = getattr(server_module.HermesACPAgent, "prompt", None)
+    if not callable(original_prompt):
+        return
+    if getattr(original_prompt, "__nextclaw_request_scoped_agent_bridge__", False):
+        return
+
+    async def bridged_prompt(self, prompt, session_id: str, **kwargs):
+        if not callable(CREATE_EXECUTION_AGENT):
+            raise RuntimeError("NextClaw Hermes ACP request-scoped agent bridge is not ready.")
+        state = self.session_manager.get_session(session_id)
+        if state is None:
+            return await original_prompt(self, prompt, session_id, **kwargs)
+
+        prompt_route = read_nextclaw_prompt_route(kwargs)
+        if prompt_route is not None:
+            remember_session_route(session_id, prompt_route)
+            if prompt_route.get("model"):
+                state.model = prompt_route["model"]
+
+            previous_agent = getattr(state, "agent", None)
+            provider_hint = None
+            base_url_hint = None
+            api_mode_hint = None
+            try:
+                state.agent = CREATE_EXECUTION_AGENT(
+                    session_id=session_id,
+                    cwd=state.cwd,
+                    model=state.model or getattr(previous_agent, "model", None),
+                    requested_provider=provider_hint,
+                    base_url=base_url_hint,
+                    api_mode=api_mode_hint,
+                )
+                session_module._register_task_cwd(session_id, state.cwd)
+            except Exception as exc:
+                LOGGER.exception(
+                    "Failed to create prompt-routed Hermes execution agent for session %s",
+                    session_id,
+                )
+                raise RuntimeError(
+                    "NextClaw Hermes ACP failed to create the prompt-routed execution agent."
+                ) from exc
+
+        return await original_prompt(self, prompt, session_id, **kwargs)
+
+    bridged_prompt.__nextclaw_request_scoped_agent_bridge__ = True
+    server_module.HermesACPAgent.prompt = bridged_prompt
 
 
 def _patch_acp_reasoning_mapping() -> None:
@@ -215,10 +305,11 @@ def _patch_acp_reasoning_mapping() -> None:
 
 
 def _activate() -> None:
-    if _read_text_env(ROUTE_ENABLE_ENV) != "1":
+    if read_text_env(ROUTE_ENABLE_ENV) != "1":
         return
     _patch_acp_auth()
     _patch_session_manager()
+    _patch_prompt_execution()
     _patch_acp_reasoning_mapping()
 
 

package/dist/hermes-acp-route-bridge.utils.js

@@ -1,5 +1,5 @@
 import { existsSync } from "node:fs";
-import { basename, delimiter } from "node:path";
+import { basename, delimiter, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 //#region src/hermes-acp-route-bridge.utils.ts
 const HERMES_ACP_BRIDGE_ENABLE_ENV = "NEXTCLAW_HERMES_ACP_ROUTE_BRIDGE";
@@ -34,8 +34,11 @@ function isHermesAcpRuntimeConfig(config) {
 	return false;
 }
 function resolveHermesAcpBridgeDir() {
-	const bridgeDir = fileURLToPath(new URL("./hermes-acp-route-bridge", import.meta.url));
-	return existsSync(bridgeDir) ? bridgeDir : null;
+	const packageDir = fileURLToPath(new URL("../", import.meta.url));
+	const sourceBridgeDir = resolve(packageDir, "src/hermes-acp-route-bridge");
+	if (existsSync(sourceBridgeDir)) return sourceBridgeDir;
+	const distBridgeDir = resolve(packageDir, "dist/hermes-acp-route-bridge");
+	return existsSync(distBridgeDir) ? distBridgeDir : null;
 }
 function mergePathList(existingValue, injectedPath) {
 	const parts = (existingValue ?? "").split(delimiter).map((entry) => entry.trim()).filter(Boolean);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextclaw/nextclaw-hermes-acp-bridge",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "private": false,
   "description": "Hermes-specific ACP bridge helpers used by NextClaw runtime integrations.",
   "type": "module",
@@ -16,7 +16,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@nextclaw/ncp": "0.5.2"
+    "@nextclaw/ncp": "0.5.4"
   },
   "devDependencies": {
     "@types/node": "^20.17.6",
@@ -25,6 +25,7 @@
   },
   "scripts": {
     "build": "tsdown src/index.ts --dts --clean --target es2022 --no-fixedExtension --unbundle && node ./scripts/copy-hermes-acp-route-bridge.mjs",
+    "check:bridge-sync": "node ./scripts/check-hermes-acp-route-bridge-sync.mjs",
     "lint": "eslint .",
     "tsc": "tsc -p tsconfig.json",
     "test": "vitest run"