@langchain/langgraph-api 1.1.16 → 1.2.0

package/dist/stream.d.mts

@@ -1,5 +1,6 @@
 import type { BaseCheckpointSaver, LangGraphRunnableConfig, CheckpointMetadata, Interrupt, StateSnapshot } from "@langchain/langgraph";
 import type { Pregel } from "@langchain/langgraph/pregel";
+import type { SourceStreamEvent } from "./protocol/types.mjs";
 import type { Checkpoint, Run, RunnableConfig } from "./storage/types.mjs";
 interface DebugTask {
     id: string;
@@ -36,8 +37,28 @@ export declare function streamState(run: Run, options: {
     onCheckpoint?: (checkpoint: StreamCheckpoint) => void;
     onTaskResult?: (taskResult: StreamTaskResult) => void;
     signal?: AbortSignal;
-}): AsyncGenerator<{
-    event: string;
-    data: unknown;
-}>;
+}): AsyncGenerator<SourceStreamEvent>;
+/**
+ * Executes a graph run using `graph.streamEvents(..., { version: "v3" })`
+ * and maps the resulting `ProtocolEvent` objects into the `{ event, data }`
+ * shape consumed by both the legacy SSE path and the protocol v2 session.
+ *
+ * This path activates graph-level `streamTransformers` (registered via
+ * `.compile({ transformers })`) so that custom transformer output flows to
+ * clients automatically.
+ *
+ * @param run - The queued run to execute.
+ * @param options - Callbacks and graph-loading infrastructure.
+ * @returns Async generator of `{ event, data }` pairs.
+ */
+export declare function streamStateV2(run: Run, options: {
+    attempt: number;
+    graph: Pregel<any, any, any, any, any>;
+    getGraph: (graphId: string, config: LangGraphRunnableConfig | undefined, options?: {
+        checkpointer?: BaseCheckpointSaver | null;
+    }) => Promise<Pregel<any, any, any, any, any>>;
+    onCheckpoint?: (checkpoint: StreamCheckpoint) => void;
+    onTaskResult?: (taskResult: StreamTaskResult) => void;
+    signal?: AbortSignal;
+}): AsyncGenerator<SourceStreamEvent>;
 export {};

package/dist/stream.mjs

@@ -1,7 +1,9 @@
 import { isBaseMessage } from "@langchain/core/messages";
 import { LangChainTracer } from "@langchain/core/tracers/tracer_langchain";
+import { convertToProtocolEvent, STREAM_EVENTS_V3_MODES, } from "@langchain/langgraph/web";
 import { Client as LangSmithClient, getDefaultProjectName } from "langsmith";
 import { getLangGraphCommand } from "./command.mjs";
+import { PROTOCOL_STREAM_RUN_KEY } from "./protocol/constants.mjs";
 import { checkLangGraphSemver } from "./semver/index.mjs";
 import { runnableConfigToCheckpoint, taskRunnableConfigToCheckpoint, } from "./utils/runnableConfig.mjs";
 const isRunnableConfig = (config) => {
@@ -62,6 +64,15 @@ export async function* streamState(run, options) {
     const graph = await options.getGraph(graphId, kwargs.config, {
         checkpointer: kwargs.temporary ? null : undefined,
     });
+    // Only v2 protocol entrypoints opt into `streamStateV2`.
+    // Legacy run/stream endpoints stay on the existing `streamEvents`
+    // path even if a graph defines stream transformers, so they do not
+    // emit protocol-framed events on non-protocol transports.
+    const isProtocolV2Run = kwargs[PROTOCOL_STREAM_RUN_KEY] === true;
+    if (isProtocolV2Run) {
+        yield* streamStateV2(run, { ...options, graph });
+        return;
+    }
     const userStreamMode = kwargs.stream_mode ?? [];
     const libStreamMode = new Set(userStreamMode.filter((mode) => mode !== "events" && mode !== "messages-tuple") ?? []);
     if (userStreamMode.includes("messages-tuple")) {
@@ -103,7 +114,7 @@ export async function* streamState(run, options) {
         : undefined;
     const events = graph.streamEvents(kwargs.command != null
         ? getLangGraphCommand(kwargs.command)
-        : kwargs.input ?? null, {
+        : (kwargs.input ?? null), {
         version: "v2",
         interruptAfter: kwargs.interrupt_after,
         interruptBefore: kwargs.interrupt_before,
@@ -123,9 +134,16 @@ export async function* streamState(run, options) {
     for await (const event of events) {
         if (event.tags?.includes("langsmith:hidden"))
             continue;
-        if (event.event === "on_chain_stream" && event.run_id === run.run_id) {
-            const [ns, mode, chunk] = (kwargs.subgraphs ? event.data.chunk : [null, ...event.data.chunk]);
-            // Listen for debug events and capture checkpoint
+        if (event.event === "on_chain_stream" &&
+            (kwargs.subgraphs || event.run_id === run.run_id)) {
+            // Pregel's stream tuple is `[ns, mode, payload, meta?]` (4th element
+            // is the optional `StreamChunkMeta`, preserved when streaming with
+            // `subgraphs: true`). The meta carries the lightweight checkpoint
+            // envelope attached by `_emitValuesWithCheckpointMeta`, which we
+            // forward as a companion `checkpoints` source event below.
+            const rawTuple = (kwargs.subgraphs ? event.data.chunk : [null, ...event.data.chunk]);
+            const [ns, mode, chunk] = rawTuple;
+            const chunkMeta = rawTuple[3];
             let data = chunk;
             if (mode === "debug") {
                 const debugChunk = chunk;
@@ -152,6 +170,20 @@ export async function* streamState(run, options) {
                 }
                 data = debugTask;
             }
+            // Emit the lightweight checkpoint envelope as a dedicated
+            // `checkpoints` source event immediately BEFORE the companion
+            // `values` event so clients subscribed to both channels have the
+            // envelope buffered by the time the values payload arrives
+            // (`useMessageMetadata(msg.id).parentCheckpointId` for fork /
+            // edit flows). Clients that only want fork / time-travel metadata
+            // subscribe to `checkpoints` alone and avoid the full-state
+            // payload.
+            if (mode === "values" && chunkMeta?.checkpoint != null) {
+                const sseEvent = kwargs.subgraphs && ns?.length
+                    ? `checkpoints|${ns.join("|")}`
+                    : "checkpoints";
+                yield { event: sseEvent, data: chunkMeta.checkpoint };
+            }
             if (mode === "messages") {
                 if (userStreamMode.includes("messages-tuple")) {
                     if (kwargs.subgraphs && ns?.length) {
@@ -163,12 +195,8 @@ export async function* streamState(run, options) {
                 }
             }
             else if (userStreamMode.includes(mode)) {
-                if (kwargs.subgraphs && ns?.length) {
-                    yield { event: `${mode}|${ns.join("|")}`, data };
-                }
-                else {
-                    yield { event: mode, data };
-                }
+                const sseEvent = kwargs.subgraphs && ns?.length ? `${mode}|${ns.join("|")}` : mode;
+                yield { event: sseEvent, data };
             }
         }
         else if (userStreamMode.includes("events")) {
@@ -182,7 +210,8 @@ export async function* streamState(run, options) {
         // - handleLLMEnd should not dedupe the message
         // - Don't think there's an utility that would convert a BaseMessageChunk to a BaseMessage?
         if (userStreamMode.includes("messages")) {
-            if (event.event === "on_chain_stream" && event.run_id === run.run_id) {
+            if (event.event === "on_chain_stream" &&
+                (kwargs.subgraphs || event.run_id === run.run_id)) {
                 const newMessages = [];
                 const [_, chunk] = event.data.chunk;
                 let chunkMessages = [];
@@ -233,3 +262,166 @@ export async function* streamState(run, options) {
         yield { event: "feedback", data };
     }
 }
+function isUnsupportedStreamEventsV3Error(error) {
+    return (error instanceof Error &&
+        error.message.includes('Only versions "v1" and "v2" of the schema are currently supported'));
+}
+async function* fallbackProtocolStreamFromGraphStream(graph, input, options) {
+    let seq = 0;
+    const stream = await graph.stream(input, options);
+    for await (const tuple of stream) {
+        const [namespace, mode, payload, meta] = tuple;
+        const events = convertToProtocolEvent({
+            namespace: namespace ?? [],
+            mode,
+            payload,
+            seq,
+            meta: meta,
+        });
+        seq += events.length;
+        for (const event of events) {
+            yield event;
+        }
+    }
+}
+/**
+ * Executes a graph run using `graph.streamEvents(..., { version: "v3" })`
+ * and maps the resulting `ProtocolEvent` objects into the `{ event, data }`
+ * shape consumed by both the legacy SSE path and the protocol v2 session.
+ *
+ * This path activates graph-level `streamTransformers` (registered via
+ * `.compile({ transformers })`) so that custom transformer output flows to
+ * clients automatically.
+ *
+ * @param run - The queued run to execute.
+ * @param options - Callbacks and graph-loading infrastructure.
+ * @returns Async generator of `{ event, data }` pairs.
+ */
+export async function* streamStateV2(run, options) {
+    const kwargs = run.kwargs;
+    const graph = options.graph;
+    yield {
+        event: "metadata",
+        data: { run_id: run.run_id, attempt: options.attempt },
+    };
+    if (!LANGGRAPH_VERSION) {
+        const version = await checkLangGraphSemver();
+        LANGGRAPH_VERSION = version.find((v) => v.name === "@langchain/langgraph");
+    }
+    const metadata = {
+        ...kwargs.config?.metadata,
+        run_attempt: options.attempt,
+        langgraph_version: LANGGRAPH_VERSION?.version ?? "0.0.0",
+        langgraph_plan: "developer",
+        langgraph_host: "self-hosted",
+        langgraph_api_url: process.env.LANGGRAPH_API_URL ?? undefined,
+    };
+    const tracer = run.kwargs?.config?.configurable?.langsmith_project
+        ? new LangChainTracer({
+            replicas: [
+                [
+                    run.kwargs?.config?.configurable?.langsmith_project,
+                    {
+                        reference_example_id: run.kwargs?.config?.configurable?.langsmith_example_id,
+                    },
+                ],
+                [getDefaultProjectName(), undefined],
+            ],
+        })
+        : undefined;
+    const graphInput = kwargs.command != null
+        ? getLangGraphCommand(kwargs.command)
+        : (kwargs.input ?? null);
+    const graphOptions = {
+        version: "v3",
+        interruptAfter: kwargs.interrupt_after,
+        interruptBefore: kwargs.interrupt_before,
+        tags: kwargs.config?.tags,
+        context: kwargs.context,
+        configurable: kwargs.config?.configurable,
+        recursionLimit: kwargs.config?.recursion_limit,
+        metadata: { ls_integration: "langgraph", ...metadata },
+        runId: run.run_id,
+        signal: options?.signal,
+        ...(tracer && { callbacks: [tracer] }),
+    };
+    let graphRun;
+    try {
+        graphRun = await graph.streamEvents(graphInput, graphOptions);
+    }
+    catch (error) {
+        if (!isUnsupportedStreamEventsV3Error(error)) {
+            throw error;
+        }
+        graphRun = fallbackProtocolStreamFromGraphStream(graph, graphInput, {
+            ...graphOptions,
+            streamMode: STREAM_EVENTS_V3_MODES,
+            subgraphs: true,
+        });
+    }
+    for await (const event of graphRun) {
+        const ns = event.params.namespace;
+        const mode = event.method;
+        const data = event.params.data;
+        if (mode === "debug") {
+            const debugChunk = data;
+            if (debugChunk.type === "checkpoint") {
+                const debugCheckpoint = preprocessDebugCheckpoint(debugChunk.payload);
+                options?.onCheckpoint?.(debugCheckpoint);
+                const sseEvent = ns.length > 0 ? `${mode}|${ns.join("|")}` : mode;
+                yield {
+                    event: sseEvent,
+                    data: { ...debugChunk, payload: debugCheckpoint },
+                };
+                continue;
+            }
+            else if (debugChunk.type === "task_result") {
+                const debugResult = preprocessDebugCheckpointTask(debugChunk.payload);
+                options?.onTaskResult?.(debugResult);
+                const sseEvent = ns.length > 0 ? `${mode}|${ns.join("|")}` : mode;
+                yield {
+                    event: sseEvent,
+                    data: { ...debugChunk, payload: debugResult },
+                };
+                continue;
+            }
+        }
+        else if (mode === "tasks") {
+            const debugTask = preprocessDebugCheckpointTask(data);
+            if ("result" in debugTask || "error" in debugTask) {
+                options?.onTaskResult?.(debugTask);
+            }
+            const sseEvent = ns.length > 0 ? `${mode}|${ns.join("|")}` : mode;
+            yield { event: sseEvent, data: debugTask };
+            continue;
+        }
+        const sseEvent = ns.length > 0 ? `${mode}|${ns.join("|")}` : mode;
+        /**
+         * These modes have already been converted to their protocol shape by
+         * core's `convertToProtocolEvent`, so the session can skip
+         * re-normalization.  Other modes (values, debug, tasks) still
+         * require API-specific processing (interrupt stripping, state
+         * message normalization, checkpoint preprocessing). `checkpoints`
+         * is emitted by core as a standalone protocol event whose `data` is
+         * already the lightweight envelope; the session frames it on the
+         * dedicated `checkpoints` channel.  `lifecycle` events are
+         * synthesized by core's `LifecycleTransformer` and forwarded
+         * verbatim by the session.
+         */
+        const normalized = mode === "tools" ||
+            mode === "updates" ||
+            mode === "custom" ||
+            mode === "messages" ||
+            mode === "checkpoints" ||
+            mode === "lifecycle";
+        yield { event: sseEvent, data, normalized };
+    }
+    if (kwargs.feedback_keys) {
+        const client = new LangSmithClient();
+        const feedbackData = Object.fromEntries(await Promise.all(kwargs.feedback_keys.map(async (feedback) => {
+            const { url } = await client.createPresignedFeedbackToken(run.run_id, feedback);
+            return [feedback, url];
+        })));
+        yield { event: "feedback", data: feedbackData };
+    }
+}

package/dist/utils/serde.mjs

@@ -10,7 +10,7 @@ export const serialiseAsDict = (obj) => {
             return { ...data, type };
         }
         return value;
-    }, 2);
+    });
 };
 export const serializeError = (error) => {
     if (error instanceof Error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@langchain/langgraph-api",
-  "version": "1.1.16",
+  "version": "1.2.0",
   "type": "module",
   "engines": {
     "node": "^18.19.0 || >=20.16.0"
@@ -52,15 +52,17 @@
   },
   "dependencies": {
     "@babel/code-frame": "^7.26.2",
-    "@hono/node-server": "^1.12.0",
+    "@hono/node-server": "^1.19.13",
+    "@hono/node-ws": "^1.3.0",
     "@hono/zod-validator": "^0.7.6",
+    "@langchain/protocol": "^0.0.15",
     "@types/json-schema": "^7.0.15",
     "@typescript/vfs": "^1.6.0",
     "dedent": "^1.5.3",
     "dotenv": "^16.4.7",
     "exit-hook": "^4.0.0",
-    "hono": "^4.5.4",
-    "langsmith": ">=0.3.33 <1.0.0",
+    "hono": "^4.12.14",
+    "langsmith": ">=0.5.19 <1.0.0",
     "open": "^10.1.0",
     "semver": "^7.7.1",
     "stacktrace-parser": "^0.1.10",
@@ -70,10 +72,10 @@
     "winston": "^3.17.0",
     "winston-console-format": "^1.0.8",
     "zod": "^3.25.76 || ^4",
-    "@langchain/langgraph-ui": "1.1.16"
+    "@langchain/langgraph-ui": "1.2.0"
   },
   "peerDependencies": {
-    "@langchain/core": "^0.3.59 || ^1.0.1",
+    "@langchain/core": "^1.1.44",
     "@langchain/langgraph": "^0.2.57 || ^0.3.0 || ^0.4.0 || ^1.0.0-alpha || ^1.0.0",
     "@langchain/langgraph-checkpoint": "~0.0.16 || ^0.1.0 || ~1.0.0",
     "@langchain/langgraph-sdk": "^1.6.5",
@@ -85,32 +87,32 @@
     }
   },
   "devDependencies": {
-    "@langchain/core": "^1.1.28",
+    "@langchain/core": "^1.1.44",
     "@types/babel__code-frame": "^7.0.6",
     "@types/node": "^18.15.11",
     "@types/react": "^19.0.8",
     "@types/react-dom": "^19.0.3",
     "@types/semver": "^7.7.0",
     "@types/uuid": "^10.0.0",
+    "deepagents": "^1.9.0",
     "jose": "^6.0.10",
+    "langchain": "^1.2.30",
     "postgres": "^3.4.5",
-    "prettier": "^2.8.3",
     "typescript": "^4.9.5 || ^5.4.5",
     "vitest": "^3.2.4",
     "wait-port": "^1.1.0",
-    "@langchain/langgraph": "1.2.3",
-    "@langchain/langgraph-checkpoint": "1.0.1",
-    "@langchain/langgraph-sdk": "1.7.3"
+    "@langchain/langgraph-checkpoint": "1.0.2",
+    "@langchain/langgraph-sdk": "1.9.0",
+    "@langchain/langgraph": "1.3.0"
   },
   "scripts": {
-    "clean": "rm -rf dist/ .turbo/ ./tests/graphs/.langgraph_api/",
+    "clean": "rm -rf dist/ .turbo/ ./tests/graphs/.langgraph_api/ ./tests/protocol-v2/graphs/.langgraph_api/",
     "build": "pnpm turbo build:internal --filter=@langchain/langgraph-api",
     "build:internal": "pnpm clean && node scripts/build.mjs",
     "dev": "tsx ./tests/utils.server.mts --dev",
     "prepublish": "pnpm build",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "format": "prettier --write .",
-    "format:check": "prettier --check ."
+    "test:protocol-v2": "vitest run tests/protocol-v2"
   }
 }