langgraph-api 0.12.0.dev8__py3-none-any.whl → 0.12.0.dev10__py3-none-any.whl

langgraph_api/__init__.py

@@ -1 +1 @@
-__version__ = "0.12.0.dev8"
+__version__ = "0.12.0.dev10"

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/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/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/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/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.dev8.dist-info → langgraph_api-0.12.0.dev10.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langgraph-api
-Version: 0.12.0.dev8
+Version: 0.12.0.dev10
 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.dev8.dist-info → langgraph_api-0.12.0.dev10.dist-info}/RECORD

@@ -1,4 +1,4 @@
-langgraph_api/__init__.py,sha256=qaaIIb9IS9kMth5gp-OOazPqIX9KmiNNhR5sP21XRX0,28
+langgraph_api/__init__.py,sha256=ET9JJ1BldzP5SKSEuzw5ZRYUjqRmfoJF5DqqnNc_Taw,29
 langgraph_api/_factory_utils.py,sha256=5JsiJbg_YocVSryN2jwoZTg03-eyymlWMK6sKCmXwz0,5756
 langgraph_api/asgi_transport.py,sha256=XApY3lIWBZTMbbsl8dDJzl0cLGirmAGE0SifqZUnXvs,11896
 langgraph_api/asyncio.py,sha256=c-YE-14N7_AP1GzifsbP14XnhLsmxT2P916KXruerpI,10573
@@ -7,7 +7,7 @@ langgraph_api/cli.py,sha256=ATtS9s9Cx7QNiGPJceKnMCko29A25ZA-xz39fdxmgfg,22389
 langgraph_api/command.py,sha256=d-k8h6H4ix1n7fSZ-Zb01NbSkEyqrD6cMKfDFXEIYEw,821
 langgraph_api/cron_scheduler.py,sha256=OwFzCwD86pfMNpfm9Z8bBS_WY9bBfDxGnq8_7wXurdA,6016
 langgraph_api/errors.py,sha256=zlMW99wAzNkz2xfik-HMkl_wMqmRFvs1j8V-_DZbAUc,2553
-langgraph_api/feature_flags.py,sha256=IcSPG_EfPyE-PP4rxsNRSIRRCTt83KOHKK7IqHjh178,2242
+langgraph_api/feature_flags.py,sha256=P7yQ9jXMHO3dPWv51iWGAVrPg3LbR9m4aCT_7t1UtZw,2624
 langgraph_api/graph.py,sha256=fKlnNv4Wn1ThYiRsYgT7A4EVvJssymWtI12gnNJQIVU,37734
 langgraph_api/http.py,sha256=7hPxKbj-xoAKcm7iucBpT5nM_hXOgGVCPbBsCD693Cw,6977
 langgraph_api/http_metrics.py,sha256=etxbZNmYxdb58DVLNkHP7S-N6njXPTiQh2OWKMaIZi8,5336
@@ -36,7 +36,7 @@ langgraph_api/validation.py,sha256=XyeKyt7jAICmIlT_b0J0mv2YbwIbNoe4m6zEmfk9gOA,1
 langgraph_api/webhook.py,sha256=qXEtkE6orek2POeOQmPRsEarJgXIYp-LBrZB-OwITxc,9572
 langgraph_api/worker.py,sha256=HGirbQ1i1hxaayORoihsQ6JMVAq3VsrC8CUxAHwY9t0,21151
 langgraph_api/_checkpointer/__init__.py,sha256=ofJTJLGy7Hsuzhj-2dpfDvrDloM0BzlhTzvZOdR9K8U,2223
-langgraph_api/_checkpointer/_adapter.py,sha256=1Mdb3B_bg6EQ_3uJfk6ImiobIiAPdaMQVaruDBzVkE8,20833
+langgraph_api/_checkpointer/_adapter.py,sha256=1jJi0vXoNKeCwNP26W8bmYrwe-fOWFqepnovYFt14W0,21782
 langgraph_api/_checkpointer/protocol.py,sha256=udgYKMNtKWG_eLDwYkHXV3b2bZLZg8Rsfm3fjkhU-rU,3635
 langgraph_api/api/__init__.py,sha256=Zu1ew3dxYZu7cLRAjn-6HcYmtuQBdihlVFMKMJ77Y3c,9269
 langgraph_api/api/a2a.py,sha256=VPllgqfoLUQD6Eqob3RjcegjtKgLhphNGTrTqbNLoIY,95135
@@ -78,9 +78,9 @@ langgraph_api/event_streaming/capabilities.py,sha256=qjVbhCjl1VEQPGeiDxeJAhYGI_7
 langgraph_api/event_streaming/constants.py,sha256=eGsm-NvOlqV3gNxDO5vlr00FdngmgEQf59zuHSi_74E,1378
 langgraph_api/event_streaming/event_normalizers.py,sha256=5bVSqGPW-Uh7WX91qgTfwpK433pCSv_wchpbzW8TLi4,2794
 langgraph_api/event_streaming/namespace.py,sha256=aJDFt45Or2_bQdRpKJgdFhBgTDj6PYl7Coz5GzfbM84,1509
-langgraph_api/event_streaming/service.py,sha256=Z41ioDEDxXqDzXCGqo0L5-Qm_1Y8x_yp8yxu4gQ8nz8,48468
+langgraph_api/event_streaming/service.py,sha256=axQ2sDawAtsE96ZeJcBB8q8DbzS2VN-OqsdCM1rDF58,50063
 langgraph_api/event_streaming/session.py,sha256=8kx5nxJvJlfIu5fFzQCxEl-8UBJEtxftBLhCYgXMNwo,75947
-langgraph_api/event_streaming/state_normalizers.py,sha256=fEjb9AWihhZeqkGOlTBYmph06XAP3AvyAkNmNdquqAU,13113
+langgraph_api/event_streaming/state_normalizers.py,sha256=vgT4O4tJPr9VDBMn1EP994ieDGDYP43sROnOyLjkEAE,13659
 langgraph_api/event_streaming/types.py,sha256=RyZqfqgH-jmmmmAFQj5f6nH9M1rGK93zVG7nlmvqZgc,3647
 langgraph_api/grpc/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 langgraph_api/grpc/client.py,sha256=ypSgZWclK7OCKLGW8gD_LZwwgsgQEahJqc8mBWF8Rug,15578
@@ -93,7 +93,7 @@ langgraph_api/grpc/ops/crons.py,sha256=oGPW9qW-J4H9baX7Jsee1opsFnXfThHLHh_N47mDf
 langgraph_api/grpc/ops/runs.py,sha256=dD2Rne9EBU7z4lGF3OicpIMZNU4MBNbbli1Hw5gz2tw,41479
 langgraph_api/grpc/ops/threads.py,sha256=SJraV838nZ0m6wRrCia7sLYh8KK1WfY7x5xmcspZLek,48140
 langgraph_api/grpc/servicers/__init__.py,sha256=l8yqTA_gMbIj0xHw5-RZYo0JbjL-EpFD8RxPMgW_-bA,422
-langgraph_api/grpc/servicers/checkpointer.py,sha256=1gGTQcJrMSXc0sqP69YW9gexvBAeLNPvBQnsvxviI3M,9927
+langgraph_api/grpc/servicers/checkpointer.py,sha256=aeB2hzsDxbb9i-ildx-kylpDxaYtpAUSG6rphOzbDOs,10482
 langgraph_api/grpc/servicers/encryption.py,sha256=_qpcrjURpnm7PvdWOronNt3FtmqR1mjwxUb5bWMj32I,12962
 langgraph_api/js/.gitignore,sha256=l5yI6G_V6F1600I1IjiUKn87f4uYIrBAYU1MOyBBhg4,59
 langgraph_api/js/.prettierrc,sha256=0es3ovvyNIqIw81rPQsdt1zCQcOdBqyR_DMbFE4Ifms,19
@@ -163,20 +163,20 @@ hatch_build.py,sha256=Nn9N-EFfVqmH5q3iCUrhqX6zc7qT1jLI3gWSBN2xgYQ,1738
 logging.json,sha256=sBy8HDDPuucpLbLUD6e8t5fsiQjJoklZsbVHi2qQ7aQ,367
 openapi.json,sha256=0N-D4j0_3ruH6nMF4k5lnqmpV-aoB5Se-WWheCQuQQs,219552
 langgraph_grpc_common/__init__.py,sha256=sO7jFHekQxt6zZPhTPZAWLYLB_S8w7-VuJ7NyWFlFNo,97
-langgraph_grpc_common/checkpointer.py,sha256=WLDShg7rqC3dkxFudLNVElH_1yxe9LlqEdZYh0k1Azs,9876
-langgraph_grpc_common/serde.py,sha256=ejr7EKWK5ZZBVolilgrBDViixnPEvg9brPKiVVEst9Y,4996
+langgraph_grpc_common/checkpointer.py,sha256=u3ERFgqnUCpCYpOSxKR_6Jvo_tR4yDvq7qU-EL61bSg,14022
+langgraph_grpc_common/serde.py,sha256=pxIhgxtrXtwWVhAlLE2LAeSAuKk2ZHtnvAP3DRDT2Qw,6184
 langgraph_grpc_common/conversion/__init__.py,sha256=pLsOrRtmF9YkgmCPhcfym6lYOB7PCJTRItyo1YK_AT8,208
 langgraph_grpc_common/conversion/_compat.py,sha256=MIEo69I7tfaPskunPGwBCKheksLwxpw-z-4O3hvO9og,4010
-langgraph_grpc_common/conversion/checkpoint.py,sha256=ZxNhUOSdf9O-bHer5FXNvha9hiYF1UT7HRQ8qVV_pCY,8747
+langgraph_grpc_common/conversion/checkpoint.py,sha256=Ty81cijafeal7blzzXbYFjWpu9iXVb_spFLBZ2FvmgI,12045
 langgraph_grpc_common/conversion/config.py,sha256=HjlHRX-_GpKa1m0RWVL1PEZQCvA3w_8wKVYrtaT06do,13015
 langgraph_grpc_common/conversion/durability.py,sha256=FWhqjzVN4JrrsAL9AwsJkvIorQGNRl14w97Va-WZRk0,991
-langgraph_grpc_common/conversion/struct.py,sha256=TgpDYnOUt3TjBcOi0h56Dn92OnCFjQAVi-XpLVvumgw,770
-langgraph_grpc_common/conversion/value.py,sha256=ILTEgKcc590EFP2fXvGGSPm-3MHMV4L4l4sqDIiKJuk,7564
+langgraph_grpc_common/conversion/struct.py,sha256=yk4jpPdywzn8UosAohun21lU5D_IIglOY9rkBhiG-gA,2072
+langgraph_grpc_common/conversion/value.py,sha256=eZ9fDqKje9tKsO8A_6f0BPSI7lt94Vzuu3NNEEYLFBM,8343
 langgraph_grpc_common/proto/__init__.py,sha256=cFnJ18b62FnqKcZHz9wjKES0QetC_5twG47G1W0A2mM,1283
-langgraph_grpc_common/proto/checkpointer_pb2.py,sha256=YaKpQpn8kBpZt5mcyCfCY1XsTUCvKtTiwcMfpF4Eu7Q,6346
-langgraph_grpc_common/proto/checkpointer_pb2.pyi,sha256=R91LHQBWBOUOlQUFBKI81OEdK6FSzmQoXOKKcT2yuRk,15664
-langgraph_grpc_common/proto/checkpointer_pb2_grpc.py,sha256=PAYyUXuskG2vdfRPe5OHuo1_pLzrZZIbR6UWi13DcMo,18090
-langgraph_grpc_common/proto/checkpointer_pb2_grpc.pyi,sha256=vbZf41Y3pcnNJeopd4cRJEVdZVa0hgDLpfms5ExcVx4,8781
+langgraph_grpc_common/proto/checkpointer_pb2.py,sha256=c-gaVwNHm7sUzThJDzumME2M_nP4B1RjEki4ZG7-kjM,7915
+langgraph_grpc_common/proto/checkpointer_pb2.pyi,sha256=rGUxQyNFifmu8OPy0S418sCWSBQY_CVckobPXtFfZfs,20763
+langgraph_grpc_common/proto/checkpointer_pb2_grpc.py,sha256=MLhZ7M4g9gjfXZqWenk93oO2uIZSybbFoaeU8bauFPA,20176
+langgraph_grpc_common/proto/checkpointer_pb2_grpc.pyi,sha256=8fPL90WjHnMaREG7l9qYt5fQePeT8YFWQ0qVy56QtYw,10210
 langgraph_grpc_common/proto/core_api_pb2.py,sha256=xbzqAKhwvgc_-J5BlqS7krhOlgKsRgzrb7uhGax1jbo,50813
 langgraph_grpc_common/proto/core_api_pb2.pyi,sha256=lN5P83sM9_gvlPGOkDQIUEq9QDiiffmY2MIQOZtdV7s,206457
 langgraph_grpc_common/proto/core_api_pb2_grpc.py,sha256=zIfWY664xF4r9c48Ys1OcYN4dEmtIWAwYiCzP7gsyLI,81342
@@ -229,8 +229,8 @@ langgraph_grpc_common/proto/errors_pb2.py,sha256=JI6x-vBK1AE7DHZ5DQwN1mZWF6C4xTR
 langgraph_grpc_common/proto/errors_pb2.pyi,sha256=rd3-BYUH8V-aO66taL7OOblaLgdrDtf1Vcd38GUoVVM,2181
 langgraph_grpc_common/proto/errors_pb2_grpc.py,sha256=2-LwQ0OPGo-NtC0269q7Fw6GPBxnTLYWq3xP5Eq0_YA,886
 langgraph_grpc_common/proto/errors_pb2_grpc.pyi,sha256=uC9Wnq6uyg488QiONpJ0ba1s_iouQCOYsjd_FDd1XUM,495
-langgraph_api-0.12.0.dev8.dist-info/METADATA,sha256=r1iqOd9-5Wr4rn6DFRb5wa5fEe_iDg2u6AU4wddKxv4,4631
-langgraph_api-0.12.0.dev8.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-langgraph_api-0.12.0.dev8.dist-info/entry_points.txt,sha256=hGedv8n7cgi41PypMfinwS_HfCwA7xJIfS0jAp8htV8,78
-langgraph_api-0.12.0.dev8.dist-info/licenses/LICENSE,sha256=ZPwVR73Biwm3sK6vR54djCrhaRiM4cAD2zvOQZV8Xis,3859
-langgraph_api-0.12.0.dev8.dist-info/RECORD,,
+langgraph_api-0.12.0.dev10.dist-info/METADATA,sha256=WhXiyRWSggW7mhNlI8pkHYcnABwggJkuXPXR-jLpak0,4632
+langgraph_api-0.12.0.dev10.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+langgraph_api-0.12.0.dev10.dist-info/entry_points.txt,sha256=hGedv8n7cgi41PypMfinwS_HfCwA7xJIfS0jAp8htV8,78
+langgraph_api-0.12.0.dev10.dist-info/licenses/LICENSE,sha256=ZPwVR73Biwm3sK6vR54djCrhaRiM4cAD2zvOQZV8Xis,3859
+langgraph_api-0.12.0.dev10.dist-info/RECORD,,

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_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_grpc_common/conversion/struct.py

@@ -1,3 +1,4 @@
+import re
 from collections.abc import Mapping
 from typing import Any
 
@@ -19,8 +20,40 @@ def _default_serializer(obj: Any) -> Any:
     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]:
-    return {k: orjson.dumps(v, default=_default_serializer) for k, v in d.items()}
+    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]:

langgraph_grpc_common/conversion/value.py

@@ -18,7 +18,17 @@ def serialized_value_from_proto(value: engine_common_pb2.SerializedValue) -> Any
 
 
 def any_to_serialized_value(value: Any) -> engine_common_pb2.SerializedValue:
-    if isinstance(value, tuple):
+    # Wrap *bare* tuples (e.g. ``(task_id, channel, payload)``-style writes)
+    # in a list so the downstream msgpack consumer sees the expected
+    # list-of-tuples shape. NamedTuples (detected by ``_fields``) MUST NOT be
+    # wrapped: they have registered serde handlers — notably
+    # ``_DeltaSnapshot`` from langgraph >= 1.2, which serializes via the
+    # ``EXT_DELTA_SNAPSHOT`` msgpack ext code — and wrapping them in a list
+    # buries the NamedTuple inside a generic sequence, defeating the handler
+    # and causing the snapshot value to round-trip as ``[inner_list]`` instead
+    # of the original ``_DeltaSnapshot(inner_list)``. That manifested as
+    # ``DeltaChannel`` reconstruction reading back ``[[seed], delta1, ...]``.
+    if isinstance(value, tuple) and not hasattr(value, "_fields"):
         value = [value]
     encoding, ser_val = serde.get_serializer().dumps_typed(value)
     return engine_common_pb2.SerializedValue(encoding=encoding, value=bytes(ser_val))

langgraph_grpc_common/proto/checkpointer_pb2.py

@@ -26,7 +26,7 @@ from google.protobuf import empty_pb2 as google_dot_protobuf_dot_empty__pb2
 from . import engine_common_pb2 as engine__common__pb2
 
 
-DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x12\x63heckpointer.proto\x12\x0c\x63heckpointer\x1a\x1bgoogle/protobuf/empty.proto\x1a\x13\x65ngine-common.proto\"\x97\x02\n\nPutRequest\x12\x32\n\x06\x63onfig\x18\x01 \x01(\x0b\x32\".engineCommon.EngineRunnableConfig\x12,\n\ncheckpoint\x18\x02 \x01(\x0b\x32\x18.engineCommon.Checkpoint\x12\x32\n\x08metadata\x18\x03 \x01(\x0b\x32 .engineCommon.CheckpointMetadata\x12?\n\x0cnew_versions\x18\x04 \x03(\x0b\x32).checkpointer.PutRequest.NewVersionsEntry\x1a\x32\n\x10NewVersionsEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t:\x02\x38\x01\"\x8f\x01\n\x10PutWritesRequest\x12\x32\n\x06\x63onfig\x18\x01 \x01(\x0b\x32\".engineCommon.EngineRunnableConfig\x12#\n\x06writes\x18\x02 \x03(\x0b\x32\x13.engineCommon.Write\x12\x0f\n\x07task_id\x18\x03 \x01(\t\x12\x11\n\ttask_path\x18\x04 \x01(\t\"\x86\x01\n\x0c\x43\x61pabilities\x12\x1e\n\x16supports_delete_thread\x18\x01 \x01(\x08\x12\x16\n\x0esupports_prune\x18\x02 \x01(\x08\x12 \n\x18supports_delete_for_runs\x18\x03 \x01(\x08\x12\x1c\n\x14supports_copy_thread\x18\x04 \x01(\x08\"\xa8\x01\n\x0bListRequest\x12\x32\n\x06\x63onfig\x18\x01 \x01(\x0b\x32\".engineCommon.EngineRunnableConfig\x12\x13\n\x0b\x66ilter_json\x18\x02 \x01(\x0c\x12\x32\n\x06\x62\x65\x66ore\x18\x03 \x01(\x0b\x32\".engineCommon.EngineRunnableConfig\x12\x12\n\x05limit\x18\x04 \x01(\x03H\x00\x88\x01\x01\x42\x08\n\x06_limit\"(\n\x13\x44\x65leteThreadRequest\x12\x11\n\tthread_id\x18\x01 \x01(\t\"\'\n\x14\x44\x65leteForRunsRequest\x12\x0f\n\x07run_ids\x18\x01 \x03(\t\"A\n\x11\x43opyThreadRequest\x12\x16\n\x0e\x66rom_thread_id\x18\x01 \x01(\t\x12\x14\n\x0cto_thread_id\x18\x02 \x01(\t\"\xa1\x01\n\x0cPruneRequest\x12\x12\n\nthread_ids\x18\x01 \x03(\t\x12:\n\x08strategy\x18\x02 \x01(\x0e\x32(.checkpointer.PruneRequest.PruneStrategy\"A\n\rPruneStrategy\x12\x0f\n\x0bUNSPECIFIED\x10\x00\x12\x0f\n\x0bKEEP_LATEST\x10\x01\x12\x0e\n\nDELETE_ALL\x10\x02\"E\n\x0fGetTupleRequest\x12\x32\n\x06\x63onfig\x18\x01 \x01(\x0b\x32\".engineCommon.EngineRunnableConfig\"F\n\x0bPutResponse\x12\x37\n\x0bnext_config\x18\x01 \x01(\x0b\x32\".engineCommon.EngineRunnableConfig\"H\n\x0cListResponse\x12\x38\n\x11\x63heckpoint_tuples\x18\x01 \x03(\x0b\x32\x1d.engineCommon.CheckpointTuple\"e\n\x10GetTupleResponse\x12<\n\x10\x63heckpoint_tuple\x18\x01 \x01(\x0b\x32\x1d.engineCommon.CheckpointTupleH\x00\x88\x01\x01\x42\x13\n\x11_checkpoint_tuple2\xfc\x04\n\x0c\x43heckpointer\x12:\n\x03Put\x12\x18.checkpointer.PutRequest\x1a\x19.checkpointer.PutResponse\x12\x43\n\tPutWrites\x12\x1e.checkpointer.PutWritesRequest\x1a\x16.google.protobuf.Empty\x12\x45\n\x0fGetCapabilities\x12\x16.google.protobuf.Empty\x1a\x1a.checkpointer.Capabilities\x12=\n\x04List\x12\x19.checkpointer.ListRequest\x1a\x1a.checkpointer.ListResponse\x12I\n\x08GetTuple\x12\x1d.checkpointer.GetTupleRequest\x1a\x1e.checkpointer.GetTupleResponse\x12I\n\x0c\x44\x65leteThread\x12!.checkpointer.DeleteThreadRequest\x1a\x16.google.protobuf.Empty\x12K\n\rDeleteForRuns\x12\".checkpointer.DeleteForRunsRequest\x1a\x16.google.protobuf.Empty\x12\x45\n\nCopyThread\x12\x1f.checkpointer.CopyThreadRequest\x1a\x16.google.protobuf.Empty\x12;\n\x05Prune\x12\x1a.checkpointer.PruneRequest\x1a\x16.google.protobuf.EmptyB?Z=github.com/langchain-ai/langgraph-api/core/internal/engine/pbb\x06proto3')
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x12\x63heckpointer.proto\x12\x0c\x63heckpointer\x1a\x1bgoogle/protobuf/empty.proto\x1a\x13\x65ngine-common.proto\"\x97\x02\n\nPutRequest\x12\x32\n\x06\x63onfig\x18\x01 \x01(\x0b\x32\".engineCommon.EngineRunnableConfig\x12,\n\ncheckpoint\x18\x02 \x01(\x0b\x32\x18.engineCommon.Checkpoint\x12\x32\n\x08metadata\x18\x03 \x01(\x0b\x32 .engineCommon.CheckpointMetadata\x12?\n\x0cnew_versions\x18\x04 \x03(\x0b\x32).checkpointer.PutRequest.NewVersionsEntry\x1a\x32\n\x10NewVersionsEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t:\x02\x38\x01\"\x8f\x01\n\x10PutWritesRequest\x12\x32\n\x06\x63onfig\x18\x01 \x01(\x0b\x32\".engineCommon.EngineRunnableConfig\x12#\n\x06writes\x18\x02 \x03(\x0b\x32\x13.engineCommon.Write\x12\x0f\n\x07task_id\x18\x03 \x01(\t\x12\x11\n\ttask_path\x18\x04 \x01(\t\"\x86\x01\n\x0c\x43\x61pabilities\x12\x1e\n\x16supports_delete_thread\x18\x01 \x01(\x08\x12\x16\n\x0esupports_prune\x18\x02 \x01(\x08\x12 \n\x18supports_delete_for_runs\x18\x03 \x01(\x08\x12\x1c\n\x14supports_copy_thread\x18\x04 \x01(\x08\"\xa8\x01\n\x0bListRequest\x12\x32\n\x06\x63onfig\x18\x01 \x01(\x0b\x32\".engineCommon.EngineRunnableConfig\x12\x13\n\x0b\x66ilter_json\x18\x02 \x01(\x0c\x12\x32\n\x06\x62\x65\x66ore\x18\x03 \x01(\x0b\x32\".engineCommon.EngineRunnableConfig\x12\x12\n\x05limit\x18\x04 \x01(\x03H\x00\x88\x01\x01\x42\x08\n\x06_limit\"(\n\x13\x44\x65leteThreadRequest\x12\x11\n\tthread_id\x18\x01 \x01(\t\"\'\n\x14\x44\x65leteForRunsRequest\x12\x0f\n\x07run_ids\x18\x01 \x03(\t\"A\n\x11\x43opyThreadRequest\x12\x16\n\x0e\x66rom_thread_id\x18\x01 \x01(\t\x12\x14\n\x0cto_thread_id\x18\x02 \x01(\t\"\xa1\x01\n\x0cPruneRequest\x12\x12\n\nthread_ids\x18\x01 \x03(\t\x12:\n\x08strategy\x18\x02 \x01(\x0e\x32(.checkpointer.PruneRequest.PruneStrategy\"A\n\rPruneStrategy\x12\x0f\n\x0bUNSPECIFIED\x10\x00\x12\x0f\n\x0bKEEP_LATEST\x10\x01\x12\x0e\n\nDELETE_ALL\x10\x02\"E\n\x0fGetTupleRequest\x12\x32\n\x06\x63onfig\x18\x01 \x01(\x0b\x32\".engineCommon.EngineRunnableConfig\"F\n\x0bPutResponse\x12\x37\n\x0bnext_config\x18\x01 \x01(\x0b\x32\".engineCommon.EngineRunnableConfig\"H\n\x0cListResponse\x12\x38\n\x11\x63heckpoint_tuples\x18\x01 \x03(\x0b\x32\x1d.engineCommon.CheckpointTuple\"e\n\x10GetTupleResponse\x12<\n\x10\x63heckpoint_tuple\x18\x01 \x01(\x0b\x32\x1d.engineCommon.CheckpointTupleH\x00\x88\x01\x01\x42\x13\n\x11_checkpoint_tuple\"~\n\x18\x44\x65ltaChannelHistoryEntry\x12-\n\x04seed\x18\x01 \x01(\x0b\x32\x1a.engineCommon.ChannelValueH\x00\x88\x01\x01\x12*\n\x06writes\x18\x02 \x03(\x0b\x32\x1a.engineCommon.PendingWriteB\x07\n\x05_seed\"r\n\x1dGetDeltaChannelHistoryRequest\x12\x11\n\tthread_id\x18\x01 \x01(\t\x12\x15\n\rcheckpoint_ns\x18\x02 \x01(\t\x12\x15\n\rcheckpoint_id\x18\x03 \x01(\t\x12\x10\n\x08\x63hannels\x18\x04 \x03(\t\"\xc4\x01\n\x1eGetDeltaChannelHistoryResponse\x12J\n\x07\x65ntries\x18\x01 \x03(\x0b\x32\x39.checkpointer.GetDeltaChannelHistoryResponse.EntriesEntry\x1aV\n\x0c\x45ntriesEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\x35\n\x05value\x18\x02 \x01(\x0b\x32&.checkpointer.DeltaChannelHistoryEntry:\x02\x38\x01\x32\xf1\x05\n\x0c\x43heckpointer\x12:\n\x03Put\x12\x18.checkpointer.PutRequest\x1a\x19.checkpointer.PutResponse\x12\x43\n\tPutWrites\x12\x1e.checkpointer.PutWritesRequest\x1a\x16.google.protobuf.Empty\x12\x45\n\x0fGetCapabilities\x12\x16.google.protobuf.Empty\x1a\x1a.checkpointer.Capabilities\x12=\n\x04List\x12\x19.checkpointer.ListRequest\x1a\x1a.checkpointer.ListResponse\x12I\n\x08GetTuple\x12\x1d.checkpointer.GetTupleRequest\x1a\x1e.checkpointer.GetTupleResponse\x12I\n\x0c\x44\x65leteThread\x12!.checkpointer.DeleteThreadRequest\x1a\x16.google.protobuf.Empty\x12K\n\rDeleteForRuns\x12\".checkpointer.DeleteForRunsRequest\x1a\x16.google.protobuf.Empty\x12\x45\n\nCopyThread\x12\x1f.checkpointer.CopyThreadRequest\x1a\x16.google.protobuf.Empty\x12;\n\x05Prune\x12\x1a.checkpointer.PruneRequest\x1a\x16.google.protobuf.Empty\x12s\n\x16GetDeltaChannelHistory\x12+.checkpointer.GetDeltaChannelHistoryRequest\x1a,.checkpointer.GetDeltaChannelHistoryResponseB?Z=github.com/langchain-ai/langgraph-api/core/internal/engine/pbb\x06proto3')
 
 _globals = globals()
 _builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
@@ -36,6 +36,8 @@ if not _descriptor._USE_C_DESCRIPTORS:
   _globals['DESCRIPTOR']._serialized_options = b'Z=github.com/langchain-ai/langgraph-api/core/internal/engine/pb'
   _globals['_PUTREQUEST_NEWVERSIONSENTRY']._loaded_options = None
   _globals['_PUTREQUEST_NEWVERSIONSENTRY']._serialized_options = b'8\001'
+  _globals['_GETDELTACHANNELHISTORYRESPONSE_ENTRIESENTRY']._loaded_options = None
+  _globals['_GETDELTACHANNELHISTORYRESPONSE_ENTRIESENTRY']._serialized_options = b'8\001'
   _globals['_PUTREQUEST']._serialized_start=87
   _globals['_PUTREQUEST']._serialized_end=366
   _globals['_PUTREQUEST_NEWVERSIONSENTRY']._serialized_start=316
@@ -64,6 +66,14 @@ if not _descriptor._USE_C_DESCRIPTORS:
   _globals['_LISTRESPONSE']._serialized_end=1351
   _globals['_GETTUPLERESPONSE']._serialized_start=1353
   _globals['_GETTUPLERESPONSE']._serialized_end=1454
-  _globals['_CHECKPOINTER']._serialized_start=1457
-  _globals['_CHECKPOINTER']._serialized_end=2093
+  _globals['_DELTACHANNELHISTORYENTRY']._serialized_start=1456
+  _globals['_DELTACHANNELHISTORYENTRY']._serialized_end=1582
+  _globals['_GETDELTACHANNELHISTORYREQUEST']._serialized_start=1584
+  _globals['_GETDELTACHANNELHISTORYREQUEST']._serialized_end=1698
+  _globals['_GETDELTACHANNELHISTORYRESPONSE']._serialized_start=1701
+  _globals['_GETDELTACHANNELHISTORYRESPONSE']._serialized_end=1897
+  _globals['_GETDELTACHANNELHISTORYRESPONSE_ENTRIESENTRY']._serialized_start=1811
+  _globals['_GETDELTACHANNELHISTORYRESPONSE_ENTRIESENTRY']._serialized_end=1897
+  _globals['_CHECKPOINTER']._serialized_start=1900
+  _globals['_CHECKPOINTER']._serialized_end=2653
 # @@protoc_insertion_point(module_scope)

langgraph_grpc_common/proto/checkpointer_pb2.pyi

@@ -353,3 +353,116 @@ class GetTupleResponse(_message.Message):
     def WhichOneof(self, oneof_group: _WhichOneofArgType__checkpoint_tuple) -> _WhichOneofReturnType__checkpoint_tuple | None: ...
 
 Global___GetTupleResponse: _TypeAlias = GetTupleResponse  # noqa: Y015
+
+@_typing.final
+class DeltaChannelHistoryEntry(_message.Message):
+    """DeltaChannelHistoryEntry is the per-channel reconstruction result for
+    DeltaChannel state replay (langgraph >= 1.2).
+
+    - `seed` is the last snapshot, or absent when no snapshot was found
+    - `writes` is ordered oldest-to-newest writes between the last snapshot 
+       and the target checkpoint
+    """
+
+    DESCRIPTOR: _descriptor.Descriptor
+
+    SEED_FIELD_NUMBER: _builtins.int
+    WRITES_FIELD_NUMBER: _builtins.int
+    @_builtins.property
+    def seed(self) -> _engine_common_pb2.ChannelValue: ...
+    @_builtins.property
+    def writes(self) -> _containers.RepeatedCompositeFieldContainer[_engine_common_pb2.PendingWrite]: ...
+    def __init__(
+        self,
+        *,
+        seed: _engine_common_pb2.ChannelValue | None = ...,
+        writes: _abc.Iterable[_engine_common_pb2.PendingWrite] | None = ...,
+    ) -> None: ...
+    _HasFieldArgType: _TypeAlias = _typing.Literal["_seed", b"_seed", "seed", b"seed"]  # noqa: Y015
+    def HasField(self, field_name: _HasFieldArgType) -> _builtins.bool: ...
+    _ClearFieldArgType: _TypeAlias = _typing.Literal["_seed", b"_seed", "seed", b"seed", "writes", b"writes"]  # noqa: Y015
+    def ClearField(self, field_name: _ClearFieldArgType) -> None: ...
+    _WhichOneofReturnType__seed: _TypeAlias = _typing.Literal["seed"]  # noqa: Y015
+    _WhichOneofArgType__seed: _TypeAlias = _typing.Literal["_seed", b"_seed"]  # noqa: Y015
+    def WhichOneof(self, oneof_group: _WhichOneofArgType__seed) -> _WhichOneofReturnType__seed | None: ...
+
+Global___DeltaChannelHistoryEntry: _TypeAlias = DeltaChannelHistoryEntry  # noqa: Y015
+
+@_typing.final
+class GetDeltaChannelHistoryRequest(_message.Message):
+    DESCRIPTOR: _descriptor.Descriptor
+
+    THREAD_ID_FIELD_NUMBER: _builtins.int
+    CHECKPOINT_NS_FIELD_NUMBER: _builtins.int
+    CHECKPOINT_ID_FIELD_NUMBER: _builtins.int
+    CHANNELS_FIELD_NUMBER: _builtins.int
+    thread_id: _builtins.str
+    """Thread whose delta-channel state to reconstruct."""
+    checkpoint_ns: _builtins.str
+    """Checkpoint namespace (empty for root graph, non-empty for subgraphs)."""
+    checkpoint_id: _builtins.str
+    """Target checkpoint to reconstruct at. Empty resolves to the latest
+    checkpoint for (thread_id, checkpoint_ns).
+    """
+    @_builtins.property
+    def channels(self) -> _containers.RepeatedScalarFieldContainer[_builtins.str]:
+        """Channels to reconstruct."""
+
+    def __init__(
+        self,
+        *,
+        thread_id: _builtins.str = ...,
+        checkpoint_ns: _builtins.str = ...,
+        checkpoint_id: _builtins.str = ...,
+        channels: _abc.Iterable[_builtins.str] | None = ...,
+    ) -> None: ...
+    _HasFieldArgType: _TypeAlias = _Never  # noqa: Y015
+    def HasField(self, field_name: _HasFieldArgType) -> _builtins.bool: ...
+    _ClearFieldArgType: _TypeAlias = _typing.Literal["channels", b"channels", "checkpoint_id", b"checkpoint_id", "checkpoint_ns", b"checkpoint_ns", "thread_id", b"thread_id"]  # noqa: Y015
+    def ClearField(self, field_name: _ClearFieldArgType) -> None: ...
+    def WhichOneof(self, oneof_group: _Never) -> None: ...
+
+Global___GetDeltaChannelHistoryRequest: _TypeAlias = GetDeltaChannelHistoryRequest  # noqa: Y015
+
+@_typing.final
+class GetDeltaChannelHistoryResponse(_message.Message):
+    DESCRIPTOR: _descriptor.Descriptor
+
+    @_typing.final
+    class EntriesEntry(_message.Message):
+        DESCRIPTOR: _descriptor.Descriptor
+
+        KEY_FIELD_NUMBER: _builtins.int
+        VALUE_FIELD_NUMBER: _builtins.int
+        key: _builtins.str
+        @_builtins.property
+        def value(self) -> Global___DeltaChannelHistoryEntry: ...
+        def __init__(
+            self,
+            *,
+            key: _builtins.str = ...,
+            value: Global___DeltaChannelHistoryEntry | None = ...,
+        ) -> None: ...
+        _HasFieldArgType: _TypeAlias = _typing.Literal["value", b"value"]  # noqa: Y015
+        def HasField(self, field_name: _HasFieldArgType) -> _builtins.bool: ...
+        _ClearFieldArgType: _TypeAlias = _typing.Literal["key", b"key", "value", b"value"]  # noqa: Y015
+        def ClearField(self, field_name: _ClearFieldArgType) -> None: ...
+        def WhichOneof(self, oneof_group: _Never) -> None: ...
+
+    ENTRIES_FIELD_NUMBER: _builtins.int
+    @_builtins.property
+    def entries(self) -> _containers.MessageMap[_builtins.str, Global___DeltaChannelHistoryEntry]:
+        """Per-channel reconstruction. Keys are channel names"""
+
+    def __init__(
+        self,
+        *,
+        entries: _abc.Mapping[_builtins.str, Global___DeltaChannelHistoryEntry] | None = ...,
+    ) -> None: ...
+    _HasFieldArgType: _TypeAlias = _Never  # noqa: Y015
+    def HasField(self, field_name: _HasFieldArgType) -> _builtins.bool: ...
+    _ClearFieldArgType: _TypeAlias = _typing.Literal["entries", b"entries"]  # noqa: Y015
+    def ClearField(self, field_name: _ClearFieldArgType) -> None: ...
+    def WhichOneof(self, oneof_group: _Never) -> None: ...
+
+Global___GetDeltaChannelHistoryResponse: _TypeAlias = GetDeltaChannelHistoryResponse  # noqa: Y015

langgraph_grpc_common/proto/checkpointer_pb2_grpc.py

@@ -83,6 +83,11 @@ class CheckpointerStub(object):
                 request_serializer=checkpointer__pb2.PruneRequest.SerializeToString,
                 response_deserializer=google_dot_protobuf_dot_empty__pb2.Empty.FromString,
                 _registered_method=True)
+        self.GetDeltaChannelHistory = channel.unary_unary(
+                '/checkpointer.Checkpointer/GetDeltaChannelHistory',
+                request_serializer=checkpointer__pb2.GetDeltaChannelHistoryRequest.SerializeToString,
+                response_deserializer=checkpointer__pb2.GetDeltaChannelHistoryResponse.FromString,
+                _registered_method=True)
 
 
 class CheckpointerServicer(object):
@@ -156,6 +161,16 @@ class CheckpointerServicer(object):
         context.set_details('Method not implemented!')
         raise NotImplementedError('Method not implemented!')
 
+    def GetDeltaChannelHistory(self, request, context):
+        """GetDeltaChannelHistory reconstructs DeltaChannel state for one
+        target checkpoint by walking the parent chain to find the most
+        recent seed snapshot and collecting all writes from that snapshot
+        forward, per requested channel.
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
 
 def add_CheckpointerServicer_to_server(servicer, server):
     rpc_method_handlers = {
@@ -204,6 +219,11 @@ def add_CheckpointerServicer_to_server(servicer, server):
                     request_deserializer=checkpointer__pb2.PruneRequest.FromString,
                     response_serializer=google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
             ),
+            'GetDeltaChannelHistory': grpc.unary_unary_rpc_method_handler(
+                    servicer.GetDeltaChannelHistory,
+                    request_deserializer=checkpointer__pb2.GetDeltaChannelHistoryRequest.FromString,
+                    response_serializer=checkpointer__pb2.GetDeltaChannelHistoryResponse.SerializeToString,
+            ),
     }
     generic_handler = grpc.method_handlers_generic_handler(
             'checkpointer.Checkpointer', rpc_method_handlers)
@@ -460,3 +480,30 @@ class Checkpointer(object):
             timeout,
             metadata,
             _registered_method=True)
+
+    @staticmethod
+    def GetDeltaChannelHistory(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            '/checkpointer.Checkpointer/GetDeltaChannelHistory',
+            checkpointer__pb2.GetDeltaChannelHistoryRequest.SerializeToString,
+            checkpointer__pb2.GetDeltaChannelHistoryResponse.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)

langgraph_grpc_common/proto/checkpointer_pb2_grpc.pyi

@@ -59,6 +59,12 @@ class CheckpointerStub:
     """CopyThread copies checkpoint data from one thread to another."""
     Prune: _grpc.UnaryUnaryMultiCallable[_checkpointer_pb2.PruneRequest, _empty_pb2.Empty]
     """Prune deletes checkpoints and related data for a set of threads."""
+    GetDeltaChannelHistory: _grpc.UnaryUnaryMultiCallable[_checkpointer_pb2.GetDeltaChannelHistoryRequest, _checkpointer_pb2.GetDeltaChannelHistoryResponse]
+    """GetDeltaChannelHistory reconstructs DeltaChannel state for one
+    target checkpoint by walking the parent chain to find the most
+    recent seed snapshot and collecting all writes from that snapshot
+    forward, per requested channel.
+    """
 
 @_typing.type_check_only
 class CheckpointerAsyncStub(CheckpointerStub):
@@ -90,6 +96,12 @@ class CheckpointerAsyncStub(CheckpointerStub):
     """CopyThread copies checkpoint data from one thread to another."""
     Prune: _aio.UnaryUnaryMultiCallable[_checkpointer_pb2.PruneRequest, _empty_pb2.Empty]  # type: ignore[assignment]
     """Prune deletes checkpoints and related data for a set of threads."""
+    GetDeltaChannelHistory: _aio.UnaryUnaryMultiCallable[_checkpointer_pb2.GetDeltaChannelHistoryRequest, _checkpointer_pb2.GetDeltaChannelHistoryResponse]  # type: ignore[assignment]
+    """GetDeltaChannelHistory reconstructs DeltaChannel state for one
+    target checkpoint by walking the parent chain to find the most
+    recent seed snapshot and collecting all writes from that snapshot
+    forward, per requested channel.
+    """
 
 class CheckpointerServicer(metaclass=_abc_1.ABCMeta):
     """Checkpoint persistence.
@@ -173,4 +185,16 @@ class CheckpointerServicer(metaclass=_abc_1.ABCMeta):
     ) -> _typing.Union[_empty_pb2.Empty, _abc.Awaitable[_empty_pb2.Empty]]:
         """Prune deletes checkpoints and related data for a set of threads."""
 
+    @_abc_1.abstractmethod
+    def GetDeltaChannelHistory(
+        self,
+        request: _checkpointer_pb2.GetDeltaChannelHistoryRequest,
+        context: _ServicerContext,
+    ) -> _typing.Union[_checkpointer_pb2.GetDeltaChannelHistoryResponse, _abc.Awaitable[_checkpointer_pb2.GetDeltaChannelHistoryResponse]]:
+        """GetDeltaChannelHistory reconstructs DeltaChannel state for one
+        target checkpoint by walking the parent chain to find the most
+        recent seed snapshot and collecting all writes from that snapshot
+        forward, per requested channel.
+        """
+
 def add_CheckpointerServicer_to_server(servicer: CheckpointerServicer, server: _typing.Union[_grpc.Server, _aio.Server]) -> None: ...

langgraph_grpc_common/serde.py

@@ -2,7 +2,9 @@ import re
 import uuid
 from base64 import b64encode
 from collections import deque
-from collections.abc import Mapping
+from collections.abc import Iterator, Mapping
+from contextlib import contextmanager
+from contextvars import ContextVar
 from datetime import timedelta, timezone
 from decimal import Decimal
 from ipaddress import (
@@ -22,8 +24,16 @@ import orjson
 from langgraph.checkpoint.serde.base import SerializerProtocol
 from langgraph.checkpoint.serde.jsonplus import JsonPlusSerializer
 
+# Process-wide default serializer.
 SERIALIZER: SerializerProtocol = JsonPlusSerializer()
 
+# Task-local override and falls back to ``SERIALIZER`` when unset.
+# (e.g. ``GrpcCheckpointer``) scope a custom serializer to its own RPC
+# bodies without leaking into unrelated gRPC ops
+_SCOPED_SERIALIZER: ContextVar[SerializerProtocol | None] = ContextVar(
+    "_grpc_scoped_serializer", default=None
+)
+
 
 class Fragment(NamedTuple):
     buf: bytes
@@ -154,9 +164,31 @@ def json_dumpb(obj) -> bytes:
 
 
 def set_serializer(serializer: SerializerProtocol) -> None:
-    global SERIALIZER
-    SERIALIZER = serializer
+    """Replace the process-wide default serializer.
 
+    This only affects every consumer of ``langgraph_grpc_common.conversion.*``.
+    """
+    global SERIALIZER
+    SERIALIZER = serializer 
 
 def get_serializer() -> SerializerProtocol:
-    return SERIALIZER
+    """Return the serializer to use for gRPC payload (de)serialization.
+
+    Resolution order:
+
+    1. A task-local override bound via :func:`use_serializer`, if any.
+    2. The process-wide default set by :func:`set_serializer` (or the
+       ``JsonPlusSerializer()`` baseline if never replaced).
+    """
+    return _SCOPED_SERIALIZER.get() or SERIALIZER
+
+
+@contextmanager
+def use_serializer(serializer: SerializerProtocol) -> Iterator[None]:
+    """Bind ``serializer`` for the current async task / sync context.
+    """
+    token = _SCOPED_SERIALIZER.set(serializer)
+    try:
+        yield
+    finally:
+        _SCOPED_SERIALIZER.reset(token)