@langchain/langgraph-api 1.2.4 → 1.3.0

package/dist/protocol/service.d.mts

@@ -103,7 +103,11 @@ export declare class ProtocolService {
 }
 /**
  * Check whether a protocol event matches an SSE event sink filter.
- * Mirrors the subscription matching logic in {@link RunProtocolSession}.
+ *
+ * Shares its channel inference and namespace matching with
+ * {@link RunProtocolSession} (and the core streaming toolkit) so SSE and
+ * WebSocket subscribers apply identical semantics, including dynamic
+ * namespace-suffix normalization.
  */
 export declare function matchesSinkFilter(filter: EventSinkFilter, event: ProtocolEvent): boolean;
 export {};

package/dist/protocol/service.mjs

@@ -1,6 +1,6 @@
+import { inferChannel, isPrefixMatch } from "@langchain/langgraph/stream";
 import { v7 as uuid7 } from "uuid";
 import { getAssistantId } from "../graph/load.mjs";
-import { isSupportedChannel, isRecord as isRecordInternal, } from "./session/internal-types.mjs";
 import { PROTOCOL_STREAM_RUN_KEY } from "./constants.mjs";
 import { RunProtocolSession } from "./session/index.mjs";
 const DEFAULT_RUN_STREAM_MODES = [
@@ -564,35 +564,24 @@ export class ProtocolService {
         };
     }
 }
-function isPrefixMatch(namespace, prefix) {
-    if (prefix.length > namespace.length)
-        return false;
-    return prefix.every((segment, i) => namespace[i] === segment);
-}
 /**
  * Check whether a protocol event matches an SSE event sink filter.
- * Mirrors the subscription matching logic in {@link RunProtocolSession}.
+ *
+ * Shares its channel inference and namespace matching with
+ * {@link RunProtocolSession} (and the core streaming toolkit) so SSE and
+ * WebSocket subscribers apply identical semantics, including dynamic
+ * namespace-suffix normalization.
  */
 export function matchesSinkFilter(filter, event) {
     if (filter.since != null && (event.seq ?? 0) <= filter.since)
         return false;
-    const channel = event.method === "input.requested"
-        ? "input"
-        : isSupportedChannel(event.method)
-            ? event.method
-            : undefined;
+    // `inferChannel` resolves named custom channels to `custom:<name>`; a bare
+    // `custom` filter still matches via the prefix check below.
+    const channel = inferChannel(event);
     if (channel == null)
         return false;
-    let channelMatched = filter.channels.has(channel);
-    if (!channelMatched && channel === "custom") {
-        const params = event.params;
-        const eventName = isRecordInternal(params.data) && typeof params.data.name === "string"
-            ? params.data.name
-            : undefined;
-        if (eventName != null) {
-            channelMatched = filter.channels.has(`custom:${eventName}`);
-        }
-    }
+    const channelMatched = filter.channels.has(channel) ||
+        (channel.startsWith("custom:") && filter.channels.has("custom"));
     if (!channelMatched)
         return false;
     if (filter.namespaces == null || filter.namespaces.length === 0) {

package/dist/protocol/session/index.mjs

@@ -1,7 +1,8 @@
+import { inferChannel, isSupportedChannel } from "@langchain/langgraph/stream";
 import { v7 as uuid7 } from "uuid";
 import { serialiseAsDict, serializeError } from "../../utils/serde.mjs";
 import { normalizeInputRequestedData, normalizeToolData, stripInterruptsFromValues, toLifecycleStatus, } from "./event-normalizers.mjs";
-import { SUPPORTED_CHANNELS, isRecord, isSupportedChannel, } from "./internal-types.mjs";
+import { isRecord } from "./internal-types.mjs";
 import { guessGraphName, isPrefixMatch, normalizeNamespace, parseEventName, toNamespaceKey, } from "./namespace.mjs";
 import { normalizeProtocolStatePayload } from "./state-normalizers.mjs";
 /**
@@ -305,15 +306,20 @@ export class RunProtocolSession {
             case "tools":
                 await this.pushEvent(this.createEvent("tools", namespace, normalizeToolData(event.data, event.id ?? uuid7())));
                 return;
-            default:
-                // Route unknown methods as named custom events. This allows
-                // reducers to emit("a2a", data) and have it appear on the
-                // custom channel with name set for client-side filtering.
+            default: {
+                // Route unknown methods as named custom events. Extension
+                // StreamChannels emit `custom:<name>` on the wire (matching
+                // Python's mux); strip the prefix so `custom:<name>`
+                // subscriptions match on `data.name === <name>`.
+                const channelName = method.startsWith("custom:")
+                    ? method.slice("custom:".length)
+                    : method;
                 await this.pushEvent(this.createEvent("custom", namespace, {
-                    name: method,
+                    name: channelName,
                     payload: event.data,
                 }));
                 return;
+            }
         }
     }
     /**
@@ -367,8 +373,21 @@ export class RunProtocolSession {
                 await this.pushEvent(this.createEvent("checkpoints", namespace, data));
                 return true;
             }
-            default:
-                return false;
+            default: {
+                if (!method.startsWith("custom:")) {
+                    return false;
+                }
+                const channelName = method.slice("custom:".length);
+                if (!channelName) {
+                    return false;
+                }
+                await this.ensureNamespaces(namespace);
+                await this.pushEvent(this.createEvent("custom", namespace, {
+                    name: channelName,
+                    payload: data,
+                }));
+                return true;
+            }
         }
     }
     /**
@@ -472,25 +491,13 @@ export class RunProtocolSession {
      * @returns Whether the event matches channel and namespace filters.
      */
     matchesSubscription(subscription, event) {
-        const channel = event.method === "input.requested"
-            ? "input"
-            : isSupportedChannel(event.method)
-                ? event.method
-                : undefined;
+        // `inferChannel` resolves named custom channels to `custom:<name>`; a bare
+        // `custom` subscription still matches via the prefix check below.
+        const channel = inferChannel(event);
         if (channel == null)
             return false;
-        // Support "custom:name" subscriptions: "custom:a2a" matches custom
-        // events with data.name === "a2a", while "custom" matches all.
-        let channelMatched = subscription.channels.has(channel);
-        if (!channelMatched && channel === "custom") {
-            const params = event.params;
-            const eventName = isRecord(params.data) && typeof params.data.name === "string"
-                ? params.data.name
-                : undefined;
-            if (eventName != null) {
-                channelMatched = subscription.channels.has(`custom:${eventName}`);
-            }
-        }
+        const channelMatched = subscription.channels.has(channel) ||
+            (channel.startsWith("custom:") && subscription.channels.has("custom"));
         if (!channelMatched)
             return false;
         if (subscription.namespaces == null ||
@@ -562,9 +569,7 @@ export class RunProtocolSession {
             await this.sendError(command.id, "invalid_argument", "subscription.subscribe requires a non-empty channels array.");
             return;
         }
-        const channels = rawChannels.filter((value) => typeof value === "string" &&
-            (SUPPORTED_CHANNELS.has(value) ||
-                value.startsWith("custom:")));
+        const channels = rawChannels.filter((value) => typeof value === "string" && isSupportedChannel(value));
         if (channels.length !== rawChannels.length) {
             await this.sendError(command.id, "invalid_argument", "subscription.subscribe received an unsupported channel.");
             return;
@@ -648,9 +653,7 @@ export class RunProtocolSession {
         if (!Array.isArray(rawChannels) || rawChannels.length === 0) {
             return this.error(command.id, "invalid_argument", "subscription.subscribe requires a non-empty channels array.", meta);
         }
-        const channels = rawChannels.filter((value) => typeof value === "string" &&
-            (SUPPORTED_CHANNELS.has(value) ||
-                value.startsWith("custom:")));
+        const channels = rawChannels.filter((value) => typeof value === "string" && isSupportedChannel(value));
         if (channels.length !== rawChannels.length) {
             return this.error(command.id, "invalid_argument", "subscription.subscribe received an unsupported channel.", meta);
         }

package/dist/protocol/session/internal-types.d.mts

@@ -47,10 +47,6 @@ export type ProtocolEventDataMap = {
     input: ProtocolEventByMethod<"input">["params"]["data"];
     tasks: ProtocolEventByMethod<"tasks">["params"]["data"];
 };
-/**
- * Channel names supported by the run-scoped protocol session.
- */
-export declare const SUPPORTED_CHANNELS: Set<SupportedChannel>;
 /**
  * Checks whether a value is a non-null object record.
  *
@@ -58,10 +54,3 @@ export declare const SUPPORTED_CHANNELS: Set<SupportedChannel>;
  * @returns Whether the value can be treated as a keyed object.
  */
 export declare const isRecord: (value: unknown) => value is Record<string, unknown>;
-/**
- * Checks whether a channel name is supported by the session transport.
- *
- * @param value - Raw channel name.
- * @returns Whether the name matches a supported protocol channel.
- */
-export declare const isSupportedChannel: (value: string) => value is SupportedChannel;

package/dist/protocol/session/internal-types.mjs

@@ -1,17 +1,3 @@
-/**
- * Channel names supported by the run-scoped protocol session.
- */
-export const SUPPORTED_CHANNELS = new Set([
-    "values",
-    "updates",
-    "checkpoints",
-    "messages",
-    "tools",
-    "custom",
-    "lifecycle",
-    "input",
-    "tasks",
-]);
 /**
  * Checks whether a value is a non-null object record.
  *
@@ -19,10 +5,3 @@ export const SUPPORTED_CHANNELS = new Set([
  * @returns Whether the value can be treated as a keyed object.
  */
 export const isRecord = (value) => typeof value === "object" && value !== null;
-/**
- * Checks whether a channel name is supported by the session transport.
- *
- * @param value - Raw channel name.
- * @returns Whether the name matches a supported protocol channel.
- */
-export const isSupportedChannel = (value) => SUPPORTED_CHANNELS.has(value);

package/dist/protocol/session/namespace.d.mts

@@ -1,4 +1,11 @@
+import { isPrefixMatch, normalizeNamespaceSegment } from "@langchain/langgraph/stream";
 import type { Namespace } from "../types.mjs";
+/**
+ * Namespace prefix matching and dynamic-suffix normalization are shared with
+ * the core streaming toolkit so the server, the SDK, and custom transports all
+ * agree on subscription semantics.
+ */
+export { isPrefixMatch, normalizeNamespaceSegment };
 /**
  * Converts a namespace array into a stable internal lookup key.
  *
@@ -6,13 +13,6 @@ import type { Namespace } from "../types.mjs";
  * @returns A string key that preserves segment boundaries.
  */
 export declare const toNamespaceKey: (namespace: Namespace) => string;
-/**
- * Strips dynamic suffixes from a namespace segment for display purposes.
- *
- * @param segment - Raw namespace segment.
- * @returns The stable graph-oriented portion of the segment.
- */
-export declare const normalizeNamespaceSegment: (segment: string) => string;
 /**
  * Preserves raw namespace segments in protocol events.
  *
@@ -30,14 +30,6 @@ export declare const parseEventName: (event: string) => {
     method: string;
     namespace: string[];
 };
-/**
- * Checks whether a namespace starts with a requested prefix.
- *
- * @param namespace - Event namespace to test.
- * @param prefix - Subscription namespace prefix.
- * @returns Whether the namespace matches the prefix semantics.
- */
-export declare const isPrefixMatch: (namespace: Namespace, prefix: Namespace) => boolean;
 /**
  * Guesses a human-readable graph name from a namespace.
  *

package/dist/protocol/session/namespace.mjs

@@ -1,3 +1,10 @@
+import { isPrefixMatch, normalizeNamespaceSegment, } from "@langchain/langgraph/stream";
+/**
+ * Namespace prefix matching and dynamic-suffix normalization are shared with
+ * the core streaming toolkit so the server, the SDK, and custom transports all
+ * agree on subscription semantics.
+ */
+export { isPrefixMatch, normalizeNamespaceSegment };
 /**
  * Converts a namespace array into a stable internal lookup key.
  *
@@ -5,13 +12,6 @@
  * @returns A string key that preserves segment boundaries.
  */
 export const toNamespaceKey = (namespace) => namespace.join("\0");
-/**
- * Strips dynamic suffixes from a namespace segment for display purposes.
- *
- * @param segment - Raw namespace segment.
- * @returns The stable graph-oriented portion of the segment.
- */
-export const normalizeNamespaceSegment = (segment) => segment.split(":")[0];
 /**
  * Preserves raw namespace segments in protocol events.
  *
@@ -29,25 +29,6 @@ export const parseEventName = (event) => {
     const [method, ...namespace] = event.split("|");
     return { method, namespace };
 };
-/**
- * Checks whether a namespace starts with a requested prefix.
- *
- * @param namespace - Event namespace to test.
- * @param prefix - Subscription namespace prefix.
- * @returns Whether the namespace matches the prefix semantics.
- */
-export const isPrefixMatch = (namespace, prefix) => {
-    if (prefix.length > namespace.length)
-        return false;
-    return prefix.every((segment, index) => {
-        const candidate = namespace[index];
-        if (candidate === segment)
-            return true;
-        if (segment.includes(":"))
-            return false;
-        return normalizeNamespaceSegment(candidate) === segment;
-    });
-};
 /**
  * Guesses a human-readable graph name from a namespace.
  *

package/dist/stream.mjs

@@ -1,6 +1,6 @@
 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 { convertToProtocolEvent, isCheckpointEnvelope, 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";
@@ -136,14 +136,10 @@ export async function* streamState(run, options) {
             continue;
         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.
+            // Pregel stream chunks are `[ns, mode, payload]`. Lightweight checkpoint
+            // envelopes arrive as a separate `checkpoints` chunk before `values`.
             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;
@@ -159,9 +155,26 @@ export async function* streamState(run, options) {
                 }
             }
             else if (mode === "checkpoints") {
-                const debugCheckpoint = preprocessDebugCheckpoint(chunk);
+                if (isCheckpointEnvelope(chunk)) {
+                    // Lightweight envelopes pair with `values` on the v3 path.
+                    // Legacy `checkpoints` stream mode consumers expect full debug
+                    // snapshots (`values` / `metadata` / `next`) from `mapDebugCheckpoint`.
+                    if (!userStreamMode.includes("checkpoints")) {
+                        const sseEvent = kwargs.subgraphs && ns?.length
+                            ? `checkpoints|${ns.join("|")}`
+                            : "checkpoints";
+                        yield { event: sseEvent, data: chunk };
+                    }
+                    continue;
+                }
+                const debugPayload = chunk;
+                const debugCheckpoint = preprocessDebugCheckpoint(debugPayload);
                 options?.onCheckpoint?.(debugCheckpoint);
-                data = debugCheckpoint;
+                data = {
+                    values: debugPayload.values,
+                    metadata: debugPayload.metadata,
+                    next: debugPayload.next,
+                };
             }
             else if (mode === "tasks") {
                 const debugTask = preprocessDebugCheckpointTask(chunk);
@@ -170,20 +183,6 @@ 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) {
@@ -270,13 +269,12 @@ 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 [namespace, mode, payload] = tuple;
         const events = convertToProtocolEvent({
             namespace: namespace ?? [],
             mode,
             payload,
             seq,
-            meta: meta,
         });
         seq += events.length;
         for (const event of events) {
@@ -411,6 +409,7 @@ export async function* streamStateV2(run, options) {
         const normalized = mode === "tools" ||
             mode === "updates" ||
             mode === "custom" ||
+            mode.startsWith("custom:") ||
             mode === "messages" ||
             mode === "checkpoints" ||
             mode === "lifecycle";

package/dist/vitest.config.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("vitest/config.js").UserConfigFnObject;
+declare const _default: import("vitest/config").ViteUserConfigFnObject;
 export default _default;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@langchain/langgraph-api",
-  "version": "1.2.4",
+  "version": "1.3.0",
   "type": "module",
   "engines": {
     "node": "^18.19.0 || >=20.16.0"
@@ -61,7 +61,7 @@
     "dedent": "^1.5.3",
     "dotenv": "^16.4.7",
     "exit-hook": "^4.0.0",
-    "hono": "^4.12.18",
+    "hono": "^4.12.21",
     "langsmith": ">=0.5.19 <1.0.0",
     "open": "^10.1.0",
     "semver": "^7.7.1",
@@ -72,11 +72,11 @@
     "winston": "^3.17.0",
     "winston-console-format": "^1.0.8",
     "zod": "^3.25.76 || ^4",
-    "@langchain/langgraph-ui": "1.2.4"
+    "@langchain/langgraph-ui": "1.3.0"
   },
   "peerDependencies": {
-    "@langchain/core": "^1.1.44",
-    "@langchain/langgraph": "^0.2.57 || ^0.3.0 || ^0.4.0 || ^1.0.0-alpha || ^1.0.0 || ^1.3.1-rc.0",
+    "@langchain/core": "^1.1.48",
+    "@langchain/langgraph": "^1.3.6",
     "@langchain/langgraph-checkpoint": "~0.0.16 || ^0.1.0 || ~1.0.0",
     "@langchain/langgraph-sdk": "^1.9.3-rc.0",
     "typescript": "^5.5.4"
@@ -87,23 +87,23 @@
     }
   },
   "devDependencies": {
-    "@langchain/core": "^1.1.44",
+    "@langchain/core": "^1.1.48",
     "@types/babel__code-frame": "^7.0.6",
     "@types/node": "^18.15.11",
-    "@types/react": "^19.0.8",
+    "@types/react": "^19.2.16",
     "@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",
+    "langchain": "^1.4.4",
     "postgres": "^3.4.5",
     "typescript": "^4.9.5 || ^5.4.5",
-    "vitest": "^3.2.4",
+    "vitest": "^4.1.0",
     "wait-port": "^1.1.0",
-    "@langchain/langgraph": "1.3.3",
+    "@langchain/langgraph": "1.3.7",
     "@langchain/langgraph-checkpoint": "1.0.4",
-    "@langchain/langgraph-sdk": "1.9.11"
+    "@langchain/langgraph-sdk": "1.9.19"
   },
   "scripts": {
     "clean": "rm -rf dist/ .turbo/ ./tests/graphs/.langgraph_api/ ./tests/protocol-v2/graphs/.langgraph_api/",