@langgraph-js/sdk 3.7.0 → 3.8.0

package/src/LangGraphClient.ts

@@ -5,7 +5,7 @@ import { CallToolResult } from "./tool/createTool.js";
 import { type ILangGraphClient } from "@langgraph-js/pure-graph/dist/types.js";
 import { MessageProcessor } from "./MessageProcessor.js";
 import { revertChatTo, RevertChatToOptions } from "./time-travel/index.js";
-
+import camelcaseKeys from "camelcase-keys";
 export type RenderMessage = Message & {
     /** 对于 AIMessage 来说是节点名称，对于工具节点来说是工具名称 */
     name?: string;
@@ -85,6 +85,8 @@ export interface LangGraphClientConfig {
     defaultHeaders?: Record<string, string | null | undefined>;
     /** 自定义客户端实现，如果不提供则使用官方 Client */
     client: ILangGraphClient<any>;
+    /** 是否使用 legacy 模式，默认 false */
+    legacyMode?: boolean;
 }
 
 // 定义事件数据类型
@@ -118,10 +120,13 @@ export class LangGraphClient<TStateType = unknown> extends EventEmitter<LangGrap
     stopController: AbortController | null = null;
     /** Message 处理器 */
     private messageProcessor: MessageProcessor;
-
+    private legacyMode: boolean;
+    /** 当前流式状态 */
+    private _status: "idle" | "busy" | "interrupted" | "error" = "idle";
     constructor(config: LangGraphClientConfig) {
         super();
         this.client = config.client;
+        this.legacyMode = config.legacyMode ?? false;
         this.messageProcessor = new MessageProcessor();
     }
 
@@ -139,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,
@@ -208,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) {
@@ -345,12 +364,27 @@ export class LangGraphClient<TStateType = unknown> extends EventEmitter<LangGrap
                       content: input,
                   } as HumanMessage,
               ];
+
+        const streamRecord: any[] = [];
+        this._status = "busy";
+        this.emit("start", {
+            event: "start",
+        });
         const createStreamResponse = async () => {
             if (_debug?.streamResponse) {
                 return _debug.streamResponse;
             }
+            const onCallback = this.legacyMode
+                ? (chunk: any) => {
+                      streamRecord.push(chunk);
+                      this.processStreamChunk(chunk, command);
+                  }
+                : undefined;
             if (joinRunId) {
-                return this.runs.joinStream(this.currentThread!.thread_id, joinRunId);
+                return this.runs.joinStream(this.currentThread!.thread_id, joinRunId, {
+                    /** @ts-ignore */
+                    onCallback,
+                });
             }
 
             return this.runs.stream(this.currentThread!.thread_id, this.currentAssistant!.assistant_id, {
@@ -364,56 +398,22 @@ export class LangGraphClient<TStateType = unknown> extends EventEmitter<LangGrap
                 streamMode: ["messages", "values"],
                 streamSubgraphs: true,
                 command,
+                /** @ts-ignore 为兼容不支持 AsyncIterableFunction 的环境*/
+                onCallback,
             });
         };
         const streamResponse = await createStreamResponse();
-
-        const streamRecord: any[] = [];
-        this.emit("start", {
-            event: "start",
-        });
-
-        for await (const chunk of streamResponse) {
-            streamRecord.push(chunk);
-            if (chunk.event === "metadata") {
-                this.currentRun = chunk.data;
-            } else if (chunk.event === "error" || chunk.event === "Error" || chunk.event === "__stream_error__") {
-                this.emit("error", chunk);
-            } else if (chunk.event === "messages/metadata") {
-                Object.assign(this.messagesMetadata, chunk.data);
-                continue;
-            } else if (chunk.event === "messages/partial" || chunk.event === "messages/complete") {
-                for (const message of chunk.data) {
-                    this.messageProcessor.updateStreamingMessage(message);
-                }
-                this.emit("message", chunk);
-                continue;
-            } else if (chunk.event === "values") {
-                const data = chunk.data as {
-                    __interrupt__?: InterruptData;
-                    messages: Message[];
-                };
-
-                if (data.__interrupt__) {
-                    this.humanInTheLoop = data.__interrupt__;
-                } else if (data.messages) {
-                    const isResume = !!command?.resume;
-                    const isLongerThanLocal = data.messages.length >= this.messageProcessor.getGraphMessages().length;
-                    // resume 情况下，长度低于前端 message 的统统不接受
-                    if (!isResume || (isResume && isLongerThanLocal)) {
-                        this.messageProcessor.setGraphMessages(data.messages as RenderMessage[]);
-                        this.emit("value", chunk);
-                    }
-                    this.graphState = chunk.data;
-                }
-                continue;
-            } else if (chunk.event.startsWith("values|")) {
-                this.graphPosition = chunk.event.split("|")[1];
+        if (!this.legacyMode) {
+            // 正常的 JS 环境都可以执行，但是部分环境不支持 AsyncGeneratorFunction（比如 sb 的微信小程序）
+            for await (const chunk of streamResponse) {
+                streamRecord.push(chunk);
+                this.processStreamChunk(chunk, command);
             }
         }
         const data = await this.runFETool();
         if (data) streamRecord.push(...data);
         this.humanInTheLoop = null;
+        this._status = "idle";
         this.emit("done", {
             event: "done",
         });
@@ -436,6 +436,54 @@ export class LangGraphClient<TStateType = unknown> extends EventEmitter<LangGrap
         return position[position.length - 1];
     }
 
+    /**
+     * @zh 处理流式响应的单个 chunk。
+     * @en Processes a single chunk from the stream response.
+     * @returns 是否需要跳过后续处理 (continue)
+     */
+    private processStreamChunk(chunk: any, command?: Command): boolean {
+        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);
+            return true;
+        } else if (chunk.event === "messages/partial" || chunk.event === "messages/complete") {
+            for (const message of chunk.data) {
+                this.messageProcessor.updateStreamingMessage(message);
+            }
+            this.emit("message", chunk);
+            return true;
+        } else if (chunk.event === "values") {
+            const data = chunk.data as {
+                __interrupt__?: InterruptData;
+                messages: Message[];
+            };
+
+            if (data.__interrupt__) {
+                this._status = "interrupted";
+                this.humanInTheLoop = camelcaseKeys(data.__interrupt__, {
+                    deep: true,
+                });
+            } else if (data.messages) {
+                const isResume = !!command?.resume;
+                const isLongerThanLocal = data.messages.length >= this.messageProcessor.getGraphMessages().length;
+                // resume 情况下，长度低于前端 message 的统统不接受
+                if (!isResume || (isResume && isLongerThanLocal)) {
+                    this.messageProcessor.setGraphMessages(data.messages as RenderMessage[]);
+                    this.emit("value", chunk);
+                }
+                this.graphState = chunk.data;
+            }
+            return true;
+        } else if (chunk.event.startsWith("values|")) {
+            this.graphPosition = chunk.event.split("|")[1];
+        }
+        return false;
+    }
+
     private runFETool() {
         const data = this.messageProcessor.getStreamingMessages(); // 需要保证不被清理
         const lastMessage = data[data.length - 1];
@@ -453,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);
         }
@@ -517,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/client/LanggraphServer.ts

@@ -1,7 +1,6 @@
 import { LangGraphClientConfig } from "../LangGraphClient.js";
 import { type ILangGraphClient } from "@langgraph-js/pure-graph/dist/types.js";
-
+import { Client } from "@langchain/langgraph-sdk";
 export const createLangGraphServerClient = async (config: LangGraphClientConfig): Promise<ILangGraphClient> => {
-    const { Client } = await import("@langchain/langgraph-sdk");
     return new Client(config) as ILangGraphClient;
 };

package/src/client/LowJSServer.ts

@@ -0,0 +1,80 @@
+import { BytesLineDecoder, SSEDecoder } from "./utils/sse.js";
+import { LangGraphClientConfig } from "../LangGraphClient.js";
+import { ILangGraphClient } from "@langgraph-js/pure-graph/dist/types.js";
+
+const REGEX_RUN_METADATA = /(\/threads\/(?<thread_id>.+))?\/runs\/(?<run_id>.+)/;
+function getRunMetadataFromResponse(response: Response) {
+    const contentLocation = response.headers.get("Content-Location");
+    if (!contentLocation) return void 0;
+    const match = REGEX_RUN_METADATA.exec(contentLocation);
+    if (!match?.groups?.run_id) return void 0;
+    return {
+        run_id: match.groups.run_id,
+        thread_id: match.groups.thread_id || void 0,
+    };
+}
+import { Client } from "@langchain/langgraph-sdk";
+
+export const createLowerJSClient = (config: Omit<LangGraphClientConfig, "client">): ILangGraphClient => {
+    const client = new Client(config);
+    /** @ts-ignore */
+    client.runs.joinStream = async function (this: any, threadId: string | null, runId: string, options: any) {
+        const opts = typeof options === "object" && options != null && options instanceof AbortSignal ? { signal: options } : options;
+        let [url, init] = this.prepareFetchOptions(threadId != null ? `/threads/${threadId}/runs/${runId}/stream` : `/runs/${runId}/stream`, {
+            method: "GET",
+            timeoutMs: null,
+            signal: opts?.signal,
+            headers: opts?.lastEventId ? { "Last-Event-ID": opts.lastEventId } : void 0,
+            params: {
+                cancel_on_disconnect: opts?.cancelOnDisconnect ? "1" : "0",
+                stream_mode: opts?.streamMode,
+            },
+        });
+        if (this.onRequest != null) init = await this.onRequest(url, init);
+        const response = await this.asyncCaller.fetch(url, init);
+        const stream: ReadableStream = (response.body || new ReadableStream({ start: (ctrl) => ctrl.close() })).pipeThrough(BytesLineDecoder()).pipeThrough(SSEDecoder());
+        return stream.pipeTo(new WritableStream({ write: (chunk) => options.onCallback?.(chunk) }));
+    }.bind(client.runs);
+    /** @ts-ignore */
+    client.runs.stream = async function (this: any, threadId: string | null, assistantId: string, payload?: any) {
+        const json = {
+            input: payload?.input,
+            command: payload?.command,
+            config: payload?.config,
+            context: payload?.context,
+            metadata: payload?.metadata,
+            stream_mode: payload?.streamMode,
+            stream_subgraphs: payload?.streamSubgraphs,
+            stream_resumable: payload?.streamResumable,
+            feedback_keys: payload?.feedbackKeys,
+            assistant_id: assistantId,
+            interrupt_before: payload?.interruptBefore,
+            interrupt_after: payload?.interruptAfter,
+            checkpoint: payload?.checkpoint,
+            checkpoint_id: payload?.checkpointId,
+            webhook: payload?.webhook,
+            multitask_strategy: payload?.multitaskStrategy,
+            on_completion: payload?.onCompletion,
+            on_disconnect: payload?.onDisconnect,
+            after_seconds: payload?.afterSeconds,
+            if_not_exists: payload?.ifNotExists,
+            checkpoint_during: payload?.checkpointDuring,
+            durability: payload?.durability,
+        };
+        const endpoint = threadId == null ? `/runs/stream` : `/threads/${threadId}/runs/stream`;
+        let [url, init] = this.prepareFetchOptions(endpoint, {
+            method: "POST",
+            json,
+            timeoutMs: null,
+            signal: payload?.signal,
+        });
+        if (this.onRequest != null) init = await this.onRequest(url, init);
+        const response = await this.asyncCaller.fetch(url, init);
+        const runMetadata = getRunMetadataFromResponse(response);
+        if (runMetadata) payload?.onRunCreated?.(runMetadata);
+        const stream: ReadableStream = (response.body || new ReadableStream({ start: (ctrl) => ctrl.close() })).pipeThrough(BytesLineDecoder()).pipeThrough(SSEDecoder());
+
+        return stream.pipeTo(new WritableStream({ write: (chunk) => payload.onCallback?.(chunk) }));
+    }.bind(client.runs);
+    return client as ILangGraphClient;
+};

package/src/client/index.ts

@@ -0,0 +1,2 @@
+export * from "./LanggraphServer.js";
+export * from "./LowJSServer.js";

package/src/client/utils/sse.ts

@@ -0,0 +1,176 @@
+/** copied from https://github.com/langchain-ai/langgraphjs/tree/main/libs/sdk/src/utils */
+const CR = "\r".charCodeAt(0);
+const LF = "\n".charCodeAt(0);
+const NULL = "\0".charCodeAt(0);
+const COLON = ":".charCodeAt(0);
+const SPACE = " ".charCodeAt(0);
+
+const TRAILING_NEWLINE = [CR, LF];
+
+export function BytesLineDecoder() {
+    let buffer: Uint8Array[] = [];
+    let trailingCr = false;
+
+    return new TransformStream<Uint8Array, Uint8Array>({
+        start() {
+            buffer = [];
+            trailingCr = false;
+        },
+
+        transform(chunk, controller) {
+            // See https://docs.python.org/3/glossary.html#term-universal-newlines
+            let text = chunk;
+
+            // Handle trailing CR from previous chunk
+            if (trailingCr) {
+                text = joinArrays([[CR], text]);
+                trailingCr = false;
+            }
+
+            // Check for trailing CR in current chunk
+            if (text.length > 0 && text.at(-1) === CR) {
+                trailingCr = true;
+                text = text.subarray(0, -1);
+            }
+
+            if (!text.length) return;
+            const trailingNewline = TRAILING_NEWLINE.includes(text.at(-1)!);
+
+            const lastIdx = text.length - 1;
+            const { lines } = text.reduce<{ lines: Uint8Array[]; from: number }>(
+                (acc, cur, idx) => {
+                    if (acc.from > idx) return acc;
+
+                    if (cur === CR || cur === LF) {
+                        acc.lines.push(text.subarray(acc.from, idx));
+                        if (cur === CR && text[idx + 1] === LF) {
+                            acc.from = idx + 2;
+                        } else {
+                            acc.from = idx + 1;
+                        }
+                    }
+
+                    if (idx === lastIdx && acc.from <= lastIdx) {
+                        acc.lines.push(text.subarray(acc.from));
+                    }
+
+                    return acc;
+                },
+                { lines: [], from: 0 }
+            );
+
+            if (lines.length === 1 && !trailingNewline) {
+                buffer.push(lines[0]);
+                return;
+            }
+
+            if (buffer.length) {
+                // Include existing buffer in first line
+                buffer.push(lines[0]);
+                lines[0] = joinArrays(buffer);
+                buffer = [];
+            }
+
+            if (!trailingNewline) {
+                // If the last segment is not newline terminated,
+                // buffer it for the next chunk
+                if (lines.length) buffer = [lines.pop()!];
+            }
+
+            // Enqueue complete lines
+            for (const line of lines) {
+                controller.enqueue(line);
+            }
+        },
+
+        flush(controller) {
+            if (buffer.length) {
+                controller.enqueue(joinArrays(buffer));
+            }
+        },
+    });
+}
+
+interface StreamPart {
+    id: string | undefined;
+    event: string;
+    data: unknown;
+}
+
+export function SSEDecoder() {
+    let event = "";
+    let data: Uint8Array[] = [];
+    let lastEventId = "";
+    let retry: number | null = null;
+
+    const decoder = new TextDecoder();
+
+    return new TransformStream<Uint8Array, StreamPart>({
+        transform(chunk, controller) {
+            // Handle empty line case
+            if (!chunk.length) {
+                if (!event && !data.length && !lastEventId && retry == null) return;
+
+                const sse = {
+                    id: lastEventId || undefined,
+                    event,
+                    data: data.length ? decodeArraysToJson(decoder, data) : null,
+                };
+
+                // NOTE: as per the SSE spec, do not reset lastEventId
+                event = "";
+                data = [];
+                retry = null;
+
+                controller.enqueue(sse);
+                return;
+            }
+
+            // Ignore comments
+            if (chunk[0] === COLON) return;
+
+            const sepIdx = chunk.indexOf(COLON);
+            if (sepIdx === -1) return;
+
+            const fieldName = decoder.decode(chunk.subarray(0, sepIdx));
+            let value = chunk.subarray(sepIdx + 1);
+            if (value[0] === SPACE) value = value.subarray(1);
+
+            if (fieldName === "event") {
+                event = decoder.decode(value);
+            } else if (fieldName === "data") {
+                data.push(value);
+            } else if (fieldName === "id") {
+                if (value.indexOf(NULL) === -1) lastEventId = decoder.decode(value);
+            } else if (fieldName === "retry") {
+                const retryNum = Number.parseInt(decoder.decode(value), 10);
+                if (!Number.isNaN(retryNum)) retry = retryNum;
+            }
+        },
+
+        flush(controller) {
+            if (event) {
+                controller.enqueue({
+                    id: lastEventId || undefined,
+                    event,
+                    data: data.length ? decodeArraysToJson(decoder, data) : null,
+                });
+            }
+        },
+    });
+}
+
+function joinArrays(data: ArrayLike<number>[]) {
+    const totalLength = data.reduce((acc, curr) => acc + curr.length, 0);
+    const merged = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const c of data) {
+        merged.set(c, offset);
+        offset += c.length;
+    }
+    return merged;
+}
+
+function decodeArraysToJson(decoder: TextDecoder, data: ArrayLike<number>[]) {
+    return JSON.parse(decoder.decode(joinArrays(data)));
+}

package/src/client/utils/stream.ts

@@ -0,0 +1,114 @@
+/** copied from https://github.com/langchain-ai/langgraphjs/tree/main/libs/sdk/src/utils */
+// in this case don't quite match.
+type IterableReadableStreamInterface<T> = ReadableStream<T> & AsyncIterable<T>;
+
+/*
+ * Support async iterator syntax for ReadableStreams in all environments.
+ * Source: https://github.com/MattiasBuelens/web-streams-polyfill/pull/122#issuecomment-1627354490
+ */
+export class IterableReadableStream<T> extends ReadableStream<T> implements IterableReadableStreamInterface<T> {
+    /** @ts-ignore */
+    public reader: ReadableStreamDefaultReader<T>;
+
+    ensureReader() {
+        if (!this.reader) {
+            this.reader = this.getReader();
+        }
+    }
+
+    async next(): Promise<IteratorResult<T>> {
+        this.ensureReader();
+        try {
+            const result = await this.reader.read();
+            if (result.done) {
+                this.reader.releaseLock(); // release lock when stream becomes closed
+                return {
+                    done: true,
+                    value: undefined,
+                };
+            } else {
+                return {
+                    done: false,
+                    value: result.value,
+                };
+            }
+        } catch (e) {
+            this.reader.releaseLock(); // release lock when stream becomes errored
+            throw e;
+        }
+    }
+
+    async return(): Promise<IteratorResult<T>> {
+        this.ensureReader();
+        // If wrapped in a Node stream, cancel is already called.
+        if (this.locked) {
+            const cancelPromise = this.reader.cancel(); // cancel first, but don't await yet
+            this.reader.releaseLock(); // release lock first
+            await cancelPromise; // now await it
+        }
+        return { done: true, value: undefined };
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async throw(e: any): Promise<IteratorResult<T>> {
+        this.ensureReader();
+        if (this.locked) {
+            const cancelPromise = this.reader.cancel(); // cancel first, but don't await yet
+            this.reader.releaseLock(); // release lock first
+            await cancelPromise; // now await it
+        }
+        throw e;
+    }
+
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore Not present in Node 18 types, required in latest Node 22
+    async [Symbol.asyncDispose]() {
+        await this.return();
+    }
+
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+
+    static fromReadableStream<T>(stream: ReadableStream<T>) {
+        // From https://developer.mozilla.org/en-US/docs/Web/API/Streams_API/Using_readable_streams#reading_the_stream
+        const reader = stream.getReader();
+        return new IterableReadableStream<T>({
+            start(controller) {
+                return pump();
+                function pump(): Promise<T | undefined> {
+                    return reader.read().then(({ done, value }) => {
+                        // When no more data needs to be consumed, close the stream
+                        if (done) {
+                            controller.close();
+                            return;
+                        }
+                        // Enqueue the next data chunk into our target stream
+                        controller.enqueue(value);
+                        return pump();
+                    });
+                }
+            },
+            cancel() {
+                reader.releaseLock();
+            },
+        });
+    }
+
+    static fromAsyncGenerator<T>(generator: AsyncGenerator<T>) {
+        return new IterableReadableStream<T>({
+            async pull(controller) {
+                const { value, done } = await generator.next();
+                // When no more data needs to be consumed, close the stream
+                if (done) {
+                    controller.close();
+                }
+                // Fix: `else if (value)` will hang the streaming when nullish value (e.g. empty string) is pulled
+                controller.enqueue(value);
+            },
+            async cancel(reason) {
+                await generator.return(reason);
+            },
+        });
+    }
+}

package/src/index.ts

@@ -6,3 +6,5 @@ export * from "./ui-store/index.js";
 export * from "./ToolManager.js";
 export * from "./TestKit.js";
 export * from "./artifacts/index.js";
+export * from "./client/index.js";
+export * from "./History.js";