@langchain/langgraph-sdk 0.0.109 → 0.0.112

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @langchain/langgraph-sdk
 
+## 0.0.112
+
+### Patch Changes
+
+- a50e02e: feat(sdk): add thread streaming endpoint
+- 7e210a1: feat(sdk): add durability param to run methods
+- 5766b62: Fix `isThreadLoading: false` when initially mounting in useStream
+
+## 0.0.111
+
+### Patch Changes
+
+- b5f14d0: Add methods to connect with the /count endpoints
+
 ## 0.0.109
 
 ### Patch Changes

package/dist/client.cjs

@@ -244,6 +244,7 @@ class CronsClient extends BaseClient {
             multitask_strategy: payload?.multitaskStrategy,
             if_not_exists: payload?.ifNotExists,
             checkpoint_during: payload?.checkpointDuring,
+            durability: payload?.durability,
         };
         return this.fetch(`/threads/${threadId}/runs/crons`, {
             method: "POST",
@@ -270,6 +271,7 @@ class CronsClient extends BaseClient {
             multitask_strategy: payload?.multitaskStrategy,
             if_not_exists: payload?.ifNotExists,
             checkpoint_during: payload?.checkpointDuring,
+            durability: payload?.durability,
         };
         return this.fetch(`/runs/crons`, {
             method: "POST",
@@ -304,6 +306,22 @@ class CronsClient extends BaseClient {
             },
         });
     }
+    /**
+     * Count cron jobs matching filters.
+     *
+     * @param query.assistantId Assistant ID to filter by.
+     * @param query.threadId Thread ID to filter by.
+     * @returns Number of cron jobs matching the criteria.
+     */
+    async count(query) {
+        return this.fetch(`/runs/crons/count`, {
+            method: "POST",
+            json: {
+                assistant_id: query?.assistantId ?? undefined,
+                thread_id: query?.threadId ?? undefined,
+            },
+        });
+    }
 }
 exports.CronsClient = CronsClient;
 class AssistantsClient extends BaseClient {
@@ -418,6 +436,22 @@ class AssistantsClient extends BaseClient {
             },
         });
     }
+    /**
+     * Count assistants matching filters.
+     *
+     * @param query.metadata Metadata to filter by. Exact match for each key/value.
+     * @param query.graphId Optional graph id to filter by.
+     * @returns Number of assistants matching the criteria.
+     */
+    async count(query) {
+        return this.fetch(`/assistants/count`, {
+            method: "POST",
+            json: {
+                metadata: query?.metadata ?? undefined,
+                graph_id: query?.graphId ?? undefined,
+            },
+        });
+    }
     /**
      * List all versions of an assistant.
      *
@@ -538,6 +572,24 @@ class ThreadsClient extends BaseClient {
             },
         });
     }
+    /**
+     * Count threads matching filters.
+     *
+     * @param query.metadata Thread metadata to filter on.
+     * @param query.values State values to filter on.
+     * @param query.status Thread status to filter on.
+     * @returns Number of threads matching the criteria.
+     */
+    async count(query) {
+        return this.fetch(`/threads/count`, {
+            method: "POST",
+            json: {
+                metadata: query?.metadata ?? undefined,
+                values: query?.values ?? undefined,
+                status: query?.status ?? undefined,
+            },
+        });
+    }
     /**
      * Get state for a thread.
      *
@@ -616,6 +668,24 @@ class ThreadsClient extends BaseClient {
             },
         });
     }
+    async *joinStream(threadId, options
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ) {
+        const response = await this.asyncCaller.fetch(...this.prepareFetchOptions(`/threads/${threadId}/stream`, {
+            method: "GET",
+            headers: options?.lastEventId
+                ? { "Last-Event-ID": options.lastEventId }
+                : undefined,
+            params: options?.streamMode
+                ? { stream_mode: options.streamMode }
+                : undefined,
+        }));
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const stream = (response.body || new ReadableStream({ start: (ctrl) => ctrl.close() }))
+            .pipeThrough((0, sse_js_1.BytesLineDecoder)())
+            .pipeThrough((0, sse_js_1.SSEDecoder)());
+        yield* stream_js_1.IterableReadableStream.fromReadableStream(stream);
+    }
 }
 exports.ThreadsClient = ThreadsClient;
 class RunsClient extends BaseClient {
@@ -649,6 +719,7 @@ class RunsClient extends BaseClient {
             after_seconds: payload?.afterSeconds,
             if_not_exists: payload?.ifNotExists,
             checkpoint_during: payload?.checkpointDuring,
+            durability: payload?.durability,
         };
         const endpoint = threadId == null ? `/runs/stream` : `/threads/${threadId}/runs/stream`;
         const response = await this.asyncCaller.fetch(...this.prepareFetchOptions(endpoint, {
@@ -694,6 +765,7 @@ class RunsClient extends BaseClient {
             after_seconds: payload?.afterSeconds,
             if_not_exists: payload?.ifNotExists,
             checkpoint_during: payload?.checkpointDuring,
+            durability: payload?.durability,
             langsmith_tracer: payload?._langsmithTracer
                 ? {
                     project_name: payload?._langsmithTracer?.projectName,
@@ -756,6 +828,7 @@ class RunsClient extends BaseClient {
             after_seconds: payload?.afterSeconds,
             if_not_exists: payload?.ifNotExists,
             checkpoint_during: payload?.checkpointDuring,
+            durability: payload?.durability,
             langsmith_tracer: payload?._langsmithTracer
                 ? {
                     project_name: payload?._langsmithTracer?.projectName,

package/dist/client.d.ts

@@ -1,6 +1,6 @@
 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 type { StreamMode, ThreadStreamMode, TypedAsyncGenerator } from "./types.stream.js";
 import { AsyncCaller, AsyncCallerParams } from "./utils/async_caller.js";
 type HeaderValue = string | undefined | null;
 /**
@@ -87,6 +87,17 @@ export declare class CronsClient extends BaseClient {
         sortOrder?: SortOrder;
         select?: CronSelectField[];
     }): Promise<Cron[]>;
+    /**
+     * Count cron jobs matching filters.
+     *
+     * @param query.assistantId Assistant ID to filter by.
+     * @param query.threadId Thread ID to filter by.
+     * @returns Number of cron jobs matching the criteria.
+     */
+    count(query?: {
+        assistantId?: string;
+        threadId?: string;
+    }): Promise<number>;
 }
 export declare class AssistantsClient extends BaseClient {
     /**
@@ -171,6 +182,17 @@ export declare class AssistantsClient extends BaseClient {
         sortOrder?: SortOrder;
         select?: AssistantSelectField[];
     }): Promise<Assistant[]>;
+    /**
+     * Count assistants matching filters.
+     *
+     * @param query.metadata Metadata to filter by. Exact match for each key/value.
+     * @param query.graphId Optional graph id to filter by.
+     * @returns Number of assistants matching the criteria.
+     */
+    count(query?: {
+        metadata?: Metadata;
+        graphId?: string;
+    }): Promise<number>;
     /**
      * List all versions of an assistant.
      *
@@ -299,6 +321,19 @@ export declare class ThreadsClient<TStateType = DefaultValues, TUpdateType = TSt
         sortOrder?: SortOrder;
         select?: ThreadSelectField[];
     }): Promise<Thread<ValuesType>[]>;
+    /**
+     * Count threads matching filters.
+     *
+     * @param query.metadata Thread metadata to filter on.
+     * @param query.values State values to filter on.
+     * @param query.status Thread status to filter on.
+     * @returns Number of threads matching the criteria.
+     */
+    count<ValuesType = TStateType>(query?: {
+        metadata?: Metadata;
+        values?: ValuesType;
+        status?: ThreadStatus;
+    }): Promise<number>;
     /**
      * Get state for a thread.
      *
@@ -340,6 +375,14 @@ export declare class ThreadsClient<TStateType = DefaultValues, TUpdateType = TSt
         checkpoint?: Partial<Omit<Checkpoint, "thread_id">>;
         metadata?: Metadata;
     }): Promise<ThreadState<ValuesType>[]>;
+    joinStream(threadId: string, options?: {
+        lastEventId?: string;
+        streamMode?: ThreadStreamMode | ThreadStreamMode[];
+    }): AsyncGenerator<{
+        id?: string;
+        event: StreamEvent;
+        data: any;
+    }>;
 }
 export declare class RunsClient<TStateType = DefaultValues, TUpdateType = TStateType, TCustomEventType = unknown> extends BaseClient {
     stream<TStreamMode extends StreamMode | StreamMode[] = StreamMode, TSubgraphs extends boolean = false>(threadId: null, assistantId: string, payload?: Omit<RunsStreamPayload<TStreamMode, TSubgraphs>, "multitaskStrategy" | "onCompletion">): TypedAsyncGenerator<TStreamMode, TSubgraphs, TStateType, TUpdateType, TCustomEventType>;

package/dist/client.js

@@ -239,6 +239,7 @@ export class CronsClient extends BaseClient {
             multitask_strategy: payload?.multitaskStrategy,
             if_not_exists: payload?.ifNotExists,
             checkpoint_during: payload?.checkpointDuring,
+            durability: payload?.durability,
         };
         return this.fetch(`/threads/${threadId}/runs/crons`, {
             method: "POST",
@@ -265,6 +266,7 @@ export class CronsClient extends BaseClient {
             multitask_strategy: payload?.multitaskStrategy,
             if_not_exists: payload?.ifNotExists,
             checkpoint_during: payload?.checkpointDuring,
+            durability: payload?.durability,
         };
         return this.fetch(`/runs/crons`, {
             method: "POST",
@@ -299,6 +301,22 @@ export class CronsClient extends BaseClient {
             },
         });
     }
+    /**
+     * Count cron jobs matching filters.
+     *
+     * @param query.assistantId Assistant ID to filter by.
+     * @param query.threadId Thread ID to filter by.
+     * @returns Number of cron jobs matching the criteria.
+     */
+    async count(query) {
+        return this.fetch(`/runs/crons/count`, {
+            method: "POST",
+            json: {
+                assistant_id: query?.assistantId ?? undefined,
+                thread_id: query?.threadId ?? undefined,
+            },
+        });
+    }
 }
 export class AssistantsClient extends BaseClient {
     /**
@@ -412,6 +430,22 @@ export class AssistantsClient extends BaseClient {
             },
         });
     }
+    /**
+     * Count assistants matching filters.
+     *
+     * @param query.metadata Metadata to filter by. Exact match for each key/value.
+     * @param query.graphId Optional graph id to filter by.
+     * @returns Number of assistants matching the criteria.
+     */
+    async count(query) {
+        return this.fetch(`/assistants/count`, {
+            method: "POST",
+            json: {
+                metadata: query?.metadata ?? undefined,
+                graph_id: query?.graphId ?? undefined,
+            },
+        });
+    }
     /**
      * List all versions of an assistant.
      *
@@ -531,6 +565,24 @@ export class ThreadsClient extends BaseClient {
             },
         });
     }
+    /**
+     * Count threads matching filters.
+     *
+     * @param query.metadata Thread metadata to filter on.
+     * @param query.values State values to filter on.
+     * @param query.status Thread status to filter on.
+     * @returns Number of threads matching the criteria.
+     */
+    async count(query) {
+        return this.fetch(`/threads/count`, {
+            method: "POST",
+            json: {
+                metadata: query?.metadata ?? undefined,
+                values: query?.values ?? undefined,
+                status: query?.status ?? undefined,
+            },
+        });
+    }
     /**
      * Get state for a thread.
      *
@@ -609,6 +661,24 @@ export class ThreadsClient extends BaseClient {
             },
         });
     }
+    async *joinStream(threadId, options
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ) {
+        const response = await this.asyncCaller.fetch(...this.prepareFetchOptions(`/threads/${threadId}/stream`, {
+            method: "GET",
+            headers: options?.lastEventId
+                ? { "Last-Event-ID": options.lastEventId }
+                : undefined,
+            params: options?.streamMode
+                ? { stream_mode: options.streamMode }
+                : undefined,
+        }));
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const stream = (response.body || new ReadableStream({ start: (ctrl) => ctrl.close() }))
+            .pipeThrough(BytesLineDecoder())
+            .pipeThrough(SSEDecoder());
+        yield* IterableReadableStream.fromReadableStream(stream);
+    }
 }
 export class RunsClient extends BaseClient {
     /**
@@ -641,6 +711,7 @@ export class RunsClient extends BaseClient {
             after_seconds: payload?.afterSeconds,
             if_not_exists: payload?.ifNotExists,
             checkpoint_during: payload?.checkpointDuring,
+            durability: payload?.durability,
         };
         const endpoint = threadId == null ? `/runs/stream` : `/threads/${threadId}/runs/stream`;
         const response = await this.asyncCaller.fetch(...this.prepareFetchOptions(endpoint, {
@@ -686,6 +757,7 @@ export class RunsClient extends BaseClient {
             after_seconds: payload?.afterSeconds,
             if_not_exists: payload?.ifNotExists,
             checkpoint_during: payload?.checkpointDuring,
+            durability: payload?.durability,
             langsmith_tracer: payload?._langsmithTracer
                 ? {
                     project_name: payload?._langsmithTracer?.projectName,
@@ -748,6 +820,7 @@ export class RunsClient extends BaseClient {
             after_seconds: payload?.afterSeconds,
             if_not_exists: payload?.ifNotExists,
             checkpoint_during: payload?.checkpointDuring,
+            durability: payload?.durability,
             langsmith_tracer: payload?._langsmithTracer
                 ? {
                     project_name: payload?._langsmithTracer?.projectName,

package/dist/react/stream.cjs

@@ -202,7 +202,11 @@ function fetchHistory(client, threadId, options) {
 }
 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 [isLoading, setIsLoading] = (0, react_1.useState)(() => {
+        if (threadId == null)
+            return false;
+        return true;
+    });
     const [error, setError] = (0, react_1.useState)(undefined);
     const clientHash = (0, client_js_1.getClientConfigHash)(client);
     const clientRef = (0, react_1.useRef)(client);
@@ -236,7 +240,7 @@ function useThreadHistory(threadId, client, limit, clearCallbackRef, submittingR
         if (submittingRef.current)
             return;
         void fetcher(threadId);
-    }, [fetcher, clientHash, limit, submittingRef, threadId]);
+    }, [fetcher, submittingRef, clientHash, limit, threadId]);
     return {
         data: history,
         isLoading,
@@ -619,6 +623,7 @@ function useStream(options) {
                 streamMode,
                 streamSubgraphs: submitOptions?.streamSubgraphs,
                 streamResumable,
+                durability: submitOptions?.durability,
                 onRunCreated(params) {
                     callbackMeta = {
                         run_id: params.run_id,

package/dist/react/stream.d.ts

@@ -1,5 +1,5 @@
 import { Client, type ClientConfig } from "../client.js";
-import type { Command, DisconnectMode, MultitaskStrategy, OnCompletionBehavior } from "../types.js";
+import type { Command, DisconnectMode, Durability, MultitaskStrategy, OnCompletionBehavior } from "../types.js";
 import type { Message } from "../types.messages.js";
 import type { Checkpoint, Config, Interrupt, Metadata, ThreadState } from "../schema.js";
 import type { CheckpointsStreamEvent, CustomStreamEvent, DebugStreamEvent, EventsStreamEvent, MetadataStreamEvent, StreamMode, TasksStreamEvent, UpdatesStreamEvent } from "../types.stream.js";
@@ -304,6 +304,14 @@ interface SubmitOptions<StateType extends Record<string, unknown> = Record<strin
      */
     streamSubgraphs?: boolean;
     streamResumable?: boolean;
+    /**
+     * Whether to checkpoint during the run (or only at the end/interruption).
+     * - `"async"`: Save checkpoint asynchronously while the next step executes (default).
+     * - `"sync"`: Save checkpoint synchronously before the next step starts.
+     * - `"exit"`: Save checkpoint only when the graph exits.
+     * @default "async"
+     */
+    durability?: Durability;
     /**
      * The ID to use when creating a new thread. When provided, this ID will be used
      * for thread creation when threadId is `null` or `undefined`.

package/dist/react/stream.js

@@ -198,7 +198,11 @@ function fetchHistory(client, threadId, options) {
 }
 function useThreadHistory(threadId, client, limit, clearCallbackRef, submittingRef, onErrorRef) {
     const [history, setHistory] = useState(undefined);
-    const [isLoading, setIsLoading] = useState(false);
+    const [isLoading, setIsLoading] = useState(() => {
+        if (threadId == null)
+            return false;
+        return true;
+    });
     const [error, setError] = useState(undefined);
     const clientHash = getClientConfigHash(client);
     const clientRef = useRef(client);
@@ -232,7 +236,7 @@ function useThreadHistory(threadId, client, limit, clearCallbackRef, submittingR
         if (submittingRef.current)
             return;
         void fetcher(threadId);
-    }, [fetcher, clientHash, limit, submittingRef, threadId]);
+    }, [fetcher, submittingRef, clientHash, limit, threadId]);
     return {
         data: history,
         isLoading,
@@ -615,6 +619,7 @@ export function useStream(options) {
                 streamMode,
                 streamSubgraphs: submitOptions?.streamSubgraphs,
                 streamResumable,
+                durability: submitOptions?.durability,
                 onRunCreated(params) {
                     callbackMeta = {
                         run_id: params.run_id,

package/dist/types.d.ts

@@ -5,6 +5,7 @@ export type MultitaskStrategy = "reject" | "interrupt" | "rollback" | "enqueue";
 export type OnConflictBehavior = "raise" | "do_nothing";
 export type OnCompletionBehavior = "complete" | "continue";
 export type DisconnectMode = "cancel" | "continue";
+export type Durability = "exit" | "async" | "sync";
 export type StreamEvent = "events" | "metadata" | "debug" | "updates" | "values" | "messages/partial" | "messages/metadata" | "messages/complete" | "messages" | (string & {});
 export interface Send {
     node: string;
@@ -54,8 +55,17 @@ export interface RunsInvokePayload {
     checkpoint?: Omit<Checkpoint, "thread_id">;
     /**
      * Whether to checkpoint during the run (or only at the end/interruption).
+     * @deprecated Use `durability` instead.
      */
     checkpointDuring?: boolean;
+    /**
+     * Whether to checkpoint during the run (or only at the end/interruption).
+     * - `"async"`: Save checkpoint asynchronously while the next step executes (default).
+     * - `"sync"`: Save checkpoint synchronously before the next step starts.
+     * - `"exit"`: Save checkpoint only when the graph exits.
+     * @default "async"
+     */
+    durability?: Durability;
     /**
      * Interrupt execution before entering these nodes.
      */

package/dist/types.stream.d.ts

@@ -12,6 +12,7 @@ import type { SubgraphCheckpointsStreamEvent } from "./types.stream.subgraph.js"
  * - "custom": Stream custom events.
  */
 export type StreamMode = "values" | "messages" | "updates" | "events" | "debug" | "tasks" | "checkpoints" | "custom" | "messages-tuple";
+export type ThreadStreamMode = "run_modes" | "lifecycle" | "state_update";
 type MessageTupleMetadata = {
     tags: string[];
     [key: string]: unknown;

package/package.json

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