@nextclaw/ncp-react 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,14 +1,35 @@
-import { NcpAgentClientEndpoint, NcpAgentConversationSnapshot, NcpMessage } from '@nextclaw/ncp';
+import { NcpAgentConversationSnapshot, NcpMessage, NcpRequestEnvelope, NcpAgentClientEndpoint } from '@nextclaw/ncp';
 
-declare function useNcpAgent(sessionId: string, client: NcpAgentClientEndpoint): {
+type NcpAgentSendInput = string | NcpRequestEnvelope;
+type UseNcpAgentResult = {
     snapshot: NcpAgentConversationSnapshot;
     visibleMessages: readonly NcpMessage[];
     activeRunId: string | null;
     isRunning: boolean;
     isSending: boolean;
-    send: (content: string) => Promise<void>;
+    send: (input: NcpAgentSendInput) => Promise<void>;
     abort: () => Promise<void>;
     streamRun: () => Promise<void>;
 };
 
-export { useNcpAgent };
+type NcpConversationSeed = {
+    messages: readonly NcpMessage[];
+    status: "idle" | "running";
+};
+type NcpConversationSeedLoader = (sessionId: string, signal: AbortSignal) => Promise<NcpConversationSeed>;
+type UseHydratedNcpAgentOptions = {
+    sessionId: string;
+    client: NcpAgentClientEndpoint;
+    loadSeed: NcpConversationSeedLoader;
+    autoResumeRunningSession?: boolean;
+};
+type UseHydratedNcpAgentResult = UseNcpAgentResult & {
+    isHydrating: boolean;
+    hydrateError: Error | null;
+    reloadSeed: () => Promise<void>;
+};
+declare function useHydratedNcpAgent({ sessionId, client, loadSeed, autoResumeRunningSession, }: UseHydratedNcpAgentOptions): UseHydratedNcpAgentResult;
+
+declare function useNcpAgent(sessionId: string, client: NcpAgentClientEndpoint): UseNcpAgentResult;
+
+export { type NcpConversationSeed, type NcpConversationSeedLoader, type UseHydratedNcpAgentOptions, type UseHydratedNcpAgentResult, type UseNcpAgentResult, useHydratedNcpAgent, useNcpAgent };

package/dist/index.js

@@ -1,77 +1,144 @@
-// src/hooks/use-ncp-agent.ts
-import { useEffect, useRef, useState } from "react";
+// src/hooks/use-hydrated-ncp-agent.ts
+import { useCallback, useEffect as useEffect2, useRef as useRef2, useState as useState2 } from "react";
+
+// src/hooks/use-ncp-agent-runtime.ts
+import { useEffect, useRef, useState, useSyncExternalStore } from "react";
 import { DefaultNcpAgentConversationStateManager } from "@nextclaw/ncp-toolkit";
-import "@nextclaw/ncp";
-function useNcpAgent(sessionId, client) {
+import {
+  NcpEventType
+} from "@nextclaw/ncp";
+function shouldDispatchEventToSession(event, sessionId) {
+  const payload = "payload" in event ? event.payload : null;
+  if (!payload || typeof payload !== "object") {
+    return true;
+  }
+  if (!("sessionId" in payload) || typeof payload.sessionId !== "string") {
+    return true;
+  }
+  return payload.sessionId === sessionId;
+}
+function hasMessageContent(message) {
+  return message.parts.some((part) => {
+    if (part.type === "text" || part.type === "rich-text" || part.type === "reasoning") {
+      return part.text.trim().length > 0;
+    }
+    return true;
+  });
+}
+function normalizeSendEnvelope(input, sessionId) {
+  if (typeof input === "string") {
+    const content = input.trim();
+    if (!content) {
+      return null;
+    }
+    return {
+      sessionId,
+      message: {
+        id: `user-${Date.now().toString(36)}`,
+        sessionId,
+        role: "user",
+        status: "final",
+        parts: [{ type: "text", text: content }],
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      }
+    };
+  }
+  if (!hasMessageContent(input.message)) {
+    return null;
+  }
+  return {
+    ...input,
+    sessionId: input.sessionId,
+    message: {
+      ...input.message,
+      sessionId: input.message.sessionId || input.sessionId
+    }
+  };
+}
+function toHydrationPayload(sessionId, snapshot) {
+  return {
+    sessionId,
+    messages: snapshot.messages,
+    activeRun: snapshot.activeRun
+  };
+}
+function useScopedAgentManager(sessionId) {
   const managerRef = useRef();
-  if (!managerRef.current) {
-    managerRef.current = new DefaultNcpAgentConversationStateManager();
+  if (!managerRef.current || managerRef.current.sessionId !== sessionId) {
+    managerRef.current = {
+      sessionId,
+      manager: new DefaultNcpAgentConversationStateManager()
+    };
   }
-  const [snapshot, setSnapshot] = useState(
-    () => managerRef.current.getSnapshot()
+  return managerRef.current.manager;
+}
+function useNcpAgentRuntime({
+  sessionId,
+  client,
+  manager
+}) {
+  const snapshot = useSyncExternalStore(
+    (onStoreChange) => manager.subscribe(() => onStoreChange()),
+    () => manager.getSnapshot(),
+    () => manager.getSnapshot()
   );
   const [isSending, setIsSending] = useState(false);
   useEffect(() => {
-    const manager = managerRef.current;
-    if (!manager) {
-      return;
-    }
-    const unsubscribe = manager.subscribe((nextSnapshot) => {
-      setSnapshot(nextSnapshot);
-    });
-    return () => {
-      unsubscribe();
-    };
-  }, []);
+    setIsSending(false);
+  }, [sessionId]);
   useEffect(() => {
-    const manager = managerRef.current;
-    if (!manager) {
-      return;
-    }
     const unsubscribeClient = client.subscribe((event) => {
+      if (!shouldDispatchEventToSession(event, sessionId)) {
+        return;
+      }
       void manager.dispatch(event);
     });
     return () => {
       unsubscribeClient();
       void client.stop();
     };
-  }, [client]);
+  }, [client, manager, sessionId]);
   const visibleMessages = snapshot.streamingMessage ? [...snapshot.messages, snapshot.streamingMessage] : snapshot.messages;
   const activeRunId = snapshot.activeRun?.runId ?? null;
   const isRunning = !!snapshot.activeRun;
-  const send = async (content) => {
-    if (!content.trim() || isSending || isRunning) {
+  const send = async (input) => {
+    if (isSending || isRunning) {
+      return;
+    }
+    const envelope = normalizeSendEnvelope(input, sessionId);
+    if (!envelope) {
       return;
     }
     setIsSending(true);
-    try {
-      await client.send({
+    const previousSnapshot = manager.getSnapshot();
+    await manager.dispatch({
+      type: NcpEventType.MessageSent,
+      payload: {
         sessionId,
-        message: {
-          id: `user-${Date.now().toString(36)}`,
-          sessionId,
-          role: "user",
-          status: "final",
-          parts: [{ type: "text", text: content.trim() }],
-          timestamp: (/* @__PURE__ */ new Date()).toISOString()
-        }
-      });
+        message: envelope.message,
+        metadata: envelope.metadata
+      }
+    });
+    try {
+      await client.send(envelope);
+    } catch (error) {
+      manager.hydrate(toHydrationPayload(sessionId, previousSnapshot));
+      throw error;
     } finally {
       setIsSending(false);
     }
   };
   const abort = async () => {
-    const runId = snapshot.activeRun?.runId;
-    if (!runId) {
+    if (!snapshot.activeRun) {
       return;
     }
-    await client.abort({ runId });
+    await client.abort({ sessionId });
   };
   const streamRun = async () => {
-    if (!activeRunId) {
+    if (!snapshot.activeRun) {
       return;
     }
-    await client.stream({ sessionId, runId: activeRunId });
+    await client.stream({ sessionId });
   };
   return {
     snapshot,
@@ -84,6 +151,91 @@ function useNcpAgent(sessionId, client) {
     streamRun
   };
 }
+
+// src/hooks/use-hydrated-ncp-agent.ts
+function toError(error) {
+  return error instanceof Error ? error : new Error(String(error));
+}
+function useHydratedNcpAgent({
+  sessionId,
+  client,
+  loadSeed,
+  autoResumeRunningSession = true
+}) {
+  const manager = useScopedAgentManager(sessionId);
+  const runtime = useNcpAgentRuntime({ sessionId, client, manager });
+  const [isHydrating, setIsHydrating] = useState2(true);
+  const [hydrateError, setHydrateError] = useState2(null);
+  const loadStateRef = useRef2({ requestId: 0, controller: null });
+  const reloadSeed = useCallback(async () => {
+    loadStateRef.current.controller?.abort();
+    const controller = new AbortController();
+    const requestId = loadStateRef.current.requestId + 1;
+    loadStateRef.current = {
+      requestId,
+      controller
+    };
+    await client.stop();
+    manager.reset();
+    setHydrateError(null);
+    setIsHydrating(true);
+    try {
+      const seed = await loadSeed(sessionId, controller.signal);
+      if (controller.signal.aborted || loadStateRef.current.requestId !== requestId) {
+        return;
+      }
+      manager.hydrate({
+        sessionId,
+        messages: seed.messages,
+        activeRun: seed.status === "running" ? {
+          runId: null,
+          sessionId,
+          abortDisabledReason: null
+        } : null
+      });
+      setHydrateError(null);
+      setIsHydrating(false);
+      if (seed.status === "running" && autoResumeRunningSession) {
+        void client.stream({ sessionId }).catch((error) => {
+          if (loadStateRef.current.requestId !== requestId) {
+            return;
+          }
+          setHydrateError(toError(error));
+        });
+      }
+    } catch (error) {
+      if (controller.signal.aborted || loadStateRef.current.requestId !== requestId) {
+        return;
+      }
+      setHydrateError(toError(error));
+      setIsHydrating(false);
+    } finally {
+      if (loadStateRef.current.controller === controller) {
+        loadStateRef.current.controller = null;
+      }
+    }
+  }, [autoResumeRunningSession, client, loadSeed, manager, sessionId]);
+  useEffect2(() => {
+    void reloadSeed();
+    return () => {
+      loadStateRef.current.controller?.abort();
+      loadStateRef.current.controller = null;
+    };
+  }, [reloadSeed]);
+  return {
+    ...runtime,
+    isHydrating,
+    hydrateError,
+    reloadSeed
+  };
+}
+
+// src/hooks/use-ncp-agent.ts
+function useNcpAgent(sessionId, client) {
+  const manager = useScopedAgentManager(sessionId);
+  return useNcpAgentRuntime({ sessionId, client, manager });
+}
 export {
+  useHydratedNcpAgent,
   useNcpAgent
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextclaw/ncp-react",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "private": false,
   "description": "React bindings for building NCP-based agent applications.",
   "type": "module",
@@ -15,8 +15,8 @@
     "dist"
   ],
   "dependencies": {
-    "@nextclaw/ncp": "0.1.1",
-    "@nextclaw/ncp-toolkit": "0.1.1"
+    "@nextclaw/ncp": "0.3.0",
+    "@nextclaw/ncp-toolkit": "0.3.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0"