@langchain/langgraph-sdk 0.0.102 → 0.0.104

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @langchain/langgraph-sdk
 
+## 0.0.104
+
+### Patch Changes
+
+- af9ec5a: feat(sdk): add `isThreadLoading` option to `useStream`, handle thread error fetching
+- 8e1ec9e: feat(sdk): add Context API support for useStream
+- f43e48c: fix(sdk): handle subgraph custom events in stream processing of useStream
+
+## 0.0.103
+
+### Patch Changes
+
+- f1bcec7: Add support for context API
+
 ## 0.0.102
 
 ### Patch Changes

package/dist/auth/types.d.ts

@@ -16,6 +16,7 @@ interface AssistantCreate {
     assistant_id?: Maybe<string>;
     metadata?: Maybe<Record<string, unknown>>;
     config?: Maybe<AssistantConfig>;
+    context?: Maybe<unknown>;
     if_exists?: Maybe<"raise" | "do_nothing">;
     name?: Maybe<string>;
     graph_id: string;
@@ -34,6 +35,7 @@ interface AssistantUpdate {
     assistant_id: string;
     metadata?: Maybe<Record<string, unknown>>;
     config?: Maybe<AssistantConfig>;
+    context?: Maybe<unknown>;
     graph_id?: Maybe<string>;
     name?: Maybe<string>;
     version?: Maybe<number>;

package/dist/client.cjs

@@ -235,6 +235,7 @@ class CronsClient extends BaseClient {
             schedule: payload?.schedule,
             input: payload?.input,
             config: payload?.config,
+            context: payload?.context,
             metadata: payload?.metadata,
             assistant_id: assistantId,
             interrupt_before: payload?.interruptBefore,
@@ -260,6 +261,7 @@ class CronsClient extends BaseClient {
             schedule: payload?.schedule,
             input: payload?.input,
             config: payload?.config,
+            context: payload?.context,
             metadata: payload?.metadata,
             assistant_id: assistantId,
             interrupt_before: payload?.interruptBefore,
@@ -358,6 +360,7 @@ class AssistantsClient extends BaseClient {
             json: {
                 graph_id: payload.graphId,
                 config: payload.config,
+                context: payload.context,
                 metadata: payload.metadata,
                 assistant_id: payload.assistantId,
                 if_exists: payload.ifExists,
@@ -378,6 +381,7 @@ class AssistantsClient extends BaseClient {
             json: {
                 graph_id: payload.graphId,
                 config: payload.config,
+                context: payload.context,
                 metadata: payload.metadata,
                 name: payload.name,
                 description: payload.description,
@@ -624,6 +628,7 @@ class RunsClient extends BaseClient {
             input: payload?.input,
             command: payload?.command,
             config: payload?.config,
+            context: payload?.context,
             metadata: payload?.metadata,
             stream_mode: payload?.streamMode,
             stream_subgraphs: payload?.streamSubgraphs,
@@ -671,6 +676,7 @@ class RunsClient extends BaseClient {
             input: payload?.input,
             command: payload?.command,
             config: payload?.config,
+            context: payload?.context,
             metadata: payload?.metadata,
             stream_mode: payload?.streamMode,
             stream_subgraphs: payload?.streamSubgraphs,
@@ -733,6 +739,7 @@ class RunsClient extends BaseClient {
             input: payload?.input,
             command: payload?.command,
             config: payload?.config,
+            context: payload?.context,
             metadata: payload?.metadata,
             assistant_id: assistantId,
             interrupt_before: payload?.interruptBefore,

package/dist/client.d.ts

@@ -129,6 +129,7 @@ export declare class AssistantsClient extends BaseClient {
     create(payload: {
         graphId: string;
         config?: Config;
+        context?: unknown;
         metadata?: Metadata;
         assistantId?: string;
         ifExists?: OnConflictBehavior;
@@ -144,6 +145,7 @@ export declare class AssistantsClient extends BaseClient {
     update(assistantId: string, payload: {
         graphId?: string;
         config?: Config;
+        context?: unknown;
         metadata?: Metadata;
         name?: string;
         description?: string;

package/dist/client.js

@@ -230,6 +230,7 @@ export class CronsClient extends BaseClient {
             schedule: payload?.schedule,
             input: payload?.input,
             config: payload?.config,
+            context: payload?.context,
             metadata: payload?.metadata,
             assistant_id: assistantId,
             interrupt_before: payload?.interruptBefore,
@@ -255,6 +256,7 @@ export class CronsClient extends BaseClient {
             schedule: payload?.schedule,
             input: payload?.input,
             config: payload?.config,
+            context: payload?.context,
             metadata: payload?.metadata,
             assistant_id: assistantId,
             interrupt_before: payload?.interruptBefore,
@@ -352,6 +354,7 @@ export class AssistantsClient extends BaseClient {
             json: {
                 graph_id: payload.graphId,
                 config: payload.config,
+                context: payload.context,
                 metadata: payload.metadata,
                 assistant_id: payload.assistantId,
                 if_exists: payload.ifExists,
@@ -372,6 +375,7 @@ export class AssistantsClient extends BaseClient {
             json: {
                 graph_id: payload.graphId,
                 config: payload.config,
+                context: payload.context,
                 metadata: payload.metadata,
                 name: payload.name,
                 description: payload.description,
@@ -616,6 +620,7 @@ export class RunsClient extends BaseClient {
             input: payload?.input,
             command: payload?.command,
             config: payload?.config,
+            context: payload?.context,
             metadata: payload?.metadata,
             stream_mode: payload?.streamMode,
             stream_subgraphs: payload?.streamSubgraphs,
@@ -663,6 +668,7 @@ export class RunsClient extends BaseClient {
             input: payload?.input,
             command: payload?.command,
             config: payload?.config,
+            context: payload?.context,
             metadata: payload?.metadata,
             stream_mode: payload?.streamMode,
             stream_subgraphs: payload?.streamSubgraphs,
@@ -725,6 +731,7 @@ export class RunsClient extends BaseClient {
             input: payload?.input,
             command: payload?.command,
             config: payload?.config,
+            context: payload?.context,
             metadata: payload?.metadata,
             assistant_id: assistantId,
             interrupt_before: payload?.interruptBefore,

package/dist/react/stream.cjs

@@ -198,25 +198,38 @@ function fetchHistory(client, threadId, options) {
     const limit = typeof options?.limit === "number" ? options.limit : 1000;
     return client.threads.getHistory(threadId, { limit });
 }
-function useThreadHistory(threadId, client, limit, clearCallbackRef, submittingRef) {
-    const [history, setHistory] = (0, react_1.useState)([]);
+function useThreadHistory(threadId, client, limit, clearCallbackRef, submittingRef, onErrorRef) {
+    const [history, setHistory] = (0, react_1.useState)(undefined);
+    const [isLoading, setIsLoading] = (0, react_1.useState)(false);
+    const [error, setError] = (0, react_1.useState)(undefined);
     const clientHash = (0, client_js_1.getClientConfigHash)(client);
     const clientRef = (0, react_1.useRef)(client);
     clientRef.current = client;
     const fetcher = (0, react_1.useCallback)((threadId) => {
         if (threadId != null) {
             const client = clientRef.current;
+            setIsLoading(true);
             return fetchHistory(client, threadId, {
                 limit,
-            }).then((history) => {
+            })
+                .then((history) => {
                 setHistory(history);
                 return history;
+            }, (error) => {
+                setError(error);
+                onErrorRef.current?.(error);
+                return Promise.reject(error);
+            })
+                .finally(() => {
+                setIsLoading(false);
             });
         }
-        setHistory([]);
+        setHistory(undefined);
+        setError(undefined);
+        setIsLoading(false);
         clearCallbackRef.current?.();
         return Promise.resolve([]);
-    }, [clearCallbackRef, limit]);
+    }, [clearCallbackRef, onErrorRef, limit]);
     (0, react_1.useEffect)(() => {
         if (submittingRef.current)
             return;
@@ -224,6 +237,8 @@ function useThreadHistory(threadId, client, limit, clearCallbackRef, submittingR
     }, [fetcher, clientHash, limit, submittingRef, threadId]);
     return {
         data: history,
+        isLoading,
+        error,
         mutate: (mutateId) => fetcher(mutateId ?? threadId),
     };
 }
@@ -346,20 +361,22 @@ function useStream(options) {
         setStreamValues(null);
         messageManagerRef.current.clear();
     };
+    const onErrorRef = (0, react_1.useRef)(undefined);
+    onErrorRef.current = options.onError;
     const historyLimit = typeof fetchStateHistory === "object" && fetchStateHistory != null
         ? fetchStateHistory.limit ?? true
         : fetchStateHistory ?? true;
-    const history = useThreadHistory(threadId, client, historyLimit, clearCallbackRef, submittingRef);
+    const history = useThreadHistory(threadId, client, historyLimit, clearCallbackRef, submittingRef, onErrorRef);
     const getMessages = (0, react_1.useMemo)(() => {
         return (value) => Array.isArray(value[messagesKey])
             ? value[messagesKey]
             : [];
     }, [messagesKey]);
-    const { rootSequence, paths } = getBranchSequence(history.data);
+    const { rootSequence, paths } = getBranchSequence(history.data ?? []);
     const { history: flatHistory, branchByCheckpoint } = getBranchView(rootSequence, paths, branch);
     const threadHead = flatHistory.at(-1);
     const historyValues = threadHead?.values ?? options.initialValues ?? {};
-    const historyError = (() => {
+    const historyValueError = (() => {
         const error = threadHead?.tasks?.at(-1)?.error;
         if (error == null)
             return undefined;
@@ -379,10 +396,10 @@ function useStream(options) {
         const alreadyShown = new Set();
         return getMessages(historyValues).map((message, idx) => {
             const messageId = message.id ?? idx;
-            const firstSeenIdx = findLastIndex(history.data, (state) => getMessages(state.values)
+            const firstSeenIdx = findLastIndex(history.data ?? [], (state) => getMessages(state.values)
                 .map((m, idx) => m.id ?? idx)
                 .includes(messageId));
-            const firstSeen = history.data[firstSeenIdx];
+            const firstSeen = history.data?.[firstSeenIdx];
             const checkpointId = firstSeen?.checkpoint?.checkpoint_id;
             let branch = firstSeen && checkpointId != null
                 ? branchByCheckpoint[checkpointId]
@@ -433,7 +450,10 @@ function useStream(options) {
                 }
                 if (event === "updates")
                     options.onUpdateEvent?.(data);
-                if (event === "custom")
+                if (event === "custom" ||
+                    // if `streamSubgraphs: true`, then we also want
+                    // to also receive custom events from subgraphs
+                    event.startsWith("custom|"))
                     options.onCustomEvent?.(data, {
                         mutate: getMutateFn("stream", historyValues),
                     });
@@ -553,6 +573,8 @@ function useStream(options) {
                 onThreadId(thread.thread_id);
                 usableThreadId = thread.thread_id;
             }
+            if (!usableThreadId)
+                throw new Error("Failed to obtain valid thread ID.");
             const streamMode = unique([
                 ...(submitOptions?.streamMode ?? []),
                 ...trackStreamModeRef.current,
@@ -569,6 +591,7 @@ function useStream(options) {
             const stream = client.runs.stream(usableThreadId, assistantId, {
                 input: values,
                 config: submitOptions?.config,
+                context: submitOptions?.context,
                 command: submitOptions?.command,
                 interruptBefore: submitOptions?.interruptBefore,
                 interruptAfter: submitOptions?.interruptAfter,
@@ -631,7 +654,7 @@ function useStream(options) {
             void joinStreamRef.current?.(reconnectKey.runId);
         }
     }, [reconnectKey]);
-    const error = streamError ?? historyError;
+    const error = streamError ?? historyValueError ?? history.error;
     const values = streamValues ?? historyValues;
     return {
         get values() {
@@ -648,6 +671,7 @@ function useStream(options) {
         branch,
         setBranch,
         history: flatHistory,
+        isThreadLoading: history.isLoading && history.data == null,
         get experimental_branchTree() {
             if (historyLimit === false) {
                 throw new Error("`experimental_branchTree` is not available when `fetchStateHistory` is set to `false`");

package/dist/react/stream.d.ts

@@ -203,6 +203,10 @@ export interface UseStream<StateType extends Record<string, unknown> = Record<st
      * Whether the stream is currently running.
      */
     isLoading: boolean;
+    /**
+     * Whether the thread is currently being loaded.
+     */
+    isThreadLoading: boolean;
     /**
      * Stops the stream.
      */
@@ -264,8 +268,9 @@ export interface UseStream<StateType extends Record<string, unknown> = Record<st
 type ConfigWithConfigurable<ConfigurableType extends Record<string, unknown>> = Config & {
     configurable?: ConfigurableType;
 };
-interface SubmitOptions<StateType extends Record<string, unknown> = Record<string, unknown>, ConfigurableType extends Record<string, unknown> = Record<string, unknown>> {
-    config?: ConfigWithConfigurable<ConfigurableType>;
+interface SubmitOptions<StateType extends Record<string, unknown> = Record<string, unknown>, ContextType extends Record<string, unknown> = Record<string, unknown>> {
+    config?: ConfigWithConfigurable<ContextType>;
+    context?: ContextType;
     checkpoint?: Omit<Checkpoint, "thread_id"> | null;
     command?: Command;
     interruptBefore?: "*" | string[];

package/dist/react/stream.js

@@ -194,25 +194,38 @@ function fetchHistory(client, threadId, options) {
     const limit = typeof options?.limit === "number" ? options.limit : 1000;
     return client.threads.getHistory(threadId, { limit });
 }
-function useThreadHistory(threadId, client, limit, clearCallbackRef, submittingRef) {
-    const [history, setHistory] = useState([]);
+function useThreadHistory(threadId, client, limit, clearCallbackRef, submittingRef, onErrorRef) {
+    const [history, setHistory] = useState(undefined);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(undefined);
     const clientHash = getClientConfigHash(client);
     const clientRef = useRef(client);
     clientRef.current = client;
     const fetcher = useCallback((threadId) => {
         if (threadId != null) {
             const client = clientRef.current;
+            setIsLoading(true);
             return fetchHistory(client, threadId, {
                 limit,
-            }).then((history) => {
+            })
+                .then((history) => {
                 setHistory(history);
                 return history;
+            }, (error) => {
+                setError(error);
+                onErrorRef.current?.(error);
+                return Promise.reject(error);
+            })
+                .finally(() => {
+                setIsLoading(false);
             });
         }
-        setHistory([]);
+        setHistory(undefined);
+        setError(undefined);
+        setIsLoading(false);
         clearCallbackRef.current?.();
         return Promise.resolve([]);
-    }, [clearCallbackRef, limit]);
+    }, [clearCallbackRef, onErrorRef, limit]);
     useEffect(() => {
         if (submittingRef.current)
             return;
@@ -220,6 +233,8 @@ function useThreadHistory(threadId, client, limit, clearCallbackRef, submittingR
     }, [fetcher, clientHash, limit, submittingRef, threadId]);
     return {
         data: history,
+        isLoading,
+        error,
         mutate: (mutateId) => fetcher(mutateId ?? threadId),
     };
 }
@@ -342,20 +357,22 @@ export function useStream(options) {
         setStreamValues(null);
         messageManagerRef.current.clear();
     };
+    const onErrorRef = useRef(undefined);
+    onErrorRef.current = options.onError;
     const historyLimit = typeof fetchStateHistory === "object" && fetchStateHistory != null
         ? fetchStateHistory.limit ?? true
         : fetchStateHistory ?? true;
-    const history = useThreadHistory(threadId, client, historyLimit, clearCallbackRef, submittingRef);
+    const history = useThreadHistory(threadId, client, historyLimit, clearCallbackRef, submittingRef, onErrorRef);
     const getMessages = useMemo(() => {
         return (value) => Array.isArray(value[messagesKey])
             ? value[messagesKey]
             : [];
     }, [messagesKey]);
-    const { rootSequence, paths } = getBranchSequence(history.data);
+    const { rootSequence, paths } = getBranchSequence(history.data ?? []);
     const { history: flatHistory, branchByCheckpoint } = getBranchView(rootSequence, paths, branch);
     const threadHead = flatHistory.at(-1);
     const historyValues = threadHead?.values ?? options.initialValues ?? {};
-    const historyError = (() => {
+    const historyValueError = (() => {
         const error = threadHead?.tasks?.at(-1)?.error;
         if (error == null)
             return undefined;
@@ -375,10 +392,10 @@ export function useStream(options) {
         const alreadyShown = new Set();
         return getMessages(historyValues).map((message, idx) => {
             const messageId = message.id ?? idx;
-            const firstSeenIdx = findLastIndex(history.data, (state) => getMessages(state.values)
+            const firstSeenIdx = findLastIndex(history.data ?? [], (state) => getMessages(state.values)
                 .map((m, idx) => m.id ?? idx)
                 .includes(messageId));
-            const firstSeen = history.data[firstSeenIdx];
+            const firstSeen = history.data?.[firstSeenIdx];
             const checkpointId = firstSeen?.checkpoint?.checkpoint_id;
             let branch = firstSeen && checkpointId != null
                 ? branchByCheckpoint[checkpointId]
@@ -429,7 +446,10 @@ export function useStream(options) {
                 }
                 if (event === "updates")
                     options.onUpdateEvent?.(data);
-                if (event === "custom")
+                if (event === "custom" ||
+                    // if `streamSubgraphs: true`, then we also want
+                    // to also receive custom events from subgraphs
+                    event.startsWith("custom|"))
                     options.onCustomEvent?.(data, {
                         mutate: getMutateFn("stream", historyValues),
                     });
@@ -549,6 +569,8 @@ export function useStream(options) {
                 onThreadId(thread.thread_id);
                 usableThreadId = thread.thread_id;
             }
+            if (!usableThreadId)
+                throw new Error("Failed to obtain valid thread ID.");
             const streamMode = unique([
                 ...(submitOptions?.streamMode ?? []),
                 ...trackStreamModeRef.current,
@@ -565,6 +587,7 @@ export function useStream(options) {
             const stream = client.runs.stream(usableThreadId, assistantId, {
                 input: values,
                 config: submitOptions?.config,
+                context: submitOptions?.context,
                 command: submitOptions?.command,
                 interruptBefore: submitOptions?.interruptBefore,
                 interruptAfter: submitOptions?.interruptAfter,
@@ -627,7 +650,7 @@ export function useStream(options) {
             void joinStreamRef.current?.(reconnectKey.runId);
         }
     }, [reconnectKey]);
-    const error = streamError ?? historyError;
+    const error = streamError ?? historyValueError ?? history.error;
     const values = streamValues ?? historyValues;
     return {
         get values() {
@@ -644,6 +667,7 @@ export function useStream(options) {
         branch,
         setBranch,
         history: flatHistory,
+        isThreadLoading: history.isLoading && history.data == null,
         get experimental_branchTree() {
             if (historyLimit === false) {
                 throw new Error("`experimental_branchTree` is not available when `fetchStateHistory` is set to `false`");

package/dist/schema.d.ts

@@ -55,6 +55,11 @@ export interface GraphSchema {
      * Missing if unable to generate JSON schema from graph.
      */
     config_schema?: JSONSchema7 | null | undefined;
+    /**
+     * The schema for the graph context.
+     * Missing if unable to generate JSON schema from graph.
+     */
+    context_schema?: JSONSchema7 | null | undefined;
 }
 export type Subgraphs = Record<string, GraphSchema>;
 export type Metadata = Optional<{

package/dist/types.d.ts

@@ -39,6 +39,11 @@ export interface RunsInvokePayload {
      * Additional configuration for the run.
      */
     config?: Config;
+    /**
+     * Static context to add to the assistant.
+     * @remarks Added in LangGraph.js 0.4
+     */
+    context?: unknown;
     /**
      * Checkpoint ID for when creating a new run.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@langchain/langgraph-sdk",
-  "version": "0.0.102",
+  "version": "0.0.104",
   "description": "Client library for interacting with the LangGraph API",
   "type": "module",
   "scripts": {