@langgraph-js/sdk 3.7.0 → 3.8.0

package/README.md

@@ -57,6 +57,35 @@ pnpm add @langgraph-js/sdk
 
 - ✅ Read History from LangGraph
 
+## Legacy Mode
+
+Legacy mode is designed to be compatible with environments that don't support `AsyncGeneratorFunction` (such as WeChat Mini Programs). In these environments, standard async iterators may not work properly.
+
+### Legacy Mode Example
+
+```typescript
+import { TestLangGraphChat, createChatStore, createLowerJSClient } from "@langgraph-js/sdk";
+
+const client = await createLowerJSClient({
+    apiUrl: "http://localhost:8123",
+    defaultHeaders: {
+        Authorization: "Bearer 123",
+    },
+});
+
+createChatStore(
+    "graph",
+    {
+        defaultHeaders: {
+            Authorization: "Bearer 123",
+        },
+        client,
+        legacyMode: true,
+    },
+    {}
+);
+```
+
 ## Advanced Usage
 
 ### Creating a Chat Store

package/dist/History.d.ts

@@ -0,0 +1,115 @@
+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 declare class History {
+    /** 存储所有会话的 Map */
+    private sessions;
+    /** 当前活跃的会话 ID */
+    private activeSessionId;
+    /** 客户端配置，用于创建新的 LangGraphClient 实例 */
+    private clientConfig;
+    /** 虚拟 Client，用于查询操作（不绑定特定 Thread） */
+    private virtualClient;
+    constructor(clientConfig: LangGraphClientConfig);
+    /**
+     * @zh 创建新会话（延迟创建 Thread，直到发送第一条消息）
+     * @en Creates a new session (lazy Thread creation until first message)
+     */
+    createSession(options?: CreateSessionOptions): Promise<SessionInfo>;
+    /**
+     * @zh 激活指定会话（懒加载创建 Client）
+     * @en Activates the specified session (lazy load client)
+     */
+    activateSession(sessionId: string): Promise<SessionInfo>;
+    /**
+     * @zh 获取当前活跃的会话
+     * @en Gets the current active session
+     */
+    getActiveSession(): SessionInfo | null;
+    /**
+     * @zh 获取指定会话
+     * @en Gets the specified session
+     */
+    getSession(sessionId: string): SessionInfo | null;
+    /**
+     * @zh 获取所有会话
+     * @en Gets all sessions
+     */
+    getAllSessions(): SessionInfo[];
+    /**
+     * @zh 删除指定会话
+     * @en Deletes the specified session
+     */
+    deleteSession(sessionId: string): Promise<boolean>;
+    /**
+     * @zh 清空所有会话
+     * @en Clears all sessions
+     */
+    clearAllSessions(): Promise<void>;
+    /**
+     * @zh 获取会话数量
+     * @en Gets the number of sessions
+     */
+    getSessionCount(): number;
+    /**
+     * @zh 生成会话 ID (UUID v4 格式)
+     * @en Generates a session ID (UUID v4 format)
+     */
+    private generateSessionId;
+    /**
+     * @zh 从已有的 Thread 添加会话（仅添加元数据，不创建 Client）
+     * @en Adds a session from an existing Thread (metadata only, no client created)
+     */
+    addSessionFromThread(threadId: string, agentName?: string): Promise<SessionInfo>;
+    /**
+     * @zh 获取当前活跃的客户端
+     * @en Gets the current active client
+     */
+    getActiveClient(): LangGraphClient | null;
+    /**
+     * @zh 从远程列出所有会话
+     * @en Lists all sessions from remote
+     */
+    listRemoteSessions(options?: {
+        sortOrder?: "asc" | "desc";
+        sortBy?: "created_at" | "updated_at";
+        offset?: number;
+        limit?: number;
+    }): Promise<Thread<unknown>[]>;
+    /**
+     * @zh 从远程同步会话到本地（仅同步元数据，不创建 Client）
+     * @en Syncs sessions from remote to local (metadata only, no client created)
+     */
+    syncFromRemote(options?: {
+        limit?: number;
+        agentName?: string;
+    }): Promise<SessionInfo[]>;
+    /**
+     * @zh 初始化 History（必须先调用）
+     * @en Initializes History (must be called first)
+     */
+    init(agentName?: string): Promise<import("@langchain/langgraph-sdk").Assistant | undefined>;
+}

package/dist/History.js

@@ -0,0 +1,226 @@
+import { LangGraphClient } from "./LangGraphClient.js";
+/**
+ * @zh History 类用于管理多个 LangGraphClient 实例，支持多会话场景
+ * @en History class manages multiple LangGraphClient instances for multi-session scenarios
+ */
+export class History {
+    /** 存储所有会话的 Map */
+    sessions = new Map();
+    /** 当前活跃的会话 ID */
+    activeSessionId = null;
+    /** 客户端配置，用于创建新的 LangGraphClient 实例 */
+    clientConfig;
+    /** 虚拟 Client，用于查询操作（不绑定特定 Thread） */
+    virtualClient;
+    constructor(clientConfig) {
+        this.clientConfig = clientConfig;
+        this.virtualClient = new LangGraphClient(clientConfig);
+    }
+    /**
+     * @zh 创建新会话（延迟创建 Thread，直到发送第一条消息）
+     * @en Creates a new session (lazy Thread creation until first message)
+     */
+    async createSession(options = {}) {
+        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 = {
+            sessionId,
+            agentName,
+        };
+        // 如果是从已有 Thread 恢复，则立即获取 Thread
+        if (options.restore) {
+            sessionInfo.thread = (await this.virtualClient.threads.get(sessionId));
+        }
+        // 否则 thread 为 undefined，等待第一条消息时由 Client 自动创建
+        this.sessions.set(sessionId, sessionInfo);
+        return sessionInfo;
+    }
+    /**
+     * @zh 激活指定会话（懒加载创建 Client）
+     * @en Activates the specified session (lazy load client)
+     */
+    async activateSession(sessionId) {
+        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() {
+        if (!this.activeSessionId) {
+            return null;
+        }
+        return this.sessions.get(this.activeSessionId) || null;
+    }
+    /**
+     * @zh 获取指定会话
+     * @en Gets the specified session
+     */
+    getSession(sessionId) {
+        return this.sessions.get(sessionId) || null;
+    }
+    /**
+     * @zh 获取所有会话
+     * @en Gets all sessions
+     */
+    getAllSessions() {
+        return Array.from(this.sessions.values());
+    }
+    /**
+     * @zh 删除指定会话
+     * @en Deletes the specified session
+     */
+    async deleteSession(sessionId) {
+        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() {
+        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() {
+        return this.sessions.size;
+    }
+    /**
+     * @zh 生成会话 ID (UUID v4 格式)
+     * @en Generates a session ID (UUID v4 format)
+     */
+    generateSessionId() {
+        // 优先使用 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, agentName) {
+        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() {
+        const session = this.getActiveSession();
+        return session?.client || null;
+    }
+    /**
+     * @zh 从远程列出所有会话
+     * @en Lists all sessions from remote
+     */
+    async listRemoteSessions(options = {}) {
+        return this.virtualClient.listThreads(options);
+    }
+    /**
+     * @zh 从远程同步会话到本地（仅同步元数据，不创建 Client）
+     * @en Syncs sessions from remote to local (metadata only, no client created)
+     */
+    async syncFromRemote(options = {}) {
+        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 = [];
+        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 = {
+                    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) {
+        return this.virtualClient.initAssistant(agentName);
+    }
+}

package/dist/LangGraphClient.d.ts

@@ -84,6 +84,8 @@ export interface LangGraphClientConfig {
     defaultHeaders?: Record<string, string | null | undefined>;
     /** 自定义客户端实现，如果不提供则使用官方 Client */
     client: ILangGraphClient<any>;
+    /** 是否使用 legacy 模式，默认 false */
+    legacyMode?: boolean;
 }
 export interface LangGraphEvents {
     /** 流开始事件 */
@@ -136,11 +138,17 @@ export declare class LangGraphClient<TStateType = unknown> extends EventEmitter<
     stopController: AbortController | null;
     /** Message 处理器 */
     private messageProcessor;
+    private legacyMode;
+    /** 当前流式状态 */
+    private _status;
     constructor(config: LangGraphClientConfig);
     /** 代理 assistants 属性到内部 client */
     get assistants(): {
         search(query?: {
-            graphId?: string;
+            graphId? /**
+             * The maximum number of concurrent calls that can be made.
+             * Defaults to `Infinity`, which means no limit.
+             */: string;
             metadata?: import("@langchain/langgraph-sdk").Metadata;
             limit?: number;
             offset?: number;
@@ -173,6 +181,8 @@ export declare class LangGraphClient<TStateType = unknown> extends EventEmitter<
     };
     /** 代理 runs 属性到内部 client */
     get runs(): ILangGraphClient["runs"];
+    /** 获取当前流式状态 */
+    get status(): "error" | "idle" | "busy" | "interrupted";
     private listAssistants;
     /**
      * @zh 初始化 Assistant。
@@ -194,7 +204,12 @@ export declare class LangGraphClient<TStateType = unknown> extends EventEmitter<
      * @zh 列出所有的 Thread。
      * @en Lists all Threads.
      */
-    listThreads(): Promise<Thread<TStateType>[]>;
+    listThreads(options?: {
+        sortOrder?: "asc" | "desc";
+        sortBy?: "created_at" | "updated_at";
+        offset?: number;
+        limit?: number;
+    }): Promise<Thread<TStateType>[]>;
     deleteThread(threadId: string): Promise<void>;
     /**
      * @zh 从历史中恢复 Thread 数据。
@@ -248,6 +263,12 @@ export declare class LangGraphClient<TStateType = unknown> extends EventEmitter<
         id: string;
         name: string;
     };
+    /**
+     * @zh 处理流式响应的单个 chunk。
+     * @en Processes a single chunk from the stream response.
+     * @returns 是否需要跳过后续处理 (continue)
+     */
+    private processStreamChunk;
     private runFETool;
     private callFETool;
     extraParams: Record<string, any>;