@langchain/langgraph-sdk 0.0.70 → 0.0.72

package/dist/react/stream.cjs

@@ -211,12 +211,14 @@ const useControllableThreadId = (options) => {
 function useStream(options) {
     let { assistantId, messagesKey, onError, onFinish } = options;
     messagesKey ??= "messages";
-    const client = (0, react_1.useMemo)(() => new client_js_1.Client({
-        apiUrl: options.apiUrl,
-        apiKey: options.apiKey,
-        callerOptions: options.callerOptions,
-        defaultHeaders: options.defaultHeaders,
-    }), [
+    const client = (0, react_1.useMemo)(() => options.client ??
+        new client_js_1.Client({
+            apiUrl: options.apiUrl,
+            apiKey: options.apiKey,
+            callerOptions: options.callerOptions,
+            defaultHeaders: options.defaultHeaders,
+        }), [
+        options.client,
         options.apiKey,
         options.apiUrl,
         options.callerOptions,
@@ -240,14 +242,25 @@ function useStream(options) {
     }, []);
     const hasUpdateListener = options.onUpdateEvent != null;
     const hasCustomListener = options.onCustomEvent != null;
+    const hasLangChainListener = options.onLangChainEvent != null;
+    const hasDebugListener = options.onDebugEvent != null;
     const callbackStreamMode = (0, react_1.useMemo)(() => {
         const modes = [];
         if (hasUpdateListener)
             modes.push("updates");
         if (hasCustomListener)
             modes.push("custom");
+        if (hasLangChainListener)
+            modes.push("events");
+        if (hasDebugListener)
+            modes.push("debug");
         return modes;
-    }, [hasUpdateListener, hasCustomListener]);
+    }, [
+        hasUpdateListener,
+        hasCustomListener,
+        hasLangChainListener,
+        hasDebugListener,
+    ]);
     const clearCallbackRef = (0, react_1.useRef)(null);
     clearCallbackRef.current = () => {
         setStreamError(undefined);
@@ -391,6 +404,10 @@ function useStream(options) {
                     });
                 if (event === "metadata")
                     options.onMetadataEvent?.(data);
+                if (event === "events")
+                    options.onLangChainEvent?.(data);
+                if (event === "debug")
+                    options.onDebugEvent?.(data);
                 if (event === "values")
                     setStreamValues(data);
                 if (event === "messages") {

package/dist/react/stream.d.ts

@@ -2,7 +2,7 @@ import { Client, type ClientConfig } from "../client.js";
 import type { Command, DisconnectMode, MultitaskStrategy, OnCompletionBehavior } from "../types.js";
 import type { Message } from "../types.messages.js";
 import type { Checkpoint, Config, Interrupt, Metadata, ThreadState } from "../schema.js";
-import type { CustomStreamEvent, MetadataStreamEvent, StreamMode, UpdatesStreamEvent } from "../types.stream.js";
+import type { CustomStreamEvent, DebugStreamEvent, EventsStreamEvent, MetadataStreamEvent, StreamMode, UpdatesStreamEvent } from "../types.stream.js";
 interface Node<StateType = any> {
     type: "node";
     value: ThreadState<StateType>;
@@ -58,10 +58,14 @@ export interface UseStreamOptions<StateType extends Record<string, unknown> = Re
      * The ID of the assistant to use.
      */
     assistantId: string;
+    /**
+     * Client used to send requests.
+     */
+    client?: Client;
     /**
      * The URL of the API to use.
      */
-    apiUrl: ClientConfig["apiUrl"];
+    apiUrl?: ClientConfig["apiUrl"];
     /**
      * The API key to use.
      */
@@ -103,6 +107,16 @@ export interface UseStreamOptions<StateType extends Record<string, unknown> = Re
      * Callback that is called when a metadata event is received.
      */
     onMetadataEvent?: (data: MetadataStreamEvent["data"]) => void;
+    /**
+     * Callback that is called when a LangChain event is received.
+     * @see https://langchain-ai.github.io/langgraph/cloud/how-tos/stream_events/#stream-graph-in-events-mode for more details.
+     */
+    onLangChainEvent?: (data: EventsStreamEvent["data"]) => void;
+    /**
+     * Callback that is called when a debug event is received.
+     * @internal This API is experimental and subject to change.
+     */
+    onDebugEvent?: (data: DebugStreamEvent["data"]) => void;
     /**
      * The ID of the thread to fetch history and current values from.
      */

package/dist/react/stream.js

@@ -208,12 +208,14 @@ const useControllableThreadId = (options) => {
 export function useStream(options) {
     let { assistantId, messagesKey, onError, onFinish } = options;
     messagesKey ??= "messages";
-    const client = useMemo(() => new Client({
-        apiUrl: options.apiUrl,
-        apiKey: options.apiKey,
-        callerOptions: options.callerOptions,
-        defaultHeaders: options.defaultHeaders,
-    }), [
+    const client = useMemo(() => options.client ??
+        new Client({
+            apiUrl: options.apiUrl,
+            apiKey: options.apiKey,
+            callerOptions: options.callerOptions,
+            defaultHeaders: options.defaultHeaders,
+        }), [
+        options.client,
         options.apiKey,
         options.apiUrl,
         options.callerOptions,
@@ -237,14 +239,25 @@ export function useStream(options) {
     }, []);
     const hasUpdateListener = options.onUpdateEvent != null;
     const hasCustomListener = options.onCustomEvent != null;
+    const hasLangChainListener = options.onLangChainEvent != null;
+    const hasDebugListener = options.onDebugEvent != null;
     const callbackStreamMode = useMemo(() => {
         const modes = [];
         if (hasUpdateListener)
             modes.push("updates");
         if (hasCustomListener)
             modes.push("custom");
+        if (hasLangChainListener)
+            modes.push("events");
+        if (hasDebugListener)
+            modes.push("debug");
         return modes;
-    }, [hasUpdateListener, hasCustomListener]);
+    }, [
+        hasUpdateListener,
+        hasCustomListener,
+        hasLangChainListener,
+        hasDebugListener,
+    ]);
     const clearCallbackRef = useRef(null);
     clearCallbackRef.current = () => {
         setStreamError(undefined);
@@ -388,6 +401,10 @@ export function useStream(options) {
                     });
                 if (event === "metadata")
                     options.onMetadataEvent?.(data);
+                if (event === "events")
+                    options.onLangChainEvent?.(data);
+                if (event === "debug")
+                    options.onDebugEvent?.(data);
                 if (event === "values")
                     setStreamValues(data);
                 if (event === "messages") {

package/dist/react-ui/client.cjs

@@ -88,6 +88,28 @@ const COMPONENT_STORE = new ComponentStore();
 const EXT_STORE_SYMBOL = Symbol.for("LGUI_EXT_STORE");
 const REQUIRE_SYMBOL = Symbol.for("LGUI_REQUIRE");
 const REQUIRE_EXTRA_SYMBOL = Symbol.for("LGUI_REQUIRE_EXTRA");
+const isIterable = (value) => value != null && typeof value === "object" && Symbol.iterator in value;
+const isPromise = (value) => value != null &&
+    typeof value === "object" &&
+    "then" in value &&
+    typeof value.then === "function";
+const isReactNode = (value) => {
+    if (React.isValidElement(value))
+        return true;
+    if (value == null)
+        return true;
+    if (typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "bigint" ||
+        typeof value === "boolean") {
+        return true;
+    }
+    if (isIterable(value))
+        return true;
+    if (isPromise(value))
+        return true;
+    return false;
+};
 function LoadExternalComponent({ stream, namespace, message, meta, fallback, components, ...props }) {
     const ref = React.useRef(null);
     const id = React.useId();
@@ -96,6 +118,11 @@ function LoadExternalComponent({ stream, namespace, message, meta, fallback, com
     const state = React.useSyncExternalStore(store.subscribe, store.getSnapshot);
     const clientComponent = components?.[message.name];
     const hasClientComponent = clientComponent != null;
+    const fallbackComponent = isReactNode(fallback)
+        ? fallback
+        : typeof fallback === "object" && fallback != null
+            ? fallback?.[message.name]
+            : null;
     const uiNamespace = namespace ?? stream.assistantId;
     const uiClient = stream.client["~ui"];
     React.useEffect(() => {
@@ -117,7 +144,7 @@ function LoadExternalComponent({ stream, namespace, message, meta, fallback, com
     }
     return ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)("div", { id: shadowRootId, ref: ref, ...props }), (0, jsx_runtime_1.jsx)(UseStreamContext.Provider, { value: { stream, meta }, children: state?.target != null
                     ? ReactDOM.createPortal(React.createElement(state.comp, message.props), state.target)
-                    : fallback })] }));
+                    : fallbackComponent })] }));
 }
 exports.LoadExternalComponent = LoadExternalComponent;
 function experimental_loadShare(name, module) {
@@ -129,8 +156,6 @@ function experimental_loadShare(name, module) {
 exports.experimental_loadShare = experimental_loadShare;
 function bootstrapUiContext() {
     if (typeof window === "undefined") {
-        console.warn("Attempting to bootstrap UI context outside of browser environment. " +
-            "Avoid importing from `@langchain/langgraph-sdk/react-ui` in server context.");
         return;
     }
     window[EXT_STORE_SYMBOL] = COMPONENT_STORE;

package/dist/react-ui/client.d.ts

@@ -59,7 +59,7 @@ interface LoadExternalComponentProps extends Pick<React.HTMLAttributes<HTMLDivEl
     /** Additional context to be passed to the child component */
     meta?: unknown;
     /** Fallback to be rendered when the component is loading */
-    fallback?: React.ReactNode;
+    fallback?: React.ReactNode | Record<string, React.ReactNode>;
     /**
      * Map of components that can be rendered directly without fetching the UI code
      * from the server.

package/dist/react-ui/client.js

@@ -61,6 +61,28 @@ const COMPONENT_STORE = new ComponentStore();
 const EXT_STORE_SYMBOL = Symbol.for("LGUI_EXT_STORE");
 const REQUIRE_SYMBOL = Symbol.for("LGUI_REQUIRE");
 const REQUIRE_EXTRA_SYMBOL = Symbol.for("LGUI_REQUIRE_EXTRA");
+const isIterable = (value) => value != null && typeof value === "object" && Symbol.iterator in value;
+const isPromise = (value) => value != null &&
+    typeof value === "object" &&
+    "then" in value &&
+    typeof value.then === "function";
+const isReactNode = (value) => {
+    if (React.isValidElement(value))
+        return true;
+    if (value == null)
+        return true;
+    if (typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "bigint" ||
+        typeof value === "boolean") {
+        return true;
+    }
+    if (isIterable(value))
+        return true;
+    if (isPromise(value))
+        return true;
+    return false;
+};
 export function LoadExternalComponent({ stream, namespace, message, meta, fallback, components, ...props }) {
     const ref = React.useRef(null);
     const id = React.useId();
@@ -69,6 +91,11 @@ export function LoadExternalComponent({ stream, namespace, message, meta, fallba
     const state = React.useSyncExternalStore(store.subscribe, store.getSnapshot);
     const clientComponent = components?.[message.name];
     const hasClientComponent = clientComponent != null;
+    const fallbackComponent = isReactNode(fallback)
+        ? fallback
+        : typeof fallback === "object" && fallback != null
+            ? fallback?.[message.name]
+            : null;
     const uiNamespace = namespace ?? stream.assistantId;
     const uiClient = stream.client["~ui"];
     React.useEffect(() => {
@@ -90,7 +117,7 @@ export function LoadExternalComponent({ stream, namespace, message, meta, fallba
     }
     return (_jsxs(_Fragment, { children: [_jsx("div", { id: shadowRootId, ref: ref, ...props }), _jsx(UseStreamContext.Provider, { value: { stream, meta }, children: state?.target != null
                     ? ReactDOM.createPortal(React.createElement(state.comp, message.props), state.target)
-                    : fallback })] }));
+                    : fallbackComponent })] }));
 }
 export function experimental_loadShare(name, module) {
     if (typeof window === "undefined")
@@ -100,8 +127,6 @@ export function experimental_loadShare(name, module) {
 }
 export function bootstrapUiContext() {
     if (typeof window === "undefined") {
-        console.warn("Attempting to bootstrap UI context outside of browser environment. " +
-            "Avoid importing from `@langchain/langgraph-sdk/react-ui` in server context.");
         return;
     }
     window[EXT_STORE_SYMBOL] = COMPONENT_STORE;

package/dist/react-ui/index.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.uiMessageReducer = exports.experimental_loadShare = exports.LoadExternalComponent = exports.useStreamContext = void 0;
+exports.isRemoveUIMessage = exports.isUIMessage = exports.uiMessageReducer = exports.experimental_loadShare = exports.LoadExternalComponent = exports.useStreamContext = void 0;
 const client_js_1 = require("./client.cjs");
 (0, client_js_1.bootstrapUiContext)();
 var client_js_2 = require("./client.cjs");
@@ -9,3 +9,5 @@ Object.defineProperty(exports, "LoadExternalComponent", { enumerable: true, get:
 Object.defineProperty(exports, "experimental_loadShare", { enumerable: true, get: function () { return client_js_2.experimental_loadShare; } });
 var types_js_1 = require("./types.cjs");
 Object.defineProperty(exports, "uiMessageReducer", { enumerable: true, get: function () { return types_js_1.uiMessageReducer; } });
+Object.defineProperty(exports, "isUIMessage", { enumerable: true, get: function () { return types_js_1.isUIMessage; } });
+Object.defineProperty(exports, "isRemoveUIMessage", { enumerable: true, get: function () { return types_js_1.isRemoveUIMessage; } });

package/dist/react-ui/index.d.ts

@@ -1,2 +1,2 @@
 export { useStreamContext, LoadExternalComponent, experimental_loadShare, } from "./client.js";
-export { uiMessageReducer, type UIMessage, type RemoveUIMessage, } from "./types.js";
+export { uiMessageReducer, isUIMessage, isRemoveUIMessage, type UIMessage, type RemoveUIMessage, } from "./types.js";

package/dist/react-ui/index.js

@@ -1,4 +1,4 @@
 import { bootstrapUiContext } from "./client.js";
 bootstrapUiContext();
 export { useStreamContext, LoadExternalComponent, experimental_loadShare, } from "./client.js";
-export { uiMessageReducer, } from "./types.js";
+export { uiMessageReducer, isUIMessage, isRemoveUIMessage, } from "./types.js";

package/dist/react-ui/server/server.cjs

@@ -16,20 +16,17 @@ const typedUi = (config, options) => {
     const runId = config.metadata?.run_id ?? config.runId;
     if (!runId)
         throw new Error("run_id is required");
-    const metadata = {
-        ...config.metadata,
-        tags: config.tags,
-        name: config.runName,
-        run_id: runId,
-    };
-    const handlePush = (message, options) => {
+    function handlePush(message, options) {
         const evt = {
             type: "ui",
             id: message?.id ?? (0, uuid_1.v4)(),
             name: message?.name,
             props: message?.props,
             metadata: {
-                ...metadata,
+                merge: options?.merge || undefined,
+                run_id: runId,
+                tags: config.tags,
+                name: config.runName,
                 ...message?.metadata,
                 ...(options?.message ? { message_id: options.message.id } : null),
             },
@@ -38,7 +35,7 @@ const typedUi = (config, options) => {
         config.writer?.(evt);
         config.configurable?.__pregel_send?.([[stateKey, evt]]);
         return evt;
-    };
+    }
     const handleDelete = (id) => {
         const evt = { type: "remove-ui", id };
         items.push(evt);

package/dist/react-ui/server/server.d.ts

@@ -25,15 +25,27 @@ export declare const typedUi: <Decl extends Record<string, ElementType>>(config:
     /** The key to write the UI messages to. Defaults to `ui`. */
     stateKey?: string;
 }) => {
-    push: <K extends keyof Decl & string>(message: {
-        id?: string | undefined;
-        name: K;
-        props: { [K_1 in keyof Decl]: ComponentPropsWithoutRef<Decl[K_1]>; }[K];
-        metadata?: Record<string, unknown> | undefined;
-    }, options?: {
-        message?: MessageLike;
-    }) => UIMessage;
+    push: {
+        <K extends keyof Decl & string>(message: {
+            id?: string | undefined;
+            name: K;
+            props: { [K_1 in keyof Decl]: ComponentPropsWithoutRef<Decl[K_1]>; }[K];
+            metadata?: Record<string, unknown> | undefined;
+        }, options?: {
+            message?: MessageLike;
+            merge?: boolean;
+        }): UIMessage<K, { [K_1 in keyof Decl]: ComponentPropsWithoutRef<Decl[K_1]>; }[K]>;
+        <K_2 extends keyof Decl & string>(message: {
+            id?: string | undefined;
+            name: K_2;
+            props: Partial<{ [K_1 in keyof Decl]: ComponentPropsWithoutRef<Decl[K_1]>; }[K_2]>;
+            metadata?: Record<string, unknown> | undefined;
+        }, options: {
+            message?: MessageLike;
+            merge: true;
+        }): UIMessage<K_2, Partial<{ [K_1 in keyof Decl]: ComponentPropsWithoutRef<Decl[K_1]>; }[K_2]>>;
+    };
     delete: (id: string) => RemoveUIMessage;
-    items: (UIMessage | RemoveUIMessage)[];
+    items: (RemoveUIMessage | UIMessage<string, Record<string, unknown>>)[];
 };
 export {};

package/dist/react-ui/server/server.js

@@ -13,20 +13,17 @@ export const typedUi = (config, options) => {
     const runId = config.metadata?.run_id ?? config.runId;
     if (!runId)
         throw new Error("run_id is required");
-    const metadata = {
-        ...config.metadata,
-        tags: config.tags,
-        name: config.runName,
-        run_id: runId,
-    };
-    const handlePush = (message, options) => {
+    function handlePush(message, options) {
         const evt = {
             type: "ui",
             id: message?.id ?? uuidv4(),
             name: message?.name,
             props: message?.props,
             metadata: {
-                ...metadata,
+                merge: options?.merge || undefined,
+                run_id: runId,
+                tags: config.tags,
+                name: config.runName,
                 ...message?.metadata,
                 ...(options?.message ? { message_id: options.message.id } : null),
             },
@@ -35,7 +32,7 @@ export const typedUi = (config, options) => {
         config.writer?.(evt);
         config.configurable?.__pregel_send?.([[stateKey, evt]]);
         return evt;
-    };
+    }
     const handleDelete = (id) => {
         const evt = { type: "remove-ui", id };
         items.push(evt);

package/dist/react-ui/types.cjs

@@ -1,6 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.uiMessageReducer = void 0;
+exports.uiMessageReducer = exports.isRemoveUIMessage = exports.isUIMessage = void 0;
+function isUIMessage(message) {
+    if (typeof message !== "object" || message == null)
+        return false;
+    if (!("type" in message))
+        return false;
+    return message.type === "ui";
+}
+exports.isUIMessage = isUIMessage;
+function isRemoveUIMessage(message) {
+    if (typeof message !== "object" || message == null)
+        return false;
+    if (!("type" in message))
+        return false;
+    return message.type === "remove-ui";
+}
+exports.isRemoveUIMessage = isRemoveUIMessage;
 function uiMessageReducer(state, update) {
     const events = Array.isArray(update) ? update : [update];
     let newState = state.slice();
@@ -11,7 +27,9 @@ function uiMessageReducer(state, update) {
         }
         const index = state.findIndex((ui) => ui.id === event.id);
         if (index !== -1) {
-            newState[index] = event;
+            newState[index] = event.metadata.merge
+                ? { ...event, props: { ...state[index].props, ...event.props } }
+                : event;
         }
         else {
             newState.push(event);

package/dist/react-ui/types.d.ts

@@ -1,10 +1,13 @@
-export interface UIMessage {
+export interface UIMessage<TName extends string = string, TProps extends Record<string, unknown> = Record<string, unknown>> {
     type: "ui";
     id: string;
-    name: string;
-    props: Record<string, unknown>;
+    name: TName;
+    props: TProps;
     metadata: {
-        run_id: string;
+        merge?: boolean;
+        run_id?: string;
+        name?: string;
+        tags?: string[];
         message_id?: string;
         [key: string]: unknown;
     };
@@ -13,4 +16,6 @@ export interface RemoveUIMessage {
     type: "remove-ui";
     id: string;
 }
-export declare function uiMessageReducer(state: UIMessage[], update: UIMessage | RemoveUIMessage | (UIMessage | RemoveUIMessage)[]): UIMessage[];
+export declare function isUIMessage(message: unknown): message is UIMessage;
+export declare function isRemoveUIMessage(message: unknown): message is RemoveUIMessage;
+export declare function uiMessageReducer(state: UIMessage[], update: UIMessage | RemoveUIMessage | (UIMessage | RemoveUIMessage)[]): UIMessage<string, Record<string, unknown>>[];

package/dist/react-ui/types.js

@@ -1,3 +1,17 @@
+export function isUIMessage(message) {
+    if (typeof message !== "object" || message == null)
+        return false;
+    if (!("type" in message))
+        return false;
+    return message.type === "ui";
+}
+export function isRemoveUIMessage(message) {
+    if (typeof message !== "object" || message == null)
+        return false;
+    if (!("type" in message))
+        return false;
+    return message.type === "remove-ui";
+}
 export function uiMessageReducer(state, update) {
     const events = Array.isArray(update) ? update : [update];
     let newState = state.slice();
@@ -8,7 +22,9 @@ export function uiMessageReducer(state, update) {
         }
         const index = state.findIndex((ui) => ui.id === event.id);
         if (index !== -1) {
-            newState[index] = event;
+            newState[index] = event.metadata.merge
+                ? { ...event, props: { ...state[index].props, ...event.props } }
+                : event;
         }
         else {
             newState.push(event);

package/dist/types.stream.d.ts

@@ -120,7 +120,15 @@ export type SubgraphDebugStreamEvent = AsSubgraph<DebugStreamEvent>;
  */
 export type EventsStreamEvent = {
     event: "events";
-    data: unknown;
+    data: {
+        event: `on_${"chat_model" | "llm" | "chain" | "tool" | "retriever" | "prompt"}_${"start" | "stream" | "end"}` | (string & {});
+        name: string;
+        tags: string[];
+        run_id: string;
+        metadata: Record<string, unknown>;
+        parent_ids: string[];
+        data: unknown;
+    };
 };
 /** @internal */
 export type SubgraphEventsStreamEvent = AsSubgraph<EventsStreamEvent>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@langchain/langgraph-sdk",
-  "version": "0.0.70",
+  "version": "0.0.72",
   "description": "Client library for interacting with the LangGraph API",
   "type": "module",
   "packageManager": "yarn@1.22.19",