@langchain/langgraph-sdk 0.0.105 → 0.0.109

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @langchain/langgraph-sdk
 
+## 0.0.109
+
+### Patch Changes
+
+- e8b4540: Add support for select statements in the search endpoints
+- 9c57526: fix(sdk): expose subgraph events in useStream callbacks
+
+## 0.0.107
+
+### Patch Changes
+
+- 72386a4: feat(sdk): expose stream metadata from messages via `getMessagesMetadata`
+- 3ee5c20: fix(sdk): avoid setting `messages-tuple` if only `getMessagesMetadata` is requested.
+
+## 0.0.106
+
+### Patch Changes
+
+- feat(sdk): allow setting `checkpoint: null` when submitting a run via useStream
+
 ## 0.0.105
 
 ### Patch Changes

package/dist/client.cjs

@@ -300,6 +300,7 @@ class CronsClient extends BaseClient {
                 offset: query?.offset ?? 0,
                 sort_by: query?.sortBy ?? undefined,
                 sort_order: query?.sortOrder ?? undefined,
+                select: query?.select ?? undefined,
             },
         });
     }
@@ -413,6 +414,7 @@ class AssistantsClient extends BaseClient {
                 offset: query?.offset ?? 0,
                 sort_by: query?.sortBy ?? undefined,
                 sort_order: query?.sortOrder ?? undefined,
+                select: query?.select ?? undefined,
             },
         });
     }
@@ -532,6 +534,7 @@ class ThreadsClient extends BaseClient {
                 status: query?.status,
                 sort_by: query?.sortBy,
                 sort_order: query?.sortOrder,
+                select: query?.select ?? undefined,
             },
         });
     }
@@ -795,6 +798,7 @@ class RunsClient extends BaseClient {
                 limit: options?.limit ?? 10,
                 offset: options?.offset ?? 0,
                 status: options?.status ?? undefined,
+                select: options?.select ?? undefined,
             },
         });
     }

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { Assistant, AssistantGraph, AssistantSortBy, AssistantVersion, CancelAction, Checkpoint, Config, Cron, CronCreateForThreadResponse, CronCreateResponse, CronSortBy, DefaultValues, GraphSchema, Item, ListNamespaceResponse, Metadata, Run, RunStatus, SearchItemsResponse, SortOrder, Subgraphs, Thread, ThreadSortBy, ThreadState, ThreadStatus } from "./schema.js";
+import { Assistant, AssistantGraph, AssistantSortBy, AssistantSelectField, AssistantVersion, CancelAction, Checkpoint, Config, Cron, CronSelectField, CronCreateForThreadResponse, CronCreateResponse, CronSortBy, DefaultValues, GraphSchema, Item, ListNamespaceResponse, Metadata, Run, RunSelectField, RunStatus, SearchItemsResponse, SortOrder, Subgraphs, Thread, ThreadSelectField, ThreadSortBy, ThreadState, ThreadStatus } from "./schema.js";
 import type { Command, CronsCreatePayload, OnConflictBehavior, RunsCreatePayload, RunsStreamPayload, RunsWaitPayload, StreamEvent } from "./types.js";
 import type { StreamMode, TypedAsyncGenerator } from "./types.stream.js";
 import { AsyncCaller, AsyncCallerParams } from "./utils/async_caller.js";
@@ -85,6 +85,7 @@ export declare class CronsClient extends BaseClient {
         offset?: number;
         sortBy?: CronSortBy;
         sortOrder?: SortOrder;
+        select?: CronSelectField[];
     }): Promise<Cron[]>;
 }
 export declare class AssistantsClient extends BaseClient {
@@ -168,6 +169,7 @@ export declare class AssistantsClient extends BaseClient {
         offset?: number;
         sortBy?: AssistantSortBy;
         sortOrder?: SortOrder;
+        select?: AssistantSelectField[];
     }): Promise<Assistant[]>;
     /**
      * List all versions of an assistant.
@@ -295,6 +297,7 @@ export declare class ThreadsClient<TStateType = DefaultValues, TUpdateType = TSt
          * Must be one of 'asc' or 'desc'.
          */
         sortOrder?: SortOrder;
+        select?: ThreadSelectField[];
     }): Promise<Thread<ValuesType>[]>;
     /**
      * Get state for a thread.
@@ -383,6 +386,7 @@ export declare class RunsClient<TStateType = DefaultValues, TUpdateType = TState
          * Status of the run to filter by.
          */
         status?: RunStatus;
+        select?: RunSelectField[];
     }): Promise<Run[]>;
     /**
      * Get a run by ID.

package/dist/client.js

@@ -295,6 +295,7 @@ export class CronsClient extends BaseClient {
                 offset: query?.offset ?? 0,
                 sort_by: query?.sortBy ?? undefined,
                 sort_order: query?.sortOrder ?? undefined,
+                select: query?.select ?? undefined,
             },
         });
     }
@@ -407,6 +408,7 @@ export class AssistantsClient extends BaseClient {
                 offset: query?.offset ?? 0,
                 sort_by: query?.sortBy ?? undefined,
                 sort_order: query?.sortOrder ?? undefined,
+                select: query?.select ?? undefined,
             },
         });
     }
@@ -525,6 +527,7 @@ export class ThreadsClient extends BaseClient {
                 status: query?.status,
                 sort_by: query?.sortBy,
                 sort_order: query?.sortOrder,
+                select: query?.select ?? undefined,
             },
         });
     }
@@ -787,6 +790,7 @@ export class RunsClient extends BaseClient {
                 limit: options?.limit ?? 10,
                 offset: options?.offset ?? 0,
                 status: options?.status ?? undefined,
+                select: options?.select ?? undefined,
             },
         });
     }

package/dist/react/stream.cjs

@@ -34,7 +34,7 @@ class MessageTupleManager {
         });
         this.chunks = {};
     }
-    add(serialized) {
+    add(serialized, metadata) {
         // TODO: this is sometimes sent from the API
         // figure out how to prevent this or move this to LC.js
         if (serialized.type.endsWith("MessageChunk")) {
@@ -51,6 +51,7 @@ class MessageTupleManager {
             return null;
         }
         this.chunks[id] ??= {};
+        this.chunks[id].metadata = metadata ?? this.chunks[id].metadata;
         if (chunk) {
             const prev = this.chunks[id].chunk;
             this.chunks[id].chunk =
@@ -67,7 +68,8 @@ class MessageTupleManager {
     get(id, defaultIndex) {
         if (this.chunks[id] == null)
             return null;
-        this.chunks[id].index ??= defaultIndex;
+        if (defaultIndex != null)
+            this.chunks[id].index ??= defaultIndex;
         return this.chunks[id];
     }
 }
@@ -282,6 +284,9 @@ function useStreamValuesState() {
     return [values?.[0] ?? null, setStreamValues, mutate];
 }
 function useStream(options) {
+    const matchEventType = (expected, actual, _data) => {
+        return expected === actual || actual.startsWith(`${expected}|`);
+    };
     let { messagesKey } = options;
     const { assistantId, fetchStateHistory } = options;
     const { onCreated, onError, onFinish } = options;
@@ -396,6 +401,9 @@ function useStream(options) {
         const alreadyShown = new Set();
         return getMessages(historyValues).map((message, idx) => {
             const messageId = message.id ?? idx;
+            const streamMetadata = message.id != null
+                ? messageManagerRef.current.get(message.id)?.metadata ?? undefined
+                : undefined;
             const firstSeenIdx = findLastIndex(history.data ?? [], (state) => getMessages(state.values)
                 .map((m, idx) => m.id ?? idx)
                 .includes(messageId));
@@ -418,6 +426,7 @@ function useStream(options) {
                 firstSeenState: firstSeen,
                 branch: branch?.branch,
                 branchOptions: branch?.branchOptions,
+                streamMetadata,
             };
         });
     })();
@@ -448,38 +457,39 @@ function useStream(options) {
                     streamError = new StreamError(data);
                     break;
                 }
-                if (event === "updates")
-                    options.onUpdateEvent?.(data);
-                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),
-                    });
+                const namespace = event.includes("|")
+                    ? event.split("|").slice(1)
+                    : undefined;
+                const mutate = getMutateFn("stream", historyValues);
                 if (event === "metadata")
                     options.onMetadataEvent?.(data);
                 if (event === "events")
                     options.onLangChainEvent?.(data);
-                if (event === "debug")
-                    options.onDebugEvent?.(data);
-                if (event === "checkpoints")
-                    options.onCheckpointEvent?.(data);
-                if (event === "tasks")
-                    options.onTaskEvent?.(data);
+                if (matchEventType("updates", event, data)) {
+                    options.onUpdateEvent?.(data, { namespace, mutate });
+                }
+                if (matchEventType("custom", event, data)) {
+                    options.onCustomEvent?.(data, { namespace, mutate });
+                }
+                if (matchEventType("checkpoints", event, data)) {
+                    options.onCheckpointEvent?.(data, { namespace });
+                }
+                if (matchEventType("tasks", event, data)) {
+                    options.onTaskEvent?.(data, { namespace });
+                }
+                if (matchEventType("debug", event, data)) {
+                    options.onDebugEvent?.(data, { namespace });
+                }
                 if (event === "values") {
-                    if ("__interrupt__" in data) {
-                        // don't update values on interrupt values event
+                    // don't update values on interrupt values event
+                    if ("__interrupt__" in data)
                         continue;
-                    }
                     setStreamValues(data);
                 }
-                if (event === "messages" ||
-                    // if `streamSubgraphs: true`, then we also want
-                    // to also receive messages from subgraphs
-                    event.startsWith("messages|")) {
-                    const [serialized] = data;
-                    const messageId = messageManagerRef.current.add(serialized);
+                // Consume subgraph messages as well
+                if (matchEventType("messages", event, data)) {
+                    const [serialized, metadata] = data;
+                    const messageId = messageManagerRef.current.add(serialized, metadata);
                     if (!messageId) {
                         console.warn("Failed to add message to manager, no message ID found");
                         continue;
@@ -580,7 +590,11 @@ function useStream(options) {
                 ...trackStreamModeRef.current,
                 ...callbackStreamMode,
             ]);
-            const checkpoint = submitOptions?.checkpoint ?? threadHead?.checkpoint ?? undefined;
+            let checkpoint = submitOptions?.checkpoint ?? threadHead?.checkpoint ?? undefined;
+            // Avoid specifying a checkpoint if user explicitly set it to null
+            if (submitOptions?.checkpoint === null) {
+                checkpoint = undefined;
+            }
             // eslint-disable-next-line @typescript-eslint/ban-ts-comment
             // @ts-expect-error
             if (checkpoint != null)
@@ -698,7 +712,7 @@ function useStream(options) {
             return getMessages(values);
         },
         getMessagesMetadata(message, index) {
-            trackStreamMode("messages-tuple", "values");
+            trackStreamMode("values");
             return messageMetadata?.find((m) => m.messageId === (message.id ?? index));
         },
     };

package/dist/react/stream.d.ts

@@ -34,6 +34,11 @@ export type MessageMetadata<StateType extends Record<string, unknown>> = {
      * This is useful for displaying branching controls.
      */
     branchOptions: string[] | undefined;
+    /**
+     * Metadata sent alongside the message during run streaming.
+     * @remarks This metadata only exists temporarily in browser memory during streaming and is not persisted after completion.
+     */
+    streamMetadata: Record<string, unknown> | undefined;
 };
 type BagTemplate = {
     ConfigurableType?: Record<string, unknown>;
@@ -104,11 +109,15 @@ export interface UseStreamOptions<StateType extends Record<string, unknown> = Re
     /**
      * Callback that is called when an update event is received.
      */
-    onUpdateEvent?: (data: UpdatesStreamEvent<GetUpdateType<Bag, StateType>>["data"]) => void;
+    onUpdateEvent?: (data: UpdatesStreamEvent<GetUpdateType<Bag, StateType>>["data"], options: {
+        namespace: string[] | undefined;
+        mutate: (update: Partial<StateType> | ((prev: StateType) => Partial<StateType>)) => void;
+    }) => void;
     /**
      * Callback that is called when a custom event is received.
      */
     onCustomEvent?: (data: CustomStreamEvent<GetCustomEventType<Bag>>["data"], options: {
+        namespace: string[] | undefined;
         mutate: (update: Partial<StateType> | ((prev: StateType) => Partial<StateType>)) => void;
     }) => void;
     /**
@@ -124,15 +133,21 @@ export interface UseStreamOptions<StateType extends Record<string, unknown> = Re
      * Callback that is called when a debug event is received.
      * @internal This API is experimental and subject to change.
      */
-    onDebugEvent?: (data: DebugStreamEvent["data"]) => void;
+    onDebugEvent?: (data: DebugStreamEvent["data"], options: {
+        namespace: string[] | undefined;
+    }) => void;
     /**
      * Callback that is called when a checkpoints event is received.
      */
-    onCheckpointEvent?: (data: CheckpointsStreamEvent<StateType>["data"]) => void;
+    onCheckpointEvent?: (data: CheckpointsStreamEvent<StateType>["data"], options: {
+        namespace: string[] | undefined;
+    }) => void;
     /**
      * Callback that is called when a tasks event is received.
      */
-    onTaskEvent?: (data: TasksStreamEvent<StateType, GetUpdateType<Bag, StateType>>["data"]) => void;
+    onTaskEvent?: (data: TasksStreamEvent<StateType, GetUpdateType<Bag, StateType>>["data"], options: {
+        namespace: string[] | undefined;
+    }) => void;
     /**
      * Callback that is called when the stream is stopped by the user.
      * Provides a mutate function to update the stream state immediately

package/dist/react/stream.js

@@ -30,7 +30,7 @@ class MessageTupleManager {
         });
         this.chunks = {};
     }
-    add(serialized) {
+    add(serialized, metadata) {
         // TODO: this is sometimes sent from the API
         // figure out how to prevent this or move this to LC.js
         if (serialized.type.endsWith("MessageChunk")) {
@@ -47,6 +47,7 @@ class MessageTupleManager {
             return null;
         }
         this.chunks[id] ??= {};
+        this.chunks[id].metadata = metadata ?? this.chunks[id].metadata;
         if (chunk) {
             const prev = this.chunks[id].chunk;
             this.chunks[id].chunk =
@@ -63,7 +64,8 @@ class MessageTupleManager {
     get(id, defaultIndex) {
         if (this.chunks[id] == null)
             return null;
-        this.chunks[id].index ??= defaultIndex;
+        if (defaultIndex != null)
+            this.chunks[id].index ??= defaultIndex;
         return this.chunks[id];
     }
 }
@@ -278,6 +280,9 @@ function useStreamValuesState() {
     return [values?.[0] ?? null, setStreamValues, mutate];
 }
 export function useStream(options) {
+    const matchEventType = (expected, actual, _data) => {
+        return expected === actual || actual.startsWith(`${expected}|`);
+    };
     let { messagesKey } = options;
     const { assistantId, fetchStateHistory } = options;
     const { onCreated, onError, onFinish } = options;
@@ -392,6 +397,9 @@ export function useStream(options) {
         const alreadyShown = new Set();
         return getMessages(historyValues).map((message, idx) => {
             const messageId = message.id ?? idx;
+            const streamMetadata = message.id != null
+                ? messageManagerRef.current.get(message.id)?.metadata ?? undefined
+                : undefined;
             const firstSeenIdx = findLastIndex(history.data ?? [], (state) => getMessages(state.values)
                 .map((m, idx) => m.id ?? idx)
                 .includes(messageId));
@@ -414,6 +422,7 @@ export function useStream(options) {
                 firstSeenState: firstSeen,
                 branch: branch?.branch,
                 branchOptions: branch?.branchOptions,
+                streamMetadata,
             };
         });
     })();
@@ -444,38 +453,39 @@ export function useStream(options) {
                     streamError = new StreamError(data);
                     break;
                 }
-                if (event === "updates")
-                    options.onUpdateEvent?.(data);
-                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),
-                    });
+                const namespace = event.includes("|")
+                    ? event.split("|").slice(1)
+                    : undefined;
+                const mutate = getMutateFn("stream", historyValues);
                 if (event === "metadata")
                     options.onMetadataEvent?.(data);
                 if (event === "events")
                     options.onLangChainEvent?.(data);
-                if (event === "debug")
-                    options.onDebugEvent?.(data);
-                if (event === "checkpoints")
-                    options.onCheckpointEvent?.(data);
-                if (event === "tasks")
-                    options.onTaskEvent?.(data);
+                if (matchEventType("updates", event, data)) {
+                    options.onUpdateEvent?.(data, { namespace, mutate });
+                }
+                if (matchEventType("custom", event, data)) {
+                    options.onCustomEvent?.(data, { namespace, mutate });
+                }
+                if (matchEventType("checkpoints", event, data)) {
+                    options.onCheckpointEvent?.(data, { namespace });
+                }
+                if (matchEventType("tasks", event, data)) {
+                    options.onTaskEvent?.(data, { namespace });
+                }
+                if (matchEventType("debug", event, data)) {
+                    options.onDebugEvent?.(data, { namespace });
+                }
                 if (event === "values") {
-                    if ("__interrupt__" in data) {
-                        // don't update values on interrupt values event
+                    // don't update values on interrupt values event
+                    if ("__interrupt__" in data)
                         continue;
-                    }
                     setStreamValues(data);
                 }
-                if (event === "messages" ||
-                    // if `streamSubgraphs: true`, then we also want
-                    // to also receive messages from subgraphs
-                    event.startsWith("messages|")) {
-                    const [serialized] = data;
-                    const messageId = messageManagerRef.current.add(serialized);
+                // Consume subgraph messages as well
+                if (matchEventType("messages", event, data)) {
+                    const [serialized, metadata] = data;
+                    const messageId = messageManagerRef.current.add(serialized, metadata);
                     if (!messageId) {
                         console.warn("Failed to add message to manager, no message ID found");
                         continue;
@@ -576,7 +586,11 @@ export function useStream(options) {
                 ...trackStreamModeRef.current,
                 ...callbackStreamMode,
             ]);
-            const checkpoint = submitOptions?.checkpoint ?? threadHead?.checkpoint ?? undefined;
+            let checkpoint = submitOptions?.checkpoint ?? threadHead?.checkpoint ?? undefined;
+            // Avoid specifying a checkpoint if user explicitly set it to null
+            if (submitOptions?.checkpoint === null) {
+                checkpoint = undefined;
+            }
             // eslint-disable-next-line @typescript-eslint/ban-ts-comment
             // @ts-expect-error
             if (checkpoint != null)
@@ -694,7 +708,7 @@ export function useStream(options) {
             return getMessages(values);
         },
         getMessagesMetadata(message, index) {
-            trackStreamMode("messages-tuple", "values");
+            trackStreamMode("values");
             return messageMetadata?.find((m) => m.messageId === (message.id ?? index));
         },
     };

package/dist/schema.d.ts

@@ -263,4 +263,8 @@ export type AssistantSortBy = "assistant_id" | "graph_id" | "name" | "created_at
 export type ThreadSortBy = "thread_id" | "status" | "created_at" | "updated_at";
 export type CronSortBy = "cron_id" | "assistant_id" | "thread_id" | "created_at" | "updated_at" | "next_run_date";
 export type SortOrder = "asc" | "desc";
+export type AssistantSelectField = "assistant_id" | "graph_id" | "name" | "description" | "config" | "context" | "created_at" | "updated_at" | "metadata" | "version";
+export type ThreadSelectField = "thread_id" | "created_at" | "updated_at" | "metadata" | "config" | "context" | "status" | "values" | "interrupts";
+export type RunSelectField = "run_id" | "thread_id" | "assistant_id" | "created_at" | "updated_at" | "status" | "metadata" | "kwargs" | "multitask_strategy";
+export type CronSelectField = "cron_id" | "assistant_id" | "thread_id" | "end_time" | "schedule" | "created_at" | "updated_at" | "user_id" | "payload" | "next_run_date" | "metadata" | "now";
 export {};

package/package.json

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