@langchain/langgraph 1.2.9 → 1.3.0

package/dist/stream/stream-channel.js

@@ -0,0 +1,207 @@
+//#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
+export { StreamChannel, isStreamChannel };
+
+//# sourceMappingURL=stream-channel.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stream-channel.js","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/transformers/index.cjs

@@ -0,0 +1,4 @@
+require("./lifecycle.cjs");
+require("./messages.cjs");
+require("./subgraphs.cjs");
+require("./values.cjs");

package/dist/stream/transformers/index.d.ts

@@ -0,0 +1,5 @@
+import { LifecycleEntry, LifecycleTransformerOptions, MessagesTransformerProjection, ValuesTransformerProjection } from "./types.js";
+import { LifecycleProjection, createLifecycleTransformer, filterLifecycleEntries } from "./lifecycle.js";
+import { createMessagesTransformer } from "./messages.js";
+import { SubgraphDiscoveryProjection, SubgraphDiscoveryTransformerOptions, createSubgraphDiscoveryTransformer, filterSubgraphHandles } from "./subgraphs.js";
+import { createValuesTransformer } from "./values.js";

package/dist/stream/transformers/index.js

@@ -0,0 +1,5 @@
+import "./lifecycle.js";
+import "./messages.js";
+import "./subgraphs.js";
+import "./values.js";
+export {};

package/dist/stream/transformers/lifecycle.cjs

@@ -0,0 +1,326 @@
+const require_stream_channel = require("../stream-channel.cjs");
+const require_mux = require("../mux.cjs");
+//#region src/stream/transformers/lifecycle.ts
+/**
+* Filter a lifecycle {@link StreamChannel} to only the entries whose
+* namespace lies within the subtree rooted at {@link path}.
+*
+* Returns an `AsyncIterable` whose iterator yields every entry whose
+* namespace either equals {@link path} or is a descendant of it.
+* Iteration begins at {@link startAt}, so callers can capture the
+* log's current size at construction time to skip entries emitted
+* before the caller existed (e.g. a subgraph stream discovered
+* mid-run shouldn't replay the root's `started`).
+*
+* @param log - The shared lifecycle log owned by the transformer.
+* @param path - Namespace prefix to scope entries by (use `[]` for
+*   the root subtree, i.e. everything).
+* @param startAt - Zero-based index into the log to begin from.
+* @returns An async iterable of matching lifecycle entries.
+*/
+function filterLifecycleEntries(log, path, startAt = 0) {
+	return { [Symbol.asyncIterator]() {
+		const base = log.iterate(startAt);
+		return { async next() {
+			while (true) {
+				const result = await base.next();
+				if (result.done) return {
+					value: void 0,
+					done: true
+				};
+				if (require_mux.hasPrefix(result.value.namespace, path)) return {
+					value: result.value,
+					done: false
+				};
+			}
+		} };
+	} };
+}
+const DEFAULT_ROOT_GRAPH_NAME = "root";
+function defaultGuessGraphName(ns) {
+	if (ns.length === 0) return DEFAULT_ROOT_GRAPH_NAME;
+	const last = ns[ns.length - 1];
+	const colon = last.indexOf(":");
+	return colon === -1 ? last : last.slice(0, colon);
+}
+function defaultSerializeError(err) {
+	if (err instanceof Error) return err.message;
+	if (typeof err === "string") return err;
+	try {
+		return JSON.stringify(err);
+	} catch {
+		return String(err);
+	}
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Extract an upstream `cause` from a `lifecycle.started` payload, if
+* the shape matches one of the known variants. Shape validation is
+* intentionally loose: any object with a string `type` is accepted, so
+* future protocol variants flow through unchanged.
+*/
+function extractCause(data) {
+	if (!isRecord(data)) return void 0;
+	if (data.event !== "started") return void 0;
+	const cause = data.cause;
+	if (!isRecord(cause)) return void 0;
+	if (typeof cause.type !== "string") return void 0;
+	return cause;
+}
+function extractTaskResultCompletion(data) {
+	if (!isRecord(data)) return void 0;
+	if (!("result" in data)) return void 0;
+	if (typeof data.name !== "string") return void 0;
+	if (typeof data.id !== "string") return void 0;
+	if (data.name.startsWith("__")) return void 0;
+	return {
+		name: data.name,
+		id: data.id
+	};
+}
+/**
+* Create the built-in lifecycle transformer.
+*
+* Marked as a {@link NativeStreamTransformer} so the run stream
+* factory can expose `_lifecycleLog` via a dedicated getter
+* (`run.lifecycle`) rather than through `run.extensions`.
+*/
+function createLifecycleTransformer(options = {}) {
+	const rootGraphName = options.rootGraphName ?? DEFAULT_ROOT_GRAPH_NAME;
+	const initialStatus = options.initialStatus ?? "running";
+	const emitRootOnRegister = options.emitRootOnRegister ?? true;
+	const getGraphName = options.getGraphName ?? defaultGuessGraphName;
+	const serializeError = options.serializeError ?? defaultSerializeError;
+	const getTerminalStatusOverride = options.getTerminalStatusOverride;
+	const log = require_stream_channel.StreamChannel.local();
+	const namespaces = /* @__PURE__ */ new Map();
+	const namespaceCause = /* @__PURE__ */ new Map();
+	const pendingInterruptIds = /* @__PURE__ */ new Set();
+	/**
+	* Child namespaces whose parent just saw an `updates` event with a
+	* `node` attribution. We defer the `lifecycle.completed` emission
+	* until the *next* inbound event (or `finalize`) so the parent's
+	* `updates` lands on the wire before its child is marked complete -
+	* matching the previous session behavior.
+	*/
+	const pendingCompletions = [];
+	let emitter;
+	let inSelfEmit = 0;
+	let finalized = false;
+	const resolveGraphName = (ns) => ns.length === 0 ? rootGraphName : getGraphName(ns);
+	const emit = (ns, status, extras) => {
+		const key = require_mux.nsKey(ns);
+		let current = namespaces.get(key);
+		const graphName = current?.graphName ?? resolveGraphName(ns);
+		if (current != null && current.status === status && current.graphName === graphName && extras?.error == null) return;
+		if (current == null) {
+			current = {
+				namespace: ns,
+				graphName,
+				status
+			};
+			namespaces.set(key, current);
+		} else current.status = status;
+		const data = {
+			event: status,
+			graph_name: graphName,
+			...extras?.cause != null ? { cause: extras.cause } : {},
+			...extras?.error != null ? { error: extras.error } : {}
+		};
+		const timestamp = Date.now();
+		log.push({
+			namespace: ns,
+			timestamp,
+			...data
+		});
+		if (ns.length === 0 && !emitRootOnRegister) return;
+		if (emitter == null) return;
+		inSelfEmit += 1;
+		try {
+			emitter.push(ns, {
+				type: "event",
+				seq: 0,
+				method: "lifecycle",
+				params: {
+					namespace: ns,
+					timestamp,
+					data
+				}
+			});
+		} finally {
+			inSelfEmit -= 1;
+		}
+	};
+	/**
+	* Ensures a record exists for `ns` without mutating its status. Used
+	* by hooks that need a canonical `graphName` for lookups before emit
+	* writes the first status. Status remains `undefined` until `emit`
+	* fires.
+	*/
+	const trackNamespace = (ns) => {
+		const key = require_mux.nsKey(ns);
+		let rec = namespaces.get(key);
+		if (rec == null) {
+			rec = {
+				namespace: ns,
+				graphName: resolveGraphName(ns),
+				status: void 0
+			};
+			namespaces.set(key, rec);
+		}
+		return rec;
+	};
+	const flushPendingCompletions = () => {
+		if (pendingCompletions.length === 0) return;
+		const toFlush = pendingCompletions.splice(0, pendingCompletions.length);
+		for (const completion of toFlush) {
+			const key = require_mux.nsKey(completion.namespace);
+			const rec = namespaces.get(key);
+			if (rec == null || rec.status !== "started") continue;
+			emit(completion.namespace, "completed");
+		}
+	};
+	const enqueueCompletion = (completion) => {
+		const key = require_mux.nsKey(completion.namespace);
+		const rec = namespaces.get(key);
+		if (rec == null || rec.status !== "started") return;
+		if (pendingCompletions.some((pending) => require_mux.nsKey(pending.namespace) === key)) return;
+		pendingCompletions.push(completion);
+	};
+	const removePendingNodeCompletions = (parent, node) => {
+		for (let index = pendingCompletions.length - 1; index >= 0; index -= 1) {
+			const pending = pendingCompletions[index];
+			if (pending.source.type !== "node") continue;
+			if (pending.source.node !== node) continue;
+			if (require_mux.nsKey(pending.source.parent) !== require_mux.nsKey(parent)) continue;
+			pendingCompletions.splice(index, 1);
+		}
+	};
+	const ensureStarted = (ns) => {
+		for (let length = 1; length <= ns.length; length += 1) {
+			const prefix = ns.slice(0, length);
+			const key = require_mux.nsKey(prefix);
+			if (namespaces.has(key)) continue;
+			trackNamespace(prefix);
+			const cause = namespaceCause.get(key);
+			emit(prefix, "started", cause != null ? { cause } : void 0);
+		}
+	};
+	const defaultTerminalStatus = () => pendingInterruptIds.size > 0 ? "interrupted" : "completed";
+	const cascadeTerminalStatus = (status) => {
+		for (const rec of namespaces.values()) {
+			if (rec.namespace.length === 0) continue;
+			if (rec.status !== "started") continue;
+			emit(rec.namespace, status);
+		}
+		emit([], status);
+		log.close();
+	};
+	const resolveTerminalStatusOverride = async () => {
+		if (getTerminalStatusOverride == null) return defaultTerminalStatus();
+		try {
+			return await getTerminalStatusOverride() ?? defaultTerminalStatus();
+		} catch {
+			return defaultTerminalStatus();
+		}
+	};
+	const findStartedChildForNode = (parentNamespace, node) => {
+		const prefix = `${node}:`;
+		for (const rec of namespaces.values()) {
+			if (rec.namespace.length !== parentNamespace.length + 1) continue;
+			if (rec.status !== "started") continue;
+			if (!require_mux.hasPrefix(rec.namespace, parentNamespace)) continue;
+			const last = rec.namespace[rec.namespace.length - 1];
+			if (last === node || last.startsWith(prefix)) return rec.namespace;
+		}
+	};
+	const findStartedChildForTask = (parentNamespace, task) => {
+		const namespace = [...parentNamespace, `${task.name}:${task.id}`];
+		return namespaces.get(require_mux.nsKey(namespace))?.status === "started" ? namespace : void 0;
+	};
+	return {
+		__native: true,
+		init() {
+			return {
+				_lifecycleLog: log,
+				lifecycle: filterLifecycleEntries(log, [], 0)
+			};
+		},
+		onRegister(handle) {
+			emitter = handle;
+			trackNamespace([]);
+			if (emitRootOnRegister) emit([], initialStatus);
+		},
+		process(event) {
+			const ns = event.params.namespace;
+			if (inSelfEmit > 0) return true;
+			const taskCompletion = event.method === "tasks" ? extractTaskResultCompletion(event.params.data) : void 0;
+			if (taskCompletion != null) removePendingNodeCompletions(ns, taskCompletion.name);
+			flushPendingCompletions();
+			if (event.method === "lifecycle") {
+				const cause = extractCause(event.params.data);
+				if (cause != null) namespaceCause.set(require_mux.nsKey(ns), cause);
+				ensureStarted(ns);
+				return false;
+			}
+			ensureStarted(ns);
+			if (event.method === "input" && isRecord(event.params.data) && event.params.data.event === "requested") {
+				const id = event.params.data.id;
+				if (typeof id === "string") pendingInterruptIds.add(id);
+			}
+			if (taskCompletion != null) {
+				const childNamespace = findStartedChildForTask(ns, taskCompletion);
+				if (childNamespace != null) enqueueCompletion({
+					namespace: childNamespace,
+					source: { type: "task" }
+				});
+			}
+			if (event.method === "updates") {
+				const node = event.params.node;
+				if (typeof node === "string" && !node.startsWith("__")) {
+					const childNamespace = findStartedChildForNode(ns, node);
+					if (childNamespace != null) enqueueCompletion({
+						namespace: childNamespace,
+						source: {
+							type: "node",
+							parent: ns,
+							node
+						}
+					});
+				}
+			}
+			return true;
+		},
+		finalize() {
+			if (finalized) return;
+			finalized = true;
+			flushPendingCompletions();
+			if (getTerminalStatusOverride == null) {
+				cascadeTerminalStatus(defaultTerminalStatus());
+				return;
+			}
+			return resolveTerminalStatusOverride().then(cascadeTerminalStatus).catch((err) => {
+				log.fail(err);
+			});
+		},
+		fail(err) {
+			if (finalized) return;
+			finalized = true;
+			const errorMessage = serializeError(err);
+			for (const rec of namespaces.values()) {
+				if (rec.namespace.length === 0) continue;
+				if (rec.status !== "started") continue;
+				emit(rec.namespace, "failed");
+			}
+			emit([], "failed", { error: errorMessage });
+			log.fail(err);
+		}
+	};
+}
+//#endregion
+exports.createLifecycleTransformer = createLifecycleTransformer;
+exports.filterLifecycleEntries = filterLifecycleEntries;
+
+//# sourceMappingURL=lifecycle.cjs.map

package/dist/stream/transformers/lifecycle.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.cjs","names":["hasPrefix","StreamChannel","nsKey"],"sources":["../../../src/stream/transformers/lifecycle.ts"],"sourcesContent":["/**\n * LifecycleTransformer - synthesizes `lifecycle` channel events that\n * track the status of the root run and every subgraph it spawns.\n *\n * The transformer is registered first in `createGraphRunStream` so that\n * every other transformer / consumer sees a coherent, authoritative\n * lifecycle stream. It is product-agnostic: deeper semantics (e.g.\n * DeepAgents' `SubagentTransformer` tool-call causation) reach the wire\n * by way of the re-entrant {@link StreamEmitter} - the transformer\n * stashes any `cause` attached upstream and re-emits its own\n * authoritative `lifecycle.started` with the correlation in place.\n *\n * Events are also pushed to a local {@link StreamChannel} so in-process\n * consumers can iterate `run.lifecycle` without filtering the main\n * event stream.\n */\n\nimport type {\n  AgentStatus,\n  LifecycleCause,\n  LifecycleData,\n} from \"@langchain/protocol\";\n\nimport { hasPrefix, nsKey } from \"../mux.js\";\nimport { StreamChannel } from \"../stream-channel.js\";\nimport type {\n  NativeStreamTransformer,\n  Namespace,\n  ProtocolEvent,\n  StreamEmitter,\n} from \"../types.js\";\nimport type { LifecycleEntry, LifecycleTransformerOptions } from \"./types.js\";\n\n/**\n * Projection returned from the lifecycle transformer's `init()`.\n *\n * The local `StreamChannel` is closed automatically when the transformer\n * finalizes or fails. `_lifecycleLog` is intentionally underscore-prefixed to\n * signal that it is consumed by the run stream wiring\n * (see `run-stream.ts`) and not meant for direct user access -\n * consumers should read `run.lifecycle` instead.\n *\n * The `lifecycle` iterable is the root-scoped projection (prefix\n * `[]`, starting at offset `0`) mirroring the pattern used by the\n * subgraph discovery transformer.  Root stream wiring consumes it\n * via `SET_LIFECYCLE_ITERABLE`; child streams are wired with their\n * own path-scoped iterable produced by `filterLifecycleEntries`.\n */\nexport interface LifecycleProjection {\n  _lifecycleLog: StreamChannel<LifecycleEntry>;\n  lifecycle: AsyncIterable<LifecycleEntry>;\n}\n\n/**\n * Filter a lifecycle {@link StreamChannel} to only the entries whose\n * namespace lies within the subtree rooted at {@link path}.\n *\n * Returns an `AsyncIterable` whose iterator yields every entry whose\n * namespace either equals {@link path} or is a descendant of it.\n * Iteration begins at {@link startAt}, so callers can capture the\n * log's current size at construction time to skip entries emitted\n * before the caller existed (e.g. a subgraph stream discovered\n * mid-run shouldn't replay the root's `started`).\n *\n * @param log - The shared lifecycle log owned by the transformer.\n * @param path - Namespace prefix to scope entries by (use `[]` for\n *   the root subtree, i.e. everything).\n * @param startAt - Zero-based index into the log to begin from.\n * @returns An async iterable of matching lifecycle entries.\n */\nexport function filterLifecycleEntries(\n  log: StreamChannel<LifecycleEntry>,\n  path: Namespace,\n  startAt = 0\n): AsyncIterable<LifecycleEntry> {\n  return {\n    [Symbol.asyncIterator](): AsyncIterator<LifecycleEntry> {\n      const base = log.iterate(startAt);\n      return {\n        async next(): Promise<IteratorResult<LifecycleEntry>> {\n          // eslint-disable-next-line no-constant-condition\n          while (true) {\n            const result = await base.next();\n            if (result.done) {\n              return {\n                value: undefined as unknown as LifecycleEntry,\n                done: true,\n              };\n            }\n            if (hasPrefix(result.value.namespace, path)) {\n              return { value: result.value, done: false };\n            }\n          }\n        },\n      };\n    },\n  };\n}\n\nconst DEFAULT_ROOT_GRAPH_NAME = \"root\";\n\nfunction defaultGuessGraphName(ns: Namespace): string {\n  if (ns.length === 0) return DEFAULT_ROOT_GRAPH_NAME;\n  const last = ns[ns.length - 1];\n  const colon = last.indexOf(\":\");\n  return colon === -1 ? last : last.slice(0, colon);\n}\n\nfunction defaultSerializeError(err: unknown): string {\n  // oxlint-disable-next-line no-instanceof/no-instanceof\n  if (err instanceof Error) return err.message;\n  if (typeof err === \"string\") return err;\n  try {\n    return JSON.stringify(err);\n  } catch {\n    return String(err);\n  }\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/**\n * Extract an upstream `cause` from a `lifecycle.started` payload, if\n * the shape matches one of the known variants. Shape validation is\n * intentionally loose: any object with a string `type` is accepted, so\n * future protocol variants flow through unchanged.\n */\nfunction extractCause(data: unknown): LifecycleCause | undefined {\n  if (!isRecord(data)) return undefined;\n  if (data.event !== \"started\") return undefined;\n  const cause = data.cause;\n  if (!isRecord(cause)) return undefined;\n  if (typeof cause.type !== \"string\") return undefined;\n  return cause as unknown as LifecycleCause;\n}\n\nfunction extractTaskResultCompletion(\n  data: unknown\n): TaskResultCompletion | undefined {\n  if (!isRecord(data)) return undefined;\n  if (!(\"result\" in data)) return undefined;\n  if (typeof data.name !== \"string\") return undefined;\n  if (typeof data.id !== \"string\") return undefined;\n  if (data.name.startsWith(\"__\")) return undefined;\n  return { name: data.name, id: data.id };\n}\n\ninterface NamespaceRecord {\n  readonly namespace: Namespace;\n  readonly graphName: string;\n  /** Last emitted status; `undefined` until `emit` fires for this namespace. */\n  status: AgentStatus | undefined;\n}\n\ninterface TaskResultCompletion {\n  readonly name: string;\n  readonly id: string;\n}\n\ninterface PendingCompletion {\n  readonly namespace: Namespace;\n  readonly source:\n    | { readonly type: \"task\" }\n    | {\n        readonly type: \"node\";\n        readonly parent: Namespace;\n        readonly node: string;\n      };\n}\n\n/**\n * Create the built-in lifecycle transformer.\n *\n * Marked as a {@link NativeStreamTransformer} so the run stream\n * factory can expose `_lifecycleLog` via a dedicated getter\n * (`run.lifecycle`) rather than through `run.extensions`.\n */\nexport function createLifecycleTransformer(\n  options: LifecycleTransformerOptions = {}\n): NativeStreamTransformer<LifecycleProjection> {\n  const rootGraphName = options.rootGraphName ?? DEFAULT_ROOT_GRAPH_NAME;\n  const initialStatus: AgentStatus = options.initialStatus ?? \"running\";\n  const emitRootOnRegister = options.emitRootOnRegister ?? true;\n  const getGraphName = options.getGraphName ?? defaultGuessGraphName;\n  const serializeError = options.serializeError ?? defaultSerializeError;\n  const getTerminalStatusOverride = options.getTerminalStatusOverride;\n\n  const log = StreamChannel.local<LifecycleEntry>();\n  const namespaces = new Map<string, NamespaceRecord>();\n  const namespaceCause = new Map<string, LifecycleCause>();\n  const pendingInterruptIds = new Set<string>();\n  /**\n   * Child namespaces whose parent just saw an `updates` event with a\n   * `node` attribution. We defer the `lifecycle.completed` emission\n   * until the *next* inbound event (or `finalize`) so the parent's\n   * `updates` lands on the wire before its child is marked complete -\n   * matching the previous session behavior.\n   */\n  const pendingCompletions: PendingCompletion[] = [];\n\n  let emitter: StreamEmitter | undefined;\n  let inSelfEmit = 0;\n  let finalized = false;\n\n  const resolveGraphName = (ns: Namespace): string =>\n    ns.length === 0 ? rootGraphName : getGraphName(ns);\n\n  const emit = (\n    ns: Namespace,\n    status: AgentStatus,\n    extras?: { cause?: LifecycleCause; error?: string }\n  ): void => {\n    const key = nsKey(ns);\n    let current = namespaces.get(key);\n    const graphName = current?.graphName ?? resolveGraphName(ns);\n\n    // Dedup: identical status + graph name + no error override => skip.\n    if (\n      current != null &&\n      current.status === status &&\n      current.graphName === graphName &&\n      extras?.error == null\n    ) {\n      return;\n    }\n\n    if (current == null) {\n      current = { namespace: ns, graphName, status };\n      namespaces.set(key, current);\n    } else {\n      current.status = status;\n    }\n\n    const data: LifecycleData = {\n      event: status,\n      graph_name: graphName,\n      ...(extras?.cause != null ? { cause: extras.cause } : {}),\n      ...(extras?.error != null ? { error: extras.error } : {}),\n    };\n\n    const timestamp = Date.now();\n\n    log.push({ namespace: ns, timestamp, ...data });\n\n    if (ns.length === 0 && !emitRootOnRegister) return;\n\n    if (emitter == null) return;\n\n    inSelfEmit += 1;\n    try {\n      emitter.push(ns, {\n        type: \"event\",\n        seq: 0,\n        method: \"lifecycle\",\n        params: { namespace: ns, timestamp, data },\n      });\n    } finally {\n      inSelfEmit -= 1;\n    }\n  };\n\n  /**\n   * Ensures a record exists for `ns` without mutating its status. Used\n   * by hooks that need a canonical `graphName` for lookups before emit\n   * writes the first status. Status remains `undefined` until `emit`\n   * fires.\n   */\n  const trackNamespace = (ns: Namespace): NamespaceRecord => {\n    const key = nsKey(ns);\n    let rec = namespaces.get(key);\n    if (rec == null) {\n      rec = {\n        namespace: ns,\n        graphName: resolveGraphName(ns),\n        status: undefined,\n      };\n      namespaces.set(key, rec);\n    }\n    return rec;\n  };\n\n  const flushPendingCompletions = (): void => {\n    if (pendingCompletions.length === 0) return;\n    const toFlush = pendingCompletions.splice(0, pendingCompletions.length);\n    for (const completion of toFlush) {\n      const key = nsKey(completion.namespace);\n      const rec = namespaces.get(key);\n      if (rec == null || rec.status !== \"started\") continue;\n      emit(completion.namespace, \"completed\");\n    }\n  };\n\n  const enqueueCompletion = (completion: PendingCompletion): void => {\n    const key = nsKey(completion.namespace);\n    const rec = namespaces.get(key);\n    if (rec == null || rec.status !== \"started\") return;\n    if (\n      pendingCompletions.some((pending) => nsKey(pending.namespace) === key)\n    ) {\n      return;\n    }\n    pendingCompletions.push(completion);\n  };\n\n  const removePendingNodeCompletions = (\n    parent: Namespace,\n    node: string\n  ): void => {\n    for (let index = pendingCompletions.length - 1; index >= 0; index -= 1) {\n      const pending = pendingCompletions[index];\n      if (pending.source.type !== \"node\") continue;\n      if (pending.source.node !== node) continue;\n      if (nsKey(pending.source.parent) !== nsKey(parent)) continue;\n      pendingCompletions.splice(index, 1);\n    }\n  };\n\n  const ensureStarted = (ns: Namespace): void => {\n    // Synthesize `lifecycle.started` for each unseen prefix of `ns`,\n    // outermost first. Deepest-first would force consumers to see a\n    // child's started before its parent, which is wrong.\n    for (let length = 1; length <= ns.length; length += 1) {\n      const prefix = ns.slice(0, length);\n      const key = nsKey(prefix);\n      if (namespaces.has(key)) continue;\n      trackNamespace(prefix);\n      const cause = namespaceCause.get(key);\n      emit(prefix, \"started\", cause != null ? { cause } : undefined);\n    }\n  };\n\n  const defaultTerminalStatus = (): AgentStatus =>\n    pendingInterruptIds.size > 0 ? \"interrupted\" : \"completed\";\n\n  const cascadeTerminalStatus = (status: AgentStatus): void => {\n    for (const rec of namespaces.values()) {\n      if (rec.namespace.length === 0) continue;\n      if (rec.status !== \"started\") continue;\n      emit(rec.namespace, status);\n    }\n    emit([], status);\n    log.close();\n  };\n\n  const resolveTerminalStatusOverride = async (): Promise<AgentStatus> => {\n    if (getTerminalStatusOverride == null) return defaultTerminalStatus();\n    try {\n      return (await getTerminalStatusOverride()) ?? defaultTerminalStatus();\n    } catch {\n      return defaultTerminalStatus();\n    }\n  };\n\n  const findStartedChildForNode = (\n    parentNamespace: Namespace,\n    node: string\n  ): Namespace | undefined => {\n    const prefix = `${node}:`;\n    for (const rec of namespaces.values()) {\n      if (rec.namespace.length !== parentNamespace.length + 1) continue;\n      if (rec.status !== \"started\") continue;\n      if (!hasPrefix(rec.namespace, parentNamespace)) continue;\n      const last = rec.namespace[rec.namespace.length - 1];\n      if (last === node || last.startsWith(prefix)) return rec.namespace;\n    }\n    return undefined;\n  };\n\n  const findStartedChildForTask = (\n    parentNamespace: Namespace,\n    task: TaskResultCompletion\n  ): Namespace | undefined => {\n    const namespace = [...parentNamespace, `${task.name}:${task.id}`];\n    const rec = namespaces.get(nsKey(namespace));\n    return rec?.status === \"started\" ? namespace : undefined;\n  };\n\n  const transformer: NativeStreamTransformer<LifecycleProjection> = {\n    __native: true,\n\n    init() {\n      return {\n        _lifecycleLog: log,\n        lifecycle: filterLifecycleEntries(log, [], 0),\n      };\n    },\n\n    onRegister(handle: StreamEmitter) {\n      emitter = handle;\n      // Seed root record so cascade logic can see it, even when the\n      // outer authority owns root emission.\n      trackNamespace([]);\n      if (emitRootOnRegister) {\n        emit([], initialStatus);\n      }\n    },\n\n    process(event: ProtocolEvent): boolean {\n      const ns = event.params.namespace;\n\n      // Re-entrant loopback: an event we emitted via `emitter.push`\n      // is being routed back through this transformer by the mux.\n      // Allow it through the wire unchanged.\n      if (inSelfEmit > 0) return true;\n\n      const taskCompletion =\n        event.method === \"tasks\"\n          ? extractTaskResultCompletion(event.params.data)\n          : undefined;\n      if (taskCompletion != null) {\n        // Prefer exact task-result attribution over any ambiguous\n        // `updates.node` completion deferred from the previous event.\n        removePendingNodeCompletions(ns, taskCompletion.name);\n      }\n\n      // Flush any completions deferred by the previous event so the\n      // wire order is [triggering event] -> [deferred completed].\n      flushPendingCompletions();\n\n      // Upstream `lifecycle` events: stash any `cause` attached by a\n      // product-specific transformer (e.g. deepagents' SubagentTransformer),\n      // synthesize our authoritative started/... for the namespace, and\n      // suppress the original so we are the single source of truth.\n      if (event.method === \"lifecycle\") {\n        const cause = extractCause(event.params.data);\n        if (cause != null) {\n          namespaceCause.set(nsKey(ns), cause);\n        }\n        ensureStarted(ns);\n        return false;\n      }\n\n      // Lifecycle for parent + any unseen prefix => synthesize started.\n      ensureStarted(ns);\n\n      // Track interrupt ids so `finalize` can decide between\n      // `completed` and `interrupted`.\n      if (\n        event.method === \"input\" &&\n        isRecord(event.params.data) &&\n        event.params.data.event === \"requested\"\n      ) {\n        const id = (event.params.data as { id?: unknown }).id;\n        if (typeof id === \"string\") {\n          pendingInterruptIds.add(id);\n        }\n      }\n\n      if (taskCompletion != null) {\n        const childNamespace = findStartedChildForTask(ns, taskCompletion);\n        if (childNamespace != null) {\n          enqueueCompletion({\n            namespace: childNamespace,\n            source: { type: \"task\" },\n          });\n        }\n      }\n\n      // Defer child-node completion: the `updates` event carries the\n      // node attribution; the corresponding child namespace is\n      // `[...ns, \"<node>:<uuid>\"]`. We pick the oldest still-started\n      // matching child (LangGraph emits one updates per completed task\n      // so repeated calls drain parallel fan-outs in order).\n      if (event.method === \"updates\") {\n        const node = event.params.node;\n        if (typeof node === \"string\" && !node.startsWith(\"__\")) {\n          const childNamespace = findStartedChildForNode(ns, node);\n          if (childNamespace != null) {\n            enqueueCompletion({\n              namespace: childNamespace,\n              source: { type: \"node\", parent: ns, node },\n            });\n          }\n        }\n      }\n\n      return true;\n    },\n\n    finalize(): void | PromiseLike<void> {\n      if (finalized) return;\n      finalized = true;\n      flushPendingCompletions();\n\n      if (getTerminalStatusOverride == null) {\n        cascadeTerminalStatus(defaultTerminalStatus());\n        return;\n      }\n\n      return resolveTerminalStatusOverride()\n        .then(cascadeTerminalStatus)\n        .catch((err) => {\n          log.fail(err);\n        });\n    },\n\n    fail(err: unknown) {\n      if (finalized) return;\n      finalized = true;\n      const errorMessage = serializeError(err);\n\n      // Cascade `failed` to every still-started namespace. Children\n      // that had already entered a terminal state are left untouched\n      // by the dedup guard in `emit`.\n      for (const rec of namespaces.values()) {\n        if (rec.namespace.length === 0) continue;\n        if (rec.status !== \"started\") continue;\n        emit(rec.namespace, \"failed\");\n      }\n\n      emit([], \"failed\", { error: errorMessage });\n      log.fail(err);\n    },\n  };\n\n  return transformer;\n}\n"],"mappings":"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"}