@nextclaw/nextclaw-hermes-acp-bridge 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NextClaw contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+# NextClaw Hermes ACP Bridge
+
+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.

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

@@ -0,0 +1,225 @@
+"""NextClaw bridge for Hermes ACP RuntimeRoute passthrough.
+
+This module is auto-imported by Python when PYTHONPATH points at this
+directory. It patches Hermes ACP so `hermes acp` consumes the active
+NextClaw RuntimeRoute instead of resolving its own provider config first.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import Any, Dict, Optional
+
+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,
+    }
+
+
+def _merge_openai_headers(agent: Any, headers: Dict[str, str]) -> None:
+    if not headers:
+        return
+    client_kwargs = getattr(agent, "_client_kwargs", None)
+    if not isinstance(client_kwargs, dict):
+        return
+    merged = dict(client_kwargs.get("default_headers") or {})
+    merged.update(headers)
+    client_kwargs["default_headers"] = merged
+    replace_client = getattr(agent, "_replace_primary_openai_client", None)
+    if callable(replace_client):
+        replace_client(reason="nextclaw_runtime_route_bridge")
+
+
+def _merge_anthropic_headers(agent: Any, headers: Dict[str, str]) -> None:
+    if not headers:
+        return
+    client = getattr(agent, "_anthropic_client", None)
+    if client is None:
+        return
+    merged = dict(getattr(client, "_default_headers", {}) or {})
+    merged.update(headers)
+    if hasattr(client, "_default_headers"):
+        client._default_headers = merged
+    inner_client = getattr(client, "_client", None)
+    if inner_client is not None:
+        if hasattr(inner_client, "_default_headers"):
+            inner_client._default_headers = merged
+        transport_headers = getattr(inner_client, "headers", None)
+        if hasattr(transport_headers, "update"):
+            transport_headers.update(merged)
+
+
+def _patch_acp_auth() -> None:
+    try:
+        from acp_adapter import auth as auth_module
+    except Exception:
+        LOGGER.debug("Failed to import acp_adapter.auth", exc_info=True)
+        return
+
+    original_detect_provider = auth_module.detect_provider
+
+    def detect_provider():
+        route = _read_nextclaw_route()
+        if route is not None:
+            return "nextclaw"
+        return original_detect_provider()
+
+    def has_provider():
+        return detect_provider() is not None
+
+    auth_module.detect_provider = detect_provider
+    auth_module.has_provider = has_provider
+
+
+def _patch_session_manager() -> None:
+    try:
+        from acp_adapter import session as session_module
+    except Exception:
+        LOGGER.debug("Failed to import acp_adapter.session", exc_info=True)
+        return
+
+    original_make_agent = session_module.SessionManager._make_agent
+
+    def bridged_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,
+    ):
+        route = _read_nextclaw_route(explicit_model=model)
+        if route is None:
+            return original_make_agent(
+                self,
+                session_id=session_id,
+                cwd=cwd,
+                model=model,
+                requested_provider=requested_provider,
+                base_url=base_url,
+                api_mode=api_mode,
+            )
+
+        if self._agent_factory is not None:
+            return self._agent_factory()
+
+        from run_agent import AIAgent
+
+        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._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
+
+    session_module.SessionManager._make_agent = bridged_make_agent
+
+
+def _patch_acp_reasoning_mapping() -> None:
+    try:
+        from run_agent import AIAgent
+    except Exception:
+        LOGGER.debug("Failed to import run_agent.AIAgent", exc_info=True)
+        return
+
+    original_run_conversation = getattr(AIAgent, "run_conversation", None)
+    if not callable(original_run_conversation):
+        return
+    if getattr(original_run_conversation, "__nextclaw_reasoning_bridge__", False):
+        return
+
+    def bridged_run_conversation(self, *args, **kwargs):
+        original_thinking = getattr(self, "thinking_callback", None)
+        original_reasoning = getattr(self, "reasoning_callback", None)
+        remapped = (
+            getattr(self, "platform", None) == "acp"
+            and callable(original_thinking)
+            and original_reasoning is None
+        )
+
+        if remapped:
+            # Hermes ACP currently wires its transient spinner/status callback
+            # into ACP thought events. For ACP sessions, remap that callback to
+            # the real reasoning channel so downstream clients receive model
+            # reasoning instead of strings like "(⌐■_■) computing...".
+            self.reasoning_callback = original_thinking
+            self.thinking_callback = None
+
+        try:
+            return original_run_conversation(self, *args, **kwargs)
+        finally:
+            if remapped:
+                self.thinking_callback = original_thinking
+                self.reasoning_callback = original_reasoning
+
+    bridged_run_conversation.__nextclaw_reasoning_bridge__ = True
+    AIAgent.run_conversation = bridged_run_conversation
+
+
+def _activate() -> None:
+    if _read_text_env(ROUTE_ENABLE_ENV) != "1":
+        return
+    _patch_acp_auth()
+    _patch_session_manager()
+    _patch_acp_reasoning_mapping()
+
+
+_activate()

package/dist/hermes-acp-route-bridge.utils.d.ts

@@ -0,0 +1,13 @@
+//#region src/hermes-acp-route-bridge.utils.d.ts
+type HermesAcpLaunchTarget = {
+  command: string;
+  args: string[];
+};
+type HermesAcpBridgeLaunchEnvParams = HermesAcpLaunchTarget & {
+  baseEnv?: Record<string, string | undefined>;
+  useProbeRoute?: boolean;
+};
+declare function isHermesAcpRuntimeConfig(config: HermesAcpLaunchTarget): boolean;
+declare function buildHermesAcpBridgeLaunchEnv(params: HermesAcpBridgeLaunchEnvParams): Record<string, string>;
+//#endregion
+export { buildHermesAcpBridgeLaunchEnv, isHermesAcpRuntimeConfig };

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

@@ -0,0 +1,59 @@
+import { existsSync } from "node:fs";
+import { basename, delimiter } 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";
+const HERMES_ACP_BRIDGE_DIR_ENV = "NEXTCLAW_HERMES_ACP_ROUTE_BRIDGE_DIR";
+const HERMES_ACP_PROBE_ROUTE_ENV = {
+	NEXTCLAW_MODEL: "nextclaw-hermes-acp-probe",
+	NEXTCLAW_API_BASE: "http://127.0.0.1:1/v1",
+	NEXTCLAW_API_KEY: "nextclaw-hermes-acp-probe-key",
+	NEXTCLAW_HEADERS_JSON: JSON.stringify({ "x-nextclaw-narp-api-mode": "chat_completions" })
+};
+function normalizeCommandBasename(command) {
+	return basename(command).trim().toLowerCase();
+}
+function normalizeStringEnv(source) {
+	const output = {};
+	for (const [key, value] of Object.entries(source)) if (typeof value === "string") output[key] = value;
+	return output;
+}
+function isPythonCommand(command) {
+	const normalized = normalizeCommandBasename(command);
+	return normalized === "python" || normalized === "python3" || normalized.startsWith("python3.");
+}
+function targetsHermesAcpModule(args) {
+	for (let index = 0; index < args.length - 1; index += 1) if (args[index] === "-m" && args[index + 1]?.trim().toLowerCase() === "acp_adapter.entry") return true;
+	return false;
+}
+function isHermesAcpRuntimeConfig(config) {
+	const command = normalizeCommandBasename(config.command);
+	if (command === "hermes-acp") return true;
+	if (command === "hermes") return config.args[0]?.trim().toLowerCase() === "acp";
+	if (isPythonCommand(config.command)) return targetsHermesAcpModule(config.args);
+	return false;
+}
+function resolveHermesAcpBridgeDir() {
+	const bridgeDir = fileURLToPath(new URL("./hermes-acp-route-bridge", import.meta.url));
+	return existsSync(bridgeDir) ? bridgeDir : null;
+}
+function mergePathList(existingValue, injectedPath) {
+	const parts = (existingValue ?? "").split(delimiter).map((entry) => entry.trim()).filter(Boolean);
+	if (!parts.includes(injectedPath)) parts.unshift(injectedPath);
+	return parts.join(delimiter);
+}
+function buildHermesAcpBridgeLaunchEnv(params) {
+	const env = normalizeStringEnv(params.baseEnv ?? process.env);
+	if (!isHermesAcpRuntimeConfig(params)) return env;
+	const bridgeDir = resolveHermesAcpBridgeDir();
+	if (!bridgeDir) return env;
+	return {
+		...env,
+		...params.useProbeRoute ? HERMES_ACP_PROBE_ROUTE_ENV : {},
+		[HERMES_ACP_BRIDGE_ENABLE_ENV]: "1",
+		[HERMES_ACP_BRIDGE_DIR_ENV]: bridgeDir,
+		PYTHONPATH: mergePathList(env.PYTHONPATH, bridgeDir)
+	};
+}
+//#endregion
+export { buildHermesAcpBridgeLaunchEnv, isHermesAcpRuntimeConfig };

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { buildHermesAcpBridgeLaunchEnv, isHermesAcpRuntimeConfig } from "./hermes-acp-route-bridge.utils.js";
+export { buildHermesAcpBridgeLaunchEnv, isHermesAcpRuntimeConfig };

package/dist/index.js

@@ -0,0 +1,2 @@
+import { buildHermesAcpBridgeLaunchEnv, isHermesAcpRuntimeConfig } from "./hermes-acp-route-bridge.utils.js";
+export { buildHermesAcpBridgeLaunchEnv, isHermesAcpRuntimeConfig };

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@nextclaw/nextclaw-hermes-acp-bridge",
+  "version": "0.1.1",
+  "private": false,
+  "description": "Hermes-specific ACP bridge helpers used by NextClaw runtime integrations.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@nextclaw/ncp": "0.5.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.6",
+    "typescript": "^5.6.3",
+    "vitest": "^4.1.2"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --dts --clean --target es2022 --no-fixedExtension --unbundle && node ./scripts/copy-hermes-acp-route-bridge.mjs",
+    "lint": "eslint .",
+    "tsc": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  }
+}