@langgraph-js/sdk 4.5.0 → 4.6.1

package/.turbo/turbo-build.log

@@ -0,0 +1,4 @@
+
+> @langgraph-js/sdk@4.6.0 build /Users/konghayao/code/ai/YaoAgent/apps/langgraph-client
+> tsc
+

package/dist/History.d.ts

@@ -9,6 +9,8 @@ export interface SessionInfo {
     thread?: Thread<any>;
     /** Agent 名称 */
     agentName: string;
+    /** 会话元数据 */
+    metadata?: Record<string, any>;
 }
 export interface CreateSessionOptions {
     /** 会话 ID / Thread ID，不提供则自动生成 */
@@ -19,6 +21,8 @@ export interface CreateSessionOptions {
     restore?: boolean;
     /** Graph ID */
     graphId?: string;
+    /** 会话元数据 */
+    metadata?: Record<string, any>;
 }
 /**
  * @zh History 类用于管理多个 LangGraphClient 实例，支持多会话场景
@@ -94,11 +98,17 @@ export declare class History {
      * @en Lists all sessions from remote
      */
     listRemoteSessions(options?: {
-        sortOrder?: "asc" | "desc";
-        sortBy?: "created_at" | "updated_at";
-        offset?: number;
+        ids?: string[];
+        metadata?: Record<string, any>;
+        status?: "idle" | "busy" | "interrupted" | "error";
+        values?: any;
         limit?: number;
-    }): Promise<Thread<unknown>[]>;
+        offset?: number;
+        sortBy?: "thread_id" | "status" | "created_at" | "updated_at";
+        sortOrder?: "asc" | "desc";
+        select?: Array<"thread_id" | "created_at" | "updated_at" | "metadata" | "config" | "context" | "status" | "values" | "interrupts">;
+        withoutDetails?: boolean;
+    }): Promise<Thread<unknown, unknown>[]>;
     /**
      * @zh 从远程同步会话到本地（仅同步元数据，不创建 Client）
      * @en Syncs sessions from remote to local (metadata only, no client created)

package/dist/History.js

@@ -32,6 +32,7 @@ export class History {
         const sessionInfo = {
             sessionId,
             agentName,
+            metadata: options.metadata,
         };
         // 如果是从已有 Thread 恢复，则立即获取 Thread
         if (options.restore) {
@@ -54,8 +55,14 @@ export class History {
         if (!session.client) {
             const client = new LangGraphClient(this.clientConfig);
             await client.initAssistant(session.agentName);
-            // 只有在有 thread 的情况下才重置（恢复已有会话）
-            // 新会话的 thread 会在发送第一条消息时自动创建
+            // 如果有 metadata，立即创建 Thread 并带上 metadata
+            if (session.metadata && !session.thread) {
+                await client.createThread({
+                    graphId: client.getCurrentAssistant()?.graph_id,
+                    metadata: session.metadata,
+                });
+            }
+            // 如果已有 thread 或者必须重置，则从历史恢复
             if (session.thread || mustResetStream) {
                 await client.resetThread(session.agentName, sessionId);
             }

package/dist/LangGraphClient.d.ts

@@ -43,6 +43,7 @@ export type SendMessageOptions = {
     };
     command?: Command;
     joinRunId?: string;
+    metadata?: Record<string, any>;
 };
 export interface LangGraphClientConfig {
     apiUrl?: string;
@@ -153,18 +154,18 @@ export declare class LangGraphClient<TStateType = unknown> extends EventEmitter<
             threadId?: string;
             ifExists?: import("@langchain/langgraph-sdk").OnConflictBehavior;
             graphId?: string;
-        }): Promise<Thread<TStateType>>;
+        }): Promise<Thread<TStateType, unknown>>;
         search(query?: {
             metadata?: import("@langchain/langgraph-sdk").Metadata;
-            limit?: number;
+            limit? /** 自定义客户端实现，如果不提供则使用官方 Client */: number;
             offset?: number;
             status?: import("@langchain/langgraph-sdk").ThreadStatus;
             sortBy?: import("@langgraph-js/pure-graph/dist/types.js").ThreadSortBy;
             sortOrder?: import("@langgraph-js/pure-graph/dist/types.js").SortOrder;
-        }): Promise<Thread<TStateType>[]>;
-        get(threadId: string): Promise<Thread<TStateType>>;
+        }): Promise<Thread<TStateType, unknown>[]>;
+        get(threadId: string): Promise<Thread<TStateType, unknown>>;
         delete(threadId: string): Promise<void>;
-        updateState(threadId: string, thread: Partial<Thread<TStateType>>): Promise<Pick<import("@langchain/langgraph-sdk").Config, "configurable">>;
+        updateState(threadId: string, thread: Partial<Thread<TStateType, unknown>>): Promise<Pick<import("@langchain/langgraph-sdk").Config, "configurable">>;
     };
     /** 代理 runs 属性到内部 client */
     get runs(): ILangGraphClient["runs"];
@@ -182,27 +183,34 @@ export declare class LangGraphClient<TStateType = unknown> extends EventEmitter<
      * @zh 创建一个新的 Thread。
      * @en Creates a new Thread.
      */
-    createThread({ threadId, graphId }?: {
+    createThread({ threadId, graphId, metadata }?: {
         threadId?: string;
         graphId?: string;
-    }): Promise<Thread<TStateType>>;
+        metadata?: Record<string, any>;
+    }): Promise<Thread<TStateType, unknown>>;
     graphVisualize(): Promise<import("@langchain/langgraph-sdk").AssistantGraph>;
     /**
      * @zh 列出所有的 Thread。
      * @en Lists all Threads.
      */
     listThreads(options?: {
-        sortOrder?: "asc" | "desc";
-        sortBy?: "created_at" | "updated_at";
-        offset?: number;
+        ids?: string[];
+        metadata?: Record<string, any>;
+        status?: "idle" | "busy" | "interrupted" | "error";
+        values?: any;
         limit?: number;
-    }): Promise<Thread<TStateType>[]>;
+        offset?: number;
+        sortBy?: "thread_id" | "status" | "created_at" | "updated_at";
+        sortOrder?: "asc" | "desc";
+        select?: Array<"thread_id" | "created_at" | "updated_at" | "metadata" | "config" | "context" | "status" | "values" | "interrupts">;
+        withoutDetails?: boolean;
+    }): Promise<Thread<TStateType, unknown>[]>;
     deleteThread(threadId: string): Promise<void>;
     /**
      * @zh 从历史中恢复 Thread 数据。
      * @en Resets the Thread data from history.
      */
-    resetThread(agent: string, threadId: string): Promise<Thread<TStateType>>;
+    resetThread(agent: string, threadId: string): Promise<Thread<TStateType, unknown>>;
     resetStream(): Promise<void>;
     cloneMessage(message: Message): Message;
     /**
@@ -241,7 +249,7 @@ export declare class LangGraphClient<TStateType = unknown> extends EventEmitter<
      * @zh 发送消息到 LangGraph 后端。
      * @en Sends a message to the LangGraph backend.
      */
-    sendMessage(input: string | Message[], { joinRunId, extraParams, _debug, command }?: SendMessageOptions): Promise<any[]>;
+    sendMessage(input: string | Message[], { joinRunId, extraParams, _debug, command, metadata }?: SendMessageOptions): Promise<any[]>;
     /** 当前子图位置，但是依赖 stream，不太适合稳定使用*/
     private graphPosition;
     getGraphPosition(): {
@@ -283,7 +291,7 @@ export declare class LangGraphClient<TStateType = unknown> extends EventEmitter<
      * @zh 获取当前的 Thread。
      * @en Gets the current Thread.
      */
-    getCurrentThread(): Thread<TStateType> | null;
+    getCurrentThread(): Thread<TStateType, unknown> | null;
     /**
      * @zh 获取当前的 Assistant。
      * @en Gets the current Assistant.

package/dist/LangGraphClient.js

@@ -89,9 +89,10 @@ export class LangGraphClient extends EventEmitter {
      * @zh 创建一个新的 Thread。
      * @en Creates a new Thread.
      */
-    async createThread({ threadId, graphId } = {}) {
+    async createThread({ threadId, graphId, metadata } = {}) {
         try {
             this.currentThread = await this.threads.create({
+                metadata,
                 threadId,
                 graphId,
             });
@@ -112,14 +113,39 @@ export class LangGraphClient extends EventEmitter {
      * @en Lists all Threads.
      */
     async listThreads(options = {}) {
-        return this.threads.search({
-            sortOrder: options.sortOrder || "desc",
-            sortBy: options.sortBy || "updated_at",
-            offset: options.offset || 0,
-            limit: options.limit || 10,
-            /** @ts-ignore: 用于删除不需要的字段 */
-            without_details: true,
-        });
+        const searchOptions = {};
+        if (options.ids)
+            searchOptions.ids = options.ids;
+        if (options.metadata)
+            searchOptions.metadata = options.metadata;
+        if (options.status)
+            searchOptions.status = options.status;
+        if (options.values)
+            searchOptions.values = options.values;
+        if (options.limit !== undefined)
+            searchOptions.limit = options.limit;
+        if (options.offset !== undefined)
+            searchOptions.offset = options.offset;
+        if (options.sortBy)
+            searchOptions.sortBy = options.sortBy;
+        if (options.sortOrder)
+            searchOptions.sortOrder = options.sortOrder;
+        if (options.select)
+            searchOptions.select = options.select;
+        if (options.withoutDetails !== undefined)
+            searchOptions.without_details = options.withoutDetails;
+        // 设置默认值
+        if (!options.sortBy)
+            searchOptions.sortBy = "updated_at";
+        if (!options.sortOrder)
+            searchOptions.sortOrder = "desc";
+        if (!options.limit)
+            searchOptions.limit = 10;
+        if (!options.offset)
+            searchOptions.offset = 0;
+        if (!options.withoutDetails)
+            searchOptions.without_details = true;
+        return this.threads.search(searchOptions);
     }
     async deleteThread(threadId) {
         return this.threads.delete(threadId);
@@ -224,12 +250,15 @@ export class LangGraphClient extends EventEmitter {
      * @zh 发送消息到 LangGraph 后端。
      * @en Sends a message to the LangGraph backend.
      */
-    async sendMessage(input, { joinRunId, extraParams, _debug, command } = {}) {
+    async sendMessage(input, { joinRunId, extraParams, _debug, command, metadata } = {}) {
         if (!this.currentAssistant) {
             throw new Error("Thread or Assistant not initialized");
         }
         if (!this.currentThread) {
-            await this.createThread({ graphId: this.currentAssistant.graph_id });
+            await this.createThread({
+                graphId: this.currentAssistant.graph_id,
+                metadata,
+            });
             this.emit("thread", {
                 event: "thread/create",
                 data: {

package/dist/TestKit.d.ts

@@ -146,169 +146,6 @@ export declare class TestLangGraphChat {
      */
     findLast(type: "human" | "ai" | "tool", options?: {
         before?: (item: RenderMessage) => boolean;
-    }): ({
-        additional_kwargs?: {
-            [x: string]: unknown;
-        } | undefined;
-        content: string | ({
-            type: "text";
-            text: string;
-        } | {
-            type: "image_url";
-            image_url: string | {
-                url: string;
-                detail?: ("auto" | "low" | "high") | undefined;
-            };
-        })[];
-        id?: string | undefined;
-        name?: string | undefined;
-        response_metadata?: Record<string, unknown> | undefined;
-    } & {
-        type: "human";
-        example?: boolean | undefined;
-    } & {
-        name?: string;
-        node_name?: string;
-        tool_input?: string;
-        additional_kwargs?: {
-            create_time: string;
-            update_time: string;
-            done?: boolean;
-            tool_calls?: {
-                function: {
-                    arguments: string;
-                };
-            }[];
-        };
-        usage_metadata?: {
-            total_tokens: number;
-            input_tokens: number;
-            output_tokens: number;
-        };
-        tool_call_id?: string;
-        sub_messages?: RenderMessage[];
-        spend_time?: number;
-        unique_id?: string;
-        done?: boolean;
-    }) | ({
-        additional_kwargs?: {
-            [x: string]: unknown;
-        } | undefined;
-        content: string | ({
-            type: "text";
-            text: string;
-        } | {
-            type: "image_url";
-            image_url: string | {
-                url: string;
-                detail?: ("auto" | "low" | "high") | undefined;
-            };
-        })[];
-        id?: string | undefined;
-        name?: string | undefined;
-        response_metadata?: Record<string, unknown> | undefined;
-    } & {
-        type: "ai";
-        example?: boolean | undefined;
-        tool_calls?: {
-            name: string;
-            args: {
-                [x: string]: any;
-            };
-            id?: string | undefined;
-            type?: "tool_call" | undefined;
-        }[] | undefined;
-        invalid_tool_calls?: {
-            name?: string | undefined;
-            args?: string | undefined;
-            id?: string | undefined;
-            error?: string | undefined;
-            type?: "invalid_tool_call" | undefined;
-        }[] | undefined;
-        usage_metadata?: {
-            input_tokens: number;
-            output_tokens: number;
-            total_tokens: number;
-            input_token_details?: {
-                audio?: number | undefined;
-                cache_read?: number | undefined;
-                cache_creation?: number | undefined;
-            } | undefined;
-            output_token_details?: {
-                audio?: number | undefined;
-                reasoning?: number | undefined;
-            } | undefined;
-        } | undefined;
-    } & {
-        name?: string;
-        node_name?: string;
-        tool_input?: string;
-        additional_kwargs?: {
-            create_time: string;
-            update_time: string;
-            done?: boolean;
-            tool_calls?: {
-                function: {
-                    arguments: string;
-                };
-            }[];
-        };
-        usage_metadata?: {
-            total_tokens: number;
-            input_tokens: number;
-            output_tokens: number;
-        };
-        tool_call_id?: string;
-        sub_messages?: RenderMessage[];
-        spend_time?: number;
-        unique_id?: string;
-        done?: boolean;
-    }) | ({
-        additional_kwargs?: {
-            [x: string]: unknown;
-        } | undefined;
-        content: string | ({
-            type: "text";
-            text: string;
-        } | {
-            type: "image_url";
-            image_url: string | {
-                url: string;
-                detail?: ("auto" | "low" | "high") | undefined;
-            };
-        })[];
-        id?: string | undefined;
-        name?: string | undefined;
-        response_metadata?: Record<string, unknown> | undefined;
-    } & {
-        type: "tool";
-        status?: "error" | "success" | undefined;
-        tool_call_id: string;
-        artifact?: any;
-    } & {
-        name?: string;
-        node_name?: string;
-        tool_input?: string;
-        additional_kwargs?: {
-            create_time: string;
-            update_time: string;
-            done?: boolean;
-            tool_calls?: {
-                function: {
-                    arguments: string;
-                };
-            }[];
-        };
-        usage_metadata?: {
-            total_tokens: number;
-            input_tokens: number;
-            output_tokens: number;
-        };
-        tool_call_id?: string;
-        sub_messages?: RenderMessage[];
-        spend_time?: number;
-        unique_id?: string;
-        done?: boolean;
-    });
+    }): RenderMessage;
 }
 export {};

package/dist/react/ChatContext.d.ts

@@ -26,7 +26,9 @@ export declare const useChat: () => UnionStore<{
         showHistory: import("nanostores").PreinitializedWritableAtom<boolean> & object;
         historyList: import("nanostores").PreinitializedWritableAtom<import("@langchain/langgraph-sdk").Thread<{
             messages: import("@langchain/langgraph-sdk").Message[];
-        }>[]> & object;
+        }, unknown>[]> & object;
+        historyPagination: import("nanostores").PreinitializedWritableAtom<import("../ui-store/createChatStore.js").HistoryPagination> & object;
+        historyFilter: import("nanostores").PreinitializedWritableAtom<import("../ui-store/createChatStore.js").HistoryFilter> & object;
     };
     mutations: {
         setCurrentArtifactById: (id: string, tool_id: string) => void;
@@ -38,7 +40,7 @@ export declare const useChat: () => UnionStore<{
         createNewSession: () => Promise<void>;
         refreshSessionList: () => Promise<void>;
         refreshHistoryList: () => Promise<void>;
-        sendMessage: (message?: import("@langchain/langgraph-sdk").Message[], extraData?: import("../LangGraphClient.js").SendMessageOptions, withoutCheck?: boolean, isResume?: boolean) => Promise<void>;
+        sendMessage: (message?: import("@langchain/langgraph-sdk").Message[], options?: import("../LangGraphClient.js").SendMessageOptions, withoutCheck?: boolean, isResume?: 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>;
@@ -55,13 +57,17 @@ export declare const useChat: () => UnionStore<{
         addToHistory: (thread: import("@langchain/langgraph-sdk").Thread<{
             messages: import("@langchain/langgraph-sdk").Message[];
         }>) => void;
-        createNewChat: () => Promise<void>;
+        createNewChat(metadata?: Record<string, any>): Promise<void>;
         toHistoryChat: (thread: import("@langchain/langgraph-sdk").Thread<{
             messages: import("@langchain/langgraph-sdk").Message[];
         }>) => Promise<void>;
         deleteHistoryChat(thread: import("@langchain/langgraph-sdk").Thread<{
             messages: import("@langchain/langgraph-sdk").Message[];
         }>): Promise<void>;
+        setHistoryPage(page: number): void;
+        setHistoryPageSize(pageSize: number): void;
+        setHistoryFilter(filter: Partial<import("../ui-store/createChatStore.js").HistoryFilter>): void;
+        resetHistoryFilter(): void;
     };
 }>;
 interface ChatProviderProps {

package/dist/solid/ChatContext.d.ts

@@ -26,7 +26,9 @@ export declare const useChat: () => UnionStoreSolid<{
         showHistory: PreinitializedWritableAtom<boolean> & object;
         historyList: PreinitializedWritableAtom<import("@langchain/langgraph-sdk").Thread<{
             messages: import("@langchain/langgraph-sdk").Message[];
-        }>[]> & object;
+        }, unknown>[]> & object;
+        historyPagination: PreinitializedWritableAtom<import("../ui-store/createChatStore.js").HistoryPagination> & object;
+        historyFilter: PreinitializedWritableAtom<import("../ui-store/createChatStore.js").HistoryFilter> & object;
     };
     mutations: {
         setCurrentArtifactById: (id: string, tool_id: string) => void;
@@ -38,7 +40,7 @@ export declare const useChat: () => UnionStoreSolid<{
         createNewSession: () => Promise<void>;
         refreshSessionList: () => Promise<void>;
         refreshHistoryList: () => Promise<void>;
-        sendMessage: (message?: import("@langchain/langgraph-sdk").Message[], extraData?: import("../LangGraphClient.js").SendMessageOptions, withoutCheck?: boolean, isResume?: boolean) => Promise<void>;
+        sendMessage: (message?: import("@langchain/langgraph-sdk").Message[], options?: import("../LangGraphClient.js").SendMessageOptions, withoutCheck?: boolean, isResume?: 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>;
@@ -55,13 +57,17 @@ export declare const useChat: () => UnionStoreSolid<{
         addToHistory: (thread: import("@langchain/langgraph-sdk").Thread<{
             messages: import("@langchain/langgraph-sdk").Message[];
         }>) => void;
-        createNewChat: () => Promise<void>;
+        createNewChat(metadata?: Record<string, any>): Promise<void>;
         toHistoryChat: (thread: import("@langchain/langgraph-sdk").Thread<{
             messages: import("@langchain/langgraph-sdk").Message[];
         }>) => Promise<void>;
         deleteHistoryChat(thread: import("@langchain/langgraph-sdk").Thread<{
             messages: import("@langchain/langgraph-sdk").Message[];
         }>): Promise<void>;
+        setHistoryPage(page: number): void;
+        setHistoryPageSize(pageSize: number): void;
+        setHistoryFilter(filter: Partial<import("../ui-store/createChatStore.js").HistoryFilter>): void;
+        resetHistoryFilter(): void;
     };
 }>;
 interface ChatProviderProps {

package/dist/ui-store/createChatStore.d.ts

@@ -17,6 +17,17 @@ interface ChatStoreContext {
     /** 初始化时是否自动激活最近的历史会话（默认 false，创建新会话） */
     autoRestoreLastSession?: boolean;
 }
+export interface HistoryPagination {
+    page: number;
+    pageSize: number;
+    total: number;
+}
+export interface HistoryFilter {
+    metadata: Record<string, any> | null;
+    status: "idle" | "busy" | "interrupted" | "error" | null;
+    sortBy: "thread_id" | "status" | "created_at" | "updated_at";
+    sortOrder: "asc" | "desc";
+}
 export declare const createChatStore: (initClientName: string, config: Partial<LangGraphClientConfig>, context?: ChatStoreContext) => {
     data: {
         artifacts: import("nanostores").PreinitializedWritableAtom<import("../artifacts/index.js").ComposedArtifact[]> & object;
@@ -42,7 +53,9 @@ export declare const createChatStore: (initClientName: string, config: Partial<L
         showHistory: import("nanostores").PreinitializedWritableAtom<boolean> & object;
         historyList: import("nanostores").PreinitializedWritableAtom<Thread<{
             messages: Message[];
-        }>[]> & object;
+        }, unknown>[]> & object;
+        historyPagination: import("nanostores").PreinitializedWritableAtom<HistoryPagination> & object;
+        historyFilter: import("nanostores").PreinitializedWritableAtom<HistoryFilter> & object;
     };
     mutations: {
         setCurrentArtifactById: (id: string, tool_id: string) => void;
@@ -54,7 +67,7 @@ export declare const createChatStore: (initClientName: string, config: Partial<L
         createNewSession: () => Promise<void>;
         refreshSessionList: () => Promise<void>;
         refreshHistoryList: () => Promise<void>;
-        sendMessage: (message?: Message[], extraData?: SendMessageOptions, withoutCheck?: boolean, isResume?: boolean) => Promise<void>;
+        sendMessage: (message?: Message[], options?: SendMessageOptions, withoutCheck?: boolean, isResume?: boolean) => Promise<void>;
         stopGeneration: () => void;
         setUserInput: (input: string) => void;
         revertChatTo(messageId: string, resend?: boolean, sendOptions?: SendMessageOptions & RevertChatToOptions): Promise<void>;
@@ -71,13 +84,17 @@ export declare const createChatStore: (initClientName: string, config: Partial<L
         addToHistory: (thread: Thread<{
             messages: Message[];
         }>) => void;
-        createNewChat: () => Promise<void>;
+        createNewChat(metadata?: Record<string, any>): Promise<void>;
         toHistoryChat: (thread: Thread<{
             messages: Message[];
         }>) => Promise<void>;
         deleteHistoryChat(thread: Thread<{
             messages: Message[];
         }>): Promise<void>;
+        setHistoryPage(page: number): void;
+        setHistoryPageSize(pageSize: number): void;
+        setHistoryFilter(filter: Partial<HistoryFilter>): void;
+        resetHistoryFilter(): void;
     };
 };
 export {};

package/dist/ui-store/createChatStore.js

@@ -70,6 +70,19 @@ export const createChatStore = (initClientName, config, context = {}) => {
     const showHistory = atom(context.showHistory ?? false);
     const showGraph = atom(context.showGraph ?? false);
     const graphVisualize = atom(null);
+    // 分页状态
+    const historyPagination = atom({
+        page: 1,
+        pageSize: 10,
+        total: 0,
+    });
+    // 历史记录筛选状态
+    const historyFilter = atom({
+        metadata: null,
+        status: null,
+        sortBy: "updated_at",
+        sortOrder: "desc",
+    });
     // ============ 内部状态 ============
     let cleanupCurrentClient = null;
     // ============ 计算属性 ============
@@ -113,7 +126,6 @@ export const createChatStore = (initClientName, config, context = {}) => {
         });
         await historyManager.init(currentAgent.get(), { fallbackToAvailableAssistants: context.fallbackToAvailableAssistants });
         history.set(historyManager);
-        // 同步远程会话列表
         // 根据配置决定初始化行为
         if (context.autoRestoreLastSession) {
             await refreshSessionList();
@@ -137,9 +149,36 @@ export const createChatStore = (initClientName, config, context = {}) => {
         if (!historyManager)
             return;
         try {
-            const syncedSessions = await historyManager.syncFromRemote({ limit: 10 });
-            sessions.set(syncedSessions);
-            historyList.set(syncedSessions.filter((s) => s.thread).map((s) => s.thread));
+            const pagination = historyPagination.get();
+            const filter = historyFilter.get();
+            // 计算偏移量
+            const offset = (pagination.page - 1) * pagination.pageSize;
+            // 使用 listRemoteSessions 支持筛选
+            const threads = await historyManager.listRemoteSessions({
+                limit: pagination.pageSize,
+                offset,
+                metadata: filter.metadata || undefined,
+                status: filter.status || undefined,
+                sortBy: filter.sortBy,
+                sortOrder: filter.sortOrder,
+                withoutDetails: true,
+            });
+            // 注意：后端可能不返回总数，这里需要根据返回的记录数判断是否有下一页
+            // 如果返回的记录数小于 pageSize，说明没有更多数据了
+            const hasMore = threads.length === pagination.pageSize;
+            const estimatedTotal = (pagination.page - 1) * pagination.pageSize + threads.length;
+            sessions.set(threads.map((thread) => ({
+                sessionId: thread.thread_id,
+                thread,
+                agentName: currentAgent.get(),
+                metadata: thread.metadata,
+            })));
+            historyList.set(threads);
+            // 更新分页状态（注意：这里只是估计值，实际总数可能需要从后端获取）
+            historyPagination.set({
+                ...pagination,
+                total: hasMore ? pagination.page * pagination.pageSize + 1 : estimatedTotal,
+            });
         }
         catch (error) {
             console.error("Failed to sync sessions:", error);
@@ -286,7 +325,7 @@ export const createChatStore = (initClientName, config, context = {}) => {
         }
     }
     // ============ 消息和交互逻辑 ============
-    async function sendMessage(message, extraData, withoutCheck = false, isResume = false) {
+    async function sendMessage(message, options, withoutCheck = false, isResume = false) {
         const c = client.get();
         if ((!withoutCheck && !userInput.get().trim() && !message?.length) || !c)
             return;
@@ -296,7 +335,7 @@ export const createChatStore = (initClientName, config, context = {}) => {
         inChatError.set(null);
         try {
             loading.set(true);
-            await c.sendMessage(message || userInput.get(), extraData);
+            await c.sendMessage(message || userInput.get(), options);
         }
         catch (e) {
             const isThreadRunning = e.message.includes("422");
@@ -364,6 +403,9 @@ export const createChatStore = (initClientName, config, context = {}) => {
             // 历史记录
             showHistory,
             historyList,
+            // 分页和筛选
+            historyPagination,
+            historyFilter,
             ...artifactHook.data,
         },
         mutations: {
@@ -420,7 +462,20 @@ export const createChatStore = (initClientName, config, context = {}) => {
             },
             // 历史记录（兼容旧 API）
             addToHistory,
-            createNewChat: createNewSession,
+            async createNewChat(metadata) {
+                const historyManager = history.get();
+                if (!historyManager)
+                    return;
+                try {
+                    const session = await historyManager.createSession({ metadata });
+                    await refreshSessionList();
+                    await activateSession(session.sessionId);
+                }
+                catch (error) {
+                    console.error("Failed to create new chat:", error);
+                    inChatError.set(error.message);
+                }
+            },
             toHistoryChat: (thread) => activateSession(thread.thread_id, true),
             async deleteHistoryChat(thread) {
                 const historyManager = history.get();
@@ -429,6 +484,46 @@ export const createChatStore = (initClientName, config, context = {}) => {
                     await refreshSessionList();
                 }
             },
+            // 分页和筛选操作
+            setHistoryPage(page) {
+                historyPagination.set({
+                    ...historyPagination.get(),
+                    page,
+                });
+                refreshSessionList();
+            },
+            setHistoryPageSize(pageSize) {
+                historyPagination.set({
+                    ...historyPagination.get(),
+                    pageSize,
+                    page: 1, // 重置到第一页
+                });
+                refreshSessionList();
+            },
+            setHistoryFilter(filter) {
+                historyFilter.set({
+                    ...historyFilter.get(),
+                    ...filter,
+                });
+                historyPagination.set({
+                    ...historyPagination.get(),
+                    page: 1, // 筛选变更时重置到第一页
+                });
+                refreshSessionList();
+            },
+            resetHistoryFilter() {
+                historyFilter.set({
+                    metadata: null,
+                    status: null,
+                    sortBy: "updated_at",
+                    sortOrder: "desc",
+                });
+                historyPagination.set({
+                    ...historyPagination.get(),
+                    page: 1,
+                });
+                refreshSessionList();
+            },
             ...artifactHook.mutation,
         },
     };

package/dist/vue/ChatContext.d.ts

@@ -70,7 +70,9 @@ export declare const useChatProvider: (props: ChatProviderProps) => {
             showHistory: PreinitializedWritableAtom<boolean> & object;
             historyList: PreinitializedWritableAtom<import("@langchain/langgraph-sdk").Thread<{
                 messages: import("@langchain/langgraph-sdk").Message[];
-            }>[]> & object;
+            }, unknown>[]> & object;
+            historyPagination: PreinitializedWritableAtom<import("../ui-store/createChatStore.js").HistoryPagination> & object;
+            historyFilter: PreinitializedWritableAtom<import("../ui-store/createChatStore.js").HistoryFilter> & object;
         };
         mutations: {
             setCurrentArtifactById: (id: string, tool_id: string) => void;
@@ -82,7 +84,7 @@ export declare const useChatProvider: (props: ChatProviderProps) => {
             createNewSession: () => Promise<void>;
             refreshSessionList: () => Promise<void>;
             refreshHistoryList: () => Promise<void>;
-            sendMessage: (message?: import("@langchain/langgraph-sdk").Message[], extraData?: import("../LangGraphClient.js").SendMessageOptions, withoutCheck?: boolean, isResume?: boolean) => Promise<void>;
+            sendMessage: (message?: import("@langchain/langgraph-sdk").Message[], options?: import("../LangGraphClient.js").SendMessageOptions, withoutCheck?: boolean, isResume?: 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>;
@@ -99,13 +101,17 @@ export declare const useChatProvider: (props: ChatProviderProps) => {
             addToHistory: (thread: import("@langchain/langgraph-sdk").Thread<{
                 messages: import("@langchain/langgraph-sdk").Message[];
             }>) => void;
-            createNewChat: () => Promise<void>;
+            createNewChat(metadata?: Record<string, any>): Promise<void>;
             toHistoryChat: (thread: import("@langchain/langgraph-sdk").Thread<{
                 messages: import("@langchain/langgraph-sdk").Message[];
             }>) => Promise<void>;
             deleteHistoryChat(thread: import("@langchain/langgraph-sdk").Thread<{
                 messages: import("@langchain/langgraph-sdk").Message[];
             }>): Promise<void>;
+            setHistoryPage(page: number): void;
+            setHistoryPageSize(pageSize: number): void;
+            setHistoryFilter(filter: Partial<import("../ui-store/createChatStore.js").HistoryFilter>): void;
+            resetHistoryFilter(): void;
         };
     }>;
 };

package/package.json

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

package/src/History.ts

@@ -10,6 +10,8 @@ export interface SessionInfo {
     thread?: Thread<any>;
     /** Agent 名称 */
     agentName: string;
+    /** 会话元数据 */
+    metadata?: Record<string, any>;
 }
 
 export interface CreateSessionOptions {
@@ -21,6 +23,8 @@ export interface CreateSessionOptions {
     restore?: boolean;
     /** Graph ID */
     graphId?: string;
+    /** 会话元数据 */
+    metadata?: Record<string, any>;
 }
 
 /**
@@ -61,6 +65,7 @@ export class History {
         const sessionInfo: SessionInfo = {
             sessionId,
             agentName,
+            metadata: options.metadata,
         };
 
         // 如果是从已有 Thread 恢复，则立即获取 Thread
@@ -89,8 +94,15 @@ export class History {
             const client = new LangGraphClient(this.clientConfig);
             await client.initAssistant(session.agentName);
 
-            // 只有在有 thread 的情况下才重置（恢复已有会话）
-            // 新会话的 thread 会在发送第一条消息时自动创建
+            // 如果有 metadata，立即创建 Thread 并带上 metadata
+            if (session.metadata && !session.thread) {
+                await client.createThread({ 
+                    graphId: client.getCurrentAssistant()?.graph_id,
+                    metadata: session.metadata,
+                });
+            }
+
+            // 如果已有 thread 或者必须重置，则从历史恢复
             if (session.thread || mustResetStream) {
                 await client.resetThread(session.agentName, sessionId);
             }
@@ -230,10 +242,16 @@ export class History {
      */
     async listRemoteSessions(
         options: {
-            sortOrder?: "asc" | "desc";
-            sortBy?: "created_at" | "updated_at";
-            offset?: number;
+            ids?: string[];
+            metadata?: Record<string, any>;
+            status?: "idle" | "busy" | "interrupted" | "error";
+            values?: any;
             limit?: number;
+            offset?: number;
+            sortBy?: "thread_id" | "status" | "created_at" | "updated_at";
+            sortOrder?: "asc" | "desc";
+            select?: Array<"thread_id" | "created_at" | "updated_at" | "metadata" | "config" | "context" | "status" | "values" | "interrupts">;
+            withoutDetails?: boolean;
         } = {}
     ) {
         return this.virtualClient.listThreads(options);

package/src/LangGraphClient.ts

@@ -46,6 +46,7 @@ export type SendMessageOptions = {
     _debug?: { streamResponse?: any };
     command?: Command;
     joinRunId?: string;
+    metadata?: Record<string, any>;
 };
 
 export interface LangGraphClientConfig {
@@ -188,9 +189,10 @@ export class LangGraphClient<TStateType = unknown> extends EventEmitter<LangGrap
      * @zh 创建一个新的 Thread。
      * @en Creates a new Thread.
      */
-    async createThread({ threadId, graphId }: { threadId?: string; graphId?: string } = {}) {
+    async createThread({ threadId, graphId, metadata }: { threadId?: string; graphId?: string; metadata?: Record<string, any> } = {}) {
         try {
             this.currentThread = await this.threads.create({
+                metadata,
                 threadId,
                 graphId,
             });
@@ -212,20 +214,39 @@ export class LangGraphClient<TStateType = unknown> extends EventEmitter<LangGrap
      */
     async listThreads(
         options: {
-            sortOrder?: "asc" | "desc";
-            sortBy?: "created_at" | "updated_at";
-            offset?: number;
+            ids?: string[];
+            metadata?: Record<string, any>;
+            status?: "idle" | "busy" | "interrupted" | "error";
+            values?: any;
             limit?: number;
+            offset?: number;
+            sortBy?: "thread_id" | "status" | "created_at" | "updated_at";
+            sortOrder?: "asc" | "desc";
+            select?: Array<"thread_id" | "created_at" | "updated_at" | "metadata" | "config" | "context" | "status" | "values" | "interrupts">;
+            withoutDetails?: boolean;
         } = {}
     ) {
-        return this.threads.search({
-            sortOrder: options.sortOrder || "desc",
-            sortBy: options.sortBy || "updated_at",
-            offset: options.offset || 0,
-            limit: options.limit || 10,
-            /** @ts-ignore: 用于删除不需要的字段 */
-            without_details: true,
-        });
+        const searchOptions: any = {};
+
+        if (options.ids) searchOptions.ids = options.ids;
+        if (options.metadata) searchOptions.metadata = options.metadata;
+        if (options.status) searchOptions.status = options.status;
+        if (options.values) searchOptions.values = options.values;
+        if (options.limit !== undefined) searchOptions.limit = options.limit;
+        if (options.offset !== undefined) searchOptions.offset = options.offset;
+        if (options.sortBy) searchOptions.sortBy = options.sortBy;
+        if (options.sortOrder) searchOptions.sortOrder = options.sortOrder;
+        if (options.select) searchOptions.select = options.select;
+        if (options.withoutDetails !== undefined) searchOptions.without_details = options.withoutDetails;
+
+        // 设置默认值
+        if (!options.sortBy) searchOptions.sortBy = "updated_at";
+        if (!options.sortOrder) searchOptions.sortOrder = "desc";
+        if (!options.limit) searchOptions.limit = 10;
+        if (!options.offset) searchOptions.offset = 0;
+        if (!options.withoutDetails) searchOptions.without_details = true;
+
+        return this.threads.search(searchOptions);
     }
     async deleteThread(threadId: string) {
         return this.threads.delete(threadId);
@@ -344,12 +365,15 @@ export class LangGraphClient<TStateType = unknown> extends EventEmitter<LangGrap
      * @zh 发送消息到 LangGraph 后端。
      * @en Sends a message to the LangGraph backend.
      */
-    async sendMessage(input: string | Message[], { joinRunId, extraParams, _debug, command }: SendMessageOptions = {}) {
+    async sendMessage(input: string | Message[], { joinRunId, extraParams, _debug, command, metadata }: SendMessageOptions = {}) {
         if (!this.currentAssistant) {
             throw new Error("Thread or Assistant not initialized");
         }
         if (!this.currentThread) {
-            await this.createThread({ graphId: this.currentAssistant!.graph_id! });
+            await this.createThread({ 
+                graphId: this.currentAssistant!.graph_id!,
+                metadata,
+            });
             this.emit("thread", {
                 event: "thread/create",
                 data: {

package/src/TestKit.ts

@@ -292,7 +292,7 @@ export class TestLangGraphChat {
      * const lastHuman = testChat.findLast("human");
      * ```
      */
-    findLast(type: "human" | "ai" | "tool", options: { before?: (item: RenderMessage) => boolean } = {}) {
+    findLast(type: "human" | "ai" | "tool", options: { before?: (item: RenderMessage) => boolean } = {}): RenderMessage {
         const messages = this.getMessages();
 
         for (let i = messages.length - 1; i >= 0; i--) {

package/src/ui-store/createChatStore.ts

@@ -61,6 +61,21 @@ interface ChatStoreContext {
     autoRestoreLastSession?: boolean;
 }
 
+// 分页状态类型
+export interface HistoryPagination {
+    page: number;
+    pageSize: number;
+    total: number;
+}
+
+// 历史记录筛选类型
+export interface HistoryFilter {
+    metadata: Record<string, any> | null;
+    status: "idle" | "busy" | "interrupted" | "error" | null;
+    sortBy: "thread_id" | "status" | "created_at" | "updated_at";
+    sortOrder: "asc" | "desc";
+}
+
 // ============ Store 创建函数 ============
 
 export const createChatStore = (initClientName: string, config: Partial<LangGraphClientConfig>, context: ChatStoreContext = {}) => {
@@ -91,6 +106,21 @@ export const createChatStore = (initClientName: string, config: Partial<LangGrap
     const showGraph = atom<boolean>(context.showGraph ?? false);
     const graphVisualize = atom<AssistantGraph | null>(null);
 
+    // 分页状态
+    const historyPagination = atom<HistoryPagination>({
+        page: 1,
+        pageSize: 10,
+        total: 0,
+    });
+
+    // 历史记录筛选状态
+    const historyFilter = atom<HistoryFilter>({
+        metadata: null,
+        status: null,
+        sortBy: "updated_at",
+        sortOrder: "desc",
+    });
+
     // ============ 内部状态 ============
 
     let cleanupCurrentClient: (() => void) | null = null;
@@ -145,8 +175,6 @@ export const createChatStore = (initClientName: string, config: Partial<LangGrap
         await historyManager.init(currentAgent.get(), { fallbackToAvailableAssistants: context.fallbackToAvailableAssistants });
         history.set(historyManager);
 
-        // 同步远程会话列表
-
         // 根据配置决定初始化行为
         if (context.autoRestoreLastSession) {
             await refreshSessionList();
@@ -170,9 +198,47 @@ export const createChatStore = (initClientName: string, config: Partial<LangGrap
         if (!historyManager) return;
 
         try {
-            const syncedSessions = await historyManager.syncFromRemote({ limit: 10 });
-            sessions.set(syncedSessions);
-            historyList.set(syncedSessions.filter((s) => s.thread).map((s) => s.thread!));
+            const pagination = historyPagination.get();
+            const filter = historyFilter.get();
+
+            // 计算偏移量
+            const offset = (pagination.page - 1) * pagination.pageSize;
+
+            // 使用 listRemoteSessions 支持筛选
+            const threads = await historyManager.listRemoteSessions({
+                limit: pagination.pageSize,
+                offset,
+                metadata: filter.metadata || undefined,
+                status: filter.status || undefined,
+                sortBy: filter.sortBy,
+                sortOrder: filter.sortOrder,
+                withoutDetails: true,
+            });
+
+            // 注意：后端可能不返回总数，这里需要根据返回的记录数判断是否有下一页
+            // 如果返回的记录数小于 pageSize，说明没有更多数据了
+            const hasMore = threads.length === pagination.pageSize;
+            const estimatedTotal = (pagination.page - 1) * pagination.pageSize + threads.length;
+
+            sessions.set(
+                threads.map(
+                    (thread) =>
+                        ({
+                            sessionId: thread.thread_id,
+                            thread,
+                            agentName: currentAgent.get(),
+                            metadata: thread.metadata as Record<string, any> | undefined,
+                        }) as SessionInfo
+                )
+            );
+
+            historyList.set(threads as Thread<{ messages: Message[] }>[]);
+
+            // 更新分页状态（注意：这里只是估计值，实际总数可能需要从后端获取）
+            historyPagination.set({
+                ...pagination,
+                total: hasMore ? pagination.page * pagination.pageSize + 1 : estimatedTotal,
+            });
         } catch (error) {
             console.error("Failed to sync sessions:", error);
         }
@@ -340,7 +406,7 @@ export const createChatStore = (initClientName: string, config: Partial<LangGrap
 
     // ============ 消息和交互逻辑 ============
 
-    async function sendMessage(message?: Message[], extraData?: SendMessageOptions, withoutCheck = false, isResume = false) {
+    async function sendMessage(message?: Message[], options?: SendMessageOptions, withoutCheck = false, isResume = false) {
         const c = client.get();
         if ((!withoutCheck && !userInput.get().trim() && !message?.length) || !c) return;
 
@@ -350,7 +416,7 @@ export const createChatStore = (initClientName: string, config: Partial<LangGrap
         inChatError.set(null);
         try {
             loading.set(true);
-            await c.sendMessage(message || userInput.get(), extraData);
+            await c.sendMessage(message || userInput.get(), options);
         } catch (e) {
             const isThreadRunning = (e as Error).message.includes("422");
             if (isThreadRunning) {
@@ -427,6 +493,10 @@ export const createChatStore = (initClientName: string, config: Partial<LangGrap
             showHistory,
             historyList,
 
+            // 分页和筛选
+            historyPagination,
+            historyFilter,
+
             ...artifactHook.data,
         },
         mutations: {
@@ -490,7 +560,19 @@ export const createChatStore = (initClientName: string, config: Partial<LangGrap
             },
             // 历史记录（兼容旧 API）
             addToHistory,
-            createNewChat: createNewSession,
+            async createNewChat(metadata?: Record<string, any>) {
+                const historyManager = history.get();
+                if (!historyManager) return;
+
+                try {
+                    const session = await historyManager.createSession({ metadata });
+                    await refreshSessionList();
+                    await activateSession(session.sessionId);
+                } catch (error) {
+                    console.error("Failed to create new chat:", error);
+                    inChatError.set((error as Error).message);
+                }
+            },
             toHistoryChat: (thread: Thread<{ messages: Message[] }>) => activateSession(thread.thread_id, true),
             async deleteHistoryChat(thread: Thread<{ messages: Message[] }>) {
                 const historyManager = history.get();
@@ -500,6 +582,47 @@ export const createChatStore = (initClientName: string, config: Partial<LangGrap
                 }
             },
 
+            // 分页和筛选操作
+            setHistoryPage(page: number) {
+                historyPagination.set({
+                    ...historyPagination.get(),
+                    page,
+                });
+                refreshSessionList();
+            },
+            setHistoryPageSize(pageSize: number) {
+                historyPagination.set({
+                    ...historyPagination.get(),
+                    pageSize,
+                    page: 1, // 重置到第一页
+                });
+                refreshSessionList();
+            },
+            setHistoryFilter(filter: Partial<HistoryFilter>) {
+                historyFilter.set({
+                    ...historyFilter.get(),
+                    ...filter,
+                });
+                historyPagination.set({
+                    ...historyPagination.get(),
+                    page: 1, // 筛选变更时重置到第一页
+                });
+                refreshSessionList();
+            },
+            resetHistoryFilter() {
+                historyFilter.set({
+                    metadata: null,
+                    status: null,
+                    sortBy: "updated_at",
+                    sortOrder: "desc",
+                });
+                historyPagination.set({
+                    ...historyPagination.get(),
+                    page: 1,
+                });
+                refreshSessionList();
+            },
+
             ...artifactHook.mutation,
         },
     };