@nextclaw/ncp-http-agent-server 0.1.1 → 0.3.0

package/README.md

@@ -5,7 +5,7 @@ HTTP/SSE transport adapter for exposing an `NcpAgentClientEndpoint` over Hono ro
 ## Build
 
 ```bash
-pnpm -C packages/nextclaw-ncp-http-agent-server build
+pnpm -C packages/ncp-packages/nextclaw-ncp-http-agent-server build
 ```
 
 ## API
@@ -15,7 +15,7 @@ pnpm -C packages/nextclaw-ncp-http-agent-server build
 
 **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
+- `streamProvider` (optional) — When set, `/stream` serves stored events instead of forwarding to the agent. Scenario: user reconnects after network drop and wants to continue watching the previous reply; with `streamProvider` we stream from persistence, without it we forward to the agent.
+- `basePath`, `requestTimeoutMs` — path and optional forward-stream timeout. By default no server-side timeout is applied; set a positive value only if you explicitly want the server to cut off long-running forward streams.
 
-For in-process agent (`NcpAgentServerEndpoint`), use `createAgentClientFromServer` from `@nextclaw/ncp` to wrap it.
+For in-process agent (`NcpAgentServerEndpoint`), use `createAgentClientFromServer` from `@nextclaw/ncp-toolkit` to wrap it.

package/dist/index.d.ts

@@ -1,27 +1,25 @@
-import { NcpResumeRequestPayload, NcpEndpointEvent, NcpAgentClientEndpoint } from '@nextclaw/ncp';
+import { NcpStreamRequestPayload, NcpEndpointEvent, NcpAgentClientEndpoint } from '@nextclaw/ncp';
 import { Hono } from 'hono';
 
 /**
- * Replays stored session events for `/reconnect`.
+ * Streams live session events for `/stream`.
  *
  * **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".
+ * User reconnects and requests `GET /stream?sessionId=xxx` to continue following
+ * the current live response for that session.
  *
  * **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.
+ * - **Session stream** (with streamProvider): Do not call agent again. Attach to the
+ *   active session's live event stream.
+ * - **Forward** (no streamProvider): Forward `message.stream-request` to the agent
+ *   and let the upstream endpoint provide the live stream.
  *
- * **Implementation**: `stream` fetches events by payload.sessionId and payload.remoteRunId
- * from your storage and yields them in order.
+ * **Implementation**: `stream` attaches by payload.sessionId and yields live events
+ * for that active session.
  */
-type NcpHttpAgentReplayProvider = {
+type NcpHttpAgentStreamProvider = {
     stream(params: {
-        payload: NcpResumeRequestPayload;
+        payload: NcpStreamRequestPayload;
         signal: AbortSignal;
     }): AsyncIterable<NcpEndpointEvent>;
 };
@@ -29,43 +27,48 @@ 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.
+     * Optional forward-stream timeout in milliseconds.
+     * When omitted or set to a non-positive value, no server-side timeout is applied.
      */
-    replayProvider?: NcpHttpAgentReplayProvider;
+    requestTimeoutMs?: number | null;
+    /**
+     * Optional. When set, `/stream` serves live session events from streamProvider instead of
+     * forwarding to the agent.
+     * When not set, forwards `message.stream-request` to the agent.
+     */
+    streamProvider?: NcpHttpAgentStreamProvider;
 };
 
 /** Framework-agnostic HTTP handler interface for NCP agent routes. */
 interface NcpHttpAgentHandler {
     handleSend(request: Request): Promise<Response>;
-    handleReconnect(request: Request): Promise<Response>;
+    handleStream(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.
+     * Optional. When set, `/stream` serves stored events instead of forwarding to the agent.
+     * See NcpHttpAgentStreamProvider for details.
      */
-    replayProvider?: NcpHttpAgentReplayProvider;
-    timeoutMs: number;
+    streamProvider?: NcpHttpAgentStreamProvider;
+    timeoutMs: number | null;
 };
 
 /**
  * Framework-agnostic controller for NCP agent HTTP routes.
- * Forwards /send and /reconnect to agentClientEndpoint; /reconnect uses replayProvider when set.
+ * Forwards /send and /stream to agentClientEndpoint; /stream uses streamProvider when set.
  */
 declare class NcpHttpAgentController implements NcpHttpAgentHandler {
     private readonly options;
     constructor(options: NcpHttpAgentHandlerOptions);
     handleSend(request: Request): Promise<Response>;
-    handleReconnect(request: Request): Promise<Response>;
+    handleStream(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 };
+export { NcpHttpAgentController, type NcpHttpAgentHandler, type NcpHttpAgentHandlerOptions, type NcpHttpAgentServerOptions, type NcpHttpAgentStreamProvider, createNcpHttpAgentRouter, mountNcpHttpAgentRoutes };

package/dist/index.js

@@ -1,6 +1,8 @@
+// src/controller.ts
+import { NcpEventType } from "@nextclaw/ncp";
+
 // src/types.ts
 var DEFAULT_BASE_PATH = "/ncp/agent";
-var DEFAULT_REQUEST_TIMEOUT_MS = 12e4;
 
 // src/parsers.ts
 function normalizeBasePath(basePath) {
@@ -13,7 +15,10 @@ function normalizeBasePath(basePath) {
 }
 function sanitizeTimeout(timeoutMs) {
   if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs)) {
-    return DEFAULT_REQUEST_TIMEOUT_MS;
+    return null;
+  }
+  if (timeoutMs <= 0) {
+    return null;
   }
   return Math.max(1e3, Math.trunc(timeoutMs));
 }
@@ -34,37 +39,33 @@ async function parseRequestEnvelope(request) {
     return null;
   }
 }
-function parseResumePayloadFromUrl(url) {
+function parseStreamPayloadFromUrl(url) {
   const query = new URL(url).searchParams;
   const sessionId = query.get("sessionId")?.trim();
-  const remoteRunId = query.get("remoteRunId")?.trim();
-  if (!sessionId || !remoteRunId) {
+  if (!sessionId) {
     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 } : {}
+    sessionId
   };
 }
 async function parseAbortPayload(request) {
   try {
     const payload = await request.json();
     if (!isRecord(payload)) {
-      return {};
+      return null;
+    }
+    const sessionId = readTrimmedString(payload.sessionId);
+    if (!sessionId) {
+      return null;
     }
     const messageId = readTrimmedString(payload.messageId);
-    const correlationId = readTrimmedString(payload.correlationId);
-    const runId = readTrimmedString(payload.runId);
     return {
-      ...messageId ? { messageId } : {},
-      ...correlationId ? { correlationId } : {},
-      ...runId ? { runId } : {}
+      sessionId,
+      ...messageId ? { messageId } : {}
     };
   } catch {
-    return {};
+    return null;
   }
 }
 function readTrimmedString(value) {
@@ -80,11 +81,10 @@ function extractScopeFromEvent(event) {
   if (!payload) {
     return {};
   }
-  const runId = readString(payload.runId) ?? readString(payload.remoteRunId);
   return {
     sessionId: readString(payload.sessionId),
     correlationId: readString(payload.correlationId),
-    runId
+    runId: readString(payload.runId)
   };
 }
 function matchesScope(scope, event) {
@@ -275,6 +275,7 @@ async function* createForwardSseEvents(options) {
   let timeoutId = null;
   let unsubscribe = null;
   let stopped = false;
+  let terminalStopScheduled = false;
   const push = (frame) => {
     if (!stopped) {
       queue.push(frame);
@@ -297,22 +298,31 @@ async function* createForwardSseEvents(options) {
     queue.close();
   };
   requestSignal.addEventListener("abort", stop, { once: true });
-  timeoutId = setTimeout(() => {
-    push(toErrorFrame("TIMEOUT", "NCP HTTP stream timed out before terminal event."));
-    stop();
-  }, timeoutMs);
+  if (timeoutMs !== null) {
+    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();
+      if (!terminalStopScheduled) {
+        terminalStopScheduled = true;
+        queueMicrotask(stop);
+      }
     }
   });
   void endpoint.emit(requestEvent).catch((error) => {
     push(toErrorFrame("EMIT_FAILED", errorMessage(error)));
     stop();
+  }).finally(() => {
+    if (!terminalStopScheduled) {
+      queueMicrotask(stop);
+    }
   });
   try {
     for await (const frame of queue.iterable) {
@@ -322,16 +332,16 @@ async function* createForwardSseEvents(options) {
     stop();
   }
 }
-function createReplayResponse(options) {
+function createLiveStreamResponse(options) {
   const { signal } = options;
   return buildSseResponse(
-    createSseEventStream(createReplaySseEvents(options), signal)
+    createSseEventStream(createLiveStreamSseEvents(options), signal)
   );
 }
-async function* createReplaySseEvents(options) {
-  const { replayProvider, payload, signal } = options;
+async function* createLiveStreamSseEvents(options) {
+  const { streamProvider, payload, signal } = options;
   try {
-    for await (const event of replayProvider.stream({ payload, signal })) {
+    for await (const event of streamProvider.stream({ payload, signal })) {
       if (signal.aborted) {
         break;
       }
@@ -341,7 +351,7 @@ async function* createReplaySseEvents(options) {
       }
     }
   } catch (error) {
-    yield toErrorFrame("REPLAY_FAILED", errorMessage(error));
+    yield toErrorFrame("STREAM_SOURCE_FAILED", errorMessage(error));
   }
 }
 
@@ -361,7 +371,7 @@ var NcpHttpAgentController = class {
     }
     return createForwardResponse({
       endpoint: agentClientEndpoint,
-      requestEvent: { type: "message.request", payload: envelope },
+      requestEvent: { type: NcpEventType.MessageRequest, payload: envelope },
       requestSignal: request.signal,
       timeoutMs,
       scope: {
@@ -370,36 +380,41 @@ var NcpHttpAgentController = class {
       }
     });
   }
-  async handleReconnect(request) {
-    const { agentClientEndpoint, replayProvider, timeoutMs } = this.options;
-    const resumePayload = parseResumePayloadFromUrl(request.url);
-    if (!resumePayload) {
+  async handleStream(request) {
+    const { agentClientEndpoint, streamProvider, timeoutMs } = this.options;
+    const streamPayload = parseStreamPayloadFromUrl(request.url);
+    if (!streamPayload) {
       return jsonResponse(
-        { ok: false, error: { code: "INVALID_QUERY", message: "sessionId and remoteRunId are required." } },
+        { ok: false, error: { code: "INVALID_QUERY", message: "sessionId is required." } },
         400
       );
     }
-    if (replayProvider) {
-      return createReplayResponse({
-        replayProvider,
-        payload: resumePayload,
+    if (streamProvider) {
+      return createLiveStreamResponse({
+        streamProvider,
+        payload: streamPayload,
         signal: request.signal
       });
     }
     return createForwardResponse({
       endpoint: agentClientEndpoint,
-      requestEvent: { type: "message.resume-request", payload: resumePayload },
+      requestEvent: { type: NcpEventType.MessageStreamRequest, payload: streamPayload },
       requestSignal: request.signal,
       timeoutMs,
       scope: {
-        sessionId: resumePayload.sessionId,
-        runId: resumePayload.remoteRunId
+        sessionId: streamPayload.sessionId
       }
     });
   }
   async handleAbort(request) {
     const { agentClientEndpoint } = this.options;
     const payload = await parseAbortPayload(request);
+    if (!payload) {
+      return jsonResponse(
+        { ok: false, error: { code: "INVALID_BODY", message: "sessionId is required." } },
+        400
+      );
+    }
     await agentClientEndpoint.abort(payload);
     return jsonResponse({ ok: true });
   }
@@ -413,15 +428,15 @@ function createNcpHttpAgentRouter(options) {
   return app;
 }
 function mountNcpHttpAgentRoutes(app, options) {
-  const { basePath: rawBasePath, agentClientEndpoint, replayProvider, requestTimeoutMs } = options;
+  const { basePath: rawBasePath, agentClientEndpoint, streamProvider, requestTimeoutMs } = options;
   const basePath = normalizeBasePath(rawBasePath);
   const controller = new NcpHttpAgentController({
     agentClientEndpoint,
-    replayProvider,
+    streamProvider,
     timeoutMs: sanitizeTimeout(requestTimeoutMs)
   });
   app.post(`${basePath}/send`, (c) => controller.handleSend(c.req.raw));
-  app.get(`${basePath}/reconnect`, (c) => controller.handleReconnect(c.req.raw));
+  app.get(`${basePath}/stream`, (c) => controller.handleStream(c.req.raw));
   app.post(`${basePath}/abort`, (c) => controller.handleAbort(c.req.raw));
 }
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextclaw/ncp-http-agent-server",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "private": false,
   "description": "HTTP/SSE server transport adapter for NCP agent endpoints.",
   "type": "module",
@@ -16,14 +16,10 @@
   ],
   "dependencies": {
     "hono": "^4.9.8",
-    "@nextclaw/ncp": "0.1.1"
+    "@nextclaw/ncp": "0.3.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",