@langchain/langgraph-sdk 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @langchain/langgraph-sdk
 
+## 0.1.8
+
+### Patch Changes
+
+- 90dcb8b: Add support for managing thread state manually outside of useStream hook via `experimental_thread` option
+
+## 0.1.7
+
+### Patch Changes
+
+- bbc90e6: Fix thread history state being kept stale when changing `thread_id`
+
 ## 0.1.6
 
 ### Patch Changes

package/dist/react/index.d.ts

@@ -1,3 +1,3 @@
 export { useStream } from "./stream.js";
 export { FetchStreamTransport } from "./stream.custom.js";
-export type { MessageMetadata, UseStream, UseStreamOptions, UseStreamCustom, UseStreamCustomOptions, UseStreamTransport, } from "./types.js";
+export type { MessageMetadata, UseStream, UseStreamOptions, UseStreamCustom, UseStreamCustomOptions, UseStreamTransport, UseStreamThread, } from "./types.js";

package/dist/react/stream.custom.cjs

@@ -6,8 +6,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.FetchStreamTransport = void 0;
 exports.useStreamCustom = useStreamCustom;
 const react_1 = require("react");
-const manager_js_1 = require("./manager.cjs");
-const messages_js_1 = require("./messages.cjs");
+const manager_js_1 = require("../ui/manager.cjs");
+const messages_js_1 = require("../ui/messages.cjs");
 const sse_js_1 = require("../utils/sse.cjs");
 const stream_js_1 = require("../utils/stream.cjs");
 const thread_js_1 = require("./thread.cjs");

package/dist/react/stream.custom.js

@@ -1,8 +1,8 @@
 /* __LC_ALLOW_ENTRYPOINT_SIDE_EFFECTS__ */
 "use client";
 import { useEffect, useRef, useState, useSyncExternalStore } from "react";
-import { StreamManager } from "./manager.js";
-import { MessageTupleManager } from "./messages.js";
+import { StreamManager } from "../ui/manager.js";
+import { MessageTupleManager } from "../ui/messages.js";
 import { BytesLineDecoder, SSEDecoder } from "../utils/sse.js";
 import { IterableReadableStream } from "../utils/stream.js";
 import { useControllableThreadId } from "./thread.js";

package/dist/react/stream.lgp.cjs

@@ -5,12 +5,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.useStreamLGP = useStreamLGP;
 const react_1 = require("react");
-const utils_js_1 = require("./utils.cjs");
-const errors_js_1 = require("./errors.cjs");
-const branching_js_1 = require("./branching.cjs");
-const manager_js_1 = require("./manager.cjs");
+const utils_js_1 = require("../ui/utils.cjs");
+const errors_js_1 = require("../ui/errors.cjs");
+const branching_js_1 = require("../ui/branching.cjs");
+const manager_js_1 = require("../ui/manager.cjs");
 const client_js_1 = require("../client.cjs");
-const messages_js_1 = require("./messages.cjs");
+const messages_js_1 = require("../ui/messages.cjs");
 const thread_js_1 = require("./thread.cjs");
 function getFetchHistoryKey(client, threadId, limit) {
     return [(0, client_js_1.getClientConfigHash)(client), threadId, limit].join(":");
@@ -29,6 +29,7 @@ function fetchHistory(client, threadId, options) {
 function useThreadHistory(client, threadId, limit, options) {
     const key = getFetchHistoryKey(client, threadId, limit);
     const [state, setState] = (0, react_1.useState)(() => ({
+        key: undefined,
         data: undefined,
         error: undefined,
         isLoading: threadId != null,
@@ -38,21 +39,37 @@ function useThreadHistory(client, threadId, limit, options) {
     const onErrorRef = (0, react_1.useRef)(options?.onError);
     onErrorRef.current = options?.onError;
     const fetcher = (0, react_1.useCallback)((threadId, limit) => {
+        // If only passthrough is enabled, don't fetch history
+        if (options.passthrough)
+            return Promise.resolve([]);
+        const client = clientRef.current;
+        const key = getFetchHistoryKey(client, threadId, limit);
         if (threadId != null) {
-            const client = clientRef.current;
-            setState((state) => ({ ...state, isLoading: true }));
+            setState((state) => {
+                if (state.key === key)
+                    return { ...state, isLoading: true };
+                return { key, data: undefined, error: undefined, isLoading: true };
+            });
             return fetchHistory(client, threadId, { limit }).then((data) => {
-                setState({ data, error: undefined, isLoading: false });
+                setState((state) => {
+                    if (state.key !== key)
+                        return state;
+                    return { key, data, error: undefined, isLoading: false };
+                });
                 return data;
             }, (error) => {
-                setState(({ data }) => ({ data, error, isLoading: false }));
+                setState((state) => {
+                    if (state.key !== key)
+                        return state;
+                    return { key, data: state.data, error, isLoading: false };
+                });
                 onErrorRef.current?.(error);
                 return Promise.reject(error);
             });
         }
-        setState({ data: undefined, error: undefined, isLoading: false });
+        setState({ key, data: undefined, error: undefined, isLoading: false });
         return Promise.resolve([]);
-    }, []);
+    }, [options.passthrough]);
     (0, react_1.useEffect)(() => {
         // Skip if a stream is already in progress, no need to fetch history
         if (options.submittingRef.current != null &&
@@ -152,10 +169,12 @@ function useStreamLGP(options) {
         options.fetchStateHistory != null
         ? options.fetchStateHistory.limit ?? false
         : options.fetchStateHistory ?? false;
-    const history = useThreadHistory(client, threadId, historyLimit, {
+    const builtInHistory = useThreadHistory(client, threadId, historyLimit, {
+        passthrough: options.experimental_thread != null,
         submittingRef: threadIdStreamingRef,
         onError: options.onError,
     });
+    const history = options.experimental_thread ?? builtInHistory;
     const getMessages = (value) => {
         const messagesKey = options.messagesKey ?? "messages";
         return Array.isArray(value[messagesKey]) ? value[messagesKey] : [];
@@ -165,7 +184,7 @@ function useStreamLGP(options) {
         return { ...current, [messagesKey]: messages };
     };
     const [branch, setBranch] = (0, react_1.useState)("");
-    const branchContext = (0, branching_js_1.getBranchContext)(branch, history.data);
+    const branchContext = (0, branching_js_1.getBranchContext)(branch, history.data ?? undefined);
     const historyValues = branchContext.threadHead?.values ??
         options.initialValues ??
         {};
@@ -330,7 +349,7 @@ function useStreamLGP(options) {
                     includeImplicitBranch;
                 if (shouldRefetch) {
                     const newHistory = await history.mutate(usableThreadId);
-                    const lastHead = newHistory.at(0);
+                    const lastHead = newHistory?.at(0);
                     if (lastHead) {
                         // We now have the latest update from /history
                         // Thus we can clear the local stream state
@@ -372,7 +391,7 @@ function useStreamLGP(options) {
             async onSuccess() {
                 runMetadataStorage?.removeItem(`lg:stream:${threadId}`);
                 const newHistory = await history.mutate(threadId);
-                const lastHead = newHistory.at(0);
+                const lastHead = newHistory?.at(0);
                 if (lastHead)
                     options.onFinish?.(lastHead, callbackMeta);
             },

package/dist/react/stream.lgp.js

@@ -1,12 +1,12 @@
 /* __LC_ALLOW_ENTRYPOINT_SIDE_EFFECTS__ */
 "use client";
 import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore, } from "react";
-import { findLast, unique } from "./utils.js";
-import { StreamError } from "./errors.js";
-import { getBranchContext } from "./branching.js";
-import { StreamManager } from "./manager.js";
+import { findLast, unique } from "../ui/utils.js";
+import { StreamError } from "../ui/errors.js";
+import { getBranchContext } from "../ui/branching.js";
+import { StreamManager } from "../ui/manager.js";
 import { Client, getClientConfigHash } from "../client.js";
-import { MessageTupleManager } from "./messages.js";
+import { MessageTupleManager } from "../ui/messages.js";
 import { useControllableThreadId } from "./thread.js";
 function getFetchHistoryKey(client, threadId, limit) {
     return [getClientConfigHash(client), threadId, limit].join(":");
@@ -25,6 +25,7 @@ function fetchHistory(client, threadId, options) {
 function useThreadHistory(client, threadId, limit, options) {
     const key = getFetchHistoryKey(client, threadId, limit);
     const [state, setState] = useState(() => ({
+        key: undefined,
         data: undefined,
         error: undefined,
         isLoading: threadId != null,
@@ -34,21 +35,37 @@ function useThreadHistory(client, threadId, limit, options) {
     const onErrorRef = useRef(options?.onError);
     onErrorRef.current = options?.onError;
     const fetcher = useCallback((threadId, limit) => {
+        // If only passthrough is enabled, don't fetch history
+        if (options.passthrough)
+            return Promise.resolve([]);
+        const client = clientRef.current;
+        const key = getFetchHistoryKey(client, threadId, limit);
         if (threadId != null) {
-            const client = clientRef.current;
-            setState((state) => ({ ...state, isLoading: true }));
+            setState((state) => {
+                if (state.key === key)
+                    return { ...state, isLoading: true };
+                return { key, data: undefined, error: undefined, isLoading: true };
+            });
             return fetchHistory(client, threadId, { limit }).then((data) => {
-                setState({ data, error: undefined, isLoading: false });
+                setState((state) => {
+                    if (state.key !== key)
+                        return state;
+                    return { key, data, error: undefined, isLoading: false };
+                });
                 return data;
             }, (error) => {
-                setState(({ data }) => ({ data, error, isLoading: false }));
+                setState((state) => {
+                    if (state.key !== key)
+                        return state;
+                    return { key, data: state.data, error, isLoading: false };
+                });
                 onErrorRef.current?.(error);
                 return Promise.reject(error);
             });
         }
-        setState({ data: undefined, error: undefined, isLoading: false });
+        setState({ key, data: undefined, error: undefined, isLoading: false });
         return Promise.resolve([]);
-    }, []);
+    }, [options.passthrough]);
     useEffect(() => {
         // Skip if a stream is already in progress, no need to fetch history
         if (options.submittingRef.current != null &&
@@ -148,10 +165,12 @@ export function useStreamLGP(options) {
         options.fetchStateHistory != null
         ? options.fetchStateHistory.limit ?? false
         : options.fetchStateHistory ?? false;
-    const history = useThreadHistory(client, threadId, historyLimit, {
+    const builtInHistory = useThreadHistory(client, threadId, historyLimit, {
+        passthrough: options.experimental_thread != null,
         submittingRef: threadIdStreamingRef,
         onError: options.onError,
     });
+    const history = options.experimental_thread ?? builtInHistory;
     const getMessages = (value) => {
         const messagesKey = options.messagesKey ?? "messages";
         return Array.isArray(value[messagesKey]) ? value[messagesKey] : [];
@@ -161,7 +180,7 @@ export function useStreamLGP(options) {
         return { ...current, [messagesKey]: messages };
     };
     const [branch, setBranch] = useState("");
-    const branchContext = getBranchContext(branch, history.data);
+    const branchContext = getBranchContext(branch, history.data ?? undefined);
     const historyValues = branchContext.threadHead?.values ??
         options.initialValues ??
         {};
@@ -326,7 +345,7 @@ export function useStreamLGP(options) {
                     includeImplicitBranch;
                 if (shouldRefetch) {
                     const newHistory = await history.mutate(usableThreadId);
-                    const lastHead = newHistory.at(0);
+                    const lastHead = newHistory?.at(0);
                     if (lastHead) {
                         // We now have the latest update from /history
                         // Thus we can clear the local stream state
@@ -368,7 +387,7 @@ export function useStreamLGP(options) {
             async onSuccess() {
                 runMetadataStorage?.removeItem(`lg:stream:${threadId}`);
                 const newHistory = await history.mutate(threadId);
-                const lastHead = newHistory.at(0);
+                const lastHead = newHistory?.at(0);
                 if (lastHead)
                     options.onFinish?.(lastHead, callbackMeta);
             },

package/dist/react/types.d.ts

@@ -3,7 +3,7 @@ import type { ThreadState, Interrupt, Config, Checkpoint, Metadata } from "../sc
 import type { Command, MultitaskStrategy, OnCompletionBehavior, DisconnectMode, Durability } from "../types.js";
 import type { Message } from "../types.messages.js";
 import type { UpdatesStreamEvent, CustomStreamEvent, MetadataStreamEvent, EventsStreamEvent, DebugStreamEvent, CheckpointsStreamEvent, TasksStreamEvent, StreamMode } from "../types.stream.js";
-import type { Sequence } from "./branching.js";
+import type { Sequence } from "../ui/branching.js";
 export type MessageMetadata<StateType extends Record<string, unknown>> = {
     /**
      * The ID of the message used.
@@ -50,6 +50,12 @@ export interface RunCallbackMeta {
     run_id: string;
     thread_id: string;
 }
+export interface UseStreamThread<StateType extends Record<string, unknown>> {
+    data: ThreadState<StateType>[] | null | undefined;
+    error: unknown;
+    isLoading: boolean;
+    mutate: (mutateId?: string) => Promise<ThreadState<StateType>[] | null | undefined>;
+}
 export interface UseStreamOptions<StateType extends Record<string, unknown> = Record<string, unknown>, Bag extends BagTemplate = BagTemplate> {
     /**
      * The ID of the assistant to use.
@@ -187,6 +193,11 @@ export interface UseStreamOptions<StateType extends Record<string, unknown> = Re
     fetchStateHistory?: boolean | {
         limit: number;
     };
+    /**
+     * Manage the thread state externally.
+     * @experimental
+     */
+    experimental_thread?: UseStreamThread<StateType>;
 }
 interface RunMetadataStorage {
     getItem(key: `lg:stream:${string}`): string | null;

package/dist/ui/branching.test.cjs

@@ -0,0 +1,370 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const branching_js_1 = require("./branching.cjs");
+const history = [
+    {
+        values: {
+            messages: [
+                {
+                    content: "Fork: Hello",
+                    additional_kwargs: {},
+                    response_metadata: {},
+                    id: "33357aea-9c2d-4718-92f4-20038d5a2d29",
+                    type: "human",
+                },
+                {
+                    content: "Hey",
+                    additional_kwargs: {},
+                    response_metadata: {},
+                    tool_call_chunks: [],
+                    id: "run-782a2f90-2e39-4c21-9ee6-0f38585a0ae6",
+                    tool_calls: [],
+                    invalid_tool_calls: [],
+                    type: "ai",
+                },
+            ],
+        },
+        next: [],
+        tasks: [],
+        metadata: {
+            source: "loop",
+            step: 2,
+            parents: {},
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+        },
+        created_at: "2025-08-21T12:47:12.640Z",
+        checkpoint: {
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+            checkpoint_id: "1f07e8cf-56a7-6000-8002-5e272b1d5285",
+            checkpoint_ns: "",
+            checkpoint_map: null,
+        },
+        parent_checkpoint: {
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+            checkpoint_id: "1f07e8cf-53aa-6d70-8001-2096b0bbf835",
+            checkpoint_ns: "",
+            checkpoint_map: null,
+        },
+    },
+    {
+        values: {
+            messages: [
+                {
+                    content: "Fork: Hello",
+                    additional_kwargs: {},
+                    response_metadata: {},
+                    id: "33357aea-9c2d-4718-92f4-20038d5a2d29",
+                    type: "human",
+                },
+            ],
+        },
+        next: ["agent"],
+        tasks: [
+            {
+                id: "680ee831-4d10-50f9-956f-e0d937321614",
+                name: "agent",
+                error: null,
+                interrupts: [],
+                path: ["__pregel_pull", "agent"],
+                checkpoint: null,
+                state: null,
+                result: {
+                    messages: [
+                        {
+                            content: "Hey",
+                            additional_kwargs: {},
+                            response_metadata: {},
+                            tool_call_chunks: [],
+                            id: "run-782a2f90-2e39-4c21-9ee6-0f38585a0ae6",
+                            tool_calls: [],
+                            invalid_tool_calls: [],
+                            type: "ai",
+                        },
+                    ],
+                },
+            },
+        ],
+        metadata: {
+            source: "loop",
+            step: 1,
+            parents: {},
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+        },
+        created_at: "2025-08-21T12:47:12.327Z",
+        checkpoint: {
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+            checkpoint_id: "1f07e8cf-53aa-6d70-8001-2096b0bbf835",
+            checkpoint_ns: "",
+            checkpoint_map: null,
+        },
+        parent_checkpoint: {
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+            checkpoint_id: "1f07e8cf-53a8-6660-8000-f157c9cf7d66",
+            checkpoint_ns: "",
+            checkpoint_map: null,
+        },
+    },
+    {
+        values: { messages: [] },
+        next: ["__start__"],
+        tasks: [
+            {
+                id: "4233f4c0-5ea2-5117-9153-95e5fe59eee3",
+                name: "__start__",
+                error: null,
+                interrupts: [],
+                path: ["__pregel_pull", "__start__"],
+                checkpoint: null,
+                state: null,
+                result: { messages: [{ type: "human", content: "Fork: Hello" }] },
+            },
+        ],
+        metadata: {
+            source: "input",
+            step: 0,
+            parents: {},
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+        },
+        created_at: "2025-08-21T12:47:12.326Z",
+        checkpoint: {
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+            checkpoint_id: "1f07e8cf-53a8-6660-8000-f157c9cf7d66",
+            checkpoint_ns: "",
+            checkpoint_map: null,
+        },
+        parent_checkpoint: {
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+            checkpoint_id: "1f07e8cf-4cea-6530-ffff-0995a53299c5",
+            checkpoint_ns: "",
+            checkpoint_map: null,
+        },
+    },
+    {
+        values: {
+            messages: [
+                {
+                    content: "Hello",
+                    additional_kwargs: {},
+                    response_metadata: {},
+                    id: "ec300e63-1494-4ef6-936c-60d02d7bdce1",
+                    type: "human",
+                },
+                {
+                    content: "Hey",
+                    additional_kwargs: {},
+                    response_metadata: {},
+                    tool_call_chunks: [],
+                    id: "run-593064bd-dd07-4ed3-99c0-a918625f4884",
+                    tool_calls: [],
+                    invalid_tool_calls: [],
+                    type: "ai",
+                },
+            ],
+        },
+        next: [],
+        tasks: [],
+        metadata: {
+            source: "loop",
+            step: 1,
+            parents: {},
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+        },
+        created_at: "2025-08-21T12:47:12.285Z",
+        checkpoint: {
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+            checkpoint_id: "1f07e8cf-5344-64d0-8001-8a176e91d12f",
+            checkpoint_ns: "",
+            checkpoint_map: null,
+        },
+        parent_checkpoint: {
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+            checkpoint_id: "1f07e8cf-4cf8-6f90-8000-7707fd155a8a",
+            checkpoint_ns: "",
+            checkpoint_map: null,
+        },
+    },
+    {
+        values: {
+            messages: [
+                {
+                    content: "Hello",
+                    additional_kwargs: {},
+                    response_metadata: {},
+                    id: "ec300e63-1494-4ef6-936c-60d02d7bdce1",
+                    type: "human",
+                },
+                {
+                    content: "Hey",
+                    additional_kwargs: {},
+                    response_metadata: {},
+                    tool_call_chunks: [],
+                    id: "run-b86ef558-eaff-4838-bc03-218f20554a9f",
+                    tool_calls: [],
+                    invalid_tool_calls: [],
+                    type: "ai",
+                },
+            ],
+        },
+        next: [],
+        tasks: [],
+        metadata: {
+            source: "loop",
+            step: 1,
+            parents: {},
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+        },
+        created_at: "2025-08-21T12:47:11.936Z",
+        checkpoint: {
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+            checkpoint_id: "1f07e8cf-4ff0-6400-8001-a54aedf52a76",
+            checkpoint_ns: "",
+            checkpoint_map: null,
+        },
+        parent_checkpoint: {
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+            checkpoint_id: "1f07e8cf-4cf8-6f90-8000-7707fd155a8a",
+            checkpoint_ns: "",
+            checkpoint_map: null,
+        },
+    },
+    {
+        values: {
+            messages: [
+                {
+                    content: "Hello",
+                    additional_kwargs: {},
+                    response_metadata: {},
+                    id: "ec300e63-1494-4ef6-936c-60d02d7bdce1",
+                    type: "human",
+                },
+            ],
+        },
+        next: ["agent"],
+        tasks: [
+            {
+                id: "e3f503f1-73bc-5db1-8b4d-13f660ad1b51",
+                name: "agent",
+                error: null,
+                interrupts: [],
+                path: ["__pregel_pull", "agent"],
+                checkpoint: null,
+                state: null,
+                result: {
+                    messages: [
+                        {
+                            content: "Hey",
+                            additional_kwargs: {},
+                            response_metadata: {},
+                            tool_call_chunks: [],
+                            id: "run-b86ef558-eaff-4838-bc03-218f20554a9f",
+                            tool_calls: [],
+                            invalid_tool_calls: [],
+                            type: "ai",
+                        },
+                    ],
+                },
+            },
+        ],
+        metadata: {
+            source: "loop",
+            step: 0,
+            parents: {},
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+        },
+        created_at: "2025-08-21T12:47:11.625Z",
+        checkpoint: {
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+            checkpoint_id: "1f07e8cf-4cf8-6f90-8000-7707fd155a8a",
+            checkpoint_ns: "",
+            checkpoint_map: null,
+        },
+        parent_checkpoint: {
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+            checkpoint_id: "1f07e8cf-4cea-6530-ffff-0995a53299c5",
+            checkpoint_ns: "",
+            checkpoint_map: null,
+        },
+    },
+    {
+        values: { messages: [] },
+        next: ["__start__"],
+        tasks: [
+            {
+                id: "cddede95-d276-59f1-bc08-8051d6448734",
+                name: "__start__",
+                error: null,
+                interrupts: [],
+                path: ["__pregel_pull", "__start__"],
+                checkpoint: null,
+                state: null,
+                result: { messages: [{ type: "human", content: "Hello" }] },
+            },
+        ],
+        metadata: {
+            source: "input",
+            step: -1,
+            parents: {},
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+        },
+        created_at: "2025-08-21T12:47:11.619Z",
+        checkpoint: {
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+            checkpoint_id: "1f07e8cf-4cea-6530-ffff-0995a53299c5",
+            checkpoint_ns: "",
+            checkpoint_map: null,
+        },
+        parent_checkpoint: null,
+    },
+];
+const node = (value, paths = []) => ({
+    type: "node",
+    value: typeof value === "number" ? history.at(value) : value,
+    path: paths.map((v) => {
+        if (typeof v === "number") {
+            return history.at(v)?.checkpoint?.checkpoint_id;
+        }
+        return v?.checkpoint?.checkpoint_id;
+    }),
+});
+const fork = (...items) => ({ type: "fork", items });
+const sequence = (...items) => ({ type: "sequence", items });
+(0, vitest_1.it)("full tree", async () => {
+    const { rootSequence, paths } = (0, branching_js_1.getBranchSequence)(history);
+    vitest_1.expect
+        .soft(paths)
+        .toMatchObject(vitest_1.expect.arrayContaining([[5], [5, 4], [5, 3], [2]].map((p) => p.map((i) => history.at(i)?.checkpoint?.checkpoint_id))));
+    vitest_1.expect
+        .soft(rootSequence)
+        .toMatchObject(sequence(node(6), fork(sequence(node(5, [5]), fork(sequence(node(4, [5, 4])), sequence(node(3, [5, 3])))), sequence(node(2, [2]), node(1, [2]), node(0, [2])))));
+});
+(0, vitest_1.it)("partial tree", async () => {
+    (0, vitest_1.expect)((0, branching_js_1.getBranchSequence)(history.slice(0, 1))).toMatchObject({
+        paths: [],
+        rootSequence: sequence(node(0)),
+    });
+    (0, vitest_1.expect)((0, branching_js_1.getBranchSequence)(history.slice(0, 2))).toMatchObject({
+        paths: [],
+        rootSequence: sequence(node(1), node(0)),
+    });
+    (0, vitest_1.expect)((0, branching_js_1.getBranchSequence)(history.slice(0, 3))).toMatchObject({
+        paths: [],
+        rootSequence: sequence(node(2), node(1), node(0)),
+    });
+    (0, vitest_1.expect)((0, branching_js_1.getBranchSequence)(history.slice(0, 4))).toMatchObject({
+        paths: [],
+        rootSequence: sequence(node(2), node(1), node(0)),
+    });
+    (0, vitest_1.expect)((0, branching_js_1.getBranchSequence)(history.slice(0, 5))).toMatchObject({
+        paths: [],
+        rootSequence: sequence(node(2), node(1), node(0)),
+    });
+    (0, vitest_1.expect)((0, branching_js_1.getBranchSequence)(history.slice(0, 6))).toMatchObject({
+        paths: vitest_1.expect.arrayContaining([[5], [5, 4], [5, 3], [2]].map((p) => p.map((i) => history.at(i)?.checkpoint?.checkpoint_id))),
+        rootSequence: sequence(fork(sequence(node(5, [5]), fork(sequence(node(4, [5, 4])), sequence(node(3, [5, 3])))), sequence(node(2, [2]), node(1, [2]), node(0, [2])))),
+    });
+    (0, vitest_1.expect)((0, branching_js_1.getBranchSequence)(history.slice(0, 7))).toMatchObject({
+        paths: vitest_1.expect.arrayContaining([[5], [5, 4], [5, 3], [2]].map((p) => p.map((i) => history.at(i)?.checkpoint?.checkpoint_id))),
+        rootSequence: sequence(node(6), fork(sequence(node(5, [5]), fork(sequence(node(4, [5, 4])), sequence(node(3, [5, 3])))), sequence(node(2, [2]), node(1, [2]), node(0, [2])))),
+    });
+});

package/dist/ui/branching.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/ui/branching.test.js

@@ -0,0 +1,368 @@
+import { it, expect } from "vitest";
+import { getBranchSequence } from "./branching.js";
+const history = [
+    {
+        values: {
+            messages: [
+                {
+                    content: "Fork: Hello",
+                    additional_kwargs: {},
+                    response_metadata: {},
+                    id: "33357aea-9c2d-4718-92f4-20038d5a2d29",
+                    type: "human",
+                },
+                {
+                    content: "Hey",
+                    additional_kwargs: {},
+                    response_metadata: {},
+                    tool_call_chunks: [],
+                    id: "run-782a2f90-2e39-4c21-9ee6-0f38585a0ae6",
+                    tool_calls: [],
+                    invalid_tool_calls: [],
+                    type: "ai",
+                },
+            ],
+        },
+        next: [],
+        tasks: [],
+        metadata: {
+            source: "loop",
+            step: 2,
+            parents: {},
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+        },
+        created_at: "2025-08-21T12:47:12.640Z",
+        checkpoint: {
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+            checkpoint_id: "1f07e8cf-56a7-6000-8002-5e272b1d5285",
+            checkpoint_ns: "",
+            checkpoint_map: null,
+        },
+        parent_checkpoint: {
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+            checkpoint_id: "1f07e8cf-53aa-6d70-8001-2096b0bbf835",
+            checkpoint_ns: "",
+            checkpoint_map: null,
+        },
+    },
+    {
+        values: {
+            messages: [
+                {
+                    content: "Fork: Hello",
+                    additional_kwargs: {},
+                    response_metadata: {},
+                    id: "33357aea-9c2d-4718-92f4-20038d5a2d29",
+                    type: "human",
+                },
+            ],
+        },
+        next: ["agent"],
+        tasks: [
+            {
+                id: "680ee831-4d10-50f9-956f-e0d937321614",
+                name: "agent",
+                error: null,
+                interrupts: [],
+                path: ["__pregel_pull", "agent"],
+                checkpoint: null,
+                state: null,
+                result: {
+                    messages: [
+                        {
+                            content: "Hey",
+                            additional_kwargs: {},
+                            response_metadata: {},
+                            tool_call_chunks: [],
+                            id: "run-782a2f90-2e39-4c21-9ee6-0f38585a0ae6",
+                            tool_calls: [],
+                            invalid_tool_calls: [],
+                            type: "ai",
+                        },
+                    ],
+                },
+            },
+        ],
+        metadata: {
+            source: "loop",
+            step: 1,
+            parents: {},
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+        },
+        created_at: "2025-08-21T12:47:12.327Z",
+        checkpoint: {
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+            checkpoint_id: "1f07e8cf-53aa-6d70-8001-2096b0bbf835",
+            checkpoint_ns: "",
+            checkpoint_map: null,
+        },
+        parent_checkpoint: {
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+            checkpoint_id: "1f07e8cf-53a8-6660-8000-f157c9cf7d66",
+            checkpoint_ns: "",
+            checkpoint_map: null,
+        },
+    },
+    {
+        values: { messages: [] },
+        next: ["__start__"],
+        tasks: [
+            {
+                id: "4233f4c0-5ea2-5117-9153-95e5fe59eee3",
+                name: "__start__",
+                error: null,
+                interrupts: [],
+                path: ["__pregel_pull", "__start__"],
+                checkpoint: null,
+                state: null,
+                result: { messages: [{ type: "human", content: "Fork: Hello" }] },
+            },
+        ],
+        metadata: {
+            source: "input",
+            step: 0,
+            parents: {},
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+        },
+        created_at: "2025-08-21T12:47:12.326Z",
+        checkpoint: {
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+            checkpoint_id: "1f07e8cf-53a8-6660-8000-f157c9cf7d66",
+            checkpoint_ns: "",
+            checkpoint_map: null,
+        },
+        parent_checkpoint: {
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+            checkpoint_id: "1f07e8cf-4cea-6530-ffff-0995a53299c5",
+            checkpoint_ns: "",
+            checkpoint_map: null,
+        },
+    },
+    {
+        values: {
+            messages: [
+                {
+                    content: "Hello",
+                    additional_kwargs: {},
+                    response_metadata: {},
+                    id: "ec300e63-1494-4ef6-936c-60d02d7bdce1",
+                    type: "human",
+                },
+                {
+                    content: "Hey",
+                    additional_kwargs: {},
+                    response_metadata: {},
+                    tool_call_chunks: [],
+                    id: "run-593064bd-dd07-4ed3-99c0-a918625f4884",
+                    tool_calls: [],
+                    invalid_tool_calls: [],
+                    type: "ai",
+                },
+            ],
+        },
+        next: [],
+        tasks: [],
+        metadata: {
+            source: "loop",
+            step: 1,
+            parents: {},
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+        },
+        created_at: "2025-08-21T12:47:12.285Z",
+        checkpoint: {
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+            checkpoint_id: "1f07e8cf-5344-64d0-8001-8a176e91d12f",
+            checkpoint_ns: "",
+            checkpoint_map: null,
+        },
+        parent_checkpoint: {
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+            checkpoint_id: "1f07e8cf-4cf8-6f90-8000-7707fd155a8a",
+            checkpoint_ns: "",
+            checkpoint_map: null,
+        },
+    },
+    {
+        values: {
+            messages: [
+                {
+                    content: "Hello",
+                    additional_kwargs: {},
+                    response_metadata: {},
+                    id: "ec300e63-1494-4ef6-936c-60d02d7bdce1",
+                    type: "human",
+                },
+                {
+                    content: "Hey",
+                    additional_kwargs: {},
+                    response_metadata: {},
+                    tool_call_chunks: [],
+                    id: "run-b86ef558-eaff-4838-bc03-218f20554a9f",
+                    tool_calls: [],
+                    invalid_tool_calls: [],
+                    type: "ai",
+                },
+            ],
+        },
+        next: [],
+        tasks: [],
+        metadata: {
+            source: "loop",
+            step: 1,
+            parents: {},
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+        },
+        created_at: "2025-08-21T12:47:11.936Z",
+        checkpoint: {
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+            checkpoint_id: "1f07e8cf-4ff0-6400-8001-a54aedf52a76",
+            checkpoint_ns: "",
+            checkpoint_map: null,
+        },
+        parent_checkpoint: {
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+            checkpoint_id: "1f07e8cf-4cf8-6f90-8000-7707fd155a8a",
+            checkpoint_ns: "",
+            checkpoint_map: null,
+        },
+    },
+    {
+        values: {
+            messages: [
+                {
+                    content: "Hello",
+                    additional_kwargs: {},
+                    response_metadata: {},
+                    id: "ec300e63-1494-4ef6-936c-60d02d7bdce1",
+                    type: "human",
+                },
+            ],
+        },
+        next: ["agent"],
+        tasks: [
+            {
+                id: "e3f503f1-73bc-5db1-8b4d-13f660ad1b51",
+                name: "agent",
+                error: null,
+                interrupts: [],
+                path: ["__pregel_pull", "agent"],
+                checkpoint: null,
+                state: null,
+                result: {
+                    messages: [
+                        {
+                            content: "Hey",
+                            additional_kwargs: {},
+                            response_metadata: {},
+                            tool_call_chunks: [],
+                            id: "run-b86ef558-eaff-4838-bc03-218f20554a9f",
+                            tool_calls: [],
+                            invalid_tool_calls: [],
+                            type: "ai",
+                        },
+                    ],
+                },
+            },
+        ],
+        metadata: {
+            source: "loop",
+            step: 0,
+            parents: {},
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+        },
+        created_at: "2025-08-21T12:47:11.625Z",
+        checkpoint: {
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+            checkpoint_id: "1f07e8cf-4cf8-6f90-8000-7707fd155a8a",
+            checkpoint_ns: "",
+            checkpoint_map: null,
+        },
+        parent_checkpoint: {
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+            checkpoint_id: "1f07e8cf-4cea-6530-ffff-0995a53299c5",
+            checkpoint_ns: "",
+            checkpoint_map: null,
+        },
+    },
+    {
+        values: { messages: [] },
+        next: ["__start__"],
+        tasks: [
+            {
+                id: "cddede95-d276-59f1-bc08-8051d6448734",
+                name: "__start__",
+                error: null,
+                interrupts: [],
+                path: ["__pregel_pull", "__start__"],
+                checkpoint: null,
+                state: null,
+                result: { messages: [{ type: "human", content: "Hello" }] },
+            },
+        ],
+        metadata: {
+            source: "input",
+            step: -1,
+            parents: {},
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+        },
+        created_at: "2025-08-21T12:47:11.619Z",
+        checkpoint: {
+            thread_id: "efa80f4d-725f-4903-b19f-216309f060bc",
+            checkpoint_id: "1f07e8cf-4cea-6530-ffff-0995a53299c5",
+            checkpoint_ns: "",
+            checkpoint_map: null,
+        },
+        parent_checkpoint: null,
+    },
+];
+const node = (value, paths = []) => ({
+    type: "node",
+    value: typeof value === "number" ? history.at(value) : value,
+    path: paths.map((v) => {
+        if (typeof v === "number") {
+            return history.at(v)?.checkpoint?.checkpoint_id;
+        }
+        return v?.checkpoint?.checkpoint_id;
+    }),
+});
+const fork = (...items) => ({ type: "fork", items });
+const sequence = (...items) => ({ type: "sequence", items });
+it("full tree", async () => {
+    const { rootSequence, paths } = getBranchSequence(history);
+    expect
+        .soft(paths)
+        .toMatchObject(expect.arrayContaining([[5], [5, 4], [5, 3], [2]].map((p) => p.map((i) => history.at(i)?.checkpoint?.checkpoint_id))));
+    expect
+        .soft(rootSequence)
+        .toMatchObject(sequence(node(6), fork(sequence(node(5, [5]), fork(sequence(node(4, [5, 4])), sequence(node(3, [5, 3])))), sequence(node(2, [2]), node(1, [2]), node(0, [2])))));
+});
+it("partial tree", async () => {
+    expect(getBranchSequence(history.slice(0, 1))).toMatchObject({
+        paths: [],
+        rootSequence: sequence(node(0)),
+    });
+    expect(getBranchSequence(history.slice(0, 2))).toMatchObject({
+        paths: [],
+        rootSequence: sequence(node(1), node(0)),
+    });
+    expect(getBranchSequence(history.slice(0, 3))).toMatchObject({
+        paths: [],
+        rootSequence: sequence(node(2), node(1), node(0)),
+    });
+    expect(getBranchSequence(history.slice(0, 4))).toMatchObject({
+        paths: [],
+        rootSequence: sequence(node(2), node(1), node(0)),
+    });
+    expect(getBranchSequence(history.slice(0, 5))).toMatchObject({
+        paths: [],
+        rootSequence: sequence(node(2), node(1), node(0)),
+    });
+    expect(getBranchSequence(history.slice(0, 6))).toMatchObject({
+        paths: expect.arrayContaining([[5], [5, 4], [5, 3], [2]].map((p) => p.map((i) => history.at(i)?.checkpoint?.checkpoint_id))),
+        rootSequence: sequence(fork(sequence(node(5, [5]), fork(sequence(node(4, [5, 4])), sequence(node(3, [5, 3])))), sequence(node(2, [2]), node(1, [2]), node(0, [2])))),
+    });
+    expect(getBranchSequence(history.slice(0, 7))).toMatchObject({
+        paths: expect.arrayContaining([[5], [5, 4], [5, 3], [2]].map((p) => p.map((i) => history.at(i)?.checkpoint?.checkpoint_id))),
+        rootSequence: sequence(node(6), fork(sequence(node(5, [5]), fork(sequence(node(4, [5, 4])), sequence(node(3, [5, 3])))), sequence(node(2, [2]), node(1, [2]), node(0, [2])))),
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@langchain/langgraph-sdk",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Client library for interacting with the LangGraph API",
   "type": "module",
   "scripts": {