@langgraph-js/sdk 3.7.1 → 3.8.0

package/dist/vue/ChatContext.d.ts

@@ -33,6 +33,8 @@ export interface ChatProviderProps {
     showHistory?: boolean;
     showGraph?: boolean;
     fallbackToAvailableAssistants?: boolean;
+    /** 初始化时是否自动激活最近的历史会话（默认 false，创建新会话） */
+    autoRestoreLastSession?: boolean;
     onInitError?: (error: any, currentAgent: string) => void;
     client?: ILangGraphClient;
     legacyMode?: boolean;
@@ -48,51 +50,57 @@ export declare const useChatProvider: (props: ChatProviderProps) => {
             currentArtifactId: PreinitializedWritableAtom<[string, string] | null> & object;
             showArtifact: PreinitializedWritableAtom<boolean> & object;
             client: PreinitializedWritableAtom<import("../LangGraphClient.js").LangGraphClient<unknown> | null> & object;
+            history: PreinitializedWritableAtom<import("../History.js").History | null> & object;
+            sessions: PreinitializedWritableAtom<import("../History.js").SessionInfo[]> & object;
             renderMessages: PreinitializedWritableAtom<import("../LangGraphClient.js").RenderMessage[]> & object;
             userInput: PreinitializedWritableAtom<string> & object;
             loading: PreinitializedWritableAtom<boolean> & object;
             inChatError: PreinitializedWritableAtom<string | null> & object;
             currentAgent: PreinitializedWritableAtom<string> & object;
+            currentChatId: PreinitializedWritableAtom<string | null> & object;
+            currentNodeName: PreinitializedWritableAtom<string> & object;
+            tools: PreinitializedWritableAtom<import("../index.js").UnionTool<any, Object, any>[]> & object;
             collapsedTools: PreinitializedWritableAtom<string[]> & object;
+            showGraph: PreinitializedWritableAtom<boolean> & object;
+            graphVisualize: PreinitializedWritableAtom<import("@langchain/langgraph-sdk").AssistantGraph | null> & object;
             showHistory: PreinitializedWritableAtom<boolean> & object;
             historyList: PreinitializedWritableAtom<import("@langchain/langgraph-sdk").Thread<{
                 messages: import("@langchain/langgraph-sdk").Message[];
             }>[]> & object;
-            currentChatId: PreinitializedWritableAtom<string | null> & object;
-            showGraph: PreinitializedWritableAtom<boolean> & object;
-            graphVisualize: PreinitializedWritableAtom<import("@langchain/langgraph-sdk").AssistantGraph | null> & object;
-            currentNodeName: PreinitializedWritableAtom<string> & object;
-            tools: PreinitializedWritableAtom<import("../index.js").UnionTool<any, Object, any>[]> & object;
         };
         mutations: {
             setCurrentArtifactById: (id: string, tool_id: string) => void;
             setShowArtifact: (show: boolean) => void;
-            refreshTools: () => Promise<void>;
-            setTools(new_tools: import("../index.js").UnionTool<any>[]): void;
-            isFELocking(): boolean | undefined;
-            getClient(): import("../LangGraphClient.js").LangGraphClient<unknown> | null;
-            initClient: () => Promise<import("../LangGraphClient.js").LangGraphClient<unknown>>;
+            initClient: () => Promise<import("../History.js").History>;
+            getClient: () => import("../LangGraphClient.js").LangGraphClient<unknown> | null;
+            getHistory: () => import("../History.js").History | null;
+            activateSession: (sessionId: string) => Promise<void>;
+            createNewSession: () => Promise<void>;
+            refreshSessionList: () => Promise<void>;
+            refreshHistoryList: () => Promise<void>;
             sendMessage: (message?: import("@langchain/langgraph-sdk").Message[], extraData?: import("../LangGraphClient.js").SendMessageOptions, withoutCheck?: boolean) => Promise<void>;
             stopGeneration: () => void;
+            setUserInput: (input: string) => void;
+            revertChatTo(messageId: string, resend?: boolean, sendOptions?: import("../LangGraphClient.js").SendMessageOptions & import("../time-travel/index.js").RevertChatToOptions): Promise<void>;
+            refreshTools: () => Promise<void>;
+            setTools(new_tools: import("../index.js").UnionTool<any>[]): void;
             toggleToolCollapse: (toolId: string) => void;
+            getToolUIRender: (tool_name: string) => ((message: import("../LangGraphClient.js").RenderMessage) => Object) | null;
+            isFELocking: () => boolean | undefined;
             toggleHistoryVisible: () => void;
-            refreshHistoryList: () => Promise<void>;
+            toggleGraphVisible(): void;
+            refreshGraph: () => Promise<void>;
+            setCurrentAgent(agent: string): Promise<import("../History.js").History>;
             addToHistory: (thread: import("@langchain/langgraph-sdk").Thread<{
                 messages: import("@langchain/langgraph-sdk").Message[];
             }>) => void;
-            revertChatTo(messageId: string, resend?: boolean, sendOptions?: import("../LangGraphClient.js").SendMessageOptions & import("../time-travel/index.js").RevertChatToOptions): Promise<void>;
-            setUserInput(input: string): void;
-            setCurrentAgent(agent: string): Promise<void>;
-            toggleGraphVisible(): void;
-            refreshGraph: () => Promise<void>;
-            createNewChat(): void;
-            toHistoryChat(thread: import("@langchain/langgraph-sdk").Thread<{
+            createNewChat: () => Promise<void>;
+            toHistoryChat: (thread: import("@langchain/langgraph-sdk").Thread<{
                 messages: import("@langchain/langgraph-sdk").Message[];
-            }>): Promise<import("@langchain/langgraph-sdk").Thread<unknown> | undefined>;
+            }>) => Promise<void>;
             deleteHistoryChat(thread: import("@langchain/langgraph-sdk").Thread<{
                 messages: import("@langchain/langgraph-sdk").Message[];
             }>): Promise<void>;
-            getToolUIRender: (tool_name: string) => ((message: import("../LangGraphClient.js").RenderMessage) => Object) | null;
         };
     }>;
 };
@@ -125,6 +133,10 @@ export declare const ChatProvider: import("vue").DefineComponent<import("vue").E
         type: PropType<boolean>;
         default: boolean;
     };
+    autoRestoreLastSession: {
+        type: PropType<boolean>;
+        default: boolean;
+    };
     onInitError: {
         type: PropType<(error: any, currentAgent: string) => void>;
         default: undefined;
@@ -156,6 +168,10 @@ export declare const ChatProvider: import("vue").DefineComponent<import("vue").E
         type: PropType<boolean>;
         default: boolean;
     };
+    autoRestoreLastSession: {
+        type: PropType<boolean>;
+        default: boolean;
+    };
     onInitError: {
         type: PropType<(error: any, currentAgent: string) => void>;
         default: undefined;
@@ -163,9 +179,10 @@ export declare const ChatProvider: import("vue").DefineComponent<import("vue").E
 }>> & Readonly<{}>, {
     apiUrl: string;
     defaultHeaders: Record<string, string>;
-    showHistory: boolean;
     showGraph: boolean;
+    showHistory: boolean;
     defaultAgent: string;
     withCredentials: boolean;
+    autoRestoreLastSession: boolean;
     onInitError: (error: any, currentAgent: string) => void;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;

package/dist/vue/ChatContext.js

@@ -51,6 +51,7 @@ export const useChatProvider = (props) => {
         showHistory: props.showHistory,
         showGraph: props.showGraph,
         fallbackToAvailableAssistants: props.fallbackToAvailableAssistants,
+        autoRestoreLastSession: props.autoRestoreLastSession,
     });
     const unionStore = useUnionStoreVue(store, useStore);
     // 提供 store 给子组件
@@ -106,6 +107,10 @@ export const ChatProvider = defineComponent({
             type: Boolean,
             default: false,
         },
+        autoRestoreLastSession: {
+            type: Boolean,
+            default: false,
+        },
         onInitError: {
             type: Function,
             default: undefined,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@langgraph-js/sdk",
-  "version": "3.7.1",
+  "version": "3.8.0",
   "description": "The UI SDK for LangGraph - seamlessly integrate your AI agents with frontend interfaces",
   "main": "dist/index.js",
   "type": "module",

package/src/History.ts

@@ -0,0 +1,294 @@
+import { LangGraphClient, LangGraphClientConfig } from "./LangGraphClient.js";
+import type { Thread } from "@langchain/langgraph-sdk";
+
+export interface SessionInfo {
+    /** 会话唯一标识，同时也是 threadId */
+    sessionId: string;
+    /** LangGraphClient 实例（懒加载） */
+    client?: LangGraphClient;
+    /** Thread 信息（懒加载，第一条消息后才创建） */
+    thread?: Thread<any>;
+    /** Agent 名称 */
+    agentName: string;
+}
+
+export interface CreateSessionOptions {
+    /** 会话 ID / Thread ID，不提供则自动生成 */
+    sessionId?: string;
+    /** Agent 名称 */
+    agentName?: string;
+    /** 是否从已有 Thread 恢复会话 */
+    restore?: boolean;
+    /** Graph ID */
+    graphId?: string;
+}
+
+/**
+ * @zh History 类用于管理多个 LangGraphClient 实例，支持多会话场景
+ * @en History class manages multiple LangGraphClient instances for multi-session scenarios
+ */
+export class History {
+    /** 存储所有会话的 Map */
+    private sessions: Map<string, SessionInfo> = new Map();
+    /** 当前活跃的会话 ID */
+    private activeSessionId: string | null = null;
+    /** 客户端配置，用于创建新的 LangGraphClient 实例 */
+    private clientConfig: LangGraphClientConfig;
+    /** 虚拟 Client，用于查询操作（不绑定特定 Thread） */
+    private virtualClient: LangGraphClient;
+
+    constructor(clientConfig: LangGraphClientConfig) {
+        this.clientConfig = clientConfig;
+        this.virtualClient = new LangGraphClient(clientConfig);
+    }
+
+    /**
+     * @zh 创建新会话（延迟创建 Thread，直到发送第一条消息）
+     * @en Creates a new session (lazy Thread creation until first message)
+     */
+    async createSession(options: CreateSessionOptions = {}): Promise<SessionInfo> {
+        const sessionId = options.sessionId || this.generateSessionId();
+        const agentName = options.agentName || this.virtualClient.getCurrentAssistant()?.graph_id;
+
+        if (!agentName) {
+            throw new Error("Agent name is required. Please call init() first or provide agentName.");
+        }
+
+        if (this.sessions.has(sessionId)) {
+            throw new Error(`Session ${sessionId} already exists`);
+        }
+
+        const sessionInfo: SessionInfo = {
+            sessionId,
+            agentName,
+        };
+
+        // 如果是从已有 Thread 恢复，则立即获取 Thread
+        if (options.restore) {
+            sessionInfo.thread = (await this.virtualClient.threads.get(sessionId)) as Thread<any>;
+        }
+        // 否则 thread 为 undefined，等待第一条消息时由 Client 自动创建
+
+        this.sessions.set(sessionId, sessionInfo);
+
+        return sessionInfo;
+    }
+
+    /**
+     * @zh 激活指定会话（懒加载创建 Client）
+     * @en Activates the specified session (lazy load client)
+     */
+    async activateSession(sessionId: string): Promise<SessionInfo> {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            throw new Error(`Session ${sessionId} not found`);
+        }
+
+        // 懒加载：只在激活时创建 Client
+        if (!session.client) {
+            const client = new LangGraphClient(this.clientConfig);
+            await client.initAssistant(session.agentName);
+
+            // 只有在有 thread 的情况下才重置（恢复已有会话）
+            // 新会话的 thread 会在发送第一条消息时自动创建
+            if (session.thread) {
+                await client.resetThread(session.agentName, sessionId);
+            }
+
+            session.client = client;
+        }
+        const lastSession = this.activeSessionId && this.sessions.get(this.activeSessionId);
+        // 空闲的 client 就需要销毁
+        if (lastSession && lastSession.client?.status === "idle") {
+            lastSession.client?.reset();
+            lastSession.client = undefined;
+        }
+        this.activeSessionId = sessionId;
+        return session;
+    }
+
+    /**
+     * @zh 获取当前活跃的会话
+     * @en Gets the current active session
+     */
+    getActiveSession(): SessionInfo | null {
+        if (!this.activeSessionId) {
+            return null;
+        }
+        return this.sessions.get(this.activeSessionId) || null;
+    }
+
+    /**
+     * @zh 获取指定会话
+     * @en Gets the specified session
+     */
+    getSession(sessionId: string): SessionInfo | null {
+        return this.sessions.get(sessionId) || null;
+    }
+
+    /**
+     * @zh 获取所有会话
+     * @en Gets all sessions
+     */
+    getAllSessions(): SessionInfo[] {
+        return Array.from(this.sessions.values());
+    }
+
+    /**
+     * @zh 删除指定会话
+     * @en Deletes the specified session
+     */
+    async deleteSession(sessionId: string): Promise<boolean> {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            return false;
+        }
+
+        // 如果删除的是当前活跃会话，清空活跃会话
+        if (this.activeSessionId === sessionId) {
+            this.activeSessionId = null;
+        }
+
+        // 删除对应的远程 Thread
+        try {
+            await this.virtualClient.deleteThread(sessionId);
+        } catch (error) {
+            console.warn(`Failed to delete thread for session ${sessionId}:`, error);
+        }
+
+        this.sessions.delete(sessionId);
+        return true;
+    }
+
+    /**
+     * @zh 清空所有会话
+     * @en Clears all sessions
+     */
+    async clearAllSessions(): Promise<void> {
+        const sessionIds = Array.from(this.sessions.keys());
+        for (const sessionId of sessionIds) {
+            await this.deleteSession(sessionId);
+        }
+        this.activeSessionId = null;
+    }
+
+    /**
+     * @zh 获取会话数量
+     * @en Gets the number of sessions
+     */
+    getSessionCount(): number {
+        return this.sessions.size;
+    }
+
+    /**
+     * @zh 生成会话 ID (UUID v4 格式)
+     * @en Generates a session ID (UUID v4 format)
+     */
+    private generateSessionId(): string {
+        // 优先使用 crypto.randomUUID (Node.js 15.6+, 浏览器支持)
+        if (typeof crypto !== "undefined" && crypto.randomUUID) {
+            return crypto.randomUUID();
+        }
+
+        // 降级方案：生成符合 UUID v4 格式的随机 ID
+        return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+            const r = (Math.random() * 16) | 0;
+            const v = c === "x" ? r : (r & 0x3) | 0x8;
+            return v.toString(16);
+        });
+    }
+
+    /**
+     * @zh 从已有的 Thread 添加会话（仅添加元数据，不创建 Client）
+     * @en Adds a session from an existing Thread (metadata only, no client created)
+     */
+    async addSessionFromThread(threadId: string, agentName?: string): Promise<SessionInfo> {
+        const agent = agentName || this.virtualClient.getCurrentAssistant()?.graph_id;
+        if (!agent) {
+            throw new Error("Agent name is required. Please call init() first or provide agentName.");
+        }
+
+        return this.createSession({
+            sessionId: threadId,
+            agentName: agent,
+            restore: true,
+        });
+    }
+
+    /**
+     * @zh 获取当前活跃的客户端
+     * @en Gets the current active client
+     */
+    getActiveClient(): LangGraphClient | null {
+        const session = this.getActiveSession();
+        return session?.client || null;
+    }
+
+    /**
+     * @zh 从远程列出所有会话
+     * @en Lists all sessions from remote
+     */
+    async listRemoteSessions(
+        options: {
+            sortOrder?: "asc" | "desc";
+            sortBy?: "created_at" | "updated_at";
+            offset?: number;
+            limit?: number;
+        } = {}
+    ) {
+        return this.virtualClient.listThreads(options);
+    }
+
+    /**
+     * @zh 从远程同步会话到本地（仅同步元数据，不创建 Client）
+     * @en Syncs sessions from remote to local (metadata only, no client created)
+     */
+    async syncFromRemote(
+        options: {
+            limit?: number;
+            agentName?: string;
+        } = {}
+    ): Promise<SessionInfo[]> {
+        const agentName = options.agentName || this.virtualClient.getCurrentAssistant()?.graph_id;
+        if (!agentName) {
+            throw new Error("Agent name is required. Please call init() first or provide agentName.");
+        }
+
+        const threads = await this.listRemoteSessions({
+            limit: options.limit || 100,
+            sortBy: "updated_at",
+            sortOrder: "desc",
+        });
+
+        const syncedSessions: SessionInfo[] = [];
+
+        for (const thread of threads) {
+            const threadId = thread.thread_id;
+
+            // 更新或创建会话信息
+            if (this.sessions.has(threadId)) {
+                const session = this.sessions.get(threadId)!;
+                session.thread = thread;
+                syncedSessions.push(session);
+            } else {
+                const sessionInfo: SessionInfo = {
+                    sessionId: threadId,
+                    thread,
+                    agentName,
+                };
+                this.sessions.set(threadId, sessionInfo);
+                syncedSessions.push(sessionInfo);
+            }
+        }
+
+        return syncedSessions;
+    }
+
+    /**
+     * @zh 初始化 History（必须先调用）
+     * @en Initializes History (must be called first)
+     */
+    async init(agentName?: string) {
+        return this.virtualClient.initAssistant(agentName);
+    }
+}

package/src/LangGraphClient.ts

@@ -121,6 +121,8 @@ export class LangGraphClient<TStateType = unknown> extends EventEmitter<LangGrap
     /** Message 处理器 */
     private messageProcessor: MessageProcessor;
     private legacyMode: boolean;
+    /** 当前流式状态 */
+    private _status: "idle" | "busy" | "interrupted" | "error" = "idle";
     constructor(config: LangGraphClientConfig) {
         super();
         this.client = config.client;
@@ -142,6 +144,11 @@ export class LangGraphClient<TStateType = unknown> extends EventEmitter<LangGrap
     get runs(): ILangGraphClient["runs"] {
         return this.client.runs;
     }
+
+    /** 获取当前流式状态 */
+    get status() {
+        return this._status;
+    }
     private listAssistants() {
         return this.assistants.search({
             metadata: null,
@@ -211,10 +218,19 @@ export class LangGraphClient<TStateType = unknown> extends EventEmitter<LangGrap
      * @zh 列出所有的 Thread。
      * @en Lists all Threads.
      */
-    async listThreads() {
+    async listThreads(
+        options: {
+            sortOrder?: "asc" | "desc";
+            sortBy?: "created_at" | "updated_at";
+            offset?: number;
+            limit?: number;
+        } = {}
+    ) {
         return this.threads.search({
-            sortOrder: "desc",
-            sortBy: "updated_at",
+            sortOrder: options.sortOrder || "desc",
+            sortBy: options.sortBy || "updated_at",
+            offset: options.offset || 0,
+            limit: options.limit || 10,
         });
     }
     async deleteThread(threadId: string) {
@@ -350,6 +366,7 @@ export class LangGraphClient<TStateType = unknown> extends EventEmitter<LangGrap
               ];
 
         const streamRecord: any[] = [];
+        this._status = "busy";
         this.emit("start", {
             event: "start",
         });
@@ -396,6 +413,7 @@ export class LangGraphClient<TStateType = unknown> extends EventEmitter<LangGrap
         const data = await this.runFETool();
         if (data) streamRecord.push(...data);
         this.humanInTheLoop = null;
+        this._status = "idle";
         this.emit("done", {
             event: "done",
         });
@@ -427,6 +445,7 @@ export class LangGraphClient<TStateType = unknown> extends EventEmitter<LangGrap
         if (chunk.event === "metadata") {
             this.currentRun = chunk.data;
         } else if (chunk.event === "error" || chunk.event === "Error" || chunk.event === "__stream_error__") {
+            this._status = "error";
             this.emit("error", chunk);
         } else if (chunk.event === "messages/metadata") {
             Object.assign(this.messagesMetadata, chunk.data);
@@ -444,6 +463,7 @@ export class LangGraphClient<TStateType = unknown> extends EventEmitter<LangGrap
             };
 
             if (data.__interrupt__) {
+                this._status = "interrupted";
                 this.humanInTheLoop = camelcaseKeys(data.__interrupt__, {
                     deep: true,
                 });
@@ -481,6 +501,7 @@ export class LangGraphClient<TStateType = unknown> extends EventEmitter<LangGrap
                 // json 校验
                 return this.callFETool(toolMessage, tool.args);
             });
+            this._status = "interrupted";
             this.currentThread!.status = "interrupted"; // 修复某些机制下，状态不为 interrupted 与后端有差异
             return Promise.all(result);
         }
@@ -545,6 +566,7 @@ export class LangGraphClient<TStateType = unknown> extends EventEmitter<LangGrap
         this.messageProcessor.clearStreamingMessages();
         this.currentRun = undefined;
         this.tools.clearWaiting();
+        this._status = "idle";
         this.emit("value", {
             event: "messages/partial",
             data: {

package/src/index.ts

@@ -7,3 +7,4 @@ export * from "./ToolManager.js";
 export * from "./TestKit.js";
 export * from "./artifacts/index.js";
 export * from "./client/index.js";
+export * from "./History.js";

package/src/react/ChatContext.ts

@@ -23,6 +23,8 @@ interface ChatProviderProps {
     showHistory?: boolean;
     showGraph?: boolean;
     fallbackToAvailableAssistants?: boolean;
+    /** 初始化时是否自动激活最近的历史会话（默认 false，创建新会话） */
+    autoRestoreLastSession?: boolean;
     onInitError?: (error: any, currentAgent: string) => void;
     client?: ILangGraphClient;
     legacyMode?: boolean;
@@ -37,6 +39,7 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
     showHistory = false,
     showGraph = false,
     fallbackToAvailableAssistants = false,
+    autoRestoreLastSession = false,
     onInitError,
     client,
     legacyMode = false,
@@ -73,8 +76,9 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
             showHistory,
             showGraph,
             fallbackToAvailableAssistants,
+            autoRestoreLastSession,
         });
-    }, [defaultAgent, apiUrl, stableHeaders, withCredentials, showHistory, showGraph, fallbackToAvailableAssistants]);
+    }, [defaultAgent, apiUrl, stableHeaders, withCredentials, showHistory, showGraph, fallbackToAvailableAssistants, autoRestoreLastSession]);
 
     const unionStore = useUnionStore(store, useStore);