@langchain/langgraph-sdk 0.0.77 → 0.0.78

package/dist/react/stream.cjs

@@ -209,7 +209,18 @@ const useControllableThreadId = (options) => {
     return [options.threadId ?? null, onThreadId];
 };
 function useStream(options) {
-    let { assistantId, messagesKey, onError, onFinish } = options;
+    let { assistantId, messagesKey, onCreated, onError, onFinish } = options;
+    const reconnectOnMountRef = (0, react_1.useRef)(options.reconnectOnMount);
+    const runMetadataStorage = (0, react_1.useMemo)(() => {
+        if (typeof window === "undefined")
+            return null;
+        const storage = reconnectOnMountRef.current;
+        if (storage === true)
+            return window.sessionStorage;
+        if (typeof storage === "function")
+            return storage();
+        return null;
+    }, []);
     messagesKey ??= "messages";
     const client = (0, react_1.useMemo)(() => options.client ??
         new client_js_1.Client({
@@ -268,6 +279,7 @@ function useStream(options) {
     };
     // TODO: this should be done on the server to avoid pagination
     // TODO: should we permit adapter? SWR / React Query?
+    // TODO: make this only when branching is expected
     const history = useThreadHistory(threadId, client, clearCallbackRef, submittingRef);
     const getMessages = (0, react_1.useMemo)(() => {
         return (value) => Array.isArray(value[messagesKey])
@@ -322,69 +334,26 @@ function useStream(options) {
             };
         });
     })();
-    const stop = (0, react_1.useCallback)(() => {
+    const stop = () => {
         if (abortRef.current != null)
             abortRef.current.abort();
         abortRef.current = null;
-    }, []);
-    const submit = async (values, submitOptions) => {
+        if (runMetadataStorage && threadId) {
+            const runId = runMetadataStorage.getItem(`lg:stream:${threadId}`);
+            if (runId)
+                client.runs.cancel(threadId, runId);
+            runMetadataStorage.removeItem(`lg:stream:${threadId}`);
+        }
+    };
+    async function consumeStream(action) {
         try {
             setIsLoading(true);
             setStreamError(undefined);
             submittingRef.current = true;
             abortRef.current = new AbortController();
-            // Unbranch things
-            const newPath = submitOptions?.checkpoint?.checkpoint_id
-                ? branchByCheckpoint[submitOptions?.checkpoint?.checkpoint_id]?.branch
-                : undefined;
-            if (newPath != null)
-                setBranch(newPath ?? "");
-            // Assumption: we're setting the initial value
-            // Used for instant feedback
-            setStreamValues(() => {
-                const values = { ...historyValues };
-                if (submitOptions?.optimisticValues != null) {
-                    return {
-                        ...values,
-                        ...(typeof submitOptions.optimisticValues === "function"
-                            ? submitOptions.optimisticValues(values)
-                            : submitOptions.optimisticValues),
-                    };
-                }
-                return values;
-            });
-            let usableThreadId = threadId;
-            if (!usableThreadId) {
-                const thread = await client.threads.create();
-                onThreadId(thread.thread_id);
-                usableThreadId = thread.thread_id;
-            }
-            const streamMode = unique([
-                ...(submitOptions?.streamMode ?? []),
-                ...trackStreamModeRef.current,
-                ...callbackStreamMode,
-            ]);
-            const checkpoint = submitOptions?.checkpoint ?? threadHead?.checkpoint ?? undefined;
-            // @ts-expect-error
-            if (checkpoint != null)
-                delete checkpoint.thread_id;
-            const run = client.runs.stream(usableThreadId, assistantId, {
-                input: values,
-                config: submitOptions?.config,
-                command: submitOptions?.command,
-                interruptBefore: submitOptions?.interruptBefore,
-                interruptAfter: submitOptions?.interruptAfter,
-                metadata: submitOptions?.metadata,
-                multitaskStrategy: submitOptions?.multitaskStrategy,
-                onCompletion: submitOptions?.onCompletion,
-                onDisconnect: submitOptions?.onDisconnect ?? "cancel",
-                signal: abortRef.current.signal,
-                checkpoint,
-                streamMode,
-                streamSubgraphs: submitOptions?.streamSubgraphs,
-            });
+            const run = await action(abortRef.current.signal);
             let streamError;
-            for await (const { event, data } of run) {
+            for await (const { event, data } of run.stream) {
                 if (event === "error") {
                     streamError = new StreamError(data);
                     break;
@@ -431,7 +400,7 @@ function useStream(options) {
                 }
             }
             // TODO: stream created checkpoints to avoid an unnecessary network request
-            const result = await history.mutate(usableThreadId);
+            const result = await run.onSuccess();
             setStreamValues(null);
             if (streamError != null)
                 throw streamError;
@@ -454,7 +423,127 @@ function useStream(options) {
             submittingRef.current = false;
             abortRef.current = null;
         }
+    }
+    const joinStream = async (runId, lastEventId) => {
+        lastEventId ??= "-1";
+        if (!threadId)
+            return;
+        await consumeStream(async (signal) => {
+            const stream = client.runs.joinStream(threadId, runId, {
+                signal,
+                lastEventId,
+            });
+            return {
+                onSuccess: () => {
+                    runMetadataStorage?.removeItem(`lg:stream:${threadId}`);
+                    return history.mutate(threadId);
+                },
+                stream,
+            };
+        });
     };
+    const submit = async (values, submitOptions) => {
+        await consumeStream(async (signal) => {
+            // Unbranch things
+            const newPath = submitOptions?.checkpoint?.checkpoint_id
+                ? branchByCheckpoint[submitOptions?.checkpoint?.checkpoint_id]?.branch
+                : undefined;
+            if (newPath != null)
+                setBranch(newPath ?? "");
+            // Assumption: we're setting the initial value
+            // Used for instant feedback
+            setStreamValues(() => {
+                const values = { ...historyValues };
+                if (submitOptions?.optimisticValues != null) {
+                    return {
+                        ...values,
+                        ...(typeof submitOptions.optimisticValues === "function"
+                            ? submitOptions.optimisticValues(values)
+                            : submitOptions.optimisticValues),
+                    };
+                }
+                return values;
+            });
+            let usableThreadId = threadId;
+            if (!usableThreadId) {
+                const thread = await client.threads.create();
+                onThreadId(thread.thread_id);
+                usableThreadId = thread.thread_id;
+            }
+            const streamMode = unique([
+                ...(submitOptions?.streamMode ?? []),
+                ...trackStreamModeRef.current,
+                ...callbackStreamMode,
+            ]);
+            const checkpoint = submitOptions?.checkpoint ?? threadHead?.checkpoint ?? undefined;
+            // @ts-expect-error
+            if (checkpoint != null)
+                delete checkpoint.thread_id;
+            let rejoinKey;
+            const stream = client.runs.stream(usableThreadId, assistantId, {
+                input: values,
+                config: submitOptions?.config,
+                command: submitOptions?.command,
+                interruptBefore: submitOptions?.interruptBefore,
+                interruptAfter: submitOptions?.interruptAfter,
+                metadata: submitOptions?.metadata,
+                multitaskStrategy: submitOptions?.multitaskStrategy,
+                onCompletion: submitOptions?.onCompletion,
+                onDisconnect: submitOptions?.onDisconnect ??
+                    (runMetadataStorage ? "continue" : "cancel"),
+                signal,
+                checkpoint,
+                streamMode,
+                streamSubgraphs: submitOptions?.streamSubgraphs,
+                streamResumable: submitOptions?.streamResumable ?? !!runMetadataStorage,
+                onRunCreated(params) {
+                    const runParams = {
+                        run_id: params.run_id,
+                        thread_id: params.thread_id ?? usableThreadId,
+                    };
+                    if (runMetadataStorage) {
+                        rejoinKey = `lg:stream:${runParams.thread_id}`;
+                        runMetadataStorage.setItem(rejoinKey, runParams.run_id);
+                    }
+                    onCreated?.(runParams);
+                },
+            });
+            return {
+                stream,
+                onSuccess: () => {
+                    if (rejoinKey)
+                        runMetadataStorage?.removeItem(rejoinKey);
+                    return history.mutate(usableThreadId);
+                },
+            };
+        });
+    };
+    const reconnectKey = (0, react_1.useMemo)(() => {
+        if (!runMetadataStorage || isLoading)
+            return undefined;
+        if (typeof window === "undefined")
+            return undefined;
+        const runId = runMetadataStorage?.getItem(`lg:stream:${threadId}`);
+        if (!runId)
+            return undefined;
+        return { runId, threadId };
+    }, [runMetadataStorage, isLoading, threadId]);
+    const shouldReconnect = !!runMetadataStorage;
+    const reconnectRef = (0, react_1.useRef)({ threadId, shouldReconnect });
+    const joinStreamRef = (0, react_1.useRef)(joinStream);
+    joinStreamRef.current = joinStream;
+    (0, react_1.useEffect)(() => {
+        // reset shouldReconnect when switching threads
+        if (reconnectRef.current.threadId !== threadId) {
+            reconnectRef.current = { threadId, shouldReconnect };
+        }
+    }, [threadId, shouldReconnect]);
+    (0, react_1.useEffect)(() => {
+        if (reconnectKey && reconnectRef.current.shouldReconnect) {
+            reconnectRef.current.shouldReconnect = false;
+            joinStreamRef.current?.(reconnectKey.runId);
+        }
+    }, [reconnectKey]);
     const error = streamError ?? historyError;
     const values = streamValues ?? historyValues;
     return {
@@ -468,6 +557,7 @@ function useStream(options) {
         isLoading,
         stop,
         submit,
+        joinStream,
         branch,
         setBranch,
         history: flatHistory,

package/dist/react/stream.d.ts

@@ -93,6 +93,13 @@ export interface UseStreamOptions<StateType extends Record<string, unknown> = Re
      * Callback that is called when the stream is finished.
      */
     onFinish?: (state: ThreadState<StateType>) => void;
+    /**
+     * Callback that is called when a new stream is created.
+     */
+    onCreated?: (run: {
+        run_id: string;
+        thread_id: string;
+    }) => void;
     /**
      * Callback that is called when an update event is received.
      */
@@ -125,6 +132,13 @@ export interface UseStreamOptions<StateType extends Record<string, unknown> = Re
      * Callback that is called when the thread ID is updated (ie when a new thread is created).
      */
     onThreadId?: (threadId: string) => void;
+    /** Will reconnect the stream on mount */
+    reconnectOnMount?: boolean | (() => RunMetadataStorage);
+}
+interface RunMetadataStorage {
+    getItem(key: `lg:stream:${string}`): string | null;
+    setItem(key: `lg:stream:${string}`, value: string): void;
+    removeItem(key: `lg:stream:${string}`): void;
 }
 export interface UseStream<StateType extends Record<string, unknown> = Record<string, unknown>, Bag extends BagTemplate = BagTemplate> {
     /**
@@ -190,6 +204,10 @@ export interface UseStream<StateType extends Record<string, unknown> = Record<st
      * The ID of the assistant to use.
      */
     assistantId: string;
+    /**
+     * Join an active stream.
+     */
+    joinStream: (runId: string) => Promise<void>;
 }
 type ConfigWithConfigurable<ConfigurableType extends Record<string, unknown>> = Config & {
     configurable?: ConfigurableType;
@@ -213,6 +231,7 @@ interface SubmitOptions<StateType extends Record<string, unknown> = Record<strin
      * @default false
      */
     streamSubgraphs?: boolean;
+    streamResumable?: boolean;
 }
 export declare function useStream<StateType extends Record<string, unknown> = Record<string, unknown>, Bag extends {
     ConfigurableType?: Record<string, unknown>;

package/dist/react/stream.js

@@ -206,7 +206,18 @@ const useControllableThreadId = (options) => {
     return [options.threadId ?? null, onThreadId];
 };
 export function useStream(options) {
-    let { assistantId, messagesKey, onError, onFinish } = options;
+    let { assistantId, messagesKey, onCreated, onError, onFinish } = options;
+    const reconnectOnMountRef = useRef(options.reconnectOnMount);
+    const runMetadataStorage = useMemo(() => {
+        if (typeof window === "undefined")
+            return null;
+        const storage = reconnectOnMountRef.current;
+        if (storage === true)
+            return window.sessionStorage;
+        if (typeof storage === "function")
+            return storage();
+        return null;
+    }, []);
     messagesKey ??= "messages";
     const client = useMemo(() => options.client ??
         new Client({
@@ -265,6 +276,7 @@ export function useStream(options) {
     };
     // TODO: this should be done on the server to avoid pagination
     // TODO: should we permit adapter? SWR / React Query?
+    // TODO: make this only when branching is expected
     const history = useThreadHistory(threadId, client, clearCallbackRef, submittingRef);
     const getMessages = useMemo(() => {
         return (value) => Array.isArray(value[messagesKey])
@@ -319,69 +331,26 @@ export function useStream(options) {
             };
         });
     })();
-    const stop = useCallback(() => {
+    const stop = () => {
         if (abortRef.current != null)
             abortRef.current.abort();
         abortRef.current = null;
-    }, []);
-    const submit = async (values, submitOptions) => {
+        if (runMetadataStorage && threadId) {
+            const runId = runMetadataStorage.getItem(`lg:stream:${threadId}`);
+            if (runId)
+                client.runs.cancel(threadId, runId);
+            runMetadataStorage.removeItem(`lg:stream:${threadId}`);
+        }
+    };
+    async function consumeStream(action) {
         try {
             setIsLoading(true);
             setStreamError(undefined);
             submittingRef.current = true;
             abortRef.current = new AbortController();
-            // Unbranch things
-            const newPath = submitOptions?.checkpoint?.checkpoint_id
-                ? branchByCheckpoint[submitOptions?.checkpoint?.checkpoint_id]?.branch
-                : undefined;
-            if (newPath != null)
-                setBranch(newPath ?? "");
-            // Assumption: we're setting the initial value
-            // Used for instant feedback
-            setStreamValues(() => {
-                const values = { ...historyValues };
-                if (submitOptions?.optimisticValues != null) {
-                    return {
-                        ...values,
-                        ...(typeof submitOptions.optimisticValues === "function"
-                            ? submitOptions.optimisticValues(values)
-                            : submitOptions.optimisticValues),
-                    };
-                }
-                return values;
-            });
-            let usableThreadId = threadId;
-            if (!usableThreadId) {
-                const thread = await client.threads.create();
-                onThreadId(thread.thread_id);
-                usableThreadId = thread.thread_id;
-            }
-            const streamMode = unique([
-                ...(submitOptions?.streamMode ?? []),
-                ...trackStreamModeRef.current,
-                ...callbackStreamMode,
-            ]);
-            const checkpoint = submitOptions?.checkpoint ?? threadHead?.checkpoint ?? undefined;
-            // @ts-expect-error
-            if (checkpoint != null)
-                delete checkpoint.thread_id;
-            const run = client.runs.stream(usableThreadId, assistantId, {
-                input: values,
-                config: submitOptions?.config,
-                command: submitOptions?.command,
-                interruptBefore: submitOptions?.interruptBefore,
-                interruptAfter: submitOptions?.interruptAfter,
-                metadata: submitOptions?.metadata,
-                multitaskStrategy: submitOptions?.multitaskStrategy,
-                onCompletion: submitOptions?.onCompletion,
-                onDisconnect: submitOptions?.onDisconnect ?? "cancel",
-                signal: abortRef.current.signal,
-                checkpoint,
-                streamMode,
-                streamSubgraphs: submitOptions?.streamSubgraphs,
-            });
+            const run = await action(abortRef.current.signal);
             let streamError;
-            for await (const { event, data } of run) {
+            for await (const { event, data } of run.stream) {
                 if (event === "error") {
                     streamError = new StreamError(data);
                     break;
@@ -428,7 +397,7 @@ export function useStream(options) {
                 }
             }
             // TODO: stream created checkpoints to avoid an unnecessary network request
-            const result = await history.mutate(usableThreadId);
+            const result = await run.onSuccess();
             setStreamValues(null);
             if (streamError != null)
                 throw streamError;
@@ -451,7 +420,127 @@ export function useStream(options) {
             submittingRef.current = false;
             abortRef.current = null;
         }
+    }
+    const joinStream = async (runId, lastEventId) => {
+        lastEventId ??= "-1";
+        if (!threadId)
+            return;
+        await consumeStream(async (signal) => {
+            const stream = client.runs.joinStream(threadId, runId, {
+                signal,
+                lastEventId,
+            });
+            return {
+                onSuccess: () => {
+                    runMetadataStorage?.removeItem(`lg:stream:${threadId}`);
+                    return history.mutate(threadId);
+                },
+                stream,
+            };
+        });
     };
+    const submit = async (values, submitOptions) => {
+        await consumeStream(async (signal) => {
+            // Unbranch things
+            const newPath = submitOptions?.checkpoint?.checkpoint_id
+                ? branchByCheckpoint[submitOptions?.checkpoint?.checkpoint_id]?.branch
+                : undefined;
+            if (newPath != null)
+                setBranch(newPath ?? "");
+            // Assumption: we're setting the initial value
+            // Used for instant feedback
+            setStreamValues(() => {
+                const values = { ...historyValues };
+                if (submitOptions?.optimisticValues != null) {
+                    return {
+                        ...values,
+                        ...(typeof submitOptions.optimisticValues === "function"
+                            ? submitOptions.optimisticValues(values)
+                            : submitOptions.optimisticValues),
+                    };
+                }
+                return values;
+            });
+            let usableThreadId = threadId;
+            if (!usableThreadId) {
+                const thread = await client.threads.create();
+                onThreadId(thread.thread_id);
+                usableThreadId = thread.thread_id;
+            }
+            const streamMode = unique([
+                ...(submitOptions?.streamMode ?? []),
+                ...trackStreamModeRef.current,
+                ...callbackStreamMode,
+            ]);
+            const checkpoint = submitOptions?.checkpoint ?? threadHead?.checkpoint ?? undefined;
+            // @ts-expect-error
+            if (checkpoint != null)
+                delete checkpoint.thread_id;
+            let rejoinKey;
+            const stream = client.runs.stream(usableThreadId, assistantId, {
+                input: values,
+                config: submitOptions?.config,
+                command: submitOptions?.command,
+                interruptBefore: submitOptions?.interruptBefore,
+                interruptAfter: submitOptions?.interruptAfter,
+                metadata: submitOptions?.metadata,
+                multitaskStrategy: submitOptions?.multitaskStrategy,
+                onCompletion: submitOptions?.onCompletion,
+                onDisconnect: submitOptions?.onDisconnect ??
+                    (runMetadataStorage ? "continue" : "cancel"),
+                signal,
+                checkpoint,
+                streamMode,
+                streamSubgraphs: submitOptions?.streamSubgraphs,
+                streamResumable: submitOptions?.streamResumable ?? !!runMetadataStorage,
+                onRunCreated(params) {
+                    const runParams = {
+                        run_id: params.run_id,
+                        thread_id: params.thread_id ?? usableThreadId,
+                    };
+                    if (runMetadataStorage) {
+                        rejoinKey = `lg:stream:${runParams.thread_id}`;
+                        runMetadataStorage.setItem(rejoinKey, runParams.run_id);
+                    }
+                    onCreated?.(runParams);
+                },
+            });
+            return {
+                stream,
+                onSuccess: () => {
+                    if (rejoinKey)
+                        runMetadataStorage?.removeItem(rejoinKey);
+                    return history.mutate(usableThreadId);
+                },
+            };
+        });
+    };
+    const reconnectKey = useMemo(() => {
+        if (!runMetadataStorage || isLoading)
+            return undefined;
+        if (typeof window === "undefined")
+            return undefined;
+        const runId = runMetadataStorage?.getItem(`lg:stream:${threadId}`);
+        if (!runId)
+            return undefined;
+        return { runId, threadId };
+    }, [runMetadataStorage, isLoading, threadId]);
+    const shouldReconnect = !!runMetadataStorage;
+    const reconnectRef = useRef({ threadId, shouldReconnect });
+    const joinStreamRef = useRef(joinStream);
+    joinStreamRef.current = joinStream;
+    useEffect(() => {
+        // reset shouldReconnect when switching threads
+        if (reconnectRef.current.threadId !== threadId) {
+            reconnectRef.current = { threadId, shouldReconnect };
+        }
+    }, [threadId, shouldReconnect]);
+    useEffect(() => {
+        if (reconnectKey && reconnectRef.current.shouldReconnect) {
+            reconnectRef.current.shouldReconnect = false;
+            joinStreamRef.current?.(reconnectKey.runId);
+        }
+    }, [reconnectKey]);
     const error = streamError ?? historyError;
     const values = streamValues ?? historyValues;
     return {
@@ -465,6 +554,7 @@ export function useStream(options) {
         isLoading,
         stop,
         submit,
+        joinStream,
         branch,
         setBranch,
         history: flatHistory,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@langchain/langgraph-sdk",
-  "version": "0.0.77",
+  "version": "0.0.78",
   "description": "Client library for interacting with the LangGraph API",
   "type": "module",
   "packageManager": "yarn@1.22.19",