@langchain/langgraph-sdk 0.0.111 → 0.1.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @langchain/langgraph-sdk
 
+## 0.1.0
+
+### Minor Changes
+
+- 35a0f1c: feat(sdk): set default limit of fetch history to 10
+- 35a0f1c: feat(sdk): set default of `fetchStateHistory` to `false`
+
+### Patch Changes
+
+- 35a0f1c: chore(sdk): decouple stream manager from React
+- 35a0f1c: fix(sdk): prevent partial history from hiding all values
+
+## 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

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",
@@ -666,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 {
@@ -699,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, {
@@ -744,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,
@@ -806,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;
 /**
@@ -375,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",
@@ -659,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 {
     /**
@@ -691,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, {
@@ -736,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,
@@ -798,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/branching.cjs

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBranchSequence = getBranchSequence;
+exports.getBranchView = getBranchView;
+exports.getBranchContext = getBranchContext;
+function getBranchSequence(history) {
+    const nodeIds = new Set();
+    const childrenMap = {};
+    // Short circuit if there's only a singular one state
+    if (history.length <= 1) {
+        return {
+            rootSequence: {
+                type: "sequence",
+                items: history.map((value) => ({ type: "node", value, path: [] })),
+            },
+            paths: [],
+        };
+    }
+    // First pass - collect nodes for each checkpoint
+    history.forEach((state) => {
+        const checkpointId = state.parent_checkpoint?.checkpoint_id ?? "$";
+        childrenMap[checkpointId] ??= [];
+        childrenMap[checkpointId].push(state);
+        if (state.checkpoint?.checkpoint_id != null) {
+            nodeIds.add(state.checkpoint.checkpoint_id);
+        }
+    });
+    // If dealing with partial history, take the branch
+    // with the latest checkpoint and mark it as the root.
+    const maxId = (...ids) => ids
+        .filter((i) => i != null)
+        .sort((a, b) => a.localeCompare(b))
+        .at(-1);
+    const lastOrphanedNode = childrenMap.$ == null
+        ? Object.keys(childrenMap)
+            .filter((parentId) => !nodeIds.has(parentId))
+            .map((parentId) => {
+            const queue = [parentId];
+            const seen = new Set();
+            let lastId = parentId;
+            while (queue.length > 0) {
+                const current = queue.shift();
+                if (seen.has(current))
+                    continue;
+                seen.add(current);
+                const children = (childrenMap[current] ?? []).flatMap((i) => i.checkpoint?.checkpoint_id ?? []);
+                lastId = maxId(lastId, ...children);
+                queue.push(...children);
+            }
+            return { parentId, lastId };
+        })
+            .sort((a, b) => a.lastId.localeCompare(b.lastId))
+            .at(-1)?.parentId
+        : undefined;
+    if (lastOrphanedNode != null)
+        childrenMap.$ = childrenMap[lastOrphanedNode];
+    const rootSequence = { type: "sequence", items: [] };
+    const queue = [{ id: "$", sequence: rootSequence, path: [] }];
+    const paths = [];
+    const visited = new Set();
+    while (queue.length > 0) {
+        const task = queue.shift();
+        if (visited.has(task.id))
+            continue;
+        visited.add(task.id);
+        const children = childrenMap[task.id];
+        if (children == null || children.length === 0)
+            continue;
+        // If we've encountered a fork (2+ children), push the fork
+        // to the sequence and add a new sequence for each child
+        let fork;
+        if (children.length > 1) {
+            fork = { type: "fork", items: [] };
+            task.sequence.items.push(fork);
+        }
+        for (const value of children) {
+            const id = value.checkpoint?.checkpoint_id;
+            if (id == null)
+                continue;
+            let { sequence } = task;
+            let { path } = task;
+            if (fork != null) {
+                sequence = { type: "sequence", items: [] };
+                fork.items.unshift(sequence);
+                path = path.slice();
+                path.push(id);
+                paths.push(path);
+            }
+            sequence.items.push({ type: "node", value, path });
+            queue.push({ id, sequence, path });
+        }
+    }
+    return { rootSequence, paths };
+}
+const PATH_SEP = ">";
+const ROOT_ID = "$";
+// Get flat view
+function getBranchView(sequence, paths, branch) {
+    const path = branch.split(PATH_SEP);
+    const pathMap = {};
+    for (const path of paths) {
+        const parent = path.at(-2) ?? ROOT_ID;
+        pathMap[parent] ??= [];
+        pathMap[parent].unshift(path);
+    }
+    const history = [];
+    const branchByCheckpoint = {};
+    const forkStack = path.slice();
+    const queue = [...sequence.items];
+    while (queue.length > 0) {
+        const item = queue.shift();
+        if (item.type === "node") {
+            history.push(item.value);
+            const checkpointId = item.value.checkpoint?.checkpoint_id;
+            if (checkpointId == null)
+                continue;
+            branchByCheckpoint[checkpointId] = {
+                branch: item.path.join(PATH_SEP),
+                branchOptions: (item.path.length > 0
+                    ? pathMap[item.path.at(-2) ?? ROOT_ID] ?? []
+                    : []).map((p) => p.join(PATH_SEP)),
+            };
+        }
+        if (item.type === "fork") {
+            const forkId = forkStack.shift();
+            const index = forkId != null
+                ? item.items.findIndex((value) => {
+                    const firstItem = value.items.at(0);
+                    if (!firstItem || firstItem.type !== "node")
+                        return false;
+                    return firstItem.value.checkpoint?.checkpoint_id === forkId;
+                })
+                : -1;
+            const nextItems = item.items.at(index)?.items ?? [];
+            queue.push(...nextItems);
+        }
+    }
+    return { history, branchByCheckpoint };
+}
+function getBranchContext(branch, history) {
+    const { rootSequence: branchTree, paths } = getBranchSequence(history ?? []);
+    const { history: flatHistory, branchByCheckpoint } = getBranchView(branchTree, paths, branch);
+    return {
+        branchTree,
+        flatHistory,
+        branchByCheckpoint,
+        threadHead: flatHistory.at(-1),
+    };
+}

package/dist/react/branching.d.ts

@@ -0,0 +1,35 @@
+import type { ThreadState } from "../schema.js";
+interface Node<StateType = any> {
+    type: "node";
+    value: ThreadState<StateType>;
+    path: string[];
+}
+interface Fork<StateType = any> {
+    type: "fork";
+    items: Array<Sequence<StateType>>;
+}
+export interface Sequence<StateType = any> {
+    type: "sequence";
+    items: Array<Node<StateType> | Fork<StateType>>;
+}
+export declare function getBranchSequence<StateType extends Record<string, unknown>>(history: ThreadState<StateType>[]): {
+    rootSequence: Sequence<any>;
+    paths: string[][];
+};
+export declare function getBranchView<StateType extends Record<string, unknown>>(sequence: Sequence<StateType>, paths: string[][], branch: string): {
+    history: ThreadState<StateType>[];
+    branchByCheckpoint: Record<string, {
+        branch: string | undefined;
+        branchOptions: string[] | undefined;
+    }>;
+};
+export declare function getBranchContext<StateType extends Record<string, unknown>>(branch: string, history: ThreadState<StateType>[] | undefined): {
+    branchTree: Sequence<any>;
+    flatHistory: ThreadState<any>[];
+    branchByCheckpoint: Record<string, {
+        branch: string | undefined;
+        branchOptions: string[] | undefined;
+    }>;
+    threadHead: ThreadState<any> | undefined;
+};
+export {};

package/dist/react/branching.js

@@ -0,0 +1,144 @@
+export function getBranchSequence(history) {
+    const nodeIds = new Set();
+    const childrenMap = {};
+    // Short circuit if there's only a singular one state
+    if (history.length <= 1) {
+        return {
+            rootSequence: {
+                type: "sequence",
+                items: history.map((value) => ({ type: "node", value, path: [] })),
+            },
+            paths: [],
+        };
+    }
+    // First pass - collect nodes for each checkpoint
+    history.forEach((state) => {
+        const checkpointId = state.parent_checkpoint?.checkpoint_id ?? "$";
+        childrenMap[checkpointId] ??= [];
+        childrenMap[checkpointId].push(state);
+        if (state.checkpoint?.checkpoint_id != null) {
+            nodeIds.add(state.checkpoint.checkpoint_id);
+        }
+    });
+    // If dealing with partial history, take the branch
+    // with the latest checkpoint and mark it as the root.
+    const maxId = (...ids) => ids
+        .filter((i) => i != null)
+        .sort((a, b) => a.localeCompare(b))
+        .at(-1);
+    const lastOrphanedNode = childrenMap.$ == null
+        ? Object.keys(childrenMap)
+            .filter((parentId) => !nodeIds.has(parentId))
+            .map((parentId) => {
+            const queue = [parentId];
+            const seen = new Set();
+            let lastId = parentId;
+            while (queue.length > 0) {
+                const current = queue.shift();
+                if (seen.has(current))
+                    continue;
+                seen.add(current);
+                const children = (childrenMap[current] ?? []).flatMap((i) => i.checkpoint?.checkpoint_id ?? []);
+                lastId = maxId(lastId, ...children);
+                queue.push(...children);
+            }
+            return { parentId, lastId };
+        })
+            .sort((a, b) => a.lastId.localeCompare(b.lastId))
+            .at(-1)?.parentId
+        : undefined;
+    if (lastOrphanedNode != null)
+        childrenMap.$ = childrenMap[lastOrphanedNode];
+    const rootSequence = { type: "sequence", items: [] };
+    const queue = [{ id: "$", sequence: rootSequence, path: [] }];
+    const paths = [];
+    const visited = new Set();
+    while (queue.length > 0) {
+        const task = queue.shift();
+        if (visited.has(task.id))
+            continue;
+        visited.add(task.id);
+        const children = childrenMap[task.id];
+        if (children == null || children.length === 0)
+            continue;
+        // If we've encountered a fork (2+ children), push the fork
+        // to the sequence and add a new sequence for each child
+        let fork;
+        if (children.length > 1) {
+            fork = { type: "fork", items: [] };
+            task.sequence.items.push(fork);
+        }
+        for (const value of children) {
+            const id = value.checkpoint?.checkpoint_id;
+            if (id == null)
+                continue;
+            let { sequence } = task;
+            let { path } = task;
+            if (fork != null) {
+                sequence = { type: "sequence", items: [] };
+                fork.items.unshift(sequence);
+                path = path.slice();
+                path.push(id);
+                paths.push(path);
+            }
+            sequence.items.push({ type: "node", value, path });
+            queue.push({ id, sequence, path });
+        }
+    }
+    return { rootSequence, paths };
+}
+const PATH_SEP = ">";
+const ROOT_ID = "$";
+// Get flat view
+export function getBranchView(sequence, paths, branch) {
+    const path = branch.split(PATH_SEP);
+    const pathMap = {};
+    for (const path of paths) {
+        const parent = path.at(-2) ?? ROOT_ID;
+        pathMap[parent] ??= [];
+        pathMap[parent].unshift(path);
+    }
+    const history = [];
+    const branchByCheckpoint = {};
+    const forkStack = path.slice();
+    const queue = [...sequence.items];
+    while (queue.length > 0) {
+        const item = queue.shift();
+        if (item.type === "node") {
+            history.push(item.value);
+            const checkpointId = item.value.checkpoint?.checkpoint_id;
+            if (checkpointId == null)
+                continue;
+            branchByCheckpoint[checkpointId] = {
+                branch: item.path.join(PATH_SEP),
+                branchOptions: (item.path.length > 0
+                    ? pathMap[item.path.at(-2) ?? ROOT_ID] ?? []
+                    : []).map((p) => p.join(PATH_SEP)),
+            };
+        }
+        if (item.type === "fork") {
+            const forkId = forkStack.shift();
+            const index = forkId != null
+                ? item.items.findIndex((value) => {
+                    const firstItem = value.items.at(0);
+                    if (!firstItem || firstItem.type !== "node")
+                        return false;
+                    return firstItem.value.checkpoint?.checkpoint_id === forkId;
+                })
+                : -1;
+            const nextItems = item.items.at(index)?.items ?? [];
+            queue.push(...nextItems);
+        }
+    }
+    return { history, branchByCheckpoint };
+}
+export function getBranchContext(branch, history) {
+    const { rootSequence: branchTree, paths } = getBranchSequence(history ?? []);
+    const { history: flatHistory, branchByCheckpoint } = getBranchView(branchTree, paths, branch);
+    return {
+        branchTree,
+        flatHistory,
+        branchByCheckpoint,
+        threadHead: flatHistory.at(-1),
+    };
+}

package/dist/react/errors.cjs

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StreamError = void 0;
+class StreamError extends Error {
+    constructor(data) {
+        super(data.message);
+        this.name = data.name ?? data.error ?? "StreamError";
+    }
+    static isStructuredError(error) {
+        return typeof error === "object" && error != null && "message" in error;
+    }
+}
+exports.StreamError = StreamError;

package/dist/react/errors.d.ts

@@ -0,0 +1,12 @@
+export declare class StreamError extends Error {
+    constructor(data: {
+        error?: string;
+        name?: string;
+        message: string;
+    });
+    static isStructuredError(error: unknown): error is {
+        error?: string;
+        name?: string;
+        message: string;
+    };
+}

package/dist/react/errors.js

@@ -0,0 +1,9 @@
+export class StreamError extends Error {
+    constructor(data) {
+        super(data.message);
+        this.name = data.name ?? data.error ?? "StreamError";
+    }
+    static isStructuredError(error) {
+        return typeof error === "object" && error != null && "message" in error;
+    }
+}

package/dist/react/index.d.ts

@@ -1 +1,2 @@
-export { useStream, type MessageMetadata, type UseStream, type UseStreamOptions, } from "./stream.js";
+export { useStream } from "./stream.js";
+export type { MessageMetadata, UseStream, UseStreamOptions } from "./types.js";

package/dist/react/index.js

@@ -1 +1 @@
-export { useStream, } from "./stream.js";
+export { useStream } from "./stream.js";