@nextclaw/ncp-http-agent-server 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,21 @@
+# @nextclaw/ncp-http-agent-server
+
+HTTP/SSE transport adapter for exposing an `NcpAgentClientEndpoint` over Hono routes.
+
+## Build
+
+```bash
+pnpm -C packages/nextclaw-ncp-http-agent-server build
+```
+
+## API
+
+- `createNcpHttpAgentRouter(options)` — options require `agentClientEndpoint: NcpAgentClientEndpoint`
+- `mountNcpHttpAgentRoutes(app, options)`
+
+**Options:**
+- `agentClientEndpoint` — client endpoint to forward requests to (in-process adapter or remote HTTP client)
+- `replayProvider` (optional) — When set, `/reconnect` replays stored events instead of forwarding to the agent. Scenario: user reconnects after network drop and wants to continue watching the previous reply; with replayProvider we replay from persistence, without it we forward to the agent.
+- `basePath`, `requestTimeoutMs` — path and timeout
+
+For in-process agent (`NcpAgentServerEndpoint`), use `createAgentClientFromServer` from `@nextclaw/ncp` to wrap it.

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+import { NcpResumeRequestPayload, NcpEndpointEvent, NcpAgentClientEndpoint } from '@nextclaw/ncp';
+import { Hono } from 'hono';
+
+/**
+ * Replays stored session events for `/reconnect`.
+ *
+ * **Scenario**: User sends a message, agent streams SSE back. Network drops mid-stream.
+ * User reconnects and requests `GET /reconnect?sessionId=xxx&remoteRunId=yyy` to
+ * "continue watching the previous reply".
+ *
+ * **Two paths**:
+ * - **Replay** (with replayProvider): Do not call agent. Fetch that run's events
+ *   (message.accepted, message.text-delta, message.completed, etc.) from persistence
+ *   and stream them in order. Use when you have session/event storage and want to
+ *   avoid re-running the agent.
+ * - **Forward** (no replayProvider): Forward `message.resume-request` to the agent
+ *   and let it recover or re-run.
+ *
+ * **Implementation**: `stream` fetches events by payload.sessionId and payload.remoteRunId
+ * from your storage and yields them in order.
+ */
+type NcpHttpAgentReplayProvider = {
+    stream(params: {
+        payload: NcpResumeRequestPayload;
+        signal: AbortSignal;
+    }): AsyncIterable<NcpEndpointEvent>;
+};
+type NcpHttpAgentServerOptions = {
+    /** Client endpoint to forward requests to (in-process adapter or remote HTTP client). */
+    agentClientEndpoint: NcpAgentClientEndpoint;
+    basePath?: string;
+    requestTimeoutMs?: number;
+    /**
+     * Optional. When set, `/reconnect` replays stored events instead of forwarding to the agent.
+     * When not set, forwards `message.resume-request` to the agent.
+     */
+    replayProvider?: NcpHttpAgentReplayProvider;
+};
+
+/** Framework-agnostic HTTP handler interface for NCP agent routes. */
+interface NcpHttpAgentHandler {
+    handleSend(request: Request): Promise<Response>;
+    handleReconnect(request: Request): Promise<Response>;
+    handleAbort(request: Request): Promise<Response>;
+}
+type NcpHttpAgentHandlerOptions = {
+    agentClientEndpoint: NcpAgentClientEndpoint;
+    /**
+     * Optional. When set, `/reconnect` replays stored events instead of forwarding to the agent.
+     * See NcpHttpAgentReplayProvider for details.
+     */
+    replayProvider?: NcpHttpAgentReplayProvider;
+    timeoutMs: number;
+};
+
+/**
+ * Framework-agnostic controller for NCP agent HTTP routes.
+ * Forwards /send and /reconnect to agentClientEndpoint; /reconnect uses replayProvider when set.
+ */
+declare class NcpHttpAgentController implements NcpHttpAgentHandler {
+    private readonly options;
+    constructor(options: NcpHttpAgentHandlerOptions);
+    handleSend(request: Request): Promise<Response>;
+    handleReconnect(request: Request): Promise<Response>;
+    handleAbort(request: Request): Promise<Response>;
+}
+
+declare function createNcpHttpAgentRouter(options: NcpHttpAgentServerOptions): Hono;
+declare function mountNcpHttpAgentRoutes(app: Hono, options: NcpHttpAgentServerOptions): void;
+
+export { NcpHttpAgentController, type NcpHttpAgentHandler, type NcpHttpAgentHandlerOptions, type NcpHttpAgentReplayProvider, type NcpHttpAgentServerOptions, createNcpHttpAgentRouter, mountNcpHttpAgentRoutes };

package/dist/index.js

@@ -0,0 +1,431 @@
+// src/types.ts
+var DEFAULT_BASE_PATH = "/ncp/agent";
+var DEFAULT_REQUEST_TIMEOUT_MS = 12e4;
+
+// src/parsers.ts
+function normalizeBasePath(basePath) {
+  const raw = (basePath ?? DEFAULT_BASE_PATH).trim();
+  if (!raw) {
+    return DEFAULT_BASE_PATH;
+  }
+  const withLeadingSlash = raw.startsWith("/") ? raw : `/${raw}`;
+  return withLeadingSlash.endsWith("/") ? withLeadingSlash.slice(0, -1) : withLeadingSlash;
+}
+function sanitizeTimeout(timeoutMs) {
+  if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs)) {
+    return DEFAULT_REQUEST_TIMEOUT_MS;
+  }
+  return Math.max(1e3, Math.trunc(timeoutMs));
+}
+async function parseRequestEnvelope(request) {
+  try {
+    const payload = await request.json();
+    if (!isRecord(payload)) {
+      return null;
+    }
+    if (typeof payload.sessionId !== "string" || !payload.sessionId.trim()) {
+      return null;
+    }
+    if (!isRecord(payload.message)) {
+      return null;
+    }
+    return payload;
+  } catch {
+    return null;
+  }
+}
+function parseResumePayloadFromUrl(url) {
+  const query = new URL(url).searchParams;
+  const sessionId = query.get("sessionId")?.trim();
+  const remoteRunId = query.get("remoteRunId")?.trim();
+  if (!sessionId || !remoteRunId) {
+    return null;
+  }
+  const fromEventIndexRaw = query.get("fromEventIndex");
+  const fromEventIndex = typeof fromEventIndexRaw === "string" && Number.isFinite(Number.parseInt(fromEventIndexRaw, 10)) ? Math.max(0, Number.parseInt(fromEventIndexRaw, 10)) : void 0;
+  return {
+    sessionId,
+    remoteRunId,
+    ...typeof fromEventIndex === "number" ? { fromEventIndex } : {}
+  };
+}
+async function parseAbortPayload(request) {
+  try {
+    const payload = await request.json();
+    if (!isRecord(payload)) {
+      return {};
+    }
+    const messageId = readTrimmedString(payload.messageId);
+    const correlationId = readTrimmedString(payload.correlationId);
+    const runId = readTrimmedString(payload.runId);
+    return {
+      ...messageId ? { messageId } : {},
+      ...correlationId ? { correlationId } : {},
+      ...runId ? { runId } : {}
+    };
+  } catch {
+    return {};
+  }
+}
+function readTrimmedString(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+// src/scope.ts
+function extractScopeFromEvent(event) {
+  const payload = readPayload(event);
+  if (!payload) {
+    return {};
+  }
+  const runId = readString(payload.runId) ?? readString(payload.remoteRunId);
+  return {
+    sessionId: readString(payload.sessionId),
+    correlationId: readString(payload.correlationId),
+    runId
+  };
+}
+function matchesScope(scope, event) {
+  const eventScope = extractScopeFromEvent(event);
+  if (eventScope.sessionId && eventScope.sessionId !== scope.sessionId) {
+    return false;
+  }
+  if (scope.correlationId && eventScope.correlationId && eventScope.correlationId !== scope.correlationId) {
+    return false;
+  }
+  if (scope.runId && eventScope.runId && eventScope.runId !== scope.runId) {
+    return false;
+  }
+  return true;
+}
+function isTerminalEvent(event) {
+  switch (event.type) {
+    case "message.completed":
+    case "message.failed":
+    case "run.finished":
+    case "run.error":
+    case "message.abort":
+      return true;
+    default:
+      return false;
+  }
+}
+function readPayload(event) {
+  if (!("payload" in event)) {
+    return null;
+  }
+  return isRecord2(event.payload) ? event.payload : null;
+}
+function readString(value) {
+  return typeof value === "string" && value ? value : void 0;
+}
+function isRecord2(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+// src/sse-stream.ts
+function createSseEventStream(events, signal) {
+  const encoder = new TextEncoder();
+  return new ReadableStream({
+    start: async (controller) => {
+      let closed = false;
+      const close = () => {
+        if (closed) {
+          return;
+        }
+        closed = true;
+        controller.close();
+      };
+      const onAbort = () => {
+        close();
+      };
+      signal?.addEventListener("abort", onAbort, { once: true });
+      try {
+        for await (const event of events) {
+          if (closed || signal?.aborted) {
+            break;
+          }
+          controller.enqueue(encoder.encode(toSseFrame(event.event, event.data)));
+        }
+      } finally {
+        signal?.removeEventListener("abort", onAbort);
+        close();
+      }
+    }
+  });
+}
+function buildSseResponse(stream) {
+  return new Response(stream, {
+    status: 200,
+    headers: {
+      "Content-Type": "text/event-stream; charset=utf-8",
+      "Cache-Control": "no-cache, no-transform",
+      Connection: "keep-alive",
+      "X-Accel-Buffering": "no"
+    }
+  });
+}
+function toSseFrame(eventName, data) {
+  return `event: ${eventName}
+data: ${JSON.stringify(data)}
+
+`;
+}
+function toNcpEventFrame(event) {
+  return {
+    event: "ncp-event",
+    data: event
+  };
+}
+function toErrorFrame(code, message) {
+  return {
+    event: "error",
+    data: {
+      code,
+      message
+    }
+  };
+}
+
+// src/async-queue.ts
+function createAsyncQueue() {
+  const items = [];
+  let closed = false;
+  let pendingResolve = null;
+  const iterable = {
+    [Symbol.asyncIterator]() {
+      return {
+        next: () => {
+          if (items.length > 0) {
+            return Promise.resolve({
+              value: items.shift(),
+              done: false
+            });
+          }
+          if (closed) {
+            return Promise.resolve({
+              value: void 0,
+              done: true
+            });
+          }
+          return new Promise((resolve) => {
+            pendingResolve = resolve;
+          });
+        }
+      };
+    }
+  };
+  return {
+    push(item) {
+      if (closed) {
+        return;
+      }
+      if (pendingResolve) {
+        const resolve = pendingResolve;
+        pendingResolve = null;
+        resolve({ value: item, done: false });
+        return;
+      }
+      items.push(item);
+    },
+    close() {
+      if (closed) {
+        return;
+      }
+      closed = true;
+      if (pendingResolve) {
+        const resolve = pendingResolve;
+        pendingResolve = null;
+        resolve({
+          value: void 0,
+          done: true
+        });
+      }
+    },
+    iterable
+  };
+}
+
+// src/utils.ts
+function errorMessage(error) {
+  if (error instanceof Error && error.message) {
+    return error.message;
+  }
+  return String(error ?? "Unknown error");
+}
+function jsonResponse(body, status = 200) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" }
+  });
+}
+
+// src/stream-handlers.ts
+function createForwardResponse(options) {
+  const { requestSignal } = options;
+  return buildSseResponse(
+    createSseEventStream(createForwardSseEvents(options), requestSignal)
+  );
+}
+async function* createForwardSseEvents(options) {
+  const { endpoint, requestEvent, requestSignal, timeoutMs, scope } = options;
+  const queue = createAsyncQueue();
+  let timeoutId = null;
+  let unsubscribe = null;
+  let stopped = false;
+  const push = (frame) => {
+    if (!stopped) {
+      queue.push(frame);
+    }
+  };
+  const stop = () => {
+    if (stopped) {
+      return;
+    }
+    stopped = true;
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+    }
+    if (unsubscribe) {
+      unsubscribe();
+      unsubscribe = null;
+    }
+    requestSignal.removeEventListener("abort", stop);
+    queue.close();
+  };
+  requestSignal.addEventListener("abort", stop, { once: true });
+  timeoutId = setTimeout(() => {
+    push(toErrorFrame("TIMEOUT", "NCP HTTP stream timed out before terminal event."));
+    stop();
+  }, timeoutMs);
+  unsubscribe = endpoint.subscribe((event) => {
+    if (!matchesScope(scope, event)) {
+      return;
+    }
+    push(toNcpEventFrame(event));
+    if (isTerminalEvent(event)) {
+      stop();
+    }
+  });
+  void endpoint.emit(requestEvent).catch((error) => {
+    push(toErrorFrame("EMIT_FAILED", errorMessage(error)));
+    stop();
+  });
+  try {
+    for await (const frame of queue.iterable) {
+      yield frame;
+    }
+  } finally {
+    stop();
+  }
+}
+function createReplayResponse(options) {
+  const { signal } = options;
+  return buildSseResponse(
+    createSseEventStream(createReplaySseEvents(options), signal)
+  );
+}
+async function* createReplaySseEvents(options) {
+  const { replayProvider, payload, signal } = options;
+  try {
+    for await (const event of replayProvider.stream({ payload, signal })) {
+      if (signal.aborted) {
+        break;
+      }
+      yield toNcpEventFrame(event);
+      if (isTerminalEvent(event)) {
+        break;
+      }
+    }
+  } catch (error) {
+    yield toErrorFrame("REPLAY_FAILED", errorMessage(error));
+  }
+}
+
+// src/controller.ts
+var NcpHttpAgentController = class {
+  constructor(options) {
+    this.options = options;
+  }
+  async handleSend(request) {
+    const { agentClientEndpoint, timeoutMs } = this.options;
+    const envelope = await parseRequestEnvelope(request);
+    if (!envelope) {
+      return jsonResponse(
+        { ok: false, error: { code: "INVALID_BODY", message: "Invalid NCP request envelope." } },
+        400
+      );
+    }
+    return createForwardResponse({
+      endpoint: agentClientEndpoint,
+      requestEvent: { type: "message.request", payload: envelope },
+      requestSignal: request.signal,
+      timeoutMs,
+      scope: {
+        sessionId: envelope.sessionId,
+        correlationId: envelope.correlationId
+      }
+    });
+  }
+  async handleReconnect(request) {
+    const { agentClientEndpoint, replayProvider, timeoutMs } = this.options;
+    const resumePayload = parseResumePayloadFromUrl(request.url);
+    if (!resumePayload) {
+      return jsonResponse(
+        { ok: false, error: { code: "INVALID_QUERY", message: "sessionId and remoteRunId are required." } },
+        400
+      );
+    }
+    if (replayProvider) {
+      return createReplayResponse({
+        replayProvider,
+        payload: resumePayload,
+        signal: request.signal
+      });
+    }
+    return createForwardResponse({
+      endpoint: agentClientEndpoint,
+      requestEvent: { type: "message.resume-request", payload: resumePayload },
+      requestSignal: request.signal,
+      timeoutMs,
+      scope: {
+        sessionId: resumePayload.sessionId,
+        runId: resumePayload.remoteRunId
+      }
+    });
+  }
+  async handleAbort(request) {
+    const { agentClientEndpoint } = this.options;
+    const payload = await parseAbortPayload(request);
+    await agentClientEndpoint.abort(payload);
+    return jsonResponse({ ok: true });
+  }
+};
+
+// src/router.ts
+import { Hono } from "hono";
+function createNcpHttpAgentRouter(options) {
+  const app = new Hono();
+  mountNcpHttpAgentRoutes(app, options);
+  return app;
+}
+function mountNcpHttpAgentRoutes(app, options) {
+  const { basePath: rawBasePath, agentClientEndpoint, replayProvider, requestTimeoutMs } = options;
+  const basePath = normalizeBasePath(rawBasePath);
+  const controller = new NcpHttpAgentController({
+    agentClientEndpoint,
+    replayProvider,
+    timeoutMs: sanitizeTimeout(requestTimeoutMs)
+  });
+  app.post(`${basePath}/send`, (c) => controller.handleSend(c.req.raw));
+  app.get(`${basePath}/reconnect`, (c) => controller.handleReconnect(c.req.raw));
+  app.post(`${basePath}/abort`, (c) => controller.handleAbort(c.req.raw));
+}
+export {
+  NcpHttpAgentController,
+  createNcpHttpAgentRouter,
+  mountNcpHttpAgentRoutes
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@nextclaw/ncp-http-agent-server",
+  "version": "0.1.0",
+  "private": false,
+  "description": "HTTP/SSE server 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": {
+    "hono": "^4.9.8",
+    "@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"
+  }
+}