@langchain/langgraph-sdk 0.0.112 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @langchain/langgraph-sdk
 
+## 0.1.1
+
+### Patch Changes
+
+- 7de6680: Fix `onRequest` not being called when streaming runs or threads (#1585)
+- df8b662: Fix interrupts not being exposed in `useStream["interrupt"]` when `fetchStateHistory: false`
+- 572de43: feat(threads): add `ids` filter to Threads.search
+
+  - SDK: `ThreadsClient.search` now accepts `ids?: string[]` and forwards it to `/threads/search`.
+  - API: `/threads/search` schema accepts `ids` and storage filters by provided thread IDs.
+
+  This enables fetching a specific set of threads directly via the search endpoint, while remaining backward compatible.
+
+## 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

package/dist/auth/types.d.ts

@@ -89,6 +89,7 @@ interface ThreadDelete {
  */
 interface ThreadSearch {
     thread_id?: Maybe<string>;
+    ids?: Maybe<string[]>;
     status?: Maybe<"idle" | "busy" | "interrupted" | "error" | (string & {})>;
     metadata?: Maybe<Record<string, unknown>>;
     values?: Maybe<Record<string, unknown>>;

package/dist/client.cjs

@@ -563,6 +563,7 @@ class ThreadsClient extends BaseClient {
             method: "POST",
             json: {
                 metadata: query?.metadata ?? undefined,
+                ids: query?.ids ?? undefined,
                 limit: query?.limit ?? 10,
                 offset: query?.offset ?? 0,
                 status: query?.status,
@@ -671,7 +672,7 @@ 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`, {
+        let [url, init] = this.prepareFetchOptions(`/threads/${threadId}/stream`, {
             method: "GET",
             headers: options?.lastEventId
                 ? { "Last-Event-ID": options.lastEventId }
@@ -679,7 +680,10 @@ class ThreadsClient extends BaseClient {
             params: options?.streamMode
                 ? { stream_mode: options.streamMode }
                 : undefined,
-        }));
+        });
+        if (this.onRequest != null)
+            init = await this.onRequest(url, init);
+        const response = await this.asyncCaller.fetch(url, init);
         // 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)())
@@ -722,12 +726,15 @@ class RunsClient extends BaseClient {
             durability: payload?.durability,
         };
         const endpoint = threadId == null ? `/runs/stream` : `/threads/${threadId}/runs/stream`;
-        const response = await this.asyncCaller.fetch(...this.prepareFetchOptions(endpoint, {
+        let [url, init] = this.prepareFetchOptions(endpoint, {
             method: "POST",
             json,
             timeoutMs: null,
             signal: payload?.signal,
-        }));
+        });
+        if (this.onRequest != null)
+            init = await this.onRequest(url, init);
+        const response = await this.asyncCaller.fetch(url, init);
         const runMetadata = getRunMetadataFromResponse(response);
         if (runMetadata)
             payload?.onRunCreated?.(runMetadata);
@@ -939,7 +946,7 @@ class RunsClient extends BaseClient {
             options instanceof AbortSignal
             ? { signal: options }
             : options;
-        const response = await this.asyncCaller.fetch(...this.prepareFetchOptions(threadId != null
+        let [url, init] = this.prepareFetchOptions(threadId != null
             ? `/threads/${threadId}/runs/${runId}/stream`
             : `/runs/${runId}/stream`, {
             method: "GET",
@@ -952,7 +959,10 @@ class RunsClient extends BaseClient {
                 cancel_on_disconnect: opts?.cancelOnDisconnect ? "1" : "0",
                 stream_mode: opts?.streamMode,
             },
-        }));
+        });
+        if (this.onRequest != null)
+            init = await this.onRequest(url, init);
+        const response = await this.asyncCaller.fetch(url, init);
         // 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)())
@@ -1172,14 +1182,17 @@ class UiClient extends BaseClient {
     }
     async getComponent(assistantId, agentName) {
         return UiClient.getOrCached(`${this.apiUrl}-${assistantId}-${agentName}`, async () => {
-            const response = await this.asyncCaller.fetch(...this.prepareFetchOptions(`/ui/${assistantId}`, {
+            let [url, init] = this.prepareFetchOptions(`/ui/${assistantId}`, {
                 headers: {
                     Accept: "text/html",
                     "Content-Type": "application/json",
                 },
                 method: "POST",
                 json: { name: agentName },
-            }));
+            });
+            if (this.onRequest != null)
+                init = await this.onRequest(url, init);
+            const response = await this.asyncCaller.fetch(url, init);
             return response.text();
         });
     }

package/dist/client.d.ts

@@ -297,6 +297,10 @@ export declare class ThreadsClient<TStateType = DefaultValues, TUpdateType = TSt
          * Metadata to filter threads by.
          */
         metadata?: Metadata;
+        /**
+         * Filter by specific thread IDs.
+         */
+        ids?: string[];
         /**
          * Maximum number of threads to return.
          * Defaults to 10

package/dist/client.js

@@ -556,6 +556,7 @@ export class ThreadsClient extends BaseClient {
             method: "POST",
             json: {
                 metadata: query?.metadata ?? undefined,
+                ids: query?.ids ?? undefined,
                 limit: query?.limit ?? 10,
                 offset: query?.offset ?? 0,
                 status: query?.status,
@@ -664,7 +665,7 @@ 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`, {
+        let [url, init] = this.prepareFetchOptions(`/threads/${threadId}/stream`, {
             method: "GET",
             headers: options?.lastEventId
                 ? { "Last-Event-ID": options.lastEventId }
@@ -672,7 +673,10 @@ export class ThreadsClient extends BaseClient {
             params: options?.streamMode
                 ? { stream_mode: options.streamMode }
                 : undefined,
-        }));
+        });
+        if (this.onRequest != null)
+            init = await this.onRequest(url, init);
+        const response = await this.asyncCaller.fetch(url, init);
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const stream = (response.body || new ReadableStream({ start: (ctrl) => ctrl.close() }))
             .pipeThrough(BytesLineDecoder())
@@ -714,12 +718,15 @@ export class RunsClient extends BaseClient {
             durability: payload?.durability,
         };
         const endpoint = threadId == null ? `/runs/stream` : `/threads/${threadId}/runs/stream`;
-        const response = await this.asyncCaller.fetch(...this.prepareFetchOptions(endpoint, {
+        let [url, init] = this.prepareFetchOptions(endpoint, {
             method: "POST",
             json,
             timeoutMs: null,
             signal: payload?.signal,
-        }));
+        });
+        if (this.onRequest != null)
+            init = await this.onRequest(url, init);
+        const response = await this.asyncCaller.fetch(url, init);
         const runMetadata = getRunMetadataFromResponse(response);
         if (runMetadata)
             payload?.onRunCreated?.(runMetadata);
@@ -931,7 +938,7 @@ export class RunsClient extends BaseClient {
             options instanceof AbortSignal
             ? { signal: options }
             : options;
-        const response = await this.asyncCaller.fetch(...this.prepareFetchOptions(threadId != null
+        let [url, init] = this.prepareFetchOptions(threadId != null
             ? `/threads/${threadId}/runs/${runId}/stream`
             : `/runs/${runId}/stream`, {
             method: "GET",
@@ -944,7 +951,10 @@ export class RunsClient extends BaseClient {
                 cancel_on_disconnect: opts?.cancelOnDisconnect ? "1" : "0",
                 stream_mode: opts?.streamMode,
             },
-        }));
+        });
+        if (this.onRequest != null)
+            init = await this.onRequest(url, init);
+        const response = await this.asyncCaller.fetch(url, init);
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const stream = (response.body || new ReadableStream({ start: (ctrl) => ctrl.close() }))
             .pipeThrough(BytesLineDecoder())
@@ -1162,14 +1172,17 @@ class UiClient extends BaseClient {
     }
     async getComponent(assistantId, agentName) {
         return UiClient.getOrCached(`${this.apiUrl}-${assistantId}-${agentName}`, async () => {
-            const response = await this.asyncCaller.fetch(...this.prepareFetchOptions(`/ui/${assistantId}`, {
+            let [url, init] = this.prepareFetchOptions(`/ui/${assistantId}`, {
                 headers: {
                     Accept: "text/html",
                     "Content-Type": "application/json",
                 },
                 method: "POST",
                 json: { name: agentName },
-            }));
+            });
+            if (this.onRequest != null)
+                init = await this.onRequest(url, init);
+            const response = await this.asyncCaller.fetch(url, init);
             return response.text();
         });
     }

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";