@langchain/langgraph-sdk 0.0.73 → 0.0.75

package/dist/client.cjs

@@ -32,6 +32,19 @@ function getApiKey(apiKey) {
     return undefined;
 }
 exports.getApiKey = getApiKey;
+const REGEX_RUN_METADATA = /(\/threads\/(?<thread_id>.+))?\/runs\/(?<run_id>.+)/;
+function getRunMetadataFromResponse(response) {
+    const contentLocation = response.headers.get("Content-Location");
+    if (!contentLocation)
+        return undefined;
+    const match = REGEX_RUN_METADATA.exec(contentLocation);
+    if (!match?.groups?.run_id)
+        return undefined;
+    return {
+        run_id: match.groups.run_id,
+        thread_id: match.groups.thread_id || undefined,
+    };
+}
 class BaseClient {
     constructor(config) {
         Object.defineProperty(this, "asyncCaller", {
@@ -100,6 +113,9 @@ class BaseClient {
             };
             delete mutatedOptions.json;
         }
+        if (mutatedOptions.withResponse) {
+            delete mutatedOptions.withResponse;
+        }
         let timeoutSignal = null;
         if (typeof options?.timeoutMs !== "undefined") {
             if (options.timeoutMs != null) {
@@ -126,10 +142,16 @@ class BaseClient {
     }
     async fetch(path, options) {
         const response = await this.asyncCaller.fetch(...this.prepareFetchOptions(path, options));
-        if (response.status === 202 || response.status === 204) {
-            return undefined;
+        const body = (() => {
+            if (response.status === 202 || response.status === 204) {
+                return undefined;
+            }
+            return response.json();
+        })();
+        if (options?.withResponse) {
+            return [await body, response];
         }
-        return response.json();
+        return body;
     }
 }
 class CronsClient extends BaseClient {
@@ -152,6 +174,7 @@ class CronsClient extends BaseClient {
             webhook: payload?.webhook,
             multitask_strategy: payload?.multitaskStrategy,
             if_not_exists: payload?.ifNotExists,
+            checkpoint_during: payload?.checkpointDuring,
         };
         return this.fetch(`/threads/${threadId}/runs/crons`, {
             method: "POST",
@@ -176,6 +199,7 @@ class CronsClient extends BaseClient {
             webhook: payload?.webhook,
             multitask_strategy: payload?.multitaskStrategy,
             if_not_exists: payload?.ifNotExists,
+            checkpoint_during: payload?.checkpointDuring,
         };
         return this.fetch(`/runs/crons`, {
             method: "POST",
@@ -545,6 +569,7 @@ class RunsClient extends BaseClient {
             on_disconnect: payload?.onDisconnect,
             after_seconds: payload?.afterSeconds,
             if_not_exists: payload?.ifNotExists,
+            checkpoint_during: payload?.checkpointDuring,
         };
         const endpoint = threadId == null ? `/runs/stream` : `/threads/${threadId}/runs/stream`;
         const response = await this.asyncCaller.fetch(...this.prepareFetchOptions(endpoint, {
@@ -553,6 +578,9 @@ class RunsClient extends BaseClient {
             timeoutMs: null,
             signal: payload?.signal,
         }));
+        const runMetadata = getRunMetadataFromResponse(response);
+        if (runMetadata)
+            payload?.onRunCreated?.(runMetadata);
         const stream = (response.body || new ReadableStream({ start: (ctrl) => ctrl.close() }))
             .pipeThrough(new sse_js_1.BytesLineDecoder())
             .pipeThrough(new sse_js_1.SSEDecoder());
@@ -583,12 +611,18 @@ class RunsClient extends BaseClient {
             multitask_strategy: payload?.multitaskStrategy,
             after_seconds: payload?.afterSeconds,
             if_not_exists: payload?.ifNotExists,
+            checkpoint_during: payload?.checkpointDuring,
         };
-        return this.fetch(`/threads/${threadId}/runs`, {
+        const [run, response] = await this.fetch(`/threads/${threadId}/runs`, {
             method: "POST",
             json,
             signal: payload?.signal,
+            withResponse: true,
         });
+        const runMetadata = getRunMetadataFromResponse(response);
+        if (runMetadata)
+            payload?.onRunCreated?.(runMetadata);
+        return run;
     }
     /**
      * Create a batch of stateless background runs.
@@ -632,24 +666,29 @@ class RunsClient extends BaseClient {
             on_disconnect: payload?.onDisconnect,
             after_seconds: payload?.afterSeconds,
             if_not_exists: payload?.ifNotExists,
+            checkpoint_during: payload?.checkpointDuring,
         };
         const endpoint = threadId == null ? `/runs/wait` : `/threads/${threadId}/runs/wait`;
-        const response = await this.fetch(endpoint, {
+        const [run, response] = await this.fetch(endpoint, {
             method: "POST",
             json,
             timeoutMs: null,
             signal: payload?.signal,
+            withResponse: true,
         });
+        const runMetadata = getRunMetadataFromResponse(response);
+        if (runMetadata)
+            payload?.onRunCreated?.(runMetadata);
         const raiseError = payload?.raiseError !== undefined ? payload.raiseError : true;
         if (raiseError &&
-            "__error__" in response &&
-            typeof response.__error__ === "object" &&
-            response.__error__ &&
-            "error" in response.__error__ &&
-            "message" in response.__error__) {
-            throw new Error(`${response.__error__?.error}: ${response.__error__?.message}`);
+            "__error__" in run &&
+            typeof run.__error__ === "object" &&
+            run.__error__ &&
+            "error" in run.__error__ &&
+            "message" in run.__error__) {
+            throw new Error(`${run.__error__?.error}: ${run.__error__?.message}`);
         }
-        return response;
+        return run;
     }
     /**
      * List all runs for a thread.
@@ -710,13 +749,12 @@ class RunsClient extends BaseClient {
     }
     /**
      * Stream output from a run in real-time, until the run is done.
-     * Output is not buffered, so any output produced before this call will
-     * not be received here.
      *
-     * @param threadId The ID of the thread.
+     * @param threadId The ID of the thread. Can be set to `null` | `undefined` for stateless runs.
      * @param runId The ID of the run.
      * @param options Additional options for controlling the stream behavior:
      *   - signal: An AbortSignal that can be used to cancel the stream request
+     *   - lastEventId: The ID of the last event received. Can be used to reconnect to a stream without losing events.
      *   - cancelOnDisconnect: When true, automatically cancels the run if the client disconnects from the stream
      *   - streamMode: Controls what types of events to receive from the stream (can be a single mode or array of modes)
      *        Must be a subset of the stream modes passed when creating the run. Background runs default to having the union of all
@@ -729,10 +767,15 @@ class RunsClient extends BaseClient {
             options instanceof AbortSignal
             ? { signal: options }
             : options;
-        const response = await this.asyncCaller.fetch(...this.prepareFetchOptions(`/threads/${threadId}/runs/${runId}/stream`, {
+        const response = await this.asyncCaller.fetch(...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 }
+                : undefined,
             params: {
                 cancel_on_disconnect: opts?.cancelOnDisconnect ? "1" : "0",
                 stream_mode: opts?.streamMode,

package/dist/client.d.ts

@@ -31,12 +31,21 @@ declare class BaseClient {
         json?: unknown;
         params?: Record<string, unknown>;
         timeoutMs?: number | null;
+        withResponse?: boolean;
     }): [url: URL, init: RequestInit];
+    protected fetch<T>(path: string, options: RequestInit & {
+        json?: unknown;
+        params?: Record<string, unknown>;
+        timeoutMs?: number | null;
+        signal?: AbortSignal;
+        withResponse: true;
+    }): Promise<[T, Response]>;
     protected fetch<T>(path: string, options?: RequestInit & {
         json?: unknown;
         params?: Record<string, unknown>;
         timeoutMs?: number | null;
         signal?: AbortSignal;
+        withResponse?: false;
     }): Promise<T>;
 }
 export declare class CronsClient extends BaseClient {
@@ -398,24 +407,25 @@ export declare class RunsClient<TStateType = DefaultValues, TUpdateType = TState
     }): Promise<void>;
     /**
      * Stream output from a run in real-time, until the run is done.
-     * Output is not buffered, so any output produced before this call will
-     * not be received here.
      *
-     * @param threadId The ID of the thread.
+     * @param threadId The ID of the thread. Can be set to `null` | `undefined` for stateless runs.
      * @param runId The ID of the run.
      * @param options Additional options for controlling the stream behavior:
      *   - signal: An AbortSignal that can be used to cancel the stream request
+     *   - lastEventId: The ID of the last event received. Can be used to reconnect to a stream without losing events.
      *   - cancelOnDisconnect: When true, automatically cancels the run if the client disconnects from the stream
      *   - streamMode: Controls what types of events to receive from the stream (can be a single mode or array of modes)
      *        Must be a subset of the stream modes passed when creating the run. Background runs default to having the union of all
      *        stream modes enabled.
      * @returns An async generator yielding stream parts.
      */
-    joinStream(threadId: string, runId: string, options?: {
+    joinStream(threadId: string | undefined | null, runId: string, options?: {
         signal?: AbortSignal;
         cancelOnDisconnect?: boolean;
+        lastEventId?: string;
         streamMode?: StreamMode | StreamMode[];
     } | AbortSignal): AsyncGenerator<{
+        id?: string;
         event: StreamEvent;
         data: any;
     }>;

package/dist/client.js

@@ -28,6 +28,19 @@ export function getApiKey(apiKey) {
     }
     return undefined;
 }
+const REGEX_RUN_METADATA = /(\/threads\/(?<thread_id>.+))?\/runs\/(?<run_id>.+)/;
+function getRunMetadataFromResponse(response) {
+    const contentLocation = response.headers.get("Content-Location");
+    if (!contentLocation)
+        return undefined;
+    const match = REGEX_RUN_METADATA.exec(contentLocation);
+    if (!match?.groups?.run_id)
+        return undefined;
+    return {
+        run_id: match.groups.run_id,
+        thread_id: match.groups.thread_id || undefined,
+    };
+}
 class BaseClient {
     constructor(config) {
         Object.defineProperty(this, "asyncCaller", {
@@ -96,6 +109,9 @@ class BaseClient {
             };
             delete mutatedOptions.json;
         }
+        if (mutatedOptions.withResponse) {
+            delete mutatedOptions.withResponse;
+        }
         let timeoutSignal = null;
         if (typeof options?.timeoutMs !== "undefined") {
             if (options.timeoutMs != null) {
@@ -122,10 +138,16 @@ class BaseClient {
     }
     async fetch(path, options) {
         const response = await this.asyncCaller.fetch(...this.prepareFetchOptions(path, options));
-        if (response.status === 202 || response.status === 204) {
-            return undefined;
+        const body = (() => {
+            if (response.status === 202 || response.status === 204) {
+                return undefined;
+            }
+            return response.json();
+        })();
+        if (options?.withResponse) {
+            return [await body, response];
         }
-        return response.json();
+        return body;
     }
 }
 export class CronsClient extends BaseClient {
@@ -148,6 +170,7 @@ export class CronsClient extends BaseClient {
             webhook: payload?.webhook,
             multitask_strategy: payload?.multitaskStrategy,
             if_not_exists: payload?.ifNotExists,
+            checkpoint_during: payload?.checkpointDuring,
         };
         return this.fetch(`/threads/${threadId}/runs/crons`, {
             method: "POST",
@@ -172,6 +195,7 @@ export class CronsClient extends BaseClient {
             webhook: payload?.webhook,
             multitask_strategy: payload?.multitaskStrategy,
             if_not_exists: payload?.ifNotExists,
+            checkpoint_during: payload?.checkpointDuring,
         };
         return this.fetch(`/runs/crons`, {
             method: "POST",
@@ -538,6 +562,7 @@ export class RunsClient extends BaseClient {
             on_disconnect: payload?.onDisconnect,
             after_seconds: payload?.afterSeconds,
             if_not_exists: payload?.ifNotExists,
+            checkpoint_during: payload?.checkpointDuring,
         };
         const endpoint = threadId == null ? `/runs/stream` : `/threads/${threadId}/runs/stream`;
         const response = await this.asyncCaller.fetch(...this.prepareFetchOptions(endpoint, {
@@ -546,6 +571,9 @@ export class RunsClient extends BaseClient {
             timeoutMs: null,
             signal: payload?.signal,
         }));
+        const runMetadata = getRunMetadataFromResponse(response);
+        if (runMetadata)
+            payload?.onRunCreated?.(runMetadata);
         const stream = (response.body || new ReadableStream({ start: (ctrl) => ctrl.close() }))
             .pipeThrough(new BytesLineDecoder())
             .pipeThrough(new SSEDecoder());
@@ -576,12 +604,18 @@ export class RunsClient extends BaseClient {
             multitask_strategy: payload?.multitaskStrategy,
             after_seconds: payload?.afterSeconds,
             if_not_exists: payload?.ifNotExists,
+            checkpoint_during: payload?.checkpointDuring,
         };
-        return this.fetch(`/threads/${threadId}/runs`, {
+        const [run, response] = await this.fetch(`/threads/${threadId}/runs`, {
             method: "POST",
             json,
             signal: payload?.signal,
+            withResponse: true,
         });
+        const runMetadata = getRunMetadataFromResponse(response);
+        if (runMetadata)
+            payload?.onRunCreated?.(runMetadata);
+        return run;
     }
     /**
      * Create a batch of stateless background runs.
@@ -625,24 +659,29 @@ export class RunsClient extends BaseClient {
             on_disconnect: payload?.onDisconnect,
             after_seconds: payload?.afterSeconds,
             if_not_exists: payload?.ifNotExists,
+            checkpoint_during: payload?.checkpointDuring,
         };
         const endpoint = threadId == null ? `/runs/wait` : `/threads/${threadId}/runs/wait`;
-        const response = await this.fetch(endpoint, {
+        const [run, response] = await this.fetch(endpoint, {
             method: "POST",
             json,
             timeoutMs: null,
             signal: payload?.signal,
+            withResponse: true,
         });
+        const runMetadata = getRunMetadataFromResponse(response);
+        if (runMetadata)
+            payload?.onRunCreated?.(runMetadata);
         const raiseError = payload?.raiseError !== undefined ? payload.raiseError : true;
         if (raiseError &&
-            "__error__" in response &&
-            typeof response.__error__ === "object" &&
-            response.__error__ &&
-            "error" in response.__error__ &&
-            "message" in response.__error__) {
-            throw new Error(`${response.__error__?.error}: ${response.__error__?.message}`);
+            "__error__" in run &&
+            typeof run.__error__ === "object" &&
+            run.__error__ &&
+            "error" in run.__error__ &&
+            "message" in run.__error__) {
+            throw new Error(`${run.__error__?.error}: ${run.__error__?.message}`);
         }
-        return response;
+        return run;
     }
     /**
      * List all runs for a thread.
@@ -703,13 +742,12 @@ export class RunsClient extends BaseClient {
     }
     /**
      * Stream output from a run in real-time, until the run is done.
-     * Output is not buffered, so any output produced before this call will
-     * not be received here.
      *
-     * @param threadId The ID of the thread.
+     * @param threadId The ID of the thread. Can be set to `null` | `undefined` for stateless runs.
      * @param runId The ID of the run.
      * @param options Additional options for controlling the stream behavior:
      *   - signal: An AbortSignal that can be used to cancel the stream request
+     *   - lastEventId: The ID of the last event received. Can be used to reconnect to a stream without losing events.
      *   - cancelOnDisconnect: When true, automatically cancels the run if the client disconnects from the stream
      *   - streamMode: Controls what types of events to receive from the stream (can be a single mode or array of modes)
      *        Must be a subset of the stream modes passed when creating the run. Background runs default to having the union of all
@@ -722,10 +760,15 @@ export class RunsClient extends BaseClient {
             options instanceof AbortSignal
             ? { signal: options }
             : options;
-        const response = await this.asyncCaller.fetch(...this.prepareFetchOptions(`/threads/${threadId}/runs/${runId}/stream`, {
+        const response = await this.asyncCaller.fetch(...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 }
+                : undefined,
             params: {
                 cancel_on_disconnect: opts?.cancelOnDisconnect ? "1" : "0",
                 stream_mode: opts?.streamMode,

package/dist/types.d.ts

@@ -46,6 +46,10 @@ interface RunsInvokePayload {
      * Checkpoint for when creating a new run.
      */
     checkpoint?: Omit<Checkpoint, "thread_id">;
+    /**
+     * Whether to checkpoint during the run (or only at the end/interruption).
+     */
+    checkpointDuring?: boolean;
     /**
      * Interrupt execution before entering these nodes.
      */
@@ -100,6 +104,13 @@ interface RunsInvokePayload {
      * One or more commands to invoke the graph with.
      */
     command?: Command;
+    /**
+     * Callback when a run is created.
+     */
+    onRunCreated?: (params: {
+        run_id: string;
+        thread_id?: string;
+    }) => void;
 }
 export interface RunsStreamPayload<TStreamMode extends StreamMode | StreamMode[] = [], TSubgraphs extends boolean = false> extends RunsInvokePayload {
     /**

package/dist/types.stream.d.ts

@@ -15,9 +15,11 @@ type MessageTupleMetadata = {
     [key: string]: unknown;
 };
 type AsSubgraph<TEvent extends {
+    id?: string;
     event: string;
     data: unknown;
 }> = {
+    id?: TEvent["id"];
     event: TEvent["event"] | `${TEvent["event"]}|${string}`;
     data: TEvent["data"];
 };
@@ -25,6 +27,7 @@ type AsSubgraph<TEvent extends {
  * Stream event with values after completion of each step.
  */
 export type ValuesStreamEvent<StateType> = {
+    id?: string;
     event: "values";
     data: StateType;
 };
@@ -43,6 +46,7 @@ export type SubgraphMessagesTupleStreamEvent = AsSubgraph<MessagesTupleStreamEve
  * Metadata stream event with information about the run and thread
  */
 export type MetadataStreamEvent = {
+    id?: string;
     event: "metadata";
     data: {
         run_id: string;
@@ -53,6 +57,7 @@ export type MetadataStreamEvent = {
  * Stream event with error information.
  */
 export type ErrorStreamEvent = {
+    id?: string;
     event: "error";
     data: {
         error: string;
@@ -67,6 +72,7 @@ export type SubgraphErrorStreamEvent = AsSubgraph<ErrorStreamEvent>;
  * produced the update as well as the update.
  */
 export type UpdatesStreamEvent<UpdateType> = {
+    id?: string;
     event: "updates";
     data: {
         [node: string]: UpdateType;
@@ -84,6 +90,7 @@ export type CustomStreamEvent<T> = {
 /** @internal */
 export type SubgraphCustomStreamEvent<T> = AsSubgraph<CustomStreamEvent<T>>;
 type MessagesMetadataStreamEvent = {
+    id?: string;
     event: "messages/metadata";
     data: {
         [messageId: string]: {
@@ -92,10 +99,12 @@ type MessagesMetadataStreamEvent = {
     };
 };
 type MessagesCompleteStreamEvent = {
+    id?: string;
     event: "messages/complete";
     data: Message[];
 };
 type MessagesPartialStreamEvent = {
+    id?: string;
     event: "messages/partial";
     data: Message[];
 };
@@ -110,6 +119,7 @@ export type SubgraphMessagesStreamEvent = AsSubgraph<MessagesMetadataStreamEvent
  * Stream event with detailed debug information.
  */
 export type DebugStreamEvent = {
+    id?: string;
     event: "debug";
     data: unknown;
 };
@@ -119,6 +129,7 @@ export type SubgraphDebugStreamEvent = AsSubgraph<DebugStreamEvent>;
  * Stream event with events occurring during execution.
  */
 export type EventsStreamEvent = {
+    id?: string;
     event: "events";
     data: {
         event: `on_${"chat_model" | "llm" | "chain" | "tool" | "retriever" | "prompt"}_${"start" | "stream" | "end"}` | (string & {});
@@ -137,6 +148,7 @@ export type SubgraphEventsStreamEvent = AsSubgraph<EventsStreamEvent>;
  * the `RunsStreamPayload` to receive this event.
  */
 export type FeedbackStreamEvent = {
+    id?: string;
     event: "feedback";
     data: {
         [feedbackKey: string]: string;

package/dist/utils/sse.cjs

@@ -94,6 +94,7 @@ class SSEDecoder extends TransformStream {
                     if (!event && !data.length && !lastEventId && retry == null)
                         return;
                     const sse = {
+                        id: lastEventId || undefined,
                         event,
                         data: data.length ? decodeArraysToJson(decoder, data) : null,
                     };
@@ -133,6 +134,7 @@ class SSEDecoder extends TransformStream {
             flush(controller) {
                 if (event) {
                     controller.enqueue({
+                        id: lastEventId || undefined,
                         event,
                         data: data.length ? decodeArraysToJson(decoder, data) : null,
                     });

package/dist/utils/sse.d.ts

@@ -2,6 +2,7 @@ export declare class BytesLineDecoder extends TransformStream<Uint8Array, Uint8A
     constructor();
 }
 interface StreamPart {
+    id: string | undefined;
     event: string;
     data: unknown;
 }

package/dist/utils/sse.js

@@ -90,6 +90,7 @@ export class SSEDecoder extends TransformStream {
                     if (!event && !data.length && !lastEventId && retry == null)
                         return;
                     const sse = {
+                        id: lastEventId || undefined,
                         event,
                         data: data.length ? decodeArraysToJson(decoder, data) : null,
                     };
@@ -129,6 +130,7 @@ export class SSEDecoder extends TransformStream {
             flush(controller) {
                 if (event) {
                     controller.enqueue({
+                        id: lastEventId || undefined,
                         event,
                         data: data.length ? decodeArraysToJson(decoder, data) : null,
                     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@langchain/langgraph-sdk",
-  "version": "0.0.73",
+  "version": "0.0.75",
   "description": "Client library for interacting with the LangGraph API",
   "type": "module",
   "packageManager": "yarn@1.22.19",
@@ -10,7 +10,7 @@
     "prepack": "yarn run build",
     "format": "prettier --write src",
     "lint": "prettier --check src && tsc --noEmit",
-    "test": "NODE_OPTIONS=--experimental-vm-modules jest --testPathIgnorePatterns=\\.int\\.test.ts",
+    "test": "vitest",
     "typedoc": "typedoc && typedoc src/react/index.ts --out docs/react --options typedoc.react.json && typedoc src/auth/index.ts --out docs/auth --options typedoc.auth.json"
   },
   "main": "index.js",
@@ -22,28 +22,32 @@
     "uuid": "^9.0.0"
   },
   "devDependencies": {
-    "@jest/globals": "^29.7.0",
     "@langchain/core": "^0.3.31",
     "@langchain/scripts": "^0.1.4",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^14.6.1",
     "@tsconfig/recommended": "^1.0.2",
-    "@types/jest": "^29.5.12",
     "@types/node": "^20.12.12",
-    "@types/uuid": "^9.0.1",
     "@types/react": "^19.0.8",
     "@types/react-dom": "^19.0.3",
+    "@types/uuid": "^9.0.1",
+    "@vitejs/plugin-react": "^4.4.1",
     "concat-md": "^0.5.1",
-    "jest": "^29.7.0",
+    "jsdom": "^26.1.0",
+    "msw": "^2.8.2",
     "prettier": "^3.2.5",
-    "ts-jest": "^29.1.2",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
     "typedoc": "^0.27.7",
     "typedoc-plugin-markdown": "^4.4.2",
     "typescript": "^5.4.5",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0"
+    "vitest": "^3.1.3"
   },
   "peerDependencies": {
-    "react": "^18 || ^19",
-    "@langchain/core": ">=0.2.31 <0.4.0"
+    "@langchain/core": ">=0.2.31 <0.4.0",
+    "react": "^18 || ^19"
   },
   "peerDependenciesMeta": {
     "react": {