@nextclaw/nextclaw-ncp-runtime-adapter-hermes-http 0.1.1

package/dist/hermes-http-adapter.service.js

@@ -0,0 +1,454 @@
+import { HermesHttpAdapterConfigResolver } from "./hermes-http-adapter-config.utils.js";
+import { HermesAssistantEventCollector, HermesInlineToolTraceTranslator, HermesReasoningDeltaTranslator, buildHermesMessages, createAssistantMessageFromParts, inferHermesProvider, normalizeHermesRequestedModel, readHermesProviderRoute, resolveHermesModel, toErrorSseFrame, toNcpError, toNcpSseFrame } from "./hermes-http-adapter-message.utils.js";
+import { parseHermesOpenAIChatStream } from "./hermes-openai-stream-parser.utils.js";
+import { HermesHttpAdapterSessionStore } from "./hermes-http-adapter-session-store.service.js";
+import { createServer } from "node:http";
+import { randomUUID } from "node:crypto";
+import { DefaultNcpStreamEncoder } from "@nextclaw/ncp-agent-runtime";
+import { NcpEventType } from "@nextclaw/ncp";
+//#region src/hermes-http-adapter.service.ts
+function isUserVisibleAssistantEvent(event) {
+	const eventType = event.type;
+	return eventType.startsWith("message.text-") || eventType.startsWith("message.reasoning-") || eventType.startsWith("message.tool-call-");
+}
+var HermesHttpAdapterRouteService = class {
+	sessions = new HermesHttpAdapterSessionStore();
+	streamEncoder = new DefaultNcpStreamEncoder({ reasoningNormalizationMode: "think-tags" });
+	fetchImpl;
+	constructor(config, buildAssistantMessage = createAssistantMessageFromParts) {
+		this.config = config;
+		this.buildAssistantMessage = buildAssistantMessage;
+		this.fetchImpl = config.fetchImpl ?? fetch;
+	}
+	handle = async (request, response) => {
+		const requestUrl = new URL(request.url ?? "/", this.baseOrigin);
+		const normalizedPath = requestUrl.pathname;
+		if (request.method === "GET" && normalizedPath === "/health") {
+			await this.handleHealth(response);
+			return;
+		}
+		if (request.method === "POST" && normalizedPath === `${this.config.basePath}/send`) {
+			await this.handleSend(request, response);
+			return;
+		}
+		if (request.method === "GET" && normalizedPath === `${this.config.basePath}/stream`) {
+			await this.handleStream(request, response, requestUrl);
+			return;
+		}
+		if (request.method === "POST" && normalizedPath === `${this.config.basePath}/abort`) {
+			await this.handleAbort(request, response);
+			return;
+		}
+		this.writeJson(response, 404, {
+			ok: false,
+			error: {
+				code: "NOT_FOUND",
+				message: `Unknown path: ${normalizedPath}`
+			}
+		});
+	};
+	dispose = () => {
+		this.sessions.dispose();
+	};
+	get baseOrigin() {
+		return `http://${this.config.host}:${this.config.port}`;
+	}
+	handleHealth = async (response) => {
+		const controller = new AbortController();
+		const timeout = setTimeout(() => controller.abort(), this.config.healthcheckTimeoutMs);
+		try {
+			const upstream = await this.fetchImpl(this.config.healthcheckUrl, {
+				method: "GET",
+				signal: controller.signal
+			});
+			if (!upstream.ok) {
+				this.writeJson(response, 503, {
+					status: "degraded",
+					adapter: "ok",
+					upstream: {
+						status: "error",
+						httpStatus: upstream.status
+					}
+				});
+				return;
+			}
+			this.writeJson(response, 200, {
+				status: "ok",
+				adapter: "ok",
+				upstream: "ok"
+			});
+		} catch (error) {
+			this.writeJson(response, 503, {
+				status: "degraded",
+				adapter: "ok",
+				upstream: {
+					status: "unreachable",
+					message: error instanceof Error ? error.message : String(error)
+				}
+			});
+		} finally {
+			clearTimeout(timeout);
+		}
+	};
+	handleSend = async (request, response) => {
+		try {
+			const envelope = await this.readJsonBody(request);
+			if (!envelope?.sessionId || !envelope.message) {
+				this.writeJson(response, 400, {
+					ok: false,
+					error: {
+						code: "INVALID_BODY",
+						message: "sessionId and message are required."
+					}
+				});
+				return;
+			}
+			const run = {
+				envelope,
+				messageId: randomUUID(),
+				runId: randomUUID()
+			};
+			this.sessions.setPendingRun(run);
+			this.writeJson(response, 200, { ok: true });
+		} catch (error) {
+			this.writeJson(response, 409, {
+				ok: false,
+				error: {
+					code: "RUN_CONFLICT",
+					message: error instanceof Error ? error.message : String(error)
+				}
+			});
+		}
+	};
+	handleAbort = async (request, response) => {
+		try {
+			const payload = await this.readJsonBody(request);
+			const sessionId = typeof payload?.sessionId === "string" ? payload.sessionId : "";
+			if (!sessionId.trim()) {
+				this.writeJson(response, 400, {
+					ok: false,
+					error: {
+						code: "INVALID_BODY",
+						message: "sessionId is required."
+					}
+				});
+				return;
+			}
+			const aborted = this.sessions.abortSession(sessionId);
+			this.writeJson(response, 200, {
+				ok: true,
+				aborted
+			});
+		} catch (error) {
+			this.writeJson(response, 500, {
+				ok: false,
+				error: {
+					code: "ABORT_FAILED",
+					message: error instanceof Error ? error.message : String(error)
+				}
+			});
+		}
+	};
+	handleStream = async (request, response, requestUrl) => {
+		const sessionId = requestUrl.searchParams.get("sessionId")?.trim();
+		if (!sessionId) {
+			this.writeJson(response, 400, {
+				ok: false,
+				error: {
+					code: "INVALID_QUERY",
+					message: "sessionId is required."
+				}
+			});
+			return;
+		}
+		const connectionController = new AbortController();
+		const runController = new AbortController();
+		response.once("close", () => {
+			connectionController.abort("client disconnected");
+			runController.abort("client disconnected");
+		});
+		response.writeHead(200, {
+			"content-type": "text/event-stream; charset=utf-8",
+			"cache-control": "no-cache, no-transform",
+			connection: "keep-alive",
+			"x-accel-buffering": "no"
+		});
+		try {
+			const run = await this.sessions.waitForPendingRun(sessionId, connectionController.signal, this.config.streamWaitTimeoutMs);
+			this.sessions.setActiveAbortController(sessionId, runController);
+			const streamResult = await this.startRun({
+				run,
+				signal: runController.signal
+			});
+			for await (const event of streamResult.events) {
+				if (connectionController.signal.aborted) break;
+				response.write(toNcpSseFrame(event));
+			}
+		} catch (error) {
+			if (!connectionController.signal.aborted) response.write(toErrorSseFrame({
+				code: "STREAM_FAILED",
+				message: error instanceof Error ? error.message : String(error)
+			}));
+		} finally {
+			this.sessions.clearActiveAbortController(sessionId);
+			response.end();
+		}
+	};
+	startRun = async (params) => {
+		const { run, signal } = params;
+		const providerRoute = this.readProviderRoute(run.envelope);
+		const requestedModel = normalizeHermesRequestedModel(resolveHermesModel({
+			envelope: run.envelope,
+			fallbackModel: this.config.model
+		}));
+		if (!providerRoute) await this.ensureHermesSessionModel({
+			sessionId: run.envelope.sessionId,
+			requestedModel,
+			signal
+		});
+		const response = await this.fetchHermesChatCompletion({
+			sessionId: run.envelope.sessionId,
+			signal,
+			stream: true,
+			model: requestedModel,
+			providerRoute,
+			messages: buildHermesMessages({
+				envelope: run.envelope,
+				systemPrompt: this.config.systemPrompt
+			}),
+			tools: run.envelope.tools
+		});
+		if (!response.body) throw new Error("[hermes-http-adapter] Hermes stream response body is missing.");
+		this.sessions.setSelectedModel(run.envelope.sessionId, requestedModel);
+		return { events: this.createRunEvents({
+			response,
+			run,
+			signal
+		}) };
+	};
+	createRunEvents = async function* (params) {
+		const { response, run, signal } = params;
+		const sessionId = run.envelope.sessionId;
+		this.readProviderRoute(run.envelope);
+		const metadata = { hermesModel: normalizeHermesRequestedModel(resolveHermesModel({
+			envelope: run.envelope,
+			fallbackModel: this.config.model
+		})) };
+		let emittedUserVisibleAssistantEvent = false;
+		const messageCollector = new HermesAssistantEventCollector();
+		const inlineToolTraceTranslator = new HermesInlineToolTraceTranslator();
+		const reasoningDeltaTranslator = new HermesReasoningDeltaTranslator();
+		yield {
+			type: NcpEventType.MessageAccepted,
+			payload: {
+				messageId: run.messageId,
+				correlationId: run.envelope.correlationId
+			}
+		};
+		yield {
+			type: NcpEventType.RunStarted,
+			payload: {
+				sessionId,
+				messageId: run.messageId,
+				runId: run.runId
+			}
+		};
+		try {
+			for await (const event of reasoningDeltaTranslator.translate(inlineToolTraceTranslator.translate(this.streamEncoder.encode(parseHermesOpenAIChatStream(response.body), {
+				sessionId,
+				messageId: run.messageId,
+				runId: run.runId,
+				correlationId: run.envelope.correlationId
+			})))) {
+				messageCollector.applyEvent(event);
+				if (isUserVisibleAssistantEvent(event)) emittedUserVisibleAssistantEvent = true;
+				yield event;
+			}
+			if (!emittedUserVisibleAssistantEvent || !messageCollector.hasParts()) throw new Error(`[hermes-http-adapter] Hermes completed without any assistant content for session ${sessionId}.`);
+			const message = this.buildAssistantMessage({
+				sessionId,
+				messageId: run.messageId,
+				parts: messageCollector.buildParts(),
+				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+				metadata
+			});
+			yield {
+				type: NcpEventType.MessageCompleted,
+				payload: {
+					sessionId,
+					message,
+					correlationId: run.envelope.correlationId,
+					metadata
+				}
+			};
+			yield {
+				type: NcpEventType.RunFinished,
+				payload: {
+					sessionId,
+					messageId: run.messageId,
+					runId: run.runId
+				}
+			};
+		} catch (error) {
+			if (signal.aborted) {
+				const abortError = toNcpError(error, "abort-error");
+				yield {
+					type: NcpEventType.MessageFailed,
+					payload: {
+						sessionId,
+						messageId: run.messageId,
+						correlationId: run.envelope.correlationId,
+						error: abortError
+					}
+				};
+				yield {
+					type: NcpEventType.RunError,
+					payload: {
+						sessionId,
+						messageId: run.messageId,
+						runId: run.runId,
+						error: abortError.message
+					}
+				};
+				return;
+			}
+			const runtimeError = toNcpError(error, "runtime-error");
+			yield {
+				type: NcpEventType.MessageFailed,
+				payload: {
+					sessionId,
+					messageId: run.messageId,
+					correlationId: run.envelope.correlationId,
+					error: runtimeError
+				}
+			};
+			yield {
+				type: NcpEventType.RunError,
+				payload: {
+					sessionId,
+					messageId: run.messageId,
+					runId: run.runId,
+					error: runtimeError.message
+				}
+			};
+		}
+	};
+	ensureHermesSessionModel = async (params) => {
+		const { requestedModel, sessionId, signal } = params;
+		if ((this.sessions.readSelectedModel(sessionId) ?? this.config.model) === requestedModel) return;
+		const response = await this.fetchHermesChatCompletion({
+			sessionId,
+			signal,
+			stream: false,
+			model: requestedModel,
+			messages: [{
+				role: "user",
+				content: `/model ${requestedModel}`
+			}]
+		});
+		const content = (await this.readJsonResponse(response)).choices?.[0]?.message?.content;
+		if (typeof content === "string" && content.trim().startsWith("Error:")) throw new Error(`[hermes-http-adapter] failed to switch Hermes model to ${requestedModel}: ${content.trim()}`);
+		this.sessions.setSelectedModel(sessionId, requestedModel);
+	};
+	fetchHermesChatCompletion = async (params) => {
+		const { messages, model, providerRoute, sessionId, signal, stream, tools } = params;
+		const headers = new Headers({
+			"content-type": "application/json",
+			accept: stream ? "text/event-stream" : "application/json"
+		});
+		if (this.config.hermesApiKey) headers.set("authorization", `Bearer ${this.config.hermesApiKey}`);
+		const hermesSessionId = this.sessions.readHermesSessionId(sessionId);
+		if (hermesSessionId) headers.set("x-hermes-session-id", hermesSessionId);
+		const response = await this.fetchImpl(this.config.chatCompletionsUrl, {
+			method: "POST",
+			headers,
+			signal,
+			body: JSON.stringify({
+				model,
+				stream,
+				messages,
+				...providerRoute ? { nextclaw_provider_route: this.toHermesProviderRoutePayload(providerRoute) } : {},
+				...tools && tools.length > 0 ? { tools } : {}
+			})
+		});
+		if (!response.ok) throw new Error(`[hermes-http-adapter] Hermes request failed with HTTP ${response.status}.`);
+		const returnedSessionId = response.headers.get("x-hermes-session-id")?.trim();
+		if (returnedSessionId) this.sessions.setHermesSessionId(sessionId, returnedSessionId);
+		return response;
+	};
+	readProviderRoute = (envelope) => {
+		const providerRoute = readHermesProviderRoute(envelope);
+		if (!providerRoute) return;
+		if (!providerRoute.apiBase) throw new Error(`[hermes-http-adapter] missing provider apiBase for model "${providerRoute.model}". Configure the selected NextClaw provider before using Hermes.`);
+		return providerRoute;
+	};
+	toHermesProviderRoutePayload = (providerRoute) => {
+		const inferredProvider = inferHermesProvider(providerRoute);
+		return {
+			model: providerRoute.model,
+			...inferredProvider ? { provider: inferredProvider } : {},
+			...providerRoute.apiKey ? { api_key: providerRoute.apiKey } : {},
+			...providerRoute.apiBase ? { base_url: providerRoute.apiBase } : {},
+			...providerRoute.apiMode ? { api_mode: providerRoute.apiMode } : {},
+			...Object.keys(providerRoute.headers).length > 0 ? { extra_headers: providerRoute.headers } : {}
+		};
+	};
+	readJsonResponse = async (response) => {
+		try {
+			return await response.json();
+		} catch (error) {
+			throw new Error(`[hermes-http-adapter] expected JSON response from Hermes: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	};
+	readJsonBody = async (request) => {
+		const chunks = [];
+		for await (const chunk of request) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+		const body = Buffer.concat(chunks).toString("utf8");
+		if (!body.trim()) throw new Error("request body is empty");
+		return JSON.parse(body);
+	};
+	writeJson = (response, statusCode, payload) => {
+		response.writeHead(statusCode, { "content-type": "application/json; charset=utf-8" });
+		response.end(JSON.stringify(payload));
+	};
+};
+var HermesHttpAdapterServer = class {
+	config;
+	routeService;
+	server = null;
+	constructor(configInput = {}) {
+		this.config = new HermesHttpAdapterConfigResolver(configInput).resolve();
+		this.routeService = new HermesHttpAdapterRouteService(this.config);
+	}
+	start = async () => {
+		if (this.server) return;
+		const nextServer = createServer((request, response) => {
+			this.routeService.handle(request, response);
+		});
+		await new Promise((resolve, reject) => {
+			nextServer.once("error", reject);
+			nextServer.listen(this.config.port, this.config.host, () => {
+				nextServer.off("error", reject);
+				resolve();
+			});
+		});
+		this.server = nextServer;
+	};
+	stop = async () => {
+		this.routeService.dispose();
+		const activeServer = this.server;
+		if (!activeServer) return;
+		await new Promise((resolve, reject) => {
+			activeServer.close((error) => {
+				if (error) {
+					reject(error);
+					return;
+				}
+				resolve();
+			});
+		});
+		this.server = null;
+	};
+};
+//#endregion
+export { HermesHttpAdapterServer };

package/dist/hermes-http-adapter.types.d.ts

@@ -0,0 +1,26 @@
+import { NcpEndpointEvent, NcpMessage, NcpMessagePart, NcpRequestEnvelope } from "@nextclaw/ncp";
+
+//#region src/hermes-http-adapter.types.d.ts
+type HermesHttpAdapterFetchLike = (input: URL | string | Request, init?: RequestInit) => Promise<Response>;
+type HermesHttpAdapterConfig = {
+  host: string;
+  port: number;
+  basePath: string;
+  hermesBaseUrl: string;
+  hermesApiKey?: string;
+  model: string;
+  systemPrompt?: string;
+  streamWaitTimeoutMs: number;
+  healthcheckTimeoutMs: number;
+  fetchImpl?: HermesHttpAdapterFetchLike;
+};
+type HermesHttpAdapterResolvedConfig = HermesHttpAdapterConfig & {
+  chatCompletionsUrl: string;
+  healthcheckUrl: string;
+};
+type HermesOpenAIMessage = {
+  role: "system" | "user" | "assistant";
+  content: string;
+};
+//#endregion
+export { HermesHttpAdapterConfig, HermesHttpAdapterFetchLike, HermesHttpAdapterResolvedConfig, HermesOpenAIMessage };

package/dist/hermes-openai-stream-parser.utils.d.ts

@@ -0,0 +1,6 @@
+import { OpenAIChatChunk } from "@nextclaw/ncp";
+
+//#region src/hermes-openai-stream-parser.utils.d.ts
+declare function parseHermesOpenAIChatStream(stream: ReadableStream<Uint8Array>): AsyncGenerator<OpenAIChatChunk>;
+//#endregion
+export { parseHermesOpenAIChatStream };

package/dist/hermes-openai-stream-parser.utils.js

@@ -0,0 +1,54 @@
+//#region src/hermes-openai-stream-parser.utils.ts
+async function* parseHermesOpenAIChatStream(stream) {
+	for await (const frame of consumeSseFrames(stream)) {
+		const payload = frame.data.trim();
+		if (!payload || payload === "[DONE]") continue;
+		yield JSON.parse(payload);
+	}
+}
+async function* consumeSseFrames(stream) {
+	const reader = stream.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+	try {
+		while (true) {
+			const { value, done } = await reader.read();
+			if (done) break;
+			buffer += decoder.decode(value, { stream: true });
+			const drained = drainSseFrames(buffer);
+			buffer = drained.rest;
+			for (const frame of drained.frames) yield frame;
+		}
+		buffer += decoder.decode();
+		const drained = drainSseFrames(buffer, true);
+		for (const frame of drained.frames) yield frame;
+	} finally {
+		reader.releaseLock();
+	}
+}
+function drainSseFrames(rawBuffer, flush = false) {
+	const parts = rawBuffer.split(/\r?\n\r?\n/u);
+	const rest = parts.pop() ?? "";
+	const frames = parts.map(parseSseFrame).filter((frame) => Boolean(frame));
+	if (!flush || !rest.trim()) return {
+		frames,
+		rest
+	};
+	const finalFrame = parseSseFrame(rest);
+	return {
+		frames: finalFrame ? [...frames, finalFrame] : frames,
+		rest: ""
+	};
+}
+function parseSseFrame(frameText) {
+	const dataLines = [];
+	for (const rawLine of frameText.split(/\r?\n/u)) {
+		const line = rawLine.trimEnd();
+		if (!line || line.startsWith(":") || !line.startsWith("data:")) continue;
+		dataLines.push(line.slice(5).trimStart());
+	}
+	if (dataLines.length === 0) return null;
+	return { data: dataLines.join("\n") };
+}
+//#endregion
+export { parseHermesOpenAIChatStream };

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { HermesHttpAdapterConfig, HermesHttpAdapterFetchLike, HermesHttpAdapterResolvedConfig } from "./hermes-http-adapter.types.js";
+import { HermesHttpAdapterConfigInput, HermesHttpAdapterConfigResolver, normalizeBasePath, resolveHermesApiUrl, resolveHermesHealthcheckUrl } from "./hermes-http-adapter-config.utils.js";
+import { HermesHttpAdapterServer } from "./hermes-http-adapter.service.js";
+import { HermesAssistantEventCollector, HermesInlineToolTraceTranslator, HermesProviderRoute, HermesReasoningDeltaTranslator, buildHermesMessages, createAssistantMessage, createAssistantMessageFromParts, inferHermesProvider, normalizeHermesRequestedModel, readHermesProviderRoute, resolveHermesModel, toErrorSseFrame, toNcpError, toNcpSseFrame } from "./hermes-http-adapter-message.utils.js";
+import { parseHermesOpenAIChatStream } from "./hermes-openai-stream-parser.utils.js";
+export { HermesAssistantEventCollector, type HermesHttpAdapterConfig, type HermesHttpAdapterConfigInput, HermesHttpAdapterConfigResolver, type HermesHttpAdapterFetchLike, type HermesHttpAdapterResolvedConfig, HermesHttpAdapterServer, HermesInlineToolTraceTranslator, type HermesProviderRoute, HermesReasoningDeltaTranslator, buildHermesMessages, createAssistantMessage, createAssistantMessageFromParts, inferHermesProvider, normalizeBasePath, normalizeHermesRequestedModel, parseHermesOpenAIChatStream, readHermesProviderRoute, resolveHermesApiUrl, resolveHermesHealthcheckUrl, resolveHermesModel, toErrorSseFrame, toNcpError, toNcpSseFrame };

package/dist/index.js

@@ -0,0 +1,5 @@
+import { HermesHttpAdapterConfigResolver, normalizeBasePath, resolveHermesApiUrl, resolveHermesHealthcheckUrl } from "./hermes-http-adapter-config.utils.js";
+import { HermesAssistantEventCollector, HermesInlineToolTraceTranslator, HermesReasoningDeltaTranslator, buildHermesMessages, createAssistantMessage, createAssistantMessageFromParts, inferHermesProvider, normalizeHermesRequestedModel, readHermesProviderRoute, resolveHermesModel, toErrorSseFrame, toNcpError, toNcpSseFrame } from "./hermes-http-adapter-message.utils.js";
+import { parseHermesOpenAIChatStream } from "./hermes-openai-stream-parser.utils.js";
+import { HermesHttpAdapterServer } from "./hermes-http-adapter.service.js";
+export { HermesAssistantEventCollector, HermesHttpAdapterConfigResolver, HermesHttpAdapterServer, HermesInlineToolTraceTranslator, HermesReasoningDeltaTranslator, buildHermesMessages, createAssistantMessage, createAssistantMessageFromParts, inferHermesProvider, normalizeBasePath, normalizeHermesRequestedModel, parseHermesOpenAIChatStream, readHermesProviderRoute, resolveHermesApiUrl, resolveHermesHealthcheckUrl, resolveHermesModel, toErrorSseFrame, toNcpError, toNcpSseFrame };

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@nextclaw/nextclaw-ncp-runtime-adapter-hermes-http",
+  "version": "0.1.1",
+  "private": false,
+  "description": "Standalone NCP HTTP adapter server that bridges NextClaw http-runtime sessions to Hermes API Server.",
+  "type": "module",
+  "bin": {
+    "nextclaw-hermes-http-adapter": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@nextclaw/ncp-agent-runtime": "0.3.12",
+    "@nextclaw/ncp-http-agent-client": "0.3.14",
+    "@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 src/cli.ts --dts --clean --target es2022 --no-fixedExtension --unbundle",
+    "lint": "eslint .",
+    "tsc": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  }
+}