Merge branch 'main' into nh/namespace-keyed-subagents

Comment follow up

.github/workflows/_test.yml

@@ -33,7 +33,7 @@ jobs:
           cache-suffix: test-${{ inputs.working-directory }}
           working-directory: ${{ inputs.working-directory }}
       - name: Login to Docker Hub
-        uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2 # v4
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4
         if: ${{ !github.event.pull_request.head.repo.fork }}
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}

.github/workflows/_test_langgraph.yml

@@ -31,7 +31,7 @@ jobs:
           cache-suffix: "test-langgraph"
           working-directory: libs/langgraph
       - name: Login to Docker Hub
-        uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2 # v4
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4
         if: ${{ !github.event.pull_request.head.repo.fork }}
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}

.github/workflows/_test_release.yml

@@ -82,7 +82,7 @@ jobs:
           path: ${{ inputs.working-directory }}/dist/
 
       - name: Publish to test PyPI
-        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # release/v1
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1
         with:
           packages-dir: ${{ inputs.working-directory }}/dist/
           verbose: true

.github/workflows/bench.yml

@@ -57,7 +57,7 @@ jobs:
             echo EOF
           } >> "$GITHUB_OUTPUT"
       - name: Annotation
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         with:
           script: |
             const file = JSON.parse(`${{ steps.files.outputs.added_modified_renamed }}`)[0]

.github/workflows/deploy-redirects.yml

@@ -40,7 +40,7 @@ jobs:
         uses: actions/configure-pages@v6
 
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v4
+        uses: actions/upload-pages-artifact@v5
         with:
           path: 'docs/_site'
 

.github/workflows/release.yml

@@ -276,7 +276,7 @@ jobs:
           path: ${{ inputs.working-directory }}/dist/
 
       - name: Publish package distributions to PyPI
-        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # release/v1
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1
         with:
           packages-dir: ${{ inputs.working-directory }}/dist/
           verbose: true

.github/workflows/reopen_on_assignment.yml

@@ -26,7 +26,7 @@ jobs:
 
     steps:
       - name: Find and reopen matching PRs
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         with:
           script: |
             const { owner, repo } = context.repo;

.github/workflows/require_issue_link.yml

@@ -50,7 +50,7 @@ jobs:
     steps:
       - name: Check for issue link and assignee
         id: check-link
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         with:
           script: |
             const { owner, repo } = context.repo;
@@ -283,7 +283,7 @@ jobs:
         if: >-
           env.ENFORCE_ISSUE_LINK == 'true' &&
           (steps.check-link.outputs.has-link != 'true' || steps.check-link.outputs.is-assigned != 'true')
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         with:
           script: |
             const { owner, repo } = context.repo;
@@ -312,7 +312,7 @@ jobs:
         if: >-
           env.ENFORCE_ISSUE_LINK == 'true' &&
           steps.check-link.outputs.has-link == 'true' && steps.check-link.outputs.is-assigned == 'true'
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         with:
           script: |
             const { owner, repo } = context.repo;
@@ -366,7 +366,7 @@ jobs:
         if: >-
           env.ENFORCE_ISSUE_LINK == 'true' &&
           (steps.check-link.outputs.has-link != 'true' || steps.check-link.outputs.is-assigned != 'true')
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         with:
           script: |
             const { owner, repo } = context.repo;

.github/workflows/tag-external-issues.yml

@@ -63,7 +63,7 @@ jobs:
       - name: Check if contributor is external
         if: steps.app-token.outcome == 'success'
         id: check-membership
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         with:
           github-token: ${{ steps.app-token.outputs.token }}
           script: |
@@ -102,7 +102,7 @@ jobs:
 
       - name: Apply contributor tier label
         if: steps.check-membership.outputs.is-external == 'true'
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
@@ -155,7 +155,7 @@ jobs:
 
       - name: Add external label
         if: steps.check-membership.outputs.is-external == 'true'
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
@@ -168,7 +168,7 @@ jobs:
 
       - name: Add internal label
         if: steps.check-membership.outputs.is-external == 'false'
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
@@ -196,7 +196,7 @@ jobs:
           private-key: ${{ secrets.ORG_MEMBERSHIP_APP_PRIVATE_KEY }}
 
       - name: Backfill labels
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         with:
           github-token: ${{ steps.app-token.outputs.token }}
           script: |

.github/workflows/tag-external-prs.yml

@@ -48,7 +48,7 @@ jobs:
       - name: Check if contributor is external
         if: steps.app-token.outcome == 'success'
         id: check-membership
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         with:
           github-token: ${{ steps.app-token.outputs.token }}
           script: |
@@ -90,7 +90,7 @@ jobs:
       # event fires and triggers require_issue_link.yml.
       - name: Apply contributor tier label
         if: steps.check-membership.outputs.is-external == 'true'
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         with:
           # Use App token so the "labeled" event propagates to downstream
           # workflows (e.g. require_issue_link.yml).
@@ -145,7 +145,7 @@ jobs:
 
       - name: Add external label
         if: steps.check-membership.outputs.is-external == 'true'
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         with:
           # Use App token so the "labeled" event propagates to downstream
           # workflows (e.g. require_issue_link.yml). Events created by the
@@ -161,7 +161,7 @@ jobs:
 
       - name: Add internal label
         if: steps.check-membership.outputs.is-external == 'false'
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |

.github/workflows/uv_lock_ugprade.yml

@@ -28,7 +28,7 @@ jobs:
         run: make lock-upgrade
           
       - name: Create Pull Request
-        uses: peter-evans/create-pull-request@c0f553fe549906ede9cf27b5156039d195d2ece0 # v8
+        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           commit-message: "chore(deps): upgrade dependencies with `uv lock --upgrade`"

.gitignore

@@ -100,3 +100,4 @@ dmypy.json
 .turbo
 .editorconfig
 .scratch
+.worktrees/

README.md

@@ -27,10 +27,10 @@ Trusted by companies shaping the future of agents – including Klarna, Replit,
 pip install -U langgraph
 ```
 
-If you're looking to quickly build agents with LangChain's `create_agent` (built on LangGraph), check out the [LangChain Agents documentation](https://docs.langchain.com/oss/python/langchain/agents).
+> [!TIP]
+> If you're looking to quickly build agents, check out **[Deep Agents](https://docs.langchain.com/oss/python/deepagents/overview)** — a higher-level package built on LangGraph for agents that can plan, use subagents, and leverage file systems for complex tasks.
 
-> [!NOTE]
-> Looking for the JS/TS library? Check out [LangGraph.js](https://github.com/langchain-ai/langgraphjs) and the [JS docs](https://docs.langchain.com/oss/javascript/langgraph/overview).
+For an equivalent JS/TS library, check out [LangGraph.js](https://github.com/langchain-ai/langgraphjs) and the [JS docs](https://docs.langchain.com/oss/javascript/langgraph/overview).
 
 ## Why use LangGraph?
 
@@ -51,7 +51,7 @@ While LangGraph can be used standalone, it also integrates seamlessly with any L
 
 To improve your LLM application development, pair LangGraph with:
 
-- [Deep Agents](https://github.com/langchain-ai/deepagents) *(new!)* – Build agents that can plan, use subagents, and leverage file systems for complex tasks.
+- [Deep Agents](https://docs.langchain.com/oss/python/deepagents/overview) – Build agents that can plan, use subagents, and leverage file systems for complex tasks.
 - [LangChain](https://docs.langchain.com/oss/python/langchain/overview) – Provides integrations and composable components to streamline LLM application development.
 - [LangSmith](https://www.langchain.com/langsmith) – Helpful for agent evals and observability. Debug poor-performing LLM app runs, evaluate agent trajectories, gain visibility in production, and improve performance over time.
 - [LangSmith Deployment](https://docs.langchain.com/langsmith/deployments) – Deploy and scale agents effortlessly with a purpose-built deployment platform for long-running, stateful workflows. Discover, reuse, configure, and share agents across teams – and iterate quickly with visual prototyping in [LangSmith Studio](https://docs.langchain.com/langsmith/studio).

libs/checkpoint-conformance/README.md

@@ -63,6 +63,7 @@ The suite tests **base** capabilities (required) and **extended** capabilities (
 | `delete_for_runs` | no | `adelete_for_runs` |
 | `copy_thread` | no | `acopy_thread` |
 | `prune` | no | `aprune` |
+| `delta_channel_history` | no | `aget_delta_channel_history` |
 
 Extended capabilities are detected by checking whether the method is overridden from `BaseCheckpointSaver`. If not overridden, those tests are skipped.
 

libs/checkpoint-conformance/langgraph/checkpoint/conformance/capabilities.py

@@ -23,6 +23,7 @@ class Capability(str, Enum):
     DELETE_FOR_RUNS = "delete_for_runs"
     COPY_THREAD = "copy_thread"
     PRUNE = "prune"
+    DELTA_CHANNEL_HISTORY = "delta_channel_history"
 
 
 # Capabilities that every checkpointer must support.
@@ -42,6 +43,7 @@ EXTENDED_CAPABILITIES = frozenset(
         Capability.DELETE_FOR_RUNS,
         Capability.COPY_THREAD,
         Capability.PRUNE,
+        Capability.DELTA_CHANNEL_HISTORY,
     }
 )
 
@@ -57,6 +59,7 @@ _CAPABILITY_METHOD_MAP: dict[Capability, str] = {
     Capability.DELETE_FOR_RUNS: "adelete_for_runs",
     Capability.COPY_THREAD: "acopy_thread",
     Capability.PRUNE: "aprune",
+    Capability.DELTA_CHANNEL_HISTORY: "aget_delta_channel_history",
 }
 
 

libs/checkpoint-conformance/langgraph/checkpoint/conformance/spec/__init__.py

@@ -9,6 +9,9 @@ from langgraph.checkpoint.conformance.spec.test_delete_for_runs import (
 from langgraph.checkpoint.conformance.spec.test_delete_thread import (
     run_delete_thread_tests,
 )
+from langgraph.checkpoint.conformance.spec.test_delta_channel_history import (
+    run_delta_channel_history_tests,
+)
 from langgraph.checkpoint.conformance.spec.test_get_tuple import run_get_tuple_tests
 from langgraph.checkpoint.conformance.spec.test_list import run_list_tests
 from langgraph.checkpoint.conformance.spec.test_prune import run_prune_tests
@@ -24,4 +27,5 @@ __all__ = [
     "run_delete_for_runs_tests",
     "run_copy_thread_tests",
     "run_prune_tests",
+    "run_delta_channel_history_tests",
 ]

libs/checkpoint-conformance/langgraph/checkpoint/conformance/spec/_delta_fixtures.py

@@ -0,0 +1,99 @@
+"""Shared fixtures for delta-channel conformance tests.
+
+Builds a parent chain with `_DeltaSnapshot` blobs at known positions via
+direct `aput` / `aput_writes` calls. No langgraph or Pregel dependency.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+from uuid import uuid4
+
+from langchain_core.runnables import RunnableConfig
+from langgraph.checkpoint.base import BaseCheckpointSaver, Checkpoint
+from langgraph.checkpoint.base.id import uuid6
+
+from langgraph.checkpoint.conformance.test_utils import generate_metadata
+
+
+async def build_delta_chain(
+    saver: BaseCheckpointSaver,
+    *,
+    thread_id: str | None = None,
+    checkpoint_ns: str = "",
+    channel: str = "messages",
+    snapshots_at_steps: Sequence[int] = (0,),
+    total_steps: int = 6,
+    write_value_fn: Any | None = None,
+) -> list[RunnableConfig]:
+    """Build a parent chain with `_DeltaSnapshot` at known positions.
+
+    Args:
+        saver: Checkpointer instance.
+        thread_id: Defaults to a random UUID.
+        checkpoint_ns: Namespace (default root).
+        channel: Channel name used for snapshots and writes.
+        snapshots_at_steps: Steps at which a `_DeltaSnapshot` blob is stored
+            in `channel_values[channel]`. Step 0 is the oldest checkpoint.
+        total_steps: Number of checkpoints in the chain.
+        write_value_fn: Callable(step) -> write value. Defaults to step index.
+
+    Returns:
+        List of stored configs (oldest first), one per step.
+    """
+    if write_value_fn is None:
+
+        def write_value_fn(step: int) -> Any:
+            return step
+
+    from langgraph.checkpoint.serde.types import _DeltaSnapshot
+
+    thread_id = thread_id or str(uuid4())
+    snapshot_set = set(snapshots_at_steps)
+    stored: list[RunnableConfig] = []
+    parent_cfg: RunnableConfig | None = None
+
+    for step in range(total_steps):
+        config: RunnableConfig = {
+            "configurable": {
+                "thread_id": thread_id,
+                "checkpoint_ns": checkpoint_ns,
+            }
+        }
+        if parent_cfg:
+            config["configurable"]["checkpoint_id"] = parent_cfg["configurable"][
+                "checkpoint_id"
+            ]
+
+        channel_values: dict[str, Any] = {}
+        channel_versions: dict[str, int] = {}
+        if step in snapshot_set:
+            channel_values[channel] = _DeltaSnapshot(
+                write_value_fn(step),
+            )
+            channel_versions[channel] = step + 1
+
+        cp = Checkpoint(
+            v=1,
+            id=str(uuid6(clock_seq=-1)),
+            ts="",
+            channel_values=channel_values,
+            channel_versions=channel_versions,
+            versions_seen={},
+            updated_channels=None,
+        )
+        new_versions = dict(channel_versions)
+        parent_cfg = await saver.aput(
+            config, cp, generate_metadata(step=step), new_versions
+        )
+        stored.append(parent_cfg)
+
+        # Write a pending write for non-snapshot steps so the walk has
+        # something to collect.
+        if step not in snapshot_set:
+            await saver.aput_writes(
+                parent_cfg, [(channel, write_value_fn(step))], str(uuid4())
+            )
+
+    return stored

libs/checkpoint-conformance/langgraph/checkpoint/conformance/spec/test_delta_channel_history.py

@@ -0,0 +1,247 @@
+"""DELTA_CHANNEL_HISTORY capability tests — aget_delta_channel_history contract."""
+
+from __future__ import annotations
+
+import traceback
+from collections.abc import Callable
+from uuid import uuid4
+
+from langgraph.checkpoint.base import BaseCheckpointSaver
+
+from langgraph.checkpoint.conformance.spec._delta_fixtures import build_delta_chain
+
+
+async def test_history_returns_writes_oldest_first(
+    saver: BaseCheckpointSaver,
+) -> None:
+    """Writes are returned oldest-to-newest."""
+    tid = str(uuid4())
+    # 5 steps: snapshot at 0, writes at 1,2,3,4.
+    # Head is step 4. Walk starts at step 3 (parent of head).
+    # Collects writes from steps 1,2,3 (between snapshot at 0 and head's parent).
+    configs = await build_delta_chain(
+        saver, thread_id=tid, channel="ch", snapshots_at_steps=[0], total_steps=5
+    )
+    head = configs[-1]
+    result = await saver.aget_delta_channel_history(config=head, channels=["ch"])
+    writes = result["ch"]["writes"]
+    values = [w[2] for w in writes]
+    assert values == [1, 2, 3], f"Expected [1,2,3], got {values}"
+
+
+async def test_history_seed_is_nearest_snapshot(
+    saver: BaseCheckpointSaver,
+) -> None:
+    """Seed is the value from the nearest ancestor with channel_values populated."""
+    tid = str(uuid4())
+    # 6 steps: snapshots at 0 and 3, writes at 1,2,4,5.
+    # Head is step 5. Walk from step 4 backward stops at step 3 (snapshot).
+    # Collects writes from step 4 only (between step 3 and head's parent step 4).
+    configs = await build_delta_chain(
+        saver,
+        thread_id=tid,
+        channel="ch",
+        snapshots_at_steps=[0, 3],
+        total_steps=6,
+    )
+    head = configs[-1]
+    result = await saver.aget_delta_channel_history(config=head, channels=["ch"])
+    assert "seed" in result["ch"], "Expected seed from snapshot at step 3"
+    seed = result["ch"]["seed"]
+    from langgraph.checkpoint.serde.types import _DeltaSnapshot
+
+    actual_value = seed.value if isinstance(seed, _DeltaSnapshot) else seed
+    assert actual_value == 3, f"Expected seed value 3 (step 3), got {actual_value}"
+    writes = result["ch"]["writes"]
+    values = [w[2] for w in writes]
+    assert values == [4], f"Expected [4], got {values}"
+
+
+async def test_history_excludes_target_pending_writes(
+    saver: BaseCheckpointSaver,
+) -> None:
+    """Target's own pending_writes are NOT included in the history."""
+    tid = str(uuid4())
+    configs = await build_delta_chain(
+        saver, thread_id=tid, channel="ch", snapshots_at_steps=[0], total_steps=3
+    )
+    head = configs[-1]
+    # Add writes directly to the head checkpoint
+    await saver.aput_writes(head, [("ch", "extra")], str(uuid4()))
+    result = await saver.aget_delta_channel_history(config=head, channels=["ch"])
+    writes = result["ch"]["writes"]
+    values = [w[2] for w in writes]
+    assert "extra" not in values, f"Target's writes should be excluded, got {values}"
+
+
+async def test_history_multi_channel(
+    saver: BaseCheckpointSaver,
+) -> None:
+    """Multiple channels have independent walk termination."""
+    tid = str(uuid4())
+    configs: list = []
+    parent_cfg = None
+    from langgraph.checkpoint.base import Checkpoint
+    from langgraph.checkpoint.base.id import uuid6
+    from langgraph.checkpoint.serde.types import _DeltaSnapshot
+
+    from langgraph.checkpoint.conformance.test_utils import generate_metadata
+
+    for step in range(5):
+        config = {"configurable": {"thread_id": tid, "checkpoint_ns": ""}}
+        if parent_cfg:
+            config["configurable"]["checkpoint_id"] = parent_cfg["configurable"][
+                "checkpoint_id"
+            ]
+        cv: dict = {}
+        cvs: dict = {}
+        if step == 1:
+            cv["a"] = _DeltaSnapshot("snap_a")
+            cvs["a"] = step + 1
+        if step == 3:
+            cv["b"] = _DeltaSnapshot("snap_b")
+            cvs["b"] = step + 1
+        cp = Checkpoint(
+            v=1,
+            id=str(uuid6(clock_seq=-1)),
+            ts="",
+            channel_values=cv,
+            channel_versions=cvs,
+            versions_seen={},
+            updated_channels=None,
+        )
+        parent_cfg = await saver.aput(config, cp, generate_metadata(step=step), cvs)
+        configs.append(parent_cfg)
+        await saver.aput_writes(parent_cfg, [("a", step), ("b", step)], str(uuid4()))
+
+    head = configs[-1]
+    result = await saver.aget_delta_channel_history(config=head, channels=["a", "b"])
+    a_writes = [w[2] for w in result["a"]["writes"]]
+    b_writes = [w[2] for w in result["b"]["writes"]]
+    assert a_writes == [1, 2, 3], f"Expected a writes [1,2,3], got {a_writes}"
+    assert b_writes == [3], f"Expected b writes [3], got {b_writes}"
+
+
+async def test_history_empty_channels_returns_empty(
+    saver: BaseCheckpointSaver,
+) -> None:
+    """Empty channels list returns empty mapping."""
+    tid = str(uuid4())
+    configs = await build_delta_chain(
+        saver, thread_id=tid, channel="ch", snapshots_at_steps=[0], total_steps=3
+    )
+    result = await saver.aget_delta_channel_history(config=configs[-1], channels=[])
+    assert result == {}
+
+
+async def test_history_walk_to_root_no_seed(
+    saver: BaseCheckpointSaver,
+) -> None:
+    """Walk reaches root without finding seed — no 'seed' key in result."""
+    tid = str(uuid4())
+    configs = await build_delta_chain(
+        saver,
+        thread_id=tid,
+        channel="ch",
+        snapshots_at_steps=[],
+        total_steps=4,
+    )
+    head = configs[-1]
+    result = await saver.aget_delta_channel_history(config=head, channels=["ch"])
+    assert "seed" not in result["ch"], f"Expected no seed, got {result['ch']}"
+
+
+async def test_history_migration_plain_value_as_seed(
+    saver: BaseCheckpointSaver,
+) -> None:
+    """Pre-delta plain value in channel_values acts as seed (migration case).
+
+    When a thread was originally using a regular channel (BinaryOperatorAggregate)
+    and later switches to DeltaChannel, the old checkpoint has a plain value in
+    channel_values[ch] (not a _DeltaSnapshot). The walk should treat it as the
+    seed and terminate there.
+    """
+    from langgraph.checkpoint.base import Checkpoint
+    from langgraph.checkpoint.base.id import uuid6
+
+    from langgraph.checkpoint.conformance.test_utils import generate_metadata
+
+    tid = str(uuid4())
+    configs: list = []
+    parent_cfg = None
+
+    for step in range(4):
+        config = {"configurable": {"thread_id": tid, "checkpoint_ns": ""}}
+        if parent_cfg:
+            config["configurable"]["checkpoint_id"] = parent_cfg["configurable"][
+                "checkpoint_id"
+            ]
+        cv: dict = {}
+        cvs: dict = {}
+        # Step 1: plain value (migration case — old checkpoint before delta)
+        if step == 1:
+            cv["ch"] = [10, 20, 30]
+            cvs["ch"] = step + 1
+        cp = Checkpoint(
+            v=1,
+            id=str(uuid6(clock_seq=-1)),
+            ts="",
+            channel_values=cv,
+            channel_versions=cvs,
+            versions_seen={},
+            updated_channels=None,
+        )
+        parent_cfg = await saver.aput(config, cp, generate_metadata(step=step), cvs)
+        configs.append(parent_cfg)
+        if step != 1:
+            await saver.aput_writes(parent_cfg, [("ch", step)], str(uuid4()))
+
+    head = configs[-1]
+    result = await saver.aget_delta_channel_history(config=head, channels=["ch"])
+    # Seed should be the plain value from step 1
+    assert "seed" in result["ch"], "Expected seed from migration plain value at step 1"
+    seed = result["ch"]["seed"]
+    assert seed == [10, 20, 30], f"Expected plain value [10,20,30], got {seed}"
+    # Writes should be from step 2 only (between seed at step 1 and head's parent step 2)
+    writes = result["ch"]["writes"]
+    values = [w[2] for w in writes]
+    assert values == [2], f"Expected [2], got {values}"
+
+
+ALL_DELTA_CHANNEL_HISTORY_TESTS = [
+    test_history_returns_writes_oldest_first,
+    test_history_seed_is_nearest_snapshot,
+    test_history_excludes_target_pending_writes,
+    test_history_multi_channel,
+    test_history_empty_channels_returns_empty,
+    test_history_walk_to_root_no_seed,
+    test_history_migration_plain_value_as_seed,
+]
+
+
+async def run_delta_channel_history_tests(
+    saver: BaseCheckpointSaver,
+    on_test_result: Callable[[str, str, bool, str | None], None] | None = None,
+) -> tuple[int, int, list[str]]:
+    """Run all delta_channel_history tests. Returns (passed, failed, failure_names)."""
+    passed = 0
+    failed = 0
+    failures: list[str] = []
+    for test_fn in ALL_DELTA_CHANNEL_HISTORY_TESTS:
+        try:
+            await test_fn(saver)
+            passed += 1
+            if on_test_result:
+                on_test_result("delta_channel_history", test_fn.__name__, True, None)
+        except Exception:
+            failed += 1
+            msg = f"{test_fn.__name__}: {traceback.format_exc()}"
+            failures.append(msg)
+            if on_test_result:
+                on_test_result(
+                    "delta_channel_history",
+                    test_fn.__name__,
+                    False,
+                    traceback.format_exc(),
+                )
+    return passed, failed, failures

libs/checkpoint-conformance/langgraph/checkpoint/conformance/validate.py

@@ -19,6 +19,9 @@ from langgraph.checkpoint.conformance.spec.test_delete_for_runs import (
 from langgraph.checkpoint.conformance.spec.test_delete_thread import (
     run_delete_thread_tests,
 )
+from langgraph.checkpoint.conformance.spec.test_delta_channel_history import (
+    run_delta_channel_history_tests,
+)
 from langgraph.checkpoint.conformance.spec.test_get_tuple import run_get_tuple_tests
 from langgraph.checkpoint.conformance.spec.test_list import run_list_tests
 from langgraph.checkpoint.conformance.spec.test_prune import run_prune_tests
@@ -35,6 +38,7 @@ _RUNNERS = {
     Capability.DELETE_FOR_RUNS: run_delete_for_runs_tests,
     Capability.COPY_THREAD: run_copy_thread_tests,
     Capability.PRUNE: run_prune_tests,
+    Capability.DELTA_CHANNEL_HISTORY: run_delta_channel_history_tests,
 }
 
 

libs/checkpoint-conformance/pyproject.toml

@@ -43,7 +43,11 @@ asyncio_mode = "auto"
 # The extended methods (acopy_thread, adelete_for_runs, aprune) are checked
 # at runtime via capability detection and may not exist on the installed
 # base class. Dict literal inference is also overly strict for RunnableConfig.
+# Delta-channel tests import from `langgraph` (not a declared dep of this
+# package — at test time it is installed alongside); private `_DeltaSnapshot`
+# imports are intentional (beta surface).
 unresolved-attribute = "ignore"
+unresolved-import = "ignore"
 invalid-argument-type = "ignore"
 invalid-return-type = "ignore"
 
@@ -58,6 +62,9 @@ lint.select = [
 lint.ignore = ["E501", "B008"]
 target-version = "py310"
 
+[tool.uv.sources]
+langgraph-checkpoint = {path = "../checkpoint", editable = true}
+
 [[tool.uv.index]]
 name = "testpypi"
 url = "https://test.pypi.org/simple/"

libs/checkpoint-postgres/langgraph/checkpoint/postgres/__init__.py

@@ -2,9 +2,9 @@ from __future__ import annotations
 
 import threading
 from collections import defaultdict
-from collections.abc import Iterator, Sequence
+from collections.abc import Iterator, Mapping, Sequence
 from contextlib import contextmanager
-from typing import Any
+from typing import Any, cast
 
 from langchain_core.runnables import RunnableConfig
 from langgraph.checkpoint.base import (
@@ -13,17 +13,25 @@ from langgraph.checkpoint.base import (
     Checkpoint,
     CheckpointMetadata,
     CheckpointTuple,
+    DeltaChannelHistory,
     get_checkpoint_id,
     get_serializable_checkpoint_metadata,
 )
 from langgraph.checkpoint.serde.base import SerializerProtocol
+from langgraph.checkpoint.serde.types import _DeltaSnapshot
 from psycopg import Capabilities, Connection, Cursor, Pipeline
 from psycopg.rows import DictRow, dict_row
 from psycopg.types.json import Jsonb
 from psycopg_pool import ConnectionPool
 
 from langgraph.checkpoint.postgres import _internal
-from langgraph.checkpoint.postgres.base import BasePostgresSaver
+from langgraph.checkpoint.postgres.base import (
+    _DELTA_PAGE_SIZE,
+    BasePostgresSaver,
+    _build_delta_stage1_sql,
+    _build_delta_stage2_sql,
+    _DeltaStage2Row,
+)
 from langgraph.checkpoint.postgres.shallow import ShallowPostgresSaver
 
 Conn = _internal.Conn  # For backward compatibility
@@ -302,7 +310,10 @@ class PostgresSaver(BasePostgresSaver):
         # others are stored in blobs table
         blob_values = {}
         for k, v in checkpoint["channel_values"].items():
-            if v is None or isinstance(v, (str, int, float, bool)):
+            if isinstance(v, _DeltaSnapshot):
+                blob_values[k] = copy["channel_values"].pop(k)
+                copy["channel_values"][k] = True
+            elif v is None or isinstance(v, (str, int, float, bool)):
                 pass
             else:
                 blob_values[k] = copy["channel_values"].pop(k)
@@ -430,6 +441,114 @@ class PostgresSaver(BasePostgresSaver):
                 with conn.cursor(binary=True, row_factory=dict_row) as cur:
                     yield cur
 
+    def get_delta_channel_history(
+        self, *, config: RunnableConfig, channels: Sequence[str]
+    ) -> Mapping[str, DeltaChannelHistory]:
+        """Fast-path override of `BaseCheckpointSaver.get_delta_channel_history`.
+
+        Two-stage query, both stages cover ALL requested channels:
+
+        * Stage 1 (paged): dynamic SELECT over `checkpoints` with K parallel
+          JSONB key lookups (one column pair per channel) — no subquery, no
+          aggregation. Pages newest-first by `checkpoint_id` with a cursor;
+          page size is `_DELTA_PAGE_SIZE`. Stops paging when every channel
+          has found its seed or the chain is exhausted.
+
+        * Stage 2 (per-channel UNION ALL): one branch per channel reading
+          `checkpoint_writes` filtered to that channel's specific
+          `chain_cids`, plus one branch per channel that has a seed reading
+          `checkpoint_blobs` for that channel + version. Avoids the
+          over-fetch of a single `channel = ANY(channels)` filter when
+          channels have different chain depths.
+        """
+        if not channels:
+            return {}
+        channels = list(channels)
+        thread_id = config["configurable"]["thread_id"]
+        checkpoint_ns = config["configurable"].get("checkpoint_ns", "")
+        checkpoint_id = get_checkpoint_id(config)
+        if checkpoint_id is None:
+            target = self.get_tuple(config)
+            if target is None:
+                return {ch: {"writes": []} for ch in channels}
+            checkpoint_id = target.config["configurable"]["checkpoint_id"]
+
+        # Stage 1: paged K-JSONB-lookup scan, walking the parent chain in
+        # Python after each page. Stops as soon as every channel has its seed.
+        stage1_sql = _build_delta_stage1_sql(channels, paged=True)
+        parent_of: dict[str, str | None] = {}
+        ver_by_i_by_cid: list[dict[str, str | None]] = [{} for _ in channels]
+        hs_by_i_by_cid: list[dict[str, bool]] = [{} for _ in channels]
+        chain_by_ch: dict[str, list[str]] = {ch: [] for ch in channels}
+        seed_ver_by_ch: dict[str, str | None] = {ch: None for ch in channels}
+        walk_cursor_by_ch: dict[str, str | None] = {}
+        seeded: set[str] = set()
+        cursor: str | None = None
+
+        with self._cursor() as cur:
+            while True:
+                stage1_params: list[Any] = []
+                for ch in channels:
+                    stage1_params.extend([ch, ch])
+                stage1_params.extend(
+                    [thread_id, checkpoint_ns, cursor, cursor, _DELTA_PAGE_SIZE]
+                )
+                cur.execute(stage1_sql, stage1_params)
+                page = cur.fetchall()
+                if not page:
+                    break
+                oldest = self._ingest_stage1_page(
+                    cast("list[Mapping[str, Any]]", page),
+                    channels,
+                    parent_of,
+                    ver_by_i_by_cid,
+                    hs_by_i_by_cid,
+                )
+                self._try_advance_walks(
+                    checkpoint_id,
+                    channels,
+                    parent_of,
+                    ver_by_i_by_cid,
+                    hs_by_i_by_cid,
+                    chain_by_ch,
+                    seed_ver_by_ch,
+                    walk_cursor_by_ch,
+                    seeded,
+                )
+                # Stop if every channel is seeded, or the page was short
+                # (chain exhausted — no more rows to fetch).
+                if len(seeded) == len(channels) or len(page) < _DELTA_PAGE_SIZE:
+                    break
+                cursor = oldest
+
+        # Stage 2: per-channel UNION ALL — one writes branch per channel
+        # with non-empty chain, plus one blob branch per seeded channel.
+        channels_with_chain = [ch for ch in channels if chain_by_ch[ch]]
+        channels_with_seed = [ch for ch in channels if seed_ver_by_ch[ch] is not None]
+        stage2_sql = _build_delta_stage2_sql(
+            channels_with_chain=channels_with_chain,
+            channels_with_seed=channels_with_seed,
+        )
+
+        if stage2_sql:
+            stage2_params: list[Any] = []
+            for ch in channels_with_chain:
+                stage2_params.extend([thread_id, checkpoint_ns, ch, chain_by_ch[ch]])
+            for ch in channels_with_seed:
+                stage2_params.extend([thread_id, checkpoint_ns, ch, seed_ver_by_ch[ch]])
+            with self._cursor() as cur:
+                cur.execute(stage2_sql, stage2_params)
+                stage2_rows = cur.fetchall()
+        else:
+            stage2_rows = []
+
+        return self._build_delta_channels_writes_history(
+            channels=channels,
+            chain_by_ch=chain_by_ch,
+            seed_ver_by_ch=seed_ver_by_ch,
+            stage2_rows=cast("list[_DeltaStage2Row]", stage2_rows),
+        )
+
     def _load_checkpoint_tuple(self, value: DictRow) -> CheckpointTuple:
         """
         Convert a database row into a CheckpointTuple object.

libs/checkpoint-postgres/langgraph/checkpoint/postgres/aio.py

@@ -2,9 +2,9 @@ from __future__ import annotations
 
 import asyncio
 from collections import defaultdict
-from collections.abc import AsyncIterator, Iterator, Sequence
+from collections.abc import AsyncIterator, Iterator, Mapping, Sequence
 from contextlib import asynccontextmanager
-from typing import Any
+from typing import Any, cast
 
 from langchain_core.runnables import RunnableConfig
 from langgraph.checkpoint.base import (
@@ -13,17 +13,25 @@ from langgraph.checkpoint.base import (
     Checkpoint,
     CheckpointMetadata,
     CheckpointTuple,
+    DeltaChannelHistory,
     get_checkpoint_id,
     get_serializable_checkpoint_metadata,
 )
 from langgraph.checkpoint.serde.base import SerializerProtocol
+from langgraph.checkpoint.serde.types import _DeltaSnapshot
 from psycopg import AsyncConnection, AsyncCursor, AsyncPipeline, Capabilities
 from psycopg.rows import DictRow, dict_row
 from psycopg.types.json import Jsonb
 from psycopg_pool import AsyncConnectionPool
 
 from langgraph.checkpoint.postgres import _ainternal
-from langgraph.checkpoint.postgres.base import BasePostgresSaver
+from langgraph.checkpoint.postgres.base import (
+    _DELTA_PAGE_SIZE,
+    BasePostgresSaver,
+    _build_delta_stage1_sql,
+    _build_delta_stage2_sql,
+    _DeltaStage2Row,
+)
 from langgraph.checkpoint.postgres.shallow import AsyncShallowPostgresSaver
 
 Conn = _ainternal.Conn  # For backward compatibility
@@ -261,7 +269,10 @@ class AsyncPostgresSaver(BasePostgresSaver):
         # others are stored in blobs table
         blob_values = {}
         for k, v in checkpoint["channel_values"].items():
-            if v is None or isinstance(v, (str, int, float, bool)):
+            if isinstance(v, _DeltaSnapshot):
+                blob_values[k] = copy["channel_values"].pop(k)
+                copy["channel_values"][k] = True
+            elif v is None or isinstance(v, (str, int, float, bool)):
                 pass
             else:
                 blob_values[k] = copy["channel_values"].pop(k)
@@ -391,6 +402,97 @@ class AsyncPostgresSaver(BasePostgresSaver):
                 async with conn.cursor(binary=True, row_factory=dict_row) as cur:
                     yield cur
 
+    async def aget_delta_channel_history(
+        self, *, config: RunnableConfig, channels: Sequence[str]
+    ) -> Mapping[str, DeltaChannelHistory]:
+        """Fast-path override of `BaseCheckpointSaver.aget_delta_channel_history`.
+
+        See `PostgresSaver.get_delta_channel_history` for design notes; this is
+        the async equivalent with internal stage-1 paging and per-channel
+        UNION ALL stage-2.
+        """
+        if not channels:
+            return {}
+        channels = list(channels)
+        thread_id = config["configurable"]["thread_id"]
+        checkpoint_ns = config["configurable"].get("checkpoint_ns", "")
+        checkpoint_id = get_checkpoint_id(config)
+        if checkpoint_id is None:
+            target = await self.aget_tuple(config)
+            if target is None:
+                return {ch: {"writes": []} for ch in channels}
+            checkpoint_id = target.config["configurable"]["checkpoint_id"]
+
+        stage1_sql = _build_delta_stage1_sql(channels, paged=True)
+        parent_of: dict[str, str | None] = {}
+        ver_by_i_by_cid: list[dict[str, str | None]] = [{} for _ in channels]
+        hs_by_i_by_cid: list[dict[str, bool]] = [{} for _ in channels]
+        chain_by_ch: dict[str, list[str]] = {ch: [] for ch in channels}
+        seed_ver_by_ch: dict[str, str | None] = {ch: None for ch in channels}
+        walk_cursor_by_ch: dict[str, str | None] = {}
+        seeded: set[str] = set()
+        cursor: str | None = None
+
+        async with self._cursor() as cur:
+            while True:
+                stage1_params: list[Any] = []
+                for ch in channels:
+                    stage1_params.extend([ch, ch])
+                stage1_params.extend(
+                    [thread_id, checkpoint_ns, cursor, cursor, _DELTA_PAGE_SIZE]
+                )
+                await cur.execute(stage1_sql, stage1_params)
+                page = await cur.fetchall()
+                if not page:
+                    break
+                oldest = self._ingest_stage1_page(
+                    cast("list[Mapping[str, Any]]", page),
+                    channels,
+                    parent_of,
+                    ver_by_i_by_cid,
+                    hs_by_i_by_cid,
+                )
+                self._try_advance_walks(
+                    checkpoint_id,
+                    channels,
+                    parent_of,
+                    ver_by_i_by_cid,
+                    hs_by_i_by_cid,
+                    chain_by_ch,
+                    seed_ver_by_ch,
+                    walk_cursor_by_ch,
+                    seeded,
+                )
+                if len(seeded) == len(channels) or len(page) < _DELTA_PAGE_SIZE:
+                    break
+                cursor = oldest
+
+        channels_with_chain = [ch for ch in channels if chain_by_ch[ch]]
+        channels_with_seed = [ch for ch in channels if seed_ver_by_ch[ch] is not None]
+        stage2_sql = _build_delta_stage2_sql(
+            channels_with_chain=channels_with_chain,
+            channels_with_seed=channels_with_seed,
+        )
+
+        if stage2_sql:
+            stage2_params: list[Any] = []
+            for ch in channels_with_chain:
+                stage2_params.extend([thread_id, checkpoint_ns, ch, chain_by_ch[ch]])
+            for ch in channels_with_seed:
+                stage2_params.extend([thread_id, checkpoint_ns, ch, seed_ver_by_ch[ch]])
+            async with self._cursor() as cur:
+                await cur.execute(stage2_sql, stage2_params)
+                stage2_rows = await cur.fetchall()
+        else:
+            stage2_rows = []
+
+        return self._build_delta_channels_writes_history(
+            channels=channels,
+            chain_by_ch=chain_by_ch,
+            seed_ver_by_ch=seed_ver_by_ch,
+            stage2_rows=cast("list[_DeltaStage2Row]", stage2_rows),
+        )
+
     async def _load_checkpoint_tuple(self, value: DictRow) -> CheckpointTuple:
         """
         Convert a database row into a CheckpointTuple object.

libs/checkpoint-postgres/langgraph/checkpoint/postgres/base.py

@@ -2,20 +2,26 @@ from __future__ import annotations
 
 import random
 import warnings
-from collections.abc import Sequence
+from collections.abc import Mapping, Sequence
 from importlib.metadata import version as get_version
-from typing import Any, cast
+from typing import Any, TypedDict, cast
 
 from langchain_core.runnables import RunnableConfig
 from langgraph.checkpoint.base import (
     WRITES_IDX_MAP,
     BaseCheckpointSaver,
     ChannelVersions,
+    DeltaChannelHistory,
+    PendingWrite,
     get_checkpoint_id,
 )
 from langgraph.checkpoint.serde.types import TASKS
 from psycopg.types.json import Jsonb
 
+# Page size for stage-1 paged scan in `get_delta_channel_history`. Internal
+# constant — exposing this as a kwarg is left as a follow-up.
+_DELTA_PAGE_SIZE = 1024
+
 MetadataInput = dict[str, Any] | None
 
 try:
@@ -153,6 +159,141 @@ INSERT_CHECKPOINT_WRITES_SQL = """
 """
 
 
+class _DeltaStage2Row(TypedDict, total=False):
+    """One row from `_build_delta_stage2_sql` (a UNION ALL of writes and blobs)."""
+
+    _kind: str  # "w" or "b"
+    checkpoint_id: str | None  # "w" rows only
+    channel: str | None  # set on both "w" and "b" rows
+    type: str | None
+    blob: bytes | None
+    task_id: str | None  # "w" rows only
+    idx: int | None  # "w" rows only
+    version: str | None  # "b" rows only
+
+
+# Multi-channel two-stage DeltaChannel reconstruction.
+#
+# Stage 1 scans checkpoint metadata (no blob bytes) and emits one row per
+# checkpoint with K parallel JSONB key lookups (one column pair per
+# requested delta channel: ver_i / hs_i).  No subqueries, no aggregation.
+# Python walks the parent chain once across all channels.
+#
+# Stage 2 fetches all writes and the seed blobs for ALL channels in a
+# single roundtrip via `channel = ANY(%s)` and chain/seed-version
+# filtering.
+#
+# Empirical comparison vs an alternative "ship full channel_versions /
+# channel_values JSONB and let Python pick" form (1000 checkpoints,
+# 8 total channels in graph, 3 delta channels requested):
+#
+#   Postgres execution:    A=0.24ms vs B=0.38ms   (both negligible)
+#   End-to-end latency:    A=6.83ms vs B=2.28ms   (B is 3.0x faster)
+#   Wire payload:          A=836KB  vs B=330KB    (61% smaller)
+#   Buffer hits:           identical (167 blocks)
+#
+# B (this dynamic-columns design) wins because it avoids JSONB
+# serialization on the wire and JSONB-to-dict deserialization in
+# psycopg.  Even at K=8 (8 delta channels = 16 dynamic columns), B
+# still beats A end-to-end (4.2ms vs 6.8ms).
+
+
+def _build_delta_stage1_sql(channels: Sequence[str], *, paged: bool) -> str:
+    """Build stage 1 SQL with 2K parallel JSONB key lookups.
+
+    For channels=["messages", "files"] (with `paged=True`) the result is::
+
+        SELECT checkpoint_id, parent_checkpoint_id,
+               checkpoint -> 'channel_versions' ->> %s AS ver_0,
+               (checkpoint -> 'channel_values' -> %s) IS NOT NULL AS hs_0,
+               checkpoint -> 'channel_versions' ->> %s AS ver_1,
+               (checkpoint -> 'channel_values' -> %s) IS NOT NULL AS hs_1
+        FROM checkpoints
+        WHERE thread_id = %s AND checkpoint_ns = %s
+          AND (%s::text IS NULL OR checkpoint_id < %s)
+        ORDER BY checkpoint_id DESC
+        LIMIT %s
+
+    Channel names are passed as `%s` parameters (safe from SQL injection).
+    Only the column aliases `ver_i` / `hs_i` are interpolated into the
+    SQL string (i is bounded by len(channels) and uses safe identifiers).
+
+    Caller must extend params with `[ch_0, ch_0, ch_1, ch_1, ...,
+    thread_id, ns, cursor, cursor, page_size]` when `paged=True`.
+
+    When `paged=False`, the WHERE has no cursor predicate and there's no
+    LIMIT/ORDER BY — kept as a non-public helper for tests/diagnostics.
+    """
+    cols = []
+    for i in range(len(channels)):
+        cols.append(
+            f"checkpoint -> 'channel_versions' ->> %s AS ver_{i}, "
+            f"(checkpoint -> 'channel_values' -> %s) IS NOT NULL AS hs_{i}"
+        )
+    sql = (
+        "SELECT checkpoint_id, parent_checkpoint_id, "
+        + ", ".join(cols)
+        + " FROM checkpoints WHERE thread_id = %s AND checkpoint_ns = %s"
+    )
+    if paged:
+        sql += (
+            " AND (%s::text IS NULL OR checkpoint_id < %s)"
+            " ORDER BY checkpoint_id DESC LIMIT %s"
+        )
+    return sql
+
+
+def _build_delta_stage2_sql(
+    *,
+    channels_with_chain: Sequence[str],
+    channels_with_seed: Sequence[str],
+) -> str:
+    """Build stage 2 SQL as a per-channel UNION ALL.
+
+    For each channel with a non-empty chain, emit one branch reading
+    `checkpoint_writes` for that specific channel + chain_cids. For each
+    channel with a seed_version, emit one branch reading `checkpoint_blobs`
+    for that channel + version. This avoids the over-fetch of the prior
+    `channel = ANY(channels) AND checkpoint_id = ANY(union)` form when
+    channels have different chain depths.
+
+    The caller must pass parameters in matching order:
+
+        for ch in channels_with_chain:
+            params += [thread_id, checkpoint_ns, ch, chain_cids[ch]]
+        for ch in channels_with_seed:
+            params += [thread_id, checkpoint_ns, ch, seed_version[ch]]
+
+    Returns an empty SQL string if both channel lists are empty (caller
+    must skip executing in that case).
+    """
+    branches: list[str] = []
+    for _ in channels_with_chain:
+        branches.append(
+            "SELECT 'w'::text AS _kind, "
+            "checkpoint_id, channel, "
+            "type, blob, task_id, idx, NULL::text AS version "
+            "FROM checkpoint_writes "
+            "WHERE thread_id = %s AND checkpoint_ns = %s AND channel = %s "
+            "AND checkpoint_id = ANY(%s)"
+        )
+    for _ in channels_with_seed:
+        branches.append(
+            "SELECT 'b'::text AS _kind, NULL::text AS checkpoint_id, channel, "
+            "type, blob, NULL::text AS task_id, NULL::int AS idx, version "
+            "FROM checkpoint_blobs "
+            "WHERE thread_id = %s AND checkpoint_ns = %s AND channel = %s "
+            "AND version = %s"
+        )
+    return " UNION ALL ".join(branches)
+
+
+# Stage 1 rows are dynamic-shape dicts: {checkpoint_id, parent_checkpoint_id,
+# ver_0, hs_0, ver_1, hs_1, ...}.  Walking is parameterized by the channel
+# list to map indices back to channel names — no static TypedDict here.
+# `dict[str, Any]` is the practical signature.
+
+
 class BasePostgresSaver(BaseCheckpointSaver[str]):
     SELECT_SQL = SELECT_SQL
     SELECT_PENDING_SENDS_SQL = SELECT_PENDING_SENDS_SQL
@@ -195,6 +336,146 @@ class BasePostgresSaver(BaseCheckpointSaver[str]):
             if t.decode() != "empty"
         }
 
+    @staticmethod
+    def _ingest_stage1_page(
+        stage1_rows: Sequence[Mapping[str, Any]],
+        channels: Sequence[str],
+        parent_of: dict[str, str | None],
+        ver_by_i_by_cid: list[dict[str, str | None]],
+        hs_by_i_by_cid: list[dict[str, bool]],
+    ) -> str | None:
+        """Fold one stage-1 page into the running walk-state mappings.
+
+        Returns the oldest checkpoint_id seen on this page (smallest, since
+        pages come back DESC). Caller uses it as the cursor for the next
+        page (`AND checkpoint_id < cursor`).
+        """
+        oldest: str | None = None
+        for r in stage1_rows:
+            cid = cast(str, r["checkpoint_id"])
+            parent_of[cid] = cast("str | None", r["parent_checkpoint_id"])
+            for i in range(len(channels)):
+                ver_by_i_by_cid[i][cid] = cast("str | None", r.get(f"ver_{i}"))
+                hs_by_i_by_cid[i][cid] = bool(r.get(f"hs_{i}"))
+            # Rows are DESC; the last one is the smallest cid in the page.
+            oldest = cid
+        return oldest
+
+    @staticmethod
+    def _try_advance_walks(
+        target_id: str,
+        channels: Sequence[str],
+        parent_of: Mapping[str, str | None],
+        ver_by_i_by_cid: Sequence[Mapping[str, str | None]],
+        hs_by_i_by_cid: Sequence[Mapping[str, bool]],
+        chain_by_ch: dict[str, list[str]],
+        seed_ver_by_ch: dict[str, str | None],
+        walk_cursor_by_ch: dict[str, str | None],
+        seeded: set[str],
+    ) -> None:
+        """Advance each not-yet-seeded channel's walk as far as possible.
+
+        Uses the partial `parent_of` map accumulated so far. A walk stops
+        either because:
+          (a) it found a snapshot for its channel (channel becomes seeded),
+          (b) it reached a real root (parent_of[cid] is None — fully
+              materialized at this point), or
+          (c) the next ancestor cid isn't in `parent_of` yet (waiting for
+              a later page; the cursor stays put).
+
+        Mutates `chain_by_ch`, `seed_ver_by_ch`, `walk_cursor_by_ch`, and
+        `seeded` in place.
+        """
+        for i, ch in enumerate(channels):
+            if ch in seeded:
+                continue
+            # First-time entry: cursor starts at the target's parent.
+            if ch not in walk_cursor_by_ch:
+                walk_cursor_by_ch[ch] = parent_of.get(target_id)
+            cur_cid = walk_cursor_by_ch[ch]
+            ch_chain = chain_by_ch[ch]
+            hs_i = hs_by_i_by_cid[i]
+            ver_i = ver_by_i_by_cid[i]
+            while cur_cid is not None:
+                if cur_cid not in parent_of:
+                    # Need more pages to continue this walk.
+                    break
+                ch_chain.append(cur_cid)
+                if hs_i.get(cur_cid, False):
+                    seed_ver_by_ch[ch] = ver_i.get(cur_cid)
+                    seeded.add(ch)
+                    cur_cid = None
+                    break
+                cur_cid = parent_of[cur_cid]
+            walk_cursor_by_ch[ch] = cur_cid
+
+    def _build_delta_channels_writes_history(
+        self,
+        *,
+        channels: Sequence[str],
+        chain_by_ch: Mapping[str, list[str]],
+        seed_ver_by_ch: Mapping[str, str | None],
+        stage2_rows: Sequence[_DeltaStage2Row],
+    ) -> dict[str, DeltaChannelHistory]:
+        """Demux stage 2 rows per channel; produce per-channel histories.
+
+        stage2_rows carry `channel` on every row. We build per-channel
+        `writes_by_cid` and per-channel `seed_blob` dicts, then assemble
+        a `DeltaChannelHistory` per requested channel. The `seed` key is omitted
+        when the walk reached root with no snapshot found, or when the
+        seed blob is sentinel "empty" — in both cases the consumer treats
+        absence as "start empty".
+        """
+        # writes_by_ch_by_cid[channel][cid] = list of (type, blob, task_id, idx)
+        writes_by_ch_by_cid: dict[str, dict[str, list[tuple[str, bytes, str, int]]]] = {
+            ch: {} for ch in channels
+        }
+        # seed_blob_by_ver[(channel, version)] = (type, blob)
+        seed_blob_by_ver: dict[tuple[str, str], tuple[str, bytes]] = {}
+
+        for r in stage2_rows:
+            ch = cast(str, r["channel"])
+            kind = r["_kind"]
+            if kind == "w":
+                cid = cast(str, r["checkpoint_id"])
+                writes_by_ch_by_cid.setdefault(ch, {}).setdefault(cid, []).append(
+                    cast(
+                        "tuple[str, bytes, str, int]",
+                        (r["type"], r["blob"], r["task_id"], r["idx"]),
+                    )
+                )
+            else:  # kind == "b"
+                ver = cast(str, r["version"])
+                seed_blob_by_ver[(ch, ver)] = cast(
+                    "tuple[str, bytes]", (r["type"], r["blob"])
+                )
+
+        # Sort writes per (channel, cid) newest-first by (task_id, idx)
+        for cid_map in writes_by_ch_by_cid.values():
+            for ws in cid_map.values():
+                ws.sort(key=lambda w: (w[2], w[3]), reverse=True)
+
+        result: dict[str, DeltaChannelHistory] = {}
+        for ch in channels:
+            chain_cids = chain_by_ch.get(ch, [])
+            seed_version = seed_ver_by_ch.get(ch)
+
+            collected: list[PendingWrite] = []
+            cid_writes = writes_by_ch_by_cid.get(ch, {})
+            for cid in chain_cids:
+                for type_tag, write_blob, task_id, _idx in cid_writes.get(cid, []):
+                    val = self.serde.loads_typed((type_tag, write_blob))
+                    collected.append((task_id, ch, val))
+            collected.reverse()
+
+            entry: DeltaChannelHistory = {"writes": collected}
+            if seed_version is not None:
+                blob = seed_blob_by_ver.get((ch, seed_version))
+                if blob is not None and blob[0] != "empty":
+                    entry["seed"] = self.serde.loads_typed(blob)
+            result[ch] = entry
+        return result
+
     def _dump_blobs(
         self,
         thread_id: str,

libs/checkpoint-postgres/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "langgraph-checkpoint-postgres"
-version = "3.0.5"
+version = "3.1.0a4"
 description = "Library with a Postgres implementation of LangGraph checkpoint saver."
 authors = []
 requires-python = ">=3.10"
@@ -12,7 +12,7 @@ readme = "README.md"
 license = "MIT"
 license-files = ['LICENSE']
 dependencies = [
-  "langgraph-checkpoint>=2.1.2,<5.0.0",
+  "langgraph-checkpoint>=4.1.0a4,<5.0.0",
   "orjson>=3.11.5",
   "psycopg>=3.2.0",
   "psycopg-pool>=3.2.0",

libs/checkpoint-postgres/tests/test_async.py

@@ -361,9 +361,9 @@ async def test_get_checkpoint_no_channel_values(
 
         load_checkpoint_tuple = saver._load_checkpoint_tuple
 
-        def patched_load_checkpoint_tuple(value):
+        async def patched_load_checkpoint_tuple(value):
             value["checkpoint"].pop("channel_values", None)
-            return load_checkpoint_tuple(value)
+            return await load_checkpoint_tuple(value)
 
         monkeypatch.setattr(
             saver, "_load_checkpoint_tuple", patched_load_checkpoint_tuple
@@ -371,3 +371,47 @@ async def test_get_checkpoint_no_channel_values(
 
         checkpoint = await saver.aget_tuple(config)
         assert checkpoint.checkpoint["channel_values"] == {}
+
+
+@pytest.mark.parametrize("saver_name", ["base", "pool", "pipe"])
+async def test_delta_channel_chain_reconstruction(saver_name: str) -> None:
+    """AsyncPostgresSaver reconstructs DeltaChannel chain via point-lookup traversal."""
+    pytest.importorskip(
+        "langgraph.channels.delta", reason="langgraph core not installed"
+    )
+
+    from typing import Annotated
+
+    from langchain_core.messages import AIMessage, HumanMessage
+    from langgraph.channels.delta import DeltaChannel
+    from langgraph.graph import START, StateGraph
+    from langgraph.graph.message import _messages_delta_reducer
+    from typing_extensions import TypedDict
+
+    class State(TypedDict):
+        messages: Annotated[list, DeltaChannel(_messages_delta_reducer)]
+
+    def respond(state: State) -> dict:
+        n = len(state["messages"])
+        return {"messages": [AIMessage(content=f"reply-{n}", id=f"ai-{n}")]}
+
+    builder = StateGraph(State)
+    builder.add_node("respond", respond)
+    builder.add_edge(START, "respond")
+
+    async with _saver(saver_name) as saver:
+        graph = builder.compile(checkpointer=saver)
+        config = {"configurable": {"thread_id": "diff-channel-test-1"}}
+
+        await graph.ainvoke({"messages": [HumanMessage(content="hi", id="h1")]}, config)
+        await graph.ainvoke(
+            {"messages": [HumanMessage(content="there", id="h2")]}, config
+        )
+
+        state = await graph.aget_state(config)
+        msgs = state.values["messages"]
+        assert len(msgs) == 4, f"expected 4, got {len(msgs)}: {msgs}"
+        assert msgs[0].content == "hi"
+        assert msgs[1].content == "reply-1"
+        assert msgs[2].content == "there"
+        assert msgs[3].content == "reply-3"

libs/checkpoint-postgres/uv.lock

@@ -1,6 +1,10 @@
 version = 1
 revision = 3
 requires-python = ">=3.10"
+resolution-markers = [
+    "python_full_version >= '3.15'",
+    "python_full_version < '3.15'",
+]
 
 [[package]]
 name = "annotated-types"
@@ -240,10 +244,11 @@ wheels = [
 
 [[package]]
 name = "langchain-core"
-version = "1.2.28"
+version = "1.3.2"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "jsonpatch" },
+    { name = "langchain-protocol" },
     { name = "langsmith" },
     { name = "packaging" },
     { name = "pydantic" },
@@ -252,14 +257,26 @@ dependencies = [
     { name = "typing-extensions" },
     { name = "uuid-utils" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/f8/a4/317a1a3ac1df33a64adb3670bf88bbe3b3d5baa274db6863a979db472897/langchain_core-1.2.28.tar.gz", hash = "sha256:271a3d8bd618f795fdeba112b0753980457fc90537c46a0c11998516a74dc2cb", size = 846119, upload-time = "2026-04-08T18:19:34.867Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/a8/03/7219502e8ca728d65eb44d7a3eb60239230742a70dbfc9241b9bfd61c4ab/langchain_core-1.3.2.tar.gz", hash = "sha256:fd7a50b2f28ba561fd9d7f5d2760bc9e06cf00cdf820a3ccafe88a94ffa8d5b7", size = 911813, upload-time = "2026-04-24T15:49:23.699Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/a8/92/32f785f077c7e898da97064f113c73fbd9ad55d1e2169cf3a391b183dedb/langchain_core-1.2.28-py3-none-any.whl", hash = "sha256:80764232581eaf8057bcefa71dbf8adc1f6a28d257ebd8b95ba9b8b452e8c6ac", size = 508727, upload-time = "2026-04-08T18:19:32.823Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/d5/8fa4431007cbb7cfed7590f4d6a5dea3ad724f4174d248f6642ef5ce7d05/langchain_core-1.3.2-py3-none-any.whl", hash = "sha256:d44a66127f9f8db735bdfd0ab9661bccb47a97113cfd3f2d89c74864422b7274", size = 542390, upload-time = "2026-04-24T15:49:21.991Z" },
+]
+
+[[package]]
+name = "langchain-protocol"
+version = "0.0.15"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/4f/24/9777489d6fbbee64af0c8f96d4f840239c408cf694f3394672807dafc490/langchain_protocol-0.0.15.tar.gz", hash = "sha256:9ab2d11ee73944754f10e037e717098d3a6796f0e58afa9cadda6154e7655ade", size = 5862, upload-time = "2026-05-01T22:30:04.748Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/1d/7a/9c97a7b9cbe4c5dc6a44cdb1545450c28f0c8ce89b9c1f0ee7fbad896263/langchain_protocol-0.0.15-py3-none-any.whl", hash = "sha256:461eb794358f83d5e42635a5797799ffec7b4702314e34edf73ac21e75d3ef79", size = 6982, upload-time = "2026-05-01T22:30:03.877Z" },
 ]
 
 [[package]]
 name = "langgraph-checkpoint"
-version = "4.0.3"
+version = "4.1.0a4"
 source = { editable = "../checkpoint" }
 dependencies = [
     { name = "langchain-core" },
@@ -307,7 +324,7 @@ test = [
 
 [[package]]
 name = "langgraph-checkpoint-postgres"
-version = "3.0.5"
+version = "3.1.0a4"
 source = { editable = "." }
 dependencies = [
     { name = "langgraph-checkpoint" },
@@ -487,7 +504,7 @@ wheels = [
 
 [[package]]
 name = "mypy"
-version = "1.20.0"
+version = "1.20.2"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "librt", marker = "platform_python_implementation != 'PyPy'" },
@@ -496,51 +513,51 @@ dependencies = [
     { name = "tomli", marker = "python_full_version < '3.11'" },
     { name = "typing-extensions" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/f8/5c/b0089fe7fef0a994ae5ee07029ced0526082c6cfaaa4c10d40a10e33b097/mypy-1.20.0.tar.gz", hash = "sha256:eb96c84efcc33f0b5e0e04beacf00129dd963b67226b01c00b9dfc8affb464c3", size = 3815028, upload-time = "2026-03-31T16:55:14.959Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/04/af/e3d4b3e9ec91a0ff9aabfdb38692952acf49bbb899c2e4c29acb3a6da3ae/mypy-1.20.2.tar.gz", hash = "sha256:e8222c26daaafd9e8626dec58ae36029f82585890589576f769a650dd20fd665", size = 3817349, upload-time = "2026-04-21T17:12:28.473Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/4d/a2/a965c8c3fcd4fa8b84ba0d46606181b0d0a1d50f274c67877f3e9ed4882c/mypy-1.20.0-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:d99f515f95fd03a90875fdb2cca12ff074aa04490db4d190905851bdf8a549a8", size = 14430138, upload-time = "2026-03-31T16:52:37.843Z" },
-    { url = "https://files.pythonhosted.org/packages/53/6e/043477501deeb8eabbab7f1a2f6cac62cfb631806dc1d6862a04a7f5011b/mypy-1.20.0-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:bd0212976dc57a5bfeede7c219e7cd66568a32c05c9129686dd487c059c1b88a", size = 13311282, upload-time = "2026-03-31T16:55:11.021Z" },
-    { url = "https://files.pythonhosted.org/packages/65/aa/bd89b247b83128197a214f29f0632ff3c14f54d4cd70d144d157bd7d7d6e/mypy-1.20.0-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f8426d4d75d68714abc17a4292d922f6ba2cfb984b72c2278c437f6dae797865", size = 13750889, upload-time = "2026-03-31T16:52:02.909Z" },
-    { url = "https://files.pythonhosted.org/packages/fa/9d/2860be7355c45247ccc0be1501c91176318964c2a137bd4743f58ce6200e/mypy-1.20.0-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:02cca0761c75b42a20a2757ae58713276605eb29a08dd8a6e092aa347c4115ca", size = 14619788, upload-time = "2026-03-31T16:50:48.928Z" },
-    { url = "https://files.pythonhosted.org/packages/75/7f/3ef3e360c91f3de120f205c8ce405e9caf9fc52ef14b65d37073e322c114/mypy-1.20.0-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:b3a49064504be59e59da664c5e149edc1f26c67c4f8e8456f6ba6aba55033018", size = 14918849, upload-time = "2026-03-31T16:51:10.478Z" },
-    { url = "https://files.pythonhosted.org/packages/ae/72/af970dfe167ef788df7c5e6109d2ed0229f164432ce828bc9741a4250e64/mypy-1.20.0-cp310-cp310-win_amd64.whl", hash = "sha256:ebea00201737ad4391142808ed16e875add5c17f676e0912b387739f84991e13", size = 10822007, upload-time = "2026-03-31T16:50:25.268Z" },
-    { url = "https://files.pythonhosted.org/packages/93/94/ba9065c2ebe5421619aff684b793d953e438a8bfe31a320dd6d1e0706e81/mypy-1.20.0-cp310-cp310-win_arm64.whl", hash = "sha256:e80cf77847d0d3e6e3111b7b25db32a7f8762fd4b9a3a72ce53fe16a2863b281", size = 9756158, upload-time = "2026-03-31T16:48:36.213Z" },
-    { url = "https://files.pythonhosted.org/packages/6e/1c/74cb1d9993236910286865679d1c616b136b2eae468493aa939431eda410/mypy-1.20.0-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:4525e7010b1b38334516181c5b81e16180b8e149e6684cee5a727c78186b4e3b", size = 14343972, upload-time = "2026-03-31T16:49:04.887Z" },
-    { url = "https://files.pythonhosted.org/packages/d5/0d/01399515eca280386e308cf57901e68d3a52af18691941b773b3380c1df8/mypy-1.20.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:a17c5d0bdcca61ce24a35beb828a2d0d323d3fcf387d7512206888c900193367", size = 13225007, upload-time = "2026-03-31T16:50:08.151Z" },
-    { url = "https://files.pythonhosted.org/packages/56/ac/b4ba5094fb2d7fe9d2037cd8d18bbe02bcf68fd22ab9ff013f55e57ba095/mypy-1.20.0-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f75ff57defcd0f1d6e006d721ccdec6c88d4f6a7816eb92f1c4890d979d9ee62", size = 13663752, upload-time = "2026-03-31T16:49:26.064Z" },
-    { url = "https://files.pythonhosted.org/packages/db/a7/460678d3cf7da252d2288dad0c602294b6ec22a91932ec368cc11e44bb6e/mypy-1.20.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:b503ab55a836136b619b5fc21c8803d810c5b87551af8600b72eecafb0059cb0", size = 14532265, upload-time = "2026-03-31T16:53:55.077Z" },
-    { url = "https://files.pythonhosted.org/packages/a3/3e/051cca8166cf0438ae3ea80e0e7c030d7a8ab98dffc93f80a1aa3f23c1a2/mypy-1.20.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:1973868d2adbb4584a3835780b27436f06d1dc606af5be09f187aaa25be1070f", size = 14768476, upload-time = "2026-03-31T16:50:34.587Z" },
-    { url = "https://files.pythonhosted.org/packages/be/66/8e02ec184f852ed5c4abb805583305db475930854e09964b55e107cdcbc4/mypy-1.20.0-cp311-cp311-win_amd64.whl", hash = "sha256:2fcedb16d456106e545b2bfd7ef9d24e70b38ec252d2a629823a4d07ebcdb69e", size = 10818226, upload-time = "2026-03-31T16:53:15.624Z" },
-    { url = "https://files.pythonhosted.org/packages/13/4b/383ad1924b28f41e4879a74151e7a5451123330d45652da359f9183bcd45/mypy-1.20.0-cp311-cp311-win_arm64.whl", hash = "sha256:379edf079ce44ac8d2805bcf9b3dd7340d4f97aad3a5e0ebabbf9d125b84b442", size = 9750091, upload-time = "2026-03-31T16:54:12.162Z" },
-    { url = "https://files.pythonhosted.org/packages/be/dd/3afa29b58c2e57c79116ed55d700721c3c3b15955e2b6251dd165d377c0e/mypy-1.20.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:002b613ae19f4ac7d18b7e168ffe1cb9013b37c57f7411984abbd3b817b0a214", size = 14509525, upload-time = "2026-03-31T16:55:01.824Z" },
-    { url = "https://files.pythonhosted.org/packages/54/eb/227b516ab8cad9f2a13c5e7a98d28cd6aa75e9c83e82776ae6c1c4c046c7/mypy-1.20.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:a9336b5e6712f4adaf5afc3203a99a40b379049104349d747eb3e5a3aa23ac2e", size = 13326469, upload-time = "2026-03-31T16:51:41.23Z" },
-    { url = "https://files.pythonhosted.org/packages/57/d4/1ddb799860c1b5ac6117ec307b965f65deeb47044395ff01ab793248a591/mypy-1.20.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f13b3e41bce9d257eded794c0f12878af3129d80aacd8a3ee0dee51f3a978651", size = 13705953, upload-time = "2026-03-31T16:48:55.69Z" },
-    { url = "https://files.pythonhosted.org/packages/c5/b7/54a720f565a87b893182a2a393370289ae7149e4715859e10e1c05e49154/mypy-1.20.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9804c3ad27f78e54e58b32e7cb532d128b43dbfb9f3f9f06262b821a0f6bd3f5", size = 14710363, upload-time = "2026-03-31T16:53:26.948Z" },
-    { url = "https://files.pythonhosted.org/packages/b2/2a/74810274848d061f8a8ea4ac23aaad43bd3d8c1882457999c2e568341c57/mypy-1.20.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:697f102c5c1d526bdd761a69f17c6070f9892eebcb94b1a5963d679288c09e78", size = 14947005, upload-time = "2026-03-31T16:50:17.591Z" },
-    { url = "https://files.pythonhosted.org/packages/77/91/21b8ba75f958bcda75690951ce6fa6b7138b03471618959529d74b8544e2/mypy-1.20.0-cp312-cp312-win_amd64.whl", hash = "sha256:0ecd63f75fdd30327e4ad8b5704bd6d91fc6c1b2e029f8ee14705e1207212489", size = 10880616, upload-time = "2026-03-31T16:52:19.986Z" },
-    { url = "https://files.pythonhosted.org/packages/8a/15/3d8198ef97c1ca03aea010cce4f1d4f3bc5d9849e8c0140111ca2ead9fdd/mypy-1.20.0-cp312-cp312-win_arm64.whl", hash = "sha256:f194db59657c58593a3c47c6dfd7bad4ef4ac12dbc94d01b3a95521f78177e33", size = 9813091, upload-time = "2026-03-31T16:53:44.385Z" },
-    { url = "https://files.pythonhosted.org/packages/d6/a7/f64ea7bd592fa431cb597418b6dec4a47f7d0c36325fec7ac67bc8402b94/mypy-1.20.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:b20c8b0fd5877abdf402e79a3af987053de07e6fb208c18df6659f708b535134", size = 14485344, upload-time = "2026-03-31T16:49:16.78Z" },
-    { url = "https://files.pythonhosted.org/packages/bb/72/8927d84cfc90c6abea6e96663576e2e417589347eb538749a464c4c218a0/mypy-1.20.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:367e5c993ba34d5054d11937d0485ad6dfc60ba760fa326c01090fc256adf15c", size = 13327400, upload-time = "2026-03-31T16:53:08.02Z" },
-    { url = "https://files.pythonhosted.org/packages/ab/4a/11ab99f9afa41aa350178d24a7d2da17043228ea10f6456523f64b5a6cf6/mypy-1.20.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f799d9db89fc00446f03281f84a221e50018fc40113a3ba9864b132895619ebe", size = 13706384, upload-time = "2026-03-31T16:52:28.577Z" },
-    { url = "https://files.pythonhosted.org/packages/42/79/694ca73979cfb3535ebfe78733844cd5aff2e63304f59bf90585110d975a/mypy-1.20.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:555658c611099455b2da507582ea20d2043dfdfe7f5ad0add472b1c6238b433f", size = 14700378, upload-time = "2026-03-31T16:48:45.527Z" },
-    { url = "https://files.pythonhosted.org/packages/84/24/a022ccab3a46e3d2cdf2e0e260648633640eb396c7e75d5a42818a8d3971/mypy-1.20.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:efe8d70949c3023698c3fca1e94527e7e790a361ab8116f90d11221421cd8726", size = 14932170, upload-time = "2026-03-31T16:49:36.038Z" },
-    { url = "https://files.pythonhosted.org/packages/d8/9b/549228d88f574d04117e736f55958bd4908f980f9f5700a07aeb85df005b/mypy-1.20.0-cp313-cp313-win_amd64.whl", hash = "sha256:f49590891d2c2f8a9de15614e32e459a794bcba84693c2394291a2038bbaaa69", size = 10888526, upload-time = "2026-03-31T16:50:59.827Z" },
-    { url = "https://files.pythonhosted.org/packages/91/17/15095c0e54a8bc04d22d4ff06b2139d5f142c2e87520b4e39010c4862771/mypy-1.20.0-cp313-cp313-win_arm64.whl", hash = "sha256:76a70bf840495729be47510856b978f1b0ec7d08f257ca38c9d932720bf6b43e", size = 9816456, upload-time = "2026-03-31T16:49:59.537Z" },
-    { url = "https://files.pythonhosted.org/packages/4e/0e/6ca4a84cbed9e62384bc0b2974c90395ece5ed672393e553996501625fc5/mypy-1.20.0-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:0f42dfaab7ec1baff3b383ad7af562ab0de573c5f6edb44b2dab016082b89948", size = 14483331, upload-time = "2026-03-31T16:52:57.999Z" },
-    { url = "https://files.pythonhosted.org/packages/7d/c5/5fe9d8a729dd9605064691816243ae6c49fde0bd28f6e5e17f6a24203c43/mypy-1.20.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:31b5dbb55293c1bd27c0fc813a0d2bb5ceef9d65ac5afa2e58f829dab7921fd5", size = 13342047, upload-time = "2026-03-31T16:54:21.555Z" },
-    { url = "https://files.pythonhosted.org/packages/4c/33/e18bcfa338ca4e6b2771c85d4c5203e627d0c69d9de5c1a2cf2ba13320ba/mypy-1.20.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:49d11c6f573a5a08f77fad13faff2139f6d0730ebed2cfa9b3d2702671dd7188", size = 13719585, upload-time = "2026-03-31T16:51:53.89Z" },
-    { url = "https://files.pythonhosted.org/packages/6b/8d/93491ff7b79419edc7eabf95cb3b3f7490e2e574b2855c7c7e7394ff933f/mypy-1.20.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:7d3243c406773185144527f83be0e0aefc7bf4601b0b2b956665608bf7c98a83", size = 14685075, upload-time = "2026-03-31T16:54:04.464Z" },
-    { url = "https://files.pythonhosted.org/packages/b5/9d/d924b38a4923f8d164bf2b4ec98bf13beaf6e10a5348b4b137eadae40a6e/mypy-1.20.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:a79c1eba7ac4209f2d850f0edd0a2f8bba88cbfdfefe6fb76a19e9d4fe5e71a2", size = 14919141, upload-time = "2026-03-31T16:54:51.785Z" },
-    { url = "https://files.pythonhosted.org/packages/59/98/1da9977016678c0b99d43afe52ed00bb3c1a0c4c995d3e6acca1a6ebb9b4/mypy-1.20.0-cp314-cp314-win_amd64.whl", hash = "sha256:00e047c74d3ec6e71a2eb88e9ea551a2edb90c21f993aefa9e0d2a898e0bb732", size = 11050925, upload-time = "2026-03-31T16:51:30.758Z" },
-    { url = "https://files.pythonhosted.org/packages/5e/e3/ba0b7a3143e49a9c4f5967dde6ea4bf8e0b10ecbbcca69af84027160ee89/mypy-1.20.0-cp314-cp314-win_arm64.whl", hash = "sha256:931a7630bba591593dcf6e97224a21ff80fb357e7982628d25e3c618e7f598ef", size = 10001089, upload-time = "2026-03-31T16:49:43.632Z" },
-    { url = "https://files.pythonhosted.org/packages/12/28/e617e67b3be9d213cda7277913269c874eb26472489f95d09d89765ce2d8/mypy-1.20.0-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:26c8b52627b6552f47ff11adb4e1509605f094e29815323e487fc0053ebe93d1", size = 15534710, upload-time = "2026-03-31T16:52:12.506Z" },
-    { url = "https://files.pythonhosted.org/packages/6e/0c/3b5f2d3e45dc7169b811adce8451679d9430399d03b168f9b0489f43adaa/mypy-1.20.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:39362cdb4ba5f916e7976fccecaab1ba3a83e35f60fa68b64e9a70e221bb2436", size = 14393013, upload-time = "2026-03-31T16:54:41.186Z" },
-    { url = "https://files.pythonhosted.org/packages/a3/49/edc8b0aa145cc09c1c74f7ce2858eead9329931dcbbb26e2ad40906daa4e/mypy-1.20.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:34506397dbf40c15dc567635d18a21d33827e9ab29014fb83d292a8f4f8953b6", size = 15047240, upload-time = "2026-03-31T16:54:31.955Z" },
-    { url = "https://files.pythonhosted.org/packages/42/37/a946bb416e37a57fa752b3100fd5ede0e28df94f92366d1716555d47c454/mypy-1.20.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:555493c44a4f5a1b58d611a43333e71a9981c6dbe26270377b6f8174126a0526", size = 15858565, upload-time = "2026-03-31T16:53:36.997Z" },
-    { url = "https://files.pythonhosted.org/packages/2f/99/7690b5b5b552db1bd4ff362e4c0eb3107b98d680835e65823fbe888c8b78/mypy-1.20.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:2721f0ce49cb74a38f00c50da67cb7d36317b5eda38877a49614dc018e91c787", size = 16087874, upload-time = "2026-03-31T16:52:48.313Z" },
-    { url = "https://files.pythonhosted.org/packages/aa/76/53e893a498138066acd28192b77495c9357e5a58cc4be753182846b43315/mypy-1.20.0-cp314-cp314t-win_amd64.whl", hash = "sha256:47781555a7aa5fedcc2d16bcd72e0dc83eb272c10dd657f9fb3f9cc08e2e6abb", size = 12572380, upload-time = "2026-03-31T16:49:52.454Z" },
-    { url = "https://files.pythonhosted.org/packages/76/9c/6dbdae21f01b7aacddc2c0bbf3c5557aa547827fdf271770fe1e521e7093/mypy-1.20.0-cp314-cp314t-win_arm64.whl", hash = "sha256:c70380fe5d64010f79fb863b9081c7004dd65225d2277333c219d93a10dad4dd", size = 10381174, upload-time = "2026-03-31T16:51:20.179Z" },
-    { url = "https://files.pythonhosted.org/packages/21/66/4d734961ce167f0fd8380769b3b7c06dbdd6ff54c2190f3f2ecd22528158/mypy-1.20.0-py3-none-any.whl", hash = "sha256:a6e0641147cbfa7e4e94efdb95c2dab1aff8cfc159ded13e07f308ddccc8c48e", size = 2636365, upload-time = "2026-03-31T16:51:44.911Z" },
+    { url = "https://files.pythonhosted.org/packages/76/97/ce2502df2cecf2ef997b6c6527c4a223b92feb9e7b790cdc8dcd683f3a8a/mypy-1.20.2-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:cf5a4db6dca263010e2c7bff081c89383c72d187ba2cf4c44759aac970e2f0c4", size = 14457059, upload-time = "2026-04-21T17:06:14.935Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/34/417ee60b822cc80c0f3dc9f495ad7fd8dbb8d8b2cf4baf22d4046d25d01d/mypy-1.20.2-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:7b0e817b518bff7facd7f85ea05b643ad8bdcce684cf29784987b0a7c8e1f997", size = 13346816, upload-time = "2026-04-21T17:10:41.433Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/85/e20951978702df58379d0bcc2e8f7ccdca4e78cd7dc66dd3ddbf9b29d517/mypy-1.20.2-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:97d7b9a485b40f8ca425460e89bf1da2814625b2da627c0dcc6aa46c92631d14", size = 13772593, upload-time = "2026-04-21T17:08:11.24Z" },
+    { url = "https://files.pythonhosted.org/packages/63/a5/5441a13259ec516c56fd5de0fd96a69a9590ae6c5e5d3e5174aa84b97973/mypy-1.20.2-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:1e1c12f6d2db3d78b909b5f77513c11eb7f2dd2782b96a3ab6dffc7d44575c99", size = 14656635, upload-time = "2026-04-21T17:09:54.042Z" },
+    { url = "https://files.pythonhosted.org/packages/3b/51/b89c69157c5e1f19fd125a65d991166a26906e7902f026f00feebbcfa2b9/mypy-1.20.2-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:89dce27e142d25ffbc154c1819383b69f2e9234dc4ed4766f42e0e8cb264ab5c", size = 14943278, upload-time = "2026-04-21T17:09:15.599Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/44/6b0eeecfe96d7cce1d71c66b8e03cb304aa70ec11f1955dc1d6b46aca3c3/mypy-1.20.2-cp310-cp310-win_amd64.whl", hash = "sha256:f376e37f9bf2a946872fc5fd1199c99310748e3c26c7a26683f13f8bdb756cbd", size = 10851915, upload-time = "2026-04-21T17:06:03.5Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/36/6593dc88545d75fb96416184be5392da5e2a8e8c2802a8597913e16ae25c/mypy-1.20.2-cp310-cp310-win_arm64.whl", hash = "sha256:6e2b469efd811707bc530fd1effef0f5d6eebcb7fe376affae69025da4b979a2", size = 9786676, upload-time = "2026-04-21T17:07:02.035Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/4d/9ebeae211caccbdaddde7ed5e31dfcf57faac66be9b11deb1dc6526c8078/mypy-1.20.2-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:4077797a273e56e8843d001e9dfe4ba10e33323d6ade647ff260e5cd97d9758c", size = 14371307, upload-time = "2026-04-21T17:08:56.442Z" },
+    { url = "https://files.pythonhosted.org/packages/95/d7/93473d34b61f04fac1aecc01368485c89c5c4af7a4b9a0cab5d77d04b63f/mypy-1.20.2-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:cdecf62abcc4292500d7858aeae87a1f8f1150f4c4dd08fb0b336ee79b2a6df3", size = 13258917, upload-time = "2026-04-21T17:05:50.978Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/30/3dd903e8bafb7b5f7bf87fcd58f8382086dea2aa19f0a7b357f21f63071b/mypy-1.20.2-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c566c3a88b6ece59b3d70f65bedef17304f48eb52ff040a6a18214e1917b3254", size = 13700516, upload-time = "2026-04-21T17:11:33.161Z" },
+    { url = "https://files.pythonhosted.org/packages/07/05/c61a140aba4c729ac7bc99ae26fc627c78a6e08f5b9dd319244ea71a3d7e/mypy-1.20.2-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0deb80d062b2479f2c87ae568f89845afc71d11bc41b04179e58165fd9f31e98", size = 14562889, upload-time = "2026-04-21T17:05:27.674Z" },
+    { url = "https://files.pythonhosted.org/packages/fd/87/da78243742ffa8a36d98c3010f0d829f93d5da4e6786f1a1a6f2ad616502/mypy-1.20.2-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:bba9ad231e92a3e424b3e56b65aa17704993425bba97e302c832f9466bb85bac", size = 14803844, upload-time = "2026-04-21T17:10:06.2Z" },
+    { url = "https://files.pythonhosted.org/packages/37/52/10a1ddf91b40f843943a3c6db51e2df59c9e237f29d355e95eaab427461f/mypy-1.20.2-cp311-cp311-win_amd64.whl", hash = "sha256:baf593f2765fa3a6b1ef95807dbaa3d25b594f6a52adcc506a6b9cb115e1be67", size = 10846300, upload-time = "2026-04-21T17:12:23.886Z" },
+    { url = "https://files.pythonhosted.org/packages/20/02/f9a4415b664c53bd34d6709be59da303abcae986dc4ac847b402edb6fa1e/mypy-1.20.2-cp311-cp311-win_arm64.whl", hash = "sha256:20175a1c0f49863946ec20b7f63255768058ac4f07d2b9ded6a6b46cfb5a9100", size = 9779498, upload-time = "2026-04-21T17:09:23.695Z" },
+    { url = "https://files.pythonhosted.org/packages/71/4e/7560e4528db9e9b147e4c0f22660466bf30a0a1fe3d63d1b9d3b0fd354ee/mypy-1.20.2-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:4dbfcf869f6b0517f70cf0030ba6ea1d6645e132337a7d5204a18d8d5636c02b", size = 14539393, upload-time = "2026-04-21T17:07:12.52Z" },
+    { url = "https://files.pythonhosted.org/packages/32/d9/34a5efed8124f5a9234f55ac6a4ced4201e2c5b81e1109c49ad23190ec8c/mypy-1.20.2-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:4b6481b228d072315b053210b01ac320e1be243dc17f9e5887ef167f23f5fae4", size = 13361642, upload-time = "2026-04-21T17:06:53.742Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/14/eb377acf78c03c92d566a1510cda8137348215b5335085ef662ab82ecd3a/mypy-1.20.2-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:34397cdced6b90b836e38182076049fdb41424322e0b0728c946b0939ebdf9f6", size = 13740347, upload-time = "2026-04-21T17:12:04.73Z" },
+    { url = "https://files.pythonhosted.org/packages/b9/94/7e4634a32b641aa1c112422eed1bbece61ee16205f674190e8b536f884de/mypy-1.20.2-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:a5da6976f20cae27059ea8d0c86e7cef3de720e04c4bb9ee18e3690fdb792066", size = 14734042, upload-time = "2026-04-21T17:07:43.16Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/f3/f7e62395cb7f434541b4491a01149a4439e28ace4c0c632bbf5431e92d1f/mypy-1.20.2-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:56908d7e08318d39f85b1f0c6cfd47b0cac1a130da677630dac0de3e0623e102", size = 14964958, upload-time = "2026-04-21T17:11:00.665Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/0d/47e3c3a0ec2a876e35aeac365df3cac7776c36bbd4ed18cc521e1b9d255b/mypy-1.20.2-cp312-cp312-win_amd64.whl", hash = "sha256:d52ad8d78522da1d308789df651ee5379088e77c76cb1994858d40a426b343b9", size = 10911340, upload-time = "2026-04-21T17:10:49.179Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/b2/6c852d72e0ea8b01f49da817fb52539993cde327e7d010e0103dc12d0dac/mypy-1.20.2-cp312-cp312-win_arm64.whl", hash = "sha256:785b08db19c9f214dc37d65f7c165d19a30fcecb48abfa30f31b01b5acaabb58", size = 9833947, upload-time = "2026-04-21T17:09:05.267Z" },
+    { url = "https://files.pythonhosted.org/packages/5b/c4/b93812d3a192c9bcf5df405bd2f30277cd0e48106a14d1023c7f6ed6e39b/mypy-1.20.2-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:edfbfca868cdd6bd8d974a60f8a3682f5565d3f5c99b327640cedd24c4264026", size = 14524670, upload-time = "2026-04-21T17:10:30.737Z" },
+    { url = "https://files.pythonhosted.org/packages/f3/47/42c122501bff18eaf1e8f457f5c017933452d8acdc52918a9f59f6812955/mypy-1.20.2-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:e2877a02380adfcdbc69071a0f74d6e9dbbf593c0dc9d174e1f223ffd5281943", size = 13336218, upload-time = "2026-04-21T17:08:44.069Z" },
+    { url = "https://files.pythonhosted.org/packages/92/8f/75bbc92f41725fbd585fb17b440b1119b576105df1013622983e18640a93/mypy-1.20.2-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:7488448de6007cd5177c6cea0517ac33b4c0f5ee9b5e9f2be51ce75511a85517", size = 13724906, upload-time = "2026-04-21T17:08:01.02Z" },
+    { url = "https://files.pythonhosted.org/packages/a1/32/4c49da27a606167391ff0c39aa955707a00edc500572e562f7c36c08a71f/mypy-1.20.2-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:bb9c2fa06887e21d6a3a868762acb82aec34e2c6fd0174064f27c93ede68ad15", size = 14726046, upload-time = "2026-04-21T17:11:22.354Z" },
+    { url = "https://files.pythonhosted.org/packages/7f/fc/4e354a1bd70216359deb0c9c54847ee6b32ef78dfb09f5131ff99b494078/mypy-1.20.2-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:9d56a78b646f2e3daa865bc70cd5ec5a46c50045801ca8ff17a0c43abc97e3ee", size = 14955587, upload-time = "2026-04-21T17:12:16.033Z" },
+    { url = "https://files.pythonhosted.org/packages/62/b2/c0f2056e9eb8f08c62cafd9715e4584b89132bdc832fcf85d27d07b5f3e5/mypy-1.20.2-cp313-cp313-win_amd64.whl", hash = "sha256:2a4102b03bb7481d9a91a6da8d174740c9c8c4401024684b9ca3b7cc5e49852f", size = 10922681, upload-time = "2026-04-21T17:06:35.842Z" },
+    { url = "https://files.pythonhosted.org/packages/e5/14/065e333721f05de8ef683d0aa804c23026bcc287446b61cac657b902ccac/mypy-1.20.2-cp313-cp313-win_arm64.whl", hash = "sha256:a95a9248b0c6fd933a442c03c3b113c3b61320086b88e2c444676d3fd1ca3330", size = 9830560, upload-time = "2026-04-21T17:07:51.023Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/d1/b4ec96b0ecc620a4443570c6e95c867903428cfcde4206518eafdd5880c3/mypy-1.20.2-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:419413398fe250aae057fd2fe50166b61077083c9b82754c341cf4fd73038f30", size = 14524561, upload-time = "2026-04-21T17:06:27.325Z" },
+    { url = "https://files.pythonhosted.org/packages/3a/63/d2c2ff4fa66bc49477d32dfa26e8a167ba803ea6a69c5efb416036909d30/mypy-1.20.2-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:e73c07f23009962885c197ccb9b41356a30cc0e5a1d0c2ea8fd8fb1362d7f924", size = 13363883, upload-time = "2026-04-21T17:11:11.239Z" },
+    { url = "https://files.pythonhosted.org/packages/2a/56/983916806bf4eddeaaa2c9230903c3669c6718552a921154e1c5182c701f/mypy-1.20.2-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0c64e5973df366b747646fc98da921f9d6eba9716d57d1db94a83c026a08e0fb", size = 13742945, upload-time = "2026-04-21T17:08:34.181Z" },
+    { url = "https://files.pythonhosted.org/packages/19/65/0cd9285ab010ee8214c83d67c6b49417c40d86ce46f1aa109457b5a9b8d7/mypy-1.20.2-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:5a65aa591af023864fd08a97da9974e919452cfe19cb146c8a5dc692626445dc", size = 14706163, upload-time = "2026-04-21T17:05:15.51Z" },
+    { url = "https://files.pythonhosted.org/packages/94/97/48ff3b297cafcc94d185243a9190836fb1b01c1b0918fff64e941e973cc9/mypy-1.20.2-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:4fef51b01e638974a6e69885687e9bd40c8d1e09a6cd291cca0619625cf1f558", size = 14938677, upload-time = "2026-04-21T17:05:39.562Z" },
+    { url = "https://files.pythonhosted.org/packages/fd/a1/1b4233d255bdd0b38a1f284feeb1c143ca508c19184964e22f8d837ec851/mypy-1.20.2-cp314-cp314-win_amd64.whl", hash = "sha256:913485a03f1bcf5d279409a9d2b9ed565c151f61c09f29991e5faa14033da4c8", size = 11089322, upload-time = "2026-04-21T17:06:44.29Z" },
+    { url = "https://files.pythonhosted.org/packages/78/c2/ce7ee2ba36aeb954ba50f18fa25d9c1188578654b97d02a66a15b6f09531/mypy-1.20.2-cp314-cp314-win_arm64.whl", hash = "sha256:c3bae4f855d965b5453784300c12ffc63a548304ac7f99e55d4dc7c898673aa3", size = 10017775, upload-time = "2026-04-21T17:07:20.732Z" },
+    { url = "https://files.pythonhosted.org/packages/4e/a1/9d93a7d0b5859af0ead82b4888b46df6c8797e1bc5e1e262a08518c6d48e/mypy-1.20.2-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:2de3dcea53babc1c3237a19002bc3d228ce1833278f093b8d619e06e7cc79609", size = 15549002, upload-time = "2026-04-21T17:08:23.107Z" },
+    { url = "https://files.pythonhosted.org/packages/00/d2/09a6a10ee1bf0008f6c144d9676f2ca6a12512151b4e0ad0ff6c4fac5337/mypy-1.20.2-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:52b176444e2e5054dfcbcb8c75b0b719865c96247b37407184bbfca5c353f2c2", size = 14401942, upload-time = "2026-04-21T17:07:31.837Z" },
+    { url = "https://files.pythonhosted.org/packages/57/da/9594b75c3c019e805250bed3583bdf4443ff9e6ef08f97e39ae308cb06f2/mypy-1.20.2-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:688c3312e5dadb573a2c69c82af3a298d43ecf9e6d264e0f95df960b5f6ac19c", size = 15041649, upload-time = "2026-04-21T17:09:34.653Z" },
+    { url = "https://files.pythonhosted.org/packages/97/77/f75a65c278e6e8eba2071f7f5a90481891053ecc39878cc444634d892abe/mypy-1.20.2-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:29752dbbf8cc53f89f6ac096d363314333045c257c9c75cbd189ca2de0455744", size = 15864588, upload-time = "2026-04-21T17:11:44.936Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/46/1a4e1c66e96c1a3246ddf5403d122ac9b0a8d2b7e65730b9d6533ba7a6d3/mypy-1.20.2-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:803203d2b6ea644982c644895c2f78b28d0e208bba7b27d9b921e0ec5eb207c6", size = 16093956, upload-time = "2026-04-21T17:10:17.683Z" },
+    { url = "https://files.pythonhosted.org/packages/5a/2c/78a8851264dec38cd736ca5b8bc9380674df0dd0be7792f538916157716c/mypy-1.20.2-cp314-cp314t-win_amd64.whl", hash = "sha256:9bcb8aa397ff0093c824182fd76a935a9ba7ad097fcbef80ae89bf6c1731d8ec", size = 12568661, upload-time = "2026-04-21T17:11:54.473Z" },
+    { url = "https://files.pythonhosted.org/packages/83/01/cd7318aa03493322ce275a0e14f4f52b8896335e4e79d4fb8153a7ad2b77/mypy-1.20.2-cp314-cp314t-win_arm64.whl", hash = "sha256:e061b58443f1736f8a37c48978d7ab581636d6ab03e3d4f99e3fa90463bb9382", size = 10389240, upload-time = "2026-04-21T17:09:42.719Z" },
+    { url = "https://files.pythonhosted.org/packages/28/9a/f23c163e25b11074188251b0b5a0342625fc1cdb6af604757174fa9acc9b/mypy-1.20.2-py3-none-any.whl", hash = "sha256:a94c5a76ab46c5e6257c7972b6c8cff0574201ca7dc05647e33e795d78680563", size = 2637314, upload-time = "2026-04-21T17:05:54.5Z" },
 ]
 
 [[package]]
@@ -1099,27 +1116,27 @@ wheels = [
 
 [[package]]
 name = "ruff"
-version = "0.15.8"
+version = "0.15.12"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/14/b0/73cf7550861e2b4824950b8b52eebdcc5adc792a00c514406556c5b80817/ruff-0.15.8.tar.gz", hash = "sha256:995f11f63597ee362130d1d5a327a87cb6f3f5eae3094c620bcc632329a4d26e", size = 4610921, upload-time = "2026-03-26T18:39:38.675Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/99/43/3291f1cc9106f4c63bdce7a8d0df5047fe8422a75b091c16b5e9355e0b11/ruff-0.15.12.tar.gz", hash = "sha256:ecea26adb26b4232c0c2ca19ccbc0083a68344180bba2a600605538ce51a40a6", size = 4643852, upload-time = "2026-04-24T18:17:14.305Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/4a/92/c445b0cd6da6e7ae51e954939cb69f97e008dbe750cfca89b8cedc081be7/ruff-0.15.8-py3-none-linux_armv6l.whl", hash = "sha256:cbe05adeba76d58162762d6b239c9056f1a15a55bd4b346cfd21e26cd6ad7bc7", size = 10527394, upload-time = "2026-03-26T18:39:41.566Z" },
-    { url = "https://files.pythonhosted.org/packages/eb/92/f1c662784d149ad1414cae450b082cf736430c12ca78367f20f5ed569d65/ruff-0.15.8-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:d3e3d0b6ba8dca1b7ef9ab80a28e840a20070c4b62e56d675c24f366ef330570", size = 10905693, upload-time = "2026-03-26T18:39:30.364Z" },
-    { url = "https://files.pythonhosted.org/packages/ca/f2/7a631a8af6d88bcef997eb1bf87cc3da158294c57044aafd3e17030613de/ruff-0.15.8-py3-none-macosx_11_0_arm64.whl", hash = "sha256:6ee3ae5c65a42f273f126686353f2e08ff29927b7b7e203b711514370d500de3", size = 10323044, upload-time = "2026-03-26T18:39:33.37Z" },
-    { url = "https://files.pythonhosted.org/packages/67/18/1bf38e20914a05e72ef3b9569b1d5c70a7ef26cd188d69e9ca8ef588d5bf/ruff-0.15.8-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:fdce027ada77baa448077ccc6ebb2fa9c3c62fd110d8659d601cf2f475858d94", size = 10629135, upload-time = "2026-03-26T18:39:44.142Z" },
-    { url = "https://files.pythonhosted.org/packages/d2/e9/138c150ff9af60556121623d41aba18b7b57d95ac032e177b6a53789d279/ruff-0.15.8-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:12e617fc01a95e5821648a6df341d80456bd627bfab8a829f7cfc26a14a4b4a3", size = 10348041, upload-time = "2026-03-26T18:39:52.178Z" },
-    { url = "https://files.pythonhosted.org/packages/02/f1/5bfb9298d9c323f842c5ddeb85f1f10ef51516ac7a34ba446c9347d898df/ruff-0.15.8-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:432701303b26416d22ba696c39f2c6f12499b89093b61360abc34bcc9bf07762", size = 11121987, upload-time = "2026-03-26T18:39:55.195Z" },
-    { url = "https://files.pythonhosted.org/packages/10/11/6da2e538704e753c04e8d86b1fc55712fdbdcc266af1a1ece7a51fff0d10/ruff-0.15.8-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:d910ae974b7a06a33a057cb87d2a10792a3b2b3b35e33d2699fdf63ec8f6b17a", size = 11951057, upload-time = "2026-03-26T18:39:19.18Z" },
-    { url = "https://files.pythonhosted.org/packages/83/f0/c9208c5fd5101bf87002fed774ff25a96eea313d305f1e5d5744698dc314/ruff-0.15.8-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:2033f963c43949d51e6fdccd3946633c6b37c484f5f98c3035f49c27395a8ab8", size = 11464613, upload-time = "2026-03-26T18:40:06.301Z" },
-    { url = "https://files.pythonhosted.org/packages/f8/22/d7f2fabdba4fae9f3b570e5605d5eb4500dcb7b770d3217dca4428484b17/ruff-0.15.8-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:0f29b989a55572fb885b77464cf24af05500806ab4edf9a0fd8977f9759d85b1", size = 11257557, upload-time = "2026-03-26T18:39:57.972Z" },
-    { url = "https://files.pythonhosted.org/packages/71/8c/382a9620038cf6906446b23ce8632ab8c0811b8f9d3e764f58bedd0c9a6f/ruff-0.15.8-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:ac51d486bf457cdc985a412fb1801b2dfd1bd8838372fc55de64b1510eff4bec", size = 11169440, upload-time = "2026-03-26T18:39:22.205Z" },
-    { url = "https://files.pythonhosted.org/packages/4d/0d/0994c802a7eaaf99380085e4e40c845f8e32a562e20a38ec06174b52ef24/ruff-0.15.8-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:c9861eb959edab053c10ad62c278835ee69ca527b6dcd72b47d5c1e5648964f6", size = 10605963, upload-time = "2026-03-26T18:39:46.682Z" },
-    { url = "https://files.pythonhosted.org/packages/19/aa/d624b86f5b0aad7cef6bbf9cd47a6a02dfdc4f72c92a337d724e39c9d14b/ruff-0.15.8-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:8d9a5b8ea13f26ae90838afc33f91b547e61b794865374f114f349e9036835fb", size = 10357484, upload-time = "2026-03-26T18:39:49.176Z" },
-    { url = "https://files.pythonhosted.org/packages/35/c3/e0b7835d23001f7d999f3895c6b569927c4d39912286897f625736e1fd04/ruff-0.15.8-py3-none-musllinux_1_2_i686.whl", hash = "sha256:c2a33a529fb3cbc23a7124b5c6ff121e4d6228029cba374777bd7649cc8598b8", size = 10830426, upload-time = "2026-03-26T18:40:03.702Z" },
-    { url = "https://files.pythonhosted.org/packages/f0/51/ab20b322f637b369383adc341d761eaaa0f0203d6b9a7421cd6e783d81b9/ruff-0.15.8-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:75e5cd06b1cf3f47a3996cfc999226b19aa92e7cce682dcd62f80d7035f98f49", size = 11345125, upload-time = "2026-03-26T18:39:27.799Z" },
-    { url = "https://files.pythonhosted.org/packages/37/e6/90b2b33419f59d0f2c4c8a48a4b74b460709a557e8e0064cf33ad894f983/ruff-0.15.8-py3-none-win32.whl", hash = "sha256:bc1f0a51254ba21767bfa9a8b5013ca8149dcf38092e6a9eb704d876de94dc34", size = 10571959, upload-time = "2026-03-26T18:39:36.117Z" },
-    { url = "https://files.pythonhosted.org/packages/1f/a2/ef467cb77099062317154c63f234b8a7baf7cb690b99af760c5b68b9ee7f/ruff-0.15.8-py3-none-win_amd64.whl", hash = "sha256:04f79eff02a72db209d47d665ba7ebcad609d8918a134f86cb13dd132159fc89", size = 11743893, upload-time = "2026-03-26T18:39:25.01Z" },
-    { url = "https://files.pythonhosted.org/packages/15/e2/77be4fff062fa78d9b2a4dea85d14785dac5f1d0c1fb58ed52331f0ebe28/ruff-0.15.8-py3-none-win_arm64.whl", hash = "sha256:cf891fa8e3bb430c0e7fac93851a5978fc99c8fa2c053b57b118972866f8e5f2", size = 11048175, upload-time = "2026-03-26T18:40:01.06Z" },
+    { url = "https://files.pythonhosted.org/packages/c3/6e/e78ffb61d4686f3d96ba3df2c801161843746dcbcbb17a1e927d4829312b/ruff-0.15.12-py3-none-linux_armv6l.whl", hash = "sha256:f86f176e188e94d6bdbc09f09bfd9dc729059ad93d0e7390b5a73efe19f8861c", size = 10640713, upload-time = "2026-04-24T18:17:22.841Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/08/a317bc231fb9e7b93e4ef3089501e51922ff88d6936ce5cf870c4fe55419/ruff-0.15.12-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:e3bcd123364c3770b8e1b7baaf343cc99a35f197c5c6e8af79015c666c423a6c", size = 11069267, upload-time = "2026-04-24T18:17:30.105Z" },
+    { url = "https://files.pythonhosted.org/packages/aa/a4/f828e9718d3dce1f5f11c39c4f65afd32783c8b2aebb2e3d259e492c47bd/ruff-0.15.12-py3-none-macosx_11_0_arm64.whl", hash = "sha256:fe87510d000220aa1ed530d4448a7c696a0cae1213e5ec30e5874287b66557b5", size = 10397182, upload-time = "2026-04-24T18:17:07.177Z" },
+    { url = "https://files.pythonhosted.org/packages/71/e0/3310fc6d1b5e1fdea22bf3b1b807c7e187b581021b0d7d4514cccdb5fb71/ruff-0.15.12-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:84a1630093121375a3e2a95b4a6dc7b59e2b4ee76216e32d81aae550a832d002", size = 10758012, upload-time = "2026-04-24T18:16:55.759Z" },
+    { url = "https://files.pythonhosted.org/packages/11/c1/a606911aee04c324ddaa883ae418f3569792fd3c4a10c50e0dd0a2311e1e/ruff-0.15.12-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:fb129f40f114f089ebe0ca56c0d251cf2061b17651d464bb6478dc01e69f11f5", size = 10447479, upload-time = "2026-04-24T18:16:51.677Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/68/4201e8444f0894f21ab4aeeaee68aa4f10b51613514a20d80bd628d57e88/ruff-0.15.12-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:b0c862b172d695db7598426b8af465e7e9ac00a3ea2a3630ee67eb82e366aaa6", size = 11234040, upload-time = "2026-04-24T18:17:16.529Z" },
+    { url = "https://files.pythonhosted.org/packages/34/ff/8a6d6cf4ccc23fd67060874e832c18919d1557a0611ebef03fdb01fff11e/ruff-0.15.12-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:2849ea9f3484c3aca43a82f484210370319e7170df4dfe4843395ddf6c57bc33", size = 12087377, upload-time = "2026-04-24T18:17:04.944Z" },
+    { url = "https://files.pythonhosted.org/packages/85/f6/c669cf73f5152f623d34e69866a46d5e6185816b19fcd5b6dd8a2d299922/ruff-0.15.12-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:9e77c7e51c07fe396826d5969a5b846d9cd4c402535835fb6e21ce8b28fef847", size = 11367784, upload-time = "2026-04-24T18:17:25.409Z" },
+    { url = "https://files.pythonhosted.org/packages/e8/39/c61d193b8a1daaa8977f7dea9e8d8ba866e02ea7b65d32f6861693aa4c12/ruff-0.15.12-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:83b2f4f2f3b1026b5fb449b467d9264bf22067b600f7b6f41fc5958909f449d0", size = 11344088, upload-time = "2026-04-24T18:17:12.258Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/8d/49afab3645e31e12c590acb6d3b5b69d7aab5b81926dbaf7461f9441f37a/ruff-0.15.12-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:9ba3b8f1afd7e2e43d8943e55f249e13f9682fde09711644a6e7290eb4f3e339", size = 11271770, upload-time = "2026-04-24T18:17:02.457Z" },
+    { url = "https://files.pythonhosted.org/packages/46/06/33f41fe94403e2b755481cdfb9b7ef3e4e0ed031c4581124658d935d52b4/ruff-0.15.12-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:e852ba9fdc890655e1d78f2df1499efbe0e54126bd405362154a75e2bde159c5", size = 10719355, upload-time = "2026-04-24T18:17:27.648Z" },
+    { url = "https://files.pythonhosted.org/packages/0d/59/18aa4e014debbf559670e4048e39260a85c7fcee84acfd761ac01e7b8d35/ruff-0.15.12-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:dd8aed930da53780d22fc70bdf84452c843cf64f8cb4eb38984319c24c5cd5fd", size = 10462758, upload-time = "2026-04-24T18:17:32.347Z" },
+    { url = "https://files.pythonhosted.org/packages/25/e7/cc9f16fd0f3b5fddcbd7ec3d6ae30c8f3fde1047f32a4093a98d633c6570/ruff-0.15.12-py3-none-musllinux_1_2_i686.whl", hash = "sha256:01da3988d225628b709493d7dc67c3b9b12c0210016b08690ef9bd27970b262b", size = 10953498, upload-time = "2026-04-24T18:17:20.674Z" },
+    { url = "https://files.pythonhosted.org/packages/72/7a/a9ba7f98c7a575978698f4230c5e8cc54bbc761af34f560818f933dafa0c/ruff-0.15.12-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:9cae0f92bd5700d1213188b31cd3bdd2b315361296d10b96b8e2337d3d11f53e", size = 11447765, upload-time = "2026-04-24T18:17:09.755Z" },
+    { url = "https://files.pythonhosted.org/packages/ea/f9/0ae446942c846b8266059ad8a30702a35afae55f5cdc54c5adf8d7afdc27/ruff-0.15.12-py3-none-win32.whl", hash = "sha256:d0185894e038d7043ba8fd6aee7499ece6462dc0ea9f1e260c7451807c714c20", size = 10657277, upload-time = "2026-04-24T18:17:18.591Z" },
+    { url = "https://files.pythonhosted.org/packages/33/f1/9614e03e1cdcbf9437570b5400ced8a720b5db22b28d8e0f1bda429f660d/ruff-0.15.12-py3-none-win_amd64.whl", hash = "sha256:c87a162d61ab3adca47c03f7f717c68672edec7d1b5499e652331780fe74950d", size = 11837758, upload-time = "2026-04-24T18:17:00.113Z" },
+    { url = "https://files.pythonhosted.org/packages/c0/98/6beb4b351e472e5f4c4613f7c35a5290b8be2497e183825310c4c3a3984b/ruff-0.15.12-py3-none-win_arm64.whl", hash = "sha256:a538f7a82d061cee7be55542aca1d86d1393d55d81d4fcc314370f4340930d4f", size = 11120821, upload-time = "2026-04-24T18:16:57.979Z" },
 ]
 
 [[package]]

libs/checkpoint-sqlite/langgraph/checkpoint/sqlite/__init__.py

@@ -4,7 +4,7 @@ import json
 import random
 import sqlite3
 import threading
-from collections.abc import AsyncIterator, Iterator, Sequence
+from collections.abc import AsyncIterator, Iterator, Mapping, Sequence
 from contextlib import closing, contextmanager
 from typing import Any, cast
 
@@ -16,12 +16,19 @@ from langgraph.checkpoint.base import (
     Checkpoint,
     CheckpointMetadata,
     CheckpointTuple,
+    DeltaChannelHistory,
     SerializerProtocol,
     get_checkpoint_id,
     get_checkpoint_metadata,
 )
 from langgraph.checkpoint.serde.jsonplus import JsonPlusSerializer
 
+from langgraph.checkpoint.sqlite._delta import (
+    DELTA_STAGE1_SQL,
+    build_delta_channels_writes_history,
+    build_delta_stage2_sql,
+    step_walk_with_row,
+)
 from langgraph.checkpoint.sqlite.utils import search_where
 
 _AIO_ERROR_MSG = (
@@ -493,6 +500,88 @@ class SqliteSaver(BaseCheckpointSaver[str]):
                 (str(thread_id),),
             )
 
+    def get_delta_channel_history(
+        self, *, config: RunnableConfig, channels: Sequence[str]
+    ) -> Mapping[str, DeltaChannelHistory]:
+        """Fast-path override of `BaseCheckpointSaver.get_delta_channel_history`.
+
+        Two-stage query:
+
+        * Stage 1 (paged): newest-first slice of `checkpoints` returning
+          `(checkpoint_id, parent_checkpoint_id, type, checkpoint)` per
+          ancestor. Sqlite has no JSONB, so we ship the full serialized
+          checkpoint blob and inspect `channel_values` in Python. Pages
+          newest-first by `checkpoint_id` with a `< cursor` predicate;
+          page size is `DELTA_PAGE_SIZE`. Stops paging when every channel
+          has found its seed or the chain is exhausted.
+
+        * Stage 2 (per-channel UNION ALL): one branch per channel reading
+          `writes` filtered to that channel's specific `chain_cids`. No
+          separate seed-blob fetch — sqlite stores `channel_values` inline
+          in the checkpoint blob, so seeds come back from stage 1.
+        """
+        if not channels:
+            return {}
+        channels = list(channels)
+        thread_id = str(config["configurable"]["thread_id"])
+        checkpoint_ns = config["configurable"].get("checkpoint_ns", "")
+        checkpoint_id = get_checkpoint_id(config)
+        if checkpoint_id is None:
+            target = self.get_tuple(config)
+            if target is None:
+                return {ch: {"writes": []} for ch in channels}
+            checkpoint_id = target.config["configurable"]["checkpoint_id"]
+
+        chain_by_ch: dict[str, list[str]] = {ch: [] for ch in channels}
+        seed_val_by_ch: dict[str, Any] = {}
+        walk_state: dict[str, Any] = {}
+        seeded: set[str] = set()
+
+        with self.cursor(transaction=False) as cur:
+            cur.execute(DELTA_STAGE1_SQL, (thread_id, checkpoint_ns, checkpoint_id))
+            for row in cur:
+                cid, parent_cid, type_tag, blob = row
+                if step_walk_with_row(
+                    cid=cid,
+                    parent_cid=parent_cid,
+                    type_tag=type_tag,
+                    blob=blob,
+                    target_id=checkpoint_id,
+                    serde=self.serde,
+                    chain_by_ch=chain_by_ch,
+                    seed_val_by_ch=seed_val_by_ch,
+                    walk_state=walk_state,
+                    seeded=seeded,
+                    channels=channels,
+                ):
+                    break
+
+            channels_with_chain = [ch for ch in channels if chain_by_ch[ch]]
+            stage2_sql = build_delta_stage2_sql(
+                chain_lens=[len(chain_by_ch[ch]) for ch in channels_with_chain],
+            )
+            if stage2_sql:
+                stage2_params: list[Any] = []
+                for ch in channels_with_chain:
+                    stage2_params.extend(
+                        [thread_id, checkpoint_ns, ch, *chain_by_ch[ch]]
+                    )
+                cur.execute(stage2_sql, stage2_params)
+                stage2_rows = cast(
+                    "list[tuple[str, str, str, int, str, bytes]]", cur.fetchall()
+                )
+            else:
+                stage2_rows = []
+
+        return build_delta_channels_writes_history(
+            channels=channels,
+            chain_by_ch=chain_by_ch,
+            seed_val_by_ch=seed_val_by_ch,
+            seeded=seeded,
+            stage2_rows=stage2_rows,
+            serde=self.serde,
+        )
+
     async def aget_tuple(self, config: RunnableConfig) -> CheckpointTuple | None:
         """Get a checkpoint tuple from the database asynchronously.
 

libs/checkpoint-sqlite/langgraph/checkpoint/sqlite/_delta.py

@@ -0,0 +1,172 @@
+"""Shared helpers for `get_delta_channel_history` on sqlite savers.
+
+Mirrors the two-stage shape of `BasePostgresSaver` (ancestor walk +
+per-channel UNION ALL writes fetch), but adapted for sqlite's
+constraints. The structural differences:
+
+* No JSONB — to inspect `channel_values` for a checkpoint we must
+  deserialize the full blob. Stage 1 streams the cursor row-by-row and
+  deserializes only the rows the merged walk visits, freeing each blob
+  before advancing.
+* No separate blob table — `channel_values` lives inline in the
+  checkpoint, so seeds come back from stage 1 with no second fetch.
+* Single merged walk (not K independent walks): each visited cid is
+  deserialized exactly once, regardless of how many channels are still
+  seeking their seed.
+
+The streaming design keeps peak in-flight memory at roughly one
+deserialized checkpoint at a time, instead of holding the entire
+ancestor chain's worth of raw blobs as a `fetchall()`-materialized list.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from langgraph.checkpoint.base import DeltaChannelHistory, PendingWrite
+
+# Stage 1 streams ancestors of `target_cid` newest-first. The `<=`
+# predicate keeps target itself in the stream so we can read its
+# `parent_checkpoint_id` from the first row without a separate lookup;
+# the caller skips target's own writes/seed (matches the
+# `BaseCheckpointSaver` contract).
+DELTA_STAGE1_SQL = (
+    "SELECT checkpoint_id, parent_checkpoint_id, type, checkpoint "
+    "FROM checkpoints "
+    "WHERE thread_id = ? AND checkpoint_ns = ? AND checkpoint_id <= ? "
+    "ORDER BY checkpoint_id DESC"
+)
+
+
+def build_delta_stage2_sql(*, chain_lens: Sequence[int]) -> str:
+    """Stage-2 per-channel UNION ALL fetching writes from `writes`.
+
+    One branch per channel with a non-empty chain. Each branch inlines its
+    own `IN (?, ?, ...)` placeholder list because sqlite has no array-bind
+    equivalent of postgres's `= ANY(%s)`. Caller passes parameters in
+    matching order: `[thread_id, checkpoint_ns, channel, *chain_cids]` per
+    branch.
+
+    Returns an empty string when no channel has a chain (caller skips
+    executing in that case). Per-channel UNION ALL avoids the over-fetch
+    of a single `channel = ANY(channels)` filter when channels have
+    different chain depths — same rationale as postgres.
+    """
+    branches: list[str] = []
+    for n in chain_lens:
+        cid_placeholders = ",".join("?" * n)
+        branches.append(
+            "SELECT checkpoint_id, channel, task_id, idx, type, value "
+            "FROM writes "
+            "WHERE thread_id = ? AND checkpoint_ns = ? AND channel = ? "
+            f"AND checkpoint_id IN ({cid_placeholders})"
+        )
+    return " UNION ALL ".join(branches)
+
+
+def step_walk_with_row(
+    *,
+    cid: str,
+    parent_cid: str | None,
+    type_tag: str,
+    blob: bytes,
+    target_id: str,
+    serde: Any,
+    chain_by_ch: dict[str, list[str]],
+    seed_val_by_ch: dict[str, Any],
+    walk_state: dict[str, Any],
+    seeded: set[str],
+    channels: Sequence[str],
+) -> bool:
+    """Process one streamed stage-1 row in the merged ancestor walk.
+
+    The cursor returns (cid, parent_cid, type, blob) rows in
+    `checkpoint_id` DESC order starting at target. The first row is
+    target itself; we read its parent_cid to seed the walk and otherwise
+    skip it (target's own writes/seed are not part of the contract).
+
+    For each subsequent row, if `cid` matches the walk's current
+    position, we deserialize the blob, append the cid to every
+    not-yet-seeded channel's chain, and check `channel_values` for
+    seeds. The deserialized checkpoint is dropped before advancing — no
+    cross-row cache, so peak in-flight is one deserialized checkpoint.
+
+    Off-path rows (different branch on the same thread) advance the
+    cursor without doing any work.
+
+    Returns True when every requested channel is seeded — the caller
+    can stop iterating and close the cursor.
+    """
+    if "started" not in walk_state:
+        if cid == target_id:
+            walk_state["started"] = True
+            walk_state["cur_cid"] = parent_cid
+            walk_state["active"] = {ch for ch in channels if ch not in seeded}
+        # Not target yet (or target not present): keep streaming.
+        return False
+    active: set[str] = walk_state["active"]
+    if not active:
+        return True
+    if cid != walk_state["cur_cid"]:
+        # Off-path row from a sibling branch — skip without deserializing.
+        return False
+    for ch in active:
+        chain_by_ch[ch].append(cid)
+    ckpt = serde.loads_typed((type_tag, blob))
+    channel_values: Mapping[str, Any] = ckpt.get("channel_values") or {}
+    for ch in [ch for ch in active if ch in channel_values]:
+        seed_val_by_ch[ch] = channel_values[ch]
+        seeded.add(ch)
+        active.discard(ch)
+    del ckpt, channel_values
+    walk_state["cur_cid"] = parent_cid
+    return not active
+
+
+def build_delta_channels_writes_history(
+    *,
+    channels: Sequence[str],
+    chain_by_ch: Mapping[str, list[str]],
+    seed_val_by_ch: Mapping[str, Any],
+    seeded: set[str],
+    stage2_rows: Sequence[tuple[str, str, str, int, str, bytes]],
+    serde: Any,
+) -> dict[str, DeltaChannelHistory]:
+    """Demux stage-2 rows per channel; produce per-channel histories.
+
+    Stage-2 rows are `(checkpoint_id, channel, task_id, idx, type, value)`.
+    Final write order is oldest→newest globally and `(task_id, idx)` within
+    a checkpoint, matching the contract on `DeltaChannelHistory.writes`.
+
+    `seed` is omitted when the walk reached a true root with no snapshot
+    found (channel never entered `seeded`); consumers treat absence as
+    "start empty".
+    """
+    writes_by_ch_by_cid: dict[str, dict[str, list[tuple[str, bytes, str, int]]]] = {
+        ch: {} for ch in channels
+    }
+    for cid, ch, task_id, idx, type_tag, value_blob in stage2_rows:
+        writes_by_ch_by_cid.setdefault(ch, {}).setdefault(cid, []).append(
+            (type_tag, value_blob, task_id, idx)
+        )
+    for cid_map in writes_by_ch_by_cid.values():
+        for ws in cid_map.values():
+            ws.sort(key=lambda w: (w[2], w[3]))
+
+    result: dict[str, DeltaChannelHistory] = {}
+    for ch in channels:
+        chain_cids = chain_by_ch.get(ch, [])
+        cid_writes = writes_by_ch_by_cid.get(ch, {})
+        collected: list[PendingWrite] = []
+        # Chain is newest-first; iterate oldest-first for the public order.
+        for cid in reversed(chain_cids):
+            for type_tag, value_blob, task_id, _idx in cid_writes.get(cid, []):
+                collected.append(
+                    (task_id, ch, serde.loads_typed((type_tag, value_blob)))
+                )
+        entry: DeltaChannelHistory = {"writes": collected}
+        if ch in seeded:
+            entry["seed"] = seed_val_by_ch[ch]
+        result[ch] = entry
+    return result

libs/checkpoint-sqlite/langgraph/checkpoint/sqlite/aio.py

@@ -4,7 +4,7 @@ import asyncio
 import json
 import random
 import threading
-from collections.abc import AsyncIterator, Callable, Iterator, Sequence
+from collections.abc import AsyncIterator, Callable, Iterator, Mapping, Sequence
 from contextlib import asynccontextmanager
 from typing import Any, TypeVar, cast
 
@@ -17,12 +17,19 @@ from langgraph.checkpoint.base import (
     Checkpoint,
     CheckpointMetadata,
     CheckpointTuple,
+    DeltaChannelHistory,
     SerializerProtocol,
     get_checkpoint_id,
     get_checkpoint_metadata,
 )
 from langgraph.checkpoint.serde.jsonplus import JsonPlusSerializer
 
+from langgraph.checkpoint.sqlite._delta import (
+    DELTA_STAGE1_SQL,
+    build_delta_channels_writes_history,
+    build_delta_stage2_sql,
+    step_walk_with_row,
+)
 from langgraph.checkpoint.sqlite.utils import search_where
 
 T = TypeVar("T", bound=Callable)
@@ -272,6 +279,29 @@ class AsyncSqliteSaver(BaseCheckpointSaver[str]):
             self.adelete_thread(thread_id), self.loop
         ).result()
 
+    def get_delta_channel_history(
+        self, *, config: RunnableConfig, channels: Sequence[str]
+    ) -> Mapping[str, DeltaChannelHistory]:
+        """Sync bridge to `aget_delta_channel_history`.
+
+        Mirrors the same cross-thread guard as `get_tuple` /
+        `delete_thread` — calling from the loop thread raises rather than
+        deadlocking.
+        """
+        try:
+            if asyncio.get_running_loop() is self.loop:
+                raise asyncio.InvalidStateError(
+                    "Synchronous calls to AsyncSqliteSaver are only allowed from a "
+                    "different thread. From the main thread, use the async interface. "
+                    "For example, use `await checkpointer.aget_delta_channel_history(...)`."
+                )
+        except RuntimeError:
+            pass
+        return asyncio.run_coroutine_threadsafe(
+            self.aget_delta_channel_history(config=config, channels=channels),
+            self.loop,
+        ).result()
+
     async def setup(self) -> None:
         """Set up the checkpoint database asynchronously.
 
@@ -589,6 +619,83 @@ class AsyncSqliteSaver(BaseCheckpointSaver[str]):
             )
             await self.conn.commit()
 
+    async def aget_delta_channel_history(
+        self, *, config: RunnableConfig, channels: Sequence[str]
+    ) -> Mapping[str, DeltaChannelHistory]:
+        """Fast-path override of `BaseCheckpointSaver.aget_delta_channel_history`.
+
+        See `SqliteSaver.get_delta_channel_history` for design notes; this
+        is the async equivalent using `aiosqlite` cursors. Stage 1 pages
+        the parent chain newest-first and Python-deserializes each
+        checkpoint blob to find per-channel snapshots; stage 2 fetches
+        only the relevant writes via per-channel UNION ALL.
+        """
+        if not channels:
+            return {}
+        channels = list(channels)
+        await self.setup()
+        thread_id = str(config["configurable"]["thread_id"])
+        checkpoint_ns = config["configurable"].get("checkpoint_ns", "")
+        checkpoint_id = get_checkpoint_id(config)
+        if checkpoint_id is None:
+            target = await self.aget_tuple(config)
+            if target is None:
+                return {ch: {"writes": []} for ch in channels}
+            checkpoint_id = target.config["configurable"]["checkpoint_id"]
+
+        chain_by_ch: dict[str, list[str]] = {ch: [] for ch in channels}
+        seed_val_by_ch: dict[str, Any] = {}
+        walk_state: dict[str, Any] = {}
+        seeded: set[str] = set()
+
+        async with self.lock, self.conn.cursor() as cur:
+            await cur.execute(
+                DELTA_STAGE1_SQL, (thread_id, checkpoint_ns, checkpoint_id)
+            )
+            async for row in cur:
+                cid, parent_cid, type_tag, blob = row
+                if step_walk_with_row(
+                    cid=cid,
+                    parent_cid=parent_cid,
+                    type_tag=type_tag,
+                    blob=blob,
+                    target_id=checkpoint_id,
+                    serde=self.serde,
+                    chain_by_ch=chain_by_ch,
+                    seed_val_by_ch=seed_val_by_ch,
+                    walk_state=walk_state,
+                    seeded=seeded,
+                    channels=channels,
+                ):
+                    break
+
+            channels_with_chain = [ch for ch in channels if chain_by_ch[ch]]
+            stage2_sql = build_delta_stage2_sql(
+                chain_lens=[len(chain_by_ch[ch]) for ch in channels_with_chain],
+            )
+            if stage2_sql:
+                stage2_params: list[Any] = []
+                for ch in channels_with_chain:
+                    stage2_params.extend(
+                        [thread_id, checkpoint_ns, ch, *chain_by_ch[ch]]
+                    )
+                await cur.execute(stage2_sql, stage2_params)
+                stage2_rows = cast(
+                    "list[tuple[str, str, str, int, str, bytes]]",
+                    await cur.fetchall(),
+                )
+            else:
+                stage2_rows = []
+
+        return build_delta_channels_writes_history(
+            channels=channels,
+            chain_by_ch=chain_by_ch,
+            seed_val_by_ch=seed_val_by_ch,
+            seeded=seeded,
+            stage2_rows=stage2_rows,
+            serde=self.serde,
+        )
+
     def get_next_version(self, current: str | None, channel: None) -> str:
         """Generate the next version ID for a channel.
 

libs/checkpoint-sqlite/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "langgraph-checkpoint-sqlite"
-version = "3.0.3"
+version = "3.1.0a1"
 description = "Library with a SQLite implementation of LangGraph checkpoint saver."
 authors = []
 requires-python = ">=3.10"
@@ -12,7 +12,7 @@ readme = "README.md"
 license = "MIT"
 license-files = ['LICENSE']
 dependencies = [
-    "langgraph-checkpoint>=3,<5.0.0",
+    "langgraph-checkpoint>=4.1.0a4,<5.0.0",
     "aiosqlite>=0.20",
     "sqlite-vec>=0.1.6",
 ]

libs/checkpoint-sqlite/tests/test_conformance_delta.py

@@ -0,0 +1,35 @@
+"""Run delta-channel conformance capabilities against AsyncSqliteSaver."""
+
+from __future__ import annotations
+
+import pytest
+
+pytest.importorskip(
+    "langgraph.checkpoint.conformance",
+    reason="langgraph-checkpoint-conformance not installed",
+)
+pytest.importorskip("aiosqlite", reason="aiosqlite not installed")
+
+
+@pytest.mark.asyncio
+async def test_delta_channel_conformance():
+    from langgraph.checkpoint.conformance import validate
+    from langgraph.checkpoint.conformance.initializer import checkpointer_test
+
+    from langgraph.checkpoint.sqlite.aio import AsyncSqliteSaver
+
+    @checkpointer_test(name="AsyncSqliteSaver")
+    async def sqlite_saver():
+        async with AsyncSqliteSaver.from_conn_string(":memory:") as saver:
+            yield saver
+
+    report = await validate(
+        sqlite_saver,
+        capabilities={
+            "delta_channel_history",
+        },
+    )
+    for cap, result in report.results.items():
+        if result.passed is False:
+            details = "\n".join(result.failures or [])
+            pytest.fail(f"Capability {cap} failed:\n{details}")

libs/checkpoint-sqlite/tests/test_delta_channel_migration.py

@@ -0,0 +1,170 @@
+"""Sqlite-specific migration smoke tests: BinaryOperatorAggregate -> DeltaChannel.
+
+Mirrors `libs/langgraph/tests/test_delta_channel_migration.py` (which
+covers `InMemorySaver` + a third-party fallback to the base default
+impl). This file exercises the same migration scenario through the
+sqlite-specific `SqliteSaver.get_delta_channel_history` override —
+specifically that the streaming ancestor walk finds a pre-migration
+plain `channel_values[ch]` entry and surfaces it as the `seed`, with
+post-migration writes folding on top through the reducer.
+
+Pre-migration checkpoints under `BinaryOperatorAggregate` carry the
+full accumulated value at every settled super-step boundary. The
+override has to identify those as "real" seeds (not `_DeltaSnapshot`
+sentinels) — the saver layer is intentionally delta-agnostic and just
+returns whatever is stored in `channel_values[ch]`.
+"""
+
+from __future__ import annotations
+
+import operator
+from typing import Annotated, Any
+
+import pytest
+from langchain_core.runnables import RunnableConfig
+
+# `langgraph` core isn't a dep of `langgraph-checkpoint-sqlite`. Skip the
+# whole module rather than importerror-ing in the standalone CI shape.
+pytest.importorskip("langgraph.channels.delta", reason="langgraph core not installed")
+pytest.importorskip("langgraph.channels.binop", reason="langgraph core not installed")
+pytest.importorskip("langgraph.graph", reason="langgraph core not installed")
+
+from langgraph.channels.binop import BinaryOperatorAggregate  # type: ignore[import-untyped]  # noqa: E402,I001
+from langgraph.channels.delta import DeltaChannel  # type: ignore[import-untyped]  # noqa: E402
+from langgraph.graph import END, START, StateGraph  # type: ignore[import-untyped]  # noqa: E402
+from typing_extensions import TypedDict  # noqa: E402
+
+from langgraph.checkpoint.sqlite import SqliteSaver  # noqa: E402
+from langgraph.checkpoint.sqlite.aio import AsyncSqliteSaver  # noqa: E402
+
+pytestmark = pytest.mark.anyio
+
+
+def _noop(_state: Any) -> dict:
+    return {}
+
+
+def _list_concat(state: list, writes: list) -> list:
+    result = list(state)
+    for w in writes:
+        result.extend(w if isinstance(w, list) else [w])
+    return result
+
+
+def _binop_graph(checkpointer: Any) -> Any:
+    class BinopState(TypedDict):
+        items: Annotated[list, BinaryOperatorAggregate(list, operator.add)]
+
+    return (
+        StateGraph(BinopState)
+        .add_node("noop", _noop)
+        .add_edge(START, "noop")
+        .add_edge("noop", END)
+        .compile(checkpointer=checkpointer)
+    )
+
+
+def _delta_graph(checkpointer: Any) -> Any:
+    class DeltaState(TypedDict):
+        items: Annotated[list, DeltaChannel(_list_concat)]
+
+    return (
+        StateGraph(DeltaState)
+        .add_node("noop", _noop)
+        .add_edge(START, "noop")
+        .add_edge("noop", END)
+        .compile(checkpointer=checkpointer)
+    )
+
+
+def _drive(graph: Any, config: RunnableConfig, tag: str, n: int) -> None:
+    for i in range(n):
+        graph.invoke({"items": [f"{tag}{i}"]}, config)
+
+
+async def _adrive(graph: Any, config: RunnableConfig, tag: str, n: int) -> None:
+    for i in range(n):
+        await graph.ainvoke({"items": [f"{tag}{i}"]}, config)
+
+
+def _settled_boundaries(history: list) -> list[tuple[RunnableConfig, list]]:
+    """`(config, items)` for every checkpoint with `next == ('__start__',)`
+    — the stable inter-invoke boundaries that round-trip predictably.
+    """
+    return [
+        (s.config, list(s.values.get("items", [])))
+        for s in history
+        if s.next == ("__start__",)
+    ]
+
+
+def test_migration_preserves_pre_migration_state_sync() -> None:
+    """Drive 3 invokes under `BinaryOperatorAggregate`, swap the
+    annotation to `DeltaChannel` on the same sqlite-backed thread, and
+    verify every settled pre-migration boundary round-trips exactly.
+
+    The override's streaming walk must identify the plain accumulated
+    list at each pre-migration ancestor as a valid `seed` even though
+    no `_DeltaSnapshot` was ever written there.
+    """
+    with SqliteSaver.from_conn_string(":memory:") as saver:
+        config: RunnableConfig = {"configurable": {"thread_id": "mig-sync"}}
+
+        binop = _binop_graph(saver)
+        _drive(binop, config, "u", 3)
+
+        pre_boundaries = _settled_boundaries(list(binop.get_state_history(config)))
+        assert len(pre_boundaries) >= 2, "expected multiple settled boundaries"
+
+        delta = _delta_graph(saver)
+        for cfg, items in pre_boundaries:
+            snap = delta.get_state(cfg)
+            assert list(snap.values.get("items", [])) == items, (
+                f"snapshot mismatch at {cfg['configurable']['checkpoint_id']}: "
+                f"expected {items}, got {snap.values.get('items', [])}"
+            )
+
+
+def test_migration_continued_thread_folds_deltas_on_seed_sync() -> None:
+    """After migration, driving one more super-step extends the
+    pre-migration accumulated state via the delta reducer — the seed
+    plus a single new write.
+    """
+    with SqliteSaver.from_conn_string(":memory:") as saver:
+        config: RunnableConfig = {"configurable": {"thread_id": "mig-continue-sync"}}
+
+        binop = _binop_graph(saver)
+        _drive(binop, config, "u", 3)
+
+        pre_history = list(binop.get_state_history(config))
+        pre_boundaries = _settled_boundaries(pre_history)
+        # Latest settled boundary — the leaf pre-migration state.
+        leaf_cfg, leaf_items = pre_boundaries[0]
+        assert leaf_items, "expected non-empty pre-migration leaf"
+
+        delta = _delta_graph(saver)
+        delta.invoke({"items": ["after-migration"]}, leaf_cfg)
+        new_state = delta.get_state(config).values["items"]
+        assert new_state[: len(leaf_items)] == leaf_items
+        assert "after-migration" in new_state
+
+
+async def test_migration_preserves_pre_migration_state_async() -> None:
+    """Async equivalent of the basic-migration round-trip check on
+    `AsyncSqliteSaver`."""
+    async with AsyncSqliteSaver.from_conn_string(":memory:") as saver:
+        config: RunnableConfig = {"configurable": {"thread_id": "mig-async"}}
+
+        binop = _binop_graph(saver)
+        await _adrive(binop, config, "u", 3)
+
+        pre_history = [s async for s in binop.aget_state_history(config)]
+        pre_boundaries = _settled_boundaries(pre_history)
+        assert len(pre_boundaries) >= 2
+
+        delta = _delta_graph(saver)
+        for cfg, items in pre_boundaries:
+            snap = await delta.aget_state(cfg)
+            assert list(snap.values.get("items", [])) == items, (
+                f"async snapshot mismatch at {cfg['configurable']['checkpoint_id']}"
+            )

libs/checkpoint-sqlite/tests/test_get_delta_channel_history.py

@@ -0,0 +1,271 @@
+"""Smoke tests for `BaseCheckpointSaver.get_delta_channel_history` on sqlite.
+
+`SqliteSaver` (and `AsyncSqliteSaver`) deliberately don't override the
+default implementation in `BaseCheckpointSaver` — these tests pin the
+default impl to behave correctly end-to-end against a real persistent
+saver and a real `DeltaChannel`-backed graph.
+
+Scenarios covered:
+
+* Empty `channels` argument returns an empty mapping (no I/O).
+* On a non-trivial multi-checkpoint thread, per-channel writes come back
+  oldest→newest.
+* When the walk reaches the root without ever finding a stored value,
+  `seed` is omitted from the entry (consumer treats absence as "start
+  empty").
+* When a `_DeltaSnapshot` blob is present at an ancestor, it is returned
+  as the `seed`.
+* The async saver returns the same shape via `aget_delta_channel_history`.
+"""
+
+from __future__ import annotations
+
+import operator
+from typing import Annotated, Any
+
+import pytest
+from langchain_core.runnables import RunnableConfig
+
+# `langgraph` is not a dep of `langgraph-checkpoint-sqlite`. When tests run
+# in the sqlite lib's standalone CI environment without it installed, skip
+# the whole module rather than failing at import.
+pytest.importorskip("langgraph.channels.delta", reason="langgraph core not installed")
+pytest.importorskip("langgraph.graph", reason="langgraph core not installed")
+
+from langgraph.channels.delta import DeltaChannel  # type: ignore[import-untyped]  # noqa: E402,I001
+from langgraph.checkpoint.serde.types import _DeltaSnapshot  # noqa: E402
+from langgraph.graph import END, START, StateGraph  # type: ignore[import-untyped]  # noqa: E402
+from typing_extensions import TypedDict  # noqa: E402
+
+from langgraph.checkpoint.sqlite import SqliteSaver  # noqa: E402
+from langgraph.checkpoint.sqlite.aio import AsyncSqliteSaver  # noqa: E402
+
+pytestmark = pytest.mark.anyio
+
+
+# ---------------------------------------------------------------------------
+# Graph helpers
+# ---------------------------------------------------------------------------
+
+
+def _noop(_state: Any) -> dict[str, Any]:
+    return {}
+
+
+class _DeltaState(TypedDict):
+    items: Annotated[list, DeltaChannel(operator.add)]
+
+
+def _delta_graph(checkpointer: Any) -> Any:
+    return (
+        StateGraph(_DeltaState)
+        .add_node("noop", _noop)
+        .add_edge(START, "noop")
+        .add_edge("noop", END)
+        .compile(checkpointer=checkpointer)
+    )
+
+
+def _drive(graph: Any, config: RunnableConfig, n: int) -> None:
+    for i in range(n):
+        graph.invoke({"items": [f"v{i}"]}, config)
+
+
+async def _adrive(graph: Any, config: RunnableConfig, n: int) -> None:
+    for i in range(n):
+        await graph.ainvoke({"items": [f"v{i}"]}, config)
+
+
+def _pick_non_root(saver: Any, config: RunnableConfig) -> RunnableConfig:
+    """Return a config pointing at a checkpoint that has at least one ancestor.
+
+    `get_delta_channel_history` walks the parent chain — calling it on the root
+    checkpoint produces `writes=[]` and no `seed`, which is uninteresting
+    for the multi-step assertions below.
+    """
+    history = list(saver.list(config))
+    assert history, "expected non-empty history"
+    # `list` yields newest→oldest; the second entry has the first entry
+    # as its parent, so its parent_config is non-None.
+    for tup in history:
+        if tup.parent_config is not None:
+            return tup.config
+    raise AssertionError("no checkpoint with a parent in history")
+
+
+async def _apick_non_root(saver: Any, config: RunnableConfig) -> RunnableConfig:
+    history = [tup async for tup in saver.alist(config)]
+    assert history, "expected non-empty history"
+    for tup in history:
+        if tup.parent_config is not None:
+            return tup.config
+    raise AssertionError("no checkpoint with a parent in history")
+
+
+# ---------------------------------------------------------------------------
+# Sync: SqliteSaver
+# ---------------------------------------------------------------------------
+
+
+def test_empty_channels_returns_empty_mapping_sync() -> None:
+    """Empty `channels` short-circuits to `{}` without touching storage."""
+    with SqliteSaver.from_conn_string(":memory:") as saver:
+        config: RunnableConfig = {"configurable": {"thread_id": "empty"}}
+        assert saver.get_delta_channel_history(config=config, channels=[]) == {}
+
+
+def test_writes_history_oldest_to_newest_sync() -> None:
+    """Per-channel writes accumulated across the walk come back oldest→newest."""
+    with SqliteSaver.from_conn_string(":memory:") as saver:
+        config: RunnableConfig = {"configurable": {"thread_id": "history-sync"}}
+        graph = _delta_graph(saver)
+        _drive(graph, config, 3)
+
+        target_cfg = _pick_non_root(saver, config)
+        result = saver.get_delta_channel_history(config=target_cfg, channels=["items"])
+
+        assert "items" in result
+        entry = result["items"]
+        assert isinstance(entry["writes"], list)
+
+        # If any writes were collected, their values should be in oldest→newest
+        # order — i.e. tagged 'v0', 'v1', ... matching invoke order.
+        write_values: list[Any] = []
+        for _task_id, channel, value in entry["writes"]:
+            assert channel == "items"
+            write_values.extend(value if isinstance(value, list) else [value])
+
+        # `_drive` invokes with payloads ['v0'], ['v1'], ['v2']. Whatever
+        # subset shows up in the chain must be a contiguous prefix in order.
+        for idx, val in enumerate(write_values):
+            assert val == f"v{idx}", (
+                f"writes not in oldest→newest order: {write_values}"
+            )
+
+
+def test_seed_present_when_snapshot_in_ancestor_sync() -> None:
+    """Inserting a `_DeltaSnapshot` blob at an ancestor → walk returns it as `seed`."""
+    with SqliteSaver.from_conn_string(":memory:") as saver:
+        config: RunnableConfig = {"configurable": {"thread_id": "seed-sync"}}
+        graph = _delta_graph(saver)
+        _drive(graph, config, 2)
+
+        # Find the oldest non-root checkpoint, then walk to its parent and
+        # rewrite that parent's `channel_values["items"]` to a real
+        # `_DeltaSnapshot`. After this surgery, calling `get_delta_channel_history`
+        # at the leaf must return the snapshot value as `seed`.
+        history = list(saver.list(config))
+        assert len(history) >= 2
+        leaf_tup = history[0]
+        # Walk to an ancestor with a parent_config (any non-root will do).
+        ancestor_tup = next(
+            (tup for tup in history if tup.parent_config is not None), None
+        )
+        assert ancestor_tup is not None
+        parent_cfg = ancestor_tup.parent_config
+        assert parent_cfg is not None
+        parent_tup = saver.get_tuple(parent_cfg)
+        assert parent_tup is not None
+
+        snapshot_value = ["seeded", "items"]
+        parent_tup.checkpoint["channel_values"]["items"] = _DeltaSnapshot(
+            snapshot_value
+        )
+        # Make sure the channel has a version so the optimized blob lookup
+        # in any future override has something to hit.
+        parent_tup.checkpoint["channel_versions"].setdefault("items", 1)
+        saver.put(
+            parent_tup.parent_config or {"configurable": parent_cfg["configurable"]},
+            parent_tup.checkpoint,
+            parent_tup.metadata,
+            {},
+        )
+
+        result = saver.get_delta_channel_history(
+            config=leaf_tup.config, channels=["items"]
+        )
+        entry = result["items"]
+        assert "seed" in entry, f"expected seed to be present, got {entry}"
+        seed = entry["seed"]
+        assert isinstance(seed, _DeltaSnapshot), (
+            f"expected _DeltaSnapshot, got {seed!r}"
+        )
+        assert seed.value == snapshot_value
+
+
+def test_seed_omitted_when_walk_reaches_root_sync() -> None:
+    """`get_delta_channel_history` on the root checkpoint → no `seed` key, no writes."""
+    with SqliteSaver.from_conn_string(":memory:") as saver:
+        config: RunnableConfig = {"configurable": {"thread_id": "root-sync"}}
+        graph = _delta_graph(saver)
+        _drive(graph, config, 1)
+
+        history = list(saver.list(config))
+        # Root is the oldest checkpoint (no parent_config).
+        root_tup = history[-1]
+        assert root_tup.parent_config is None
+
+        result = saver.get_delta_channel_history(
+            config=root_tup.config, channels=["items"]
+        )
+        entry = result["items"]
+        assert "seed" not in entry, f"root-walk should have no seed, got {entry}"
+        assert entry["writes"] == []
+
+
+# ---------------------------------------------------------------------------
+# Async: AsyncSqliteSaver
+# ---------------------------------------------------------------------------
+
+
+async def test_empty_channels_returns_empty_mapping_async() -> None:
+    """Async equivalent of the empty-channels short-circuit."""
+    async with AsyncSqliteSaver.from_conn_string(":memory:") as saver:
+        config: RunnableConfig = {"configurable": {"thread_id": "empty-async"}}
+        assert await saver.aget_delta_channel_history(config=config, channels=[]) == {}
+
+
+async def test_writes_history_oldest_to_newest_async() -> None:
+    """Async equivalent of the oldest→newest ordering check."""
+    async with AsyncSqliteSaver.from_conn_string(":memory:") as saver:
+        config: RunnableConfig = {"configurable": {"thread_id": "history-async"}}
+        graph = _delta_graph(saver)
+        await _adrive(graph, config, 3)
+
+        target_cfg = await _apick_non_root(saver, config)
+        result = await saver.aget_delta_channel_history(
+            config=target_cfg, channels=["items"]
+        )
+
+        assert "items" in result
+        entry = result["items"]
+        assert isinstance(entry["writes"], list)
+
+        write_values: list[Any] = []
+        for _task_id, channel, value in entry["writes"]:
+            assert channel == "items"
+            write_values.extend(value if isinstance(value, list) else [value])
+
+        for idx, val in enumerate(write_values):
+            assert val == f"v{idx}", (
+                f"writes not in oldest→newest order: {write_values}"
+            )
+
+
+async def test_seed_omitted_when_walk_reaches_root_async() -> None:
+    """Async equivalent of the root-walk seed-absence check."""
+    async with AsyncSqliteSaver.from_conn_string(":memory:") as saver:
+        config: RunnableConfig = {"configurable": {"thread_id": "root-async"}}
+        graph = _delta_graph(saver)
+        await _adrive(graph, config, 1)
+
+        history = [tup async for tup in saver.alist(config)]
+        root_tup = history[-1]
+        assert root_tup.parent_config is None
+
+        result = await saver.aget_delta_channel_history(
+            config=root_tup.config, channels=["items"]
+        )
+        entry = result["items"]
+        assert "seed" not in entry, f"root-walk should have no seed, got {entry}"
+        assert entry["writes"] == []

libs/checkpoint-sqlite/uv.lock

@@ -1,6 +1,10 @@
 version = 1
 revision = 3
 requires-python = ">=3.10"
+resolution-markers = [
+    "python_full_version >= '3.15'",
+    "python_full_version < '3.15'",
+]
 
 [[package]]
 name = "aiosqlite"
@@ -268,7 +272,7 @@ wheels = [
 
 [[package]]
 name = "langgraph-checkpoint"
-version = "4.0.3"
+version = "4.1.0a4"
 source = { editable = "../checkpoint" }
 dependencies = [
     { name = "langchain-core" },
@@ -316,7 +320,7 @@ test = [
 
 [[package]]
 name = "langgraph-checkpoint-sqlite"
-version = "3.0.3"
+version = "3.1.0a1"
 source = { editable = "." }
 dependencies = [
     { name = "aiosqlite" },
@@ -490,7 +494,7 @@ wheels = [
 
 [[package]]
 name = "mypy"
-version = "1.20.0"
+version = "1.20.2"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "librt", marker = "platform_python_implementation != 'PyPy'" },
@@ -499,51 +503,51 @@ dependencies = [
     { name = "tomli", marker = "python_full_version < '3.11'" },
     { name = "typing-extensions" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/f8/5c/b0089fe7fef0a994ae5ee07029ced0526082c6cfaaa4c10d40a10e33b097/mypy-1.20.0.tar.gz", hash = "sha256:eb96c84efcc33f0b5e0e04beacf00129dd963b67226b01c00b9dfc8affb464c3", size = 3815028, upload-time = "2026-03-31T16:55:14.959Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/04/af/e3d4b3e9ec91a0ff9aabfdb38692952acf49bbb899c2e4c29acb3a6da3ae/mypy-1.20.2.tar.gz", hash = "sha256:e8222c26daaafd9e8626dec58ae36029f82585890589576f769a650dd20fd665", size = 3817349, upload-time = "2026-04-21T17:12:28.473Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/4d/a2/a965c8c3fcd4fa8b84ba0d46606181b0d0a1d50f274c67877f3e9ed4882c/mypy-1.20.0-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:d99f515f95fd03a90875fdb2cca12ff074aa04490db4d190905851bdf8a549a8", size = 14430138, upload-time = "2026-03-31T16:52:37.843Z" },
-    { url = "https://files.pythonhosted.org/packages/53/6e/043477501deeb8eabbab7f1a2f6cac62cfb631806dc1d6862a04a7f5011b/mypy-1.20.0-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:bd0212976dc57a5bfeede7c219e7cd66568a32c05c9129686dd487c059c1b88a", size = 13311282, upload-time = "2026-03-31T16:55:11.021Z" },
-    { url = "https://files.pythonhosted.org/packages/65/aa/bd89b247b83128197a214f29f0632ff3c14f54d4cd70d144d157bd7d7d6e/mypy-1.20.0-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f8426d4d75d68714abc17a4292d922f6ba2cfb984b72c2278c437f6dae797865", size = 13750889, upload-time = "2026-03-31T16:52:02.909Z" },
-    { url = "https://files.pythonhosted.org/packages/fa/9d/2860be7355c45247ccc0be1501c91176318964c2a137bd4743f58ce6200e/mypy-1.20.0-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:02cca0761c75b42a20a2757ae58713276605eb29a08dd8a6e092aa347c4115ca", size = 14619788, upload-time = "2026-03-31T16:50:48.928Z" },
-    { url = "https://files.pythonhosted.org/packages/75/7f/3ef3e360c91f3de120f205c8ce405e9caf9fc52ef14b65d37073e322c114/mypy-1.20.0-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:b3a49064504be59e59da664c5e149edc1f26c67c4f8e8456f6ba6aba55033018", size = 14918849, upload-time = "2026-03-31T16:51:10.478Z" },
-    { url = "https://files.pythonhosted.org/packages/ae/72/af970dfe167ef788df7c5e6109d2ed0229f164432ce828bc9741a4250e64/mypy-1.20.0-cp310-cp310-win_amd64.whl", hash = "sha256:ebea00201737ad4391142808ed16e875add5c17f676e0912b387739f84991e13", size = 10822007, upload-time = "2026-03-31T16:50:25.268Z" },
-    { url = "https://files.pythonhosted.org/packages/93/94/ba9065c2ebe5421619aff684b793d953e438a8bfe31a320dd6d1e0706e81/mypy-1.20.0-cp310-cp310-win_arm64.whl", hash = "sha256:e80cf77847d0d3e6e3111b7b25db32a7f8762fd4b9a3a72ce53fe16a2863b281", size = 9756158, upload-time = "2026-03-31T16:48:36.213Z" },
-    { url = "https://files.pythonhosted.org/packages/6e/1c/74cb1d9993236910286865679d1c616b136b2eae468493aa939431eda410/mypy-1.20.0-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:4525e7010b1b38334516181c5b81e16180b8e149e6684cee5a727c78186b4e3b", size = 14343972, upload-time = "2026-03-31T16:49:04.887Z" },
-    { url = "https://files.pythonhosted.org/packages/d5/0d/01399515eca280386e308cf57901e68d3a52af18691941b773b3380c1df8/mypy-1.20.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:a17c5d0bdcca61ce24a35beb828a2d0d323d3fcf387d7512206888c900193367", size = 13225007, upload-time = "2026-03-31T16:50:08.151Z" },
-    { url = "https://files.pythonhosted.org/packages/56/ac/b4ba5094fb2d7fe9d2037cd8d18bbe02bcf68fd22ab9ff013f55e57ba095/mypy-1.20.0-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f75ff57defcd0f1d6e006d721ccdec6c88d4f6a7816eb92f1c4890d979d9ee62", size = 13663752, upload-time = "2026-03-31T16:49:26.064Z" },
-    { url = "https://files.pythonhosted.org/packages/db/a7/460678d3cf7da252d2288dad0c602294b6ec22a91932ec368cc11e44bb6e/mypy-1.20.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:b503ab55a836136b619b5fc21c8803d810c5b87551af8600b72eecafb0059cb0", size = 14532265, upload-time = "2026-03-31T16:53:55.077Z" },
-    { url = "https://files.pythonhosted.org/packages/a3/3e/051cca8166cf0438ae3ea80e0e7c030d7a8ab98dffc93f80a1aa3f23c1a2/mypy-1.20.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:1973868d2adbb4584a3835780b27436f06d1dc606af5be09f187aaa25be1070f", size = 14768476, upload-time = "2026-03-31T16:50:34.587Z" },
-    { url = "https://files.pythonhosted.org/packages/be/66/8e02ec184f852ed5c4abb805583305db475930854e09964b55e107cdcbc4/mypy-1.20.0-cp311-cp311-win_amd64.whl", hash = "sha256:2fcedb16d456106e545b2bfd7ef9d24e70b38ec252d2a629823a4d07ebcdb69e", size = 10818226, upload-time = "2026-03-31T16:53:15.624Z" },
-    { url = "https://files.pythonhosted.org/packages/13/4b/383ad1924b28f41e4879a74151e7a5451123330d45652da359f9183bcd45/mypy-1.20.0-cp311-cp311-win_arm64.whl", hash = "sha256:379edf079ce44ac8d2805bcf9b3dd7340d4f97aad3a5e0ebabbf9d125b84b442", size = 9750091, upload-time = "2026-03-31T16:54:12.162Z" },
-    { url = "https://files.pythonhosted.org/packages/be/dd/3afa29b58c2e57c79116ed55d700721c3c3b15955e2b6251dd165d377c0e/mypy-1.20.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:002b613ae19f4ac7d18b7e168ffe1cb9013b37c57f7411984abbd3b817b0a214", size = 14509525, upload-time = "2026-03-31T16:55:01.824Z" },
-    { url = "https://files.pythonhosted.org/packages/54/eb/227b516ab8cad9f2a13c5e7a98d28cd6aa75e9c83e82776ae6c1c4c046c7/mypy-1.20.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:a9336b5e6712f4adaf5afc3203a99a40b379049104349d747eb3e5a3aa23ac2e", size = 13326469, upload-time = "2026-03-31T16:51:41.23Z" },
-    { url = "https://files.pythonhosted.org/packages/57/d4/1ddb799860c1b5ac6117ec307b965f65deeb47044395ff01ab793248a591/mypy-1.20.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f13b3e41bce9d257eded794c0f12878af3129d80aacd8a3ee0dee51f3a978651", size = 13705953, upload-time = "2026-03-31T16:48:55.69Z" },
-    { url = "https://files.pythonhosted.org/packages/c5/b7/54a720f565a87b893182a2a393370289ae7149e4715859e10e1c05e49154/mypy-1.20.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9804c3ad27f78e54e58b32e7cb532d128b43dbfb9f3f9f06262b821a0f6bd3f5", size = 14710363, upload-time = "2026-03-31T16:53:26.948Z" },
-    { url = "https://files.pythonhosted.org/packages/b2/2a/74810274848d061f8a8ea4ac23aaad43bd3d8c1882457999c2e568341c57/mypy-1.20.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:697f102c5c1d526bdd761a69f17c6070f9892eebcb94b1a5963d679288c09e78", size = 14947005, upload-time = "2026-03-31T16:50:17.591Z" },
-    { url = "https://files.pythonhosted.org/packages/77/91/21b8ba75f958bcda75690951ce6fa6b7138b03471618959529d74b8544e2/mypy-1.20.0-cp312-cp312-win_amd64.whl", hash = "sha256:0ecd63f75fdd30327e4ad8b5704bd6d91fc6c1b2e029f8ee14705e1207212489", size = 10880616, upload-time = "2026-03-31T16:52:19.986Z" },
-    { url = "https://files.pythonhosted.org/packages/8a/15/3d8198ef97c1ca03aea010cce4f1d4f3bc5d9849e8c0140111ca2ead9fdd/mypy-1.20.0-cp312-cp312-win_arm64.whl", hash = "sha256:f194db59657c58593a3c47c6dfd7bad4ef4ac12dbc94d01b3a95521f78177e33", size = 9813091, upload-time = "2026-03-31T16:53:44.385Z" },
-    { url = "https://files.pythonhosted.org/packages/d6/a7/f64ea7bd592fa431cb597418b6dec4a47f7d0c36325fec7ac67bc8402b94/mypy-1.20.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:b20c8b0fd5877abdf402e79a3af987053de07e6fb208c18df6659f708b535134", size = 14485344, upload-time = "2026-03-31T16:49:16.78Z" },
-    { url = "https://files.pythonhosted.org/packages/bb/72/8927d84cfc90c6abea6e96663576e2e417589347eb538749a464c4c218a0/mypy-1.20.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:367e5c993ba34d5054d11937d0485ad6dfc60ba760fa326c01090fc256adf15c", size = 13327400, upload-time = "2026-03-31T16:53:08.02Z" },
-    { url = "https://files.pythonhosted.org/packages/ab/4a/11ab99f9afa41aa350178d24a7d2da17043228ea10f6456523f64b5a6cf6/mypy-1.20.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f799d9db89fc00446f03281f84a221e50018fc40113a3ba9864b132895619ebe", size = 13706384, upload-time = "2026-03-31T16:52:28.577Z" },
-    { url = "https://files.pythonhosted.org/packages/42/79/694ca73979cfb3535ebfe78733844cd5aff2e63304f59bf90585110d975a/mypy-1.20.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:555658c611099455b2da507582ea20d2043dfdfe7f5ad0add472b1c6238b433f", size = 14700378, upload-time = "2026-03-31T16:48:45.527Z" },
-    { url = "https://files.pythonhosted.org/packages/84/24/a022ccab3a46e3d2cdf2e0e260648633640eb396c7e75d5a42818a8d3971/mypy-1.20.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:efe8d70949c3023698c3fca1e94527e7e790a361ab8116f90d11221421cd8726", size = 14932170, upload-time = "2026-03-31T16:49:36.038Z" },
-    { url = "https://files.pythonhosted.org/packages/d8/9b/549228d88f574d04117e736f55958bd4908f980f9f5700a07aeb85df005b/mypy-1.20.0-cp313-cp313-win_amd64.whl", hash = "sha256:f49590891d2c2f8a9de15614e32e459a794bcba84693c2394291a2038bbaaa69", size = 10888526, upload-time = "2026-03-31T16:50:59.827Z" },
-    { url = "https://files.pythonhosted.org/packages/91/17/15095c0e54a8bc04d22d4ff06b2139d5f142c2e87520b4e39010c4862771/mypy-1.20.0-cp313-cp313-win_arm64.whl", hash = "sha256:76a70bf840495729be47510856b978f1b0ec7d08f257ca38c9d932720bf6b43e", size = 9816456, upload-time = "2026-03-31T16:49:59.537Z" },
-    { url = "https://files.pythonhosted.org/packages/4e/0e/6ca4a84cbed9e62384bc0b2974c90395ece5ed672393e553996501625fc5/mypy-1.20.0-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:0f42dfaab7ec1baff3b383ad7af562ab0de573c5f6edb44b2dab016082b89948", size = 14483331, upload-time = "2026-03-31T16:52:57.999Z" },
-    { url = "https://files.pythonhosted.org/packages/7d/c5/5fe9d8a729dd9605064691816243ae6c49fde0bd28f6e5e17f6a24203c43/mypy-1.20.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:31b5dbb55293c1bd27c0fc813a0d2bb5ceef9d65ac5afa2e58f829dab7921fd5", size = 13342047, upload-time = "2026-03-31T16:54:21.555Z" },
-    { url = "https://files.pythonhosted.org/packages/4c/33/e18bcfa338ca4e6b2771c85d4c5203e627d0c69d9de5c1a2cf2ba13320ba/mypy-1.20.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:49d11c6f573a5a08f77fad13faff2139f6d0730ebed2cfa9b3d2702671dd7188", size = 13719585, upload-time = "2026-03-31T16:51:53.89Z" },
-    { url = "https://files.pythonhosted.org/packages/6b/8d/93491ff7b79419edc7eabf95cb3b3f7490e2e574b2855c7c7e7394ff933f/mypy-1.20.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:7d3243c406773185144527f83be0e0aefc7bf4601b0b2b956665608bf7c98a83", size = 14685075, upload-time = "2026-03-31T16:54:04.464Z" },
-    { url = "https://files.pythonhosted.org/packages/b5/9d/d924b38a4923f8d164bf2b4ec98bf13beaf6e10a5348b4b137eadae40a6e/mypy-1.20.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:a79c1eba7ac4209f2d850f0edd0a2f8bba88cbfdfefe6fb76a19e9d4fe5e71a2", size = 14919141, upload-time = "2026-03-31T16:54:51.785Z" },
-    { url = "https://files.pythonhosted.org/packages/59/98/1da9977016678c0b99d43afe52ed00bb3c1a0c4c995d3e6acca1a6ebb9b4/mypy-1.20.0-cp314-cp314-win_amd64.whl", hash = "sha256:00e047c74d3ec6e71a2eb88e9ea551a2edb90c21f993aefa9e0d2a898e0bb732", size = 11050925, upload-time = "2026-03-31T16:51:30.758Z" },
-    { url = "https://files.pythonhosted.org/packages/5e/e3/ba0b7a3143e49a9c4f5967dde6ea4bf8e0b10ecbbcca69af84027160ee89/mypy-1.20.0-cp314-cp314-win_arm64.whl", hash = "sha256:931a7630bba591593dcf6e97224a21ff80fb357e7982628d25e3c618e7f598ef", size = 10001089, upload-time = "2026-03-31T16:49:43.632Z" },
-    { url = "https://files.pythonhosted.org/packages/12/28/e617e67b3be9d213cda7277913269c874eb26472489f95d09d89765ce2d8/mypy-1.20.0-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:26c8b52627b6552f47ff11adb4e1509605f094e29815323e487fc0053ebe93d1", size = 15534710, upload-time = "2026-03-31T16:52:12.506Z" },
-    { url = "https://files.pythonhosted.org/packages/6e/0c/3b5f2d3e45dc7169b811adce8451679d9430399d03b168f9b0489f43adaa/mypy-1.20.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:39362cdb4ba5f916e7976fccecaab1ba3a83e35f60fa68b64e9a70e221bb2436", size = 14393013, upload-time = "2026-03-31T16:54:41.186Z" },
-    { url = "https://files.pythonhosted.org/packages/a3/49/edc8b0aa145cc09c1c74f7ce2858eead9329931dcbbb26e2ad40906daa4e/mypy-1.20.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:34506397dbf40c15dc567635d18a21d33827e9ab29014fb83d292a8f4f8953b6", size = 15047240, upload-time = "2026-03-31T16:54:31.955Z" },
-    { url = "https://files.pythonhosted.org/packages/42/37/a946bb416e37a57fa752b3100fd5ede0e28df94f92366d1716555d47c454/mypy-1.20.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:555493c44a4f5a1b58d611a43333e71a9981c6dbe26270377b6f8174126a0526", size = 15858565, upload-time = "2026-03-31T16:53:36.997Z" },
-    { url = "https://files.pythonhosted.org/packages/2f/99/7690b5b5b552db1bd4ff362e4c0eb3107b98d680835e65823fbe888c8b78/mypy-1.20.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:2721f0ce49cb74a38f00c50da67cb7d36317b5eda38877a49614dc018e91c787", size = 16087874, upload-time = "2026-03-31T16:52:48.313Z" },
-    { url = "https://files.pythonhosted.org/packages/aa/76/53e893a498138066acd28192b77495c9357e5a58cc4be753182846b43315/mypy-1.20.0-cp314-cp314t-win_amd64.whl", hash = "sha256:47781555a7aa5fedcc2d16bcd72e0dc83eb272c10dd657f9fb3f9cc08e2e6abb", size = 12572380, upload-time = "2026-03-31T16:49:52.454Z" },
-    { url = "https://files.pythonhosted.org/packages/76/9c/6dbdae21f01b7aacddc2c0bbf3c5557aa547827fdf271770fe1e521e7093/mypy-1.20.0-cp314-cp314t-win_arm64.whl", hash = "sha256:c70380fe5d64010f79fb863b9081c7004dd65225d2277333c219d93a10dad4dd", size = 10381174, upload-time = "2026-03-31T16:51:20.179Z" },
-    { url = "https://files.pythonhosted.org/packages/21/66/4d734961ce167f0fd8380769b3b7c06dbdd6ff54c2190f3f2ecd22528158/mypy-1.20.0-py3-none-any.whl", hash = "sha256:a6e0641147cbfa7e4e94efdb95c2dab1aff8cfc159ded13e07f308ddccc8c48e", size = 2636365, upload-time = "2026-03-31T16:51:44.911Z" },
+    { url = "https://files.pythonhosted.org/packages/76/97/ce2502df2cecf2ef997b6c6527c4a223b92feb9e7b790cdc8dcd683f3a8a/mypy-1.20.2-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:cf5a4db6dca263010e2c7bff081c89383c72d187ba2cf4c44759aac970e2f0c4", size = 14457059, upload-time = "2026-04-21T17:06:14.935Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/34/417ee60b822cc80c0f3dc9f495ad7fd8dbb8d8b2cf4baf22d4046d25d01d/mypy-1.20.2-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:7b0e817b518bff7facd7f85ea05b643ad8bdcce684cf29784987b0a7c8e1f997", size = 13346816, upload-time = "2026-04-21T17:10:41.433Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/85/e20951978702df58379d0bcc2e8f7ccdca4e78cd7dc66dd3ddbf9b29d517/mypy-1.20.2-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:97d7b9a485b40f8ca425460e89bf1da2814625b2da627c0dcc6aa46c92631d14", size = 13772593, upload-time = "2026-04-21T17:08:11.24Z" },
+    { url = "https://files.pythonhosted.org/packages/63/a5/5441a13259ec516c56fd5de0fd96a69a9590ae6c5e5d3e5174aa84b97973/mypy-1.20.2-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:1e1c12f6d2db3d78b909b5f77513c11eb7f2dd2782b96a3ab6dffc7d44575c99", size = 14656635, upload-time = "2026-04-21T17:09:54.042Z" },
+    { url = "https://files.pythonhosted.org/packages/3b/51/b89c69157c5e1f19fd125a65d991166a26906e7902f026f00feebbcfa2b9/mypy-1.20.2-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:89dce27e142d25ffbc154c1819383b69f2e9234dc4ed4766f42e0e8cb264ab5c", size = 14943278, upload-time = "2026-04-21T17:09:15.599Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/44/6b0eeecfe96d7cce1d71c66b8e03cb304aa70ec11f1955dc1d6b46aca3c3/mypy-1.20.2-cp310-cp310-win_amd64.whl", hash = "sha256:f376e37f9bf2a946872fc5fd1199c99310748e3c26c7a26683f13f8bdb756cbd", size = 10851915, upload-time = "2026-04-21T17:06:03.5Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/36/6593dc88545d75fb96416184be5392da5e2a8e8c2802a8597913e16ae25c/mypy-1.20.2-cp310-cp310-win_arm64.whl", hash = "sha256:6e2b469efd811707bc530fd1effef0f5d6eebcb7fe376affae69025da4b979a2", size = 9786676, upload-time = "2026-04-21T17:07:02.035Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/4d/9ebeae211caccbdaddde7ed5e31dfcf57faac66be9b11deb1dc6526c8078/mypy-1.20.2-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:4077797a273e56e8843d001e9dfe4ba10e33323d6ade647ff260e5cd97d9758c", size = 14371307, upload-time = "2026-04-21T17:08:56.442Z" },
+    { url = "https://files.pythonhosted.org/packages/95/d7/93473d34b61f04fac1aecc01368485c89c5c4af7a4b9a0cab5d77d04b63f/mypy-1.20.2-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:cdecf62abcc4292500d7858aeae87a1f8f1150f4c4dd08fb0b336ee79b2a6df3", size = 13258917, upload-time = "2026-04-21T17:05:50.978Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/30/3dd903e8bafb7b5f7bf87fcd58f8382086dea2aa19f0a7b357f21f63071b/mypy-1.20.2-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c566c3a88b6ece59b3d70f65bedef17304f48eb52ff040a6a18214e1917b3254", size = 13700516, upload-time = "2026-04-21T17:11:33.161Z" },
+    { url = "https://files.pythonhosted.org/packages/07/05/c61a140aba4c729ac7bc99ae26fc627c78a6e08f5b9dd319244ea71a3d7e/mypy-1.20.2-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0deb80d062b2479f2c87ae568f89845afc71d11bc41b04179e58165fd9f31e98", size = 14562889, upload-time = "2026-04-21T17:05:27.674Z" },
+    { url = "https://files.pythonhosted.org/packages/fd/87/da78243742ffa8a36d98c3010f0d829f93d5da4e6786f1a1a6f2ad616502/mypy-1.20.2-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:bba9ad231e92a3e424b3e56b65aa17704993425bba97e302c832f9466bb85bac", size = 14803844, upload-time = "2026-04-21T17:10:06.2Z" },
+    { url = "https://files.pythonhosted.org/packages/37/52/10a1ddf91b40f843943a3c6db51e2df59c9e237f29d355e95eaab427461f/mypy-1.20.2-cp311-cp311-win_amd64.whl", hash = "sha256:baf593f2765fa3a6b1ef95807dbaa3d25b594f6a52adcc506a6b9cb115e1be67", size = 10846300, upload-time = "2026-04-21T17:12:23.886Z" },
+    { url = "https://files.pythonhosted.org/packages/20/02/f9a4415b664c53bd34d6709be59da303abcae986dc4ac847b402edb6fa1e/mypy-1.20.2-cp311-cp311-win_arm64.whl", hash = "sha256:20175a1c0f49863946ec20b7f63255768058ac4f07d2b9ded6a6b46cfb5a9100", size = 9779498, upload-time = "2026-04-21T17:09:23.695Z" },
+    { url = "https://files.pythonhosted.org/packages/71/4e/7560e4528db9e9b147e4c0f22660466bf30a0a1fe3d63d1b9d3b0fd354ee/mypy-1.20.2-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:4dbfcf869f6b0517f70cf0030ba6ea1d6645e132337a7d5204a18d8d5636c02b", size = 14539393, upload-time = "2026-04-21T17:07:12.52Z" },
+    { url = "https://files.pythonhosted.org/packages/32/d9/34a5efed8124f5a9234f55ac6a4ced4201e2c5b81e1109c49ad23190ec8c/mypy-1.20.2-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:4b6481b228d072315b053210b01ac320e1be243dc17f9e5887ef167f23f5fae4", size = 13361642, upload-time = "2026-04-21T17:06:53.742Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/14/eb377acf78c03c92d566a1510cda8137348215b5335085ef662ab82ecd3a/mypy-1.20.2-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:34397cdced6b90b836e38182076049fdb41424322e0b0728c946b0939ebdf9f6", size = 13740347, upload-time = "2026-04-21T17:12:04.73Z" },
+    { url = "https://files.pythonhosted.org/packages/b9/94/7e4634a32b641aa1c112422eed1bbece61ee16205f674190e8b536f884de/mypy-1.20.2-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:a5da6976f20cae27059ea8d0c86e7cef3de720e04c4bb9ee18e3690fdb792066", size = 14734042, upload-time = "2026-04-21T17:07:43.16Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/f3/f7e62395cb7f434541b4491a01149a4439e28ace4c0c632bbf5431e92d1f/mypy-1.20.2-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:56908d7e08318d39f85b1f0c6cfd47b0cac1a130da677630dac0de3e0623e102", size = 14964958, upload-time = "2026-04-21T17:11:00.665Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/0d/47e3c3a0ec2a876e35aeac365df3cac7776c36bbd4ed18cc521e1b9d255b/mypy-1.20.2-cp312-cp312-win_amd64.whl", hash = "sha256:d52ad8d78522da1d308789df651ee5379088e77c76cb1994858d40a426b343b9", size = 10911340, upload-time = "2026-04-21T17:10:49.179Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/b2/6c852d72e0ea8b01f49da817fb52539993cde327e7d010e0103dc12d0dac/mypy-1.20.2-cp312-cp312-win_arm64.whl", hash = "sha256:785b08db19c9f214dc37d65f7c165d19a30fcecb48abfa30f31b01b5acaabb58", size = 9833947, upload-time = "2026-04-21T17:09:05.267Z" },
+    { url = "https://files.pythonhosted.org/packages/5b/c4/b93812d3a192c9bcf5df405bd2f30277cd0e48106a14d1023c7f6ed6e39b/mypy-1.20.2-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:edfbfca868cdd6bd8d974a60f8a3682f5565d3f5c99b327640cedd24c4264026", size = 14524670, upload-time = "2026-04-21T17:10:30.737Z" },
+    { url = "https://files.pythonhosted.org/packages/f3/47/42c122501bff18eaf1e8f457f5c017933452d8acdc52918a9f59f6812955/mypy-1.20.2-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:e2877a02380adfcdbc69071a0f74d6e9dbbf593c0dc9d174e1f223ffd5281943", size = 13336218, upload-time = "2026-04-21T17:08:44.069Z" },
+    { url = "https://files.pythonhosted.org/packages/92/8f/75bbc92f41725fbd585fb17b440b1119b576105df1013622983e18640a93/mypy-1.20.2-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:7488448de6007cd5177c6cea0517ac33b4c0f5ee9b5e9f2be51ce75511a85517", size = 13724906, upload-time = "2026-04-21T17:08:01.02Z" },
+    { url = "https://files.pythonhosted.org/packages/a1/32/4c49da27a606167391ff0c39aa955707a00edc500572e562f7c36c08a71f/mypy-1.20.2-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:bb9c2fa06887e21d6a3a868762acb82aec34e2c6fd0174064f27c93ede68ad15", size = 14726046, upload-time = "2026-04-21T17:11:22.354Z" },
+    { url = "https://files.pythonhosted.org/packages/7f/fc/4e354a1bd70216359deb0c9c54847ee6b32ef78dfb09f5131ff99b494078/mypy-1.20.2-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:9d56a78b646f2e3daa865bc70cd5ec5a46c50045801ca8ff17a0c43abc97e3ee", size = 14955587, upload-time = "2026-04-21T17:12:16.033Z" },
+    { url = "https://files.pythonhosted.org/packages/62/b2/c0f2056e9eb8f08c62cafd9715e4584b89132bdc832fcf85d27d07b5f3e5/mypy-1.20.2-cp313-cp313-win_amd64.whl", hash = "sha256:2a4102b03bb7481d9a91a6da8d174740c9c8c4401024684b9ca3b7cc5e49852f", size = 10922681, upload-time = "2026-04-21T17:06:35.842Z" },
+    { url = "https://files.pythonhosted.org/packages/e5/14/065e333721f05de8ef683d0aa804c23026bcc287446b61cac657b902ccac/mypy-1.20.2-cp313-cp313-win_arm64.whl", hash = "sha256:a95a9248b0c6fd933a442c03c3b113c3b61320086b88e2c444676d3fd1ca3330", size = 9830560, upload-time = "2026-04-21T17:07:51.023Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/d1/b4ec96b0ecc620a4443570c6e95c867903428cfcde4206518eafdd5880c3/mypy-1.20.2-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:419413398fe250aae057fd2fe50166b61077083c9b82754c341cf4fd73038f30", size = 14524561, upload-time = "2026-04-21T17:06:27.325Z" },
+    { url = "https://files.pythonhosted.org/packages/3a/63/d2c2ff4fa66bc49477d32dfa26e8a167ba803ea6a69c5efb416036909d30/mypy-1.20.2-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:e73c07f23009962885c197ccb9b41356a30cc0e5a1d0c2ea8fd8fb1362d7f924", size = 13363883, upload-time = "2026-04-21T17:11:11.239Z" },
+    { url = "https://files.pythonhosted.org/packages/2a/56/983916806bf4eddeaaa2c9230903c3669c6718552a921154e1c5182c701f/mypy-1.20.2-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0c64e5973df366b747646fc98da921f9d6eba9716d57d1db94a83c026a08e0fb", size = 13742945, upload-time = "2026-04-21T17:08:34.181Z" },
+    { url = "https://files.pythonhosted.org/packages/19/65/0cd9285ab010ee8214c83d67c6b49417c40d86ce46f1aa109457b5a9b8d7/mypy-1.20.2-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:5a65aa591af023864fd08a97da9974e919452cfe19cb146c8a5dc692626445dc", size = 14706163, upload-time = "2026-04-21T17:05:15.51Z" },
+    { url = "https://files.pythonhosted.org/packages/94/97/48ff3b297cafcc94d185243a9190836fb1b01c1b0918fff64e941e973cc9/mypy-1.20.2-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:4fef51b01e638974a6e69885687e9bd40c8d1e09a6cd291cca0619625cf1f558", size = 14938677, upload-time = "2026-04-21T17:05:39.562Z" },
+    { url = "https://files.pythonhosted.org/packages/fd/a1/1b4233d255bdd0b38a1f284feeb1c143ca508c19184964e22f8d837ec851/mypy-1.20.2-cp314-cp314-win_amd64.whl", hash = "sha256:913485a03f1bcf5d279409a9d2b9ed565c151f61c09f29991e5faa14033da4c8", size = 11089322, upload-time = "2026-04-21T17:06:44.29Z" },
+    { url = "https://files.pythonhosted.org/packages/78/c2/ce7ee2ba36aeb954ba50f18fa25d9c1188578654b97d02a66a15b6f09531/mypy-1.20.2-cp314-cp314-win_arm64.whl", hash = "sha256:c3bae4f855d965b5453784300c12ffc63a548304ac7f99e55d4dc7c898673aa3", size = 10017775, upload-time = "2026-04-21T17:07:20.732Z" },
+    { url = "https://files.pythonhosted.org/packages/4e/a1/9d93a7d0b5859af0ead82b4888b46df6c8797e1bc5e1e262a08518c6d48e/mypy-1.20.2-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:2de3dcea53babc1c3237a19002bc3d228ce1833278f093b8d619e06e7cc79609", size = 15549002, upload-time = "2026-04-21T17:08:23.107Z" },
+    { url = "https://files.pythonhosted.org/packages/00/d2/09a6a10ee1bf0008f6c144d9676f2ca6a12512151b4e0ad0ff6c4fac5337/mypy-1.20.2-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:52b176444e2e5054dfcbcb8c75b0b719865c96247b37407184bbfca5c353f2c2", size = 14401942, upload-time = "2026-04-21T17:07:31.837Z" },
+    { url = "https://files.pythonhosted.org/packages/57/da/9594b75c3c019e805250bed3583bdf4443ff9e6ef08f97e39ae308cb06f2/mypy-1.20.2-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:688c3312e5dadb573a2c69c82af3a298d43ecf9e6d264e0f95df960b5f6ac19c", size = 15041649, upload-time = "2026-04-21T17:09:34.653Z" },
+    { url = "https://files.pythonhosted.org/packages/97/77/f75a65c278e6e8eba2071f7f5a90481891053ecc39878cc444634d892abe/mypy-1.20.2-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:29752dbbf8cc53f89f6ac096d363314333045c257c9c75cbd189ca2de0455744", size = 15864588, upload-time = "2026-04-21T17:11:44.936Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/46/1a4e1c66e96c1a3246ddf5403d122ac9b0a8d2b7e65730b9d6533ba7a6d3/mypy-1.20.2-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:803203d2b6ea644982c644895c2f78b28d0e208bba7b27d9b921e0ec5eb207c6", size = 16093956, upload-time = "2026-04-21T17:10:17.683Z" },
+    { url = "https://files.pythonhosted.org/packages/5a/2c/78a8851264dec38cd736ca5b8bc9380674df0dd0be7792f538916157716c/mypy-1.20.2-cp314-cp314t-win_amd64.whl", hash = "sha256:9bcb8aa397ff0093c824182fd76a935a9ba7ad097fcbef80ae89bf6c1731d8ec", size = 12568661, upload-time = "2026-04-21T17:11:54.473Z" },
+    { url = "https://files.pythonhosted.org/packages/83/01/cd7318aa03493322ce275a0e14f4f52b8896335e4e79d4fb8153a7ad2b77/mypy-1.20.2-cp314-cp314t-win_arm64.whl", hash = "sha256:e061b58443f1736f8a37c48978d7ab581636d6ab03e3d4f99e3fa90463bb9382", size = 10389240, upload-time = "2026-04-21T17:09:42.719Z" },
+    { url = "https://files.pythonhosted.org/packages/28/9a/f23c163e25b11074188251b0b5a0342625fc1cdb6af604757174fa9acc9b/mypy-1.20.2-py3-none-any.whl", hash = "sha256:a94c5a76ab46c5e6257c7972b6c8cff0574201ca7dc05647e33e795d78680563", size = 2637314, upload-time = "2026-04-21T17:05:54.5Z" },
 ]
 
 [[package]]
@@ -1023,27 +1027,27 @@ wheels = [
 
 [[package]]
 name = "ruff"
-version = "0.15.8"
+version = "0.15.12"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/14/b0/73cf7550861e2b4824950b8b52eebdcc5adc792a00c514406556c5b80817/ruff-0.15.8.tar.gz", hash = "sha256:995f11f63597ee362130d1d5a327a87cb6f3f5eae3094c620bcc632329a4d26e", size = 4610921, upload-time = "2026-03-26T18:39:38.675Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/99/43/3291f1cc9106f4c63bdce7a8d0df5047fe8422a75b091c16b5e9355e0b11/ruff-0.15.12.tar.gz", hash = "sha256:ecea26adb26b4232c0c2ca19ccbc0083a68344180bba2a600605538ce51a40a6", size = 4643852, upload-time = "2026-04-24T18:17:14.305Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/4a/92/c445b0cd6da6e7ae51e954939cb69f97e008dbe750cfca89b8cedc081be7/ruff-0.15.8-py3-none-linux_armv6l.whl", hash = "sha256:cbe05adeba76d58162762d6b239c9056f1a15a55bd4b346cfd21e26cd6ad7bc7", size = 10527394, upload-time = "2026-03-26T18:39:41.566Z" },
-    { url = "https://files.pythonhosted.org/packages/eb/92/f1c662784d149ad1414cae450b082cf736430c12ca78367f20f5ed569d65/ruff-0.15.8-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:d3e3d0b6ba8dca1b7ef9ab80a28e840a20070c4b62e56d675c24f366ef330570", size = 10905693, upload-time = "2026-03-26T18:39:30.364Z" },
-    { url = "https://files.pythonhosted.org/packages/ca/f2/7a631a8af6d88bcef997eb1bf87cc3da158294c57044aafd3e17030613de/ruff-0.15.8-py3-none-macosx_11_0_arm64.whl", hash = "sha256:6ee3ae5c65a42f273f126686353f2e08ff29927b7b7e203b711514370d500de3", size = 10323044, upload-time = "2026-03-26T18:39:33.37Z" },
-    { url = "https://files.pythonhosted.org/packages/67/18/1bf38e20914a05e72ef3b9569b1d5c70a7ef26cd188d69e9ca8ef588d5bf/ruff-0.15.8-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:fdce027ada77baa448077ccc6ebb2fa9c3c62fd110d8659d601cf2f475858d94", size = 10629135, upload-time = "2026-03-26T18:39:44.142Z" },
-    { url = "https://files.pythonhosted.org/packages/d2/e9/138c150ff9af60556121623d41aba18b7b57d95ac032e177b6a53789d279/ruff-0.15.8-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:12e617fc01a95e5821648a6df341d80456bd627bfab8a829f7cfc26a14a4b4a3", size = 10348041, upload-time = "2026-03-26T18:39:52.178Z" },
-    { url = "https://files.pythonhosted.org/packages/02/f1/5bfb9298d9c323f842c5ddeb85f1f10ef51516ac7a34ba446c9347d898df/ruff-0.15.8-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:432701303b26416d22ba696c39f2c6f12499b89093b61360abc34bcc9bf07762", size = 11121987, upload-time = "2026-03-26T18:39:55.195Z" },
-    { url = "https://files.pythonhosted.org/packages/10/11/6da2e538704e753c04e8d86b1fc55712fdbdcc266af1a1ece7a51fff0d10/ruff-0.15.8-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:d910ae974b7a06a33a057cb87d2a10792a3b2b3b35e33d2699fdf63ec8f6b17a", size = 11951057, upload-time = "2026-03-26T18:39:19.18Z" },
-    { url = "https://files.pythonhosted.org/packages/83/f0/c9208c5fd5101bf87002fed774ff25a96eea313d305f1e5d5744698dc314/ruff-0.15.8-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:2033f963c43949d51e6fdccd3946633c6b37c484f5f98c3035f49c27395a8ab8", size = 11464613, upload-time = "2026-03-26T18:40:06.301Z" },
-    { url = "https://files.pythonhosted.org/packages/f8/22/d7f2fabdba4fae9f3b570e5605d5eb4500dcb7b770d3217dca4428484b17/ruff-0.15.8-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:0f29b989a55572fb885b77464cf24af05500806ab4edf9a0fd8977f9759d85b1", size = 11257557, upload-time = "2026-03-26T18:39:57.972Z" },
-    { url = "https://files.pythonhosted.org/packages/71/8c/382a9620038cf6906446b23ce8632ab8c0811b8f9d3e764f58bedd0c9a6f/ruff-0.15.8-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:ac51d486bf457cdc985a412fb1801b2dfd1bd8838372fc55de64b1510eff4bec", size = 11169440, upload-time = "2026-03-26T18:39:22.205Z" },
-    { url = "https://files.pythonhosted.org/packages/4d/0d/0994c802a7eaaf99380085e4e40c845f8e32a562e20a38ec06174b52ef24/ruff-0.15.8-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:c9861eb959edab053c10ad62c278835ee69ca527b6dcd72b47d5c1e5648964f6", size = 10605963, upload-time = "2026-03-26T18:39:46.682Z" },
-    { url = "https://files.pythonhosted.org/packages/19/aa/d624b86f5b0aad7cef6bbf9cd47a6a02dfdc4f72c92a337d724e39c9d14b/ruff-0.15.8-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:8d9a5b8ea13f26ae90838afc33f91b547e61b794865374f114f349e9036835fb", size = 10357484, upload-time = "2026-03-26T18:39:49.176Z" },
-    { url = "https://files.pythonhosted.org/packages/35/c3/e0b7835d23001f7d999f3895c6b569927c4d39912286897f625736e1fd04/ruff-0.15.8-py3-none-musllinux_1_2_i686.whl", hash = "sha256:c2a33a529fb3cbc23a7124b5c6ff121e4d6228029cba374777bd7649cc8598b8", size = 10830426, upload-time = "2026-03-26T18:40:03.702Z" },
-    { url = "https://files.pythonhosted.org/packages/f0/51/ab20b322f637b369383adc341d761eaaa0f0203d6b9a7421cd6e783d81b9/ruff-0.15.8-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:75e5cd06b1cf3f47a3996cfc999226b19aa92e7cce682dcd62f80d7035f98f49", size = 11345125, upload-time = "2026-03-26T18:39:27.799Z" },
-    { url = "https://files.pythonhosted.org/packages/37/e6/90b2b33419f59d0f2c4c8a48a4b74b460709a557e8e0064cf33ad894f983/ruff-0.15.8-py3-none-win32.whl", hash = "sha256:bc1f0a51254ba21767bfa9a8b5013ca8149dcf38092e6a9eb704d876de94dc34", size = 10571959, upload-time = "2026-03-26T18:39:36.117Z" },
-    { url = "https://files.pythonhosted.org/packages/1f/a2/ef467cb77099062317154c63f234b8a7baf7cb690b99af760c5b68b9ee7f/ruff-0.15.8-py3-none-win_amd64.whl", hash = "sha256:04f79eff02a72db209d47d665ba7ebcad609d8918a134f86cb13dd132159fc89", size = 11743893, upload-time = "2026-03-26T18:39:25.01Z" },
-    { url = "https://files.pythonhosted.org/packages/15/e2/77be4fff062fa78d9b2a4dea85d14785dac5f1d0c1fb58ed52331f0ebe28/ruff-0.15.8-py3-none-win_arm64.whl", hash = "sha256:cf891fa8e3bb430c0e7fac93851a5978fc99c8fa2c053b57b118972866f8e5f2", size = 11048175, upload-time = "2026-03-26T18:40:01.06Z" },
+    { url = "https://files.pythonhosted.org/packages/c3/6e/e78ffb61d4686f3d96ba3df2c801161843746dcbcbb17a1e927d4829312b/ruff-0.15.12-py3-none-linux_armv6l.whl", hash = "sha256:f86f176e188e94d6bdbc09f09bfd9dc729059ad93d0e7390b5a73efe19f8861c", size = 10640713, upload-time = "2026-04-24T18:17:22.841Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/08/a317bc231fb9e7b93e4ef3089501e51922ff88d6936ce5cf870c4fe55419/ruff-0.15.12-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:e3bcd123364c3770b8e1b7baaf343cc99a35f197c5c6e8af79015c666c423a6c", size = 11069267, upload-time = "2026-04-24T18:17:30.105Z" },
+    { url = "https://files.pythonhosted.org/packages/aa/a4/f828e9718d3dce1f5f11c39c4f65afd32783c8b2aebb2e3d259e492c47bd/ruff-0.15.12-py3-none-macosx_11_0_arm64.whl", hash = "sha256:fe87510d000220aa1ed530d4448a7c696a0cae1213e5ec30e5874287b66557b5", size = 10397182, upload-time = "2026-04-24T18:17:07.177Z" },
+    { url = "https://files.pythonhosted.org/packages/71/e0/3310fc6d1b5e1fdea22bf3b1b807c7e187b581021b0d7d4514cccdb5fb71/ruff-0.15.12-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:84a1630093121375a3e2a95b4a6dc7b59e2b4ee76216e32d81aae550a832d002", size = 10758012, upload-time = "2026-04-24T18:16:55.759Z" },
+    { url = "https://files.pythonhosted.org/packages/11/c1/a606911aee04c324ddaa883ae418f3569792fd3c4a10c50e0dd0a2311e1e/ruff-0.15.12-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:fb129f40f114f089ebe0ca56c0d251cf2061b17651d464bb6478dc01e69f11f5", size = 10447479, upload-time = "2026-04-24T18:16:51.677Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/68/4201e8444f0894f21ab4aeeaee68aa4f10b51613514a20d80bd628d57e88/ruff-0.15.12-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:b0c862b172d695db7598426b8af465e7e9ac00a3ea2a3630ee67eb82e366aaa6", size = 11234040, upload-time = "2026-04-24T18:17:16.529Z" },
+    { url = "https://files.pythonhosted.org/packages/34/ff/8a6d6cf4ccc23fd67060874e832c18919d1557a0611ebef03fdb01fff11e/ruff-0.15.12-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:2849ea9f3484c3aca43a82f484210370319e7170df4dfe4843395ddf6c57bc33", size = 12087377, upload-time = "2026-04-24T18:17:04.944Z" },
+    { url = "https://files.pythonhosted.org/packages/85/f6/c669cf73f5152f623d34e69866a46d5e6185816b19fcd5b6dd8a2d299922/ruff-0.15.12-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:9e77c7e51c07fe396826d5969a5b846d9cd4c402535835fb6e21ce8b28fef847", size = 11367784, upload-time = "2026-04-24T18:17:25.409Z" },
+    { url = "https://files.pythonhosted.org/packages/e8/39/c61d193b8a1daaa8977f7dea9e8d8ba866e02ea7b65d32f6861693aa4c12/ruff-0.15.12-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:83b2f4f2f3b1026b5fb449b467d9264bf22067b600f7b6f41fc5958909f449d0", size = 11344088, upload-time = "2026-04-24T18:17:12.258Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/8d/49afab3645e31e12c590acb6d3b5b69d7aab5b81926dbaf7461f9441f37a/ruff-0.15.12-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:9ba3b8f1afd7e2e43d8943e55f249e13f9682fde09711644a6e7290eb4f3e339", size = 11271770, upload-time = "2026-04-24T18:17:02.457Z" },
+    { url = "https://files.pythonhosted.org/packages/46/06/33f41fe94403e2b755481cdfb9b7ef3e4e0ed031c4581124658d935d52b4/ruff-0.15.12-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:e852ba9fdc890655e1d78f2df1499efbe0e54126bd405362154a75e2bde159c5", size = 10719355, upload-time = "2026-04-24T18:17:27.648Z" },
+    { url = "https://files.pythonhosted.org/packages/0d/59/18aa4e014debbf559670e4048e39260a85c7fcee84acfd761ac01e7b8d35/ruff-0.15.12-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:dd8aed930da53780d22fc70bdf84452c843cf64f8cb4eb38984319c24c5cd5fd", size = 10462758, upload-time = "2026-04-24T18:17:32.347Z" },
+    { url = "https://files.pythonhosted.org/packages/25/e7/cc9f16fd0f3b5fddcbd7ec3d6ae30c8f3fde1047f32a4093a98d633c6570/ruff-0.15.12-py3-none-musllinux_1_2_i686.whl", hash = "sha256:01da3988d225628b709493d7dc67c3b9b12c0210016b08690ef9bd27970b262b", size = 10953498, upload-time = "2026-04-24T18:17:20.674Z" },
+    { url = "https://files.pythonhosted.org/packages/72/7a/a9ba7f98c7a575978698f4230c5e8cc54bbc761af34f560818f933dafa0c/ruff-0.15.12-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:9cae0f92bd5700d1213188b31cd3bdd2b315361296d10b96b8e2337d3d11f53e", size = 11447765, upload-time = "2026-04-24T18:17:09.755Z" },
+    { url = "https://files.pythonhosted.org/packages/ea/f9/0ae446942c846b8266059ad8a30702a35afae55f5cdc54c5adf8d7afdc27/ruff-0.15.12-py3-none-win32.whl", hash = "sha256:d0185894e038d7043ba8fd6aee7499ece6462dc0ea9f1e260c7451807c714c20", size = 10657277, upload-time = "2026-04-24T18:17:18.591Z" },
+    { url = "https://files.pythonhosted.org/packages/33/f1/9614e03e1cdcbf9437570b5400ced8a720b5db22b28d8e0f1bda429f660d/ruff-0.15.12-py3-none-win_amd64.whl", hash = "sha256:c87a162d61ab3adca47c03f7f717c68672edec7d1b5499e652331780fe74950d", size = 11837758, upload-time = "2026-04-24T18:17:00.113Z" },
+    { url = "https://files.pythonhosted.org/packages/c0/98/6beb4b351e472e5f4c4613f7c35a5290b8be2497e183825310c4c3a3984b/ruff-0.15.12-py3-none-win_arm64.whl", hash = "sha256:a538f7a82d061cee7be55542aca1d86d1393d55d81d4fcc314370f4340930d4f", size = 11120821, upload-time = "2026-04-24T18:16:57.979Z" },
 ]
 
 [[package]]

libs/checkpoint/langgraph/checkpoint/base/__init__.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import copy
 import logging
 from collections.abc import AsyncIterator, Collection, Iterator, Mapping, Sequence
-from typing import (  # noqa: UP035
+from typing import (
     Any,
     Generic,
     Literal,
@@ -13,6 +13,7 @@ from typing import (  # noqa: UP035
 )
 
 from langchain_core.runnables import RunnableConfig
+from typing_extensions import NotRequired
 
 from langgraph.checkpoint.base.id import uuid6
 from langgraph.checkpoint.serde.base import SerializerProtocol, maybe_add_typed_methods
@@ -28,6 +29,8 @@ from langgraph.checkpoint.serde.types import (
 
 V = TypeVar("V", int, float, str)
 PendingWrite = tuple[str, str, Any]
+
+
 logger = logging.getLogger(__name__)
 
 
@@ -57,6 +60,21 @@ class CheckpointMetadata(TypedDict, total=False):
     """
     run_id: str
     """The ID of the run that created this checkpoint."""
+    delta_updates_since_snapshot: dict[str, int]
+    """Per-channel update count since the last `_DeltaSnapshot` was written.
+
+    !!! warning "Beta"
+
+        This metadata field backs `DeltaChannel` (beta). The key name and
+        contents may change while the delta-channel design stabilizes.
+
+    Maps channel name → number of supersteps that wrote to this channel
+    since its last snapshot blob. Used by `pregel.create_checkpoint` to
+    decide when to write the next snapshot (when the count reaches the
+    channel's `snapshot_frequency`, snapshot fires and the count resets
+    to 0). Absent on threads that don't use delta channels. Version-format
+    independent — works for int, float, and string version schemes.
+    """
 
 
 ChannelVersions = dict[str, str | int | float]
@@ -119,6 +137,33 @@ class CheckpointTuple(NamedTuple):
     pending_writes: list[PendingWrite] | None = None
 
 
+class DeltaChannelHistory(TypedDict):
+    """Per-channel result entry from `BaseCheckpointSaver.get_delta_channel_history`.
+
+    !!! warning "Beta"
+
+        Part of the `DeltaChannel` support surface; in beta. Field names and
+        semantics may change.
+
+    Storage-level view of what one channel contributed across the ancestor
+    chain of a target checkpoint:
+
+    * `writes` — on-path deltas oldest→newest as `PendingWrite` tuples.
+      Always present; possibly empty. Already filtered to one channel.
+      Writes stored at the target checkpoint itself are pending for the
+      next super-step and are excluded.
+    * `seed` — the stored value at the nearest ancestor whose
+      `channel_values[ch]` is populated. Omitted if the walk reached the
+      root without finding any stored value (consumer treats absence as
+      "start empty"). Typically a `_DeltaSnapshot` for delta channels with
+      finite snapshot frequency, or a plain value for threads migrated
+      from a pre-delta channel type.
+    """
+
+    writes: list[PendingWrite]
+    seed: NotRequired[Any]
+
+
 class BaseCheckpointSaver(Generic[V]):
     """Base class for creating a graph checkpointer.
 
@@ -282,6 +327,14 @@ class BaseCheckpointSaver(Generic[V]):
 
         Args:
             run_ids: The run IDs whose checkpoints should be deleted.
+
+        !!! warning "DeltaChannel"
+
+            Deleting a run that produced ancestor `checkpoint_writes` — or
+            the only `_DeltaSnapshot` blob — for a still-live thread will
+            break reconstruction of any `DeltaChannel` whose history
+            depended on those rows. See the `DeltaChannel` note on `prune`
+            for safe-recovery strategies.
         """
         raise NotImplementedError
 
@@ -295,6 +348,17 @@ class BaseCheckpointSaver(Generic[V]):
         Args:
             source_thread_id: The thread ID to copy from.
             target_thread_id: The thread ID to copy to.
+
+        !!! warning "DeltaChannel"
+
+            Implementations must copy the **complete** parent chain (all
+            ancestor checkpoints and their `checkpoint_writes`) — copying
+            only the head checkpoint will leave the target thread with
+            `DeltaChannel` state that cannot be reconstructed (no path back
+            to a `_DeltaSnapshot` ancestor). Equivalently, the copy must
+            include enough ancestors that every `DeltaChannel`-backed key
+            has either a `_DeltaSnapshot` in `channel_values` somewhere in
+            the chain, or a complete write history back to the chain root.
         """
         raise NotImplementedError
 
@@ -310,6 +374,34 @@ class BaseCheckpointSaver(Generic[V]):
             thread_ids: The thread IDs to prune.
             strategy: The pruning strategy. `"keep_latest"` retains only the most
                 recent checkpoint per namespace. `"delete"` removes all checkpoints.
+
+        !!! warning "DeltaChannel"
+
+            Custom implementations must be `DeltaChannel`-aware. `DeltaChannel`
+            stores only a sentinel in `channel_values` for non-snapshot steps;
+            reconstruction walks the parent chain via
+            `get_delta_channel_history`, accumulating rows from
+            `checkpoint_writes` until it reaches an ancestor whose
+            `channel_values` contains a `_DeltaSnapshot` blob (written every
+            `snapshot_frequency` updates).
+
+            A naive `"keep_latest"` that drops intermediate checkpoints and
+            their writes can sever that chain: the surviving "latest"
+            checkpoint is rarely a snapshot point itself, so its delta
+            channels would silently reconstruct as empty (no error raised —
+            `get_delta_channel_history` simply returns no `seed`). Safe
+            options when the graph uses `DeltaChannel`:
+
+            * Walk back from each kept checkpoint and preserve every
+              ancestor (plus its `checkpoint_writes`) up to the nearest one
+              whose `channel_values` already contains a `_DeltaSnapshot` for
+              every `DeltaChannel`-backed key.
+            * Force a fresh snapshot on the kept checkpoint before deleting
+              ancestors — rewrite `channel_values[k] = _DeltaSnapshot(value)`
+              for each delta channel `k` (resolving `value` via the existing
+              ancestor walk first), then prune.
+            * Skip pruning threads whose graph uses `DeltaChannel` until one
+              of the above is implemented.
         """
         raise NotImplementedError
 
@@ -426,6 +518,13 @@ class BaseCheckpointSaver(Generic[V]):
 
         Args:
             run_ids: The run IDs whose checkpoints should be deleted.
+
+        !!! warning "DeltaChannel"
+
+            See `delete_for_runs` — deleting rows a still-live thread's
+            `DeltaChannel` reconstruction depends on (writes between the
+            head and its nearest `_DeltaSnapshot` ancestor) will silently
+            corrupt that channel's state.
         """
         raise NotImplementedError
 
@@ -439,6 +538,13 @@ class BaseCheckpointSaver(Generic[V]):
         Args:
             source_thread_id: The thread ID to copy from.
             target_thread_id: The thread ID to copy to.
+
+        !!! warning "DeltaChannel"
+
+            See `copy_thread` — the copy must carry the complete parent
+            chain (or at least back to a `_DeltaSnapshot` ancestor for every
+            `DeltaChannel`) so the target thread can reconstruct delta
+            state.
         """
         raise NotImplementedError
 
@@ -454,9 +560,126 @@ class BaseCheckpointSaver(Generic[V]):
             thread_ids: The thread IDs to prune.
             strategy: The pruning strategy. `"keep_latest"` retains only the most
                 recent checkpoint per namespace. `"delete"` removes all checkpoints.
+
+        !!! warning "DeltaChannel"
+
+            See `prune` for the full `DeltaChannel` caveat. In short:
+            `"keep_latest"` must not drop ancestor checkpoints / writes that
+            sit between the kept checkpoint and the nearest `_DeltaSnapshot`
+            ancestor, or delta channels will silently reconstruct as empty.
         """
         raise NotImplementedError
 
+    def get_delta_channel_history(
+        self, *, config: RunnableConfig, channels: Sequence[str]
+    ) -> Mapping[str, DeltaChannelHistory]:
+        """Walk the parent chain returning per-channel writes + seed.
+
+        !!! warning "Beta"
+
+            This method is part of the `DeltaChannel` support surface and is
+            in beta. The signature, return shape (`DeltaChannelHistory`), and
+            interaction with `_DeltaSnapshot` blobs may change. Override at
+            your own risk; the default implementation will continue to work
+            against the public `BaseCheckpointSaver` contract.
+
+        For each requested channel, walks ancestors of the checkpoint
+        identified by `config` (following `parent_config`) and accumulates
+        `pending_writes` for that channel. The walk terminates per-channel
+        at the nearest ancestor whose `channel_values[ch]` is populated;
+        that value is returned as `seed`. If the walk reaches the root
+        without finding a stored value, `seed` is omitted from that
+        channel's entry — the consumer treats the absence as "start
+        empty."
+
+        Walks the **parent chain** (not `list(before=...)`): for forked
+        threads, only on-path ancestors contribute.
+
+        The default implementation walks `get_tuple` + `parent_config`
+        once for all channels — each ancestor visited once, not once per
+        channel. Savers with direct storage access (`InMemorySaver`,
+        `PostgresSaver`) override for performance; the return contract is
+        fixed here.
+
+        Args:
+            config: Configuration identifying the target checkpoint.
+            channels: Channel names to walk for. Empty → empty mapping.
+
+        Returns:
+            Per-channel `DeltaChannelHistory` for every name in `channels`.
+        """
+        if not channels:
+            return {}
+        collected_by_ch: dict[str, list[PendingWrite]] = {c: [] for c in channels}
+        seed_by_ch: dict[str, Any] = {}
+        remaining: set[str] = set(channels)
+        target_tuple = self.get_tuple(config)
+        cursor_config: RunnableConfig | None = (
+            target_tuple.parent_config if target_tuple else None
+        )
+        while cursor_config is not None and remaining:
+            tup = self.get_tuple(cursor_config)
+            if tup is None:
+                break
+            if tup.pending_writes:
+                for write in reversed(tup.pending_writes):
+                    ch = write[1]
+                    if ch in remaining:
+                        collected_by_ch[ch].append(write)
+            for ch in list(remaining):
+                if ch in tup.checkpoint["channel_values"]:
+                    seed_by_ch[ch] = tup.checkpoint["channel_values"][ch]
+                    remaining.discard(ch)
+            cursor_config = tup.parent_config
+        result: dict[str, DeltaChannelHistory] = {}
+        for ch in channels:
+            entry: DeltaChannelHistory = {"writes": list(reversed(collected_by_ch[ch]))}
+            if ch in seed_by_ch:
+                entry["seed"] = seed_by_ch[ch]
+            result[ch] = entry
+        return result
+
+    async def aget_delta_channel_history(
+        self, *, config: RunnableConfig, channels: Sequence[str]
+    ) -> Mapping[str, DeltaChannelHistory]:
+        """Async version of `get_delta_channel_history`.
+
+        !!! warning "Beta"
+
+            This method is part of the `DeltaChannel` support surface and is
+            in beta. See `get_delta_channel_history` for caveats.
+        """
+        if not channels:
+            return {}
+        collected_by_ch: dict[str, list[PendingWrite]] = {c: [] for c in channels}
+        seed_by_ch: dict[str, Any] = {}
+        remaining: set[str] = set(channels)
+        target_tuple = await self.aget_tuple(config)
+        cursor_config: RunnableConfig | None = (
+            target_tuple.parent_config if target_tuple else None
+        )
+        while cursor_config is not None and remaining:
+            tup = await self.aget_tuple(cursor_config)
+            if tup is None:
+                break
+            if tup.pending_writes:
+                for write in reversed(tup.pending_writes):
+                    ch = write[1]
+                    if ch in remaining:
+                        collected_by_ch[ch].append(write)
+            for ch in list(remaining):
+                if ch in tup.checkpoint["channel_values"]:
+                    seed_by_ch[ch] = tup.checkpoint["channel_values"][ch]
+                    remaining.discard(ch)
+            cursor_config = tup.parent_config
+        result: dict[str, DeltaChannelHistory] = {}
+        for ch in channels:
+            entry: DeltaChannelHistory = {"writes": list(reversed(collected_by_ch[ch]))}
+            if ch in seed_by_ch:
+                entry["seed"] = seed_by_ch[ch]
+            result[ch] = entry
+        return result
+
     def get_next_version(self, current: V | None, channel: None) -> V:
         """Generate the next version ID for a channel.
 

libs/checkpoint/langgraph/checkpoint/memory/__init__.py

@@ -6,7 +6,7 @@ import pickle
 import random
 import shutil
 from collections import defaultdict
-from collections.abc import AsyncIterator, Iterator, Sequence
+from collections.abc import AsyncIterator, Iterator, Mapping, Sequence
 from contextlib import AbstractAsyncContextManager, AbstractContextManager, ExitStack
 from types import TracebackType
 from typing import Any
@@ -20,6 +20,8 @@ from langgraph.checkpoint.base import (
     Checkpoint,
     CheckpointMetadata,
     CheckpointTuple,
+    DeltaChannelHistory,
+    PendingWrite,
     SerializerProtocol,
     get_checkpoint_id,
     get_checkpoint_metadata,
@@ -121,16 +123,115 @@ class InMemorySaver(
         return self.stack.__exit__(__exc_type, __exc_value, __traceback)
 
     def _load_blobs(
-        self, thread_id: str, checkpoint_ns: str, versions: ChannelVersions
+        self,
+        thread_id: str,
+        checkpoint_ns: str,
+        versions: ChannelVersions,
     ) -> dict[str, Any]:
-        channel_values: dict[str, Any] = {}
-        for k, v in versions.items():
-            kk = (thread_id, checkpoint_ns, k, v)
-            if kk in self.blobs:
-                vv = self.blobs[kk]
-                if vv[0] != "empty":
-                    channel_values[k] = self.serde.loads_typed(vv)
-        return channel_values
+        result: dict[str, Any] = {}
+        for k, ver in versions.items():
+            kk = (thread_id, checkpoint_ns, k, ver)
+            if kk not in self.blobs:
+                continue
+            vv = self.blobs[kk]
+            if vv[0] == "empty":
+                continue
+            result[k] = self.serde.loads_typed(vv)
+        return result
+
+    def get_delta_channel_history(
+        self, *, config: RunnableConfig, channels: Sequence[str]
+    ) -> Mapping[str, DeltaChannelHistory]:
+        """Override: walk the parent chain ONCE for all requested channels.
+
+        Each channel terminates independently at the nearest ancestor
+        whose stored blob is non-empty. Other channels keep walking until
+        they find their own terminator or hit the root.
+
+        Pre-delta plain-value blobs subsume their ancestor's pending
+        writes (the value already includes them); `_DeltaSnapshot` blobs
+        do not (snapshot is the value AT that ancestor, prior to its own
+        pending writes that produce the child).
+        """
+        if not channels:
+            return {}
+        # Imported lazily to avoid a hard checkpoint→serde-types coupling at
+        # module import; only this override needs the runtime check.
+        from langgraph.checkpoint.serde.types import _DeltaSnapshot
+
+        thread_id = config["configurable"]["thread_id"]
+        checkpoint_ns = config["configurable"].get("checkpoint_ns", "")
+        checkpoint_id = config["configurable"].get("checkpoint_id", "")
+        ns_storage = self.storage.get(thread_id, {}).get(checkpoint_ns, {})
+
+        chain: list[str] = []
+        target_entry = ns_storage.get(checkpoint_id)
+        current: str | None = target_entry[2] if target_entry is not None else None
+        while current is not None:
+            entry = ns_storage.get(current)
+            if entry is None:
+                break
+            chain.append(current)
+            _, _, parent = entry
+            current = parent
+
+        collected_by_ch: dict[str, list[PendingWrite]] = {c: [] for c in channels}
+        seed_by_ch: dict[str, Any] = {}
+        remaining: set[str] = set(channels)
+
+        for cp_id in chain:
+            if not remaining:
+                break
+            entry = ns_storage.get(cp_id)
+            ckpt = self.serde.loads_typed(entry[0]) if entry is not None else None
+
+            terminated_here: set[str] = set()
+            blob_value_by_ch: dict[str, Any] = {}
+            if ckpt is not None:
+                versions = ckpt.get("channel_versions", {})
+                for ch in remaining:
+                    ver = versions.get(ch)
+                    if ver is None:
+                        continue
+                    blob_entry = self.blobs.get((thread_id, checkpoint_ns, ch, ver))
+                    if blob_entry is None or blob_entry[0] == "empty":
+                        continue
+                    blob_value_by_ch[ch] = self.serde.loads_typed(blob_entry)
+                    terminated_here.add(ch)
+
+            step_writes = self.writes.get((thread_id, checkpoint_ns, cp_id), {})
+            for (_task_id, _idx), (tid, ch, serialized, _) in sorted(
+                step_writes.items(), reverse=True
+            ):
+                if ch not in remaining:
+                    continue
+                blob_value = blob_value_by_ch.get(ch)
+                if blob_value is not None and not isinstance(
+                    blob_value, _DeltaSnapshot
+                ):
+                    continue
+                collected_by_ch[ch].append(
+                    (tid, ch, self.serde.loads_typed(serialized))
+                )
+
+            for ch in terminated_here:
+                seed_by_ch[ch] = blob_value_by_ch[ch]
+                remaining.discard(ch)
+
+        result: dict[str, DeltaChannelHistory] = {}
+        for ch in channels:
+            entry_h: DeltaChannelHistory = {
+                "writes": list(reversed(collected_by_ch[ch]))
+            }
+            if ch in seed_by_ch:
+                entry_h["seed"] = seed_by_ch[ch]
+            result[ch] = entry_h
+        return result
+
+    async def aget_delta_channel_history(
+        self, *, config: RunnableConfig, channels: Sequence[str]
+    ) -> Mapping[str, DeltaChannelHistory]:
+        return self.get_delta_channel_history(config=config, channels=channels)
 
     def get_tuple(self, config: RunnableConfig) -> CheckpointTuple | None:
         """Get a checkpoint tuple from the in-memory storage.

libs/checkpoint/langgraph/checkpoint/serde/jsonplus.py

@@ -33,14 +33,16 @@ from langchain_core.load.load import Reviver
 from langgraph.checkpoint.serde import _msgpack as _lg_msgpack
 from langgraph.checkpoint.serde.base import SerializerProtocol
 from langgraph.checkpoint.serde.event_hooks import emit_serde_event
-from langgraph.checkpoint.serde.types import SendProtocol
+from langgraph.checkpoint.serde.types import (
+    SendProtocol,
+    _DeltaSnapshot,
+)
 from langgraph.store.base import Item
 
 if TYPE_CHECKING:
     from langgraph.checkpoint.serde._msgpack import (
         AllowedMsgpackModules,
     )
-    from langgraph.checkpoint.serde.types import SendProtocol
 
 LC_REVIVER = Reviver()
 EMPTY_BYTES = b""
@@ -317,10 +319,13 @@ EXT_METHOD_SINGLE_ARG = 3
 EXT_PYDANTIC_V1 = 4
 EXT_PYDANTIC_V2 = 5
 EXT_NUMPY_ARRAY = 6
+EXT_DELTA_SNAPSHOT = 7
 
 
 def _msgpack_default(obj: Any) -> str | ormsgpack.Ext:
-    if hasattr(obj, "model_dump") and callable(obj.model_dump):  # pydantic v2
+    if isinstance(obj, _DeltaSnapshot):
+        return ormsgpack.Ext(EXT_DELTA_SNAPSHOT, _msgpack_enc(obj.value))
+    elif hasattr(obj, "model_dump") and callable(obj.model_dump):  # pydantic v2
         return ormsgpack.Ext(
             EXT_PYDANTIC_V2,
             _msgpack_enc(
@@ -646,7 +651,13 @@ def _create_msgpack_ext_hook(
         return False
 
     def ext_hook(code: int, data: bytes) -> Any:
-        if code == EXT_CONSTRUCTOR_SINGLE_ARG:
+        if code == EXT_DELTA_SNAPSHOT:
+            return _DeltaSnapshot(
+                ormsgpack.unpackb(
+                    data, ext_hook=ext_hook, option=ormsgpack.OPT_NON_STR_KEYS
+                )
+            )
+        elif code == EXT_CONSTRUCTOR_SINGLE_ARG:
             try:
                 tup = ormsgpack.unpackb(
                     data, ext_hook=ext_hook, option=ormsgpack.OPT_NON_STR_KEYS

libs/checkpoint/langgraph/checkpoint/serde/types.py

@@ -1,6 +1,7 @@
 from collections.abc import Sequence
 from typing import (
     Any,
+    NamedTuple,
     Protocol,
     TypeVar,
     runtime_checkable,
@@ -14,6 +15,22 @@ INTERRUPT = "__interrupt__"
 RESUME = "__resume__"
 TASKS = "__pregel_tasks"
 
+
+class _DeltaSnapshot(NamedTuple):
+    """Snapshot blob for a DeltaChannel with finite snapshot_frequency.
+
+    Stored in checkpoint_blobs via the `EXT_DELTA_SNAPSHOT` msgpack ext code.
+    The ancestor walk in `BaseCheckpointSaver.get_delta_channel_history` terminates
+    when it encounters this type (any non-empty channel_values entry stops
+    the walk for that channel).
+
+    `from_checkpoint` reconstructs the channel value directly from `.value`
+    without replaying writes — the snapshot IS the accumulated state.
+    """
+
+    value: Any
+
+
 Value = TypeVar("Value", covariant=True)
 Update = TypeVar("Update", contravariant=True)
 C = TypeVar("C")

libs/checkpoint/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "langgraph-checkpoint"
-version = "4.0.3"
+version = "4.1.0a4"
 description = "Library with base interfaces for LangGraph checkpoint savers."
 authors = []
 requires-python = ">=3.10"

libs/checkpoint/tests/test_conformance_delta.py

@@ -0,0 +1,33 @@
+"""Run delta-channel conformance capabilities against InMemorySaver."""
+
+from __future__ import annotations
+
+import pytest
+
+conformance = pytest.importorskip(
+    "langgraph.checkpoint.conformance",
+    reason="langgraph-checkpoint-conformance not installed",
+)
+
+
+@pytest.mark.asyncio
+async def test_delta_channel_conformance():
+    from langgraph.checkpoint.conformance import validate
+    from langgraph.checkpoint.conformance.initializer import checkpointer_test
+
+    from langgraph.checkpoint.memory import InMemorySaver
+
+    @checkpointer_test(name="InMemorySaver")
+    async def mem_saver():
+        yield InMemorySaver()
+
+    report = await validate(
+        mem_saver,
+        capabilities={
+            "delta_channel_history",
+        },
+    )
+    for cap, result in report.results.items():
+        if result.passed is False:
+            details = "\n".join(result.failures or [])
+            pytest.fail(f"Capability {cap} failed:\n{details}")

libs/checkpoint/tests/test_memory.py

@@ -208,8 +208,6 @@ class TestMemorySaver:
 
 
 async def test_memory_saver() -> None:
-    from langgraph.checkpoint.memory import InMemorySaver
-
     memory_saver = InMemorySaver()
     assert isinstance(memory_saver, InMemorySaver)
 
@@ -320,3 +318,363 @@ def test_memory_saver_with_allowlist_proxy_isolated() -> None:
     assert direct is not None
     expected = obj.model_dump() if hasattr(obj, "model_dump") else obj.dict()
     assert direct.checkpoint["channel_values"]["foo"] == expected
+
+
+class TestInMemorySaverDeltaChannel:
+    def test_load_blobs_omits_delta_channel(self) -> None:
+        """_load_blobs omits delta channels (stored as 'empty'); reconstruction deferred."""
+        saver = InMemorySaver()
+
+        thread_id, ns, channel = "t1", "", "messages"
+        v1 = "00000000000000000000000000000001.0000000000000000"
+
+        saver.blobs[(thread_id, ns, channel, v1)] = ("empty", b"")
+
+        result = saver._load_blobs(thread_id, ns, {channel: v1})
+        assert channel not in result
+
+    def test_get_channel_writes_collects_ancestor_writes_only(self) -> None:
+        """`get_delta_channel_history` collects ancestor writes oldest→newest, and
+        excludes writes stored at the target checkpoint itself (those are
+        pending writes for the next step, applied separately by pregel).
+
+        When the walk reaches the root without finding any stored value for
+        the channel, the per-channel entry has no `seed` key (TypedDict
+        absence indicates "start empty").
+        """
+        saver = InMemorySaver()
+        serde = JsonPlusSerializer()
+
+        thread_id, ns, channel = "t1", "", "messages"
+
+        cp1 = empty_checkpoint()
+        cp1["id"] = "cp1"
+        cp2 = empty_checkpoint()
+        cp2["id"] = "cp2"
+        saver.storage[thread_id][ns] = {
+            "cp1": (serde.dumps_typed(cp1), serde.dumps_typed({}), None),
+            "cp2": (serde.dumps_typed(cp2), serde.dumps_typed({}), "cp1"),
+        }
+        # Writes stored at cp1 produced the cp1 snapshot; part of history.
+        saver.writes[(thread_id, ns, "cp1")][("task1", 0)] = (
+            "task1",
+            channel,
+            serde.dumps_typed({"content": "hi"}),
+            "",
+        )
+        # Writes stored at cp2 are pending — they will produce cp3 when the
+        # step that loaded cp2 completes. They MUST NOT appear in the
+        # reconstructed snapshot value at cp2.
+        saver.writes[(thread_id, ns, "cp2")][("task2", 0)] = (
+            "task2",
+            channel,
+            serde.dumps_typed({"content": "pending"}),
+            "",
+        )
+
+        config: RunnableConfig = {
+            "configurable": {
+                "thread_id": thread_id,
+                "checkpoint_ns": ns,
+                "checkpoint_id": "cp2",
+            }
+        }
+        result = saver.get_delta_channel_history(config=config, channels=[channel])[
+            channel
+        ]
+        # Walk reached the root without finding a stored value → no `seed` key.
+        assert "seed" not in result
+        values = [v for _, _, v in result["writes"]]
+        assert values == [{"content": "hi"}]
+
+    def test_get_channel_writes_at_root_returns_empty(self) -> None:
+        """Reconstructing the root checkpoint's state: no ancestors → []."""
+        saver = InMemorySaver()
+        serde = JsonPlusSerializer()
+        thread_id, ns, channel = "t1", "", "messages"
+
+        cp1 = empty_checkpoint()
+        cp1["id"] = "cp1"
+        saver.storage[thread_id][ns] = {
+            "cp1": (serde.dumps_typed(cp1), serde.dumps_typed({}), None),
+        }
+        saver.writes[(thread_id, ns, "cp1")][("task1", 0)] = (
+            "task1",
+            channel,
+            serde.dumps_typed({"content": "pending"}),
+            "",
+        )
+
+        config: RunnableConfig = {
+            "configurable": {
+                "thread_id": thread_id,
+                "checkpoint_ns": ns,
+                "checkpoint_id": "cp1",
+            }
+        }
+        result = saver.get_delta_channel_history(config=config, channels=[channel])[
+            channel
+        ]
+        # No ancestors → no seed found, no writes accumulated.
+        assert "seed" not in result
+        assert result["writes"] == []
+
+
+class TestBaseFallbackGetChannelWrites:
+    """Exercises the `BaseCheckpointSaver.get_delta_channel_history` default
+    implementation — the path third-party savers inherit when they don't
+    override `get_delta_channel_history` themselves.
+
+    Regression guard for a bug where the fallback passed the caller's config
+    (with `checkpoint_id`) straight to `self.list()`, which most savers
+    collapse to a single row — causing the fallback to return `[]`.
+    """
+
+    def _build_saver_with_chain(self) -> tuple[InMemorySaver, str, str]:
+        """Build an InMemorySaver with a 3-checkpoint chain and per-step writes
+        for a `messages` channel.
+
+        Returns `(saver, thread_id, namespace)`. The saver subclass deletes the
+        InMemorySaver override so the base class fallback is exercised.
+        """
+
+        class _ThirdPartyStyleSaver(InMemorySaver):
+            get_delta_channel_history = (
+                InMemorySaver.__mro__[1].get_delta_channel_history  # type: ignore[attr-defined]
+            )
+            aget_delta_channel_history = (
+                InMemorySaver.__mro__[1].aget_delta_channel_history  # type: ignore[attr-defined]
+            )
+
+        saver = _ThirdPartyStyleSaver()
+        serde = JsonPlusSerializer()
+        thread_id, ns, channel = "t1", "", "messages"
+
+        cp0 = empty_checkpoint()
+        cp0["id"] = "00000000000000000000000000000001.0000000000000000"
+        cp1 = empty_checkpoint()
+        cp1["id"] = "00000000000000000000000000000002.0000000000000000"
+        cp2 = empty_checkpoint()
+        cp2["id"] = "00000000000000000000000000000003.0000000000000000"
+        saver.storage[thread_id][ns] = {
+            cp0["id"]: (serde.dumps_typed(cp0), serde.dumps_typed({}), None),
+            cp1["id"]: (serde.dumps_typed(cp1), serde.dumps_typed({}), cp0["id"]),
+            cp2["id"]: (serde.dumps_typed(cp2), serde.dumps_typed({}), cp1["id"]),
+        }
+        # Writes under cp0 produced cp1's state; writes under cp1 produced cp2's.
+        saver.writes[(thread_id, ns, cp0["id"])][("task1", 0)] = (
+            "task1",
+            channel,
+            serde.dumps_typed({"content": "first"}),
+            "",
+        )
+        saver.writes[(thread_id, ns, cp1["id"])][("task2", 0)] = (
+            "task2",
+            channel,
+            serde.dumps_typed({"content": "second"}),
+            "",
+        )
+        return saver, thread_id, ns
+
+    def test_fallback_returns_ancestor_writes_oldest_first(self) -> None:
+        saver, thread_id, ns = self._build_saver_with_chain()
+        target_id = "00000000000000000000000000000003.0000000000000000"
+        config: RunnableConfig = {
+            "configurable": {
+                "thread_id": thread_id,
+                "checkpoint_ns": ns,
+                "checkpoint_id": target_id,
+            }
+        }
+
+        result = saver.get_delta_channel_history(config=config, channels=["messages"])[
+            "messages"
+        ]
+
+        # Walk reached root without a stored value → `seed` key absent.
+        assert "seed" not in result
+        values = [v for _, _, v in result["writes"]]
+        assert values == [{"content": "first"}, {"content": "second"}]
+
+    async def test_async_fallback_returns_ancestor_writes_oldest_first(self) -> None:
+        saver, thread_id, ns = self._build_saver_with_chain()
+        target_id = "00000000000000000000000000000003.0000000000000000"
+        config: RunnableConfig = {
+            "configurable": {
+                "thread_id": thread_id,
+                "checkpoint_ns": ns,
+                "checkpoint_id": target_id,
+            }
+        }
+
+        result = (
+            await saver.aget_delta_channel_history(config=config, channels=["messages"])
+        )["messages"]
+
+        assert "seed" not in result
+        values = [v for _, _, v in result["writes"]]
+        assert values == [{"content": "first"}, {"content": "second"}]
+
+    async def test_async_fallback_concurrent_tasks_do_not_interfere(self) -> None:
+        """Regression: the re-entrancy guard must be task-local, not thread-local.
+
+        Two concurrent `aget_delta_channel_history` calls on the same event-loop
+        thread must each see their full reconstructed writes. A
+        `threading.local()` guard would let whichever task set it first
+        short-circuit the other to `writes=[]`.
+        """
+        import asyncio
+
+        saver, thread_id, ns = self._build_saver_with_chain()
+
+        # Force the two tasks to interleave across the `set(True)` boundary:
+        # each `aget_tuple` yields control, so if the guard were thread-local
+        # the second task would observe `active=True` set by the first.
+        orig_aget_tuple = saver.aget_tuple
+
+        async def slow_aget_tuple(config: RunnableConfig) -> Any:
+            await asyncio.sleep(0)
+            return await orig_aget_tuple(config)
+
+        saver.aget_tuple = slow_aget_tuple  # type: ignore[method-assign]
+
+        target_id = "00000000000000000000000000000003.0000000000000000"
+        config: RunnableConfig = {
+            "configurable": {
+                "thread_id": thread_id,
+                "checkpoint_ns": ns,
+                "checkpoint_id": target_id,
+            }
+        }
+
+        results = await asyncio.gather(
+            saver.aget_delta_channel_history(config=config, channels=["messages"]),
+            saver.aget_delta_channel_history(config=config, channels=["messages"]),
+        )
+
+        expected_values = [{"content": "first"}, {"content": "second"}]
+        for result_map in results:
+            result = result_map["messages"]
+            assert "seed" not in result
+            values = [v for _, _, v in result["writes"]]
+            assert values == expected_values
+
+
+class TestPreDeltaBlobTerminator:
+    """Verify the pre-delta blob terminator: when the ancestor walk hits a
+    checkpoint whose blob for the channel is a real value, reconstruction
+    seeds from it and stops. This guards
+
+      * back-compat: a thread written by pre-delta code, then extended under
+        delta — reconstruction must return the correct value without walking
+        past the last pre-delta ancestor;
+      * perf: without the terminator, every reconstruct-after-migration would
+        walk all the way to the thread root.
+
+    Under the new public API a found seed populates `seed` in the
+    `DeltaChannelHistory` TypedDict; absence of the `seed` key means the walk
+    reached root without finding a stored value.
+    """
+
+    def _build_mixed_thread(self) -> tuple[InMemorySaver, str, str, str, str]:
+        """Three-checkpoint chain: cp1 (pre-delta, blob=[A]), cp2 (delta,
+        write=B), cp3 (delta, write=C). Reconstructing at cp3 must yield
+        seed=[A] + writes=[B, C].
+
+        Returns `(saver, thread_id, ns, channel, cp3_id)`.
+        """
+        saver = InMemorySaver()
+        serde = JsonPlusSerializer()
+        thread_id, ns, channel = "t1", "", "messages"
+
+        v1 = "00000000000000000000000000000001.0"
+        v2 = "00000000000000000000000000000002.0"
+        v3 = "00000000000000000000000000000003.0"
+
+        # Pre-delta: cp1 stored a real blob for the channel.
+        saver.blobs[(thread_id, ns, channel, v1)] = serde.dumps_typed(["A"])
+        # Delta-era: cp2 and cp3 store "empty"; real writes in checkpoint_writes.
+        saver.blobs[(thread_id, ns, channel, v2)] = ("empty", b"")
+        saver.blobs[(thread_id, ns, channel, v3)] = ("empty", b"")
+
+        cp1 = empty_checkpoint()
+        cp1["id"] = "cp1"
+        cp1["channel_versions"][channel] = v1
+        cp2 = empty_checkpoint()
+        cp2["id"] = "cp2"
+        cp2["channel_versions"][channel] = v2
+        cp3 = empty_checkpoint()
+        cp3["id"] = "cp3"
+        cp3["channel_versions"][channel] = v3
+
+        saver.storage[thread_id][ns] = {
+            "cp1": (serde.dumps_typed(cp1), serde.dumps_typed({}), None),
+            "cp2": (serde.dumps_typed(cp2), serde.dumps_typed({}), "cp1"),
+            "cp3": (serde.dumps_typed(cp3), serde.dumps_typed({}), "cp2"),
+        }
+        # Write under cp1 would be from the pre-delta era and MUST be ignored
+        # (the blob already captures it). We add one and assert it is not
+        # folded into the reconstructed result.
+        saver.writes[(thread_id, ns, "cp1")][("task0", 0)] = (
+            "task0",
+            channel,
+            serde.dumps_typed("PRE-DELTA-WRITE"),
+            "",
+        )
+        saver.writes[(thread_id, ns, "cp2")][("task2", 0)] = (
+            "task2",
+            channel,
+            serde.dumps_typed("B"),
+            "",
+        )
+        saver.writes[(thread_id, ns, "cp3")][("task3", 0)] = (
+            "task3",
+            channel,
+            serde.dumps_typed("PENDING-AT-TARGET"),
+            "",
+        )
+        return saver, thread_id, ns, channel, "cp3"
+
+    def test_seed_from_pre_delta_ancestor_blob(self) -> None:
+        saver, thread_id, ns, channel, target = self._build_mixed_thread()
+        config: RunnableConfig = {
+            "configurable": {
+                "thread_id": thread_id,
+                "checkpoint_ns": ns,
+                "checkpoint_id": target,
+            }
+        }
+
+        result = saver.get_delta_channel_history(config=config, channels=[channel])[
+            channel
+        ]
+
+        # Seed came from the pre-delta blob at cp1.
+        assert result["seed"] == ["A"]
+        # Delta-era writes from cp2 replay through the reducer on top of seed.
+        # cp3 is the target — its own write is pending for the NEXT step and
+        # must be excluded.
+        values = [v for _, _, v in result["writes"]]
+        assert values == ["B"]
+
+    def test_pre_delta_blob_terminates_walk_before_older_writes(self) -> None:
+        """Writes stored at the pre-delta ancestor itself must not be replayed
+        (the blob subsumes them)."""
+        saver, thread_id, ns, channel, target = self._build_mixed_thread()
+        config: RunnableConfig = {
+            "configurable": {
+                "thread_id": thread_id,
+                "checkpoint_ns": ns,
+                "checkpoint_id": target,
+            }
+        }
+
+        result = saver.get_delta_channel_history(config=config, channels=[channel])[
+            channel
+        ]
+
+        values = [v for _, _, v in result["writes"]]
+        # The pre-delta write under cp1 must not appear (the blob subsumes it).
+        assert "PRE-DELTA-WRITE" not in values
+        # And the pending write at the target is never folded in.
+        assert "PENDING-AT-TARGET" not in values

libs/checkpoint/uv.lock

@@ -2,7 +2,8 @@ version = 1
 revision = 3
 requires-python = ">=3.10"
 resolution-markers = [
-    "python_full_version >= '3.12'",
+    "python_full_version >= '3.15'",
+    "python_full_version >= '3.12' and python_full_version < '3.15'",
     "python_full_version == '3.11.*'",
     "python_full_version < '3.11'",
 ]
@@ -267,10 +268,11 @@ wheels = [
 
 [[package]]
 name = "langchain-core"
-version = "1.2.28"
+version = "1.3.2"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "jsonpatch" },
+    { name = "langchain-protocol" },
     { name = "langsmith" },
     { name = "packaging" },
     { name = "pydantic" },
@@ -279,14 +281,26 @@ dependencies = [
     { name = "typing-extensions" },
     { name = "uuid-utils" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/f8/a4/317a1a3ac1df33a64adb3670bf88bbe3b3d5baa274db6863a979db472897/langchain_core-1.2.28.tar.gz", hash = "sha256:271a3d8bd618f795fdeba112b0753980457fc90537c46a0c11998516a74dc2cb", size = 846119, upload-time = "2026-04-08T18:19:34.867Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/a8/03/7219502e8ca728d65eb44d7a3eb60239230742a70dbfc9241b9bfd61c4ab/langchain_core-1.3.2.tar.gz", hash = "sha256:fd7a50b2f28ba561fd9d7f5d2760bc9e06cf00cdf820a3ccafe88a94ffa8d5b7", size = 911813, upload-time = "2026-04-24T15:49:23.699Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/a8/92/32f785f077c7e898da97064f113c73fbd9ad55d1e2169cf3a391b183dedb/langchain_core-1.2.28-py3-none-any.whl", hash = "sha256:80764232581eaf8057bcefa71dbf8adc1f6a28d257ebd8b95ba9b8b452e8c6ac", size = 508727, upload-time = "2026-04-08T18:19:32.823Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/d5/8fa4431007cbb7cfed7590f4d6a5dea3ad724f4174d248f6642ef5ce7d05/langchain_core-1.3.2-py3-none-any.whl", hash = "sha256:d44a66127f9f8db735bdfd0ab9661bccb47a97113cfd3f2d89c74864422b7274", size = 542390, upload-time = "2026-04-24T15:49:21.991Z" },
+]
+
+[[package]]
+name = "langchain-protocol"
+version = "0.0.15"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/4f/24/9777489d6fbbee64af0c8f96d4f840239c408cf694f3394672807dafc490/langchain_protocol-0.0.15.tar.gz", hash = "sha256:9ab2d11ee73944754f10e037e717098d3a6796f0e58afa9cadda6154e7655ade", size = 5862, upload-time = "2026-05-01T22:30:04.748Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/1d/7a/9c97a7b9cbe4c5dc6a44cdb1545450c28f0c8ce89b9c1f0ee7fbad896263/langchain_protocol-0.0.15-py3-none-any.whl", hash = "sha256:461eb794358f83d5e42635a5797799ffec7b4702314e34edf73ac21e75d3ef79", size = 6982, upload-time = "2026-05-01T22:30:03.877Z" },
 ]
 
 [[package]]
 name = "langgraph-checkpoint"
-version = "4.0.3"
+version = "4.1.0a4"
 source = { editable = "." }
 dependencies = [
     { name = "langchain-core" },
@@ -486,7 +500,7 @@ wheels = [
 
 [[package]]
 name = "mypy"
-version = "1.20.0"
+version = "1.20.2"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "librt", marker = "platform_python_implementation != 'PyPy'" },
@@ -495,51 +509,51 @@ dependencies = [
     { name = "tomli", marker = "python_full_version < '3.11'" },
     { name = "typing-extensions" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/f8/5c/b0089fe7fef0a994ae5ee07029ced0526082c6cfaaa4c10d40a10e33b097/mypy-1.20.0.tar.gz", hash = "sha256:eb96c84efcc33f0b5e0e04beacf00129dd963b67226b01c00b9dfc8affb464c3", size = 3815028, upload-time = "2026-03-31T16:55:14.959Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/04/af/e3d4b3e9ec91a0ff9aabfdb38692952acf49bbb899c2e4c29acb3a6da3ae/mypy-1.20.2.tar.gz", hash = "sha256:e8222c26daaafd9e8626dec58ae36029f82585890589576f769a650dd20fd665", size = 3817349, upload-time = "2026-04-21T17:12:28.473Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/4d/a2/a965c8c3fcd4fa8b84ba0d46606181b0d0a1d50f274c67877f3e9ed4882c/mypy-1.20.0-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:d99f515f95fd03a90875fdb2cca12ff074aa04490db4d190905851bdf8a549a8", size = 14430138, upload-time = "2026-03-31T16:52:37.843Z" },
-    { url = "https://files.pythonhosted.org/packages/53/6e/043477501deeb8eabbab7f1a2f6cac62cfb631806dc1d6862a04a7f5011b/mypy-1.20.0-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:bd0212976dc57a5bfeede7c219e7cd66568a32c05c9129686dd487c059c1b88a", size = 13311282, upload-time = "2026-03-31T16:55:11.021Z" },
-    { url = "https://files.pythonhosted.org/packages/65/aa/bd89b247b83128197a214f29f0632ff3c14f54d4cd70d144d157bd7d7d6e/mypy-1.20.0-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f8426d4d75d68714abc17a4292d922f6ba2cfb984b72c2278c437f6dae797865", size = 13750889, upload-time = "2026-03-31T16:52:02.909Z" },
-    { url = "https://files.pythonhosted.org/packages/fa/9d/2860be7355c45247ccc0be1501c91176318964c2a137bd4743f58ce6200e/mypy-1.20.0-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:02cca0761c75b42a20a2757ae58713276605eb29a08dd8a6e092aa347c4115ca", size = 14619788, upload-time = "2026-03-31T16:50:48.928Z" },
-    { url = "https://files.pythonhosted.org/packages/75/7f/3ef3e360c91f3de120f205c8ce405e9caf9fc52ef14b65d37073e322c114/mypy-1.20.0-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:b3a49064504be59e59da664c5e149edc1f26c67c4f8e8456f6ba6aba55033018", size = 14918849, upload-time = "2026-03-31T16:51:10.478Z" },
-    { url = "https://files.pythonhosted.org/packages/ae/72/af970dfe167ef788df7c5e6109d2ed0229f164432ce828bc9741a4250e64/mypy-1.20.0-cp310-cp310-win_amd64.whl", hash = "sha256:ebea00201737ad4391142808ed16e875add5c17f676e0912b387739f84991e13", size = 10822007, upload-time = "2026-03-31T16:50:25.268Z" },
-    { url = "https://files.pythonhosted.org/packages/93/94/ba9065c2ebe5421619aff684b793d953e438a8bfe31a320dd6d1e0706e81/mypy-1.20.0-cp310-cp310-win_arm64.whl", hash = "sha256:e80cf77847d0d3e6e3111b7b25db32a7f8762fd4b9a3a72ce53fe16a2863b281", size = 9756158, upload-time = "2026-03-31T16:48:36.213Z" },
-    { url = "https://files.pythonhosted.org/packages/6e/1c/74cb1d9993236910286865679d1c616b136b2eae468493aa939431eda410/mypy-1.20.0-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:4525e7010b1b38334516181c5b81e16180b8e149e6684cee5a727c78186b4e3b", size = 14343972, upload-time = "2026-03-31T16:49:04.887Z" },
-    { url = "https://files.pythonhosted.org/packages/d5/0d/01399515eca280386e308cf57901e68d3a52af18691941b773b3380c1df8/mypy-1.20.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:a17c5d0bdcca61ce24a35beb828a2d0d323d3fcf387d7512206888c900193367", size = 13225007, upload-time = "2026-03-31T16:50:08.151Z" },
-    { url = "https://files.pythonhosted.org/packages/56/ac/b4ba5094fb2d7fe9d2037cd8d18bbe02bcf68fd22ab9ff013f55e57ba095/mypy-1.20.0-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f75ff57defcd0f1d6e006d721ccdec6c88d4f6a7816eb92f1c4890d979d9ee62", size = 13663752, upload-time = "2026-03-31T16:49:26.064Z" },
-    { url = "https://files.pythonhosted.org/packages/db/a7/460678d3cf7da252d2288dad0c602294b6ec22a91932ec368cc11e44bb6e/mypy-1.20.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:b503ab55a836136b619b5fc21c8803d810c5b87551af8600b72eecafb0059cb0", size = 14532265, upload-time = "2026-03-31T16:53:55.077Z" },
-    { url = "https://files.pythonhosted.org/packages/a3/3e/051cca8166cf0438ae3ea80e0e7c030d7a8ab98dffc93f80a1aa3f23c1a2/mypy-1.20.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:1973868d2adbb4584a3835780b27436f06d1dc606af5be09f187aaa25be1070f", size = 14768476, upload-time = "2026-03-31T16:50:34.587Z" },
-    { url = "https://files.pythonhosted.org/packages/be/66/8e02ec184f852ed5c4abb805583305db475930854e09964b55e107cdcbc4/mypy-1.20.0-cp311-cp311-win_amd64.whl", hash = "sha256:2fcedb16d456106e545b2bfd7ef9d24e70b38ec252d2a629823a4d07ebcdb69e", size = 10818226, upload-time = "2026-03-31T16:53:15.624Z" },
-    { url = "https://files.pythonhosted.org/packages/13/4b/383ad1924b28f41e4879a74151e7a5451123330d45652da359f9183bcd45/mypy-1.20.0-cp311-cp311-win_arm64.whl", hash = "sha256:379edf079ce44ac8d2805bcf9b3dd7340d4f97aad3a5e0ebabbf9d125b84b442", size = 9750091, upload-time = "2026-03-31T16:54:12.162Z" },
-    { url = "https://files.pythonhosted.org/packages/be/dd/3afa29b58c2e57c79116ed55d700721c3c3b15955e2b6251dd165d377c0e/mypy-1.20.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:002b613ae19f4ac7d18b7e168ffe1cb9013b37c57f7411984abbd3b817b0a214", size = 14509525, upload-time = "2026-03-31T16:55:01.824Z" },
-    { url = "https://files.pythonhosted.org/packages/54/eb/227b516ab8cad9f2a13c5e7a98d28cd6aa75e9c83e82776ae6c1c4c046c7/mypy-1.20.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:a9336b5e6712f4adaf5afc3203a99a40b379049104349d747eb3e5a3aa23ac2e", size = 13326469, upload-time = "2026-03-31T16:51:41.23Z" },
-    { url = "https://files.pythonhosted.org/packages/57/d4/1ddb799860c1b5ac6117ec307b965f65deeb47044395ff01ab793248a591/mypy-1.20.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f13b3e41bce9d257eded794c0f12878af3129d80aacd8a3ee0dee51f3a978651", size = 13705953, upload-time = "2026-03-31T16:48:55.69Z" },
-    { url = "https://files.pythonhosted.org/packages/c5/b7/54a720f565a87b893182a2a393370289ae7149e4715859e10e1c05e49154/mypy-1.20.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9804c3ad27f78e54e58b32e7cb532d128b43dbfb9f3f9f06262b821a0f6bd3f5", size = 14710363, upload-time = "2026-03-31T16:53:26.948Z" },
-    { url = "https://files.pythonhosted.org/packages/b2/2a/74810274848d061f8a8ea4ac23aaad43bd3d8c1882457999c2e568341c57/mypy-1.20.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:697f102c5c1d526bdd761a69f17c6070f9892eebcb94b1a5963d679288c09e78", size = 14947005, upload-time = "2026-03-31T16:50:17.591Z" },
-    { url = "https://files.pythonhosted.org/packages/77/91/21b8ba75f958bcda75690951ce6fa6b7138b03471618959529d74b8544e2/mypy-1.20.0-cp312-cp312-win_amd64.whl", hash = "sha256:0ecd63f75fdd30327e4ad8b5704bd6d91fc6c1b2e029f8ee14705e1207212489", size = 10880616, upload-time = "2026-03-31T16:52:19.986Z" },
-    { url = "https://files.pythonhosted.org/packages/8a/15/3d8198ef97c1ca03aea010cce4f1d4f3bc5d9849e8c0140111ca2ead9fdd/mypy-1.20.0-cp312-cp312-win_arm64.whl", hash = "sha256:f194db59657c58593a3c47c6dfd7bad4ef4ac12dbc94d01b3a95521f78177e33", size = 9813091, upload-time = "2026-03-31T16:53:44.385Z" },
-    { url = "https://files.pythonhosted.org/packages/d6/a7/f64ea7bd592fa431cb597418b6dec4a47f7d0c36325fec7ac67bc8402b94/mypy-1.20.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:b20c8b0fd5877abdf402e79a3af987053de07e6fb208c18df6659f708b535134", size = 14485344, upload-time = "2026-03-31T16:49:16.78Z" },
-    { url = "https://files.pythonhosted.org/packages/bb/72/8927d84cfc90c6abea6e96663576e2e417589347eb538749a464c4c218a0/mypy-1.20.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:367e5c993ba34d5054d11937d0485ad6dfc60ba760fa326c01090fc256adf15c", size = 13327400, upload-time = "2026-03-31T16:53:08.02Z" },
-    { url = "https://files.pythonhosted.org/packages/ab/4a/11ab99f9afa41aa350178d24a7d2da17043228ea10f6456523f64b5a6cf6/mypy-1.20.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f799d9db89fc00446f03281f84a221e50018fc40113a3ba9864b132895619ebe", size = 13706384, upload-time = "2026-03-31T16:52:28.577Z" },
-    { url = "https://files.pythonhosted.org/packages/42/79/694ca73979cfb3535ebfe78733844cd5aff2e63304f59bf90585110d975a/mypy-1.20.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:555658c611099455b2da507582ea20d2043dfdfe7f5ad0add472b1c6238b433f", size = 14700378, upload-time = "2026-03-31T16:48:45.527Z" },
-    { url = "https://files.pythonhosted.org/packages/84/24/a022ccab3a46e3d2cdf2e0e260648633640eb396c7e75d5a42818a8d3971/mypy-1.20.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:efe8d70949c3023698c3fca1e94527e7e790a361ab8116f90d11221421cd8726", size = 14932170, upload-time = "2026-03-31T16:49:36.038Z" },
-    { url = "https://files.pythonhosted.org/packages/d8/9b/549228d88f574d04117e736f55958bd4908f980f9f5700a07aeb85df005b/mypy-1.20.0-cp313-cp313-win_amd64.whl", hash = "sha256:f49590891d2c2f8a9de15614e32e459a794bcba84693c2394291a2038bbaaa69", size = 10888526, upload-time = "2026-03-31T16:50:59.827Z" },
-    { url = "https://files.pythonhosted.org/packages/91/17/15095c0e54a8bc04d22d4ff06b2139d5f142c2e87520b4e39010c4862771/mypy-1.20.0-cp313-cp313-win_arm64.whl", hash = "sha256:76a70bf840495729be47510856b978f1b0ec7d08f257ca38c9d932720bf6b43e", size = 9816456, upload-time = "2026-03-31T16:49:59.537Z" },
-    { url = "https://files.pythonhosted.org/packages/4e/0e/6ca4a84cbed9e62384bc0b2974c90395ece5ed672393e553996501625fc5/mypy-1.20.0-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:0f42dfaab7ec1baff3b383ad7af562ab0de573c5f6edb44b2dab016082b89948", size = 14483331, upload-time = "2026-03-31T16:52:57.999Z" },
-    { url = "https://files.pythonhosted.org/packages/7d/c5/5fe9d8a729dd9605064691816243ae6c49fde0bd28f6e5e17f6a24203c43/mypy-1.20.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:31b5dbb55293c1bd27c0fc813a0d2bb5ceef9d65ac5afa2e58f829dab7921fd5", size = 13342047, upload-time = "2026-03-31T16:54:21.555Z" },
-    { url = "https://files.pythonhosted.org/packages/4c/33/e18bcfa338ca4e6b2771c85d4c5203e627d0c69d9de5c1a2cf2ba13320ba/mypy-1.20.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:49d11c6f573a5a08f77fad13faff2139f6d0730ebed2cfa9b3d2702671dd7188", size = 13719585, upload-time = "2026-03-31T16:51:53.89Z" },
-    { url = "https://files.pythonhosted.org/packages/6b/8d/93491ff7b79419edc7eabf95cb3b3f7490e2e574b2855c7c7e7394ff933f/mypy-1.20.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:7d3243c406773185144527f83be0e0aefc7bf4601b0b2b956665608bf7c98a83", size = 14685075, upload-time = "2026-03-31T16:54:04.464Z" },
-    { url = "https://files.pythonhosted.org/packages/b5/9d/d924b38a4923f8d164bf2b4ec98bf13beaf6e10a5348b4b137eadae40a6e/mypy-1.20.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:a79c1eba7ac4209f2d850f0edd0a2f8bba88cbfdfefe6fb76a19e9d4fe5e71a2", size = 14919141, upload-time = "2026-03-31T16:54:51.785Z" },
-    { url = "https://files.pythonhosted.org/packages/59/98/1da9977016678c0b99d43afe52ed00bb3c1a0c4c995d3e6acca1a6ebb9b4/mypy-1.20.0-cp314-cp314-win_amd64.whl", hash = "sha256:00e047c74d3ec6e71a2eb88e9ea551a2edb90c21f993aefa9e0d2a898e0bb732", size = 11050925, upload-time = "2026-03-31T16:51:30.758Z" },
-    { url = "https://files.pythonhosted.org/packages/5e/e3/ba0b7a3143e49a9c4f5967dde6ea4bf8e0b10ecbbcca69af84027160ee89/mypy-1.20.0-cp314-cp314-win_arm64.whl", hash = "sha256:931a7630bba591593dcf6e97224a21ff80fb357e7982628d25e3c618e7f598ef", size = 10001089, upload-time = "2026-03-31T16:49:43.632Z" },
-    { url = "https://files.pythonhosted.org/packages/12/28/e617e67b3be9d213cda7277913269c874eb26472489f95d09d89765ce2d8/mypy-1.20.0-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:26c8b52627b6552f47ff11adb4e1509605f094e29815323e487fc0053ebe93d1", size = 15534710, upload-time = "2026-03-31T16:52:12.506Z" },
-    { url = "https://files.pythonhosted.org/packages/6e/0c/3b5f2d3e45dc7169b811adce8451679d9430399d03b168f9b0489f43adaa/mypy-1.20.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:39362cdb4ba5f916e7976fccecaab1ba3a83e35f60fa68b64e9a70e221bb2436", size = 14393013, upload-time = "2026-03-31T16:54:41.186Z" },
-    { url = "https://files.pythonhosted.org/packages/a3/49/edc8b0aa145cc09c1c74f7ce2858eead9329931dcbbb26e2ad40906daa4e/mypy-1.20.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:34506397dbf40c15dc567635d18a21d33827e9ab29014fb83d292a8f4f8953b6", size = 15047240, upload-time = "2026-03-31T16:54:31.955Z" },
-    { url = "https://files.pythonhosted.org/packages/42/37/a946bb416e37a57fa752b3100fd5ede0e28df94f92366d1716555d47c454/mypy-1.20.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:555493c44a4f5a1b58d611a43333e71a9981c6dbe26270377b6f8174126a0526", size = 15858565, upload-time = "2026-03-31T16:53:36.997Z" },
-    { url = "https://files.pythonhosted.org/packages/2f/99/7690b5b5b552db1bd4ff362e4c0eb3107b98d680835e65823fbe888c8b78/mypy-1.20.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:2721f0ce49cb74a38f00c50da67cb7d36317b5eda38877a49614dc018e91c787", size = 16087874, upload-time = "2026-03-31T16:52:48.313Z" },
-    { url = "https://files.pythonhosted.org/packages/aa/76/53e893a498138066acd28192b77495c9357e5a58cc4be753182846b43315/mypy-1.20.0-cp314-cp314t-win_amd64.whl", hash = "sha256:47781555a7aa5fedcc2d16bcd72e0dc83eb272c10dd657f9fb3f9cc08e2e6abb", size = 12572380, upload-time = "2026-03-31T16:49:52.454Z" },
-    { url = "https://files.pythonhosted.org/packages/76/9c/6dbdae21f01b7aacddc2c0bbf3c5557aa547827fdf271770fe1e521e7093/mypy-1.20.0-cp314-cp314t-win_arm64.whl", hash = "sha256:c70380fe5d64010f79fb863b9081c7004dd65225d2277333c219d93a10dad4dd", size = 10381174, upload-time = "2026-03-31T16:51:20.179Z" },
-    { url = "https://files.pythonhosted.org/packages/21/66/4d734961ce167f0fd8380769b3b7c06dbdd6ff54c2190f3f2ecd22528158/mypy-1.20.0-py3-none-any.whl", hash = "sha256:a6e0641147cbfa7e4e94efdb95c2dab1aff8cfc159ded13e07f308ddccc8c48e", size = 2636365, upload-time = "2026-03-31T16:51:44.911Z" },
+    { url = "https://files.pythonhosted.org/packages/76/97/ce2502df2cecf2ef997b6c6527c4a223b92feb9e7b790cdc8dcd683f3a8a/mypy-1.20.2-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:cf5a4db6dca263010e2c7bff081c89383c72d187ba2cf4c44759aac970e2f0c4", size = 14457059, upload-time = "2026-04-21T17:06:14.935Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/34/417ee60b822cc80c0f3dc9f495ad7fd8dbb8d8b2cf4baf22d4046d25d01d/mypy-1.20.2-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:7b0e817b518bff7facd7f85ea05b643ad8bdcce684cf29784987b0a7c8e1f997", size = 13346816, upload-time = "2026-04-21T17:10:41.433Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/85/e20951978702df58379d0bcc2e8f7ccdca4e78cd7dc66dd3ddbf9b29d517/mypy-1.20.2-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:97d7b9a485b40f8ca425460e89bf1da2814625b2da627c0dcc6aa46c92631d14", size = 13772593, upload-time = "2026-04-21T17:08:11.24Z" },
+    { url = "https://files.pythonhosted.org/packages/63/a5/5441a13259ec516c56fd5de0fd96a69a9590ae6c5e5d3e5174aa84b97973/mypy-1.20.2-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:1e1c12f6d2db3d78b909b5f77513c11eb7f2dd2782b96a3ab6dffc7d44575c99", size = 14656635, upload-time = "2026-04-21T17:09:54.042Z" },
+    { url = "https://files.pythonhosted.org/packages/3b/51/b89c69157c5e1f19fd125a65d991166a26906e7902f026f00feebbcfa2b9/mypy-1.20.2-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:89dce27e142d25ffbc154c1819383b69f2e9234dc4ed4766f42e0e8cb264ab5c", size = 14943278, upload-time = "2026-04-21T17:09:15.599Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/44/6b0eeecfe96d7cce1d71c66b8e03cb304aa70ec11f1955dc1d6b46aca3c3/mypy-1.20.2-cp310-cp310-win_amd64.whl", hash = "sha256:f376e37f9bf2a946872fc5fd1199c99310748e3c26c7a26683f13f8bdb756cbd", size = 10851915, upload-time = "2026-04-21T17:06:03.5Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/36/6593dc88545d75fb96416184be5392da5e2a8e8c2802a8597913e16ae25c/mypy-1.20.2-cp310-cp310-win_arm64.whl", hash = "sha256:6e2b469efd811707bc530fd1effef0f5d6eebcb7fe376affae69025da4b979a2", size = 9786676, upload-time = "2026-04-21T17:07:02.035Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/4d/9ebeae211caccbdaddde7ed5e31dfcf57faac66be9b11deb1dc6526c8078/mypy-1.20.2-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:4077797a273e56e8843d001e9dfe4ba10e33323d6ade647ff260e5cd97d9758c", size = 14371307, upload-time = "2026-04-21T17:08:56.442Z" },
+    { url = "https://files.pythonhosted.org/packages/95/d7/93473d34b61f04fac1aecc01368485c89c5c4af7a4b9a0cab5d77d04b63f/mypy-1.20.2-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:cdecf62abcc4292500d7858aeae87a1f8f1150f4c4dd08fb0b336ee79b2a6df3", size = 13258917, upload-time = "2026-04-21T17:05:50.978Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/30/3dd903e8bafb7b5f7bf87fcd58f8382086dea2aa19f0a7b357f21f63071b/mypy-1.20.2-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c566c3a88b6ece59b3d70f65bedef17304f48eb52ff040a6a18214e1917b3254", size = 13700516, upload-time = "2026-04-21T17:11:33.161Z" },
+    { url = "https://files.pythonhosted.org/packages/07/05/c61a140aba4c729ac7bc99ae26fc627c78a6e08f5b9dd319244ea71a3d7e/mypy-1.20.2-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0deb80d062b2479f2c87ae568f89845afc71d11bc41b04179e58165fd9f31e98", size = 14562889, upload-time = "2026-04-21T17:05:27.674Z" },
+    { url = "https://files.pythonhosted.org/packages/fd/87/da78243742ffa8a36d98c3010f0d829f93d5da4e6786f1a1a6f2ad616502/mypy-1.20.2-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:bba9ad231e92a3e424b3e56b65aa17704993425bba97e302c832f9466bb85bac", size = 14803844, upload-time = "2026-04-21T17:10:06.2Z" },
+    { url = "https://files.pythonhosted.org/packages/37/52/10a1ddf91b40f843943a3c6db51e2df59c9e237f29d355e95eaab427461f/mypy-1.20.2-cp311-cp311-win_amd64.whl", hash = "sha256:baf593f2765fa3a6b1ef95807dbaa3d25b594f6a52adcc506a6b9cb115e1be67", size = 10846300, upload-time = "2026-04-21T17:12:23.886Z" },
+    { url = "https://files.pythonhosted.org/packages/20/02/f9a4415b664c53bd34d6709be59da303abcae986dc4ac847b402edb6fa1e/mypy-1.20.2-cp311-cp311-win_arm64.whl", hash = "sha256:20175a1c0f49863946ec20b7f63255768058ac4f07d2b9ded6a6b46cfb5a9100", size = 9779498, upload-time = "2026-04-21T17:09:23.695Z" },
+    { url = "https://files.pythonhosted.org/packages/71/4e/7560e4528db9e9b147e4c0f22660466bf30a0a1fe3d63d1b9d3b0fd354ee/mypy-1.20.2-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:4dbfcf869f6b0517f70cf0030ba6ea1d6645e132337a7d5204a18d8d5636c02b", size = 14539393, upload-time = "2026-04-21T17:07:12.52Z" },
+    { url = "https://files.pythonhosted.org/packages/32/d9/34a5efed8124f5a9234f55ac6a4ced4201e2c5b81e1109c49ad23190ec8c/mypy-1.20.2-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:4b6481b228d072315b053210b01ac320e1be243dc17f9e5887ef167f23f5fae4", size = 13361642, upload-time = "2026-04-21T17:06:53.742Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/14/eb377acf78c03c92d566a1510cda8137348215b5335085ef662ab82ecd3a/mypy-1.20.2-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:34397cdced6b90b836e38182076049fdb41424322e0b0728c946b0939ebdf9f6", size = 13740347, upload-time = "2026-04-21T17:12:04.73Z" },
+    { url = "https://files.pythonhosted.org/packages/b9/94/7e4634a32b641aa1c112422eed1bbece61ee16205f674190e8b536f884de/mypy-1.20.2-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:a5da6976f20cae27059ea8d0c86e7cef3de720e04c4bb9ee18e3690fdb792066", size = 14734042, upload-time = "2026-04-21T17:07:43.16Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/f3/f7e62395cb7f434541b4491a01149a4439e28ace4c0c632bbf5431e92d1f/mypy-1.20.2-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:56908d7e08318d39f85b1f0c6cfd47b0cac1a130da677630dac0de3e0623e102", size = 14964958, upload-time = "2026-04-21T17:11:00.665Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/0d/47e3c3a0ec2a876e35aeac365df3cac7776c36bbd4ed18cc521e1b9d255b/mypy-1.20.2-cp312-cp312-win_amd64.whl", hash = "sha256:d52ad8d78522da1d308789df651ee5379088e77c76cb1994858d40a426b343b9", size = 10911340, upload-time = "2026-04-21T17:10:49.179Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/b2/6c852d72e0ea8b01f49da817fb52539993cde327e7d010e0103dc12d0dac/mypy-1.20.2-cp312-cp312-win_arm64.whl", hash = "sha256:785b08db19c9f214dc37d65f7c165d19a30fcecb48abfa30f31b01b5acaabb58", size = 9833947, upload-time = "2026-04-21T17:09:05.267Z" },
+    { url = "https://files.pythonhosted.org/packages/5b/c4/b93812d3a192c9bcf5df405bd2f30277cd0e48106a14d1023c7f6ed6e39b/mypy-1.20.2-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:edfbfca868cdd6bd8d974a60f8a3682f5565d3f5c99b327640cedd24c4264026", size = 14524670, upload-time = "2026-04-21T17:10:30.737Z" },
+    { url = "https://files.pythonhosted.org/packages/f3/47/42c122501bff18eaf1e8f457f5c017933452d8acdc52918a9f59f6812955/mypy-1.20.2-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:e2877a02380adfcdbc69071a0f74d6e9dbbf593c0dc9d174e1f223ffd5281943", size = 13336218, upload-time = "2026-04-21T17:08:44.069Z" },
+    { url = "https://files.pythonhosted.org/packages/92/8f/75bbc92f41725fbd585fb17b440b1119b576105df1013622983e18640a93/mypy-1.20.2-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:7488448de6007cd5177c6cea0517ac33b4c0f5ee9b5e9f2be51ce75511a85517", size = 13724906, upload-time = "2026-04-21T17:08:01.02Z" },
+    { url = "https://files.pythonhosted.org/packages/a1/32/4c49da27a606167391ff0c39aa955707a00edc500572e562f7c36c08a71f/mypy-1.20.2-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:bb9c2fa06887e21d6a3a868762acb82aec34e2c6fd0174064f27c93ede68ad15", size = 14726046, upload-time = "2026-04-21T17:11:22.354Z" },
+    { url = "https://files.pythonhosted.org/packages/7f/fc/4e354a1bd70216359deb0c9c54847ee6b32ef78dfb09f5131ff99b494078/mypy-1.20.2-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:9d56a78b646f2e3daa865bc70cd5ec5a46c50045801ca8ff17a0c43abc97e3ee", size = 14955587, upload-time = "2026-04-21T17:12:16.033Z" },
+    { url = "https://files.pythonhosted.org/packages/62/b2/c0f2056e9eb8f08c62cafd9715e4584b89132bdc832fcf85d27d07b5f3e5/mypy-1.20.2-cp313-cp313-win_amd64.whl", hash = "sha256:2a4102b03bb7481d9a91a6da8d174740c9c8c4401024684b9ca3b7cc5e49852f", size = 10922681, upload-time = "2026-04-21T17:06:35.842Z" },
+    { url = "https://files.pythonhosted.org/packages/e5/14/065e333721f05de8ef683d0aa804c23026bcc287446b61cac657b902ccac/mypy-1.20.2-cp313-cp313-win_arm64.whl", hash = "sha256:a95a9248b0c6fd933a442c03c3b113c3b61320086b88e2c444676d3fd1ca3330", size = 9830560, upload-time = "2026-04-21T17:07:51.023Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/d1/b4ec96b0ecc620a4443570c6e95c867903428cfcde4206518eafdd5880c3/mypy-1.20.2-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:419413398fe250aae057fd2fe50166b61077083c9b82754c341cf4fd73038f30", size = 14524561, upload-time = "2026-04-21T17:06:27.325Z" },
+    { url = "https://files.pythonhosted.org/packages/3a/63/d2c2ff4fa66bc49477d32dfa26e8a167ba803ea6a69c5efb416036909d30/mypy-1.20.2-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:e73c07f23009962885c197ccb9b41356a30cc0e5a1d0c2ea8fd8fb1362d7f924", size = 13363883, upload-time = "2026-04-21T17:11:11.239Z" },
+    { url = "https://files.pythonhosted.org/packages/2a/56/983916806bf4eddeaaa2c9230903c3669c6718552a921154e1c5182c701f/mypy-1.20.2-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0c64e5973df366b747646fc98da921f9d6eba9716d57d1db94a83c026a08e0fb", size = 13742945, upload-time = "2026-04-21T17:08:34.181Z" },
+    { url = "https://files.pythonhosted.org/packages/19/65/0cd9285ab010ee8214c83d67c6b49417c40d86ce46f1aa109457b5a9b8d7/mypy-1.20.2-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:5a65aa591af023864fd08a97da9974e919452cfe19cb146c8a5dc692626445dc", size = 14706163, upload-time = "2026-04-21T17:05:15.51Z" },
+    { url = "https://files.pythonhosted.org/packages/94/97/48ff3b297cafcc94d185243a9190836fb1b01c1b0918fff64e941e973cc9/mypy-1.20.2-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:4fef51b01e638974a6e69885687e9bd40c8d1e09a6cd291cca0619625cf1f558", size = 14938677, upload-time = "2026-04-21T17:05:39.562Z" },
+    { url = "https://files.pythonhosted.org/packages/fd/a1/1b4233d255bdd0b38a1f284feeb1c143ca508c19184964e22f8d837ec851/mypy-1.20.2-cp314-cp314-win_amd64.whl", hash = "sha256:913485a03f1bcf5d279409a9d2b9ed565c151f61c09f29991e5faa14033da4c8", size = 11089322, upload-time = "2026-04-21T17:06:44.29Z" },
+    { url = "https://files.pythonhosted.org/packages/78/c2/ce7ee2ba36aeb954ba50f18fa25d9c1188578654b97d02a66a15b6f09531/mypy-1.20.2-cp314-cp314-win_arm64.whl", hash = "sha256:c3bae4f855d965b5453784300c12ffc63a548304ac7f99e55d4dc7c898673aa3", size = 10017775, upload-time = "2026-04-21T17:07:20.732Z" },
+    { url = "https://files.pythonhosted.org/packages/4e/a1/9d93a7d0b5859af0ead82b4888b46df6c8797e1bc5e1e262a08518c6d48e/mypy-1.20.2-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:2de3dcea53babc1c3237a19002bc3d228ce1833278f093b8d619e06e7cc79609", size = 15549002, upload-time = "2026-04-21T17:08:23.107Z" },
+    { url = "https://files.pythonhosted.org/packages/00/d2/09a6a10ee1bf0008f6c144d9676f2ca6a12512151b4e0ad0ff6c4fac5337/mypy-1.20.2-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:52b176444e2e5054dfcbcb8c75b0b719865c96247b37407184bbfca5c353f2c2", size = 14401942, upload-time = "2026-04-21T17:07:31.837Z" },
+    { url = "https://files.pythonhosted.org/packages/57/da/9594b75c3c019e805250bed3583bdf4443ff9e6ef08f97e39ae308cb06f2/mypy-1.20.2-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:688c3312e5dadb573a2c69c82af3a298d43ecf9e6d264e0f95df960b5f6ac19c", size = 15041649, upload-time = "2026-04-21T17:09:34.653Z" },
+    { url = "https://files.pythonhosted.org/packages/97/77/f75a65c278e6e8eba2071f7f5a90481891053ecc39878cc444634d892abe/mypy-1.20.2-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:29752dbbf8cc53f89f6ac096d363314333045c257c9c75cbd189ca2de0455744", size = 15864588, upload-time = "2026-04-21T17:11:44.936Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/46/1a4e1c66e96c1a3246ddf5403d122ac9b0a8d2b7e65730b9d6533ba7a6d3/mypy-1.20.2-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:803203d2b6ea644982c644895c2f78b28d0e208bba7b27d9b921e0ec5eb207c6", size = 16093956, upload-time = "2026-04-21T17:10:17.683Z" },
+    { url = "https://files.pythonhosted.org/packages/5a/2c/78a8851264dec38cd736ca5b8bc9380674df0dd0be7792f538916157716c/mypy-1.20.2-cp314-cp314t-win_amd64.whl", hash = "sha256:9bcb8aa397ff0093c824182fd76a935a9ba7ad097fcbef80ae89bf6c1731d8ec", size = 12568661, upload-time = "2026-04-21T17:11:54.473Z" },
+    { url = "https://files.pythonhosted.org/packages/83/01/cd7318aa03493322ce275a0e14f4f52b8896335e4e79d4fb8153a7ad2b77/mypy-1.20.2-cp314-cp314t-win_arm64.whl", hash = "sha256:e061b58443f1736f8a37c48978d7ab581636d6ab03e3d4f99e3fa90463bb9382", size = 10389240, upload-time = "2026-04-21T17:09:42.719Z" },
+    { url = "https://files.pythonhosted.org/packages/28/9a/f23c163e25b11074188251b0b5a0342625fc1cdb6af604757174fa9acc9b/mypy-1.20.2-py3-none-any.whl", hash = "sha256:a94c5a76ab46c5e6257c7972b6c8cff0574201ca7dc05647e33e795d78680563", size = 2637314, upload-time = "2026-04-21T17:05:54.5Z" },
 ]
 
 [[package]]
@@ -621,7 +635,8 @@ name = "numpy"
 version = "2.4.1"
 source = { registry = "https://pypi.org/simple" }
 resolution-markers = [
-    "python_full_version >= '3.12'",
+    "python_full_version >= '3.15'",
+    "python_full_version >= '3.12' and python_full_version < '3.15'",
     "python_full_version == '3.11.*'",
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/24/62/ae72ff66c0f1fd959925b4c11f8c2dea61f47f6acaea75a08512cdfe3fed/numpy-2.4.1.tar.gz", hash = "sha256:a1ceafc5042451a858231588a104093474c6a5c57dcc724841f5c888d237d690", size = 20721320, upload-time = "2026-01-10T06:44:59.619Z" }
@@ -1299,27 +1314,27 @@ wheels = [
 
 [[package]]
 name = "ruff"
-version = "0.15.8"
+version = "0.15.12"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/14/b0/73cf7550861e2b4824950b8b52eebdcc5adc792a00c514406556c5b80817/ruff-0.15.8.tar.gz", hash = "sha256:995f11f63597ee362130d1d5a327a87cb6f3f5eae3094c620bcc632329a4d26e", size = 4610921, upload-time = "2026-03-26T18:39:38.675Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/99/43/3291f1cc9106f4c63bdce7a8d0df5047fe8422a75b091c16b5e9355e0b11/ruff-0.15.12.tar.gz", hash = "sha256:ecea26adb26b4232c0c2ca19ccbc0083a68344180bba2a600605538ce51a40a6", size = 4643852, upload-time = "2026-04-24T18:17:14.305Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/4a/92/c445b0cd6da6e7ae51e954939cb69f97e008dbe750cfca89b8cedc081be7/ruff-0.15.8-py3-none-linux_armv6l.whl", hash = "sha256:cbe05adeba76d58162762d6b239c9056f1a15a55bd4b346cfd21e26cd6ad7bc7", size = 10527394, upload-time = "2026-03-26T18:39:41.566Z" },
-    { url = "https://files.pythonhosted.org/packages/eb/92/f1c662784d149ad1414cae450b082cf736430c12ca78367f20f5ed569d65/ruff-0.15.8-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:d3e3d0b6ba8dca1b7ef9ab80a28e840a20070c4b62e56d675c24f366ef330570", size = 10905693, upload-time = "2026-03-26T18:39:30.364Z" },
-    { url = "https://files.pythonhosted.org/packages/ca/f2/7a631a8af6d88bcef997eb1bf87cc3da158294c57044aafd3e17030613de/ruff-0.15.8-py3-none-macosx_11_0_arm64.whl", hash = "sha256:6ee3ae5c65a42f273f126686353f2e08ff29927b7b7e203b711514370d500de3", size = 10323044, upload-time = "2026-03-26T18:39:33.37Z" },
-    { url = "https://files.pythonhosted.org/packages/67/18/1bf38e20914a05e72ef3b9569b1d5c70a7ef26cd188d69e9ca8ef588d5bf/ruff-0.15.8-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:fdce027ada77baa448077ccc6ebb2fa9c3c62fd110d8659d601cf2f475858d94", size = 10629135, upload-time = "2026-03-26T18:39:44.142Z" },
-    { url = "https://files.pythonhosted.org/packages/d2/e9/138c150ff9af60556121623d41aba18b7b57d95ac032e177b6a53789d279/ruff-0.15.8-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:12e617fc01a95e5821648a6df341d80456bd627bfab8a829f7cfc26a14a4b4a3", size = 10348041, upload-time = "2026-03-26T18:39:52.178Z" },
-    { url = "https://files.pythonhosted.org/packages/02/f1/5bfb9298d9c323f842c5ddeb85f1f10ef51516ac7a34ba446c9347d898df/ruff-0.15.8-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:432701303b26416d22ba696c39f2c6f12499b89093b61360abc34bcc9bf07762", size = 11121987, upload-time = "2026-03-26T18:39:55.195Z" },
-    { url = "https://files.pythonhosted.org/packages/10/11/6da2e538704e753c04e8d86b1fc55712fdbdcc266af1a1ece7a51fff0d10/ruff-0.15.8-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:d910ae974b7a06a33a057cb87d2a10792a3b2b3b35e33d2699fdf63ec8f6b17a", size = 11951057, upload-time = "2026-03-26T18:39:19.18Z" },
-    { url = "https://files.pythonhosted.org/packages/83/f0/c9208c5fd5101bf87002fed774ff25a96eea313d305f1e5d5744698dc314/ruff-0.15.8-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:2033f963c43949d51e6fdccd3946633c6b37c484f5f98c3035f49c27395a8ab8", size = 11464613, upload-time = "2026-03-26T18:40:06.301Z" },
-    { url = "https://files.pythonhosted.org/packages/f8/22/d7f2fabdba4fae9f3b570e5605d5eb4500dcb7b770d3217dca4428484b17/ruff-0.15.8-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:0f29b989a55572fb885b77464cf24af05500806ab4edf9a0fd8977f9759d85b1", size = 11257557, upload-time = "2026-03-26T18:39:57.972Z" },
-    { url = "https://files.pythonhosted.org/packages/71/8c/382a9620038cf6906446b23ce8632ab8c0811b8f9d3e764f58bedd0c9a6f/ruff-0.15.8-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:ac51d486bf457cdc985a412fb1801b2dfd1bd8838372fc55de64b1510eff4bec", size = 11169440, upload-time = "2026-03-26T18:39:22.205Z" },
-    { url = "https://files.pythonhosted.org/packages/4d/0d/0994c802a7eaaf99380085e4e40c845f8e32a562e20a38ec06174b52ef24/ruff-0.15.8-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:c9861eb959edab053c10ad62c278835ee69ca527b6dcd72b47d5c1e5648964f6", size = 10605963, upload-time = "2026-03-26T18:39:46.682Z" },
-    { url = "https://files.pythonhosted.org/packages/19/aa/d624b86f5b0aad7cef6bbf9cd47a6a02dfdc4f72c92a337d724e39c9d14b/ruff-0.15.8-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:8d9a5b8ea13f26ae90838afc33f91b547e61b794865374f114f349e9036835fb", size = 10357484, upload-time = "2026-03-26T18:39:49.176Z" },
-    { url = "https://files.pythonhosted.org/packages/35/c3/e0b7835d23001f7d999f3895c6b569927c4d39912286897f625736e1fd04/ruff-0.15.8-py3-none-musllinux_1_2_i686.whl", hash = "sha256:c2a33a529fb3cbc23a7124b5c6ff121e4d6228029cba374777bd7649cc8598b8", size = 10830426, upload-time = "2026-03-26T18:40:03.702Z" },
-    { url = "https://files.pythonhosted.org/packages/f0/51/ab20b322f637b369383adc341d761eaaa0f0203d6b9a7421cd6e783d81b9/ruff-0.15.8-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:75e5cd06b1cf3f47a3996cfc999226b19aa92e7cce682dcd62f80d7035f98f49", size = 11345125, upload-time = "2026-03-26T18:39:27.799Z" },
-    { url = "https://files.pythonhosted.org/packages/37/e6/90b2b33419f59d0f2c4c8a48a4b74b460709a557e8e0064cf33ad894f983/ruff-0.15.8-py3-none-win32.whl", hash = "sha256:bc1f0a51254ba21767bfa9a8b5013ca8149dcf38092e6a9eb704d876de94dc34", size = 10571959, upload-time = "2026-03-26T18:39:36.117Z" },
-    { url = "https://files.pythonhosted.org/packages/1f/a2/ef467cb77099062317154c63f234b8a7baf7cb690b99af760c5b68b9ee7f/ruff-0.15.8-py3-none-win_amd64.whl", hash = "sha256:04f79eff02a72db209d47d665ba7ebcad609d8918a134f86cb13dd132159fc89", size = 11743893, upload-time = "2026-03-26T18:39:25.01Z" },
-    { url = "https://files.pythonhosted.org/packages/15/e2/77be4fff062fa78d9b2a4dea85d14785dac5f1d0c1fb58ed52331f0ebe28/ruff-0.15.8-py3-none-win_arm64.whl", hash = "sha256:cf891fa8e3bb430c0e7fac93851a5978fc99c8fa2c053b57b118972866f8e5f2", size = 11048175, upload-time = "2026-03-26T18:40:01.06Z" },
+    { url = "https://files.pythonhosted.org/packages/c3/6e/e78ffb61d4686f3d96ba3df2c801161843746dcbcbb17a1e927d4829312b/ruff-0.15.12-py3-none-linux_armv6l.whl", hash = "sha256:f86f176e188e94d6bdbc09f09bfd9dc729059ad93d0e7390b5a73efe19f8861c", size = 10640713, upload-time = "2026-04-24T18:17:22.841Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/08/a317bc231fb9e7b93e4ef3089501e51922ff88d6936ce5cf870c4fe55419/ruff-0.15.12-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:e3bcd123364c3770b8e1b7baaf343cc99a35f197c5c6e8af79015c666c423a6c", size = 11069267, upload-time = "2026-04-24T18:17:30.105Z" },
+    { url = "https://files.pythonhosted.org/packages/aa/a4/f828e9718d3dce1f5f11c39c4f65afd32783c8b2aebb2e3d259e492c47bd/ruff-0.15.12-py3-none-macosx_11_0_arm64.whl", hash = "sha256:fe87510d000220aa1ed530d4448a7c696a0cae1213e5ec30e5874287b66557b5", size = 10397182, upload-time = "2026-04-24T18:17:07.177Z" },
+    { url = "https://files.pythonhosted.org/packages/71/e0/3310fc6d1b5e1fdea22bf3b1b807c7e187b581021b0d7d4514cccdb5fb71/ruff-0.15.12-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:84a1630093121375a3e2a95b4a6dc7b59e2b4ee76216e32d81aae550a832d002", size = 10758012, upload-time = "2026-04-24T18:16:55.759Z" },
+    { url = "https://files.pythonhosted.org/packages/11/c1/a606911aee04c324ddaa883ae418f3569792fd3c4a10c50e0dd0a2311e1e/ruff-0.15.12-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:fb129f40f114f089ebe0ca56c0d251cf2061b17651d464bb6478dc01e69f11f5", size = 10447479, upload-time = "2026-04-24T18:16:51.677Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/68/4201e8444f0894f21ab4aeeaee68aa4f10b51613514a20d80bd628d57e88/ruff-0.15.12-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:b0c862b172d695db7598426b8af465e7e9ac00a3ea2a3630ee67eb82e366aaa6", size = 11234040, upload-time = "2026-04-24T18:17:16.529Z" },
+    { url = "https://files.pythonhosted.org/packages/34/ff/8a6d6cf4ccc23fd67060874e832c18919d1557a0611ebef03fdb01fff11e/ruff-0.15.12-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:2849ea9f3484c3aca43a82f484210370319e7170df4dfe4843395ddf6c57bc33", size = 12087377, upload-time = "2026-04-24T18:17:04.944Z" },
+    { url = "https://files.pythonhosted.org/packages/85/f6/c669cf73f5152f623d34e69866a46d5e6185816b19fcd5b6dd8a2d299922/ruff-0.15.12-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:9e77c7e51c07fe396826d5969a5b846d9cd4c402535835fb6e21ce8b28fef847", size = 11367784, upload-time = "2026-04-24T18:17:25.409Z" },
+    { url = "https://files.pythonhosted.org/packages/e8/39/c61d193b8a1daaa8977f7dea9e8d8ba866e02ea7b65d32f6861693aa4c12/ruff-0.15.12-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:83b2f4f2f3b1026b5fb449b467d9264bf22067b600f7b6f41fc5958909f449d0", size = 11344088, upload-time = "2026-04-24T18:17:12.258Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/8d/49afab3645e31e12c590acb6d3b5b69d7aab5b81926dbaf7461f9441f37a/ruff-0.15.12-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:9ba3b8f1afd7e2e43d8943e55f249e13f9682fde09711644a6e7290eb4f3e339", size = 11271770, upload-time = "2026-04-24T18:17:02.457Z" },
+    { url = "https://files.pythonhosted.org/packages/46/06/33f41fe94403e2b755481cdfb9b7ef3e4e0ed031c4581124658d935d52b4/ruff-0.15.12-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:e852ba9fdc890655e1d78f2df1499efbe0e54126bd405362154a75e2bde159c5", size = 10719355, upload-time = "2026-04-24T18:17:27.648Z" },
+    { url = "https://files.pythonhosted.org/packages/0d/59/18aa4e014debbf559670e4048e39260a85c7fcee84acfd761ac01e7b8d35/ruff-0.15.12-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:dd8aed930da53780d22fc70bdf84452c843cf64f8cb4eb38984319c24c5cd5fd", size = 10462758, upload-time = "2026-04-24T18:17:32.347Z" },
+    { url = "https://files.pythonhosted.org/packages/25/e7/cc9f16fd0f3b5fddcbd7ec3d6ae30c8f3fde1047f32a4093a98d633c6570/ruff-0.15.12-py3-none-musllinux_1_2_i686.whl", hash = "sha256:01da3988d225628b709493d7dc67c3b9b12c0210016b08690ef9bd27970b262b", size = 10953498, upload-time = "2026-04-24T18:17:20.674Z" },
+    { url = "https://files.pythonhosted.org/packages/72/7a/a9ba7f98c7a575978698f4230c5e8cc54bbc761af34f560818f933dafa0c/ruff-0.15.12-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:9cae0f92bd5700d1213188b31cd3bdd2b315361296d10b96b8e2337d3d11f53e", size = 11447765, upload-time = "2026-04-24T18:17:09.755Z" },
+    { url = "https://files.pythonhosted.org/packages/ea/f9/0ae446942c846b8266059ad8a30702a35afae55f5cdc54c5adf8d7afdc27/ruff-0.15.12-py3-none-win32.whl", hash = "sha256:d0185894e038d7043ba8fd6aee7499ece6462dc0ea9f1e260c7451807c714c20", size = 10657277, upload-time = "2026-04-24T18:17:18.591Z" },
+    { url = "https://files.pythonhosted.org/packages/33/f1/9614e03e1cdcbf9437570b5400ced8a720b5db22b28d8e0f1bda429f660d/ruff-0.15.12-py3-none-win_amd64.whl", hash = "sha256:c87a162d61ab3adca47c03f7f717c68672edec7d1b5499e652331780fe74950d", size = 11837758, upload-time = "2026-04-24T18:17:00.113Z" },
+    { url = "https://files.pythonhosted.org/packages/c0/98/6beb4b351e472e5f4c4613f7c35a5290b8be2497e183825310c4c3a3984b/ruff-0.15.12-py3-none-win_arm64.whl", hash = "sha256:a538f7a82d061cee7be55542aca1d86d1393d55d81d4fcc314370f4340930d4f", size = 11120821, upload-time = "2026-04-24T18:16:57.979Z" },
 ]
 
 [[package]]

libs/cli/js-examples/package.json

@@ -21,25 +21,25 @@
     "test:all": "yarn test && yarn test:int && yarn lint:langgraph"
   },
   "dependencies": {
-    "@langchain/core": "^1.1.38",
-    "@langchain/langgraph": "^1.2.6"
+    "@langchain/core": "^1.1.42",
+    "@langchain/langgraph": "^1.2.9"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.5",
     "@eslint/js": "^10.0.1",
     "@tsconfig/recommended": "^1.0.13",
     "@types/jest": "^30.0.0",
-    "@typescript-eslint/eslint-plugin": "^8.58.0",
-    "@typescript-eslint/parser": "^8.58.0",
-    "dotenv": "^17.3.1",
-    "eslint": "^10.1.0",
+    "@typescript-eslint/eslint-plugin": "^8.59.1",
+    "@typescript-eslint/parser": "^8.59.1",
+    "dotenv": "^17.4.2",
+    "eslint": "^10.2.1",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-no-instanceof": "^1.0.1",
     "eslint-plugin-prettier": "^5.5.5",
     "jest": "^30.3.0",
-    "prettier": "^3.8.1",
-    "ts-jest": "^29.4.6",
+    "prettier": "^3.8.3",
+    "ts-jest": "^29.4.9",
     "typescript": "^5.9.3"
   }
 }

libs/cli/js-examples/yarn.lock

@@ -474,26 +474,26 @@
   resolved "https://registry.yarnpkg.com/@eslint-community/regexpp/-/regexpp-4.12.2.tgz#bccdf615bcf7b6e8db830ec0b8d21c9a25de597b"
   integrity sha512-EriSTlt5OC9/7SXkRSCAhfSxxoSUgBm33OH+IkwbdpgoqsSsUg7y3uh+IICI/Qg4BBWr3U2i39RpmycbxMq4ew==
 
-"@eslint/config-array@^0.23.3":
-  version "0.23.3"
-  resolved "https://registry.yarnpkg.com/@eslint/config-array/-/config-array-0.23.3.tgz#3f4a93dd546169c09130cbd10f2415b13a20a219"
-  integrity sha512-j+eEWmB6YYLwcNOdlwQ6L2OsptI/LO6lNBuLIqe5R7RetD658HLoF+Mn7LzYmAWWNNzdC6cqP+L6r8ujeYXWLw==
+"@eslint/config-array@^0.23.5":
+  version "0.23.5"
+  resolved "https://registry.yarnpkg.com/@eslint/config-array/-/config-array-0.23.5.tgz#56e86d243049195d8acc0c06a1b3dfdc3fa3de95"
+  integrity sha512-Y3kKLvC1dvTOT+oGlqNQ1XLqK6D1HU2YXPc52NmAlJZbMMWDzGYXMiPRJ8TYD39muD/OTjlZmNJ4ib7dvSrMBA==
   dependencies:
-    "@eslint/object-schema" "^3.0.3"
+    "@eslint/object-schema" "^3.0.5"
     debug "^4.3.1"
     minimatch "^10.2.4"
 
-"@eslint/config-helpers@^0.5.3":
-  version "0.5.3"
-  resolved "https://registry.yarnpkg.com/@eslint/config-helpers/-/config-helpers-0.5.3.tgz#721fe6bbb90d74b0c80d6ff2428e5bbcb002becb"
-  integrity sha512-lzGN0onllOZCGroKJmRwY6QcEHxbjBw1gwB8SgRSqK8YbbtEXMvKynsXc3553ckIEBxsbMBU7oOZXKIPGZNeZw==
+"@eslint/config-helpers@^0.5.5":
+  version "0.5.5"
+  resolved "https://registry.yarnpkg.com/@eslint/config-helpers/-/config-helpers-0.5.5.tgz#ae16134e4792ac5fbdc533548a24ac1ea9f7f3ae"
+  integrity sha512-eIJYKTCECbP/nsKaaruF6LW967mtbQbsw4JTtSVkUQc9MneSkbrgPJAbKl9nWr0ZeowV8BfsarBmPpBzGelA2w==
   dependencies:
-    "@eslint/core" "^1.1.1"
+    "@eslint/core" "^1.2.1"
 
-"@eslint/core@^1.1.1":
-  version "1.1.1"
-  resolved "https://registry.yarnpkg.com/@eslint/core/-/core-1.1.1.tgz#450f3d2be2d463ccd51119544092256b4e88df32"
-  integrity sha512-QUPblTtE51/7/Zhfv8BDwO0qkkzQL7P/aWWbqcf4xWLEYn1oKjdO0gglQBB4GAsu7u6wjijbCmzsUTy6mnk6oQ==
+"@eslint/core@^1.2.1":
+  version "1.2.1"
+  resolved "https://registry.yarnpkg.com/@eslint/core/-/core-1.2.1.tgz#c1da7cd1b82fa8787f98b5629fb811848a1b63ce"
+  integrity sha512-MwcE1P+AZ4C6DWlpin/OmOA54mmIZ/+xZuJiQd4SyB29oAJjN30UW9wkKNptW2ctp4cEsvhlLY/CsQ1uoHDloQ==
   dependencies:
     "@types/json-schema" "^7.0.15"
 
@@ -517,17 +517,17 @@
   resolved "https://registry.yarnpkg.com/@eslint/js/-/js-10.0.1.tgz#1e8a876f50117af8ab67e47d5ad94d38d6622583"
   integrity sha512-zeR9k5pd4gxjZ0abRoIaxdc7I3nDktoXZk2qOv9gCNWx3mVwEn32VRhyLaRsDiJjTs0xq/T8mfPtyuXu7GWBcA==
 
-"@eslint/object-schema@^3.0.3":
-  version "3.0.3"
-  resolved "https://registry.yarnpkg.com/@eslint/object-schema/-/object-schema-3.0.3.tgz#5bf671e52e382e4adc47a9906f2699374637db6b"
-  integrity sha512-iM869Pugn9Nsxbh/YHRqYiqd23AmIbxJOcpUMOuWCVNdoQJ5ZtwL6h3t0bcZzJUlC3Dq9jCFCESBZnX0GTv7iQ==
+"@eslint/object-schema@^3.0.5":
+  version "3.0.5"
+  resolved "https://registry.yarnpkg.com/@eslint/object-schema/-/object-schema-3.0.5.tgz#88e9bf4d11d2b19c082e78ebe7ce88724a5eb091"
+  integrity sha512-vqTaUEgxzm+YDSdElad6PiRoX4t8VGDjCtt05zn4nU810UIx/uNEV7/lZJ6KwFThKZOzOxzXy48da+No7HZaMw==
 
-"@eslint/plugin-kit@^0.6.1":
-  version "0.6.1"
-  resolved "https://registry.yarnpkg.com/@eslint/plugin-kit/-/plugin-kit-0.6.1.tgz#eb9e6689b56ce8bc1855bb33090e63f3fc115e8e"
-  integrity sha512-iH1B076HoAshH1mLpHMgwdGeTs0CYwL0SPMkGuSebZrwBp16v415e9NZXg2jtrqPVQjf6IANe2Vtlr5KswtcZQ==
+"@eslint/plugin-kit@^0.7.1":
+  version "0.7.1"
+  resolved "https://registry.yarnpkg.com/@eslint/plugin-kit/-/plugin-kit-0.7.1.tgz#c4125fd015eceeb09b793109fdbcd4dd0a02d346"
+  integrity sha512-rZAP3aVgB9ds9KOeUSL+zZ21hPmo8dh6fnIFwRQj5EAZl9gzR7wxYbYXYysAM8CTqGmUGyp2S4kUdV17MnGuWQ==
   dependencies:
-    "@eslint/core" "^1.1.1"
+    "@eslint/core" "^1.2.1"
     levn "^0.4.1"
 
 "@humanfs/core@^0.19.1":
@@ -890,10 +890,10 @@
     "@jridgewell/resolve-uri" "^3.1.0"
     "@jridgewell/sourcemap-codec" "^1.4.14"
 
-"@langchain/core@^1.1.38":
-  version "1.1.38"
-  resolved "https://registry.yarnpkg.com/@langchain/core/-/core-1.1.38.tgz#b5939b2e77af408771c9bb95bf56a5ad8183313e"
-  integrity sha512-C340wH1YL10CiVOFlEpQMp0zQE85/eBLKX/gi1Lv7shAyUmR3CQ0t/mXlCd5RsZa6ntAN1kDJnp64ArWey9XAA==
+"@langchain/core@^1.1.42":
+  version "1.1.42"
+  resolved "https://registry.yarnpkg.com/@langchain/core/-/core-1.1.42.tgz#607bfd34c1414c9cbeb2859fda1b254a14c28085"
+  integrity sha512-d0tN96BrwPMryYyWR9VfyAntSivn7EQrZCe5Kpxum93tcjTXbKKmKvItFec8AluQt88iTcmAJrahUZUNfzGwTA==
   dependencies:
     "@cfworker/json-schema" "^4.0.2"
     "@standard-schema/spec" "^1.1.0"
@@ -904,7 +904,6 @@
     langsmith ">=0.5.0 <1.0.0"
     mustache "^4.2.0"
     p-queue "^6.6.2"
-    uuid "^11.1.0"
     zod "^3.25.76 || ^4"
 
 "@langchain/langgraph-checkpoint@^1.0.1":
@@ -914,23 +913,23 @@
   dependencies:
     uuid "^10.0.0"
 
-"@langchain/langgraph-sdk@~1.8.1":
-  version "1.8.3"
-  resolved "https://registry.yarnpkg.com/@langchain/langgraph-sdk/-/langgraph-sdk-1.8.3.tgz#deedc9bddd863693c6ab5f3a74058548b040377d"
-  integrity sha512-Py0S5yVtlOHz410aEsSGLRKjtsK2giDvfPS1JjAjTdcs71khuJufFtUZFwmwdJCbsG4DaGurRLHOAJu9jO4a0g==
+"@langchain/langgraph-sdk@~1.8.9":
+  version "1.8.10"
+  resolved "https://registry.yarnpkg.com/@langchain/langgraph-sdk/-/langgraph-sdk-1.8.10.tgz#bd175cda1ab629845ef28b22b45f3bdd1f65b029"
+  integrity sha512-wrB3rkRw5KAmsqezwvKP3midT4qJrV6Hj9XJMYo+cbvXC4HYpSAmyY/VriSyeTFRbLG/OP/pY2Yz+9Z54nSaXQ==
   dependencies:
     "@types/json-schema" "^7.0.15"
     p-queue "^9.0.1"
     p-retry "^7.1.1"
     uuid "^13.0.0"
 
-"@langchain/langgraph@^1.2.6":
-  version "1.2.6"
-  resolved "https://registry.yarnpkg.com/@langchain/langgraph/-/langgraph-1.2.6.tgz#e6a578f96fbbc1c54ba78e0298884671dad5d195"
-  integrity sha512-5cX402dNGN6w9+0mlMU2dgUiKx6Y1tlENp7x05e9ByDbQCHSDc0kyqRWNFLGc7vatQ92S4ylxQrcCJvi8Fr4SQ==
+"@langchain/langgraph@^1.2.9":
+  version "1.2.9"
+  resolved "https://registry.yarnpkg.com/@langchain/langgraph/-/langgraph-1.2.9.tgz#4f0ba159062c3649c83cf5f621ef926b96933e32"
+  integrity sha512-3c7BtGycHC2v9p6w/Hv8L7kEl1YnZYOQTDJtmAp3knk6JOedO7d2bYP3y0SRyhv5orUEGf/KGvx8ZsB/ideP7g==
   dependencies:
     "@langchain/langgraph-checkpoint" "^1.0.1"
-    "@langchain/langgraph-sdk" "~1.8.1"
+    "@langchain/langgraph-sdk" "~1.8.9"
     "@standard-schema/spec" "1.1.0"
     uuid "^10.0.0"
 
@@ -1098,100 +1097,100 @@
   dependencies:
     "@types/yargs-parser" "*"
 
-"@typescript-eslint/eslint-plugin@^8.58.0":
-  version "8.58.0"
-  resolved "https://registry.yarnpkg.com/@typescript-eslint/eslint-plugin/-/eslint-plugin-8.58.0.tgz#ad40e492f1931f46da1bd888e52b9e56df9063aa"
-  integrity sha512-RLkVSiNuUP1C2ROIWfqX+YcUfLaSnxGE/8M+Y57lopVwg9VTYYfhuz15Yf1IzCKgZj6/rIbYTmJCUSqr76r0Wg==
+"@typescript-eslint/eslint-plugin@^8.59.1":
+  version "8.59.1"
+  resolved "https://registry.yarnpkg.com/@typescript-eslint/eslint-plugin/-/eslint-plugin-8.59.1.tgz#781bc6f9002982cfaf75a185240e24ad7276628a"
+  integrity sha512-BOziFIfE+6osHO9FoJG4zjoHUcvI7fTNBSpdAwrNH0/TLvzjsk2oo8XSSOT2HhqUyhZPfHv4UOffoJ9oEEQ7Ag==
   dependencies:
     "@eslint-community/regexpp" "^4.12.2"
-    "@typescript-eslint/scope-manager" "8.58.0"
-    "@typescript-eslint/type-utils" "8.58.0"
-    "@typescript-eslint/utils" "8.58.0"
-    "@typescript-eslint/visitor-keys" "8.58.0"
+    "@typescript-eslint/scope-manager" "8.59.1"
+    "@typescript-eslint/type-utils" "8.59.1"
+    "@typescript-eslint/utils" "8.59.1"
+    "@typescript-eslint/visitor-keys" "8.59.1"
     ignore "^7.0.5"
     natural-compare "^1.4.0"
     ts-api-utils "^2.5.0"
 
-"@typescript-eslint/parser@^8.58.0":
-  version "8.58.0"
-  resolved "https://registry.yarnpkg.com/@typescript-eslint/parser/-/parser-8.58.0.tgz#da04ece1967b6c2fe8f10c3473dabf3825795ef7"
-  integrity sha512-rLoGZIf9afaRBYsPUMtvkDWykwXwUPL60HebR4JgTI8mxfFe2cQTu3AGitANp4b9B2QlVru6WzjgB2IzJKiCSA==
+"@typescript-eslint/parser@^8.59.1":
+  version "8.59.1"
+  resolved "https://registry.yarnpkg.com/@typescript-eslint/parser/-/parser-8.59.1.tgz#835d20a62350659a082a1ae2a60b822c40488905"
+  integrity sha512-HDQH9O/47Dxi1ceDhBXdaldtf/WV9yRYMjbjCuNk3qnaTD564qwv61Y7+gTxwxRKzSrgO5uhtw584igXVuuZkA==
   dependencies:
-    "@typescript-eslint/scope-manager" "8.58.0"
-    "@typescript-eslint/types" "8.58.0"
-    "@typescript-eslint/typescript-estree" "8.58.0"
-    "@typescript-eslint/visitor-keys" "8.58.0"
+    "@typescript-eslint/scope-manager" "8.59.1"
+    "@typescript-eslint/types" "8.59.1"
+    "@typescript-eslint/typescript-estree" "8.59.1"
+    "@typescript-eslint/visitor-keys" "8.59.1"
     debug "^4.4.3"
 
-"@typescript-eslint/project-service@8.58.0":
-  version "8.58.0"
-  resolved "https://registry.yarnpkg.com/@typescript-eslint/project-service/-/project-service-8.58.0.tgz#66ceda0aabf7427aec3e2713fa43eb278dead2aa"
-  integrity sha512-8Q/wBPWLQP1j16NxoPNIKpDZFMaxl7yWIoqXWYeWO+Bbd2mjgvoF0dxP2jKZg5+x49rgKdf7Ck473M8PC3V9lg==
+"@typescript-eslint/project-service@8.59.1":
+  version "8.59.1"
+  resolved "https://registry.yarnpkg.com/@typescript-eslint/project-service/-/project-service-8.59.1.tgz#49efe87c37ef84262f23df8bf62fdc56698ca6fe"
+  integrity sha512-+MuHQlHiEr00Of/IQbE/MmEoi44znZHbR/Pz7Opq4HryUOlRi+/44dro9Ycy8Fyo+/024IWtw8m4JUMCGTYxDg==
   dependencies:
-    "@typescript-eslint/tsconfig-utils" "^8.58.0"
-    "@typescript-eslint/types" "^8.58.0"
+    "@typescript-eslint/tsconfig-utils" "^8.59.1"
+    "@typescript-eslint/types" "^8.59.1"
     debug "^4.4.3"
 
-"@typescript-eslint/scope-manager@8.58.0":
-  version "8.58.0"
-  resolved "https://registry.yarnpkg.com/@typescript-eslint/scope-manager/-/scope-manager-8.58.0.tgz#e304142775e49a1b7ac3c8bf2536714447c72cab"
-  integrity sha512-W1Lur1oF50FxSnNdGp3Vs6P+yBRSmZiw4IIjEeYxd8UQJwhUF0gDgDD/W/Tgmh73mxgEU3qX0Bzdl/NGuSPEpQ==
+"@typescript-eslint/scope-manager@8.59.1":
+  version "8.59.1"
+  resolved "https://registry.yarnpkg.com/@typescript-eslint/scope-manager/-/scope-manager-8.59.1.tgz#ed90d054fc3db2d0c81464db3a953a94fb85bb58"
+  integrity sha512-LwuHQI4pDOYVKvmH2dkaJo6YZCSgouVgnS/z7yBPKBMvgtBvyLqiLy9Z6b7+m/TRcX1NFYUqZetI5Y+aT4GEfg==
   dependencies:
-    "@typescript-eslint/types" "8.58.0"
-    "@typescript-eslint/visitor-keys" "8.58.0"
+    "@typescript-eslint/types" "8.59.1"
+    "@typescript-eslint/visitor-keys" "8.59.1"
 
-"@typescript-eslint/tsconfig-utils@8.58.0", "@typescript-eslint/tsconfig-utils@^8.58.0":
-  version "8.58.0"
-  resolved "https://registry.yarnpkg.com/@typescript-eslint/tsconfig-utils/-/tsconfig-utils-8.58.0.tgz#c5a8edb21f31e0fdee565724e1b984171c559482"
-  integrity sha512-doNSZEVJsWEu4htiVC+PR6NpM+pa+a4ClH9INRWOWCUzMst/VA9c4gXq92F8GUD1rwhNvRLkgjfYtFXegXQF7A==
+"@typescript-eslint/tsconfig-utils@8.59.1", "@typescript-eslint/tsconfig-utils@^8.59.1":
+  version "8.59.1"
+  resolved "https://registry.yarnpkg.com/@typescript-eslint/tsconfig-utils/-/tsconfig-utils-8.59.1.tgz#ba2a779a444f1d5cb92a606f9b209d239fd4cab1"
+  integrity sha512-/0nEyPbX7gRsk0Uwfe4ALwwgxuA66d/l2mhRDNlAvaj4U3juhUtJNq0DsY8M2AYwwb9rEq2hrC3IcIcEt++iJA==
 
-"@typescript-eslint/type-utils@8.58.0":
-  version "8.58.0"
-  resolved "https://registry.yarnpkg.com/@typescript-eslint/type-utils/-/type-utils-8.58.0.tgz#ce0e72cd967ffbbe8de322db6089bd4374be352f"
-  integrity sha512-aGsCQImkDIqMyx1u4PrVlbi/krmDsQUs4zAcCV6M7yPcPev+RqVlndsJy9kJ8TLihW9TZ0kbDAzctpLn5o+lOg==
+"@typescript-eslint/type-utils@8.59.1":
+  version "8.59.1"
+  resolved "https://registry.yarnpkg.com/@typescript-eslint/type-utils/-/type-utils-8.59.1.tgz#9c83d3f2ed9187a815e8120f72c08317e513e409"
+  integrity sha512-klWPBR2ciQHS3f++ug/mVnWKPjBUo7icEL3FAO1lhAR1Z1i5NQYZ1EannMSRYcq5qCv5wNALlXr6fksRHyYl7w==
   dependencies:
-    "@typescript-eslint/types" "8.58.0"
-    "@typescript-eslint/typescript-estree" "8.58.0"
-    "@typescript-eslint/utils" "8.58.0"
+    "@typescript-eslint/types" "8.59.1"
+    "@typescript-eslint/typescript-estree" "8.59.1"
+    "@typescript-eslint/utils" "8.59.1"
     debug "^4.4.3"
     ts-api-utils "^2.5.0"
 
-"@typescript-eslint/types@8.58.0", "@typescript-eslint/types@^8.58.0":
-  version "8.58.0"
-  resolved "https://registry.yarnpkg.com/@typescript-eslint/types/-/types-8.58.0.tgz#e94ae7abdc1c6530e71183c1007b61fa93112a5a"
-  integrity sha512-O9CjxypDT89fbHxRfETNoAnHj/i6IpRK0CvbVN3qibxlLdo5p5hcLmUuCCrHMpxiWSwKyI8mCP7qRNYuOJ0Uww==
+"@typescript-eslint/types@8.59.1", "@typescript-eslint/types@^8.59.1":
+  version "8.59.1"
+  resolved "https://registry.yarnpkg.com/@typescript-eslint/types/-/types-8.59.1.tgz#c1d014d3f03a97e0113a8899fc9d4e45a7fb0ca9"
+  integrity sha512-ZDCjgccSdYPw5Bxh+my4Z0lJU96ZDN7jbBzvmEn0FZx3RtU1C7VWl6NbDx94bwY3V5YsgwRzJPOgeY2Q/nLG8A==
 
-"@typescript-eslint/typescript-estree@8.58.0":
-  version "8.58.0"
-  resolved "https://registry.yarnpkg.com/@typescript-eslint/typescript-estree/-/typescript-estree-8.58.0.tgz#ed233faa8e2f2a2e1357c3e7d553d6465a0ee59a"
-  integrity sha512-7vv5UWbHqew/dvs+D3e1RvLv1v2eeZ9txRHPnEEBUgSNLx5ghdzjHa0sgLWYVKssH+lYmV0JaWdoubo0ncGYLA==
+"@typescript-eslint/typescript-estree@8.59.1":
+  version "8.59.1"
+  resolved "https://registry.yarnpkg.com/@typescript-eslint/typescript-estree/-/typescript-estree-8.59.1.tgz#4391fadf98a22c869c5b6522dbf4e491e53e351a"
+  integrity sha512-OUd+vJS05sSkOip+BkZ/2NS8RMxrAAJemsC6vU3kmfLyeaJT0TftHkV9mcx2107MmsBVXXexhVu4F0TZXyMl4g==
   dependencies:
-    "@typescript-eslint/project-service" "8.58.0"
-    "@typescript-eslint/tsconfig-utils" "8.58.0"
-    "@typescript-eslint/types" "8.58.0"
-    "@typescript-eslint/visitor-keys" "8.58.0"
+    "@typescript-eslint/project-service" "8.59.1"
+    "@typescript-eslint/tsconfig-utils" "8.59.1"
+    "@typescript-eslint/types" "8.59.1"
+    "@typescript-eslint/visitor-keys" "8.59.1"
     debug "^4.4.3"
     minimatch "^10.2.2"
     semver "^7.7.3"
     tinyglobby "^0.2.15"
     ts-api-utils "^2.5.0"
 
-"@typescript-eslint/utils@8.58.0":
-  version "8.58.0"
-  resolved "https://registry.yarnpkg.com/@typescript-eslint/utils/-/utils-8.58.0.tgz#21a74a7963b0d288b719a4121c7dd555adaab3c3"
-  integrity sha512-RfeSqcFeHMHlAWzt4TBjWOAtoW9lnsAGiP3GbaX9uVgTYYrMbVnGONEfUCiSss+xMHFl+eHZiipmA8WkQ7FuNA==
+"@typescript-eslint/utils@8.59.1":
+  version "8.59.1"
+  resolved "https://registry.yarnpkg.com/@typescript-eslint/utils/-/utils-8.59.1.tgz#cf6204d69701bbbc5b150f98c18aeef0a42c10bd"
+  integrity sha512-3pIeoXhCeYH9FSCBI8P3iNwJlGuzPlYKkTlen2O9T1DSeeg8UG8jstq6BLk+Mda0qup7mgk4z4XL4OzRaxZ8LA==
   dependencies:
     "@eslint-community/eslint-utils" "^4.9.1"
-    "@typescript-eslint/scope-manager" "8.58.0"
-    "@typescript-eslint/types" "8.58.0"
-    "@typescript-eslint/typescript-estree" "8.58.0"
+    "@typescript-eslint/scope-manager" "8.59.1"
+    "@typescript-eslint/types" "8.59.1"
+    "@typescript-eslint/typescript-estree" "8.59.1"
 
-"@typescript-eslint/visitor-keys@8.58.0":
-  version "8.58.0"
-  resolved "https://registry.yarnpkg.com/@typescript-eslint/visitor-keys/-/visitor-keys-8.58.0.tgz#2abd55a4be70fd55967aceaba4330b9ba9f45189"
-  integrity sha512-XJ9UD9+bbDo4a4epraTwG3TsNPeiB9aShrUneAVXy8q4LuwowN+qu89/6ByLMINqvIMeI9H9hOHQtg/ijrYXzQ==
+"@typescript-eslint/visitor-keys@8.59.1":
+  version "8.59.1"
+  resolved "https://registry.yarnpkg.com/@typescript-eslint/visitor-keys/-/visitor-keys-8.59.1.tgz#b5cba576287a3eeb0b400b62813189abcc3f976a"
+  integrity sha512-LdDNl6C5iJExcM0Yh0PwAIBb9PrSiCsWamF/JyEZawm3kFDnRoaq3LGE4bpyRao/fWeGKKyw7icx0YxrLFC5Cg==
   dependencies:
-    "@typescript-eslint/types" "8.58.0"
+    "@typescript-eslint/types" "8.59.1"
     eslint-visitor-keys "^5.0.0"
 
 "@ungap/structured-clone@^1.3.0":
@@ -1909,10 +1908,10 @@ doctrine@^2.1.0:
   dependencies:
     esutils "^2.0.2"
 
-dotenv@^17.3.1:
-  version "17.3.1"
-  resolved "https://registry.yarnpkg.com/dotenv/-/dotenv-17.3.1.tgz#2706f5b0165e45a1503348187b8468f87fe6aae2"
-  integrity sha512-IO8C/dzEb6O3F9/twg6ZLXz164a2fhTnEWb95H23Dm4OuN+92NmEAlTrupP9VW6Jm3sO26tQlqyvyi4CsnY9GA==
+dotenv@^17.4.2:
+  version "17.4.2"
+  resolved "https://registry.yarnpkg.com/dotenv/-/dotenv-17.4.2.tgz#c07e54a746e11eba021dd9e1047ced5afdc1c034"
+  integrity sha512-nI4U3TottKAcAD9LLud4Cb7b2QztQMUEfHbvhTH09bqXTxnSie8WnjPALV/WMCrJZ6UV/qHJ6L03OqO3LcdYZw==
 
 dunder-proto@^1.0.0, dunder-proto@^1.0.1:
   version "1.0.1"
@@ -2263,17 +2262,17 @@ eslint-visitor-keys@^5.0.0, eslint-visitor-keys@^5.0.1:
   resolved "https://registry.yarnpkg.com/eslint-visitor-keys/-/eslint-visitor-keys-5.0.1.tgz#9e3c9489697824d2d4ce3a8ad12628f91e9f59be"
   integrity sha512-tD40eHxA35h0PEIZNeIjkHoDR4YjjJp34biM0mDvplBe//mB+IHCqHDGV7pxF+7MklTvighcCPPZC7ynWyjdTA==
 
-eslint@^10.1.0:
-  version "10.1.0"
-  resolved "https://registry.yarnpkg.com/eslint/-/eslint-10.1.0.tgz#9ca98e654e642ab2e1af6d1e9d8613857ac341b4"
-  integrity sha512-S9jlY/ELKEUwwQnqWDO+f+m6sercqOPSqXM5Go94l7DOmxHVDgmSFGWEzeE/gwgTAr0W103BWt0QLe/7mabIvA==
+eslint@^10.2.1:
+  version "10.2.1"
+  resolved "https://registry.yarnpkg.com/eslint/-/eslint-10.2.1.tgz#224b2a6caeb34473eddcf918762363e2e063222a"
+  integrity sha512-wiyGaKsDgqXvF40P8mDwiUp/KQjE1FdrIEJsM8PZ3XCiniTMXS3OHWWUe5FI5agoCnr8x4xPrTDZuxsBlNHl+Q==
   dependencies:
     "@eslint-community/eslint-utils" "^4.8.0"
     "@eslint-community/regexpp" "^4.12.2"
-    "@eslint/config-array" "^0.23.3"
-    "@eslint/config-helpers" "^0.5.3"
-    "@eslint/core" "^1.1.1"
-    "@eslint/plugin-kit" "^0.6.1"
+    "@eslint/config-array" "^0.23.5"
+    "@eslint/config-helpers" "^0.5.5"
+    "@eslint/core" "^1.2.1"
+    "@eslint/plugin-kit" "^0.7.1"
     "@humanfs/node" "^0.16.6"
     "@humanwhocodes/module-importer" "^1.0.1"
     "@humanwhocodes/retry" "^0.4.2"
@@ -2683,7 +2682,7 @@ graceful-fs@^4.2.11:
   resolved "https://registry.yarnpkg.com/graceful-fs/-/graceful-fs-4.2.11.tgz#4183e4e8bf08bb6e05bbb2f7d2e0c8f712ca40e3"
   integrity sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==
 
-handlebars@^4.7.8:
+handlebars@^4.7.9:
   version "4.7.9"
   resolved "https://registry.yarnpkg.com/handlebars/-/handlebars-4.7.9.tgz#6f139082ab58dc4e5a0e51efe7db5ae890d56a0f"
   integrity sha512-4E71E0rpOaQuJR2A3xDZ+GM1HyWYv1clR58tC8emQNeQe3RH7MAzSbat+V0wG78LQBo6m6bzSG/L4pBuCsgnUQ==
@@ -4130,10 +4129,10 @@ prettier-linter-helpers@^1.0.1:
   dependencies:
     fast-diff "^1.1.2"
 
-prettier@^3.8.1:
-  version "3.8.1"
-  resolved "https://registry.yarnpkg.com/prettier/-/prettier-3.8.1.tgz#edf48977cf991558f4fcbd8a3ba6015ba2a3a173"
-  integrity sha512-UOnG6LftzbdaHZcKoPFtOcCKztrQ57WkHDeRD9t/PTQtmT0NHSeWWepj6pS0z/N7+08BHFDQVUrfmfMRcZwbMg==
+prettier@^3.8.3:
+  version "3.8.3"
+  resolved "https://registry.yarnpkg.com/prettier/-/prettier-3.8.3.tgz#560f2de55bf01b4c0503bc629d5df99b9a1d09b0"
+  integrity sha512-7igPTM53cGHMW8xWuVTydi2KO233VFiTNyF5hLJqpilHfmn8C8gPf+PS7dUT64YcXFbiMGZxS9pCSxL/Dxm/Jw==
 
 pretty-format@30.2.0, pretty-format@^30.0.0:
   version "30.2.0"
@@ -4287,7 +4286,7 @@ semver@^6.3.1:
   resolved "https://registry.yarnpkg.com/semver/-/semver-6.3.1.tgz#556d2ef8689146e46dcea4bfdd095f3434dffcb4"
   integrity sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==
 
-semver@^7.5.3, semver@^7.5.4, semver@^7.7.2, semver@^7.7.3:
+semver@^7.5.3, semver@^7.5.4, semver@^7.7.2, semver@^7.7.3, semver@^7.7.4:
   version "7.7.4"
   resolved "https://registry.yarnpkg.com/semver/-/semver-7.7.4.tgz#28464e36060e991fa7a11d0279d2d3f3b57a7e8a"
   integrity sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA==
@@ -4623,18 +4622,18 @@ ts-api-utils@^2.5.0:
   resolved "https://registry.yarnpkg.com/ts-api-utils/-/ts-api-utils-2.5.0.tgz#4acd4a155e22734990a5ed1fe9e97f113bcb37c1"
   integrity sha512-OJ/ibxhPlqrMM0UiNHJ/0CKQkoKF243/AEmplt3qpRgkW8VG7IfOS41h7V8TjITqdByHzrjcS/2si+y4lIh8NA==
 
-ts-jest@^29.4.6:
-  version "29.4.6"
-  resolved "https://registry.yarnpkg.com/ts-jest/-/ts-jest-29.4.6.tgz#51cb7c133f227396818b71297ad7409bb77106e9"
-  integrity sha512-fSpWtOO/1AjSNQguk43hb/JCo16oJDnMJf3CdEGNkqsEX3t0KX96xvyX1D7PfLCpVoKu4MfVrqUkFyblYoY4lA==
+ts-jest@^29.4.9:
+  version "29.4.9"
+  resolved "https://registry.yarnpkg.com/ts-jest/-/ts-jest-29.4.9.tgz#47dc33d0f5c36bddcedd16afefae285e0b049d2d"
+  integrity sha512-LTb9496gYPMCqjeDLdPrKuXtncudeV1yRZnF4Wo5l3SFi0RYEnYRNgMrFIdg+FHvfzjCyQk1cLncWVqiSX+EvQ==
   dependencies:
     bs-logger "^0.2.6"
     fast-json-stable-stringify "^2.1.0"
-    handlebars "^4.7.8"
+    handlebars "^4.7.9"
     json5 "^2.2.3"
     lodash.memoize "^4.1.2"
     make-error "^1.3.6"
-    semver "^7.7.3"
+    semver "^7.7.4"
     type-fest "^4.41.0"
     yargs-parser "^21.1.1"
 
@@ -4854,11 +4853,6 @@ uuid@10.0.0, uuid@^10.0.0:
   resolved "https://registry.yarnpkg.com/uuid/-/uuid-10.0.0.tgz#5a95aa454e6e002725c79055fd42aaba30ca6294"
   integrity sha512-8XkAphELsDnEGrDxUOHB3RGvXz6TeuYSGEZBOjtTtPm2lwhGBjLgOzLHB63IUWfBpNucQjND6d3AOudO+H3RWQ==
 
-uuid@^11.1.0:
-  version "11.1.0"
-  resolved "https://registry.yarnpkg.com/uuid/-/uuid-11.1.0.tgz#9549028be1753bb934fc96e2bca09bb4105ae912"
-  integrity sha512-0/A9rDy9P7cJ+8w1c9WD9V//9Wj15Ce2MPz8Ri6032usz+NfePxx5AcN3bN+r6ZL6jEo066/yNYB3tn4pQEx+A==
-
 uuid@^13.0.0:
   version "13.0.0"
   resolved "https://registry.yarnpkg.com/uuid/-/uuid-13.0.0.tgz#263dc341b19b4d755eb8fe36b78d95a6b65707e8"

libs/cli/js-monorepo-example/apps/agent/package.json

@@ -9,8 +9,8 @@
   },
   "dependencies": {
     "@js-monorepo-example/shared": "*",
-    "@langchain/core": "^1.1.38",
-    "@langchain/langgraph": "^1.2.6"
+    "@langchain/core": "^1.1.42",
+    "@langchain/langgraph": "^1.2.9"
   },
   "devDependencies": {
     "typescript": "^5.9.3"

libs/cli/js-monorepo-example/package.json

@@ -17,18 +17,18 @@
     "lint": "eslint 'apps/**/*.ts' 'libs/**/*.ts'"
   },
   "devDependencies": {
-    "turbo": "^2.9.3",
+    "turbo": "^2.9.7",
     "typescript": "^5.9.3",
     "@tsconfig/recommended": "^1.0.13",
     "@eslint/eslintrc": "^3.3.5",
     "@eslint/js": "^10.0.1",
-    "eslint": "^10.1.0",
+    "eslint": "^10.2.1",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.27.5",
     "eslint-plugin-no-instanceof": "^1.0.1",
     "eslint-plugin-prettier": "^5.5.5",
-    "@typescript-eslint/eslint-plugin": "^8.58.0",
-    "@typescript-eslint/parser": "^8.58.0",
-    "prettier": "^3.8.1"
+    "@typescript-eslint/eslint-plugin": "^8.59.1",
+    "@typescript-eslint/parser": "^8.59.1",
+    "prettier": "^3.8.3"
   }
 }

libs/cli/js-monorepo-example/yarn.lock

@@ -19,26 +19,26 @@
   resolved "https://registry.yarnpkg.com/@eslint-community/regexpp/-/regexpp-4.12.2.tgz#bccdf615bcf7b6e8db830ec0b8d21c9a25de597b"
   integrity sha512-EriSTlt5OC9/7SXkRSCAhfSxxoSUgBm33OH+IkwbdpgoqsSsUg7y3uh+IICI/Qg4BBWr3U2i39RpmycbxMq4ew==
 
-"@eslint/config-array@^0.23.3":
-  version "0.23.3"
-  resolved "https://registry.yarnpkg.com/@eslint/config-array/-/config-array-0.23.3.tgz#3f4a93dd546169c09130cbd10f2415b13a20a219"
-  integrity sha512-j+eEWmB6YYLwcNOdlwQ6L2OsptI/LO6lNBuLIqe5R7RetD658HLoF+Mn7LzYmAWWNNzdC6cqP+L6r8ujeYXWLw==
+"@eslint/config-array@^0.23.5":
+  version "0.23.5"
+  resolved "https://registry.yarnpkg.com/@eslint/config-array/-/config-array-0.23.5.tgz#56e86d243049195d8acc0c06a1b3dfdc3fa3de95"
+  integrity sha512-Y3kKLvC1dvTOT+oGlqNQ1XLqK6D1HU2YXPc52NmAlJZbMMWDzGYXMiPRJ8TYD39muD/OTjlZmNJ4ib7dvSrMBA==
   dependencies:
-    "@eslint/object-schema" "^3.0.3"
+    "@eslint/object-schema" "^3.0.5"
     debug "^4.3.1"
     minimatch "^10.2.4"
 
-"@eslint/config-helpers@^0.5.3":
-  version "0.5.3"
-  resolved "https://registry.yarnpkg.com/@eslint/config-helpers/-/config-helpers-0.5.3.tgz#721fe6bbb90d74b0c80d6ff2428e5bbcb002becb"
-  integrity sha512-lzGN0onllOZCGroKJmRwY6QcEHxbjBw1gwB8SgRSqK8YbbtEXMvKynsXc3553ckIEBxsbMBU7oOZXKIPGZNeZw==
+"@eslint/config-helpers@^0.5.5":
+  version "0.5.5"
+  resolved "https://registry.yarnpkg.com/@eslint/config-helpers/-/config-helpers-0.5.5.tgz#ae16134e4792ac5fbdc533548a24ac1ea9f7f3ae"
+  integrity sha512-eIJYKTCECbP/nsKaaruF6LW967mtbQbsw4JTtSVkUQc9MneSkbrgPJAbKl9nWr0ZeowV8BfsarBmPpBzGelA2w==
   dependencies:
-    "@eslint/core" "^1.1.1"
+    "@eslint/core" "^1.2.1"
 
-"@eslint/core@^1.1.1":
-  version "1.1.1"
-  resolved "https://registry.yarnpkg.com/@eslint/core/-/core-1.1.1.tgz#450f3d2be2d463ccd51119544092256b4e88df32"
-  integrity sha512-QUPblTtE51/7/Zhfv8BDwO0qkkzQL7P/aWWbqcf4xWLEYn1oKjdO0gglQBB4GAsu7u6wjijbCmzsUTy6mnk6oQ==
+"@eslint/core@^1.2.1":
+  version "1.2.1"
+  resolved "https://registry.yarnpkg.com/@eslint/core/-/core-1.2.1.tgz#c1da7cd1b82fa8787f98b5629fb811848a1b63ce"
+  integrity sha512-MwcE1P+AZ4C6DWlpin/OmOA54mmIZ/+xZuJiQd4SyB29oAJjN30UW9wkKNptW2ctp4cEsvhlLY/CsQ1uoHDloQ==
   dependencies:
     "@types/json-schema" "^7.0.15"
 
@@ -62,17 +62,17 @@
   resolved "https://registry.yarnpkg.com/@eslint/js/-/js-10.0.1.tgz#1e8a876f50117af8ab67e47d5ad94d38d6622583"
   integrity sha512-zeR9k5pd4gxjZ0abRoIaxdc7I3nDktoXZk2qOv9gCNWx3mVwEn32VRhyLaRsDiJjTs0xq/T8mfPtyuXu7GWBcA==
 
-"@eslint/object-schema@^3.0.3":
-  version "3.0.3"
-  resolved "https://registry.yarnpkg.com/@eslint/object-schema/-/object-schema-3.0.3.tgz#5bf671e52e382e4adc47a9906f2699374637db6b"
-  integrity sha512-iM869Pugn9Nsxbh/YHRqYiqd23AmIbxJOcpUMOuWCVNdoQJ5ZtwL6h3t0bcZzJUlC3Dq9jCFCESBZnX0GTv7iQ==
+"@eslint/object-schema@^3.0.5":
+  version "3.0.5"
+  resolved "https://registry.yarnpkg.com/@eslint/object-schema/-/object-schema-3.0.5.tgz#88e9bf4d11d2b19c082e78ebe7ce88724a5eb091"
+  integrity sha512-vqTaUEgxzm+YDSdElad6PiRoX4t8VGDjCtt05zn4nU810UIx/uNEV7/lZJ6KwFThKZOzOxzXy48da+No7HZaMw==
 
-"@eslint/plugin-kit@^0.6.1":
-  version "0.6.1"
-  resolved "https://registry.yarnpkg.com/@eslint/plugin-kit/-/plugin-kit-0.6.1.tgz#eb9e6689b56ce8bc1855bb33090e63f3fc115e8e"
-  integrity sha512-iH1B076HoAshH1mLpHMgwdGeTs0CYwL0SPMkGuSebZrwBp16v415e9NZXg2jtrqPVQjf6IANe2Vtlr5KswtcZQ==
+"@eslint/plugin-kit@^0.7.1":
+  version "0.7.1"
+  resolved "https://registry.yarnpkg.com/@eslint/plugin-kit/-/plugin-kit-0.7.1.tgz#c4125fd015eceeb09b793109fdbcd4dd0a02d346"
+  integrity sha512-rZAP3aVgB9ds9KOeUSL+zZ21hPmo8dh6fnIFwRQj5EAZl9gzR7wxYbYXYysAM8CTqGmUGyp2S4kUdV17MnGuWQ==
   dependencies:
-    "@eslint/core" "^1.1.1"
+    "@eslint/core" "^1.2.1"
     levn "^0.4.1"
 
 "@humanfs/core@^0.19.1":
@@ -103,10 +103,10 @@
   resolved "https://registry.yarnpkg.com/@isaacs/cliui/-/cliui-9.0.0.tgz#4d0a3f127058043bf2e7ee169eaf30ed901302f3"
   integrity sha512-AokJm4tuBHillT+FpMtxQ60n8ObyXBatq7jD2/JA9dxbDDokKQm8KMht5ibGzLVU9IJDIKK4TPKgMHEYMn3lMg==
 
-"@langchain/core@^1.1.38":
-  version "1.1.38"
-  resolved "https://registry.yarnpkg.com/@langchain/core/-/core-1.1.38.tgz#b5939b2e77af408771c9bb95bf56a5ad8183313e"
-  integrity sha512-C340wH1YL10CiVOFlEpQMp0zQE85/eBLKX/gi1Lv7shAyUmR3CQ0t/mXlCd5RsZa6ntAN1kDJnp64ArWey9XAA==
+"@langchain/core@^1.1.42":
+  version "1.1.42"
+  resolved "https://registry.yarnpkg.com/@langchain/core/-/core-1.1.42.tgz#607bfd34c1414c9cbeb2859fda1b254a14c28085"
+  integrity sha512-d0tN96BrwPMryYyWR9VfyAntSivn7EQrZCe5Kpxum93tcjTXbKKmKvItFec8AluQt88iTcmAJrahUZUNfzGwTA==
   dependencies:
     "@cfworker/json-schema" "^4.0.2"
     "@standard-schema/spec" "^1.1.0"
@@ -117,7 +117,6 @@
     langsmith ">=0.5.0 <1.0.0"
     mustache "^4.2.0"
     p-queue "^6.6.2"
-    uuid "^11.1.0"
     zod "^3.25.76 || ^4"
 
 "@langchain/langgraph-checkpoint@^1.0.1":
@@ -127,23 +126,23 @@
   dependencies:
     uuid "^10.0.0"
 
-"@langchain/langgraph-sdk@~1.8.1":
-  version "1.8.3"
-  resolved "https://registry.yarnpkg.com/@langchain/langgraph-sdk/-/langgraph-sdk-1.8.3.tgz#deedc9bddd863693c6ab5f3a74058548b040377d"
-  integrity sha512-Py0S5yVtlOHz410aEsSGLRKjtsK2giDvfPS1JjAjTdcs71khuJufFtUZFwmwdJCbsG4DaGurRLHOAJu9jO4a0g==
+"@langchain/langgraph-sdk@~1.8.9":
+  version "1.8.10"
+  resolved "https://registry.yarnpkg.com/@langchain/langgraph-sdk/-/langgraph-sdk-1.8.10.tgz#bd175cda1ab629845ef28b22b45f3bdd1f65b029"
+  integrity sha512-wrB3rkRw5KAmsqezwvKP3midT4qJrV6Hj9XJMYo+cbvXC4HYpSAmyY/VriSyeTFRbLG/OP/pY2Yz+9Z54nSaXQ==
   dependencies:
     "@types/json-schema" "^7.0.15"
     p-queue "^9.0.1"
     p-retry "^7.1.1"
     uuid "^13.0.0"
 
-"@langchain/langgraph@^1.2.6":
-  version "1.2.6"
-  resolved "https://registry.yarnpkg.com/@langchain/langgraph/-/langgraph-1.2.6.tgz#e6a578f96fbbc1c54ba78e0298884671dad5d195"
-  integrity sha512-5cX402dNGN6w9+0mlMU2dgUiKx6Y1tlENp7x05e9ByDbQCHSDc0kyqRWNFLGc7vatQ92S4ylxQrcCJvi8Fr4SQ==
+"@langchain/langgraph@^1.2.9":
+  version "1.2.9"
+  resolved "https://registry.yarnpkg.com/@langchain/langgraph/-/langgraph-1.2.9.tgz#4f0ba159062c3649c83cf5f621ef926b96933e32"
+  integrity sha512-3c7BtGycHC2v9p6w/Hv8L7kEl1YnZYOQTDJtmAp3knk6JOedO7d2bYP3y0SRyhv5orUEGf/KGvx8ZsB/ideP7g==
   dependencies:
     "@langchain/langgraph-checkpoint" "^1.0.1"
-    "@langchain/langgraph-sdk" "~1.8.1"
+    "@langchain/langgraph-sdk" "~1.8.9"
     "@standard-schema/spec" "1.1.0"
     uuid "^10.0.0"
 
@@ -167,35 +166,35 @@
   resolved "https://registry.yarnpkg.com/@tsconfig/recommended/-/recommended-1.0.13.tgz#269fce3ad04ca70b93269ff44cca81b950f542da"
   integrity sha512-sySRuBfMKyKO/j2ZAhR8kSembhjuPEV4Ra3AHtmWLq51+iGaudr45crPSzNC5b7/Ctrh9dfUpBuTlYrH6rM58Q==
 
-"@turbo/darwin-64@2.9.3":
-  version "2.9.3"
-  resolved "https://registry.yarnpkg.com/@turbo/darwin-64/-/darwin-64-2.9.3.tgz#5d782d341ddebc20822d09ba1393238d4467ae7b"
-  integrity sha512-P8foouaP+y/p+hhEGBoZpzMbpVvUMwPjDpcy6wN7EYfvvyISD1USuV27qWkczecihwuPJzQ1lDBuL8ERcavTyg==
+"@turbo/darwin-64@2.9.7":
+  version "2.9.7"
+  resolved "https://registry.yarnpkg.com/@turbo/darwin-64/-/darwin-64-2.9.7.tgz#46fddae01ea7817192dc6ff36a678cc3879b753b"
+  integrity sha512-wnvOWuVWJ5EUHNKxExEWiGlTeVpLG1L0PCu5MUozyC1P2SHGiWsmpW6/yAuShH91Fa2TAHOvdCRBzriZh4j4Eg==
 
-"@turbo/darwin-arm64@2.9.3":
-  version "2.9.3"
-  resolved "https://registry.yarnpkg.com/@turbo/darwin-arm64/-/darwin-arm64-2.9.3.tgz#75cd662d9c2a572532ce82d7cae1a30e2497d693"
-  integrity sha512-SIzEkvtNdzdI50FJDaIQ6kQGqgSSdFPcdn0wqmmONN6iGKjy6hsT+EH99GP65FsfV7DLZTh2NmtTIRl2kdoz5Q==
+"@turbo/darwin-arm64@2.9.7":
+  version "2.9.7"
+  resolved "https://registry.yarnpkg.com/@turbo/darwin-arm64/-/darwin-arm64-2.9.7.tgz#cd7cf3a024509af0f59ae3885216d62fd090fdb6"
+  integrity sha512-mA0FIPMwwN3lodDkQYaGxj6PeT7ZaN5aCEbkKn/WB+ZB9yJdVWA4J83GH7t43jqDc5dcnVluVN5UFx3plRiXhA==
 
-"@turbo/linux-64@2.9.3":
-  version "2.9.3"
-  resolved "https://registry.yarnpkg.com/@turbo/linux-64/-/linux-64-2.9.3.tgz#de693a996071654a0bea51c7ed9dc6fdc3950ae8"
-  integrity sha512-pLRwFmcHHNBvsCySLS6OFabr/07kDT2pxEt/k6eBf/3asiVQZKJ7Rk88AafQx2aYA641qek4RsXvYO3JYpiBug==
+"@turbo/linux-64@2.9.7":
+  version "2.9.7"
+  resolved "https://registry.yarnpkg.com/@turbo/linux-64/-/linux-64-2.9.7.tgz#25ee9a2cb3042498a3203e14653b14041105020f"
+  integrity sha512-fEbUYpgb5l7P+q+5tsWF2gw+/GSjUsuUTcnfm+f0lozUjgcjLKyOat6PgtAChmIFcTPchCL/8rJ3TvkBy01gfA==
 
-"@turbo/linux-arm64@2.9.3":
-  version "2.9.3"
-  resolved "https://registry.yarnpkg.com/@turbo/linux-arm64/-/linux-arm64-2.9.3.tgz#88fc6fe572d83c5488eeae9b564b57c335f4d856"
-  integrity sha512-gy6ApUroC2Nzv+qjGtE/uPNkhHAFU4c8God+zd5Aiv9L9uBgHlxVJpHT3XWl5xwlJZ2KWuMrlHTaS5kmNB+q1Q==
+"@turbo/linux-arm64@2.9.7":
+  version "2.9.7"
+  resolved "https://registry.yarnpkg.com/@turbo/linux-arm64/-/linux-arm64-2.9.7.tgz#5b19d6249a50cb8153b8f2bc22ad10bbda614fbe"
+  integrity sha512-VkUjulo9ytfHKUHOS5gy0XPoh4CTKPXWCL8nLdrlHVi9fSut31ECeUqnm/dAbETP5D4xo9mH9XkJ+qMzGe/zmg==
 
-"@turbo/windows-64@2.9.3":
-  version "2.9.3"
-  resolved "https://registry.yarnpkg.com/@turbo/windows-64/-/windows-64-2.9.3.tgz#a7812e4f33972f74daed93b2ac8845f88a68c775"
-  integrity sha512-d0YelTX6hAsB7kIEtGB3PzIzSfAg3yDoUlHwuwJc3adBXUsyUIs0YLG+1NNtuhcDOUGnWQeKUoJ2pGWvbpRj7w==
+"@turbo/windows-64@2.9.7":
+  version "2.9.7"
+  resolved "https://registry.yarnpkg.com/@turbo/windows-64/-/windows-64-2.9.7.tgz#900645776fa44ff8333e801d890992736f6dbc72"
+  integrity sha512-/GWdY6/x4aIHqkYJq596Rpdk1x0MkpRPkJcLAoB3yGRwyUms0+u2F1GnV54IbyAZTeKLRWSJKzNC+QwVGdYchA==
 
-"@turbo/windows-arm64@2.9.3":
-  version "2.9.3"
-  resolved "https://registry.yarnpkg.com/@turbo/windows-arm64/-/windows-arm64-2.9.3.tgz#1891a89fe87d501e63a7a4367082f3afec18fa6f"
-  integrity sha512-/08CwpKJl3oRY8nOlh2YgilZVJDHsr60XTNxRhuDeuFXONpUZ5X+Nv65izbG/xBew9qxcJFbDX9/sAmAX+ITcQ==
+"@turbo/windows-arm64@2.9.7":
+  version "2.9.7"
+  resolved "https://registry.yarnpkg.com/@turbo/windows-arm64/-/windows-arm64-2.9.7.tgz#e678d73fdbcbb12a679403fe7ba070fb67f37810"
+  integrity sha512-xBBgxCC5PK2+WZ1PPRZdp+aJ0bMBcEbweXWux3RUHJvX9ZodcoQySkrW6qt+ahb+uk8ZjyQodLfDwtVSoYds1w==
 
 "@types/esrecurse@^4.3.1":
   version "4.3.1"
@@ -217,100 +216,100 @@
   resolved "https://registry.yarnpkg.com/@types/json5/-/json5-0.0.29.tgz#ee28707ae94e11d2b827bcbe5270bcea7f3e71ee"
   integrity sha512-dRLjCWHYg4oaA77cxO64oO+7JwCwnIzkZPdrrC71jQmQtlhM556pwKo5bUzqvZndkVbeFLIIi+9TC40JNF5hNQ==
 
-"@typescript-eslint/eslint-plugin@^8.58.0":
-  version "8.58.0"
-  resolved "https://registry.yarnpkg.com/@typescript-eslint/eslint-plugin/-/eslint-plugin-8.58.0.tgz#ad40e492f1931f46da1bd888e52b9e56df9063aa"
-  integrity sha512-RLkVSiNuUP1C2ROIWfqX+YcUfLaSnxGE/8M+Y57lopVwg9VTYYfhuz15Yf1IzCKgZj6/rIbYTmJCUSqr76r0Wg==
+"@typescript-eslint/eslint-plugin@^8.59.1":
+  version "8.59.1"
+  resolved "https://registry.yarnpkg.com/@typescript-eslint/eslint-plugin/-/eslint-plugin-8.59.1.tgz#781bc6f9002982cfaf75a185240e24ad7276628a"
+  integrity sha512-BOziFIfE+6osHO9FoJG4zjoHUcvI7fTNBSpdAwrNH0/TLvzjsk2oo8XSSOT2HhqUyhZPfHv4UOffoJ9oEEQ7Ag==
   dependencies:
     "@eslint-community/regexpp" "^4.12.2"
-    "@typescript-eslint/scope-manager" "8.58.0"
-    "@typescript-eslint/type-utils" "8.58.0"
-    "@typescript-eslint/utils" "8.58.0"
-    "@typescript-eslint/visitor-keys" "8.58.0"
+    "@typescript-eslint/scope-manager" "8.59.1"
+    "@typescript-eslint/type-utils" "8.59.1"
+    "@typescript-eslint/utils" "8.59.1"
+    "@typescript-eslint/visitor-keys" "8.59.1"
     ignore "^7.0.5"
     natural-compare "^1.4.0"
     ts-api-utils "^2.5.0"
 
-"@typescript-eslint/parser@^8.58.0":
-  version "8.58.0"
-  resolved "https://registry.yarnpkg.com/@typescript-eslint/parser/-/parser-8.58.0.tgz#da04ece1967b6c2fe8f10c3473dabf3825795ef7"
-  integrity sha512-rLoGZIf9afaRBYsPUMtvkDWykwXwUPL60HebR4JgTI8mxfFe2cQTu3AGitANp4b9B2QlVru6WzjgB2IzJKiCSA==
+"@typescript-eslint/parser@^8.59.1":
+  version "8.59.1"
+  resolved "https://registry.yarnpkg.com/@typescript-eslint/parser/-/parser-8.59.1.tgz#835d20a62350659a082a1ae2a60b822c40488905"
+  integrity sha512-HDQH9O/47Dxi1ceDhBXdaldtf/WV9yRYMjbjCuNk3qnaTD564qwv61Y7+gTxwxRKzSrgO5uhtw584igXVuuZkA==
   dependencies:
-    "@typescript-eslint/scope-manager" "8.58.0"
-    "@typescript-eslint/types" "8.58.0"
-    "@typescript-eslint/typescript-estree" "8.58.0"
-    "@typescript-eslint/visitor-keys" "8.58.0"
+    "@typescript-eslint/scope-manager" "8.59.1"
+    "@typescript-eslint/types" "8.59.1"
+    "@typescript-eslint/typescript-estree" "8.59.1"
+    "@typescript-eslint/visitor-keys" "8.59.1"
     debug "^4.4.3"
 
-"@typescript-eslint/project-service@8.58.0":
-  version "8.58.0"
-  resolved "https://registry.yarnpkg.com/@typescript-eslint/project-service/-/project-service-8.58.0.tgz#66ceda0aabf7427aec3e2713fa43eb278dead2aa"
-  integrity sha512-8Q/wBPWLQP1j16NxoPNIKpDZFMaxl7yWIoqXWYeWO+Bbd2mjgvoF0dxP2jKZg5+x49rgKdf7Ck473M8PC3V9lg==
+"@typescript-eslint/project-service@8.59.1":
+  version "8.59.1"
+  resolved "https://registry.yarnpkg.com/@typescript-eslint/project-service/-/project-service-8.59.1.tgz#49efe87c37ef84262f23df8bf62fdc56698ca6fe"
+  integrity sha512-+MuHQlHiEr00Of/IQbE/MmEoi44znZHbR/Pz7Opq4HryUOlRi+/44dro9Ycy8Fyo+/024IWtw8m4JUMCGTYxDg==
   dependencies:
-    "@typescript-eslint/tsconfig-utils" "^8.58.0"
-    "@typescript-eslint/types" "^8.58.0"
+    "@typescript-eslint/tsconfig-utils" "^8.59.1"
+    "@typescript-eslint/types" "^8.59.1"
     debug "^4.4.3"
 
-"@typescript-eslint/scope-manager@8.58.0":
-  version "8.58.0"
-  resolved "https://registry.yarnpkg.com/@typescript-eslint/scope-manager/-/scope-manager-8.58.0.tgz#e304142775e49a1b7ac3c8bf2536714447c72cab"
-  integrity sha512-W1Lur1oF50FxSnNdGp3Vs6P+yBRSmZiw4IIjEeYxd8UQJwhUF0gDgDD/W/Tgmh73mxgEU3qX0Bzdl/NGuSPEpQ==
+"@typescript-eslint/scope-manager@8.59.1":
+  version "8.59.1"
+  resolved "https://registry.yarnpkg.com/@typescript-eslint/scope-manager/-/scope-manager-8.59.1.tgz#ed90d054fc3db2d0c81464db3a953a94fb85bb58"
+  integrity sha512-LwuHQI4pDOYVKvmH2dkaJo6YZCSgouVgnS/z7yBPKBMvgtBvyLqiLy9Z6b7+m/TRcX1NFYUqZetI5Y+aT4GEfg==
   dependencies:
-    "@typescript-eslint/types" "8.58.0"
-    "@typescript-eslint/visitor-keys" "8.58.0"
+    "@typescript-eslint/types" "8.59.1"
+    "@typescript-eslint/visitor-keys" "8.59.1"
 
-"@typescript-eslint/tsconfig-utils@8.58.0", "@typescript-eslint/tsconfig-utils@^8.58.0":
-  version "8.58.0"
-  resolved "https://registry.yarnpkg.com/@typescript-eslint/tsconfig-utils/-/tsconfig-utils-8.58.0.tgz#c5a8edb21f31e0fdee565724e1b984171c559482"
-  integrity sha512-doNSZEVJsWEu4htiVC+PR6NpM+pa+a4ClH9INRWOWCUzMst/VA9c4gXq92F8GUD1rwhNvRLkgjfYtFXegXQF7A==
+"@typescript-eslint/tsconfig-utils@8.59.1", "@typescript-eslint/tsconfig-utils@^8.59.1":
+  version "8.59.1"
+  resolved "https://registry.yarnpkg.com/@typescript-eslint/tsconfig-utils/-/tsconfig-utils-8.59.1.tgz#ba2a779a444f1d5cb92a606f9b209d239fd4cab1"
+  integrity sha512-/0nEyPbX7gRsk0Uwfe4ALwwgxuA66d/l2mhRDNlAvaj4U3juhUtJNq0DsY8M2AYwwb9rEq2hrC3IcIcEt++iJA==
 
-"@typescript-eslint/type-utils@8.58.0":
-  version "8.58.0"
-  resolved "https://registry.yarnpkg.com/@typescript-eslint/type-utils/-/type-utils-8.58.0.tgz#ce0e72cd967ffbbe8de322db6089bd4374be352f"
-  integrity sha512-aGsCQImkDIqMyx1u4PrVlbi/krmDsQUs4zAcCV6M7yPcPev+RqVlndsJy9kJ8TLihW9TZ0kbDAzctpLn5o+lOg==
+"@typescript-eslint/type-utils@8.59.1":
+  version "8.59.1"
+  resolved "https://registry.yarnpkg.com/@typescript-eslint/type-utils/-/type-utils-8.59.1.tgz#9c83d3f2ed9187a815e8120f72c08317e513e409"
+  integrity sha512-klWPBR2ciQHS3f++ug/mVnWKPjBUo7icEL3FAO1lhAR1Z1i5NQYZ1EannMSRYcq5qCv5wNALlXr6fksRHyYl7w==
   dependencies:
-    "@typescript-eslint/types" "8.58.0"
-    "@typescript-eslint/typescript-estree" "8.58.0"
-    "@typescript-eslint/utils" "8.58.0"
+    "@typescript-eslint/types" "8.59.1"
+    "@typescript-eslint/typescript-estree" "8.59.1"
+    "@typescript-eslint/utils" "8.59.1"
     debug "^4.4.3"
     ts-api-utils "^2.5.0"
 
-"@typescript-eslint/types@8.58.0", "@typescript-eslint/types@^8.58.0":
-  version "8.58.0"
-  resolved "https://registry.yarnpkg.com/@typescript-eslint/types/-/types-8.58.0.tgz#e94ae7abdc1c6530e71183c1007b61fa93112a5a"
-  integrity sha512-O9CjxypDT89fbHxRfETNoAnHj/i6IpRK0CvbVN3qibxlLdo5p5hcLmUuCCrHMpxiWSwKyI8mCP7qRNYuOJ0Uww==
+"@typescript-eslint/types@8.59.1", "@typescript-eslint/types@^8.59.1":
+  version "8.59.1"
+  resolved "https://registry.yarnpkg.com/@typescript-eslint/types/-/types-8.59.1.tgz#c1d014d3f03a97e0113a8899fc9d4e45a7fb0ca9"
+  integrity sha512-ZDCjgccSdYPw5Bxh+my4Z0lJU96ZDN7jbBzvmEn0FZx3RtU1C7VWl6NbDx94bwY3V5YsgwRzJPOgeY2Q/nLG8A==
 
-"@typescript-eslint/typescript-estree@8.58.0":
-  version "8.58.0"
-  resolved "https://registry.yarnpkg.com/@typescript-eslint/typescript-estree/-/typescript-estree-8.58.0.tgz#ed233faa8e2f2a2e1357c3e7d553d6465a0ee59a"
-  integrity sha512-7vv5UWbHqew/dvs+D3e1RvLv1v2eeZ9txRHPnEEBUgSNLx5ghdzjHa0sgLWYVKssH+lYmV0JaWdoubo0ncGYLA==
+"@typescript-eslint/typescript-estree@8.59.1":
+  version "8.59.1"
+  resolved "https://registry.yarnpkg.com/@typescript-eslint/typescript-estree/-/typescript-estree-8.59.1.tgz#4391fadf98a22c869c5b6522dbf4e491e53e351a"
+  integrity sha512-OUd+vJS05sSkOip+BkZ/2NS8RMxrAAJemsC6vU3kmfLyeaJT0TftHkV9mcx2107MmsBVXXexhVu4F0TZXyMl4g==
   dependencies:
-    "@typescript-eslint/project-service" "8.58.0"
-    "@typescript-eslint/tsconfig-utils" "8.58.0"
-    "@typescript-eslint/types" "8.58.0"
-    "@typescript-eslint/visitor-keys" "8.58.0"
+    "@typescript-eslint/project-service" "8.59.1"
+    "@typescript-eslint/tsconfig-utils" "8.59.1"
+    "@typescript-eslint/types" "8.59.1"
+    "@typescript-eslint/visitor-keys" "8.59.1"
     debug "^4.4.3"
     minimatch "^10.2.2"
     semver "^7.7.3"
     tinyglobby "^0.2.15"
     ts-api-utils "^2.5.0"
 
-"@typescript-eslint/utils@8.58.0":
-  version "8.58.0"
-  resolved "https://registry.yarnpkg.com/@typescript-eslint/utils/-/utils-8.58.0.tgz#21a74a7963b0d288b719a4121c7dd555adaab3c3"
-  integrity sha512-RfeSqcFeHMHlAWzt4TBjWOAtoW9lnsAGiP3GbaX9uVgTYYrMbVnGONEfUCiSss+xMHFl+eHZiipmA8WkQ7FuNA==
+"@typescript-eslint/utils@8.59.1":
+  version "8.59.1"
+  resolved "https://registry.yarnpkg.com/@typescript-eslint/utils/-/utils-8.59.1.tgz#cf6204d69701bbbc5b150f98c18aeef0a42c10bd"
+  integrity sha512-3pIeoXhCeYH9FSCBI8P3iNwJlGuzPlYKkTlen2O9T1DSeeg8UG8jstq6BLk+Mda0qup7mgk4z4XL4OzRaxZ8LA==
   dependencies:
     "@eslint-community/eslint-utils" "^4.9.1"
-    "@typescript-eslint/scope-manager" "8.58.0"
-    "@typescript-eslint/types" "8.58.0"
-    "@typescript-eslint/typescript-estree" "8.58.0"
+    "@typescript-eslint/scope-manager" "8.59.1"
+    "@typescript-eslint/types" "8.59.1"
+    "@typescript-eslint/typescript-estree" "8.59.1"
 
-"@typescript-eslint/visitor-keys@8.58.0":
-  version "8.58.0"
-  resolved "https://registry.yarnpkg.com/@typescript-eslint/visitor-keys/-/visitor-keys-8.58.0.tgz#2abd55a4be70fd55967aceaba4330b9ba9f45189"
-  integrity sha512-XJ9UD9+bbDo4a4epraTwG3TsNPeiB9aShrUneAVXy8q4LuwowN+qu89/6ByLMINqvIMeI9H9hOHQtg/ijrYXzQ==
+"@typescript-eslint/visitor-keys@8.59.1":
+  version "8.59.1"
+  resolved "https://registry.yarnpkg.com/@typescript-eslint/visitor-keys/-/visitor-keys-8.59.1.tgz#b5cba576287a3eeb0b400b62813189abcc3f976a"
+  integrity sha512-LdDNl6C5iJExcM0Yh0PwAIBb9PrSiCsWamF/JyEZawm3kFDnRoaq3LGE4bpyRao/fWeGKKyw7icx0YxrLFC5Cg==
   dependencies:
-    "@typescript-eslint/types" "8.58.0"
+    "@typescript-eslint/types" "8.59.1"
     eslint-visitor-keys "^5.0.0"
 
 acorn-jsx@^5.3.2:
@@ -787,17 +786,17 @@ eslint-visitor-keys@^5.0.0, eslint-visitor-keys@^5.0.1:
   resolved "https://registry.yarnpkg.com/eslint-visitor-keys/-/eslint-visitor-keys-5.0.1.tgz#9e3c9489697824d2d4ce3a8ad12628f91e9f59be"
   integrity sha512-tD40eHxA35h0PEIZNeIjkHoDR4YjjJp34biM0mDvplBe//mB+IHCqHDGV7pxF+7MklTvighcCPPZC7ynWyjdTA==
 
-eslint@^10.1.0:
-  version "10.1.0"
-  resolved "https://registry.yarnpkg.com/eslint/-/eslint-10.1.0.tgz#9ca98e654e642ab2e1af6d1e9d8613857ac341b4"
-  integrity sha512-S9jlY/ELKEUwwQnqWDO+f+m6sercqOPSqXM5Go94l7DOmxHVDgmSFGWEzeE/gwgTAr0W103BWt0QLe/7mabIvA==
+eslint@^10.2.1:
+  version "10.2.1"
+  resolved "https://registry.yarnpkg.com/eslint/-/eslint-10.2.1.tgz#224b2a6caeb34473eddcf918762363e2e063222a"
+  integrity sha512-wiyGaKsDgqXvF40P8mDwiUp/KQjE1FdrIEJsM8PZ3XCiniTMXS3OHWWUe5FI5agoCnr8x4xPrTDZuxsBlNHl+Q==
   dependencies:
     "@eslint-community/eslint-utils" "^4.8.0"
     "@eslint-community/regexpp" "^4.12.2"
-    "@eslint/config-array" "^0.23.3"
-    "@eslint/config-helpers" "^0.5.3"
-    "@eslint/core" "^1.1.1"
-    "@eslint/plugin-kit" "^0.6.1"
+    "@eslint/config-array" "^0.23.5"
+    "@eslint/config-helpers" "^0.5.5"
+    "@eslint/core" "^1.2.1"
+    "@eslint/plugin-kit" "^0.7.1"
     "@humanfs/node" "^0.16.6"
     "@humanwhocodes/module-importer" "^1.0.1"
     "@humanwhocodes/retry" "^0.4.2"
@@ -1559,10 +1558,10 @@ prettier-linter-helpers@^1.0.1:
   dependencies:
     fast-diff "^1.1.2"
 
-prettier@^3.8.1:
-  version "3.8.1"
-  resolved "https://registry.yarnpkg.com/prettier/-/prettier-3.8.1.tgz#edf48977cf991558f4fcbd8a3ba6015ba2a3a173"
-  integrity sha512-UOnG6LftzbdaHZcKoPFtOcCKztrQ57WkHDeRD9t/PTQtmT0NHSeWWepj6pS0z/N7+08BHFDQVUrfmfMRcZwbMg==
+prettier@^3.8.3:
+  version "3.8.3"
+  resolved "https://registry.yarnpkg.com/prettier/-/prettier-3.8.3.tgz#560f2de55bf01b4c0503bc629d5df99b9a1d09b0"
+  integrity sha512-7igPTM53cGHMW8xWuVTydi2KO233VFiTNyF5hLJqpilHfmn8C8gPf+PS7dUT64YcXFbiMGZxS9pCSxL/Dxm/Jw==
 
 punycode@^2.1.0:
   version "2.3.1"
@@ -1815,17 +1814,17 @@ tsconfig-paths@^3.15.0:
     minimist "^1.2.6"
     strip-bom "^3.0.0"
 
-turbo@^2.9.3:
-  version "2.9.3"
-  resolved "https://registry.yarnpkg.com/turbo/-/turbo-2.9.3.tgz#4f0adf2c8677edd7b46d400629c99e9e26e58e44"
-  integrity sha512-J/VUvsGRykPb9R8Kh8dHVBOqioDexLk9BhLCU/ZybRR+HN9UR3cURdazFvNgMDt9zPP8TF6K73Z+tplfmi0PqQ==
+turbo@^2.9.7:
+  version "2.9.7"
+  resolved "https://registry.yarnpkg.com/turbo/-/turbo-2.9.7.tgz#da6d5a821f0bde5174e1a55af6690dad5c2fb004"
+  integrity sha512-epxzqVO2s0IxcSWcgb+qKrtco8isfe7g3VtiS6hkYnEK4A9XQDZbrtavQ6MtWR1KoQn+1fUomaQth2rfRHlUlg==
   optionalDependencies:
-    "@turbo/darwin-64" "2.9.3"
-    "@turbo/darwin-arm64" "2.9.3"
-    "@turbo/linux-64" "2.9.3"
-    "@turbo/linux-arm64" "2.9.3"
-    "@turbo/windows-64" "2.9.3"
-    "@turbo/windows-arm64" "2.9.3"
+    "@turbo/darwin-64" "2.9.7"
+    "@turbo/darwin-arm64" "2.9.7"
+    "@turbo/linux-64" "2.9.7"
+    "@turbo/linux-arm64" "2.9.7"
+    "@turbo/windows-64" "2.9.7"
+    "@turbo/windows-arm64" "2.9.7"
 
 type-check@^0.4.0, type-check@~0.4.0:
   version "0.4.0"
@@ -1906,11 +1905,6 @@ uuid@10.0.0, uuid@^10.0.0:
   resolved "https://registry.yarnpkg.com/uuid/-/uuid-10.0.0.tgz#5a95aa454e6e002725c79055fd42aaba30ca6294"
   integrity sha512-8XkAphELsDnEGrDxUOHB3RGvXz6TeuYSGEZBOjtTtPm2lwhGBjLgOzLHB63IUWfBpNucQjND6d3AOudO+H3RWQ==
 
-uuid@^11.1.0:
-  version "11.1.0"
-  resolved "https://registry.yarnpkg.com/uuid/-/uuid-11.1.0.tgz#9549028be1753bb934fc96e2bca09bb4105ae912"
-  integrity sha512-0/A9rDy9P7cJ+8w1c9WD9V//9Wj15Ce2MPz8Ri6032usz+NfePxx5AcN3bN+r6ZL6jEo066/yNYB3tn4pQEx+A==
-
 uuid@^13.0.0:
   version "13.0.0"
   resolved "https://registry.yarnpkg.com/uuid/-/uuid-13.0.0.tgz#263dc341b19b4d755eb8fe36b78d95a6b65707e8"

libs/cli/langgraph_cli/__init__.py

@@ -1 +1 @@
-__version__ = "0.4.24"
+__version__ = "0.4.25"

libs/cli/langgraph_cli/deploy.py

@@ -115,6 +115,172 @@ class BuildResult:
     show_build_logs_on_failure: bool = False
 
 
+# ---------------------------------------------------------------------------
+# Structured output emitter
+# ---------------------------------------------------------------------------
+
+_emitter: "_Emitter | None" = None
+_no_input: bool = False
+
+
+class _Emitter:
+    """Dual-mode output: JSON-lines (``--json``) or human-readable click text."""
+
+    def __init__(self, json_mode: bool) -> None:
+        self._json = json_mode
+
+    @property
+    def json_mode(self) -> bool:
+        return self._json
+
+    # -- Structured event helpers ------------------------------------------
+
+    def step(self, step: int, message: str, **extra: object) -> None:
+        if self._json:
+            self._write({"event": "step", "step": step, "message": message, **extra})
+        else:
+            click.secho(f"{step}. {message}", fg="cyan")
+
+    def info(self, message: str, **extra: object) -> None:
+        if self._json:
+            self._write({"event": "info", "message": message, **extra})
+        else:
+            click.secho(f"   {message}", fg="green")
+
+    def warn(self, message: str, **extra: object) -> None:
+        """Warning nested under a step. Text mode indents; JSON mode strips leading whitespace."""
+        if self._json:
+            self._write({"event": "warn", "message": message.lstrip(), **extra})
+        else:
+            click.secho(f"   {message}", fg="yellow")
+
+    def note(self, message: str, **extra: object) -> None:
+        """Top-level banner (pre-step). Text mode does not indent."""
+        if self._json:
+            self._write({"event": "note", "message": message, **extra})
+        else:
+            click.secho(message, fg="yellow")
+
+    def error(self, message: str, **extra: object) -> None:
+        if self._json:
+            self._write({"event": "error", "message": message, **extra})
+        else:
+            click.secho(f"   {message}", fg="red")
+
+    def status_change(
+        self,
+        status: str,
+        elapsed_seconds: float,
+        finished: bool = False,
+    ) -> None:
+        mins, secs = divmod(int(elapsed_seconds), 60)
+        elapsed_str = f"{mins}m {secs:02d}s" if mins else f"{secs}s"
+        if self._json:
+            self._write(
+                {
+                    "event": "status_change",
+                    "status": status,
+                    "elapsed_seconds": round(elapsed_seconds, 1),
+                    "message": f"{status}... ({elapsed_str})",
+                }
+            )
+        else:
+            click.echo(f"   {status}... ({elapsed_str})")
+
+    def log(self, message: str) -> None:
+        if self._json:
+            self._write({"event": "log", "message": message})
+        else:
+            click.echo(f"   | {message}")
+
+    def status_url(self, url: str) -> None:
+        if self._json:
+            self._write({"event": "status_url", "url": url})
+        else:
+            click.secho(f"   View status: {url}", fg="cyan")
+
+    def result(
+        self,
+        status: str,
+        *,
+        deployment_id: str,
+        url: str | None = None,
+        status_url: str | None = None,
+        fallback_status_message: str | None = None,
+    ) -> None:
+        if self._json:
+            if status == "succeeded":
+                message = "Deployment successful!"
+            elif status == "failed":
+                message = "Deployment failed"
+            else:
+                message = "Timed out waiting for deployment."
+            payload: dict = {
+                "event": "result",
+                "status": status,
+                "deployment_id": deployment_id,
+                "message": message,
+            }
+            if url:
+                payload["url"] = url
+            if status_url:
+                payload["status_url"] = status_url
+            self._write(payload)
+        else:
+            if status == "succeeded":
+                click.secho("   Deployment successful!", fg="green")
+                if url:
+                    click.secho(f"   URL: {url}", fg="green")
+                if status_url:
+                    click.secho(f"   View status: {status_url}", fg="green")
+            elif status == "failed":
+                click.secho("   Deployment failed", fg="red")
+                if status_url:
+                    click.secho(f"   View status: {status_url}", fg="red")
+            elif status == "timed_out":
+                click.secho("   Timed out waiting for deployment.", fg="yellow")
+                if status_url:
+                    click.secho(f"   Check status at: {status_url}", fg="yellow")
+                elif fallback_status_message:
+                    click.secho(f"   {fallback_status_message}", fg="yellow")
+
+    def heartbeat(self, status: str, elapsed_seconds: float) -> None:
+        if self._json:
+            mins, secs = divmod(int(elapsed_seconds), 60)
+            elapsed_str = f"{mins}m {secs:02d}s" if mins else f"{secs}s"
+            self._write(
+                {
+                    "event": "heartbeat",
+                    "status": status,
+                    "elapsed_seconds": round(elapsed_seconds, 1),
+                    "message": f"{status}... ({elapsed_str})",
+                }
+            )
+
+    def upload_progress(self, size_mb: float, pct: int) -> None:
+        if self._json:
+            self._write(
+                {
+                    "event": "upload_progress",
+                    "size_mb": round(size_mb, 1),
+                    "pct": pct,
+                }
+            )
+        else:
+            click.echo(f"\r   Uploading ({size_mb:.1f} MB)... {pct}%", nl=False)
+
+    def _write(self, obj: dict) -> None:
+        import sys as _sys
+
+        _sys.stdout.write(json_mod.dumps(obj, default=str) + "\n")
+        _sys.stdout.flush()
+
+
+def _get_emitter() -> _Emitter:
+    """Return the module-level emitter (falls back to text mode)."""
+    return _emitter or _Emitter(json_mode=False)
+
+
 # ---------------------------------------------------------------------------
 # Validators
 # ---------------------------------------------------------------------------
@@ -172,15 +338,16 @@ def find_deployment_id_by_name(
 # ---------------------------------------------------------------------------
 
 
-def normalize_image_name(value: str | None) -> str:
-    """Sanitize a deployment/directory name into a valid Docker repository name.
+def normalize_name(value: str | None) -> str:
+    """Sanitize a deployment/directory name into a valid deployment name.
 
-    Docker repository names must be lowercase and may only contain
-    [a-z0-9._-].  Invalid characters are replaced with hyphens.
+    LangSmith Deployment names only allow lowercase
+    alphanumeric characters and hyphens ([a-z0-9-]).
+    Invalid characters are replaced with hyphens.
     """
     if not value:
         return "app"
-    slug = re.sub(r"[^a-z0-9._-]+", "-", value.lower()).strip("-.")
+    slug = re.sub(r"[^a-z0-9-]+", "-", value.lower()).strip("-")
     return slug or "app"
 
 
@@ -307,9 +474,8 @@ def _resolve_env_path(
     if isinstance(env_field, str):
         env_path = (config_path.parent / env_field).resolve()
         if not env_path.exists():
-            click.secho(
-                f"Warning: env file '{env_field}' specified in langgraph.json not found.",
-                fg="yellow",
+            _get_emitter().note(
+                f"Warning: env file '{env_field}' specified in langgraph.json not found."
             )
             return None
         return env_path
@@ -343,7 +509,7 @@ def _secrets_from_env(
     secrets: list[dict[str, str]] = []
     for name, value in env_vars.items():
         if name in RESERVED_ENV_VARS:
-            click.secho(f"   Skipping reserved env var: {name}", fg="yellow")
+            _get_emitter().note(f"Skipping reserved env var: {name}")
             continue
         if not value:
             continue
@@ -386,8 +552,8 @@ def _resolve_build_mode(
 # ---------------------------------------------------------------------------
 
 
-def _log_deploy_step(step: int, message: str) -> None:
-    click.secho(f"{step}. {message}", fg="cyan")
+def _log_deploy_step(step: int, message: str, **extra: object) -> None:
+    _get_emitter().step(step, message, **extra)
 
 
 def _resolve_deployment(
@@ -411,12 +577,13 @@ def _resolve_deployment(
     found_id = _call_host_backend_with_optional_tenant(
         client, lambda c: find_deployment_id_by_name(c, name)
     )
+    em = _get_emitter()
     if found_id:
         deployment_id = str(found_id)
-        click.secho(f"   Found existing deployment (ID: {deployment_id})", fg="green")
+        em.info(f"Found existing deployment (ID: {deployment_id})")
     else:
         needs_creation = True
-        click.secho(not_found_message, fg="yellow")
+        em.warn(not_found_message)
     return deployment_id, needs_creation, step + 1
 
 
@@ -444,7 +611,7 @@ def _create_deployment(
         raise HostBackendError(
             "POST /v2/deployments succeeded but response missing a valid 'id'"
         )
-    click.secho(f"   Deployment ID: {created_id}", fg="green")
+    _get_emitter().info(f"Deployment ID: {created_id}", deployment_id=created_id)
     return created_id, step + 1
 
 
@@ -458,21 +625,36 @@ def _smith_dashboard_base_url(host_url: str | None) -> str:
     hostname = parsed.hostname or ""
     if hostname in ("localhost", "127.0.0.1"):
         return host_url.rstrip("/")
-    if hostname.startswith("eu."):
-        return "https://eu.smith.langchain.com"
+
+    api_host_suffix = "api.host.langchain.com"
+    if hostname == api_host_suffix:
+        return "https://smith.langchain.com"
+    if hostname.endswith(f".{api_host_suffix}"):
+        prefix = hostname[: -(len(api_host_suffix) + 1)]
+        return f"https://{prefix}.smith.langchain.com"
+
     return "https://smith.langchain.com"
 
 
-def _print_deployment_status_url(
+def _get_deployment_status_url(
     updated: object, deployment_id: str, host_url: str | None = None
-) -> None:
-    """Print the deployment status URL when tenant metadata is available."""
+) -> str | None:
+    """Compute the LangSmith dashboard URL for a deployment, if possible."""
     tenant_id = updated.get("tenant_id") if isinstance(updated, dict) else None
     if not tenant_id:
-        return
+        return None
     base = _smith_dashboard_base_url(host_url)
-    status_url = f"{base}/o/{tenant_id}/host/deployments/{deployment_id}"
-    click.secho(f"   View status: {status_url}", fg="cyan")
+    return f"{base}/o/{tenant_id}/host/deployments/{deployment_id}"
+
+
+def _emit_deployment_status_url(
+    updated: object, deployment_id: str, host_url: str | None = None
+) -> str | None:
+    """Emit the deployment status URL and return it."""
+    url = _get_deployment_status_url(updated, deployment_id, host_url)
+    if url:
+        _get_emitter().status_url(url)
+    return url
 
 
 def _poll_revision_status(
@@ -486,6 +668,7 @@ def _poll_revision_status(
     on_interrupt: Callable[[str], None] | None = None,
 ) -> tuple[str, str | None]:
     """Poll latest revision status until terminal status or timeout."""
+    em = _get_emitter()
     revisions_resp = client.list_revisions(deployment_id, limit=1)
     resources = (
         revisions_resp.get("resources", []) if isinstance(revisions_resp, dict) else []
@@ -497,7 +680,11 @@ def _poll_revision_status(
     last_status = ""
     deadline = time.time() + timeout_seconds
     start_time = time.monotonic()
-    with Progress(message=progress_message, elapsed=True) as set_progress:
+    last_heartbeat = start_time
+    json_mode = em.json_mode
+    with Progress(
+        message=progress_message, elapsed=True, json_mode=json_mode
+    ) as set_progress:
         while time.time() < deadline:
             try:
                 rev = client.get_revision(deployment_id, revision_id)
@@ -514,14 +701,15 @@ def _poll_revision_status(
             if status != last_status:
                 set_progress("")
                 if last_status:
-                    elapsed = time.monotonic() - start_time
-                    mins, secs = divmod(int(elapsed), 60)
-                    elapsed_str = f"{mins}m {secs:02d}s" if mins else f"{secs}s"
-                    click.echo(f"   {last_status}... ({elapsed_str})")
+                    em.status_change(last_status, time.monotonic() - start_time)
                 last_status = status
                 if status in _TERMINAL_STATUSES:
                     break
                 set_progress(f"{status}...")
+                last_heartbeat = time.monotonic()
+            elif json_mode and time.monotonic() - last_heartbeat > 10:
+                em.heartbeat(last_status, time.monotonic() - start_time)
+                last_heartbeat = time.monotonic()
 
             if on_poll is not None:
                 on_poll(status, revision_id, set_progress)
@@ -538,8 +726,10 @@ def _print_deployment_result(
     last_status: str,
     *,
     dashboard_label: str,
+    status_url: str | None = None,
 ) -> None:
     """Print final deployment status and raise on failure."""
+    em = _get_emitter()
     dep_info = client.get_deployment(deployment_id)
     custom_url = None
     if isinstance(dep_info, dict):
@@ -548,24 +738,28 @@ def _print_deployment_result(
             custom_url = sc.get("custom_url")
 
     if last_status == "DEPLOYED":
-        click.secho("   Deployment successful!", fg="green")
-        if custom_url:
-            click.secho(f"   URL: {custom_url}", fg="green")
+        em.result(
+            "succeeded",
+            deployment_id=deployment_id,
+            url=custom_url,
+            status_url=status_url,
+        )
     elif last_status in ("BUILD_FAILED", "DEPLOY_FAILED", "CREATE_FAILED"):
-        click.secho(f"   Deployment failed: {last_status}", fg="red")
+        em.result(
+            "failed",
+            deployment_id=deployment_id,
+            status_url=status_url,
+        )
         raise click.exceptions.Exit(1)
     else:
-        click.secho(
-            f"   Timed out waiting for deployment (last status: {last_status}).",
-            fg="yellow",
+        em.result(
+            "timed_out",
+            deployment_id=deployment_id,
+            status_url=status_url,
+            fallback_status_message=(
+                f"Check status in the LangSmith {dashboard_label}."
+            ),
         )
-        if custom_url:
-            click.secho(f"   Check status at: {custom_url}", fg="yellow")
-        else:
-            click.secho(
-                f"   Check status in the LangSmith {dashboard_label}.",
-                fg="yellow",
-            )
 
 
 # ---------------------------------------------------------------------------
@@ -594,14 +788,16 @@ def _docker_config_for_token(registry_host: str, token: str):
 # ---------------------------------------------------------------------------
 
 _UPLOAD_TIMEOUT_SECONDS = 300
+_BYTES_PER_MIB = 1_048_576
 
 
 class _ProgressReader:
-    """File-like wrapper that displays upload progress via click."""
+    """File-like wrapper that reports upload progress via the emitter."""
 
-    def __init__(self, fobj, file_size: int):
+    def __init__(self, fobj, file_size: int, emitter: "_Emitter"):
         self._fobj = fobj
         self._file_size = file_size
+        self._emitter = emitter
         self._uploaded = 0
 
     def read(self, size=-1):
@@ -611,10 +807,7 @@ class _ProgressReader:
             pct = (
                 int(self._uploaded * 100 / self._file_size) if self._file_size else 100
             )
-            click.echo(
-                f"\r   Uploading ({self._file_size / 1_048_576:.1f} MB)... {pct}%",
-                nl=False,
-            )
+            self._emitter.upload_progress(self._file_size / _BYTES_PER_MIB, pct)
         return data
 
     def __len__(self):
@@ -626,10 +819,13 @@ def _upload_to_gcs(signed_url: str, file_path: str, file_size: int) -> None:
     import urllib.error
     import urllib.request
 
+    em = _get_emitter()
+
     with open(file_path, "rb") as f:
+        reader = _ProgressReader(f, file_size, em)
         req = urllib.request.Request(
             signed_url,
-            data=_ProgressReader(f, file_size),
+            data=reader,
             method="PUT",
             headers={
                 "Content-Type": "application/gzip",
@@ -644,7 +840,8 @@ def _upload_to_gcs(signed_url: str, file_path: str, file_size: int) -> None:
             raise click.ClickException(
                 f"Upload failed with status {err.code}: {detail}"
             ) from None
-    click.echo()
+    if not em.json_mode:
+        click.echo()
 
 
 # ---------------------------------------------------------------------------
@@ -752,7 +949,7 @@ def _run_local_build(
         if "://" in normalized_registry:
             normalized_registry = normalized_registry.split("//", 1)[1]
         repo_seed = image_name or name or config.parent.name
-        repo_name = normalize_image_name(repo_seed)
+        repo_name = normalize_name(repo_seed)
         tag_value = normalize_image_tag(tag)
         remote_image = f"{normalized_registry}/{repo_name}:{tag_value}"
 
@@ -811,9 +1008,8 @@ def _run_local_build(
                     break
                 except click.exceptions.Exit:
                     if attempt < max_push_retries - 1:
-                        click.secho(
-                            f"   Push failed, retrying (attempt {attempt + 2} of {max_push_retries})...",
-                            fg="yellow",
+                        _get_emitter().warn(
+                            f"   Push failed, retrying (attempt {attempt + 2} of {max_push_retries})..."
                         )
                     else:
                         raise
@@ -847,9 +1043,10 @@ def _run_remote_build(
     """Upload source tarball and trigger a remote build."""
     from langgraph_cli.archive import create_archive
 
+    em = _get_emitter()
     _log_deploy_step(step, "Creating source archive")
     with create_archive(config, config_json) as (archive_path, file_size, config_rel):
-        click.secho(f"   Archive created ({file_size / 1_048_576:.1f} MB)", fg="green")
+        em.info(f"Archive created ({file_size / _BYTES_PER_MIB:.1f} MB)")
         step += 1
 
         _log_deploy_step(step, "Requesting upload URL")
@@ -897,12 +1094,12 @@ def _run_remote_build(
                 if has_output:
                     set_progress("")
                     if not logs_header_printed:
-                        click.echo(f"   {status} (build logs):")
+                        em.info(f"{status} (build logs):")
                         logs_header_printed = True
                 for entry in entries:
                     msg = entry.get("message", "")
                     if msg:
-                        click.echo(f"   | {msg}")
+                        em.log(msg)
                 log_offset = logs_resp.get("next_offset") or log_offset
                 if has_output:
                     set_progress(f"{status}...")
@@ -910,11 +1107,10 @@ def _run_remote_build(
             pass
 
     def _handle_interrupt(revision_id: str) -> None:
-        click.secho(
-            f"\n   Interrupted. Deployment ID: {deployment_id}, Revision ID: {revision_id}",
-            fg="yellow",
+        em.warn(
+            f"\nInterrupted. Deployment ID: {deployment_id}, Revision ID: {revision_id}"
         )
-        click.secho("   The build will continue remotely.", fg="yellow")
+        em.warn("The build will continue remotely.")
 
     return BuildResult(
         updated=updated if isinstance(updated, dict) else {},
@@ -952,12 +1148,20 @@ def _create_host_backend_client(
                 resolved_api_key = val
                 break
     if not resolved_api_key:
+        if _no_input:
+            raise click.ClickException(
+                "No LangSmith API key found. Set LANGSMITH_API_KEY in the "
+                "environment or .env file."
+            )
         click.secho(
             "No LangSmith API key found. Create one at Settings > API Keys in LangSmith.",
             fg="yellow",
         )
         resolved_api_key = click.prompt("Enter LangSmith API key", hide_input=True)
-    return HostBackendClient(host_url, resolved_api_key)
+    tenant_id = env_vars.get("LANGSMITH_TENANT_ID") or os.environ.get(
+        "LANGSMITH_TENANT_ID"
+    )
+    return HostBackendClient(host_url, resolved_api_key, tenant_id=tenant_id)
 
 
 def _call_host_backend_with_optional_tenant(
@@ -982,6 +1186,12 @@ def _call_host_backend_with_optional_tenant(
                 and err.status_code == 403
                 and "requires workspace specification" in err.message
             ):
+                if _no_input:
+                    raise click.ClickException(
+                        "API key is org-scoped and requires a workspace ID. "
+                        "Set LANGSMITH_TENANT_ID in your .env file or "
+                        "use a workspace-scoped API key."
+                    ) from None
                 click.secho(
                     "Your API key is org-scoped and requires a workspace ID.",
                     fg="yellow",
@@ -1189,6 +1399,19 @@ def _deploy_base_options(
                     "if Docker is not available locally."
                 ),
             ),
+            click.option(
+                "--json",
+                "json_output",
+                is_flag=True,
+                default=False,
+                help="Emit structured JSON-lines to stdout instead of human-readable text.",
+            ),
+            click.option(
+                "--no-input",
+                is_flag=True,
+                default=False,
+                help="Never prompt for input; fail with an error if a required value is missing.",
+            ),
         ]
         if include_docker_args:
             # Only attach build args to the default command; on the group they
@@ -1256,36 +1479,50 @@ def _deploy_cmd(
     no_wait: bool,
     remote_build_flag: bool | None,
     docker_build_args: Sequence[str],
+    json_output: bool,
+    no_input: bool,
 ):
-    click.secho(
-        "Note: 'langgraph deploy' is in beta. Expect frequent updates and improvements.",
-        fg="yellow",
+    global _emitter, _no_input
+    _emitter = _Emitter(json_mode=json_output)
+    _no_input = no_input
+    em = _emitter
+
+    em.note(
+        "Note: 'langgraph deploy' is in beta. Expect frequent updates and improvements."
     )
-    click.echo()
+    if not json_output:
+        click.echo()
 
     # -- 1. Preflight --
     validate_deploy_commands(install_command, build_command)
     config_json = langgraph_cli.config.validate_config_file(config)
-    warn_non_wolfi_distro(config_json)
+    warn_non_wolfi_distro(config_json, emit=em.note)
 
     env_vars = _parse_env_from_config(config_json, config)
 
     if not deployment_id and not name:
         name = env_vars.get(_DEPLOYMENT_NAME_ENV)
     if not deployment_id and not name:
-        default_name = normalize_image_name(pathlib.Path.cwd().name)
-        name = click.prompt("Deployment name", default=default_name)
-        env_path = _resolve_env_path(config_json, config)
-        if env_path is not None:
-            set_key(str(env_path), _DEPLOYMENT_NAME_ENV, name)
-            click.echo(f"Saved deployment name to {env_path}")
+        default_name = normalize_name(pathlib.Path.cwd().name)
+        if no_input:
+            name = default_name
+        else:
+            name = click.prompt("Deployment name", default=default_name)
+    if name and not deployment_id:
+        name = normalize_name(name)
+        if not no_input:
+            env_path = _resolve_env_path(config_json, config)
+            if env_path is not None:
+                set_key(str(env_path), _DEPLOYMENT_NAME_ENV, name)
+                em.info(f"Saved deployment name to {env_path}")
 
     secrets = _secrets_from_env(_env_without_deployment_name(env_vars))
 
     use_remote_build, local_build_error = _resolve_build_mode(remote_build_flag)
     if use_remote_build and remote_build_flag is None and local_build_error:
-        click.secho(f"{local_build_error}\nUsing remote build instead.", fg="yellow")
-        click.echo()
+        em.note(f"{local_build_error}\nUsing remote build instead.")
+        if not json_output:
+            click.echo()
 
     # -- 2. Resolve / create deployment --
     client = _create_host_backend_client(host_url, api_key, env_vars=env_vars)
@@ -1297,9 +1534,9 @@ def _deploy_cmd(
         deployment_id,
         name,
         not_found_message=(
-            "   No deployment found. Will create."
+            "No deployment found. Will create."
             if use_remote_build
-            else "   No deployment found. Will create after build."
+            else "No deployment found. Will create after build."
         ),
     )
 
@@ -1350,10 +1587,14 @@ def _deploy_cmd(
         )
 
     # -- 4. Shared wait + result --
-    _print_deployment_status_url(build_result.updated, deployment_id, host_url)
+    dep_status_url = _emit_deployment_status_url(
+        build_result.updated,
+        deployment_id,
+        host_url,
+    )
 
     if no_wait:
-        click.secho(f"   {build_result.no_result_message}", fg="green")
+        em.info(build_result.no_result_message)
         return
 
     last_status, revision_id = _poll_revision_status(
@@ -1366,7 +1607,7 @@ def _deploy_cmd(
         on_interrupt=build_result.on_interrupt,
     )
     if not last_status:
-        click.secho(f"   {build_result.no_result_message}", fg="green")
+        em.info(build_result.no_result_message)
         return
 
     if (
@@ -1375,7 +1616,7 @@ def _deploy_cmd(
         and not verbose
         and revision_id is not None
     ):
-        click.secho("   Last build log lines:", fg="red")
+        em.error("Last build log lines:")
         try:
             logs_resp = client.get_build_logs(
                 deployment_id,
@@ -1387,19 +1628,17 @@ def _deploy_cmd(
                 for entry in entries:
                     msg = entry.get("message", "")
                     if msg:
-                        click.echo(f"   | {msg}")
+                        em.log(msg)
         except Exception:
-            click.secho("   (failed to fetch build logs)", fg="red")
-        click.secho(
-            "   Re-run with --verbose to see full build output.",
-            fg="yellow",
-        )
+            em.error("(failed to fetch build logs)")
+        em.warn("Re-run with --verbose to see full build output.")
 
     _print_deployment_result(
         client,
         deployment_id,
         last_status,
         dashboard_label="Deployment dashboard",
+        status_url=dep_status_url,
     )
 
 

libs/cli/langgraph_cli/progress.py

@@ -12,10 +12,11 @@ class Progress:
         while True:
             yield from "|/-\\"
 
-    def __init__(self, *, message="", elapsed: bool = False):
+    def __init__(self, *, message="", elapsed: bool = False, json_mode: bool = False):
         self.message = message
         self._base_message = message
         self._show_elapsed = elapsed
+        self._json_mode = json_mode
         # use this to make sure we don't kill thread when we set msg to ""
         self._stop = threading.Event()
         # signalled when the spinner has no text on screen
@@ -69,6 +70,9 @@ class Progress:
             self._line_clear.set()
 
     def __enter__(self) -> Callable[[str], None]:
+        if self._json_mode:
+            return lambda message: None
+
         if sys.stdout.isatty():
             self.thread = threading.Thread(target=self.spinner_task)
             self.thread.start()
@@ -90,6 +94,8 @@ class Progress:
             return set_message
 
     def __exit__(self, exception, value, tb):
+        if self._json_mode:
+            return
         if sys.stdout.isatty():
             self.message = ""
             self._stop.set()

libs/cli/langgraph_cli/util.py

@@ -1,5 +1,7 @@
 """General-purpose utilities shared across the LangGraph CLI."""
 
+from collections.abc import Callable
+
 import click
 
 
@@ -7,21 +9,42 @@ def clean_empty_lines(input_str: str):
     return "\n".join(filter(None, input_str.splitlines()))
 
 
-def warn_non_wolfi_distro(config_json: dict) -> None:
-    """Show warning if image_distro is not set to 'wolfi'."""
+def warn_non_wolfi_distro(
+    config_json: dict,
+    *,
+    emit: Callable[[str], None] | None = None,
+) -> None:
+    """Show warning if image_distro is not set to 'wolfi'.
+
+    When ``emit`` is provided, each warning line is sent through it (used by
+    callers that need JSON-aware output). Otherwise falls back to colored
+    ``click.secho`` output.
+    """
     image_distro = config_json.get("image_distro", "debian")  # Default is debian
-    if image_distro != "wolfi":
-        click.secho(
-            "⚠️  Security Recommendation: Consider switching to Wolfi Linux for enhanced security.",
-            fg="yellow",
-            bold=True,
+    if image_distro == "wolfi":
+        return
+    if emit is not None:
+        emit(
+            "⚠️  Security Recommendation: Consider switching to Wolfi Linux for enhanced security."
         )
-        click.secho(
-            "   Wolfi is a security-oriented, minimal Linux distribution designed for containers.",
-            fg="yellow",
+        emit(
+            "   Wolfi is a security-oriented, minimal Linux distribution designed for containers."
         )
-        click.secho(
-            '   To switch, add \'"image_distro": "wolfi"\' to your langgraph.json config file.',
-            fg="yellow",
+        emit(
+            '   To switch, add \'"image_distro": "wolfi"\' to your langgraph.json config file.'
         )
-        click.secho("")  # Empty line for better readability
+        return
+    click.secho(
+        "⚠️  Security Recommendation: Consider switching to Wolfi Linux for enhanced security.",
+        fg="yellow",
+        bold=True,
+    )
+    click.secho(
+        "   Wolfi is a security-oriented, minimal Linux distribution designed for containers.",
+        fg="yellow",
+    )
+    click.secho(
+        '   To switch, add \'"image_distro": "wolfi"\' to your langgraph.json config file.',
+        fg="yellow",
+    )
+    click.secho("")  # Empty line for better readability

libs/cli/tests/unit_tests/test_deploy_helpers.py

@@ -1,6 +1,8 @@
 import base64
+import io
 import json
 import os
+import sys
 
 import click
 import httpx
@@ -8,12 +10,15 @@ import pytest
 
 from langgraph_cli.deploy import (
     _call_host_backend_with_optional_tenant,
+    _create_host_backend_client,
     _docker_config_for_token,
+    _Emitter,
     _env_without_deployment_name,
     _parse_env_from_config,
     _resolve_env_path,
-    normalize_image_name,
+    _smith_dashboard_base_url,
     normalize_image_tag,
+    normalize_name,
 )
 from langgraph_cli.host_backend import HostBackendClient, HostBackendError
 
@@ -40,30 +45,33 @@ class TestDockerConfigForToken:
             assert "gcr.io" in data["auths"]
 
 
-class TestNormalizeImageName:
+class TestNormalizeName:
     def test_simple_name(self):
-        assert normalize_image_name("myapp") == "myapp"
+        assert normalize_name("myapp") == "myapp"
 
     def test_uppercase_lowered(self):
-        assert normalize_image_name("MyApp") == "myapp"
+        assert normalize_name("MyApp") == "myapp"
 
     def test_special_chars_replaced(self):
-        assert normalize_image_name("my app!@#v2") == "my-app-v2"
+        assert normalize_name("my app!@#v2") == "my-app-v2"
 
-    def test_dots_and_hyphens_kept(self):
-        assert normalize_image_name("my-app.v2") == "my-app.v2"
+    def test_dots_replaced_with_hyphens(self):
+        assert normalize_name("my-app.v2") == "my-app-v2"
+
+    def test_underscores_replaced_with_hyphens(self):
+        assert normalize_name("simple_graph_name") == "simple-graph-name"
 
     def test_leading_trailing_stripped(self):
-        assert normalize_image_name("--my-app..") == "my-app"
+        assert normalize_name("--my-app..") == "my-app"
 
     def test_empty_string_returns_app(self):
-        assert normalize_image_name("") == "app"
+        assert normalize_name("") == "app"
 
     def test_none_returns_app(self):
-        assert normalize_image_name(None) == "app"
+        assert normalize_name(None) == "app"
 
     def test_all_invalid_chars_returns_app(self):
-        assert normalize_image_name("!!!") == "app"
+        assert normalize_name("!!!") == "app"
 
 
 class TestNormalizeImageTag:
@@ -271,3 +279,256 @@ class TestCallHostBackendWithOptionalTenant:
             _call_host_backend_with_optional_tenant(
                 client, lambda c: c.list_deployments()
             )
+
+    def test_workspace_prompt_blocked_by_no_input(self, monkeypatch):
+        """With _no_input=True, 403 requiring workspace should raise ClickException."""
+        import langgraph_cli.deploy as deploy_mod
+
+        monkeypatch.setattr(deploy_mod, "_no_input", True)
+
+        requires_workspace = '{"detail":"requires workspace specification"}'
+        client = self._make_client(
+            lambda req: httpx.Response(403, text=requires_workspace)
+        )
+        with pytest.raises(click.ClickException, match="workspace"):
+            _call_host_backend_with_optional_tenant(
+                client, lambda c: c.list_deployments()
+            )
+
+
+# ---------------------------------------------------------------------------
+# _Emitter JSON mode
+# ---------------------------------------------------------------------------
+
+
+class TestEmitterJsonMode:
+    """Verify that _Emitter in json_mode writes valid JSON-lines to stdout."""
+
+    def _capture(self, fn):
+        """Run fn with stdout captured and return parsed JSON objects."""
+        buf = io.StringIO()
+        old = sys.stdout
+        sys.stdout = buf
+        try:
+            fn()
+        finally:
+            sys.stdout = old
+        lines = [line for line in buf.getvalue().splitlines() if line.strip()]
+        return [json.loads(line) for line in lines]
+
+    def test_step_event(self):
+        em = _Emitter(json_mode=True)
+        events = self._capture(lambda: em.step(1, "Building image"))
+        assert len(events) == 1
+        assert events[0]["event"] == "step"
+        assert events[0]["step"] == 1
+        assert events[0]["message"] == "Building image"
+
+    def test_info_event(self):
+        em = _Emitter(json_mode=True)
+        events = self._capture(lambda: em.info("All good"))
+        assert events[0]["event"] == "info"
+        assert events[0]["message"] == "All good"
+
+    def test_warn_event(self):
+        em = _Emitter(json_mode=True)
+        events = self._capture(lambda: em.warn("Careful"))
+        assert events[0]["event"] == "warn"
+
+    def test_error_event(self):
+        em = _Emitter(json_mode=True)
+        events = self._capture(lambda: em.error("Boom"))
+        assert events[0]["event"] == "error"
+        assert events[0]["message"] == "Boom"
+
+    def test_status_change_event(self):
+        em = _Emitter(json_mode=True)
+        events = self._capture(lambda: em.status_change("building", 12.345))
+        assert events[0]["event"] == "status_change"
+        assert events[0]["status"] == "building"
+        assert events[0]["elapsed_seconds"] == 12.3
+        assert events[0]["message"] == "building... (12s)"
+
+    def test_status_change_event_with_minutes(self):
+        em = _Emitter(json_mode=True)
+        events = self._capture(lambda: em.status_change("deploying", 95.0))
+        assert events[0]["message"] == "deploying... (1m 35s)"
+
+    def test_log_event(self):
+        em = _Emitter(json_mode=True)
+        events = self._capture(lambda: em.log("some output"))
+        assert events[0] == {"event": "log", "message": "some output"}
+
+    def test_status_url_event(self):
+        em = _Emitter(json_mode=True)
+        events = self._capture(
+            lambda: em.status_url("https://smith.langchain.com/deploy/123")
+        )
+        assert events[0]["event"] == "status_url"
+        assert events[0]["url"] == "https://smith.langchain.com/deploy/123"
+
+    def test_result_event_full(self):
+        em = _Emitter(json_mode=True)
+        events = self._capture(
+            lambda: em.result(
+                "succeeded",
+                deployment_id="dep-1",
+                url="https://app.example.com",
+                status_url="https://smith.langchain.com/deploy/dep-1",
+            )
+        )
+        assert events[0]["event"] == "result"
+        assert events[0]["status"] == "succeeded"
+        assert events[0]["deployment_id"] == "dep-1"
+        assert events[0]["message"] == "Deployment successful!"
+        assert events[0]["url"] == "https://app.example.com"
+        assert events[0]["status_url"] == "https://smith.langchain.com/deploy/dep-1"
+
+    def test_result_event_minimal(self):
+        em = _Emitter(json_mode=True)
+        events = self._capture(lambda: em.result("failed", deployment_id="dep-2"))
+        assert events[0]["event"] == "result"
+        assert events[0]["status"] == "failed"
+        assert events[0]["message"] == "Deployment failed"
+        assert "url" not in events[0]
+        assert "status_url" not in events[0]
+
+    def test_heartbeat_event(self):
+        em = _Emitter(json_mode=True)
+        events = self._capture(lambda: em.heartbeat("building", 30.789))
+        assert events[0]["event"] == "heartbeat"
+        assert events[0]["elapsed_seconds"] == 30.8
+        assert events[0]["message"] == "building... (30s)"
+
+    def test_heartbeat_silent_in_text_mode(self, capsys):
+        em = _Emitter(json_mode=False)
+        em.heartbeat("building", 10.0)
+        captured = capsys.readouterr()
+        assert captured.out == ""
+
+    def test_upload_progress_event(self):
+        em = _Emitter(json_mode=True)
+        events = self._capture(lambda: em.upload_progress(5.678, 42))
+        assert events[0]["event"] == "upload_progress"
+        assert events[0]["size_mb"] == 5.7
+        assert events[0]["pct"] == 42
+
+
+# ---------------------------------------------------------------------------
+# _Emitter text mode (non-json)
+# ---------------------------------------------------------------------------
+
+
+class TestEmitterTextMode:
+    """Verify that _Emitter in text mode uses click.echo/click.secho."""
+
+    def test_step_writes_text(self, capsys):
+        em = _Emitter(json_mode=False)
+        em.step(1, "Hello")
+        captured = capsys.readouterr()
+        assert "1. Hello" in captured.out
+
+    def test_log_writes_text(self, capsys):
+        em = _Emitter(json_mode=False)
+        em.log("my line")
+        captured = capsys.readouterr()
+        assert "my line" in captured.out
+
+    def test_result_succeeded_text(self, capsys):
+        em = _Emitter(json_mode=False)
+        em.result("succeeded", deployment_id="d1", url="https://app.test")
+        captured = capsys.readouterr()
+        lines = [line.strip() for line in captured.out.splitlines() if line.strip()]
+        assert "Deployment successful!" in lines
+        assert "URL: https://app.test" in lines
+
+
+# ---------------------------------------------------------------------------
+# --no-input guard on _create_host_backend_client
+# ---------------------------------------------------------------------------
+
+
+class TestCreateHostBackendClientNoInput:
+    def test_raises_when_no_api_key_and_no_input(self, monkeypatch, tmp_path):
+        import langgraph_cli.deploy as deploy_mod
+
+        monkeypatch.setattr(deploy_mod, "_no_input", True)
+        monkeypatch.delenv("LANGSMITH_API_KEY", raising=False)
+        monkeypatch.delenv("LANGCHAIN_API_KEY", raising=False)
+        monkeypatch.delenv("LANGGRAPH_HOST_API_KEY", raising=False)
+
+        with pytest.raises(click.ClickException, match="API key"):
+            _create_host_backend_client(
+                host_url="https://api.example.com",
+                api_key=None,
+                env_vars={},
+            )
+
+    def test_succeeds_with_api_key_in_env(self, monkeypatch, tmp_path):
+        import langgraph_cli.deploy as deploy_mod
+
+        monkeypatch.setattr(deploy_mod, "_no_input", True)
+        monkeypatch.setenv("LANGSMITH_API_KEY", "lsv2_test")
+
+        client = _create_host_backend_client(
+            host_url="https://api.example.com",
+            api_key=None,
+            env_vars={},
+        )
+        assert client is not None
+
+
+class TestSmithDashboardBaseUrl:
+    def test_none_returns_default(self):
+        assert _smith_dashboard_base_url(None) == "https://smith.langchain.com"
+
+    def test_empty_returns_default(self):
+        assert _smith_dashboard_base_url("") == "https://smith.langchain.com"
+
+    def test_prod_host_url(self):
+        assert (
+            _smith_dashboard_base_url("https://api.host.langchain.com")
+            == "https://smith.langchain.com"
+        )
+
+    def test_dev_host_url(self):
+        assert (
+            _smith_dashboard_base_url("https://dev.api.host.langchain.com")
+            == "https://dev.smith.langchain.com"
+        )
+
+    def test_eu_host_url(self):
+        assert (
+            _smith_dashboard_base_url("https://eu.api.host.langchain.com")
+            == "https://eu.smith.langchain.com"
+        )
+
+    def test_staging_host_url(self):
+        assert (
+            _smith_dashboard_base_url("https://staging.api.host.langchain.com")
+            == "https://staging.smith.langchain.com"
+        )
+
+    def test_localhost(self):
+        assert (
+            _smith_dashboard_base_url("http://localhost:8080")
+            == "http://localhost:8080"
+        )
+
+    def test_localhost_trailing_slash(self):
+        assert (
+            _smith_dashboard_base_url("http://localhost:8080/")
+            == "http://localhost:8080"
+        )
+
+    def test_127_0_0_1(self):
+        assert (
+            _smith_dashboard_base_url("http://127.0.0.1:3000")
+            == "http://127.0.0.1:3000"
+        )
+
+    def test_unknown_domain_returns_default(self):
+        assert (
+            _smith_dashboard_base_url("https://custom.example.com")
+            == "https://smith.langchain.com"
+        )

libs/cli/uv.lock

@@ -2,7 +2,8 @@ version = 1
 revision = 3
 requires-python = ">=3.10"
 resolution-markers = [
-    "python_full_version >= '3.11'",
+    "python_full_version >= '3.15'",
+    "python_full_version >= '3.11' and python_full_version < '3.15'",
     "python_full_version < '3.11'",
 ]
 
@@ -362,14 +363,14 @@ wheels = [
 
 [[package]]
 name = "click"
-version = "8.3.2"
+version = "8.3.3"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "colorama", marker = "sys_platform == 'win32'" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/57/75/31212c6bf2503fdf920d87fee5d7a86a2e3bcf444984126f13d8e4016804/click-8.3.2.tar.gz", hash = "sha256:14162b8b3b3550a7d479eafa77dfd3c38d9dc8951f6f69c78913a8f9a7540fd5", size = 302856, upload-time = "2026-04-03T19:14:45.118Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/bb/63/f9e1ea081ce35720d8b92acde70daaedace594dc93b693c869e0d5910718/click-8.3.3.tar.gz", hash = "sha256:398329ad4837b2ff7cbe1dd166a4c0f8900c3ca3a218de04466f38f6497f18a2", size = 328061, upload-time = "2026-04-22T15:11:27.506Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/e4/20/71885d8b97d4f3dde17b1fdb92dbd4908b00541c5a3379787137285f602e/click-8.3.2-py3-none-any.whl", hash = "sha256:1924d2c27c5653561cd2cae4548d1406039cb79b858b747cfea24924bbc1616d", size = 108379, upload-time = "2026-04-03T19:14:43.505Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/44/c1221527f6a71a01ec6fbad7fa78f1d50dfa02217385cf0fa3eec7087d59/click-8.3.3-py3-none-any.whl", hash = "sha256:a2bf429bb3033c89fa4936ffb35d5cb471e3719e1f3c8a7c3fff0b8314305613", size = 110502, upload-time = "2026-04-22T15:11:25.044Z" },
 ]
 
 [[package]]
@@ -1358,7 +1359,7 @@ wheels = [
 
 [[package]]
 name = "mypy"
-version = "1.20.1"
+version = "1.20.2"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "librt", marker = "platform_python_implementation != 'PyPy'" },
@@ -1367,51 +1368,51 @@ dependencies = [
     { name = "tomli", marker = "python_full_version < '3.11'" },
     { name = "typing-extensions" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/0b/3d/5b373635b3146264eb7a68d09e5ca11c305bbb058dfffbb47c47daf4f632/mypy-1.20.1.tar.gz", hash = "sha256:6fc3f4ecd52de81648fed1945498bf42fa2993ddfad67c9056df36ae5757f804", size = 3815892, upload-time = "2026-04-13T02:46:51.474Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/04/af/e3d4b3e9ec91a0ff9aabfdb38692952acf49bbb899c2e4c29acb3a6da3ae/mypy-1.20.2.tar.gz", hash = "sha256:e8222c26daaafd9e8626dec58ae36029f82585890589576f769a650dd20fd665", size = 3817349, upload-time = "2026-04-21T17:12:28.473Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/21/4b/b1fa23297c8a5c403aabaac0649549efc5a0af7095f3dd33e7482863f973/mypy-1.20.1-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:3ba5d1e712ada9c3b6223dcbc5a31dac334ed62991e5caa17bcf5a4ddc349af0", size = 14426426, upload-time = "2026-04-13T02:46:37.828Z" },
-    { url = "https://files.pythonhosted.org/packages/22/53/82923480aee5507a46df22428316e28b2b710d08506a128b2acef81ab18e/mypy-1.20.1-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:2e731284c117b0987fb1e6c5013a56f33e7faa1fce594066ab83876183ce1c66", size = 13307651, upload-time = "2026-04-13T02:46:22.676Z" },
-    { url = "https://files.pythonhosted.org/packages/4e/0c/91905b393c790440fa273f0903ee2b07cce95bb6deccac87e6eb343d077a/mypy-1.20.1-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f8e945b872a05f4fbefabe2249c0b07b6b194e5e11a86ebee9edf855de09806c", size = 13746066, upload-time = "2026-04-13T02:45:15.345Z" },
-    { url = "https://files.pythonhosted.org/packages/88/b9/8a7017270438e34544e19dd6284cad54fd65dde3c35418a2ce07a1897804/mypy-1.20.1-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:2fc88acef0dc9b15246502b418980478c1bfc9702057a0e1e7598d01a7af8937", size = 14617944, upload-time = "2026-04-13T02:45:44.954Z" },
-    { url = "https://files.pythonhosted.org/packages/0c/cf/5a61ceec3fc133e0f559d1e1f9adf4150abdbc2ad8eb831ec26fc8459196/mypy-1.20.1-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:14911a115c73608f155f648b978c5055d16ff974e6b1b5512d7fedf4fa8b15c6", size = 14918205, upload-time = "2026-04-13T02:45:42.653Z" },
-    { url = "https://files.pythonhosted.org/packages/6f/80/afb1c665e9c426c78e4711cce04e446b645867bfb97936158886103c1648/mypy-1.20.1-cp310-cp310-win_amd64.whl", hash = "sha256:76d9b4c992cca3331d9793ef197ae360ea44953cf35beb2526e95b9e074f2866", size = 10823344, upload-time = "2026-04-13T02:46:07.607Z" },
-    { url = "https://files.pythonhosted.org/packages/11/68/7ad64b49b7663c88fef76a2ac689ea73e17804832ac4cb5416bcff17775b/mypy-1.20.1-cp310-cp310-win_arm64.whl", hash = "sha256:b408722f80be44845da555671a5ef3a0c63f51ca5752b0c20e992dc9c0fbd3cd", size = 9760694, upload-time = "2026-04-13T02:46:49.369Z" },
-    { url = "https://files.pythonhosted.org/packages/82/0d/555ab7453cc4a4a8643b7f21c842b1a84c36b15392061ae7b052ee119320/mypy-1.20.1-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:c01eb9bac2c6a962d00f9d23421cd2913840e65bba365167d057bd0b4171a92e", size = 14336012, upload-time = "2026-04-13T02:45:39.935Z" },
-    { url = "https://files.pythonhosted.org/packages/57/26/85a28893f7db8a16ebb41d1e9dfcb4475844d06a88480b6639e32a74d6ef/mypy-1.20.1-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:55d12ddbd8a9cac5b276878bd534fa39fff5bf543dc6ae18f25d30c8d7d27fca", size = 13224636, upload-time = "2026-04-13T02:45:49.659Z" },
-    { url = "https://files.pythonhosted.org/packages/93/41/bd4cd3c2caeb6c448b669222b8cfcbdee4a03b89431527b56fca9e56b6f3/mypy-1.20.1-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c0aa322c1468b6cdfc927a44ce130f79bb44bcd34eb4a009eb9f96571fd80955", size = 13663471, upload-time = "2026-04-13T02:46:20.276Z" },
-    { url = "https://files.pythonhosted.org/packages/3e/56/7ee8c471e10402d64b6517ae10434541baca053cffd81090e4097d5609d4/mypy-1.20.1-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:3f8bc95899cf676b6e2285779a08a998cc3a7b26f1026752df9d2741df3c79e8", size = 14532344, upload-time = "2026-04-13T02:46:44.205Z" },
-    { url = "https://files.pythonhosted.org/packages/b5/95/b37d1fa859a433f6156742e12f62b0bb75af658544fb6dada9363918743a/mypy-1.20.1-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:47c2b90191a870a04041e910277494b0d92f0711be9e524d45c074fe60c00b65", size = 14776670, upload-time = "2026-04-13T02:45:52.481Z" },
-    { url = "https://files.pythonhosted.org/packages/03/77/b302e4cb0b80d2bdf6bf4fce5864bb4cbfa461f7099cea544eaf2457df78/mypy-1.20.1-cp311-cp311-win_amd64.whl", hash = "sha256:9857dc8d2ec1a392ffbda518075beb00ac58859979c79f9e6bdcb7277082c2f2", size = 10816524, upload-time = "2026-04-13T02:45:37.711Z" },
-    { url = "https://files.pythonhosted.org/packages/7f/21/d969d7a68eb964993ebcc6170d5ecaf0cf65830c58ac3344562e16dc42a9/mypy-1.20.1-cp311-cp311-win_arm64.whl", hash = "sha256:09d8df92bb25b6065ab91b178da843dda67b33eb819321679a6e98a907ce0e10", size = 9750419, upload-time = "2026-04-13T02:45:08.542Z" },
-    { url = "https://files.pythonhosted.org/packages/69/1b/75a7c825a02781ca10bc2f2f12fba2af5202f6d6005aad8d2d1f264d8d78/mypy-1.20.1-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:36ee2b9c6599c230fea89bbd79f401f9f9f8e9fcf0c777827789b19b7da90f51", size = 14494077, upload-time = "2026-04-13T02:45:55.085Z" },
-    { url = "https://files.pythonhosted.org/packages/b0/54/5e5a569ea5c2b4d48b729fb32aa936eeb4246e4fc3e6f5b3d36a2dfbefb9/mypy-1.20.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:fba3fb0968a7b48806b0c90f38d39296f10766885a94c83bd21399de1e14eb28", size = 13319495, upload-time = "2026-04-13T02:45:29.674Z" },
-    { url = "https://files.pythonhosted.org/packages/6f/a4/a1945b19f33e91721b59deee3abb484f2fa5922adc33bb166daf5325d76d/mypy-1.20.1-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:ef1415a637cd3627d6304dfbeddbadd21079dafc2a8a753c477ce4fc0c2af54f", size = 13696948, upload-time = "2026-04-13T02:46:15.006Z" },
-    { url = "https://files.pythonhosted.org/packages/b2/c6/75e969781c2359b2f9c15b061f28ec6d67c8b61865ceda176e85c8e7f2de/mypy-1.20.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:ef3461b1ad5cd446e540016e90b5984657edda39f982f4cc45ca317b628f5a37", size = 14706744, upload-time = "2026-04-13T02:46:00.482Z" },
-    { url = "https://files.pythonhosted.org/packages/a8/6e/b221b1de981fc4262fe3e0bf9ec272d292dfe42394a689c2d49765c144c4/mypy-1.20.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:542dd63c9e1339b6092eb25bd515f3a32a1453aee8c9521d2ddb17dacd840237", size = 14949035, upload-time = "2026-04-13T02:45:06.021Z" },
-    { url = "https://files.pythonhosted.org/packages/ca/4b/298ba2de0aafc0da3ff2288da06884aae7ba6489bc247c933f87847c41b3/mypy-1.20.1-cp312-cp312-win_amd64.whl", hash = "sha256:1d55c7cd8ca22e31f93af2a01160a9e95465b5878de23dba7e48116052f20a8d", size = 10883216, upload-time = "2026-04-13T02:45:47.232Z" },
-    { url = "https://files.pythonhosted.org/packages/c7/f9/5e25b8f0b8cb92f080bfed9c21d3279b2a0b6a601cdca369a039ba84789d/mypy-1.20.1-cp312-cp312-win_arm64.whl", hash = "sha256:f5b84a79070586e0d353ee07b719d9d0a4aa7c8ee90c0ea97747e98cbe193019", size = 9814299, upload-time = "2026-04-13T02:45:21.934Z" },
-    { url = "https://files.pythonhosted.org/packages/21/e8/ef0991aa24c8f225df10b034f3c2681213cb54cf247623c6dec9a5744e70/mypy-1.20.1-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:8f3886c03e40afefd327bd70b3f634b39ea82e87f314edaa4d0cce4b927ddcc1", size = 14500739, upload-time = "2026-04-13T02:46:05.442Z" },
-    { url = "https://files.pythonhosted.org/packages/23/73/416ebec3047636ed89fa871dc8c54bf05e9e20aa9499da59790d7adb312d/mypy-1.20.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:e860eb3904f9764e83bafd70c8250bdffdc7dde6b82f486e8156348bf7ceb184", size = 13314735, upload-time = "2026-04-13T02:46:47.154Z" },
-    { url = "https://files.pythonhosted.org/packages/10/1e/1505022d9c9ac2e014a384eb17638fb37bf8e9d0a833ea60605b66f8f7ba/mypy-1.20.1-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:a4b5aac6e785719da51a84f5d09e9e843d473170a9045b1ea7ea1af86225df4b", size = 13704356, upload-time = "2026-04-13T02:45:19.773Z" },
-    { url = "https://files.pythonhosted.org/packages/98/91/275b01f5eba5c467a3318ec214dd865abb66e9c811231c8587287b92876a/mypy-1.20.1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:f37b6cd0fe2ad3a20f05ace48ca3523fc52ff86940e34937b439613b6854472e", size = 14696420, upload-time = "2026-04-13T02:45:24.205Z" },
-    { url = "https://files.pythonhosted.org/packages/a1/57/b3779e134e1b7250d05f874252780d0a88c068bc054bcff99ca20a3a2986/mypy-1.20.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:e4bbb0f6b54ce7cc350ef4a770650d15fa70edd99ad5267e227133eda9c94218", size = 14936093, upload-time = "2026-04-13T02:45:32.087Z" },
-    { url = "https://files.pythonhosted.org/packages/be/33/81b64991b0f3f278c3b55c335888794af190b2d59031a5ad1401bcb69f1e/mypy-1.20.1-cp313-cp313-win_amd64.whl", hash = "sha256:c3dc20f8ec76eecd77148cdd2f1542ed496e51e185713bf488a414f862deb8f2", size = 10889659, upload-time = "2026-04-13T02:46:02.926Z" },
-    { url = "https://files.pythonhosted.org/packages/1b/fd/7adcb8053572edf5ef8f3db59599dfeeee3be9cc4c8c97e2d28f66f42ac5/mypy-1.20.1-cp313-cp313-win_arm64.whl", hash = "sha256:a9d62bbac5d6d46718e2b0330b25e6264463ed832722b8f7d4440ff1be3ca895", size = 9815515, upload-time = "2026-04-13T02:46:32.103Z" },
-    { url = "https://files.pythonhosted.org/packages/40/cd/db831e84c81d57d4886d99feee14e372f64bbec6a9cb1a88a19e243f2ef5/mypy-1.20.1-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:12927b9c0ed794daedcf1dab055b6c613d9d5659ac511e8d936d96f19c087d12", size = 14483064, upload-time = "2026-04-13T02:45:26.901Z" },
-    { url = "https://files.pythonhosted.org/packages/d5/82/74e62e7097fa67da328ac8ece8de09133448c04d20ddeaeba251a3000f01/mypy-1.20.1-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:752507dd481e958b2c08fc966d3806c962af5a9433b5bf8f3bdd7175c20e34fe", size = 13335694, upload-time = "2026-04-13T02:46:12.514Z" },
-    { url = "https://files.pythonhosted.org/packages/74/c4/97e9a0abe4f3cdbbf4d079cb87a03b786efeccf5bf2b89fe4f96939ab2e6/mypy-1.20.1-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c614655b5a065e56274c6cbbe405f7cf7e96c0654db7ba39bc680238837f7b08", size = 13726365, upload-time = "2026-04-13T02:45:17.422Z" },
-    { url = "https://files.pythonhosted.org/packages/d7/aa/a19d884a8d28fcd3c065776323029f204dbc774e70ec9c85eba228b680de/mypy-1.20.1-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:2c3f6221a76f34d5100c6d35b3ef6b947054123c3f8d6938a4ba00b1308aa572", size = 14693472, upload-time = "2026-04-13T02:46:41.253Z" },
-    { url = "https://files.pythonhosted.org/packages/84/44/cc9324bd21cf786592b44bf3b5d224b3923c1230ec9898d508d00241d465/mypy-1.20.1-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:4bdfc06303ac06500af71ea0cdbe995c502b3c9ba32f3f8313523c137a25d1b6", size = 14919266, upload-time = "2026-04-13T02:46:28.37Z" },
-    { url = "https://files.pythonhosted.org/packages/6e/dc/779abb25a8c63e8f44bf5a336217fa92790fa17e0c40e0c725d10cb01bbd/mypy-1.20.1-cp314-cp314-win_amd64.whl", hash = "sha256:0131edd7eba289973d1ba1003d1a37c426b85cdef76650cd02da6420898a5eb3", size = 11049713, upload-time = "2026-04-13T02:45:57.673Z" },
-    { url = "https://files.pythonhosted.org/packages/28/08/4172be2ad7de9119b5a92ca36abbf641afdc5cb1ef4ae0c3a8182f29674f/mypy-1.20.1-cp314-cp314-win_arm64.whl", hash = "sha256:33f02904feb2c07e1fdf7909026206396c9deeb9e6f34d466b4cfedb0aadbbe4", size = 9999819, upload-time = "2026-04-13T02:46:35.039Z" },
-    { url = "https://files.pythonhosted.org/packages/2d/af/af9e46b0c8eabbce9fc04a477564170f47a1c22b308822282a59b7ff315f/mypy-1.20.1-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:168472149dd8cc505c98cefd21ad77e4257ed6022cd5ed2fe2999bed56977a5a", size = 15547508, upload-time = "2026-04-13T02:46:25.588Z" },
-    { url = "https://files.pythonhosted.org/packages/a7/cd/39c9e4ad6ba33e069e5837d772a9e6c304b4a5452a14a975d52b36444650/mypy-1.20.1-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:eb674600309a8f22790cca883a97c90299f948183ebb210fbef6bcee07cb1986", size = 14399557, upload-time = "2026-04-13T02:46:10.021Z" },
-    { url = "https://files.pythonhosted.org/packages/83/c1/3fd71bdc118ffc502bf57559c909927bb7e011f327f7bb8e0488e98a5870/mypy-1.20.1-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:ef2b2e4cc464ba9795459f2586923abd58a0055487cbe558cb538ea6e6bc142a", size = 15045789, upload-time = "2026-04-13T02:45:10.81Z" },
-    { url = "https://files.pythonhosted.org/packages/8e/73/6f07ff8b57a7d7b3e6e5bf34685d17632382395c8bb53364ec331661f83e/mypy-1.20.1-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:dee461d396dd46b3f0ed5a098dbc9b8860c81c46ad44fa071afcfbc149f167c9", size = 15850795, upload-time = "2026-04-13T02:45:03.349Z" },
-    { url = "https://files.pythonhosted.org/packages/ec/e2/f7dffec1c7767078f9e9adf0c786d1fe0ff30964a77eb213c09b8b58cb76/mypy-1.20.1-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:e364926308b3e66f1361f81a566fc1b2f8cd47fc8525e8136d4058a65a4b4f02", size = 16088539, upload-time = "2026-04-13T02:46:17.841Z" },
-    { url = "https://files.pythonhosted.org/packages/1a/76/e0dee71035316e75a69d73aec2f03c39c21c967b97e277fd0ef8fd6aec66/mypy-1.20.1-cp314-cp314t-win_amd64.whl", hash = "sha256:a0c17fbd746d38c70cbc42647cfd884f845a9708a4b160a8b4f7e70d41f4d7fa", size = 12575567, upload-time = "2026-04-13T02:45:34.795Z" },
-    { url = "https://files.pythonhosted.org/packages/22/a8/7ed43c9d9c3d1468f86605e323a5d97e411a448790a00f07e779f3211a46/mypy-1.20.1-cp314-cp314t-win_arm64.whl", hash = "sha256:db2cb89654626a912efda69c0d5c1d22d948265e2069010d3dde3abf751c7d08", size = 10378823, upload-time = "2026-04-13T02:45:13.35Z" },
-    { url = "https://files.pythonhosted.org/packages/d8/28/926bd972388e65a39ee98e188ccf67e81beb3aacfd5d6b310051772d974b/mypy-1.20.1-py3-none-any.whl", hash = "sha256:1aae28507f253fe82d883790d1c0a0d35798a810117c88184097fe8881052f06", size = 2636553, upload-time = "2026-04-13T02:46:30.45Z" },
+    { url = "https://files.pythonhosted.org/packages/76/97/ce2502df2cecf2ef997b6c6527c4a223b92feb9e7b790cdc8dcd683f3a8a/mypy-1.20.2-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:cf5a4db6dca263010e2c7bff081c89383c72d187ba2cf4c44759aac970e2f0c4", size = 14457059, upload-time = "2026-04-21T17:06:14.935Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/34/417ee60b822cc80c0f3dc9f495ad7fd8dbb8d8b2cf4baf22d4046d25d01d/mypy-1.20.2-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:7b0e817b518bff7facd7f85ea05b643ad8bdcce684cf29784987b0a7c8e1f997", size = 13346816, upload-time = "2026-04-21T17:10:41.433Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/85/e20951978702df58379d0bcc2e8f7ccdca4e78cd7dc66dd3ddbf9b29d517/mypy-1.20.2-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:97d7b9a485b40f8ca425460e89bf1da2814625b2da627c0dcc6aa46c92631d14", size = 13772593, upload-time = "2026-04-21T17:08:11.24Z" },
+    { url = "https://files.pythonhosted.org/packages/63/a5/5441a13259ec516c56fd5de0fd96a69a9590ae6c5e5d3e5174aa84b97973/mypy-1.20.2-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:1e1c12f6d2db3d78b909b5f77513c11eb7f2dd2782b96a3ab6dffc7d44575c99", size = 14656635, upload-time = "2026-04-21T17:09:54.042Z" },
+    { url = "https://files.pythonhosted.org/packages/3b/51/b89c69157c5e1f19fd125a65d991166a26906e7902f026f00feebbcfa2b9/mypy-1.20.2-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:89dce27e142d25ffbc154c1819383b69f2e9234dc4ed4766f42e0e8cb264ab5c", size = 14943278, upload-time = "2026-04-21T17:09:15.599Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/44/6b0eeecfe96d7cce1d71c66b8e03cb304aa70ec11f1955dc1d6b46aca3c3/mypy-1.20.2-cp310-cp310-win_amd64.whl", hash = "sha256:f376e37f9bf2a946872fc5fd1199c99310748e3c26c7a26683f13f8bdb756cbd", size = 10851915, upload-time = "2026-04-21T17:06:03.5Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/36/6593dc88545d75fb96416184be5392da5e2a8e8c2802a8597913e16ae25c/mypy-1.20.2-cp310-cp310-win_arm64.whl", hash = "sha256:6e2b469efd811707bc530fd1effef0f5d6eebcb7fe376affae69025da4b979a2", size = 9786676, upload-time = "2026-04-21T17:07:02.035Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/4d/9ebeae211caccbdaddde7ed5e31dfcf57faac66be9b11deb1dc6526c8078/mypy-1.20.2-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:4077797a273e56e8843d001e9dfe4ba10e33323d6ade647ff260e5cd97d9758c", size = 14371307, upload-time = "2026-04-21T17:08:56.442Z" },
+    { url = "https://files.pythonhosted.org/packages/95/d7/93473d34b61f04fac1aecc01368485c89c5c4af7a4b9a0cab5d77d04b63f/mypy-1.20.2-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:cdecf62abcc4292500d7858aeae87a1f8f1150f4c4dd08fb0b336ee79b2a6df3", size = 13258917, upload-time = "2026-04-21T17:05:50.978Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/30/3dd903e8bafb7b5f7bf87fcd58f8382086dea2aa19f0a7b357f21f63071b/mypy-1.20.2-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c566c3a88b6ece59b3d70f65bedef17304f48eb52ff040a6a18214e1917b3254", size = 13700516, upload-time = "2026-04-21T17:11:33.161Z" },
+    { url = "https://files.pythonhosted.org/packages/07/05/c61a140aba4c729ac7bc99ae26fc627c78a6e08f5b9dd319244ea71a3d7e/mypy-1.20.2-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0deb80d062b2479f2c87ae568f89845afc71d11bc41b04179e58165fd9f31e98", size = 14562889, upload-time = "2026-04-21T17:05:27.674Z" },
+    { url = "https://files.pythonhosted.org/packages/fd/87/da78243742ffa8a36d98c3010f0d829f93d5da4e6786f1a1a6f2ad616502/mypy-1.20.2-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:bba9ad231e92a3e424b3e56b65aa17704993425bba97e302c832f9466bb85bac", size = 14803844, upload-time = "2026-04-21T17:10:06.2Z" },
+    { url = "https://files.pythonhosted.org/packages/37/52/10a1ddf91b40f843943a3c6db51e2df59c9e237f29d355e95eaab427461f/mypy-1.20.2-cp311-cp311-win_amd64.whl", hash = "sha256:baf593f2765fa3a6b1ef95807dbaa3d25b594f6a52adcc506a6b9cb115e1be67", size = 10846300, upload-time = "2026-04-21T17:12:23.886Z" },
+    { url = "https://files.pythonhosted.org/packages/20/02/f9a4415b664c53bd34d6709be59da303abcae986dc4ac847b402edb6fa1e/mypy-1.20.2-cp311-cp311-win_arm64.whl", hash = "sha256:20175a1c0f49863946ec20b7f63255768058ac4f07d2b9ded6a6b46cfb5a9100", size = 9779498, upload-time = "2026-04-21T17:09:23.695Z" },
+    { url = "https://files.pythonhosted.org/packages/71/4e/7560e4528db9e9b147e4c0f22660466bf30a0a1fe3d63d1b9d3b0fd354ee/mypy-1.20.2-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:4dbfcf869f6b0517f70cf0030ba6ea1d6645e132337a7d5204a18d8d5636c02b", size = 14539393, upload-time = "2026-04-21T17:07:12.52Z" },
+    { url = "https://files.pythonhosted.org/packages/32/d9/34a5efed8124f5a9234f55ac6a4ced4201e2c5b81e1109c49ad23190ec8c/mypy-1.20.2-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:4b6481b228d072315b053210b01ac320e1be243dc17f9e5887ef167f23f5fae4", size = 13361642, upload-time = "2026-04-21T17:06:53.742Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/14/eb377acf78c03c92d566a1510cda8137348215b5335085ef662ab82ecd3a/mypy-1.20.2-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:34397cdced6b90b836e38182076049fdb41424322e0b0728c946b0939ebdf9f6", size = 13740347, upload-time = "2026-04-21T17:12:04.73Z" },
+    { url = "https://files.pythonhosted.org/packages/b9/94/7e4634a32b641aa1c112422eed1bbece61ee16205f674190e8b536f884de/mypy-1.20.2-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:a5da6976f20cae27059ea8d0c86e7cef3de720e04c4bb9ee18e3690fdb792066", size = 14734042, upload-time = "2026-04-21T17:07:43.16Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/f3/f7e62395cb7f434541b4491a01149a4439e28ace4c0c632bbf5431e92d1f/mypy-1.20.2-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:56908d7e08318d39f85b1f0c6cfd47b0cac1a130da677630dac0de3e0623e102", size = 14964958, upload-time = "2026-04-21T17:11:00.665Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/0d/47e3c3a0ec2a876e35aeac365df3cac7776c36bbd4ed18cc521e1b9d255b/mypy-1.20.2-cp312-cp312-win_amd64.whl", hash = "sha256:d52ad8d78522da1d308789df651ee5379088e77c76cb1994858d40a426b343b9", size = 10911340, upload-time = "2026-04-21T17:10:49.179Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/b2/6c852d72e0ea8b01f49da817fb52539993cde327e7d010e0103dc12d0dac/mypy-1.20.2-cp312-cp312-win_arm64.whl", hash = "sha256:785b08db19c9f214dc37d65f7c165d19a30fcecb48abfa30f31b01b5acaabb58", size = 9833947, upload-time = "2026-04-21T17:09:05.267Z" },
+    { url = "https://files.pythonhosted.org/packages/5b/c4/b93812d3a192c9bcf5df405bd2f30277cd0e48106a14d1023c7f6ed6e39b/mypy-1.20.2-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:edfbfca868cdd6bd8d974a60f8a3682f5565d3f5c99b327640cedd24c4264026", size = 14524670, upload-time = "2026-04-21T17:10:30.737Z" },
+    { url = "https://files.pythonhosted.org/packages/f3/47/42c122501bff18eaf1e8f457f5c017933452d8acdc52918a9f59f6812955/mypy-1.20.2-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:e2877a02380adfcdbc69071a0f74d6e9dbbf593c0dc9d174e1f223ffd5281943", size = 13336218, upload-time = "2026-04-21T17:08:44.069Z" },
+    { url = "https://files.pythonhosted.org/packages/92/8f/75bbc92f41725fbd585fb17b440b1119b576105df1013622983e18640a93/mypy-1.20.2-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:7488448de6007cd5177c6cea0517ac33b4c0f5ee9b5e9f2be51ce75511a85517", size = 13724906, upload-time = "2026-04-21T17:08:01.02Z" },
+    { url = "https://files.pythonhosted.org/packages/a1/32/4c49da27a606167391ff0c39aa955707a00edc500572e562f7c36c08a71f/mypy-1.20.2-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:bb9c2fa06887e21d6a3a868762acb82aec34e2c6fd0174064f27c93ede68ad15", size = 14726046, upload-time = "2026-04-21T17:11:22.354Z" },
+    { url = "https://files.pythonhosted.org/packages/7f/fc/4e354a1bd70216359deb0c9c54847ee6b32ef78dfb09f5131ff99b494078/mypy-1.20.2-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:9d56a78b646f2e3daa865bc70cd5ec5a46c50045801ca8ff17a0c43abc97e3ee", size = 14955587, upload-time = "2026-04-21T17:12:16.033Z" },
+    { url = "https://files.pythonhosted.org/packages/62/b2/c0f2056e9eb8f08c62cafd9715e4584b89132bdc832fcf85d27d07b5f3e5/mypy-1.20.2-cp313-cp313-win_amd64.whl", hash = "sha256:2a4102b03bb7481d9a91a6da8d174740c9c8c4401024684b9ca3b7cc5e49852f", size = 10922681, upload-time = "2026-04-21T17:06:35.842Z" },
+    { url = "https://files.pythonhosted.org/packages/e5/14/065e333721f05de8ef683d0aa804c23026bcc287446b61cac657b902ccac/mypy-1.20.2-cp313-cp313-win_arm64.whl", hash = "sha256:a95a9248b0c6fd933a442c03c3b113c3b61320086b88e2c444676d3fd1ca3330", size = 9830560, upload-time = "2026-04-21T17:07:51.023Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/d1/b4ec96b0ecc620a4443570c6e95c867903428cfcde4206518eafdd5880c3/mypy-1.20.2-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:419413398fe250aae057fd2fe50166b61077083c9b82754c341cf4fd73038f30", size = 14524561, upload-time = "2026-04-21T17:06:27.325Z" },
+    { url = "https://files.pythonhosted.org/packages/3a/63/d2c2ff4fa66bc49477d32dfa26e8a167ba803ea6a69c5efb416036909d30/mypy-1.20.2-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:e73c07f23009962885c197ccb9b41356a30cc0e5a1d0c2ea8fd8fb1362d7f924", size = 13363883, upload-time = "2026-04-21T17:11:11.239Z" },
+    { url = "https://files.pythonhosted.org/packages/2a/56/983916806bf4eddeaaa2c9230903c3669c6718552a921154e1c5182c701f/mypy-1.20.2-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0c64e5973df366b747646fc98da921f9d6eba9716d57d1db94a83c026a08e0fb", size = 13742945, upload-time = "2026-04-21T17:08:34.181Z" },
+    { url = "https://files.pythonhosted.org/packages/19/65/0cd9285ab010ee8214c83d67c6b49417c40d86ce46f1aa109457b5a9b8d7/mypy-1.20.2-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:5a65aa591af023864fd08a97da9974e919452cfe19cb146c8a5dc692626445dc", size = 14706163, upload-time = "2026-04-21T17:05:15.51Z" },
+    { url = "https://files.pythonhosted.org/packages/94/97/48ff3b297cafcc94d185243a9190836fb1b01c1b0918fff64e941e973cc9/mypy-1.20.2-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:4fef51b01e638974a6e69885687e9bd40c8d1e09a6cd291cca0619625cf1f558", size = 14938677, upload-time = "2026-04-21T17:05:39.562Z" },
+    { url = "https://files.pythonhosted.org/packages/fd/a1/1b4233d255bdd0b38a1f284feeb1c143ca508c19184964e22f8d837ec851/mypy-1.20.2-cp314-cp314-win_amd64.whl", hash = "sha256:913485a03f1bcf5d279409a9d2b9ed565c151f61c09f29991e5faa14033da4c8", size = 11089322, upload-time = "2026-04-21T17:06:44.29Z" },
+    { url = "https://files.pythonhosted.org/packages/78/c2/ce7ee2ba36aeb954ba50f18fa25d9c1188578654b97d02a66a15b6f09531/mypy-1.20.2-cp314-cp314-win_arm64.whl", hash = "sha256:c3bae4f855d965b5453784300c12ffc63a548304ac7f99e55d4dc7c898673aa3", size = 10017775, upload-time = "2026-04-21T17:07:20.732Z" },
+    { url = "https://files.pythonhosted.org/packages/4e/a1/9d93a7d0b5859af0ead82b4888b46df6c8797e1bc5e1e262a08518c6d48e/mypy-1.20.2-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:2de3dcea53babc1c3237a19002bc3d228ce1833278f093b8d619e06e7cc79609", size = 15549002, upload-time = "2026-04-21T17:08:23.107Z" },
+    { url = "https://files.pythonhosted.org/packages/00/d2/09a6a10ee1bf0008f6c144d9676f2ca6a12512151b4e0ad0ff6c4fac5337/mypy-1.20.2-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:52b176444e2e5054dfcbcb8c75b0b719865c96247b37407184bbfca5c353f2c2", size = 14401942, upload-time = "2026-04-21T17:07:31.837Z" },
+    { url = "https://files.pythonhosted.org/packages/57/da/9594b75c3c019e805250bed3583bdf4443ff9e6ef08f97e39ae308cb06f2/mypy-1.20.2-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:688c3312e5dadb573a2c69c82af3a298d43ecf9e6d264e0f95df960b5f6ac19c", size = 15041649, upload-time = "2026-04-21T17:09:34.653Z" },
+    { url = "https://files.pythonhosted.org/packages/97/77/f75a65c278e6e8eba2071f7f5a90481891053ecc39878cc444634d892abe/mypy-1.20.2-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:29752dbbf8cc53f89f6ac096d363314333045c257c9c75cbd189ca2de0455744", size = 15864588, upload-time = "2026-04-21T17:11:44.936Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/46/1a4e1c66e96c1a3246ddf5403d122ac9b0a8d2b7e65730b9d6533ba7a6d3/mypy-1.20.2-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:803203d2b6ea644982c644895c2f78b28d0e208bba7b27d9b921e0ec5eb207c6", size = 16093956, upload-time = "2026-04-21T17:10:17.683Z" },
+    { url = "https://files.pythonhosted.org/packages/5a/2c/78a8851264dec38cd736ca5b8bc9380674df0dd0be7792f538916157716c/mypy-1.20.2-cp314-cp314t-win_amd64.whl", hash = "sha256:9bcb8aa397ff0093c824182fd76a935a9ba7ad097fcbef80ae89bf6c1731d8ec", size = 12568661, upload-time = "2026-04-21T17:11:54.473Z" },
+    { url = "https://files.pythonhosted.org/packages/83/01/cd7318aa03493322ce275a0e14f4f52b8896335e4e79d4fb8153a7ad2b77/mypy-1.20.2-cp314-cp314t-win_arm64.whl", hash = "sha256:e061b58443f1736f8a37c48978d7ab581636d6ab03e3d4f99e3fa90463bb9382", size = 10389240, upload-time = "2026-04-21T17:09:42.719Z" },
+    { url = "https://files.pythonhosted.org/packages/28/9a/f23c163e25b11074188251b0b5a0342625fc1cdb6af604757174fa9acc9b/mypy-1.20.2-py3-none-any.whl", hash = "sha256:a94c5a76ab46c5e6257c7972b6c8cff0574201ca7dc05647e33e795d78680563", size = 2637314, upload-time = "2026-04-21T17:05:54.5Z" },
 ]
 
 [[package]]
@@ -1653,11 +1654,11 @@ wheels = [
 
 [[package]]
 name = "pathspec"
-version = "1.0.4"
+version = "1.1.1"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/fa/36/e27608899f9b8d4dff0617b2d9ab17ca5608956ca44461ac14ac48b44015/pathspec-1.0.4.tar.gz", hash = "sha256:0210e2ae8a21a9137c0d470578cb0e595af87edaa6ebf12ff176f14a02e0e645", size = 131200, upload-time = "2026-01-27T03:59:46.938Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/5a/82/42f767fc1c1143d6fd36efb827202a2d997a375e160a71eb2888a925aac1/pathspec-1.1.1.tar.gz", hash = "sha256:17db5ecd524104a120e173814c90367a96a98d07c45b2e10c2f3919fff91bf5a", size = 135180, upload-time = "2026-04-27T01:46:08.907Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/ef/3c/2c197d226f9ea224a9ab8d197933f9da0ae0aac5b6e0f884e2b8d9c8e9f7/pathspec-1.0.4-py3-none-any.whl", hash = "sha256:fb6ae2fd4e7c921a165808a552060e722767cfa526f99ca5156ed2ce45a5c723", size = 55206, upload-time = "2026-01-27T03:59:45.137Z" },
+    { url = "https://files.pythonhosted.org/packages/f1/d9/7fb5aa316bc299258e68c73ba3bddbc499654a07f151cba08f6153988714/pathspec-1.1.1-py3-none-any.whl", hash = "sha256:a00ce642f577bf7f473932318056212bc4f8bfdf53128c78bbd5af0b9b20b189", size = 57328, upload-time = "2026-04-27T01:46:07.06Z" },
 ]
 
 [[package]]
@@ -2086,27 +2087,27 @@ wheels = [
 
 [[package]]
 name = "ruff"
-version = "0.15.11"
+version = "0.15.12"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/e4/8d/192f3d7103816158dfd5ea50d098ef2aec19194e6cbccd4b3485bdb2eb2d/ruff-0.15.11.tar.gz", hash = "sha256:f092b21708bf0e7437ce9ada249dfe688ff9a0954fc94abab05dcea7dcd29c33", size = 4637264, upload-time = "2026-04-16T18:46:26.58Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/99/43/3291f1cc9106f4c63bdce7a8d0df5047fe8422a75b091c16b5e9355e0b11/ruff-0.15.12.tar.gz", hash = "sha256:ecea26adb26b4232c0c2ca19ccbc0083a68344180bba2a600605538ce51a40a6", size = 4643852, upload-time = "2026-04-24T18:17:14.305Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/02/1e/6aca3427f751295ab011828e15e9bf452200ac74484f1db4be0197b8170b/ruff-0.15.11-py3-none-linux_armv6l.whl", hash = "sha256:e927cfff503135c558eb581a0c9792264aae9507904eb27809cdcff2f2c847b7", size = 10607943, upload-time = "2026-04-16T18:46:05.967Z" },
-    { url = "https://files.pythonhosted.org/packages/e7/26/1341c262e74f36d4e84f3d6f4df0ac68cd53331a66bfc5080daa17c84c0b/ruff-0.15.11-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:7a1b5b2938d8f890b76084d4fa843604d787a912541eae85fd7e233398bbb73e", size = 10988592, upload-time = "2026-04-16T18:46:00.742Z" },
-    { url = "https://files.pythonhosted.org/packages/03/71/850b1d6ffa9564fbb6740429bad53df1094082fe515c8c1e74b6d8d05f18/ruff-0.15.11-py3-none-macosx_11_0_arm64.whl", hash = "sha256:d4176f3d194afbdaee6e41b9ccb1a2c287dba8700047df474abfbe773825d1cb", size = 10338501, upload-time = "2026-04-16T18:46:03.723Z" },
-    { url = "https://files.pythonhosted.org/packages/f2/11/cc1284d3e298c45a817a6aadb6c3e1d70b45c9b36d8d9cce3387b495a03a/ruff-0.15.11-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:3b17c886fb88203ced3afe7f14e8d5ae96e9d2f4ccc0ee66aa19f2c2675a27e4", size = 10670693, upload-time = "2026-04-16T18:46:41.941Z" },
-    { url = "https://files.pythonhosted.org/packages/ce/9e/f8288b034ab72b371513c13f9a41d9ba3effac54e24bfb467b007daee2ca/ruff-0.15.11-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:49fafa220220afe7758a487b048de4c8f9f767f37dfefad46b9dd06759d003eb", size = 10416177, upload-time = "2026-04-16T18:46:21.717Z" },
-    { url = "https://files.pythonhosted.org/packages/85/71/504d79abfd3d92532ba6bbe3d1c19fada03e494332a59e37c7c2dabae427/ruff-0.15.11-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:f2ab8427e74a00d93b8bda1307b1e60970d40f304af38bccb218e056c220120d", size = 11221886, upload-time = "2026-04-16T18:46:15.086Z" },
-    { url = "https://files.pythonhosted.org/packages/43/5a/947e6ab7a5ad603d65b474be15a4cbc6d29832db5d762cd142e4e3a74164/ruff-0.15.11-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:195072c0c8e1fc8f940652073df082e37a5d9cb43b4ab1e4d0566ab8977a13b7", size = 12075183, upload-time = "2026-04-16T18:46:07.944Z" },
-    { url = "https://files.pythonhosted.org/packages/9f/a1/0b7bb6268775fdd3a0818aee8efd8f5b4e231d24dd4d528ced2534023182/ruff-0.15.11-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:a3a0996d486af3920dec930a2e7daed4847dfc12649b537a9335585ada163e9e", size = 11516575, upload-time = "2026-04-16T18:46:31.687Z" },
-    { url = "https://files.pythonhosted.org/packages/30/c3/bb5168fc4d233cc06e95f482770d0f3c87945a0cd9f614b90ea8dc2f2833/ruff-0.15.11-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:1bef2cb556d509259f1fe440bb9cd33c756222cf0a7afe90d15edf0866702431", size = 11306537, upload-time = "2026-04-16T18:46:36.988Z" },
-    { url = "https://files.pythonhosted.org/packages/e4/92/4cfae6441f3967317946f3b788136eecf093729b94d6561f963ed810c82e/ruff-0.15.11-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:030d921a836d7d4a12cf6e8d984a88b66094ccb0e0f17ddd55067c331191bf19", size = 11296813, upload-time = "2026-04-16T18:46:24.182Z" },
-    { url = "https://files.pythonhosted.org/packages/43/26/972784c5dde8313acde8ac71ba8ac65475b85db4a2352a76c9934361f9bc/ruff-0.15.11-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:0e783b599b4577788dbbb66b9addcef87e9a8832f4ce0c19e34bf55543a2f890", size = 10633136, upload-time = "2026-04-16T18:46:39.802Z" },
-    { url = "https://files.pythonhosted.org/packages/5b/53/3985a4f185020c2f367f2e08a103032e12564829742a1b417980ce1514a0/ruff-0.15.11-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:ae90592246625ba4a34349d68ec28d4400d75182b71baa196ddb9f82db025ef5", size = 10424701, upload-time = "2026-04-16T18:46:10.381Z" },
-    { url = "https://files.pythonhosted.org/packages/d3/57/bf0dfb32241b56c83bb663a826133da4bf17f682ba8c096973065f6e6a68/ruff-0.15.11-py3-none-musllinux_1_2_i686.whl", hash = "sha256:1f111d62e3c983ed20e0ca2e800f8d77433a5b1161947df99a5c2a3fb60514f0", size = 10873887, upload-time = "2026-04-16T18:46:29.157Z" },
-    { url = "https://files.pythonhosted.org/packages/02/05/e48076b2a57dc33ee8c7a957296f97c744ca891a8ffb4ffb1aaa3b3f517d/ruff-0.15.11-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:06f483d6646f59eaffba9ae30956370d3a886625f511a3108994000480621d1c", size = 11404316, upload-time = "2026-04-16T18:46:19.462Z" },
-    { url = "https://files.pythonhosted.org/packages/88/27/0195d15fe7a897cbcba0904792c4b7c9fdd958456c3a17d2ea6093716a9a/ruff-0.15.11-py3-none-win32.whl", hash = "sha256:476a2aa56b7da0b73a3ee80b6b2f0e19cce544245479adde7baa65466664d5f3", size = 10655535, upload-time = "2026-04-16T18:46:12.47Z" },
-    { url = "https://files.pythonhosted.org/packages/3a/5e/c927b325bd4c1d3620211a4b96f47864633199feed60fa936025ab27e090/ruff-0.15.11-py3-none-win_amd64.whl", hash = "sha256:8b6756d88d7e234fb0c98c91511aae3cd519d5e3ed271cae31b20f39cb2a12a3", size = 11779692, upload-time = "2026-04-16T18:46:17.268Z" },
-    { url = "https://files.pythonhosted.org/packages/63/b6/aeadee5443e49baa2facd51131159fd6301cc4ccfc1541e4df7b021c37dd/ruff-0.15.11-py3-none-win_arm64.whl", hash = "sha256:063fed18cc1bbe0ee7393957284a6fe8b588c6a406a285af3ee3f46da2391ee4", size = 11032614, upload-time = "2026-04-16T18:46:34.487Z" },
+    { url = "https://files.pythonhosted.org/packages/c3/6e/e78ffb61d4686f3d96ba3df2c801161843746dcbcbb17a1e927d4829312b/ruff-0.15.12-py3-none-linux_armv6l.whl", hash = "sha256:f86f176e188e94d6bdbc09f09bfd9dc729059ad93d0e7390b5a73efe19f8861c", size = 10640713, upload-time = "2026-04-24T18:17:22.841Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/08/a317bc231fb9e7b93e4ef3089501e51922ff88d6936ce5cf870c4fe55419/ruff-0.15.12-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:e3bcd123364c3770b8e1b7baaf343cc99a35f197c5c6e8af79015c666c423a6c", size = 11069267, upload-time = "2026-04-24T18:17:30.105Z" },
+    { url = "https://files.pythonhosted.org/packages/aa/a4/f828e9718d3dce1f5f11c39c4f65afd32783c8b2aebb2e3d259e492c47bd/ruff-0.15.12-py3-none-macosx_11_0_arm64.whl", hash = "sha256:fe87510d000220aa1ed530d4448a7c696a0cae1213e5ec30e5874287b66557b5", size = 10397182, upload-time = "2026-04-24T18:17:07.177Z" },
+    { url = "https://files.pythonhosted.org/packages/71/e0/3310fc6d1b5e1fdea22bf3b1b807c7e187b581021b0d7d4514cccdb5fb71/ruff-0.15.12-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:84a1630093121375a3e2a95b4a6dc7b59e2b4ee76216e32d81aae550a832d002", size = 10758012, upload-time = "2026-04-24T18:16:55.759Z" },
+    { url = "https://files.pythonhosted.org/packages/11/c1/a606911aee04c324ddaa883ae418f3569792fd3c4a10c50e0dd0a2311e1e/ruff-0.15.12-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:fb129f40f114f089ebe0ca56c0d251cf2061b17651d464bb6478dc01e69f11f5", size = 10447479, upload-time = "2026-04-24T18:16:51.677Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/68/4201e8444f0894f21ab4aeeaee68aa4f10b51613514a20d80bd628d57e88/ruff-0.15.12-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:b0c862b172d695db7598426b8af465e7e9ac00a3ea2a3630ee67eb82e366aaa6", size = 11234040, upload-time = "2026-04-24T18:17:16.529Z" },
+    { url = "https://files.pythonhosted.org/packages/34/ff/8a6d6cf4ccc23fd67060874e832c18919d1557a0611ebef03fdb01fff11e/ruff-0.15.12-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:2849ea9f3484c3aca43a82f484210370319e7170df4dfe4843395ddf6c57bc33", size = 12087377, upload-time = "2026-04-24T18:17:04.944Z" },
+    { url = "https://files.pythonhosted.org/packages/85/f6/c669cf73f5152f623d34e69866a46d5e6185816b19fcd5b6dd8a2d299922/ruff-0.15.12-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:9e77c7e51c07fe396826d5969a5b846d9cd4c402535835fb6e21ce8b28fef847", size = 11367784, upload-time = "2026-04-24T18:17:25.409Z" },
+    { url = "https://files.pythonhosted.org/packages/e8/39/c61d193b8a1daaa8977f7dea9e8d8ba866e02ea7b65d32f6861693aa4c12/ruff-0.15.12-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:83b2f4f2f3b1026b5fb449b467d9264bf22067b600f7b6f41fc5958909f449d0", size = 11344088, upload-time = "2026-04-24T18:17:12.258Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/8d/49afab3645e31e12c590acb6d3b5b69d7aab5b81926dbaf7461f9441f37a/ruff-0.15.12-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:9ba3b8f1afd7e2e43d8943e55f249e13f9682fde09711644a6e7290eb4f3e339", size = 11271770, upload-time = "2026-04-24T18:17:02.457Z" },
+    { url = "https://files.pythonhosted.org/packages/46/06/33f41fe94403e2b755481cdfb9b7ef3e4e0ed031c4581124658d935d52b4/ruff-0.15.12-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:e852ba9fdc890655e1d78f2df1499efbe0e54126bd405362154a75e2bde159c5", size = 10719355, upload-time = "2026-04-24T18:17:27.648Z" },
+    { url = "https://files.pythonhosted.org/packages/0d/59/18aa4e014debbf559670e4048e39260a85c7fcee84acfd761ac01e7b8d35/ruff-0.15.12-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:dd8aed930da53780d22fc70bdf84452c843cf64f8cb4eb38984319c24c5cd5fd", size = 10462758, upload-time = "2026-04-24T18:17:32.347Z" },
+    { url = "https://files.pythonhosted.org/packages/25/e7/cc9f16fd0f3b5fddcbd7ec3d6ae30c8f3fde1047f32a4093a98d633c6570/ruff-0.15.12-py3-none-musllinux_1_2_i686.whl", hash = "sha256:01da3988d225628b709493d7dc67c3b9b12c0210016b08690ef9bd27970b262b", size = 10953498, upload-time = "2026-04-24T18:17:20.674Z" },
+    { url = "https://files.pythonhosted.org/packages/72/7a/a9ba7f98c7a575978698f4230c5e8cc54bbc761af34f560818f933dafa0c/ruff-0.15.12-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:9cae0f92bd5700d1213188b31cd3bdd2b315361296d10b96b8e2337d3d11f53e", size = 11447765, upload-time = "2026-04-24T18:17:09.755Z" },
+    { url = "https://files.pythonhosted.org/packages/ea/f9/0ae446942c846b8266059ad8a30702a35afae55f5cdc54c5adf8d7afdc27/ruff-0.15.12-py3-none-win32.whl", hash = "sha256:d0185894e038d7043ba8fd6aee7499ece6462dc0ea9f1e260c7451807c714c20", size = 10657277, upload-time = "2026-04-24T18:17:18.591Z" },
+    { url = "https://files.pythonhosted.org/packages/33/f1/9614e03e1cdcbf9437570b5400ced8a720b5db22b28d8e0f1bda429f660d/ruff-0.15.12-py3-none-win_amd64.whl", hash = "sha256:c87a162d61ab3adca47c03f7f717c68672edec7d1b5499e652331780fe74950d", size = 11837758, upload-time = "2026-04-24T18:17:00.113Z" },
+    { url = "https://files.pythonhosted.org/packages/c0/98/6beb4b351e472e5f4c4613f7c35a5290b8be2497e183825310c4c3a3984b/ruff-0.15.12-py3-none-win_arm64.whl", hash = "sha256:a538f7a82d061cee7be55542aca1d86d1393d55d81d4fcc314370f4340930d4f", size = 11120821, upload-time = "2026-04-24T18:16:57.979Z" },
 ]
 
 [[package]]

libs/langgraph/langgraph/_internal/_constants.py

@@ -12,6 +12,9 @@ RESUME = sys.intern("__resume__")
 # for values passed to resume a node after an interrupt
 ERROR = sys.intern("__error__")
 # for errors raised by nodes
+ERROR_SOURCE_NODE = sys.intern("__error_source_node__")
+# failed source node name for node-level error handlers
+# value format in pending writes: `(task_id, ERROR_SOURCE_NODE, node_name: str)`
 NO_WRITES = sys.intern("__no_writes__")
 # marker to signal node didn't write anything
 TASKS = sys.intern("__pregel_tasks")
@@ -71,6 +74,10 @@ CONFIG_KEY_RESUME_MAP = sys.intern("__pregel_resume_map")
 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 StreamingHandler only.
+CONFIG_KEY_NODE_ERROR = sys.intern("__pregel_node_error")
+# holds a `NodeError` (failed source node + exception) for the current
+# node-level error handler invocation, injected when handler signature
+# requests `error: NodeError`
 
 # --- Other constants ---
 PUSH = sys.intern("__pregel_push")
@@ -98,6 +105,7 @@ RESERVED = {
     INTERRUPT,
     RESUME,
     ERROR,
+    ERROR_SOURCE_NODE,
     NO_WRITES,
     # reserved config.configurable keys
     CONFIG_KEY_SEND,

libs/langgraph/langgraph/_internal/_runnable.py

@@ -51,9 +51,11 @@ from langgraph._internal._config import (
 )
 from langgraph._internal._constants import (
     CONF,
+    CONFIG_KEY_NODE_ERROR,
     CONFIG_KEY_RUNTIME,
 )
 from langgraph._internal._typing import MISSING
+from langgraph.errors import NodeError
 from langgraph.types import StreamWriter
 
 try:
@@ -194,6 +196,15 @@ KWARGS_CONFIG_KEYS: tuple[tuple[str, tuple[Any, ...], str, Any], ...] = (
         "N/A",
         inspect.Parameter.empty,
     ),
+    (
+        "error",
+        (NodeError, "NodeError"),
+        # we never hit this block, we read directly from configurable
+        "N/A",
+        # default to None so non-handler nodes that happen to type a parameter
+        # `error: NodeError` don't blow up; handlers always receive a NodeError.
+        None,
+    ),
 )
 """List of kwargs that can be passed to functions, and their corresponding
 config keys, default values and type annotations.
@@ -367,6 +378,8 @@ class RunnableCallable(Runnable):
             kw_value: Any = MISSING
             if kw == "config":
                 kw_value = config
+            elif kw == "error":
+                kw_value = config.get(CONF, {}).get(CONFIG_KEY_NODE_ERROR, MISSING)
             elif runtime:
                 if kw == "runtime":
                     kw_value = runtime
@@ -439,6 +452,8 @@ class RunnableCallable(Runnable):
             kw_value: Any = MISSING
             if kw == "config":
                 kw_value = config
+            elif kw == "error":
+                kw_value = config.get(CONF, {}).get(CONFIG_KEY_NODE_ERROR, MISSING)
             elif runtime:
                 if kw == "runtime":
                     kw_value = runtime

libs/langgraph/langgraph/channels/__init__.py

@@ -1,6 +1,7 @@
 from langgraph.channels.any_value import AnyValue
 from langgraph.channels.base import BaseChannel
 from langgraph.channels.binop import BinaryOperatorAggregate
+from langgraph.channels.delta import DeltaChannel
 from langgraph.channels.ephemeral_value import EphemeralValue
 from langgraph.channels.last_value import LastValue, LastValueAfterFinish
 from langgraph.channels.named_barrier_value import (
@@ -20,6 +21,7 @@ __all__ = (
     "UntrackedValue",
     "EphemeralValue",
     "BinaryOperatorAggregate",
+    "DeltaChannel",
     "NamedBarrierValue",
     "NamedBarrierValueAfterFinish",
     # topics

libs/langgraph/langgraph/channels/binop.py

@@ -22,10 +22,9 @@ __all__ = ("BinaryOperatorAggregate",)
 def _strip_extras(t):  # type: ignore[no-untyped-def]
     """Strips Annotated, Required and NotRequired from a given type."""
     if hasattr(t, "__origin__"):
+        if t.__origin__ in (Required, NotRequired):
+            return _strip_extras(t.__args__[0])
         return _strip_extras(t.__origin__)
-    if hasattr(t, "__origin__") and t.__origin__ in (Required, NotRequired):
-        return _strip_extras(t.__args__[0])
-
     return t
 
 
@@ -33,11 +32,22 @@ def _get_overwrite(value: Any) -> tuple[bool, Any]:
     """Inspects the given value and returns (is_overwrite, overwrite_value)."""
     if isinstance(value, Overwrite):
         return True, value.value
-    if isinstance(value, dict) and set(value.keys()) == {OVERWRITE}:
+    if isinstance(value, dict) and len(value) == 1 and OVERWRITE in value:
         return True, value[OVERWRITE]
     return False, None
 
 
+def _operators_equal(a: Callable, b: Callable) -> bool:
+    """Return True if two reducer operators should be considered equal.
+
+    Lambdas all share the name '<lambda>' so identity comparison is
+    unreliable; treat any pairing that includes a lambda as equal.
+    """
+    if a.__name__ == "<lambda>" or b.__name__ == "<lambda>":
+        return True
+    return a is b
+
+
 class BinaryOperatorAggregate(Generic[Value], BaseChannel[Value, Value, Value]):
     """Stores the result of applying a binary operator to the current value and each new value.
 
@@ -68,11 +78,8 @@ class BinaryOperatorAggregate(Generic[Value], BaseChannel[Value, Value, Value]):
             self.value = MISSING
 
     def __eq__(self, value: object) -> bool:
-        return isinstance(value, BinaryOperatorAggregate) and (
-            value.operator is self.operator
-            if value.operator.__name__ != "<lambda>"
-            and self.operator.__name__ != "<lambda>"
-            else True
+        return isinstance(value, BinaryOperatorAggregate) and _operators_equal(
+            self.operator, value.operator
         )
 
     @property

libs/langgraph/langgraph/channels/delta.py

@@ -0,0 +1,201 @@
+from __future__ import annotations
+
+import collections.abc
+import copy as _copy
+from collections.abc import Callable, Sequence
+from typing import Any, Generic
+
+from langgraph.checkpoint.base import PendingWrite
+from langgraph.checkpoint.serde.types import _DeltaSnapshot
+from typing_extensions import Self
+
+from langgraph._internal._typing import MISSING
+from langgraph.channels.base import BaseChannel, Value
+from langgraph.channels.binop import _get_overwrite, _operators_equal, _strip_extras
+from langgraph.errors import (
+    EmptyChannelError,
+    ErrorCode,
+    InvalidUpdateError,
+    create_error_message,
+)
+
+__all__ = ("DeltaChannel",)
+
+
+class DeltaChannel(Generic[Value], BaseChannel[Any, Any, Any]):
+    """Reducer channel that stores only a sentinel in checkpoint blobs and
+    reconstructs state by replaying ancestor writes through the reducer.
+
+    !!! warning "Beta"
+
+        `DeltaChannel` is in beta. The API and on-disk representation may
+        change in future releases. Threads written with `DeltaChannel` today
+        are expected to remain readable, but the surrounding contract
+        (`BaseCheckpointSaver.get_delta_channel_history`, the
+        `_DeltaSnapshot` blob shape, the `delta_updates_since_snapshot`
+        metadata field) is not yet stable.
+
+    The reducer receives the current accumulated value and a batch of writes
+    in one call: `reducer(state, [write1, write2, ...]) -> new_state`.
+
+    Reducers must be deterministic and batching-invariant (associative across
+    folds): applying two consecutive write batches separately must produce the
+    same state as applying their concatenation once:
+
+        reducer(reducer(state, xs), ys) == reducer(state, xs + ys)
+
+    This lets LangGraph replay checkpointed writes in larger batches than they
+    were originally produced without changing reconstructed state.
+
+    Snapshot cadence is driven by per-channel update count. `create_checkpoint`
+    writes a full `_DeltaSnapshot` blob every `snapshot_frequency` updates to
+    this channel, bounding replay depth.
+
+    Parameters:
+        reducer: `(state, list[writes]) -> new_state`. Must be deterministic
+            and batching-invariant as described above.
+        typ: The value type (e.g. `list`, `dict`). Inferred automatically
+            from the outer type when used inside `Annotated[T, DeltaChannel(...)]`.
+        snapshot_frequency: Every Nth update to this channel writes a snapshot
+            blob (default `1000`). Must be a positive int.
+    """
+
+    __slots__ = ("value", "reducer", "snapshot_frequency")
+    value: Value | Any
+
+    def __init__(
+        self,
+        reducer: Callable[[Any, Sequence[Any]], Any],
+        typ: type[Value] | None = None,
+        *,
+        snapshot_frequency: int = 1000,
+    ) -> None:
+        if snapshot_frequency <= 0:
+            raise ValueError(
+                f"snapshot_frequency must be a positive int, got {snapshot_frequency}"
+            )
+        if typ is None:
+            typ = list  # type: ignore[assignment]  # placeholder; overridden by _is_field_channel
+        super().__init__(typ)
+        self.reducer = reducer
+        self.snapshot_frequency = snapshot_frequency
+        typ = _strip_extras(typ)
+        if typ in (collections.abc.Sequence, collections.abc.MutableSequence):
+            typ = list
+        if typ in (collections.abc.Set, collections.abc.MutableSet):
+            typ = set
+        if typ in (collections.abc.Mapping, collections.abc.MutableMapping):
+            typ = dict
+        self.typ = typ
+        self.value: Any = MISSING
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, DeltaChannel):
+            return False
+        if self.snapshot_frequency != other.snapshot_frequency:
+            return False
+        return _operators_equal(self.reducer, other.reducer)
+
+    @property
+    def ValueType(self) -> Any:
+        return self.typ
+
+    @property
+    def UpdateType(self) -> Any:
+        return self.typ
+
+    def copy(self) -> Self:
+        new = self.__class__(
+            self.reducer, self.typ, snapshot_frequency=self.snapshot_frequency
+        )
+        new.key = self.key
+        new.value = self.value if self.value is MISSING else _copy.copy(self.value)
+        return new
+
+    def from_checkpoint(self, checkpoint: Any) -> Self:
+        """Initialize from a stored blob.
+
+        Blob types:
+          * `MISSING`: start empty; caller replays writes.
+          * `_DeltaSnapshot(value)`: restore value directly from snapshot.
+          * plain value (migration from old `BinaryOperatorAggregate` blobs):
+            use directly.
+        """
+        new = self.__class__(
+            self.reducer, self.typ, snapshot_frequency=self.snapshot_frequency
+        )
+        new.key = self.key
+        if checkpoint is MISSING:
+            new.value = self.typ()
+        elif isinstance(checkpoint, _DeltaSnapshot):
+            new.value = checkpoint.value
+        else:
+            new.value = checkpoint
+        return new
+
+    def replay_writes(self, writes: Sequence[PendingWrite]) -> None:
+        """Apply ancestor writes oldest-to-newest via a single reducer call.
+
+        If any write is an Overwrite, the last one in the sequence acts as
+        the reset point: its value becomes the new base and only writes
+        after it are passed to the reducer.
+        """
+        values = [v for _, _, v in writes]
+        if not values:
+            return
+        base = self.value
+        start = 0
+        for i, v in enumerate(values):
+            is_ow, ow_value = _get_overwrite(v)
+            if is_ow:
+                base = _copy.copy(ow_value) if ow_value is not None else self.typ()
+                start = i + 1
+        remaining = values[start:]
+        self.value = self.reducer(base, remaining) if remaining else base
+
+    def update(self, values: Sequence[Any]) -> bool:
+        if not values:
+            return False
+        overwrite_idx: int | None = None
+        for i, v in enumerate(values):
+            is_ow, _ = _get_overwrite(v)
+            if is_ow:
+                if overwrite_idx is not None:
+                    msg = create_error_message(
+                        message="Can receive only one Overwrite value per super-step.",
+                        error_code=ErrorCode.INVALID_CONCURRENT_GRAPH_UPDATE,
+                    )
+                    raise InvalidUpdateError(msg)
+                overwrite_idx = i
+        if overwrite_idx is not None:
+            _, overwrite_value = _get_overwrite(values[overwrite_idx])
+            base = (
+                _copy.copy(overwrite_value)
+                if overwrite_value is not None
+                else self.typ()
+            )
+            remaining = [v for i, v in enumerate(values) if i != overwrite_idx]
+            self.value = self.reducer(base, remaining) if remaining else base
+            return True
+        base = self.typ() if self.value is MISSING else self.value
+        self.value = self.reducer(base, list(values))
+        return True
+
+    def get(self) -> Any:
+        if self.value is MISSING:
+            raise EmptyChannelError()
+        return self.value
+
+    def is_available(self) -> bool:
+        return self.value is not MISSING
+
+    def checkpoint(self) -> Any:
+        """Return stored representation: always `MISSING`.
+
+        Snapshot decisions live in `create_checkpoint` (which has the channel
+        version) and write `_DeltaSnapshot(ch.get())` directly into
+        `channel_values`. For non-snapshot steps the channel does not appear
+        in `channel_values`; reconstruction walks ancestor writes via the
+        saver's `get_delta_channel_history`.
+        """
+        return MISSING

libs/langgraph/langgraph/errors.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from collections.abc import Sequence
+from dataclasses import dataclass
 from enum import Enum
 from typing import Any, Literal
 from warnings import warn
@@ -15,10 +16,12 @@ from langgraph.warnings import LangGraphDeprecatedSinceV10
 __all__ = (
     "EmptyChannelError",
     "ErrorCode",
+    "GraphDrained",
     "GraphRecursionError",
     "InvalidUpdateError",
     "GraphBubbleUp",
     "GraphInterrupt",
+    "NodeError",
     "NodeInterrupt",
     "NodeTimeoutError",
     "ParentCommand",
@@ -43,6 +46,23 @@ def create_error_message(*, message: str, error_code: ErrorCode) -> str:
     )
 
 
+class GraphBubbleUp(Exception):
+    pass
+
+
+class GraphDrained(GraphBubbleUp):
+    """Raised when a graph run exits early due to a drain request.
+
+    This indicates the graph stopped cooperatively at a superstep boundary
+    because `RunControl.request_drain()` was called (e.g., in response to
+    SIGTERM). The checkpoint is saved and the run can be resumed later.
+    """
+
+    def __init__(self, reason: str = "shutdown") -> None:
+        self.reason = reason
+        super().__init__(f"Graph drained: {reason}")
+
+
 class GraphRecursionError(RecursionError):
     """Raised when the graph has exhausted the maximum number of steps.
 
@@ -78,10 +98,6 @@ class InvalidUpdateError(Exception):
     pass
 
 
-class GraphBubbleUp(Exception):
-    pass
-
-
 class GraphInterrupt(GraphBubbleUp):
     """Raised when a subgraph is interrupted, suppressed by the root graph.
     Never raised directly, or surfaced to the user."""
@@ -128,12 +144,31 @@ class TaskNotFound(Exception):
     pass
 
 
-class NodeTimeoutError(TimeoutError):
+@dataclass(frozen=True, slots=True)
+class NodeError:
+    """Failure context passed to a node-level error handler.
+
+    Inject by adding a parameter typed `NodeError` to a handler registered via
+    `StateGraph.add_node(..., error_handler=...)`:
+
+    ```python
+    def handler(state: State, error: NodeError) -> Command:
+        return Command(update={"status": f"recovered from {error.node}: {error.error}"})
+    ```
+    """
+
+    node: str
+    """Name of the node whose execution failed."""
+
+    error: BaseException
+    """Exception raised by the failed node."""
+
+
+class NodeTimeoutError(Exception):
     """Raised when a node invocation exceeds one of its configured timeouts.
 
-    Subclasses the built-in `TimeoutError`, so existing `except TimeoutError`
-    handlers keep working. If the node has a `retry_policy` whose `retry_on`
-    permits `TimeoutError`, the attempt will be retried.
+    Does **not** inherit from the built-in `TimeoutError` (a subclass of
+    `OSError`) so that the default `RetryPolicy` treats it as retryable.
 
     Both `idle_timeout` and `run_timeout` reflect the configured policy at the
     time of the failure (each is `None` if not configured). `kind` and

libs/langgraph/langgraph/graph/_node.py

@@ -88,6 +88,8 @@ class StateNodeSpec(Generic[NodeInputT, ContextT]):
     input_schema: type[NodeInputT]
     retry_policy: RetryPolicy | Sequence[RetryPolicy] | None
     cache_policy: CachePolicy | None
+    is_error_handler: bool = False
+    error_handler_node: str | None = None
     ends: tuple[str, ...] | dict[str, str] | None = EMPTY_SEQ
     defer: bool = False
     timeout: TimeoutPolicy | None = None

libs/langgraph/langgraph/graph/message.py

@@ -244,6 +244,71 @@ def add_messages(
     return merged
 
 
+def _messages_delta_reducer(
+    state: list[AnyMessage], writes: list[list[AnyMessage]]
+) -> list[AnyMessage]:
+    """**Experimental.** Batch reducer for use with `DeltaChannel`.
+
+    Processes all writes in one pass — dedup by ID, `RemoveMessage`
+    tombstoning — without calling `add_messages`.
+
+    This reducer is batching-invariant, as required by `DeltaChannel`:
+    `reducer(reducer(state, xs), ys) == reducer(state, xs + ys)`.
+
+    Raw dict / string / tuple inputs are coerced to typed `BaseMessage`
+    objects so that HTTP-driven graphs work without a separate coercion
+    step. This is not full `add_messages` parity — `REMOVE_ALL_MESSAGES`,
+    unknown-id `RemoveMessage` errors, missing-id UUID assignment, and
+    `BaseMessageChunk` conversion are not handled here.
+
+    Example::
+
+        from typing import Annotated
+        from langgraph.channels.delta import DeltaChannel
+        from langgraph.graph.message import _messages_delta_reducer
+
+        class State(TypedDict):
+            messages: Annotated[list, DeltaChannel(_messages_delta_reducer)]
+    """
+
+    # Each write is either a list of message-likes or a single message-like
+    # (BaseMessage / dict / str / tuple). Only lists flatten; everything
+    # else is one message.
+    flat: list[Any] = []
+    for w in writes:
+        if isinstance(w, list):
+            flat.extend(w)
+        else:
+            flat.append(w)
+    # Steady state: the reducer's own output is already typed, so skip
+    # `convert_to_messages` on state when the first element is a BaseMessage.
+    # Only raw input (initial dicts, deserialized blobs) hits the slow path.
+    if state and isinstance(state[0], BaseMessage):
+        state_msgs = state
+    else:
+        state_msgs = cast("list[AnyMessage]", convert_to_messages(state))
+    msgs = cast("list[AnyMessage]", convert_to_messages(flat))
+
+    index: dict[str, int] = {
+        m.id: i for i, m in enumerate(state_msgs) if m.id is not None
+    }
+    result: list[AnyMessage | None] = list(state_msgs)
+    for msg in msgs:
+        mid = msg.id
+        if mid is None:
+            result.append(msg)
+        elif isinstance(msg, RemoveMessage):
+            if mid in index:
+                result[index[mid]] = None
+                del index[mid]
+        elif mid in index:
+            result[index[mid]] = msg
+        else:
+            index[mid] = len(result)
+            result.append(msg)
+    return [m for m in result if m is not None]
+
+
 @deprecated(
     "MessageGraph is deprecated in langgraph 1.0.0, to be removed in 2.0.0. Please use StateGraph with a `messages` key instead.",
     category=None,

libs/langgraph/langgraph/graph/state.py

@@ -50,6 +50,7 @@ from langgraph._internal._timeout import coerce_timeout_policy
 from langgraph._internal._typing import EMPTY_SEQ, MISSING, DeprecatedKwargs
 from langgraph.channels.base import BaseChannel
 from langgraph.channels.binop import BinaryOperatorAggregate
+from langgraph.channels.delta import DeltaChannel
 from langgraph.channels.ephemeral_value import EphemeralValue
 from langgraph.channels.last_value import LastValue, LastValueAfterFinish
 from langgraph.channels.named_barrier_value import (
@@ -302,6 +303,7 @@ class StateGraph(Generic[StateT, ContextT, InputT, OutputT]):
         input_schema: None = None,
         retry_policy: RetryPolicy | Sequence[RetryPolicy] | None = None,
         cache_policy: CachePolicy | None = None,
+        error_handler: StateNode[Any, ContextT] | None = None,
         destinations: dict[str, str] | tuple[str, ...] | None = None,
         timeout: float | timedelta | TimeoutPolicy | None = None,
         **kwargs: Unpack[DeprecatedKwargs],
@@ -370,6 +372,7 @@ class StateGraph(Generic[StateT, ContextT, InputT, OutputT]):
         input_schema: type[NodeInputT],
         retry_policy: RetryPolicy | Sequence[RetryPolicy] | None = None,
         cache_policy: CachePolicy | None = None,
+        error_handler: StateNode[Any, ContextT] | None = None,
         destinations: dict[str, str] | tuple[str, ...] | None = None,
         timeout: float | timedelta | TimeoutPolicy | None = None,
         **kwargs: Unpack[DeprecatedKwargs],
@@ -443,6 +446,7 @@ class StateGraph(Generic[StateT, ContextT, InputT, OutputT]):
         input_schema: None = None,
         retry_policy: RetryPolicy | Sequence[RetryPolicy] | None = None,
         cache_policy: CachePolicy | None = None,
+        error_handler: StateNode[Any, ContextT] | None = None,
         destinations: dict[str, str] | tuple[str, ...] | None = None,
         timeout: float | timedelta | TimeoutPolicy | None = None,
         **kwargs: Unpack[DeprecatedKwargs],
@@ -511,6 +515,7 @@ class StateGraph(Generic[StateT, ContextT, InputT, OutputT]):
         input_schema: type[NodeInputT],
         retry_policy: RetryPolicy | Sequence[RetryPolicy] | None = None,
         cache_policy: CachePolicy | None = None,
+        error_handler: StateNode[Any, ContextT] | None = None,
         destinations: dict[str, str] | tuple[str, ...] | None = None,
         timeout: float | timedelta | TimeoutPolicy | None = None,
         **kwargs: Unpack[DeprecatedKwargs],
@@ -586,6 +591,7 @@ class StateGraph(Generic[StateT, ContextT, InputT, OutputT]):
         input_schema: type[NodeInputT] | None = None,
         retry_policy: RetryPolicy | Sequence[RetryPolicy] | None = None,
         cache_policy: CachePolicy | None = None,
+        error_handler: StateNode[Any, ContextT] | None = None,
         destinations: dict[str, str] | tuple[str, ...] | None = None,
         timeout: float | timedelta | TimeoutPolicy | None = None,
         **kwargs: Unpack[DeprecatedKwargs],
@@ -606,6 +612,7 @@ class StateGraph(Generic[StateT, ContextT, InputT, OutputT]):
 
                 If a sequence is provided, the first matching policy will be applied.
             cache_policy: The cache policy for the node.
+            error_handler: Optional node-level error handler callable for this node.
             destinations: Destinations that indicate where a node can route to.
 
                 Useful for edgeless graphs with nodes that return `Command` objects.
@@ -765,6 +772,25 @@ class StateGraph(Generic[StateT, ContextT, InputT, OutputT]):
         if destinations is not None:
             ends = destinations
 
+        resolved_input_schema: type[Any] = (
+            input_schema or inferred_input_schema or self.state_schema
+        )
+        handler_node_name: str | None = None
+        if error_handler is not None:
+            handler_node_name = f"__error_handler__{node}"
+            if handler_node_name in self.nodes:
+                raise ValueError(
+                    f"Auto-generated error handler node `{handler_node_name}` already exists."
+                )
+            self.nodes[handler_node_name] = StateNodeSpec[Any, ContextT](
+                coerce_to_runnable(error_handler, name=handler_node_name, trace=False),  # type: ignore[arg-type]
+                metadata=None,
+                input_schema=resolved_input_schema,
+                retry_policy=None,
+                cache_policy=None,
+                is_error_handler=True,
+            )
+
         if input_schema is not None:
             self.nodes[node] = StateNodeSpec[NodeInputT, ContextT](
                 coerce_to_runnable(action, name=node, trace=False),  # type: ignore[arg-type]
@@ -772,6 +798,7 @@ class StateGraph(Generic[StateT, ContextT, InputT, OutputT]):
                 input_schema=input_schema,
                 retry_policy=retry_policy,
                 cache_policy=cache_policy,
+                error_handler_node=handler_node_name,
                 ends=ends,
                 defer=defer,
                 timeout=timeout,
@@ -783,6 +810,7 @@ class StateGraph(Generic[StateT, ContextT, InputT, OutputT]):
                 input_schema=inferred_input_schema,
                 retry_policy=retry_policy,
                 cache_policy=cache_policy,
+                error_handler_node=handler_node_name,
                 ends=ends,
                 defer=defer,
                 timeout=timeout,
@@ -794,6 +822,7 @@ class StateGraph(Generic[StateT, ContextT, InputT, OutputT]):
                 input_schema=self.state_schema,
                 retry_policy=retry_policy,
                 cache_policy=cache_policy,
+                error_handler_node=handler_node_name,
                 ends=ends,
                 defer=defer,
                 timeout=timeout,
@@ -1051,7 +1080,6 @@ class StateGraph(Generic[StateT, ContextT, InputT, OutputT]):
             for node in interrupt:
                 if node not in self.nodes:
                     raise ValueError(f"Interrupt node `{node}` not found")
-
         self.compiled = True
         return self
 
@@ -1100,7 +1128,7 @@ class StateGraph(Generic[StateT, ContextT, InputT, OutputT]):
             name: The name to use for the compiled graph.
             transformers: Optional sequence of `StreamTransformer` classes or
                 configured factories. Classes and factories are instantiated
-                per run whenever `stream_v2` / `astream_v2` is called and are
+                per run whenever `stream_events(version="v3")` / `astream_events(version="v3")` is called and are
                 propagated to subgraph scopes. Custom factories should follow
                 the standard `StreamTransformer` constructor shape by
                 accepting `scope` as their first argument. Appended after the
@@ -1110,6 +1138,7 @@ class StateGraph(Generic[StateT, ContextT, InputT, OutputT]):
             CompiledStateGraph: The compiled `StateGraph`.
         """
         checkpointer = ensure_valid_checkpointer(checkpointer)
+
         serde_allowlist: set[tuple[str, ...]] | None = None
         if _serde.STRICT_MSGPACK_ENABLED:
             schema_types: list[type[Any]] = [
@@ -1164,6 +1193,11 @@ class StateGraph(Generic[StateT, ContextT, InputT, OutputT]):
                 key for key, val in self.channels.items() if not is_managed_value(val)
             ]
         )
+        node_error_handler_map = {
+            node_name: spec.error_handler_node
+            for node_name, spec in self.nodes.items()
+            if spec.error_handler_node is not None
+        }
 
         compiled = CompiledStateGraph[StateT, ContextT, InputT, OutputT](
             builder=self,
@@ -1186,6 +1220,7 @@ class StateGraph(Generic[StateT, ContextT, InputT, OutputT]):
             debug=debug,
             store=store,
             cache=cache,
+            node_error_handler_map=node_error_handler_map,
             name=name or "LangGraph",
             stream_transformers=transformers,
         )
@@ -1360,6 +1395,8 @@ class CompiledStateGraph(
                 metadata=node.metadata,
                 retry_policy=node.retry_policy,
                 cache_policy=node.cache_policy,
+                is_error_handler=node.is_error_handler,
+                error_handler_node=node.error_handler_node,
                 bound=node.runnable,  # type: ignore[arg-type]
                 timeout=node.timeout,
             )
@@ -1697,6 +1734,20 @@ def _is_field_channel(typ: type[Any]) -> BaseChannel | None:
         # Search through all annotated medata to find channel annotations
         for item in meta:
             if isinstance(item, BaseChannel):
+                if isinstance(item, DeltaChannel) and hasattr(typ, "__origin__"):
+                    origin = typ.__origin__
+                    # Unwrap parameterized Required[X]/NotRequired[X] to X
+                    # (e.g. Annotated[NotRequired[dict[...]], ...]).
+                    if hasattr(origin, "__origin__") and origin.__origin__ in (
+                        Required,
+                        NotRequired,
+                    ):
+                        origin = origin.__args__[0]
+                    item = item.__class__(
+                        item.reducer,
+                        origin,
+                        snapshot_frequency=item.snapshot_frequency,
+                    )
                 return item
             elif isclass(item) and issubclass(item, BaseChannel):
                 # ex, Annotated[int, EphemeralValue, SomeOtherAnnotation]

libs/langgraph/langgraph/pregel/_algo.py

@@ -39,6 +39,7 @@ from langgraph._internal._constants import (
     CONFIG_KEY_CHECKPOINT_MAP,
     CONFIG_KEY_CHECKPOINT_NS,
     CONFIG_KEY_CHECKPOINTER,
+    CONFIG_KEY_NODE_ERROR,
     CONFIG_KEY_READ,
     CONFIG_KEY_RESUME_MAP,
     CONFIG_KEY_RUNTIME,
@@ -47,6 +48,7 @@ from langgraph._internal._constants import (
     CONFIG_KEY_TASK_ID,
     CONFIG_KEY_THREAD_ID,
     ERROR,
+    ERROR_SOURCE_NODE,
     INTERRUPT,
     NO_WRITES,
     NS_END,
@@ -66,6 +68,7 @@ from langgraph.channels.base import BaseChannel
 from langgraph.channels.topic import Topic
 from langgraph.channels.untracked_value import UntrackedValue
 from langgraph.constants import TAG_HIDDEN
+from langgraph.errors import NodeError
 from langgraph.managed.base import ManagedValueMapping
 from langgraph.pregel._call import get_runnable_for_task, identifier
 from langgraph.pregel._io import read_channels
@@ -292,7 +295,15 @@ def apply_writes(
     pending_writes_by_channel: dict[str, list[Any]] = defaultdict(list)
     for task in tasks:
         for chan, val in task.writes:
-            if chan in (NO_WRITES, PUSH, RESUME, INTERRUPT, RETURN, ERROR):
+            if chan in (
+                NO_WRITES,
+                PUSH,
+                RESUME,
+                INTERRUPT,
+                RETURN,
+                ERROR,
+                ERROR_SOURCE_NODE,
+            ):
                 pass
             elif chan in channels:
                 pending_writes_by_channel[chan].append(val)
@@ -750,6 +761,42 @@ def prepare_single_task(
                 return PregelTask(task_id, name, task_path[:3])
 
 
+def _coerce_pending_error(value: Any) -> BaseException:
+    if isinstance(value, BaseException):
+        return value
+    return Exception(str(value))
+
+
+def _read_errors_from_pending_writes(
+    pending_writes: list[PendingWrite],
+) -> list[BaseException]:
+    errors: list[BaseException] = []
+    for _, channel, value in pending_writes:
+        if channel == ERROR:
+            errors.append(_coerce_pending_error(value))
+    return errors
+
+
+def _read_error_for_task_id_from_pending_writes(
+    pending_writes: list[PendingWrite], task_id: str
+) -> BaseException | None:
+    for pending_task_id, channel, value in reversed(pending_writes):
+        if pending_task_id == task_id and channel == ERROR:
+            return _coerce_pending_error(value)
+    return None
+
+
+def _read_error_source_node_from_pending_writes(
+    pending_writes: list[PendingWrite], task_id: str
+) -> str | None:
+    for pending_task_id, channel, value in reversed(pending_writes):
+        if pending_task_id == task_id and channel == ERROR_SOURCE_NODE:
+            if isinstance(value, str):
+                return value
+            return str(value)
+    return None
+
+
 def prepare_push_task_functional(
     task_path: tuple[str, tuple, int, str, Call],
     # (PUSH, parent task path, idx of PUSH write, id of parent task, Call)
@@ -1060,6 +1107,147 @@ def prepare_push_task_send(
         return PregelTask(task_id, packet.node, translated_task_path)
 
 
+def prepare_node_error_handler_task(
+    failed_task: PregelExecutableTask,
+    *,
+    handler_node_name: str,
+    failed_error: BaseException,
+    checkpoint: Checkpoint,
+    pending_writes: list[PendingWrite],
+    processes: Mapping[str, PregelNode],
+    channels: Mapping[str, BaseChannel],
+    managed: ManagedValueMapping,
+    config: RunnableConfig,
+    step: int,
+    stop: int,
+    store: BaseStore | None = None,
+    checkpointer: BaseCheckpointSaver | None = None,
+    manager: None | ParentRunManager | AsyncParentRunManager = None,
+    cache_policy: CachePolicy | None = None,
+    retry_policy: Sequence[RetryPolicy] = (),
+) -> PregelExecutableTask | None:
+    """Prepare an immediate node-level error handler task for a failed task."""
+    if handler_node_name not in processes:
+        return None
+    proc = processes[handler_node_name]
+    proc_node = proc.node
+    if proc_node is None:
+        return None
+
+    checkpoint_id_bytes = binascii.unhexlify(checkpoint["id"].replace("-", ""))
+    task_id_func = _xxhash_str if checkpoint["v"] > 1 else _uuid5_str
+    configurable = config.get(CONF, {})
+    parent_ns = configurable.get(CONFIG_KEY_CHECKPOINT_NS, "")
+    checkpoint_ns = (
+        f"{parent_ns}{NS_SEP}{handler_node_name}" if parent_ns else handler_node_name
+    )
+    task_id = task_id_func(
+        checkpoint_id_bytes,
+        checkpoint_ns,
+        str(step),
+        handler_node_name,
+        PUSH,
+        "node_error_handler",
+        failed_task.id,
+    )
+    task_checkpoint_ns = f"{checkpoint_ns}:{task_id}"
+    translated_task_path = (*failed_task.path[:3], "node_error_handler", False)
+    metadata = {
+        "langgraph_step": step,
+        "langgraph_node": handler_node_name,
+        "langgraph_triggers": PUSH_TRIGGER,
+        "langgraph_path": translated_task_path,
+        "langgraph_checkpoint_ns": task_checkpoint_ns,
+    }
+    if proc.metadata:
+        metadata.update(proc.metadata)
+    writes: deque[tuple[str, Any]] = deque()
+
+    effective_retry_policy = proc.retry_policy or retry_policy
+    effective_cache_policy = proc.cache_policy or cache_policy
+    if effective_cache_policy:
+        args_key = effective_cache_policy.key_func(failed_task.input)
+        cache_key = CacheKey(
+            (
+                CACHE_NS_WRITES,
+                (identifier(proc) or "__dynamic__"),
+                handler_node_name,
+            ),
+            xxh3_128_hexdigest(
+                args_key.encode() if isinstance(args_key, str) else args_key
+            ),
+            effective_cache_policy.ttl,
+        )
+    else:
+        cache_key = None
+
+    scratchpad = _scratchpad(
+        config[CONF].get(CONFIG_KEY_SCRATCHPAD),
+        pending_writes,
+        task_id,
+        xxh3_128_hexdigest(task_checkpoint_ns.encode()),
+        config[CONF].get(CONFIG_KEY_RESUME_MAP),
+        step,
+        stop,
+    )
+    runtime = cast(Runtime, configurable.get(CONFIG_KEY_RUNTIME, DEFAULT_RUNTIME))
+    runtime = runtime.override(
+        store=store, previous=checkpoint["channel_values"].get(PREVIOUS, None)
+    )
+    additional_config: RunnableConfig = {
+        "metadata": metadata,
+        "tags": proc.tags,
+    }
+    return PregelExecutableTask(
+        handler_node_name,
+        failed_task.input,
+        proc_node,
+        writes,
+        patch_config(
+            merge_configs(config, additional_config),
+            run_name=handler_node_name,
+            callbacks=manager.get_child(f"graph:step:{step}") if manager else None,
+            configurable={
+                CONFIG_KEY_TASK_ID: task_id,
+                CONFIG_KEY_SEND: writes.extend,
+                CONFIG_KEY_READ: partial(
+                    local_read,
+                    scratchpad,
+                    channels,
+                    managed,
+                    PregelTaskWrites(
+                        translated_task_path,
+                        handler_node_name,
+                        writes,
+                        PUSH_TRIGGER,
+                    ),
+                ),
+                CONFIG_KEY_CHECKPOINTER: (
+                    checkpointer or configurable.get(CONFIG_KEY_CHECKPOINTER)
+                ),
+                CONFIG_KEY_CHECKPOINT_MAP: {
+                    **configurable.get(CONFIG_KEY_CHECKPOINT_MAP, {}),
+                    parent_ns: checkpoint["id"],
+                },
+                CONFIG_KEY_CHECKPOINT_ID: None,
+                CONFIG_KEY_CHECKPOINT_NS: task_checkpoint_ns,
+                CONFIG_KEY_SCRATCHPAD: scratchpad,
+                CONFIG_KEY_RUNTIME: runtime,
+                CONFIG_KEY_NODE_ERROR: NodeError(
+                    node=failed_task.name, error=failed_error
+                ),
+            },
+        ),
+        PUSH_TRIGGER,
+        effective_retry_policy,
+        cache_key,
+        task_id,
+        translated_task_path,
+        writers=proc.flat_writers,
+        subgraphs=proc.subgraphs,
+    )
+
+
 def checkpoint_null_version(
     checkpoint: Checkpoint,
 ) -> V | None:

libs/langgraph/langgraph/pregel/_checkpoint.py

@@ -1,17 +1,27 @@
 from __future__ import annotations
 
-from collections.abc import Mapping
+from collections.abc import Callable, Mapping
 from datetime import datetime, timezone
+from typing import Any, cast
 
-from langgraph.checkpoint.base import Checkpoint
+from langchain_core.runnables import RunnableConfig
+from langgraph.checkpoint.base import (
+    BaseCheckpointSaver,
+    Checkpoint,
+    CheckpointMetadata,
+)
 from langgraph.checkpoint.base.id import uuid6
+from langgraph.checkpoint.serde.types import _DeltaSnapshot
 
 from langgraph._internal._typing import MISSING
 from langgraph.channels.base import BaseChannel
+from langgraph.channels.delta import DeltaChannel
 from langgraph.managed.base import ManagedValueMapping, ManagedValueSpec
 
 LATEST_VERSION = 4
 
+GetNextVersion = Callable[[Any, None], Any]
+
 
 def empty_checkpoint() -> Checkpoint:
     return Checkpoint(
@@ -24,6 +34,25 @@ def empty_checkpoint() -> Checkpoint:
     )
 
 
+def delta_channels_to_snapshot(
+    channels: Mapping[str, BaseChannel],
+    counts: Mapping[str, int],
+) -> set[str]:
+    """Return the set of DeltaChannel names that should snapshot now.
+
+    A channel snapshots when its accumulated update count (since the last
+    snapshot) reaches or exceeds `snapshot_frequency`. This is a pure
+    predicate — no mutation.
+    """
+    return {
+        name
+        for name, ch in channels.items()
+        if isinstance(ch, DeltaChannel)
+        and ch.is_available()
+        and counts.get(name, 0) >= ch.snapshot_frequency
+    }
+
+
 def create_checkpoint(
     checkpoint: Checkpoint,
     channels: Mapping[str, BaseChannel] | None,
@@ -31,35 +60,91 @@ def create_checkpoint(
     *,
     id: str | None = None,
     updated_channels: set[str] | None = None,
+    get_next_version: GetNextVersion | None = None,
+    channels_to_snapshot: set[str] | None = None,
 ) -> Checkpoint:
-    """Create a checkpoint for the given channels."""
+    """Build a new Checkpoint from the previous one and live channel state.
+
+    For each name in `channels_to_snapshot`, a `_DeltaSnapshot(value)` blob
+    is written into `channel_values[k]`. Other delta channels are omitted
+    from `channel_values` — the ancestor walk reconstructs their state
+    from `checkpoint_writes`. Callers compute the set via
+    `delta_channels_to_snapshot(channels, counts)`; defaults to empty
+    (no snapshots) when not provided.
+    """
     ts = datetime.now(timezone.utc).isoformat()
+    channels_to_snapshot = channels_to_snapshot or set()
     if channels is None:
         values = checkpoint["channel_values"]
+        channel_versions = checkpoint["channel_versions"]
     else:
         values = {}
+        channel_versions = dict(checkpoint["channel_versions"])
         for k in channels:
-            if k not in checkpoint["channel_versions"]:
+            if k not in channel_versions:
                 continue
-            v = channels[k].checkpoint()
-            if v is not MISSING:
-                values[k] = v
+            ch = channels[k]
+            if k in channels_to_snapshot:
+                # In exit mode, the snapshot decision is deferred to exit
+                # time (intermediate steps have do_checkpoint=False). The
+                # channel's count may have reached snapshot_frequency over
+                # several supersteps, but the LAST superstep may not have
+                # written to this channel. In that case apply_writes()
+                # (in _algo.py) didn't bump this channel's version, so
+                # saver.put() wouldn't include it in new_versions and
+                # the snapshot blob would be silently dropped. The manual
+                # bump below closes the gap. In sync/async durability this
+                # branch is effectively dead code (the step that pushes
+                # the count to freq always writes the channel).
+                if get_next_version is not None and (
+                    updated_channels is None or k not in updated_channels
+                ):
+                    channel_versions[k] = get_next_version(channel_versions[k], None)
+                values[k] = _DeltaSnapshot(ch.get())
+            else:
+                v = ch.checkpoint()
+                if v is not MISSING:
+                    values[k] = v
     return Checkpoint(
         v=LATEST_VERSION,
         ts=ts,
         id=id or str(uuid6(clock_seq=step)),
         channel_values=values,
-        channel_versions=checkpoint["channel_versions"],
+        channel_versions=channel_versions,
         versions_seen=checkpoint["versions_seen"],
         updated_channels=None if updated_channels is None else sorted(updated_channels),
     )
 
 
+def _needs_replay(spec: BaseChannel, stored: object) -> bool:
+    """True if `spec` is a `DeltaChannel` and no value is stored at this
+    checkpoint, requiring an ancestor walk to reconstruct.
+
+    `_DeltaSnapshot` blobs and plain values (migration) resolve directly via
+    `from_checkpoint` — only absence (`MISSING`) triggers replay.
+    """
+    if not isinstance(spec, DeltaChannel):
+        return False
+    return stored is MISSING
+
+
 def channels_from_checkpoint(
     specs: Mapping[str, BaseChannel | ManagedValueSpec],
     checkpoint: Checkpoint,
+    *,
+    saver: BaseCheckpointSaver | None = None,
+    config: RunnableConfig | None = None,
 ) -> tuple[Mapping[str, BaseChannel], ManagedValueMapping]:
-    """Get channels from a checkpoint."""
+    """Hydrate channels from a checkpoint.
+
+    For most channels, `spec.from_checkpoint(checkpoint["channel_values"][k])`
+    is sufficient. `DeltaChannel` is the exception: when the channel is
+    absent from `channel_values`, an ancestor walk via
+    `saver.get_delta_channel_history` is required to find the nearest seed
+    (`_DeltaSnapshot` blob or pre-migration plain value) and accumulate
+    the writes between it and the target. All delta channels needing
+    replay are batched into a single saver call.
+    """
     channel_specs: dict[str, BaseChannel] = {}
     managed_specs: dict[str, ManagedValueSpec] = {}
     for k, v in specs.items():
@@ -67,13 +152,73 @@ def channels_from_checkpoint(
             channel_specs[k] = v
         else:
             managed_specs[k] = v
-    return (
-        {
-            k: v.from_checkpoint(checkpoint["channel_values"].get(k, MISSING))
-            for k, v in channel_specs.items()
-        },
-        managed_specs,
-    )
+
+    delta_channels: list[str] = [
+        k
+        for k, spec in channel_specs.items()
+        if _needs_replay(spec, checkpoint["channel_values"].get(k, MISSING))
+    ]
+    histories: Mapping[str, Any] = {}
+    if delta_channels and saver is not None and config is not None:
+        histories = saver.get_delta_channel_history(
+            config=config, channels=delta_channels
+        )
+
+    channels: dict[str, BaseChannel] = {}
+    for k, spec in channel_specs.items():
+        ch: BaseChannel
+        if k in histories:
+            delta_spec = cast(DeltaChannel, spec)
+            history = histories[k]
+            replay_ch = delta_spec.from_checkpoint(history.get("seed", MISSING))
+            replay_ch.replay_writes(history["writes"])
+            ch = replay_ch
+        else:
+            ch = spec.from_checkpoint(checkpoint["channel_values"].get(k, MISSING))
+        channels[k] = ch
+    return channels, managed_specs
+
+
+async def achannels_from_checkpoint(
+    specs: Mapping[str, BaseChannel | ManagedValueSpec],
+    checkpoint: Checkpoint,
+    *,
+    saver: BaseCheckpointSaver | None = None,
+    config: RunnableConfig | None = None,
+) -> tuple[Mapping[str, BaseChannel], ManagedValueMapping]:
+    """Async version of `channels_from_checkpoint`. See docstring there."""
+    channel_specs: dict[str, BaseChannel] = {}
+    managed_specs: dict[str, ManagedValueSpec] = {}
+    for k, v in specs.items():
+        if isinstance(v, BaseChannel):
+            channel_specs[k] = v
+        else:
+            managed_specs[k] = v
+
+    delta_channels: list[str] = [
+        k
+        for k, spec in channel_specs.items()
+        if _needs_replay(spec, checkpoint["channel_values"].get(k, MISSING))
+    ]
+    histories: Mapping[str, Any] = {}
+    if delta_channels and saver is not None and config is not None:
+        histories = await saver.aget_delta_channel_history(
+            config=config, channels=delta_channels
+        )
+
+    channels: dict[str, BaseChannel] = {}
+    for k, spec in channel_specs.items():
+        ch: BaseChannel
+        if k in histories:
+            delta_spec = cast(DeltaChannel, spec)
+            history = histories[k]
+            replay_ch = delta_spec.from_checkpoint(history.get("seed", MISSING))
+            replay_ch.replay_writes(history["writes"])
+            ch = replay_ch
+        else:
+            ch = spec.from_checkpoint(checkpoint["channel_values"].get(k, MISSING))
+        channels[k] = ch
+    return channels, managed_specs
 
 
 def copy_checkpoint(checkpoint: Checkpoint) -> Checkpoint:
@@ -86,3 +231,17 @@ def copy_checkpoint(checkpoint: Checkpoint) -> Checkpoint:
         versions_seen={k: v.copy() for k, v in checkpoint["versions_seen"].items()},
         updated_channels=checkpoint.get("updated_channels", None),
     )
+
+
+def read_delta_updates_since_snapshot(
+    metadata: CheckpointMetadata | None,
+) -> dict[str, int]:
+    """Read the per-channel update counter from checkpoint metadata.
+
+    Returns an empty dict for missing/None metadata; the dict is
+    `total=False` on `CheckpointMetadata`, so absence means "no prior
+    delta-channel activity tracked."
+    """
+    if not metadata:
+        return {}
+    return dict(metadata.get("delta_updates_since_snapshot", {}) or {})

libs/langgraph/langgraph/pregel/_loop.py

@@ -45,11 +45,13 @@ from langgraph._internal._constants import (
     CONFIG_KEY_REPLAY_STATE,
     CONFIG_KEY_RESUME_MAP,
     CONFIG_KEY_RESUMING,
+    CONFIG_KEY_RUNTIME,
     CONFIG_KEY_SCRATCHPAD,
     CONFIG_KEY_STREAM,
     CONFIG_KEY_TASK_ID,
     CONFIG_KEY_THREAD_ID,
     ERROR,
+    ERROR_SOURCE_NODE,
     INPUT,
     INTERRUPT,
     NS_END,
@@ -68,6 +70,7 @@ from langgraph.callbacks import (
     GraphResumeEvent,
 )
 from langgraph.channels.base import BaseChannel
+from langgraph.channels.delta import DeltaChannel
 from langgraph.channels.untracked_value import UntrackedValue
 from langgraph.constants import TAG_HIDDEN
 from langgraph.errors import (
@@ -86,15 +89,18 @@ from langgraph.pregel._algo import (
     checkpoint_null_version,
     increment,
     prepare_next_tasks,
+    prepare_node_error_handler_task,
     prepare_single_task,
     sanitize_untracked_values_in_send,
     should_interrupt,
     task_path_str,
 )
 from langgraph.pregel._checkpoint import (
+    achannels_from_checkpoint,
     channels_from_checkpoint,
     copy_checkpoint,
     create_checkpoint,
+    delta_channels_to_snapshot,
     empty_checkpoint,
 )
 from langgraph.pregel._executor import (
@@ -117,6 +123,7 @@ from langgraph.pregel.debug import (
     map_debug_tasks,
 )
 from langgraph.pregel.protocol import StreamChunk, StreamProtocol
+from langgraph.runtime import RunControl, Runtime
 from langgraph.types import (
     All,
     CachePolicy,
@@ -188,6 +195,40 @@ class PregelLoop:
     _migrate_checkpoint: Callable[[Checkpoint], None] | None
     submit: Submit
     channels: Mapping[str, BaseChannel]
+    # Futures from `checkpointer.put_writes` calls that produced delta-channel
+    # writes. `_checkpointer_put_after_previous` drains this list (swap to a
+    # local `futs` then reset to `[]` and wait/gather) before putting the
+    # next checkpoint, so a checkpoint never becomes durable before the
+    # writes that produced it. Initialised to `[]` in both sync and async
+    # `__enter__`; stays `None` only when no checkpointer.
+    _delta_write_futs: list[Any] | None = None
+
+    # Exit-mode accumulator: every delta-channel write produced during this
+    # run (input writes from `_first` + per-superstep writes captured in
+    # `after_tick`). At exit, `_put_exit_delta_writes` filters out channels
+    # that will snapshot, then persists the rest under an anchor parent.
+    # `None` when not in exit mode (so the capture sites are no-ops).
+    # Each tuple is `(step, task_id, channel, value)` — `step` drives the
+    # synthetic step-prefixed task_id used to preserve chronological order
+    # under the saver's `ORDER BY task_id, idx` sorting.
+    _exit_delta_writes: list[tuple[int, str, str, Any]] | None = None
+
+    # The checkpoint_config that points at the parent loaded at `__enter__`
+    # (or the synthetic-empty checkpoint, on first run). We capture it
+    # eagerly because every `_put_checkpoint` advances `self.checkpoint_config`
+    # to the newly-saved checkpoint's id — by exit time the original parent
+    # config would otherwise be lost. `_put_exit_delta_writes` uses this:
+    # on resumed runs as the anchor for exit delta writes; on first runs
+    # to derive the lazy stub's config (its `checkpoint_id` is the
+    # synthetic-empty id we want the stub persisted under).
+    _initial_checkpoint_config: RunnableConfig
+
+    # True iff the saver actually returned a tuple at `__enter__`. False
+    # on the first-ever run for a thread (no parent persisted yet).
+    # `_put_exit_delta_writes` uses this to decide between anchoring on
+    # the existing parent (True) or creating a lazy stub (False).
+    _has_persisted_parent: bool = False
+
     managed: ManagedValueMapping
     checkpoint: Checkpoint
     checkpoint_id_saved: str
@@ -202,10 +243,12 @@ class PregelLoop:
         "input",
         "pending",
         "done",
+        "draining",
         "interrupt_before",
         "interrupt_after",
         "out_of_steps",
     ]
+    control: RunControl | None
     tasks: dict[str, PregelExecutableTask]
     output: None | dict[str, Any] | Any = None
     updated_channels: set[str] | None = None
@@ -313,6 +356,8 @@ class PregelLoop:
             else ()
         )
         self.prev_checkpoint_config = None
+        runtime = self.config[CONF].get(CONFIG_KEY_RUNTIME)
+        self.control = runtime.control if isinstance(runtime, Runtime) else None
 
     def _push_graph_lifecycle_event(
         self,
@@ -320,11 +365,16 @@ class PregelLoop:
         *,
         interrupts: tuple[Interrupt, ...] = (),
     ) -> None:
+        # drain status never reaches lifecycle events: tick() returns False
+        # before pushing, and interrupts are raised through GraphInterrupt
+        if self.status == "draining":
+            raise RuntimeError("Draining status cannot emit lifecycle events")
+        status = self.status
         if kind == "resume":
             self._graph_lifecycle_events.append(
                 GraphResumeEvent(
                     run_id=None,
-                    status=self.status,
+                    status=status,
                     checkpoint_id=self.checkpoint["id"],
                     checkpoint_ns=self.checkpoint_ns,
                 )
@@ -333,7 +383,7 @@ class PregelLoop:
             self._graph_lifecycle_events.append(
                 GraphInterruptEvent(
                     run_id=None,
-                    status=self.status,
+                    status=status,
                     checkpoint_id=self.checkpoint["id"],
                     checkpoint_ns=self.checkpoint_ns,
                     interrupts=interrupts,
@@ -406,7 +456,7 @@ class PregelLoop:
                     task = self.tasks.get(task_id)
                 else:
                     task = None
-                self.submit(
+                fut = self.submit(
                     self.checkpointer_put_writes,
                     config,
                     writes_to_save,
@@ -414,12 +464,16 @@ class PregelLoop:
                     task_path_str(task.path) if task else "",
                 )
             else:
-                self.submit(
+                fut = self.submit(
                     self.checkpointer_put_writes,
                     config,
                     writes_to_save,
                     task_id,
                 )
+            if self._delta_write_futs is not None and any(
+                isinstance(self.specs.get(c), DeltaChannel) for c, _ in writes_to_save
+            ):
+                self._delta_write_futs.append(fut)
         # output writes
         if hasattr(self, "tasks"):
             self.output_writes(task_id, writes)
@@ -503,6 +557,16 @@ class PregelLoop:
             # return the new task, to be started if not run before
             return pushed
 
+    def schedule_error_handler(
+        self, failed_task: PregelExecutableTask, error: BaseException
+    ) -> PregelExecutableTask | None:
+        raise NotImplementedError
+
+    async def aschedule_error_handler(
+        self, failed_task: PregelExecutableTask, error: BaseException
+    ) -> PregelExecutableTask | None:
+        raise NotImplementedError
+
     def tick(self) -> bool:
         """Execute a single iteration of the Pregel loop.
 
@@ -561,6 +625,10 @@ class PregelLoop:
             self.status = "done"
             return False
 
+        if self.control is not None and self.control.drain_requested:
+            self.status = "draining"
+            return False
+
         # if there are pending writes from a previous loop, apply them
         if not self.is_replaying and self.checkpoint_pending_writes:
             self._match_writes(self.tasks)
@@ -602,6 +670,11 @@ class PregelLoop:
             self._emit(
                 "values", map_output_values, self.output_keys, writes, self.channels
             )
+        # capture delta-channel writes for exit-mode accumulator before clearing
+        if self._exit_delta_writes is not None:
+            for tid, ch, v in self.checkpoint_pending_writes:
+                if isinstance(self.specs.get(ch), DeltaChannel):
+                    self._exit_delta_writes.append((self.step, tid, ch, v))
         # clear pending writes
         self.checkpoint_pending_writes.clear()
         # only replay (re-execute) done tasks on the first tick
@@ -627,7 +700,7 @@ class PregelLoop:
 
     def _match_writes(self, tasks: Mapping[str, PregelExecutableTask]) -> None:
         for tid, k, v in self.checkpoint_pending_writes:
-            if k in (ERROR, INTERRUPT, RESUME):
+            if k in (ERROR, ERROR_SOURCE_NODE, INTERRUPT, RESUME):
                 continue
             if task := tasks.get(tid):
                 task.writes.append((k, v))
@@ -819,6 +892,27 @@ class PregelLoop:
                 self.checkpointer_get_next_version,
                 self.trigger_to_nodes,
             )
+            # Input writes go through `apply_writes` directly (above) — they
+            # never enter `checkpoint_pending_writes`, so the after_tick
+            # capture site does not see them. In exit mode, capture them
+            # here so `_exit_delta_writes` includes the input's delta writes
+            # alongside per-superstep writes; otherwise the input would be
+            # lost on read (it's not in final_checkpoint.channel_values for
+            # sub-freq channels, and walks ignore target.pending_writes).
+            if self._exit_delta_writes is not None:
+                for c, v in input_writes:
+                    if isinstance(self.specs.get(c), DeltaChannel):
+                        self._exit_delta_writes.append((self.step, NULL_TASK_ID, c, v))
+            # Persist delta-channel input writes so sub-freq inputs are
+            # recoverable via ancestor walk (mirrors the Command input path).
+            if self.durability != "exit":
+                delta_input = [
+                    (c, v)
+                    for c, v in input_writes
+                    if isinstance(self.specs.get(c), DeltaChannel)
+                ]
+                if delta_input:
+                    self.put_writes(NULL_TASK_ID, delta_input)
             # save input checkpoint
             self.updated_channels = updated_channels
             self._put_checkpoint({"source": "input"})
@@ -870,27 +964,77 @@ class PregelLoop:
         return updated_channels
 
     def _put_checkpoint(self, metadata: CheckpointMetadata) -> None:
-        # assign step and parents
+        # `is` (object identity) — not `==`. Three of four call sites pass a
+        # fresh dict ({"source":"input"|"loop"|"fork"}); only
+        # `_suppress_interrupt`(will rename to _on_loop_exit soon)
+        # at exit reuses the existing `self.checkpoint_metadata` instance. So
+        # `metadata is self.checkpoint_metadata` is True only on the exit call,
+        # which is what we use to gate exit-only behaviour (skip count-bump,
+        # don't replace metadata). Could be replaced by an explicit
+        # `exiting: bool = False` parameter; left as-is to match the existing
+        # idiom in this file.
+        # TODO: replace with an explicit `exiting: bool = False` parameter.
         exiting = metadata is self.checkpoint_metadata
         if exiting and self.checkpoint["id"] == self.checkpoint_id_saved:
             # checkpoint already saved
             return
+        # Per-delta-channel update bookkeeping.
+        #
+        # `_put_checkpoint` is called once per superstep with a fresh
+        # metadata dict (source="input"|"loop"|"fork") — those are the
+        # intermediate calls that bump the count by +1 for each delta
+        # channel touched that step. In exit mode,
+        # `_suppress_interrupt`(will rename to _on_loop_exit soon)
+        # additionally calls `_put_checkpoint(self.checkpoint_metadata)` AT
+        # EXIT to commit the final checkpoint — this runs *after* the last
+        # intermediate call already counted the last superstep. So the
+        # exit call must NOT bump again or it would double-count the last
+        # superstep. (Sync/async durability does not call `_put_checkpoint`
+        # at exit, so the issue only surfaces in exit mode. force_delta_snapshot
+        # used to mask this latent bug by resetting every count to 0.)
         if not exiting:
+            prev_counts = dict(
+                self.checkpoint_metadata.get("delta_updates_since_snapshot", {}) or {}
+            )
+            new_counts = dict(prev_counts)
+            if self.updated_channels:
+                for ch_name in self.updated_channels:
+                    if isinstance(self.channels.get(ch_name), DeltaChannel):
+                        new_counts[ch_name] = new_counts.get(ch_name, 0) + 1
             metadata["step"] = self.step
             metadata["parents"] = self.config[CONF].get(CONFIG_KEY_CHECKPOINT_MAP, {})
             self.checkpoint_metadata = metadata
+        else:
+            new_counts = dict(
+                self.checkpoint_metadata.get("delta_updates_since_snapshot", {}) or {}
+            )
         # do checkpoint?
         do_checkpoint = self._checkpointer_put_after_previous is not None and (
             exiting or self.durability != "exit"
         )
         # create new checkpoint
+        channels_to_snapshot = (
+            delta_channels_to_snapshot(self.channels, new_counts)
+            if do_checkpoint
+            else set()
+        )
         self.checkpoint = create_checkpoint(
             self.checkpoint,
             self.channels if do_checkpoint else None,
             self.step,
             id=self.checkpoint["id"] if exiting else None,
             updated_channels=self.updated_channels,
+            get_next_version=self.checkpointer_get_next_version
+            if do_checkpoint
+            else None,
+            channels_to_snapshot=channels_to_snapshot,
         )
+        for k in channels_to_snapshot:
+            new_counts[k] = 0
+        if new_counts:
+            self.checkpoint_metadata["delta_updates_since_snapshot"] = new_counts
+        elif "delta_updates_since_snapshot" in self.checkpoint_metadata:
+            del self.checkpoint_metadata["delta_updates_since_snapshot"]
         # sanitize TASK channel in the checkpoint before saving (durability=="exit")
         if TASKS in self.checkpoint["channel_values"] and any(
             isinstance(channel, UntrackedValue) for channel in self.channels.values()
@@ -949,6 +1093,97 @@ class PregelLoop:
             # increment step
             self.step += 1
 
+    def _put_exit_delta_writes(self) -> None:
+        """Stage stub + accumulated delta writes so final_checkpoint's put
+        waits on them (visibility invariant: both must be durable before
+        final_checkpoint becomes visible to readers).
+
+        Stub is created lazily — only when no persisted parent exists AND at
+        least one delta channel has writes that won't be snapshotted.
+        """
+        if (
+            not self._exit_delta_writes
+            or self.checkpointer is None
+            or self._checkpointer_put_after_previous is None
+            or self.checkpointer_put_writes is None
+        ):
+            return
+
+        counts = self.checkpoint_metadata.get("delta_updates_since_snapshot", {}) or {}
+        channels_to_snapshot = delta_channels_to_snapshot(self.channels, counts)
+
+        pending = [
+            (step, tid, ch, v)
+            for (step, tid, ch, v) in self._exit_delta_writes
+            if ch not in channels_to_snapshot
+        ]
+        if not pending:
+            return
+
+        if self._has_persisted_parent:
+            # _initial_checkpoint_config's checkpoint_id is the saved parent's
+            # id (saver returned a real tuple at __enter__).
+            anchor_config = self._initial_checkpoint_config
+        else:
+            stub_cp = empty_checkpoint()
+            stub_cp["id"] = self.checkpoint_id_saved
+            stub_cp["ts"] = datetime.now(timezone.utc).isoformat()
+            # Stub has no parent (checkpoint_id=None in config).
+            stub_put_config = patch_configurable(
+                self._initial_checkpoint_config,
+                {CONFIG_KEY_CHECKPOINT_ID: None},
+            )
+            # Anchor config for put_writes: checkpoint_id = stub's id.
+            anchor_config = patch_configurable(
+                self._initial_checkpoint_config,
+                {CONFIG_KEY_CHECKPOINT_ID: stub_cp["id"]},
+            )
+            self._put_checkpoint_fut = self.submit(
+                self._checkpointer_put_after_previous,
+                getattr(self, "_put_checkpoint_fut", None),
+                stub_put_config,
+                stub_cp,
+                {"step": -2},
+                {},
+            )
+            # Set checkpoint_config so final_checkpoint's _put_checkpoint
+            # sees the stub as its parent.
+            self.checkpoint_config = anchor_config
+
+        # Step-prefixed synthetic task_id preserves chronological superstep
+        # order under the saver's ORDER BY task_id, idx sorting.
+        grouped: dict[tuple[int, str], list[tuple[str, Any]]] = {}
+        for step, tid, ch, v in pending:
+            grouped.setdefault((step, tid), []).append((ch, v))
+        anchor_write_config = patch_configurable(
+            anchor_config,
+            {
+                CONFIG_KEY_CHECKPOINT_NS: self.config[CONF].get(
+                    CONFIG_KEY_CHECKPOINT_NS, ""
+                ),
+                CONFIG_KEY_CHECKPOINT_ID: anchor_config[CONF][CONFIG_KEY_CHECKPOINT_ID],
+            },
+        )
+        for (step, tid), entries in grouped.items():
+            synth_tid = f"{step:08d}-{tid}"
+            if self.checkpointer_put_writes_accepts_task_path:
+                fut = self.submit(
+                    self.checkpointer_put_writes,
+                    anchor_write_config,
+                    entries,
+                    synth_tid,
+                    "",
+                )
+            else:
+                fut = self.submit(
+                    self.checkpointer_put_writes,
+                    anchor_write_config,
+                    entries,
+                    synth_tid,
+                )
+            if self._delta_write_futs is not None:
+                self._delta_write_futs.append(fut)
+
     def _suppress_interrupt(
         self,
         exc_type: type[BaseException] | None,
@@ -964,6 +1199,7 @@ class PregelLoop:
             # or a nested graph with checkpointer=True
             or all(NS_END not in part for part in self.checkpoint_ns)
         ):
+            self._put_exit_delta_writes()
             self._put_checkpoint(self.checkpoint_metadata)
             self._put_pending_writes()
         # suppress interrupt
@@ -1169,6 +1405,9 @@ class SyncPregelLoop(PregelLoop, AbstractContextManager):
         metadata: CheckpointMetadata,
         new_versions: ChannelVersions,
     ) -> RunnableConfig:
+        if self._delta_write_futs:
+            futs, self._delta_write_futs = self._delta_write_futs, []
+            concurrent.futures.wait(futs)
         try:
             if prev is not None:
                 prev.result()
@@ -1200,6 +1439,45 @@ class SyncPregelLoop(PregelLoop, AbstractContextManager):
                 self.output_writes(task.id, task.writes, cached=True)
         return pushed
 
+    def schedule_error_handler(
+        self, failed_task: PregelExecutableTask, error: BaseException
+    ) -> PregelExecutableTask | None:
+        handler_node = self.nodes[failed_task.name].error_handler_node
+        if not handler_node:
+            return None
+        writes = list(failed_task.writes)
+        writes.append((ERROR_SOURCE_NODE, failed_task.name))
+        self.put_writes(
+            failed_task.id,
+            writes,
+        )
+        handler_task = prepare_node_error_handler_task(
+            failed_task,
+            handler_node_name=handler_node,
+            failed_error=error,
+            checkpoint=self.checkpoint,
+            pending_writes=self.checkpoint_pending_writes,
+            processes=self.nodes,
+            channels=self.channels,
+            managed=self.managed,
+            config=failed_task.config,
+            step=self.step,
+            stop=self.stop,
+            store=self.store,
+            checkpointer=self.checkpointer,
+            manager=self.manager,
+            retry_policy=self.retry_policy,
+            cache_policy=self.cache_policy,
+        )
+        if handler_task is None:
+            return None
+        self.tasks[handler_task.id] = handler_task
+        if not self.is_replaying:
+            self._match_writes({handler_task.id: handler_task})
+        for task in self.match_cached_writes():
+            self.output_writes(task.id, task.writes, cached=True)
+        return handler_task
+
     def put_writes(self, task_id: str, writes: WritesT) -> None:
         """Put writes for a task, to be read by the next tick."""
         super().put_writes(task_id, writes)
@@ -1247,6 +1525,10 @@ class SyncPregelLoop(PregelLoop, AbstractContextManager):
             # graph/thread. Returns None on first invocation.
             saved = self.checkpointer.get_tuple(self.checkpoint_config)
 
+        # Capture before the synthetic-empty fallback below overwrites `saved`.
+        # `_put_exit_delta_writes` uses this on first run (no persisted parent)
+        # to lazy-create a stub instead of anchoring delta writes on a parent.
+        self._has_persisted_parent = saved is not None
         if saved is None:
             saved = CheckpointTuple(
                 self.checkpoint_config, empty_checkpoint(), {"step": -2}, None, []
@@ -1262,6 +1544,7 @@ class SyncPregelLoop(PregelLoop, AbstractContextManager):
                 **saved.config.get(CONF, {}),
             },
         }
+        self._initial_checkpoint_config = self.checkpoint_config
         self.prev_checkpoint_config = saved.parent_config
         self.checkpoint_id_saved = saved.checkpoint["id"]
         self.checkpoint = saved.checkpoint
@@ -1271,9 +1554,16 @@ class SyncPregelLoop(PregelLoop, AbstractContextManager):
             if saved.pending_writes is not None
             else []
         )
+        self._delta_write_futs = []
+        self._exit_delta_writes = (
+            [] if self.durability == "exit" and self.checkpointer is not None else None
+        )
         self.submit = self.stack.enter_context(BackgroundExecutor(self.config))
         self.channels, self.managed = channels_from_checkpoint(
-            self.specs, self.checkpoint
+            self.specs,
+            self.checkpoint,
+            saver=self.checkpointer,
+            config=self.checkpoint_config,
         )
         self.stack.push(self._suppress_interrupt)
         self.status = "input"
@@ -1368,6 +1658,11 @@ class AsyncPregelLoop(PregelLoop, AbstractAsyncContextManager):
         metadata: CheckpointMetadata,
         new_versions: ChannelVersions,
     ) -> RunnableConfig:
+        # Drain DeltaChannel write futures before committing the checkpoint so
+        # ancestor walks never see a checkpoint without its backing writes.
+        if self._delta_write_futs:
+            futs, self._delta_write_futs = self._delta_write_futs, []
+            await asyncio.gather(*futs)
         try:
             if prev is not None:
                 await prev
@@ -1399,6 +1694,45 @@ class AsyncPregelLoop(PregelLoop, AbstractAsyncContextManager):
                 self.output_writes(task.id, task.writes, cached=True)
         return pushed
 
+    async def aschedule_error_handler(
+        self, failed_task: PregelExecutableTask, error: BaseException
+    ) -> PregelExecutableTask | None:
+        handler_node = self.nodes[failed_task.name].error_handler_node
+        if not handler_node:
+            return None
+        writes = list(failed_task.writes)
+        writes.append((ERROR_SOURCE_NODE, failed_task.name))
+        self.put_writes(
+            failed_task.id,
+            writes,
+        )
+        handler_task = prepare_node_error_handler_task(
+            failed_task,
+            handler_node_name=handler_node,
+            failed_error=error,
+            checkpoint=self.checkpoint,
+            pending_writes=self.checkpoint_pending_writes,
+            processes=self.nodes,
+            channels=self.channels,
+            managed=self.managed,
+            config=failed_task.config,
+            step=self.step,
+            stop=self.stop,
+            store=self.store,
+            checkpointer=self.checkpointer,
+            manager=self.manager,
+            retry_policy=self.retry_policy,
+            cache_policy=self.cache_policy,
+        )
+        if handler_task is None:
+            return None
+        self.tasks[handler_task.id] = handler_task
+        if not self.is_replaying:
+            self._match_writes({handler_task.id: handler_task})
+        for task in await self.amatch_cached_writes():
+            self.output_writes(task.id, task.writes, cached=True)
+        return handler_task
+
     def put_writes(self, task_id: str, writes: WritesT) -> None:
         """Put writes for a task, to be read by the next tick."""
         super().put_writes(task_id, writes)
@@ -1449,6 +1783,10 @@ class AsyncPregelLoop(PregelLoop, AbstractAsyncContextManager):
             # graph/thread. Returns None on first invocation.
             saved = await self.checkpointer.aget_tuple(self.checkpoint_config)
 
+        # Capture before the synthetic-empty fallback below overwrites `saved`.
+        # `_put_exit_delta_writes` uses this on first run (no persisted parent)
+        # to lazy-create a stub instead of anchoring delta writes on a parent.
+        self._has_persisted_parent = saved is not None
         if saved is None:
             saved = CheckpointTuple(
                 self.checkpoint_config, empty_checkpoint(), {"step": -2}, None, []
@@ -1464,6 +1802,7 @@ class AsyncPregelLoop(PregelLoop, AbstractAsyncContextManager):
                 **saved.config.get(CONF, {}),
             },
         }
+        self._initial_checkpoint_config = self.checkpoint_config
         self.prev_checkpoint_config = saved.parent_config
         self.checkpoint_id_saved = saved.checkpoint["id"]
         self.checkpoint = saved.checkpoint
@@ -1473,11 +1812,18 @@ class AsyncPregelLoop(PregelLoop, AbstractAsyncContextManager):
             if saved.pending_writes is not None
             else []
         )
+        self._delta_write_futs = []
+        self._exit_delta_writes = (
+            [] if self.durability == "exit" and self.checkpointer is not None else None
+        )
         self.submit = await self.stack.enter_async_context(
             AsyncBackgroundExecutor(self.config)
         )
-        self.channels, self.managed = channels_from_checkpoint(
-            self.specs, self.checkpoint
+        self.channels, self.managed = await achannels_from_checkpoint(
+            self.specs,
+            self.checkpoint,
+            saver=self.checkpointer,
+            config=self.checkpoint_config,
         )
         self.stack.push(self._suppress_interrupt)
         self.status = "input"

libs/langgraph/langgraph/pregel/_messages.py

@@ -349,7 +349,7 @@ class StreamMessagesHandlerV2(StreamMessagesHandler, _V2StreamingCallbackHandler
         tags: list[str] | None = None,
         **kwargs: Any,
     ) -> Any:
-        """Forward a protocol event from `stream_v2` as a messages stream part.
+        """Forward a protocol event from `stream_events(version="v3")` as a messages stream part.
 
         Fires once per `MessagesData` event (`message-start`, per-block
         `content-block-*`, `message-finish`). The transformer layer

libs/langgraph/langgraph/pregel/_read.py

@@ -138,6 +138,12 @@ class PregelNode:
     metadata: Mapping[str, Any] | None
     """Metadata to attach to the node for tracing."""
 
+    is_error_handler: bool
+    """Whether this node is registered as an error handler node."""
+
+    error_handler_node: str | None
+    """Optional handler node name for failures from this node."""
+
     subgraphs: Sequence[PregelProtocol]
     """Subgraphs used by the node."""
 
@@ -153,6 +159,8 @@ class PregelNode:
         bound: Runnable[Any, Any] | None = None,
         retry_policy: RetryPolicy | Sequence[RetryPolicy] | None = None,
         cache_policy: CachePolicy | None = None,
+        is_error_handler: bool = False,
+        error_handler_node: str | None = None,
         subgraphs: Sequence[PregelProtocol] | None = None,
         timeout: float | timedelta | TimeoutPolicy | None = None,
     ) -> None:
@@ -169,6 +177,8 @@ class PregelNode:
         self.timeout = coerce_timeout_policy(timeout)
         self.tags = tags
         self.metadata = metadata
+        self.is_error_handler = is_error_handler
+        self.error_handler_node = error_handler_node
         if subgraphs is not None:
             self.subgraphs = subgraphs
         elif self.bound is not DEFAULT_BOUND:

libs/langgraph/langgraph/pregel/_runner.py

@@ -10,8 +10,10 @@ from collections.abc import (
     AsyncIterator,
     Awaitable,
     Callable,
+    Collection,
     Iterable,
     Iterator,
+    Mapping,
     Sequence,
 )
 from functools import partial
@@ -72,6 +74,10 @@ SKIP_RERAISE_SET: weakref.WeakSet[concurrent.futures.Future | asyncio.Future] =
 class FuturesDict(Generic[F, E], dict[F, PregelExecutableTask | None]):
     event: E
     callback: weakref.ref[Callable[[PregelExecutableTask, BaseException | None], None]]
+    # Stop condition is injected by PregelRunner instead of hard-coded here.
+    # This lets the runner treat graph-error-handled exceptions as non-fatal
+    # so `on_done` does not trigger an early stop for those futures.
+    should_stop: Callable[[set[F]], bool]
     counter: int
     done: set[F]
     lock: threading.Lock
@@ -82,6 +88,7 @@ class FuturesDict(Generic[F, E], dict[F, PregelExecutableTask | None]):
         callback: weakref.ref[
             Callable[[PregelExecutableTask, BaseException | None], None]
         ],
+        should_stop: Callable[[set[F]], bool],
         future_type: type[F],
         # used for generic typing, newer py supports FutureDict[...](...)
     ) -> None:
@@ -89,6 +96,7 @@ class FuturesDict(Generic[F, E], dict[F, PregelExecutableTask | None]):
         self.lock = threading.Lock()
         self.event = event
         self.callback = callback
+        self.should_stop = should_stop
         self.counter = 0
         self.done: set[F] = set()
 
@@ -109,6 +117,7 @@ class FuturesDict(Generic[F, E], dict[F, PregelExecutableTask | None]):
         task: PregelExecutableTask,
         fut: F,
     ) -> None:
+        # Called automatically by future.add_done_callback registered in __setitem__.
         try:
             if cb := self.callback():
                 cb(task, _exception(fut))
@@ -116,7 +125,9 @@ class FuturesDict(Generic[F, E], dict[F, PregelExecutableTask | None]):
             with self.lock:
                 self.done.add(fut)
                 self.counter -= 1
-                if self.counter == 0 or _should_stop_others(self.done):
+                # Wake waiter when all tracked futures are done, or when runner-level
+                # stop condition is met (for example, a non-handled fatal exception).
+                if self.counter == 0 or self.should_stop(self.done):
                     self.event.set()
 
 
@@ -132,11 +143,34 @@ class PregelRunner:
         put_writes: weakref.ref[Callable[[str, Sequence[tuple[str, Any]]], None]],
         use_astream: bool = False,
         node_finished: Callable[[str], None] | None = None,
+        node_error_handler_map: Mapping[str, str] | None = None,
+        schedule_error_handler: Callable[
+            [PregelExecutableTask, BaseException], PregelExecutableTask | None
+        ]
+        | None = None,
+        aschedule_error_handler: Callable[
+            [PregelExecutableTask, BaseException],
+            Awaitable[PregelExecutableTask | None],
+        ]
+        | None = None,
     ) -> None:
         self.submit = submit
         self.put_writes = put_writes
         self.use_astream = use_astream
         self.node_finished = node_finished
+        self.node_error_handler_map = dict(node_error_handler_map or {})
+        self.error_handler_nodes = set(self.node_error_handler_map.values())
+        self.schedule_error_handler = schedule_error_handler
+        self.aschedule_error_handler = aschedule_error_handler
+        # Exception object ids that are already routed to graph-level error handler.
+        # These ids are consulted by stop/panic checks to avoid re-raising handled
+        # exceptions via the normal fatal path in the same run.
+        self._handled_exception_ids: set[int] = set()
+
+    def _should_route_to_error_handler(self, task: PregelExecutableTask) -> bool:
+        if task.name in self.error_handler_nodes:
+            return False
+        return task.name in self.node_error_handler_map
 
     def tick(
         self,
@@ -155,6 +189,9 @@ class PregelRunner:
         futures = FuturesDict(
             callback=weakref.WeakMethod(self.commit),
             event=threading.Event(),
+            should_stop=partial(
+                _should_stop_others, handled_exception_ids=self._handled_exception_ids
+            ),
             future_type=concurrent.futures.Future,
         )
         # give control back to the caller
@@ -164,6 +201,7 @@ class PregelRunner:
             return
         elif len(tasks) == 1 and timeout is None and get_waiter is None:
             t = tasks[0]
+            scheduled_error_handler = False
             try:
                 run_with_retry(
                     t,
@@ -182,12 +220,23 @@ class PregelRunner:
                 self.commit(t, None)
             except Exception as exc:
                 self.commit(t, exc)
+                if (
+                    not isinstance(exc, GraphBubbleUp)
+                    and self._should_route_to_error_handler(t)
+                    and self.schedule_error_handler is not None
+                ):
+                    self._handled_exception_ids.add(id(exc))
+                    if handler_task := self.schedule_error_handler(t, exc):
+                        tasks = (handler_task,)
+                        scheduled_error_handler = True
+                        # Continue to the regular scheduling path for handler execution.
                 if reraise and futures:
-                    # will be re-raised after futures are done
-                    fut: concurrent.futures.Future = concurrent.futures.Future()
-                    fut.set_exception(exc)
-                    futures.done.add(fut)
-                elif reraise:
+                    if id(exc) not in self._handled_exception_ids:
+                        # will be re-raised after futures are done
+                        fut: concurrent.futures.Future = concurrent.futures.Future()
+                        fut.set_exception(exc)
+                        futures.done.add(fut)
+                elif reraise and id(exc) not in self._handled_exception_ids:
                     if tb := exc.__traceback__:
                         while tb.tb_next is not None and any(
                             tb.tb_frame.f_code.co_filename.endswith(name)
@@ -196,10 +245,12 @@ class PregelRunner:
                             tb = tb.tb_next
                         exc.__traceback__ = tb
                     raise
-            if not futures:  # maybe `t` scheduled another task
+            if not futures and not scheduled_error_handler:
+                # maybe `t` scheduled another task
                 return
             else:
-                tasks = ()  # don't reschedule this task
+                if not scheduled_error_handler:
+                    tasks = ()  # don't reschedule this task
         # add waiter task if requested
         if get_waiter is not None:
             futures[get_waiter()] = None
@@ -226,6 +277,7 @@ class PregelRunner:
         # each task is independent from all other concurrent tasks
         # yield updates/debug output as each task finishes
         end_time = timeout + time.monotonic() if timeout else None
+        handled_futures: set[concurrent.futures.Future[Any]] = set()
         while len(futures) > (1 if get_waiter is not None else 0):
             done, inflight = concurrent.futures.wait(
                 futures,
@@ -234,17 +286,49 @@ class PregelRunner:
             )
             if not done:
                 break  # timed out
+            done_for_stop: set[concurrent.futures.Future[Any]] = set()
             for fut in done:
                 task = futures.pop(fut)
                 if task is None:
                     # waiter task finished, schedule another
                     if inflight and get_waiter is not None:
                         futures[get_waiter()] = None
+                elif (
+                    (task_exc := _exception(fut))
+                    and self._should_route_to_error_handler(task)
+                    and not isinstance(task_exc, GraphBubbleUp)
+                ):
+                    self._handled_exception_ids.add(id(task_exc))
+                    SKIP_RERAISE_SET.add(fut)
+                    handled_futures.add(fut)
+                    if self.schedule_error_handler is not None:
+                        if handler_task := self.schedule_error_handler(task, task_exc):
+                            handler_fut = self.submit()(  # type: ignore[misc]
+                                run_with_retry,
+                                handler_task,
+                                retry_policy,
+                                configurable={
+                                    CONFIG_KEY_CALL: partial(
+                                        _call,
+                                        weakref.ref(handler_task),
+                                        retry_policy=retry_policy,
+                                        futures=weakref.ref(futures),
+                                        schedule_task=schedule_task,
+                                        submit=self.submit,
+                                    ),
+                                },
+                                __reraise_on_exit__=reraise,
+                            )
+                            futures[handler_fut] = handler_task
+                else:
+                    done_for_stop.add(fut)
             else:
                 # remove references to loop vars
                 del fut, task
             # maybe stop other tasks
-            if _should_stop_others(done):
+            if _should_stop_others(
+                done_for_stop, handled_exception_ids=self._handled_exception_ids
+            ):
                 break
             # give control back to the caller
             yield
@@ -259,6 +343,8 @@ class PregelRunner:
             _panic_or_proceed(
                 futures.done.union(f for f, t in futures.items() if t is not None),
                 panic=reraise,
+                handled_exception_ids=self._handled_exception_ids,
+                handled_futures=handled_futures,
             )
         except Exception as exc:
             if tb := exc.__traceback__:
@@ -292,6 +378,9 @@ class PregelRunner:
         futures = FuturesDict(
             callback=weakref.WeakMethod(self.commit),
             event=asyncio.Event(),
+            should_stop=partial(
+                _should_stop_others, handled_exception_ids=self._handled_exception_ids
+            ),
             future_type=asyncio.Future,
         )
         # give control back to the caller
@@ -301,6 +390,7 @@ class PregelRunner:
             return
         elif len(tasks) == 1 and get_waiter is None and timeout is None:
             t = tasks[0]
+            scheduled_error_handler = False
             try:
                 await arun_with_retry(
                     t,
@@ -322,12 +412,22 @@ class PregelRunner:
                 self.commit(t, None)
             except Exception as exc:
                 self.commit(t, exc)
+                if (
+                    not isinstance(exc, GraphBubbleUp)
+                    and self._should_route_to_error_handler(t)
+                    and self.aschedule_error_handler is not None
+                ):
+                    self._handled_exception_ids.add(id(exc))
+                    if handler_task := await self.aschedule_error_handler(t, exc):
+                        tasks = (handler_task,)
+                        scheduled_error_handler = True
                 if reraise and futures:
-                    # will be re-raised after futures are done
-                    fut: asyncio.Future = loop.create_future()
-                    fut.set_exception(exc)
-                    futures.done.add(fut)
-                elif reraise:
+                    if id(exc) not in self._handled_exception_ids:
+                        # will be re-raised after futures are done
+                        fut: asyncio.Future = loop.create_future()
+                        fut.set_exception(exc)
+                        futures.done.add(fut)
+                elif reraise and id(exc) not in self._handled_exception_ids:
                     if tb := exc.__traceback__:
                         while tb.tb_next is not None and any(
                             tb.tb_frame.f_code.co_filename.endswith(name)
@@ -336,10 +436,12 @@ class PregelRunner:
                             tb = tb.tb_next
                         exc.__traceback__ = tb
                     raise
-            if not futures:  # maybe `t` scheduled another task
+            if not futures and not scheduled_error_handler:
+                # maybe `t` scheduled another task
                 return
             else:
-                tasks = ()  # don't reschedule this task
+                if not scheduled_error_handler:
+                    tasks = ()  # don't reschedule this task
         # add waiter task if requested
         if get_waiter is not None:
             futures[get_waiter()] = None
@@ -374,6 +476,7 @@ class PregelRunner:
         # each task is independent from all other concurrent tasks
         # yield updates/debug output as each task finishes
         end_time = timeout + loop.time() if timeout else None
+        handled_futures: set[asyncio.Future[Any]] = set()
         while len(futures) > (1 if get_waiter is not None else 0):
             done, inflight = await asyncio.wait(
                 futures,
@@ -382,17 +485,59 @@ class PregelRunner:
             )
             if not done:
                 break  # timed out
+            done_for_stop: set[asyncio.Future[Any]] = set()
             for fut in done:
                 task = futures.pop(fut)
                 if task is None:
                     # waiter task finished, schedule another
                     if inflight and get_waiter is not None:
                         futures[get_waiter()] = None
+                elif (
+                    (task_exc := _exception(fut))
+                    and self._should_route_to_error_handler(task)
+                    and not isinstance(task_exc, GraphBubbleUp)
+                ):
+                    self._handled_exception_ids.add(id(task_exc))
+                    SKIP_RERAISE_SET.add(fut)
+                    handled_futures.add(fut)
+                    if self.aschedule_error_handler is not None:
+                        if handler_task := await self.aschedule_error_handler(
+                            task, task_exc
+                        ):
+                            handler_fut = cast(
+                                asyncio.Future,
+                                self.submit()(  # type: ignore[misc]
+                                    arun_with_retry,
+                                    handler_task,
+                                    retry_policy,
+                                    stream=self.use_astream,
+                                    configurable={
+                                        CONFIG_KEY_CALL: partial(
+                                            _acall,
+                                            weakref.ref(handler_task),
+                                            retry_policy=retry_policy,
+                                            stream=self.use_astream,
+                                            futures=weakref.ref(futures),
+                                            schedule_task=schedule_task,
+                                            submit=self.submit,
+                                            loop=loop,
+                                        ),
+                                    },
+                                    __name__=handler_task.name,
+                                    __cancel_on_exit__=True,
+                                    __reraise_on_exit__=reraise,
+                                ),
+                            )
+                            futures[handler_fut] = handler_task
+                else:
+                    done_for_stop.add(fut)
             else:
                 # remove references to loop vars
                 del fut, task
             # maybe stop other tasks
-            if _should_stop_others(done):
+            if _should_stop_others(
+                done_for_stop, handled_exception_ids=self._handled_exception_ids
+            ):
                 break
             # give control back to the caller
             yield
@@ -412,6 +557,8 @@ class PregelRunner:
                 futures.done.union(f for f, t in futures.items() if t is not None),
                 timeout_exc_cls=asyncio.TimeoutError,
                 panic=reraise,
+                handled_exception_ids=self._handled_exception_ids,
+                handled_futures=handled_futures,
             )
         except Exception as exc:
             if tb := exc.__traceback__:
@@ -447,6 +594,11 @@ class PregelRunner:
             else:
                 # save error to checkpointer
                 task.writes.append((ERROR, exception))
+                if self._should_route_to_error_handler(task) and not isinstance(
+                    exception, GraphBubbleUp
+                ):
+                    # Mark early in commit path; loop-side routing may happen later.
+                    self._handled_exception_ids.add(id(exception))
                 self.put_writes()(task.id, task.writes)  # type: ignore[misc]
         else:
             if self.node_finished and (
@@ -462,6 +614,8 @@ class PregelRunner:
 
 def _should_stop_others(
     done: set[F],
+    *,
+    handled_exception_ids: set[int] | None = None,
 ) -> bool:
     """Check if any task failed, if so, cancel all other tasks.
     GraphInterrupts are not considered failures."""
@@ -469,7 +623,11 @@ def _should_stop_others(
         if fut.cancelled():
             continue
         elif exc := fut.exception():
-            if not isinstance(exc, GraphBubbleUp) and fut not in SKIP_RERAISE_SET:
+            if (
+                id(exc) not in (handled_exception_ids or set())
+                and not isinstance(exc, GraphBubbleUp)
+                and fut not in SKIP_RERAISE_SET
+            ):
                 return True
 
     return False
@@ -493,6 +651,9 @@ def _panic_or_proceed(
     *,
     timeout_exc_cls: type[Exception] = TimeoutError,
     panic: bool = True,
+    handled_exception_ids: set[int] | None = None,
+    handled_futures: Collection[concurrent.futures.Future[Any] | asyncio.Future[Any]]
+    | None = None,
 ) -> None:
     """Cancel remaining tasks if any failed, re-raise exception if panic is True."""
     done: set[concurrent.futures.Future[Any] | asyncio.Future[Any]] = set()
@@ -509,6 +670,10 @@ def _panic_or_proceed(
         # if any task failed
         fut = done.pop()
         if exc := _exception(fut):
+            if fut in (handled_futures or set()):
+                continue
+            if id(exc) in (handled_exception_ids or set()):
+                continue
             # cancel all pending tasks
             while inflight:
                 inflight.pop().cancel()

libs/langgraph/langgraph/pregel/main.py

@@ -30,6 +30,7 @@ from typing import (
 )
 from uuid import UUID, uuid5
 
+from langchain_core._api import beta
 from langchain_core.globals import get_debug
 from langchain_core.runnables import (
     RunnableSequence,
@@ -41,6 +42,7 @@ from langchain_core.runnables.config import (
     get_callback_manager_for_config,
 )
 from langchain_core.runnables.graph import Graph
+from langchain_core.runnables.schema import StreamEvent
 from langgraph.cache.base import BaseCache
 from langgraph.checkpoint.base import (
     BaseCheckpointSaver,
@@ -111,6 +113,7 @@ from langgraph.config import get_config
 from langgraph.constants import END
 from langgraph.errors import (
     ErrorCode,
+    GraphDrained,
     GraphRecursionError,
     InvalidUpdateError,
     create_error_message,
@@ -125,6 +128,7 @@ from langgraph.pregel._algo import (
 )
 from langgraph.pregel._call import identifier
 from langgraph.pregel._checkpoint import (
+    achannels_from_checkpoint,
     channels_from_checkpoint,
     copy_checkpoint,
     create_checkpoint,
@@ -155,6 +159,7 @@ from langgraph.pregel.protocol import PregelProtocol, StreamChunk, StreamProtoco
 from langgraph.runtime import (
     DEFAULT_RUNTIME,
     BaseUser,
+    RunControl,
     Runtime,
     ServerInfo,
 )
@@ -369,11 +374,30 @@ class NodeBuilder:
         )
 
 
+# Kwargs that ``stream_events(version="v3")`` / ``astream_events(version="v3")``
+# manage internally and must not be overridden by callers. ``stream_mode`` is
+# derived from the transformer mux; ``subgraphs`` is forced True so nested
+# namespaces flow through scoped muxes. Forwarding either to the inner
+# ``stream(...)`` would silently break v3's invariants, so we raise instead.
+_V3_INVARIANT_KWARGS: tuple[str, ...] = ("stream_mode", "subgraphs")
+
+
+def _reject_v3_invariant_kwargs(kwargs: dict[str, Any]) -> None:
+    collisions = [k for k in _V3_INVARIANT_KWARGS if k in kwargs]
+    if collisions:
+        raise TypeError(
+            "stream_events(version='v3') / astream_events(version='v3') do "
+            f"not accept {', '.join(collisions)}; v3 owns these "
+            "(stream_mode is built from the transformer mux, subgraphs is "
+            "forced True so nested namespaces flow through scoped muxes)."
+        )
+
+
 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
+    `stream_events(version="v3")` asks the graph for exactly that union — no hardcoded
     default set. If zero transformers declare a given mode, the graph
     does not stream events for it.
     """
@@ -403,14 +427,14 @@ def _normalize_stream_transformer_factories(
     for spec in specs or ():
         if isinstance(spec, StreamTransformer):
             raise TypeError(
-                "stream_v2 transformers must be scope-aware callables, "
+                "stream_events(version='v3') transformers must be scope-aware callables, "
                 f"got pre-built instance {type(spec).__name__}. Pass the "
                 "transformer class or a factory like "
                 "`lambda scope: MyTransformer(scope, ...)`."
             )
         if not callable(spec):
             raise TypeError(
-                "stream_v2 transformers must be scope-aware callables, "
+                "stream_events(version='v3') transformers must be scope-aware callables, "
                 f"got {type(spec).__name__}."
             )
 
@@ -727,6 +751,7 @@ class Pregel(
     name: str = "LangGraph"
 
     trigger_to_nodes: Mapping[str, Sequence[str]]
+    node_error_handler_map: Mapping[str, str]
 
     def __init__(
         self,
@@ -751,6 +776,7 @@ class Pregel(
         context_schema: type[ContextT] | None = None,
         config: RunnableConfig | None = None,
         trigger_to_nodes: Mapping[str, Sequence[str]] | None = None,
+        node_error_handler_map: Mapping[str, str] | None = None,
         name: str = "LangGraph",
         stream_transformers: Sequence[Callable[[tuple[str, ...]], Any]] | None = None,
         **deprecated_kwargs: Unpack[DeprecatedKwargs],
@@ -798,6 +824,7 @@ class Pregel(
         self.context_schema = context_schema
         self.config = config
         self.trigger_to_nodes = trigger_to_nodes or {}
+        self.node_error_handler_map = node_error_handler_map or {}
         self.name = name
         self.stream_transformers: tuple[Callable[[tuple[str, ...]], Any], ...] = tuple(
             stream_transformers or ()
@@ -1140,6 +1167,10 @@ class Pregel(
         channels, managed = channels_from_checkpoint(
             self.channels,
             saved.checkpoint,
+            saver=self.checkpointer
+            if isinstance(self.checkpointer, BaseCheckpointSaver)
+            else None,
+            config=saved.config,
         )
         # tasks for this checkpoint
         next_tasks = prepare_next_tasks(
@@ -1256,9 +1287,13 @@ class Pregel(
 
         step = saved.metadata.get("step", -1) + 1
         stop = step + 2
-        channels, managed = channels_from_checkpoint(
+        channels, managed = await achannels_from_checkpoint(
             self.channels,
             saved.checkpoint,
+            saver=self.checkpointer
+            if isinstance(self.checkpointer, BaseCheckpointSaver)
+            else None,
+            config=saved.config,
         )
         # tasks for this checkpoint
         next_tasks = prepare_next_tasks(
@@ -1629,6 +1664,11 @@ class Pregel(
             channels, managed = channels_from_checkpoint(
                 self.channels,
                 checkpoint,
+                saver=self.checkpointer
+                if saved is not None
+                and isinstance(self.checkpointer, BaseCheckpointSaver)
+                else None,
+                config=saved.config if saved is not None else None,
             )
             values, as_node = updates[0][:2]
 
@@ -2072,9 +2112,14 @@ class Pregel(
             )
             if saved:
                 checkpoint_config = patch_configurable(config, saved.config[CONF])
-            channels, managed = channels_from_checkpoint(
+            channels, managed = await achannels_from_checkpoint(
                 self.channels,
                 checkpoint,
+                saver=self.checkpointer
+                if saved is not None
+                and isinstance(self.checkpointer, BaseCheckpointSaver)
+                else None,
+                config=saved.config if saved is not None else None,
             )
             values, as_node = updates[0][:2]
             # no values, just clear all tasks
@@ -2551,6 +2596,7 @@ class Pregel(
         interrupt_before: All | Sequence[str] | None = None,
         interrupt_after: All | Sequence[str] | None = None,
         durability: Durability | None = None,
+        control: RunControl | None = None,
         subgraphs: bool = False,
         debug: bool | None = None,
         version: Literal["v2"],
@@ -2570,6 +2616,7 @@ class Pregel(
         interrupt_before: All | Sequence[str] | None = None,
         interrupt_after: All | Sequence[str] | None = None,
         durability: Durability | None = None,
+        control: RunControl | None = None,
         subgraphs: bool = False,
         debug: bool | None = None,
         version: Literal["v1"] = ...,
@@ -2588,6 +2635,7 @@ class Pregel(
         interrupt_before: All | Sequence[str] | None = None,
         interrupt_after: All | Sequence[str] | None = None,
         durability: Durability | None = None,
+        control: RunControl | None = None,
         subgraphs: bool = False,
         debug: bool | None = None,
         version: Literal["v1", "v2"] = "v1",
@@ -2632,6 +2680,7 @@ class Pregel(
                 - `"sync"`: Changes are persisted synchronously before the next step starts.
                 - `"async"`: Changes are persisted asynchronously while the next step executes.
                 - `"exit"`: Changes are persisted only when the graph exits.
+            control: Optional run control used to request cooperative drain.
             subgraphs: Whether to stream events from inside subgraphs, defaults to `False`.
 
                 If `True`, the events will be emitted as tuples `(namespace, data)`,
@@ -2796,6 +2845,7 @@ class Pregel(
                 previous=None,
                 execution_info=None,
                 server_info=server_info,
+                control=control or parent_runtime.control or RunControl(),
             )
             runtime = parent_runtime.merge(runtime)
             config[CONF][CONFIG_KEY_RUNTIME] = runtime
@@ -2845,6 +2895,8 @@ class Pregel(
                     ),
                     put_writes=weakref.WeakMethod(loop.put_writes),
                     node_finished=config[CONF].get(CONFIG_KEY_NODE_FINISHED),
+                    node_error_handler_map=self.node_error_handler_map,
+                    schedule_error_handler=loop.schedule_error_handler,
                 )
                 # enable subgraph streaming
                 if subgraphs:
@@ -2926,6 +2978,10 @@ class Pregel(
                     error_code=ErrorCode.GRAPH_RECURSION_LIMIT,
                 )
                 raise GraphRecursionError(msg)
+            elif loop.status == "draining":
+                if loop.control is None:
+                    raise RuntimeError("Draining status requires run control")
+                raise GraphDrained(loop.control.drain_reason or "shutdown")
             # set final channel values as run output
             run_manager.on_chain_end(loop.output)
         except BaseException as e:
@@ -2946,6 +3002,7 @@ class Pregel(
         interrupt_before: All | Sequence[str] | None = None,
         interrupt_after: All | Sequence[str] | None = None,
         durability: Durability | None = None,
+        control: RunControl | None = None,
         subgraphs: bool = False,
         debug: bool | None = None,
         version: Literal["v2"],
@@ -2965,6 +3022,7 @@ class Pregel(
         interrupt_before: All | Sequence[str] | None = None,
         interrupt_after: All | Sequence[str] | None = None,
         durability: Durability | None = None,
+        control: RunControl | None = None,
         subgraphs: bool = False,
         debug: bool | None = None,
         version: Literal["v1"] = ...,
@@ -2983,6 +3041,7 @@ class Pregel(
         interrupt_before: All | Sequence[str] | None = None,
         interrupt_after: All | Sequence[str] | None = None,
         durability: Durability | None = None,
+        control: RunControl | None = None,
         subgraphs: bool = False,
         debug: bool | None = None,
         version: Literal["v1", "v2"] = "v1",
@@ -3027,6 +3086,7 @@ class Pregel(
                 - `"sync"`: Changes are persisted synchronously before the next step starts.
                 - `"async"`: Changes are persisted asynchronously while the next step executes.
                 - `"exit"`: Changes are persisted only when the graph exits.
+            control: Optional run control used to request cooperative drain.
             subgraphs: Whether to stream events from inside subgraphs, defaults to `False`.
 
                 If `True`, the events will be emitted as tuples `(namespace, data)`,
@@ -3226,6 +3286,7 @@ class Pregel(
                 previous=None,
                 execution_info=None,
                 server_info=server_info,
+                control=control or parent_runtime.control or RunControl(),
             )
             runtime = parent_runtime.merge(runtime)
             config[CONF][CONFIG_KEY_RUNTIME] = runtime
@@ -3287,6 +3348,8 @@ class Pregel(
                     put_writes=weakref.WeakMethod(loop.put_writes),
                     use_astream=do_stream,
                     node_finished=config[CONF].get(CONFIG_KEY_NODE_FINISHED),
+                    node_error_handler_map=self.node_error_handler_map,
+                    aschedule_error_handler=loop.aschedule_error_handler,
                 )
                 # enable subgraph streaming
                 if subgraphs:
@@ -3394,6 +3457,10 @@ class Pregel(
                     error_code=ErrorCode.GRAPH_RECURSION_LIMIT,
                 )
                 raise GraphRecursionError(msg)
+            elif loop.status == "draining":
+                if loop.control is None:
+                    raise RuntimeError("Draining status requires run control")
+                raise GraphDrained(loop.control.drain_reason or "shutdown")
             # set final channel values as run output
             await run_manager.on_chain_end(loop.output)
         except BaseException as e:
@@ -3401,49 +3468,29 @@ class Pregel(
                 await asyncio.shield(run_manager.on_chain_error(e))
             raise
 
-    def stream_v2(
+    @beta(message="The v3 streaming protocol on Pregel is experimental.")
+    def _pregel_stream_v3(
         self,
         input: InputT | Command | None,
         config: RunnableConfig | None = None,
         *,
         interrupt_before: All | Sequence[str] | None = None,
         interrupt_after: All | Sequence[str] | None = None,
+        control: RunControl | None = None,
         transformers: Sequence[Callable[[tuple[str, ...]], Any]] | None = None,
+        **kwargs: Any,
     ) -> Any:
-        """Start a sync v2 streaming run driven by transformer projections.
+        """Internal v3 sync streaming implementation. Public entry: stream_events(version='v3').
 
-        Builds a `StreamMux` from the built-in transformers, 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.
+        Extra keyword arguments are forwarded to the underlying ``stream(...)``
+        call. The dispatcher in ``stream_events`` rejects ``stream_mode`` and
+        ``subgraphs`` since v3 owns them (``stream_mode`` is derived from the
+        transformer mux; ``subgraphs`` is always True so nested namespaces
+        flow through scoped muxes).
 
-        `run.output`, `run.interrupted` and `run.interrupts` work
-        regardless of which transformers are registered.
+        !!! warning
 
-        Note:
-            Nesting v1 `stream(stream_mode="messages")` inside a node
-            of a `stream_v2` run is not fully supported. The outer v2
-            messages handler reroutes `BaseChatModel.invoke` through
-            the v2 event protocol, so the inner v1 handler does not see
-            `on_llm_new_token` chunks. The inner stream still yields a
-            finalized message via `on_llm_end`. Use `stream_v2` for
-            the inner graph as well, or call
-            `chat_model.stream(...)` explicitly, to get token-level
-            streaming.
-
-        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 classes or configured factories
-                appended after compile-time `stream_transformers`. Factories
-                are called as `factory(scope)` so they can propagate to
-                subgraph scopes.
-
-        Returns:
-            A `GraphRunStream` the caller iterates to drive the run.
+            The v3 streaming protocol is experimental and may change.
         """
         parent_ns = _resolve_parent_ns(self.config, config)
         compiled_factories = _normalize_stream_transformer_factories(
@@ -3471,43 +3518,35 @@ class Pregel(
                 version="v2",
                 interrupt_before=interrupt_before,
                 interrupt_after=interrupt_after,
+                control=control,
+                **kwargs,
             )
         )
         return GraphRunStream(graph_iter, mux)
 
-    async def astream_v2(
+    @beta(message="The v3 streaming protocol on Pregel is experimental.")
+    async def _apregel_stream_v3(
         self,
         input: InputT | Command | None,
         config: RunnableConfig | None = None,
         *,
         interrupt_before: All | Sequence[str] | None = None,
         interrupt_after: All | Sequence[str] | None = None,
+        control: RunControl | None = None,
         transformers: Sequence[Callable[[tuple[str, ...]], Any]] | None = None,
+        **kwargs: Any,
     ) -> Any:
-        """Async counterpart to `stream_v2`.
+        """Internal v3 async streaming implementation. Public entry: astream_events(version='v3').
 
-        Returns an `AsyncGraphRunStream` whose projections can be awaited
-        concurrently; each subscribed cursor drives the pump when its
-        buffer is empty.
+        Extra keyword arguments are forwarded to the underlying ``astream(...)``
+        call. The dispatcher in ``astream_events`` rejects ``stream_mode`` and
+        ``subgraphs`` since v3 owns them (``stream_mode`` is derived from the
+        transformer mux; ``subgraphs`` is always True so nested namespaces
+        flow through scoped muxes).
 
-        Note:
-            Same nesting limitation as `stream_v2`: nesting v1
-            `astream(stream_mode="messages")` inside a node of an
-            `astream_v2` run drops `on_llm_new_token` chunks because
-            the outer v2 handler reroutes `BaseChatModel.invoke`
-            through the v2 event protocol. Use `astream_v2` for the
-            inner graph as well, or call `chat_model.astream(...)`
-            explicitly, to get token-level streaming.
+        !!! warning
 
-        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 classes or configured factories
-                appended after compile-time `stream_transformers`. Factories
-                are called as `factory(scope)` so they can propagate to
-                subgraph scopes.
+            The v3 streaming protocol is experimental and may change.
         """
         parent_ns = _resolve_parent_ns(self.config, config)
         compiled_factories = _normalize_stream_transformer_factories(
@@ -3534,9 +3573,179 @@ class Pregel(
             version="v2",
             interrupt_before=interrupt_before,
             interrupt_after=interrupt_after,
+            control=control,
+            **kwargs,
         ).__aiter__()
         return AsyncGraphRunStream(graph_aiter, mux)
 
+    @overload
+    def stream_events(
+        self,
+        input: InputT | Command | None,
+        config: RunnableConfig | None = None,
+        *,
+        version: Literal["v1", "v2"] = "v2",
+        **kwargs: Any,
+    ) -> Iterator[StreamEvent]: ...
+
+    @overload
+    def stream_events(
+        self,
+        input: InputT | Command | None,
+        config: RunnableConfig | None = None,
+        *,
+        version: Literal["v3"],
+        interrupt_before: All | Sequence[str] | None = None,
+        interrupt_after: All | Sequence[str] | None = None,
+        control: RunControl | None = None,
+        transformers: Sequence[Callable[[tuple[str, ...]], Any]] | None = None,
+        **kwargs: Any,
+    ) -> Any: ...
+
+    def stream_events(
+        self,
+        input: InputT | Command | None,
+        config: RunnableConfig | None = None,
+        *,
+        version: Literal["v1", "v2", "v3"] = "v2",
+        interrupt_before: All | Sequence[str] | None = None,
+        interrupt_after: All | Sequence[str] | None = None,
+        control: RunControl | None = None,
+        transformers: Sequence[Callable[[tuple[str, ...]], Any]] | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Stream events from this graph.
+
+        For `version="v1"` / `"v2"`, yields `StreamEvent` dicts (see
+        `Runnable.stream_events`). For `version="v3"`, returns a
+        `GraphRunStream` whose typed projections the caller drives by
+        iterating — no background thread.
+
+        !!! warning
+
+            The `version="v3"` API is experimental and may change.
+
+        Builds a `StreamMux` from the built-in transformers, this
+        graph's compile-time `stream_transformers`, and any additional
+        `transformers=` supplied at the call site. `run.output`,
+        `run.interrupted`, and `run.interrupts` work regardless of
+        which transformers are registered.
+
+        Note:
+            Nesting v1 `stream(stream_mode="messages")` inside a node
+            of a `stream_events(version="v3")` run is not fully
+            supported. The outer v3 messages handler reroutes
+            `BaseChatModel.invoke` through the v2 event protocol, so
+            the inner v1 handler does not see `on_llm_new_token`
+            chunks. The inner stream still yields a finalized message
+            via `on_llm_end`. Use `stream_events(version="v3")` for the
+            inner graph as well, or call `chat_model.stream(...)`
+            explicitly, to get token-level streaming.
+
+        Args:
+            input: Graph input.
+            config: Optional runnable config.
+            version: Streaming-event schema version. `"v3"` selects the
+                content-block-centric streaming protocol.
+            interrupt_before: Nodes to interrupt before, if any. Only
+                used for `version="v3"`.
+            interrupt_after: Nodes to interrupt after, if any. Only
+                used for `version="v3"`.
+            control: Optional run control used to request cooperative
+                drain. Only used for `version="v3"`.
+            transformers: Extra transformer classes or configured
+                factories appended after compile-time
+                `stream_transformers`. Factories are called as
+                `factory(scope)` so they can propagate to subgraph
+                scopes. Only used for `version="v3"`.
+            **kwargs: For `version="v1"`/`"v2"`, forwarded to
+                `Runnable.stream_events`. For `version="v3"`, forwarded
+                to the underlying `stream(...)` call (e.g. `context`,
+                `durability`, `output_keys`, `print_mode`, `debug`).
+                `stream_mode` and `subgraphs` are not accepted under
+                `version="v3"` and raise `TypeError` if supplied; v3
+                owns them.
+
+        Returns:
+            For `version="v3"`, a `GraphRunStream` the caller iterates
+            to drive the run. Otherwise an `Iterator[StreamEvent]`.
+        """
+        if version == "v3":
+            _reject_v3_invariant_kwargs(kwargs)
+            return self._pregel_stream_v3(
+                input,
+                config,
+                interrupt_before=interrupt_before,
+                interrupt_after=interrupt_after,
+                control=control,
+                transformers=transformers,
+                **kwargs,
+            )
+        return super().stream_events(input, config, version=version, **kwargs)
+
+    @overload
+    def astream_events(
+        self,
+        input: InputT | Command | None,
+        config: RunnableConfig | None = None,
+        *,
+        version: Literal["v1", "v2"] = "v2",
+        **kwargs: Any,
+    ) -> AsyncIterator[StreamEvent]: ...
+
+    @overload
+    def astream_events(
+        self,
+        input: InputT | Command | None,
+        config: RunnableConfig | None = None,
+        *,
+        version: Literal["v3"],
+        interrupt_before: All | Sequence[str] | None = None,
+        interrupt_after: All | Sequence[str] | None = None,
+        control: RunControl | None = None,
+        transformers: Sequence[Callable[[tuple[str, ...]], Any]] | None = None,
+        **kwargs: Any,
+    ) -> Awaitable[Any]: ...
+
+    def astream_events(
+        self,
+        input: InputT | Command | None,
+        config: RunnableConfig | None = None,
+        *,
+        version: Literal["v1", "v2", "v3"] = "v2",
+        interrupt_before: All | Sequence[str] | None = None,
+        interrupt_after: All | Sequence[str] | None = None,
+        control: RunControl | None = None,
+        transformers: Sequence[Callable[[tuple[str, ...]], Any]] | None = None,
+        **kwargs: Any,
+    ) -> AsyncIterator[StreamEvent] | Awaitable[Any]:
+        """Async variant of `stream_events`.
+
+        For `version="v3"`, returns an `AsyncGraphRunStream` whose
+        projections can be awaited concurrently; each subscribed cursor
+        drives the pump when its buffer is empty. The same nesting
+        limitation as the sync path applies — see `stream_events` for
+        details.
+
+        !!! warning
+
+            The `version="v3"` API is experimental and may change.
+
+        See `stream_events` for full argument and return documentation.
+        """
+        if version == "v3":
+            _reject_v3_invariant_kwargs(kwargs)
+            return self._apregel_stream_v3(
+                input,
+                config,
+                interrupt_before=interrupt_before,
+                interrupt_after=interrupt_after,
+                control=control,
+                transformers=transformers,
+                **kwargs,
+            )
+        return super().astream_events(input, config, version=version, **kwargs)
+
     @overload
     def invoke(
         self,
@@ -3550,6 +3759,7 @@ class Pregel(
         interrupt_before: All | Sequence[str] | None = None,
         interrupt_after: All | Sequence[str] | None = None,
         durability: Durability | None = None,
+        control: RunControl | None = None,
         version: Literal["v2"],
         **kwargs: Any,
     ) -> GraphOutput[OutputT]: ...
@@ -3567,6 +3777,7 @@ class Pregel(
         interrupt_before: All | Sequence[str] | None = None,
         interrupt_after: All | Sequence[str] | None = None,
         durability: Durability | None = None,
+        control: RunControl | None = None,
         version: Literal["v2"],
         **kwargs: Any,
     ) -> list[StreamPart[StateT, OutputT]]: ...
@@ -3584,6 +3795,7 @@ class Pregel(
         interrupt_before: All | Sequence[str] | None = None,
         interrupt_after: All | Sequence[str] | None = None,
         durability: Durability | None = None,
+        control: RunControl | None = None,
         version: Literal["v1"] = ...,
         **kwargs: Any,
     ) -> dict[str, Any] | Any: ...
@@ -3600,6 +3812,7 @@ class Pregel(
         interrupt_before: All | Sequence[str] | None = None,
         interrupt_after: All | Sequence[str] | None = None,
         durability: Durability | None = None,
+        control: RunControl | None = None,
         version: Literal["v1", "v2"] = "v1",
         **kwargs: Any,
     ) -> dict[str, Any] | Any:
@@ -3624,6 +3837,7 @@ class Pregel(
                 - `"sync"`: Changes are persisted synchronously before the next step starts.
                 - `"async"`: Changes are persisted asynchronously while the next step executes.
                 - `"exit"`: Changes are persisted only when the graph exits.
+            control: Optional run control used to request cooperative drain.
             version: The streaming format version. `"v1"` (default) returns the
                 traditional format, `"v2"` returns `StreamPart` typed dicts when
                 `stream_mode` is not `"values"`.
@@ -3651,6 +3865,7 @@ class Pregel(
                 interrupt_before=interrupt_before,
                 interrupt_after=interrupt_after,
                 durability=durability,
+                control=control,
                 version=version,
                 **kwargs,
             ):
@@ -3674,6 +3889,7 @@ class Pregel(
                 interrupt_before=interrupt_before,
                 interrupt_after=interrupt_after,
                 durability=durability,
+                control=control,
                 **kwargs,
             ):
                 if stream_mode == "values":
@@ -3720,6 +3936,7 @@ class Pregel(
         interrupt_before: All | Sequence[str] | None = None,
         interrupt_after: All | Sequence[str] | None = None,
         durability: Durability | None = None,
+        control: RunControl | None = None,
         version: Literal["v2"],
         **kwargs: Any,
     ) -> GraphOutput[OutputT]: ...
@@ -3737,6 +3954,7 @@ class Pregel(
         interrupt_before: All | Sequence[str] | None = None,
         interrupt_after: All | Sequence[str] | None = None,
         durability: Durability | None = None,
+        control: RunControl | None = None,
         version: Literal["v2"],
         **kwargs: Any,
     ) -> list[StreamPart[StateT, OutputT]]: ...
@@ -3754,6 +3972,7 @@ class Pregel(
         interrupt_before: All | Sequence[str] | None = None,
         interrupt_after: All | Sequence[str] | None = None,
         durability: Durability | None = None,
+        control: RunControl | None = None,
         version: Literal["v1"] = ...,
         **kwargs: Any,
     ) -> dict[str, Any] | Any: ...
@@ -3770,6 +3989,7 @@ class Pregel(
         interrupt_before: All | Sequence[str] | None = None,
         interrupt_after: All | Sequence[str] | None = None,
         durability: Durability | None = None,
+        control: RunControl | None = None,
         version: Literal["v1", "v2"] = "v1",
         **kwargs: Any,
     ) -> dict[str, Any] | Any:
@@ -3794,6 +4014,7 @@ class Pregel(
                 - `"sync"`: Changes are persisted synchronously before the next step starts.
                 - `"async"`: Changes are persisted asynchronously while the next step executes.
                 - `"exit"`: Changes are persisted only when the graph exits.
+            control: Optional run control used to request cooperative drain.
             version: The streaming format version. `"v1"` (default) returns the
                 traditional format, `"v2"` returns `StreamPart` typed dicts when
                 `stream_mode` is not `"values"`.
@@ -3821,6 +4042,7 @@ class Pregel(
                 interrupt_before=interrupt_before,
                 interrupt_after=interrupt_after,
                 durability=durability,
+                control=control,
                 version=version,
                 **kwargs,
             ):
@@ -3844,6 +4066,7 @@ class Pregel(
                 interrupt_before=interrupt_before,
                 interrupt_after=interrupt_after,
                 durability=durability,
+                control=control,
                 **kwargs,
             ):
                 if stream_mode == "values":
@@ -4017,7 +4240,7 @@ def _resolve_parent_ns(
 ) -> tuple[str, ...]:
     """Return the checkpoint namespace the caller is running under.
 
-    `stream_v2` uses this to scope its native projections
+    `stream_events(version="v3")` uses this to scope its native projections
     (`ValuesTransformer`, `MessagesTransformer`) to events emitted at
     the run's own level. A root call resolves to `()`; a call made
     from inside a node carries the outer graph's task namespace so the

libs/langgraph/langgraph/runtime.py

@@ -16,6 +16,7 @@ from langgraph.typing import ContextT
 __all__ = (
     "BaseUser",
     "ExecutionInfo",
+    "RunControl",
     "Runtime",
     "ServerInfo",
     "get_runtime",
@@ -75,6 +76,34 @@ class ServerInfo:
     """
 
 
+class RunControl:
+    """Run-scoped control surface for cooperative draining.
+
+    Intended for a single graph run. Create a fresh `RunControl` per run;
+    reusing a control after `request_drain()` leaves it drained.
+
+    Safe to call from any thread: the drain request is represented by a
+    single attribute write, so no lock is needed for this signal.
+    If more mutable state is added here, add synchronization.
+    """
+
+    __slots__ = ("_drain_reason",)
+
+    def __init__(self) -> None:
+        self._drain_reason: str | None = None
+
+    def request_drain(self, reason: str = "shutdown") -> None:
+        self._drain_reason = reason
+
+    @property
+    def drain_requested(self) -> bool:
+        return self._drain_reason is not None
+
+    @property
+    def drain_reason(self) -> str | None:
+        return self._drain_reason
+
+
 def _no_op_stream_writer(_: Any) -> None: ...
 
 
@@ -89,6 +118,7 @@ class _RuntimeOverrides(TypedDict, Generic[ContextT], total=False):
     previous: Any
     execution_info: ExecutionInfo
     server_info: ServerInfo | None
+    control: RunControl | None
 
 
 @dataclass(**_DC_KWARGS)
@@ -167,7 +197,7 @@ class Runtime(Generic[ContextT]):
 
     context: ContextT = field(default=None)  # type: ignore[assignment]
     """Static context for the graph run, like `user_id`, `db_conn`, etc.
-    
+
     Can also be thought of as 'run dependencies'."""
 
     store: BaseStore | None = field(default=None)
@@ -188,7 +218,7 @@ class Runtime(Generic[ContextT]):
 
     previous: Any = field(default=None)
     """The previous return value for the given thread.
-    
+
     Only available with the functional API when a checkpointer is provided.
     """
 
@@ -200,6 +230,13 @@ class Runtime(Generic[ContextT]):
     server_info: ServerInfo | None = field(default=None)
     """Metadata injected by LangGraph Server. None when running open-source LangGraph without LangSmith deployments."""
 
+    control: RunControl | None = field(default=None)
+    """Run-scoped control plane for cooperative draining.
+
+    Populated automatically during graph runs. None outside an active
+    graph runtime.
+    """
+
     def merge(self, other: Runtime[ContextT]) -> Runtime[ContextT]:
         """Merge two runtimes together.
 
@@ -217,6 +254,7 @@ class Runtime(Generic[ContextT]):
             previous=self.previous if other.previous is None else other.previous,
             execution_info=other.execution_info or self.execution_info,
             server_info=other.server_info or self.server_info,
+            control=other.control or self.control,
         )
 
     def override(
@@ -235,6 +273,14 @@ class Runtime(Generic[ContextT]):
             execution_info=self.execution_info.patch(**overrides),
         )
 
+    @property
+    def drain_requested(self) -> bool:
+        return self.control.drain_requested if self.control is not None else False
+
+    @property
+    def drain_reason(self) -> str | None:
+        return self.control.drain_reason if self.control is not None else None
+
 
 DEFAULT_RUNTIME = Runtime(
     context=None,
@@ -243,6 +289,7 @@ DEFAULT_RUNTIME = Runtime(
     heartbeat=_no_op_heartbeat,
     previous=None,
     execution_info=None,
+    control=None,
 )
 
 

libs/langgraph/langgraph/stream/__init__.py

@@ -1,7 +1,7 @@
 """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
+Compile a graph with `transformers=[...]` and call `graph.stream_events(version="v3")` /
+`graph.astream_events(version="v3")` to drive a transformer pipeline that projects the
 graph's raw events into ergonomic per-channel streams.
 """
 
@@ -17,9 +17,9 @@ from langgraph.stream.transformers import (
     CheckpointsTransformer,
     CustomTransformer,
     DebugTransformer,
+    LifecycleEvent,
     LifecyclePayload,
     LifecycleTransformer,
-    SubgraphStatus,
     SubgraphTransformer,
     TasksTransformer,
     UpdatesTransformer,
@@ -32,13 +32,13 @@ __all__ = [
     "CustomTransformer",
     "DebugTransformer",
     "GraphRunStream",
+    "LifecycleEvent",
     "LifecyclePayload",
     "LifecycleTransformer",
     "ProtocolEvent",
     "StreamChannel",
     "StreamTransformer",
     "SubgraphRunStream",
-    "SubgraphStatus",
     "SubgraphTransformer",
     "TasksTransformer",
     "UpdatesTransformer",

libs/langgraph/langgraph/stream/_mux.py

@@ -91,9 +91,11 @@ class StreamMux:
         self._assign_seq = _assign_seq
         self._events: StreamChannel[ProtocolEvent] = StreamChannel()
         self._events._bind(is_async=is_async)
+        self._events._bind_mux(self)
         self._transformers: list[StreamTransformer] = []
         self._channels: list[StreamChannel[Any]] = []
         self._seq = 0
+        self._push_seq = 0
 
         self.extensions: dict[str, Any] = {}
         self.native_keys: set[str] = set()
@@ -124,6 +126,10 @@ class StreamMux:
         """Return the transformer that contributed `key` to the projection."""
         return self._transformer_by_key.get(key)
 
+    def _next_push_seq(self) -> int:
+        self._push_seq += 1
+        return self._push_seq
+
     # ------------------------------------------------------------------
     # Pump wiring + mini-mux nesting
     # ------------------------------------------------------------------
@@ -449,6 +455,7 @@ class StreamMux:
         for value in projection.values():
             if isinstance(value, StreamChannel):
                 value._bind(is_async=self.is_async)
+                value._bind_mux(self)
                 self._channels.append(value)
                 if value.name is not None:
                     method = value.name if native else f"custom:{value.name}"

libs/langgraph/langgraph/stream/_types.py

@@ -88,7 +88,7 @@ class StreamTransformer(ABC):
         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 `stream_v2` run requests from the graph.
+            which modes a `stream_events(version="v3")` run requests from the graph.
             Empty tuple means the transformer consumes only synthetic
             events (or is purely passive).
     """

libs/langgraph/langgraph/stream/run_stream.py

@@ -5,12 +5,14 @@ from collections.abc import AsyncIterator, Awaitable, Callable, Iterator, Mappin
 from types import MappingProxyType, TracebackType
 from typing import TYPE_CHECKING, Any
 
+from langchain_core._api import beta
+
 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 SubgraphStatus
+    from langgraph.stream.transformers import LifecycleEvent
 
 
 def _drive_until_done(pump: Callable[[], bool]) -> None:
@@ -25,6 +27,7 @@ async def _adrive_until_done(pump: Callable[[], Awaitable[bool]]) -> None:
         pass
 
 
+@beta(message="The v3 streaming protocol on Pregel is experimental.")
 class GraphRunStream:
     """Sync run stream with caller-driven pumping.
 
@@ -38,6 +41,11 @@ class GraphRunStream:
     All transformer projections live in `extensions`. Native transformer
     projections (those with `_native = True`) are also set as direct
     attributes on this instance (e.g. `run.values`, `run.messages`).
+
+    !!! warning
+
+        Returned by `Pregel.stream_events(version="v3")`, which is
+        experimental and may change.
     """
 
     def __init__(
@@ -185,28 +193,25 @@ class GraphRunStream:
         return iter(self._mux._events)
 
     def interleave(self, *names: str) -> Iterator[tuple[str, Any]]:
-        """Iterate multiple projections round-robin, yielding ``(name, item)``.
+        """Iterate multiple projections in arrival order, 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.
+        Items are ordered by a monotonic push stamp assigned when each
+        transformer pushes into its `StreamChannel`. This gives strict
+        arrival ordering across projections, unlike round-robin.
 
         Args:
             *names: Projection keys to interleave. Must match keys in
                 ``extensions``.
 
         Yields:
-            ``(name, item)`` tuples in round-robin order across the named
+            ``(name, item)`` tuples in arrival order across the named
             projections.
 
+        Each named channel is locked for the duration of iteration and
+        released when the generator completes, is closed, or raises.
+        Channels cannot be subscribed concurrently — use `.tee(n)` if
+        you need fan-out.
+
         Raises:
             KeyError: If a name doesn't match a registered projection.
 
@@ -219,22 +224,73 @@ class GraphRunStream:
                     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)
+        from langgraph.stream.stream_channel import StreamChannel
+
+        channels: dict[str, StreamChannel[Any]] = {}
+        try:
+            for name in names:
+                ch = self.extensions[name]
+                if not isinstance(ch, StreamChannel):
+                    raise TypeError(
+                        f"interleave() requires StreamChannel projections, "
+                        f"got {type(ch).__name__} for {name!r}"
+                    )
+                if ch._is_async is None:
+                    raise TypeError(
+                        f"StreamChannel {name!r} has not been bound yet. "
+                        "Register the transformer with a StreamMux first."
+                    )
+                if ch._is_async:
+                    raise TypeError(
+                        f"StreamChannel {name!r} is bound to async mode — "
+                        "sync interleave() cannot consume async channels."
+                    )
+                if ch._subscribed:
+                    raise RuntimeError(
+                        f"StreamChannel {name!r} already has a subscriber; "
+                        "use .tee(n) for fan-out."
+                    )
+                ch._subscribed = True
+                channels[name] = ch
+
+            done: set[str] = set()
+
+            while len(done) < len(channels):
+                best: tuple[int, str] | None = None
+                for name, ch in channels.items():
+                    if name in done:
+                        continue
+                    if ch._closed and not ch._items:
+                        if ch._error is not None:
+                            raise ch._error
+                        done.add(name)
+                        continue
+                    if ch._items:
+                        stamp = ch._items[0][0]
+                        if best is None or stamp < best[0]:
+                            best = (stamp, name)
+
+                if best is not None:
+                    _stamp, item = channels[best[1]]._items.popleft()
+                    yield (best[1], item)
+                else:
+                    pump = self._mux._pump_fn
+                    if pump is None or not pump():
+                        before = len(done)
+                        for name, ch in channels.items():
+                            if name not in done and not ch._items:
+                                if ch._closed:
+                                    if ch._error is not None:
+                                        raise ch._error
+                                    done.add(name)
+                        if len(done) == before:
+                            break
+        finally:
+            for ch in channels.values():
+                ch._subscribed = False
 
 
+@beta(message="The v3 streaming protocol on Pregel is experimental.")
 class AsyncGraphRunStream:
     """Async run stream with caller-driven pumping.
 
@@ -256,6 +312,11 @@ class AsyncGraphRunStream:
         async for msg in run.messages:
             ...
     ```
+
+    !!! warning
+
+        Awaited from `Pregel.astream_events(version="v3")`, which is
+        experimental and may change.
     """
 
     def __init__(
@@ -462,8 +523,8 @@ class _SubgraphRunStreamMixin:
 
     path: tuple[str, ...]
     graph_name: str | None
-    trigger_call_id: str | None
-    status: SubgraphStatus
+    parent_task_id: str | None
+    status: LifecycleEvent
     error: str | None
     _seen_terminal: bool
 
@@ -477,7 +538,7 @@ class SubgraphRunStream(GraphRunStream, _SubgraphRunStreamMixin):
         *,
         path: tuple[str, ...],
         graph_name: str | None = None,
-        trigger_call_id: str | None = None,
+        parent_task_id: str | None = None,
     ) -> None:
         # Capture the parent-inherited pump before super().__init__
         # touches anything; we delegate to it from `_pump_next`.
@@ -489,7 +550,7 @@ class SubgraphRunStream(GraphRunStream, _SubgraphRunStreamMixin):
         )
         self.path = path
         self.graph_name = graph_name
-        self.trigger_call_id = trigger_call_id
+        self.parent_task_id = parent_task_id
         self.status = "started"
         self.error = None
         self._seen_terminal = False
@@ -520,7 +581,7 @@ class AsyncSubgraphRunStream(AsyncGraphRunStream, _SubgraphRunStreamMixin):
         *,
         path: tuple[str, ...],
         graph_name: str | None = None,
-        trigger_call_id: str | None = None,
+        parent_task_id: str | None = None,
     ) -> None:
         self._parent_apump_fn: Callable[[], Awaitable[bool]] | None = mux._apump_fn
         super().__init__(
@@ -530,7 +591,7 @@ class AsyncSubgraphRunStream(AsyncGraphRunStream, _SubgraphRunStreamMixin):
         )
         self.path = path
         self.graph_name = graph_name
-        self.trigger_call_id = trigger_call_id
+        self.parent_task_id = parent_task_id
         self.status = "started"
         self.error = None
         self._seen_terminal = False

libs/langgraph/langgraph/stream/stream_channel.py

@@ -3,7 +3,10 @@ from __future__ import annotations
 import asyncio
 from collections import deque
 from collections.abc import AsyncIterator, Awaitable, Callable, Iterator
-from typing import Generic, TypeVar
+from typing import TYPE_CHECKING, Generic, TypeVar
+
+if TYPE_CHECKING:
+    from langgraph.stream._mux import StreamMux
 
 T = TypeVar("T")
 
@@ -64,7 +67,7 @@ class StreamChannel(Generic[T]):
         if maxlen is not None and maxlen <= 0:
             raise ValueError("StreamChannel maxlen must be a positive int or None")
         self.name = name
-        self._items: deque[T] = deque()
+        self._items: deque[tuple[int, T]] = deque()
         self._maxlen: int | None = maxlen
         self._closed = False
         self._error: BaseException | None = None
@@ -77,11 +80,15 @@ class StreamChannel(Generic[T]):
         self._arequest_more: Callable[[], Awaitable[bool]] | None = None
 
         self._wire_fn: Callable[[T], None] | None = None
+        self._mux: StreamMux | None = None
 
     # ------------------------------------------------------------------
     # Binding
     # ------------------------------------------------------------------
 
+    def _bind_mux(self, mux: StreamMux) -> None:
+        self._mux = mux
+
     def _bind(self, *, is_async: bool) -> None:
         """Bind this channel to sync or async mode.
 
@@ -117,13 +124,18 @@ class StreamChannel(Generic[T]):
         registered, but auto-forwarding always fires so wired events
         reach the main event log regardless of subscription state.
 
+        Items are stored as `(stamp, item)` tuples where stamp is a
+        monotonic counter from the owning mux. Stamps are stripped by
+        the default cursors; raw stamped tuples are visible on `_items`.
+
         Raises:
             RuntimeError: If the channel is closed (and subscribed).
         """
         if self._subscribed:
             if self._closed:
                 raise RuntimeError("Cannot push to a closed StreamChannel")
-            self._items.append(item)
+            stamp = self._mux._next_push_seq() if self._mux is not None else 0
+            self._items.append((stamp, item))
         if self._wire_fn is not None:
             self._wire_fn(item)
 
@@ -170,7 +182,8 @@ class StreamChannel(Generic[T]):
     def _sync_cursor(self) -> Iterator[T]:
         while True:
             if self._items:
-                yield self._items.popleft()
+                _stamp, item = self._items.popleft()
+                yield item
             elif self._closed:
                 if self._error is not None:
                     raise self._error
@@ -212,7 +225,8 @@ class StreamChannel(Generic[T]):
     async def _async_cursor(self) -> AsyncIterator[T]:
         while True:
             if self._items:
-                yield self._items.popleft()
+                _stamp, item = self._items.popleft()
+                yield item
             elif self._closed:
                 if self._error is not None:
                     raise self._error

libs/langgraph/langgraph/stream/transformers.py

@@ -12,7 +12,7 @@ from langchain_core.messages import AIMessageChunk, BaseMessage
 from langchain_protocol.protocol import MessagesData
 from typing_extensions import NotRequired, TypedDict
 
-from langgraph.errors import GraphInterrupt
+from langgraph.errors import GraphDrained, GraphInterrupt
 from langgraph.stream._types import ProtocolEvent, StreamTransformer
 from langgraph.stream.run_stream import AsyncSubgraphRunStream, SubgraphRunStream
 from langgraph.stream.stream_channel import StreamChannel
@@ -38,8 +38,8 @@ class ValuesTransformer(StreamTransformer):
     Only values events at the run's own level are captured; snapshots
     from deeper subgraphs are left in the main event log but excluded
     from the projection. "Own level" is defined by `scope`, which
-    `stream_v2` / `astream_v2` populate from the caller's
-    checkpoint namespace so that a nested `stream_v2` call still
+    `stream_events(version="v3")` / `astream_events(version="v3")` populate from the caller's
+    checkpoint namespace so that a nested `stream_events(version="v3")` call still
     sees its own root snapshots.
     """
 
@@ -165,7 +165,7 @@ class MessagesTransformer(StreamTransformer):
     metadata)` from `StreamMessagesHandler`):
 
     1. Protocol event (dict with `"event"` key) — emitted by
-       `stream_v2()` / `astream_v2()` via the `on_stream_event`
+       `stream_events(version="v3")` / `astream_events(version="v3")` 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.
@@ -177,15 +177,15 @@ class MessagesTransformer(StreamTransformer):
     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_events(version="v3")` / `astream_events(version="v3")`. Models called via the legacy
     `stream()` method still surface their final `AIMessage` via
     `on_chain_end` when a node returns it as state.
 
     Only events at the run's own level are projected; tokens from
     deeper subgraphs are left in the main event log but excluded from
     `.messages`. "Own level" is defined by `scope`, which
-    `stream_v2` / `astream_v2` populate from the caller's checkpoint
-    namespace so that a `stream_v2` call inside a node still sees its
+    `stream_events(version="v3")` / `astream_events(version="v3")` populate from the caller's checkpoint
+    namespace so that a `stream_events(version="v3")` call inside a node still sees its
     own root chat model streams on `.messages`. Consumers that need
     subgraph tokens should iterate the raw event stream or register a
     custom transformer.
@@ -281,7 +281,7 @@ class MessagesTransformer(StreamTransformer):
         ):
             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
+        # v1 streaming callers must switch to stream_events(version="v3") to populate this
         # projection.
 
         return True
@@ -327,11 +327,31 @@ class MessagesTransformer(StreamTransformer):
         self._by_run.clear()
 
 
-SubgraphStatus = Literal["started", "completed", "failed", "interrupted"]
+LifecycleEvent = Literal["started", "completed", "failed", "interrupted", "drained"]
+"""State transition surfaced on the `lifecycle` channel for a tracked subgraph.
+
+Each value:
+
+- `started` — first `tasks` event observed at the tracked namespace. Carries
+  `graph_name` / `parent_task_id` / optional `metadata` describing what spawned
+  the subgraph.
+- `completed` — the dispatching task's `TaskResultPayload` arrived with neither
+  error nor interrupts. Also emitted by `finalize` for any tracked namespace
+  still open at run end.
+- `failed` — the dispatching task's result carried an `error`, OR the run
+  failed at top level with a non-interrupt / non-drain exception. Carries
+  `error` (string).
+- `interrupted` — the dispatching task's result carried `interrupts` (takes
+  precedence over `error` if both present), OR the run failed with
+  `GraphInterrupt`.
+- `drained` — the run was cooperatively stopped at a superstep boundary via
+  `RunControl.request_drain()` (e.g. SIGTERM). The checkpoint is saved and
+  the run is resumable.
+"""
 
 
 def _parse_ns_segment(segment: str) -> tuple[str, str | None]:
-    """Split a namespace segment into `(graph_name, trigger_call_id)`.
+    """Split a namespace segment into `(graph_name, parent_task_id)`.
 
     Segments are formatted `node_name:task_id` by `prepare_next_tasks`.
     Returns `(segment, None)` if no `:` is present.
@@ -340,6 +360,36 @@ def _parse_ns_segment(segment: str) -> tuple[str, str | None]:
     return name, task_id if sep else None
 
 
+def _extract_dispatching_tool_call_id(payload: Any) -> str | None:
+    """Return the model-side `tool_call_id` from a per-call dispatched task's
+    `input`, or `None` if the payload doesn't match a recognised shape.
+
+    Two shapes are recognised; both are duck-typed so any tool runner
+    that mimics the layout participates without naming any specific
+    dispatcher's types:
+
+    1. Single-element list of tool-call dicts:
+       `[{"id": ..., "name": ..., "args": {...}}]`. The current public
+       shape — `langchain.agents.create_agent` Send-fans this out per
+       pending tool call.
+    2. Dict envelope wrapping a tool call:
+       `{"tool_call": {"id": ..., "args": {...}, ...}, ...}`. Older
+       prebuilt agent paths Send-fan-out this shape.
+    """
+    if isinstance(payload, dict):
+        tool_call = payload.get("tool_call")
+        if not isinstance(tool_call, dict):
+            return None
+    elif (
+        isinstance(payload, list) and len(payload) == 1 and isinstance(payload[0], dict)
+    ):
+        tool_call = payload[0]
+    else:
+        return None
+    raw_id = tool_call.get("id")
+    return raw_id if isinstance(raw_id, str) else None
+
+
 class LifecyclePayload(TypedDict, total=False):
     """Payload of a lifecycle event surfaced on the `lifecycle` channel.
 
@@ -349,11 +399,54 @@ class LifecyclePayload(TypedDict, total=False):
     `run.lifecycle`.
     """
 
-    event: SubgraphStatus
+    event: LifecycleEvent
+    """State transition. See `LifecycleEvent` for per-value semantics."""
     namespace: list[str]
+    """Checkpoint namespace of the subgraph the event is about. Always present.
+
+    A list of `node_name:task_id` segments, one per nesting level (root has
+    `[]`, a direct child of root has `["agent:abc123"]`, a grandchild has
+    `["agent:abc123", "tool:def456"]`, etc.). Stable identity across the
+    `started → terminal` pair for the same subgraph instance.
+    """
     graph_name: NotRequired[str]
-    trigger_call_id: NotRequired[str]
+    """Name of the parent-scope node that dispatched this subgraph
+    (`add_node` name, surrounding tool's name for in-tool invokes,
+    `Send` target name, etc.) — parsed from the namespace tail
+    segment. Absent when the segment has no `:` separator.
+    """
+    parent_task_id: str
+    """Pregel task id of the dispatching task — the task whose execution
+    spawned this subgraph.
+
+    Always present on every event for the same subgraph instance. This is
+    the join key for correlating `started` ↔ terminal events and for
+    matching a `started` back to its `tasks` parent. Each Send produces
+    its own pregel task with its own id, so the join is 1:1 even when a
+    model dispatches multiple parallel tool calls in one turn.
+    """
+    metadata: NotRequired[dict[str, Any]]
+    """Optional generic descriptor of *what triggered* this subgraph.
+    Forwarded by protocol layers as the wire `lifecycle.started.metadata` field.
+
+    Shape:
+
+    - `{"type": "tool_call", "tool_call_id": "<id>"}` — set when the subgraph
+      was triggered by a per-call tool dispatch (a model tool call routed
+      through whatever tool node the agent uses). `tool_call_id` is the
+      model-side id of the originating tool call, exposed so UI consumers
+      can anchor the lifecycle event back to the AI message that dispatched
+      it. The langgraph layer deliberately doesn't mine `args` — those live
+      on the AIMessage's `tool_calls[i].args` already, and consumers that
+      want descriptive intent (subagent type, prompt text, etc.) look it
+      up there to keep one source of truth.
+
+    Absent for structurally-triggered subgraphs (parallel branches via
+    `Send` with non-tool-call payloads, nested `graph.invoke()`, etc.) and
+    for tool dispatches whose envelope carried no `id`.
+    """
     error: NotRequired[str]
+    """Error string. Set on `failed` events; absent otherwise."""
 
 
 class _TasksLifecycleBase(StreamTransformer):
@@ -371,13 +464,13 @@ class _TasksLifecycleBase(StreamTransformer):
 
     - `_should_track(ns)` — scope filter (e.g. multi-depth vs
       direct-children-only).
-    - `_on_started(ns, graph_name, trigger_call_id)` — first sighting
-      action (push payload / build handle / etc.). Called once per
-      discovered namespace.
-    - `_on_terminal(ns, status, error)` — terminal action (push
-      terminal payload / mark handle status). Called once per
-      tracked namespace at result time, or via `finalize` / `fail`
-      sweeps if no parent result arrived.
+    - `_on_started(ns, graph_name, parent_task_id, tool_call_id)` —
+      first sighting action (push payload / build handle / etc.).
+      Called once per discovered namespace.
+    - `_on_terminal(ns, status, error, parent_task_id)` — terminal
+      action (push terminal payload / mark handle status). Called
+      once per tracked namespace at result time, or via `finalize` /
+      `fail` sweeps if no parent result arrived.
 
     Tasks events are suppressed from the main event log (`process`
     returns False) — they're folded into whichever projection the
@@ -390,9 +483,15 @@ class _TasksLifecycleBase(StreamTransformer):
     def __init__(self, scope: tuple[str, ...] = ()) -> None:
         super().__init__(scope)
         self._seen: set[tuple[str, ...]] = set()
-        # Maps tracked namespace -> task_id of the parent task whose
+        # Maps tracked namespace -> task_id of the dispatching task whose
         # `TaskResultPayload` will close it.
         self._open: dict[tuple[str, ...], str] = {}
+        # Maps task_id -> model-side `tool_call_id` for tasks whose `input`
+        # matched a recognized per-call tool-dispatch shape. The lifecycle
+        # hook joins on this when a child subgraph fires its first task
+        # event so it can anchor the lifecycle.started to the originating
+        # AI message tool call.
+        self._dispatching_tool_call_id: dict[str, str] = {}
 
     # --- Template-method hooks (subclass overrides) ---
 
@@ -404,19 +503,33 @@ class _TasksLifecycleBase(StreamTransformer):
         self,
         ns: tuple[str, ...],
         graph_name: str | None,
-        trigger_call_id: str | None,
+        parent_task_id: str | None,
+        tool_call_id: str | None = None,
     ) -> None:
-        """Fired once per discovered namespace (first observed task event)."""
+        """Fired once per discovered namespace (first observed task event).
+
+        `tool_call_id` is the model-side id of the originating tool call
+        (from the per-call dispatched task's `input`). `None` for
+        structurally-triggered subgraphs or per-call envelopes that omitted
+        an `id`. Consumers join on `parent_task_id` (the pregel task id)
+        for identity; `tool_call_id` is purely an anchor back to the AI
+        message that dispatched the subgraph.
+        """
         raise NotImplementedError
 
     def _on_terminal(
         self,
         ns: tuple[str, ...],
-        status: SubgraphStatus,
+        status: LifecycleEvent,
         error: str | None,
+        parent_task_id: str,
     ) -> None:
-        """Fired once per tracked namespace when its parent's result arrives,
-        or via finalize/fail safety-net sweeps.
+        """Fired once per tracked namespace when its dispatching task's
+        result arrives, or via finalize/fail safety-net sweeps.
+
+        `parent_task_id` is the same id paired with the namespace at
+        `_on_started` time, so subscribers can correlate the terminal
+        event back to its `started`.
         """
         raise NotImplementedError
 
@@ -430,59 +543,99 @@ class _TasksLifecycleBase(StreamTransformer):
         if "result" in data:
             self._handle_task_result(ns, data)
         else:
-            self._handle_task_start(ns)
+            self._handle_task_start(ns, data)
         # Tasks events are folded into the synthesized projections;
         # suppress from the main event log so iterators don't double-see
         # the same information in two shapes.
         return False
 
-    def _handle_task_start(self, ns: tuple[str, ...]) -> None:
+    def _handle_task_start(self, ns: tuple[str, ...], data: dict[str, Any]) -> None:
+        # Mine input shape on every tasks event (not just tracked ones)
+        # so we capture dispatching tasks that themselves live outside the
+        # tracked region but whose `id` will appear as `parent_task_id`
+        # for a child subgraph.
+        self._record_dispatching_tool_call_id(data)
         if not self._should_track(ns) or ns in self._seen:
             return
         self._seen.add(ns)
-        graph_name, trigger_call_id = _parse_ns_segment(ns[-1])
-        self._on_started(ns, graph_name or None, trigger_call_id)
-        if trigger_call_id is not None:
-            self._open[ns] = trigger_call_id
+        graph_name, parent_task_id = _parse_ns_segment(ns[-1])
+        tool_call_id = (
+            self._dispatching_tool_call_id.pop(parent_task_id, None)
+            if parent_task_id is not None
+            else None
+        )
+        self._on_started(
+            ns,
+            graph_name or None,
+            parent_task_id,
+            tool_call_id,
+        )
+        if parent_task_id is not None:
+            self._open[ns] = parent_task_id
+
+    def _record_dispatching_tool_call_id(self, data: dict[str, Any]) -> None:
+        """Remember `task_id -> tool_call_id` if the task input matches
+        a recognized per-call tool-dispatch shape.
+
+        Shape detection and id extraction both live in
+        `_extract_dispatching_tool_call_id`; this method just records the
+        mapping under the dispatching task's own `id` so the lifecycle hook
+        can anchor a child subgraph back to the originating AI message
+        tool call when that subgraph's first task event arrives.
+        """
+        task_id = data.get("id")
+        if not isinstance(task_id, str):
+            return
+        tool_call_id = _extract_dispatching_tool_call_id(data.get("input"))
+        if tool_call_id is None:
+            return
+        self._dispatching_tool_call_id[task_id] = tool_call_id
 
     def _pop_terminal_transitions(
         self, ns: tuple[str, ...], data: dict[str, Any]
-    ) -> list[tuple[tuple[str, ...], SubgraphStatus, str | None]]:
-        """Return and remove tracked children closed by this task result."""
+    ) -> list[tuple[tuple[str, ...], LifecycleEvent, str | None, str]]:
+        """Return and remove tracked children closed by this task result.
+
+        Each tuple is `(child_ns, status, error, parent_task_id)`.
+        `parent_task_id` is the dispatching task's id — the same id
+        we'd already paired with the namespace at `_on_started`.
+        """
         result_id = data.get("id")
         if not result_id:
             return []
-        transitions: list[tuple[tuple[str, ...], SubgraphStatus, str | None]] = []
-        for child_ns, parent_task_id in list(self._open.items()):
-            if child_ns[:-1] != ns or parent_task_id != result_id:
+        transitions: list[tuple[tuple[str, ...], LifecycleEvent, str | None, str]] = []
+        for child_ns, dispatching_task_id in list(self._open.items()):
+            if child_ns[:-1] != ns or dispatching_task_id != result_id:
                 continue
             status, error = _terminal_from_result(data)
-            transitions.append((child_ns, status, error))
+            transitions.append((child_ns, status, error, dispatching_task_id))
             del self._open[child_ns]
         return transitions
 
     def _handle_task_result(self, ns: tuple[str, ...], data: dict[str, Any]) -> None:
-        for child_ns, status, error in self._pop_terminal_transitions(ns, data):
-            self._on_terminal(child_ns, status, error)
+        for child_ns, status, error, parent_task_id in self._pop_terminal_transitions(
+            ns, data
+        ):
+            self._on_terminal(child_ns, status, error, parent_task_id)
 
     def finalize(self) -> None:
         """Emit `completed` for any tracked namespace still open at run end."""
-        for ns in list(self._open):
-            self._on_terminal(ns, "completed", None)
+        for ns, parent_task_id in list(self._open.items()):
+            self._on_terminal(ns, "completed", None, parent_task_id)
         self._open.clear()
 
     def fail(self, err: BaseException) -> None:
-        """Emit `failed` / `interrupted` for any tracked namespace still open."""
-        is_interrupt = isinstance(err, GraphInterrupt)
-        status: SubgraphStatus = "interrupted" if is_interrupt else "failed"
-        error_str = None if is_interrupt else str(err)
-        for ns in list(self._open):
-            self._on_terminal(ns, status, error_str)
+        """Emit terminal status for any tracked namespace still open."""
+        status, error_str = _status_from_exception(err)
+        for ns, parent_task_id in list(self._open.items()):
+            self._on_terminal(ns, status, error_str, parent_task_id)
         self._open.clear()
 
 
-def _status_from_exception(err: BaseException) -> tuple[SubgraphStatus, str | None]:
+def _status_from_exception(err: BaseException) -> tuple[LifecycleEvent, str | None]:
     """Map a run exception to a subgraph terminal status and error string."""
+    if isinstance(err, GraphDrained):
+        return "drained", None
     if isinstance(err, GraphInterrupt):
         return "interrupted", None
     return "failed", str(err)
@@ -490,7 +643,7 @@ def _status_from_exception(err: BaseException) -> tuple[SubgraphStatus, str | No
 
 def _terminal_from_result(
     payload: dict[str, Any],
-) -> tuple[SubgraphStatus, str | None]:
+) -> tuple[LifecycleEvent, str | None]:
     """Map a `TaskResultPayload` to a `(status, error)` pair.
 
     Order matters: a result with both `error` and `interrupts` prefers
@@ -539,26 +692,37 @@ class LifecycleTransformer(_TasksLifecycleBase):
         self,
         ns: tuple[str, ...],
         graph_name: str | None,
-        trigger_call_id: str | None,
+        parent_task_id: str | None,
+        tool_call_id: str | None = None,
     ) -> None:
-        if trigger_call_id is None:
-            # Without a task id we can't correlate a parent-result
+        if parent_task_id is None:
+            # Without a task id we can't correlate a dispatching-task-result
             # event back to this namespace — skip the started payload
             # and rely on finalize/fail to close.
             return
-        payload: LifecyclePayload = {"event": "started", "namespace": list(ns)}
+        payload: LifecyclePayload = {
+            "event": "started",
+            "namespace": list(ns),
+            "parent_task_id": parent_task_id,
+        }
         if graph_name:
             payload["graph_name"] = graph_name
-        payload["trigger_call_id"] = trigger_call_id
+        if tool_call_id is not None:
+            payload["metadata"] = {"type": "tool_call", "tool_call_id": tool_call_id}
         self._channel.push(payload)
 
     def _on_terminal(
         self,
         ns: tuple[str, ...],
-        status: SubgraphStatus,
+        status: LifecycleEvent,
         error: str | None,
+        parent_task_id: str,
     ) -> None:
-        payload: LifecyclePayload = {"event": status, "namespace": list(ns)}
+        payload: LifecyclePayload = {
+            "event": status,
+            "namespace": list(ns),
+            "parent_task_id": parent_task_id,
+        }
         if error is not None:
             payload["error"] = error
         self._channel.push(payload)
@@ -611,7 +775,8 @@ class SubgraphTransformer(_TasksLifecycleBase):
         self,
         ns: tuple[str, ...],
         graph_name: str | None,
-        trigger_call_id: str | None,
+        parent_task_id: str | None,
+        tool_call_id: str | None = None,  # noqa: ARG002
     ) -> None:
         if self._mux is None:
             return
@@ -624,7 +789,7 @@ class SubgraphTransformer(_TasksLifecycleBase):
             mux=child_mux,
             path=ns,
             graph_name=graph_name,
-            trigger_call_id=trigger_call_id,
+            parent_task_id=parent_task_id,
         )
         self._handles[ns] = handle
         self._log.push(handle)
@@ -632,8 +797,9 @@ class SubgraphTransformer(_TasksLifecycleBase):
     def _on_terminal(
         self,
         ns: tuple[str, ...],
-        status: SubgraphStatus,
+        status: LifecycleEvent,
         error: str | None,
+        parent_task_id: str,  # noqa: ARG002
     ) -> None:
         handle = self._handles.get(ns)
         if handle is None or not self._mark_terminal(handle, status, error):
@@ -643,8 +809,9 @@ class SubgraphTransformer(_TasksLifecycleBase):
     async def _aon_terminal(
         self,
         ns: tuple[str, ...],
-        status: SubgraphStatus,
+        status: LifecycleEvent,
         error: str | None,
+        parent_task_id: str,  # noqa: ARG002
     ) -> None:
         handle = self._handles.get(ns)
         if handle is None or not self._mark_terminal(handle, status, error):
@@ -654,7 +821,7 @@ class SubgraphTransformer(_TasksLifecycleBase):
     def _mark_terminal(
         self,
         handle: SubgraphRunStream | AsyncSubgraphRunStream,
-        status: SubgraphStatus,
+        status: LifecycleEvent,
         error: str | None,
     ) -> bool:
         """Mark a handle terminal once. Returns True on first transition."""
@@ -669,7 +836,7 @@ class SubgraphTransformer(_TasksLifecycleBase):
     def _close_or_fail_handle(
         self,
         handle: SubgraphRunStream | AsyncSubgraphRunStream,
-        status: SubgraphStatus,
+        status: LifecycleEvent,
         error: str | None,
     ) -> None:
         if handle._mux is None or handle._mux._events._closed:
@@ -682,7 +849,7 @@ class SubgraphTransformer(_TasksLifecycleBase):
     async def _aclose_or_fail_handle(
         self,
         handle: SubgraphRunStream | AsyncSubgraphRunStream,
-        status: SubgraphStatus,
+        status: LifecycleEvent,
         error: str | None,
     ) -> None:
         if handle._mux is None or handle._mux._events._closed:
@@ -721,10 +888,15 @@ class SubgraphTransformer(_TasksLifecycleBase):
             ns = tuple(event["params"]["namespace"])
             data = event["params"]["data"]
             if "result" in data:
-                for child_ns, status, error in self._pop_terminal_transitions(ns, data):
-                    await self._aon_terminal(child_ns, status, error)
+                for (
+                    child_ns,
+                    status,
+                    error,
+                    parent_task_id,
+                ) in self._pop_terminal_transitions(ns, data):
+                    await self._aon_terminal(child_ns, status, error, parent_task_id)
             else:
-                self._handle_task_start(ns)
+                self._handle_task_start(ns, data)
             keep = False
         else:
             keep = True
@@ -736,9 +908,9 @@ class SubgraphTransformer(_TasksLifecycleBase):
 
     def _complete_open_handles(self) -> BaseException | None:
         first_error: BaseException | None = None
-        for ns in list(self._open):
+        for ns, parent_task_id in list(self._open.items()):
             try:
-                self._on_terminal(ns, "completed", None)
+                self._on_terminal(ns, "completed", None, parent_task_id)
             except BaseException as e:
                 if first_error is None:
                     first_error = e
@@ -754,9 +926,9 @@ class SubgraphTransformer(_TasksLifecycleBase):
 
     async def _acomplete_open_handles(self) -> BaseException | None:
         first_error: BaseException | None = None
-        for ns in list(self._open):
+        for ns, parent_task_id in list(self._open.items()):
             try:
-                await self._aon_terminal(ns, "completed", None)
+                await self._aon_terminal(ns, "completed", None, parent_task_id)
             except BaseException as e:
                 if first_error is None:
                     first_error = e

libs/langgraph/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "langgraph"
-version = "1.1.10"
+version = "1.2.0a7"
 description = "Building stateful, multi-actor applications with LLMs"
 authors = []
 requires-python = ">=3.10"
@@ -24,10 +24,10 @@ classifiers = [
     'Programming Language :: Python :: 3.13',
 ]
 dependencies = [
-    "langchain-core>=1.3.2,<2",
-    "langgraph-checkpoint>=2.1.0,<5.0.0",
+    "langchain-core>=1.4.0a2,<2",
+    "langgraph-checkpoint>=4.1.0a4,<5.0.0",
     "langgraph-sdk>=0.3.0,<0.4.0",
-    "langgraph-prebuilt>=1.0.12,<1.1.0",
+    "langgraph-prebuilt>=1.1.0a2,<1.2.0",
     "xxhash>=3.5.0",
     "pydantic>=2.7.4",
 ]

libs/langgraph/tests/test_channels.py

@@ -1,18 +1,33 @@
 import operator
 from collections.abc import Sequence
+from typing import Annotated
 
 import pytest
+from langchain_core.messages import AIMessage, HumanMessage, RemoveMessage
+from langgraph.checkpoint.memory import InMemorySaver
+from langgraph.checkpoint.serde.types import _DeltaSnapshot
+from typing_extensions import NotRequired, TypedDict
 
 from langgraph._internal._typing import MISSING
 from langgraph.channels.binop import BinaryOperatorAggregate
+from langgraph.channels.delta import DeltaChannel
 from langgraph.channels.last_value import LastValue
 from langgraph.channels.topic import Topic
 from langgraph.channels.untracked_value import UntrackedValue
 from langgraph.errors import EmptyChannelError, InvalidUpdateError
+from langgraph.graph import START, StateGraph
+from langgraph.graph.message import _messages_delta_reducer
+from langgraph.graph.state import _get_channel
+from langgraph.types import Overwrite
 
 pytestmark = pytest.mark.anyio
 
 
+# ---------------------------------------------------------------------------
+# Core channel primitives
+# ---------------------------------------------------------------------------
+
+
 def test_last_value() -> None:
     channel = LastValue(int).from_checkpoint(MISSING)
     assert channel.ValueType is int
@@ -95,25 +110,563 @@ def test_untracked_value() -> None:
     assert channel.ValueType is dict
     assert channel.UpdateType is dict
 
-    # UntrackedValue should start empty
     with pytest.raises(EmptyChannelError):
         channel.get()
 
-    # Should be able to update with a value
     test_data = {"session": "test", "temp": "dir"}
     channel.update([test_data])
     assert channel.get() == test_data
 
-    # Update with new value
     new_data = {"session": "updated", "temp": "newdir"}
     channel.update([new_data])
     assert channel.get() == new_data
 
-    # On checkpoint, UntrackedValue should return MISSING
     checkpoint = channel.checkpoint()
     assert checkpoint is MISSING
 
-    # Creating from checkpoint with MISSING should start empty
     new_channel = UntrackedValue(dict).from_checkpoint(checkpoint)
     with pytest.raises(EmptyChannelError):
         new_channel.get()
+
+
+# ---------------------------------------------------------------------------
+# DeltaChannel — message reducer
+# ---------------------------------------------------------------------------
+
+
+def test_delta_channel_basic_two_steps() -> None:
+    ch = DeltaChannel(_messages_delta_reducer, list).from_checkpoint(MISSING)
+
+    ch.update([HumanMessage(content="hi", id="h1")])
+    d1 = ch.checkpoint()
+    assert d1 is MISSING
+
+    ch.update([AIMessage(content="hello", id="a1")])
+    d2 = ch.checkpoint()
+    assert d2 is MISSING
+
+    assert len(ch.get()) == 2
+    assert ch.get()[0].content == "hi"
+    assert ch.get()[1].content == "hello"
+
+
+def test_delta_channel_from_checkpoint_writes_list() -> None:
+    """replay_writes on a fresh channel replays through the operator."""
+    spec = DeltaChannel(_messages_delta_reducer, list)
+    ch = spec.from_checkpoint(MISSING)
+    ch.replay_writes(
+        [
+            ("t0", "messages", HumanMessage(content="hi", id="h1")),
+            ("t1", "messages", AIMessage(content="hello", id="a1")),
+            ("t2", "messages", HumanMessage(content="bye", id="h2")),
+        ]
+    )
+    msgs = ch.get()
+    assert len(msgs) == 3
+    assert msgs[0].content == "hi"
+    assert msgs[1].content == "hello"
+    assert msgs[2].content == "bye"
+
+
+def test_delta_channel_from_checkpoint_backwards_compat() -> None:
+    spec = DeltaChannel(_messages_delta_reducer, list)
+    old_value = [HumanMessage(content="old", id="h1")]
+    ch = spec.from_checkpoint(old_value)
+    assert ch.get() == old_value
+
+
+def test_delta_channel_overwrite() -> None:
+    ch = DeltaChannel(_messages_delta_reducer, list).from_checkpoint(MISSING)
+    ch.update([HumanMessage(content="old", id="h1")])
+
+    ch.update([Overwrite([HumanMessage(content="new", id="h2")])])
+    d = ch.checkpoint()
+    assert d is MISSING
+    assert len(ch.get()) == 1
+    assert ch.get()[0].content == "new"
+
+
+def test_delta_channel_remove_message_and_replay() -> None:
+    """RemoveMessage must round-trip correctly when writes are replayed."""
+    spec = DeltaChannel(_messages_delta_reducer, list)
+    ch = spec.from_checkpoint(MISSING)
+
+    ch.update([HumanMessage(content="hi", id="h1")])
+    ch.update([AIMessage(content="hello", id="a1")])
+    assert ch.get() == [
+        HumanMessage(content="hi", id="h1"),
+        AIMessage(content="hello", id="a1"),
+    ]
+
+    ch.update([RemoveMessage(id="a1")])
+    assert ch.get() == [HumanMessage(content="hi", id="h1")]
+
+    ch2 = spec.from_checkpoint(MISSING)
+    ch2.replay_writes(
+        [
+            ("t0", "messages", HumanMessage(content="hi", id="h1")),
+            ("t1", "messages", AIMessage(content="hello", id="a1")),
+            ("t2", "messages", RemoveMessage(id="a1")),
+        ]
+    )
+    assert ch2.get() == [HumanMessage(content="hi", id="h1")]
+
+
+def test_delta_channel_update_by_id_and_replay() -> None:
+    """Updating a message by ID must round-trip correctly through writes replay."""
+    spec = DeltaChannel(_messages_delta_reducer, list)
+    ch = spec.from_checkpoint(MISSING)
+
+    ch.update([HumanMessage(content="original", id="h1")])
+    ch.update([HumanMessage(content="updated", id="h1")])
+    assert ch.get() == [HumanMessage(content="updated", id="h1")]
+
+    ch2 = spec.from_checkpoint(MISSING)
+    ch2.replay_writes(
+        [
+            ("t0", "messages", HumanMessage(content="original", id="h1")),
+            ("t1", "messages", HumanMessage(content="updated", id="h1")),
+        ]
+    )
+    assert len(ch2.get()) == 1
+    assert ch2.get()[0].content == "updated"
+
+
+def test_delta_channel_dict_coercion() -> None:
+    """_messages_delta_reducer coerces dict writes to BaseMessage objects.
+
+    HTTP-driven input always arrives as JSON dicts.  The reducer must coerce
+    them (same contract as add_messages) so graphs work without a separate
+    coercion step.
+    """
+    ch = DeltaChannel(_messages_delta_reducer, list).from_checkpoint(MISSING)
+
+    # dict input — simulates what arrives from the HTTP API
+    ch.update([{"role": "human", "content": "hello", "id": "h1"}])
+    assert len(ch.get()) == 1
+    assert isinstance(ch.get()[0], HumanMessage)
+    assert ch.get()[0].content == "hello"
+    assert ch.get()[0].id == "h1"
+
+    # update by ID via dict
+    ch.update([{"role": "ai", "content": "world", "id": "h1"}])
+    assert len(ch.get()) == 1
+    assert ch.get()[0].content == "world"
+
+    # remove via RemoveMessage instance (same contract as add_messages)
+    ch.update([RemoveMessage(id="h1")])
+    assert ch.get() == []
+
+
+def test_messages_delta_reducer_coerces_state() -> None:
+    """State (left side) is coerced when raw — supports raw initial input
+    and deserialized blobs. The steady-state path (state already typed)
+    short-circuits and skips coercion.
+    """
+    state = [{"role": "human", "content": "hello", "id": "h1"}]
+    writes = [[{"role": "ai", "content": "world", "id": "h1"}]]
+    result = _messages_delta_reducer(state, writes)  # type: ignore[arg-type]
+    assert len(result) == 1
+    assert isinstance(result[0], AIMessage)
+    assert result[0].content == "world"
+    assert result[0].id == "h1"
+
+
+def test_messages_delta_reducer_tuple_write_is_one_message() -> None:
+    """A top-level tuple write is one message-like, not a sequence to flatten.
+
+    `("user", "hi")` is a valid `MessageLikeRepresentation`; flattening it
+    would produce two HumanMessages ("user", "hi") instead of one.
+    """
+    result = _messages_delta_reducer([], [("user", "hi")])  # type: ignore[arg-type]
+    assert len(result) == 1
+    assert isinstance(result[0], HumanMessage)
+    assert result[0].content == "hi"
+
+
+def test_delta_channel_checkpoint_returns_missing() -> None:
+    """checkpoint() always returns MISSING regardless of state.
+
+    Pregel writes `_DeltaSnapshot(ch.get())` directly into `channel_values`
+    on snapshot steps; the channel itself never participates in snapshot
+    serialization, so its `checkpoint()` is always the absence sentinel.
+    """
+    ch = DeltaChannel(_messages_delta_reducer, list).from_checkpoint(MISSING)
+    assert ch.checkpoint() is MISSING
+
+    ch.update([HumanMessage(content="hi", id="h1")])
+    assert ch.checkpoint() is MISSING
+
+
+# ---------------------------------------------------------------------------
+# DeltaChannel — snapshot frequency
+# ---------------------------------------------------------------------------
+
+
+def test_delta_channel_snapshot_version_based() -> None:
+    """Snapshots fire when a channel accumulates `snapshot_frequency` updates.
+
+    Under the version-delta cadence, every time the channel's
+    `current_version - last_snapshot_version >= snapshot_frequency` a
+    `_DeltaSnapshot` blob is written. Bounds the ancestor walk to at most
+    `snapshot_frequency` steps on any read for that channel.
+    """
+
+    class State(TypedDict):
+        messages: Annotated[
+            list, DeltaChannel(_messages_delta_reducer, snapshot_frequency=5)
+        ]
+        other: str
+
+    def node_a(state: State) -> dict:
+        i = len(state["messages"]) // 2
+        return {"messages": [AIMessage(content=f"a{i}", id=f"a{i}")]}
+
+    def node_b(state: State) -> dict:
+        return {"other": "y"}
+
+    g = StateGraph(State)
+    g.add_node("a", node_a)
+    g.add_node("b", node_b)
+    g.add_edge(START, "a")
+    g.add_edge("a", "b")
+    saver = InMemorySaver()
+    graph = g.compile(checkpointer=saver)
+
+    config = {"configurable": {"thread_id": "t1"}}
+    for i in range(6):
+        graph.invoke(
+            {"messages": [HumanMessage(content=f"h{i}", id=f"h{i}")], "other": ""},
+            config,
+        )
+
+    msg_blob_values = [
+        saver.serde.loads_typed((type_tag, blob))
+        for k, (type_tag, blob) in saver.blobs.items()
+        if k[2] == "messages" and type_tag == "msgpack" and blob
+    ]
+    snapshots = [v for v in msg_blob_values if isinstance(v, _DeltaSnapshot)]
+    assert snapshots, "expected at least one _DeltaSnapshot blob for messages"
+
+    state = graph.get_state(config)
+    assert len(state.values["messages"]) == 12  # 6 human + 6 AI
+
+
+# TODO(delta-channel-cadence): the previous "snapshot fires even when channel
+# was not written" test asserted eager step-based snapshotting; under the new
+# version-delta cadence (`should_snapshot` triggers on per-channel update
+# count, not superstep count), no snapshot fires for an unwritten channel.
+# Replace with a test that exercises the version-delta trigger plus the
+# durability="exit" force-snapshot branch — see
+# `docs/superpowers/specs/2026-05-04-delta-channel-batched-reads-design.md`
+# section "Snapshot cadence".
+
+
+# ---------------------------------------------------------------------------
+# DeltaChannel — end-to-end (InMemorySaver)
+# ---------------------------------------------------------------------------
+
+
+def test_delta_channel_inmemory_saver_assembles_writes() -> None:
+    """InMemorySaver assembles writes from checkpoint_writes inside get_tuple."""
+
+    class State(TypedDict):
+        messages: Annotated[list, DeltaChannel(_messages_delta_reducer, list)]
+
+    n = {"v": 0}
+
+    def respond(state: State) -> dict:
+        n["v"] += 1
+        return {"messages": [AIMessage(content=f"ok{n['v']}", id=f"ai{n['v']}")]}
+
+    builder = StateGraph(State)
+    builder.add_node("respond", respond)
+    builder.add_edge(START, "respond")
+    saver = InMemorySaver()
+    graph = builder.compile(checkpointer=saver)
+    config = {"configurable": {"thread_id": "t1"}}
+
+    graph.invoke({"messages": [HumanMessage(content="hi", id="h1")]}, config)
+    graph.invoke({"messages": [HumanMessage(content="bye", id="h2")]}, config)
+
+    saved = saver.get_tuple(config)
+    assert saved is not None
+    assert "messages" not in saved.checkpoint["channel_values"]
+
+    state = graph.get_state(config)
+    assert len(state.values["messages"]) == 4  # 2 human + 2 AI
+
+
+# ---------------------------------------------------------------------------
+# DeltaChannel — dict reducer
+# ---------------------------------------------------------------------------
+
+
+def _delta_channel_with_type(op, typ):
+    """Build a DeltaChannel with an explicit type via the Annotated injection path."""
+    return _get_channel("_test", Annotated[typ, DeltaChannel(op)])
+
+
+def test_delta_channel_dict_reducer_fresh_channel() -> None:
+    """DeltaChannel with a dict reducer starts as empty dict on MISSING checkpoint."""
+
+    def merge_dicts(state: dict, writes: list) -> dict:
+        result = dict(state)
+        for w in writes:
+            result.update(w)
+        return result
+
+    ch = _delta_channel_with_type(merge_dicts, dict).from_checkpoint(MISSING)
+    assert ch.is_available()
+    assert ch.get() == {}
+
+
+def test_delta_channel_dict_reducer_basic_updates() -> None:
+    """DeltaChannel with a dict reducer accumulates key/value pairs across steps."""
+
+    def merge_dicts(state: dict, writes: list) -> dict:
+        result = dict(state)
+        for w in writes:
+            result.update(w)
+        return result
+
+    ch = _delta_channel_with_type(merge_dicts, dict).from_checkpoint(MISSING)
+
+    ch.update([{"a": 1}])
+    d1 = ch.checkpoint()
+    assert d1 is MISSING
+
+    ch.update([{"b": 2}])
+    d2 = ch.checkpoint()
+    assert d2 is MISSING
+
+    assert ch.get() == {"a": 1, "b": 2}
+
+
+def test_delta_channel_dict_reducer_writes_reconstruction() -> None:
+    """replay_writes on a fresh channel replays through a dict merge reducer."""
+
+    def merge_dicts(state: dict, writes: list) -> dict:
+        result = dict(state)
+        for w in writes:
+            result.update(w)
+        return result
+
+    spec = _delta_channel_with_type(merge_dicts, dict)
+    ch = spec.from_checkpoint(MISSING)
+    ch.replay_writes(
+        [
+            ("t0", "files", {"a": 1}),
+            ("t1", "files", {"b": 2}),
+            ("t2", "files", {"c": 3}),
+        ]
+    )
+    assert ch.get() == {"a": 1, "b": 2, "c": 3}
+
+
+def test_delta_channel_dict_reducer_with_deletions() -> None:
+    """Dict reducer that treats None values as deletions works end-to-end."""
+
+    def merge_files(state: dict, writes: list) -> dict:
+        result = dict(state)
+        for w in writes:
+            for k, v in w.items():
+                if v is None:
+                    result.pop(k, None)
+                else:
+                    result[k] = v
+        return result
+
+    ch = _delta_channel_with_type(merge_files, dict).from_checkpoint(MISSING)
+    ch.update([{"file1.py": "content1", "file2.py": "content2"}])
+    ch.update([{"file1.py": None, "file3.py": "content3"}])
+    assert ch.get() == {"file2.py": "content2", "file3.py": "content3"}
+
+    spec = _delta_channel_with_type(merge_files, dict)
+    ch2 = spec.from_checkpoint(MISSING)
+    ch2.replay_writes(
+        [
+            ("t0", "files", {"file1.py": "content1", "file2.py": "content2"}),
+            ("t1", "files", {"file1.py": None, "file3.py": "content3"}),
+        ]
+    )
+    assert ch2.get() == {"file2.py": "content2", "file3.py": "content3"}
+
+
+def test_delta_channel_dict_reducer_overwrite_in_update() -> None:
+    """Overwrite(dict) in update() must preserve dict shape, not coerce to list."""
+
+    def merge_dicts(state: dict, writes: list) -> dict:
+        result = dict(state)
+        for w in writes:
+            result.update(w)
+        return result
+
+    ch = _delta_channel_with_type(merge_dicts, dict).from_checkpoint(MISSING)
+    ch.update([{"a": 1}])
+    ch.update([Overwrite({"b": 2, "c": 3})])
+    assert ch.get() == {"b": 2, "c": 3}
+
+
+def test_delta_channel_dict_reducer_overwrite_in_writes_replay() -> None:
+    """Overwrite(dict) embedded in replayed writes must reconstruct as dict."""
+
+    def merge_dicts(state: dict, writes: list) -> dict:
+        result = dict(state)
+        for w in writes:
+            result.update(w)
+        return result
+
+    spec = _delta_channel_with_type(merge_dicts, dict)
+    ch = spec.from_checkpoint(MISSING)
+    ch.replay_writes(
+        [
+            ("t0", "files", {"a": 1}),
+            ("t1", "files", Overwrite({"x": 10, "y": 20})),
+            ("t2", "files", {"z": 30}),
+        ]
+    )
+    assert ch.get() == {"x": 10, "y": 20, "z": 30}
+
+
+def test_delta_channel_dict_reducer_with_notrequired_annotation() -> None:
+    """DeltaChannel infers dict type through `Annotated[NotRequired[dict[...]], ch]`."""
+
+    def merge_dicts(state: dict, writes: list) -> dict:
+        result = dict(state)
+        for w in writes:
+            result.update(w)
+        return result
+
+    annotation = Annotated[NotRequired[dict[str, int]], DeltaChannel(merge_dicts)]
+    ch = _get_channel("files", annotation).from_checkpoint(MISSING)
+    assert ch.get() == {}
+    ch.update([{"a": 1}])
+    ch.update([{"b": 2}])
+    assert ch.get() == {"a": 1, "b": 2}
+
+
+def test_delta_channel_dict_reducer_end_to_end_filesystem() -> None:
+    """End-to-end: graph with dict-reducer (filesystem-style) channel wrapped in DeltaChannel."""
+
+    def merge_files(state: dict, writes: list) -> dict:
+        result = dict(state)
+        for w in writes:
+            for k, v in w.items():
+                if v is None:
+                    result.pop(k, None)
+                else:
+                    result[k] = v
+        return result
+
+    class State(TypedDict):
+        files: Annotated[dict[str, str], DeltaChannel(merge_files)]
+
+    turn = {"v": 0}
+
+    def write_file(state: State) -> dict:
+        turn["v"] += 1
+        n = turn["v"]
+        return {"files": {f"/doc_{n}.txt": f"content for turn {n}"}}
+
+    builder = StateGraph(State)
+    builder.add_node("write_file", write_file)
+    builder.add_edge(START, "write_file")
+    saver = InMemorySaver()
+    graph = builder.compile(checkpointer=saver)
+    config = {"configurable": {"thread_id": "fs"}}
+
+    for _ in range(3):
+        graph.invoke({"files": {}}, config)
+
+    saved = saver.get_tuple(config)
+    assert saved is not None
+    assert "files" not in saved.checkpoint["channel_values"]
+    state = graph.get_state(config)
+    assert state.values["files"] == {
+        "/doc_1.txt": "content for turn 1",
+        "/doc_2.txt": "content for turn 2",
+        "/doc_3.txt": "content for turn 3",
+    }
+
+    def delete_file(state: State) -> dict:
+        return {"files": {"/doc_1.txt": None}}
+
+    builder2 = StateGraph(State)
+    builder2.add_node("write_file", write_file)
+    builder2.add_node("delete_file", delete_file)
+    builder2.add_edge(START, "write_file")
+    builder2.add_edge("write_file", "delete_file")
+    turn["v"] = 0
+    saver2 = InMemorySaver()
+    graph2 = builder2.compile(checkpointer=saver2)
+    config2 = {"configurable": {"thread_id": "fs2"}}
+    graph2.invoke({"files": {}}, config2)
+    state2 = graph2.get_state(config2)
+    assert state2.values["files"] == {}
+
+
+def test_delta_channel_dict_reducer_backwards_compat() -> None:
+    """A pre-DeltaChannel dict checkpoint must load as a dict, not be listified."""
+
+    def merge_dicts(state: dict, writes: list) -> dict:
+        result = dict(state)
+        for w in writes:
+            result.update(w)
+        return result
+
+    spec = _delta_channel_with_type(merge_dicts, dict)
+    old_value = {"a": 1, "b": 2}
+    ch = spec.from_checkpoint(old_value)
+    assert ch.get() == {"a": 1, "b": 2}
+
+
+# ---------------------------------------------------------------------------
+# DeltaChannel — seed / pre-delta migration
+# ---------------------------------------------------------------------------
+
+
+def test_delta_channel_from_checkpoint_honors_seed() -> None:
+    """A non-sentinel value to from_checkpoint is used as the pre-delta seed.
+
+    Guards the pre-delta migration path: when the saver's ancestor walk hits
+    a pre-DeltaChannel blob it passes it as `seed` so replay reconstructs
+    the post-migration state correctly rather than replaying from empty.
+    """
+    spec = DeltaChannel(_messages_delta_reducer, list)
+    seed = [HumanMessage(content="pre-delta", id="p1")]
+    ch = spec.from_checkpoint(seed)
+    ch.replay_writes(
+        [
+            ("t0", "messages", AIMessage(content="delta-1", id="d1")),
+            ("t1", "messages", HumanMessage(content="delta-2", id="d2")),
+        ]
+    )
+    msgs = ch.get()
+    assert [m.content for m in msgs] == ["pre-delta", "delta-1", "delta-2"]
+
+
+def test_delta_channel_from_checkpoint_seed_without_writes() -> None:
+    """Reconstruction at a pre-delta ancestor with no newer deltas returns
+    just the seed — the saver's terminator fired immediately."""
+    spec = DeltaChannel(_messages_delta_reducer, list)
+    seed = [HumanMessage(content="only-snap", id="s1")]
+    ch = spec.from_checkpoint(seed)
+    ch.replay_writes([])
+    assert ch.get() == seed
+
+
+def test_delta_channel_from_checkpoint_seed_none_is_distinct_from_sentinel() -> None:
+    """`seed=None` must start replay from None, not from an empty channel.
+
+    The `MISSING` absence sentinel means 'no seed'; passing `None`
+    explicitly should feed None to the reducer as the left operand.
+    """
+
+    def replace(state, writes):
+        return writes[-1] if writes else state
+
+    spec = DeltaChannel(replace, list)
+    ch = spec.from_checkpoint(None)
+    ch.replay_writes([("t0", "x", "after")])
+    assert ch.get() == "after"

libs/langgraph/tests/test_delta_channel_benchmark.py

@@ -0,0 +1,321 @@
+"""Benchmark: DeltaChannel — multi-channel reads, mixed snapshot frequencies.
+
+Run directly:  python tests/test_delta_channel_benchmark.py
+Run via pytest: pytest tests/test_delta_channel_benchmark.py -s
+
+Sweeps `(K delta channels, snapshot_frequency strategy, turn count)` and
+reports per-scenario read latency, write latency, storage, and peak Python
+heap usage during `get_state`.
+
+Scenarios cover the dimensions where this branch's optimizations matter:
+
+  * K-channel batching   — varying K (number of `DeltaChannel`s the graph
+                           reads on hydrate) shows the effect of merging
+                           per-channel reads into a single saver call.
+  * Mixed frequencies    — channels with very different snapshot cadences
+                           in one graph exercise the per-channel chain
+                           bound in stage-2.
+  * Turn count           — chain depth shows how paged stage-1 holds up.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import gc
+import os
+import sys
+import time
+import tracemalloc
+from typing import Annotated, Any
+
+import pytest
+from langchain_core.messages import HumanMessage
+from langgraph.checkpoint.memory import MemorySaver
+from typing_extensions import TypedDict
+
+from langgraph.channels.delta import DeltaChannel
+from langgraph.graph import END, StateGraph
+from langgraph.graph.message import _messages_delta_reducer
+
+try:
+    from langgraph.checkpoint.postgres import PostgresSaver
+
+    _POSTGRES_AVAILABLE = True
+    _POSTGRES_URI = os.environ.get(
+        "LANGGRAPH_BENCH_POSTGRES_URI",
+        "postgres://postgres@localhost:5432/postgres?sslmode=disable",
+    )
+except ImportError:
+    _POSTGRES_AVAILABLE = False
+
+
+# ---------------------------------------------------------------------------
+# Realistic message payload (~100 tokens / ~400 chars each)
+# ---------------------------------------------------------------------------
+
+_HUMAN_TEMPLATE = (
+    "I need help understanding the implications of {topic} on our system "
+    "architecture. Specifically, I'm concerned about how this interacts with "
+    "our existing {concern} and whether we need to refactor the {component} "
+    "layer before proceeding."
+)
+
+_TOPICS = [
+    "distributed tracing",
+    "eventual consistency",
+    "schema migration",
+    "backpressure handling",
+    "idempotency guarantees",
+]
+_CONCERNS = ["concurrency model", "retry semantics", "ordering guarantees"]
+_COMPONENTS = ["persistence", "ingestion", "routing"]
+
+
+def _human_content(i: int) -> str:
+    return _HUMAN_TEMPLATE.format(
+        topic=_TOPICS[i % len(_TOPICS)],
+        concern=_CONCERNS[i % len(_CONCERNS)],
+        component=_COMPONENTS[i % len(_COMPONENTS)],
+    )
+
+
+# ---------------------------------------------------------------------------
+# State / graph factory: K DeltaChannel fields with per-channel freqs
+# ---------------------------------------------------------------------------
+
+
+def _make_state_cls(freqs: list[int]) -> type:
+    """Build a TypedDict with one DeltaChannel per entry in `freqs`."""
+    fields: dict[str, Any] = {}
+    for i, freq in enumerate(freqs):
+        ch = DeltaChannel(_messages_delta_reducer, snapshot_frequency=freq)
+        fields[f"ch{i}"] = Annotated[list, ch]
+    return TypedDict(  # type: ignore[return-value]
+        "_BenchState_" + "-".join(str(f) for f in freqs),
+        fields,
+    )
+
+
+def _make_graph(state_cls: type, K: int, checkpointer: Any = None) -> Any:
+    """Graph: one node, writes a fresh message into every channel each turn."""
+
+    def fanout(state: Any) -> dict[str, Any]:
+        i = max(len(state.get(f"ch{j}", [])) for j in range(K))
+        # Each channel gets its own copy with a unique id so the reducer
+        # does meaningful per-channel state accumulation.
+        return {
+            f"ch{j}": [HumanMessage(content=_human_content(i), id=f"c{j}_{i}")]
+            for j in range(K)
+        }
+
+    g = StateGraph(state_cls)
+    g.add_node("fanout", fanout)
+    g.set_entry_point("fanout")
+    g.add_edge("fanout", END)
+    return g.compile(checkpointer=checkpointer or MemorySaver())
+
+
+# ---------------------------------------------------------------------------
+# Storage / memory measurement
+# ---------------------------------------------------------------------------
+
+
+def _inmemory_blob_bytes(saver: MemorySaver) -> int:
+    return sum(
+        len(blob) for (_, _, _, _), (_, blob) in saver.blobs.items() if blob is not None
+    )
+
+
+def _postgres_storage_bytes(saver: Any, thread_id: str) -> int:
+    """Total bytes across checkpoints / checkpoint_blobs / checkpoint_writes
+    rows for this `thread_id`. Uses `pg_column_size` for an in-row payload
+    estimate; faster than full-table size and scoped to the thread."""
+    sql = """
+    SELECT COALESCE(SUM(pg_column_size(c.*)), 0)
+         + COALESCE((SELECT SUM(pg_column_size(b.*)) FROM checkpoint_blobs b
+                     WHERE b.thread_id = %s), 0)
+         + COALESCE((SELECT SUM(pg_column_size(w.*)) FROM checkpoint_writes w
+                     WHERE w.thread_id = %s), 0)
+         AS total
+    FROM checkpoints c
+    WHERE c.thread_id = %s
+    """
+    with saver._cursor() as cur:
+        cur.execute(sql, (thread_id, thread_id, thread_id))
+        row = cur.fetchone()
+    if row is None:
+        return 0
+    if isinstance(row, dict):
+        return int(row.get("total") or 0)
+    return int(row[0] or 0)
+
+
+def _run_scenario(
+    freqs: list[int],
+    n_turns: int,
+    checkpointer: Any,
+    thread_id: str,
+) -> dict[str, float | int]:
+    """Drive `n_turns` invocations of a K-channel graph, measure
+    write/read/storage/peak-memory."""
+    K = len(freqs)
+    state_cls = _make_state_cls(freqs)
+    graph = _make_graph(state_cls, K, checkpointer)
+    config = {"configurable": {"thread_id": thread_id}}
+
+    # Write phase
+    t0 = time.perf_counter()
+    for i in range(n_turns):
+        graph.invoke({}, config)
+    write_elapsed = time.perf_counter() - t0
+
+    # Read phase + tracemalloc peak across get_state calls
+    gc.collect()
+    tracemalloc.start()
+    t1 = time.perf_counter()
+    for _ in range(5):
+        graph.get_state(config)
+    read_elapsed = (time.perf_counter() - t1) / 5
+    _, peak_bytes = tracemalloc.get_traced_memory()
+    tracemalloc.stop()
+
+    # Storage
+    if isinstance(graph.checkpointer, MemorySaver):
+        storage = _inmemory_blob_bytes(graph.checkpointer)
+    elif _POSTGRES_AVAILABLE and isinstance(graph.checkpointer, PostgresSaver):
+        storage = _postgres_storage_bytes(graph.checkpointer, thread_id)
+    else:
+        storage = -1
+
+    return {
+        "K": K,
+        "turns": n_turns,
+        "write_total_s": write_elapsed,
+        "write_per_invoke_ms": (write_elapsed / n_turns) * 1000,
+        "read_avg_ms": read_elapsed * 1000,
+        "storage_bytes": storage,
+        "peak_mem_bytes": peak_bytes,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Postgres helpers
+# ---------------------------------------------------------------------------
+
+
+@contextlib.contextmanager
+def _pg_saver(thread_id: str):
+    with PostgresSaver.from_conn_string(_POSTGRES_URI) as saver:
+        saver.setup()
+        with saver._cursor() as cur:
+            for tbl in ("checkpoints", "checkpoint_blobs", "checkpoint_writes"):
+                cur.execute(f"DELETE FROM {tbl} WHERE thread_id = %s", (thread_id,))
+        yield saver
+        with saver._cursor() as cur:
+            for tbl in ("checkpoints", "checkpoint_blobs", "checkpoint_writes"):
+                cur.execute(f"DELETE FROM {tbl} WHERE thread_id = %s", (thread_id,))
+
+
+def _checkpointers() -> list[tuple[str, Any]]:
+    result: list[tuple[str, Any]] = [("InMemory", None)]
+    if _POSTGRES_AVAILABLE:
+        try:
+            import psycopg
+
+            psycopg.connect(_POSTGRES_URI).close()
+            result.append(("Postgres", "postgres"))
+        except Exception:
+            pass
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Scenarios
+# ---------------------------------------------------------------------------
+
+SCENARIOS: list[tuple[str, list[int]]] = [
+    ("K=1, freq=50", [50]),
+    ("K=3, freq=50 uniform", [50, 50, 50]),
+    ("K=3, freq=mixed", [50, 200, 1000]),
+    ("K=8, freq=50 uniform", [50] * 8),
+    ("K=8, freq=mixed", [25, 50, 100, 200, 500, 1000, 1000, 1000]),
+]
+
+TURN_COUNTS = [100, 500]
+
+
+def _fmt_bytes(n: int) -> str:
+    if n < 0:
+        return "n/a"
+    if n >= 1_000_000:
+        return f"{n / 1_000_000:.1f} MB"
+    if n >= 1_000:
+        return f"{n / 1_000:.1f} KB"
+    return f"{n} B"
+
+
+def _print_scenario_table(cp_label: str, rows: list[dict]) -> None:
+    print(f"\n  [{cp_label}]")
+    header = (
+        f"  {'scenario':<28}{'turns':>8}{'write_ms':>11}"
+        f"{'read_ms':>10}{'storage':>12}{'peak_mem':>12}"
+    )
+    print(header)
+    print("  " + "-" * (len(header) - 2))
+    for row in rows:
+        print(
+            f"  {row['scenario']:<28}"
+            f"{row['turns']:>8}"
+            f"{row['write_per_invoke_ms']:>10.1f}"
+            f"{row['read_avg_ms']:>10.2f}"
+            f"{_fmt_bytes(row['storage_bytes']):>12}"
+            f"{_fmt_bytes(row['peak_mem_bytes']):>12}"
+        )
+
+
+def run_benchmark() -> list[dict]:
+    """Run the full sweep and return all measurement rows."""
+    all_rows: list[dict] = []
+    for cp_label, cp_hint in _checkpointers():
+        rows: list[dict] = []
+        for scenario_label, freqs in SCENARIOS:
+            for turns in TURN_COUNTS:
+                thread_id = f"bench-{scenario_label.replace(' ', '_')}-{turns}".lower()
+                if cp_hint is None:
+                    saver_ctx: Any = contextlib.nullcontext(None)
+                else:
+                    saver_ctx = _pg_saver(thread_id)
+                with saver_ctx as saver:
+                    measured = _run_scenario(freqs, turns, saver, thread_id)
+                measured["scenario"] = scenario_label
+                measured["saver"] = cp_label
+                rows.append(measured)
+                all_rows.append(measured)
+        _print_scenario_table(cp_label, rows)
+    return all_rows
+
+
+# ---------------------------------------------------------------------------
+# Pytest entry point
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.skip(
+    reason="slow benchmark — run manually with: python tests/test_delta_channel_benchmark.py"
+)
+def test_delta_channel_benchmark(capsys: Any) -> None:
+    """Manual benchmark — see module docstring."""
+    with capsys.disabled():
+        run_benchmark()
+
+
+# ---------------------------------------------------------------------------
+# Script entry point
+# ---------------------------------------------------------------------------
+
+
+if __name__ == "__main__":
+    print("DeltaChannel benchmark — multi-channel reads, mixed frequencies")
+    print("=" * 78)
+    run_benchmark()
+    sys.exit(0)

libs/langgraph/tests/test_delta_channel_exit_mode.py

@@ -0,0 +1,365 @@
+"""Tests for exit-mode delta channel persistence redesign.
+
+Validates that `durability="exit"` correctly persists delta-channel writes
+using count-based snapshot decisions (rather than force-snapshotting every
+channel), lazy stub creation when no parent exists, and proper read-path
+reconstruction via ancestor walks.
+"""
+
+from typing import Annotated, Any
+
+import pytest
+from langchain_core.messages import AIMessage, HumanMessage
+from langgraph.checkpoint.memory import InMemorySaver
+from langgraph.checkpoint.serde.types import _DeltaSnapshot
+from typing_extensions import TypedDict
+
+from langgraph.channels.delta import DeltaChannel
+from langgraph.graph import START, StateGraph
+from langgraph.graph.message import _messages_delta_reducer
+
+pytestmark = pytest.mark.anyio
+
+
+def _build_graph(
+    checkpointer: InMemorySaver,
+    *,
+    freq: int = 1000,
+) -> Any:
+    channel = DeltaChannel(_messages_delta_reducer, snapshot_frequency=freq)
+    # Functional TypedDict form: class form can't reference `channel` (a
+    # local variable) inside Annotated due to forward-ref evaluation rules.
+    State = TypedDict("State", {"messages": Annotated[list, channel]})  # type: ignore[call-overload]  # noqa: UP013
+
+    def respond(state: dict) -> dict:
+        i = len(state["messages"])
+        return {"messages": [AIMessage(content=f"reply-{i}", id=f"ai{i}")]}
+
+    builder = StateGraph(State)
+    builder.add_node("respond", respond)
+    builder.add_edge(START, "respond")
+    return builder.compile(checkpointer=checkpointer)
+
+
+# ---------------------------------------------------------------------------
+# 8a. Write-path / structural tests
+# ---------------------------------------------------------------------------
+
+
+async def test_exit_first_run_no_delta_writes() -> None:
+    """Graph with delta channel invoked with input that doesn't touch it.
+    Only one checkpoint row, no stub."""
+    State = TypedDict(  # noqa: UP013
+        "State",
+        {
+            "messages": Annotated[list, DeltaChannel(_messages_delta_reducer)],
+            "value": str,
+        },
+    )  # type: ignore[call-overload]
+
+    def noop(state: dict) -> dict:
+        return {"value": "done"}
+
+    saver = InMemorySaver()
+    builder = StateGraph(State)
+    builder.add_node("noop", noop)
+    builder.add_edge(START, "noop")
+    graph = builder.compile(checkpointer=saver)
+    config = {"configurable": {"thread_id": "no-delta-writes"}}
+
+    graph.invoke({"value": "start"}, config, durability="exit")
+
+    checkpoints = list(saver.list(config))
+    assert len(checkpoints) == 1
+    stubs = [t for t in checkpoints if t.metadata.get("step") == -2]
+    assert len(stubs) == 0
+
+
+async def test_exit_first_run_all_snapshot() -> None:
+    """snapshot_frequency=1 forces every channel to snapshot.
+    No stub needed; final_checkpoint has _DeltaSnapshot."""
+    saver = InMemorySaver()
+    graph = _build_graph(saver, freq=1)
+    config = {"configurable": {"thread_id": "all-snapshot"}}
+
+    result = graph.invoke(
+        {"messages": [HumanMessage(content="hi", id="h1")]},
+        config,
+        durability="exit",
+    )
+    assert len(result["messages"]) == 2
+
+    checkpoints = list(saver.list(config))
+    stubs = [t for t in checkpoints if t.metadata.get("step") == -2]
+    assert len(stubs) == 0
+
+    head = saver.get_tuple(config)
+    assert head is not None
+    assert isinstance(head.checkpoint["channel_values"].get("messages"), _DeltaSnapshot)
+
+    state = graph.get_state(config)
+    assert [m.content for m in state.values["messages"]] == ["hi", "reply-1"]
+
+
+async def test_exit_first_run_sub_freq_with_writes() -> None:
+    """First run with default snapshot_frequency (1000), writes below threshold.
+    A stub is created; writes are anchored under it; get_state reconstructs."""
+    saver = InMemorySaver()
+    graph = _build_graph(saver)
+    config = {"configurable": {"thread_id": "sub-freq-first"}}
+
+    result = graph.invoke(
+        {"messages": [HumanMessage(content="hello", id="h1")]},
+        config,
+        durability="exit",
+    )
+    assert [m.content for m in result["messages"]] == ["hello", "reply-1"]
+
+    checkpoints = list(saver.list(config))
+    stubs = [t for t in checkpoints if t.metadata.get("step") == -2]
+    assert len(stubs) == 1, f"Expected 1 stub, got {len(stubs)}"
+
+    head = saver.get_tuple(config)
+    assert head is not None
+    assert "messages" not in head.checkpoint["channel_values"]
+    assert "messages" in head.checkpoint["channel_versions"]
+
+    state = graph.get_state(config)
+    assert [m.content for m in state.values["messages"]] == ["hello", "reply-1"]
+
+
+async def test_exit_resumed_run_sub_freq() -> None:
+    """Two consecutive exit runs. Second run anchors on the first's
+    final_checkpoint (no new stub). Ordering preserved."""
+    saver = InMemorySaver()
+    graph = _build_graph(saver)
+    config = {"configurable": {"thread_id": "resumed-sub-freq"}}
+
+    graph.invoke(
+        {"messages": [HumanMessage(content="msg1", id="h1")]},
+        config,
+        durability="exit",
+    )
+
+    graph.invoke(
+        {"messages": [HumanMessage(content="msg2", id="h2")]},
+        config,
+        durability="exit",
+    )
+
+    checkpoints = list(saver.list(config))
+    stubs = [t for t in checkpoints if t.metadata.get("step") == -2]
+    assert len(stubs) == 1
+
+    state = graph.get_state(config)
+    contents = [m.content for m in state.values["messages"]]
+    assert len(contents) == 4
+    assert contents[0] == "msg1"
+    assert contents[2] == "msg2"
+    assert contents[0:4:2] == ["msg1", "msg2"]
+
+
+async def test_exit_count_parity_sync_vs_exit() -> None:
+    """Sync and exit durability produce the same delta_updates_since_snapshot
+    after an equivalent run."""
+    for durability in ("sync", "exit"):
+        saver = InMemorySaver()
+        graph = _build_graph(saver)
+        config = {"configurable": {"thread_id": f"parity-{durability}"}}
+
+        graph.invoke(
+            {"messages": [HumanMessage(content="hi", id="h1")]},
+            config,
+            durability=durability,
+        )
+
+        head = saver.get_tuple(config)
+        assert head is not None
+        counts = head.metadata.get("delta_updates_since_snapshot", {})
+        assert counts.get("messages") == 2, (
+            f"durability={durability}: expected count=2, got {counts}"
+        )
+
+
+async def test_exit_snapshot_fires_at_frequency() -> None:
+    """With snapshot_frequency=3, after 3 exit runs (each incrementing count
+    by 2: input + superstep), the 2nd run hits count=4>=3, triggering snapshot.
+    After that run, count resets to 0 and channel_values has _DeltaSnapshot."""
+    saver = InMemorySaver()
+    graph = _build_graph(saver, freq=3)
+    config = {"configurable": {"thread_id": "snapshot-at-freq"}}
+
+    graph.invoke(
+        {"messages": [HumanMessage(content="m1", id="h1")]},
+        config,
+        durability="exit",
+    )
+    head = saver.get_tuple(config)
+    assert head is not None
+    count1 = head.metadata.get("delta_updates_since_snapshot", {}).get("messages", 0)
+    assert count1 == 2
+
+    graph.invoke(
+        {"messages": [HumanMessage(content="m2", id="h2")]},
+        config,
+        durability="exit",
+    )
+    head = saver.get_tuple(config)
+    assert head is not None
+    count2 = head.metadata.get("delta_updates_since_snapshot", {}).get("messages", 0)
+    assert count2 == 0, f"Expected reset to 0 after snapshot, got {count2}"
+    assert isinstance(head.checkpoint["channel_values"].get("messages"), _DeltaSnapshot)
+
+
+async def test_exit_mixed_snapshot_and_non_snapshot() -> None:
+    """One delta channel at freq=1 (always snapshot) and one at freq=1000
+    (never snapshot within this test). Verify correct behavior for both."""
+
+    fast_ch = DeltaChannel(_messages_delta_reducer, snapshot_frequency=1)
+    slow_ch = DeltaChannel(_messages_delta_reducer, snapshot_frequency=1000)
+    State = TypedDict(  # noqa: UP013
+        "State",
+        {"fast": Annotated[list, fast_ch], "slow": Annotated[list, slow_ch]},
+    )  # type: ignore[call-overload]
+
+    def respond(state: dict) -> dict:
+        return {
+            "fast": [AIMessage(content="fast-reply", id="f1")],
+            "slow": [AIMessage(content="slow-reply", id="s1")],
+        }
+
+    saver = InMemorySaver()
+    builder = StateGraph(State)
+    builder.add_node("respond", respond)
+    builder.add_edge(START, "respond")
+    graph = builder.compile(checkpointer=saver)
+    config = {"configurable": {"thread_id": "mixed-freq"}}
+
+    graph.invoke(
+        {
+            "fast": [HumanMessage(content="fast-in", id="fi")],
+            "slow": [HumanMessage(content="slow-in", id="si")],
+        },
+        config,
+        durability="exit",
+    )
+
+    head = saver.get_tuple(config)
+    assert head is not None
+    assert isinstance(head.checkpoint["channel_values"].get("fast"), _DeltaSnapshot)
+    assert "slow" not in head.checkpoint["channel_values"]
+
+    state = graph.get_state(config)
+    assert [m.content for m in state.values["fast"]] == ["fast-in", "fast-reply"]
+    assert [m.content for m in state.values["slow"]] == ["slow-in", "slow-reply"]
+
+
+# ---------------------------------------------------------------------------
+# 8b. Read-path tests
+# ---------------------------------------------------------------------------
+
+
+async def test_exit_multi_run_replay_chain() -> None:
+    """K=4 consecutive exit runs, each adding a message. After each run,
+    get_state returns all messages in chronological order."""
+    saver = InMemorySaver()
+    graph = _build_graph(saver)
+    config = {"configurable": {"thread_id": "replay-chain"}}
+
+    for i in range(4):
+        graph.invoke(
+            {"messages": [HumanMessage(content=f"user-{i}", id=f"h{i}")]},
+            config,
+            durability="exit",
+        )
+
+        state = graph.get_state(config)
+        contents = [m.content for m in state.values["messages"]]
+        user_msgs = [c for c in contents if c.startswith("user-")]
+        assert user_msgs == [f"user-{j}" for j in range(i + 1)], (
+            f"After run {i}: user messages out of order: {user_msgs}"
+        )
+        assert len(contents) == (i + 1) * 2
+
+
+async def test_exit_metadata_round_trip() -> None:
+    """K=5 consecutive exit runs with snapshot_frequency=5. Verify metadata
+    delta_updates_since_snapshot increments correctly across runs."""
+    freq = 5
+    saver = InMemorySaver()
+    graph = _build_graph(saver, freq=freq)
+    config = {"configurable": {"thread_id": "metadata-rt"}}
+
+    for i in range(1, 6):
+        graph.invoke(
+            {"messages": [HumanMessage(content=f"m{i}", id=f"h{i}")]},
+            config,
+            durability="exit",
+        )
+        head = saver.get_tuple(config)
+        assert head is not None
+        count = head.metadata.get("delta_updates_since_snapshot", {}).get("messages", 0)
+        cumulative = i * 2
+        if cumulative >= freq:
+            assert count == 0 or count == cumulative % freq or count < freq, (
+                f"After run {i}: count={count} should have reset or be partial"
+            )
+        else:
+            assert count == cumulative, (
+                f"After run {i}: expected {cumulative}, got {count}"
+            )
+
+
+async def test_exit_mixed_durability_round_trip() -> None:
+    """Alternate sync and exit durability; verify counts stay monotonic
+    and state accumulates correctly."""
+    saver = InMemorySaver()
+    graph = _build_graph(saver)
+    config = {"configurable": {"thread_id": "mixed-durability"}}
+
+    for i, dur in enumerate(["sync", "exit", "sync", "exit"]):
+        graph.invoke(
+            {"messages": [HumanMessage(content=f"msg-{i}", id=f"h{i}")]},
+            config,
+            durability=dur,
+        )
+
+        state = graph.get_state(config)
+        contents = [m.content for m in state.values["messages"]]
+        user_msgs = [c for c in contents if c.startswith("msg-")]
+        assert user_msgs == [f"msg-{j}" for j in range(i + 1)], (
+            f"After run {i} (durability={dur}): {user_msgs}"
+        )
+        assert len(contents) == (i + 1) * 2
+
+
+async def test_exit_snapshot_then_tail_deltas() -> None:
+    """Run 1 forces snapshot (freq=1). Run 2 at freq=1000 adds more writes
+    that don't snapshot. Reading after run 2 must combine the snapshot seed
+    with the tail deltas."""
+    saver = InMemorySaver()
+
+    graph1 = _build_graph(saver, freq=1)
+    config = {"configurable": {"thread_id": "snapshot-then-tail"}}
+    graph1.invoke(
+        {"messages": [HumanMessage(content="seed-msg", id="h1")]},
+        config,
+        durability="exit",
+    )
+
+    head = saver.get_tuple(config)
+    assert head is not None
+    assert isinstance(head.checkpoint["channel_values"].get("messages"), _DeltaSnapshot)
+
+    graph2 = _build_graph(saver, freq=1000)
+    graph2.invoke(
+        {"messages": [HumanMessage(content="tail-msg", id="h2")]},
+        config,
+        durability="exit",
+    )
+
+    state = graph2.get_state(config)
+    contents = [m.content for m in state.values["messages"]]
+    assert "seed-msg" in contents
+    assert "tail-msg" in contents
+    assert contents.index("seed-msg") < contents.index("tail-msg")

libs/langgraph/tests/test_delta_channel_migration.py

@@ -0,0 +1,618 @@
+"""Tests for the BinaryOperatorAggregate -> DeltaChannel migration path.
+
+A thread written under `BinaryOperatorAggregate(...)` must keep working
+after its annotation is swapped to `DeltaChannel(...)` on the same
+checkpointer — pre-migration state visible at each *settled* ancestor
+checkpoint is preserved, and post-migration writes fold on top through
+the reducer.
+
+Mechanism under test: the saver's public `get_delta_channel_history(config,
+channels)` walks the parent chain; when it encounters an ancestor whose
+`channel_values[channel]` is a real value, it populates that channel's
+`seed` in the returned `DeltaChannelHistory`. If the walk reaches the root
+without finding a stored value, the `seed` key is omitted (TypedDict
+absence indicates "start empty"). `DeltaChannel.from_checkpoint(seed)`
+uses it as the base value, and `replay_writes(writes)` folds on-path
+deltas.
+
+Scenarios covered:
+
+1. **Basic migration (sync + async)**: build pre-migration state with
+   `BinaryOperatorAggregate`, swap the annotation to `DeltaChannel` on
+   the same checkpointer, and verify that every settled pre-migration
+   super-step boundary (`next=('__start__',)`) round-trips exactly
+   under the delta-channel view.
+2. **Time travel into a pre-migration checkpoint** after migration —
+   `graph.get_state(pre_migration_config)` at a settled ancestor
+   returns the same state as under the binop channel.
+3. **Continuing a migrated thread**: driving one more super-step after
+   migration produces a state that includes the pre-migration settled
+   prefix plus the new delta write — proving `from_checkpoint(seed)` +
+   `replay_writes` correctly fold post-migration deltas onto the
+   pre-migration seed.
+4. **Base-saver fallback path**: a third-party-style subclass that
+   removes the optimized `InMemorySaver` override and falls back to
+   `BaseCheckpointSaver.get_delta_channel_history` must produce the same
+   result as the optimized path.
+5. **Channel-type isolation across threads**: two threads on the same
+   checkpointer under the delta-channel graph — one freshly-started,
+   one migrated from pre-migration state — don't cross-contaminate.
+   The parent-chain walk is scoped to the thread.
+
+TODO: add postgres variants in the existing `libs/checkpoint-postgres`
+test files (different fixture setup; not this file).
+"""
+
+from __future__ import annotations
+
+import operator
+from typing import Annotated, Any
+
+import pytest
+from langchain_core.messages import AIMessage, HumanMessage
+from langgraph.checkpoint.memory import InMemorySaver
+from typing_extensions import TypedDict
+
+from langgraph.channels.binop import BinaryOperatorAggregate
+from langgraph.channels.delta import DeltaChannel
+from langgraph.graph import END, START, StateGraph
+from langgraph.graph.message import _messages_delta_reducer, add_messages
+
+pytestmark = pytest.mark.anyio
+
+
+# ---------------------------------------------------------------------------
+# Graph factories
+#
+# A minimal reducer (`operator.add` on lists of str) with a noop node keeps
+# state change localized to the HumanMessage-like payload passed through
+# `invoke`. That isolates the pre/post-migration parity assertions to
+# channel-hydration semantics.
+# ---------------------------------------------------------------------------
+
+
+def _noop(_state: Any) -> dict:
+    return {}
+
+
+def _list_concat(state: list, writes: list) -> list:
+    result = list(state)
+    for w in writes:
+        result.extend(w if isinstance(w, list) else [w])
+    return result
+
+
+def _binop_graph(checkpointer: Any) -> Any:
+    class BinopState(TypedDict):
+        items: Annotated[list, BinaryOperatorAggregate(list, operator.add)]
+
+    return (
+        StateGraph(BinopState)
+        .add_node("noop", _noop)
+        .add_edge(START, "noop")
+        .add_edge("noop", END)
+        .compile(checkpointer=checkpointer)
+    )
+
+
+def _delta_graph(checkpointer: Any) -> Any:
+    class DeltaState(TypedDict):
+        items: Annotated[list, DeltaChannel(_list_concat)]
+
+    return (
+        StateGraph(DeltaState)
+        .add_node("noop", _noop)
+        .add_edge(START, "noop")
+        .add_edge("noop", END)
+        .compile(checkpointer=checkpointer)
+    )
+
+
+def _drive(graph: Any, config: dict, tag: str, n: int) -> None:
+    for i in range(n):
+        graph.invoke({"items": [f"{tag}{i}"]}, config)
+
+
+async def _adrive(graph: Any, config: dict, tag: str, n: int) -> None:
+    for i in range(n):
+        await graph.ainvoke({"items": [f"{tag}{i}"]}, config)
+
+
+def _settled_boundaries(history: list) -> list[tuple[dict, list]]:
+    """Return `[(config, items), ...]` for every checkpoint in `history`
+    whose `next == ('__start__',)` — the stable boundaries between invokes.
+    """
+    return [
+        (s.config, list(s.values.get("items", [])))
+        for s in history
+        if s.next == ("__start__",)
+    ]
+
+
+# ---------------------------------------------------------------------------
+# 1. Basic migration (sync + async)
+# ---------------------------------------------------------------------------
+
+
+def test_basic_migration_preserves_pre_migration_state() -> None:
+    """Build state under `BinaryOperatorAggregate`, migrate to
+    `DeltaChannel` on the same checkpointer, and verify that every
+    settled pre-migration super-step boundary round-trips exactly.
+
+    Settled boundaries (`next=('__start__',)`) are the stable hydration
+    targets for the migration path: writes that produced the NEXT
+    super-step are kept as `pending_writes` on the ancestor, so walking
+    from a descendant finds the ancestor's blob as the seed and
+    reconstructs the correct state.
+    """
+
+    checkpointer = InMemorySaver()
+    config = {"configurable": {"thread_id": "basic-sync"}}
+
+    # Pre-migration: accumulate items across 3 invokes.
+    binop = _binop_graph(checkpointer)
+    _drive(binop, config, "u", 3)
+
+    pre_boundaries = _settled_boundaries(list(binop.get_state_history(config)))
+    assert len(pre_boundaries) >= 2, "expected multiple settled boundaries"
+
+    # Migrate: swap the annotation on the same checkpointer.
+    delta = _delta_graph(checkpointer)
+
+    for cfg, items in pre_boundaries:
+        snap = delta.get_state(cfg)
+        assert list(snap.values.get("items", [])) == items, (
+            f"snapshot mismatch at {cfg['configurable']['checkpoint_id']}: "
+            f"expected {items}, got {snap.values.get('items', [])}"
+        )
+
+
+async def test_basic_migration_preserves_pre_migration_state_async() -> None:
+    """Async variant of the basic migration scenario."""
+
+    checkpointer = InMemorySaver()
+    config = {"configurable": {"thread_id": "basic-async"}}
+
+    binop = _binop_graph(checkpointer)
+    await _adrive(binop, config, "u", 3)
+
+    pre_history = [s async for s in binop.aget_state_history(config)]
+    pre_boundaries = _settled_boundaries(pre_history)
+    assert len(pre_boundaries) >= 2
+
+    delta = _delta_graph(checkpointer)
+
+    for cfg, items in pre_boundaries:
+        snap = await delta.aget_state(cfg)
+        assert list(snap.values.get("items", [])) == items, (
+            f"async snapshot mismatch at {cfg['configurable']['checkpoint_id']}"
+        )
+
+
+# ---------------------------------------------------------------------------
+# 2. Time travel into a pre-migration checkpoint after migration
+# ---------------------------------------------------------------------------
+
+
+def test_time_travel_into_pre_migration_checkpoint() -> None:
+    """After migration, `graph.get_state(pre_migration_config)` at a
+    settled ancestor returns the state as stored at that point."""
+
+    checkpointer = InMemorySaver()
+    config = {"configurable": {"thread_id": "time-travel"}}
+
+    binop = _binop_graph(checkpointer)
+    _drive(binop, config, "u", 3)
+
+    pre_boundaries = _settled_boundaries(list(binop.get_state_history(config)))
+    assert pre_boundaries, "no settled ancestors to time-travel to"
+
+    delta = _delta_graph(checkpointer)
+
+    # Pick the oldest non-empty boundary — a long distance to walk back.
+    non_empty = [(cfg, items) for cfg, items in pre_boundaries if items]
+    assert non_empty, "expected at least one non-empty boundary"
+    target_cfg, expected_items = non_empty[-1]
+
+    snap = delta.get_state(target_cfg)
+    assert list(snap.values.get("items", [])) == expected_items
+
+
+# ---------------------------------------------------------------------------
+# 3. Continuing a migrated thread: deltas fold onto pre-migration seed
+# ---------------------------------------------------------------------------
+
+
+def test_continuing_migrated_thread_folds_deltas_on_seed() -> None:
+    """Resume a pre-migration settled ancestor via `invoke(None, cfg)`
+    under the delta-channel graph. Since the pre-migration checkpoint
+    has an existing `pending_writes` entry (the input for the NEXT
+    super-step), re-running from that ancestor reproduces the same
+    post-ancestor state as the original binop run.
+
+    This proves the seed-terminator + write-replay pipeline works
+    end-to-end across the migration boundary.
+    """
+
+    checkpointer = InMemorySaver()
+    config = {"configurable": {"thread_id": "continue"}}
+
+    binop = _binop_graph(checkpointer)
+    _drive(binop, config, "u", 2)
+
+    # Pick the oldest settled boundary with non-empty state.
+    pre_boundaries = _settled_boundaries(list(binop.get_state_history(config)))
+    target_cfg, seed_items = next(
+        (cfg, items) for cfg, items in reversed(pre_boundaries) if items
+    )
+    assert seed_items, "need a non-empty seed boundary"
+
+    # Migrate and resume from the pre-migration ancestor. `invoke(None,
+    # cfg)` replays the pending writes staged at `cfg` under the new
+    # channel; the reducer folds those deltas onto the seed.
+    delta = _delta_graph(checkpointer)
+    result = delta.invoke(None, target_cfg)
+
+    # The resumed state must include the pre-migration seed items in order.
+    result_items = list(result.get("items", []))
+    for idx, prefix_item in enumerate(seed_items):
+        assert result_items[idx] == prefix_item, (
+            f"pre-migration seed item at {idx} not preserved: "
+            f"got {result_items[: idx + 1]}, expected {seed_items}"
+        )
+
+
+# ---------------------------------------------------------------------------
+# 4. Base-saver fallback path
+# ---------------------------------------------------------------------------
+
+
+class _ThirdPartyStyleSaver(InMemorySaver):
+    """Simulates a third-party saver that inherits the reference
+    `get_delta_channel_history` implementation from `BaseCheckpointSaver`
+    rather than overriding it.
+
+    We rebind the two methods to the base-class versions (via MRO) so
+    the fallback path is exercised even though the storage layer is
+    still the in-memory one.
+    """
+
+    # MRO: [_ThirdPartyStyleSaver, InMemorySaver, BaseCheckpointSaver, ...]
+    get_delta_channel_history = (  # type: ignore[assignment]
+        InMemorySaver.__mro__[1].get_delta_channel_history  # type: ignore[attr-defined]
+    )
+    aget_delta_channel_history = (  # type: ignore[assignment]
+        InMemorySaver.__mro__[1].aget_delta_channel_history  # type: ignore[attr-defined]
+    )
+
+
+def test_base_saver_fallback_matches_optimized_override() -> None:
+    """The reference `BaseCheckpointSaver` implementation must produce
+    the same migration behavior as the optimized `InMemorySaver`
+    override. We drive the same migration scenario through both savers
+    and assert per-snapshot parity in the delta-channel view."""
+
+    # Fast path: optimized InMemorySaver override.
+    fast_saver = InMemorySaver()
+    fast_config = {"configurable": {"thread_id": "fast"}}
+    fast_binop = _binop_graph(fast_saver)
+    _drive(fast_binop, fast_config, "u", 3)
+    fast_delta = _delta_graph(fast_saver)
+    fast_history = [
+        (s.next, list(s.values.get("items", [])))
+        for s in fast_delta.get_state_history(fast_config)
+    ]
+
+    # Slow path: base-class fallback.
+    slow_saver = _ThirdPartyStyleSaver()
+    slow_config = {"configurable": {"thread_id": "slow"}}
+    slow_binop = _binop_graph(slow_saver)
+    _drive(slow_binop, slow_config, "u", 3)
+    slow_delta = _delta_graph(slow_saver)
+    slow_history = [
+        (s.next, list(s.values.get("items", [])))
+        for s in slow_delta.get_state_history(slow_config)
+    ]
+
+    assert slow_history == fast_history, (
+        "base-saver fallback should match optimized-override behavior; "
+        f"fast={fast_history}, slow={slow_history}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# 5. Thread isolation under mixed-generation storage
+# ---------------------------------------------------------------------------
+
+
+def test_delta_and_migrated_threads_do_not_cross_contaminate() -> None:
+    """Two threads sharing a checkpointer — one migrated from
+    pre-migration state, one freshly-started under DeltaChannel — must
+    maintain independent state. The parent-chain walk in
+    `get_delta_channel_history` must be scoped to the target thread.
+    """
+
+    checkpointer = InMemorySaver()
+    migrated_cfg = {"configurable": {"thread_id": "migrated"}}
+    fresh_cfg = {"configurable": {"thread_id": "fresh"}}
+
+    # Thread A: pre-migration build-up.
+    binop = _binop_graph(checkpointer)
+    _drive(binop, migrated_cfg, "m", 2)
+
+    # Thread B: fresh delta-channel run.
+    delta = _delta_graph(checkpointer)
+    _drive(delta, fresh_cfg, "f", 2)
+
+    # Thread A: migrate and confirm its state is anchored in its own
+    # thread's pre-migration history (tag 'm'), never mixing in tag 'f'.
+    migrated_boundaries = _settled_boundaries(
+        list(delta.get_state_history(migrated_cfg))
+    )
+    assert migrated_boundaries, "migrated thread has no settled boundaries"
+    for _, items in migrated_boundaries:
+        for it in items:
+            assert it.startswith("m"), (
+                f"migrated thread leaked item from other thread: {it}"
+            )
+
+    # Thread B: settled boundaries must only contain 'f' tags.
+    fresh_boundaries = _settled_boundaries(list(delta.get_state_history(fresh_cfg)))
+    assert fresh_boundaries, "fresh thread has no settled boundaries"
+    for _, items in fresh_boundaries:
+        for it in items:
+            assert it.startswith("f"), (
+                f"fresh thread leaked item from migrated thread: {it}"
+            )
+
+
+# ---------------------------------------------------------------------------
+# 6. Tip-of-pre-migration hydration: the latest checkpoint from a binop-run
+# thread has a real accumulated value in its own `channel_values["items"]`.
+# When hydrated under the delta-channel graph via `get_state(config)` with no
+# `checkpoint_id`, the short-circuit must use that value directly instead of
+# walking ancestors (which would skip the tip's own blob).
+# ---------------------------------------------------------------------------
+
+
+def test_tip_of_pre_migration_hydrates_directly() -> None:
+    """`graph.get_state(config)` at the latest (pre-migration) checkpoint
+    returns the full accumulated list stored in that checkpoint's own
+    `channel_values`. The hydration must not walk ancestors past it."""
+
+    checkpointer = InMemorySaver()
+    config = {"configurable": {"thread_id": "tip-sync"}}
+
+    binop = _binop_graph(checkpointer)
+    _drive(binop, config, "u", 3)
+
+    binop_tip = binop.get_state(config)
+    expected_items = list(binop_tip.values.get("items", []))
+    assert expected_items == ["u0", "u1", "u2"], (
+        f"sanity: pre-migration tip should accumulate all 3 items, got {expected_items}"
+    )
+
+    delta = _delta_graph(checkpointer)
+
+    snap = delta.get_state(config)
+    assert list(snap.values.get("items", [])) == expected_items, (
+        f"tip hydration mismatch: expected {expected_items}, "
+        f"got {snap.values.get('items', [])}"
+    )
+
+
+async def test_tip_of_pre_migration_hydrates_directly_async() -> None:
+    """Async variant of the tip-of-pre-migration hydration scenario."""
+
+    checkpointer = InMemorySaver()
+    config = {"configurable": {"thread_id": "tip-async"}}
+
+    binop = _binop_graph(checkpointer)
+    await _adrive(binop, config, "u", 3)
+
+    binop_tip = await binop.aget_state(config)
+    expected_items = list(binop_tip.values.get("items", []))
+    assert expected_items == ["u0", "u1", "u2"]
+
+    delta = _delta_graph(checkpointer)
+
+    snap = await delta.aget_state(config)
+    assert list(snap.values.get("items", [])) == expected_items, (
+        f"async tip hydration mismatch: expected {expected_items}, "
+        f"got {snap.values.get('items', [])}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# 7. `update_state` after migration writes a real value to the new
+# checkpoint's `channel_values` (not a sentinel). Hydration must use it
+# directly — the ancestor walk would skip this blob and return stale state.
+# ---------------------------------------------------------------------------
+
+
+def test_update_state_after_migration_uses_written_value() -> None:
+    """After migrating and running at least one post-migration super-step
+    (so the thread's tip has its delta channel absent from `channel_values`,
+    or stored as a `_DeltaSnapshot` on a snapshot step), `update_state`
+    writes a concrete value into a new checkpoint's `channel_values`.
+    `get_state` must reflect that concrete value."""
+
+    checkpointer = InMemorySaver()
+    config = {"configurable": {"thread_id": "update-state"}}
+
+    # Pre-migration: accumulate a little state.
+    binop = _binop_graph(checkpointer)
+    _drive(binop, config, "u", 2)
+
+    # Migrate and run one more super-step so the tip is a post-migration
+    # checkpoint where the delta channel is absent from `channel_values`
+    # (no snapshot fired this step).
+    delta = _delta_graph(checkpointer)
+    delta.invoke({"items": ["post"]}, config)
+
+    # `update_state` writes a concrete value into a new checkpoint's blob
+    # via the reducer against the hydrated prior state.
+    delta.update_state(config, {"items": ["x", "y"]})
+
+    snap = delta.get_state(config)
+    updated_items = list(snap.values.get("items", []))
+    # Must include the "x","y" update; without the hydration fix, the
+    # update_state-written blob would be skipped in favor of an ancestor
+    # walk, and the update values would disappear.
+    assert "x" in updated_items and "y" in updated_items, (
+        f"update_state values missing from snapshot: {updated_items}"
+    )
+    # The "x","y" items should be folded onto the prior accumulated state,
+    # not stand alone. This verifies the update-written blob is used
+    # directly by `get_state` (no ancestor walk past it).
+    assert len(updated_items) >= 4, (
+        f"update_state snapshot should preserve pre-update state, got {updated_items}"
+    )
+    assert updated_items[-2:] == ["x", "y"], (
+        f"update_state deltas should be at the tail, got {updated_items}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# 8. Fork from an `update_state` checkpoint: a new run branched off the
+# update_state-produced checkpoint must see that checkpoint's concrete
+# `channel_values` as its base, with new deltas folded on top.
+# ---------------------------------------------------------------------------
+
+
+def test_fork_from_update_state_checkpoint() -> None:
+    """Branching a new run from the checkpoint produced by `update_state`
+    must use that checkpoint's concrete blob as the base. Additional
+    deltas from the forked run fold onto it through the reducer."""
+
+    checkpointer = InMemorySaver()
+    config = {"configurable": {"thread_id": "fork"}}
+
+    # Pre-migration build-up, then migrate and add one post-migration step.
+    binop = _binop_graph(checkpointer)
+    _drive(binop, config, "u", 2)
+    delta = _delta_graph(checkpointer)
+    delta.invoke({"items": ["post"]}, config)
+
+    # Apply `update_state` and capture the returned config (references
+    # the new checkpoint produced by the update).
+    update_cfg = delta.update_state(config, {"items": ["x", "y"]})
+
+    update_snap = delta.get_state(update_cfg)
+    base_items = list(update_snap.values.get("items", []))
+    assert "x" in base_items and "y" in base_items, (
+        f"update_state values missing from snapshot: {base_items}"
+    )
+    assert base_items[-2:] == ["x", "y"], (
+        f"sanity: update_state deltas should be at the tail, got {base_items}"
+    )
+
+    # Fork: invoke from the update_state checkpoint with a new delta.
+    forked = delta.invoke({"items": ["fork0"]}, update_cfg)
+    forked_items = list(forked.get("items", []))
+    # The fork must see the update_state-written blob as its base (not
+    # walk past it), and the new delta must fold on top of it.
+    assert forked_items[: len(base_items)] == base_items, (
+        f"fork lost update_state base: base={base_items}, forked={forked_items}"
+    )
+    assert forked_items[-1] == "fork0", f"fork delta not appended: {forked_items}"
+
+
+# ---------------------------------------------------------------------------
+# 9. Migration from `add_messages` → `DeltaChannel(_messages_delta_reducer)`
+#
+# `add_messages` is the primary real-world use case: it creates a
+# BinaryOperatorAggregate with dedup-by-ID and RemoveMessage semantics.
+# After swapping the annotation to DeltaChannel, pre-migration blobs
+# (plain lists of Message objects) must be used directly as the seed.
+# ---------------------------------------------------------------------------
+
+
+def _add_messages_graph(checkpointer: Any) -> Any:
+    class MessagesState(TypedDict):
+        messages: Annotated[list, add_messages]
+
+    return (
+        StateGraph(MessagesState)
+        .add_node("noop", _noop)
+        .add_edge(START, "noop")
+        .add_edge("noop", END)
+        .compile(checkpointer=checkpointer)
+    )
+
+
+def _delta_messages_graph(checkpointer: Any) -> Any:
+    class DeltaMessagesState(TypedDict):
+        messages: Annotated[list, DeltaChannel(_messages_delta_reducer)]
+
+    return (
+        StateGraph(DeltaMessagesState)
+        .add_node("noop", _noop)
+        .add_edge(START, "noop")
+        .add_edge("noop", END)
+        .compile(checkpointer=checkpointer)
+    )
+
+
+def test_add_messages_to_delta_migration_preserves_message_history() -> None:
+    """Migration from `add_messages` to `DeltaChannel(_messages_delta_reducer)`
+    preserves message ordering and IDs at both the tip and settled ancestor
+    boundaries.
+
+    The pre-migration blob is a plain list of Message objects; DeltaChannel
+    must use it directly as the seed without walking ancestors past it.
+    """
+    checkpointer = InMemorySaver()
+    config = {"configurable": {"thread_id": "add-messages-migration"}}
+
+    pre_graph = _add_messages_graph(checkpointer)
+    pre_graph.invoke({"messages": [HumanMessage(content="hello", id="h1")]}, config)
+    pre_graph.invoke({"messages": [AIMessage(content="hi", id="a1")]}, config)
+    pre_graph.invoke({"messages": [HumanMessage(content="thanks", id="h2")]}, config)
+
+    pre_tip = pre_graph.get_state(config)
+    assert [m.id for m in pre_tip.values["messages"]] == ["h1", "a1", "h2"]
+
+    delta_graph = _delta_messages_graph(checkpointer)
+
+    # Tip: latest checkpoint has a full list blob — must use it directly.
+    snap = delta_graph.get_state(config)
+    assert [m.id for m in snap.values["messages"]] == ["h1", "a1", "h2"], (
+        f"tip hydration mismatch: got {[m.id for m in snap.values['messages']]}"
+    )
+
+    # Settled ancestor boundaries must also match.
+    pre_settled = [
+        [m.id for m in s.values.get("messages", [])]
+        for s in pre_graph.get_state_history(config)
+        if s.next == ("__start__",)
+    ]
+    delta_settled = [
+        [m.id for m in s.values.get("messages", [])]
+        for s in delta_graph.get_state_history(config)
+        if s.next == ("__start__",)
+    ]
+    assert delta_settled == pre_settled, (
+        f"settled boundary mismatch after migration: "
+        f"pre={pre_settled}, delta={delta_settled}"
+    )
+
+
+async def test_add_messages_to_delta_migration_preserves_message_history_async() -> (
+    None
+):
+    """Async variant of the add_messages migration test."""
+    checkpointer = InMemorySaver()
+    config = {"configurable": {"thread_id": "add-messages-migration-async"}}
+
+    pre_graph = _add_messages_graph(checkpointer)
+    await pre_graph.ainvoke(
+        {"messages": [HumanMessage(content="hello", id="h1")]}, config
+    )
+    await pre_graph.ainvoke({"messages": [AIMessage(content="hi", id="a1")]}, config)
+
+    delta_graph = _delta_messages_graph(checkpointer)
+    snap = await delta_graph.aget_state(config)
+    assert [m.id for m in snap.values["messages"]] == ["h1", "a1"], (
+        f"async tip hydration mismatch: got {[m.id for m in snap.values['messages']]}"
+    )

libs/langgraph/tests/test_interleave_arrival_order.py

@@ -0,0 +1,359 @@
+"""Tests for arrival-ordered interleave and push stamps."""
+
+from __future__ import annotations
+
+import operator
+from typing import Annotated, Any
+
+import pytest
+from typing_extensions import TypedDict
+
+from langgraph.constants import END, START
+from langgraph.graph import StateGraph
+from langgraph.stream import StreamChannel, StreamTransformer
+from langgraph.stream._mux import StreamMux
+from langgraph.stream._types import ProtocolEvent
+from langgraph.stream.run_stream import GraphRunStream
+from langgraph.stream.transformers import ValuesTransformer
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+class _TwoChannelTransformer(StreamTransformer):
+    """Transformer that exposes two named channels for testing interleave."""
+
+    _native = True
+
+    def __init__(self, scope: tuple[str, ...] = ()) -> None:
+        super().__init__(scope)
+        self._alpha: StreamChannel[str] = StreamChannel("alpha")
+        self._beta: StreamChannel[str] = StreamChannel("beta")
+
+    def init(self) -> dict[str, Any]:
+        return {"alpha": self._alpha, "beta": self._beta}
+
+    def process(self, event: ProtocolEvent) -> bool:
+        return True
+
+
+class SimpleState(TypedDict):
+    value: str
+    items: Annotated[list[str], operator.add]
+
+
+def _build_simple_graph():
+    def node_a(state: SimpleState) -> dict:
+        return {"value": state["value"] + "A", "items": ["a"]}
+
+    def node_b(state: SimpleState) -> dict:
+        return {"value": state["value"] + "B", "items": ["b"]}
+
+    builder = StateGraph(SimpleState)
+    builder.add_node("node_a", node_a)
+    builder.add_node("node_b", node_b)
+    builder.add_edge(START, "node_a")
+    builder.add_edge("node_a", "node_b")
+    builder.add_edge("node_b", END)
+    return builder.compile()
+
+
+# ---------------------------------------------------------------------------
+# Unit tests: push stamps on StreamChannel
+# ---------------------------------------------------------------------------
+
+
+class TestPushStamps:
+    def test_stamps_are_monotonic_across_channels(self) -> None:
+        mux = StreamMux(
+            factories=[ValuesTransformer, _TwoChannelTransformer],
+            is_async=False,
+        )
+        alpha = mux.extensions["alpha"]
+        beta = mux.extensions["beta"]
+
+        alpha._subscribed = True
+        beta._subscribed = True
+
+        alpha.push("a1")
+        beta.push("b1")
+        alpha.push("a2")
+        beta.push("b2")
+
+        all_stamped = list(alpha._items) + list(beta._items)
+        stamps = [s for s, _ in all_stamped]
+        assert len(set(stamps)) == 4
+        items_by_arrival = [item for _, item in sorted(all_stamped)]
+        assert items_by_arrival == ["a1", "b1", "a2", "b2"]
+
+    def test_regular_iter_strips_stamps(self) -> None:
+        mux = StreamMux(
+            factories=[ValuesTransformer, _TwoChannelTransformer],
+            is_async=False,
+        )
+        alpha = mux.extensions["alpha"]
+        it = iter(alpha)
+        alpha.push("a1")
+        alpha.push("a2")
+        alpha.close()
+        items = list(it)
+        assert items == ["a1", "a2"]
+        assert all(isinstance(item, str) for item in items)
+
+    def test_events_channel_gets_real_stamps(self) -> None:
+        mux = StreamMux(
+            factories=[ValuesTransformer, _TwoChannelTransformer],
+            is_async=False,
+        )
+        alpha = mux.extensions["alpha"]
+
+        alpha._subscribed = True
+        alpha.push("a1")
+
+        mux._events._subscribed = True
+        mux._events.push({"method": "test", "data": "x"})
+
+        alpha.push("a2")
+
+        all_stamps = [s for s, _ in alpha._items] + [s for s, _ in mux._events._items]
+        assert len(set(all_stamps)) == len(all_stamps), "all stamps should be unique"
+        assert all(s > 0 for s in all_stamps), "no stamp should be zero"
+
+    def test_channel_without_mux_gets_zero_stamp(self) -> None:
+        ch: StreamChannel[str] = StreamChannel()
+        ch._bind(is_async=False)
+        ch._subscribed = True
+        ch.push("x")
+        assert list(ch._items) == [(0, "x")]
+
+
+# ---------------------------------------------------------------------------
+# Unit tests: interleave arrival order
+# ---------------------------------------------------------------------------
+
+
+class TestInterleaveArrivalOrder:
+    def test_arrival_order_not_round_robin(self) -> None:
+        mux = StreamMux(
+            factories=[ValuesTransformer, _TwoChannelTransformer],
+            is_async=False,
+        )
+        alpha = mux.extensions["alpha"]
+        beta = mux.extensions["beta"]
+        run = GraphRunStream(None, mux, wire_pump=False)
+
+        # interleave() subscribes channels directly and reads _items
+        # for stamp-ordered iteration. We simulate the pump by wiring
+        # a custom callback that pushes items in a known order.
+        push_script = [
+            ("alpha", "a1"),
+            ("alpha", "a2"),
+            ("beta", "b1"),
+            ("alpha", "a3"),
+            ("beta", "b2"),
+        ]
+        push_iter = iter(push_script)
+        channels = {"alpha": alpha, "beta": beta}
+
+        def fake_pump() -> bool:
+            try:
+                name, item = next(push_iter)
+                channels[name].push(item)
+                return True
+            except StopIteration:
+                mux.close()
+                return False
+
+        mux.bind_pump(fake_pump)
+
+        result = list(run.interleave("alpha", "beta"))
+        names = [name for name, _ in result]
+        items = [item for _, item in result]
+
+        assert items == ["a1", "a2", "b1", "a3", "b2"]
+        assert names == ["alpha", "alpha", "beta", "alpha", "beta"]
+
+    def test_single_projection(self) -> None:
+        mux = StreamMux(
+            factories=[ValuesTransformer, _TwoChannelTransformer],
+            is_async=False,
+        )
+        alpha = mux.extensions["alpha"]
+        run = GraphRunStream(None, mux, wire_pump=False)
+
+        push_script = [("alpha", "a1"), ("alpha", "a2")]
+        push_iter = iter(push_script)
+
+        def fake_pump() -> bool:
+            try:
+                _, item = next(push_iter)
+                alpha.push(item)
+                return True
+            except StopIteration:
+                mux.close()
+                return False
+
+        mux.bind_pump(fake_pump)
+
+        result = list(run.interleave("alpha"))
+        assert result == [("alpha", "a1"), ("alpha", "a2")]
+
+    def test_empty_projection(self) -> None:
+        mux = StreamMux(
+            factories=[ValuesTransformer, _TwoChannelTransformer],
+            is_async=False,
+        )
+        alpha = mux.extensions["alpha"]
+        run = GraphRunStream(None, mux, wire_pump=False)
+
+        push_script = [("alpha", "a1"), ("alpha", "a2")]
+        push_iter = iter(push_script)
+        channels = {"alpha": alpha}
+
+        def fake_pump() -> bool:
+            try:
+                name, item = next(push_iter)
+                channels[name].push(item)
+                return True
+            except StopIteration:
+                mux.close()
+                return False
+
+        mux.bind_pump(fake_pump)
+
+        result = list(run.interleave("alpha", "beta"))
+        assert result == [("alpha", "a1"), ("alpha", "a2")]
+
+    def test_unknown_projection_raises(self) -> None:
+        mux = StreamMux(
+            factories=[ValuesTransformer, _TwoChannelTransformer],
+            is_async=False,
+        )
+        run = GraphRunStream(None, mux, wire_pump=False)
+        mux.close()
+        with pytest.raises((KeyError, AttributeError)):
+            list(run.interleave("alpha", "does_not_exist"))
+
+    def test_all_empty(self) -> None:
+        mux = StreamMux(
+            factories=[ValuesTransformer, _TwoChannelTransformer],
+            is_async=False,
+        )
+        run = GraphRunStream(None, mux, wire_pump=False)
+
+        def fake_pump() -> bool:
+            mux.close()
+            return False
+
+        mux.bind_pump(fake_pump)
+
+        result = list(run.interleave("alpha", "beta"))
+        assert result == []
+
+    def test_error_propagation(self) -> None:
+        mux = StreamMux(
+            factories=[ValuesTransformer, _TwoChannelTransformer],
+            is_async=False,
+        )
+        alpha = mux.extensions["alpha"]
+        beta = mux.extensions["beta"]
+        run = GraphRunStream(None, mux, wire_pump=False)
+
+        err = RuntimeError("boom")
+
+        push_script = [
+            ("alpha", "a1"),
+            ("beta", "b1"),
+        ]
+        push_iter = iter(push_script)
+        channels = {"alpha": alpha, "beta": beta}
+
+        def fake_pump() -> bool:
+            try:
+                name, item = next(push_iter)
+                channels[name].push(item)
+                return True
+            except StopIteration:
+                alpha.fail(err)
+                beta.close()
+                return False
+
+        mux.bind_pump(fake_pump)
+
+        collected = []
+        with pytest.raises(RuntimeError, match="boom"):
+            for pair in run.interleave("alpha", "beta"):
+                collected.append(pair)
+
+        assert ("alpha", "a1") in collected
+        assert ("beta", "b1") in collected
+
+
+# ---------------------------------------------------------------------------
+# Integration test: interleave with stream_events(version="v3")
+# ---------------------------------------------------------------------------
+
+
+class TestInterleaveIntegration:
+    def test_interleave_values_and_messages(self) -> None:
+        run = _build_simple_graph().stream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
+        tagged = list(run.interleave("values", "messages"))
+        names = [name for name, _ in tagged]
+        assert set(names).issubset({"values", "messages"})
+        assert names.count("values") >= 1
+
+    def test_interleave_rejects_already_subscribed(self) -> None:
+        mux = StreamMux(
+            factories=[ValuesTransformer, _TwoChannelTransformer],
+            is_async=False,
+        )
+        alpha = mux.extensions["alpha"]
+        run = GraphRunStream(None, mux, wire_pump=False)
+
+        # Subscribe alpha via iter first
+        _ = iter(alpha)
+        mux.close()
+
+        with pytest.raises(RuntimeError, match="already has a subscriber"):
+            list(run.interleave("alpha"))
+
+    def test_interleave_releases_projections_on_completion(self) -> None:
+        run = _build_simple_graph().stream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
+        list(run.interleave("values", "messages"))
+        # Subscriptions should be released after the generator completes,
+        # so the channels can be re-iterated (they'll be empty / closed).
+        assert run.extensions["values"]._subscribed is False
+        assert run.extensions["messages"]._subscribed is False
+
+    def test_interleave_releases_projections_on_early_break(self) -> None:
+        run = _build_simple_graph().stream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
+        gen = run.interleave("values", "messages")
+        next(gen)
+        gen.close()
+        assert run.extensions["values"]._subscribed is False
+        assert run.extensions["messages"]._subscribed is False
+
+    def test_interleave_releases_projections_on_validation_failure(self) -> None:
+        mux = StreamMux(
+            factories=[ValuesTransformer, _TwoChannelTransformer],
+            is_async=False,
+        )
+        alpha = mux.extensions["alpha"]
+        # Pre-subscribe alpha so that interleave will fail validation when
+        # it gets to the second name. The first (already-validated) channel
+        # should still be released.
+        run = GraphRunStream(None, mux, wire_pump=False)
+        mux.close()
+        alpha._subscribed = True
+
+        with pytest.raises(RuntimeError, match="already has a subscriber"):
+            list(run.interleave("values", "alpha"))
+
+        assert mux.extensions["values"]._subscribed is False

libs/langgraph/tests/test_pregel.py

@@ -16,7 +16,7 @@ from typing import Annotated, Any, Literal, get_type_hints
 
 import pytest
 from langchain_core.language_models import GenericFakeChatModel
-from langchain_core.messages import AIMessage, AnyMessage, HumanMessage
+from langchain_core.messages import AIMessage, AnyMessage, HumanMessage, RemoveMessage
 from langchain_core.runnables import (
     RunnableConfig,
     RunnableLambda,
@@ -41,6 +41,7 @@ from typing_extensions import NotRequired, TypedDict
 
 from langgraph._internal._constants import CONFIG_KEY_NODE_FINISHED, ERROR, PULL
 from langgraph.channels.binop import BinaryOperatorAggregate
+from langgraph.channels.delta import DeltaChannel
 from langgraph.channels.ephemeral_value import EphemeralValue
 from langgraph.channels.last_value import LastValue
 from langgraph.channels.topic import Topic
@@ -49,7 +50,7 @@ from langgraph.config import get_stream_writer
 from langgraph.errors import GraphRecursionError, InvalidUpdateError, ParentCommand
 from langgraph.func import entrypoint, task
 from langgraph.graph import END, START, StateGraph
-from langgraph.graph.message import MessagesState, add_messages
+from langgraph.graph.message import MessagesState, _messages_delta_reducer, add_messages
 from langgraph.pregel import (
     NodeBuilder,
     Pregel,
@@ -120,6 +121,29 @@ def test_graph_validation() -> None:
         graph.invoke({"hello": "there"})
 
 
+def test_request_drain_allows_inflight_call_scheduling(
+    sync_checkpointer: BaseCheckpointSaver,
+) -> None:
+    from langgraph.runtime import RunControl
+
+    @task
+    def child(x: int) -> int:
+        return x + 1
+
+    control = RunControl()
+
+    @entrypoint(checkpointer=sync_checkpointer)
+    def graph(x: int) -> int:
+        control.request_drain()
+        fut = child(x)
+        return fut.result()
+
+    config = {"configurable": {"thread_id": "drain-call-sync"}}
+
+    assert graph.invoke(1, config=config, control=control) == 2
+    assert control.drain_requested
+
+
 def test_invalid_checkpointer_type() -> None:
     class State(TypedDict):
         foo: str
@@ -9400,3 +9424,263 @@ def test_fork_does_not_apply_pending_writes(
 
     # Should be: 1 (input) + 20 (forked node_a) + 100 (node_b) = 121
     assert result == {"value": 121}
+
+
+async def test_delta_channel_end_to_end_inmemory() -> None:
+    """Full graph run: DeltaChannel accumulates correctly across multiple turns."""
+
+    class State(TypedDict):
+        messages: Annotated[list, DeltaChannel(_messages_delta_reducer)]
+
+    def respond(state: State) -> dict:
+        n = len(state["messages"])
+        return {"messages": [AIMessage(content=f"reply-{n}", id=f"ai-{n}")]}
+
+    builder = StateGraph(State)
+    builder.add_node("respond", respond)
+    builder.add_edge(START, "respond")
+    graph = builder.compile(checkpointer=InMemorySaver())
+
+    config = {"configurable": {"thread_id": "diff-test-1"}}
+
+    # Turn 1
+    graph.invoke({"messages": [HumanMessage(content="hello", id="h1")]}, config)
+    # Turn 2
+    graph.invoke({"messages": [HumanMessage(content="world", id="h2")]}, config)
+    # Turn 3
+    graph.invoke({"messages": [HumanMessage(content="bye", id="h3")]}, config)
+
+    state = graph.get_state(config)
+    msgs = state.values["messages"]
+    # 3 human + 3 AI = 6 total
+    assert len(msgs) == 6, f"expected 6 messages, got {len(msgs)}: {msgs}"
+    assert msgs[0].content == "hello"
+    assert msgs[2].content == "world"
+    assert msgs[4].content == "bye"
+    assert msgs[1].content == "reply-1"
+    assert msgs[3].content == "reply-3"
+    assert msgs[5].content == "reply-5"
+
+
+async def test_delta_channel_time_travel() -> None:
+    """Time-travel back to turn-1 checkpoint and resume; continuation must not include turn-2 deltas."""
+
+    class State(TypedDict):
+        messages: Annotated[list, DeltaChannel(_messages_delta_reducer)]
+
+    counter = {"n": 0}
+
+    def respond(state: State) -> dict:
+        counter["n"] += 1
+        return {
+            "messages": [
+                AIMessage(content=f"ai-{counter['n']}", id=f"ai-{counter['n']}")
+            ]
+        }
+
+    builder = StateGraph(State)
+    builder.add_node("respond", respond)
+    builder.add_edge(START, "respond")
+    saver = InMemorySaver()
+    graph = builder.compile(checkpointer=saver)
+
+    config = {"configurable": {"thread_id": "diff-time-travel"}}
+
+    # Run 2 turns: h1→ai-1, h2→ai-2
+    graph.invoke({"messages": [HumanMessage(content="h1", id="h1")]}, config)
+    graph.invoke({"messages": [HumanMessage(content="h2", id="h2")]}, config)
+
+    # Find the checkpoint after turn 1 (2 messages: h1 + ai-1)
+    history = list(graph.get_state_history(config))
+    after_turn1 = next(h for h in history if len(h.values.get("messages", [])) == 2)
+
+    assert len(after_turn1.values["messages"]) == 2
+    assert after_turn1.values["messages"][0].content == "h1"
+    assert after_turn1.values["messages"][1].content == "ai-1"
+
+    # Resume from turn-1 checkpoint: inject h3, expect 3 messages total (h1, ai-1, ai-N)
+    # NOT 5 messages (turn-2 deltas must not bleed into the resumed run)
+    result = graph.invoke(
+        {"messages": [HumanMessage(content="h3", id="h3")]},
+        after_turn1.config,
+    )
+    msgs = result["messages"]
+    # Should be: h1, ai-1, h3, ai-N — 4 messages total
+    assert len(msgs) == 4, (
+        f"expected 4 messages after time-travel resume, got {len(msgs)}: {msgs}"
+    )
+    assert msgs[0].content == "h1"
+    assert msgs[1].content == "ai-1"
+    assert msgs[2].content == "h3"
+
+
+async def test_delta_channel_remove_message_end_to_end() -> None:
+    """RemoveMessage inside a DeltaChannel graph must persist and reload correctly."""
+
+    class State(TypedDict):
+        messages: Annotated[list, DeltaChannel(_messages_delta_reducer)]
+
+    def respond(state: State) -> dict:
+        return {"messages": [AIMessage(content="reply", id="ai-1")]}
+
+    def delete_first(state: State) -> dict:
+        # removes the first message
+        return {"messages": [RemoveMessage(id=state["messages"][0].id)]}
+
+    builder = StateGraph(State)
+    builder.add_node("respond", respond)
+    builder.add_node("delete_first", delete_first)
+    builder.add_edge(START, "respond")
+    builder.add_edge("respond", "delete_first")
+    graph = builder.compile(checkpointer=InMemorySaver())
+
+    config = {"configurable": {"thread_id": "diff-remove-test"}}
+    graph.invoke({"messages": [HumanMessage(content="hello", id="h1")]}, config)
+
+    state = graph.get_state(config)
+    msgs = state.values["messages"]
+    # h1 was removed, only ai-1 should remain
+    assert len(msgs) == 1, f"expected 1 message, got {len(msgs)}: {msgs}"
+    assert msgs[0].id == "ai-1"
+
+    # A subsequent turn must reconstruct from the checkpoint correctly
+    graph.invoke({"messages": [HumanMessage(content="again", id="h2")]}, config)
+    state = graph.get_state(config)
+    msgs = state.values["messages"]
+    # ai-1 + h2 + ai-1(second reply, same id overwrites) + h2 removed
+    # more simply: after second run we expect ai-1 updated + h2 remaining minus deleted h2
+    # just assert h1 is still gone
+    assert all(m.id != "h1" for m in msgs), (
+        "h1 should still be absent after second turn"
+    )
+
+
+async def test_delta_channel_update_by_id_end_to_end() -> None:
+    """Updating a message by ID via DeltaChannel must persist and reload correctly."""
+
+    class State(TypedDict):
+        messages: Annotated[list, DeltaChannel(_messages_delta_reducer)]
+
+    def update_msg(state: State) -> dict:
+        # re-send h1 with updated content
+        return {"messages": [HumanMessage(content="updated", id="h1")]}
+
+    builder = StateGraph(State)
+    builder.add_node("update_msg", update_msg)
+    builder.add_edge(START, "update_msg")
+    graph = builder.compile(checkpointer=InMemorySaver())
+
+    config = {"configurable": {"thread_id": "diff-update-id-test"}}
+    graph.invoke({"messages": [HumanMessage(content="original", id="h1")]}, config)
+
+    state = graph.get_state(config)
+    msgs = state.values["messages"]
+    assert len(msgs) == 1, f"expected 1 message, got {len(msgs)}: {msgs}"
+    assert msgs[0].content == "updated"
+    assert msgs[0].id == "h1"
+
+    # Second turn: verify the updated state is the base for further accumulation
+    graph.invoke({"messages": [HumanMessage(content="new", id="h2")]}, config)
+    state = graph.get_state(config)
+    msgs = state.values["messages"]
+    ids = [m.id for m in msgs]
+    assert "h1" in ids  # h1 persists (updated, not duplicated)
+    assert "h2" in ids
+    assert ids.count("h1") == 1, "h1 must not be duplicated"
+
+
+async def test_delta_channel_durability_exit_stores_snapshot() -> None:
+    """DeltaChannel must reload from a durability='exit' checkpoint."""
+
+    class State(TypedDict):
+        messages: Annotated[list, DeltaChannel(_messages_delta_reducer)]
+
+    def respond(state: State) -> dict:
+        return {"messages": [AIMessage(content="reply", id="ai1")]}
+
+    builder = StateGraph(State)
+    builder.add_node("respond", respond)
+    builder.add_edge(START, "respond")
+    graph = builder.compile(checkpointer=InMemorySaver())
+    config = {"configurable": {"thread_id": "delta-exit-test"}}
+
+    result = graph.invoke(
+        {"messages": [HumanMessage(content="hello", id="h1")]},
+        config,
+        durability="exit",
+    )
+    assert [m.content for m in result["messages"]] == ["hello", "reply"]
+
+    state = graph.get_state(config)
+    assert [m.content for m in state.values["messages"]] == ["hello", "reply"]
+
+
+async def test_delta_channel_async_write_ordering() -> None:
+    """In async mode, DeltaChannel write futures are awaited before the checkpoint
+    is committed, so aput_writes always precedes aput for delta-channel
+    checkpoints (those where the delta channel had a versioned write but
+    is absent from `channel_values`, i.e. no snapshot fired this step)."""
+
+    class State(TypedDict):
+        messages: Annotated[list, DeltaChannel(_messages_delta_reducer)]
+
+    def respond(state: State) -> dict:
+        i = len(state["messages"])
+        return {"messages": [AIMessage(content=f"r{i}", id=f"ai{i}")]}
+
+    order: list[str] = []
+    original_aput_writes = InMemorySaver.aput_writes
+    original_aput = InMemorySaver.aput
+
+    async def tracked_aput_writes(self, config, writes, task_id, task_path=""):
+        result = await original_aput_writes(self, config, writes, task_id, task_path)
+        order.append("aput_writes")
+        return result
+
+    async def tracked_aput(self, config, checkpoint, metadata, new_versions):
+        # A "delta" checkpoint here = `messages` versioned but absent from
+        # `channel_values` (no snapshot fired). When a snapshot does fire,
+        # `channel_values["messages"]` is a `_DeltaSnapshot` — also a delta
+        # checkpoint shape, since the writes still have to be persisted
+        # before the parent checkpoint commits.
+        channel_values = checkpoint.get("channel_values", {})
+        is_delta_step = (
+            "messages" in checkpoint.get("channel_versions", {})
+            and "messages" not in channel_values
+        )
+        order.append("aput_delta" if is_delta_step else "aput_other")
+        return await original_aput(self, config, checkpoint, metadata, new_versions)
+
+    InMemorySaver.aput_writes = tracked_aput_writes
+    InMemorySaver.aput = tracked_aput
+    try:
+        builder = StateGraph(State)
+        builder.add_node("respond", respond)
+        builder.add_edge(START, "respond")
+        graph = builder.compile(checkpointer=InMemorySaver())
+        config = {"configurable": {"thread_id": "async-ordering-test"}}
+
+        for i in range(3):
+            await graph.ainvoke(
+                {"messages": [HumanMessage(content=f"h{i}", id=f"h{i}")]}, config
+            )
+
+        # Every aput_delta must be preceded by at least one aput_writes
+        for i, event in enumerate(order):
+            if event == "aput_delta":
+                preceding = order[:i]
+                assert "aput_writes" in preceding, (
+                    f"aput_delta at {i} had no preceding aput_writes: {order}"
+                )
+                last_write_idx = max(
+                    j for j, e in enumerate(order[:i]) if e == "aput_writes"
+                )
+                assert last_write_idx < i, (
+                    f"aput_writes at {last_write_idx} should precede aput_delta at {i}: {order}"
+                )
+    finally:
+        InMemorySaver.aput_writes = original_aput_writes
+        InMemorySaver.aput = original_aput
+
+    state = await graph.aget_state(config)
+    assert len(state.values["messages"]) == 6  # 3 human + 3 AI

libs/langgraph/tests/test_pregel_async.py

@@ -16,6 +16,7 @@ from typing import (
     Literal,
     Optional,
 )
+from unittest.mock import patch
 from uuid import UUID
 
 import pytest
@@ -48,6 +49,7 @@ from langgraph.channels.topic import Topic
 from langgraph.errors import (
     GraphRecursionError,
     InvalidUpdateError,
+    NodeError,
     ParentCommand,
 )
 from langgraph.func import entrypoint, task
@@ -215,6 +217,30 @@ async def test_checkpoint_errors() -> None:
             pass
 
 
+@NEEDS_CONTEXTVARS
+async def test_request_drain_allows_inflight_acall_scheduling(
+    async_checkpointer: BaseCheckpointSaver,
+) -> None:
+    from langgraph.runtime import RunControl
+
+    @task
+    async def child(x: int) -> int:
+        return x + 1
+
+    control = RunControl()
+
+    @entrypoint(checkpointer=async_checkpointer)
+    async def graph(x: int) -> int:
+        control.request_drain()
+        fut = child(x)
+        return await fut
+
+    config = {"configurable": {"thread_id": "drain-call-async"}}
+
+    assert await graph.ainvoke(1, config=config, control=control) == 2
+    assert control.drain_requested
+
+
 async def test_py_async_with_cancel_behavior() -> None:
     """This test confirms that in all versions of Python we support, __aexit__
     is not cancelled when the coroutine containing the async with block is cancelled."""
@@ -6101,6 +6127,36 @@ async def test_parent_command(
     )
 
 
+async def test_delta_channel_durability_exit_stores_snapshot_async() -> None:
+    """DeltaChannel must reload from an async durability='exit' checkpoint."""
+    from langchain_core.messages import AIMessage
+
+    from langgraph.channels.delta import DeltaChannel
+    from langgraph.graph.message import _messages_delta_reducer
+
+    class State(TypedDict):
+        messages: Annotated[list, DeltaChannel(_messages_delta_reducer)]
+
+    async def respond(state: State) -> dict:
+        return {"messages": [AIMessage(content="reply", id="ai1")]}
+
+    builder = StateGraph(State)
+    builder.add_node("respond", respond)
+    builder.add_edge(START, "respond")
+    graph = builder.compile(checkpointer=InMemorySaver())
+    config = {"configurable": {"thread_id": "delta-exit-async-test"}}
+
+    result = await graph.ainvoke(
+        {"messages": [HumanMessage(content="hello", id="h1")]},
+        config,
+        durability="exit",
+    )
+    assert [m.content for m in result["messages"]] == ["hello", "reply"]
+
+    state = await graph.aget_state(config)
+    assert [m.content for m in state.values["messages"]] == ["hello", "reply"]
+
+
 @NEEDS_CONTEXTVARS
 async def test_interrupt_subgraph(async_checkpointer: BaseCheckpointSaver) -> None:
     class State(TypedDict):
@@ -9709,3 +9765,126 @@ async def test_fork_does_not_apply_pending_writes(
 
     # 1 (input) + 20 (forked node_a) + 100 (node_b) = 121
     assert result == {"value": 121}
+
+
+async def test_graph_error_handler_async_runtime_info() -> None:
+    class State(TypedDict):
+        foo: str
+
+    attempts = 0
+    captured: dict[str, object] = {}
+
+    async def always_failing_node(state: State) -> State:
+        nonlocal attempts
+        attempts += 1
+        raise ValueError("Always fails async")
+
+    async def err_handler_node(state: State, error: NodeError) -> State:
+        captured["from_node_name"] = error.node
+        captured["from_node_error"] = error.error
+        return {"foo": "handled_async"}
+
+    graph = (
+        StateGraph(State)
+        .add_node(
+            "always_failing",
+            always_failing_node,
+            retry_policy=RetryPolicy(
+                max_attempts=2,
+                initial_interval=0.01,
+                jitter=False,
+                retry_on=ValueError,
+            ),
+            error_handler=err_handler_node,
+        )
+        .add_edge(START, "always_failing")
+        .compile()
+    )
+
+    with patch("asyncio.sleep"):
+        result = await graph.ainvoke({"foo": ""})
+
+    assert attempts == 2
+    assert result["foo"] == "handled_async"
+    assert captured["from_node_name"] == "always_failing"
+    assert isinstance(captured["from_node_error"], BaseException)
+
+
+@NEEDS_CONTEXTVARS
+async def test_graph_error_handler_does_not_swallow_interrupt_concurrent() -> None:
+    """When a graph error handler is configured and a node calls interrupt()
+    concurrently with other nodes, the interrupt must still be raised — not
+    silently swallowed."""
+
+    class State(TypedDict):
+        foo: str
+
+    async def node_a(state: State) -> State:
+        val = interrupt("need human input")
+        return {"foo": f"a_{val}"}
+
+    async def node_b(state: State) -> State:
+        return {}
+
+    async def err_handler(state: State) -> State:
+        return {"foo": "handled"}
+
+    checkpointer = InMemorySaver()
+    graph = (
+        StateGraph(State)
+        .add_node("node_a", node_a, error_handler=err_handler)
+        .add_node("node_b", node_b)
+        .add_edge(START, "node_a")
+        .add_edge(START, "node_b")
+        .compile(checkpointer=checkpointer)
+    )
+
+    config = {"configurable": {"thread_id": "test-interrupt-concurrent-async"}}
+
+    await graph.ainvoke({"foo": ""}, config)
+
+    state = await graph.aget_state(config)
+    assert len(state.tasks) > 0
+
+    interrupts = [t for t in state.tasks if hasattr(t, "interrupts") and t.interrupts]
+    assert len(interrupts) > 0, (
+        "GraphInterrupt was swallowed — interrupt() in node_a "
+        "should have paused execution"
+    )
+
+
+async def test_node_error_handler_handles_subgraph_internal_failure_async() -> None:
+    class SubState(TypedDict):
+        foo: str
+
+    class ParentState(TypedDict):
+        foo: str
+
+    captured: dict[str, object] = {}
+
+    async def sub_fail_node(state: SubState) -> SubState:
+        raise ValueError("async subgraph boom")
+
+    async def parent_handler(state: ParentState, error: NodeError) -> ParentState:
+        captured["from_node_name"] = error.node
+        captured["from_node_error"] = error.error
+        return {"foo": "handled_async_subgraph"}
+
+    subgraph = (
+        StateGraph(SubState)
+        .add_node("sub_fail_node", sub_fail_node)
+        .add_edge(START, "sub_fail_node")
+        .compile()
+    )
+
+    parent_graph = (
+        StateGraph(ParentState)
+        .add_node("subgraph_node", subgraph, error_handler=parent_handler)
+        .add_edge(START, "subgraph_node")
+        .compile()
+    )
+
+    result = await parent_graph.ainvoke({"foo": ""})
+    assert result["foo"] == "handled_async_subgraph"
+    assert captured["from_node_name"] == "subgraph_node"
+    assert isinstance(captured["from_node_error"], BaseException)

libs/langgraph/tests/test_pregel_stream_events_v3.py

@@ -1,4 +1,4 @@
-"""Tests for Pregel.stream_v2 / astream_v2 and the transformer pipeline."""
+"""Tests for Pregel.stream_events(version="v3") / astream_events(version="v3") and the transformer pipeline."""
 
 from __future__ import annotations
 
@@ -125,7 +125,7 @@ def _build_custom_stream_graph():
 class _CustomPassthroughTransformer(StreamTransformer):
     """Opts a run into the `custom` stream mode without building a projection.
 
-    `stream_v2` requests only the modes that registered transformers
+    `stream_events(version="v3")` requests only the modes that registered transformers
     declare via `required_stream_modes`. Custom events are raw user
     emissions from `StreamWriter`, so tests that want them visible on
     the main event log register this pass-through transformer.
@@ -390,25 +390,31 @@ class TestStreamChannelNamed:
 
 
 # ---------------------------------------------------------------------------
-# stream_v2 sync tests
+# stream_events(version="v3") sync tests
 # ---------------------------------------------------------------------------
 
 
 class TestStreamV2Sync:
     def test_values_projection(self) -> None:
-        run = _build_simple_graph().stream_v2({"value": "x", "items": []})
+        run = _build_simple_graph().stream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         snapshots = list(run.values)
         assert len(snapshots) >= 1
         last = snapshots[-1]
         assert "A" in last["value"] and "B" in last["value"]
 
     def test_output(self) -> None:
-        run = _build_simple_graph().stream_v2({"value": "x", "items": []})
+        run = _build_simple_graph().stream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         output = run.output
         assert output == {"value": "xAB", "items": ["a", "b"]}
 
     def test_raw_event_iteration(self) -> None:
-        run = _build_simple_graph().stream_v2({"value": "x", "items": []})
+        run = _build_simple_graph().stream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         events = list(run)
         assert len(events) > 0
         for event in events:
@@ -418,22 +424,27 @@ class TestStreamV2Sync:
             assert isinstance(event["params"]["timestamp"], int)
 
     def test_extensions_has_native_keys(self) -> None:
-        run = _build_simple_graph().stream_v2({"value": "x", "items": []})
+        run = _build_simple_graph().stream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         _ = run.output
         assert "values" in run.extensions and "messages" in run.extensions
         assert run.values is run.extensions["values"]
         assert run.messages is run.extensions["messages"]
 
     def test_extensions_is_read_only(self) -> None:
-        run = _build_simple_graph().stream_v2({"value": "x", "items": []})
+        run = _build_simple_graph().stream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         with pytest.raises(TypeError):
             run.extensions["new_key"] = object()  # type: ignore[index]
         with pytest.raises(TypeError):
             del run.extensions["values"]  # type: ignore[attr-defined]
 
     def test_custom_stream_events(self) -> None:
-        run = _build_custom_stream_graph().stream_v2(
+        run = _build_custom_stream_graph().stream_events(
             {"value": "x", "items": []},
+            version="v3",
             transformers=[_CustomPassthroughTransformer],
         )
         custom_events = [e for e in run if e["method"] == "custom"]
@@ -444,27 +455,34 @@ class TestStreamV2Sync:
     def test_custom_events_suppressed_without_transformer(self) -> None:
         """Without a transformer declaring `"custom"`, no custom events flow.
 
-        `stream_v2` asks the graph only for the modes that registered
+        `stream_events(version="v3")` asks the graph only for the modes that registered
         transformers require. Built-ins cover `values` / `messages`;
         consumers that want raw custom events surface them by
         registering a transformer whose `required_stream_modes`
         includes `"custom"`.
         """
-        run = _build_custom_stream_graph().stream_v2({"value": "x", "items": []})
+        run = _build_custom_stream_graph().stream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         custom_events = [e for e in run if e["method"] == "custom"]
         assert custom_events == []
 
     def test_interleave_values_and_messages(self) -> None:
-        run = _build_simple_graph().stream_v2({"value": "x", "items": []})
+        run = _build_simple_graph().stream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         tagged = list(run.interleave("values", "messages"))
         names = [name for name, _ in tagged]
         assert set(names).issubset({"values", "messages"})
         assert names.count("values") >= 1
-        with pytest.raises(RuntimeError, match="already has a subscriber"):
-            list(run.values)
+        # interleave releases its subscription on completion.
+        assert run.extensions["values"]._subscribed is False
+        assert run.extensions["messages"]._subscribed is False
 
     def test_abort_marks_exhausted_and_closes_mux(self) -> None:
-        run = _build_simple_graph().stream_v2({"value": "x", "items": []})
+        run = _build_simple_graph().stream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         values_iter = iter(run.values)
         _ = next(values_iter)
         run.abort()
@@ -473,48 +491,63 @@ class TestStreamV2Sync:
         run.abort()  # idempotent
 
     def test_context_manager_calls_abort_on_exit(self) -> None:
-        with _build_simple_graph().stream_v2({"value": "x", "items": []}) as run:
+        with _build_simple_graph().stream_events(
+            {"value": "x", "items": []}, version="v3"
+        ) as run:
             _ = next(iter(run.values))
         assert run._exhausted is True
 
     def test_interleave_unknown_projection(self) -> None:
-        run = _build_simple_graph().stream_v2({"value": "x", "items": []})
+        run = _build_simple_graph().stream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         with pytest.raises(KeyError):
             list(run.interleave("values", "does_not_exist"))
 
 
 class TestStreamV2SyncErrors:
     def test_error_propagation_output(self) -> None:
-        run = _build_error_graph().stream_v2({"value": "x", "items": []})
+        run = _build_error_graph().stream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         with pytest.raises(ValueError, match="boom"):
             _ = run.output
 
     def test_error_propagation_values(self) -> None:
-        run = _build_error_graph().stream_v2({"value": "x", "items": []})
+        run = _build_error_graph().stream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         with pytest.raises(ValueError, match="boom"):
             list(run.values)
 
     def test_error_propagation_raw_events(self) -> None:
-        run = _build_error_graph().stream_v2({"value": "x", "items": []})
+        run = _build_error_graph().stream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         with pytest.raises(ValueError, match="boom"):
             list(run)
 
     def test_error_propagation_interrupted(self) -> None:
-        run = _build_error_graph().stream_v2({"value": "x", "items": []})
+        run = _build_error_graph().stream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         with pytest.raises(ValueError, match="boom"):
             _ = run.interrupted
 
     def test_error_propagation_interrupts(self) -> None:
-        run = _build_error_graph().stream_v2({"value": "x", "items": []})
+        run = _build_error_graph().stream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         with pytest.raises(ValueError, match="boom"):
             _ = run.interrupts
 
 
 class TestStreamV2SyncInterrupt:
     def test_interrupted(self) -> None:
-        run = _build_interrupt_graph().stream_v2(
+        run = _build_interrupt_graph().stream_events(
             {"value": "x", "items": []},
             {"configurable": {"thread_id": "t1"}},
+            version="v3",
         )
         _ = run.output
         assert run.interrupted is True
@@ -522,7 +555,7 @@ class TestStreamV2SyncInterrupt:
 
 
 # ---------------------------------------------------------------------------
-# astream_v2 async tests
+# astream_events(version="v3") async tests
 # ---------------------------------------------------------------------------
 
 
@@ -530,26 +563,34 @@ class TestStreamV2SyncInterrupt:
 @NEEDS_CONTEXTVARS
 class TestStreamV2Async:
     async def test_values_projection(self) -> None:
-        run = await _build_simple_graph().astream_v2({"value": "x", "items": []})
+        run = await _build_simple_graph().astream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         snapshots = [s async for s in run.values]
         assert len(snapshots) >= 1
         last = snapshots[-1]
         assert "A" in last["value"] and "B" in last["value"]
 
     async def test_output(self) -> None:
-        run = await _build_simple_graph().astream_v2({"value": "x", "items": []})
+        run = await _build_simple_graph().astream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         output = await run.output()
         assert output == {"value": "xAB", "items": ["a", "b"]}
 
     async def test_raw_event_iteration(self) -> None:
-        run = await _build_simple_graph().astream_v2({"value": "x", "items": []})
+        run = await _build_simple_graph().astream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         events = [e async for e in run]
         assert len(events) > 0
         for event in events:
             assert event["type"] == "event"
 
     async def test_abort_marks_exhausted_and_closes_mux(self) -> None:
-        run = await _build_simple_graph().astream_v2({"value": "x", "items": []})
+        run = await _build_simple_graph().astream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         values_iter = aiter(run.values)
         _ = await anext(values_iter)
         await run.abort()
@@ -559,21 +600,26 @@ class TestStreamV2Async:
         await run.abort()  # idempotent
 
     async def test_context_manager_calls_abort_on_exit(self) -> None:
-        run = await _build_simple_graph().astream_v2({"value": "x", "items": []})
+        run = await _build_simple_graph().astream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         async with run:
             _ = await anext(aiter(run.values))
         assert run._exhausted is True
 
     async def test_extensions_has_native_keys(self) -> None:
-        run = await _build_simple_graph().astream_v2({"value": "x", "items": []})
+        run = await _build_simple_graph().astream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         _ = await run.output()
         assert "values" in run.extensions and "messages" in run.extensions
         assert run.values is run.extensions["values"]
         assert run.messages is run.extensions["messages"]
 
     async def test_custom_stream_events(self) -> None:
-        run = await _build_custom_stream_graph().astream_v2(
+        run = await _build_custom_stream_graph().astream_events(
             {"value": "x", "items": []},
+            version="v3",
             transformers=[_CustomPassthroughTransformer],
         )
         events = [e async for e in run]
@@ -587,29 +633,39 @@ class TestStreamV2Async:
 @NEEDS_CONTEXTVARS
 class TestStreamV2AsyncErrors:
     async def test_error_propagation_output(self) -> None:
-        run = await _build_error_graph().astream_v2({"value": "x", "items": []})
+        run = await _build_error_graph().astream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         with pytest.raises(ValueError, match="boom"):
             await run.output()
 
     async def test_error_propagation_values(self) -> None:
-        run = await _build_error_graph().astream_v2({"value": "x", "items": []})
+        run = await _build_error_graph().astream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         with pytest.raises(ValueError, match="boom"):
             async for _ in run.values:
                 pass
 
     async def test_error_propagation_raw_events(self) -> None:
-        run = await _build_error_graph().astream_v2({"value": "x", "items": []})
+        run = await _build_error_graph().astream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         with pytest.raises(ValueError, match="boom"):
             async for _ in run:
                 pass
 
     async def test_error_propagation_interrupted(self) -> None:
-        run = await _build_error_graph().astream_v2({"value": "x", "items": []})
+        run = await _build_error_graph().astream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         with pytest.raises(ValueError, match="boom"):
             await run.interrupted()
 
     async def test_error_propagation_interrupts(self) -> None:
-        run = await _build_error_graph().astream_v2({"value": "x", "items": []})
+        run = await _build_error_graph().astream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         with pytest.raises(ValueError, match="boom"):
             await run.interrupts()
 
@@ -618,9 +674,10 @@ class TestStreamV2AsyncErrors:
 @NEEDS_CONTEXTVARS
 class TestStreamV2AsyncInterrupt:
     async def test_interrupted(self) -> None:
-        run = await _build_interrupt_graph().astream_v2(
+        run = await _build_interrupt_graph().astream_events(
             {"value": "x", "items": []},
             {"configurable": {"thread_id": "t2"}},
+            version="v3",
         )
         _ = await run.output()
         assert await run.interrupted() is True
@@ -984,8 +1041,8 @@ class TestCustomTransformer:
                     self._channel.push(self._count)
                 return True
 
-        run = _build_simple_graph().stream_v2(
-            {"value": "x", "items": []}, transformers=[CounterTransformer]
+        run = _build_simple_graph().stream_events(
+            {"value": "x", "items": []}, version="v3", transformers=[CounterTransformer]
         )
         assert "counter" in run.extensions
         counter_iter = iter(run.extensions["counter"])
@@ -1010,15 +1067,15 @@ class TestCustomTransformer:
                     self._log.push("saw_values")
                 return True
 
-        run = _build_simple_graph().stream_v2(
-            {"value": "x", "items": []}, transformers=[FooTransformer]
+        run = _build_simple_graph().stream_events(
+            {"value": "x", "items": []}, version="v3", transformers=[FooTransformer]
         )
         foo_iter = iter(run.foo)
         _ = run.output
         assert "foo" in run.extensions and run.foo is run.extensions["foo"]
         assert "saw_values" in list(foo_iter)
 
-    def test_stream_v2_rejects_transformer_instances(self) -> None:
+    def test_stream_events_v3_rejects_transformer_instances(self) -> None:
         class InstanceTransformer(StreamTransformer):
             def init(self) -> dict[str, Any]:
                 return {}
@@ -1027,8 +1084,10 @@ class TestCustomTransformer:
                 return True
 
         with pytest.raises(TypeError, match="pre-built instance"):
-            _build_simple_graph().stream_v2(
-                {"value": "x", "items": []}, transformers=[InstanceTransformer()]
+            _build_simple_graph().stream_events(
+                {"value": "x", "items": []},
+                version="v3",
+                transformers=[InstanceTransformer()],
             )
 
     def test_stream_channel_auto_forward(self) -> None:
@@ -1047,8 +1106,8 @@ class TestCustomTransformer:
                     self._channel.push("emitted")
                 return True
 
-        run = _build_simple_graph().stream_v2(
-            {"value": "x", "items": []}, transformers=[EmitterTransformer]
+        run = _build_simple_graph().stream_events(
+            {"value": "x", "items": []}, version="v3", transformers=[EmitterTransformer]
         )
         custom_events = [e for e in run if e["method"] == "custom:emitter"]
         assert len(custom_events) > 0
@@ -1092,8 +1151,10 @@ class TestCustomTransformer:
                 return True
 
         with pytest.raises(ValueError, match=r"conflict.*'values'.*ValuesTransformer"):
-            _build_simple_graph().stream_v2(
-                {"value": "x", "items": []}, transformers=[ConflictTransformer]
+            _build_simple_graph().stream_events(
+                {"value": "x", "items": []},
+                version="v3",
+                transformers=[ConflictTransformer],
             )
 
 
@@ -1175,8 +1236,8 @@ class TestStreamChannelAutoLifecycle:
                     self._log.push("got_it")
                 return True
 
-        run = _build_simple_graph().stream_v2(
-            {"value": "x", "items": []}, transformers=[MinimalTransformer]
+        run = _build_simple_graph().stream_events(
+            {"value": "x", "items": []}, version="v3", transformers=[MinimalTransformer]
         )
         minimal_iter = iter(run.extensions["minimal"])
         _ = run.output
@@ -1436,8 +1497,8 @@ class TestAsyncTransformerLane:
             async def afinalize(self) -> None:
                 self._log.close()
 
-        run = await _build_simple_graph().astream_v2(
-            {"value": "x", "items": []}, transformers=[Scorer]
+        run = await _build_simple_graph().astream_events(
+            {"value": "x", "items": []}, version="v3", transformers=[Scorer]
         )
         scores_cursor = aiter(run.extensions["scores"])
         _ = await run.output()
@@ -1453,7 +1514,9 @@ class TestAsyncTransformerLane:
 @NEEDS_CONTEXTVARS
 class TestMemoryBounds:
     def test_sync_subscribed_buffer_stays_at_most_one_between_yields(self) -> None:
-        run = _build_simple_graph().stream_v2({"value": "x", "items": []})
+        run = _build_simple_graph().stream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         events_iter = iter(run)
         max_buffered = 0
         count = 0
@@ -1466,7 +1529,9 @@ class TestMemoryBounds:
         )
 
     def test_unsubscribed_projections_never_accumulate(self) -> None:
-        run = _build_simple_graph().stream_v2({"value": "x", "items": []})
+        run = _build_simple_graph().stream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         list(run)
         values_log = run.extensions["values"]
         messages_log = run.extensions["messages"]
@@ -1474,19 +1539,25 @@ class TestMemoryBounds:
         assert len(messages_log._items) == 0 and not messages_log._subscribed
 
     def test_output_path_does_not_retain_values(self) -> None:
-        run = _build_simple_graph().stream_v2({"value": "x", "items": []})
+        run = _build_simple_graph().stream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         _ = run.output
         values_log = run.extensions["values"]
         assert len(values_log._items) == 0 and not values_log._subscribed
 
     def test_drained_subscriber_buffer_returns_to_empty(self) -> None:
-        run = _build_simple_graph().stream_v2({"value": "x", "items": []})
+        run = _build_simple_graph().stream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         list(run.values)
         assert len(run.extensions["values"]._items) == 0
 
     @pytest.mark.anyio
     async def test_async_single_consumer_buffer_stays_at_most_one(self) -> None:
-        run = await _build_simple_graph().astream_v2({"value": "x", "items": []})
+        run = await _build_simple_graph().astream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         max_buffered = 0
         count = 0
         async for _ in run:
@@ -1497,7 +1568,9 @@ class TestMemoryBounds:
 
     @pytest.mark.anyio
     async def test_async_unsubscribed_projections_never_accumulate(self) -> None:
-        run = await _build_simple_graph().astream_v2({"value": "x", "items": []})
+        run = await _build_simple_graph().astream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         _ = await run.output()
         values_log = run.extensions["values"]
         messages_log = run.extensions["messages"]

libs/langgraph/tests/test_retry.py

@@ -1,4 +1,5 @@
 import asyncio
+import operator
 import sys
 import threading
 import time
@@ -15,7 +16,7 @@ from langchain_core.language_models.fake_chat_models import GenericFakeChatModel
 from langchain_core.messages import AIMessage, AIMessageChunk, BaseMessage, HumanMessage
 from langchain_core.outputs import ChatGeneration, ChatGenerationChunk, ChatResult
 from langchain_core.runnables import RunnableLambda, RunnableParallel
-from langgraph.checkpoint.memory import MemorySaver
+from langgraph.checkpoint.memory import InMemorySaver, MemorySaver
 from langgraph.checkpoint.serde.jsonplus import JsonPlusSerializer
 from typing_extensions import TypedDict
 
@@ -34,7 +35,7 @@ from langgraph._internal._runnable import RunnableCallable
 from langgraph._internal._timeout import coerce_timeout_policy
 from langgraph.channels.ephemeral_value import EphemeralValue
 from langgraph.channels.last_value import LastValue
-from langgraph.errors import GraphInterrupt, NodeTimeoutError, ParentCommand
+from langgraph.errors import GraphInterrupt, NodeError, NodeTimeoutError, ParentCommand
 from langgraph.func import entrypoint, task
 from langgraph.graph import END, START, StateGraph, add_messages
 from langgraph.pregel import NodeBuilder, Pregel
@@ -209,6 +210,15 @@ def test_should_retry_default_retry_on():
     req_error_no_resp.response = None
     assert _should_retry_on(policy, req_error_no_resp) is True
 
+    # NodeTimeoutError should be retryable by default
+    assert (
+        _should_retry_on(
+            policy,
+            NodeTimeoutError("node", 1.0, kind="run", run_timeout=0.5),
+        )
+        is True
+    )
+
     # Should retry on other exceptions by default
     class CustomException(Exception):
         pass
@@ -1455,14 +1465,14 @@ async def test_state_graph_add_node_timeout_composes_with_retry():
     async def flaky(state: _TimeoutState) -> _TimeoutState:
         attempts.append(len(attempts))
         if len(attempts) < 2:
-            await asyncio.sleep(0.5)
+            await asyncio.sleep(1.0)
         return {"x": state["x"] + 1}
 
     builder = StateGraph(_TimeoutState)
     builder.add_node(
         "flaky",
         flaky,
-        timeout=TimeoutPolicy(idle_timeout=0.1),
+        timeout=TimeoutPolicy(idle_timeout=0.3),
         retry_policy=RetryPolicy(
             max_attempts=3,
             initial_interval=0.0,
@@ -1664,15 +1674,28 @@ async def test_arun_with_retry_timeout_observer_tracks_attempts():
 async def test_arun_with_retry_timeout_observer_emits_progress_on_heartbeat():
     events: list = []
 
+    # `_TimedAttemptScope.__init__` sets `_last_progress` to `time.monotonic()`,
+    # but the watchdog itself doesn't start running until after `wrap_config`
+    # and task scheduling — under CI load that gap can be large enough to eat
+    # the entire idle window before the task body's first await even runs. We
+    # defend against that by:
+    #   1. Using a generous idle_timeout so scheduling slack stays well within it.
+    #   2. Calling `runtime.heartbeat()` BEFORE the first sleep, which resets
+    #      `_last_progress` to "now" the moment the task body actually starts.
+    idle_timeout_s = 1.0
+
     class HeartbeatProc:
         async def ainvoke(self, input, config):
             runtime = config[CONF][CONFIG_KEY_RUNTIME]
+            runtime.heartbeat()  # reset the idle clock at task-body entry
             for _ in range(8):
                 await asyncio.sleep(0.05)
                 runtime.heartbeat()
             return "ok"
 
-    task = _make_task(HeartbeatProc(), timeout=_idle_timeout(0.2), name="heartbeat")
+    task = _make_task(
+        HeartbeatProc(), timeout=_idle_timeout(idle_timeout_s), name="heartbeat"
+    )
     task.config[CONF][CONFIG_KEY_TIMED_ATTEMPT_OBSERVER] = events.append
     assert await arun_with_retry(task, retry_policy=None) == "ok"
 
@@ -1681,13 +1704,13 @@ async def test_arun_with_retry_timeout_observer_emits_progress_on_heartbeat():
     assert by_event[-1] == "finish"
     progress = [ev for ev in events if ev.event == "progress"]
     assert progress, "expected at least one progress event from heartbeat"
-    # Rate limit is `idle_timeout / 4` = 0.05s; with 8 heartbeats spaced ~0.05s
-    # we should see at most ~one progress event per heartbeat (well below 8).
+    # Rate limit is `idle_timeout / 4` = 0.25s; with the task running for
+    # ~400ms we expect 1–2 progress events (well below the 9 heartbeats).
     assert len(progress) <= len(by_event)
     for ev in progress:
         assert ev.context.task_name == "heartbeat"
         assert ev.context.attempt == 1
-        assert ev.context.idle_timeout_secs == 0.2
+        assert ev.context.idle_timeout_secs == idle_timeout_s
         assert isinstance(ev.progress_at, datetime)
 
 
@@ -1755,3 +1778,505 @@ async def test_arun_with_retry_timeout_observer_treats_bubble_up_as_non_error():
     assert finish.status == "success"
     assert finish.error_type is None
     assert finish.error_message is None
+
+
+# ---------------------------------------------------------------------------
+# Watcher invariant: any timeout that retry/error_handler can recover from
+# MUST emit `finish=error` BEFORE the in-process recovery work happens. The
+# external watchdog (langgraph-api) relies on this so it only kills a worker
+# when no `finish` arrives within the deadline. The tests below pin down the
+# three recovery paths so a refactor that moves `_finish_timed_attempt` past
+# an `await` (or past the final `raise`) trips CI.
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.anyio
+async def test_arun_with_retry_observer_emits_finish_before_retry_backoff():
+    """`finish=error` of attempt N must arrive before the retry backoff sleep."""
+    timeline: list[tuple[float, Any]] = []
+
+    class TimingOutOnceProc:
+        def __init__(self) -> None:
+            self.calls = 0
+
+        async def ainvoke(self, input, config):
+            self.calls += 1
+            if self.calls == 1:
+                await asyncio.sleep(1.0)
+            return "ok"
+
+    backoff = 0.25
+    policy = RetryPolicy(
+        max_attempts=2,
+        initial_interval=backoff,
+        backoff_factor=1.0,
+        max_interval=backoff,
+        jitter=False,
+        retry_on=NodeTimeoutError,
+    )
+    task = _make_task(
+        TimingOutOnceProc(),
+        timeout=_idle_timeout(0.05),
+        retry_policy=(policy,),
+        name="backoff_watcher",
+    )
+    task.config[CONF][CONFIG_KEY_TIMED_ATTEMPT_OBSERVER] = lambda ev: timeline.append(
+        (time.monotonic(), ev)
+    )
+
+    assert await arun_with_retry(task, retry_policy=None) == "ok"
+
+    starts = [(t, ev) for t, ev in timeline if ev.event == "start"]
+    finishes = [(t, ev) for t, ev in timeline if ev.event == "finish"]
+    assert [ev.context.attempt for _, ev in starts] == [1, 2]
+    assert [ev.status for _, ev in finishes] == ["error", "success"]
+
+    first_finish_t = finishes[0][0]
+    second_start_t = starts[1][0]
+
+    # The watcher relies on this gap: `finish=error` for attempt 1 must arrive
+    # before `arun_with_retry` enters `await asyncio.sleep(backoff)`. We give a
+    # generous slack to keep this stable on slow CI; the structural invariant
+    # is "finish lands first", not "the gap equals exactly backoff".
+    assert second_start_t - first_finish_t >= backoff * 0.5, (
+        f"finish=error appears to be emitted after retry backoff sleep; "
+        f"gap was {second_start_t - first_finish_t:.3f}s, expected >= {backoff * 0.5:.3f}s"
+    )
+
+
+@pytest.mark.anyio
+async def test_state_graph_observer_emits_finish_before_error_handler_start():
+    """Original task's `finish=error` must arrive before the error_handler task's `start`."""
+
+    class State(TypedDict):
+        foo: str
+
+    async def slow_node(state: State) -> State:
+        await asyncio.sleep(1.0)
+        return {"foo": "should-not-happen"}
+
+    async def handler_node(state: State, error: NodeError) -> State:
+        return {"foo": "handled"}
+
+    events: list = []
+    graph = (
+        StateGraph(State)
+        .add_node(
+            "slow",
+            slow_node,
+            timeout=TimeoutPolicy(idle_timeout=0.05),
+            error_handler=handler_node,
+        )
+        .add_edge(START, "slow")
+        .compile()
+    )
+
+    result = await graph.ainvoke(
+        {"foo": ""},
+        config={
+            "configurable": {CONFIG_KEY_TIMED_ATTEMPT_OBSERVER: events.append},
+        },
+    )
+    assert result["foo"] == "handled"
+
+    # Filter to events from the failing node only — the handler node has no
+    # timeout configured here, so it doesn't appear in the observer stream.
+    slow_events = [ev for ev in events if ev.context.task_name == "slow"]
+    starts = [ev for ev in slow_events if ev.event == "start"]
+    finishes = [ev for ev in slow_events if ev.event == "finish"]
+    assert len(starts) == 1
+    assert len(finishes) == 1
+    assert finishes[0].status == "error"
+    assert finishes[0].error_type == "NodeTimeoutError"
+    # The slow task's finish-error event must precede every event for any
+    # follow-up task in the same observer stream.
+    slow_finish_index = events.index(finishes[0])
+    for ev in events[slow_finish_index + 1 :]:
+        assert ev.context.task_name == "slow" or ev.event == "start", (
+            f"unexpected event {ev.event} for {ev.context.task_name} "
+            f"after slow's finish=error"
+        )
+
+
+@pytest.mark.anyio
+async def test_arun_with_retry_observer_emits_finish_before_final_raise_on_exhaustion():
+    """When retry exhausts and the timeout propagates, the final `finish=error` must
+    be emitted before `arun_with_retry` re-raises."""
+    events: list = []
+
+    class AlwaysTimingOutProc:
+        async def ainvoke(self, input, config):
+            await asyncio.sleep(1.0)
+            return "never"
+
+    policy = RetryPolicy(
+        max_attempts=2,
+        initial_interval=0.0,
+        jitter=False,
+        retry_on=NodeTimeoutError,
+    )
+    task = _make_task(
+        AlwaysTimingOutProc(),
+        timeout=_idle_timeout(0.05),
+        retry_policy=(policy,),
+        name="never_succeeds",
+    )
+    task.config[CONF][CONFIG_KEY_TIMED_ATTEMPT_OBSERVER] = events.append
+
+    with pytest.raises(NodeTimeoutError):
+        await arun_with_retry(task, retry_policy=None)
+
+    starts = [ev for ev in events if ev.event == "start"]
+    finishes = [ev for ev in events if ev.event == "finish"]
+    assert [ev.context.attempt for ev in starts] == [1, 2]
+    assert [ev.context.attempt for ev in finishes] == [1, 2]
+    assert [ev.status for ev in finishes] == ["error", "error"]
+    assert all(ev.error_type == "NodeTimeoutError" for ev in finishes)
+    # Both finish events were observed BEFORE arun_with_retry raised, otherwise
+    # the `with pytest.raises` block would have exited before `events` got
+    # populated with the second finish.
+
+
+@pytest.mark.anyio
+async def test_sync_sleep_in_async_node_bypasses_timeout_and_emits_finish_success():
+    """Sync `time.sleep` inside an async node blocks the event loop so the
+    in-process watchdog cannot fire. We document the resulting behavior here:
+
+    1. `NodeTimeoutError` is NOT raised, even though the sync sleep exceeds
+       `idle_timeout`.
+    2. The node's normal return value flows through.
+    3. `finish=success` is emitted to the observer.
+
+    This is the canonical case where the in-process timeout is defeated and
+    the only safety net is the external watcher (langgraph-api), which
+    SIGKILLs the worker when no `finish` arrives within its deadline. The
+    catch is that with a *short* sync sleep the event loop unblocks before
+    the watcher's deadline expires, so the watcher legitimately does not
+    kill — meaning the configured `idle_timeout` is silently honored at the
+    process level only when the block is long enough to outlast the
+    watcher's grace.
+
+    This is the documented "Cooperative cancellation" caveat on
+    `TimeoutPolicy`. The test pins the behavior so any future change that
+    starts raising `NodeTimeoutError` for sync-blocked async nodes (or stops
+    emitting `finish=success`) is caught.
+    """
+    events: list = []
+
+    class SyncSleepingProc:
+        async def ainvoke(self, input, config):
+            time.sleep(0.1)
+            return "completed_despite_timeout"
+
+    task = _make_task(
+        SyncSleepingProc(),
+        timeout=_idle_timeout(0.05),
+        name="sync_sleeper",
+    )
+    task.config[CONF][CONFIG_KEY_TIMED_ATTEMPT_OBSERVER] = events.append
+
+    result = await arun_with_retry(task, retry_policy=None)
+
+    assert result == "completed_despite_timeout"
+    starts = [ev for ev in events if ev.event == "start"]
+    finishes = [ev for ev in events if ev.event == "finish"]
+    assert len(starts) == 1
+    assert len(finishes) == 1
+    assert finishes[0].status == "success"
+    assert finishes[0].error_type is None
+
+
+def test_graph_error_handler_runs_after_retry_exhaustion():
+    class State(TypedDict):
+        foo: str
+
+    attempts = 0
+    captured: dict[str, object] = {}
+
+    def always_failing_node(state: State) -> State:
+        nonlocal attempts
+        attempts += 1
+        raise ValueError("Always fails")
+
+    def err_handler_node(state: State, error: NodeError) -> Command:
+        captured["from_node_name"] = error.node
+        captured["from_node_error"] = error.error
+        return Command(update={"foo": "handled"}, goto="after_handler")
+
+    def after_handler(state: State) -> State:
+        return {"foo": f"{state['foo']}_after"}
+
+    retry_policy = RetryPolicy(
+        max_attempts=2,
+        initial_interval=0.01,
+        jitter=False,
+        retry_on=ValueError,
+    )
+
+    graph = (
+        StateGraph(State)
+        .add_node(
+            "always_failing",
+            always_failing_node,
+            retry_policy=retry_policy,
+            error_handler=err_handler_node,
+        )
+        .add_node("after_handler", after_handler)
+        .add_edge(START, "always_failing")
+        .compile()
+    )
+
+    with patch("time.sleep"):
+        result = graph.invoke({"foo": ""})
+
+    assert attempts == 2
+    assert result["foo"] == "handled_after"
+    assert captured["from_node_name"] == "always_failing"
+    assert isinstance(captured["from_node_error"], BaseException)
+
+
+def test_graph_error_handler_can_route_with_command():
+    class State(TypedDict):
+        foo: str
+
+    attempts = 0
+
+    def always_failing_node(state: State) -> State:
+        nonlocal attempts
+        attempts += 1
+        raise ValueError("Always fails")
+
+    def err_handler_node(state: State) -> Command:
+        return Command(update={"foo": "handled"}, goto="next_node")
+
+    def next_node(state: State) -> State:
+        return {"foo": f"{state['foo']}_next"}
+
+    retry_policy = RetryPolicy(
+        max_attempts=1,
+        initial_interval=0.01,
+        jitter=False,
+        retry_on=ValueError,
+    )
+
+    graph = (
+        StateGraph(State)
+        .add_node(
+            "always_failing",
+            always_failing_node,
+            retry_policy=retry_policy,
+            error_handler=err_handler_node,
+        )
+        .add_node("next_node", next_node)
+        .add_edge(START, "always_failing")
+        .compile()
+    )
+
+    result = graph.invoke({"foo": ""})
+    assert attempts == 1
+    assert result["foo"] == "handled_next"
+
+
+def test_graph_error_handler_failure_fails_run():
+    class State(TypedDict):
+        foo: str
+
+    def always_failing_node(state: State) -> State:
+        raise ValueError("Always fails")
+
+    def err_handler_node(state: State) -> State:
+        raise RuntimeError("handler failed")
+
+    graph = (
+        StateGraph(State)
+        .add_node("always_failing", always_failing_node, error_handler=err_handler_node)
+        .add_edge(START, "always_failing")
+        .compile()
+    )
+
+    with pytest.raises(RuntimeError, match="handler failed"):
+        graph.invoke({"foo": ""})
+
+
+def test_graph_error_handler_handles_subgraph_internal_failure():
+    class SubState(TypedDict):
+        foo: str
+
+    class ParentState(TypedDict):
+        foo: str
+
+    parent_handler_called = False
+    captured: dict[str, object] = {}
+
+    def sub_fail_node(state: SubState) -> SubState:
+        raise ValueError("subgraph boom")
+
+    def parent_handler(state: ParentState, error: NodeError) -> ParentState:
+        nonlocal parent_handler_called
+        parent_handler_called = True
+        captured["from_node_name"] = error.node
+        captured["from_node_error"] = error.error
+        return {"foo": "handled_by_parent"}
+
+    subgraph = (
+        StateGraph(SubState)
+        .add_node("sub_fail_node", sub_fail_node)
+        .add_edge(START, "sub_fail_node")
+        .compile()
+    )
+
+    parent_graph = (
+        StateGraph(ParentState)
+        .add_node("subgraph_node", subgraph, error_handler=parent_handler)
+        .add_edge(START, "subgraph_node")
+        .compile()
+    )
+
+    result = parent_graph.invoke({"foo": ""})
+    assert result["foo"] == "handled_by_parent"
+    assert parent_handler_called is True
+    assert captured["from_node_name"] == "subgraph_node"
+    assert isinstance(captured["from_node_error"], BaseException)
+
+
+def test_graph_error_handler_error_context_survives_checkpoint_resume():
+    class State(TypedDict):
+        foo: str
+
+    captured: dict[str, object] = {}
+
+    def always_failing_node(state: State) -> State:
+        raise RuntimeError("failed before handler")
+
+    def err_handler_node(state: State, error: NodeError) -> State:
+        captured["from_node_name"] = error.node
+        captured["from_node_error"] = error.error
+        return {"foo": "handled_after_resume"}
+
+    checkpointer = InMemorySaver()
+    config = {"configurable": {"thread_id": "graph-error-resume"}}
+    graph = (
+        StateGraph(State)
+        .add_node("always_failing", always_failing_node, error_handler=err_handler_node)
+        .add_edge(START, "always_failing")
+        .compile(
+            checkpointer=checkpointer,
+            interrupt_before=["__error_handler__always_failing"],
+        )
+    )
+
+    # First run pauses before handler, after failure context is checkpointed.
+    graph.invoke({"foo": ""}, config)
+    # Resume should execute handler and recover serialized error context.
+    result = graph.invoke(None, config)
+
+    assert result["foo"] == "handled_after_resume"
+    assert captured["from_node_name"] == "always_failing"
+    assert isinstance(captured["from_node_error"], BaseException)
+
+
+def test_graph_error_handler_does_not_swallow_interrupt_concurrent():
+    """When a graph error handler is configured and a node calls interrupt()
+    concurrently with other nodes, the interrupt must still be raised — not
+    silently swallowed."""
+    from langgraph.types import interrupt
+
+    class State(TypedDict):
+        foo: str
+
+    def node_a(state: State) -> State:
+        # This node uses interrupt() which raises GraphInterrupt
+        val = interrupt("need human input")
+        return {"foo": f"a_{val}"}
+
+    def node_b(state: State) -> State:
+        return {}
+
+    def err_handler(state: State) -> State:
+        return {"foo": "handled"}
+
+    checkpointer = InMemorySaver()
+    graph = (
+        StateGraph(State)
+        .add_node("node_a", node_a, error_handler=err_handler)
+        .add_node("node_b", node_b)
+        # Fan-out: both node_a and node_b run concurrently
+        .add_edge(START, "node_a")
+        .add_edge(START, "node_b")
+        .compile(checkpointer=checkpointer)
+    )
+
+    config = {"configurable": {"thread_id": "test-interrupt-concurrent"}}
+
+    # First invoke should pause at the interrupt, not silently complete
+    graph.invoke({"foo": ""}, config)
+
+    # The graph should have an interrupt pending
+    state = graph.get_state(config)
+    assert len(state.tasks) > 0
+
+    # There should be a pending interrupt from node_a
+    interrupts = [t for t in state.tasks if hasattr(t, "interrupts") and t.interrupts]
+    assert len(interrupts) > 0, (
+        "GraphInterrupt was swallowed — interrupt() in node_a "
+        "should have paused execution"
+    )
+
+
+def test_node_error_handlers_route_to_matching_handler():
+    class State(TypedDict):
+        route: str
+        foo: Annotated[list[str], operator.add]
+
+    def route_node(state: State) -> State:
+        return {"foo": []}
+
+    def choose_node(state: State) -> str:
+        return state["route"]
+
+    def fail_a(state: State) -> State:
+        raise ValueError("a failed")
+
+    def fail_b(state: State) -> State:
+        raise RuntimeError("b failed")
+
+    def handler_a(state: State, error: NodeError) -> State:
+        assert error.node == "fail_a"
+        return {"foo": ["handled_a"]}
+
+    def handler_b(state: State, error: NodeError) -> State:
+        assert error.node == "fail_b"
+        return {"foo": ["handled_b"]}
+
+    graph = (
+        StateGraph(State)
+        .add_node("route_node", route_node)
+        .add_node("fail_a", fail_a, error_handler=handler_a)
+        .add_node("fail_b", fail_b, error_handler=handler_b)
+        .add_edge(START, "route_node")
+        .add_conditional_edges("route_node", choose_node, path_map=["fail_a", "fail_b"])
+        .compile()
+    )
+
+    result_a = graph.invoke({"route": "fail_a", "foo": []})
+    result_b = graph.invoke({"route": "fail_b", "foo": []})
+    assert result_a["foo"] == ["handled_a"]
+    assert result_b["foo"] == ["handled_b"]
+
+
+def test_node_without_error_handler_still_fails_run():
+    class State(TypedDict):
+        foo: str
+
+    def fail_without_handler(state: State) -> State:
+        raise ValueError("no handler")
+
+    graph = (
+        StateGraph(State)
+        .add_node("fail_without_handler", fail_without_handler)
+        .add_edge(START, "fail_without_handler")
+        .compile()
+    )
+
+    with pytest.raises(ValueError, match="no handler"):
+        graph.invoke({"foo": ""})

libs/langgraph/tests/test_runtime.py

@@ -1,3 +1,6 @@
+import asyncio
+import threading
+import time
 from dataclasses import dataclass
 from typing import Any
 
@@ -6,8 +9,15 @@ from langgraph.checkpoint.memory import MemorySaver
 from pydantic import BaseModel, ValidationError
 from typing_extensions import TypedDict
 
+from langgraph.errors import GraphDrained
 from langgraph.graph import END, START, StateGraph
-from langgraph.runtime import ExecutionInfo, Runtime, ServerInfo, get_runtime
+from langgraph.runtime import (
+    ExecutionInfo,
+    RunControl,
+    Runtime,
+    ServerInfo,
+    get_runtime,
+)
 
 
 def test_injected_runtime() -> None:
@@ -79,6 +89,183 @@ def test_merge_runtime() -> None:
     assert runtime1.merge(runtime3).context.api_key == "abc"  # type: ignore
 
 
+def test_merge_runtime_preserves_run_control() -> None:
+    control = RunControl()
+    runtime1 = Runtime(control=control)
+    runtime2 = Runtime(context=None)
+
+    assert runtime1.merge(runtime2).control is control
+
+
+def test_run_control_request_drain_stops_future_steps() -> None:
+    class State(TypedDict, total=False):
+        first: str
+        second: str
+
+    control = RunControl()
+
+    def first_node(state: State) -> dict[str, str]:
+        control.request_drain()
+        return {"first": "done"}
+
+    def second_node(state: State) -> dict[str, str]:
+        return {"second": "should-not-run"}
+
+    graph = StateGraph(State)
+    graph.add_node("first", first_node)
+    graph.add_node("second", second_node)
+    graph.add_edge(START, "first")
+    graph.add_edge("first", "second")
+    graph.add_edge("second", END)
+
+    with pytest.raises(GraphDrained, match="shutdown"):
+        graph.compile().invoke({}, control=control)
+
+
+@pytest.mark.anyio
+async def test_run_control_request_drain_stops_future_steps_async() -> None:
+    class State(TypedDict, total=False):
+        first: str
+        second: str
+
+    control = RunControl()
+
+    async def first_node(state: State) -> dict[str, str]:
+        control.request_drain()
+        return {"first": "done"}
+
+    async def second_node(state: State) -> dict[str, str]:
+        return {"second": "should-not-run"}
+
+    graph = StateGraph(State)
+    graph.add_node("first", first_node)
+    graph.add_node("second", second_node)
+    graph.add_edge(START, "first")
+    graph.add_edge("first", "second")
+    graph.add_edge("second", END)
+
+    with pytest.raises(GraphDrained, match="shutdown"):
+        await graph.compile().ainvoke({}, control=control)
+
+
+def test_drain_requested_in_terminal_step_finishes_normally() -> None:
+    class State(TypedDict, total=False):
+        value: str
+
+    control = RunControl()
+
+    def node(state: State) -> dict[str, str]:
+        control.request_drain()
+        return {"value": "done"}
+
+    graph = StateGraph(State)
+    graph.add_node("node", node)
+    graph.add_edge(START, "node")
+    graph.add_edge("node", END)
+
+    assert graph.compile().invoke({}, control=control) == {"value": "done"}
+    assert control.drain_requested
+
+
+def test_drain_with_exit_durability_persists_resume_checkpoint() -> None:
+    class State(TypedDict, total=False):
+        first: str
+        second: str
+
+    control = RunControl()
+
+    def first_node(state: State) -> dict[str, str]:
+        control.request_drain("sigterm")
+        return {"first": "done"}
+
+    def second_node(state: State) -> dict[str, str]:
+        return {"second": "done"}
+
+    graph = StateGraph(State)
+    graph.add_node("first", first_node)
+    graph.add_node("second", second_node)
+    graph.add_edge(START, "first")
+    graph.add_edge("first", "second")
+    graph.add_edge("second", END)
+
+    compiled = graph.compile(checkpointer=MemorySaver())
+    config = {"configurable": {"thread_id": "drain-exit"}}
+
+    with pytest.raises(GraphDrained, match="sigterm"):
+        compiled.invoke({}, config, durability="exit", control=control)
+
+    assert compiled.invoke(None, config, durability="exit") == {
+        "first": "done",
+        "second": "done",
+    }
+
+
+def test_drain_from_subgraph_can_resume_parent() -> None:
+    class State(TypedDict, total=False):
+        child_first: str
+        child_second: str
+        parent_second: str
+
+    control = RunControl()
+
+    def child_first(state: State) -> dict[str, str]:
+        control.request_drain("sigterm")
+        return {"child_first": "done"}
+
+    def child_second(state: State) -> dict[str, str]:
+        return {"child_second": "done"}
+
+    child_builder = StateGraph(State)
+    child_builder.add_node("child_first", child_first)
+    child_builder.add_node("child_second", child_second)
+    child_builder.add_edge(START, "child_first")
+    child_builder.add_edge("child_first", "child_second")
+    child_builder.add_edge("child_second", END)
+    child_graph = child_builder.compile(checkpointer=True)
+
+    def parent_second(state: State) -> dict[str, str]:
+        return {"parent_second": "done"}
+
+    parent_builder = StateGraph(State)
+    parent_builder.add_node("child", child_graph)
+    parent_builder.add_node("parent_second", parent_second)
+    parent_builder.add_edge(START, "child")
+    parent_builder.add_edge("child", "parent_second")
+    parent_builder.add_edge("parent_second", END)
+
+    compiled = parent_builder.compile(checkpointer=MemorySaver())
+    config = {"configurable": {"thread_id": "drain-subgraph"}}
+
+    with pytest.raises(GraphDrained, match="sigterm"):
+        compiled.invoke({}, config, control=control)
+
+    assert compiled.invoke(None, config) == {
+        "child_first": "done",
+        "child_second": "done",
+        "parent_second": "done",
+    }
+
+
+@pytest.mark.anyio
+async def test_drain_requested_in_terminal_step_finishes_normally_async() -> None:
+    class State(TypedDict, total=False):
+        value: str
+
+    control = RunControl()
+
+    async def node(state: State) -> dict[str, str]:
+        control.request_drain()
+        return {"value": "done"}
+
+    graph = StateGraph(State)
+    graph.add_node("node", node)
+    graph.add_edge(START, "node")
+    graph.add_edge("node", END)
+
+    assert await graph.compile().ainvoke({}, control=control) == {"value": "done"}
+    assert control.drain_requested
+
+
 def test_runtime_propogated_to_subgraph() -> None:
     @dataclass
     class Context:
@@ -392,6 +579,334 @@ def test_context_coercion_pydantic_validation_errors() -> None:
         )
 
 
+def test_external_drain_concurrent_sync() -> None:
+    """External thread calls request_drain() while graph is mid-execution."""
+
+    class State(TypedDict, total=False):
+        first: str
+        second: str
+
+    started = threading.Event()
+
+    def first_node(state: State) -> dict[str, str]:
+        started.set()
+        time.sleep(0.05)
+        return {"first": "done"}
+
+    def second_node(state: State) -> dict[str, str]:
+        return {"second": "should-not-run"}
+
+    graph = StateGraph(State)
+    graph.add_node("first", first_node)
+    graph.add_node("second", second_node)
+    graph.add_edge(START, "first")
+    graph.add_edge("first", "second")
+    graph.add_edge("second", END)
+
+    control = RunControl()
+    compiled = graph.compile()
+
+    exc_holder: list[BaseException | None] = [None]
+
+    def run_graph() -> None:
+        try:
+            compiled.invoke({}, control=control)
+        except GraphDrained as e:
+            exc_holder[0] = e
+
+    t = threading.Thread(target=run_graph)
+    t.start()
+
+    started.wait(timeout=5)
+    control.request_drain("sigterm")
+
+    t.join(timeout=10)
+
+    exc = exc_holder[0]
+    assert isinstance(exc, GraphDrained)
+    assert exc.reason == "sigterm"
+
+
+@pytest.mark.anyio
+async def test_external_drain_concurrent_async() -> None:
+    """External task calls request_drain() while graph is mid-execution."""
+
+    class State(TypedDict, total=False):
+        first: str
+        second: str
+
+    started = asyncio.Event()
+
+    async def first_node(state: State) -> dict[str, str]:
+        started.set()
+        await asyncio.sleep(0.05)
+        return {"first": "done"}
+
+    async def second_node(state: State) -> dict[str, str]:
+        return {"second": "should-not-run"}
+
+    graph = StateGraph(State)
+    graph.add_node("first", first_node)
+    graph.add_node("second", second_node)
+    graph.add_edge(START, "first")
+    graph.add_edge("first", "second")
+    graph.add_edge("second", END)
+
+    control = RunControl()
+    compiled = graph.compile()
+
+    async def drain_after_start() -> None:
+        await started.wait()
+        control.request_drain("sigterm")
+
+    drain_task = asyncio.create_task(drain_after_start())
+
+    with pytest.raises(GraphDrained, match="sigterm"):
+        await compiled.ainvoke({}, control=control)
+
+    await drain_task
+
+
+@pytest.mark.anyio
+async def test_drain_then_cancel_after_graceful_timeout() -> None:
+    """Simulate: drain requested -> node still running -> graceful timeout -> cancel.
+
+    This shows what happens when a long-running node doesn't finish within
+    the graceful period after drain is requested.
+    """
+
+    class State(TypedDict, total=False):
+        first: str
+        second: str
+
+    node_started = asyncio.Event()
+    node_cancelled = asyncio.Event()
+    node_finished = asyncio.Event()
+
+    async def slow_node(state: State) -> dict[str, str]:
+        node_started.set()
+        try:
+            await asyncio.sleep(30)  # very long operation
+        except asyncio.CancelledError:
+            node_cancelled.set()
+            raise
+        node_finished.set()
+        return {"first": "done"}
+
+    async def second_node(state: State) -> dict[str, str]:
+        return {"second": "should-not-run"}
+
+    graph = StateGraph(State)
+    graph.add_node("first", slow_node)
+    graph.add_node("second", second_node)
+    graph.add_edge(START, "first")
+    graph.add_edge("first", "second")
+    graph.add_edge("second", END)
+
+    control = RunControl()
+    compiled = graph.compile()
+
+    # Phase 1: start graph
+    graph_task = asyncio.create_task(compiled.ainvoke({}, control=control))
+
+    # Phase 2: wait for node to start, then request drain
+    await node_started.wait()
+    control.request_drain("sigterm")
+
+    # Phase 3: graceful timeout — node is still running, cancel after 1s
+    graceful_timeout = 1.0
+    await asyncio.sleep(graceful_timeout)
+
+    assert not node_finished.is_set(), "node should still be running"
+    assert not node_cancelled.is_set(), "node should not be cancelled yet"
+
+    # Phase 4: force cancel
+    graph_task.cancel()
+
+    with pytest.raises(asyncio.CancelledError):
+        await graph_task
+
+    # The node received CancelledError at the await point
+    assert node_cancelled.is_set(), "node should have received CancelledError"
+    assert not node_finished.is_set(), "node should NOT have finished normally"
+
+
+@pytest.mark.anyio
+async def test_cancel_ainvoke_with_async_node() -> None:
+    """Cancel ainvoke running an async node: CancelledError is delivered
+    at the await point and the node stops immediately."""
+
+    class State(TypedDict, total=False):
+        first: str
+        second: str
+
+    timeline: list[str] = []
+    node_started = asyncio.Event()
+
+    async def slow_async_node(state: State) -> dict[str, str]:
+        timeline.append(f"async_node:start thread={threading.current_thread().name}")
+        node_started.set()
+        try:
+            await asyncio.sleep(30)
+        except asyncio.CancelledError:
+            timeline.append("async_node:cancelled")
+            raise
+        timeline.append("async_node:finished")
+        return {"first": "done"}
+
+    async def second_node(state: State) -> dict[str, str]:
+        timeline.append("second_node:run")
+        return {"second": "should-not-run"}
+
+    graph = StateGraph(State)
+    graph.add_node("first", slow_async_node)
+    graph.add_node("second", second_node)
+    graph.add_edge(START, "first")
+    graph.add_edge("first", "second")
+    graph.add_edge("second", END)
+
+    compiled = graph.compile()
+    graph_task = asyncio.create_task(compiled.ainvoke({}))
+
+    await node_started.wait()
+    timeline.append("test:cancel")
+    graph_task.cancel()
+
+    with pytest.raises(asyncio.CancelledError):
+        await graph_task
+    timeline.append("test:done")
+
+    # async node runs on the event loop thread (MainThread)
+    assert any("MainThread" in e for e in timeline if "async_node:start" in e)
+    # CancelledError was delivered at the await point — node stopped
+    assert "async_node:cancelled" in timeline
+    # Node did NOT run to completion
+    assert "async_node:finished" not in timeline
+    # Second node never ran
+    assert "second_node:run" not in timeline
+
+
+@pytest.mark.anyio
+async def test_cancel_ainvoke_with_sync_node() -> None:
+    """Cancel ainvoke running a sync node.
+
+    Sync nodes in ainvoke run on a separate thread (via run_in_executor),
+    NOT on the event loop thread. Cancelling the asyncio task disconnects
+    from the thread future, but the thread keeps running as an orphan and
+    completes on its own.
+
+    Key difference from async nodes:
+    - async node: CancelledError stops the coroutine at an await point
+    - sync node: cancel only disconnects asyncio; the thread runs to completion
+
+    In shutdown case, we will ignore this because the instance will be destroyed soon.
+    """
+
+    class State(TypedDict, total=False):
+        first: str
+        second: str
+
+    timeline: list[str] = []
+    node_started = threading.Event()
+    node_finished = threading.Event()
+
+    def slow_sync_node(state: State) -> dict[str, str]:
+        timeline.append(f"sync_node:start thread={threading.current_thread().name}")
+        node_started.set()
+        time.sleep(1)
+        timeline.append("sync_node:after_sleep")
+        node_finished.set()
+        return {"first": "done"}
+
+    def second_node(state: State) -> dict[str, str]:
+        timeline.append("second_node:run")
+        return {"second": "should-not-run"}
+
+    graph = StateGraph(State)
+    graph.add_node("first", slow_sync_node)
+    graph.add_node("second", second_node)
+    graph.add_edge(START, "first")
+    graph.add_edge("first", "second")
+    graph.add_edge("second", END)
+
+    control = RunControl()
+    compiled = graph.compile()
+
+    timeline.append(f"test:main thread={threading.current_thread().name}")
+    graph_task = asyncio.create_task(compiled.ainvoke({}, control=control))
+
+    loop = asyncio.get_event_loop()
+    await loop.run_in_executor(None, node_started.wait, 5)
+
+    timeline.append("test:cancel+drain")
+    graph_task.cancel()
+    control.request_drain("sigterm")
+
+    with pytest.raises(asyncio.CancelledError):
+        await graph_task
+    timeline.append("test:exc=CancelledError")
+
+    # Sync node runs on a background thread (asyncio_*), NOT MainThread
+    sync_start = next(e for e in timeline if "sync_node:start" in e)
+    assert "MainThread" not in sync_start, (
+        "sync node should run on a background thread, not the event loop thread"
+    )
+
+    # At this point, the asyncio task is done but the thread is orphaned.
+    # The sync node has NOT finished yet — cancel only disconnected asyncio.
+    assert not node_finished.is_set(), (
+        "sync node should still be running in its background thread"
+    )
+
+    # Wait for the orphaned thread to complete on its own.
+    await loop.run_in_executor(None, node_finished.wait, 5)
+    assert node_finished.is_set()
+
+    # After the orphaned thread finishes, the full timeline looks like:
+    #   test:main thread=MainThread
+    #   sync_node:start thread=asyncio_N    <- background thread
+    #   test:cancel+drain                   <- cancel + drain fired
+    #   test:exc=CancelledError             <- asyncio disconnected
+    #   sync_node:after_sleep               <- thread ran to completion anyway
+    assert "sync_node:after_sleep" in timeline
+    # Second node never ran
+    assert "second_node:run" not in timeline
+
+    # Verify timeline ordering: cancel happened before node finished
+    cancel_idx = timeline.index("test:cancel+drain")
+    sleep_idx = timeline.index("sync_node:after_sleep")
+    assert cancel_idx < sleep_idx, (
+        "cancel was issued while the sync node was still sleeping"
+    )
+
+
+def test_drain_with_control_parameter_sync() -> None:
+    """Control parameter is wired through invoke -> stream."""
+
+    class State(TypedDict, total=False):
+        value: str
+
+    ran = False
+
+    def node(state: State) -> dict[str, str]:
+        nonlocal ran
+        ran = True
+        return {"value": "done"}
+
+    graph = StateGraph(State)
+    graph.add_node("node", node)
+    graph.add_edge(START, "node")
+    graph.add_edge("node", END)
+
+    # Pre-drained control stops before executing the first pending task.
+    control = RunControl()
+    control.request_drain("pre-drained")
+
+    with pytest.raises(GraphDrained, match="pre-drained"):
+        graph.compile().invoke({}, control=control)
+    assert not ran
+
+
 # --- ExecutionInfo unit tests ---
 
 

libs/langgraph/tests/test_stream_data_transformers.py

@@ -4,7 +4,7 @@ These transformers capture raw protocol events for their respective stream
 modes and expose them as native projections on the run stream (run.custom,
 run.updates, run.checkpoints, run.debug, run.tasks). Tests dispatch synthetic
 protocol events through a StreamMux to isolate transformer logic; the final
-group exercises real graphs through stream_v2.
+group exercises real graphs through stream_events(version="v3").
 """
 
 from __future__ import annotations
@@ -77,8 +77,13 @@ def _arm(mux: StreamMux, transformer: Any) -> None:
     transformer._log._subscribed = True
 
 
+def _unstamped(items):
+    """Strip push stamps from a StreamChannel's internal buffer."""
+    return [item for _stamp, item in items]
+
+
 def _drain(transformer: Any) -> list[Any]:
-    return list(transformer._log._items)
+    return _unstamped(transformer._log._items)
 
 
 # ---------------------------------------------------------------------------
@@ -140,7 +145,7 @@ def test_custom_does_not_suppress_from_main_log() -> None:
 
     mux.push(_custom_event([], "data"))
 
-    methods = [evt["method"] for evt in mux._events._items]
+    methods = [evt["method"] for evt in _unstamped(mux._events._items)]
     assert "custom" in methods
 
 
@@ -219,7 +224,7 @@ def test_checkpoints_does_not_suppress_from_main_log() -> None:
 
     mux.push(_checkpoints_event([], {"values": {}}))
 
-    methods = [evt["method"] for evt in mux._events._items]
+    methods = [evt["method"] for evt in _unstamped(mux._events._items)]
     assert "checkpoints" in methods
 
 
@@ -284,7 +289,7 @@ def test_debug_does_not_suppress_from_main_log() -> None:
 
     mux.push(_debug_event([], {"step": 0}))
 
-    methods = [evt["method"] for evt in mux._events._items]
+    methods = [evt["method"] for evt in _unstamped(mux._events._items)]
     assert "debug" in methods
 
 
@@ -360,7 +365,7 @@ def test_tasks_does_not_suppress_from_main_log() -> None:
 
     mux.push(_tasks_event([], {"id": "t1"}))
 
-    methods = [evt["method"] for evt in mux._events._items]
+    methods = [evt["method"] for evt in _unstamped(mux._events._items)]
     assert "tasks" in methods
 
 
@@ -429,7 +434,7 @@ def test_updates_does_not_suppress_from_main_log() -> None:
 
     mux.push(_updates_event([], {"n": {}}))
 
-    methods = [evt["method"] for evt in mux._events._items]
+    methods = [evt["method"] for evt in _unstamped(mux._events._items)]
     assert "updates" in methods
 
 
@@ -469,11 +474,11 @@ def test_unrelated_events_ignored_by_all() -> None:
     )
 
     for t in transformers:
-        assert list(t._log._items) == []
+        assert _unstamped(t._log._items) == []
 
 
 # ---------------------------------------------------------------------------
-# End-to-end: real graphs through stream_v2
+# End-to-end: real graphs through stream_events(version="v3")
 # ---------------------------------------------------------------------------
 
 
@@ -498,11 +503,11 @@ def _make_simple_graph() -> Any:
     return builder.compile()
 
 
-def test_stream_v2_custom_projection_opt_in() -> None:
+def test_stream_events_v3_custom_projection_opt_in() -> None:
     """run.custom surfaces get_stream_writer() payloads when opted in."""
     graph = _make_simple_graph()
-    run = graph.stream_v2(
-        {"value": "hello", "items": []}, transformers=[CustomTransformer]
+    run = graph.stream_events(
+        {"value": "hello", "items": []}, version="v3", transformers=[CustomTransformer]
     )
 
     custom_events = list(run.custom)
@@ -510,11 +515,11 @@ def test_stream_v2_custom_projection_opt_in() -> None:
     assert any(e.get("status") == "working" for e in custom_events)
 
 
-def test_stream_v2_custom_and_values_coexist() -> None:
+def test_stream_events_v3_custom_and_values_coexist() -> None:
     """Both run.custom and run.values work in the same run."""
     graph = _make_simple_graph()
-    run = graph.stream_v2(
-        {"value": "hello", "items": []}, transformers=[CustomTransformer]
+    run = graph.stream_events(
+        {"value": "hello", "items": []}, version="v3", transformers=[CustomTransformer]
     )
 
     custom_events = list(run.custom)
@@ -523,10 +528,12 @@ def test_stream_v2_custom_and_values_coexist() -> None:
     assert len(custom_events) >= 1
 
 
-def test_stream_v2_tasks_projection_opt_in() -> None:
+def test_stream_events_v3_tasks_projection_opt_in() -> None:
     """run.tasks surfaces raw task events when opted in via transformers=."""
     graph = _make_simple_graph()
-    run = graph.stream_v2({"value": "x", "items": []}, transformers=[TasksTransformer])
+    run = graph.stream_events(
+        {"value": "x", "items": []}, transformers=[TasksTransformer], version="v3"
+    )
 
     tasks_events = list(run.tasks)
     assert len(tasks_events) >= 1
@@ -534,10 +541,12 @@ def test_stream_v2_tasks_projection_opt_in() -> None:
     assert "my_node" in names
 
 
-def test_stream_v2_debug_projection_opt_in() -> None:
+def test_stream_events_v3_debug_projection_opt_in() -> None:
     """run.debug surfaces debug events when opted in via transformers=."""
     graph = _make_simple_graph()
-    run = graph.stream_v2({"value": "x", "items": []}, transformers=[DebugTransformer])
+    run = graph.stream_events(
+        {"value": "x", "items": []}, transformers=[DebugTransformer], version="v3"
+    )
 
     debug_events = list(run.debug)
     assert len(debug_events) >= 1
@@ -545,11 +554,11 @@ def test_stream_v2_debug_projection_opt_in() -> None:
     assert types & {"checkpoint", "task", "task_result"}
 
 
-def test_stream_v2_updates_projection_opt_in() -> None:
+def test_stream_events_v3_updates_projection_opt_in() -> None:
     """run.updates surfaces node output dicts when opted in via transformers=."""
     graph = _make_simple_graph()
-    run = graph.stream_v2(
-        {"value": "x", "items": []}, transformers=[UpdatesTransformer]
+    run = graph.stream_events(
+        {"value": "x", "items": []}, version="v3", transformers=[UpdatesTransformer]
     )
 
     updates = list(run.updates)
@@ -558,11 +567,12 @@ def test_stream_v2_updates_projection_opt_in() -> None:
     assert "my_node" in node_names
 
 
-def test_stream_v2_all_transformers_interleaved() -> None:
+def test_stream_events_v3_all_transformers_interleaved() -> None:
     """All five transformers registered together, consumed via interleave."""
     graph = _make_simple_graph()
-    run = graph.stream_v2(
+    run = graph.stream_events(
         {"value": "x", "items": []},
+        version="v3",
         transformers=[
             CustomTransformer,
             UpdatesTransformer,
@@ -594,7 +604,7 @@ def test_stream_v2_all_transformers_interleaved() -> None:
     assert run.output["value"] == "x!"
 
 
-def test_stream_v2_all_transformers_with_checkpointer() -> None:
+def test_stream_events_v3_all_transformers_with_checkpointer() -> None:
     """All transformers with a checkpointer — run.checkpoints populated."""
     from langgraph.checkpoint.memory import InMemorySaver
 
@@ -604,8 +614,9 @@ def test_stream_v2_all_transformers_with_checkpointer() -> None:
     builder.add_edge("my_node", END)
     graph = builder.compile(checkpointer=InMemorySaver())
 
-    run = graph.stream_v2(
+    run = graph.stream_events(
         {"value": "x", "items": []},
+        version="v3",
         config={"configurable": {"thread_id": "test-all"}},
         transformers=[
             CustomTransformer,
@@ -632,7 +643,7 @@ def test_stream_v2_all_transformers_with_checkpointer() -> None:
     assert len(collected["custom"]) >= 1
 
 
-def test_stream_v2_checkpoints_projection_opt_in() -> None:
+def test_stream_events_v3_checkpoints_projection_opt_in() -> None:
     """run.checkpoints surfaces checkpoint data when opted in with a checkpointer."""
     from langgraph.checkpoint.memory import InMemorySaver
 
@@ -642,8 +653,9 @@ def test_stream_v2_checkpoints_projection_opt_in() -> None:
     builder.add_edge("my_node", END)
     graph = builder.compile(checkpointer=InMemorySaver())
 
-    run = graph.stream_v2(
+    run = graph.stream_events(
         {"value": "x", "items": []},
+        version="v3",
         config={"configurable": {"thread_id": "test-ckpt-standalone"}},
         transformers=[CheckpointsTransformer],
     )
@@ -674,7 +686,7 @@ def test_tasks_and_lifecycle_coregistration() -> None:
 
     assert _drain(tasks) == [task_data]
 
-    methods = [evt["method"] for evt in mux._events._items]
+    methods = [evt["method"] for evt in _unstamped(mux._events._items)]
     assert "tasks" not in methods
 
 
@@ -683,8 +695,9 @@ def test_tasks_and_lifecycle_coregistration_e2e() -> None:
     is present and suppressing them from the main log.
     """
     graph = _make_simple_graph()
-    run = graph.stream_v2(
+    run = graph.stream_events(
         {"value": "x", "items": []},
+        version="v3",
         transformers=[TasksTransformer],
     )
 

libs/langgraph/tests/test_stream_events_v3.py

@@ -19,9 +19,11 @@ from typing_extensions import TypedDict, assert_type
 
 from langgraph._internal._constants import INTERRUPT
 from langgraph.constants import END, START
+from langgraph.errors import GraphDrained
 from langgraph.func import entrypoint
 from langgraph.graph import StateGraph
 from langgraph.graph.message import MessagesState
+from langgraph.runtime import RunControl
 from langgraph.types import (
     CheckpointPayload,
     CheckpointStreamPart,
@@ -229,6 +231,32 @@ class TestV2Stream:
         for c in chunks:
             _assert_stream_part_shape(c)
 
+    def test_stream_events_v3_accepts_control_for_drain(self) -> None:
+        class DrainState(TypedDict, total=False):
+            value: str
+            skipped: str
+
+        control = RunControl()
+
+        def first_node(state: DrainState) -> dict[str, str]:
+            control.request_drain("sigterm")
+            return {"value": "done"}
+
+        def second_node(state: DrainState) -> dict[str, str]:
+            return {"skipped": "nope"}
+
+        builder = StateGraph(DrainState)
+        builder.add_node("first", first_node)
+        builder.add_node("second", second_node)
+        builder.add_edge(START, "first")
+        builder.add_edge("first", "second")
+        builder.add_edge("second", END)
+        graph = builder.compile()
+
+        run = graph.stream_events({}, control=control, version="v3")
+        with pytest.raises(GraphDrained, match="sigterm"):
+            list(run.values)
+
     def test_subgraphs_ns(self) -> None:
         outer = _make_subgraph()
         chunks = list(
@@ -1096,7 +1124,7 @@ class TestV2ValidationErrors:
 
     _INVALID_INPUT: dict[str, Any] = {"value": [1, 2, 3], "items": []}
 
-    def test_stream_v2_pydantic_validation_error(self) -> None:
+    def test_stream_events_v3_pydantic_validation_error(self) -> None:
         """Invalid input to stream with v2 + pydantic state raises ValidationError."""
         graph = _make_pydantic_graph()
         with pytest.raises(ValidationError):

libs/langgraph/tests/test_stream_events_v3_e2e.py

@@ -1,9 +1,9 @@
-"""End-to-end tests exercising all stream_v2 projections together.
+"""End-to-end tests exercising all stream_events(version="v3") projections together.
 
 Each test builds a realistic graph (subgraphs, LLM calls, custom writers,
 interrupts) and verifies that every projection — values, messages, lifecycle,
 subgraphs, raw events, output, interleave — produces correct, consistent
-results through a single stream_v2 / astream_v2 run.
+results through a single stream_events(version="v3") / astream_events(version="v3") run.
 """
 
 from __future__ import annotations
@@ -218,9 +218,9 @@ class _CounterTransformer(StreamTransformer):
 
 class TestStreamV2E2ESync:
     def test_all_projections_nested_graph(self) -> None:
-        """Run a nested graph through stream_v2 and verify values + lifecycle."""
+        """Run a nested graph through stream_events(version="v3") and verify values + lifecycle."""
         graph = _make_nested_graph()
-        run = graph.stream_v2({"value": "x", "items": []})
+        run = graph.stream_events({"value": "x", "items": []}, version="v3")
 
         values_snapshots: list[dict[str, Any]] = []
         lifecycle_events: list[dict[str, Any]] = []
@@ -246,7 +246,7 @@ class TestStreamV2E2ESync:
     def test_subgraph_handles_with_drill_down(self) -> None:
         """Subgraph handles yield and support values drill-down."""
         graph = _make_nested_graph()
-        run = graph.stream_v2({"value": "x", "items": []})
+        run = graph.stream_events({"value": "x", "items": []}, version="v3")
 
         handles = []
         for handle in run.subgraphs:
@@ -270,7 +270,7 @@ class TestStreamV2E2ESync:
     def test_raw_events_have_monotonic_seq(self) -> None:
         """Raw protocol events have monotonically increasing seq numbers."""
         graph = _make_nested_graph()
-        run = graph.stream_v2({"value": "x", "items": []})
+        run = graph.stream_events({"value": "x", "items": []}, version="v3")
         events = list(run)
         assert len(events) > 0
 
@@ -285,11 +285,15 @@ class TestStreamV2E2ESync:
 
     def test_output_matches_final_values_snapshot(self) -> None:
         """output property returns the same state as the last values snapshot."""
-        run1 = _make_nested_graph().stream_v2({"value": "x", "items": []})
+        run1 = _make_nested_graph().stream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         snapshots = list(run1.values)
         final_via_values = snapshots[-1]
 
-        run2 = _make_nested_graph().stream_v2({"value": "x", "items": []})
+        run2 = _make_nested_graph().stream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         final_via_output = run2.output
 
         assert final_via_values == final_via_output
@@ -297,7 +301,7 @@ class TestStreamV2E2ESync:
     def test_context_manager_and_abort(self) -> None:
         """Context manager calls abort, marking the stream exhausted."""
         graph = _make_nested_graph()
-        with graph.stream_v2({"value": "x", "items": []}) as run:
+        with graph.stream_events({"value": "x", "items": []}, version="v3") as run:
             first_val = next(iter(run.values))
             assert isinstance(first_val, dict)
         assert run._exhausted is True
@@ -305,7 +309,7 @@ class TestStreamV2E2ESync:
     def test_extensions_has_all_native_keys(self) -> None:
         """Extensions dict exposes all native projection keys."""
         graph = _make_nested_graph()
-        run = graph.stream_v2({"value": "x", "items": []})
+        run = graph.stream_events({"value": "x", "items": []}, version="v3")
         _ = run.output
 
         assert "values" in run.extensions
@@ -327,7 +331,7 @@ class TestStreamV2E2EMessages:
     def test_messages_projection_from_invoke(self) -> None:
         """Messages projection captures LLM calls via model.invoke() auto-routing."""
         graph = _make_messages_graph()
-        run = graph.stream_v2({"messages": "hi"})
+        run = graph.stream_events({"messages": "hi"}, version="v3")
         streams = list(run.messages)
 
         assert len(streams) >= 1
@@ -350,7 +354,7 @@ class TestStreamV2E2EMessages:
             .compile()
         )
 
-        run = graph.stream_v2({"messages": "go"})
+        run = graph.stream_events({"messages": "go"}, version="v3")
         (stream,) = list(run.messages)
         assert "".join(stream.text) == "streamed answer"
 
@@ -368,7 +372,7 @@ class TestStreamV2E2EMessages:
             .compile()
         )
 
-        run = graph.stream_v2({"messages": "hi"})
+        run = graph.stream_events({"messages": "hi"}, version="v3")
         (stream,) = list(run.messages)
         assert stream.output.text == "hardcoded"
         assert stream.message_id == "msg-1"
@@ -376,7 +380,7 @@ class TestStreamV2E2EMessages:
     def test_root_messages_only_shows_root_scope(self) -> None:
         """Root messages projection doesn't surface subgraph-scoped messages."""
         graph = _make_messages_subgraph()
-        run = graph.stream_v2({"messages": ["hi"], "done": False})
+        run = graph.stream_events({"messages": ["hi"], "done": False}, version="v3")
         root_streams = list(run.messages)
         # The message is emitted inside the subgraph, so the root
         # messages projection (scoped to root namespace) doesn't see it.
@@ -385,7 +389,7 @@ class TestStreamV2E2EMessages:
     def test_subgraph_handle_messages_drill_down(self) -> None:
         """Drilling into subgraph handle's messages surfaces subgraph messages."""
         graph = _make_messages_subgraph()
-        run = graph.stream_v2({"messages": ["hi"], "done": False})
+        run = graph.stream_events({"messages": ["hi"], "done": False}, version="v3")
 
         found_messages = False
         for handle in run.subgraphs:
@@ -407,8 +411,9 @@ class TestStreamV2E2ECustom:
         """Custom StreamWriter events appear on the main log when a
         transformer declares the custom mode."""
         graph = _make_custom_writer_graph()
-        run = graph.stream_v2(
+        run = graph.stream_events(
             {"value": "x", "items": []},
+            version="v3",
             transformers=[_CustomPassthroughTransformer],
         )
         events = list(run)
@@ -420,7 +425,7 @@ class TestStreamV2E2ECustom:
     def test_custom_events_suppressed_without_transformer(self) -> None:
         """Without a custom-mode transformer, custom events don't flow."""
         graph = _make_custom_writer_graph()
-        run = graph.stream_v2({"value": "x", "items": []})
+        run = graph.stream_events({"value": "x", "items": []}, version="v3")
         events = list(run)
         custom = [e for e in events if e["method"] == "custom"]
         assert custom == []
@@ -428,8 +433,9 @@ class TestStreamV2E2ECustom:
     def test_custom_transformer_with_stream_channel(self) -> None:
         """A custom transformer with a StreamChannel produces extension data."""
         graph = _make_nested_graph()
-        run = graph.stream_v2(
+        run = graph.stream_events(
             {"value": "x", "items": []},
+            version="v3",
             transformers=[_CounterTransformer],
         )
 
@@ -444,8 +450,9 @@ class TestStreamV2E2ECustom:
     def test_custom_channel_events_on_main_log(self) -> None:
         """StreamChannel auto-forward injects custom:<name> events into the main log."""
         graph = _make_nested_graph()
-        run = graph.stream_v2(
+        run = graph.stream_events(
             {"value": "x", "items": []},
+            version="v3",
             transformers=[_CounterTransformer],
         )
         events = list(run)
@@ -464,7 +471,7 @@ class TestStreamV2E2EInterrupt:
         """Interrupted run has correct flags and interrupt payloads."""
         graph = _make_interrupt_graph()
         config: dict[str, Any] = {"configurable": {"thread_id": "int-1"}}
-        run = graph.stream_v2({"value": "x", "items": []}, config)
+        run = graph.stream_events({"value": "x", "items": []}, config, version="v3")
 
         output = run.output
         assert output is not None
@@ -477,7 +484,7 @@ class TestStreamV2E2EInterrupt:
         """Values snapshots captured before the interrupt reflect partial state."""
         graph = _make_interrupt_graph()
         config: dict[str, Any] = {"configurable": {"thread_id": "int-2"}}
-        run = graph.stream_v2({"value": "x", "items": []}, config)
+        run = graph.stream_events({"value": "x", "items": []}, config, version="v3")
 
         snapshots = list(run.values)
         assert len(snapshots) >= 1
@@ -494,14 +501,14 @@ class TestStreamV2E2EErrors:
     def test_subgraph_error_propagates_through_output(self) -> None:
         """Error in a subgraph propagates through output."""
         graph = _make_error_subgraph()
-        run = graph.stream_v2({"value": "x", "items": []})
+        run = graph.stream_events({"value": "x", "items": []}, version="v3")
 
         with pytest.raises(ValueError, match="subgraph explosion"):
             _ = run.output
 
     def test_subgraph_error_propagates_through_raw_events(self) -> None:
         graph = _make_error_subgraph()
-        run = graph.stream_v2({"value": "x", "items": []})
+        run = graph.stream_events({"value": "x", "items": []}, version="v3")
 
         with pytest.raises(ValueError, match="subgraph explosion"):
             list(run)
@@ -509,7 +516,7 @@ class TestStreamV2E2EErrors:
     def test_error_subgraph_handle_status(self) -> None:
         """Subgraph handle surfaces the error status."""
         graph = _make_error_subgraph()
-        run = graph.stream_v2({"value": "x", "items": []})
+        run = graph.stream_events({"value": "x", "items": []}, version="v3")
 
         handle = next(iter(run.subgraphs))
         with pytest.raises(RuntimeError, match="subgraph explosion"):
@@ -529,7 +536,7 @@ class TestStreamV2E2EAsync:
     async def test_all_projections_async(self) -> None:
         """Async run exercises values projection."""
         graph = _make_nested_graph()
-        run = await graph.astream_v2({"value": "x", "items": []})
+        run = await graph.astream_events({"value": "x", "items": []}, version="v3")
 
         values_snapshots = [s async for s in run.values]
         assert len(values_snapshots) >= 1
@@ -540,7 +547,7 @@ class TestStreamV2E2EAsync:
     async def test_async_output(self) -> None:
         """Async output returns the final state."""
         graph = _make_nested_graph()
-        run = await graph.astream_v2({"value": "x", "items": []})
+        run = await graph.astream_events({"value": "x", "items": []}, version="v3")
         output = await run.output()
         assert output is not None
         assert output["value"] == "x_routed_processed"
@@ -550,7 +557,7 @@ class TestStreamV2E2EAsync:
     async def test_async_raw_events(self) -> None:
         """Async raw event iteration yields well-formed ProtocolEvents."""
         graph = _make_nested_graph()
-        run = await graph.astream_v2({"value": "x", "items": []})
+        run = await graph.astream_events({"value": "x", "items": []}, version="v3")
         events = [e async for e in run]
         assert len(events) > 0
         seqs = [e["seq"] for e in events]
@@ -572,7 +579,7 @@ class TestStreamV2E2EAsync:
             .compile()
         )
 
-        run = await graph.astream_v2({"messages": "hi"})
+        run = await graph.astream_events({"messages": "hi"}, version="v3")
         streams = [s async for s in run.messages]
         assert len(streams) >= 1
         for s in streams:
@@ -583,7 +590,9 @@ class TestStreamV2E2EAsync:
         """Async interrupted run has correct flags."""
         graph = _make_interrupt_graph()
         config: dict[str, Any] = {"configurable": {"thread_id": "async-int-1"}}
-        run = await graph.astream_v2({"value": "x", "items": []}, config)
+        run = await graph.astream_events(
+            {"value": "x", "items": []}, config, version="v3"
+        )
 
         output = await run.output()
         assert output is not None
@@ -593,14 +602,14 @@ class TestStreamV2E2EAsync:
     async def test_async_error_propagation(self) -> None:
         """Async error from subgraph propagates through output."""
         graph = _make_error_subgraph()
-        run = await graph.astream_v2({"value": "x", "items": []})
+        run = await graph.astream_events({"value": "x", "items": []}, version="v3")
         with pytest.raises(ValueError, match="subgraph explosion"):
             await run.output()
 
     async def test_async_context_manager(self) -> None:
         """Async context manager calls abort on exit."""
         graph = _make_nested_graph()
-        run = await graph.astream_v2({"value": "x", "items": []})
+        run = await graph.astream_events({"value": "x", "items": []}, version="v3")
         async with run:
             _ = await anext(aiter(run.values))
         assert run._exhausted is True
@@ -608,7 +617,7 @@ class TestStreamV2E2EAsync:
     async def test_async_extensions_present(self) -> None:
         """Async run has all native extensions."""
         graph = _make_nested_graph()
-        run = await graph.astream_v2({"value": "x", "items": []})
+        run = await graph.astream_events({"value": "x", "items": []}, version="v3")
         _ = await run.output()
         assert "values" in run.extensions
         assert "messages" in run.extensions
@@ -618,8 +627,9 @@ class TestStreamV2E2EAsync:
     async def test_async_custom_transformer(self) -> None:
         """Async custom transformer with StreamChannel works."""
         graph = _make_nested_graph()
-        run = await graph.astream_v2(
+        run = await graph.astream_events(
             {"value": "x", "items": []},
+            version="v3",
             transformers=[_CounterTransformer],
         )
         assert "counter" in run.extensions
@@ -639,7 +649,7 @@ class TestStreamV2E2ECombined:
     def test_interleave_all_native_projections(self) -> None:
         """Interleave values + messages + lifecycle without deadlock."""
         graph = _make_nested_graph()
-        run = graph.stream_v2({"value": "x", "items": []})
+        run = graph.stream_events({"value": "x", "items": []}, version="v3")
 
         seen_names: set[str] = set()
         for name, _item in run.interleave("values", "messages", "lifecycle"):
@@ -667,8 +677,9 @@ class TestStreamV2E2ECombined:
                 return True
 
         graph = _make_nested_graph()
-        run = graph.stream_v2(
+        run = graph.stream_events(
             {"value": "x", "items": []},
+            version="v3",
             transformers=[_CounterTransformer, TagTransformer],
         )
 
@@ -722,7 +733,7 @@ class TestStreamV2E2ECombined:
             .compile()
         )
 
-        run = outer.stream_v2({"items": []})
+        run = outer.stream_events({"items": []}, version="v3")
         handles = []
         for handle in run.subgraphs:
             list(handle.values)
@@ -740,13 +751,17 @@ class TestStreamV2E2ECombined:
 
     def test_lifecycle_matches_subgraph_handles(self) -> None:
         """Lifecycle events and subgraph handles agree on discovered subgraphs."""
-        run1 = _make_nested_graph().stream_v2({"value": "x", "items": []})
+        run1 = _make_nested_graph().stream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         handle_paths: list[tuple[str, ...]] = []
         for handle in run1.subgraphs:
             list(handle.values)
             handle_paths.append(handle.path)
 
-        run2 = _make_nested_graph().stream_v2({"value": "x", "items": []})
+        run2 = _make_nested_graph().stream_events(
+            {"value": "x", "items": []}, version="v3"
+        )
         lifecycle = list(run2.lifecycle)
 
         started_ns = [
@@ -773,8 +788,9 @@ class TestStreamV2E2ECombined:
             .compile()
         )
 
-        run = graph.stream_v2(
+        run = graph.stream_events(
             {"messages": "hi"},
+            version="v3",
             transformers=[_CounterTransformer],
         )
 

libs/langgraph/tests/test_stream_events_v3_kwarg_forwarding.py

@@ -0,0 +1,108 @@
+"""Tests that ``(a)stream_events(version="v3")`` forwards extra kwargs to the
+underlying ``(a)stream`` call, and rejects the kwargs v3 owns internally.
+
+Background: prior to this change the v3 dispatcher silently dropped ``**kwargs``
+on the v3 branch while forwarding them on v1/v2, so callers passing e.g.
+``context=...`` saw their value disappear with no error. v3 now forwards
+caller kwargs to the inner ``(a)stream`` call but rejects ``stream_mode`` and
+``subgraphs`` since v3 owns them (``stream_mode`` is built from the
+transformer mux; ``subgraphs`` is forced True so nested namespaces flow
+through scoped muxes).
+"""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+from typing import Any
+
+import pytest
+from typing_extensions import TypedDict
+
+from langgraph.constants import END, START
+from langgraph.graph import StateGraph
+from langgraph.runtime import Runtime
+
+NEEDS_CONTEXTVARS = pytest.mark.skipif(
+    sys.version_info < (3, 11),
+    reason="Python 3.11+ is required for async contextvars support",
+)
+
+
+@dataclass
+class _Ctx:
+    api_key: str
+
+
+class _State(TypedDict):
+    message: str
+
+
+def _build_context_reading_graph():
+    def read_context(state: _State, runtime: Runtime[_Ctx]) -> dict[str, Any]:
+        return {"message": f"api key: {runtime.context.api_key}"}
+
+    builder = StateGraph(state_schema=_State, context_schema=_Ctx)
+    builder.add_node("read_context", read_context)
+    builder.add_edge(START, "read_context")
+    builder.add_edge("read_context", END)
+    return builder.compile()
+
+
+class TestKwargForwardingSync:
+    def test_context_reaches_node(self) -> None:
+        run = _build_context_reading_graph().stream_events(
+            {"message": "hello"},
+            version="v3",
+            context=_Ctx(api_key="sk_sync"),
+        )
+        assert run.output == {"message": "api key: sk_sync"}
+
+    def test_rejects_stream_mode(self) -> None:
+        graph = _build_context_reading_graph()
+        with pytest.raises(TypeError, match="stream_mode"):
+            graph.stream_events(
+                {"message": "hello"},
+                version="v3",
+                stream_mode=["values"],
+            )
+
+    def test_rejects_subgraphs(self) -> None:
+        graph = _build_context_reading_graph()
+        with pytest.raises(TypeError, match="subgraphs"):
+            graph.stream_events(
+                {"message": "hello"},
+                version="v3",
+                subgraphs=False,
+            )
+
+
+@pytest.mark.anyio
+@NEEDS_CONTEXTVARS
+class TestKwargForwardingAsync:
+    async def test_context_reaches_node(self) -> None:
+        run = await _build_context_reading_graph().astream_events(
+            {"message": "hello"},
+            version="v3",
+            context=_Ctx(api_key="sk_async"),
+        )
+        output = await run.output()
+        assert output == {"message": "api key: sk_async"}
+
+    async def test_rejects_stream_mode(self) -> None:
+        graph = _build_context_reading_graph()
+        with pytest.raises(TypeError, match="stream_mode"):
+            await graph.astream_events(
+                {"message": "hello"},
+                version="v3",
+                stream_mode=["values"],
+            )
+
+    async def test_rejects_subgraphs(self) -> None:
+        graph = _build_context_reading_graph()
+        with pytest.raises(TypeError, match="subgraphs"):
+            await graph.astream_events(
+                {"message": "hello"},
+                version="v3",
+                subgraphs=False,
+            )

libs/langgraph/tests/test_stream_lifecycle_transformer.py

@@ -6,7 +6,7 @@ on the `lifecycle` channel for both in-process iteration via
 events. Most tests dispatch synthetic protocol events through a
 `StreamMux` to keep the inference logic isolated; the end-of-file
 group exercises the path through real graphs (multi-depth
-discovery, nested `stream_v2` calls with non-empty `parent_ns`).
+discovery, nested `stream_events(version="v3")` calls with non-empty `parent_ns`).
 """
 
 from __future__ import annotations
@@ -35,8 +35,16 @@ def _tasks_start(
     *,
     task_id: str,
     name: str,
+    input: Any = None,
 ) -> dict[str, Any]:
-    """Build a `tasks` ProtocolEvent carrying a TaskPayload (start)."""
+    """Build a `tasks` ProtocolEvent carrying a TaskPayload (start).
+
+    Pass `input=[{"id": ..., "name": ..., "args": {...}}]` (the per-call
+    list shape `langchain.agents.create_agent` Send-fans out) or
+    `input={"tool_call": {"id": ..., ...}, ...}` (the dict envelope older
+    prebuilt agent paths emit) to exercise the lifecycle transformer's
+    `tool_call_id` mining for `lifecycle.started.metadata`.
+    """
     return {
         "type": "event",
         "method": "tasks",
@@ -46,7 +54,7 @@ def _tasks_start(
             "data": {
                 "id": task_id,
                 "name": name,
-                "input": None,
+                "input": input,
                 "triggers": [],
             },
         },
@@ -92,11 +100,16 @@ def _arm(mux: StreamMux) -> None:
             transformer._channel._subscribed = True
 
 
+def _unstamped(items):
+    """Strip push stamps from a StreamChannel's internal buffer."""
+    return [item for _stamp, item in items]
+
+
 def _drain_lifecycle(mux: StreamMux) -> list[LifecyclePayload]:
     """Snapshot the lifecycle channel's buffer."""
     transformer = mux.transformer_by_key("lifecycle")
     assert isinstance(transformer, LifecycleTransformer)
-    return list(transformer._channel._items)
+    return _unstamped(transformer._channel._items)
 
 
 def _build_lifecycle_mux(*, scope: tuple[str, ...] = ()) -> StreamMux:
@@ -118,7 +131,220 @@ def test_started_emitted_on_first_direct_child_task() -> None:
     assert payload["event"] == "started"
     assert payload["namespace"] == ["agent:abc123"]
     assert payload["graph_name"] == "agent"
-    assert payload["trigger_call_id"] == "abc123"
+    assert payload["parent_task_id"] == "abc123"
+
+
+def test_started_carries_metadata_for_dict_envelope_input() -> None:
+    """When the dispatching task's `input` is a dict envelope with a
+    `tool_call` field (the shape older prebuilt agent paths Send-fan
+    out per call), the transformer mines `tool_call_id` from
+    `tool_call.id` and remembers it keyed by the dispatching task id.
+    When that task triggers a subgraph (the child's namespace ends in
+    `name:<dispatching_task_id>`), `lifecycle.started.metadata` carries
+    `{"type": "tool_call", "tool_call_id": ...}`. Identity correlation
+    still uses `parent_task_id`; `tool_call_id` is exposed so UI
+    consumers can anchor the lifecycle event back to the originating
+    AI message tool call. Args are deliberately NOT mined — they live
+    on the AIMessage and have a single source of truth there.
+    """
+    mux = _build_lifecycle_mux()
+    mux.push(
+        _tasks_start(
+            [],
+            task_id="abc123",
+            name="tools",
+            input={
+                "tool_call": {
+                    "id": "call_xyz",
+                    "name": "task",
+                    "args": {"subagent_type": "researcher"},
+                }
+            },
+        )
+    )
+    mux.push(_tasks_start(["agent:abc123"], task_id="t1", name="model"))
+
+    [payload] = _drain_lifecycle(mux)
+    assert payload["event"] == "started"
+    assert payload["parent_task_id"] == "abc123"
+    assert payload["metadata"] == {
+        "type": "tool_call",
+        "tool_call_id": "call_xyz",
+    }
+
+
+def test_started_carries_metadata_for_list_shape_per_call_input() -> None:
+    """`langchain.agents.create_agent` Send-fans out a per-call task
+    whose `input` is a single-element list of tool-call dicts:
+    `[{"id": ..., "name": ..., "args": {...}}]`. The transformer mines
+    `tool_call_id` exactly as for the dict envelope shape, so
+    `lifecycle.started.metadata` fires regardless of which agent factory
+    drove the dispatch.
+    """
+    mux = _build_lifecycle_mux()
+    mux.push(
+        _tasks_start(
+            [],
+            task_id="abc123",
+            name="tools",
+            input=[
+                {
+                    "id": "tc-1",
+                    "name": "task",
+                    "args": {"subagent_type": "researcher"},
+                }
+            ],
+        )
+    )
+    mux.push(_tasks_start(["agent:abc123"], task_id="t1", name="model"))
+
+    [payload] = _drain_lifecycle(mux)
+    assert payload["event"] == "started"
+    assert payload["parent_task_id"] == "abc123"
+    assert payload["metadata"] == {"type": "tool_call", "tool_call_id": "tc-1"}
+
+
+def test_started_carries_metadata_when_args_absent() -> None:
+    """`tool_call_id` is the only field metadata needs; the dispatching
+    envelope can omit `args` entirely (or have non-dict args) and we
+    still produce a metadata as long as `id` is a string."""
+    mux = _build_lifecycle_mux()
+    mux.push(
+        _tasks_start(
+            [],
+            task_id="abc123",
+            name="tools",
+            input=[{"id": "tc-1", "name": "some_tool"}],
+        )
+    )
+    mux.push(_tasks_start(["agent:abc123"], task_id="t1", name="model"))
+
+    [payload] = _drain_lifecycle(mux)
+    assert payload["metadata"] == {"type": "tool_call", "tool_call_id": "tc-1"}
+
+
+def test_list_shape_ignored_when_not_single_element() -> None:
+    """Only single-element lists are recognized as the per-call shape;
+    a 0- or 2+-element list is some other batched/multi-call payload
+    and must not be mined."""
+    # Two-element list — not the per-call shape.
+    mux = _build_lifecycle_mux()
+    mux.push(
+        _tasks_start(
+            [],
+            task_id="abc123",
+            name="tools",
+            input=[
+                {"id": "tc-1", "name": "task"},
+                {"id": "tc-2", "name": "task"},
+            ],
+        )
+    )
+    mux.push(_tasks_start(["agent:abc123"], task_id="t1", name="model"))
+
+    [payload] = _drain_lifecycle(mux)
+    assert "metadata" not in payload
+
+    # Empty list.
+    mux2 = _build_lifecycle_mux()
+    mux2.push(_tasks_start([], task_id="def456", name="tools", input=[]))
+    mux2.push(_tasks_start(["agent:def456"], task_id="t1", name="model"))
+    [payload2] = _drain_lifecycle(mux2)
+    assert "metadata" not in payload2
+
+
+def test_list_shape_robust_to_non_dict_or_missing_id() -> None:
+    """Duck-typing safety: a single-element list whose element isn't a
+    dict, or whose dict has no string `id`, must not raise — it just
+    leaves `metadata` absent."""
+    # Element is not a dict.
+    mux = _build_lifecycle_mux()
+    mux.push(_tasks_start([], task_id="t-a", name="tools", input=["not-a-dict"]))
+    mux.push(_tasks_start(["agent:t-a"], task_id="t1", name="model"))
+    [payload] = _drain_lifecycle(mux)
+    assert "metadata" not in payload
+
+    # Element has no `id`.
+    mux2 = _build_lifecycle_mux()
+    mux2.push(_tasks_start([], task_id="t-b", name="tools", input=[{"name": "task"}]))
+    mux2.push(_tasks_start(["agent:t-b"], task_id="t1", name="model"))
+    [payload2] = _drain_lifecycle(mux2)
+    assert "metadata" not in payload2
+
+    # Element's `id` is not a string.
+    mux3 = _build_lifecycle_mux()
+    mux3.push(_tasks_start([], task_id="t-c", name="tools", input=[{"id": 123}]))
+    mux3.push(_tasks_start(["agent:t-c"], task_id="t1", name="model"))
+    [payload3] = _drain_lifecycle(mux3)
+    assert "metadata" not in payload3
+
+
+def test_parallel_dispatches_attributed_to_correct_parent() -> None:
+    """Two dispatching task envelopes in the same model turn each fan
+    out to their own child subgraph; each child's `metadata.tool_call_id`
+    must reflect its own dispatching envelope, not the other.
+
+    Defends the `parent_task_id` (pregel task id) join: that id is
+    parsed from the child namespace segment and is unique per Send,
+    so it disambiguates parallel dispatches 1:1. Both children share
+    the same `subagent_type` (in args, not on metadata) — only the
+    pregel task id can tell them apart, so the `tool_call_id` must
+    follow the pregel id, not anything from `args`.
+    """
+    mux = _build_lifecycle_mux()
+    mux.push(
+        _tasks_start(
+            [],
+            task_id="parent_A",
+            name="tools",
+            input={
+                "tool_call": {
+                    "id": "call_1",
+                    "name": "task",
+                    "args": {"subagent_type": "researcher"},
+                }
+            },
+        )
+    )
+    mux.push(
+        _tasks_start(
+            [],
+            task_id="parent_B",
+            name="tools",
+            input={
+                "tool_call": {
+                    "id": "call_2",
+                    "name": "task",
+                    "args": {"subagent_type": "researcher"},
+                }
+            },
+        )
+    )
+    mux.push(_tasks_start(["agent:parent_A"], task_id="t1", name="model"))
+    mux.push(_tasks_start(["agent:parent_B"], task_id="t2", name="model"))
+
+    payloads = _drain_lifecycle(mux)
+    by_ns = {tuple(p["namespace"]): p for p in payloads}
+    assert by_ns[("agent:parent_A",)]["metadata"] == {
+        "type": "tool_call",
+        "tool_call_id": "call_1",
+    }
+    assert by_ns[("agent:parent_B",)]["metadata"] == {
+        "type": "tool_call",
+        "tool_call_id": "call_2",
+    }
+
+
+def test_started_omits_metadata_for_structurally_triggered_subgraph() -> None:
+    """Subgraphs triggered without a recognizable tool-call envelope on
+    the parent's input (Send with custom payloads, plain nested
+    `graph.invoke`, etc.) don't get a `metadata` field on
+    `lifecycle.started`."""
+    mux = _build_lifecycle_mux()
+    mux.push(_tasks_start(["agent:abc123"], task_id="t1", name="tool"))
+
+    [payload] = _drain_lifecycle(mux)
+    assert "metadata" not in payload
 
 
 def test_started_dedup_on_repeat_namespace() -> None:
@@ -183,8 +409,12 @@ def test_completed_on_parent_task_result() -> None:
     mux.push(_tasks_start(["agent:abc"], task_id="t1", name="tool"))
     mux.push(_tasks_result([], task_id="abc", name="agent"))
 
-    events = [p["event"] for p in _drain_lifecycle(mux)]
-    assert events == ["started", "completed"]
+    payloads = _drain_lifecycle(mux)
+    assert [p["event"] for p in payloads] == ["started", "completed"]
+    # `parent_task_id` is required on every event for the same subgraph
+    # so consumers can correlate `started` ↔ terminal without joining
+    # via `namespace`.
+    assert all(p["parent_task_id"] == "abc" for p in payloads)
 
 
 def test_failed_on_parent_task_result_with_error() -> None:
@@ -260,6 +490,54 @@ def test_fail_emits_failed_for_other_exceptions() -> None:
     assert payloads[1]["error"] == "boom"
 
 
+def test_parent_task_id_present_on_every_terminal_path() -> None:
+    """Every exit path that emits a terminal event (parent-result with
+    error / interrupts, finalize sweep, fail sweep) must carry
+    `parent_task_id` so consumers can correlate the terminal event
+    back to its `started` without falling back to namespace joins."""
+    # Path 1: parent-result with error.
+    mux = _build_lifecycle_mux()
+    mux.push(_tasks_start(["agent:abc"], task_id="t1", name="tool"))
+    mux.push(_tasks_result([], task_id="abc", name="agent", error="boom"))
+    [_, terminal] = _drain_lifecycle(mux)
+    assert terminal["event"] == "failed"
+    assert terminal["parent_task_id"] == "abc"
+
+    # Path 2: parent-result with interrupts.
+    mux2 = _build_lifecycle_mux()
+    mux2.push(_tasks_start(["agent:def"], task_id="t1", name="tool"))
+    mux2.push(
+        _tasks_result([], task_id="def", name="agent", interrupts=[{"value": "pause"}])
+    )
+    [_, terminal2] = _drain_lifecycle(mux2)
+    assert terminal2["event"] == "interrupted"
+    assert terminal2["parent_task_id"] == "def"
+
+    # Path 3: finalize sweep (no parent result arrived).
+    mux3 = _build_lifecycle_mux()
+    mux3.push(_tasks_start(["agent:ghi"], task_id="t1", name="tool"))
+    mux3.close()
+    [_, terminal3] = _drain_lifecycle(mux3)
+    assert terminal3["event"] == "completed"
+    assert terminal3["parent_task_id"] == "ghi"
+
+    # Path 4: fail sweep with GraphInterrupt.
+    mux4 = _build_lifecycle_mux()
+    mux4.push(_tasks_start(["agent:jkl"], task_id="t1", name="tool"))
+    mux4.fail(GraphInterrupt())
+    [_, terminal4] = _drain_lifecycle(mux4)
+    assert terminal4["event"] == "interrupted"
+    assert terminal4["parent_task_id"] == "jkl"
+
+    # Path 5: fail sweep with generic exception.
+    mux5 = _build_lifecycle_mux()
+    mux5.push(_tasks_start(["agent:mno"], task_id="t1", name="tool"))
+    mux5.fail(RuntimeError("kaboom"))
+    [_, terminal5] = _drain_lifecycle(mux5)
+    assert terminal5["event"] == "failed"
+    assert terminal5["parent_task_id"] == "mno"
+
+
 def test_unrelated_methods_pass_through() -> None:
     """Non-`tasks` events are not consumed and don't emit lifecycle."""
     mux = _build_lifecycle_mux()
@@ -301,7 +579,7 @@ def test_protocol_event_method_is_native() -> None:
     mux = _build_lifecycle_mux()
     mux.push(_tasks_start(["agent:abc"], task_id="t1", name="tool"))
 
-    methods = {evt["method"] for evt in mux._events._items}
+    methods = {evt["method"] for evt in _unstamped(mux._events._items)}
     assert "lifecycle" in methods
     assert "custom:lifecycle" not in methods
 
@@ -312,14 +590,14 @@ def test_tasks_events_suppressed_from_main_log() -> None:
     mux.push(_tasks_start(["agent:abc"], task_id="t1", name="tool"))
     mux.push(_tasks_result([], task_id="abc", name="agent"))
 
-    methods = [evt["method"] for evt in mux._events._items]
+    methods = [evt["method"] for evt in _unstamped(mux._events._items)]
     assert "tasks" not in methods
     # Lifecycle events did make it through, though.
     assert "lifecycle" in methods
 
 
 # ---------------------------------------------------------------------------
-# End-to-end: real graphs through stream_v2
+# End-to-end: real graphs through stream_events(version="v3")
 # ---------------------------------------------------------------------------
 
 
@@ -353,10 +631,10 @@ def _make_two_level_nested() -> Any:
     return outer_b.compile()
 
 
-def test_stream_v2_real_graph_emits_lifecycle_at_each_depth() -> None:
+def test_stream_events_v3_real_graph_emits_lifecycle_at_each_depth() -> None:
     """Outer graph with two nested subgraphs surfaces lifecycle for both."""
     graph = _make_two_level_nested()
-    run = graph.stream_v2({"value": "x", "items": []})
+    run = graph.stream_events({"value": "x", "items": []}, version="v3")
 
     # Iterating the projection drives the pump and drains synthesized
     # lifecycle events at the same time.
@@ -379,17 +657,17 @@ def test_stream_v2_real_graph_emits_lifecycle_at_each_depth() -> None:
         )
 
 
-def test_stream_v2_with_nested_parent_ns_scopes_lifecycle() -> None:
-    """When `stream_v2` is called with a non-empty checkpoint_ns in config,
+def test_stream_events_v3_with_nested_parent_ns_scopes_lifecycle() -> None:
+    """When `stream_events(version="v3")` is called with a non-empty checkpoint_ns in config,
     `_resolve_parent_ns` returns that namespace and the registered
     `LifecycleTransformer` is constructed with `scope=parent_ns`. This
-    exercises the path that exists today purely for nested-stream_v2
+    exercises the path that exists today purely for nested-stream_events(version="v3")
     callers; the test simulates such a caller by injecting a
     checkpoint_ns into the config.
     """
     graph = _make_two_level_nested()
     config = {CONF: {CONFIG_KEY_CHECKPOINT_NS: "outer:abc"}}
-    run = graph.stream_v2({"value": "x", "items": []}, config=config)
+    run = graph.stream_events({"value": "x", "items": []}, config=config, version="v3")
 
     payloads = list(run.lifecycle)
     # Every emitted lifecycle namespace must extend the caller's scope —

libs/langgraph/tests/test_stream_messages_transformer.py

@@ -1,5 +1,5 @@
 """Tests for MessagesTransformer: protocol event routing, whole-message fallback,
-legacy v1 chunk filtering, and end-to-end via stream_v2 / astream_v2."""
+legacy v1 chunk filtering, and end-to-end via stream_events(version="v3") / astream_events(version="v3")."""
 
 from __future__ import annotations
 
@@ -26,6 +26,11 @@ from langgraph.stream.transformers import MessagesTransformer, ValuesTransformer
 TS = int(time.time() * 1000)
 
 
+def _unstamped(items):
+    """Strip push stamps from a StreamChannel's internal buffer."""
+    return [item for _stamp, item in items]
+
+
 # ---------------------------------------------------------------------------
 # Helpers
 # ---------------------------------------------------------------------------
@@ -147,7 +152,7 @@ def _lifecycle(
 def _simple_graph():
     def call_model(state: MessagesState) -> dict[str, Any]:
         model = GenericFakeChatModel(messages=iter(["hello world"]))
-        stream = model.stream_v2(state["messages"])
+        stream = model.stream_events(state["messages"], version="v3")
         return {"messages": stream.output}
 
     return (
@@ -174,7 +179,7 @@ class TestProtocolEventRouting:
             )
         )
         log.close()
-        (stream,) = list(log._items)
+        (stream,) = _unstamped(log._items)
         assert isinstance(stream, ChatModelStream)
         assert stream.message_id == "run-1"
 
@@ -183,7 +188,7 @@ class TestProtocolEventRouting:
         for evt in _lifecycle(text="hello world"):
             t.process(_proto_event(evt, run_id="run-1"))
         log.close()
-        (stream,) = list(log._items)
+        (stream,) = _unstamped(log._items)
         assert stream.done
         assert stream.output.text == "hello world"
 
@@ -206,7 +211,7 @@ class TestProtocolEventRouting:
             )
         )
         log.close()
-        assert list(log._items) == []
+        assert _unstamped(log._items) == []
 
     def test_concurrent_streams_routed_by_run_id(self) -> None:
         t, log = _make_sync_transformer()
@@ -216,7 +221,7 @@ class TestProtocolEventRouting:
             t.process(_proto_event(a, run_id="run-a"))
             t.process(_proto_event(b, run_id="run-b"))
         log.close()
-        streams = list(log._items)
+        streams = _unstamped(log._items)
         assert len(streams) == 2
         by_id = {s.message_id: s for s in streams}
         assert by_id["run-a"].output.text == "aaaa"
@@ -227,7 +232,7 @@ class TestProtocolEventRouting:
         for evt in _lifecycle(text="abcdef"):
             t.process(_proto_event(evt))
         log.close()
-        (stream,) = list(log._items)
+        (stream,) = _unstamped(log._items)
         assert "".join(stream._text_proj._deltas) == "abcdef"
 
     def test_stream_pushed_on_message_start_not_finish(self) -> None:
@@ -250,7 +255,7 @@ class TestProtocolEventRouting:
                 node="my_llm",
             )
         )
-        (stream,) = list(log._items)
+        (stream,) = _unstamped(log._items)
         assert stream.node == "my_llm"
 
 
@@ -264,7 +269,7 @@ class TestWholeMessageFallback:
         t, log = _make_sync_transformer()
         t.process(_whole_msg("the full answer"))
         log.close()
-        (stream,) = list(log._items)
+        (stream,) = _unstamped(log._items)
         assert stream.done
         assert stream.output.text == "the full answer"
 
@@ -272,7 +277,7 @@ class TestWholeMessageFallback:
         t, log = _make_sync_transformer()
         t.process(_whole_msg("full"))
         log.close()
-        (stream,) = list(log._items)
+        (stream,) = _unstamped(log._items)
         assert [e["event"] for e in stream._events] == [
             "message-start",
             "content-block-start",
@@ -318,16 +323,16 @@ class TestFiltering:
             }
         )
         log.close()
-        assert list(log._items) == []
+        assert _unstamped(log._items) == []
 
     def test_legacy_v1_chunks_ignored(self) -> None:
         # v1 AIMessageChunk tuples (from on_llm_new_token) are not streamed
-        # into this projection; callers must migrate to stream_v2.
+        # into this projection; callers must migrate to stream_events(version="v3").
         t, log = _make_sync_transformer()
         t.process(_v1_chunk("hello"))
         t.process(_v1_chunk(" world", finish=True))
         log.close()
-        assert list(log._items) == []
+        assert _unstamped(log._items) == []
 
 
 # ---------------------------------------------------------------------------
@@ -343,7 +348,7 @@ class TestLifecycle:
                 {"event": "message-start", "message_id": "run-1"}, run_id="run-1"
             )
         )
-        streams = list(log._items)
+        streams = _unstamped(log._items)
         err = RuntimeError("graph died")
         t.fail(err)
         assert t._by_run == {}
@@ -371,14 +376,14 @@ class TestAsyncMode:
         t, log = _make_async_transformer()
         for evt in _lifecycle(text="async stream"):
             t.process(_proto_event(evt))
-        assert isinstance(list(log._items)[0], AsyncChatModelStream)
+        assert isinstance(_unstamped(log._items)[0], AsyncChatModelStream)
 
     @pytest.mark.anyio
     async def test_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)
+        (stream,) = _unstamped(log._items)
         assert isinstance(stream, AsyncChatModelStream)
         assert "".join([d async for d in stream.text]) == "hello world"
 
@@ -387,7 +392,7 @@ class TestAsyncMode:
         t, log = _make_async_transformer()
         for evt in _lifecycle(text="async"):
             t.process(_proto_event(evt))
-        (stream,) = list(log._items)
+        (stream,) = _unstamped(log._items)
         assert (await stream.output).text == "async"
 
 
@@ -419,7 +424,7 @@ class TestWireRequestMore:
         for evt in _lifecycle():
             messages_t.process(_proto_event(evt))
 
-        (stream,) = list(log._items)
+        (stream,) = _unstamped(log._items)
         assert stream._request_more is messages_t._pump_fn
 
 
@@ -445,14 +450,14 @@ class TestViaMux:
         for evt in _lifecycle(text="mux stream"):
             mux.push(_proto_event(evt))
         mux.close()
-        (stream,) = list(log._items)
+        (stream,) = _unstamped(log._items)
         assert stream.output.text == "mux stream"
 
     def test_whole_message_via_mux(self) -> None:
         t, mux, log = self._make_mux()
         mux.push(_whole_msg("result"))
         mux.close()
-        (stream,) = list(log._items)
+        (stream,) = _unstamped(log._items)
         assert stream.output.text == "result"
 
     @pytest.mark.anyio
@@ -466,24 +471,24 @@ class TestViaMux:
         for evt in _lifecycle(text="async mux"):
             await mux.apush(_proto_event(evt))
 
-        (stream,) = list(log._items)
+        (stream,) = _unstamped(log._items)
         assert (await stream.output).text == "async mux"
         await mux.aclose()
 
 
 # ---------------------------------------------------------------------------
-# End-to-end: graph → stream_v2 → run.messages (node calls stream_v2)
+# End-to-end: graph → stream_events(version="v3") → run.messages (node calls stream_events)
 # ---------------------------------------------------------------------------
 
 
 class TestEndToEnd:
-    """stream_v2 path: node calls model.stream_v2() explicitly."""
+    """stream_events(version="v3") path: node calls model.stream_events() explicitly."""
 
     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"])
+            stream = model.stream_events(state["messages"], version="v3")
             return {"messages": stream.output}
 
         graph = (
@@ -494,7 +499,7 @@ class TestEndToEnd:
             .compile()
         )
 
-        run = graph.stream_v2({"messages": "hi"})
+        run = graph.stream_events({"messages": "hi"}, version="v3")
         (stream,) = list(run.messages)
         assert isinstance(stream, ChatModelStream)
         assert stream.output.text == "hello world"
@@ -504,7 +509,7 @@ class TestEndToEnd:
         model = GenericFakeChatModel(messages=iter(["streamed answer"]))
 
         def call_model(state: MessagesState) -> dict[str, Any]:
-            stream = model.stream_v2(state["messages"])
+            stream = model.stream_events(state["messages"], version="v3")
             return {"messages": stream.output}
 
         graph = (
@@ -515,7 +520,7 @@ class TestEndToEnd:
             .compile()
         )
 
-        run = graph.stream_v2({"messages": "go"})
+        run = graph.stream_events({"messages": "go"}, version="v3")
         (stream,) = list(run.messages)
         assert "".join(stream.text) == "streamed answer"
 
@@ -533,7 +538,7 @@ class TestEndToEnd:
             .compile()
         )
 
-        run = graph.stream_v2({"messages": "hi"})
+        run = graph.stream_events({"messages": "hi"}, version="v3")
         (stream,) = list(run.messages)
         assert stream.output.text == "hardcoded"
 
@@ -542,7 +547,7 @@ class TestEndToEnd:
         model = GenericFakeChatModel(messages=iter(["async answer"]))
 
         async def call_model(state: MessagesState) -> dict[str, Any]:
-            stream = await model.astream_v2(state["messages"])
+            stream = await model.astream_events(state["messages"], version="v3")
             return {"messages": await stream}
 
         graph = (
@@ -553,7 +558,7 @@ class TestEndToEnd:
             .compile()
         )
 
-        run = await graph.astream_v2({"messages": "hi"})
+        run = await graph.astream_events({"messages": "hi"}, version="v3")
         streams = [s async for s in run.messages]
         assert len(streams) == 1
         assert isinstance(streams[0], AsyncChatModelStream)
@@ -567,7 +572,7 @@ class TestEndToEnd:
         model = GenericFakeChatModel(messages=iter(["hello world"]))
 
         async def call_model(state: MessagesState) -> dict[str, Any]:
-            stream = await model.astream_v2(state["messages"])
+            stream = await model.astream_events(state["messages"], version="v3")
             return {"messages": await stream}
 
         graph = (
@@ -578,7 +583,7 @@ class TestEndToEnd:
             .compile()
         )
 
-        run = await graph.astream_v2({"messages": "hi"})
+        run = await graph.astream_events({"messages": "hi"}, version="v3")
 
         async def consume() -> list[str]:
             collected: list[str] = []
@@ -591,12 +596,12 @@ class TestEndToEnd:
 
 
 # ---------------------------------------------------------------------------
-# End-to-end: graph → stream_v2 → run.messages (node calls invoke)
+# End-to-end: graph → stream_events(version="v3") → run.messages (node calls invoke)
 # ---------------------------------------------------------------------------
 
 
 class TestEndToEndV2Invoke:
-    """Auto-routing path: stream_v2 injects CONFIG_KEY_STREAM_MESSAGES_V2,
+    """Auto-routing path: stream_events(version="v3") injects CONFIG_KEY_STREAM_MESSAGES_V2,
     causing BaseChatModel to drive the v2 protocol event generator even for
     model.invoke()."""
 
@@ -615,7 +620,7 @@ class TestEndToEndV2Invoke:
     def test_invoke_populates_messages(self) -> None:
         run = self._graph(
             GenericFakeChatModel(messages=iter(["hello world"]))
-        ).stream_v2({"messages": "hi"})
+        ).stream_events({"messages": "hi"}, version="v3")
         (stream,) = list(run.messages)
         assert isinstance(stream, ChatModelStream)
         assert stream.output.text == "hello world"
@@ -624,7 +629,7 @@ class TestEndToEndV2Invoke:
         """Iterating the stream yields the full v2 lifecycle, not v1 chunks."""
         run = self._graph(
             GenericFakeChatModel(messages=iter(["streamed answer"]))
-        ).stream_v2({"messages": "go"})
+        ).stream_events({"messages": "go"}, version="v3")
         (stream,) = list(run.messages)
 
         events = list(stream)
@@ -645,7 +650,7 @@ class TestEndToEndV2Invoke:
     def test_invoke_text_deltas_iterate(self) -> None:
         run = self._graph(
             GenericFakeChatModel(messages=iter(["delta streaming works"]))
-        ).stream_v2({"messages": "hi"})
+        ).stream_events({"messages": "hi"}, version="v3")
         (stream,) = list(run.messages)
         assert "".join(stream.text) == "delta streaming works"
 
@@ -669,7 +674,7 @@ class TestEndToEndV2Invoke:
             .compile()
         )
 
-        streams = list(graph.stream_v2({"messages": "hi"}).messages)
+        streams = list(graph.stream_events({"messages": "hi"}, version="v3").messages)
         assert len(streams) == 2
         assert {s.output.text for s in streams} == {"alpha", "beta"}
 
@@ -693,7 +698,7 @@ class TestEndToEndV2Invoke:
             .compile()
         )
 
-        run = graph.stream_v2({"messages": "hi"})
+        run = graph.stream_events({"messages": "hi"}, version="v3")
         streams = list(run.messages)
         assert len(streams) == 2
         assert streams[0].node == "streaming_node"
@@ -717,7 +722,7 @@ class TestEndToEndV2Invoke:
             .compile()
         )
 
-        run = await graph.astream_v2({"messages": "hi"})
+        run = await graph.astream_events({"messages": "hi"}, version="v3")
         streams = [s async for s in run.messages]
         assert len(streams) == 1
         assert isinstance(streams[0], AsyncChatModelStream)
@@ -732,7 +737,7 @@ class TestEndToEndV2Invoke:
 class TestDirectMessagesModeStaysV1:
     def test_direct_graph_stream_messages_yields_ai_message_chunks(self) -> None:
         """graph.stream(stream_mode="messages") must not leak v2 event dicts —
-        the v2 flag is only injected by stream_v2 / astream_v2."""
+        the v2 flag is only injected by stream_events(version="v3") / astream_events(version="v3")."""
         model = GenericFakeChatModel(messages=iter(["legacy path"]))
 
         def call_model(state: MessagesState) -> dict[str, Any]:
@@ -755,8 +760,10 @@ class TestDirectMessagesModeStaysV1:
             == "legacy path"
         )
 
-    def test_nested_graph_stream_messages_stays_v1_under_outer_stream_v2(self) -> None:
-        """An outer `stream_v2()` run must not flip an inner direct
+    def test_nested_graph_stream_messages_stays_v1_under_outer_stream_events_v3(
+        self,
+    ) -> None:
+        """An outer `stream_events(version="v3")` run must not flip an inner direct
         `stream_mode="messages"` call onto the v2 event protocol."""
         model = GenericFakeChatModel(messages=iter(["nested legacy path"]))
 
@@ -807,7 +814,7 @@ class TestDirectMessagesModeStaysV1:
             .compile()
         )
 
-        result = outer.stream_v2({}).output
+        result = outer.stream_events({}, version="v3").output
 
         assert result is not None
         assert result["saw_only_chunks"] is True

libs/langgraph/tests/test_stream_subgraph_transformer.py

@@ -4,7 +4,7 @@ Subscribes to `tasks` events and produces in-process `SubgraphRunStream`
 handles backed by mini-muxes (built via `StreamMux._make_child`). The
 synthetic-event tests isolate the inference / mini-mux wiring; the
 real-graph tests exercise the end-to-end navigation path through
-`stream_v2`.
+`stream_events(version="v3")`.
 """
 
 from __future__ import annotations
@@ -93,7 +93,7 @@ def _tasks_result(
 
 
 def _native_factories() -> list[Any]:
-    """Mirror the factory list `Pregel.stream_v2` registers."""
+    """Mirror the factory list `Pregel.stream_events(version="v3")` registers."""
     return [
         ValuesTransformer,
         MessagesTransformer,
@@ -159,8 +159,13 @@ def _subgraph_transformer(mux: StreamMux) -> SubgraphTransformer:
     return transformer
 
 
+def _unstamped(items):
+    """Strip push stamps from a StreamChannel's internal buffer."""
+    return [item for _stamp, item in items]
+
+
 def _drain_subgraphs(mux: StreamMux) -> list[SubgraphRunStream]:
-    return list(_subgraph_transformer(mux)._log._items)
+    return _unstamped(_subgraph_transformer(mux)._log._items)
 
 
 def _child_mux(handle: SubgraphRunStream | AsyncSubgraphRunStream) -> StreamMux:
@@ -169,13 +174,13 @@ def _child_mux(handle: SubgraphRunStream | AsyncSubgraphRunStream) -> StreamMux:
 
 
 def _event_items(mux: StreamMux) -> list[ProtocolEvent]:
-    return list(mux._events._items)
+    return _unstamped(mux._events._items)
 
 
 def _lifecycle_payloads(mux: StreamMux) -> list[dict[str, Any]]:
     lifecycle_t = mux.transformer_by_key("lifecycle")
     assert isinstance(lifecycle_t, LifecycleTransformer)
-    return list(lifecycle_t._channel._items)
+    return _unstamped(lifecycle_t._channel._items)
 
 
 # ---------------------------------------------------------------------------
@@ -190,7 +195,7 @@ def test_handle_created_on_first_direct_child_task() -> None:
     [handle] = _drain_subgraphs(mux)
     assert handle.path == ("agent:abc",)
     assert handle.graph_name == "agent"
-    assert handle.trigger_call_id == "abc"
+    assert handle.parent_task_id == "abc"
     assert handle.status == "started"
     _child_mux(handle)  # mini-mux backed
 
@@ -247,7 +252,7 @@ def test_grandchild_discovered_via_child_mini_mux() -> None:
     [child_handle] = _drain_subgraphs(mux)
     assert child_handle.path == ("agent:abc",)
     # The grandchild appears on the CHILD'S subgraphs projection.
-    grandchildren = list(child_handle.subgraphs._items)
+    grandchildren = _unstamped(child_handle.subgraphs._items)
     assert len(grandchildren) == 1
     assert grandchildren[0].path == ("agent:abc", "tool:def")
 
@@ -756,10 +761,10 @@ def _make_failing_nested() -> Any:
     return outer_b.compile()
 
 
-def test_stream_v2_real_graph_yields_subgraph_handles() -> None:
+def test_stream_events_v3_real_graph_yields_subgraph_handles() -> None:
     """Iterating `run.subgraphs` yields handles for direct-child subgraphs."""
     graph = _make_two_level_nested()
-    run = graph.stream_v2({"value": "x", "items": []})
+    run = graph.stream_events({"value": "x", "items": []}, version="v3")
 
     handle_paths: list[tuple[str, ...]] = []
     final_status: dict[tuple[str, ...], str] = {}
@@ -775,10 +780,10 @@ def test_stream_v2_real_graph_yields_subgraph_handles() -> None:
     assert final_status[handle_paths[0]] == "completed"
 
 
-def test_stream_v2_grandchild_visible_on_child_handle() -> None:
+def test_stream_events_v3_grandchild_visible_on_child_handle() -> None:
     """Drilling into `handle.subgraphs` surfaces nested grandchildren."""
     graph = _make_two_level_nested()
-    run = graph.stream_v2({"value": "x", "items": []})
+    run = graph.stream_events({"value": "x", "items": []}, version="v3")
 
     grandchild_paths: list[tuple[str, ...]] = []
     middle_path: tuple[str, ...] | None = None
@@ -805,7 +810,7 @@ def test_subgraph_output_stops_at_own_terminal_without_draining_siblings() -> No
     inside the loop body misses its events.
     """
     graph = _make_two_sibling_subgraphs()
-    run = graph.stream_v2({"value": "x", "items": []})
+    run = graph.stream_events({"value": "x", "items": []}, version="v3")
 
     paths: list[tuple[str, ...]] = []
     second_values: list[dict[str, Any]] = []
@@ -824,7 +829,7 @@ def test_subgraph_output_stops_at_own_terminal_without_draining_siblings() -> No
 
 def test_aborted_subgraph_handle_does_not_fail_parent_forwarding() -> None:
     graph = _make_two_sibling_subgraphs()
-    run = graph.stream_v2({"value": "x", "items": []})
+    run = graph.stream_events({"value": "x", "items": []}, version="v3")
 
     seen: list[str | None] = []
     for handle in run.subgraphs:
@@ -842,7 +847,7 @@ def test_aborted_subgraph_handle_does_not_fail_parent_forwarding() -> None:
 
 def test_failed_subgraph_output_raises_terminal_error() -> None:
     graph = _make_failing_nested()
-    run = graph.stream_v2({"value": "x", "items": []})
+    run = graph.stream_events({"value": "x", "items": []}, version="v3")
 
     handle = next(iter(run.subgraphs))
     with pytest.raises(RuntimeError, match="child boom"):

libs/prebuilt/langgraph/prebuilt/_tool_call_transformer.py

@@ -77,10 +77,16 @@ class ToolCallTransformer(StreamTransformer):
         return stream
 
     def process(self, event: ProtocolEvent) -> bool:
-        # Namespace filtering is handled by the mux via `scope_exact`.
         if event["method"] != "tools":
             return True
 
+        # Only project events emitted at this transformer's scope. Subgraph
+        # events still flow through the parent's mux (the parent's main
+        # event log keeps them) but they belong to the child mini-mux's
+        # `tool_calls` projection, not the parent's.
+        if tuple(event["params"]["namespace"]) != self.scope:
+            return True
+
         data = event["params"]["data"]
         tool_call_id = data.get("tool_call_id")
         if tool_call_id is None:

libs/prebuilt/langgraph/prebuilt/tool_node.py

@@ -44,7 +44,7 @@ import inspect
 import json
 from collections.abc import Awaitable, Callable
 from copy import copy, deepcopy
-from dataclasses import dataclass, replace
+from dataclasses import dataclass, field, replace
 from types import UnionType
 from typing import (
     TYPE_CHECKING,
@@ -1723,9 +1723,9 @@ class ToolRuntime(_DirectlyInjectedToolArg, Generic[ContextT, StateT]):
     context: ContextT
     config: RunnableConfig
     stream_writer: StreamWriter
-    tools: list[BaseTool]
     tool_call_id: str | None
     store: BaseStore | None
+    tools: list[BaseTool] = field(default_factory=list)
     execution_info: ExecutionInfo | None = None
     server_info: ServerInfo | None = None
 

libs/prebuilt/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "langgraph-prebuilt"
-version = "1.0.12"
+version = "1.1.0a2"
 description = "Library with high-level APIs for creating and executing LangGraph agents and tools."
 authors = []
 requires-python = ">=3.10"

libs/prebuilt/tests/test_tool_call_transformer.py

@@ -30,6 +30,11 @@ from langgraph.prebuilt._tool_call_stream import ToolCallStream
 TS = int(time.time() * 1000)
 
 
+def _unstamped(items):
+    """Strip push stamps from a StreamChannel's internal buffer."""
+    return [item for _stamp, item in items]
+
+
 def _tool_event(
     event: str,
     tool_call_id: str,
@@ -95,7 +100,7 @@ class TestToolCallTransformerUnit:
                 input={"text": "hi"},
             )
         )
-        handles = list(transformer._log._items)
+        handles = _unstamped(transformer._log._items)
         assert len(handles) == 1
         h = handles[0]
         assert isinstance(h, ToolCallStream)
@@ -111,7 +116,7 @@ class TestToolCallTransformerUnit:
         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"]
+        assert _unstamped(stream._output_deltas._items) == ["a", "b"]
 
     def test_finish_closes_stream(self) -> None:
         mux, transformer = _mux()
@@ -142,16 +147,89 @@ class TestToolCallTransformerUnit:
         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"]
+        assert _unstamped(transformer._active["a"]._output_deltas._items) == [
+            "A1",
+            "A2",
+        ]
+        assert _unstamped(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"]
+        kept = [e for e in _unstamped(mux._events._items) if e["method"] == "tools"]
         assert len(kept) == 1
 
+    def test_out_of_scope_event_skipped(self) -> None:
+        """Subgraph-scoped `tools` events must not project into a parent
+        transformer's `tool_calls` log.
+
+        The parent's main event log keeps the event (so wire consumers
+        still see it) but the parent's `ToolCallTransformer` only owns
+        the projection at its own scope. Per-scope `ToolCallTransformer`
+        instances on child mini-muxes are responsible for projecting
+        events at their own depth.
+        """
+        # Root-scope transformer (`scope == ()`).
+        mux, transformer = _mux()
+        _subscribe(mux._events)
+        mux.push(
+            _tool_event(
+                "tool-started",
+                "tc1",
+                tool_name="inner_echo",
+                namespace=["child:abc"],
+            )
+        )
+        # No `ToolCallStream` was projected into the root's log.
+        assert _unstamped(transformer._log._items) == []
+        assert "tc1" not in transformer._active
+        # The event still passes through the main event log so consumers
+        # of the raw `tools` channel see it untouched.
+        kept = [e for e in _unstamped(mux._events._items) if e["method"] == "tools"]
+        assert len(kept) == 1
+
+    def test_in_scope_event_projected_when_scope_set(self) -> None:
+        """A non-root transformer projects only events at its own scope."""
+        scope: tuple[str, ...] = ("child:abc",)
+        transformer = ToolCallTransformer(scope=scope)
+        mux = StreamMux(
+            [ValuesTransformer(), MessagesTransformer(), transformer],
+            scope=scope,
+            is_async=False,
+        )
+        _subscribe(transformer._log)
+        # Event at this scope: projected.
+        mux.push(
+            _tool_event(
+                "tool-started",
+                "tc1",
+                tool_name="echo",
+                namespace=list(scope),
+            )
+        )
+        assert len(_unstamped(transformer._log._items)) == 1
+        # Event at a deeper scope: ignored.
+        mux.push(
+            _tool_event(
+                "tool-started",
+                "tc2",
+                tool_name="grandchild",
+                namespace=[*scope, "grand:xyz"],
+            )
+        )
+        assert len(_unstamped(transformer._log._items)) == 1
+        # Event at root (above this scope): ignored.
+        mux.push(
+            _tool_event(
+                "tool-started",
+                "tc3",
+                tool_name="root_tool",
+                namespace=[],
+            )
+        )
+        assert len(_unstamped(transformer._log._items)) == 1
+
 
 # ---------------------------------------------------------------------------
 # End-to-end tests with a real graph
@@ -194,7 +272,9 @@ class TestToolCallTransformerEndToEnd:
             }
 
         graph = _build_graph(caller, [streamer])
-        run = graph.stream_v2({"messages": []}, transformers=[ToolCallTransformer])
+        run = graph.stream_events(
+            {"messages": []}, transformers=[ToolCallTransformer], version="v3"
+        )
 
         tool_calls: list[ToolCallStream] = []
         for tc in run.tool_calls:
@@ -230,11 +310,13 @@ class TestToolCallTransformerEndToEnd:
         # 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": []})
+        run_no_tc = graph.stream_events({"messages": []}, version="v3")
         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])
+        run = graph.stream_events(
+            {"messages": []}, transformers=[ToolCallTransformer], version="v3"
+        )
         assert "tool_calls" in run._mux.extensions  # type: ignore[attr-defined]
         # Drain so the run closes cleanly.
         list(run.tool_calls)
@@ -261,8 +343,8 @@ class TestToolCallTransformerEndToEnd:
             }
 
         graph = _build_graph(caller, [astreamer])
-        run = await graph.astream_v2(
-            {"messages": []}, transformers=[ToolCallTransformer]
+        run = await graph.astream_events(
+            {"messages": []}, version="v3", transformers=[ToolCallTransformer]
         )
 
         collected: list[ToolCallStream] = []
@@ -291,7 +373,9 @@ class TestToolCallTransformerEndToEnd:
             }
 
         graph = _build_graph(caller, [boom])
-        run = graph.stream_v2({"messages": []}, transformers=[ToolCallTransformer])
+        run = graph.stream_events(
+            {"messages": []}, transformers=[ToolCallTransformer], version="v3"
+        )
 
         collected: list[ToolCallStream] = []
         with pytest.raises(ValueError, match="nope"):