@nextclaw/nextclaw-ncp-runtime-adapter-hermes-http 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,53 @@
+# NextClaw Hermes HTTP Adapter
+
+This package exposes a standalone NCP-over-HTTP adapter for Hermes API Server.
+
+It is intentionally not a Hermes-specific NextClaw runtime. NextClaw keeps using the generic `http-runtime` kind, while this server translates that runtime contract into Hermes' OpenAI-compatible `/v1/chat/completions` streaming API.
+
+## Start
+
+```bash
+pnpm -C packages/nextclaw-ncp-runtime-adapter-hermes-http build
+nextclaw-hermes-http-adapter \
+  --port 8765 \
+  --hermes-base-url http://127.0.0.1:8642 \
+  --api-key change-me-local-dev
+```
+
+Environment variables are also supported:
+
+```bash
+NEXTCLAW_HERMES_ADAPTER_PORT=8765
+HERMES_API_BASE_URL=http://127.0.0.1:8642
+HERMES_API_KEY=change-me-local-dev
+HERMES_MODEL=hermes-agent
+```
+
+## NextClaw Runtime Entry
+
+Point a `type: "narp-http"` runtime entry at this adapter:
+
+```json
+{
+  "label": "Hermes",
+  "type": "narp-http",
+  "config": {
+    "baseUrl": "http://127.0.0.1:8765",
+    "basePath": "/ncp/agent",
+    "healthcheckUrl": "http://127.0.0.1:8765/health",
+    "recommendedModel": "hermes-agent",
+    "supportedModels": ["hermes-agent"]
+  }
+}
+```
+
+## Contract
+
+The adapter exposes:
+
+- `GET /health`
+- `POST /ncp/agent/send`
+- `GET /ncp/agent/stream?sessionId=...`
+- `POST /ncp/agent/abort`
+
+Hermes conversation continuity is preserved through `X-Hermes-Session-Id`, stored per NextClaw `sessionId`.

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/cli.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import { HermesHttpAdapterServer } from "./hermes-http-adapter.service.js";
+//#region src/cli.ts
+var HermesHttpAdapterCli = class {
+	run = async () => {
+		const server = new HermesHttpAdapterServer(this.readArgs());
+		await server.start();
+		process.stdout.write(`[hermes-http-adapter] listening on http://${server.config.host}:${server.config.port}${server.config.basePath}\n`);
+		const shutdown = async () => {
+			await server.stop();
+			process.exit(0);
+		};
+		process.once("SIGINT", () => {
+			shutdown();
+		});
+		process.once("SIGTERM", () => {
+			shutdown();
+		});
+	};
+	readArgs = () => {
+		const args = process.argv.slice(2);
+		const config = {};
+		for (let index = 0; index < args.length; index += 1) {
+			const current = args[index];
+			if (!current?.startsWith("--")) continue;
+			const key = current.slice(2);
+			const nextValue = args[index + 1];
+			if (!nextValue || nextValue.startsWith("--")) {
+				config[key] = true;
+				continue;
+			}
+			config[key] = nextValue;
+			index += 1;
+		}
+		return {
+			host: config.host,
+			port: config.port,
+			basePath: config["base-path"],
+			hermesBaseUrl: config["hermes-base-url"],
+			hermesApiKey: config["api-key"],
+			model: config.model,
+			systemPrompt: config["system-prompt"]
+		};
+	};
+};
+new HermesHttpAdapterCli().run();
+//#endregion
+export {};

package/dist/hermes-http-adapter-config.utils.d.ts

@@ -0,0 +1,16 @@
+import { HermesHttpAdapterConfig, HermesHttpAdapterFetchLike, HermesHttpAdapterResolvedConfig } from "./hermes-http-adapter.types.js";
+
+//#region src/hermes-http-adapter-config.utils.d.ts
+type HermesHttpAdapterConfigInput = Partial<Omit<HermesHttpAdapterConfig, "fetchImpl">> & {
+  fetchImpl?: HermesHttpAdapterFetchLike;
+};
+declare class HermesHttpAdapterConfigResolver {
+  private readonly source;
+  constructor(source?: HermesHttpAdapterConfigInput);
+  resolve: () => HermesHttpAdapterResolvedConfig;
+}
+declare function normalizeBasePath(value: string): string;
+declare function resolveHermesApiUrl(baseUrl: string, path: string): string;
+declare function resolveHermesHealthcheckUrl(baseUrl: string): string;
+//#endregion
+export { HermesHttpAdapterConfigInput, HermesHttpAdapterConfigResolver, normalizeBasePath, resolveHermesApiUrl, resolveHermesHealthcheckUrl };

package/dist/hermes-http-adapter-config.utils.js

@@ -0,0 +1,59 @@
+//#region src/hermes-http-adapter-config.utils.ts
+const DEFAULT_HOST = "127.0.0.1";
+const DEFAULT_PORT = 8765;
+const DEFAULT_BASE_PATH = "/ncp/agent";
+const DEFAULT_HERMES_BASE_URL = "http://127.0.0.1:8642";
+const DEFAULT_MODEL = "hermes-agent";
+const DEFAULT_STREAM_WAIT_TIMEOUT_MS = 15e3;
+const DEFAULT_HEALTHCHECK_TIMEOUT_MS = 3e3;
+var HermesHttpAdapterConfigResolver = class {
+	constructor(source = {}) {
+		this.source = source;
+	}
+	resolve = () => {
+		const basePath = normalizeBasePath(this.source.basePath ?? process.env.NEXTCLAW_HERMES_ADAPTER_BASE_PATH ?? DEFAULT_BASE_PATH);
+		const hermesBaseUrl = readString(this.source.hermesBaseUrl ?? process.env.HERMES_API_BASE_URL) ?? DEFAULT_HERMES_BASE_URL;
+		return {
+			host: readString(this.source.host ?? process.env.NEXTCLAW_HERMES_ADAPTER_HOST) ?? DEFAULT_HOST,
+			port: readPositiveInteger(this.source.port) ?? readPositiveInteger(process.env.NEXTCLAW_HERMES_ADAPTER_PORT) ?? DEFAULT_PORT,
+			basePath,
+			hermesBaseUrl,
+			hermesApiKey: readString(this.source.hermesApiKey ?? process.env.HERMES_API_KEY),
+			model: readString(this.source.model ?? process.env.HERMES_MODEL) ?? DEFAULT_MODEL,
+			systemPrompt: readString(this.source.systemPrompt ?? process.env.HERMES_SYSTEM_PROMPT),
+			streamWaitTimeoutMs: readPositiveInteger(this.source.streamWaitTimeoutMs) ?? readPositiveInteger(process.env.NEXTCLAW_HERMES_ADAPTER_STREAM_WAIT_TIMEOUT_MS) ?? DEFAULT_STREAM_WAIT_TIMEOUT_MS,
+			healthcheckTimeoutMs: readPositiveInteger(this.source.healthcheckTimeoutMs) ?? readPositiveInteger(process.env.NEXTCLAW_HERMES_ADAPTER_HEALTHCHECK_TIMEOUT_MS) ?? DEFAULT_HEALTHCHECK_TIMEOUT_MS,
+			...this.source.fetchImpl ? { fetchImpl: this.source.fetchImpl } : {},
+			chatCompletionsUrl: resolveHermesApiUrl(hermesBaseUrl, "chat/completions"),
+			healthcheckUrl: resolveHermesHealthcheckUrl(hermesBaseUrl)
+		};
+	};
+};
+function normalizeBasePath(value) {
+	const trimmed = value.trim();
+	if (!trimmed) return DEFAULT_BASE_PATH;
+	const withLeadingSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+	return withLeadingSlash.endsWith("/") ? withLeadingSlash.slice(0, -1) : withLeadingSlash;
+}
+function resolveHermesApiUrl(baseUrl, path) {
+	const normalizedBase = baseUrl.trim().replace(/\/+$/, "");
+	const normalizedPath = path.replace(/^\/+/, "");
+	return `${normalizedBase}${/\/v1$/u.test(normalizedBase) ? "" : "/v1"}/${normalizedPath}`;
+}
+function resolveHermesHealthcheckUrl(baseUrl) {
+	const normalizedBase = baseUrl.trim().replace(/\/+$/, "");
+	return `${normalizedBase.endsWith("/v1") ? normalizedBase.slice(0, -3) : normalizedBase}/health`;
+}
+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;
+}
+//#endregion
+export { HermesHttpAdapterConfigResolver, normalizeBasePath, resolveHermesApiUrl, resolveHermesHealthcheckUrl };

package/dist/hermes-http-adapter-message.utils.d.ts

@@ -0,0 +1,83 @@
+import { HermesOpenAIMessage } from "./hermes-http-adapter.types.js";
+import { NcpEndpointEvent, NcpError, NcpMessage, NcpMessagePart, NcpRequestEnvelope } from "@nextclaw/ncp";
+
+//#region src/hermes-http-adapter-message.utils.d.ts
+type HermesProviderRoute = {
+  model: string;
+  apiKey?: string;
+  apiBase?: string;
+  headers: Record<string, string>;
+  apiMode?: "chat_completions" | "codex_responses" | "anthropic_messages";
+};
+declare function readHermesProviderRoute(envelope: NcpRequestEnvelope): HermesProviderRoute | undefined;
+declare function buildHermesMessages(params: {
+  envelope: NcpRequestEnvelope;
+  systemPrompt?: string;
+}): HermesOpenAIMessage[];
+declare function createAssistantMessage(params: {
+  sessionId: string;
+  messageId: string;
+  text: string;
+  timestamp: string;
+  metadata?: Record<string, unknown>;
+}): NcpMessage;
+declare function createAssistantMessageFromParts(params: {
+  sessionId: string;
+  messageId: string;
+  parts: NcpMessagePart[];
+  timestamp: string;
+  metadata?: Record<string, unknown>;
+}): NcpMessage;
+declare class HermesAssistantEventCollector {
+  private readonly parts;
+  private readonly toolPartIndexByCallId;
+  applyEvent: (event: NcpEndpointEvent) => void;
+  hasParts: () => boolean;
+  buildParts: () => NcpMessagePart[];
+  private appendTextPart;
+  private appendReasoningPart;
+  private applyToolCallArgsDelta;
+  private upsertToolInvocationPart;
+  private readToolArgs;
+  private readToolName;
+  private findToolPart;
+}
+declare class HermesInlineToolTraceTranslator {
+  private pendingTextBuffer;
+  private sawStructuredToolCall;
+  private toolCallCount;
+  translate: (this: HermesInlineToolTraceTranslator, events: AsyncIterable<NcpEndpointEvent>) => AsyncGenerator<NcpEndpointEvent>;
+  private flushPendingText;
+  private shouldFlushPendingText;
+  private isStructuredToolCallEvent;
+  private readEventSessionId;
+  private readEventMessageId;
+}
+declare class HermesReasoningDeltaTranslator {
+  private readonly normalizer;
+  translate: (this: HermesReasoningDeltaTranslator, events: AsyncIterable<NcpEndpointEvent>) => AsyncGenerator<NcpEndpointEvent>;
+  private emitNormalizedTextDelta;
+  private flushPendingText;
+  private flushSegments;
+  private shouldFlushPendingText;
+  private readEventSessionId;
+  private readEventMessageId;
+}
+declare function resolveHermesModel(params: {
+  envelope: NcpRequestEnvelope;
+  fallbackModel: string;
+}): string;
+declare function normalizeHermesRequestedModel(model: string): string;
+declare function inferHermesProvider(params: {
+  model: string;
+  apiBase?: string | null;
+  apiMode?: HermesProviderRoute["apiMode"];
+}): string | undefined;
+declare function toNcpError(error: unknown, code: NcpError["code"]): NcpError;
+declare function toNcpSseFrame(event: NcpEndpointEvent): string;
+declare function toErrorSseFrame(error: {
+  code: string;
+  message: string;
+}): string;
+//#endregion
+export { HermesAssistantEventCollector, HermesInlineToolTraceTranslator, HermesProviderRoute, HermesReasoningDeltaTranslator, buildHermesMessages, createAssistantMessage, createAssistantMessageFromParts, inferHermesProvider, normalizeHermesRequestedModel, readHermesProviderRoute, resolveHermesModel, toErrorSseFrame, toNcpError, toNcpSseFrame };