@nextclaw/ncp-http-agent-client 0.1.0

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,13 @@
+# @nextclaw/ncp-http-agent-client
+
+HTTP/SSE transport adapter implementing `NcpAgentClientEndpoint` for agent scenarios.
+
+## Build
+
+```bash
+pnpm -C packages/nextclaw-ncp-http-agent-client build
+```
+
+## API
+
+- `new NcpHttpAgentClientEndpoint(options)`

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+import { NcpAgentClientEndpoint, NcpEndpointManifest, NcpEndpointEvent, NcpEndpointSubscriber, NcpRequestEnvelope, NcpResumeRequestPayload, NcpMessageAbortPayload } from '@nextclaw/ncp';
+
+type FetchLike = (input: URL | string | Request, init?: RequestInit) => Promise<Response>;
+
+type NcpHttpAgentClientOptions = {
+    baseUrl: string;
+    basePath?: string;
+    endpointId?: string;
+    headers?: Record<string, string>;
+    fetchImpl?: FetchLike;
+};
+declare class NcpHttpAgentClientEndpoint implements NcpAgentClientEndpoint {
+    readonly manifest: NcpEndpointManifest;
+    private readonly baseUrl;
+    private readonly basePath;
+    private readonly fetchImpl;
+    private readonly defaultHeaders;
+    private readonly subscribers;
+    private readonly activeControllers;
+    private started;
+    constructor(options: NcpHttpAgentClientOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    emit(event: NcpEndpointEvent): Promise<void>;
+    subscribe(listener: NcpEndpointSubscriber): () => void;
+    send(envelope: NcpRequestEnvelope): Promise<void>;
+    resume(payload: NcpResumeRequestPayload): Promise<void>;
+    abort(payload?: NcpMessageAbortPayload): Promise<void>;
+    private ensureStarted;
+    private publish;
+    private resolveUrl;
+    private streamRequest;
+    private handleSseFrame;
+}
+
+export { NcpHttpAgentClientEndpoint, type NcpHttpAgentClientOptions };

package/dist/index.js

@@ -0,0 +1,419 @@
+// src/sse.ts
+function parseSseFrame(frameText) {
+  const lines = frameText.split(/\r?\n/);
+  let eventName = "message";
+  const dataLines = [];
+  for (const rawLine of lines) {
+    const line = rawLine.trimEnd();
+    if (!line || line.startsWith(":")) {
+      continue;
+    }
+    if (line.startsWith("event:")) {
+      eventName = line.slice(6).trim() || "message";
+      continue;
+    }
+    if (line.startsWith("data:")) {
+      dataLines.push(line.slice(5).trimStart());
+    }
+  }
+  if (dataLines.length === 0) {
+    return null;
+  }
+  return {
+    event: eventName,
+    data: dataLines.join("\n")
+  };
+}
+async function* consumeSseStream(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 { frames: frames2, rest } = drainFrames(buffer);
+      buffer = rest;
+      for (const frame of frames2) {
+        yield frame;
+      }
+    }
+    buffer += decoder.decode();
+    const { frames } = drainFrames(buffer, true);
+    for (const frame of frames) {
+      yield frame;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+function drainFrames(rawBuffer, flush = false) {
+  const parts = rawBuffer.split(/\r?\n\r?\n/);
+  const rest = parts.pop() ?? "";
+  const frames = [];
+  for (const part of parts) {
+    const frame = parseSseFrame(part);
+    if (frame) {
+      frames.push(frame);
+    }
+  }
+  if (flush && rest.trim()) {
+    const frame = parseSseFrame(rest);
+    if (frame) {
+      frames.push(frame);
+    }
+    return { frames, rest: "" };
+  }
+  return { frames, rest };
+}
+
+// src/utils.ts
+var DEFAULT_BASE_PATH = "/ncp/agent";
+var DEFAULT_ENDPOINT_ID = "ncp-http-agent-client";
+var NcpHttpAgentClientError = class extends Error {
+  ncpError;
+  alreadyPublished;
+  constructor(ncpError, alreadyPublished = false) {
+    super(ncpError.message);
+    this.name = `NcpHttpAgentClientError(${ncpError.code})`;
+    this.ncpError = ncpError;
+    this.alreadyPublished = alreadyPublished;
+  }
+};
+function toBaseUrl(baseUrl) {
+  const trimmed = baseUrl.trim();
+  if (!trimmed) {
+    throw new Error("NcpHttpAgentClient requires a non-empty baseUrl.");
+  }
+  return new URL(trimmed);
+}
+function resolveFetchImpl(fetchImpl) {
+  if (fetchImpl) {
+    return fetchImpl;
+  }
+  if (typeof globalThis.fetch === "function") {
+    return globalThis.fetch.bind(globalThis);
+  }
+  throw new Error("No fetch implementation found. Pass options.fetchImpl explicitly.");
+}
+function normalizeBasePath(basePath) {
+  const raw = (basePath ?? DEFAULT_BASE_PATH).trim();
+  if (!raw) {
+    return DEFAULT_BASE_PATH;
+  }
+  const withSlash = raw.startsWith("/") ? raw : `/${raw}`;
+  return withSlash.endsWith("/") ? withSlash.slice(0, -1) : withSlash;
+}
+async function safeReadText(response) {
+  try {
+    const text = await response.text();
+    return text.trim();
+  } catch {
+    return "";
+  }
+}
+function toNcpError(error) {
+  if (isNcpHttpAgentClientError(error)) {
+    return error.ncpError;
+  }
+  if (isNcpError(error)) {
+    return error;
+  }
+  const message = error instanceof Error ? error.message : String(error ?? "Unknown error");
+  return {
+    code: normalizeErrorCode(void 0),
+    message,
+    ...error instanceof Error && error.stack ? { details: { stack: error.stack } } : {}
+  };
+}
+function ncpErrorToError(error, options = {}) {
+  return new NcpHttpAgentClientError(error, options.alreadyPublished ?? false);
+}
+function isNcpError(value) {
+  return isRecord(value) && typeof value.code === "string" && typeof value.message === "string";
+}
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function isNcpHttpAgentClientError(error) {
+  return error instanceof NcpHttpAgentClientError;
+}
+var ERROR_CODE_MAP = {
+  "config-error": "config-error",
+  "auth-error": "auth-error",
+  "runtime-error": "runtime-error",
+  "timeout-error": "timeout-error",
+  "abort-error": "abort-error"
+};
+function normalizeErrorCode(code) {
+  if (!code) {
+    return "runtime-error";
+  }
+  const mapped = ERROR_CODE_MAP[code];
+  if (mapped) {
+    return mapped;
+  }
+  const lowered = code.toLowerCase();
+  if (lowered.includes("timeout")) return "timeout-error";
+  if (lowered.includes("abort") || lowered.includes("cancel")) return "abort-error";
+  if (lowered.includes("auth")) return "auth-error";
+  if (lowered.includes("config")) return "config-error";
+  return "runtime-error";
+}
+
+// src/parsers.ts
+function parseNcpEvent(rawData) {
+  const parsed = parseJsonRecord(rawData);
+  if (!parsed) {
+    return null;
+  }
+  if (typeof parsed.type !== "string" || !parsed.type.trim()) {
+    return null;
+  }
+  return parsed;
+}
+function parseNcpError(rawData) {
+  const parsed = parseJsonRecord(rawData);
+  if (!parsed) {
+    return {
+      code: "runtime-error",
+      message: rawData || "Unknown stream error."
+    };
+  }
+  const inputCode = typeof parsed.code === "string" ? parsed.code : void 0;
+  const normalizedCode = normalizeErrorCode(inputCode);
+  const details = isRecord(parsed.details) ? parsed.details : {};
+  if (inputCode && inputCode !== normalizedCode) {
+    details.originalCode = inputCode;
+  }
+  return {
+    code: normalizedCode,
+    message: typeof parsed.message === "string" && parsed.message ? parsed.message : "Unknown stream error.",
+    ...Object.keys(details).length > 0 ? { details } : {}
+  };
+}
+function parseJsonRecord(value) {
+  try {
+    const parsed = JSON.parse(value);
+    return isRecord(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+// src/client.ts
+var SUPPORTED_PART_TYPES = [
+  "text",
+  "file",
+  "source",
+  "step-start",
+  "reasoning",
+  "tool-invocation",
+  "card",
+  "rich-text",
+  "action",
+  "extension"
+];
+var NcpHttpAgentClientEndpoint = class {
+  manifest;
+  baseUrl;
+  basePath;
+  fetchImpl;
+  defaultHeaders;
+  subscribers = /* @__PURE__ */ new Set();
+  activeControllers = /* @__PURE__ */ new Set();
+  started = false;
+  constructor(options) {
+    this.baseUrl = toBaseUrl(options.baseUrl);
+    this.basePath = normalizeBasePath(options.basePath);
+    this.fetchImpl = resolveFetchImpl(options.fetchImpl);
+    this.defaultHeaders = options.headers ?? {};
+    this.manifest = {
+      endpointKind: "custom",
+      endpointId: options.endpointId?.trim() || DEFAULT_ENDPOINT_ID,
+      version: "0.1.0",
+      supportsStreaming: true,
+      supportsAbort: true,
+      supportsProactiveMessages: false,
+      supportsSessionResume: true,
+      supportedPartTypes: SUPPORTED_PART_TYPES,
+      expectedLatency: "seconds",
+      metadata: { transport: "http+sse", scope: "agent" }
+    };
+  }
+  async start() {
+    if (this.started) {
+      return;
+    }
+    this.started = true;
+    this.publish({ type: "endpoint.ready" });
+  }
+  async stop() {
+    if (!this.started) {
+      return;
+    }
+    this.started = false;
+    for (const controller of this.activeControllers) {
+      controller.abort();
+    }
+    this.activeControllers.clear();
+  }
+  async emit(event) {
+    switch (event.type) {
+      case "message.request":
+        await this.send(event.payload);
+        return;
+      case "message.resume-request":
+        await this.resume(event.payload);
+        return;
+      case "message.abort":
+        await this.abort(event.payload);
+        return;
+      default:
+        this.publish(event);
+        return;
+    }
+  }
+  subscribe(listener) {
+    this.subscribers.add(listener);
+    return () => {
+      this.subscribers.delete(listener);
+    };
+  }
+  async send(envelope) {
+    await this.ensureStarted();
+    await this.streamRequest({
+      path: "/send",
+      method: "POST",
+      body: envelope
+    });
+  }
+  async resume(payload) {
+    await this.ensureStarted();
+    const query = new URLSearchParams({
+      sessionId: payload.sessionId,
+      remoteRunId: payload.remoteRunId
+    });
+    if (typeof payload.fromEventIndex === "number" && Number.isFinite(payload.fromEventIndex)) {
+      query.set("fromEventIndex", String(Math.max(0, Math.trunc(payload.fromEventIndex))));
+    }
+    await this.streamRequest({
+      path: `/reconnect?${query.toString()}`,
+      method: "GET"
+    });
+  }
+  async abort(payload = {}) {
+    await this.ensureStarted();
+    const controller = new AbortController();
+    this.activeControllers.add(controller);
+    try {
+      const response = await this.fetchImpl(this.resolveUrl("/abort"), {
+        method: "POST",
+        headers: {
+          ...this.defaultHeaders,
+          "content-type": "application/json",
+          accept: "application/json"
+        },
+        body: JSON.stringify(payload),
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        throw new Error(
+          `Abort request failed with HTTP ${response.status}: ${await safeReadText(response)}`
+        );
+      }
+    } catch (error) {
+      if (controller.signal.aborted) {
+        return;
+      }
+      const ncpError = toNcpError(error);
+      this.publish({ type: "endpoint.error", payload: ncpError });
+      throw ncpErrorToError(ncpError);
+    } finally {
+      this.activeControllers.delete(controller);
+    }
+  }
+  async ensureStarted() {
+    if (!this.started) {
+      await this.start();
+    }
+  }
+  publish(event) {
+    for (const subscriber of this.subscribers) {
+      subscriber(event);
+    }
+  }
+  resolveUrl(path) {
+    return new URL(`${this.basePath}${path}`, this.baseUrl);
+  }
+  async streamRequest(options) {
+    const controller = new AbortController();
+    this.activeControllers.add(controller);
+    try {
+      const response = await this.fetchImpl(this.resolveUrl(options.path), {
+        method: options.method,
+        headers: {
+          ...this.defaultHeaders,
+          accept: "text/event-stream",
+          ...options.body !== void 0 ? { "content-type": "application/json" } : {}
+        },
+        body: options.body === void 0 ? void 0 : JSON.stringify(options.body),
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        throw new Error(
+          `NCP stream request failed with HTTP ${response.status}: ${await safeReadText(response)}`
+        );
+      }
+      if (!response.body) {
+        throw new Error("NCP stream response has no body.");
+      }
+      for await (const frame of consumeSseStream(response.body)) {
+        if (controller.signal.aborted) {
+          return;
+        }
+        this.handleSseFrame(frame);
+      }
+    } catch (error) {
+      if (controller.signal.aborted) {
+        return;
+      }
+      if (isNcpHttpAgentClientError(error)) {
+        throw error;
+      }
+      const ncpError = toNcpError(error);
+      this.publish({ type: "endpoint.error", payload: ncpError });
+      throw ncpErrorToError(ncpError);
+    } finally {
+      this.activeControllers.delete(controller);
+    }
+  }
+  handleSseFrame(frame) {
+    if (frame.event === "ncp-event") {
+      const event = parseNcpEvent(frame.data);
+      if (!event) {
+        this.publish({
+          type: "endpoint.error",
+          payload: {
+            code: "runtime-error",
+            message: "Received malformed ncp-event frame."
+          }
+        });
+        return;
+      }
+      this.publish(event);
+      return;
+    }
+    if (frame.event === "error") {
+      const ncpError = parseNcpError(frame.data);
+      this.publish({ type: "endpoint.error", payload: ncpError });
+      throw ncpErrorToError(ncpError, { alreadyPublished: true });
+    }
+  }
+};
+export {
+  NcpHttpAgentClientEndpoint
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@nextclaw/ncp-http-agent-client",
+  "version": "0.1.0",
+  "private": false,
+  "description": "HTTP/SSE client transport adapter for NCP agent endpoints.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@nextclaw/ncp": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.6",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
+    "eslint": "^8.57.1",
+    "eslint-config-prettier": "^9.1.0",
+    "prettier": "^3.3.3",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.2"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --out-dir dist",
+    "lint": "eslint .",
+    "tsc": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  }
+}