Broaden compile(transformers=...) signature to accept scope-aware factories

# Conflicts:
#	libs/langgraph/langgraph/stream/__init__.py
#	libs/langgraph/langgraph/stream/graph_streamer.py
#	libs/langgraph/langgraph/stream/run_stream.py
#	libs/langgraph/tests/test_graph_streamer.py
#	libs/langgraph/tests/test_pregel_stream_v2.py
#	libs/langgraph/tests/test_stream_messages_transformer.py
#	libs/langgraph/tests/test_stream_subgraph_transformer.py
#	libs/langgraph/tests/test_streaming_handler.py

libs/langgraph/langgraph/_internal/_constants.py

@@ -66,6 +66,9 @@ CONFIG_KEY_RUNTIME = sys.intern("__pregel_runtime")
 # holds a `Runtime` instance with context, store, stream writer, etc.
 CONFIG_KEY_RESUME_MAP = sys.intern("__pregel_resume_map")
 # holds a mapping of task ns -> resume value for resuming tasks
+CONFIG_KEY_STREAM_MESSAGES_V2 = sys.intern("__pregel_stream_messages_v2")
+# when True, attach StreamMessagesHandlerV2 so content-block (v2) events
+# flow through stream_mode="messages"; set by GraphStreamer only.
 
 # --- Other constants ---
 PUSH = sys.intern("__pregel_push")
@@ -107,6 +110,7 @@ RESERVED = {
     CONFIG_KEY_CHECKPOINT_ID,
     CONFIG_KEY_CHECKPOINT_NS,
     CONFIG_KEY_RESUME_MAP,
+    CONFIG_KEY_STREAM_MESSAGES_V2,
     # other constants
     PUSH,
     PULL,

libs/langgraph/langgraph/config.py

@@ -1,5 +1,7 @@
 import asyncio
 import sys
+from collections.abc import Callable
+from contextvars import ContextVar
 from typing import Any
 
 from langchain_core.runnables import RunnableConfig
@@ -9,6 +11,18 @@ from langgraph.store.base import BaseStore
 from langgraph._internal._constants import CONF, CONFIG_KEY_RUNTIME
 from langgraph.types import StreamWriter
 
+_tool_call_writer: ContextVar[Callable[[Any], None] | None] = ContextVar(
+    "langgraph_tool_call_writer", default=None
+)
+"""ContextVar holding the writer for the currently-executing tool call.
+
+Set by `StreamToolCallHandler.on_tool_start` and reset on end/error.
+Defined here (rather than alongside the handler in `pregel/_tools.py`)
+so `emit_tool_output_delta` can import it without triggering the
+pregel import chain — user tool code does
+`from langgraph.config import emit_tool_output_delta` at import time.
+"""
+
 
 def _no_op_stream_writer(c: Any) -> None:
     pass
@@ -194,3 +208,30 @@ def get_stream_writer() -> StreamWriter:
     """
     runtime = get_config()[CONF][CONFIG_KEY_RUNTIME]
     return runtime.stream_writer
+
+
+def emit_tool_output_delta(delta: Any) -> None:
+    """Emit a `tool-output-delta` event onto the `tools` stream mode.
+
+    Must be called from inside a tool's execution scope (sync or async).
+    While a tool is running, `StreamToolCallHandler.on_tool_start` sets a
+    writer closure on a ContextVar keyed to that call's `tool_call_id`
+    and namespace; this helper reads the ContextVar and forwards `delta`
+    through it.
+
+    When called outside any tool call, or when the graph was not
+    streamed with `"tools"` in `stream_mode`, this is a silent no-op —
+    tool authors can leave `emit_tool_output_delta` calls in place
+    without gating them on stream mode.
+
+    Args:
+        delta: The partial output chunk to stream. Shape is up to the
+            caller — strings are the common case, but any JSON-
+            serializable value is accepted and surfaced as-is on the
+            `tools` channel's `tool-output-delta` payload under
+            `"delta"`.
+    """
+    writer = _tool_call_writer.get()
+    if writer is None:
+        return
+    writer(delta)

libs/langgraph/langgraph/graph/state.py

@@ -1045,6 +1045,7 @@ class StateGraph(Generic[StateT, ContextT, InputT, OutputT]):
         interrupt_after: All | list[str] | None = None,
         debug: bool = False,
         name: str | None = None,
+        transformers: Sequence[Callable[..., Any]] | None = None,
     ) -> CompiledStateGraph[StateT, ContextT, InputT, OutputT]:
         """Compiles the `StateGraph` into a `CompiledStateGraph` object.
 
@@ -1077,6 +1078,11 @@ class StateGraph(Generic[StateT, ContextT, InputT, OutputT]):
             interrupt_after: An optional list of node names to interrupt after.
             debug: A flag indicating whether to enable debug mode.
             name: The name to use for the compiled graph.
+            transformers: Optional sequence of zero-arg factories returning
+                `StreamTransformer` instances. Registered on the compiled
+                graph and instantiated per-run whenever `stream_v2` /
+                `astream_v2` is called. Appended after the built-in
+                `ValuesTransformer` and `MessagesTransformer`.
 
         Returns:
             CompiledStateGraph: The compiled `StateGraph`.
@@ -1159,6 +1165,7 @@ class StateGraph(Generic[StateT, ContextT, InputT, OutputT]):
             store=store,
             cache=cache,
             name=name or "LangGraph",
+            stream_transformers=transformers,
         )
         compiled._serde_allowlist = serde_allowlist
 

libs/langgraph/langgraph/pregel/_lifecycle.py

@@ -0,0 +1,291 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Callable, Iterator
+from typing import Any, TypeVar, cast
+from uuid import UUID
+
+from langchain_core.callbacks import BaseCallbackHandler
+
+from langgraph._internal._constants import NS_SEP
+from langgraph.errors import GraphInterrupt
+from langgraph.pregel.protocol import StreamChunk
+
+try:
+    from langchain_core.tracers._streaming import _StreamingCallbackHandler
+except ImportError:
+    _StreamingCallbackHandler = object  # type: ignore[assignment,misc]
+
+
+T = TypeVar("T")
+
+
+_LANGGRAPH_SENTINEL_NODES = frozenset({"__start__", "__end__"})
+
+
+def _is_nested_pregel_start(
+    name: str | None,
+    metadata: dict[str, Any] | None,
+    parent_run_id: UUID | None,
+    task_run_ids: set[UUID],
+) -> bool:
+    """Recognize a nested `Pregel` invocation from its `on_chain_start` metadata.
+
+    When a compiled graph is added as a node, pregel fires two
+    `on_chain_start` callbacks at that task: first for the node chain
+    (whose `name` matches `metadata["langgraph_node"]`) and second for
+    the inner `Pregel` chain (whose `name` is the graph's `name`, not
+    the node name). Both share the same `langgraph_checkpoint_ns`.
+
+    Primary signal: a `langgraph_checkpoint_ns` is set AND `name`
+    differs from the owning task's `langgraph_node`. This covers the
+    common case where the compiled subgraph's name differs from the
+    node name it was registered under.
+
+    Fallback for name collisions (subgraph compiled with
+    `name == node_name`): the inner `Pregel` start's `parent_run_id`
+    is the run_id of the node chain's start event, which the handler
+    records in `task_run_ids` on the first start. Matching
+    `parent_run_id` to that set identifies the second start as the
+    nested `Pregel` even when names coincide.
+
+    Regular node chains are skipped; the root `Pregel` (which has no
+    `langgraph_node` metadata) isn't observed by this handler because
+    the root's start fires before the handler is attached.
+
+    Metadata-based detection is used because `on_chain_start`'s
+    `serialized` argument is `None` for compiled graphs in this
+    version of langchain-core, so class-based detection via
+    `serialized["id"]` isn't available.
+
+    Sentinel nodes (`__start__` / `__end__`) are excluded: conditional
+    edges from `START` fire an `on_chain_start` with `lg_node=__start__`
+    and the router function's name as `name`, which would otherwise
+    match the discriminator without representing an actual nested
+    `Pregel`.
+
+    Args:
+        name: The `name` kwarg from `on_chain_start`.
+        metadata: The `metadata` kwarg from `on_chain_start`.
+        parent_run_id: The `parent_run_id` kwarg from `on_chain_start`.
+        task_run_ids: The set of run_ids the handler has already seen
+            as node-chain starts (i.e. `name == langgraph_node`).
+    """
+    if not metadata:
+        return False
+    if not metadata.get("langgraph_checkpoint_ns"):
+        return False
+    lg_node = metadata.get("langgraph_node")
+    if lg_node is None or lg_node in _LANGGRAPH_SENTINEL_NODES:
+        return False
+    if name != lg_node:
+        return True
+    # Name collision fallback: the inner Pregel's parent_run_id is
+    # the node chain's run_id, which we recorded when that node
+    # chain's start fired.
+    return parent_run_id is not None and parent_run_id in task_run_ids
+
+
+class StreamLifecycleHandler(BaseCallbackHandler, _StreamingCallbackHandler):
+    """Callback handler that emits subgraph lifecycle events on the stream.
+
+    Pushes `LifecycleData`-shaped payloads onto the pregel stream under
+    the `"lifecycle"` mode, keyed by the subgraph's namespace tuple.
+    Drives the `started` → `running` → `completed` / `failed` /
+    `interrupted` state machine.
+
+    The handler is attached to `run_manager.inheritable_handlers` inside
+    a `Pregel.stream` / `astream` call, so it sees callbacks for every
+    descendant chain (nodes, nested `Pregel` subgraphs) but *not* for
+    the root `Pregel` whose start event has already fired. The root's
+    `started` event is emitted eagerly at construction; its terminal
+    state is emitted by `SubgraphTransformer.finalize` / `fail`.
+
+    `run_inline = True` keeps event ordering deterministic.
+    """
+
+    run_inline = True
+
+    def __init__(
+        self,
+        stream: Callable[[StreamChunk], None],
+        *,
+        root_graph_name: str | None = None,
+    ) -> None:
+        """Initialize the handler and emit the root graph's `started` event.
+
+        Args:
+            stream: Callable that accepts a `StreamChunk` tuple
+                `(namespace, mode, payload)` and enqueues it.
+            root_graph_name: The root `Pregel` instance's `name`, emitted
+                with the root's `started` lifecycle payload.
+        """
+        self.stream = stream
+        # Namespaces awaiting the started→running transition.
+        self._pending_running: set[tuple[str, ...]] = set()
+        # run_id → subgraph namespace; populated only for Pregel chains.
+        self._run_to_ns: dict[UUID, tuple[str, ...]] = {}
+        # run_ids of node-chain starts (name == langgraph_node); used
+        # as the parent_run_id fallback when a subgraph's name equals
+        # its node name. Cleared as each chain ends.
+        self._task_run_ids: set[UUID] = set()
+
+        root_payload: dict[str, Any] = {"event": "started"}
+        if root_graph_name is not None:
+            root_payload["graph_name"] = root_graph_name
+        self.stream(((), "lifecycle", root_payload))
+        self._pending_running.add(())
+
+    @staticmethod
+    def _subgraph_ns_from_metadata(metadata: dict[str, Any] | None) -> tuple[str, ...]:
+        """Return the running subgraph's own namespace from task metadata.
+
+        For a nested `Pregel` invoked as a node, `langgraph_checkpoint_ns`
+        ends at the node segment (no inner task appended yet), so
+        splitting on `NS_SEP` gives the subgraph's own namespace.
+        """
+        if not metadata:
+            return ()
+        nskey = metadata.get("langgraph_checkpoint_ns")
+        if not nskey:
+            return ()
+        return tuple(cast(str, nskey).split(NS_SEP))
+
+    @staticmethod
+    def _containing_ns_from_metadata(
+        metadata: dict[str, Any] | None,
+    ) -> tuple[str, ...]:
+        """Return the namespace of the subgraph that contains this task.
+
+        For an inner task with `langgraph_checkpoint_ns`
+        `"seg_a|seg_b"`, the containing subgraph is `("seg_a",)`.
+        """
+        if not metadata:
+            return ()
+        nskey = metadata.get("langgraph_checkpoint_ns")
+        if not nskey:
+            return ()
+        return tuple(cast(str, nskey).split(NS_SEP))[:-1]
+
+    @staticmethod
+    def _trigger_call_id(metadata: dict[str, Any] | None) -> str | None:
+        """Extract `trigger_call_id` from task metadata if present.
+
+        The task that spawned a nested `Pregel` has its task id encoded
+        in `langgraph_checkpoint_ns`'s last segment as
+        `node_name:task_id`. Returns the `task_id` portion, which
+        parents can correlate with their `tools` / `tasks` events.
+        """
+        if not metadata:
+            return None
+        nskey = cast(str | None, metadata.get("langgraph_checkpoint_ns"))
+        if not nskey:
+            return None
+        last = nskey.split(NS_SEP)[-1]
+        _, sep, task_id = last.rpartition(":")
+        return task_id if sep else None
+
+    def _emit(self, ns: tuple[str, ...], payload: dict[str, Any]) -> None:
+        self.stream((ns, "lifecycle", payload))
+
+    def tap_output_aiter(
+        self, run_id: UUID, output: AsyncIterator[T]
+    ) -> AsyncIterator[T]:
+        """Pass-through — required by the `_StreamingCallbackHandler` protocol.
+
+        Returns the iterator unchanged. A missing implementation lets
+        langchain's default `Protocol` body return `None`, which breaks
+        the `_consume_aiter` code path in `_runnable.py:900`.
+        """
+        return output
+
+    def tap_output_iter(self, run_id: UUID, output: Iterator[T]) -> Iterator[T]:
+        """Pass-through — sync counterpart to `tap_output_aiter`."""
+        return output
+
+    def _fire_running_if_pending(self, ns: tuple[str, ...]) -> None:
+        if ns in self._pending_running:
+            self._pending_running.discard(ns)
+            self._emit(ns, {"event": "running"})
+
+    def on_chain_start(
+        self,
+        serialized: dict[str, Any],
+        inputs: dict[str, Any],
+        *,
+        run_id: UUID,
+        parent_run_id: UUID | None = None,
+        tags: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        # Any descendant activity transitions the containing subgraph to running.
+        containing = self._containing_ns_from_metadata(metadata)
+        self._fire_running_if_pending(containing)
+
+        name = cast(str | None, kwargs.get("name"))
+        lg_node = (metadata or {}).get("langgraph_node")
+
+        # Record node-chain starts so the name-collision fallback in
+        # `_is_nested_pregel_start` can match the inner Pregel's
+        # parent_run_id to them.
+        if (
+            lg_node is not None
+            and lg_node not in _LANGGRAPH_SENTINEL_NODES
+            and name == lg_node
+        ):
+            self._task_run_ids.add(run_id)
+
+        if not _is_nested_pregel_start(
+            name, metadata, parent_run_id, self._task_run_ids
+        ):
+            return
+
+        ns = self._subgraph_ns_from_metadata(metadata)
+        if not ns:
+            return
+
+        self._run_to_ns[run_id] = ns
+        payload: dict[str, Any] = {"event": "started"}
+        if name:
+            payload["graph_name"] = name
+        trigger_call_id = self._trigger_call_id(metadata)
+        if trigger_call_id:
+            payload["trigger_call_id"] = trigger_call_id
+        self._emit(ns, payload)
+        self._pending_running.add(ns)
+
+    def on_chain_end(
+        self,
+        response: Any,
+        *,
+        run_id: UUID,
+        parent_run_id: UUID | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        self._task_run_ids.discard(run_id)
+        ns = self._run_to_ns.pop(run_id, None)
+        if ns is None:
+            return
+        # Ensure started→running fired even for empty subgraphs.
+        if ns in self._pending_running:
+            self._pending_running.discard(ns)
+            self._emit(ns, {"event": "running"})
+        self._emit(ns, {"event": "completed"})
+
+    def on_chain_error(
+        self,
+        error: BaseException,
+        *,
+        run_id: UUID,
+        parent_run_id: UUID | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        self._task_run_ids.discard(run_id)
+        ns = self._run_to_ns.pop(run_id, None)
+        if ns is None:
+            return
+        self._pending_running.discard(ns)
+        if isinstance(error, GraphInterrupt):
+            self._emit(ns, {"event": "interrupted"})
+        else:
+            self._emit(ns, {"event": "failed", "error": str(error)})

libs/langgraph/langgraph/pregel/_messages.py

@@ -24,6 +24,11 @@ try:
 except ImportError:
     _StreamingCallbackHandler = object  # type: ignore
 
+try:
+    from langchain_core.tracers._streaming import _V2StreamingCallbackHandler
+except ImportError:
+    _V2StreamingCallbackHandler = object  # type: ignore
+
 T = TypeVar("T")
 Meta = tuple[tuple[str, ...], dict[str, Any]]
 
@@ -256,3 +261,78 @@ class StreamMessagesHandler(BaseCallbackHandler, _StreamingCallbackHandler):
         **kwargs: Any,
     ) -> Any:
         self.metadata.pop(run_id, None)
+
+
+class StreamMessagesHandlerV2(StreamMessagesHandler, _V2StreamingCallbackHandler):
+    """v2 variant of `StreamMessagesHandler`.
+
+    Declaring `_V2StreamingCallbackHandler` as a base flips
+    `BaseChatModel.invoke` to route through `_stream_chat_model_events`
+    (firing `on_stream_event`) instead of `_stream` (firing
+    `on_llm_new_token`). Inherits `on_stream_event` from the parent,
+    which forwards protocol events onto the messages stream channel.
+
+    Pregel attaches this class instead of the v1 handler only when
+    `GraphStreamer` opts in via the internal
+    `CONFIG_KEY_STREAM_MESSAGES_V2` config key; direct
+    `graph.stream(stream_mode="messages")` callers keep the v1
+    AIMessageChunk shape.
+    """
+
+    def on_llm_new_token(
+        self,
+        token: str,
+        *,
+        chunk: ChatGenerationChunk | None = None,
+        run_id: UUID,
+        parent_run_id: UUID | None = None,
+        tags: list[str] | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Intentional no-op — v1 chunks are not used on v2-flagged runs.
+
+        The v2 marker already steers `invoke` to the event generator, so
+        `on_llm_new_token` should not fire under normal routing. This
+        override stays a pass-through (no call to `super()`) to make
+        the intent explicit and to guard against any caller (e.g. a
+        node that calls `model.stream()` directly, which still fires
+        the v1 callback) leaking AIMessageChunks onto a v2-flagged
+        messages stream.
+        """
+        # Intentionally empty: v2 handler does not forward v1 chunks.
+
+    def on_stream_event(
+        self,
+        event: dict[str, Any],
+        *,
+        run_id: UUID,
+        parent_run_id: UUID | None = None,
+        tags: list[str] | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Forward a protocol event from `stream_v2` as a messages stream part.
+
+        Fires once per `MessagesData` event (`message-start`, per-block
+        `content-block-*`, `message-finish`). The transformer layer
+        correlates events back to a single `ChatModelStream` via
+        `metadata["run_id"]` — attached here so the v1
+        `stream_mode="messages"` output (which emits
+        `(AIMessageChunk, metadata)` via `on_llm_new_token`) keeps its
+        original metadata shape.
+
+        Lives on the v2 handler rather than the v1 base: content-block
+        events are a v2-only concept, and forwarding them only when the
+        v2 handler is attached keeps the message channel's shape
+        predictable for v1 callers.
+        """
+        if meta := self.metadata.get(run_id):
+            # Record message_id on message-start so on_chain_end's
+            # dedupe skips the finalized AIMessage the node returns
+            # (otherwise the messages projection double-counts: once
+            # from streaming, once from the chain output).
+            if event.get("event") == "message-start":
+                msg_id = event.get("message_id")
+                if msg_id:
+                    self.seen.add(msg_id)
+            v2_meta = {**meta[1], "run_id": str(run_id)}
+            self.stream((meta[0], "messages", (event, v2_meta)))

libs/langgraph/langgraph/pregel/_tools.py

@@ -0,0 +1,223 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Callable, Iterator
+from contextvars import Token
+from typing import Any, TypeVar, cast
+from uuid import UUID
+
+from langchain_core.callbacks import BaseCallbackHandler
+
+from langgraph._internal._constants import NS_SEP
+from langgraph.config import _tool_call_writer
+from langgraph.pregel.protocol import StreamChunk
+
+try:
+    from langchain_core.tracers._streaming import _StreamingCallbackHandler
+except ImportError:
+    _StreamingCallbackHandler = object  # type: ignore[assignment,misc]
+
+
+T = TypeVar("T")
+
+ToolCallWriter = Callable[[Any], None]
+"""A closure bound to a single tool call that emits `tool-output-delta` events."""
+
+
+class StreamToolCallHandler(BaseCallbackHandler, _StreamingCallbackHandler):
+    """Callback handler that emits tool-call lifecycle events on the stream.
+
+    Fires on LangChain's `on_tool_*` callbacks and pushes to the `tools`
+    stream mode. Emits `tool-started` / `tool-output-delta` /
+    `tool-finished` / `tool-error` payloads keyed by `tool_call_id`.
+
+    While a tool is executing, this handler sets `_tool_call_writer` to a
+    closure bound to that call's namespace and `tool_call_id`. The
+    `emit_tool_output_delta` helper in `langgraph.config` reads that
+    ContextVar so tool bodies can stream partial output without threading
+    the writer through their own signature.
+
+    Attached by `Pregel.stream` / `astream` when `"tools"` is in
+    `stream_modes`. `run_inline = True` keeps event ordering
+    deterministic.
+    """
+
+    run_inline = True
+
+    def __init__(self, stream: Callable[[StreamChunk], None]) -> None:
+        """Initialize the handler.
+
+        Args:
+            stream: Callable that accepts a `StreamChunk` tuple
+                `(namespace, mode, payload)` and enqueues it.
+        """
+        self.stream = stream
+        # run_id → (namespace, tool_call_id, ContextVar token)
+        # `on_tool_end` does not receive `tool_call_id` in kwargs, so
+        # we correlate by `run_id` which is present on every callback.
+        self._run_to_call: dict[
+            UUID, tuple[tuple[str, ...], str, Token[ToolCallWriter | None]]
+        ] = {}
+
+    @staticmethod
+    def _containing_ns_from_metadata(
+        metadata: dict[str, Any] | None,
+    ) -> tuple[str, ...]:
+        """Return the namespace of the subgraph that contains this tool call.
+
+        `langgraph_checkpoint_ns` on a tool's callback metadata ends with
+        the `node_name:task_id` segment of the node that invoked the
+        tool. Dropping that segment gives the subgraph's own namespace,
+        which matches what other `tools` / `lifecycle` / `messages`
+        emitters use.
+        """
+        if not metadata:
+            return ()
+        nskey = metadata.get("langgraph_checkpoint_ns")
+        if not nskey:
+            return ()
+        return tuple(cast(str, nskey).split(NS_SEP))[:-1]
+
+    def _start(
+        self,
+        serialized: dict[str, Any] | None,
+        input_str: str,
+        *,
+        run_id: UUID,
+        metadata: dict[str, Any] | None,
+        inputs: dict[str, Any] | None,
+        kwargs: dict[str, Any],
+    ) -> None:
+        tool_call_id = cast("str | None", kwargs.get("tool_call_id")) or str(run_id)
+        tool_name = (
+            (serialized or {}).get("name")
+            or cast("str | None", kwargs.get("name"))
+            or ""
+        )
+        ns = self._containing_ns_from_metadata(metadata)
+
+        def writer(delta: Any) -> None:
+            self.stream(
+                (
+                    ns,
+                    "tools",
+                    {
+                        "event": "tool-output-delta",
+                        "tool_call_id": tool_call_id,
+                        "delta": delta,
+                    },
+                )
+            )
+
+        token = _tool_call_writer.set(writer)
+        self._run_to_call[run_id] = (ns, tool_call_id, token)
+
+        payload: dict[str, Any] = {
+            "event": "tool-started",
+            "tool_call_id": tool_call_id,
+            "tool_name": tool_name,
+        }
+        if inputs is not None:
+            payload["input"] = inputs
+        self.stream((ns, "tools", payload))
+
+    def _end(self, output: Any, *, run_id: UUID) -> None:
+        info = self._run_to_call.pop(run_id, None)
+        if info is None:
+            return
+        ns, tool_call_id, token = info
+        self._reset_writer(token)
+        self.stream(
+            (
+                ns,
+                "tools",
+                {
+                    "event": "tool-finished",
+                    "tool_call_id": tool_call_id,
+                    "output": output,
+                },
+            )
+        )
+
+    def _error(self, error: BaseException, *, run_id: UUID) -> None:
+        info = self._run_to_call.pop(run_id, None)
+        if info is None:
+            return
+        ns, tool_call_id, token = info
+        self._reset_writer(token)
+        self.stream(
+            (
+                ns,
+                "tools",
+                {
+                    "event": "tool-error",
+                    "tool_call_id": tool_call_id,
+                    "message": str(error),
+                },
+            )
+        )
+
+    def tap_output_aiter(
+        self, run_id: UUID, output: AsyncIterator[T]
+    ) -> AsyncIterator[T]:
+        """Pass-through — required by the `_StreamingCallbackHandler` protocol."""
+        return output
+
+    def tap_output_iter(self, run_id: UUID, output: Iterator[T]) -> Iterator[T]:
+        """Pass-through — sync counterpart to `tap_output_aiter`."""
+        return output
+
+    @staticmethod
+    def _reset_writer(token: Token[ToolCallWriter | None]) -> None:
+        # Token is invalid if `on_tool_end` runs in a different context
+        # than `on_tool_start` (e.g. langchain may hand off to a thread
+        # worker without copying the context). Swallow that case; the
+        # ContextVar lifetime is bounded by the enclosing task anyway.
+        try:
+            _tool_call_writer.reset(token)
+        except ValueError:
+            pass
+
+    # ------------------------------------------------------------------
+    # Sync callbacks
+    # ------------------------------------------------------------------
+
+    def on_tool_start(
+        self,
+        serialized: dict[str, Any],
+        input_str: str,
+        *,
+        run_id: UUID,
+        parent_run_id: UUID | None = None,
+        tags: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+        inputs: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        self._start(
+            serialized,
+            input_str,
+            run_id=run_id,
+            metadata=metadata,
+            inputs=inputs,
+            kwargs=kwargs,
+        )
+
+    def on_tool_end(
+        self,
+        output: Any,
+        *,
+        run_id: UUID,
+        parent_run_id: UUID | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        self._end(output, run_id=run_id)
+
+    def on_tool_error(
+        self,
+        error: BaseException,
+        *,
+        run_id: UUID,
+        parent_run_id: UUID | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        self._error(error, run_id=run_id)

libs/langgraph/langgraph/pregel/main.py

@@ -73,6 +73,7 @@ from langgraph._internal._constants import (
     CONFIG_KEY_RUNTIME,
     CONFIG_KEY_SEND,
     CONFIG_KEY_STREAM,
+    CONFIG_KEY_STREAM_MESSAGES_V2,
     CONFIG_KEY_TASK_ID,
     CONFIG_KEY_THREAD_ID,
     ERROR,
@@ -129,14 +130,19 @@ from langgraph.pregel._checkpoint import (
 )
 from langgraph.pregel._draw import draw_graph
 from langgraph.pregel._io import map_input, read_channels
+from langgraph.pregel._lifecycle import StreamLifecycleHandler
 from langgraph.pregel._loop import (
     AsyncPregelLoop,
     SyncPregelLoop,
 )
-from langgraph.pregel._messages import StreamMessagesHandler
+from langgraph.pregel._messages import (
+    StreamMessagesHandler,
+    StreamMessagesHandlerV2,
+)
 from langgraph.pregel._read import DEFAULT_BOUND, PregelNode
 from langgraph.pregel._retry import RetryPolicy
 from langgraph.pregel._runner import PregelRunner
+from langgraph.pregel._tools import StreamToolCallHandler
 from langgraph.pregel._utils import get_new_channel_versions
 from langgraph.pregel._validate import validate_graph, validate_keys
 from langgraph.pregel._write import ChannelWrite, ChannelWriteEntry
@@ -340,6 +346,63 @@ class NodeBuilder:
         )
 
 
+def _collect_stream_modes(mux: Any) -> list[StreamMode]:
+    """Return the union of `required_stream_modes` across registered transformers.
+
+    Transformers declare the stream modes they need to function, and
+    `stream_v2` asks the graph for exactly that union — no hardcoded
+    default set. If zero transformers are registered (or none declares
+    a given mode), the graph does not stream events for that mode.
+    """
+    modes: set[str] = set()
+    for transformer in mux._transformers:
+        modes.update(transformer.required_stream_modes)
+    return cast("list[StreamMode]", list(modes))
+
+
+def _build_stream_factories(
+    compile_time: Sequence[Callable[..., Any]],
+    call_site: Sequence[Any] | None,
+) -> list[Callable[..., Any]]:
+    """Assemble the factory list handed to `StreamMux(factories=...)`.
+
+    Prepends the built-in `ValuesTransformer`, `MessagesTransformer`,
+    and `SubgraphTransformer` factories, then appends the graph's
+    compile-time `stream_transformers` followed by any call-site
+    additions. Factories flow down into subgraph mini-muxes, so
+    per-scope instances propagate automatically.
+    """
+    from langgraph.stream.transformers import (
+        MessagesTransformer,
+        SubgraphTransformer,
+        ValuesTransformer,
+    )
+
+    builtins: list[Callable[..., Any]] = [
+        ValuesTransformer,
+        MessagesTransformer,
+        SubgraphTransformer,
+    ]
+    return [*builtins, *compile_time, *(call_site or ())]
+
+
+def _merge_v2_messages_flag(
+    config: RunnableConfig | None,
+) -> RunnableConfig:
+    """Return a config with the v2 messages flag set in `configurable`.
+
+    Signals to pregel that `stream_mode="messages"` should attach
+    `StreamMessagesHandlerV2` for this call so invoke-time model runs
+    route through the v2 event generator and their protocol events
+    reach the messages channel.
+    """
+    merged: RunnableConfig = dict(config or {})  # type: ignore[assignment]
+    configurable = dict(merged.get(CONF) or {})
+    configurable[CONFIG_KEY_STREAM_MESSAGES_V2] = True
+    merged[CONF] = configurable
+    return merged
+
+
 class Pregel(
     PregelProtocol[StateT, ContextT, InputT, OutputT],
     Generic[StateT, ContextT, InputT, OutputT],
@@ -671,6 +734,7 @@ class Pregel(
         config: RunnableConfig | None = None,
         trigger_to_nodes: Mapping[str, Sequence[str]] | None = None,
         name: str = "LangGraph",
+        stream_transformers: Sequence[Callable[..., Any]] | None = None,
         **deprecated_kwargs: Unpack[DeprecatedKwargs],
     ) -> None:
         if (
@@ -717,6 +781,9 @@ class Pregel(
         self.config = config
         self.trigger_to_nodes = trigger_to_nodes or {}
         self.name = name
+        self._stream_transformers: tuple[Callable[..., Any], ...] = tuple(
+            stream_transformers or ()
+        )
         self._serde_allowlist: set[tuple[str, ...]] | None = None
         if auto_validate:
             self.validate()
@@ -2626,14 +2693,34 @@ class Pregel(
             # set up messages stream mode
             if "messages" in stream_modes:
                 ns_ = cast(str | None, config[CONF].get(CONFIG_KEY_CHECKPOINT_NS))
+                messages_handler_cls = (
+                    StreamMessagesHandlerV2
+                    if config[CONF].get(CONFIG_KEY_STREAM_MESSAGES_V2)
+                    else StreamMessagesHandler
+                )
                 run_manager.inheritable_handlers.append(
-                    StreamMessagesHandler(
+                    messages_handler_cls(
                         stream.put,
                         subgraphs,
                         parent_ns=tuple(ns_.split(NS_SEP)) if ns_ else None,
                     )
                 )
 
+            # set up lifecycle stream mode
+            if "lifecycle" in stream_modes:
+                run_manager.inheritable_handlers.append(
+                    StreamLifecycleHandler(
+                        stream.put,
+                        root_graph_name=self.name,
+                    )
+                )
+
+            # set up tools stream mode
+            if "tools" in stream_modes:
+                run_manager.inheritable_handlers.append(
+                    StreamToolCallHandler(stream.put)
+                )
+
             # set up custom stream mode
             if "custom" in stream_modes:
 
@@ -3003,14 +3090,34 @@ class Pregel(
             if "messages" in stream_modes:
                 # namespace can be None in a root level graph?
                 ns_ = cast(str | None, config[CONF].get(CONFIG_KEY_CHECKPOINT_NS))
+                messages_handler_cls = (
+                    StreamMessagesHandlerV2
+                    if config[CONF].get(CONFIG_KEY_STREAM_MESSAGES_V2)
+                    else StreamMessagesHandler
+                )
                 run_manager.inheritable_handlers.append(
-                    StreamMessagesHandler(
+                    messages_handler_cls(
                         stream_put,
                         subgraphs,
                         parent_ns=tuple(ns_.split(NS_SEP)) if ns_ else None,
                     )
                 )
 
+            # set up lifecycle stream mode
+            if "lifecycle" in stream_modes:
+                run_manager.inheritable_handlers.append(
+                    StreamLifecycleHandler(
+                        stream_put,
+                        root_graph_name=self.name,
+                    )
+                )
+
+            # set up tools stream mode
+            if "tools" in stream_modes:
+                run_manager.inheritable_handlers.append(
+                    StreamToolCallHandler(stream_put)
+                )
+
             # set up custom stream mode
             def stream_writer(c: Any) -> None:
                 aioloop.call_soon_threadsafe(
@@ -3237,6 +3344,94 @@ class Pregel(
             await asyncio.shield(run_manager.on_chain_error(e))
             raise
 
+    def stream_v2(
+        self,
+        input: InputT | Command | None,
+        config: RunnableConfig | None = None,
+        *,
+        interrupt_before: All | Sequence[str] | None = None,
+        interrupt_after: All | Sequence[str] | None = None,
+        transformers: Sequence[Any] | None = None,
+    ) -> Any:
+        """Start a sync v2 streaming run driven by transformer projections.
+
+        Builds a `StreamMux` from the built-in `ValuesTransformer` /
+        `MessagesTransformer`, this graph's compile-time
+        `stream_transformers`, and any additional `transformers=`
+        supplied at the call site. Returns a `GraphRunStream` that the
+        caller drives by iterating any projection — no background
+        thread.
+
+        Args:
+            input: Graph input.
+            config: Optional runnable config forwarded to the graph.
+            interrupt_before: Nodes to interrupt before, if any.
+            interrupt_after: Nodes to interrupt after, if any.
+            transformers: Extra transformer instances appended after
+                compile-time `stream_transformers`.
+
+        Returns:
+            A `GraphRunStream` the caller iterates to drive the run.
+        """
+        from langgraph.stream._mux import StreamMux
+        from langgraph.stream.run_stream import GraphRunStream
+
+        factories = _build_stream_factories(self._stream_transformers, transformers)
+        mux = StreamMux(factories=factories, is_async=False)
+        stream_modes = _collect_stream_modes(mux)
+        graph_iter = iter(
+            self.stream(
+                input,
+                _merge_v2_messages_flag(config),
+                stream_mode=stream_modes,
+                subgraphs=True,
+                version="v2",
+                interrupt_before=interrupt_before,
+                interrupt_after=interrupt_after,
+            )
+        )
+        return GraphRunStream(graph_iter, mux)
+
+    async def astream_v2(
+        self,
+        input: InputT | Command | None,
+        config: RunnableConfig | None = None,
+        *,
+        interrupt_before: All | Sequence[str] | None = None,
+        interrupt_after: All | Sequence[str] | None = None,
+        transformers: Sequence[Any] | None = None,
+    ) -> Any:
+        """Async counterpart to `stream_v2`.
+
+        Returns an `AsyncGraphRunStream` whose projections can be awaited
+        concurrently; each subscribed cursor drives the pump when its
+        buffer is empty.
+
+        Args:
+            input: Graph input.
+            config: Optional runnable config forwarded to the graph.
+            interrupt_before: Nodes to interrupt before, if any.
+            interrupt_after: Nodes to interrupt after, if any.
+            transformers: Extra transformer instances appended after
+                compile-time `stream_transformers`.
+        """
+        from langgraph.stream._mux import StreamMux
+        from langgraph.stream.run_stream import AsyncGraphRunStream
+
+        factories = _build_stream_factories(self._stream_transformers, transformers)
+        mux = StreamMux(factories=factories, is_async=True)
+        stream_modes = _collect_stream_modes(mux)
+        graph_aiter = self.astream(
+            input,
+            _merge_v2_messages_flag(config),
+            stream_mode=stream_modes,
+            subgraphs=True,
+            version="v2",
+            interrupt_before=interrupt_before,
+            interrupt_after=interrupt_after,
+        ).__aiter__()
+        return AsyncGraphRunStream(graph_aiter, mux)
+
     @overload
     def invoke(
         self,

libs/langgraph/langgraph/pregel/remote.py

@@ -650,22 +650,46 @@ class RemoteGraph(PregelProtocol):
         """
         updated_stream_modes: list[StreamModeSDK] = []
         req_single = True
+        # `"lifecycle"` is emitted locally by the `StreamLifecycleHandler`
+        # attached inside `Pregel.stream` / `astream`. The remote graph
+        # API has no corresponding mode, so requests for it against a
+        # `RemoteGraph` are silently stripped here and a warning is
+        # logged so the caller isn't left wondering why no lifecycle
+        # events arrive.
+        dropped_lifecycle = False
         # coerce to list, or add default stream mode
         if stream_mode:
             if isinstance(stream_mode, str):
-                updated_stream_modes.append(stream_mode)
+                if stream_mode != "lifecycle":
+                    updated_stream_modes.append(cast(StreamModeSDK, stream_mode))
+                else:
+                    dropped_lifecycle = True
             else:
                 req_single = False
-                updated_stream_modes.extend(stream_mode)
+                for m in stream_mode:
+                    if m == "lifecycle":
+                        dropped_lifecycle = True
+                    else:
+                        updated_stream_modes.append(cast(StreamModeSDK, m))
         else:
-            updated_stream_modes.append(default)
+            updated_stream_modes.append(default)  # type: ignore[arg-type]
         requested_stream_modes = updated_stream_modes.copy()
         # add any from parent graph
         stream: StreamProtocol | None = (
             (config or {}).get(CONF, {}).get(CONFIG_KEY_STREAM)
         )
         if stream:
-            updated_stream_modes.extend(stream.modes)
+            for m in stream.modes:
+                if m == "lifecycle":
+                    dropped_lifecycle = True
+                else:
+                    updated_stream_modes.append(cast(StreamModeSDK, m))
+        if dropped_lifecycle:
+            logger.warning(
+                "Stream mode 'lifecycle' is not supported by RemoteGraph "
+                "and was stripped from the request; no lifecycle events "
+                "will be emitted for this remote run."
+            )
         # map "messages" to "messages-tuple"
         if "messages" in updated_stream_modes:
             updated_stream_modes.remove("messages")

libs/langgraph/langgraph/stream/__init__.py

@@ -0,0 +1,20 @@
+"""Streaming infrastructure for LangGraph.
+
+Compile a graph with `transformers=[...]` and call `graph.stream_v2()` /
+`graph.astream_v2()` to drive a transformer pipeline that projects the
+graph's raw events into ergonomic per-channel streams.
+"""
+
+from langgraph.stream._event_log import EventLog
+from langgraph.stream._types import ProtocolEvent, StreamTransformer
+from langgraph.stream.run_stream import AsyncGraphRunStream, GraphRunStream
+from langgraph.stream.stream_channel import StreamChannel
+
+__all__ = [
+    "AsyncGraphRunStream",
+    "EventLog",
+    "GraphRunStream",
+    "ProtocolEvent",
+    "StreamChannel",
+    "StreamTransformer",
+]

libs/langgraph/langgraph/stream/_convert.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import time
+from typing import Any, cast
+
+from langgraph.stream._types import ProtocolEvent, _ProtocolEventParams
+from langgraph.types import StreamPart
+
+
+def convert_to_protocol_event(part: StreamPart) -> ProtocolEvent:
+    """Convert a v2 StreamPart to a ProtocolEvent.
+
+    Args:
+        part: A stream part with keys `type`, `ns`, `data`, and
+            optionally `interrupts` (present on values events).
+
+    Returns:
+        The equivalent ProtocolEvent.
+    """
+    part_dict = cast(dict[str, Any], part)
+    params: _ProtocolEventParams = {
+        "namespace": list(part_dict["ns"]),
+        "timestamp": int(time.time() * 1000),
+        "data": part_dict["data"],
+    }
+    if "interrupts" in part_dict:
+        params["interrupts"] = part_dict["interrupts"]
+    return {
+        "type": "event",
+        "method": part_dict["type"],
+        "params": params,
+    }

libs/langgraph/langgraph/stream/_event_log.py

@@ -0,0 +1,306 @@
+from __future__ import annotations
+
+import asyncio
+from collections import deque
+from collections.abc import AsyncIterator, Awaitable, Callable, Iterator
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+
+class EventLog(Generic[T]):
+    """Single-consumer drainable queue for streaming events.
+
+    Items are popped off the front as the consumer advances — there is
+    no retention beyond what's currently queued. A log accepts exactly
+    one subscriber; a second `__iter__` / `__aiter__` call raises. Use
+    `tee(n)` / `atee(n)` for fan-out.
+
+    Starts unbound — neither `__iter__` nor `__aiter__` is available
+    until the StreamMux calls `_bind(is_async)`. After binding, only
+    the matching iteration protocol works; the other raises `TypeError`.
+
+    Pump wiring (set by the run stream, not by `_bind`):
+        - `_request_more`: sync pump callable, returns True if a new
+          event was produced.
+        - `_arequest_more`: async pump coroutine factory, same contract.
+
+    Memory is bounded by caller pace: both sync and async use caller-
+    driven pumps, so each cursor advance produces at most one event.
+    The only shape where a log can accumulate meaningfully is
+    concurrent async consumers at unequal rates — a slow consumer's
+    log grows while fast consumers drive the shared pump. That's the
+    documented tradeoff for concurrent consumption; consume at similar
+    rates or use a single consumer if memory matters.
+
+    Lazy-subscribe: `push` is a no-op when no subscriber has registered.
+    Transformers still execute `process()` (so scalar state like
+    `ValuesTransformer._latest` stays current); only the log append is
+    skipped.
+    """
+
+    def __init__(self, maxlen: int | None = None) -> None:
+        """Initialize an empty, unbound log.
+
+        Args:
+            maxlen: Accepted for forward compatibility; currently unused.
+                The caller-driven pump bounds memory naturally for
+                single-consumer use.
+
+        Raises:
+            ValueError: If `maxlen` is not a positive integer or `None`.
+        """
+        if maxlen is not None and maxlen <= 0:
+            raise ValueError("EventLog maxlen must be a positive int or None")
+        self._items: deque[T] = deque()
+        self._maxlen: int | None = maxlen
+        self._closed = False
+        self._error: BaseException | None = None
+
+        # Binding state — None means unbound.
+        self._is_async: bool | None = None
+
+        # Flipped on first __iter__ / __aiter__. Pre-subscription
+        # pushes are silent no-ops.
+        self._subscribed = False
+
+        # Pump wiring set by the run stream after bind.
+        self._request_more: Callable[[], bool] | None = None
+        self._arequest_more: Callable[[], Awaitable[bool]] | None = None
+
+    # ------------------------------------------------------------------
+    # Binding
+    # ------------------------------------------------------------------
+
+    def _bind(self, *, is_async: bool) -> None:
+        """Bind this log to sync or async mode.
+
+        Called by the StreamMux after transformer registration. Must be
+        called exactly once before any iteration.
+
+        Args:
+            is_async: True to enable async iteration, False for sync.
+
+        Raises:
+            RuntimeError: If the log has already been bound.
+        """
+        if self._is_async is not None:
+            raise RuntimeError("EventLog is already bound")
+        self._is_async = is_async
+
+    # ------------------------------------------------------------------
+    # Producer API
+    # ------------------------------------------------------------------
+
+    def push(self, item: T) -> None:
+        """Append an item. No-op when no subscriber is registered.
+
+        Non-blocking in both sync and async — matches v1's
+        `put_nowait` producer shape. Memory is bounded by caller pace
+        via the caller-driven pump.
+
+        Raises:
+            RuntimeError: If the log is closed (and subscribed).
+        """
+        if not self._subscribed:
+            return
+        if self._closed:
+            raise RuntimeError("Cannot push to a closed EventLog")
+        self._items.append(item)
+
+    def close(self) -> None:
+        """Mark the log as complete."""
+        self._closed = True
+
+    def fail(self, err: BaseException) -> None:
+        """Mark the log as errored.
+
+        Args:
+            err: The exception to surface to the subscriber.
+        """
+        self._error = err
+        self._closed = True
+
+    # ------------------------------------------------------------------
+    # Sync iteration (caller-driven pump)
+    # ------------------------------------------------------------------
+
+    def __iter__(self) -> Iterator[T]:
+        """Subscribe and return a sync cursor. Can be called only once.
+
+        Raises:
+            TypeError: If the log is unbound or bound to async mode.
+            RuntimeError: If the log already has a subscriber.
+        """
+        if self._is_async is None:
+            raise TypeError(
+                "EventLog has not been bound yet. "
+                "Register the transformer with a StreamMux first."
+            )
+        if self._is_async:
+            raise TypeError(
+                "This EventLog is bound to async mode — use 'async for' instead."
+            )
+        if self._subscribed:
+            raise RuntimeError(
+                "EventLog already has a subscriber; use .tee(n) for fan-out."
+            )
+        self._subscribed = True
+        return self._sync_cursor()
+
+    def _sync_cursor(self) -> Iterator[T]:
+        while True:
+            if self._items:
+                yield self._items.popleft()
+            elif self._closed:
+                if self._error is not None:
+                    raise self._error
+                return
+            elif self._request_more is not None:
+                if not self._request_more():
+                    if not self._items and not self._closed:
+                        return
+            else:
+                return
+
+    # ------------------------------------------------------------------
+    # Async iteration (caller-driven pump)
+    # ------------------------------------------------------------------
+
+    def __aiter__(self) -> AsyncIterator[T]:
+        """Subscribe and return an async cursor. Can be called only once.
+
+        Raises:
+            TypeError: If the log is unbound or bound to sync mode.
+            RuntimeError: If the log already has a subscriber.
+        """
+        if self._is_async is None:
+            raise TypeError(
+                "EventLog has not been bound yet. "
+                "Register the transformer with a StreamMux first."
+            )
+        if not self._is_async:
+            raise TypeError("This EventLog is bound to sync mode — use 'for' instead.")
+        if self._subscribed:
+            raise RuntimeError(
+                "EventLog already has a subscriber; use .atee(n) for fan-out."
+            )
+        self._subscribed = True
+        return self._async_cursor()
+
+    async def _async_cursor(self) -> AsyncIterator[T]:
+        while True:
+            if self._items:
+                yield self._items.popleft()
+            elif self._closed:
+                if self._error is not None:
+                    raise self._error
+                return
+            elif self._arequest_more is not None:
+                if not await self._arequest_more():
+                    if not self._items and not self._closed:
+                        return
+            else:
+                return
+
+    # ------------------------------------------------------------------
+    # Fan-out via tee
+    # ------------------------------------------------------------------
+
+    def tee(self, n: int = 2) -> tuple[Iterator[T], ...]:
+        """Subscribe and return `n` independent sync iterators.
+
+        Each branch has its own buffer; items pulled from the
+        underlying cursor are copied into every branch. Branches are
+        naturally bounded by caller pace since the sync pump is
+        caller-driven.
+
+        Args:
+            n: Number of branches to create. Must be >= 1.
+
+        Returns:
+            A tuple of `n` iterators over the same underlying stream.
+
+        Raises:
+            TypeError: If the log is unbound or bound to async mode.
+            RuntimeError: If the log already has a subscriber.
+            ValueError: If `n` < 1.
+        """
+        if n < 1:
+            raise ValueError("tee() requires n >= 1")
+        source = self.__iter__()
+        buffers: list[deque[T]] = [deque() for _ in range(n)]
+        exhausted = [False]
+
+        def branch(i: int) -> Iterator[T]:
+            buf = buffers[i]
+            while True:
+                if buf:
+                    yield buf.popleft()
+                elif exhausted[0]:
+                    return
+                else:
+                    try:
+                        item = next(source)
+                    except StopIteration:
+                        exhausted[0] = True
+                        return
+                    for b in buffers:
+                        b.append(item)
+
+        return tuple(branch(i) for i in range(n))
+
+    def atee(self, n: int = 2) -> tuple[AsyncIterator[T], ...]:
+        """Subscribe and return `n` independent async iterators.
+
+        Caller-driven fan-out: each branch's `__anext__` either pops
+        from its own buffer or, under a shared `asyncio.Lock`, pulls
+        one item from the underlying cursor and distributes it to
+        every branch's buffer.
+
+        Args:
+            n: Number of branches to create. Must be >= 1.
+
+        Returns:
+            A tuple of `n` async iterators over the same underlying
+            stream.
+
+        Raises:
+            TypeError: If the log is unbound or bound to sync mode.
+            RuntimeError: If the log already has a subscriber.
+            ValueError: If `n` < 1.
+        """
+        if n < 1:
+            raise ValueError("atee() requires n >= 1")
+        source = self.__aiter__()
+        buffers: list[deque[T]] = [deque() for _ in range(n)]
+        exhausted = [False]
+        error: list[BaseException | None] = [None]
+        lock = asyncio.Lock()
+
+        async def branch(i: int) -> AsyncIterator[T]:
+            buf = buffers[i]
+            while True:
+                if buf:
+                    yield buf.popleft()
+                    continue
+                if exhausted[0]:
+                    if error[0] is not None:
+                        raise error[0]
+                    return
+                async with lock:
+                    if buf or exhausted[0]:
+                        continue
+                    try:
+                        item = await source.__anext__()
+                    except StopAsyncIteration:
+                        exhausted[0] = True
+                        continue
+                    except Exception as e:
+                        error[0] = e
+                        exhausted[0] = True
+                        continue
+                    for b in buffers:
+                        b.append(item)
+
+        return tuple(branch(i) for i in range(n))

libs/langgraph/langgraph/stream/_mux.py

@@ -0,0 +1,487 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from langgraph.stream._event_log import EventLog
+from langgraph.stream._types import (
+    ProtocolEvent,
+    StreamTransformer,
+    transformer_requires_async,
+)
+from langgraph.stream.stream_channel import StreamChannel
+
+TransformerFactory = Callable[["tuple[str, ...]"], StreamTransformer]
+"""Factory that builds a scoped transformer for a mux.
+
+Called once per `StreamMux` (root or mini-mux) with the mux's scope
+— typically a subgraph's namespace or `()` for the root. Standard
+transformer classes (`ValuesTransformer`, `MessagesTransformer`,
+`SubgraphTransformer`) accept a single positional scope argument, so
+the class itself is a valid factory. User transformers can close over
+their config: `lambda scope: MyTransformer(scope, foo=...)`.
+"""
+
+
+class StreamMux:
+    """Central event dispatcher for the streaming infrastructure.
+
+    Owns the main event log and routes events through a transformer
+    pipeline. StreamChannels discovered in transformer projections are
+    auto-wired so that every `push()` also injects a `ProtocolEvent`
+    into the main log.
+
+    Pass `is_async=True` when the mux will be consumed via async
+    iteration (`handler.astream()`). All EventLog and StreamChannel
+    instances discovered during registration are automatically bound
+    to the matching mode.
+
+    Attributes:
+        extensions: Merged projection dict across all registered
+            transformers. Treat as read-only — mutations won't be
+            reflected back in individual transformers' state.
+        native_keys: Projection keys contributed by transformers with
+            `_native = True`.
+    """
+
+    def __init__(
+        self,
+        transformers: list[StreamTransformer] | None = None,
+        *,
+        is_async: bool = False,
+        factories: list[TransformerFactory] | None = None,
+        scope: tuple[str, ...] = (),
+    ) -> None:
+        """Initialize the mux and register transformers in order.
+
+        Callers pass either `transformers` (pre-built instances) or
+        `factories` (callables producing fresh instances per mux). A
+        factory list is preferred — mini-muxes built by `make_child()`
+        inherit the factory list, so transformers propagate naturally
+        into every subgraph's scope. `transformers` is kept for
+        back-compat tests that exercise the mux directly.
+
+        Each transformer's `init()` is called once during registration,
+        projections are merged into `extensions`, `_native` keys are
+        recorded in `native_keys`, and any EventLog / StreamChannel
+        instances are bound and wired.
+
+        Args:
+            transformers: Already-built transformer instances. Mutually
+                exclusive with `factories`.
+            is_async: True for async dispatch (`apush` / `aclose` /
+                `afail`), False for the sync path.
+            factories: Zero-or-one-argument callables producing
+                transformers. Called with this mux's `scope`.
+            scope: The namespace the mux operates within. The root mux
+                is `()`; mini-muxes for subgraphs use the subgraph's
+                namespace tuple.
+
+        Raises:
+            RuntimeError: If any transformer requires an async run but
+                the mux is in sync mode.
+            TypeError: If a transformer's `init()` doesn't return a dict.
+            ValueError: If transformers' projection keys collide, or if
+                both `transformers` and `factories` are supplied.
+        """
+        if transformers is not None and factories is not None:
+            raise ValueError("Pass either `transformers` or `factories`, not both.")
+
+        self._is_async = is_async
+        self._factories: list[TransformerFactory] = list(factories or ())
+        self.scope: tuple[str, ...] = scope
+        self._pump_fn: Callable[[], bool] | None = None
+        self._apump_fn: Callable[[], Awaitable[bool]] | None = None
+
+        self._events: EventLog[ProtocolEvent] = EventLog()
+        self._events._bind(is_async=is_async)
+        self._transformers: list[StreamTransformer] = []
+        self._channels: list[StreamChannel[Any]] = []
+        self._logs: list[EventLog[Any]] = []
+        self._seq = 0
+
+        self.extensions: dict[str, Any] = {}
+        self.native_keys: set[str] = set()
+        self._projection_owners: dict[str, str] = {}
+        self._transformer_by_key: dict[str, StreamTransformer] = {}
+
+        if factories is not None:
+            for factory in factories:
+                self._register(factory(scope))
+        else:
+            for transformer in transformers or ():
+                self._register(transformer)
+
+    def make_child(self, scope: tuple[str, ...]) -> StreamMux:
+        """Build a mini-mux with the same factories scoped to `scope`.
+
+        Used by `SubgraphTransformer` to attach a fresh transformer
+        pipeline to each discovered subgraph handle. The child mux
+        inherits the current pump binding (so cursors on its projection
+        logs drive the root pump) and carries the same factory list
+        forward to any grandchild subgraphs.
+
+        Raises:
+            RuntimeError: If the mux was not built from a factory list
+                (i.e., constructed with `transformers=`). Mini-muxes
+                require factories so each scope gets its own fresh
+                transformer instances.
+        """
+        if not self._factories:
+            raise RuntimeError(
+                "StreamMux.make_child requires the mux to be constructed "
+                "with factories; pre-built transformers can't be cloned "
+                "to a new scope."
+            )
+        child = StreamMux(
+            factories=self._factories,
+            is_async=self._is_async,
+            scope=scope,
+        )
+        if self._pump_fn is not None:
+            child.bind_pump(self._pump_fn)
+        if self._apump_fn is not None:
+            child.bind_apump(self._apump_fn)
+        return child
+
+    def bind_pump(self, fn: Callable[[], bool]) -> None:
+        """Wire the sync pull callback onto every EventLog in the mux.
+
+        Also propagates to transformers that expose `_bind_pump` so
+        nested handles (e.g., `ChatModelStream` instances produced by
+        `MessagesTransformer`) can drive the graph pump from their
+        projection cursors.
+        """
+        self._pump_fn = fn
+        self._events._request_more = fn
+        for value in self.extensions.values():
+            if isinstance(value, EventLog):
+                value._request_more = fn
+            elif isinstance(value, StreamChannel):
+                value._log._request_more = fn
+        for transformer in self._transformers:
+            bind = getattr(transformer, "_bind_pump", None)
+            if bind is not None:
+                bind(fn)
+
+    def bind_apump(self, fn: Callable[[], Awaitable[bool]]) -> None:
+        """Async counterpart to `bind_pump`."""
+        self._apump_fn = fn
+        self._events._arequest_more = fn
+        for value in self.extensions.values():
+            if isinstance(value, EventLog):
+                value._arequest_more = fn
+            elif isinstance(value, StreamChannel):
+                value._log._arequest_more = fn
+        for transformer in self._transformers:
+            abind = getattr(transformer, "_bind_apump", None)
+            if abind is not None:
+                abind(fn)
+
+    def _register(self, transformer: StreamTransformer) -> None:
+        """Register a single transformer.
+
+        Calls `transformer.init()`, stores the transformer for event
+        processing, binds any EventLog or StreamChannel instances in
+        the projection, and merges the projection into `extensions`.
+        """
+        if transformer_requires_async(transformer) and not self._is_async:
+            raise RuntimeError(
+                f"{type(transformer).__name__} requires an async run — "
+                "it overrides aprocess/afinalize/afail or sets "
+                "requires_async=True. Use astream(), not stream()."
+            )
+        projection = transformer.init()
+        if not isinstance(projection, dict):
+            raise TypeError(
+                f"StreamTransformer.init() must return a dict, "
+                f"got {type(projection).__name__}"
+            )
+        conflicts = set(projection) & set(self.extensions)
+        if conflicts:
+            attributions = ", ".join(
+                f"{key!r} (owned by {self._projection_owners[key]})"
+                for key in sorted(conflicts)
+            )
+            raise ValueError(
+                f"Transformer {type(transformer).__name__} returned "
+                f"projection keys that conflict with already-registered "
+                f"keys: {attributions}"
+            )
+        self._transformers.append(transformer)
+        self._bind_and_wire(projection)
+        self.extensions.update(projection)
+        owner_name = type(transformer).__name__
+        for key in projection:
+            self._projection_owners[key] = owner_name
+            self._transformer_by_key[key] = transformer
+        if getattr(transformer, "_native", False):
+            self.native_keys.update(projection.keys())
+        on_register = getattr(transformer, "_on_register", None)
+        if on_register is not None:
+            on_register(self)
+
+    def transformer_by_key(self, key: str) -> StreamTransformer | None:
+        """Return the transformer that owns the projection at `key`, if any."""
+        return self._transformer_by_key.get(key)
+
+    def push(self, event: ProtocolEvent) -> None:
+        """Route an event through all transformers, then append to the main log.
+
+        Each transformer's `process()` is called in registration order
+        — except when the transformer has `scope_exact = True` (the
+        default) and the event's namespace differs from the mux's
+        `scope`, in which case the transformer is skipped. Transformers
+        that need to see cross-scope events opt out by setting
+        `scope_exact = False` (e.g. `SubgraphTransformer`).
+
+        If any transformer returns False, the event is suppressed from
+        the main log, but transformers that already saw it keep their
+        side effects.
+
+        Seq is assigned right before an event enters the main log, not
+        before the transformer pipeline runs. This ensures that events
+        auto-forwarded from StreamChannels during `process()` get
+        earlier seq numbers than the original event, preserving
+        monotonic ordering in the log.
+
+        Args:
+            event: The protocol event to dispatch.
+        """
+        ns = tuple(event["params"]["namespace"])
+        in_scope = ns == self.scope
+        keep = True
+        for transformer in self._transformers:
+            if transformer.scope_exact and not in_scope:
+                continue
+            if not transformer.process(event):
+                keep = False
+        if keep:
+            self._seq += 1
+            event["seq"] = self._seq
+            self._events.push(event)
+
+    def close(self) -> None:
+        """Finalize all transformers, close all projections and the main log.
+
+        EventLogs and StreamChannels discovered in transformer
+        projections are auto-closed after `finalize()` runs —
+        transformers don't need to close them manually. If any
+        transformer's `finalize()` raises, the remaining transformers,
+        projections, and the main log are still closed; the first error
+        is re-raised after cleanup completes.
+
+        Raises:
+            BaseException: The first error raised by a transformer's
+                `finalize()`, re-raised after cleanup finishes.
+        """
+        first_error: BaseException | None = None
+        for transformer in self._transformers:
+            try:
+                transformer.finalize()
+            except BaseException as e:
+                if first_error is None:
+                    first_error = e
+        for log in self._logs:
+            if not log._closed:
+                log.close()
+        for ch in self._channels:
+            if not ch._log._closed:
+                ch._close()
+        self._events.close()
+        if first_error is not None:
+            raise first_error
+
+    def fail(self, err: BaseException) -> None:
+        """Fail all transformers, projections, and the main log.
+
+        EventLogs and StreamChannels discovered in transformer
+        projections are auto-failed — transformers don't need to fail
+        them manually. If any transformer's `fail()` raises, the
+        remaining transformers, projections, and the main log are still
+        failed.
+
+        Args:
+            err: The exception that ended the run.
+        """
+        for transformer in self._transformers:
+            try:
+                transformer.fail(err)
+            except BaseException:
+                pass
+        for log in self._logs:
+            if not log._closed:
+                log.fail(err)
+        for ch in self._channels:
+            if not ch._log._closed:
+                ch._fail(err)
+        self._events.fail(err)
+
+    # ------------------------------------------------------------------
+    # Async dispatch
+    # ------------------------------------------------------------------
+
+    async def apush(self, event: ProtocolEvent) -> None:
+        """Dispatch an event on the async lane.
+
+        Awaits each transformer's `aprocess` in registration order
+        before appending to the main log — except when the transformer
+        has `scope_exact = True` and the event's namespace differs from
+        `self.scope`, in which case it is skipped. A slow `aprocess`
+        serializes the pipeline by design — that's the guarantee that
+        lets a later transformer (or a synchronous consumer) see the
+        result of the async work. For decoupled work, use `schedule()`
+        from inside `process` / `aprocess` instead.
+
+        The main log append is a non-blocking `push` — matching v1's
+        `put_nowait` shape. Memory is bounded by caller pace via the
+        caller-driven pump; see `EventLog` for the full tradeoff story.
+
+        Args:
+            event: The protocol event to dispatch.
+        """
+        ns = tuple(event["params"]["namespace"])
+        in_scope = ns == self.scope
+        keep = True
+        for transformer in self._transformers:
+            if transformer.scope_exact and not in_scope:
+                continue
+            if not await transformer.aprocess(event):
+                keep = False
+        if keep:
+            self._seq += 1
+            event["seq"] = self._seq
+            self._events.push(event)
+
+    async def aclose(self) -> None:
+        """Finalize on the async lane.
+
+        Awaits every task started via `StreamTransformer.schedule()`
+        across all transformers, then calls `afinalize()` on each,
+        then auto-closes logs, channels, and the main event log.
+
+        If any scheduled task raised under `on_error="raise"`, or any
+        transformer's `afinalize` raises, the exception propagates.
+        The caller (the pump) handles it by routing into `afail`.
+
+        Raises:
+            BaseException: The first scheduled-task or `afinalize`
+                error, re-raised after cleanup.
+        """
+        pending = self._collect_scheduled_tasks()
+        if pending:
+            results = await asyncio.gather(*pending, return_exceptions=True)
+            first_err = next(
+                (
+                    r
+                    for r in results
+                    if isinstance(r, BaseException)
+                    and not isinstance(r, asyncio.CancelledError)
+                ),
+                None,
+            )
+            if first_err is not None:
+                raise first_err
+
+        first_error: BaseException | None = None
+        for transformer in self._transformers:
+            try:
+                await transformer.afinalize()
+            except BaseException as e:
+                if first_error is None:
+                    first_error = e
+        for log in self._logs:
+            if not log._closed:
+                log.close()
+        for ch in self._channels:
+            if not ch._log._closed:
+                ch._close()
+        self._events.close()
+        if first_error is not None:
+            raise first_error
+
+    async def afail(self, err: BaseException) -> None:
+        """Fail on the async lane.
+
+        Cancels every scheduled task across all transformers, awaits
+        them to completion, then runs each transformer's `afail` hook
+        and auto-fails logs, channels, and the main event log.
+
+        Args:
+            err: The exception that ended the run.
+        """
+        pending = self._collect_scheduled_tasks()
+        for task in pending:
+            task.cancel()
+        if pending:
+            await asyncio.gather(*pending, return_exceptions=True)
+
+        for transformer in self._transformers:
+            try:
+                await transformer.afail(err)
+            except BaseException:
+                pass
+        for log in self._logs:
+            if not log._closed:
+                log.fail(err)
+        for ch in self._channels:
+            if not ch._log._closed:
+                ch._fail(err)
+        if not self._events._closed:
+            self._events.fail(err)
+
+    def _collect_scheduled_tasks(self) -> list[asyncio.Task[Any]]:
+        """Return a snapshot of in-flight tasks scheduled via transformers."""
+        return [
+            task
+            for transformer in self._transformers
+            for task in getattr(transformer, "_stream_scheduled_tasks", ())
+            if not task.done()
+        ]
+
+    # ------------------------------------------------------------------
+    # Binding and StreamChannel auto-wiring
+    # ------------------------------------------------------------------
+
+    def _bind_and_wire(self, projection: dict[str, Any]) -> None:
+        """Bind and wire EventLog / StreamChannel instances in a projection."""
+        for value in projection.values():
+            if isinstance(value, StreamChannel):
+                value._bind(is_async=self._is_async)
+                self._channels.append(value)
+                channel_name = value.name
+
+                def _make_forward(name: str) -> Callable[[Any], None]:
+                    def _forward(item: Any) -> None:
+                        self._forward(name, item)
+
+                    return _forward
+
+                value._wire(_make_forward(channel_name))
+            elif isinstance(value, EventLog):
+                value._bind(is_async=self._is_async)
+                self._logs.append(value)
+
+    def _forward(self, channel_name: str, item: Any) -> None:
+        """Inject a ProtocolEvent for a StreamChannel push.
+
+        Forwarded events bypass the transformer pipeline to avoid
+        infinite recursion (a transformer that pushes to a channel
+        during `process()` would re-trigger itself). These events are
+        visible in the main event log but are not passed through
+        transformers' `process()` methods.
+        """
+        self._seq += 1
+        event: ProtocolEvent = {
+            "type": "event",
+            "seq": self._seq,
+            "method": f"custom:{channel_name}",
+            "params": {
+                "namespace": [],
+                "timestamp": int(time.time() * 1000),
+                "data": item,
+            },
+        }
+        self._events.push(event)

libs/langgraph/langgraph/stream/_types.py

@@ -0,0 +1,310 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from abc import ABC, abstractmethod
+from collections.abc import Coroutine
+from typing import Any, ClassVar, Literal
+
+from typing_extensions import NotRequired, TypedDict
+
+_logger = logging.getLogger(__name__)
+
+
+class _ProtocolEventParams(TypedDict):
+    """Parameters for a protocol event.
+
+    `timestamp` is wall-clock milliseconds since the epoch and can go
+    backwards across NTP adjustments — use `ProtocolEvent.seq` for
+    ordering.
+    """
+
+    namespace: list[str]
+    timestamp: int
+    data: Any
+    interrupts: NotRequired[tuple[Any, ...]]
+
+
+class ProtocolEvent(TypedDict):
+    """A protocol event emitted by the streaming infrastructure.
+
+    Wraps a raw stream part (values, messages, custom, etc.) in a uniform
+    envelope with a monotonic sequence number assigned by the StreamMux.
+    Consumers that need a total order across events should use `seq`, not
+    `params.timestamp` (which is wall-clock and not monotonic).
+    """
+
+    type: Literal["event"]
+    eventId: NotRequired[str]
+    seq: NotRequired[int]
+    method: str  # StreamMode value: "values", "messages", "custom", etc.
+    params: _ProtocolEventParams
+
+
+class StreamTransformer(ABC):
+    """Extension point for custom stream projections.
+
+    Transformers observe protocol events flowing through the StreamMux and
+    build typed derived projections (EventLogs, StreamChannels, promises,
+    etc.).
+
+    Set `_native = True` on a transformer to have its projection keys
+    exposed as direct attributes on the run stream (in addition to
+    appearing in `run.extensions`).
+
+    Subclasses must implement `init` and override at least one of
+    `process` / `aprocess`. The `finalize` / `afinalize` and `fail` /
+    `afail` hooks are optional — the default implementations are no-ops.
+    EventLog and StreamChannel instances in the projection dict are
+    auto-closed / auto-failed by the mux, so most transformers don't
+    need `finalize` or `fail` at all.
+
+    Transformers that need async work pick the async lane by:
+
+    1. Overriding `aprocess` (and optionally `afinalize` / `afail`), or
+    2. Calling `self.schedule(coro)` from inside a sync `process`, or
+    3. Setting `requires_async = True` explicitly.
+
+    The mux detects these cases at registration and raises if they're
+    used under sync `stream()` — they only work under `astream()`.
+
+    Use `aprocess` when the pump must wait for async work before the
+    next transformer sees the event (e.g. PII redaction that mutates
+    `event` in place). Use `schedule()` for decoupled async work whose
+    result lands on an independent projection (e.g. async moderation
+    scoring, cost lookup, external tracing).
+
+    Attributes:
+        scope: Namespace the transformer operates within — `()` for the
+            root mux, a subgraph's namespace tuple inside a mini-mux.
+            Set at construction from the mux's scope (each factory is
+            called as `factory(scope)`). Transformers that only care
+            about events at their own namespace compare against
+            `self.scope`; subgraph-aware transformers can treat it as
+            a parent path.
+        scope_exact: If True (the default), the mux only calls
+            `process` / `aprocess` for events whose namespace equals
+            `self.scope` — user transformers get scope-scoped events
+            for free with no boilerplate. Set False for transformers
+            that need to see events across scopes (e.g.
+            `SubgraphTransformer` forwards deeper events into child
+            mini-muxes).
+        requires_async: Explicit opt-in for transformers that need a
+            running event loop but don't override any async method (for
+            example, transformers that call `schedule()` from a sync
+            `process`). The mux also auto-detects the async lane when
+            `aprocess`, `afinalize`, or `afail` is overridden.
+        required_stream_modes: Stream modes the graph must emit for
+            this transformer to have anything to process. Computed as
+            the union across all registered transformers to determine
+            which modes a `GraphStreamer` run requests from the
+            graph. Empty tuple means the transformer consumes only
+            synthetic events (or is purely passive).
+    """
+
+    requires_async: ClassVar[bool] = False
+    scope_exact: ClassVar[bool] = True
+    required_stream_modes: ClassVar[tuple[str, ...]] = ()
+
+    def __init__(self, scope: tuple[str, ...] = ()) -> None:
+        """Initialize the transformer with its mux's scope.
+
+        Args:
+            scope: The namespace tuple the owning mux is scoped to.
+                `()` for the root, the subgraph's namespace inside a
+                mini-mux. Factories receive this at construction time
+                (`factory(scope)` in `StreamMux`).
+        """
+        self.scope: tuple[str, ...] = scope
+
+    @abstractmethod
+    def init(self) -> dict[str, Any]:
+        """Return the projection dict.
+
+        Keys become entries in `run.extensions`. If the transformer has
+        `_native = True`, keys are also set as direct attributes on the
+        run stream.
+
+        StreamChannel instances in the return value are automatically
+        wired by the StreamMux for protocol event auto-forwarding.
+        """
+        ...
+
+    def process(self, event: ProtocolEvent) -> bool:
+        """Handle an event on the sync lane.
+
+        Called for every event before it is appended to the main event
+        log. Subclasses must override either `process` or `aprocess`.
+        The default raises so a missing override fails loudly rather
+        than silently passing every event through.
+
+        Args:
+            event: The protocol event to observe.
+
+        Returns:
+            True to keep the event in the main log, False to suppress it.
+        """
+        raise NotImplementedError(
+            f"{type(self).__name__} must override process() or aprocess()"
+        )
+
+    async def aprocess(self, event: ProtocolEvent) -> bool:
+        """Handle an event on the async lane.
+
+        The mux awaits this before dispatching to the next transformer,
+        so a slow `aprocess` serializes the pipeline. Use it only when
+        a later transformer — or a consumer reading the event
+        synchronously — must see the result of the async work (e.g.
+        PII redaction that mutates `event` in place).
+
+        The default delegates to `process`, so purely-sync transformers
+        run unchanged under `astream()`.
+
+        Args:
+            event: The protocol event to observe.
+
+        Returns:
+            True to keep the event in the main log, False to suppress it.
+        """
+        return self.process(event)
+
+    def finalize(self) -> None:
+        """Called when the run ends normally (sync lane).
+
+        Override to close EventLogs, resolve promises, or perform other
+        teardown. StreamChannel instances are auto-closed by the mux.
+        """
+
+    async def afinalize(self) -> None:
+        """Called when the run ends normally (async lane).
+
+        By the time this runs, the mux has already awaited every task
+        started via `schedule()`, so EventLogs can be closed here
+        without a last-task-wins race.
+
+        The default delegates to `finalize`.
+        """
+        self.finalize()
+
+    def fail(self, err: BaseException) -> None:
+        """Called when the run ends with an error (sync lane).
+
+        Override to fail EventLogs, reject promises, or perform other
+        teardown. StreamChannel instances are auto-failed by the mux.
+
+        Args:
+            err: The exception that ended the run.
+        """
+
+    async def afail(self, err: BaseException) -> None:
+        """Called when the run ends with an error (async lane).
+
+        The mux cancels and awaits every task started via `schedule()`
+        before calling this, so cleanup doesn't race with in-flight work.
+
+        The default delegates to `fail`.
+
+        Args:
+            err: The exception that ended the run.
+        """
+        self.fail(err)
+
+    # ------------------------------------------------------------------
+    # Scheduled async work
+    # ------------------------------------------------------------------
+
+    def schedule(
+        self,
+        coro: Coroutine[Any, Any, Any],
+        *,
+        on_error: Literal["log", "raise"] = "log",
+    ) -> asyncio.Task[Any]:
+        """Schedule a coroutine tied to this transformer's lifecycle.
+
+        The mux holds the task reference, awaits all scheduled tasks
+        during `aclose()` before calling `afinalize()`, and cancels
+        them on `afail()`. Authors don't need to track tasks or
+        implement the last-task-closes-the-log dance.
+
+        Requires a running event loop — call only under `astream()`.
+        Set `requires_async = True` on the class so registration under
+        sync `stream()` fails fast with a clear message.
+
+        Args:
+            coro: The coroutine to run. Its lifecycle is owned by the
+                mux from this point on.
+            on_error: `"log"` (default) catches and logs any exception
+                the coroutine raises, so a single failure doesn't tear
+                down the run. `"raise"` lets the exception propagate
+                when the mux joins pendings, converting the close path
+                into the fail path.
+
+        Returns:
+            The asyncio Task. Authors rarely need to await it directly
+            — consumers read results from whatever projection the
+            coroutine pushes into.
+
+        Raises:
+            RuntimeError: If called without a running event loop (i.e.
+                under sync `stream()` rather than `astream()`).
+        """
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            raise RuntimeError(
+                f"{type(self).__name__}.schedule() requires a running "
+                "event loop; this transformer must run under astream(), "
+                "not stream(). Set requires_async=True on the class so "
+                "this fails at registration rather than at first event."
+            ) from None
+
+        wrapped = self._wrap_scheduled(coro) if on_error == "log" else coro
+        task = asyncio.create_task(wrapped)
+        tasks = self._scheduled_task_set()
+        tasks.add(task)
+        task.add_done_callback(tasks.discard)
+        return task
+
+    @staticmethod
+    async def _wrap_scheduled(coro: Coroutine[Any, Any, Any]) -> Any:
+        try:
+            return await coro
+        except asyncio.CancelledError:
+            raise
+        except BaseException:
+            _logger.exception("Scheduled StreamTransformer task failed")
+
+    def _scheduled_task_set(self) -> set[asyncio.Task[Any]]:
+        """Return the lazily-allocated task set.
+
+        Avoids requiring subclasses to call `super().__init__()`.
+        """
+        tasks: set[asyncio.Task[Any]] | None = getattr(
+            self, "_stream_scheduled_tasks", None
+        )
+        if tasks is None:
+            tasks = set()
+            self._stream_scheduled_tasks = tasks
+        return tasks
+
+
+def transformer_requires_async(transformer: StreamTransformer) -> bool:
+    """Return True if the transformer needs a running event loop.
+
+    A transformer requires async if it explicitly opts in
+    (`requires_async = True`) or overrides any of the async-lane methods
+    (`aprocess`, `afinalize`, `afail`).
+
+    Args:
+        transformer: The transformer to inspect.
+
+    Returns:
+        True if the transformer cannot run under sync `stream()`.
+    """
+    if transformer.requires_async:
+        return True
+    cls = type(transformer)
+    for name in ("aprocess", "afinalize", "afail"):
+        if getattr(cls, name) is not getattr(StreamTransformer, name):
+            return True
+    return False

libs/langgraph/langgraph/stream/run_stream.py

@@ -0,0 +1,412 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator, Awaitable, Callable, Iterator, Mapping
+from types import MappingProxyType, TracebackType
+from typing import TYPE_CHECKING, Any
+
+from langgraph.stream._convert import convert_to_protocol_event
+from langgraph.stream._mux import StreamMux
+from langgraph.stream._types import ProtocolEvent
+
+if TYPE_CHECKING:
+    from langgraph.stream.transformers import ValuesTransformer
+
+
+def _drive_until_done(pump: Callable[[], bool]) -> None:
+    """Call the sync pump until it returns False."""
+    while pump():
+        pass
+
+
+async def _adrive_until_done(pump: Callable[[], Awaitable[bool]]) -> None:
+    """Call the async pump until it returns False."""
+    while await pump():
+        pass
+
+
+class BaseRunStream:
+    """Shared shape for any object that wraps a `StreamMux`.
+
+    Root (`GraphRunStream` / `AsyncGraphRunStream`) and scoped
+    (`SubgraphRunStream`) streams both compose a `StreamMux`. The mux
+    owns the projections — `values`, `messages`, `subgraphs`, and any
+    user-registered keys — all exposed via `extensions`. Native
+    projections (`_native = True`) are also bound as direct attributes
+    (`run.values`, `run.messages`, …) for ergonomics.
+
+    Raw iteration (`for event in run` / `async for event in run`) and
+    the `interleave(...)` helper both live here so every subclass
+    behaves consistently. Subclasses only add pump ownership, scope
+    metadata, or sync/async flavor.
+    """
+
+    def __init__(self, mux: StreamMux) -> None:
+        self._mux = mux
+        self.extensions: Mapping[str, Any] = MappingProxyType(mux.extensions)
+        for key in mux.native_keys:
+            setattr(self, key, mux.extensions[key])
+
+    @property
+    def _values_transformer(self) -> ValuesTransformer:
+        """Look up the `ValuesTransformer` backing `output` / `interrupted`.
+
+        Resolved lazily off the mux so subclasses don't have to thread
+        it through their constructors. Raises if no `ValuesTransformer`
+        is registered — `output` / `interrupted` / `interrupts` have
+        nothing to return in that case, so failing loudly is better
+        than returning `None` silently.
+        """
+        from langgraph.stream.transformers import ValuesTransformer
+
+        vt = self._mux.transformer_by_key("values")
+        if not isinstance(vt, ValuesTransformer):
+            raise RuntimeError(
+                "No ValuesTransformer is registered on this mux — "
+                "`output`, `interrupted`, and `interrupts` require one. "
+                "Add it to your GraphStreamer subclass's "
+                "`builtin_factories` or pass it via `transformers=`."
+            )
+        return vt
+
+    def __iter__(self) -> Iterator[ProtocolEvent]:
+        """Sync iteration of protocol events on this mux's main log.
+
+        Raises at the EventLog level if the mux is async-bound.
+        """
+        return iter(self._mux._events)
+
+    def __aiter__(self) -> AsyncIterator[ProtocolEvent]:
+        """Async iteration of protocol events on this mux's main log.
+
+        Raises at the EventLog level if the mux is sync-bound.
+        """
+        return self._mux._events.__aiter__()
+
+    def interleave(self, *names: str) -> Iterator[tuple[str, Any]]:
+        """Iterate multiple projections round-robin, yielding ``(name, item)``.
+
+        Each turn advances one projection's cursor; when a cursor's
+        buffer is empty, pulling from it drives the pump once, which
+        fans out to every subscribed projection log. Projections whose
+        items aren't consumed on this turn sit in their own buffers
+        only until the next turn reaches them, bounding memory by the
+        skew between projection rates rather than letting any single
+        log grow to the full run length.
+
+        Projections are exhausted independently; a projection that
+        finishes early drops out of the rotation while others
+        continue. The overall iterator ends once all named projections
+        are done.
+
+        Args:
+            *names: Projection keys to interleave. Must match keys in
+                `extensions`.
+
+        Yields:
+            `(name, item)` tuples in round-robin order across the named
+            projections.
+
+        Raises:
+            KeyError: If a name doesn't match a registered projection.
+
+        Example:
+            ```python
+            for name, item in run.interleave("messages", "values"):
+                if name == "messages":
+                    print("msg:", item)
+                else:
+                    print("val:", item)
+            ```
+        """
+        cursors: dict[str, Iterator[Any]] = {
+            name: iter(self.extensions[name]) for name in names
+        }
+        done: set[str] = set()
+        while len(done) < len(cursors):
+            for name, cursor in cursors.items():
+                if name in done:
+                    continue
+                try:
+                    item = next(cursor)
+                except StopIteration:
+                    done.add(name)
+                    continue
+                yield (name, item)
+
+
+class GraphRunStream(BaseRunStream):
+    """Sync run stream with caller-driven pumping.
+
+    The caller's iteration on any projection (`values`, `messages`,
+    raw events, or `output`) drives the graph forward. No background
+    thread is used — the caller's `for` loop is the pump.
+
+    Projections are single-consumer — iterating `run.values` twice
+    raises. Use `projection.tee(n)` if you genuinely need fan-out.
+    """
+
+    def __init__(
+        self,
+        graph_iter: Iterator[Any],
+        mux: StreamMux,
+    ) -> None:
+        """Initialize the run stream.
+
+        Args:
+            graph_iter: Pull-based iterator over the graph's stream.
+            mux: The StreamMux owning projections and the main log.
+                Must have a `ValuesTransformer` registered under the
+                `"values"` key — `output` / `interrupted` / `interrupts`
+                read from it lazily.
+        """
+        super().__init__(mux)
+        self._graph_iter = graph_iter
+        self._exhausted = False
+        mux.bind_pump(self._pump_next)
+
+    def _pump_next(self) -> bool:
+        """Pull one event from the graph and push it through the mux.
+
+        Returns:
+            True if an event was pulled, False if the graph is
+            exhausted or has raised.
+        """
+        if self._exhausted:
+            return False
+        try:
+            part = next(self._graph_iter)
+        except StopIteration:
+            self._mux.close()
+            self._exhausted = True
+            return False
+        except Exception as e:
+            self._mux.fail(e)
+            self._exhausted = True
+            return False
+        self._mux.push(convert_to_protocol_event(part))
+        return True
+
+    def abort(self) -> None:
+        """Stop the run early.
+
+        Closes the mux and marks the stream exhausted. The graph
+        iterator is dropped; any in-flight nodes see the closure on
+        their next yield point. Idempotent.
+        """
+        if self._exhausted:
+            return
+        self._exhausted = True
+        try:
+            self._mux.close()
+        except Exception:
+            pass
+
+    def __enter__(self) -> GraphRunStream:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.abort()
+
+    @property
+    def output(self) -> dict[str, Any] | None:
+        """Drive the run to completion and return the final state."""
+        _drive_until_done(self._pump_next)
+        vt = self._values_transformer
+        if vt.error is not None:
+            raise vt.error
+        return vt._latest
+
+    @property
+    def interrupted(self) -> bool:
+        """Drive the run to completion, then return whether it was interrupted.
+
+        Raises:
+            BaseException: If the run ended with an error.
+        """
+        _drive_until_done(self._pump_next)
+        vt = self._values_transformer
+        if vt.error is not None:
+            raise vt.error
+        return vt._interrupted
+
+    @property
+    def interrupts(self) -> list[Any]:
+        """Drive the run to completion, then return interrupt payloads.
+
+        Raises:
+            BaseException: If the run ended with an error.
+        """
+        _drive_until_done(self._pump_next)
+        vt = self._values_transformer
+        if vt.error is not None:
+            raise vt.error
+        return vt._interrupts
+
+
+class AsyncGraphRunStream(BaseRunStream):
+    """Async run stream with caller-driven pumping.
+
+    Async iteration on any projection drives the graph forward — there
+    is no background task. Concurrent consumers share a single-flight
+    pump via an `asyncio.Lock`, so each awaiting cursor contributes
+    one event per acquisition. Backpressure comes from the logs: when
+    a subscribed log's buffer reaches `maxlen`, `apush` awaits the
+    subscriber to drain, which holds back the pump and paces the
+    graph.
+
+    Projections are single-consumer — a second `aiter(run.values)`
+    raises. Use `projection.tee(n)` for fan-out.
+
+    Use as an async context manager to guarantee clean shutdown on
+    early exit:
+
+    ```python
+    async with await handler.astream(input) as run:
+        async for msg in run.messages:
+            ...
+    ```
+    """
+
+    def __init__(
+        self,
+        graph_aiter: AsyncIterator[Any],
+        mux: StreamMux,
+    ) -> None:
+        """Initialize the async run stream.
+
+        Args:
+            graph_aiter: Async iterator over the graph's stream.
+            mux: The StreamMux owning projections and the main log.
+                Must have a `ValuesTransformer` registered under the
+                `"values"` key — `output` / `interrupted` / `interrupts`
+                read from it lazily.
+        """
+        super().__init__(mux)
+        self._graph_aiter = graph_aiter
+        self._exhausted = False
+        self._pump_cond = asyncio.Condition()
+        self._pumping = False
+        mux.bind_apump(self._apump_next)
+
+    async def _apump_next(self) -> bool:
+        """Drive one pump step, or wait for the active pumper to drive one.
+
+        "Take-a-number" semantics: at most one task at a time calls
+        `graph_aiter.__anext__()` (asyncio iterators can't be advanced
+        concurrently). Other callers wait on a Condition that the
+        active pumper notifies after each step. This lets a "passive"
+        consumer — one whose projection's buffer is being filled by the
+        active pumper's push — wake up as soon as its data lands,
+        instead of queueing on the pump and only observing its data one
+        graph event late.
+
+        `except Exception` is intentional — `CancelledError` and other
+        `BaseException` subclasses propagate, matching asyncio's
+        cancellation contract.
+
+        Returns:
+            True if a pump step completed (by this task or another),
+            False if the graph is exhausted.
+        """
+        async with self._pump_cond:
+            if self._exhausted:
+                return False
+            if self._pumping:
+                # Another task is pumping; wait for its progress signal.
+                await self._pump_cond.wait()
+                return not self._exhausted
+            self._pumping = True
+
+        try:
+            try:
+                part = await self._graph_aiter.__anext__()
+            except StopAsyncIteration:
+                self._exhausted = True
+                await self._mux.aclose()
+                return False
+            except Exception as e:
+                self._exhausted = True
+                await self._mux.afail(e)
+                return False
+            await self._mux.apush(convert_to_protocol_event(part))
+            return True
+        finally:
+            async with self._pump_cond:
+                self._pumping = False
+                self._pump_cond.notify_all()
+
+    async def abort(self) -> None:
+        """Stop the run early.
+
+        Marks the stream exhausted, wakes any pump-waiters, and closes
+        the mux. Any `apush` blocked on backpressure wakes and returns
+        without appending. Idempotent.
+        """
+        async with self._pump_cond:
+            if self._exhausted:
+                return
+            self._exhausted = True
+            self._pump_cond.notify_all()
+        try:
+            await self._mux.aclose()
+        except Exception:
+            pass
+
+    async def __aenter__(self) -> AsyncGraphRunStream:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.abort()
+
+    async def output(self) -> dict[str, Any] | None:
+        """Drive the run to completion and return the final state.
+
+        Methods (not properties) on the async lane so `run.output`
+        without `await` raises at type-check time instead of silently
+        yielding a coroutine object.
+
+        Example:
+            ```python
+            output = await run.output()
+            ```
+
+        Raises:
+            BaseException: If the run ended with an error.
+        """
+        await _adrive_until_done(self._apump_next)
+        if (err := self._values_transformer.error) is not None:
+            raise err
+        return self._values_transformer._latest
+
+    async def interrupted(self) -> bool:
+        """Drive the run to completion and return whether it was interrupted.
+
+        Raises:
+            BaseException: If the run ended with an error.
+        """
+        await _adrive_until_done(self._apump_next)
+        if (err := self._values_transformer.error) is not None:
+            raise err
+        return self._values_transformer._interrupted
+
+    async def interrupts(self) -> list[Any]:
+        """Drive the run to completion and return interrupt payloads.
+
+        Raises:
+            BaseException: If the run ended with an error.
+        """
+        await _adrive_until_done(self._apump_next)
+        if (err := self._values_transformer.error) is not None:
+            raise err
+        return self._values_transformer._interrupts

libs/langgraph/langgraph/stream/stream_channel.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Callable, Iterator
+from typing import Generic, TypeVar
+
+from langgraph.stream._event_log import EventLog
+
+T = TypeVar("T")
+
+
+class StreamChannel(Generic[T]):
+    """A named projection channel with optional protocol auto-forwarding.
+
+    Wraps an event log and declares a protocol channel name. When the
+    StreamMux detects a StreamChannel in a transformer's `init()`
+    return value, it automatically wires every `push()` to inject a
+    `ProtocolEvent` into the main event stream using the channel's
+    name as the method.
+
+    Auto-forwarded events bypass the transformer pipeline — other
+    transformers' `process()` / `aprocess()` methods do not see
+    `custom:<name>` events produced by a channel push. This prevents a
+    transformer that pushes to its own channel during `process()` from
+    re-triggering itself, but it also means filter- or tap-style
+    transformers cannot observe channel output from peer transformers.
+    Consumers that need that should iterate the main event stream.
+
+    In-process consumers iterate the channel directly (`for item in ch`
+    or `async for item in ch`). Remote SDK clients subscribe via
+    `session.subscribe("custom:<channelName>")`.
+
+    Like EventLog, a StreamChannel starts unbound. The mux calls
+    `_bind(is_async)` during registration so the correct iteration
+    protocol is available by the time user code sees it.
+
+    Lifecycle (`_close` / `_fail`) is managed by the mux — transformers
+    using only StreamChannels don't need `finalize` or `fail` hooks.
+    """
+
+    def __init__(self, name: str, *, maxlen: int | None = None) -> None:
+        """Initialize the channel with an empty inner log.
+
+        Args:
+            name: The protocol channel name used for auto-forwarded
+                events (`custom:<name>` on the wire).
+            maxlen: Optional retention cap on the inner EventLog. See
+                `EventLog.__init__` for semantics.
+        """
+        self.name = name
+        self._log: EventLog[T] = EventLog(maxlen=maxlen)
+        self._wire_fn: Callable[[T], None] | None = None
+
+    def _bind(self, *, is_async: bool) -> None:
+        """Bind the underlying event log to sync or async mode.
+
+        Args:
+            is_async: True for async iteration, False for sync.
+        """
+        self._log._bind(is_async=is_async)
+
+    def push(self, item: T) -> None:
+        """Append an item to the log and auto-forward if wired.
+
+        Args:
+            item: The item to push.
+        """
+        self._log.push(item)
+        if self._wire_fn is not None:
+            self._wire_fn(item)
+
+    # ------------------------------------------------------------------
+    # Mux lifecycle hooks (not called by transformers directly)
+    # ------------------------------------------------------------------
+
+    def _wire(self, fn: Callable[[T], None]) -> None:
+        """Install the auto-forward callback (called by StreamMux)."""
+        self._wire_fn = fn
+
+    def _close(self) -> None:
+        """Close the underlying log (called by StreamMux on run end)."""
+        self._log.close()
+
+    def _fail(self, err: BaseException) -> None:
+        """Fail the underlying log (called by StreamMux on run error)."""
+        self._log.fail(err)
+
+    # ------------------------------------------------------------------
+    # Iteration — delegates to the inner event log (multi-cursor)
+    # ------------------------------------------------------------------
+
+    def __iter__(self) -> Iterator[T]:
+        return iter(self._log)
+
+    def __aiter__(self) -> AsyncIterator[T]:
+        return self._log.__aiter__()
+
+    def tee(self, n: int = 2) -> tuple[Iterator[T], ...]:
+        """Fan out the channel into `n` independent sync iterators.
+
+        Delegates to the underlying EventLog's `tee()`.
+        """
+        return self._log.tee(n)
+
+    def atee(self, n: int = 2) -> tuple[AsyncIterator[T], ...]:
+        """Fan out the channel into `n` independent async iterators.
+
+        Delegates to the underlying EventLog's `atee()`.
+        """
+        return self._log.atee(n)

libs/langgraph/langgraph/stream/transformers.py

@@ -0,0 +1,477 @@
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any, Literal, cast
+
+from langchain_core.language_models._compat_bridge import message_to_events
+from langchain_core.language_models.chat_model_stream import (
+    AsyncChatModelStream,
+    ChatModelStream,
+)
+from langchain_core.messages import AIMessageChunk, BaseMessage
+from langchain_protocol.protocol import CheckpointRef, LifecycleData, MessagesData
+
+from langgraph.errors import GraphInterrupt
+from langgraph.stream._event_log import EventLog
+from langgraph.stream._types import ProtocolEvent, StreamTransformer
+from langgraph.stream.run_stream import BaseRunStream
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from langgraph.stream._mux import StreamMux
+
+
+logger = logging.getLogger(__name__)
+
+
+SubgraphStatus = Literal["started", "running", "completed", "failed", "interrupted"]
+_TERMINAL_STATUSES: frozenset[SubgraphStatus] = frozenset(
+    {"completed", "failed", "interrupted"}
+)
+
+
+class ValuesTransformer(StreamTransformer):
+    """Capture values events as a drainable stream of state snapshots.
+
+    Keeps `_latest` / `_interrupted` / `_interrupts` as scalar state
+    regardless of whether the log has a subscriber — so `run.output()`
+    and `run.interrupted` work without forcing the caller to iterate
+    `run.values`. Log pushes are silent no-ops when unsubscribed.
+
+    Native transformer — projection keys are exposed as direct
+    attributes on the run stream (e.g. `run.values`).
+
+    `scope` (inherited from `StreamTransformer`) is the namespace the
+    transformer captures values for. `()` matches the root graph;
+    subgraph mini-muxes pass their subgraph's namespace, so each
+    instance sees only its own level.
+    """
+
+    _native = True
+    required_stream_modes = ("values",)
+
+    def __init__(self, scope: tuple[str, ...] = ()) -> None:
+        super().__init__(scope)
+        self._log: EventLog[dict[str, Any]] = EventLog()
+        self._latest: dict[str, Any] | None = None
+        self._interrupted = False
+        self._interrupts: list[Any] = []
+
+    def init(self) -> dict[str, Any]:
+        return {"values": self._log}
+
+    @property
+    def error(self) -> BaseException | None:
+        """The error that ended the run, or `None` if it succeeded.
+
+        Set by the mux when it auto-fails the projection log.
+        """
+        return self._log._error
+
+    def process(self, event: ProtocolEvent) -> bool:
+        # Namespace filtering is handled by the mux via `scope_exact`.
+        if event["method"] != "values":
+            return True
+        params = event["params"]
+        self._latest = params["data"]
+        interrupts = params.get("interrupts", ())
+        if interrupts:
+            self._interrupted = True
+            self._interrupts.extend(interrupts)
+        self._log.push(params["data"])
+        return True
+
+
+class MessagesTransformer(StreamTransformer):
+    """Capture messages events as ChatModelStream objects.
+
+    The messages projection yields one `ChatModelStream` (or
+    `AsyncChatModelStream`) per LLM call. Consumers iterate
+    `run.messages` to get stream handles, then use each handle's typed
+    projections (`.text`, `.reasoning`, `.tool_calls`, `.usage`,
+    `.output`) for per-message content.
+
+    Two input shapes are handled (via `params["data"] = (payload,
+    metadata)` from `StreamMessagesHandler`):
+
+    1. Protocol event (dict with `"event"` key) — emitted by
+       `stream_v2()` / `astream_v2()` via the `on_stream_event`
+       callback. Routed to an existing `ChatModelStream` by
+       `metadata["run_id"]`. A `message-start` event creates a new
+       stream; `message-finish` closes it.
+    2. Whole `AIMessage` — emitted from `on_chain_end` when a node
+       returns a finalized message. Replayed as a synthetic protocol
+       event lifecycle via `message_to_events`, then the
+       already-complete stream is pushed to the log.
+
+    V1 `AIMessageChunk` tuples (from `on_llm_new_token`) are not
+    streamed into this projection: chat models that want to populate
+    `run.messages` with content-block streaming must use
+    `stream_v2()` / `astream_v2()`. Models called via the legacy
+    `stream()` method still surface their final `AIMessage` via
+    `on_chain_end` when a node returns it as state.
+
+    `scope` (inherited from `StreamTransformer`) is the namespace the
+    transformer captures messages for. `()` matches the root graph;
+    subgraph mini-muxes pass their subgraph's namespace, so each
+    instance sees only its own level.
+
+    Native transformer — the `messages` projection is exposed as a
+    direct attribute on the run stream.
+    """
+
+    _native = True
+    required_stream_modes = ("messages",)
+
+    def __init__(self, scope: tuple[str, ...] = ()) -> None:
+        super().__init__(scope)
+        self._log: EventLog[ChatModelStream] = EventLog()
+        # Correlate protocol events back to a ChatModelStream by run_id
+        # (attached to the event's metadata by StreamMessagesHandler).
+        self._by_run: dict[str, ChatModelStream] = {}
+        self._pump_fn: Callable[[], bool] | None = None
+        self._apump_fn: Callable[[], Awaitable[bool]] | None = None
+
+    def init(self) -> dict[str, Any]:
+        return {"messages": self._log}
+
+    def _bind_pump(self, fn: Callable[[], bool]) -> None:
+        """Wire the sync pull callback. Called by GraphRunStream._wire_request_more."""
+        self._pump_fn = fn
+
+    def _bind_apump(self, fn: Callable[[], Awaitable[bool]]) -> None:
+        """Wire the async pull callback.
+
+        Called by `AsyncGraphRunStream._wire_arequest_more` so each
+        `AsyncChatModelStream` this transformer creates can drive the
+        shared graph pump from its projection cursors.
+        """
+        self._apump_fn = fn
+
+    def _make_stream(
+        self,
+        *,
+        namespace: list[str],
+        node: str | None,
+        message_id: str | None,
+    ) -> ChatModelStream:
+        """Create a ChatModelStream (sync) or AsyncChatModelStream (async).
+
+        Wires whichever pump is bound. Prefers the async pump so nested
+        iteration under `AsyncGraphRunStream` drives the graph forward
+        without a background task. The unwired fallback (no pump bound)
+        is used by unit tests that dispatch events manually.
+        """
+        if self._apump_fn is not None:
+            astream = AsyncChatModelStream(
+                namespace=namespace,
+                node=node,
+                message_id=message_id,
+            )
+            astream.set_arequest_more(self._apump_fn)
+            return astream
+        if self._pump_fn is not None:
+            stream: ChatModelStream = ChatModelStream(
+                namespace=namespace,
+                node=node,
+                message_id=message_id,
+            )
+            stream.set_request_more(self._pump_fn)
+            return stream
+        return AsyncChatModelStream(
+            namespace=namespace,
+            node=node,
+            message_id=message_id,
+        )
+
+    def process(self, event: ProtocolEvent) -> bool:
+        # Namespace filtering is handled by the mux via `scope_exact`.
+        if event["method"] != "messages":
+            return True
+        params = event["params"]
+
+        payload, metadata = params["data"]
+        node: str | None = metadata.get("langgraph_node")
+        run_id = str(metadata.get("run_id", "")) if metadata else ""
+
+        if isinstance(payload, dict) and "event" in payload:
+            self._route_protocol_event(
+                cast("MessagesData", payload), run_id=run_id, node=node
+            )
+        elif isinstance(payload, BaseMessage) and not isinstance(
+            payload, AIMessageChunk
+        ):
+            self._route_whole_message(payload, node=node)
+        # Legacy AIMessageChunk tuples (from on_llm_new_token) are ignored;
+        # v1 streaming callers must switch to stream_v2() to populate this
+        # projection.
+
+        return True
+
+    def _route_protocol_event(
+        self,
+        event: MessagesData,
+        *,
+        run_id: str,
+        node: str | None,
+    ) -> None:
+        event_type = event.get("event")
+        if event_type == "message-start":
+            message_id = event.get("message_id")
+            stream = self._make_stream(
+                namespace=list(self.scope),
+                node=node,
+                message_id=str(message_id) if message_id is not None else None,
+            )
+            self._by_run[run_id] = stream
+            self._log.push(stream)
+            stream.dispatch(event)
+        elif run_id in self._by_run:
+            stream = self._by_run[run_id]
+            stream.dispatch(event)
+            if event_type == "message-finish":
+                del self._by_run[run_id]
+
+    def _route_whole_message(self, message: BaseMessage, *, node: str | None) -> None:
+        stream = self._make_stream(
+            namespace=list(self.scope),
+            node=node,
+            message_id=message.id,
+        )
+        for evt in message_to_events(message, message_id=message.id):
+            stream.dispatch(evt)
+        self._log.push(stream)
+
+    def finalize(self) -> None:
+        """Clear any routing state — streams close themselves via `message-finish`."""
+        self._by_run.clear()
+
+    def fail(self, err: BaseException) -> None:
+        """Propagate run error to any streams still open when the graph fails."""
+        for stream in list(self._by_run.values()):
+            stream.fail(err)
+        self._by_run.clear()
+
+
+class SubgraphRunStream(BaseRunStream):
+    """Scoped view of a single nested subgraph execution.
+
+    Yielded on `run.subgraphs` (or `parent.subgraphs` for grandchildren)
+    when a nested `Pregel` spawns. Wraps a mini-`StreamMux` built with
+    the same transformer factories as the root mux, so `.values`,
+    `.messages`, `.subgraphs` are populated by the standard
+    transformers scoped to this handle's namespace — no duplicated
+    routing logic. The mini-mux borrows the root's pump via
+    `make_child`'s pump inheritance, so any cursor on a subagent
+    projection drives the whole run forward.
+
+    Lifecycle fields update in place as events arrive:
+
+    - `path`: the namespace tuple — stable for the life of the handle.
+    - `graph_name` / `trigger_call_id`: set once from the `started`
+      payload.
+    - `status`: advances `started` → `running` → `completed` /
+      `failed` / `interrupted`.
+    - `error` / `checkpoint`: set on the terminal event when present.
+
+    `.output` is a snapshot of the latest values seen at this
+    namespace — it doesn't drive the pump (unlike root's
+    `GraphRunStream.output`), because advancing a subgraph to
+    completion is only meaningful as part of advancing the whole run.
+    """
+
+    def __init__(
+        self,
+        path: tuple[str, ...],
+        mux: StreamMux,
+        *,
+        graph_name: str | None = None,
+        trigger_call_id: str | None = None,
+    ) -> None:
+        super().__init__(mux)
+        self.path: tuple[str, ...] = path
+        self.graph_name: str | None = graph_name
+        self.trigger_call_id: str | None = trigger_call_id
+        self.status: SubgraphStatus = "started"
+        self.error: str | None = None
+        self.checkpoint: CheckpointRef | None = None
+
+    @property
+    def output(self) -> dict[str, Any] | None:
+        """Latest values snapshot at this namespace, or `None`.
+
+        Snapshot-only — iterating other projections or the root's
+        `.output` is what drives the pump.
+        """
+        values_t = self._mux.transformer_by_key("values")
+        if isinstance(values_t, ValuesTransformer):
+            return values_t._latest
+        return None
+
+
+class SubgraphTransformer(StreamTransformer):
+    """Discover subgraphs and route events into per-subgraph mini-muxes.
+
+    Thin state-machine + dispatcher. At its own `scope` (inherited
+    from `StreamTransformer`, determined by the enclosing mux), it
+    watches for `lifecycle` events at exactly one level deeper to
+    discover direct children. Each discovered child gets its own
+    `SubgraphRunStream` backed by a mini-`StreamMux` — built via
+    `parent_mux.make_child(path)`, so the same factory list produces
+    fresh transformer instances at the child's scope.
+
+    Every incoming event that falls under one of the direct children
+    (ns starts with a child's `path`) is forwarded into that child's
+    mini-mux via `push`. The standard transformers in that mini-mux
+    (`ValuesTransformer`, `MessagesTransformer`, and another
+    `SubgraphTransformer` for grandchildren) handle the rest. No
+    duplicated routing or assembly logic.
+
+    Lifecycle state for each handle (running / completed / failed /
+    interrupted) is updated in place as events fire. On terminal
+    events, the handle's mini-mux is closed so any subscribed cursors
+    unblock. `finalize` / `fail` handle dangling handles left mid-run.
+
+    Native transformer — `subgraphs` exposes the direct-children log.
+
+    `scope_exact = False`: this transformer sees events at any
+    namespace, because it forwards out-of-scope events to the matching
+    direct-child mini-mux.
+    """
+
+    _native = True
+    scope_exact = False
+    required_stream_modes = ("lifecycle",)
+
+    def __init__(self, scope: tuple[str, ...] = ()) -> None:
+        super().__init__(scope)
+        self._root_log: EventLog[SubgraphRunStream] = EventLog()
+        # Direct children only (namespace = scope + one segment).
+        self._by_ns: dict[tuple[str, ...], SubgraphRunStream] = {}
+        self._mux: StreamMux | None = None
+
+    def init(self) -> dict[str, Any]:
+        return {"subgraphs": self._root_log}
+
+    def _on_register(self, mux: StreamMux) -> None:
+        """Capture the enclosing mux so we can build child mini-muxes."""
+        self._mux = mux
+
+    def process(self, event: ProtocolEvent) -> bool:
+        ns = tuple(event["params"]["namespace"])
+        method = event["method"]
+        depth = len(self.scope)
+
+        # 1. On `started` for a direct child (ns depth = mine + 1 and
+        #    ns prefix matches mine), register the handle.
+        if method == "lifecycle" and len(ns) == depth + 1 and ns[:-1] == self.scope:
+            data = cast(LifecycleData, event["params"]["data"])
+            if data.get("event") == "started":
+                self._on_started(ns, data)
+
+        # 2. Forward the event to the matching direct-child mini-mux
+        #    before the status-change step below so that terminal events
+        #    reach the child's log and grandchild transformers *before*
+        #    the child's mini-mux is closed. Prefix-match: ns must start
+        #    with some child's path.
+        direct_child_ns = ns[: depth + 1] if len(ns) > depth else None
+        if direct_child_ns is not None and direct_child_ns in self._by_ns:
+            self._by_ns[direct_child_ns]._mux.push(event)
+
+        # 3. Status change for a direct child (ns = child's path, method
+        #    = lifecycle). Update handle fields, close mini-mux on
+        #    terminal.
+        if (
+            method == "lifecycle"
+            and ns in self._by_ns
+            and len(ns) == depth + 1
+            and ns[:-1] == self.scope
+        ):
+            data = cast(LifecycleData, event["params"]["data"])
+            event_type = data.get("event")
+            if event_type in ("running", "completed", "failed", "interrupted"):
+                self._on_status_change(ns, event_type, data)
+
+        return True
+
+    def _on_started(self, ns: tuple[str, ...], data: LifecycleData) -> None:
+        if ns in self._by_ns:
+            # Duplicate started — ignore.
+            return
+        # `_on_register` is called by the mux during registration, which
+        # happens before any event can be dispatched — so this should
+        # always be set by the time we process an event.
+        assert self._mux is not None, (
+            "SubgraphTransformer processed an event before _on_register; "
+            "transformer registration ordering is broken."
+        )
+        child_mux = self._mux.make_child(ns)
+        handle = SubgraphRunStream(
+            path=ns,
+            mux=child_mux,
+            graph_name=data.get("graph_name"),
+            trigger_call_id=data.get("trigger_call_id"),
+        )
+        self._by_ns[ns] = handle
+        self._root_log.push(handle)
+
+    def _on_status_change(
+        self,
+        ns: tuple[str, ...],
+        event_type: SubgraphStatus,
+        data: LifecycleData,
+    ) -> None:
+        handle = self._by_ns[ns]
+        handle.status = event_type
+        err = data.get("error")
+        if err is not None:
+            handle.error = err
+        checkpoint = data.get("checkpoint")
+        if checkpoint is not None:
+            handle.checkpoint = checkpoint
+        if event_type in _TERMINAL_STATUSES:
+            self._close_handle_mux(handle)
+
+    @staticmethod
+    def _close_handle_mux(handle: SubgraphRunStream) -> None:
+        # Idempotent close — mux.close() runs finalize on its transformers
+        # (which cascades through grandchildren) and closes projection logs.
+        if not handle._mux._events._closed:
+            try:
+                handle._mux.close()
+            except Exception:
+                logger.warning(
+                    "Error closing subgraph mini-mux at %s; subscribers "
+                    "may not see a clean close.",
+                    handle.path,
+                    exc_info=True,
+                )
+
+    def finalize(self) -> None:
+        """Transition any still-open direct children to `completed`."""
+        for handle in self._by_ns.values():
+            if handle.status not in _TERMINAL_STATUSES:
+                handle.status = "completed"
+            self._close_handle_mux(handle)
+
+    def fail(self, err: BaseException) -> None:
+        """Transition any still-open direct children to `failed` / `interrupted`."""
+        is_interrupt = isinstance(err, GraphInterrupt)
+        terminal: SubgraphStatus = "interrupted" if is_interrupt else "failed"
+        error_str = None if is_interrupt else str(err)
+        for handle in self._by_ns.values():
+            if handle.status not in _TERMINAL_STATUSES:
+                handle.status = terminal
+                if error_str is not None and handle.error is None:
+                    handle.error = error_str
+            if not handle._mux._events._closed:
+                try:
+                    handle._mux.fail(err)
+                except Exception:
+                    logger.warning(
+                        "Error failing subgraph mini-mux at %s; subscribers "
+                        "may not see the terminal error.",
+                        handle.path,
+                        exc_info=True,
+                    )

libs/langgraph/langgraph/types.py

@@ -116,7 +116,15 @@ def ensure_valid_checkpointer(checkpointer: Checkpointer) -> Checkpointer:
 
 
 StreamMode = Literal[
-    "values", "updates", "checkpoints", "tasks", "debug", "messages", "custom"
+    "values",
+    "updates",
+    "checkpoints",
+    "tasks",
+    "debug",
+    "messages",
+    "custom",
+    "lifecycle",
+    "tools",
 ]
 """How the stream method should emit outputs.
 
@@ -129,6 +137,8 @@ StreamMode = Literal[
 - `"checkpoints"`: Emit an event when a checkpoint is created, in the same format as returned by `get_state()`.
 - `"tasks"`: Emit events when tasks start and finish, including their results and errors.
 - `"debug"`: Emit `"checkpoints"` and `"tasks"` events for debugging purposes.
+- `"lifecycle"`: Emit subgraph lifecycle events (`started`, `running`, `completed`, `failed`, `interrupted`) with payloads matching `LifecycleData`.
+- `"tools"`: Emit tool-call lifecycle events (`tool-started`, `tool-output-delta`, `tool-finished`, `tool-error`) keyed by `tool_call_id`.
 """
 
 StreamWriter = Callable[[Any], None]

libs/langgraph/tests/test_stream_messages_transformer.py

@@ -0,0 +1,907 @@
+"""Tests for the MessagesTransformer content-block upgrade (B2).
+
+Verifies that `MessagesTransformer` routes protocol events (emitted by
+`stream_v2` via `on_stream_event`) to `ChatModelStream` objects keyed by
+run_id, and replays whole `AIMessage` payloads via `message_to_events`.
+Legacy v1 `AIMessageChunk` tuples (from `on_llm_new_token`) are ignored.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import pytest
+from langchain_core.language_models import GenericFakeChatModel
+from langchain_core.language_models.chat_model_stream import (
+    AsyncChatModelStream,
+    ChatModelStream,
+)
+from langchain_core.messages import AIMessage, AIMessageChunk
+
+from langgraph.constants import END, START
+from langgraph.graph import MessagesState, StateGraph
+from langgraph.stream._event_log import EventLog
+from langgraph.stream._mux import StreamMux
+from langgraph.stream.run_stream import GraphRunStream
+from langgraph.stream.transformers import MessagesTransformer, ValuesTransformer
+
+TS = int(time.time() * 1000)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _proto_event(
+    event: dict[str, Any],
+    *,
+    run_id: str = "run-1",
+    node: str = "llm",
+) -> dict[str, Any]:
+    """Build a messages ProtocolEvent carrying a protocol event dict (v2 path)."""
+    metadata: dict[str, Any] = {"langgraph_node": node, "run_id": run_id}
+    return {
+        "type": "event",
+        "method": "messages",
+        "params": {
+            "namespace": [],
+            "timestamp": TS,
+            "data": (event, metadata),
+        },
+    }
+
+
+def _v1_chunk(
+    text: str,
+    msg_id: str = "msg-1",
+    *,
+    finish: bool = False,
+    node: str = "llm",
+) -> dict[str, Any]:
+    """Build a messages ProtocolEvent carrying a v1 AIMessageChunk tuple."""
+    rm: dict[str, Any] = {}
+    if finish:
+        rm["finish_reason"] = "stop"
+    message = AIMessageChunk(content=text, id=msg_id, response_metadata=rm)
+    metadata: dict[str, Any] = {"langgraph_node": node}
+    return {
+        "type": "event",
+        "method": "messages",
+        "params": {
+            "namespace": [],
+            "timestamp": TS,
+            "data": (message, metadata),
+        },
+    }
+
+
+def _whole_msg(
+    text: str,
+    msg_id: str = "msg-10",
+    *,
+    node: str = "node",
+) -> dict[str, Any]:
+    """Build a messages ProtocolEvent carrying a completed AIMessage."""
+    message = AIMessage(content=text, id=msg_id)
+    metadata: dict[str, Any] = {"langgraph_node": node}
+    return {
+        "type": "event",
+        "method": "messages",
+        "params": {
+            "namespace": [],
+            "timestamp": TS,
+            "data": (message, metadata),
+        },
+    }
+
+
+def _make_sync_transformer() -> tuple[MessagesTransformer, EventLog[ChatModelStream]]:
+    t = MessagesTransformer()
+    proj = t.init()
+    log: EventLog[ChatModelStream] = proj["messages"]
+    log._bind(is_async=False)
+    # Production subscribes via `iter(log)` from the graph consumer — do that
+    # up front so `push` during `process` isn't a no-op. Tests read buffered
+    # items via `log._items` directly rather than re-iterating.
+    log._subscribed = True
+    t._bind_pump(lambda: False)
+    return t, log
+
+
+def _make_async_transformer() -> tuple[MessagesTransformer, EventLog[ChatModelStream]]:
+    t = MessagesTransformer()
+    proj = t.init()
+    log: EventLog[ChatModelStream] = proj["messages"]
+    log._bind(is_async=True)
+    log._subscribed = True
+    return t, log
+
+
+# Standard lifecycle events for one streaming LLM call.
+def _lifecycle(
+    *,
+    text: str = "hello world",
+    message_id: str = "run-1",
+) -> list[dict[str, Any]]:
+    """Produce a valid protocol event lifecycle: start, delta, finish, end."""
+    # Split text into two deltas to exercise delta accumulation.
+    half = len(text) // 2
+    first, second = text[:half], text[half:]
+    return [
+        {"event": "message-start", "role": "ai", "message_id": message_id},
+        {
+            "event": "content-block-start",
+            "index": 0,
+            "content_block": {"type": "text", "text": ""},
+        },
+        {
+            "event": "content-block-delta",
+            "index": 0,
+            "content_block": {"type": "text", "text": first},
+        },
+        {
+            "event": "content-block-delta",
+            "index": 0,
+            "content_block": {"type": "text", "text": second},
+        },
+        {
+            "event": "content-block-finish",
+            "index": 0,
+            "content_block": {"type": "text", "text": text},
+        },
+        {"event": "message-finish", "reason": "stop"},
+    ]
+
+
+# ---------------------------------------------------------------------------
+# Primary path: protocol event routing
+# ---------------------------------------------------------------------------
+
+
+class TestProtocolEventRouting:
+    def test_message_start_creates_stream(self) -> None:
+        t, log = _make_sync_transformer()
+        t.process(
+            _proto_event(
+                {"event": "message-start", "role": "ai", "message_id": "run-1"},
+                run_id="run-1",
+            )
+        )
+        # Stream is in the log immediately.
+        log.close()
+        streams = list(log._items)
+        assert len(streams) == 1
+        assert isinstance(streams[0], ChatModelStream)
+        assert streams[0].message_id == "run-1"
+
+    def test_full_lifecycle_yields_done_stream(self) -> None:
+        t, log = _make_sync_transformer()
+        for evt in _lifecycle(text="hello world"):
+            t.process(_proto_event(evt, run_id="run-1"))
+        log.close()
+        (stream,) = list(log._items)
+        assert stream.done
+        assert stream.output.content == "hello world"
+
+    def test_message_finish_cleans_up_routing(self) -> None:
+        t, log = _make_sync_transformer()
+        for evt in _lifecycle():
+            t.process(_proto_event(evt, run_id="run-1"))
+        assert t._by_run == {}
+
+    def test_events_without_prior_start_are_ignored(self) -> None:
+        """Orphan delta events (no preceding message-start) are dropped silently."""
+        t, log = _make_sync_transformer()
+        t.process(
+            _proto_event(
+                {
+                    "event": "content-block-delta",
+                    "index": 0,
+                    "content_block": {"type": "text", "text": "orphan"},
+                },
+                run_id="unknown",
+            )
+        )
+        log.close()
+        assert list(log._items) == []
+
+    def test_concurrent_streams_routed_by_run_id(self) -> None:
+        """Two interleaved LLM calls each produce their own stream."""
+        t, log = _make_sync_transformer()
+        # Interleave events from two different run_ids.
+        life_a = _lifecycle(text="aaaa", message_id="run-a")
+        life_b = _lifecycle(text="bbbb", message_id="run-b")
+        for a, b in zip(life_a, life_b):
+            t.process(_proto_event(a, run_id="run-a"))
+            t.process(_proto_event(b, run_id="run-b"))
+        log.close()
+        streams = list(log._items)
+        assert len(streams) == 2
+        by_id = {s.message_id: s for s in streams}
+        assert by_id["run-a"].output.content == "aaaa"
+        assert by_id["run-b"].output.content == "bbbb"
+
+    def test_text_deltas_accumulated_on_stream(self) -> None:
+        t, log = _make_sync_transformer()
+        for evt in _lifecycle(text="abcdef"):
+            t.process(_proto_event(evt))
+        log.close()
+        (stream,) = list(log._items)
+        deltas = list(stream._text_proj._deltas)
+        assert "".join(deltas) == "abcdef"
+
+    def test_stream_pushed_on_message_start_not_finish(self) -> None:
+        """Consumer can see the stream before it finishes."""
+        t, log = _make_sync_transformer()
+        t.process(
+            _proto_event(
+                {"event": "message-start", "role": "ai", "message_id": "run-1"},
+                run_id="run-1",
+            )
+        )
+        # The log has the stream immediately — even though message-finish
+        # hasn't arrived yet.
+        assert len(log._items) == 1
+
+    def test_node_metadata_set_on_stream(self) -> None:
+        t, log = _make_sync_transformer()
+        t.process(
+            _proto_event(
+                {"event": "message-start", "role": "ai", "message_id": "run-1"},
+                run_id="run-1",
+                node="my_llm",
+            )
+        )
+        (stream,) = [*log._items]
+        assert stream.node == "my_llm"
+
+
+# ---------------------------------------------------------------------------
+# Non-streaming (whole AIMessage) fallback
+# ---------------------------------------------------------------------------
+
+
+class TestWholeMessageFallback:
+    def test_whole_ai_message_produces_complete_stream(self) -> None:
+        t, log = _make_sync_transformer()
+        t.process(_whole_msg("the full answer"))
+        log.close()
+        (stream,) = list(log._items)
+        assert stream.done
+        assert stream.output.content == "the full answer"
+
+    def test_whole_message_has_full_lifecycle(self) -> None:
+        t, log = _make_sync_transformer()
+        t.process(_whole_msg("full"))
+        log.close()
+        (stream,) = list(log._items)
+        event_types = [e["event"] for e in stream._events]
+        assert event_types == [
+            "message-start",
+            "content-block-start",
+            "content-block-delta",
+            "content-block-finish",
+            "message-finish",
+        ]
+
+
+# ---------------------------------------------------------------------------
+# Legacy v1 chunks are ignored (users must migrate to stream_v2)
+# ---------------------------------------------------------------------------
+
+
+class TestLegacyChunksIgnored:
+    def test_aimessage_chunk_tuple_is_dropped(self) -> None:
+        t, log = _make_sync_transformer()
+        t.process(_v1_chunk("hello"))
+        t.process(_v1_chunk(" world", finish=True))
+        log.close()
+        assert list(log._items) == []
+
+
+# ---------------------------------------------------------------------------
+# Filtering behaviors
+# ---------------------------------------------------------------------------
+
+
+class TestFiltering:
+    def test_non_messages_events_pass_through(self) -> None:
+        t, _ = _make_sync_transformer()
+        values_event = {
+            "type": "event",
+            "method": "values",
+            "params": {"namespace": [], "timestamp": TS, "data": {"x": 1}},
+        }
+        assert t.process(values_event) is True
+
+    def test_subgraph_namespace_dropped(self) -> None:
+        """Root MessagesTransformer (via the mux) ignores non-root events."""
+        from langgraph.stream._mux import StreamMux
+
+        mux = StreamMux([MessagesTransformer()], is_async=False)
+        t = mux.transformer_by_key("messages")
+        assert isinstance(t, MessagesTransformer)
+        t._log._subscribed = True
+        t._bind_pump(lambda: False)
+
+        mux.push(
+            {
+                "type": "event",
+                "method": "messages",
+                "params": {
+                    "namespace": ["subgraph"],
+                    "timestamp": TS,
+                    "data": (
+                        {"event": "message-start", "message_id": "run-x"},
+                        {"run_id": "run-x"},
+                    ),
+                },
+            }
+        )
+        t._log.close()
+        assert list(t._log._items) == []
+
+
+# ---------------------------------------------------------------------------
+# Lifecycle: finalize / fail
+# ---------------------------------------------------------------------------
+
+
+class TestLifecycle:
+    def test_fail_propagates_to_open_streams(self) -> None:
+        t, log = _make_sync_transformer()
+        t.process(
+            _proto_event(
+                {"event": "message-start", "message_id": "run-1"},
+                run_id="run-1",
+            )
+        )
+        streams = list(log._items)
+        err = RuntimeError("graph died")
+        t.fail(err)
+        assert t._by_run == {}
+        assert streams[0]._error is err
+
+    def test_finalize_clears_routing_state(self) -> None:
+        t, _ = _make_sync_transformer()
+        t.process(
+            _proto_event(
+                {"event": "message-start", "message_id": "run-1"},
+                run_id="run-1",
+            )
+        )
+        assert "run-1" in t._by_run
+        t.finalize()
+        assert t._by_run == {}
+
+
+# ---------------------------------------------------------------------------
+# Async mode (AsyncChatModelStream)
+# ---------------------------------------------------------------------------
+
+
+class TestAsyncMode:
+    def test_async_mode_creates_async_stream(self) -> None:
+        t, log = _make_async_transformer()
+        for evt in _lifecycle(text="async stream"):
+            t.process(_proto_event(evt))
+        streams = list(log._items)
+        assert len(streams) == 1
+        assert isinstance(streams[0], AsyncChatModelStream)
+
+    @pytest.mark.anyio
+    async def test_async_text_projection_yields_deltas(self) -> None:
+        t, log = _make_async_transformer()
+        for evt in _lifecycle(text="hello world"):
+            t.process(_proto_event(evt))
+        (stream,) = list(log._items)
+        assert isinstance(stream, AsyncChatModelStream)
+        collected = []
+        async for delta in stream.text:
+            collected.append(delta)
+        assert "".join(collected) == "hello world"
+
+    @pytest.mark.anyio
+    async def test_async_output_awaitable(self) -> None:
+        t, log = _make_async_transformer()
+        for evt in _lifecycle(text="async"):
+            t.process(_proto_event(evt))
+        (stream,) = list(log._items)
+        msg = await stream.output
+        assert msg.content == "async"
+
+
+# ---------------------------------------------------------------------------
+# GraphRunStream integration
+# ---------------------------------------------------------------------------
+
+
+class TestWireRequestMore:
+    def test_bind_pump_called_on_wire(self) -> None:
+        values_t = ValuesTransformer()
+        messages_t = MessagesTransformer()
+        mux = StreamMux([values_t, messages_t], is_async=False)
+
+        assert messages_t._pump_fn is None
+        run = GraphRunStream(iter([]), mux)
+        # After wire, the transformer's pump callback is set.
+        assert messages_t._pump_fn is not None
+        # And calling it invokes GraphRunStream._pump_next (drains an empty
+        # graph_iter, returns False).
+        assert messages_t._pump_fn() is False
+        assert run._exhausted
+
+    def test_created_streams_have_request_more(self) -> None:
+        values_t = ValuesTransformer()
+        messages_t = MessagesTransformer()
+        mux = StreamMux([values_t, messages_t], is_async=False)
+
+        GraphRunStream(iter([]), mux)
+        log: EventLog[ChatModelStream] = mux.extensions["messages"]
+        log._subscribed = True
+
+        for evt in _lifecycle():
+            messages_t.process(_proto_event(evt))
+
+        (stream,) = list(log._items)
+        # Pump was threaded through: the stream's _request_more points at
+        # the same callable the transformer was bound with.
+        assert stream._request_more is messages_t._pump_fn
+
+
+# ---------------------------------------------------------------------------
+# End-to-end via StreamMux
+# ---------------------------------------------------------------------------
+
+
+class TestViaMux:
+    def test_streaming_via_mux(self) -> None:
+        t = MessagesTransformer()
+        v = ValuesTransformer()
+        mux = StreamMux([v, t], is_async=False)
+        t._bind_pump(lambda: False)
+        log: EventLog[ChatModelStream] = mux.extensions["messages"]
+        # Simulate a consumer subscribing (as `run.messages` iteration would).
+        log._subscribed = True
+
+        for evt in _lifecycle(text="mux stream"):
+            mux.push(_proto_event(evt))
+        mux.close()
+
+        (stream,) = list(log._items)
+        assert stream.output.content == "mux stream"
+
+    def test_whole_message_via_mux(self) -> None:
+        t = MessagesTransformer()
+        v = ValuesTransformer()
+        mux = StreamMux([v, t], is_async=False)
+        t._bind_pump(lambda: False)
+        log: EventLog[ChatModelStream] = mux.extensions["messages"]
+        log._subscribed = True
+
+        mux.push(_whole_msg("result"))
+        mux.close()
+
+        (stream,) = list(log._items)
+        assert stream.output.content == "result"
+
+    @pytest.mark.anyio
+    async def test_async_streaming_via_mux(self) -> None:
+        t = MessagesTransformer()
+        v = ValuesTransformer()
+        mux = StreamMux([v, t], is_async=True)
+        log: EventLog[ChatModelStream] = mux.extensions["messages"]
+        log._subscribed = True
+
+        for evt in _lifecycle(text="async mux"):
+            await mux.apush(_proto_event(evt))
+
+        streams = list(log._items)
+        assert len(streams) == 1
+        msg = await streams[0].output
+        assert msg.content == "async mux"
+        await mux.aclose()
+
+
+# ---------------------------------------------------------------------------
+# End-to-end: full graph → stream_v2 → run.messages
+# ---------------------------------------------------------------------------
+
+
+class TestEndToEnd:
+    """Prove the full pipeline works when a node calls `model.stream_v2()`.
+
+    These tests exercise the path that the new messages projection is
+    designed for: a user node invokes `stream_v2` on a chat model,
+    `on_stream_event` fires on `StreamMessagesHandler`, the handler
+    forwards to the mux, and the transformer routes events into a
+    `ChatModelStream` exposed on `run.messages`.
+
+    Nothing in Pregel calls `stream_v2` automatically yet; the planned
+    `graph.stream_v2()` API (B4) and the `create_react_agent`
+    integration (C2) will wire that up. Until then, populating the
+    messages projection is opt-in at the node level.
+    """
+
+    def test_node_calling_stream_v2_populates_messages(self) -> None:
+        model = GenericFakeChatModel(messages=iter(["hello world"]))
+
+        def call_model(state: MessagesState) -> dict[str, Any]:
+            stream = model.stream_v2(state["messages"])
+            return {"messages": stream.output}
+
+        graph = (
+            StateGraph(MessagesState)
+            .add_node("call_model", call_model)
+            .add_edge(START, "call_model")
+            .add_edge("call_model", END)
+            .compile()
+        )
+
+        run = graph.stream_v2({"messages": "hi"})
+        streams = list(run.messages)
+
+        assert len(streams) == 1
+        assert isinstance(streams[0], ChatModelStream)
+        assert streams[0].output.content == "hello world"
+
+    def test_node_stream_v2_text_deltas_iterate(self) -> None:
+        """Consumer can iterate `.text` on the streamed message in real time."""
+        model = GenericFakeChatModel(messages=iter(["streamed answer"]))
+
+        def call_model(state: MessagesState) -> dict[str, Any]:
+            stream = model.stream_v2(state["messages"])
+            return {"messages": stream.output}
+
+        graph = (
+            StateGraph(MessagesState)
+            .add_node("call_model", call_model)
+            .add_edge(START, "call_model")
+            .add_edge("call_model", END)
+            .compile()
+        )
+
+        run = graph.stream_v2({"messages": "go"})
+
+        # Pull the stream handle out, then iterate its text deltas.
+        (stream,) = list(run.messages)
+        text = "".join(stream.text)
+        assert text == "streamed answer"
+
+    def test_non_llm_message_returned_from_node(self) -> None:
+        """Node returns a finalized AIMessage directly — whole-message fallback."""
+
+        def return_message(state: MessagesState) -> dict[str, Any]:
+            return {"messages": AIMessage(content="hardcoded", id="msg-abc")}
+
+        graph = (
+            StateGraph(MessagesState)
+            .add_node("return_message", return_message)
+            .add_edge(START, "return_message")
+            .add_edge("return_message", END)
+            .compile()
+        )
+
+        run = graph.stream_v2({"messages": "hi"})
+        streams = list(run.messages)
+
+        assert len(streams) == 1
+        assert streams[0].output.content == "hardcoded"
+
+    @pytest.mark.anyio
+    async def test_async_node_calling_astream_v2(self) -> None:
+        model = GenericFakeChatModel(messages=iter(["async answer"]))
+
+        async def call_model(state: MessagesState) -> dict[str, Any]:
+            stream = await model.astream_v2(state["messages"])
+            msg = await stream
+            return {"messages": msg}
+
+        graph = (
+            StateGraph(MessagesState)
+            .add_node("call_model", call_model)
+            .add_edge(START, "call_model")
+            .add_edge("call_model", END)
+            .compile()
+        )
+
+        run = await graph.astream_v2({"messages": "hi"})
+
+        streams = []
+        async for stream in run.messages:
+            streams.append(stream)
+
+        assert len(streams) == 1
+        assert isinstance(streams[0], AsyncChatModelStream)
+        msg = await streams[0].output
+        assert msg.content == "async answer"
+
+    @pytest.mark.anyio
+    async def test_nested_async_iteration_yields_text_deltas(self) -> None:
+        """Iterate `stream.text` inside `async for stream in run.messages`.
+
+        The inner `stream.text` cursor drives the shared graph pump via
+        `AsyncProjection._arequest_more`, wired by
+        `MessagesTransformer._bind_apump` and
+        `AsyncGraphRunStream._wire_arequest_more`.
+        """
+        import asyncio
+
+        model = GenericFakeChatModel(messages=iter(["hello world"]))
+
+        async def call_model(state: MessagesState) -> dict[str, Any]:
+            stream = await model.astream_v2(state["messages"])
+            msg = await stream
+            return {"messages": msg}
+
+        graph = (
+            StateGraph(MessagesState)
+            .add_node("call_model", call_model)
+            .add_edge(START, "call_model")
+            .add_edge("call_model", END)
+            .compile()
+        )
+
+        run = await graph.astream_v2({"messages": "hi"})
+
+        async def consume_nested() -> list[str]:
+            collected: list[str] = []
+            async for stream in run.messages:
+                async for delta in stream.text:
+                    collected.append(delta)
+            return collected
+
+        deltas = await asyncio.wait_for(consume_nested(), timeout=2.0)
+        assert "".join(deltas) == "hello world"
+
+
+class TestEndToEndV2Invoke:
+    """Nodes call `model.invoke()`; `stream_v2` routes through v2.
+
+    Exercises the auto-routing path added in
+    `feat(core): route invoke through v2 event path for
+    _V2StreamingCallbackHandler`: `stream_v2` injects
+    `CONFIG_KEY_STREAM_MESSAGES_V2` into the config, pregel attaches
+    `StreamMessagesHandlerV2`, `BaseChatModel._should_stream_v2` sees the
+    v2 marker and drives the protocol event generator, and
+    `on_stream_event` forwards each event onto the messages channel.
+    """
+
+    def test_invoke_with_v2_marker_populates_messages(self) -> None:
+        """Node calling `model.invoke()` produces one ChatModelStream with v2 events."""
+        model = GenericFakeChatModel(messages=iter(["hello world"]))
+
+        def call_model(state: MessagesState) -> dict[str, Any]:
+            return {"messages": model.invoke(state["messages"])}
+
+        graph = (
+            StateGraph(MessagesState)
+            .add_node("call_model", call_model)
+            .add_edge(START, "call_model")
+            .add_edge("call_model", END)
+            .compile()
+        )
+
+        run = graph.stream_v2({"messages": "hi"})
+        streams = list(run.messages)
+
+        assert len(streams) == 1, (
+            "Expected exactly one ChatModelStream — the streamed invoke and "
+            "the node's return of the same AIMessage must dedupe."
+        )
+        stream = streams[0]
+        assert isinstance(stream, ChatModelStream)
+        assert stream.output.content == "hello world"
+
+    def test_invoke_v2_emits_protocol_events(self) -> None:
+        """Iterating the stream yields the full v2 lifecycle (not v1 chunks)."""
+        model = GenericFakeChatModel(messages=iter(["streamed answer"]))
+
+        def call_model(state: MessagesState) -> dict[str, Any]:
+            return {"messages": model.invoke(state["messages"])}
+
+        graph = (
+            StateGraph(MessagesState)
+            .add_node("call_model", call_model)
+            .add_edge(START, "call_model")
+            .add_edge("call_model", END)
+            .compile()
+        )
+
+        run = graph.stream_v2({"messages": "go"})
+        (stream,) = list(run.messages)
+
+        events = list(stream)
+        event_types = [e.get("event") for e in events]
+        assert "message-start" in event_types
+        assert "content-block-start" in event_types
+        assert "content-block-delta" in event_types
+        assert "content-block-finish" in event_types
+        assert "message-finish" in event_types
+        # Sanity: every event is a dict carrying an "event" key — not an
+        # AIMessageChunk tuple from the v1 path.
+        for event in events:
+            assert isinstance(event, dict)
+            assert "event" in event
+        # Typed projection still assembles the final text.
+        assert stream.output.content == "streamed answer"
+
+    def test_invoke_text_deltas_iterate_live(self) -> None:
+        """`.text` projection yields deltas in order."""
+        model = GenericFakeChatModel(messages=iter(["delta streaming works"]))
+
+        def call_model(state: MessagesState) -> dict[str, Any]:
+            return {"messages": model.invoke(state["messages"])}
+
+        graph = (
+            StateGraph(MessagesState)
+            .add_node("call_model", call_model)
+            .add_edge(START, "call_model")
+            .add_edge("call_model", END)
+            .compile()
+        )
+
+        run = graph.stream_v2({"messages": "hi"})
+        (stream,) = list(run.messages)
+
+        assembled = "".join(stream.text)
+        assert assembled == "delta streaming works"
+
+    def test_invoke_dedupe_survives_multi_node_graph(self) -> None:
+        """Two model-invoking nodes produce exactly two streams, each once."""
+        model_a = GenericFakeChatModel(messages=iter(["alpha"]))
+        model_b = GenericFakeChatModel(messages=iter(["beta"]))
+
+        def node_a(state: MessagesState) -> dict[str, Any]:
+            return {"messages": model_a.invoke(state["messages"])}
+
+        def node_b(state: MessagesState) -> dict[str, Any]:
+            return {"messages": model_b.invoke(state["messages"])}
+
+        graph = (
+            StateGraph(MessagesState)
+            .add_node("node_a", node_a)
+            .add_node("node_b", node_b)
+            .add_edge(START, "node_a")
+            .add_edge("node_a", "node_b")
+            .add_edge("node_b", END)
+            .compile()
+        )
+
+        run = graph.stream_v2({"messages": "hi"})
+        streams = list(run.messages)
+
+        assert len(streams) == 2
+        contents = {s.output.content for s in streams}
+        assert contents == {"alpha", "beta"}
+
+    def test_invoke_plus_constructed_message_two_streams(self) -> None:
+        """A v2-streamed node + a node that returns a constructed AIMessage
+        produces two ChatModelStreams — one from the live event lifecycle,
+        one synthesized from the constructed message via `message_to_events`.
+        """
+        model = GenericFakeChatModel(messages=iter(["live stream"]))
+
+        def streaming_node(state: MessagesState) -> dict[str, Any]:
+            return {"messages": model.invoke(state["messages"])}
+
+        def constructed_node(state: MessagesState) -> dict[str, Any]:
+            return {"messages": [AIMessage(content="hardcoded", id="constructed-1")]}
+
+        graph = (
+            StateGraph(MessagesState)
+            .add_node("streaming_node", streaming_node)
+            .add_node("constructed_node", constructed_node)
+            .add_edge(START, "streaming_node")
+            .add_edge("streaming_node", "constructed_node")
+            .add_edge("constructed_node", END)
+            .compile()
+        )
+
+        run = graph.stream_v2({"messages": "hi"})
+        streams = list(run.messages)
+
+        assert len(streams) == 2
+        assert streams[0].node == "streaming_node"
+        assert streams[0].output.content == "live stream"
+        assert streams[1].node == "constructed_node"
+        assert streams[1].output.content == "hardcoded"
+        assert streams[1].message_id == "constructed-1"
+
+    @pytest.mark.anyio
+    async def test_ainvoke_with_v2_marker_populates_messages(self) -> None:
+        """Async mirror: `model.ainvoke()` + `astream_v2`."""
+        model = GenericFakeChatModel(messages=iter(["async invoke"]))
+
+        async def call_model(state: MessagesState) -> dict[str, Any]:
+            return {"messages": await model.ainvoke(state["messages"])}
+
+        graph = (
+            StateGraph(MessagesState)
+            .add_node("call_model", call_model)
+            .add_edge(START, "call_model")
+            .add_edge("call_model", END)
+            .compile()
+        )
+
+        run = await graph.astream_v2({"messages": "hi"})
+
+        streams = []
+        async for stream in run.messages:
+            streams.append(stream)
+
+        assert len(streams) == 1
+        assert isinstance(streams[0], AsyncChatModelStream)
+        msg = await streams[0].output
+        assert msg.content == "async invoke"
+
+
+class TestDirectMessagesModeStaysV1:
+    """Regression guard: direct `graph.stream(stream_mode="messages")`
+    (no `stream_v2`) must keep the v1 `(AIMessageChunk, metadata)`
+    tuple shape. The v2 flag is only injected by `stream_v2` / `astream_v2`.
+    """
+
+    def test_direct_graph_stream_messages_yields_ai_message_chunks(self) -> None:
+        model = GenericFakeChatModel(messages=iter(["legacy path"]))
+
+        def call_model(state: MessagesState) -> dict[str, Any]:
+            return {"messages": model.invoke(state["messages"])}
+
+        graph = (
+            StateGraph(MessagesState)
+            .add_node("call_model", call_model)
+            .add_edge(START, "call_model")
+            .add_edge("call_model", END)
+            .compile()
+        )
+
+        parts = list(graph.stream({"messages": "hi"}, stream_mode="messages"))
+        # Should have at least one streamed chunk; each part is
+        # (AIMessageChunk, metadata) — not a v2 event dict.
+        assert parts, "expected stream_mode='messages' to emit tuples"
+        for part in parts:
+            payload, _metadata = part
+            assert isinstance(payload, AIMessageChunk), (
+                "direct graph.stream(stream_mode='messages') leaked v2 "
+                "event dicts — stream_v2 flag bled through."
+            )
+        assembled = "".join(
+            p[0].content for p in parts if isinstance(p[0].content, str)
+        )
+        assert assembled == "legacy path"
+
+
+class TestStreamMessagesHandlerV2Unit:
+    """Unit tests on the handler class itself."""
+
+    def test_on_llm_new_token_is_noop(self) -> None:
+        """v2 handler must not emit v1 chunks even if `on_llm_new_token` fires
+        (e.g. from a node calling `model.stream()` directly on a v2-flagged run).
+        """
+        from uuid import uuid4
+
+        from langchain_core.outputs import ChatGenerationChunk
+
+        from langgraph.pregel._messages import StreamMessagesHandlerV2
+
+        emitted: list[Any] = []
+        handler = StreamMessagesHandlerV2(emitted.append, subgraphs=False)
+        run_id = uuid4()
+        # Register a fake run so `self.metadata.get(run_id)` would succeed for
+        # other callbacks — this makes sure the no-op is unconditional, not a
+        # side effect of missing metadata.
+        handler.metadata[run_id] = ((), {"langgraph_node": "x"})
+
+        handler.on_llm_new_token(
+            "hello",
+            chunk=ChatGenerationChunk(message=AIMessageChunk(content="hello")),
+            run_id=run_id,
+        )
+
+        assert emitted == [], (
+            "StreamMessagesHandlerV2.on_llm_new_token must not push to the "
+            "messages stream — it's the v2 marker's guarantee."
+        )

libs/langgraph/tests/test_stream_subgraph_transformer.py

@@ -0,0 +1,453 @@
+"""Tests for subgraph lifecycle events and the SubgraphTransformer."""
+
+from __future__ import annotations
+
+import operator
+import time
+from typing import Annotated, Any
+
+import pytest
+from langgraph.checkpoint.memory import InMemorySaver
+from typing_extensions import TypedDict
+
+from langgraph.constants import END, START
+from langgraph.errors import GraphInterrupt
+from langgraph.graph import StateGraph
+from langgraph.stream._event_log import EventLog
+from langgraph.stream._mux import StreamMux
+from langgraph.stream._types import ProtocolEvent
+from langgraph.stream.transformers import (
+    MessagesTransformer,
+    SubgraphRunStream,
+    SubgraphTransformer,
+    ValuesTransformer,
+)
+from langgraph.types import interrupt
+
+TS = int(time.time() * 1000)
+
+
+def _lifecycle(
+    event: str,
+    *,
+    namespace: list[str] | None = None,
+    graph_name: str | None = None,
+    trigger_call_id: str | None = None,
+    error: str | None = None,
+) -> ProtocolEvent:
+    data: dict[str, Any] = {"event": event}
+    if graph_name is not None:
+        data["graph_name"] = graph_name
+    if trigger_call_id is not None:
+        data["trigger_call_id"] = trigger_call_id
+    if error is not None:
+        data["error"] = error
+    return {
+        "type": "event",
+        "method": "lifecycle",
+        "params": {
+            "namespace": namespace or [],
+            "timestamp": TS,
+            "data": data,
+        },
+    }
+
+
+def _values(payload: dict[str, Any], *, namespace: list[str]) -> ProtocolEvent:
+    return {
+        "type": "event",
+        "method": "values",
+        "params": {
+            "namespace": namespace,
+            "timestamp": TS,
+            "data": payload,
+        },
+    }
+
+
+def _subscribe(log: EventLog) -> None:
+    """Flip `_subscribed = True` so pushes retain items for test inspection."""
+    log._subscribed = True
+
+
+# ---------------------------------------------------------------------------
+# Unit tests: feed events directly into the transformer
+# ---------------------------------------------------------------------------
+
+
+_FACTORIES = [ValuesTransformer, MessagesTransformer, SubgraphTransformer]
+
+
+def _handle_values_items(handle: SubgraphRunStream) -> list:
+    return list(handle._mux.extensions["values"]._items)  # type: ignore[attr-defined]
+
+
+def _handle_subgraphs_items(handle: SubgraphRunStream) -> list:
+    return list(handle._mux.extensions["subgraphs"]._items)  # type: ignore[attr-defined]
+
+
+def _pre_subscribe_handle(handle: SubgraphRunStream) -> None:
+    """Flip `_subscribed` on every EventLog inside the handle's mini-mux.
+
+    The mini-mux is built via `make_child` with the full factory list,
+    so values / messages / subgraphs logs all exist as projections.
+    Tests that feed events directly need them subscribed so pushes
+    retain items in the deque for `_items` inspection.
+    """
+    for value in handle._mux.extensions.values():
+        if isinstance(value, EventLog):
+            _subscribe(value)
+
+
+class TestSubgraphTransformerUnit:
+    def _mux(self) -> tuple[StreamMux, SubgraphTransformer]:
+        mux = StreamMux(factories=_FACTORIES, is_async=False)
+        transformer = mux.transformer_by_key("subgraphs")
+        assert isinstance(transformer, SubgraphTransformer)
+        _subscribe(transformer._root_log)
+        return mux, transformer
+
+    def _handle(self, transformer: SubgraphTransformer) -> SubgraphRunStream:
+        """Return the single root handle after pushing one lifecycle started."""
+        (handle,) = list(transformer._root_log._items)
+        return handle
+
+    def test_root_started_is_ignored(self) -> None:
+        mux, transformer = self._mux()
+        mux.push(_lifecycle("started", graph_name="root"))
+        assert list(transformer._root_log._items) == []
+        assert transformer._by_ns == {}
+
+    def test_child_started_yields_handle(self) -> None:
+        mux, transformer = self._mux()
+        mux.push(
+            _lifecycle(
+                "started",
+                namespace=["task_a:child"],
+                graph_name="child",
+                trigger_call_id="task_a",
+            )
+        )
+
+        handle = self._handle(transformer)
+        assert handle.path == ("task_a:child",)
+        assert handle.graph_name == "child"
+        assert handle.trigger_call_id == "task_a"
+        assert handle.status == "started"
+
+    def test_status_transitions(self) -> None:
+        mux, transformer = self._mux()
+        mux.push(_lifecycle("started", namespace=["t:c"], graph_name="c"))
+        mux.push(_lifecycle("running", namespace=["t:c"]))
+        mux.push(_lifecycle("completed", namespace=["t:c"]))
+
+        handle = self._handle(transformer)
+        assert handle.status == "completed"
+
+    def test_grandchild_surfaces_under_child(self) -> None:
+        mux, transformer = self._mux()
+        mux.push(_lifecycle("started", namespace=["t:child"], graph_name="child"))
+
+        child = self._handle(transformer)
+        _pre_subscribe_handle(child)
+
+        mux.push(
+            _lifecycle(
+                "started",
+                namespace=["t:child", "u:grand"],
+                graph_name="grand",
+            )
+        )
+
+        (grand,) = _handle_subgraphs_items(child)
+        assert grand.path == ("t:child", "u:grand")
+        assert grand.graph_name == "grand"
+
+    def test_failed_stores_error(self) -> None:
+        mux, transformer = self._mux()
+        mux.push(_lifecycle("started", namespace=["t:c"], graph_name="c"))
+        mux.push(_lifecycle("failed", namespace=["t:c"], error="boom"))
+
+        handle = self._handle(transformer)
+        assert handle.status == "failed"
+        assert handle.error == "boom"
+
+    def test_values_routed_into_handle(self) -> None:
+        mux, transformer = self._mux()
+        mux.push(_lifecycle("started", namespace=["t:c"], graph_name="c"))
+
+        handle = self._handle(transformer)
+        _pre_subscribe_handle(handle)
+
+        mux.push(_values({"value": 1}, namespace=["t:c"]))
+        mux.push(_values({"value": 2}, namespace=["t:c"]))
+
+        assert _handle_values_items(handle) == [{"value": 1}, {"value": 2}]
+        assert handle.output == {"value": 2}
+
+    def test_root_values_not_routed(self) -> None:
+        mux, transformer = self._mux()
+        mux.push(_lifecycle("started", namespace=["t:c"], graph_name="c"))
+        handle = self._handle(transformer)
+        _pre_subscribe_handle(handle)
+
+        # Values event at root namespace — must not leak into child handle.
+        mux.push(_values({"value": "root"}, namespace=[]))
+        assert _handle_values_items(handle) == []
+
+    def test_finalize_closes_dangling(self) -> None:
+        mux, transformer = self._mux()
+        mux.push(_lifecycle("started", namespace=["t:c"], graph_name="c"))
+        handle = self._handle(transformer)
+
+        mux.close()
+        assert handle.status == "completed"
+        assert handle._mux.extensions["values"]._closed
+        assert handle._mux.extensions["subgraphs"]._closed
+
+    def test_fail_with_graph_interrupt_marks_interrupted(self) -> None:
+        mux, transformer = self._mux()
+        mux.push(_lifecycle("started", namespace=["t:c"], graph_name="c"))
+        handle = self._handle(transformer)
+
+        mux.fail(GraphInterrupt())
+        assert handle.status == "interrupted"
+
+    def test_fail_with_generic_error_marks_failed(self) -> None:
+        mux, transformer = self._mux()
+        mux.push(_lifecycle("started", namespace=["t:c"], graph_name="c"))
+        handle = self._handle(transformer)
+
+        mux.fail(RuntimeError("explode"))
+        assert handle.status == "failed"
+        assert handle.error == "explode"
+
+    def test_duplicate_started_ignored(self) -> None:
+        mux, transformer = self._mux()
+        mux.push(_lifecycle("started", namespace=["t:c"], graph_name="c"))
+        mux.push(_lifecycle("started", namespace=["t:c"], graph_name="other"))
+
+        handles = list(transformer._root_log._items)
+        assert len(handles) == 1
+        assert handles[0].graph_name == "c"
+
+    def test_non_lifecycle_non_values_passthrough(self) -> None:
+        mux, transformer = self._mux()
+        mux.push(
+            {
+                "type": "event",
+                "method": "messages",
+                "params": {"namespace": ["t:c"], "timestamp": TS, "data": "x"},
+            }
+        )
+        assert list(transformer._root_log._items) == []
+
+
+# ---------------------------------------------------------------------------
+# End-to-end tests via stream_v2 on real graphs
+# ---------------------------------------------------------------------------
+
+
+class SimpleState(TypedDict):
+    value: str
+    items: Annotated[list[str], operator.add]
+
+
+def _build_nested_graph():
+    """Parent graph with a compiled subgraph node."""
+
+    def inner_node(state: SimpleState) -> dict:
+        return {"value": state["value"] + "X", "items": ["x"]}
+
+    inner_builder = StateGraph(SimpleState)
+    inner_builder.add_node("inner_node", inner_node)
+    inner_builder.add_edge(START, "inner_node")
+    inner_builder.add_edge("inner_node", END)
+    inner = inner_builder.compile()
+
+    def outer_node(state: SimpleState) -> dict:
+        return {"value": state["value"] + "Y", "items": ["y"]}
+
+    outer_builder = StateGraph(SimpleState)
+    outer_builder.add_node("outer_node", outer_node)
+    outer_builder.add_node("sub", inner)
+    outer_builder.add_edge(START, "outer_node")
+    outer_builder.add_edge("outer_node", "sub")
+    outer_builder.add_edge("sub", END)
+    return outer_builder.compile()
+
+
+class TestSubgraphTransformerEndToEnd:
+    def test_flat_graph_yields_no_subgraphs(self) -> None:
+        builder = StateGraph(SimpleState)
+        builder.add_node("n", lambda s: {"value": s["value"] + "!", "items": ["!"]})
+        builder.add_edge(START, "n")
+        builder.add_edge("n", END)
+        graph = builder.compile()
+
+        run = graph.stream_v2({"value": "", "items": []})
+
+        collected: list[SubgraphRunStream] = []
+        for sub in run.subgraphs:
+            collected.append(sub)
+        assert collected == []
+        # Output still resolves.
+        assert run.output is not None
+
+    def test_nested_graph_yields_one_child(self) -> None:
+        graph = _build_nested_graph()
+        run = graph.stream_v2({"value": "", "items": []})
+
+        collected: list[SubgraphRunStream] = []
+        for sub in run.subgraphs:
+            collected.append(sub)
+
+        assert len(collected) == 1
+        child = collected[0]
+        assert len(child.path) == 1
+        assert child.path[0].startswith("sub:")
+        assert child.status == "completed"
+
+    def test_error_in_subgraph_fails_child(self) -> None:
+        def boom(state: SimpleState) -> dict:
+            raise RuntimeError("subgraph_failed")
+
+        inner_builder = StateGraph(SimpleState)
+        inner_builder.add_node("inner", boom)
+        inner_builder.add_edge(START, "inner")
+        inner_builder.add_edge("inner", END)
+        inner = inner_builder.compile()
+
+        outer_builder = StateGraph(SimpleState)
+        outer_builder.add_node("sub", inner)
+        outer_builder.add_edge(START, "sub")
+        outer_builder.add_edge("sub", END)
+        graph = outer_builder.compile()
+
+        run = graph.stream_v2({"value": "", "items": []})
+
+        collected: list[SubgraphRunStream] = []
+        with pytest.raises(RuntimeError):
+            for sub in run.subgraphs:
+                collected.append(sub)
+
+        assert len(collected) == 1
+        assert collected[0].status == "failed"
+
+
+class TestSubgraphTransformerAsyncEndToEnd:
+    @pytest.mark.anyio
+    async def test_nested_graph_yields_one_child(self) -> None:
+        async def inner(state: SimpleState) -> dict:
+            return {"value": state["value"] + "X", "items": ["x"]}
+
+        inner_builder = StateGraph(SimpleState)
+        inner_builder.add_node("inner", inner)
+        inner_builder.add_edge(START, "inner")
+        inner_builder.add_edge("inner", END)
+        inner_graph = inner_builder.compile()
+
+        outer_builder = StateGraph(SimpleState)
+        outer_builder.add_node("sub", inner_graph)
+        outer_builder.add_edge(START, "sub")
+        outer_builder.add_edge("sub", END)
+        graph = outer_builder.compile()
+
+        run = await graph.astream_v2({"value": "", "items": []})
+
+        collected: list[SubgraphRunStream] = []
+        async for sub in run.subgraphs:
+            collected.append(sub)
+
+        assert len(collected) == 1
+        child = collected[0]
+        assert child.status == "completed"
+
+
+class TestSubgraphTriggerCallId:
+    """Confirm `trigger_call_id` flows from real pregel metadata."""
+
+    def test_trigger_call_id_populated_end_to_end(self) -> None:
+        graph = _build_nested_graph()
+        run = graph.stream_v2({"value": "", "items": []})
+
+        collected: list[SubgraphRunStream] = list(run.subgraphs)
+        assert len(collected) == 1
+        child = collected[0]
+
+        # The child's single-segment path encodes `node_name:task_id`.
+        # Both the parsed task_id (`trigger_call_id`) and the segment
+        # should match the same task_id suffix.
+        assert ":" in child.path[0]
+        node_name, _, task_id = child.path[0].partition(":")
+        assert node_name == "sub"
+        assert task_id  # non-empty
+        assert child.trigger_call_id == task_id
+
+
+class TestSubgraphInterrupt:
+    """Interrupts raised inside a subgraph surface as status=interrupted."""
+
+    def _build_interrupt_subgraph(self):
+        def inner_node(state: SimpleState) -> dict:
+            interrupt("need approval")
+            return {"value": state["value"] + "X", "items": ["x"]}
+
+        inner_builder = StateGraph(SimpleState)
+        inner_builder.add_node("inner_node", inner_node)
+        inner_builder.add_edge(START, "inner_node")
+        inner_builder.add_edge("inner_node", END)
+        inner = inner_builder.compile()
+
+        outer_builder = StateGraph(SimpleState)
+        outer_builder.add_node("sub", inner)
+        outer_builder.add_edge(START, "sub")
+        outer_builder.add_edge("sub", END)
+        return outer_builder.compile(checkpointer=InMemorySaver())
+
+    def test_interrupt_in_subgraph_marks_handle_interrupted(self) -> None:
+        graph = self._build_interrupt_subgraph()
+        run = graph.stream_v2(
+            {"value": "", "items": []},
+            config={"configurable": {"thread_id": "t1"}},
+        )
+
+        collected: list[SubgraphRunStream] = list(run.subgraphs)
+
+        assert run.interrupted is True
+        assert len(collected) == 1
+        assert collected[0].status == "interrupted"
+
+
+class TestSubgraphNameCollision:
+    """The subgraph's compiled `name` equaling its node name is detected.
+
+    Primary detector `name != langgraph_node` fails here; the
+    parent_run_id fallback in `_is_nested_pregel_start` is what keeps
+    the subgraph visible.
+    """
+
+    def test_name_equals_node_name_still_detected(self) -> None:
+        def inner_node(state: SimpleState) -> dict:
+            return {"value": state["value"] + "X", "items": ["x"]}
+
+        inner_builder = StateGraph(SimpleState)
+        inner_builder.add_node("inner_node", inner_node)
+        inner_builder.add_edge(START, "inner_node")
+        inner_builder.add_edge("inner_node", END)
+        # Compile with the same name as the node it will be registered as.
+        inner = inner_builder.compile(name="sub")
+
+        outer_builder = StateGraph(SimpleState)
+        outer_builder.add_node("sub", inner)
+        outer_builder.add_edge(START, "sub")
+        outer_builder.add_edge("sub", END)
+        graph = outer_builder.compile()
+
+        run = graph.stream_v2({"value": "", "items": []})
+
+        collected: list[SubgraphRunStream] = list(run.subgraphs)
+        assert len(collected) == 1
+        child = collected[0]
+        assert child.graph_name == "sub"
+        assert child.status == "completed"

libs/langgraph/tests/test_tool_stream_handler.py

@@ -0,0 +1,290 @@
+"""Tests for StreamToolCallHandler and emit_tool_output_delta.
+
+These tests exercise the langgraph-core piece in isolation — the prebuilt
+`ToolCallTransformer` has its own test file. Here we feed real graphs
+through `Pregel.stream(stream_mode=["tools", ...])` and inspect the raw
+`(ns, mode, payload)` tuples on the `tools` channel.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+import pytest
+from langchain_core.messages import AIMessage
+from langchain_core.tools import tool
+from langgraph.prebuilt import ToolNode
+from typing_extensions import TypedDict
+
+from langgraph.config import emit_tool_output_delta
+from langgraph.constants import END, START
+from langgraph.graph import StateGraph
+from langgraph.graph.message import add_messages
+
+
+class _State(TypedDict):
+    messages: Annotated[list, add_messages]
+
+
+def _caller_sync(tool_name: str, tool_args: dict[str, Any], tc_id: str = "tc1"):
+    def caller(state: _State) -> dict:
+        return {
+            "messages": [
+                AIMessage(
+                    content="",
+                    tool_calls=[{"name": tool_name, "args": tool_args, "id": tc_id}],
+                )
+            ]
+        }
+
+    return caller
+
+
+def _caller_async(tool_name: str, tool_args: dict[str, Any], tc_id: str = "tc1"):
+    async def caller(state: _State) -> dict:
+        return {
+            "messages": [
+                AIMessage(
+                    content="",
+                    tool_calls=[{"name": tool_name, "args": tool_args, "id": tc_id}],
+                )
+            ]
+        }
+
+    return caller
+
+
+def _build_graph(caller, tools) -> Any:
+    sg = StateGraph(_State)
+    sg.add_node("caller", caller)
+    sg.add_node("tools", ToolNode(tools))
+    sg.add_edge(START, "caller")
+    sg.add_edge("caller", "tools")
+    sg.add_edge("tools", END)
+    return sg.compile()
+
+
+def _tool_events(stream) -> list[tuple[tuple[str, ...], dict]]:
+    """Collect `(ns, payload)` for every `tools`-mode chunk."""
+    out: list[tuple[tuple[str, ...], dict]] = []
+    for ns, mode, payload in stream:
+        if mode == "tools":
+            out.append((tuple(ns), payload))
+    return out
+
+
+class TestSyncGraphSyncTool:
+    def test_started_finished_cycle(self) -> None:
+        @tool
+        def echo(text: str) -> str:
+            """echo."""
+            return f"echoed:{text}"
+
+        graph = _build_graph(_caller_sync("echo", {"text": "hi"}), [echo])
+        events = _tool_events(
+            graph.stream(
+                {"messages": []},
+                stream_mode=["tools"],
+                subgraphs=True,
+            )
+        )
+
+        assert [p["event"] for _, p in events] == [
+            "tool-started",
+            "tool-finished",
+        ]
+        assert events[0][1]["tool_call_id"] == "tc1"
+        assert events[0][1]["tool_name"] == "echo"
+        assert events[0][1]["input"] == {"text": "hi"}
+        # ToolNode wraps the return in a ToolMessage.
+        assert events[1][1]["tool_call_id"] == "tc1"
+
+    def test_emit_tool_output_delta_produces_delta_events(self) -> None:
+        @tool
+        def streaming_echo(text: str) -> str:
+            """stream chunks."""
+            for chunk in ("a", "b", "c"):
+                emit_tool_output_delta(chunk)
+            return text
+
+        graph = _build_graph(
+            _caller_sync("streaming_echo", {"text": "x"}), [streaming_echo]
+        )
+        events = _tool_events(
+            graph.stream(
+                {"messages": []},
+                stream_mode=["tools"],
+                subgraphs=True,
+            )
+        )
+
+        deltas = [p["delta"] for _, p in events if p["event"] == "tool-output-delta"]
+        assert deltas == ["a", "b", "c"]
+        # The deltas must be bracketed by started and finished.
+        ordered = [p["event"] for _, p in events]
+        assert ordered[0] == "tool-started"
+        assert ordered[-1] == "tool-finished"
+
+    def test_tool_error_event(self) -> None:
+        @tool
+        def boom() -> str:
+            """raises."""
+            raise ValueError("nope")
+
+        graph = _build_graph(_caller_sync("boom", {}), [boom])
+        events: list[tuple[tuple[str, ...], dict]] = []
+        with pytest.raises(ValueError, match="nope"):
+            for ns, mode, payload in graph.stream(
+                {"messages": []},
+                stream_mode=["tools"],
+                subgraphs=True,
+            ):
+                if mode == "tools":
+                    events.append((tuple(ns), payload))
+
+        kinds = [p["event"] for _, p in events]
+        assert kinds == ["tool-started", "tool-error"]
+        assert events[1][1]["message"] == "nope"
+
+    def test_emit_outside_tool_is_noop(self) -> None:
+        # Called at import time (outside any tool body) — must not raise.
+        emit_tool_output_delta("ignored")
+        emit_tool_output_delta({"any": "payload"})
+
+    def test_no_events_without_tools_mode(self) -> None:
+        @tool
+        def echo(text: str) -> str:
+            """echo."""
+            return text
+
+        graph = _build_graph(_caller_sync("echo", {"text": "hi"}), [echo])
+        # No "tools" in stream_mode — handler is not attached and zero
+        # `tools`-method events fire.
+        chunks = list(
+            graph.stream(
+                {"messages": []},
+                stream_mode=["values"],
+                subgraphs=True,
+            )
+        )
+        assert all(
+            not (isinstance(c, tuple) and len(c) == 3 and c[1] == "tools")
+            for c in chunks
+        )
+
+
+class TestAsyncGraphAsyncTool:
+    @pytest.mark.anyio
+    async def test_async_tool_produces_events(self) -> None:
+        @tool
+        async def aecho(text: str) -> str:
+            """async echo."""
+            emit_tool_output_delta(text)
+            return f"got:{text}"
+
+        graph = _build_graph(_caller_async("aecho", {"text": "hi"}), [aecho])
+        events: list[tuple[tuple[str, ...], dict]] = []
+        async for ns, mode, payload in graph.astream(
+            {"messages": []},
+            stream_mode=["tools"],
+            subgraphs=True,
+        ):
+            if mode == "tools":
+                events.append((tuple(ns), payload))
+
+        kinds = [p["event"] for _, p in events]
+        assert kinds == ["tool-started", "tool-output-delta", "tool-finished"]
+        assert events[1][1]["delta"] == "hi"
+
+
+class TestConcurrentToolCalls:
+    def test_parallel_tool_calls_do_not_bleed(self) -> None:
+        @tool
+        def streamer(marker: str) -> str:
+            """emits marker twice."""
+            emit_tool_output_delta(f"{marker}-1")
+            emit_tool_output_delta(f"{marker}-2")
+            return marker
+
+        def caller(state: _State) -> dict:
+            return {
+                "messages": [
+                    AIMessage(
+                        content="",
+                        tool_calls=[
+                            {"name": "streamer", "args": {"marker": "A"}, "id": "a"},
+                            {"name": "streamer", "args": {"marker": "B"}, "id": "b"},
+                        ],
+                    )
+                ]
+            }
+
+        graph = _build_graph(caller, [streamer])
+        events = _tool_events(
+            graph.stream(
+                {"messages": []},
+                stream_mode=["tools"],
+                subgraphs=True,
+            )
+        )
+
+        # Group deltas by tool_call_id.
+        by_id: dict[str, list[str]] = {}
+        for _, p in events:
+            if p["event"] == "tool-output-delta":
+                by_id.setdefault(p["tool_call_id"], []).append(p["delta"])
+        assert by_id["a"] == ["A-1", "A-2"]
+        assert by_id["b"] == ["B-1", "B-2"]
+
+
+class TestSubgraphNamespacePropagation:
+    def test_tool_inside_subgraph_emits_with_subgraph_ns(self) -> None:
+        @tool
+        def inner_tool(text: str) -> str:
+            """inner tool."""
+            return text
+
+        def sub_caller(state: _State) -> dict:
+            return {
+                "messages": [
+                    AIMessage(
+                        content="",
+                        tool_calls=[
+                            {
+                                "name": "inner_tool",
+                                "args": {"text": "x"},
+                                "id": "tc1",
+                            }
+                        ],
+                    )
+                ]
+            }
+
+        inner = StateGraph(_State)
+        inner.add_node("sub_caller", sub_caller)
+        inner.add_node("sub_tools", ToolNode([inner_tool]))
+        inner.add_edge(START, "sub_caller")
+        inner.add_edge("sub_caller", "sub_tools")
+        inner.add_edge("sub_tools", END)
+        inner_graph = inner.compile()
+
+        outer = StateGraph(_State)
+        outer.add_node("sub", inner_graph)
+        outer.add_edge(START, "sub")
+        outer.add_edge("sub", END)
+        graph = outer.compile()
+
+        events = _tool_events(
+            graph.stream(
+                {"messages": []},
+                stream_mode=["tools"],
+                subgraphs=True,
+            )
+        )
+
+        # All `tools` events should carry a non-empty namespace rooted
+        # at the `sub` node.
+        assert events, "expected at least one tools event"
+        for ns, _ in events:
+            assert ns  # non-empty
+            assert ns[0].startswith("sub:")

libs/prebuilt/langgraph/prebuilt/__init__.py

@@ -1,5 +1,7 @@
 """langgraph.prebuilt exposes a higher-level API for creating and executing agents and tools."""
 
+from langgraph.prebuilt._tool_call_stream import ToolCallStream
+from langgraph.prebuilt._tool_call_transformer import ToolCallTransformer
 from langgraph.prebuilt.chat_agent_executor import create_react_agent
 from langgraph.prebuilt.tool_node import (
     InjectedState,
@@ -13,6 +15,8 @@ from langgraph.prebuilt.tool_validator import ValidationNode
 __all__ = [
     "create_react_agent",
     "ToolNode",
+    "ToolCallStream",
+    "ToolCallTransformer",
     "tools_condition",
     "ValidationNode",
     "InjectedState",

libs/prebuilt/langgraph/prebuilt/_tool_call_stream.py

@@ -0,0 +1,117 @@
+"""In-process handle for a single tool call's streaming execution.
+
+Mirrors the shape of `ChatModelStream` from langchain-core but simpler —
+a tool has one output channel, no content-block multiplexing. Populated
+by `ToolCallTransformer` as `tool-started` / `tool-output-delta` /
+`tool-finished` / `tool-error` events flow in on the `tools` channel.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Iterator
+from typing import Any
+
+from langgraph.stream._event_log import EventLog
+
+
+class ToolCallStream:
+    """Scoped view of a single tool call's lifecycle.
+
+    Yielded on `run.tool_calls` once per `tool-started` event. Fields
+    are populated as events arrive:
+
+    - `tool_call_id`, `tool_name`, `input`: stable from the start event.
+    - `output_deltas`: an `EventLog` of delta chunks. Iterate (sync or
+      async) to consume partial output in arrival order.
+    - `output`: terminal payload from `tool-finished`, or `None` if the
+      call failed or is still in flight.
+    - `error`: terminal error string from `tool-error`, or `None` if the
+      call succeeded or is still in flight.
+    - `completed`: True once a terminal event (`tool-finished` or
+      `tool-error`) has been observed.
+
+    `ToolCallStream` is not meant to be constructed by end users — it's
+    produced by `ToolCallTransformer` as events flow through the mux.
+    """
+
+    def __init__(
+        self,
+        tool_call_id: str,
+        tool_name: str,
+        input: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize a fresh handle for a tool call.
+
+        Args:
+            tool_call_id: The `tool_call_id` from the AIMessage.
+            tool_name: The tool's name.
+            input: The tool's input arguments (as reported by
+                `on_tool_start`), or `None` if none were captured.
+        """
+        self.tool_call_id = tool_call_id
+        self.tool_name = tool_name
+        self.input = input
+        self._output_deltas: EventLog[Any] = EventLog()
+        self.output: Any = None
+        self.error: str | None = None
+        self.completed = False
+
+    @property
+    def output_deltas(self) -> EventLog[Any]:
+        """The EventLog of streamed `tool-output-delta` payloads.
+
+        Iterate (sync or async depending on how the run was started)
+        to consume partial output in arrival order. The log closes when
+        the tool finishes or errors.
+        """
+        return self._output_deltas
+
+    def _bind(self, *, is_async: bool) -> None:
+        """Bind the deltas log to sync or async iteration.
+
+        Called by `ToolCallTransformer` when constructing this handle so
+        the log matches the enclosing mux's mode.
+        """
+        self._output_deltas._bind(is_async=is_async)
+
+    def _push_delta(self, delta: Any) -> None:
+        self._output_deltas.push(delta)
+
+    def _finish(self, output: Any) -> None:
+        self.output = output
+        self.completed = True
+        self._output_deltas.close()
+
+    def _fail(self, message: str) -> None:
+        self.error = message
+        self.completed = True
+        self._output_deltas.close()
+
+    def __iter__(self) -> Iterator[Any]:
+        """Iterate delta chunks synchronously.
+
+        Equivalent to `iter(self.output_deltas)`. Raises `TypeError` if
+        the underlying log is bound to async mode.
+        """
+        return iter(self._output_deltas)
+
+    def __aiter__(self) -> AsyncIterator[Any]:
+        """Iterate delta chunks asynchronously.
+
+        Equivalent to `aiter(self.output_deltas)`. Raises `TypeError`
+        if the underlying log is bound to sync mode.
+        """
+        return self._output_deltas.__aiter__()
+
+    def __repr__(self) -> str:
+        status = (
+            "completed"
+            if self.completed and self.error is None
+            else "failed"
+            if self.completed
+            else "running"
+        )
+        return (
+            f"ToolCallStream(tool_call_id={self.tool_call_id!r}, "
+            f"tool_name={self.tool_name!r}, status={status})"
+        )

libs/prebuilt/langgraph/prebuilt/_tool_call_transformer.py

@@ -0,0 +1,128 @@
+"""Transformer that projects `tools` channel events into `ToolCallStream`s."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from langgraph.stream._event_log import EventLog
+from langgraph.stream._types import ProtocolEvent, StreamTransformer
+
+from langgraph.prebuilt._tool_call_stream import ToolCallStream
+
+
+class ToolCallTransformer(StreamTransformer):
+    """Project `tools` channel events into `ToolCallStream` handles.
+
+    Each `tool-started` event spawns a `ToolCallStream`, pushed onto
+    `run.tool_calls`. Subsequent `tool-output-delta` events append to
+    that stream's deltas log; `tool-finished` and `tool-error` close it.
+
+    Native transformer — the `tool_calls` projection is exposed as a
+    direct attribute on the run stream.
+
+    `EventLog[ToolCallStream]` is used (not `StreamChannel`) because the
+    live handles are not serializable and should not be auto-forwarded
+    onto the main event log. Wire consumers subscribe to the `tools`
+    channel instead, where the raw protocol events flow through
+    untouched by this transformer (`process` returns `True`).
+
+    Registered explicitly by users at compile time via
+    `builder.compile(transformers=[ToolCallTransformer])` — not a
+    default built-in, so the `tools` channel is user-opt-in.
+    """
+
+    _native = True
+    required_stream_modes = ("tools",)
+
+    def __init__(self, scope: tuple[str, ...] = ()) -> None:
+        super().__init__(scope)
+        self._log: EventLog[ToolCallStream] = EventLog()
+        self._active: dict[str, ToolCallStream] = {}
+        self._is_async = False
+        self._pump_fn: Callable[[], bool] | None = None
+        self._apump_fn: Callable[[], Awaitable[bool]] | None = None
+
+    def init(self) -> dict[str, Any]:
+        return {"tool_calls": self._log}
+
+    def _bind_pump(self, fn: Callable[[], bool]) -> None:
+        """Wire the sync pull callback onto this transformer.
+
+        Called by `StreamMux.bind_pump`. Stored so each new
+        `ToolCallStream` created by `process` can wire its deltas log
+        for pump-driven iteration.
+        """
+        self._pump_fn = fn
+        self._is_async = False
+
+    def _bind_apump(self, fn: Callable[[], Awaitable[bool]]) -> None:
+        """Async counterpart to `_bind_pump`."""
+        self._apump_fn = fn
+        self._is_async = True
+
+    def _new_stream(
+        self,
+        tool_call_id: str,
+        tool_name: str,
+        tool_input: dict[str, Any] | None,
+    ) -> ToolCallStream:
+        stream = ToolCallStream(tool_call_id, tool_name, tool_input)
+        stream._bind(is_async=self._is_async)
+        if self._apump_fn is not None:
+            stream._output_deltas._arequest_more = self._apump_fn
+        if self._pump_fn is not None:
+            stream._output_deltas._request_more = self._pump_fn
+        return stream
+
+    def process(self, event: ProtocolEvent) -> bool:
+        # Namespace filtering is handled by the mux via `scope_exact`.
+        if event["method"] != "tools":
+            return True
+
+        data = event["params"]["data"]
+        tool_call_id = data.get("tool_call_id")
+        if tool_call_id is None:
+            return True
+        event_type = data.get("event")
+
+        stream: ToolCallStream | None
+        if event_type == "tool-started":
+            stream = self._new_stream(
+                tool_call_id,
+                data.get("tool_name", ""),
+                data.get("input"),
+            )
+            self._active[tool_call_id] = stream
+            self._log.push(stream)
+        elif event_type == "tool-output-delta":
+            stream = self._active.get(tool_call_id)
+            if stream is not None:
+                stream._push_delta(data.get("delta"))
+        elif event_type == "tool-finished":
+            stream = self._active.pop(tool_call_id, None)
+            if stream is not None:
+                stream._finish(data.get("output"))
+        elif event_type == "tool-error":
+            stream = self._active.pop(tool_call_id, None)
+            if stream is not None:
+                stream._fail(data.get("message", ""))
+
+        # Pass-through — wire consumers subscribe to the `tools` channel
+        # directly and reconstruct handles client-side.
+        return True
+
+    def finalize(self) -> None:
+        """Close any still-active tool streams left open at run end."""
+        for stream in self._active.values():
+            if not stream.completed:
+                stream._finish(None)
+        self._active.clear()
+
+    def fail(self, err: BaseException) -> None:
+        """Fail any still-active tool streams when the run errors."""
+        message = str(err)
+        for stream in self._active.values():
+            if not stream.completed:
+                stream._fail(message)
+        self._active.clear()

libs/prebuilt/tests/test_tool_call_transformer.py

@@ -0,0 +1,306 @@
+"""Tests for ToolCallTransformer and the ToolCallStream projection."""
+
+from __future__ import annotations
+
+import time
+from typing import Annotated, Any
+
+import pytest
+from langchain_core.messages import AIMessage
+from langchain_core.tools import tool
+from langgraph.config import emit_tool_output_delta
+from langgraph.constants import END, START
+from langgraph.graph import StateGraph
+from langgraph.graph.message import add_messages
+from langgraph.stream._event_log import EventLog
+from langgraph.stream._mux import StreamMux
+from langgraph.stream._types import ProtocolEvent
+from langgraph.stream.transformers import (
+    MessagesTransformer,
+    SubgraphTransformer,
+    ValuesTransformer,
+)
+from typing_extensions import TypedDict
+
+from langgraph.prebuilt import ToolCallStream, ToolCallTransformer, ToolNode
+
+TS = int(time.time() * 1000)
+
+
+def _tool_event(
+    event: str,
+    tool_call_id: str,
+    *,
+    tool_name: str = "",
+    input: dict[str, Any] | None = None,
+    delta: Any = None,
+    output: Any = None,
+    message: str = "",
+    namespace: list[str] | None = None,
+) -> ProtocolEvent:
+    data: dict[str, Any] = {"event": event, "tool_call_id": tool_call_id}
+    if event == "tool-started":
+        data["tool_name"] = tool_name
+        if input is not None:
+            data["input"] = input
+    elif event == "tool-output-delta":
+        data["delta"] = delta
+    elif event == "tool-finished":
+        data["output"] = output
+    elif event == "tool-error":
+        data["message"] = message
+    return {
+        "type": "event",
+        "method": "tools",
+        "params": {
+            "namespace": namespace or [],
+            "timestamp": TS,
+            "data": data,
+        },
+    }
+
+
+def _subscribe(log: EventLog) -> None:
+    log._subscribed = True
+
+
+def _mux() -> tuple[StreamMux, ToolCallTransformer]:
+    mux = StreamMux(
+        factories=[
+            ValuesTransformer,
+            MessagesTransformer,
+            SubgraphTransformer,
+            ToolCallTransformer,
+        ],
+        is_async=False,
+    )
+    transformer = mux.transformer_by_key("tool_calls")
+    assert isinstance(transformer, ToolCallTransformer)
+    _subscribe(transformer._log)
+    return mux, transformer
+
+
+class TestToolCallTransformerUnit:
+    def test_required_stream_modes_declares_tools(self) -> None:
+        assert ToolCallTransformer.required_stream_modes == ("tools",)
+
+    def test_tool_started_yields_handle(self) -> None:
+        mux, transformer = _mux()
+        mux.push(
+            _tool_event(
+                "tool-started",
+                "tc1",
+                tool_name="echo",
+                input={"text": "hi"},
+            )
+        )
+        handles = list(transformer._log._items)
+        assert len(handles) == 1
+        h = handles[0]
+        assert isinstance(h, ToolCallStream)
+        assert h.tool_call_id == "tc1"
+        assert h.tool_name == "echo"
+        assert h.input == {"text": "hi"}
+        assert h.completed is False
+
+    def test_delta_accumulates_on_active_stream(self) -> None:
+        mux, transformer = _mux()
+        mux.push(_tool_event("tool-started", "tc1", tool_name="echo"))
+        _subscribe(transformer._active["tc1"]._output_deltas)
+        mux.push(_tool_event("tool-output-delta", "tc1", delta="a"))
+        mux.push(_tool_event("tool-output-delta", "tc1", delta="b"))
+        stream = transformer._active["tc1"]
+        assert list(stream._output_deltas._items) == ["a", "b"]
+
+    def test_finish_closes_stream(self) -> None:
+        mux, transformer = _mux()
+        mux.push(_tool_event("tool-started", "tc1", tool_name="echo"))
+        stream = transformer._active["tc1"]
+        mux.push(_tool_event("tool-finished", "tc1", output="done"))
+        assert stream.completed is True
+        assert stream.output == "done"
+        assert stream.error is None
+        assert "tc1" not in transformer._active
+
+    def test_error_closes_stream(self) -> None:
+        mux, transformer = _mux()
+        mux.push(_tool_event("tool-started", "tc1", tool_name="boom"))
+        stream = transformer._active["tc1"]
+        mux.push(_tool_event("tool-error", "tc1", message="nope"))
+        assert stream.completed is True
+        assert stream.output is None
+        assert stream.error == "nope"
+        assert "tc1" not in transformer._active
+
+    def test_concurrent_tool_calls_do_not_bleed(self) -> None:
+        mux, transformer = _mux()
+        mux.push(_tool_event("tool-started", "a", tool_name="t"))
+        mux.push(_tool_event("tool-started", "b", tool_name="t"))
+        for tc in ("a", "b"):
+            _subscribe(transformer._active[tc]._output_deltas)
+        mux.push(_tool_event("tool-output-delta", "a", delta="A1"))
+        mux.push(_tool_event("tool-output-delta", "b", delta="B1"))
+        mux.push(_tool_event("tool-output-delta", "a", delta="A2"))
+        assert list(transformer._active["a"]._output_deltas._items) == ["A1", "A2"]
+        assert list(transformer._active["b"]._output_deltas._items) == ["B1"]
+
+    def test_tools_event_passes_through_main_log(self) -> None:
+        mux, transformer = _mux()
+        _subscribe(mux._events)
+        mux.push(_tool_event("tool-started", "tc1", tool_name="echo"))
+        kept = [e for e in mux._events._items if e["method"] == "tools"]
+        assert len(kept) == 1
+
+
+# ---------------------------------------------------------------------------
+# End-to-end tests with a real graph
+# ---------------------------------------------------------------------------
+
+
+class _State(TypedDict):
+    messages: Annotated[list, add_messages]
+
+
+def _build_graph(caller, tools):
+    sg = StateGraph(_State)
+    sg.add_node("caller", caller)
+    sg.add_node("tools", ToolNode(tools))
+    sg.add_edge(START, "caller")
+    sg.add_edge("caller", "tools")
+    sg.add_edge("tools", END)
+    return sg.compile()
+
+
+class TestToolCallTransformerEndToEnd:
+    def test_sync_streaming_tool_populates_tool_calls(self) -> None:
+        @tool
+        def streamer(text: str) -> str:
+            """streams chunks."""
+            for chunk in ("one", "two"):
+                emit_tool_output_delta(chunk)
+            return text
+
+        def caller(state: _State) -> dict:
+            return {
+                "messages": [
+                    AIMessage(
+                        content="",
+                        tool_calls=[
+                            {"name": "streamer", "args": {"text": "x"}, "id": "tc1"}
+                        ],
+                    )
+                ]
+            }
+
+        graph = _build_graph(caller, [streamer])
+        run = graph.stream_v2({"messages": []}, transformers=[ToolCallTransformer])
+
+        tool_calls: list[ToolCallStream] = []
+        for tc in run.tool_calls:
+            tool_calls.append(tc)
+            deltas = list(tc.output_deltas)
+            assert deltas == ["one", "two"]
+        assert len(tool_calls) == 1
+        tc = tool_calls[0]
+        assert tc.tool_call_id == "tc1"
+        assert tc.tool_name == "streamer"
+        assert tc.completed is True
+        assert tc.error is None
+
+    def test_stream_modes_union_includes_tools(self) -> None:
+        @tool
+        def echo(text: str) -> str:
+            """echo."""
+            return text
+
+        def caller(state: _State) -> dict:
+            return {
+                "messages": [
+                    AIMessage(
+                        content="",
+                        tool_calls=[
+                            {"name": "echo", "args": {"text": "x"}, "id": "tc1"}
+                        ],
+                    )
+                ]
+            }
+
+        graph = _build_graph(caller, [echo])
+        # Without ToolCallTransformer, no tool_calls projection is
+        # exposed and no `tools` events flow through (required_stream_modes
+        # omits it).
+        run_no_tc = graph.stream_v2({"messages": []})
+        assert "tool_calls" not in run_no_tc._mux.extensions  # type: ignore[attr-defined]
+
+        # With ToolCallTransformer, the projection is present.
+        run = graph.stream_v2({"messages": []}, transformers=[ToolCallTransformer])
+        assert "tool_calls" in run._mux.extensions  # type: ignore[attr-defined]
+        # Drain so the run closes cleanly.
+        list(run.tool_calls)
+
+    @pytest.mark.anyio
+    async def test_async_streaming_tool_populates_tool_calls(self) -> None:
+        @tool
+        async def astreamer(text: str) -> str:
+            """async streams."""
+            emit_tool_output_delta(text)
+            emit_tool_output_delta(text + "!")
+            return text
+
+        async def caller(state: _State) -> dict:
+            return {
+                "messages": [
+                    AIMessage(
+                        content="",
+                        tool_calls=[
+                            {"name": "astreamer", "args": {"text": "hi"}, "id": "tc1"}
+                        ],
+                    )
+                ]
+            }
+
+        graph = _build_graph(caller, [astreamer])
+        run = await graph.astream_v2(
+            {"messages": []}, transformers=[ToolCallTransformer]
+        )
+
+        collected: list[ToolCallStream] = []
+        async for tc in run.tool_calls:
+            collected.append(tc)
+            deltas = [d async for d in tc.output_deltas]
+            assert deltas == ["hi", "hi!"]
+        assert len(collected) == 1
+        assert collected[0].completed is True
+        assert collected[0].error is None
+
+    def test_tool_error_populates_error_field(self) -> None:
+        @tool
+        def boom() -> str:
+            """raises."""
+            raise ValueError("nope")
+
+        def caller(state: _State) -> dict:
+            return {
+                "messages": [
+                    AIMessage(
+                        content="",
+                        tool_calls=[{"name": "boom", "args": {}, "id": "tc1"}],
+                    )
+                ]
+            }
+
+        graph = _build_graph(caller, [boom])
+        run = graph.stream_v2({"messages": []}, transformers=[ToolCallTransformer])
+
+        collected: list[ToolCallStream] = []
+        with pytest.raises(ValueError, match="nope"):
+            for tc in run.tool_calls:
+                collected.append(tc)
+                # Drain deltas so the error field is populated before we
+                # inspect it below.
+                list(tc.output_deltas)
+
+        assert len(collected) == 1
+        assert collected[0].error == "nope"
+        assert collected[0].output is None
+        assert collected[0].completed is True