@nextclaw/nextclaw-ncp-runtime-stdio-client 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,9 @@
+# @nextclaw/nextclaw-ncp-runtime-stdio-client
+
+Generic `NcpAgentRuntime` package for external agent connectors that speak ACP over stdio.
+
+It is intentionally generic:
+
+- no Hermes-specific protocol logic
+- no runtime type registration logic
+- no UI config concerns

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.js

@@ -0,0 +1,61 @@
+import { buildRuntimeRouteBridgeEnv } from "./stdio-runtime-config.utils.js";
+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 = {
+	model: "nextclaw-hermes-acp-probe",
+	apiBase: "http://127.0.0.1:1/v1",
+	apiKey: "nextclaw-hermes-acp-probe-key",
+	headers: { "x-nextclaw-narp-api-mode": "chat_completions" }
+};
+function normalizeCommandBasename(command) {
+	return basename(command).trim().toLowerCase();
+}
+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 buildStdioLaunchEnv(params) {
+	const providerRoute = params.providerRoute ?? (params.useProbeRoute && isHermesAcpRuntimeConfig(params.config) ? HERMES_ACP_PROBE_ROUTE : void 0);
+	const baseEnv = {};
+	for (const [key, value] of Object.entries(params.baseEnv ?? process.env)) if (typeof value === "string") baseEnv[key] = value;
+	const env = {
+		...baseEnv,
+		...params.config.env ?? {},
+		...buildRuntimeRouteBridgeEnv({ providerRoute })
+	};
+	if (!isHermesAcpRuntimeConfig(params.config)) return env;
+	const bridgeDir = resolveHermesAcpBridgeDir();
+	if (!bridgeDir) return env;
+	return {
+		...env,
+		[HERMES_ACP_BRIDGE_ENABLE_ENV]: "1",
+		[HERMES_ACP_BRIDGE_DIR_ENV]: bridgeDir,
+		PYTHONPATH: mergePathList(env.PYTHONPATH, bridgeDir)
+	};
+}
+//#endregion
+export { buildStdioLaunchEnv };

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { NARP_STDIO_PROMPT_META_KEY, NarpStdioPromptMeta, StdioRuntimeConfigResolver, StdioRuntimeEnv, StdioRuntimeProcessScope, StdioRuntimeResolvedConfig, StdioRuntimeWireDialect, buildRuntimeRouteBridgeEnv } from "./stdio-runtime-config.utils.js";
+import { StdioRuntimeNcpAgentRuntime, StdioRuntimeNcpAgentRuntimeConfig } from "./stdio-runtime.service.js";
+import { probeStdioRuntime } from "./stdio-runtime-probe.utils.js";
+export { NARP_STDIO_PROMPT_META_KEY, type NarpStdioPromptMeta, StdioRuntimeConfigResolver, type StdioRuntimeEnv, StdioRuntimeNcpAgentRuntime, type StdioRuntimeNcpAgentRuntimeConfig, type StdioRuntimeProcessScope, type StdioRuntimeResolvedConfig, type StdioRuntimeWireDialect, buildRuntimeRouteBridgeEnv, probeStdioRuntime };

package/dist/index.js

@@ -0,0 +1,4 @@
+import { NARP_STDIO_PROMPT_META_KEY, StdioRuntimeConfigResolver, buildRuntimeRouteBridgeEnv } from "./stdio-runtime-config.utils.js";
+import { StdioRuntimeNcpAgentRuntime } from "./stdio-runtime.service.js";
+import { probeStdioRuntime } from "./stdio-runtime-probe.utils.js";
+export { NARP_STDIO_PROMPT_META_KEY, StdioRuntimeConfigResolver, StdioRuntimeNcpAgentRuntime, buildRuntimeRouteBridgeEnv, probeStdioRuntime };

package/dist/stdio-runtime-config.utils.d.ts

@@ -0,0 +1,36 @@
+import { NcpProviderRuntimeRoute, OpenAITool } from "@nextclaw/ncp";
+
+//#region src/stdio-runtime-config.utils.d.ts
+declare const NARP_STDIO_PROMPT_META_KEY = "nextclaw_narp";
+type StdioRuntimeEnv = Record<string, string>;
+type StdioRuntimeWireDialect = "acp";
+type StdioRuntimeProcessScope = "per-session";
+type NarpStdioPromptMeta = {
+  correlationId?: string;
+  providerRoute?: NcpProviderRuntimeRoute;
+  sessionMetadata?: Record<string, unknown>;
+  tools?: ReadonlyArray<OpenAITool>;
+};
+type StdioRuntimeResolvedConfig = {
+  wireDialect: StdioRuntimeWireDialect;
+  processScope: StdioRuntimeProcessScope;
+  command: string;
+  args: string[];
+  cwd?: string;
+  env?: StdioRuntimeEnv;
+  startupTimeoutMs: number;
+  probeTimeoutMs: number;
+  requestTimeoutMs: number;
+};
+declare class StdioRuntimeConfigResolver {
+  private readonly source;
+  constructor(source?: Record<string, unknown>);
+  resolve: () => StdioRuntimeResolvedConfig;
+  private resolveWireDialect;
+  private resolveProcessScope;
+}
+declare function buildRuntimeRouteBridgeEnv(params: {
+  providerRoute?: NcpProviderRuntimeRoute;
+}): Record<string, string>;
+//#endregion
+export { NARP_STDIO_PROMPT_META_KEY, NarpStdioPromptMeta, StdioRuntimeConfigResolver, StdioRuntimeEnv, StdioRuntimeProcessScope, StdioRuntimeResolvedConfig, StdioRuntimeWireDialect, buildRuntimeRouteBridgeEnv };

package/dist/stdio-runtime-config.utils.js

@@ -0,0 +1,102 @@
+//#region src/stdio-runtime-config.utils.ts
+const NARP_STDIO_PROMPT_META_KEY = "nextclaw_narp";
+const DEFAULT_STARTUP_TIMEOUT_MS = 1e4;
+const DEFAULT_PROBE_TIMEOUT_MS = 3e3;
+const DEFAULT_REQUEST_TIMEOUT_MS = 12e4;
+const DEFAULT_RUNTIME_ROUTE_BRIDGE_FIELDS = {
+	model: "NEXTCLAW_MODEL",
+	apiBase: "NEXTCLAW_API_BASE",
+	apiKey: "NEXTCLAW_API_KEY",
+	headers: "NEXTCLAW_HEADERS_JSON"
+};
+function readString(value) {
+	if (typeof value !== "string") return;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : void 0;
+}
+function readPositiveInteger(value) {
+	const parsed = typeof value === "number" ? value : typeof value === "string" ? Number.parseInt(value, 10) : NaN;
+	if (!Number.isFinite(parsed)) return;
+	const normalized = Math.trunc(parsed);
+	return normalized > 0 ? normalized : void 0;
+}
+function readStringArray(value) {
+	if (!Array.isArray(value)) return;
+	const output = [];
+	for (const entry of value) {
+		const normalized = readString(entry);
+		if (!normalized) continue;
+		output.push(normalized);
+	}
+	return output.length > 0 ? output : void 0;
+}
+function readStringRecord(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return;
+	const output = {};
+	for (const [entryKey, entryValue] of Object.entries(value)) {
+		const normalizedValue = readString(entryValue);
+		if (!normalizedValue) continue;
+		output[entryKey] = normalizedValue;
+	}
+	return Object.keys(output).length > 0 ? output : void 0;
+}
+var StdioRuntimeConfigResolver = class {
+	constructor(source = {}) {
+		this.source = source;
+	}
+	resolve = () => {
+		const wireDialect = this.resolveWireDialect();
+		const processScope = this.resolveProcessScope();
+		const command = readString(this.source.command) ?? readString(process.env.NEXTCLAW_NARP_STDIO_COMMAND);
+		if (!command) throw new Error("[narp-stdio] missing stdio command");
+		return {
+			wireDialect,
+			processScope,
+			command,
+			args: readStringArray(this.source.args) ?? readStringArray(parseJsonArray(process.env.NEXTCLAW_NARP_STDIO_ARGS)) ?? [],
+			...readString(this.source.cwd) ?? readString(process.env.NEXTCLAW_NARP_STDIO_CWD) ? { cwd: readString(this.source.cwd) ?? readString(process.env.NEXTCLAW_NARP_STDIO_CWD) } : {},
+			...readStringRecord(this.source.env) ?? readStringRecord(parseJsonObject(process.env.NEXTCLAW_NARP_STDIO_ENV)) ? { env: readStringRecord(this.source.env) ?? readStringRecord(parseJsonObject(process.env.NEXTCLAW_NARP_STDIO_ENV)) } : {},
+			startupTimeoutMs: readPositiveInteger(this.source.startupTimeoutMs) ?? readPositiveInteger(process.env.NEXTCLAW_NARP_STDIO_STARTUP_TIMEOUT_MS) ?? DEFAULT_STARTUP_TIMEOUT_MS,
+			probeTimeoutMs: readPositiveInteger(this.source.probeTimeoutMs) ?? DEFAULT_PROBE_TIMEOUT_MS,
+			requestTimeoutMs: readPositiveInteger(this.source.requestTimeoutMs) ?? DEFAULT_REQUEST_TIMEOUT_MS
+		};
+	};
+	resolveWireDialect = () => {
+		const wireDialect = readString(this.source.wireDialect) ?? "acp";
+		if (wireDialect !== "acp") throw new Error(`[narp-stdio] unsupported wireDialect "${wireDialect}"`);
+		return "acp";
+	};
+	resolveProcessScope = () => {
+		const processScope = readString(this.source.processScope) ?? "per-session";
+		if (processScope !== "per-session") throw new Error(`[narp-stdio] unsupported processScope "${processScope}"`);
+		return "per-session";
+	};
+};
+function buildRuntimeRouteBridgeEnv(params) {
+	const { providerRoute } = params;
+	if (!providerRoute) return {};
+	return {
+		[DEFAULT_RUNTIME_ROUTE_BRIDGE_FIELDS.model]: providerRoute.model,
+		[DEFAULT_RUNTIME_ROUTE_BRIDGE_FIELDS.apiBase]: providerRoute.apiBase ?? "",
+		[DEFAULT_RUNTIME_ROUTE_BRIDGE_FIELDS.apiKey]: providerRoute.apiKey ?? "",
+		[DEFAULT_RUNTIME_ROUTE_BRIDGE_FIELDS.headers]: JSON.stringify(providerRoute.headers ?? {})
+	};
+}
+function parseJsonArray(value) {
+	if (typeof value !== "string" || !value.trim()) return;
+	try {
+		return JSON.parse(value);
+	} catch {
+		return;
+	}
+}
+function parseJsonObject(value) {
+	if (typeof value !== "string" || !value.trim()) return;
+	try {
+		return JSON.parse(value);
+	} catch {
+		return;
+	}
+}
+//#endregion
+export { NARP_STDIO_PROMPT_META_KEY, StdioRuntimeConfigResolver, buildRuntimeRouteBridgeEnv, readString };

package/dist/stdio-runtime-probe.utils.d.ts

@@ -0,0 +1,6 @@
+import { StdioRuntimeResolvedConfig } from "./stdio-runtime-config.utils.js";
+
+//#region src/stdio-runtime-probe.utils.d.ts
+declare function probeStdioRuntime(config: StdioRuntimeResolvedConfig): Promise<void>;
+//#endregion
+export { probeStdioRuntime };

package/dist/stdio-runtime-probe.utils.js

@@ -0,0 +1,69 @@
+import { buildStdioLaunchEnv } from "./hermes-acp-route-bridge.utils.js";
+import { spawn } from "node:child_process";
+import { Readable, Writable } from "node:stream";
+import * as acp from "@agentclientprotocol/sdk";
+//#region src/stdio-runtime-probe.utils.ts
+const createProbeClientBridge = () => ({
+	sessionUpdate: async () => void 0,
+	requestPermission: async () => ({ outcome: { outcome: "cancelled" } }),
+	readTextFile: async () => ({ content: "" }),
+	writeTextFile: async () => ({})
+});
+async function probeStdioRuntime(config) {
+	const child = spawn(config.command, config.args, {
+		cwd: config.cwd,
+		env: buildStdioLaunchEnv({
+			config,
+			useProbeRoute: true
+		}),
+		stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		]
+	});
+	const spawnErrorPromise = new Promise((_, reject) => {
+		child.once("error", (error) => {
+			const cwdSuffix = config.cwd ? ` (cwd: ${config.cwd})` : "";
+			reject(/* @__PURE__ */ new Error(`[narp-stdio] failed to start stdio runtime command "${config.command}"${cwdSuffix}: ${error.message}`));
+		});
+	});
+	let stderr = "";
+	child.stderr.setEncoding("utf8");
+	child.stderr.on("data", (chunk) => {
+		stderr = `${stderr}${chunk}`.slice(-4e3);
+	});
+	const stream = acp.ndJsonStream(Writable.toWeb(child.stdin), Readable.toWeb(child.stdout));
+	const connection = new acp.ClientSideConnection(() => createProbeClientBridge(), stream);
+	try {
+		const session = await Promise.race([(async () => {
+			await withTimeout(connection.initialize({
+				protocolVersion: acp.PROTOCOL_VERSION,
+				clientCapabilities: {}
+			}), config.probeTimeoutMs, `[narp-stdio] probe timed out initializing stdio runtime`);
+			return withTimeout(connection.newSession({
+				cwd: config.cwd ?? process.cwd(),
+				mcpServers: []
+			}), config.probeTimeoutMs, `[narp-stdio] probe timed out creating remote session`);
+		})(), spawnErrorPromise]);
+		await connection.cancel({ sessionId: session.sessionId }).catch(() => void 0);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : "[narp-stdio] stdio runtime probe failed";
+		throw new Error(`${message}. stderr=${stderr}`.trim());
+	} finally {
+		child.kill("SIGTERM");
+	}
+}
+async function withTimeout(promise, timeoutMs, message) {
+	let timeoutHandle;
+	const timeoutPromise = new Promise((_, reject) => {
+		timeoutHandle = setTimeout(() => reject(new Error(message)), timeoutMs);
+	});
+	try {
+		return await Promise.race([promise, timeoutPromise]);
+	} finally {
+		if (timeoutHandle) clearTimeout(timeoutHandle);
+	}
+}
+//#endregion
+export { probeStdioRuntime };

package/dist/stdio-runtime.service.d.ts

@@ -0,0 +1,18 @@
+import { StdioRuntimeResolvedConfig } from "./stdio-runtime-config.utils.js";
+import { NcpAgentConversationStateManager, NcpAgentRunInput, NcpAgentRunOptions, NcpAgentRuntime, NcpEndpointEvent, NcpProviderRuntimeRoute, OpenAITool } from "@nextclaw/ncp";
+
+//#region src/stdio-runtime.service.d.ts
+type StdioRuntimeNcpAgentRuntimeConfig = StdioRuntimeResolvedConfig & {
+  sessionId: string;
+  stateManager?: NcpAgentConversationStateManager;
+  resolveTools?: (input: NcpAgentRunInput) => ReadonlyArray<OpenAITool> | undefined;
+  resolveProviderRoute?: (input: NcpAgentRunInput) => NcpProviderRuntimeRoute | undefined;
+};
+declare class StdioRuntimeNcpAgentRuntime implements NcpAgentRuntime {
+  private readonly config;
+  private readonly session;
+  constructor(config: StdioRuntimeNcpAgentRuntimeConfig);
+  run: (this: StdioRuntimeNcpAgentRuntime, input: NcpAgentRunInput, options?: NcpAgentRunOptions) => AsyncGenerator<NcpEndpointEvent>;
+}
+//#endregion
+export { StdioRuntimeNcpAgentRuntime, StdioRuntimeNcpAgentRuntimeConfig };

package/dist/stdio-runtime.service.js

@@ -0,0 +1,603 @@
+import { NARP_STDIO_PROMPT_META_KEY, readString } from "./stdio-runtime-config.utils.js";
+import { buildStdioLaunchEnv } from "./hermes-acp-route-bridge.utils.js";
+import { randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import { Readable, Writable } from "node:stream";
+import * as acp from "@agentclientprotocol/sdk";
+import { NcpEventType } from "@nextclaw/ncp";
+//#region src/stdio-runtime.service.ts
+var UpdateBuffer = class {
+	updates = [];
+	waiters = /* @__PURE__ */ new Set();
+	push = (update) => {
+		this.updates.push(update);
+		this.flush();
+	};
+	shift = () => this.updates.shift();
+	hasItems = () => this.updates.length > 0;
+	waitForChange = async () => {
+		if (this.updates.length > 0) return;
+		await new Promise((resolve) => {
+			this.waiters.add(resolve);
+		});
+	};
+	notify = () => {
+		this.flush();
+	};
+	flush = () => {
+		if (this.waiters.size === 0) return;
+		const waiters = [...this.waiters];
+		this.waiters.clear();
+		for (const waiter of waiters) waiter();
+	};
+};
+var PromptUpdateCollector = class {
+	parts = [];
+	toolIndex = /* @__PURE__ */ new Map();
+	apply = (event) => {
+		switch (event.type) {
+			case NcpEventType.MessageTextDelta:
+				this.appendPart("text", event.payload.delta);
+				return;
+			case NcpEventType.MessageReasoningDelta:
+				this.appendPart("reasoning", event.payload.delta);
+				return;
+			case NcpEventType.MessageToolCallStart:
+				this.upsertTool({
+					toolCallId: event.payload.toolCallId,
+					toolName: event.payload.toolName,
+					args: "",
+					state: "partial-call"
+				});
+				return;
+			case NcpEventType.MessageToolCallArgs:
+				this.upsertTool({
+					toolCallId: event.payload.toolCallId,
+					toolName: this.readToolName(event.payload.toolCallId),
+					args: event.payload.args,
+					state: "partial-call"
+				});
+				return;
+			case NcpEventType.MessageToolCallArgsDelta:
+				this.upsertTool({
+					toolCallId: event.payload.toolCallId,
+					toolName: this.readToolName(event.payload.toolCallId),
+					args: `${this.readToolArgs(event.payload.toolCallId)}${event.payload.delta}`,
+					state: "partial-call"
+				});
+				return;
+			case NcpEventType.MessageToolCallEnd:
+				this.upsertTool({
+					toolCallId: event.payload.toolCallId,
+					toolName: this.readToolName(event.payload.toolCallId),
+					args: this.readToolArgs(event.payload.toolCallId),
+					state: "call"
+				});
+				return;
+			default: return;
+		}
+	};
+	hasParts = () => this.parts.length > 0;
+	buildParts = () => structuredClone(this.parts);
+	appendPart = (type, text) => {
+		if (!text) return;
+		const last = this.parts.at(-1);
+		if (last?.type === type) {
+			last.text = `${last.text}${text}`;
+			return;
+		}
+		this.parts.push({
+			type,
+			text
+		});
+	};
+	upsertTool = (nextTool) => {
+		const existingIndex = this.toolIndex.get(nextTool.toolCallId);
+		if (typeof existingIndex === "number") {
+			const existing = this.parts[existingIndex];
+			if (existing?.type !== "tool-invocation") return;
+			this.parts[existingIndex] = {
+				...existing,
+				...nextTool
+			};
+			return;
+		}
+		this.toolIndex.set(nextTool.toolCallId, this.parts.length);
+		this.parts.push({
+			type: "tool-invocation",
+			...nextTool
+		});
+	};
+	readToolArgs = (toolCallId) => {
+		return this.findTool(toolCallId)?.args ?? "";
+	};
+	readToolName = (toolCallId) => {
+		return this.findTool(toolCallId)?.toolName ?? "unknown";
+	};
+	findTool = (toolCallId) => {
+		const index = this.toolIndex.get(toolCallId);
+		if (typeof index !== "number") return null;
+		const part = this.parts[index];
+		return part?.type === "tool-invocation" ? part : null;
+	};
+};
+var StdioRuntimeClientBridge = class {
+	activeSessionId = null;
+	updateHandler = null;
+	attach = (params) => {
+		this.activeSessionId = params.sessionId;
+		this.updateHandler = params.onUpdate;
+		return () => {
+			if (this.activeSessionId !== params.sessionId) return;
+			this.activeSessionId = null;
+			this.updateHandler = null;
+		};
+	};
+	sessionUpdate = async (params) => {
+		if (params.sessionId !== this.activeSessionId) return;
+		this.updateHandler?.(params.update);
+	};
+	requestPermission = async () => ({ outcome: { outcome: "cancelled" } });
+	readTextFile = async () => ({ content: "" });
+	writeTextFile = async () => ({});
+};
+var StdioRuntimeSession = class {
+	child = null;
+	connection = null;
+	promptInFlight = false;
+	remoteSessionId = null;
+	clientBridge = new StdioRuntimeClientBridge();
+	stderr = "";
+	pendingProviderRoute;
+	constructor(config, sessionId) {
+		this.config = config;
+		this.sessionId = sessionId;
+	}
+	ensureStarted = async (params) => {
+		this.pendingProviderRoute = params?.providerRoute;
+		if (this.connection && this.remoteSessionId) return;
+		const env = buildStdioLaunchEnv({
+			config: this.config,
+			providerRoute: this.pendingProviderRoute
+		});
+		this.child = spawn(this.config.command, this.config.args, {
+			cwd: this.config.cwd,
+			env,
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			]
+		});
+		const spawnErrorPromise = new Promise((_, reject) => {
+			this.child?.once("error", (error) => {
+				reject(new Error(buildSpawnFailureMessage({
+					command: this.config.command,
+					cwd: this.config.cwd,
+					error
+				})));
+			});
+		});
+		this.child.stderr.setEncoding("utf8");
+		this.child.stderr.on("data", (chunk) => {
+			this.stderr = `${this.stderr}${chunk}`.slice(-4e3);
+		});
+		const stream = acp.ndJsonStream(Writable.toWeb(this.child.stdin), Readable.toWeb(this.child.stdout));
+		this.connection = new acp.ClientSideConnection(() => this.clientBridge, stream);
+		this.remoteSessionId = (await Promise.race([(async () => {
+			await withTimeout(this.connection?.initialize({
+				protocolVersion: acp.PROTOCOL_VERSION,
+				clientCapabilities: {}
+			}) ?? Promise.reject(/* @__PURE__ */ new Error("[narp-stdio] stdio runtime connection not started")), this.config.startupTimeoutMs, `[narp-stdio] timed out initializing stdio runtime for session ${this.sessionId}`);
+			return withTimeout(this.connection?.newSession({
+				cwd: this.config.cwd ?? process.cwd(),
+				mcpServers: []
+			}) ?? Promise.reject(/* @__PURE__ */ new Error("[narp-stdio] stdio runtime connection not started")), this.config.startupTimeoutMs, `[narp-stdio] timed out creating remote session for ${this.sessionId}`);
+		})(), spawnErrorPromise])).sessionId;
+	};
+	runPrompt = async (params) => {
+		const { meta, modelId, onUpdate, signal, text } = params;
+		if (!this.connection || !this.remoteSessionId) throw new Error("[narp-stdio] stdio runtime connection not started");
+		if (this.promptInFlight) throw new Error("[narp-stdio] concurrent prompt is not supported for one stdio session");
+		this.promptInFlight = true;
+		const detach = this.clientBridge.attach({
+			sessionId: this.remoteSessionId,
+			onUpdate
+		});
+		const releaseAbort = this.bindAbortSignal(signal);
+		try {
+			if (modelId) try {
+				await this.connection.unstable_setSessionModel({
+					sessionId: this.remoteSessionId,
+					modelId
+				});
+			} catch {}
+			return await withTimeout(this.connection.prompt({
+				sessionId: this.remoteSessionId,
+				prompt: [{
+					type: "text",
+					text
+				}],
+				_meta: { [NARP_STDIO_PROMPT_META_KEY]: meta }
+			}), this.config.requestTimeoutMs, `[narp-stdio] prompt timed out for session ${this.sessionId}`);
+		} finally {
+			releaseAbort();
+			detach();
+			this.promptInFlight = false;
+		}
+	};
+	cancel = async () => {
+		if (!this.connection || !this.remoteSessionId) return;
+		try {
+			await this.connection.cancel({ sessionId: this.remoteSessionId });
+		} catch {}
+	};
+	bindAbortSignal = (signal) => {
+		if (!signal) return () => void 0;
+		const onAbort = () => {
+			this.cancel();
+		};
+		if (signal.aborted) {
+			onAbort();
+			return () => void 0;
+		}
+		signal.addEventListener("abort", onAbort, { once: true });
+		return () => {
+			signal.removeEventListener("abort", onAbort);
+		};
+	};
+	readStderr = () => this.stderr;
+};
+function buildSpawnFailureMessage(params) {
+	const cwdSuffix = params.cwd ? ` (cwd: ${params.cwd})` : "";
+	return `[narp-stdio] failed to start stdio runtime command "${params.command}"${cwdSuffix}: ${params.error.message}`;
+}
+var StdioRuntimeRunController = class {
+	buffer = new UpdateBuffer();
+	collector = new PromptUpdateCollector();
+	toolStates = /* @__PURE__ */ new Map();
+	textStarted = false;
+	reasoningStarted = false;
+	resolvedTools;
+	resolvedProviderRoute;
+	constructor(session, input, stateManager, resolveTools, resolveProviderRoute) {
+		this.session = session;
+		this.input = input;
+		this.stateManager = stateManager;
+		this.resolveTools = resolveTools;
+		this.resolveProviderRoute = resolveProviderRoute;
+		this.resolvedTools = resolveTools?.(input) ?? [];
+		this.resolvedProviderRoute = resolveProviderRoute?.(input);
+	}
+	execute = async function* (options) {
+		const requestMessage = this.input.messages.at(-1);
+		if (!requestMessage) throw new Error("[narp-stdio] runtime.run requires at least one input message");
+		const assistantMessageId = createAssistantMessageId(requestMessage.id);
+		const promptPromise = this.session.runPrompt({
+			text: extractPromptText(requestMessage),
+			meta: {
+				...this.input.correlationId ? { correlationId: this.input.correlationId } : {},
+				...this.resolvedProviderRoute ? { providerRoute: this.resolvedProviderRoute } : {},
+				...this.input.metadata ? { sessionMetadata: this.input.metadata } : {},
+				...this.resolvedTools.length > 0 ? { tools: this.resolvedTools } : {}
+			},
+			modelId: resolveModelId({
+				providerRoute: this.resolvedProviderRoute,
+				metadata: this.input.metadata
+			}),
+			signal: options?.signal,
+			onUpdate: (update) => this.buffer.push(update)
+		});
+		let promptSettled = false;
+		let promptError = null;
+		promptPromise.then(() => {
+			promptSettled = true;
+			this.buffer.notify();
+		}).catch((error) => {
+			promptSettled = true;
+			promptError = error;
+			this.buffer.notify();
+		});
+		yield* this.emitEvent({
+			type: NcpEventType.MessageAccepted,
+			payload: {
+				messageId: assistantMessageId,
+				...this.input.correlationId ? { correlationId: this.input.correlationId } : {}
+			}
+		});
+		yield* this.emitEvent({
+			type: NcpEventType.RunStarted,
+			payload: {
+				sessionId: this.input.sessionId,
+				messageId: assistantMessageId,
+				runId: `narp-stdio:${this.input.sessionId}:${Date.now()}`
+			}
+		});
+		try {
+			while (!promptSettled || this.buffer.hasItems()) {
+				const update = this.buffer.shift();
+				if (!update) {
+					await this.buffer.waitForChange();
+					continue;
+				}
+				for (const event of this.translateUpdate(update, assistantMessageId)) yield* this.emitEvent(event);
+			}
+			if (promptError) throw promptError;
+			if (options?.signal?.aborted) throw createNcpError("abort-error", "ACP prompt cancelled");
+			for (const terminalEvent of this.createTerminalEvents(assistantMessageId)) yield* this.emitEvent(terminalEvent);
+			if (!this.collector.hasParts()) throw new Error(`[narp-stdio] ACP prompt completed without any assistant content for session ${this.input.sessionId}. stderr=${this.session.readStderr()}`);
+			yield* this.emitEvent({
+				type: NcpEventType.MessageCompleted,
+				payload: {
+					sessionId: this.input.sessionId,
+					correlationId: this.input.correlationId,
+					message: {
+						id: assistantMessageId,
+						sessionId: this.input.sessionId,
+						role: "assistant",
+						status: "final",
+						parts: this.collector.buildParts(),
+						timestamp: (/* @__PURE__ */ new Date()).toISOString()
+					}
+				}
+			});
+			yield* this.emitEvent({
+				type: NcpEventType.RunFinished,
+				payload: {
+					sessionId: this.input.sessionId,
+					messageId: assistantMessageId,
+					runId: `narp-stdio:${this.input.sessionId}`
+				}
+			});
+		} catch (error) {
+			const ncpError = normalizeRuntimeError(error);
+			yield* this.emitEvent({
+				type: NcpEventType.MessageFailed,
+				payload: {
+					sessionId: this.input.sessionId,
+					messageId: assistantMessageId,
+					correlationId: this.input.correlationId,
+					error: ncpError
+				}
+			});
+			yield* this.emitEvent({
+				type: NcpEventType.RunError,
+				payload: {
+					sessionId: this.input.sessionId,
+					messageId: assistantMessageId,
+					runId: `narp-stdio:${this.input.sessionId}`,
+					error: ncpError.message
+				}
+			});
+		}
+	};
+	emitEvent = async function* (event) {
+		this.collector.apply(event);
+		await this.stateManager?.dispatch(event);
+		yield event;
+	};
+	translateUpdate = (update, messageId) => {
+		switch (update.sessionUpdate) {
+			case "agent_message_chunk": return this.emitTextDelta(update.content, messageId);
+			case "agent_thought_chunk": return this.emitReasoningDelta(update.content, messageId);
+			case "tool_call": return this.emitToolCallStart(update, messageId);
+			case "tool_call_update": return this.emitToolCallUpdate(update);
+			default: return [];
+		}
+	};
+	emitTextDelta = (content, messageId) => {
+		if (content.type !== "text" || !content.text) return [];
+		const events = [];
+		if (!this.textStarted) {
+			this.textStarted = true;
+			events.push({
+				type: NcpEventType.MessageTextStart,
+				payload: {
+					sessionId: this.input.sessionId,
+					messageId
+				}
+			});
+		}
+		events.push({
+			type: NcpEventType.MessageTextDelta,
+			payload: {
+				sessionId: this.input.sessionId,
+				messageId,
+				delta: content.text
+			}
+		});
+		return events;
+	};
+	emitReasoningDelta = (content, messageId) => {
+		if (content.type !== "text" || !content.text) return [];
+		const events = [];
+		if (!this.reasoningStarted) {
+			this.reasoningStarted = true;
+			events.push({
+				type: NcpEventType.MessageReasoningStart,
+				payload: {
+					sessionId: this.input.sessionId,
+					messageId
+				}
+			});
+		}
+		events.push({
+			type: NcpEventType.MessageReasoningDelta,
+			payload: {
+				sessionId: this.input.sessionId,
+				messageId,
+				delta: content.text
+			}
+		});
+		return events;
+	};
+	emitToolCallStart = (update, messageId) => {
+		const toolName = resolveToolName(update);
+		const args = serializeToolArgs(update.rawInput);
+		this.toolStates.set(update.toolCallId, {
+			toolName,
+			args,
+			completed: false
+		});
+		return [{
+			type: NcpEventType.MessageToolCallStart,
+			payload: {
+				sessionId: this.input.sessionId,
+				messageId,
+				toolCallId: update.toolCallId,
+				toolName
+			}
+		}, {
+			type: NcpEventType.MessageToolCallArgs,
+			payload: {
+				sessionId: this.input.sessionId,
+				toolCallId: update.toolCallId,
+				args
+			}
+		}];
+	};
+	emitToolCallUpdate = (update) => {
+		const existing = this.toolStates.get(update.toolCallId);
+		if (!existing) return [];
+		const nextArgs = serializeToolArgs(update.rawInput);
+		const argsChanged = typeof update.rawInput !== "undefined" && nextArgs !== existing.args;
+		const events = [];
+		if (argsChanged) {
+			existing.args = nextArgs;
+			events.push({
+				type: NcpEventType.MessageToolCallArgs,
+				payload: {
+					sessionId: this.input.sessionId,
+					toolCallId: update.toolCallId,
+					args: nextArgs
+				}
+			});
+		}
+		if (update.status === "completed" || update.status === "failed") {
+			if (!existing.completed) {
+				existing.completed = true;
+				events.push({
+					type: NcpEventType.MessageToolCallEnd,
+					payload: {
+						sessionId: this.input.sessionId,
+						toolCallId: update.toolCallId
+					}
+				});
+			}
+			if (typeof update.rawOutput !== "undefined") events.push({
+				type: NcpEventType.MessageToolCallResult,
+				payload: {
+					sessionId: this.input.sessionId,
+					toolCallId: update.toolCallId,
+					content: update.rawOutput
+				}
+			});
+		}
+		return events;
+	};
+	createTerminalEvents = (messageId) => {
+		const events = [];
+		if (this.textStarted) {
+			events.push({
+				type: NcpEventType.MessageTextEnd,
+				payload: {
+					sessionId: this.input.sessionId,
+					messageId
+				}
+			});
+			this.textStarted = false;
+		}
+		if (this.reasoningStarted) {
+			events.push({
+				type: NcpEventType.MessageReasoningEnd,
+				payload: {
+					sessionId: this.input.sessionId,
+					messageId
+				}
+			});
+			this.reasoningStarted = false;
+		}
+		for (const [toolCallId, state] of this.toolStates.entries()) {
+			if (state.completed) continue;
+			events.push({
+				type: NcpEventType.MessageToolCallEnd,
+				payload: {
+					sessionId: this.input.sessionId,
+					toolCallId
+				}
+			});
+			state.completed = true;
+		}
+		return events;
+	};
+};
+var StdioRuntimeNcpAgentRuntime = class {
+	session;
+	constructor(config) {
+		this.config = config;
+		this.session = new StdioRuntimeSession(config, config.sessionId);
+	}
+	run = async function* (input, options) {
+		await this.session.ensureStarted({ providerRoute: this.config.resolveProviderRoute?.(input) });
+		yield* new StdioRuntimeRunController(this.session, input, this.config.stateManager, this.config.resolveTools, this.config.resolveProviderRoute).execute(options);
+	};
+};
+function extractPromptText(message) {
+	const text = (message.parts ?? []).map((part) => {
+		if (part.type === "text" || part.type === "reasoning" || part.type === "rich-text") return part.text ?? "";
+		return "";
+	}).join("\n").trim();
+	return text.length > 0 ? text : "[empty message]";
+}
+function resolveModelId(params) {
+	const { metadata, providerRoute } = params;
+	return providerRoute?.model ?? readString(metadata?.preferred_model) ?? readString(metadata?.preferredModel) ?? readString(metadata?.model);
+}
+function resolveToolName(update) {
+	if (typeof update.rawInput === "object" && update.rawInput && !Array.isArray(update.rawInput)) {
+		const candidate = readString(update.rawInput.toolName) ?? readString(update.rawInput.tool);
+		if (candidate) return candidate;
+	}
+	return readString(update.title) ?? "unknown";
+}
+function createAssistantMessageId(requestMessageId) {
+	return `assistant:${requestMessageId.trim() || "request"}:${randomUUID()}`;
+}
+function serializeToolArgs(value) {
+	if (typeof value === "string") return value;
+	if (typeof value === "undefined") return "{}";
+	return JSON.stringify(value);
+}
+function normalizeRuntimeError(error) {
+	if (isNcpError(error)) return error;
+	const message = error instanceof Error ? error.message : String(error);
+	const lowered = message.toLowerCase();
+	return {
+		code: lowered.includes("abort") || lowered.includes("cancel") ? "abort-error" : "runtime-error",
+		message
+	};
+}
+function createNcpError(code, message) {
+	return {
+		code,
+		message
+	};
+}
+function isNcpError(value) {
+	if (!value || typeof value !== "object") return false;
+	return typeof value.code === "string" && typeof value.message === "string";
+}
+async function withTimeout(promise, timeoutMs, message) {
+	let timeoutHandle = null;
+	try {
+		return await Promise.race([promise, new Promise((_, reject) => {
+			timeoutHandle = setTimeout(() => {
+				reject(new Error(message));
+			}, timeoutMs);
+		})]);
+	} finally {
+		if (timeoutHandle) clearTimeout(timeoutHandle);
+	}
+}
+//#endregion
+export { StdioRuntimeNcpAgentRuntime };

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@nextclaw/nextclaw-ncp-runtime-stdio-client",
+  "version": "0.1.1",
+  "private": false,
+  "description": "Optional NCP runtime adapter backed by a protocol-aware stdio agent command.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@agentclientprotocol/sdk": "^0.19.0",
+    "@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"
+  }
+}