connectonion 0.0.18 → 0.0.21

package/dist/react/use-agent-for-human.js

@@ -0,0 +1,203 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isEventType = void 0;
+exports.useAgentForHuman = useAgentForHuman;
+exports.isChatItemType = isChatItemType;
+const react_1 = require("react");
+const connect_1 = require("../connect");
+const store_1 = require("./store");
+/**
+ * React hook for a human user to interact with a remote AI agent.
+ *
+ * This is the primary hook for building chat UIs where a human drives the
+ * conversation. It handles approval gates, ULW pauses, onboarding flows,
+ * and session persistence — all concerns specific to human interaction.
+ * For agent-to-agent communication, use `connect()` directly instead.
+ *
+ * Wraps a `RemoteAgent` instance with Zustand-backed localStorage persistence
+ * so chat history and session state survive page refreshes. One store is created
+ * per `(address, sessionId)` pair and cached for the lifetime of the module.
+ *
+ * **Lifecycle**
+ * 1. On mount (or when `sessionId` changes), any persisted session is restored
+ *    into the `RemoteAgent` so the server can resume from the correct context.
+ * 2. `agent.onMessage` is registered in an effect to receive every streaming
+ *    event from the agent — UI items, status, connection state, and session
+ *    snapshots are all synced here without a polling interval.
+ * 3. `input()` is fire-and-forget: it merges the session and dispatches the
+ *    prompt; all reactive updates come back through `onMessage`.
+ *
+ * **Session ID ownership**
+ * The caller is responsible for generating and managing the session UUID.
+ * A stable ID (e.g. persisted in a URL parameter or parent component state)
+ * lets users resume interrupted sessions across browser refreshes.
+ *
+ * @param address - Agent's 0x-prefixed public address on the relay network
+ * @param sessionId - UUID identifying this conversation session
+ * @returns Reactive state and methods for driving a chat UI
+ *
+ * @example
+ * ```tsx
+ * const { status, ui, input, isProcessing } = useAgentForHuman(agentAddress, sessionId);
+ *
+ * return (
+ *   <button disabled={isProcessing} onClick={() => input('Hello')}>
+ *     Send
+ *   </button>
+ * );
+ * ```
+ */
+function useAgentForHuman(address, sessionId) {
+    const useStore = (0, store_1.getStore)(address, sessionId);
+    // State from store
+    const messages = useStore((s) => s.messages);
+    const ui = useStore((s) => s.ui);
+    const session = useStore((s) => s.session);
+    const status = useStore((s) => s.status);
+    const error = useStore((s) => s.error);
+    // Actions from store
+    const setStatus = useStore((s) => s.setStatus);
+    const setUI = useStore((s) => s.setUI);
+    const setSession = useStore((s) => s.setSession);
+    const setError = useStore((s) => s.setError);
+    const updateMessages = useStore((s) => s.updateMessages);
+    const resetStore = useStore((s) => s.reset);
+    // RemoteAgent instance (keyed by address + sessionId)
+    const agentRef = (0, react_1.useRef)(null);
+    const keyRef = (0, react_1.useRef)(`${address}:${sessionId}`);
+    // Tear down the cached agent when the caller switches to a different address or session
+    // so the next render creates a fresh RemoteAgent pointing at the correct endpoint.
+    if (keyRef.current !== `${address}:${sessionId}`) {
+        agentRef.current = null;
+        keyRef.current = `${address}:${sessionId}`;
+    }
+    if (!agentRef.current) {
+        agentRef.current = (0, connect_1.connect)(address);
+    }
+    const agent = agentRef.current;
+    // connectionState is initialized from the agent and then kept in sync via onMessage.
+    const [connectionState, setConnectionState] = (0, react_1.useState)(agent.connectionState);
+    // Register a single onMessage callback for the lifetime of this agent instance.
+    // This replaces a polling interval: every streaming event from the server triggers
+    // one synchronous flush of all derived state into React/Zustand.
+    (0, react_1.useEffect)(() => {
+        agent.onMessage = () => {
+            setUI([...agent.ui]);
+            setStatus(agent.status);
+            setConnectionState(agent.connectionState);
+            if (agent.error)
+                setError(agent.error);
+            if (agent.currentSession) {
+                setSession(agent.currentSession);
+                if (agent.currentSession.messages) {
+                    updateMessages(agent.currentSession.messages);
+                }
+            }
+        };
+        return () => { agent.onMessage = null; };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [agent]);
+    // Restore persisted session into the RemoteAgent on mount or when sessionId changes.
+    // Then auto-reconnect to sync with server (get newer data, resume executing agent, etc.)
+    (0, react_1.useEffect)(() => {
+        if (session) {
+            agent._currentSession = { ...session, session_id: sessionId };
+            agent._chatItems = [...ui];
+        }
+        else if (messages.length > 0) {
+            agent._currentSession = { session_id: sessionId, messages };
+            agent._chatItems = [...ui];
+        }
+        // No auto-reconnect on mount. Show cached conversation from localStorage.
+        // When user sends next message, input() → _ensureConnected() → CONNECT
+        // will sync with server (session merge, server_newer, etc.).
+    }, [sessionId]);
+    const input = (prompt, options) => {
+        setError(null);
+        // Merge session before dispatching: the agent may have received a mode change via
+        // setMode() (stored only on _currentSession) that isn't reflected in the Zustand
+        // store yet. We preserve those in-flight agent properties while ensuring the server
+        // receives the canonical message history and the correct session ID.
+        const agentSession = agent._currentSession || {};
+        agent._currentSession = {
+            ...agentSession, // Preserve mode set by setMode()
+            ...(session || {}), // Overlay with store session
+            session_id: sessionId, // Ensure correct session ID
+            messages: session?.messages || messages,
+        };
+        // Restore chat items if agent is empty but store has data
+        // (Zustand hydration is async — the mount-time restore effect may have
+        // run before localStorage was hydrated, leaving _chatItems empty)
+        if (agent._chatItems.length === 0 && ui.length > 0) {
+            agent._chatItems = [...ui];
+        }
+        agent.input(prompt, options); // non-blocking — updates come via onMessage
+    };
+    const reconnect = () => {
+        // Ensure session is set on agent before reconnecting
+        if (!agent._currentSession?.session_id) {
+            agent._currentSession = { ...(session || {}), session_id: sessionId };
+        }
+        if (agent._chatItems.length === 0 && ui.length > 0) {
+            agent._chatItems = [...ui];
+        }
+        agent.reconnect(sessionId); // non-blocking — updates come via onMessage
+    };
+    const reset = () => {
+        agent.reset();
+        resetStore();
+    };
+    const sendMessage = (message) => {
+        agent.send(message);
+    };
+    const setMode = (newMode, options) => {
+        agent.setMode(newMode, options);
+        // Mirror the mode change into the Zustand store immediately so the UI reflects it
+        // before the next server-synced session arrives. ULW counters are also seeded here
+        // so consumers can render a turn budget without waiting for the first response.
+        const updates = { mode: newMode };
+        if (newMode === 'ulw') {
+            updates.ulw_turns = options?.turns || 100;
+            updates.ulw_turns_used = 0;
+        }
+        setSession(session
+            ? { ...session, ...updates }
+            : { session_id: sessionId, ...updates });
+    };
+    return {
+        status,
+        connectionState,
+        ui,
+        sessionId,
+        isProcessing: status !== 'idle',
+        error,
+        checkSessionStatus: (sid) => agent.checkSessionStatus(sid),
+        mode: session?.mode || 'safe',
+        ulwTurns: session?.ulw_turns ?? null,
+        ulwTurnsUsed: session?.ulw_turns_used ?? null,
+        input,
+        sendMessage,
+        signOnboard: (options) => agent.signOnboard(options),
+        setMode,
+        reconnect,
+        reset,
+    };
+}
+/**
+ * Type guard that narrows a `ChatItem` to the specific variant identified by `type`.
+ *
+ * Prefer this over a raw `item.type === 'tool_call'` comparison in render code
+ * because TypeScript will fully narrow the variant's unique fields inside the branch.
+ *
+ * @example
+ * ```ts
+ * if (isChatItemType(item, 'tool_call')) {
+ *   console.log(item.name, item.timing_ms); // fully typed
+ * }
+ * ```
+ */
+function isChatItemType(item, type) {
+    return item.type === type;
+}
+/** @deprecated Use isChatItemType instead */
+exports.isEventType = isChatItemType;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "connectonion",
-  "version": "0.0.18",
+  "version": "0.0.21",
   "description": "Connect to Python AI agents from TypeScript apps - Use powerful Python agents in your React, Next.js, Node.js, and Electron applications",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",