langgraph-api 0.17.0.dev3__py3-none-any.whl → 0.17.0.dev5__py3-none-any.whl

LICENSE

@@ -90,4 +90,4 @@ these terms.
 
 **use** means anything you do with the software requiring one of your licenses.
 
-**trademark** means trademarks, service marks, and similar rights.
+**trademark** means trademarks, service marks, and similar rights.

langgraph_api/__init__.py

@@ -1 +1 @@
-__version__ = "0.17.0.dev3"
+__version__ = "0.17.0.dev5"

langgraph_api/api/event_streaming.py

@@ -33,7 +33,7 @@ from starlette.websockets import WebSocketDisconnect
 
 from langgraph_api.event_streaming.service import ThreadRunManager
 from langgraph_api.event_streaming.session import _is_supported_channel
-from langgraph_api.event_streaming.types import Subscription
+from langgraph_api.event_streaming.types import ErrorResponse, Subscription
 from langgraph_api.feature_flags import IS_POSTGRES_OR_GRPC_BACKEND
 from langgraph_api.route import ApiRoute, ApiWebSocketRoute
 from langgraph_api.serde import json_dumpb
@@ -61,6 +61,19 @@ logger = structlog.stdlib.get_logger(__name__)
 # connection, vs. the unbounded set this replaces.
 _DELIVERED_DEDUP_WINDOW = 2048
 
+# Final frame on SSE and WebSocket when the thread-stream consumer stops
+# without being cancelled. A thread stream has no natural end, so that always
+# means the read failed. The message is fixed because the exception text can
+# carry raw backend errors; the consumer has already logged it.
+_THREAD_STREAM_FAILED_DATA = json_dumpb(
+    ErrorResponse(
+        type="error",
+        id=None,
+        error="unknown_error",
+        message="Thread event stream failed.",
+    )
+)
+
 
 def _json_response(content: Any, *, status_code: int = 200) -> Response:
     """JSON response backed by the repo's orjson helper.
@@ -118,6 +131,10 @@ async def _thread_events(request: Request) -> Response:
         The filter applies for the lifetime of the connection; closing the
         connection unsubscribes. No state is persisted server-side beyond the
         connection.
+
+        If reading the thread's event stream fails, the server ends the
+        stream with a final ``event: error`` frame carrying a protocol error
+        (``"type": "error"``, ``"id": null``, ``"error": "unknown_error"``).
     """
     thread_id = request.path_params["thread_id"]
     try:
@@ -245,10 +262,9 @@ async def _thread_events(request: Request) -> Response:
         try:
             while True:
                 # Race ``flush_pending`` against the thread-stream consumer
-                # ending. If the consumer dies (transient join_event_streaming
-                # error, or normal shutdown), we want this loop to exit
-                # rather than wedge forever waiting for events that will
-                # never arrive.
+                # ending. If the consumer stops (its read failed or its
+                # source ended), we want this loop to exit rather than
+                # wedge forever waiting for events that will never arrive.
                 flush_task = asyncio.create_task(flush_pending.wait())
                 done_task = asyncio.create_task(manager.wait_for_thread_stream_end())
                 try:
@@ -285,6 +301,8 @@ async def _thread_events(request: Request) -> Response:
                         str(sse_id).encode() if isinstance(sse_id, int) else None,
                     )
                 if stream_finished:
+                    if manager.thread_stream_failed:
+                        yield (b"error", _THREAD_STREAM_FAILED_DATA)
                     break
         finally:
             await manager.close()
@@ -366,14 +384,16 @@ async def _thread_websocket(websocket: WebSocket) -> None:
     manager = _make_manager(thread_id, send_event=ws_send_event)
     manager.start_thread_stream()
 
-    # Watchdog: when the thread-stream consumer ends (transient
-    # ``join_event_streaming`` failure or normal shutdown), close the socket so
-    # the client sees a clean disconnect instead of an open connection
-    # that will never deliver another event. ``receive_text`` below
-    # raises ``WebSocketDisconnect`` once the close lands, exiting the
-    # loop through its existing handler.
+    # Watchdog: when the thread-stream consumer stops, send the error frame
+    # (if it wasn't cancelled) and close the socket, instead of leaving the
+    # client on an open connection that will never deliver another event.
+    # ``receive_text`` below raises ``WebSocketDisconnect`` once the close
+    # lands, exiting the loop through its existing handler.
     async def _stream_watchdog() -> None:
         await manager.wait_for_thread_stream_end()
+        if manager.thread_stream_failed:
+            with contextlib.suppress(Exception):
+                await websocket.send_text(_THREAD_STREAM_FAILED_DATA.decode())
         with contextlib.suppress(Exception):
             await websocket.close(code=1011, reason="thread stream ended")
 

langgraph_api/api/threads.py

@@ -36,7 +36,6 @@ from langgraph_api.validation import (
     ThreadStateSearch,
     ThreadStateUpdate,
 )
-from langgraph_runtime import checkpoint as runtime_checkpoint
 from langgraph_runtime.database import connect
 from langgraph_runtime.retry import retry_db
 
@@ -349,17 +348,13 @@ async def get_thread_storage(request: ApiRequest):
     """Bytes a thread's checkpoints occupy, per table and per channel."""
     thread_id = request.path_params["thread_id"]
     validate_uuid(thread_id, "Invalid thread ID: must be a UUID")
-    thread_storage = getattr(runtime_checkpoint, "thread_storage", None)
-    if USE_CUSTOM_CHECKPOINTER or thread_storage is None:
+    if USE_CUSTOM_CHECKPOINTER or not hasattr(Threads, "storage"):
         raise HTTPException(
             status_code=501,
             detail="Checkpoint storage is only reported for the built-in checkpointer.",
         )
     async with connect() as conn:
-        await fetchone(await Threads.get(conn, thread_id))
-    # The built-in tables are read directly; the core-api stand-in cannot run SQL.
-    async with connect(supports_core_api=False) as conn:
-        storage = await thread_storage(conn, thread_id)
+        storage = await Threads.storage(conn, thread_id)
     return ApiResponse({"thread_id": thread_id, **storage})
 
 

langgraph_api/cache.py

@@ -26,12 +26,17 @@ else:
 
     async def _cache_set(key: str, value: bytes, ttl: timedelta | None = None) -> None:
         ttl = _clamp_ttl(ttl)
-        _CACHE.set(key, value)
+        _CACHE.set(key, value, ttl=ttl.total_seconds())
 
 
 logger = logging.getLogger(__name__)
 
 _SWR_KEY_PREFIX = "__lg_swr__:"
+# Deliberately a disjoint prefix (diverges from _SWR_KEY_PREFIX at the first
+# character after the shared "__lg_swr" stem), not a suffix appended to a
+# cache_key: a caller using swr(key="foo:marker") would otherwise produce a
+# cache_key identical to the marker key for swr(key="foo"), clobbering it.
+_SWR_MARKER_KEY_PREFIX = "__lg_swr_marker__:"
 _SWR_SCHEMA_VERSION = 1
 _DELTA_ZERO = timedelta(0)
 _UNSET: Any = object()
@@ -127,6 +132,31 @@ class _SWREntry(TypedDict):
     stored_at_ms: int
 
 
+class _SWRMarker(TypedDict):
+    """A tiny, payload-free record of when a key was last written.
+
+    Stored under a separate key with a much longer ttl than the full entry,
+    so swr() can still tell "this existed and is now expired" from "never
+    written" long after the (possibly large) payload itself has expired.
+
+    Two accepted trade-offs from using a second key, deliberately not
+    engineered around:
+    - A write's ttl=max_age reflects that call's own max_age, not the
+      largest max_age any caller has ever used for this key. A key read
+      with different max_age values across calls can see an earlier,
+      shorter-lived write evict the entry before a later call's own window
+      would have, forcing an extra reload. The reload still returns a
+      correct value; only cache-hit efficiency is affected.
+    - Every swr() key now costs two slots in the in-memory backend's
+      max_size=1000 LRU instead of one. swr() is scoped to moderate-
+      cardinality use (auth/metadata lookups per its own docstring), so this
+      is judged an acceptable capacity cost for bounding payload memory.
+    """
+
+    v: int
+    stored_at_ms: int
+
+
 @dataclass(slots=True)
 class _SWRState:
     task: asyncio.Task[Any] | None = None
@@ -158,10 +188,15 @@ async def swr(
             Defaults to ``timedelta(0)`` so every access triggers a background
             revalidate while still returning the cached value instantly. Values
             above :data:`MAX_CACHE_TTL` are clamped to the backend maximum.
-        max_age: Total lifetime of a cached entry. After this, the next access
-            blocks on the loader. Defaults to :data:`MAX_CACHE_TTL` (24 h by
-            default). Values above :data:`MAX_CACHE_TTL` are clamped to the
-            backend maximum.
+        max_age: Total lifetime of a cached entry before it's considered
+            expired rather than stale. After this, the next access blocks on
+            the loader. Defaults to :data:`MAX_CACHE_TTL` (24 h by default).
+            Values above :data:`MAX_CACHE_TTL` are clamped to the backend
+            maximum. The full entry is physically stored for `max_age`, so a
+            short `max_age` doesn't pin a large payload in the backend for
+            longer than it's needed; a small marker without the payload is
+            kept for the backend's max TTL so `swr` can still classify a
+            later access as `"expired"` instead of missing it entirely.
         model: Optional Pydantic model class. When provided, values are
             serialized via ``model_dump(mode="json")`` before storage and
             deserialized via ``model.model_validate()`` on read.
@@ -179,7 +214,7 @@ async def swr(
     """
     resolved_fresh_for = min(fresh_for, MAX_CACHE_TTL)
     resolved_max_age = _resolve_swr_max_age(max_age)
-    fresh_for_ms, max_age_ms, resolved_max_age = _validate_swr_windows(
+    fresh_for_ms, max_age_ms = _validate_swr_windows(
         resolved_fresh_for, resolved_max_age
     )
     cache_key = _swr_cache_key(key)
@@ -216,8 +251,11 @@ async def swr(
 
     entry = _parse_swr_entry(await cache_get(cache_key))
     if entry is None:
+        # The full entry is gone, but a marker surviving past the entry's own
+        # ttl means it existed before and is now expired, not merely missing.
+        marker = _parse_swr_marker(await cache_get(_swr_marker_key(cache_key)))
         raw = await _await_swr_load(cache_key, json_loader, resolved_max_age)
-        return _result(_deserialize(raw), "miss")
+        return _result(_deserialize(raw), "expired" if marker is not None else "miss")
 
     age_ms = max(0, _now_ms() - entry["stored_at_ms"])
     cached_value = _deserialize(entry["value"])
@@ -252,9 +290,11 @@ def _swr_cache_key(key: str) -> str:
     return f"{_SWR_KEY_PREFIX}{key}"
 
 
-def _validate_swr_windows(
-    fresh_for: timedelta, max_age: timedelta
-) -> tuple[int, int, timedelta]:
+def _swr_marker_key(cache_key: str) -> str:
+    return _SWR_MARKER_KEY_PREFIX + cache_key.removeprefix(_SWR_KEY_PREFIX)
+
+
+def _validate_swr_windows(fresh_for: timedelta, max_age: timedelta) -> tuple[int, int]:
     if fresh_for < _DELTA_ZERO:
         raise ValueError("fresh_for must be >= 0")
     if max_age <= _DELTA_ZERO:
@@ -265,7 +305,6 @@ def _validate_swr_windows(
     return (
         int(fresh_for.total_seconds() * 1000),
         int(max_age.total_seconds() * 1000),
-        max_age,
     )
 
 
@@ -291,6 +330,18 @@ def _parse_swr_entry(value: Any) -> _SWREntry | None:
     }
 
 
+def _parse_swr_marker(value: Any) -> _SWRMarker | None:
+    if not isinstance(value, dict):
+        return None
+
+    version = value.get("v")
+    stored_at_ms = value.get("stored_at_ms")
+    if version != _SWR_SCHEMA_VERSION or not isinstance(stored_at_ms, int):
+        return None
+
+    return {"v": _SWR_SCHEMA_VERSION, "stored_at_ms": stored_at_ms}
+
+
 def _acquire_swr_state(cache_key: str) -> _SWRState:
     state = _SWR_STATES.get(cache_key)
     if state is None:
@@ -315,34 +366,41 @@ def _maybe_cleanup_swr_state(cache_key: str, state: _SWRState) -> None:
         _SWR_STATES.pop(cache_key, None)
 
 
-async def _cache_swr_entry(cache_key: str, value: Any, ttl: timedelta) -> None:
+async def _cache_swr_entry(cache_key: str, value: Any, max_age: timedelta) -> None:
+    stored_at_ms = _now_ms()
     entry: _SWREntry = {
         "v": _SWR_SCHEMA_VERSION,
         "value": value,
-        "stored_at_ms": _now_ms(),
+        "stored_at_ms": stored_at_ms,
     }
-    await cache_set(cache_key, entry, ttl=ttl)
+    marker: _SWRMarker = {"v": _SWR_SCHEMA_VERSION, "stored_at_ms": stored_at_ms}
+    # The full payload expires at max_age, so a short max_age doesn't pin a
+    # large value in the backend longer than it's needed. The marker carries
+    # no payload, so it's cheap to keep around for the backend's own max ttl
+    # regardless of max_age - see swr()'s cache_get(cache_key) is None branch.
+    await cache_set(cache_key, entry, ttl=max_age)
+    await cache_set(_swr_marker_key(cache_key), marker)
 
 
-async def _write_swr_value(cache_key: str, value: Any, ttl: timedelta) -> None:
+async def _write_swr_value(cache_key: str, value: Any, max_age: timedelta) -> None:
     state = _acquire_swr_state(cache_key)
     try:
         async with state.write_lock:
             state.write_epoch += 1
-            await _cache_swr_entry(cache_key, value, ttl)
+            await _cache_swr_entry(cache_key, value, max_age)
     finally:
         _release_swr_state(cache_key, state)
 
 
 async def _store_loaded_swr_value(
-    cache_key: str, value: Any, ttl: timedelta, *, start_epoch: int
+    cache_key: str, value: Any, max_age: timedelta, *, start_epoch: int
 ) -> bool:
     state = _acquire_swr_state(cache_key)
     try:
         async with state.write_lock:
             if start_epoch != state.write_epoch:
                 return False
-            await _cache_swr_entry(cache_key, value, ttl)
+            await _cache_swr_entry(cache_key, value, max_age)
             return True
     finally:
         _release_swr_state(cache_key, state)
@@ -351,12 +409,14 @@ async def _store_loaded_swr_value(
 async def _load_and_store_swr_value(
     cache_key: str,
     loader: Callable[[], Awaitable[T]],
-    ttl: timedelta,
+    max_age: timedelta,
     *,
     start_epoch: int,
 ) -> T:
     value = await loader()
-    if await _store_loaded_swr_value(cache_key, value, ttl, start_epoch=start_epoch):
+    if await _store_loaded_swr_value(
+        cache_key, value, max_age, start_epoch=start_epoch
+    ):
         return value
 
     entry = _parse_swr_entry(await cache_get(cache_key))
@@ -368,7 +428,7 @@ async def _load_and_store_swr_value(
 def _ensure_swr_load_task(
     cache_key: str,
     loader: Callable[[], Awaitable[T]],
-    ttl: timedelta,
+    max_age: timedelta,
     *,
     log_errors: bool,
 ) -> asyncio.Task[T]:
@@ -380,7 +440,7 @@ def _ensure_swr_load_task(
 
         task = asyncio.create_task(
             _load_and_store_swr_value(
-                cache_key, loader, ttl, start_epoch=state.write_epoch
+                cache_key, loader, max_age, start_epoch=state.write_epoch
             )
         )
         state.task = task
@@ -407,12 +467,12 @@ def _ensure_swr_load_task(
 
 
 async def _await_swr_load(
-    cache_key: str, loader: Callable[[], Awaitable[T]], ttl: timedelta
+    cache_key: str, loader: Callable[[], Awaitable[T]], max_age: timedelta
 ) -> T:
-    return await _ensure_swr_load_task(cache_key, loader, ttl, log_errors=False)
+    return await _ensure_swr_load_task(cache_key, loader, max_age, log_errors=False)
 
 
 def _start_swr_refresh(
-    cache_key: str, loader: Callable[[], Awaitable[Any]], ttl: timedelta
+    cache_key: str, loader: Callable[[], Awaitable[Any]], max_age: timedelta
 ) -> None:
-    _ensure_swr_load_task(cache_key, loader, ttl, log_errors=True)
+    _ensure_swr_load_task(cache_key, loader, max_age, log_errors=True)

langgraph_api/config/__init__.py

@@ -23,6 +23,11 @@ from langgraph_api.config.schemas import (
     WebhooksConfig,
     webhooks_validator,
 )
+from langgraph_api.feature_flags import (
+    IS_POSTGRES_BACKEND,
+    OMIT_PENDING_SENDS,
+    PREFER_GRPC_CHECKPOINTER,
+)
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -50,6 +55,21 @@ STATS_INTERVAL_SECS = env("STATS_INTERVAL_SECS", cast=int, default=60)
 DATABASE_URI: str | None = env(
     "DATABASE_URI", cast=str, default=getenv("POSTGRES_URI", None)
 )
+
+
+def _validate_langgraph_without_database(
+    *, langgraph_supported: bool, is_postgres: bool
+) -> None:
+    """Reject langgraph < 0.5 when the Postgres runtime has no DATABASE_URI."""
+    # langgraph < 0.5 always uses the Python checkpointer, which needs a direct
+    # connection (see feature_flags.PREFER_GRPC_CHECKPOINTER).
+    if is_postgres and not langgraph_supported and not DATABASE_URI:
+        raise ValueError("langgraph >= 0.5 is required when core-api owns the database")
+
+
+_validate_langgraph_without_database(
+    langgraph_supported=OMIT_PENDING_SENDS, is_postgres=IS_POSTGRES_BACKEND
+)
 AGENT_POSTGRES_IAM_AUTH_PROVIDER = env(
     "AGENT_POSTGRES_IAM_AUTH_PROVIDER", cast=str, default=""
 )
@@ -155,6 +175,28 @@ LANGGRAPH_AES_JSON_KEYS: frozenset[str] | None = env(
     "LANGGRAPH_AES_JSON_KEYS", default=None, cast=_get_aes_json_keys
 )
 
+
+def _validate_aes_rotation(
+    prefer_grpc_checkpointer: bool, *, is_postgres: bool
+) -> None:
+    """Reject AES key rotation when Python owns checkpoints, as core-server does."""
+    # Uses the derived PREFER_GRPC_CHECKPOINTER (false on langgraph < 0.5), while
+    # core-server checks the raw env var. A missing LANGGRAPH_AES_KEY is left to
+    # core-server, which reports it first.
+    rotation_keys = getenv("LANGGRAPH_AES_LEGACY_KEY") or getenv(
+        "LANGGRAPH_AES_FALLBACK_KEYS"
+    )
+    if (
+        is_postgres
+        and not prefer_grpc_checkpointer
+        and rotation_keys
+        and LANGGRAPH_AES_KEY
+    ):
+        raise ValueError("AES key rotation requires PREFER_GRPC_CHECKPOINTER=true")
+
+
+_validate_aes_rotation(PREFER_GRPC_CHECKPOINTER, is_postgres=IS_POSTGRES_BACKEND)
+
 # redis
 # Not in public docs: infrastructure, set by platform
 REDIS_URI = env("REDIS_URI_CUSTOM", cast=str, default="") or env("REDIS_URI", cast=str)
@@ -275,9 +317,6 @@ WEBHOOKS_ENABLED = HTTP_CONFIG and HTTP_CONFIG.get("disable_webhooks")
 STORE_CONFIG = env(
     "LANGGRAPH_STORE", cast=_parse.parse_schema(StoreConfig), default=None
 )
-LANGGRAPH_STORE_BACKEND = env("LANGGRAPH_STORE_BACKEND", cast=str, default="python")
-USE_GRPC_STORE = LANGGRAPH_STORE_BACKEND == "grpc"
-
 # When true, the Go core-server owns Postgres schema setup (DB migrations +
 # vector index)
 DB_MIGRATION_BY_CORE_API = env("DB_MIGRATION_BY_CORE_API", cast=bool, default=False)
@@ -469,6 +508,8 @@ FF_USE_REDIS_QUEUE = env("FF_USE_REDIS_QUEUE", cast=bool, default=True)
 
 # Internal flag intended for testing only
 CRON_SCHEDULER_SLEEP_TIME = env("CRON_SCHEDULER_SLEEP_TIME", cast=int, default=5)
+# Not in public docs: max due crons each scheduler claims per poll; <= 0 means no limit
+CRON_SCHEDULER_BATCH_SIZE = env("CRON_SCHEDULER_BATCH_SIZE", cast=int, default=-1)
 
 
 # auth
@@ -718,6 +759,7 @@ __all__ = [
     "CHECKPOINT_MAX_BATCH_SIZE",
     "CORS_ALLOW_ORIGINS",
     "CORS_CONFIG",
+    "CRON_SCHEDULER_BATCH_SIZE",
     "CRON_SCHEDULER_SLEEP_TIME",
     "DATABASE_URI",
     "DATADOG_METRICS_ENABLED",
@@ -756,7 +798,6 @@ __all__ = [
     "LANGGRAPH_METRICS_ENDPOINT",
     "LANGGRAPH_METRICS_EXPORT_INTERVAL_MS",
     "LANGGRAPH_POSTGRES_EXTENSIONS",
-    "LANGGRAPH_STORE_BACKEND",
     "LANGSMITH_API_KEY",
     "LANGSMITH_AUTH_ENDPOINT",
     "LANGSMITH_AUTH_VERIFY_TENANT_ID",
@@ -804,7 +845,6 @@ __all__ = [
     "USES_STORE_TTL",
     "USES_THREAD_TTL",
     "USE_CUSTOM_CHECKPOINTER",
-    "USE_GRPC_STORE",
     "AuthConfig",
     "CheckpointerConfig",
     "CorsConfig",

langgraph_api/config/schemas.py

@@ -150,7 +150,7 @@ class IndexConfig(TypedDict, total=False):
 
     dims: int
     """Number of dimensions in the embedding vectors.
-    
+
     Common embedding models have the following dimensions:
         - OpenAI text-embedding-3-large: 256, 1024, or 3072
         - OpenAI text-embedding-3-small: 512 or 1536
@@ -164,13 +164,13 @@ class IndexConfig(TypedDict, total=False):
     embed: str
     """Either a path to an embedding model (./path/to/file.py:embedding_model)
     or a name of an embedding model (openai:text-embedding-3-small)
-    
+
     Note: LangChain is required to use the model format specification.
     """
 
     fields: list[str] | None
     """Fields to extract text from for embedding generation.
-    
+
     Defaults to the root ["$"], which embeds the json object as a whole.
     """
 
@@ -180,21 +180,21 @@ class TTLConfig(TypedDict, total=False):
 
     refresh_on_read: bool
     """Default behavior for refreshing TTLs on read operations (GET and SEARCH).
-    
+
     If True, TTLs will be refreshed on read operations (get/search) by default.
     This can be overridden per-operation by explicitly setting refresh_ttl.
     Defaults to True if not configured.
     """
     default_ttl: float | None
     """Default TTL (time-to-live) in minutes for new items.
-    
+
     If provided, new items will expire after this many minutes after their last access.
     The expiration timer refreshes on both read and write operations.
     Defaults to None (no expiration).
     """
     sweep_interval_minutes: int | None
     """Interval in minutes between TTL sweep operations.
-    
+
     If provided, the store will periodically delete expired items based on TTL.
     Defaults to None (no sweeping).
     """
@@ -223,11 +223,11 @@ class SerdeConfig(TypedDict, total=False):
 
     allowed_json_modules: list[list[str]] | Literal[True] | None
     """Optional. List of allowed python modules to de-serialize custom objects from.
-    
+
     If provided, only the specified modules will be allowed to be deserialized.
     If omitted, no modules are allowed, and the object returned will simply be a json object OR
     a deserialized langchain object.
-    
+
     Example:
     {...
         "serde": {
@@ -245,11 +245,11 @@ class SerdeConfig(TypedDict, total=False):
             "allowed_json_modules": true
         }
     }
-    
+
     """
     pickle_fallback: bool
     """Optional. Whether to allow pickling as a fallback for deserialization.
-    
+
     If True, pickling will be allowed as a fallback for deserialization.
     If False, pickling will not be allowed as a fallback for deserialization.
     Defaults to True if not configured."""
@@ -261,7 +261,7 @@ class DefaultCheckpointerConfig(TypedDict):
     backend: Literal["default"]
     ttl: NotRequired[ThreadTTLConfig | None]
     """Optional. Defines the TTL (time-to-live) behavior configuration.
-    
+
     If provided, the checkpointer will apply TTL settings according to the configuration.
     If omitted, no TTL behavior is configured.
     """
@@ -284,7 +284,7 @@ class CustomCheckpointerConfig(TypedDict):
     """
     ttl: NotRequired[ThreadTTLConfig | None]
     """Optional. Defines the TTL (time-to-live) behavior configuration.
-    
+
     If provided, the checkpointer will apply TTL settings according to the configuration.
     If omitted, no TTL behavior is configured.
     """

langgraph_api/cron_scheduler.py

@@ -25,6 +25,7 @@ else:
 logger = structlog.stdlib.get_logger(__name__)
 
 SLEEP_TIME = config.CRON_SCHEDULER_SLEEP_TIME
+BATCH_SIZE = config.CRON_SCHEDULER_BATCH_SIZE
 
 
 def get_metadata_from_payload(
@@ -47,13 +48,19 @@ def get_metadata_from_payload(
     return {**cron_metadata, **existing_metadata}
 
 
+def batch_was_full(claimed: int) -> bool:
+    return BATCH_SIZE > 0 and claimed >= BATCH_SIZE
+
+
 @retry_db
 async def cron_scheduler():
     logger.info("Starting cron scheduler")
     while True:
         try:
+            claimed = 0
             async with connect() as conn:
                 async for cron, enc_ctx in Crons.next(conn):
+                    claimed += 1
                     on_run_completed = cron.get("on_run_completed")
 
                     run_payload = cron["payload"]
@@ -75,6 +82,12 @@ async def cron_scheduler():
                     ):
                         logger.debug(f"Scheduling cron run {cron}")
                         try:
+                            cron_id = None
+                            if run_payload.get("context"):
+                                # Cron persistence and set_auth_ctx_for_run write these into configurable, which create_valid_run rejects next to context.
+                                configurable = run_payload["config"]["configurable"]
+                                cron_id = configurable.pop("cron_id", None)
+                                configurable.pop("langgraph_auth_user", None)
                             run = await create_valid_run(
                                 conn,
                                 thread_id=(
@@ -84,6 +97,7 @@ async def cron_scheduler():
                                 ),
                                 payload=run_payload,
                                 headers={},
+                                cron_id=cron_id,
                             )
                             if not run:
                                 logger.error(
@@ -112,7 +126,8 @@ async def cron_scheduler():
                                 conn, cron["cron_id"], next_run_date
                             )
 
-            await asyncio.sleep(SLEEP_TIME)
+            if not batch_was_full(claimed):
+                await asyncio.sleep(SLEEP_TIME)
         except asyncio.CancelledError:
             raise
         except Exception:

langgraph_api/event_streaming/__init__.py

@@ -1 +0,0 @@
-

langgraph_api/event_streaming/service.py

@@ -194,11 +194,13 @@ class ThreadRunManager:
         self._seq: int = 0
         self._thread_source_task: asyncio.Task[None] | None = None
         # Set by ``_consume_thread_stream`` when the background task
-        # exits — success, cancellation, or unexpected failure all
-        # transition this. Route handlers (SSE body_iter, WS watchdog)
-        # await this so a transient ``join_event_streaming`` failure can no
-        # longer leave the connection wedged with no events flowing.
+        # exits for any reason, including cancellation. Route handlers
+        # (SSE body_iter, WS watchdog) await this so a transient
+        # ``join_event_streaming`` failure can no longer leave the
+        # connection wedged with no events flowing.
         self._thread_stream_done: asyncio.Event = asyncio.Event()
+        # Set when the consumer stops for any reason other than cancellation.
+        self._thread_stream_failed: bool = False
         # WebSocket clients typically call ``subscription.subscribe``
         # before ``run.start`` — natural ordering since they want to
         # observe before firing. Buffer those subscriptions here and
@@ -224,6 +226,15 @@ class ThreadRunManager:
     def seq(self) -> int:
         return self._seq
 
+    @property
+    def thread_stream_failed(self) -> bool:
+        """Whether the thread-stream consumer stopped without being cancelled.
+
+        A thread stream has no natural end, so the consumer stopping on its
+        own, by raising or by its source finishing, means the read failed.
+        """
+        return self._thread_stream_failed
+
     async def attach_event_sink(self, send_event: EventSink) -> None:
         """Attach a live transport consumer and flush buffered events."""
         self._send_event = send_event
@@ -307,12 +318,19 @@ class ThreadRunManager:
         except asyncio.CancelledError:
             raise
         except Exception as exc:
+            self._thread_stream_failed = True
             await logger.aexception(
                 "protocol thread stream failed",
                 thread_id=str(self._thread_id),
                 error=str(exc),
                 error_type=type(exc).__name__,
             )
+        else:
+            self._thread_stream_failed = True
+            await logger.awarning(
+                "protocol thread stream ended unexpectedly",
+                thread_id=str(self._thread_id),
+            )
         finally:
             # Wake up SSE body_iter / WS watchdog so the connection can
             # be torn down. Without this, a transient ``join_event_streaming``