@langchain/langgraph 1.3.6 → 1.3.7

package/dist/stream/index.cjs

@@ -8,4 +8,5 @@ require("./transformers/values.cjs");
 require("./transformers/index.cjs");
 require("./types.cjs");
 require("./run-stream.cjs");
+require("./subscription.cjs");
 require("@langchain/core/language_models/stream");

package/dist/stream/index.d.cts

@@ -1,5 +1,5 @@
 import { AgentStatus, ChatModelStream as ChatModelStream$1, InferExtensions, InterruptPayload, LifecycleCause, LifecycleData, MessagesEventData, Namespace, NativeStreamTransformer, ProtocolEvent, StreamEmitter, StreamTransformer, ToolCallStatus, ToolCallStream, ToolsEventData, UpdatesEventData, UsageInfo, isNativeTransformer } from "./types.cjs";
-import { StreamChannel } from "./stream-channel.cjs";
+import { StreamChannel, isStreamChannel } from "./stream-channel.cjs";
 import { ConvertToProtocolEventOptions, STREAM_EVENTS_V3_MODES, convertToProtocolEvent, isCheckpointEnvelope } from "./convert.cjs";
 import { REJECT_VALUES, RESOLVE_VALUES, StreamHandle, StreamMux, SubgraphDiscovery } from "./mux.cjs";
 import { LifecycleEntry, LifecycleTransformerOptions } from "./transformers/types.cjs";
@@ -8,5 +8,6 @@ import { createMessagesTransformer } from "./transformers/messages.cjs";
 import { SubgraphDiscoveryProjection, SubgraphDiscoveryTransformerOptions, createSubgraphDiscoveryTransformer, filterSubgraphHandles } from "./transformers/subgraphs.cjs";
 import { createValuesTransformer } from "./transformers/values.cjs";
 import { CreateGraphRunStreamOptions, GraphRunStream, SET_LIFECYCLE_ITERABLE, SET_MESSAGES_ITERABLE, SET_VALUES_LOG, SubgraphRunStream, createGraphRunStream } from "./run-stream.cjs";
+import { MatchableEvent, SUPPORTED_CHANNELS, inferChannel, isPrefixMatch, isSupportedChannel, matchesSubscription, normalizeNamespaceSegment } from "./subscription.cjs";
 import { ChatModelStream as ChatModelStreamImpl } from "@langchain/core/language_models/stream";
 export { ChatModelStreamImpl };

package/dist/stream/index.d.ts

@@ -1,5 +1,5 @@
 import { AgentStatus, ChatModelStream as ChatModelStream$1, InferExtensions, InterruptPayload, LifecycleCause, LifecycleData, MessagesEventData, Namespace, NativeStreamTransformer, ProtocolEvent, StreamEmitter, StreamTransformer, ToolCallStatus, ToolCallStream, ToolsEventData, UpdatesEventData, UsageInfo, isNativeTransformer } from "./types.js";
-import { StreamChannel } from "./stream-channel.js";
+import { StreamChannel, isStreamChannel } from "./stream-channel.js";
 import { ConvertToProtocolEventOptions, STREAM_EVENTS_V3_MODES, convertToProtocolEvent, isCheckpointEnvelope } from "./convert.js";
 import { REJECT_VALUES, RESOLVE_VALUES, StreamHandle, StreamMux, SubgraphDiscovery } from "./mux.js";
 import { LifecycleEntry, LifecycleTransformerOptions } from "./transformers/types.js";
@@ -8,5 +8,6 @@ import { createMessagesTransformer } from "./transformers/messages.js";
 import { SubgraphDiscoveryProjection, SubgraphDiscoveryTransformerOptions, createSubgraphDiscoveryTransformer, filterSubgraphHandles } from "./transformers/subgraphs.js";
 import { createValuesTransformer } from "./transformers/values.js";
 import { CreateGraphRunStreamOptions, GraphRunStream, SET_LIFECYCLE_ITERABLE, SET_MESSAGES_ITERABLE, SET_VALUES_LOG, SubgraphRunStream, createGraphRunStream } from "./run-stream.js";
+import { MatchableEvent, SUPPORTED_CHANNELS, inferChannel, isPrefixMatch, isSupportedChannel, matchesSubscription, normalizeNamespaceSegment } from "./subscription.js";
 import { ChatModelStream as ChatModelStreamImpl } from "@langchain/core/language_models/stream";
 export { ChatModelStreamImpl };

package/dist/stream/index.js

@@ -8,5 +8,6 @@ import "./transformers/values.js";
 import "./transformers/index.js";
 import "./types.js";
 import "./run-stream.js";
+import "./subscription.js";
 import { ChatModelStream as ChatModelStreamImpl } from "@langchain/core/language_models/stream";
 export { ChatModelStreamImpl };

package/dist/stream/stream-channel.d.cts

@@ -124,6 +124,14 @@ declare class StreamChannel<T> implements AsyncIterable<T> {
   _fail(err: unknown): void;
   [Symbol.asyncIterator](): AsyncIterator<T>;
 }
+/**
+ * Type guard that tests whether a value is a {@link StreamChannel}.
+ *
+ * Uses a symbol brand rather than `instanceof` so channels built
+ * against a different copy of this package (e.g. one bundled by the
+ * `langchain` umbrella package) are still recognised.
+ */
+declare function isStreamChannel(value: unknown): value is StreamChannel<unknown>;
 //#endregion
-export { StreamChannel };
+export { StreamChannel, isStreamChannel };
 //# sourceMappingURL=stream-channel.d.cts.map

package/dist/stream/stream-channel.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"stream-channel.d.cts","names":[],"sources":["../../src/stream/stream-channel.ts"],"mappings":";;AA0BA;;;;;AAIA;;;;;;;;;;;;AA+BA;;;;;;;cAnCa,oBAAA;AAAA,UAII,+BAAA;EAsE6B;;;;;EAhE5C,KAAA;EA6H2C;;;;;EAvH3C,OAAA;EA+MwC;;;;;EAzMxC,SAAA,IAAa,IAAA,EAAM,CAAA;AAAA;;;;;;;;;;;cAaR,aAAA,eAA4B,aAAA,CAAc,CAAA;EAAA;EA6BvC;EAAA,UA3BJ,oBAAA;EA2BsB;EAAA,SAxBvB,WAAA;EAQT,WAAA,CAAY,IAAA;EA0BM;;;;EAAA,OAlBX,KAAA,GAAA,CAAA,GAAY,aAAA,CAAc,CAAA;EAiC5B;;;;EAAA,OAzBE,MAAA,GAAA,CAAU,IAAA,WAAe,aAAA,CAAc,CAAA;EA2D9C;;;;;;EAAA,OAjDO,UAAA,CAAW,KAAA,YAAiB,KAAA,IAAS,aAAA;EA6D1C;;;;;EA9CF,IAAA,CAAK,IAAA,EAAM,CAAA;EAiGP;;;;;EAtFJ,OAAA,CAAQ,OAAA,YAAc,aAAA,CAAc,CAAA;EA6GnB;;;;EAtFjB,eAAA,CAAgB,OAAA,YAAc,aAAA,CAAc,CAAA;EAgGtC;;;;;EArFN,aAAA,CACE,OAAA,GAAS,+BAAA,CAAgC,CAAA,IACxC,cAAA,CAAe,UAAA;EAuFuB;;;;;EA/CzC,GAAA,CAAI,KAAA,WAAgB,CAAA;;MAUhB,IAAA,CAAA;;MAKA,IAAA,CAAA;;EAKJ,KAAA,CAAA;;EAMA,IAAA,CAAK,GAAA;;EAOL,KAAA,CAAM,EAAA,GAAK,IAAA,EAAM,CAAA;;EAKjB,MAAA,CAAA;;EAKA,KAAA,CAAM,GAAA;EAAA,CAIL,MAAA,CAAO,aAAA,KAAkB,aAAA,CAAc,CAAA;AAAA"}
+{"version":3,"file":"stream-channel.d.cts","names":[],"sources":["../../src/stream/stream-channel.ts"],"mappings":";;AA0BA;;;;;AAIA;;;;;;;;;;;;AA+BA;;;;;;;cAnCa,oBAAA;AAAA,UAII,+BAAA;EAsE6B;;;;;EAhE5C,KAAA;EA6H2C;;;;;EAvH3C,OAAA;EA+MwC;;;;;EAzMxC,SAAA,IAAa,IAAA,EAAM,CAAA;AAAA;;;;;;;;;;;cAaR,aAAA,eAA4B,aAAA,CAAc,CAAA;EAAA;EA6BvC;EAAA,UA3BJ,oBAAA;EA2BsB;EAAA,SAxBvB,WAAA;EAQT,WAAA,CAAY,IAAA;EA0BM;;;;EAAA,OAlBX,KAAA,GAAA,CAAA,GAAY,aAAA,CAAc,CAAA;EAiC5B;;;;EAAA,OAzBE,MAAA,GAAA,CAAU,IAAA,WAAe,aAAA,CAAc,CAAA;EA2D9C;;;;;;EAAA,OAjDO,UAAA,CAAW,KAAA,YAAiB,KAAA,IAAS,aAAA;EA6D1C;;;;;EA9CF,IAAA,CAAK,IAAA,EAAM,CAAA;EAiGP;;;;;EAtFJ,OAAA,CAAQ,OAAA,YAAc,aAAA,CAAc,CAAA;EA6GnB;;;;EAtFjB,eAAA,CAAgB,OAAA,YAAc,aAAA,CAAc,CAAA;EAgGtC;;;;;EArFN,aAAA,CACE,OAAA,GAAS,+BAAA,CAAgC,CAAA,IACxC,cAAA,CAAe,UAAA;EAuFuB;AAiB3C;;;;EAhEE,GAAA,CAAI,KAAA,WAAgB,CAAA;EAkEnB;EAAA,IAxDG,IAAA,CAAA;EAwDmB;EAAA,IAnDnB,IAAA,CAAA;;EAKJ,KAAA,CAAA;;EAMA,IAAA,CAAK,GAAA;;EAOL,KAAA,CAAM,EAAA,GAAK,IAAA,EAAM,CAAA;;EAKjB,MAAA,CAAA;;EAKA,KAAA,CAAM,GAAA;EAAA,CAIL,MAAA,CAAO,aAAA,KAAkB,aAAA,CAAc,CAAA;AAAA;;;;;;;;iBAiB1B,eAAA,CACd,KAAA,YACC,KAAA,IAAS,aAAA"}

package/dist/stream/stream-channel.d.ts

@@ -124,6 +124,14 @@ declare class StreamChannel<T> implements AsyncIterable<T> {
   _fail(err: unknown): void;
   [Symbol.asyncIterator](): AsyncIterator<T>;
 }
+/**
+ * Type guard that tests whether a value is a {@link StreamChannel}.
+ *
+ * Uses a symbol brand rather than `instanceof` so channels built
+ * against a different copy of this package (e.g. one bundled by the
+ * `langchain` umbrella package) are still recognised.
+ */
+declare function isStreamChannel(value: unknown): value is StreamChannel<unknown>;
 //#endregion
-export { StreamChannel };
+export { StreamChannel, isStreamChannel };
 //# sourceMappingURL=stream-channel.d.ts.map

package/dist/stream/stream-channel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stream-channel.d.ts","names":[],"sources":["../../src/stream/stream-channel.ts"],"mappings":";;AA0BA;;;;;AAIA;;;;;;;;;;;;AA+BA;;;;;;;cAnCa,oBAAA;AAAA,UAII,+BAAA;EAsE6B;;;;;EAhE5C,KAAA;EA6H2C;;;;;EAvH3C,OAAA;EA+MwC;;;;;EAzMxC,SAAA,IAAa,IAAA,EAAM,CAAA;AAAA;;;;;;;;;;;cAaR,aAAA,eAA4B,aAAA,CAAc,CAAA;EAAA;EA6BvC;EAAA,UA3BJ,oBAAA;EA2BsB;EAAA,SAxBvB,WAAA;EAQT,WAAA,CAAY,IAAA;EA0BM;;;;EAAA,OAlBX,KAAA,GAAA,CAAA,GAAY,aAAA,CAAc,CAAA;EAiC5B;;;;EAAA,OAzBE,MAAA,GAAA,CAAU,IAAA,WAAe,aAAA,CAAc,CAAA;EA2D9C;;;;;;EAAA,OAjDO,UAAA,CAAW,KAAA,YAAiB,KAAA,IAAS,aAAA;EA6D1C;;;;;EA9CF,IAAA,CAAK,IAAA,EAAM,CAAA;EAiGP;;;;;EAtFJ,OAAA,CAAQ,OAAA,YAAc,aAAA,CAAc,CAAA;EA6GnB;;;;EAtFjB,eAAA,CAAgB,OAAA,YAAc,aAAA,CAAc,CAAA;EAgGtC;;;;;EArFN,aAAA,CACE,OAAA,GAAS,+BAAA,CAAgC,CAAA,IACxC,cAAA,CAAe,UAAA;EAuFuB;;;;;EA/CzC,GAAA,CAAI,KAAA,WAAgB,CAAA;;MAUhB,IAAA,CAAA;;MAKA,IAAA,CAAA;;EAKJ,KAAA,CAAA;;EAMA,IAAA,CAAK,GAAA;;EAOL,KAAA,CAAM,EAAA,GAAK,IAAA,EAAM,CAAA;;EAKjB,MAAA,CAAA;;EAKA,KAAA,CAAM,GAAA;EAAA,CAIL,MAAA,CAAO,aAAA,KAAkB,aAAA,CAAc,CAAA;AAAA"}
+{"version":3,"file":"stream-channel.d.ts","names":[],"sources":["../../src/stream/stream-channel.ts"],"mappings":";;AA0BA;;;;;AAIA;;;;;;;;;;;;AA+BA;;;;;;;cAnCa,oBAAA;AAAA,UAII,+BAAA;EAsE6B;;;;;EAhE5C,KAAA;EA6H2C;;;;;EAvH3C,OAAA;EA+MwC;;;;;EAzMxC,SAAA,IAAa,IAAA,EAAM,CAAA;AAAA;;;;;;;;;;;cAaR,aAAA,eAA4B,aAAA,CAAc,CAAA;EAAA;EA6BvC;EAAA,UA3BJ,oBAAA;EA2BsB;EAAA,SAxBvB,WAAA;EAQT,WAAA,CAAY,IAAA;EA0BM;;;;EAAA,OAlBX,KAAA,GAAA,CAAA,GAAY,aAAA,CAAc,CAAA;EAiC5B;;;;EAAA,OAzBE,MAAA,GAAA,CAAU,IAAA,WAAe,aAAA,CAAc,CAAA;EA2D9C;;;;;;EAAA,OAjDO,UAAA,CAAW,KAAA,YAAiB,KAAA,IAAS,aAAA;EA6D1C;;;;;EA9CF,IAAA,CAAK,IAAA,EAAM,CAAA;EAiGP;;;;;EAtFJ,OAAA,CAAQ,OAAA,YAAc,aAAA,CAAc,CAAA;EA6GnB;;;;EAtFjB,eAAA,CAAgB,OAAA,YAAc,aAAA,CAAc,CAAA;EAgGtC;;;;;EArFN,aAAA,CACE,OAAA,GAAS,+BAAA,CAAgC,CAAA,IACxC,cAAA,CAAe,UAAA;EAuFuB;AAiB3C;;;;EAhEE,GAAA,CAAI,KAAA,WAAgB,CAAA;EAkEnB;EAAA,IAxDG,IAAA,CAAA;EAwDmB;EAAA,IAnDnB,IAAA,CAAA;;EAKJ,KAAA,CAAA;;EAMA,IAAA,CAAK,GAAA;;EAOL,KAAA,CAAM,EAAA,GAAK,IAAA,EAAM,CAAA;;EAKjB,MAAA,CAAA;;EAKA,KAAA,CAAM,GAAA;EAAA,CAIL,MAAA,CAAO,aAAA,KAAkB,aAAA,CAAc,CAAA;AAAA;;;;;;;;iBAiB1B,eAAA,CACd,KAAA,YACC,KAAA,IAAS,aAAA"}

package/dist/stream/subscription.cjs

@@ -0,0 +1,136 @@
+//#region src/stream/subscription.ts
+/**
+* Strip dynamic suffixes (after `:`) from a namespace segment.
+*
+* Server-emitted namespaces contain runtime-generated suffixes like
+* `"fetcher:abc-uuid"`, while user-supplied subscription filters are typically
+* static names (`"fetcher"`). Mirrors `normalize_namespace_segment` in
+* `api/langgraph_api/protocol/namespace.py`.
+*
+* @param segment - Raw namespace segment.
+* @returns The stable graph-oriented portion of the segment.
+*/
+function normalizeNamespaceSegment(segment) {
+	const idx = segment.indexOf(":");
+	return idx === -1 ? segment : segment.slice(0, idx);
+}
+/**
+* Whether `namespace` starts with `prefix`.
+*
+* Segments are compared literally first; if the prefix segment itself contains
+* no `:`, the candidate segment is also compared after its dynamic suffix is
+* stripped (see {@link normalizeNamespaceSegment}). This mirrors
+* `is_prefix_match` in `api/langgraph_api/protocol/namespace.py` so server-side
+* filtering and client-side per-subscription narrowing stay consistent.
+*
+* @param namespace - Event namespace to test.
+* @param prefix - Subscription namespace prefix.
+*/
+function isPrefixMatch(namespace, prefix) {
+	if (prefix.length > namespace.length) return false;
+	for (let i = 0; i < prefix.length; i += 1) {
+		const segment = prefix[i];
+		const candidate = namespace[i];
+		if (candidate === segment) continue;
+		if (segment.includes(":")) return false;
+		if (normalizeNamespaceSegment(candidate) === segment) continue;
+		return false;
+	}
+	return true;
+}
+function namespaceMatches(eventNamespace, prefixes, depth) {
+	if (!prefixes || prefixes.length === 0) return true;
+	return prefixes.some((prefix) => {
+		if (!isPrefixMatch(eventNamespace, prefix)) return false;
+		if (depth === void 0) return true;
+		return eventNamespace.length - prefix.length <= depth;
+	});
+}
+/**
+* The base protocol subscription channels, excluding the templated
+* `custom:<name>` form. This is the runtime counterpart to the `Channel`
+* union from `@langchain/protocol` and mirrors the channel set a server
+* recognizes when filtering its event sinks.
+*/
+const SUPPORTED_CHANNELS = new Set([
+	"values",
+	"updates",
+	"messages",
+	"tools",
+	"lifecycle",
+	"input",
+	"checkpoints",
+	"tasks",
+	"custom"
+]);
+/**
+* Whether `value` names a protocol subscription channel — either a base
+* channel (`"messages"`, `"values"`, …) or a named custom channel
+* (`"custom:<name>"`). Unknown/future method names return `false`,
+* mirroring {@link inferChannel}.
+*
+* @param value - Candidate channel name.
+*/
+function isSupportedChannel(value) {
+	return SUPPORTED_CHANNELS.has(value) || value.startsWith("custom:");
+}
+/**
+* Maps a protocol event method to its subscription {@link Channel}.
+*
+* Returns `undefined` for unrecognized methods so that new server-side
+* channels (e.g. from extension transformers) don't break existing
+* subscribers. The `custom` method resolves to the named `custom:<name>`
+* channel when the payload carries a `name`, otherwise the bare `custom`
+* channel. Both `"input"` and the wire-level `"input.requested"` map to the
+* `input` channel.
+*
+* @param event - Event whose method should be mapped to a channel.
+*/
+function inferChannel(event) {
+	switch (event.method) {
+		case "values": return "values";
+		case "checkpoints": return "checkpoints";
+		case "updates": return "updates";
+		case "messages": return "messages";
+		case "tools": return "tools";
+		case "custom": {
+			const data = event.params.data;
+			return data?.name != null ? `custom:${data.name}` : "custom";
+		}
+		case "lifecycle": return "lifecycle";
+		case "input":
+		case "input.requested": return "input";
+		case "tasks": return "tasks";
+		default: return;
+	}
+}
+/**
+* Returns whether an event should be delivered for a subscription definition.
+*
+* When the definition carries a `since` replay cursor, events at or before
+* that sequence number are excluded — letting the same predicate drive both
+* live fan-out and buffered replay over a {@link StreamChannel}.
+*
+* @param event - Event being checked for delivery.
+* @param definition - Subscription filter definition to evaluate against.
+*   The optional `since` field (a `seq` cursor) is read leniently because it
+*   is not a declared field on the base {@link SubscribeParams} shape.
+*/
+function matchesSubscription(event, definition) {
+	const since = definition.since;
+	if (typeof since === "number" && (event.seq ?? 0) <= since) return false;
+	const channel = inferChannel(event);
+	if (channel === void 0) return false;
+	const channels = definition.channels;
+	if (!(channels.includes(channel) || channel.startsWith("custom:") && channels.includes("custom"))) return false;
+	return namespaceMatches(event.params.namespace, definition.namespaces, definition.depth);
+}
+//#endregion
+exports.SUPPORTED_CHANNELS = SUPPORTED_CHANNELS;
+exports.inferChannel = inferChannel;
+exports.isPrefixMatch = isPrefixMatch;
+exports.isSupportedChannel = isSupportedChannel;
+exports.matchesSubscription = matchesSubscription;
+exports.normalizeNamespaceSegment = normalizeNamespaceSegment;
+
+//# sourceMappingURL=subscription.cjs.map

package/dist/stream/subscription.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription.cjs","names":[],"sources":["../../src/stream/subscription.ts"],"sourcesContent":["/**\n * Subscription matching and channel inference for the v2 streaming protocol.\n *\n * These helpers are the building blocks a custom transport / server needs to\n * fan protocol events out to subscribers: map an event to its logical\n * {@link Channel} ({@link inferChannel}) and decide whether a buffered event\n * should be delivered for a given {@link SubscribeParams} filter\n * ({@link matchesSubscription}). They are typed against the minimal\n * {@link MatchableEvent} shape so the same predicate works on the core\n * {@link ProtocolEvent} produced by {@link convertToProtocolEvent} /\n * {@link StreamChannel} and on the wire-level `Event` from\n * `@langchain/protocol`.\n */\n\nimport type { Channel, SubscribeParams } from \"@langchain/protocol\";\nimport type { Namespace } from \"./types.js\";\n\n/**\n * Minimal protocol-event shape consumed by {@link inferChannel} and\n * {@link matchesSubscription}.\n *\n * Both the core {@link ProtocolEvent} and the wire-level `Event` from\n * `@langchain/protocol` structurally satisfy this contract, so the same\n * predicates can drive in-process fan-out, buffered replay, and server-side\n * (SSE / WebSocket) event-sink filtering without coupling to a single event\n * type.\n */\nexport interface MatchableEvent {\n  /** Logical stream channel; see {@link inferChannel}. */\n  readonly method: string;\n\n  /** Monotonic sequence number, when present. Used by the `since` cursor. */\n  readonly seq?: number;\n\n  readonly params: {\n    /** Namespace of the node or scope that emitted this event. */\n    readonly namespace: Namespace;\n\n    /** Opaque channel payload; shape depends on `method`. */\n    readonly data?: unknown;\n  };\n}\n\n/**\n * Strip dynamic suffixes (after `:`) from a namespace segment.\n *\n * Server-emitted namespaces contain runtime-generated suffixes like\n * `\"fetcher:abc-uuid\"`, while user-supplied subscription filters are typically\n * static names (`\"fetcher\"`). Mirrors `normalize_namespace_segment` in\n * `api/langgraph_api/protocol/namespace.py`.\n *\n * @param segment - Raw namespace segment.\n * @returns The stable graph-oriented portion of the segment.\n */\nexport function normalizeNamespaceSegment(segment: string): string {\n  const idx = segment.indexOf(\":\");\n  return idx === -1 ? segment : segment.slice(0, idx);\n}\n\n/**\n * Whether `namespace` starts with `prefix`.\n *\n * Segments are compared literally first; if the prefix segment itself contains\n * no `:`, the candidate segment is also compared after its dynamic suffix is\n * stripped (see {@link normalizeNamespaceSegment}). This mirrors\n * `is_prefix_match` in `api/langgraph_api/protocol/namespace.py` so server-side\n * filtering and client-side per-subscription narrowing stay consistent.\n *\n * @param namespace - Event namespace to test.\n * @param prefix - Subscription namespace prefix.\n */\nexport function isPrefixMatch(\n  namespace: Namespace,\n  prefix: Namespace\n): boolean {\n  if (prefix.length > namespace.length) return false;\n  for (let i = 0; i < prefix.length; i += 1) {\n    const segment = prefix[i]!;\n    const candidate = namespace[i]!;\n    if (candidate === segment) continue;\n    if (segment.includes(\":\")) return false;\n    if (normalizeNamespaceSegment(candidate) === segment) continue;\n    return false;\n  }\n  return true;\n}\n\nfunction namespaceMatches(\n  eventNamespace: Namespace,\n  prefixes: Namespace[] | undefined,\n  depth: number | undefined\n): boolean {\n  if (!prefixes || prefixes.length === 0) {\n    return true;\n  }\n\n  return prefixes.some((prefix) => {\n    if (!isPrefixMatch(eventNamespace, prefix)) return false;\n    if (depth === undefined) return true;\n    return eventNamespace.length - prefix.length <= depth;\n  });\n}\n\n/**\n * The base protocol subscription channels, excluding the templated\n * `custom:<name>` form. This is the runtime counterpart to the `Channel`\n * union from `@langchain/protocol` and mirrors the channel set a server\n * recognizes when filtering its event sinks.\n */\nexport const SUPPORTED_CHANNELS = new Set<Channel>([\n  \"values\",\n  \"updates\",\n  \"messages\",\n  \"tools\",\n  \"lifecycle\",\n  \"input\",\n  \"checkpoints\",\n  \"tasks\",\n  \"custom\",\n]);\n\n/**\n * Whether `value` names a protocol subscription channel — either a base\n * channel (`\"messages\"`, `\"values\"`, …) or a named custom channel\n * (`\"custom:<name>\"`). Unknown/future method names return `false`,\n * mirroring {@link inferChannel}.\n *\n * @param value - Candidate channel name.\n */\nexport function isSupportedChannel(value: string): value is Channel {\n  return (\n    SUPPORTED_CHANNELS.has(value as Channel) || value.startsWith(\"custom:\")\n  );\n}\n\n/**\n * Maps a protocol event method to its subscription {@link Channel}.\n *\n * Returns `undefined` for unrecognized methods so that new server-side\n * channels (e.g. from extension transformers) don't break existing\n * subscribers. The `custom` method resolves to the named `custom:<name>`\n * channel when the payload carries a `name`, otherwise the bare `custom`\n * channel. Both `\"input\"` and the wire-level `\"input.requested\"` map to the\n * `input` channel.\n *\n * @param event - Event whose method should be mapped to a channel.\n */\nexport function inferChannel(event: MatchableEvent): Channel | undefined {\n  switch (event.method) {\n    case \"values\":\n      return \"values\";\n    case \"checkpoints\":\n      return \"checkpoints\";\n    case \"updates\":\n      return \"updates\";\n    case \"messages\":\n      return \"messages\";\n    case \"tools\":\n      return \"tools\";\n    case \"custom\": {\n      const data = event.params.data as { name?: string } | undefined;\n      return data?.name != null ? `custom:${data.name}` : \"custom\";\n    }\n    case \"lifecycle\":\n      return \"lifecycle\";\n    case \"input\":\n    case \"input.requested\":\n      return \"input\";\n    case \"tasks\":\n      return \"tasks\";\n    default:\n      return undefined;\n  }\n}\n\n/**\n * Returns whether an event should be delivered for a subscription definition.\n *\n * When the definition carries a `since` replay cursor, events at or before\n * that sequence number are excluded — letting the same predicate drive both\n * live fan-out and buffered replay over a {@link StreamChannel}.\n *\n * @param event - Event being checked for delivery.\n * @param definition - Subscription filter definition to evaluate against.\n *   The optional `since` field (a `seq` cursor) is read leniently because it\n *   is not a declared field on the base {@link SubscribeParams} shape.\n */\nexport function matchesSubscription(\n  event: MatchableEvent,\n  definition: SubscribeParams\n): boolean {\n  const since = (definition as { since?: unknown }).since;\n  if (typeof since === \"number\" && (event.seq ?? 0) <= since) {\n    return false;\n  }\n\n  const channel = inferChannel(event);\n  if (channel === undefined) return false;\n\n  const channels = definition.channels;\n  const channelMatched =\n    channels.includes(channel) ||\n    (channel.startsWith(\"custom:\") && channels.includes(\"custom\"));\n  if (!channelMatched) {\n    return false;\n  }\n\n  return namespaceMatches(\n    event.params.namespace,\n    definition.namespaces,\n    definition.depth\n  );\n}\n"],"mappings":";;;;;;;;;;;;AAsDA,SAAgB,0BAA0B,SAAyB;CACjE,MAAM,MAAM,QAAQ,QAAQ,IAAI;AAChC,QAAO,QAAQ,KAAK,UAAU,QAAQ,MAAM,GAAG,IAAI;;;;;;;;;;;;;;AAerD,SAAgB,cACd,WACA,QACS;AACT,KAAI,OAAO,SAAS,UAAU,OAAQ,QAAO;AAC7C,MAAK,IAAI,IAAI,GAAG,IAAI,OAAO,QAAQ,KAAK,GAAG;EACzC,MAAM,UAAU,OAAO;EACvB,MAAM,YAAY,UAAU;AAC5B,MAAI,cAAc,QAAS;AAC3B,MAAI,QAAQ,SAAS,IAAI,CAAE,QAAO;AAClC,MAAI,0BAA0B,UAAU,KAAK,QAAS;AACtD,SAAO;;AAET,QAAO;;AAGT,SAAS,iBACP,gBACA,UACA,OACS;AACT,KAAI,CAAC,YAAY,SAAS,WAAW,EACnC,QAAO;AAGT,QAAO,SAAS,MAAM,WAAW;AAC/B,MAAI,CAAC,cAAc,gBAAgB,OAAO,CAAE,QAAO;AACnD,MAAI,UAAU,KAAA,EAAW,QAAO;AAChC,SAAO,eAAe,SAAS,OAAO,UAAU;GAChD;;;;;;;;AASJ,MAAa,qBAAqB,IAAI,IAAa;CACjD;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD,CAAC;;;;;;;;;AAUF,SAAgB,mBAAmB,OAAiC;AAClE,QACE,mBAAmB,IAAI,MAAiB,IAAI,MAAM,WAAW,UAAU;;;;;;;;;;;;;;AAgB3E,SAAgB,aAAa,OAA4C;AACvE,SAAQ,MAAM,QAAd;EACE,KAAK,SACH,QAAO;EACT,KAAK,cACH,QAAO;EACT,KAAK,UACH,QAAO;EACT,KAAK,WACH,QAAO;EACT,KAAK,QACH,QAAO;EACT,KAAK,UAAU;GACb,MAAM,OAAO,MAAM,OAAO;AAC1B,UAAO,MAAM,QAAQ,OAAO,UAAU,KAAK,SAAS;;EAEtD,KAAK,YACH,QAAO;EACT,KAAK;EACL,KAAK,kBACH,QAAO;EACT,KAAK,QACH,QAAO;EACT,QACE;;;;;;;;;;;;;;;AAgBN,SAAgB,oBACd,OACA,YACS;CACT,MAAM,QAAS,WAAmC;AAClD,KAAI,OAAO,UAAU,aAAa,MAAM,OAAO,MAAM,MACnD,QAAO;CAGT,MAAM,UAAU,aAAa,MAAM;AACnC,KAAI,YAAY,KAAA,EAAW,QAAO;CAElC,MAAM,WAAW,WAAW;AAI5B,KAAI,EAFF,SAAS,SAAS,QAAQ,IACzB,QAAQ,WAAW,UAAU,IAAI,SAAS,SAAS,SAAS,EAE7D,QAAO;AAGT,QAAO,iBACL,MAAM,OAAO,WACb,WAAW,YACX,WAAW,MACZ"}

package/dist/stream/subscription.d.cts

@@ -0,0 +1,94 @@
+import { Namespace } from "./types.cjs";
+import { Channel, SubscribeParams } from "@langchain/protocol";
+
+//#region src/stream/subscription.d.ts
+/**
+ * Minimal protocol-event shape consumed by {@link inferChannel} and
+ * {@link matchesSubscription}.
+ *
+ * Both the core {@link ProtocolEvent} and the wire-level `Event` from
+ * `@langchain/protocol` structurally satisfy this contract, so the same
+ * predicates can drive in-process fan-out, buffered replay, and server-side
+ * (SSE / WebSocket) event-sink filtering without coupling to a single event
+ * type.
+ */
+interface MatchableEvent {
+  /** Logical stream channel; see {@link inferChannel}. */
+  readonly method: string;
+  /** Monotonic sequence number, when present. Used by the `since` cursor. */
+  readonly seq?: number;
+  readonly params: {
+    /** Namespace of the node or scope that emitted this event. */readonly namespace: Namespace; /** Opaque channel payload; shape depends on `method`. */
+    readonly data?: unknown;
+  };
+}
+/**
+ * Strip dynamic suffixes (after `:`) from a namespace segment.
+ *
+ * Server-emitted namespaces contain runtime-generated suffixes like
+ * `"fetcher:abc-uuid"`, while user-supplied subscription filters are typically
+ * static names (`"fetcher"`). Mirrors `normalize_namespace_segment` in
+ * `api/langgraph_api/protocol/namespace.py`.
+ *
+ * @param segment - Raw namespace segment.
+ * @returns The stable graph-oriented portion of the segment.
+ */
+declare function normalizeNamespaceSegment(segment: string): string;
+/**
+ * Whether `namespace` starts with `prefix`.
+ *
+ * Segments are compared literally first; if the prefix segment itself contains
+ * no `:`, the candidate segment is also compared after its dynamic suffix is
+ * stripped (see {@link normalizeNamespaceSegment}). This mirrors
+ * `is_prefix_match` in `api/langgraph_api/protocol/namespace.py` so server-side
+ * filtering and client-side per-subscription narrowing stay consistent.
+ *
+ * @param namespace - Event namespace to test.
+ * @param prefix - Subscription namespace prefix.
+ */
+declare function isPrefixMatch(namespace: Namespace, prefix: Namespace): boolean;
+/**
+ * The base protocol subscription channels, excluding the templated
+ * `custom:<name>` form. This is the runtime counterpart to the `Channel`
+ * union from `@langchain/protocol` and mirrors the channel set a server
+ * recognizes when filtering its event sinks.
+ */
+declare const SUPPORTED_CHANNELS: Set<Channel>;
+/**
+ * Whether `value` names a protocol subscription channel — either a base
+ * channel (`"messages"`, `"values"`, …) or a named custom channel
+ * (`"custom:<name>"`). Unknown/future method names return `false`,
+ * mirroring {@link inferChannel}.
+ *
+ * @param value - Candidate channel name.
+ */
+declare function isSupportedChannel(value: string): value is Channel;
+/**
+ * Maps a protocol event method to its subscription {@link Channel}.
+ *
+ * Returns `undefined` for unrecognized methods so that new server-side
+ * channels (e.g. from extension transformers) don't break existing
+ * subscribers. The `custom` method resolves to the named `custom:<name>`
+ * channel when the payload carries a `name`, otherwise the bare `custom`
+ * channel. Both `"input"` and the wire-level `"input.requested"` map to the
+ * `input` channel.
+ *
+ * @param event - Event whose method should be mapped to a channel.
+ */
+declare function inferChannel(event: MatchableEvent): Channel | undefined;
+/**
+ * Returns whether an event should be delivered for a subscription definition.
+ *
+ * When the definition carries a `since` replay cursor, events at or before
+ * that sequence number are excluded — letting the same predicate drive both
+ * live fan-out and buffered replay over a {@link StreamChannel}.
+ *
+ * @param event - Event being checked for delivery.
+ * @param definition - Subscription filter definition to evaluate against.
+ *   The optional `since` field (a `seq` cursor) is read leniently because it
+ *   is not a declared field on the base {@link SubscribeParams} shape.
+ */
+declare function matchesSubscription(event: MatchableEvent, definition: SubscribeParams): boolean;
+//#endregion
+export { MatchableEvent, SUPPORTED_CHANNELS, inferChannel, isPrefixMatch, isSupportedChannel, matchesSubscription, normalizeNamespaceSegment };
+//# sourceMappingURL=subscription.d.cts.map

package/dist/stream/subscription.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription.d.cts","names":[],"sources":["../../src/stream/subscription.ts"],"mappings":";;;;;AAsDA;;;;;AAiBA;;;;UA5CiB,cAAA;EA6Cf;EAAA,SA3CS,MAAA;EA4CT;EAAA,SAzCS,GAAA;EAAA,SAEA,MAAA;IA2EE,uEAzEA,SAAA,EAAW,SAAA,EAyEO;IAAA,SAtElB,IAAA;EAAA;AAAA;;;;;;;;;AA4Gb;;;iBA7FgB,yBAAA,CAA0B,OAAA;;;;;;AAqI1C;;;;;;;iBApHgB,aAAA,CACd,SAAA,EAAW,SAAA,EACX,MAAA,EAAQ,SAAA;;;;;;;cAoCG,kBAAA,EAAkB,GAAA,CAAA,OAAA;;;;;;;;;iBAoBf,kBAAA,CAAmB,KAAA,WAAgB,KAAA,IAAS,OAAA;;;;;;;;;;;;;iBAkB5C,YAAA,CAAa,KAAA,EAAO,cAAA,GAAiB,OAAA;;;;;;;;;;;;;iBAwCrC,mBAAA,CACd,KAAA,EAAO,cAAA,EACP,UAAA,EAAY,eAAA"}

package/dist/stream/subscription.d.ts

@@ -0,0 +1,94 @@
+import { Namespace } from "./types.js";
+import { Channel, SubscribeParams } from "@langchain/protocol";
+
+//#region src/stream/subscription.d.ts
+/**
+ * Minimal protocol-event shape consumed by {@link inferChannel} and
+ * {@link matchesSubscription}.
+ *
+ * Both the core {@link ProtocolEvent} and the wire-level `Event` from
+ * `@langchain/protocol` structurally satisfy this contract, so the same
+ * predicates can drive in-process fan-out, buffered replay, and server-side
+ * (SSE / WebSocket) event-sink filtering without coupling to a single event
+ * type.
+ */
+interface MatchableEvent {
+  /** Logical stream channel; see {@link inferChannel}. */
+  readonly method: string;
+  /** Monotonic sequence number, when present. Used by the `since` cursor. */
+  readonly seq?: number;
+  readonly params: {
+    /** Namespace of the node or scope that emitted this event. */readonly namespace: Namespace; /** Opaque channel payload; shape depends on `method`. */
+    readonly data?: unknown;
+  };
+}
+/**
+ * Strip dynamic suffixes (after `:`) from a namespace segment.
+ *
+ * Server-emitted namespaces contain runtime-generated suffixes like
+ * `"fetcher:abc-uuid"`, while user-supplied subscription filters are typically
+ * static names (`"fetcher"`). Mirrors `normalize_namespace_segment` in
+ * `api/langgraph_api/protocol/namespace.py`.
+ *
+ * @param segment - Raw namespace segment.
+ * @returns The stable graph-oriented portion of the segment.
+ */
+declare function normalizeNamespaceSegment(segment: string): string;
+/**
+ * Whether `namespace` starts with `prefix`.
+ *
+ * Segments are compared literally first; if the prefix segment itself contains
+ * no `:`, the candidate segment is also compared after its dynamic suffix is
+ * stripped (see {@link normalizeNamespaceSegment}). This mirrors
+ * `is_prefix_match` in `api/langgraph_api/protocol/namespace.py` so server-side
+ * filtering and client-side per-subscription narrowing stay consistent.
+ *
+ * @param namespace - Event namespace to test.
+ * @param prefix - Subscription namespace prefix.
+ */
+declare function isPrefixMatch(namespace: Namespace, prefix: Namespace): boolean;
+/**
+ * The base protocol subscription channels, excluding the templated
+ * `custom:<name>` form. This is the runtime counterpart to the `Channel`
+ * union from `@langchain/protocol` and mirrors the channel set a server
+ * recognizes when filtering its event sinks.
+ */
+declare const SUPPORTED_CHANNELS: Set<Channel>;
+/**
+ * Whether `value` names a protocol subscription channel — either a base
+ * channel (`"messages"`, `"values"`, …) or a named custom channel
+ * (`"custom:<name>"`). Unknown/future method names return `false`,
+ * mirroring {@link inferChannel}.
+ *
+ * @param value - Candidate channel name.
+ */
+declare function isSupportedChannel(value: string): value is Channel;
+/**
+ * Maps a protocol event method to its subscription {@link Channel}.
+ *
+ * Returns `undefined` for unrecognized methods so that new server-side
+ * channels (e.g. from extension transformers) don't break existing
+ * subscribers. The `custom` method resolves to the named `custom:<name>`
+ * channel when the payload carries a `name`, otherwise the bare `custom`
+ * channel. Both `"input"` and the wire-level `"input.requested"` map to the
+ * `input` channel.
+ *
+ * @param event - Event whose method should be mapped to a channel.
+ */
+declare function inferChannel(event: MatchableEvent): Channel | undefined;
+/**
+ * Returns whether an event should be delivered for a subscription definition.
+ *
+ * When the definition carries a `since` replay cursor, events at or before
+ * that sequence number are excluded — letting the same predicate drive both
+ * live fan-out and buffered replay over a {@link StreamChannel}.
+ *
+ * @param event - Event being checked for delivery.
+ * @param definition - Subscription filter definition to evaluate against.
+ *   The optional `since` field (a `seq` cursor) is read leniently because it
+ *   is not a declared field on the base {@link SubscribeParams} shape.
+ */
+declare function matchesSubscription(event: MatchableEvent, definition: SubscribeParams): boolean;
+//#endregion
+export { MatchableEvent, SUPPORTED_CHANNELS, inferChannel, isPrefixMatch, isSupportedChannel, matchesSubscription, normalizeNamespaceSegment };
+//# sourceMappingURL=subscription.d.ts.map

package/dist/stream/subscription.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription.d.ts","names":[],"sources":["../../src/stream/subscription.ts"],"mappings":";;;;;AAsDA;;;;;AAiBA;;;;UA5CiB,cAAA;EA6Cf;EAAA,SA3CS,MAAA;EA4CT;EAAA,SAzCS,GAAA;EAAA,SAEA,MAAA;IA2EE,uEAzEA,SAAA,EAAW,SAAA,EAyEO;IAAA,SAtElB,IAAA;EAAA;AAAA;;;;;;;;;AA4Gb;;;iBA7FgB,yBAAA,CAA0B,OAAA;;;;;;AAqI1C;;;;;;;iBApHgB,aAAA,CACd,SAAA,EAAW,SAAA,EACX,MAAA,EAAQ,SAAA;;;;;;;cAoCG,kBAAA,EAAkB,GAAA,CAAA,OAAA;;;;;;;;;iBAoBf,kBAAA,CAAmB,KAAA,WAAgB,KAAA,IAAS,OAAA;;;;;;;;;;;;;iBAkB5C,YAAA,CAAa,KAAA,EAAO,cAAA,GAAiB,OAAA;;;;;;;;;;;;;iBAwCrC,mBAAA,CACd,KAAA,EAAO,cAAA,EACP,UAAA,EAAY,eAAA"}

package/dist/stream/subscription.js

@@ -0,0 +1,131 @@
+//#region src/stream/subscription.ts
+/**
+* Strip dynamic suffixes (after `:`) from a namespace segment.
+*
+* Server-emitted namespaces contain runtime-generated suffixes like
+* `"fetcher:abc-uuid"`, while user-supplied subscription filters are typically
+* static names (`"fetcher"`). Mirrors `normalize_namespace_segment` in
+* `api/langgraph_api/protocol/namespace.py`.
+*
+* @param segment - Raw namespace segment.
+* @returns The stable graph-oriented portion of the segment.
+*/
+function normalizeNamespaceSegment(segment) {
+	const idx = segment.indexOf(":");
+	return idx === -1 ? segment : segment.slice(0, idx);
+}
+/**
+* Whether `namespace` starts with `prefix`.
+*
+* Segments are compared literally first; if the prefix segment itself contains
+* no `:`, the candidate segment is also compared after its dynamic suffix is
+* stripped (see {@link normalizeNamespaceSegment}). This mirrors
+* `is_prefix_match` in `api/langgraph_api/protocol/namespace.py` so server-side
+* filtering and client-side per-subscription narrowing stay consistent.
+*
+* @param namespace - Event namespace to test.
+* @param prefix - Subscription namespace prefix.
+*/
+function isPrefixMatch(namespace, prefix) {
+	if (prefix.length > namespace.length) return false;
+	for (let i = 0; i < prefix.length; i += 1) {
+		const segment = prefix[i];
+		const candidate = namespace[i];
+		if (candidate === segment) continue;
+		if (segment.includes(":")) return false;
+		if (normalizeNamespaceSegment(candidate) === segment) continue;
+		return false;
+	}
+	return true;
+}
+function namespaceMatches(eventNamespace, prefixes, depth) {
+	if (!prefixes || prefixes.length === 0) return true;
+	return prefixes.some((prefix) => {
+		if (!isPrefixMatch(eventNamespace, prefix)) return false;
+		if (depth === void 0) return true;
+		return eventNamespace.length - prefix.length <= depth;
+	});
+}
+/**
+* The base protocol subscription channels, excluding the templated
+* `custom:<name>` form. This is the runtime counterpart to the `Channel`
+* union from `@langchain/protocol` and mirrors the channel set a server
+* recognizes when filtering its event sinks.
+*/
+const SUPPORTED_CHANNELS = new Set([
+	"values",
+	"updates",
+	"messages",
+	"tools",
+	"lifecycle",
+	"input",
+	"checkpoints",
+	"tasks",
+	"custom"
+]);
+/**
+* Whether `value` names a protocol subscription channel — either a base
+* channel (`"messages"`, `"values"`, …) or a named custom channel
+* (`"custom:<name>"`). Unknown/future method names return `false`,
+* mirroring {@link inferChannel}.
+*
+* @param value - Candidate channel name.
+*/
+function isSupportedChannel(value) {
+	return SUPPORTED_CHANNELS.has(value) || value.startsWith("custom:");
+}
+/**
+* Maps a protocol event method to its subscription {@link Channel}.
+*
+* Returns `undefined` for unrecognized methods so that new server-side
+* channels (e.g. from extension transformers) don't break existing
+* subscribers. The `custom` method resolves to the named `custom:<name>`
+* channel when the payload carries a `name`, otherwise the bare `custom`
+* channel. Both `"input"` and the wire-level `"input.requested"` map to the
+* `input` channel.
+*
+* @param event - Event whose method should be mapped to a channel.
+*/
+function inferChannel(event) {
+	switch (event.method) {
+		case "values": return "values";
+		case "checkpoints": return "checkpoints";
+		case "updates": return "updates";
+		case "messages": return "messages";
+		case "tools": return "tools";
+		case "custom": {
+			const data = event.params.data;
+			return data?.name != null ? `custom:${data.name}` : "custom";
+		}
+		case "lifecycle": return "lifecycle";
+		case "input":
+		case "input.requested": return "input";
+		case "tasks": return "tasks";
+		default: return;
+	}
+}
+/**
+* Returns whether an event should be delivered for a subscription definition.
+*
+* When the definition carries a `since` replay cursor, events at or before
+* that sequence number are excluded — letting the same predicate drive both
+* live fan-out and buffered replay over a {@link StreamChannel}.
+*
+* @param event - Event being checked for delivery.
+* @param definition - Subscription filter definition to evaluate against.
+*   The optional `since` field (a `seq` cursor) is read leniently because it
+*   is not a declared field on the base {@link SubscribeParams} shape.
+*/
+function matchesSubscription(event, definition) {
+	const since = definition.since;
+	if (typeof since === "number" && (event.seq ?? 0) <= since) return false;
+	const channel = inferChannel(event);
+	if (channel === void 0) return false;
+	const channels = definition.channels;
+	if (!(channels.includes(channel) || channel.startsWith("custom:") && channels.includes("custom"))) return false;
+	return namespaceMatches(event.params.namespace, definition.namespaces, definition.depth);
+}
+//#endregion
+export { SUPPORTED_CHANNELS, inferChannel, isPrefixMatch, isSupportedChannel, matchesSubscription, normalizeNamespaceSegment };
+
+//# sourceMappingURL=subscription.js.map

package/dist/stream/subscription.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription.js","names":[],"sources":["../../src/stream/subscription.ts"],"sourcesContent":["/**\n * Subscription matching and channel inference for the v2 streaming protocol.\n *\n * These helpers are the building blocks a custom transport / server needs to\n * fan protocol events out to subscribers: map an event to its logical\n * {@link Channel} ({@link inferChannel}) and decide whether a buffered event\n * should be delivered for a given {@link SubscribeParams} filter\n * ({@link matchesSubscription}). They are typed against the minimal\n * {@link MatchableEvent} shape so the same predicate works on the core\n * {@link ProtocolEvent} produced by {@link convertToProtocolEvent} /\n * {@link StreamChannel} and on the wire-level `Event` from\n * `@langchain/protocol`.\n */\n\nimport type { Channel, SubscribeParams } from \"@langchain/protocol\";\nimport type { Namespace } from \"./types.js\";\n\n/**\n * Minimal protocol-event shape consumed by {@link inferChannel} and\n * {@link matchesSubscription}.\n *\n * Both the core {@link ProtocolEvent} and the wire-level `Event` from\n * `@langchain/protocol` structurally satisfy this contract, so the same\n * predicates can drive in-process fan-out, buffered replay, and server-side\n * (SSE / WebSocket) event-sink filtering without coupling to a single event\n * type.\n */\nexport interface MatchableEvent {\n  /** Logical stream channel; see {@link inferChannel}. */\n  readonly method: string;\n\n  /** Monotonic sequence number, when present. Used by the `since` cursor. */\n  readonly seq?: number;\n\n  readonly params: {\n    /** Namespace of the node or scope that emitted this event. */\n    readonly namespace: Namespace;\n\n    /** Opaque channel payload; shape depends on `method`. */\n    readonly data?: unknown;\n  };\n}\n\n/**\n * Strip dynamic suffixes (after `:`) from a namespace segment.\n *\n * Server-emitted namespaces contain runtime-generated suffixes like\n * `\"fetcher:abc-uuid\"`, while user-supplied subscription filters are typically\n * static names (`\"fetcher\"`). Mirrors `normalize_namespace_segment` in\n * `api/langgraph_api/protocol/namespace.py`.\n *\n * @param segment - Raw namespace segment.\n * @returns The stable graph-oriented portion of the segment.\n */\nexport function normalizeNamespaceSegment(segment: string): string {\n  const idx = segment.indexOf(\":\");\n  return idx === -1 ? segment : segment.slice(0, idx);\n}\n\n/**\n * Whether `namespace` starts with `prefix`.\n *\n * Segments are compared literally first; if the prefix segment itself contains\n * no `:`, the candidate segment is also compared after its dynamic suffix is\n * stripped (see {@link normalizeNamespaceSegment}). This mirrors\n * `is_prefix_match` in `api/langgraph_api/protocol/namespace.py` so server-side\n * filtering and client-side per-subscription narrowing stay consistent.\n *\n * @param namespace - Event namespace to test.\n * @param prefix - Subscription namespace prefix.\n */\nexport function isPrefixMatch(\n  namespace: Namespace,\n  prefix: Namespace\n): boolean {\n  if (prefix.length > namespace.length) return false;\n  for (let i = 0; i < prefix.length; i += 1) {\n    const segment = prefix[i]!;\n    const candidate = namespace[i]!;\n    if (candidate === segment) continue;\n    if (segment.includes(\":\")) return false;\n    if (normalizeNamespaceSegment(candidate) === segment) continue;\n    return false;\n  }\n  return true;\n}\n\nfunction namespaceMatches(\n  eventNamespace: Namespace,\n  prefixes: Namespace[] | undefined,\n  depth: number | undefined\n): boolean {\n  if (!prefixes || prefixes.length === 0) {\n    return true;\n  }\n\n  return prefixes.some((prefix) => {\n    if (!isPrefixMatch(eventNamespace, prefix)) return false;\n    if (depth === undefined) return true;\n    return eventNamespace.length - prefix.length <= depth;\n  });\n}\n\n/**\n * The base protocol subscription channels, excluding the templated\n * `custom:<name>` form. This is the runtime counterpart to the `Channel`\n * union from `@langchain/protocol` and mirrors the channel set a server\n * recognizes when filtering its event sinks.\n */\nexport const SUPPORTED_CHANNELS = new Set<Channel>([\n  \"values\",\n  \"updates\",\n  \"messages\",\n  \"tools\",\n  \"lifecycle\",\n  \"input\",\n  \"checkpoints\",\n  \"tasks\",\n  \"custom\",\n]);\n\n/**\n * Whether `value` names a protocol subscription channel — either a base\n * channel (`\"messages\"`, `\"values\"`, …) or a named custom channel\n * (`\"custom:<name>\"`). Unknown/future method names return `false`,\n * mirroring {@link inferChannel}.\n *\n * @param value - Candidate channel name.\n */\nexport function isSupportedChannel(value: string): value is Channel {\n  return (\n    SUPPORTED_CHANNELS.has(value as Channel) || value.startsWith(\"custom:\")\n  );\n}\n\n/**\n * Maps a protocol event method to its subscription {@link Channel}.\n *\n * Returns `undefined` for unrecognized methods so that new server-side\n * channels (e.g. from extension transformers) don't break existing\n * subscribers. The `custom` method resolves to the named `custom:<name>`\n * channel when the payload carries a `name`, otherwise the bare `custom`\n * channel. Both `\"input\"` and the wire-level `\"input.requested\"` map to the\n * `input` channel.\n *\n * @param event - Event whose method should be mapped to a channel.\n */\nexport function inferChannel(event: MatchableEvent): Channel | undefined {\n  switch (event.method) {\n    case \"values\":\n      return \"values\";\n    case \"checkpoints\":\n      return \"checkpoints\";\n    case \"updates\":\n      return \"updates\";\n    case \"messages\":\n      return \"messages\";\n    case \"tools\":\n      return \"tools\";\n    case \"custom\": {\n      const data = event.params.data as { name?: string } | undefined;\n      return data?.name != null ? `custom:${data.name}` : \"custom\";\n    }\n    case \"lifecycle\":\n      return \"lifecycle\";\n    case \"input\":\n    case \"input.requested\":\n      return \"input\";\n    case \"tasks\":\n      return \"tasks\";\n    default:\n      return undefined;\n  }\n}\n\n/**\n * Returns whether an event should be delivered for a subscription definition.\n *\n * When the definition carries a `since` replay cursor, events at or before\n * that sequence number are excluded — letting the same predicate drive both\n * live fan-out and buffered replay over a {@link StreamChannel}.\n *\n * @param event - Event being checked for delivery.\n * @param definition - Subscription filter definition to evaluate against.\n *   The optional `since` field (a `seq` cursor) is read leniently because it\n *   is not a declared field on the base {@link SubscribeParams} shape.\n */\nexport function matchesSubscription(\n  event: MatchableEvent,\n  definition: SubscribeParams\n): boolean {\n  const since = (definition as { since?: unknown }).since;\n  if (typeof since === \"number\" && (event.seq ?? 0) <= since) {\n    return false;\n  }\n\n  const channel = inferChannel(event);\n  if (channel === undefined) return false;\n\n  const channels = definition.channels;\n  const channelMatched =\n    channels.includes(channel) ||\n    (channel.startsWith(\"custom:\") && channels.includes(\"custom\"));\n  if (!channelMatched) {\n    return false;\n  }\n\n  return namespaceMatches(\n    event.params.namespace,\n    definition.namespaces,\n    definition.depth\n  );\n}\n"],"mappings":";;;;;;;;;;;;AAsDA,SAAgB,0BAA0B,SAAyB;CACjE,MAAM,MAAM,QAAQ,QAAQ,IAAI;AAChC,QAAO,QAAQ,KAAK,UAAU,QAAQ,MAAM,GAAG,IAAI;;;;;;;;;;;;;;AAerD,SAAgB,cACd,WACA,QACS;AACT,KAAI,OAAO,SAAS,UAAU,OAAQ,QAAO;AAC7C,MAAK,IAAI,IAAI,GAAG,IAAI,OAAO,QAAQ,KAAK,GAAG;EACzC,MAAM,UAAU,OAAO;EACvB,MAAM,YAAY,UAAU;AAC5B,MAAI,cAAc,QAAS;AAC3B,MAAI,QAAQ,SAAS,IAAI,CAAE,QAAO;AAClC,MAAI,0BAA0B,UAAU,KAAK,QAAS;AACtD,SAAO;;AAET,QAAO;;AAGT,SAAS,iBACP,gBACA,UACA,OACS;AACT,KAAI,CAAC,YAAY,SAAS,WAAW,EACnC,QAAO;AAGT,QAAO,SAAS,MAAM,WAAW;AAC/B,MAAI,CAAC,cAAc,gBAAgB,OAAO,CAAE,QAAO;AACnD,MAAI,UAAU,KAAA,EAAW,QAAO;AAChC,SAAO,eAAe,SAAS,OAAO,UAAU;GAChD;;;;;;;;AASJ,MAAa,qBAAqB,IAAI,IAAa;CACjD;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD,CAAC;;;;;;;;;AAUF,SAAgB,mBAAmB,OAAiC;AAClE,QACE,mBAAmB,IAAI,MAAiB,IAAI,MAAM,WAAW,UAAU;;;;;;;;;;;;;;AAgB3E,SAAgB,aAAa,OAA4C;AACvE,SAAQ,MAAM,QAAd;EACE,KAAK,SACH,QAAO;EACT,KAAK,cACH,QAAO;EACT,KAAK,UACH,QAAO;EACT,KAAK,WACH,QAAO;EACT,KAAK,QACH,QAAO;EACT,KAAK,UAAU;GACb,MAAM,OAAO,MAAM,OAAO;AAC1B,UAAO,MAAM,QAAQ,OAAO,UAAU,KAAK,SAAS;;EAEtD,KAAK,YACH,QAAO;EACT,KAAK;EACL,KAAK,kBACH,QAAO;EACT,KAAK,QACH,QAAO;EACT,QACE;;;;;;;;;;;;;;;AAgBN,SAAgB,oBACd,OACA,YACS;CACT,MAAM,QAAS,WAAmC;AAClD,KAAI,OAAO,UAAU,aAAa,MAAM,OAAO,MAAM,MACnD,QAAO;CAGT,MAAM,UAAU,aAAa,MAAM;AACnC,KAAI,YAAY,KAAA,EAAW,QAAO;CAElC,MAAM,WAAW,WAAW;AAI5B,KAAI,EAFF,SAAS,SAAS,QAAQ,IACzB,QAAQ,WAAW,UAAU,IAAI,SAAS,SAAS,SAAS,EAE7D,QAAO;AAGT,QAAO,iBACL,MAAM,OAAO,WACb,WAAW,YACX,WAAW,MACZ"}

package/dist/stream/types.d.cts

@@ -251,5 +251,5 @@ interface InterruptPayload<TPayload = unknown> {
   payload: TPayload;
 }
 //#endregion
-export { type AgentStatus$1 as AgentStatus, ChatModelStream$1 as ChatModelStream, ChatModelStreamHandle, InferExtensions, InterruptPayload, type LifecycleCause, type LifecycleData$1 as LifecycleData, type MessagesEventData, Namespace, NativeStreamTransformer, ProtocolEvent, StreamEmitter, StreamTransformer, ToolCallStatus, ToolCallStream, type ToolsEventData, type UpdatesEventData, type UsageInfo, isNativeTransformer };
+export { type AgentStatus$1 as AgentStatus, ChatModelStream$1 as ChatModelStream, ChatModelStreamHandle, InferExtensions, InterruptPayload, type LifecycleCause, type LifecycleData$1 as LifecycleData, type MessagesEventData, Namespace, NativeStreamTransformer, ProtocolEvent, ProtocolMethod, StreamEmitter, StreamTransformer, ToolCallStatus, ToolCallStream, type ToolsEventData, type UpdatesEventData, type UsageInfo, isNativeTransformer };
 //# sourceMappingURL=types.d.cts.map

package/dist/stream/types.d.ts

@@ -251,5 +251,5 @@ interface InterruptPayload<TPayload = unknown> {
   payload: TPayload;
 }
 //#endregion
-export { type AgentStatus$1 as AgentStatus, ChatModelStream$1 as ChatModelStream, ChatModelStreamHandle, InferExtensions, InterruptPayload, type LifecycleCause, type LifecycleData$1 as LifecycleData, type MessagesEventData, Namespace, NativeStreamTransformer, ProtocolEvent, StreamEmitter, StreamTransformer, ToolCallStatus, ToolCallStream, type ToolsEventData, type UpdatesEventData, type UsageInfo, isNativeTransformer };
+export { type AgentStatus$1 as AgentStatus, ChatModelStream$1 as ChatModelStream, ChatModelStreamHandle, InferExtensions, InterruptPayload, type LifecycleCause, type LifecycleData$1 as LifecycleData, type MessagesEventData, Namespace, NativeStreamTransformer, ProtocolEvent, ProtocolMethod, StreamEmitter, StreamTransformer, ToolCallStatus, ToolCallStream, type ToolsEventData, type UpdatesEventData, type UsageInfo, isNativeTransformer };
 //# sourceMappingURL=types.d.ts.map

package/dist/stream.cjs

@@ -0,0 +1,16 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_convert = require("./stream/convert.cjs");
+const require_stream_channel = require("./stream/stream-channel.cjs");
+const require_subscription = require("./stream/subscription.cjs");
+exports.EventLog = require_stream_channel.StreamChannel;
+exports.STREAM_EVENTS_V3_MODES = require_convert.STREAM_EVENTS_V3_MODES;
+exports.SUPPORTED_CHANNELS = require_subscription.SUPPORTED_CHANNELS;
+exports.StreamChannel = require_stream_channel.StreamChannel;
+exports.convertToProtocolEvent = require_convert.convertToProtocolEvent;
+exports.inferChannel = require_subscription.inferChannel;
+exports.isCheckpointEnvelope = require_convert.isCheckpointEnvelope;
+exports.isPrefixMatch = require_subscription.isPrefixMatch;
+exports.isStreamChannel = require_stream_channel.isStreamChannel;
+exports.isSupportedChannel = require_subscription.isSupportedChannel;
+exports.matchesSubscription = require_subscription.matchesSubscription;
+exports.normalizeNamespaceSegment = require_subscription.normalizeNamespaceSegment;

package/dist/stream.d.cts

@@ -0,0 +1,5 @@
+import { Namespace, ProtocolEvent, ProtocolMethod } from "./stream/types.cjs";
+import { StreamChannel, isStreamChannel } from "./stream/stream-channel.cjs";
+import { ConvertToProtocolEventOptions, STREAM_EVENTS_V3_MODES, convertToProtocolEvent, isCheckpointEnvelope } from "./stream/convert.cjs";
+import { MatchableEvent, SUPPORTED_CHANNELS, inferChannel, isPrefixMatch, isSupportedChannel, matchesSubscription, normalizeNamespaceSegment } from "./stream/subscription.cjs";
+export { type ConvertToProtocolEventOptions, StreamChannel as EventLog, type MatchableEvent, type Namespace, type ProtocolEvent, type ProtocolMethod, STREAM_EVENTS_V3_MODES, SUPPORTED_CHANNELS, StreamChannel, convertToProtocolEvent, inferChannel, isCheckpointEnvelope, isPrefixMatch, isStreamChannel, isSupportedChannel, matchesSubscription, normalizeNamespaceSegment };

package/dist/stream.d.ts

@@ -0,0 +1,5 @@
+import { Namespace, ProtocolEvent, ProtocolMethod } from "./stream/types.js";
+import { StreamChannel, isStreamChannel } from "./stream/stream-channel.js";
+import { ConvertToProtocolEventOptions, STREAM_EVENTS_V3_MODES, convertToProtocolEvent, isCheckpointEnvelope } from "./stream/convert.js";
+import { MatchableEvent, SUPPORTED_CHANNELS, inferChannel, isPrefixMatch, isSupportedChannel, matchesSubscription, normalizeNamespaceSegment } from "./stream/subscription.js";
+export { type ConvertToProtocolEventOptions, StreamChannel as EventLog, type MatchableEvent, type Namespace, type ProtocolEvent, type ProtocolMethod, STREAM_EVENTS_V3_MODES, SUPPORTED_CHANNELS, StreamChannel, convertToProtocolEvent, inferChannel, isCheckpointEnvelope, isPrefixMatch, isStreamChannel, isSupportedChannel, matchesSubscription, normalizeNamespaceSegment };

package/dist/stream.js

@@ -0,0 +1,4 @@
+import { STREAM_EVENTS_V3_MODES, convertToProtocolEvent, isCheckpointEnvelope } from "./stream/convert.js";
+import { StreamChannel, isStreamChannel } from "./stream/stream-channel.js";
+import { SUPPORTED_CHANNELS, inferChannel, isPrefixMatch, isSupportedChannel, matchesSubscription, normalizeNamespaceSegment } from "./stream/subscription.js";
+export { StreamChannel as EventLog, STREAM_EVENTS_V3_MODES, SUPPORTED_CHANNELS, StreamChannel, convertToProtocolEvent, inferChannel, isCheckpointEnvelope, isPrefixMatch, isStreamChannel, isSupportedChannel, matchesSubscription, normalizeNamespaceSegment };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@langchain/langgraph",
-  "version": "1.3.6",
+  "version": "1.3.7",
   "description": "LangGraph",
   "type": "module",
   "engines": {
@@ -20,7 +20,7 @@
     "@standard-schema/spec": "1.1.0",
     "uuid": "^14.0.0",
     "@langchain/langgraph-checkpoint": "^1.0.4",
-    "@langchain/langgraph-sdk": "~1.9.17"
+    "@langchain/langgraph-sdk": "~1.9.19"
   },
   "peerDependencies": {
     "@langchain/core": "^1.1.48",
@@ -56,10 +56,10 @@
     "tsx": "^4.19.3",
     "typescript": "^4.9.5 || ^5.4.5",
     "vite-plugin-node-polyfills": "^0.28.0",
-    "vitest": "^4.1.8",
+    "vitest": "^4.1.0",
     "zod-to-json-schema": "^3.22.4",
     "@langchain/langgraph-checkpoint-postgres": "1.0.2",
-    "@langchain/langgraph-checkpoint-sqlite": "1.0.1"
+    "@langchain/langgraph-checkpoint-sqlite": "1.0.2"
   },
   "publishConfig": {
     "access": "public",
@@ -139,6 +139,18 @@
         "default": "./dist/remote.cjs"
       }
     },
+    "./stream": {
+      "input": "./src/stream.ts",
+      "typedoc": "./src/stream.ts",
+      "import": {
+        "types": "./dist/stream.d.ts",
+        "default": "./dist/stream.js"
+      },
+      "require": {
+        "types": "./dist/stream.d.cts",
+        "default": "./dist/stream.cjs"
+      }
+    },
     "./zod": {
       "input": "./src/graph/zod/index.ts",
       "typedoc": "./src/graph/zod/index.ts",