@langchain/langgraph 1.2.8 → 1.3.0

package/dist/stream/stream-channel.cjs

@@ -0,0 +1,208 @@
+//#region src/stream/stream-channel.ts
+/**
+* StreamChannel — projection channel for local or remote streaming.
+*
+* A `StreamChannel<T>` is an append-only async stream with independent
+* cursors. Local channels stay in-process only. Remote channels declare a
+* protocol channel name; when registered with a {@link StreamMux} (via a
+* transformer's `init()` return value), every {@link push} is automatically
+* forwarded as a {@link ProtocolEvent} on the named channel — making the data
+* available both in-process (via `run.extensions`) and to remote clients (via
+* `session.subscribe("custom:<channelName>")`).
+*
+* Lifecycle (`close` / `fail`) is managed by the mux automatically;
+* transformers do not need to call them.
+*/
+/**
+* Branded symbol placed on every {@link StreamChannel} instance.
+*
+* Uses `Symbol.for` so the same symbol is shared across multiple
+* copies of this package that may coexist in a dependency graph
+* (e.g. when a user app imports `@langchain/langgraph` directly and a
+* wrapping library like `langchain` bundles its own copy). Using a
+* symbol brand instead of `instanceof` lets channels created against
+* one copy of the class be recognised by a mux from another.
+* @internal
+*/
+const STREAM_CHANNEL_BRAND = Symbol.for("langgraph.stream_channel");
+/**
+* A projection channel for {@link StreamTransformer}s.
+*
+* Implements `AsyncIterable<T>` so it can be iterated directly by
+* in-process consumers via `run.extensions.<key>`. Channels created with
+* {@link StreamChannel.remote} or `new StreamChannel(name)` are also
+* auto-forwarded to remote clients.
+*
+* @typeParam T - The type of items pushed into the channel.
+*/
+var StreamChannel = class StreamChannel {
+	/** @internal Brand used by {@link StreamChannel.isInstance}. */
+	[STREAM_CHANNEL_BRAND] = true;
+	/** Protocol channel name used for auto-forwarded events, if remote. */
+	channelName;
+	#items = [];
+	#waiters = [];
+	#done = false;
+	#error;
+	#onPush;
+	constructor(name) {
+		this.channelName = name;
+	}
+	/**
+	* Create an in-process-only channel.  Values remain available through
+	* `run.extensions.<key>` but are not forwarded to remote clients.
+	*/
+	static local() {
+		return new StreamChannel();
+	}
+	/**
+	* Create a channel whose pushes are forwarded to remote clients under
+	* the given protocol channel name.
+	*/
+	static remote(name) {
+		return new StreamChannel(name);
+	}
+	/**
+	* Brand-based type guard that recognises any {@link StreamChannel}
+	* instance, even ones originating from a different copy of this
+	* package. Prefer this over `instanceof StreamChannel` when code
+	* may observe channels that were constructed elsewhere.
+	*/
+	static isInstance(value) {
+		return typeof value === "object" && value !== null && STREAM_CHANNEL_BRAND in value && value[STREAM_CHANNEL_BRAND] === true;
+	}
+	/**
+	* Append an item to the channel.  If this is a remote channel wired to a
+	* mux, the item is also injected into the main protocol event stream under
+	* {@link channelName}.
+	*/
+	push(item) {
+		this.#items.push(item);
+		this.#wake();
+		this.#onPush?.(item);
+	}
+	/**
+	* Returns an async iterator starting at position {@link startAt}. Each call
+	* returns an independent cursor so multiple consumers can iterate the same
+	* channel concurrently.
+	*/
+	iterate(startAt = 0) {
+		let cursor = startAt;
+		return { next: async () => {
+			while (true) {
+				if (cursor < this.#items.length) return {
+					value: this.#items[cursor++],
+					done: false
+				};
+				if (this.#done) {
+					if (this.#error) throw this.#error;
+					return {
+						value: void 0,
+						done: true
+					};
+				}
+				await new Promise((resolve) => this.#waiters.push(resolve));
+			}
+		} };
+	}
+	/**
+	* Creates an {@link AsyncIterable} backed by this channel, starting from
+	* {@link startAt}.
+	*/
+	toAsyncIterable(startAt = 0) {
+		return { [Symbol.asyncIterator]: () => this.iterate(startAt) };
+	}
+	/**
+	* Creates a web {@link ReadableStream} that emits channel items as
+	* Server-Sent Events. Useful for returning a channel directly from
+	* `new Response(channel.toEventStream())`.
+	*/
+	toEventStream(options = {}) {
+		const encoder = new TextEncoder();
+		const iterator = this.iterate(options.startAt);
+		const event = options.event ?? this.channelName;
+		const serialize = options.serialize ?? ((item) => JSON.stringify(item) ?? "null");
+		return new ReadableStream({
+			async pull(controller) {
+				try {
+					const next = await iterator.next();
+					if (next.done) {
+						controller.close();
+						return;
+					}
+					const lines = [];
+					if (event != null) lines.push(`event: ${event}`);
+					for (const line of serialize(next.value).split(/\r\n|\r|\n/)) lines.push(`data: ${line}`);
+					controller.enqueue(encoder.encode(`${lines.join("\n")}\n\n`));
+				} catch (error) {
+					controller.error(error);
+				}
+			},
+			async cancel() {
+				await iterator.return?.();
+			}
+		});
+	}
+	/**
+	* Returns the item at the given zero-based index.
+	*
+	* @throws {RangeError} If the index is out of bounds.
+	*/
+	get(index) {
+		if (index < 0 || index >= this.#items.length) throw new RangeError(`StreamChannel index ${index} out of bounds (size=${this.#items.length})`);
+		return this.#items[index];
+	}
+	/** The number of items currently buffered in the channel. */
+	get size() {
+		return this.#items.length;
+	}
+	/** Whether the channel has been closed or failed. */
+	get done() {
+		return this.#done;
+	}
+	/** Mark the channel as complete after all buffered items are consumed. */
+	close() {
+		this.#done = true;
+		this.#wake();
+	}
+	/** Mark the channel as failed after all buffered items are consumed. */
+	fail(err) {
+		this.#error = err;
+		this.#done = true;
+		this.#wake();
+	}
+	/** @internal Called by the mux to wire auto-forwarding. */
+	_wire(fn) {
+		this.#onPush = fn;
+	}
+	/** @internal Called by the mux on normal completion. */
+	_close() {
+		this.close();
+	}
+	/** @internal Called by the mux on failure. */
+	_fail(err) {
+		this.fail(err);
+	}
+	[Symbol.asyncIterator]() {
+		return this.iterate();
+	}
+	#wake() {
+		const waiters = this.#waiters.splice(0);
+		for (const w of waiters) w();
+	}
+};
+/**
+* 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.
+*/
+function isStreamChannel(value) {
+	return StreamChannel.isInstance(value);
+}
+//#endregion
+exports.StreamChannel = StreamChannel;
+exports.isStreamChannel = isStreamChannel;
+
+//# sourceMappingURL=stream-channel.cjs.map

package/dist/stream/stream-channel.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-channel.cjs","names":["#items","#wake","#onPush","#done","#error","#waiters"],"sources":["../../src/stream/stream-channel.ts"],"sourcesContent":["/**\n * StreamChannel — projection channel for local or remote streaming.\n *\n * A `StreamChannel<T>` is an append-only async stream with independent\n * cursors. Local channels stay in-process only. Remote channels declare a\n * protocol channel name; when registered with a {@link StreamMux} (via a\n * transformer's `init()` return value), every {@link push} is automatically\n * forwarded as a {@link ProtocolEvent} on the named channel — making the data\n * available both in-process (via `run.extensions`) and to remote clients (via\n * `session.subscribe(\"custom:<channelName>\")`).\n *\n * Lifecycle (`close` / `fail`) is managed by the mux automatically;\n * transformers do not need to call them.\n */\n\n/**\n * Branded symbol placed on every {@link StreamChannel} instance.\n *\n * Uses `Symbol.for` so the same symbol is shared across multiple\n * copies of this package that may coexist in a dependency graph\n * (e.g. when a user app imports `@langchain/langgraph` directly and a\n * wrapping library like `langchain` bundles its own copy). Using a\n * symbol brand instead of `instanceof` lets channels created against\n * one copy of the class be recognised by a mux from another.\n * @internal\n */\nexport const STREAM_CHANNEL_BRAND: unique symbol = Symbol.for(\n  \"langgraph.stream_channel\"\n) as typeof STREAM_CHANNEL_BRAND;\n\nexport interface StreamChannelEventStreamOptions<T> {\n  /**\n   * SSE event name. Defaults to the channel's remote protocol name, if any.\n   * Set this for local channels or when exposing the same channel under a\n   * route-specific event name.\n   */\n  event?: string;\n  /**\n   * Cursor position to start streaming from. Useful for reconnects or\n   * secondary subscribers that already consumed the first N buffered items and\n   * only need replay from a known offset.\n   */\n  startAt?: number;\n  /**\n   * Serialize each item into the SSE `data:` field. Defaults to JSON. Use this\n   * when a channel item needs a wire format other than its raw JSON shape, or\n   * when the consumer expects line-oriented text payloads.\n   */\n  serialize?: (item: T) => string;\n}\n\n/**\n * A projection channel for {@link StreamTransformer}s.\n *\n * Implements `AsyncIterable<T>` so it can be iterated directly by\n * in-process consumers via `run.extensions.<key>`. Channels created with\n * {@link StreamChannel.remote} or `new StreamChannel(name)` are also\n * auto-forwarded to remote clients.\n *\n * @typeParam T - The type of items pushed into the channel.\n */\nexport class StreamChannel<T> implements AsyncIterable<T> {\n  /** @internal Brand used by {@link StreamChannel.isInstance}. */\n  readonly [STREAM_CHANNEL_BRAND] = true as const;\n\n  /** Protocol channel name used for auto-forwarded events, if remote. */\n  readonly channelName?: string;\n\n  #items: T[] = [];\n  #waiters: Array<() => void> = [];\n  #done = false;\n  #error: unknown;\n  #onPush?: (item: T) => void;\n\n  constructor(name?: string) {\n    this.channelName = name;\n  }\n\n  /**\n   * Create an in-process-only channel.  Values remain available through\n   * `run.extensions.<key>` but are not forwarded to remote clients.\n   */\n  static local<T>(): StreamChannel<T> {\n    return new StreamChannel<T>();\n  }\n\n  /**\n   * Create a channel whose pushes are forwarded to remote clients under\n   * the given protocol channel name.\n   */\n  static remote<T>(name: string): StreamChannel<T> {\n    return new StreamChannel<T>(name);\n  }\n\n  /**\n   * Brand-based type guard that recognises any {@link StreamChannel}\n   * instance, even ones originating from a different copy of this\n   * package. Prefer this over `instanceof StreamChannel` when code\n   * may observe channels that were constructed elsewhere.\n   */\n  static isInstance(value: unknown): value is StreamChannel<unknown> {\n    return (\n      typeof value === \"object\" &&\n      value !== null &&\n      STREAM_CHANNEL_BRAND in value &&\n      (value as { [STREAM_CHANNEL_BRAND]: unknown })[STREAM_CHANNEL_BRAND] ===\n        true\n    );\n  }\n\n  /**\n   * Append an item to the channel.  If this is a remote channel wired to a\n   * mux, the item is also injected into the main protocol event stream under\n   * {@link channelName}.\n   */\n  push(item: T): void {\n    this.#items.push(item);\n    this.#wake();\n    this.#onPush?.(item);\n  }\n\n  /**\n   * Returns an async iterator starting at position {@link startAt}. Each call\n   * returns an independent cursor so multiple consumers can iterate the same\n   * channel concurrently.\n   */\n  iterate(startAt = 0): AsyncIterator<T> {\n    let cursor = startAt;\n    return {\n      next: async (): Promise<IteratorResult<T>> => {\n        // eslint-disable-next-line no-constant-condition\n        while (true) {\n          if (cursor < this.#items.length) {\n            return { value: this.#items[cursor++], done: false };\n          }\n          if (this.#done) {\n            if (this.#error) throw this.#error;\n            return { value: undefined as unknown as T, done: true };\n          }\n          await new Promise<void>((resolve) => this.#waiters.push(resolve));\n        }\n      },\n    };\n  }\n\n  /**\n   * Creates an {@link AsyncIterable} backed by this channel, starting from\n   * {@link startAt}.\n   */\n  toAsyncIterable(startAt = 0): AsyncIterable<T> {\n    return {\n      [Symbol.asyncIterator]: () => this.iterate(startAt),\n    };\n  }\n\n  /**\n   * Creates a web {@link ReadableStream} that emits channel items as\n   * Server-Sent Events. Useful for returning a channel directly from\n   * `new Response(channel.toEventStream())`.\n   */\n  toEventStream(\n    options: StreamChannelEventStreamOptions<T> = {}\n  ): ReadableStream<Uint8Array> {\n    const encoder = new TextEncoder();\n    const iterator = this.iterate(options.startAt);\n    const event = options.event ?? this.channelName;\n    const serialize =\n      options.serialize ?? ((item: T) => JSON.stringify(item) ?? \"null\");\n\n    return new ReadableStream<Uint8Array>({\n      async pull(controller) {\n        try {\n          const next = await iterator.next();\n          if (next.done) {\n            controller.close();\n            return;\n          }\n\n          const lines: string[] = [];\n          if (event != null) {\n            lines.push(`event: ${event}`);\n          }\n          for (const line of serialize(next.value).split(/\\r\\n|\\r|\\n/)) {\n            lines.push(`data: ${line}`);\n          }\n\n          controller.enqueue(encoder.encode(`${lines.join(\"\\n\")}\\n\\n`));\n        } catch (error) {\n          controller.error(error);\n        }\n      },\n      async cancel() {\n        await iterator.return?.();\n      },\n    });\n  }\n\n  /**\n   * Returns the item at the given zero-based index.\n   *\n   * @throws {RangeError} If the index is out of bounds.\n   */\n  get(index: number): T {\n    if (index < 0 || index >= this.#items.length) {\n      throw new RangeError(\n        `StreamChannel index ${index} out of bounds (size=${this.#items.length})`\n      );\n    }\n    return this.#items[index];\n  }\n\n  /** The number of items currently buffered in the channel. */\n  get size(): number {\n    return this.#items.length;\n  }\n\n  /** Whether the channel has been closed or failed. */\n  get done(): boolean {\n    return this.#done;\n  }\n\n  /** Mark the channel as complete after all buffered items are consumed. */\n  close(): void {\n    this.#done = true;\n    this.#wake();\n  }\n\n  /** Mark the channel as failed after all buffered items are consumed. */\n  fail(err: unknown): void {\n    this.#error = err;\n    this.#done = true;\n    this.#wake();\n  }\n\n  /** @internal Called by the mux to wire auto-forwarding. */\n  _wire(fn: (item: T) => void): void {\n    this.#onPush = fn;\n  }\n\n  /** @internal Called by the mux on normal completion. */\n  _close(): void {\n    this.close();\n  }\n\n  /** @internal Called by the mux on failure. */\n  _fail(err: unknown): void {\n    this.fail(err);\n  }\n\n  [Symbol.asyncIterator](): AsyncIterator<T> {\n    return this.iterate();\n  }\n\n  #wake(): void {\n    const waiters = this.#waiters.splice(0);\n    for (const w of waiters) w();\n  }\n}\n\n/**\n * Type guard that tests whether a value is a {@link StreamChannel}.\n *\n * Uses a symbol brand rather than `instanceof` so channels built\n * against a different copy of this package (e.g. one bundled by the\n * `langchain` umbrella package) are still recognised.\n */\nexport function isStreamChannel(\n  value: unknown\n): value is StreamChannel<unknown> {\n  return StreamChannel.isInstance(value);\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,129 @@
+//#region src/stream/stream-channel.d.ts
+/**
+ * StreamChannel — projection channel for local or remote streaming.
+ *
+ * A `StreamChannel<T>` is an append-only async stream with independent
+ * cursors. Local channels stay in-process only. Remote channels declare a
+ * protocol channel name; when registered with a {@link StreamMux} (via a
+ * transformer's `init()` return value), every {@link push} is automatically
+ * forwarded as a {@link ProtocolEvent} on the named channel — making the data
+ * available both in-process (via `run.extensions`) and to remote clients (via
+ * `session.subscribe("custom:<channelName>")`).
+ *
+ * Lifecycle (`close` / `fail`) is managed by the mux automatically;
+ * transformers do not need to call them.
+ */
+/**
+ * Branded symbol placed on every {@link StreamChannel} instance.
+ *
+ * Uses `Symbol.for` so the same symbol is shared across multiple
+ * copies of this package that may coexist in a dependency graph
+ * (e.g. when a user app imports `@langchain/langgraph` directly and a
+ * wrapping library like `langchain` bundles its own copy). Using a
+ * symbol brand instead of `instanceof` lets channels created against
+ * one copy of the class be recognised by a mux from another.
+ * @internal
+ */
+declare const STREAM_CHANNEL_BRAND: unique symbol;
+interface StreamChannelEventStreamOptions<T> {
+  /**
+   * SSE event name. Defaults to the channel's remote protocol name, if any.
+   * Set this for local channels or when exposing the same channel under a
+   * route-specific event name.
+   */
+  event?: string;
+  /**
+   * Cursor position to start streaming from. Useful for reconnects or
+   * secondary subscribers that already consumed the first N buffered items and
+   * only need replay from a known offset.
+   */
+  startAt?: number;
+  /**
+   * Serialize each item into the SSE `data:` field. Defaults to JSON. Use this
+   * when a channel item needs a wire format other than its raw JSON shape, or
+   * when the consumer expects line-oriented text payloads.
+   */
+  serialize?: (item: T) => string;
+}
+/**
+ * A projection channel for {@link StreamTransformer}s.
+ *
+ * Implements `AsyncIterable<T>` so it can be iterated directly by
+ * in-process consumers via `run.extensions.<key>`. Channels created with
+ * {@link StreamChannel.remote} or `new StreamChannel(name)` are also
+ * auto-forwarded to remote clients.
+ *
+ * @typeParam T - The type of items pushed into the channel.
+ */
+declare class StreamChannel<T> implements AsyncIterable<T> {
+  #private;
+  /** @internal Brand used by {@link StreamChannel.isInstance}. */
+  readonly [STREAM_CHANNEL_BRAND]: true;
+  /** Protocol channel name used for auto-forwarded events, if remote. */
+  readonly channelName?: string;
+  constructor(name?: string);
+  /**
+   * Create an in-process-only channel.  Values remain available through
+   * `run.extensions.<key>` but are not forwarded to remote clients.
+   */
+  static local<T>(): StreamChannel<T>;
+  /**
+   * Create a channel whose pushes are forwarded to remote clients under
+   * the given protocol channel name.
+   */
+  static remote<T>(name: string): StreamChannel<T>;
+  /**
+   * Brand-based type guard that recognises any {@link StreamChannel}
+   * instance, even ones originating from a different copy of this
+   * package. Prefer this over `instanceof StreamChannel` when code
+   * may observe channels that were constructed elsewhere.
+   */
+  static isInstance(value: unknown): value is StreamChannel<unknown>;
+  /**
+   * Append an item to the channel.  If this is a remote channel wired to a
+   * mux, the item is also injected into the main protocol event stream under
+   * {@link channelName}.
+   */
+  push(item: T): void;
+  /**
+   * Returns an async iterator starting at position {@link startAt}. Each call
+   * returns an independent cursor so multiple consumers can iterate the same
+   * channel concurrently.
+   */
+  iterate(startAt?: number): AsyncIterator<T>;
+  /**
+   * Creates an {@link AsyncIterable} backed by this channel, starting from
+   * {@link startAt}.
+   */
+  toAsyncIterable(startAt?: number): AsyncIterable<T>;
+  /**
+   * Creates a web {@link ReadableStream} that emits channel items as
+   * Server-Sent Events. Useful for returning a channel directly from
+   * `new Response(channel.toEventStream())`.
+   */
+  toEventStream(options?: StreamChannelEventStreamOptions<T>): ReadableStream<Uint8Array>;
+  /**
+   * Returns the item at the given zero-based index.
+   *
+   * @throws {RangeError} If the index is out of bounds.
+   */
+  get(index: number): T;
+  /** The number of items currently buffered in the channel. */
+  get size(): number;
+  /** Whether the channel has been closed or failed. */
+  get done(): boolean;
+  /** Mark the channel as complete after all buffered items are consumed. */
+  close(): void;
+  /** Mark the channel as failed after all buffered items are consumed. */
+  fail(err: unknown): void;
+  /** @internal Called by the mux to wire auto-forwarding. */
+  _wire(fn: (item: T) => void): void;
+  /** @internal Called by the mux on normal completion. */
+  _close(): void;
+  /** @internal Called by the mux on failure. */
+  _fail(err: unknown): void;
+  [Symbol.asyncIterator](): AsyncIterator<T>;
+}
+//#endregion
+export { StreamChannel };
+//# sourceMappingURL=stream-channel.d.cts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,129 @@
+//#region src/stream/stream-channel.d.ts
+/**
+ * StreamChannel — projection channel for local or remote streaming.
+ *
+ * A `StreamChannel<T>` is an append-only async stream with independent
+ * cursors. Local channels stay in-process only. Remote channels declare a
+ * protocol channel name; when registered with a {@link StreamMux} (via a
+ * transformer's `init()` return value), every {@link push} is automatically
+ * forwarded as a {@link ProtocolEvent} on the named channel — making the data
+ * available both in-process (via `run.extensions`) and to remote clients (via
+ * `session.subscribe("custom:<channelName>")`).
+ *
+ * Lifecycle (`close` / `fail`) is managed by the mux automatically;
+ * transformers do not need to call them.
+ */
+/**
+ * Branded symbol placed on every {@link StreamChannel} instance.
+ *
+ * Uses `Symbol.for` so the same symbol is shared across multiple
+ * copies of this package that may coexist in a dependency graph
+ * (e.g. when a user app imports `@langchain/langgraph` directly and a
+ * wrapping library like `langchain` bundles its own copy). Using a
+ * symbol brand instead of `instanceof` lets channels created against
+ * one copy of the class be recognised by a mux from another.
+ * @internal
+ */
+declare const STREAM_CHANNEL_BRAND: unique symbol;
+interface StreamChannelEventStreamOptions<T> {
+  /**
+   * SSE event name. Defaults to the channel's remote protocol name, if any.
+   * Set this for local channels or when exposing the same channel under a
+   * route-specific event name.
+   */
+  event?: string;
+  /**
+   * Cursor position to start streaming from. Useful for reconnects or
+   * secondary subscribers that already consumed the first N buffered items and
+   * only need replay from a known offset.
+   */
+  startAt?: number;
+  /**
+   * Serialize each item into the SSE `data:` field. Defaults to JSON. Use this
+   * when a channel item needs a wire format other than its raw JSON shape, or
+   * when the consumer expects line-oriented text payloads.
+   */
+  serialize?: (item: T) => string;
+}
+/**
+ * A projection channel for {@link StreamTransformer}s.
+ *
+ * Implements `AsyncIterable<T>` so it can be iterated directly by
+ * in-process consumers via `run.extensions.<key>`. Channels created with
+ * {@link StreamChannel.remote} or `new StreamChannel(name)` are also
+ * auto-forwarded to remote clients.
+ *
+ * @typeParam T - The type of items pushed into the channel.
+ */
+declare class StreamChannel<T> implements AsyncIterable<T> {
+  #private;
+  /** @internal Brand used by {@link StreamChannel.isInstance}. */
+  readonly [STREAM_CHANNEL_BRAND]: true;
+  /** Protocol channel name used for auto-forwarded events, if remote. */
+  readonly channelName?: string;
+  constructor(name?: string);
+  /**
+   * Create an in-process-only channel.  Values remain available through
+   * `run.extensions.<key>` but are not forwarded to remote clients.
+   */
+  static local<T>(): StreamChannel<T>;
+  /**
+   * Create a channel whose pushes are forwarded to remote clients under
+   * the given protocol channel name.
+   */
+  static remote<T>(name: string): StreamChannel<T>;
+  /**
+   * Brand-based type guard that recognises any {@link StreamChannel}
+   * instance, even ones originating from a different copy of this
+   * package. Prefer this over `instanceof StreamChannel` when code
+   * may observe channels that were constructed elsewhere.
+   */
+  static isInstance(value: unknown): value is StreamChannel<unknown>;
+  /**
+   * Append an item to the channel.  If this is a remote channel wired to a
+   * mux, the item is also injected into the main protocol event stream under
+   * {@link channelName}.
+   */
+  push(item: T): void;
+  /**
+   * Returns an async iterator starting at position {@link startAt}. Each call
+   * returns an independent cursor so multiple consumers can iterate the same
+   * channel concurrently.
+   */
+  iterate(startAt?: number): AsyncIterator<T>;
+  /**
+   * Creates an {@link AsyncIterable} backed by this channel, starting from
+   * {@link startAt}.
+   */
+  toAsyncIterable(startAt?: number): AsyncIterable<T>;
+  /**
+   * Creates a web {@link ReadableStream} that emits channel items as
+   * Server-Sent Events. Useful for returning a channel directly from
+   * `new Response(channel.toEventStream())`.
+   */
+  toEventStream(options?: StreamChannelEventStreamOptions<T>): ReadableStream<Uint8Array>;
+  /**
+   * Returns the item at the given zero-based index.
+   *
+   * @throws {RangeError} If the index is out of bounds.
+   */
+  get(index: number): T;
+  /** The number of items currently buffered in the channel. */
+  get size(): number;
+  /** Whether the channel has been closed or failed. */
+  get done(): boolean;
+  /** Mark the channel as complete after all buffered items are consumed. */
+  close(): void;
+  /** Mark the channel as failed after all buffered items are consumed. */
+  fail(err: unknown): void;
+  /** @internal Called by the mux to wire auto-forwarding. */
+  _wire(fn: (item: T) => void): void;
+  /** @internal Called by the mux on normal completion. */
+  _close(): void;
+  /** @internal Called by the mux on failure. */
+  _fail(err: unknown): void;
+  [Symbol.asyncIterator](): AsyncIterator<T>;
+}
+//#endregion
+export { StreamChannel };
+//# sourceMappingURL=stream-channel.d.ts.map

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

@@ -0,0 +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"}