langgraph-api 0.12.0.dev9__tar.gz → 0.12.0.dev11__tar.gz

{langgraph_api-0.12.0.dev9 → langgraph_api-0.12.0.dev11}/Makefile

@@ -1,7 +1,7 @@
 .PHONY: build release lint format test test_watch start start-inmem start-inmem-license-oss start start-js-server build-go-server start-go-server stop-go-server check-version check-base-imports test-a2a-tck test-a2a-tck-mandatory start-test-a2a-tck start-test-a2a-tck-mandatory start-test-a2a-tck-watch test-mcp-conformance start-test-mcp-conformance list-mcp-scenarios test-auth-read-only-assistant
 
 # Environment variables
-LANGSERVE_GRAPHS_ALL = '{"agent": {"path": "./tests/graphs/agent.py:graph", "description": "agent"}, "assistant_id_runtime": "./tests/graphs/assistant_id_runtime.py:graph", "custom_lifespan": "./tests/graphs/my_router.py:graph", "single_node": "./tests/graphs/single_node.py:graph", "benchmark": "./tests/graphs/benchmark.py:graph", "config_graph": "./tests/graphs/config_graph.py:graph", "other": "./tests/graphs/other.py:make_graph", "weather": "./tests/graphs/weather.py:mk_weather_graph", "searchy": "./tests/graphs/searchy.py:graph", "agent_simple": "./tests/graphs/agent_simple.py:graph", "simple_runtime": "./tests/graphs/simple_runtime.py:graph", "agent_interrupt": "./tests/graphs/agent_interrupt.py:graph", "agent_parallel_interrupt": "./tests/graphs/agent_parallel_interrupt.py:graph", "message_type_test": "./tests/graphs/message_type_test.py:graph", "remote_subgraph_parent": "./tests/graphs/remote_subgraph_parent.py:graph", "simple_remote": "./tests/graphs/simple_remote.py:graph", "nested_subgraphs": "./tests/graphs/nested_subgraphs.py:graph", "functional_fibonacci": "./tests/graphs/functional_fibonacci.py:fibonacci", "state_graph_fibonacci": "./tests/graphs/state_graph_fibonacci.py:fibonacci", "max_concurrency_graph": "./tests/graphs/max_concurrency_graph.py:graph", "unserializable_subgraph": "./tests/graphs/unserializable_subgraph.py:graph", "agent_interrupt_text": "./tests/graphs/agent_interrupt_text.py:graph", "agent_echo_stream": "./tests/graphs/agent_echo_stream.py:graph", "agent_tool_stream": "./tests/graphs/agent_tool_stream.py:graph", "runtime_graph": "./tests/graphs/runtime_graph.py:graph", "tool_call_chunk_stream": "./tests/graphs/tool_call_chunk_stream.py:graph", "ui_tool_call_stream": "./tests/graphs/ui_tool_call_stream.py:graph", "agent_metrics_stream": "./tests/graphs/agent_metrics_stream.py:graph", "agent_multimodal_stream": "./tests/graphs/agent_multimodal_stream.py:graph", "agent_bedtime_story": "./tests/graphs/agent_bedtime_story.py:graph", "delta_channel": "./tests/graphs/delta_channel.py:graph", "delta_channel_freq": "./tests/graphs/delta_channel_freq.py:graph", "delta_channel_files": "./tests/graphs/delta_channel_files.py:graph", "delta_channel_files_freq": "./tests/graphs/delta_channel_files_freq.py:graph", "delta_channel_legacy": "./tests/graphs/delta_channel_migration.py:graph_legacy", "delta_channel_delta": "./tests/graphs/delta_channel_migration.py:graph_delta", "delta_channel_messages_freq": "./tests/graphs/delta_channel_messages.py:graph_freq", "delta_channel_messages": "./tests/graphs/delta_channel_messages.py:graph", "delta_channel_messages_legacy": "./tests/graphs/delta_channel_messages.py:graph_legacy", "delta_channel_messages_remove": "./tests/graphs/delta_channel_messages.py:graph_remove", "delta_channel_messages_update": "./tests/graphs/delta_channel_messages.py:graph_update", "delta_channel_messages_delta": "./tests/graphs/delta_channel_messages.py:graph_delta"}'
+LANGSERVE_GRAPHS_ALL = '{"agent": {"path": "./tests/graphs/agent.py:graph", "description": "agent"}, "assistant_id_runtime": "./tests/graphs/assistant_id_runtime.py:graph", "custom_lifespan": "./tests/graphs/my_router.py:graph", "single_node": "./tests/graphs/single_node.py:graph", "benchmark": "./tests/graphs/benchmark.py:graph", "config_graph": "./tests/graphs/config_graph.py:graph", "other": "./tests/graphs/other.py:make_graph", "weather": "./tests/graphs/weather.py:mk_weather_graph", "searchy": "./tests/graphs/searchy.py:graph", "agent_simple": "./tests/graphs/agent_simple.py:graph", "simple_runtime": "./tests/graphs/simple_runtime.py:graph", "agent_interrupt": "./tests/graphs/agent_interrupt.py:graph", "agent_parallel_interrupt": "./tests/graphs/agent_parallel_interrupt.py:graph", "message_type_test": "./tests/graphs/message_type_test.py:graph", "remote_subgraph_parent": "./tests/graphs/remote_subgraph_parent.py:graph", "simple_remote": "./tests/graphs/simple_remote.py:graph", "nested_subgraphs": "./tests/graphs/nested_subgraphs.py:graph", "functional_fibonacci": "./tests/graphs/functional_fibonacci.py:fibonacci", "state_graph_fibonacci": "./tests/graphs/state_graph_fibonacci.py:fibonacci", "max_concurrency_graph": "./tests/graphs/max_concurrency_graph.py:graph", "unserializable_subgraph": "./tests/graphs/unserializable_subgraph.py:graph", "agent_interrupt_text": "./tests/graphs/agent_interrupt_text.py:graph", "agent_echo_stream": "./tests/graphs/agent_echo_stream.py:graph", "agent_tool_stream": "./tests/graphs/agent_tool_stream.py:graph", "runtime_graph": "./tests/graphs/runtime_graph.py:graph", "tool_call_chunk_stream": "./tests/graphs/tool_call_chunk_stream.py:graph", "ui_tool_call_stream": "./tests/graphs/ui_tool_call_stream.py:graph", "agent_metrics_stream": "./tests/graphs/agent_metrics_stream.py:graph", "agent_multimodal_stream": "./tests/graphs/agent_multimodal_stream.py:graph", "agent_bedtime_story": "./tests/graphs/agent_bedtime_story.py:graph", "delta_channel": "./tests/graphs/delta_channel.py:graph", "delta_channel_freq": "./tests/graphs/delta_channel_freq.py:graph", "delta_channel_files": "./tests/graphs/delta_channel_files.py:graph", "delta_channel_files_freq": "./tests/graphs/delta_channel_files_freq.py:graph", "delta_channel_legacy": "./tests/graphs/delta_channel_migration.py:graph_legacy", "delta_channel_delta": "./tests/graphs/delta_channel_migration.py:graph_delta", "delta_channel_delta_filter": "./tests/graphs/delta_channel_migration.py:graph_delta_filter", "delta_channel_messages_freq": "./tests/graphs/delta_channel_messages.py:graph_freq", "delta_channel_messages": "./tests/graphs/delta_channel_messages.py:graph", "delta_channel_messages_legacy": "./tests/graphs/delta_channel_messages.py:graph_legacy", "delta_channel_messages_remove": "./tests/graphs/delta_channel_messages.py:graph_remove", "delta_channel_messages_update": "./tests/graphs/delta_channel_messages.py:graph_update", "delta_channel_messages_delta": "./tests/graphs/delta_channel_messages.py:graph_delta"}'
 LANGSERVE_GRAPHS_AUTH = '{"agent": {"path": "./tests/graphs/agent.py:graph", "description": "agent"}, "assistant_id_runtime": "./tests/graphs/assistant_id_runtime.py:graph", "config_graph": "./tests/graphs/config_graph.py:graph", "other": "./tests/graphs/other.py:make_graph", "weather": "./tests/graphs/weather.py:mk_weather_graph", "searchy": "./tests/graphs/searchy.py:graph", "agent_simple": "./tests/graphs/agent_simple.py:graph", "simple_runtime": "./tests/graphs/simple_runtime.py:graph", "agent_parallel_interrupt": "./tests/graphs/agent_parallel_interrupt.py:graph", "functional_fibonacci": "./tests/graphs/functional_fibonacci.py:fibonacci", "state_graph_fibonacci": "./tests/graphs/state_graph_fibonacci.py:fibonacci", "runtime_graph": "./tests/graphs/runtime_graph.py:graph"}'
 
 # Go server management

{langgraph_api-0.12.0.dev9 → langgraph_api-0.12.0.dev11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langgraph-api
-Version: 0.12.0.dev9
+Version: 0.12.0.dev11
 Author-email: Will Fu-Hinthorn <will@langchain.dev>, Josh Rogers <josh@langchain.dev>, Parker Rule <parker@langchain.dev>
 License: Elastic-2.0
 License-File: LICENSE
@@ -16,7 +16,7 @@ Requires-Dist: jsonschema-rs<0.45,>=0.20.0
 Requires-Dist: langchain-core>=0.3.64
 Requires-Dist: langchain-protocol<0.1,>=0.0.18
 Requires-Dist: langgraph-checkpoint<5,>=3.0.1
-Requires-Dist: langgraph-runtime-inmem<0.32.0.dev0,>=0.31.0.dev0
+Requires-Dist: langgraph-runtime-inmem<0.33.0.dev0,>=0.32.0.dev0
 Requires-Dist: langgraph-sdk>=0.3.5
 Requires-Dist: langgraph<2,>=0.4.10
 Requires-Dist: langsmith[otel]>=0.6.3

langgraph_api-0.12.0.dev11/langgraph_api/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.12.0.dev11"

{langgraph_api-0.12.0.dev9 → langgraph_api-0.12.0.dev11}/langgraph_api/_checkpointer/_adapter.py

@@ -24,6 +24,14 @@ from langgraph_grpc_common.checkpointer import GrpcCheckpointer
 from langgraph_api import config, timing
 from langgraph_api.asyncio import as_asynccontextmanager
 from langgraph_api.grpc.client import get_shared_client
+
+# Used as the per-instance serializer for ``GrpcCheckpointer`` below so
+# checkpoint payloads honour the same ``USE_PICKLE_FALLBACK`` /
+# encryption / ``allowed_json_modules`` policy as the in-process Python
+# ``Checkpointer``. Scoped to checkpointer RPCs only (via the contextvar
+# in ``langgraph_grpc_common.serde``) so non-checkpointer gRPC ops keep
+# using the safer ``JsonPlusSerializer`` default.
+from langgraph_api.serde import Serializer as _ApiSerializer
 from langgraph_api.timing import profiled_import
 from langgraph_api.utils.config import run_in_executor
 
@@ -320,7 +328,24 @@ async def get_checkpointer(
     ):
         return cast(
             "FullCheckpointerProtocol",
-            GrpcCheckpointer(get_stub=_get_shared_checkpointer_stub),
+            GrpcCheckpointer(
+                get_stub=_get_shared_checkpointer_stub,
+                serializer=_ApiSerializer(),
+            ),
+        )
+
+    from langgraph_api.feature_flags import (  # noqa: PLC0415
+        IS_POSTGRES_BACKEND,
+        PREFER_GRPC_CHECKPOINTER,
+    )
+
+    if IS_POSTGRES_BACKEND and PREFER_GRPC_CHECKPOINTER:
+        return cast(
+            "FullCheckpointerProtocol",
+            GrpcCheckpointer(
+                get_stub=_get_shared_checkpointer_stub,
+                serializer=_ApiSerializer(),
+            ),
         )
 
     from langgraph_runtime.checkpoint import Checkpointer  # noqa: PLC0415

{langgraph_api-0.12.0.dev9 → langgraph_api-0.12.0.dev11}/langgraph_api/event_streaming/service.py

@@ -21,6 +21,7 @@ from __future__ import annotations
 import asyncio
 import contextlib
 import inspect
+import time
 from collections.abc import Awaitable, Callable
 from typing import Any, cast, get_args
 from uuid import UUID, uuid4
@@ -124,6 +125,12 @@ def _multitask_strategy_from_run_start(params: dict[str, Any]) -> str:
 EventSink = Callable[[dict[str, Any]], Awaitable[None] | None]
 
 
+# ``set_joint_status`` commits interrupts after the stream event; gRPC can lag.
+_IN_FLIGHT_THREAD_STATUS = "busy"
+_INTERRUPT_SETTLE_TIMEOUT_SECONDS = 5.0
+_INTERRUPT_SETTLE_POLL_INTERVAL_SECONDS = 0.05
+
+
 # Protocol v2 commands this server implements. Anything outside this
 # set returns ``unknown_command`` up front from ``handle_command`` so
 # pre-session dispatch does not mislabel typos (or removed methods
@@ -593,13 +600,11 @@ class ThreadRunManager:
         # this HTTP request (the stateless ``POST /commands`` transport) its
         # source task hasn't had a chance to emit ``input.requested`` yet —
         # ``_pending_interrupts`` is still empty. In that case, fall back to
-        # the thread-state check so we don't reject legitimate resumes with a
-        # fresh handle. The WebSocket path (long-lived session) hits the
-        # in-memory check and skips the DB round-trip.
+        # the thread-state check (``_collect_settled_interrupt_ids``) so we
+        # don't reject legitimate resumes with a fresh handle.
         #
         # The thread-state fallback is fetched at most once per batch and
-        # cached in ``thread_state_ids``: a batch of N entries that all miss
-        # the session would otherwise issue N identical ``State.get`` calls.
+        # cached in ``thread_state_ids``.
         thread_state_ids: set[str] | None = None
         thread_state_fetched = False
         for interrupt_id, claimed_namespace, _ in entries:
@@ -623,7 +628,7 @@ class ThreadRunManager:
             # only, so trust the client-claimed namespace and validate by
             # existence (the id is a namespace hash, so that's sufficient).
             if not thread_state_fetched:
-                thread_state_ids = await self._collect_persisted_interrupt_ids()
+                thread_state_ids = await self._collect_settled_interrupt_ids()
                 thread_state_fetched = True
             # Fail open when the lookup is unavailable (``None``): only reject
             # when a definitive id set was read and lacks the target. The
@@ -669,6 +674,7 @@ class ThreadRunManager:
                 {
                     "assistant_id": assistant_id,
                     "input": resume_input,
+                    "force_resume": True,
                     "update": params.get("update"),
                     "goto": params.get("goto"),
                     "config": params.get("config"),
@@ -732,7 +738,8 @@ class ThreadRunManager:
             has_interrupts = await self._has_pending_interrupts()
 
         is_resume = params.get("input") is not None and (
-            (current_run is not None and current_status == "interrupted")
+            params.get("force_resume")
+            or (current_run is not None and current_status == "interrupted")
             or has_interrupts
         )
 
@@ -1108,6 +1115,40 @@ class ThreadRunManager:
                     found.add(entry_id)
         return found
 
+    async def _fetch_thread_status(self) -> str | None:
+        """Return durable thread status, or ``None`` if unreadable."""
+        from langgraph_runtime.database import connect  # noqa: PLC0415
+
+        try:
+            async with connect() as conn:
+                result = await self._threads.get(conn, self._thread_id)
+                thread = await anext(result) if hasattr(result, "__anext__") else result
+        except Exception:
+            return None
+        status = thread.get("status") if _is_record(thread) else None
+        return status if isinstance(status, str) else None
+
+    async def _collect_settled_interrupt_ids(self) -> set[str] | None:
+        """Persisted interrupt ids, polling while the thread is still ``busy``."""
+        ids = await self._collect_persisted_interrupt_ids()
+        if ids is None:
+            return None
+        if ids:
+            return ids
+        deadline = time.monotonic() + _INTERRUPT_SETTLE_TIMEOUT_SECONDS
+        while True:
+            status = await self._fetch_thread_status()
+            if status != _IN_FLIGHT_THREAD_STATUS:
+                return await self._collect_persisted_interrupt_ids()
+            if time.monotonic() >= deadline:
+                return set()
+            await asyncio.sleep(_INTERRUPT_SETTLE_POLL_INTERVAL_SECONDS)
+            ids = await self._collect_persisted_interrupt_ids()
+            if ids is None:
+                return None
+            if ids:
+                return ids
+
     async def _has_pending_interrupts(self) -> bool:
         # Prefer the session's in-memory pending interrupts (populated the
         # instant ``input.requested`` surfaces) to skip a DB round-trip;
@@ -1116,7 +1157,7 @@ class ThreadRunManager:
         # the ``current_status == "interrupted"`` signal for resume-vs-start.
         if self._session is not None and self._session._pending_interrupts:
             return True
-        found = await self._collect_persisted_interrupt_ids()
+        found = await self._collect_settled_interrupt_ids()
         return bool(found)
 
     # ------------------------------------------------------------------

{langgraph_api-0.12.0.dev9 → langgraph_api-0.12.0.dev11}/langgraph_api/event_streaming/state_normalizers.py

@@ -320,6 +320,14 @@ def _normalize_state_message(value: dict[str, Any]) -> dict[str, Any]:
     if msg_type in ("ai", "human") and isinstance(value.get("example"), bool):
         message["example"] = value["example"]
 
+    # Preserve ``response_metadata`` when present. It is a first-class protocol
+    # message field, and HITL flows rely on it: an interrupt's card is carried
+    # on ``AIMessage.response_metadata`` (e.g. ``{"cards": ...}``) and the
+    # frontend pushes that message into state via ``respond(decision, update)``.
+    # We only forward a non-empty record to keep the common (empty) case minimal.
+    if _is_record(value.get("response_metadata")) and value["response_metadata"]:
+        message["response_metadata"] = value["response_metadata"]
+
     if msg_type == "tool":
         if isinstance(value.get("tool_call_id"), str):
             message["tool_call_id"] = value["tool_call_id"]

{langgraph_api-0.12.0.dev9 → langgraph_api-0.12.0.dev11}/langgraph_api/feature_flags.py

@@ -35,6 +35,16 @@ FF_V2_EVENT_STREAMING = os.getenv("FF_V2_EVENT_STREAMING", "true").lower() in (
     "yes",
 )
 
+# When true on the postgres runtime, use ``GrpcCheckpointer``.
+# Inmem edition is unaffected (``IS_POSTGRES_BACKEND`` is false there).
+# Custom checkpointer (``backend=custom`` in ``LANGGRAPH_CHECKPOINTER``) and
+# Mongo (``backend=mongo``) is also unaffected.
+PREFER_GRPC_CHECKPOINTER = os.getenv("PREFER_GRPC_CHECKPOINTER", "false").lower() in (
+    "true",
+    "1",
+    "yes",
+)
+
 # In langgraph <= 1.0.3, we automatically subscribed to updates stream events to surface interrupts. In langgraph 1.0.4 we include interrupts in values events (which we are automatically subscribed to), so we no longer need to implicitly subscribe to updates stream events
 # Strip prerelease suffixes (e.g. "0a5" -> 0) so versions like 1.2.0a5 still
 # parse correctly; fall back to (0, 0, 0) only if no leading digits at all.

{langgraph_api-0.12.0.dev9 → langgraph_api-0.12.0.dev11}/langgraph_api/grpc/servicers/checkpointer.py

@@ -242,3 +242,17 @@ class CheckpointerServicerImpl(CheckpointerServicer):
                 context.set_code(grpc.StatusCode.INTERNAL)
                 context.set_details(f"Checkpointer Prune failed: {e}")
             raise
+
+    async def GetDeltaChannelHistory(
+        self,
+        request: checkpointer_pb2.GetDeltaChannelHistoryRequest,
+        context: grpc_aio.ServicerContext,
+    ) -> checkpointer_pb2.GetDeltaChannelHistoryResponse:
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details(
+            "GetDeltaChannelHistory is not implemented by the Python "
+            "checkpointer servicer"
+        )
+        raise NotImplementedError(
+            "GetDeltaChannelHistory not implemented by the Python checkpointer servicer"
+        )

{langgraph_api-0.12.0.dev9 → langgraph_api-0.12.0.dev11}/langgraph_grpc_common/checkpointer.py

@@ -8,10 +8,14 @@ from collections.abc import (
     Callable,
     Coroutine,
     Iterator,
+    Mapping,
     Sequence,
 )
+from contextlib import AbstractContextManager, nullcontext
 from typing import TYPE_CHECKING, Any, TypeVar, cast
 
+import grpc
+import grpc.aio
 from langgraph.checkpoint.base import (
     BaseCheckpointSaver,
     ChannelVersions,
@@ -20,6 +24,7 @@ from langgraph.checkpoint.base import (
     CheckpointTuple,
 )
 
+from langgraph_grpc_common import serde as _grpc_serde
 from langgraph_grpc_common.conversion import checkpoint as ckpt_conv
 from langgraph_grpc_common.conversion.config import (
     config_from_proto,
@@ -30,6 +35,7 @@ from langgraph_grpc_common.proto import checkpointer_pb2
 
 if TYPE_CHECKING:
     from langchain_core.runnables import RunnableConfig
+    from langgraph.checkpoint.serde.base import SerializerProtocol
 
     from langgraph_grpc_common.proto.checkpointer_pb2_grpc import CheckpointerStub
 
@@ -49,17 +55,43 @@ class GrpcCheckpointer(BaseCheckpointSaver):
         get_stub: StubProvider,
         retry: RetryFn | None = None,
         retry_context_prefix: str | None = None,
+        serializer: SerializerProtocol | None = None,
     ) -> None:
+        """Construct a gRPC checkpointer client.
+
+        Args:
+            get_stub: Async factory returning the ``CheckpointerStub`` to
+                use for the next RPC. Called per-call so the caller can
+                pool / refresh connections.
+            retry: Optional retry wrapper. When provided, every RPC is
+                dispatched through ``retry(func, context)``.
+            retry_context_prefix: Label included in ``retry``'s context
+                string. Defaults to the concrete class name.
+            serializer: Optional ``SerializerProtocol`` to use for
+                payload (de)serialization on *this* checkpointer
+                instance only. Scoped via a :class:`~contextvars.ContextVar`
+                so unrelated gRPC ops sharing
+                ``langgraph_grpc_common.conversion.*`` keep using the
+                process-wide default
+        """
         super().__init__(serde=None)
         self._get_stub = get_stub
         self._retry = retry
         self._retry_context_prefix = retry_context_prefix or type(self).__name__
+        self._serializer = serializer
         self.latest_iter = None
         try:
             self._loop: asyncio.AbstractEventLoop | None = asyncio.get_running_loop()
         except RuntimeError:
             self._loop = None
 
+    def _scoped(self) -> AbstractContextManager[None]:
+        """Bind ``self._serializer`` for the duration of a conversion call.
+        """
+        if self._serializer is None:
+            return nullcontext()
+        return _grpc_serde.use_serializer(self._serializer)
+
     @property
     def loop(self) -> asyncio.AbstractEventLoop:
         if self._loop is None:
@@ -94,13 +126,15 @@ class GrpcCheckpointer(BaseCheckpointSaver):
         return None
 
     async def aget_tuple(self, config: RunnableConfig) -> CheckpointTuple | None:
-        request = checkpointer_pb2.GetTupleRequest(config=config_to_proto(config))
+        with self._scoped():
+            request = checkpointer_pb2.GetTupleRequest(config=config_to_proto(config))
 
         async def _request() -> CheckpointTuple | None:
             response = await (await self._stub()).GetTuple(request)
             if not response.HasField("checkpoint_tuple"):
                 return None
-            return ckpt_conv.checkpoint_tuple_from_proto(response.checkpoint_tuple)
+            with self._scoped():
+                return ckpt_conv.checkpoint_tuple_from_proto(response.checkpoint_tuple)
 
         return await self._call("aget_tuple", _request)
 
@@ -128,16 +162,18 @@ class GrpcCheckpointer(BaseCheckpointSaver):
         metadata: CheckpointMetadata,
         new_versions: ChannelVersions,
     ) -> RunnableConfig:
-        request = checkpointer_pb2.PutRequest(
-            config=config_to_proto(config),
-            checkpoint=ckpt_conv.checkpoint_to_proto(checkpoint),
-            metadata=ckpt_conv.checkpoint_metadata_to_proto(metadata),
-            new_versions={k: str(v) for k, v in new_versions.items()},
-        )
+        with self._scoped():
+            request = checkpointer_pb2.PutRequest(
+                config=config_to_proto(config),
+                checkpoint=ckpt_conv.checkpoint_to_proto(checkpoint),
+                metadata=ckpt_conv.checkpoint_metadata_to_proto(metadata),
+                new_versions={k: str(v) for k, v in new_versions.items()},
+            )
 
         async def _request() -> RunnableConfig:
             response = await (await self._stub()).Put(request)
-            next_config = config_from_proto(response.next_config)
+            with self._scoped():
+                next_config = config_from_proto(response.next_config)
             if next_config is None:
                 raise ValueError("Unexpected None value for next_config")
             return next_config
@@ -160,12 +196,13 @@ class GrpcCheckpointer(BaseCheckpointSaver):
         task_id: str,
         task_path: str = "",
     ) -> None:
-        request = checkpointer_pb2.PutWritesRequest(
-            config=config_to_proto(config),
-            writes=ckpt_conv.writes_to_proto(writes),
-            task_id=task_id,
-            task_path=task_path,
-        )
+        with self._scoped():
+            request = checkpointer_pb2.PutWritesRequest(
+                config=config_to_proto(config),
+                writes=ckpt_conv.writes_to_proto(writes),
+                task_id=task_id,
+                task_path=task_path,
+            )
 
         async def _request() -> None:
             await (await self._stub()).PutWrites(request)
@@ -212,11 +249,12 @@ class GrpcCheckpointer(BaseCheckpointSaver):
         before: RunnableConfig | None = None,
         limit: int | None = None,
     ) -> AsyncIterator[CheckpointTuple]:
-        request = checkpointer_pb2.ListRequest(
-            config=config_to_proto(config) if config is not None else None,
-            filter_json=convert_dict_to_json_bytes(filter) or b"",
-            before=config_to_proto(before) if before is not None else None,
-        )
+        with self._scoped():
+            request = checkpointer_pb2.ListRequest(
+                config=config_to_proto(config) if config is not None else None,
+                filter_json=convert_dict_to_json_bytes(filter) or b"",
+                before=config_to_proto(before) if before is not None else None,
+            )
         if limit is not None:
             request.limit = limit
 
@@ -225,7 +263,11 @@ class GrpcCheckpointer(BaseCheckpointSaver):
 
         response = await self._call("alist", _request)
         for proto_tuple in response.checkpoint_tuples:
-            if (tup := ckpt_conv.checkpoint_tuple_from_proto(proto_tuple)) is not None:
+            # Bind inside the loop body so the override does not leak
+            # across ``yield`` into the consumer's frame.
+            with self._scoped():
+                tup = ckpt_conv.checkpoint_tuple_from_proto(proto_tuple)
+            if tup is not None:
                 yield tup
 
     def delete_thread(self, thread_id: str) -> None:
@@ -298,3 +340,55 @@ class GrpcCheckpointer(BaseCheckpointSaver):
         next_v = current_v + 1
         next_h = random.random()
         return f"{next_v:032}.{next_h:.16f}"
+
+    def get_delta_channel_history(
+        self,
+        *,
+        config: RunnableConfig,
+        channels: Sequence[str],
+    ) -> Mapping[str, dict[str, Any]]:
+        """Synchronous wrapper for ``aget_delta_channel_history``.
+
+        langgraph >= 1.2 calls the async variant from the loop, but the
+        BaseCheckpointSaver protocol expects sync wrappers to exist.
+        """
+        return self._run_sync(
+            self.aget_delta_channel_history(config=config, channels=channels)
+        )
+
+    async def aget_delta_channel_history(
+        self,
+        *,
+        config: RunnableConfig,
+        channels: Sequence[str],
+    ) -> Mapping[str, dict[str, Any]]:
+        if not channels:
+            return {}
+        configurable = config.get("configurable", {}) if config else {}
+        request = checkpointer_pb2.GetDeltaChannelHistoryRequest(
+            thread_id=configurable.get("thread_id", "") or "",
+            checkpoint_ns=configurable.get("checkpoint_ns", "") or "",
+            # Empty checkpoint_id => server resolves the latest checkpoint.
+            checkpoint_id=configurable.get("checkpoint_id", "") or "",
+            channels=list(channels),
+        )
+
+        async def _request() -> checkpointer_pb2.GetDeltaChannelHistoryResponse:
+            return await (await self._stub()).GetDeltaChannelHistory(request)
+
+        try:
+            response = await self._call("aget_delta_channel_history", _request)
+        except grpc.aio.AioRpcError as e:
+            if e.code() == grpc.StatusCode.UNIMPLEMENTED:
+                # The backend has no native fast path for delta-channel
+                # reconstruction (e.g. the Go mongo/sqlite checkpointers).
+                # Fall back to BaseCheckpointSaver's parent-chain walk, which
+                # drives aget_tuple (-> gRPC GetTuple) per ancestor. langgraph
+                # calls this method unguarded, so we must degrade gracefully
+                # rather than raise.
+                return await super().aget_delta_channel_history(
+                    config=config, channels=channels
+                )
+            raise
+        with self._scoped():
+            return ckpt_conv.delta_channel_history_from_proto(response.entries)

{langgraph_api-0.12.0.dev9 → langgraph_api-0.12.0.dev11}/langgraph_grpc_common/conversion/checkpoint.py

@@ -1,3 +1,4 @@
+from collections.abc import Mapping
 from collections.abc import Sequence as SequenceType
 from typing import Any, Literal, cast
 
@@ -16,7 +17,7 @@ from langgraph_grpc_common.conversion.config import (
 )
 from langgraph_grpc_common.conversion.struct import dict_from_raw_map, raw_map_from_dict
 from langgraph_grpc_common.conversion.value import (
-    any_to_serialized_value,
+    base_value_to_proto,
     send_to_proto,
     value_from_proto,
     value_to_proto,
@@ -86,11 +87,7 @@ def checkpoint_to_proto(checkpoint: Checkpoint) -> engine_common_pb2.Checkpoint:
                 )
             )
         else:
-            checkpoint_proto.channel_values[k].CopyFrom(
-                engine_common_pb2.ChannelValue(
-                    serialized_value=any_to_serialized_value(v)
-                )
-            )
+            checkpoint_proto.channel_values[k].CopyFrom(base_value_to_proto(v))
 
     return checkpoint_proto
 
@@ -241,3 +238,95 @@ def prune_strategy_to_proto(
         case "delete_all":
             return checkpointer_pb2.PruneRequest.PruneStrategy.DELETE_ALL
     raise ValueError("Unknown prune strategy: " + strategy)
+
+
+# ---------------------------------------------------------------------------
+# DeltaChannelHistory conversion
+# ---------------------------------------------------------------------------
+#
+# ``DeltaChannelHistory`` is a TypedDict from langgraph >= 1.2:
+#
+#   class DeltaChannelHistory(TypedDict, total=False):
+#       seed: Any                       # optional snapshot value
+#       writes: list[PendingWrite]      # (task_id, channel, value) tuples
+#
+# These helpers serialize/deserialize that shape to/from the wire-format
+# ``DeltaChannelHistoryEntry`` proto.
+#
+# We accept and return plain ``dict[str, dict]`` rather than importing
+# the ``DeltaChannelHistory`` TypedDict — langgraph treats the TypedDict
+# structurally, so any dict with the right keys is accepted by the
+# consumer (langgraph's ``DeltaChannel.replay_writes``).
+
+
+def delta_channel_history_entry_to_proto(
+    entry: Mapping[str, Any],
+    *,
+    channel: str,
+) -> checkpointer_pb2.DeltaChannelHistoryEntry:
+    """Encode one channel's ``DeltaChannelHistory`` dict as proto.
+
+    Args:
+        entry: Mapping with optional ``seed`` and optional ``writes``.
+            ``writes`` is a sequence of ``(task_id, channel, value)`` tuples
+            (langgraph's ``PendingWrite``).
+        channel: The channel name this entry corresponds to. We pass it to
+            ``value_to_proto`` so the TASKS channel special-cases the
+            seed/write conversion if it ever appears here.
+    """
+    pb_entry = checkpointer_pb2.DeltaChannelHistoryEntry()
+    if "seed" in entry:
+        pb_entry.seed.CopyFrom(value_to_proto(channel, entry["seed"]))
+    for write in entry.get("writes", ()) or ():
+        task_id, write_channel, write_value = write
+        pb_entry.writes.append(
+            engine_common_pb2.PendingWrite(
+                task_id=str(task_id),
+                channel=str(write_channel),
+                value=value_to_proto(write_channel, write_value),
+            )
+        )
+    return pb_entry
+
+
+def delta_channel_history_to_proto(
+    history: Mapping[str, Mapping[str, Any]],
+) -> dict[str, checkpointer_pb2.DeltaChannelHistoryEntry]:
+    """Encode the full per-channel mapping for the response proto."""
+    return {
+        ch: delta_channel_history_entry_to_proto(entry, channel=ch)
+        for ch, entry in history.items()
+    }
+
+
+def delta_channel_history_entry_from_proto(
+    entry: checkpointer_pb2.DeltaChannelHistoryEntry,
+) -> dict[str, Any]:
+    """Decode one channel's proto entry to a ``DeltaChannelHistory`` dict.
+
+    The ``seed`` key is omitted from the result when the proto has no
+    seed set — matches the Python source's "absence means MISSING"
+    contract (see ``_assemble_delta_history`` in
+    ``storage_postgres/langgraph_runtime_postgres/checkpoint.py``).
+    """
+    out: dict[str, Any] = {
+        "writes": [
+            (write.task_id, write.channel, value_from_proto(write.value))
+            for write in entry.writes
+        ],
+    }
+    if entry.HasField("seed"):
+        out["seed"] = value_from_proto(entry.seed)
+    return out
+
+
+def delta_channel_history_from_proto(
+    entries: Mapping[str, checkpointer_pb2.DeltaChannelHistoryEntry],
+) -> dict[str, dict[str, Any]]:
+    """Decode the full per-channel response proto map."""
+    return {
+        ch: delta_channel_history_entry_from_proto(entry)
+        for ch, entry in entries.items()
+    }
+
+

langgraph_api-0.12.0.dev11/langgraph_grpc_common/conversion/struct.py

@@ -0,0 +1,60 @@
+import re
+from collections.abc import Mapping
+from typing import Any
+
+import orjson
+from google.protobuf import struct_pb2
+
+
+def struct_from_dict(d: Mapping[str, Any]) -> struct_pb2.Struct:
+    s = struct_pb2.Struct()
+    s.update(d)
+    return s
+
+
+def _default_serializer(obj: Any) -> Any:
+    if hasattr(obj, "dict") and callable(obj.dict):
+        return obj.dict()
+    if hasattr(obj, "__dict__"):
+        return obj.__dict__
+    raise TypeError(f"Type is not JSON serializable: {type(obj).__name__}")
+
+
+_SURROGATE_RE = re.compile(r"[\ud800-\udfff]")
+
+
+def _replace_surrogates(o: Any) -> Any:
+    """Recursively replace lone-surrogate codepoints (orjson rejects them).
+
+    Mirrors ``_sanitise`` in ``langgraph_grpc_common.serde`` so metadata
+    encode falls back gracefully instead of raising. Without this,
+    fixtures that intentionally embed surrogates (e.g.
+    ``test_thread_copy``'s ``"surrogate"`` field on
+    ``langgraph==0.4.10`` which mirrors input into metadata) crash the
+    whole put.
+    """
+    if isinstance(o, str):
+        return _SURROGATE_RE.sub("?", o) if _SURROGATE_RE.search(o) else o
+    if isinstance(o, Mapping):
+        return {_replace_surrogates(k): _replace_surrogates(v) for k, v in o.items()}
+    if isinstance(o, (list, tuple, set)):
+        return type(o)(_replace_surrogates(x) for x in o)
+    return o
+
+
+def raw_map_from_dict(d: Mapping[str, Any]) -> Mapping[str, bytes]:
+    out: dict[str, bytes] = {}
+    for k, v in d.items():
+        try:
+            out[k] = orjson.dumps(v, default=_default_serializer)
+        except (TypeError, ValueError):
+            # orjson rejects e.g. lone surrogates and a few other oddities
+            # that the in-process Python ``Checkpointer.aput`` happily
+            # stores via its own serde. Sanitize and retry rather than
+            # failing the entire put.
+            out[k] = orjson.dumps(_replace_surrogates(v), default=_default_serializer)
+    return out
+
+
+def dict_from_raw_map(m: Mapping[str, bytes]) -> dict[str, Any]:
+    return {k: orjson.loads(v) for k, v in m.items()}