langgraph-api 0.18.0.dev3__tar.gz → 0.18.0.dev4__tar.gz

{langgraph_api-0.18.0.dev3 → langgraph_api-0.18.0.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langgraph-api
-Version: 0.18.0.dev3
+Version: 0.18.0.dev4
 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

langgraph_api-0.18.0.dev4/langgraph_api/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.18.0.dev4"

{langgraph_api-0.18.0.dev3 → langgraph_api-0.18.0.dev4}/langgraph_api/api/event_streaming.py

@@ -28,6 +28,7 @@ from uuid import uuid4
 
 import orjson
 import structlog
+from starlette.exceptions import HTTPException
 from starlette.responses import Response
 from starlette.websockets import WebSocketDisconnect
 
@@ -38,6 +39,7 @@ 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
 from langgraph_api.sse import EventSourceResponse
+from langgraph_api.utils import validate_uuid
 
 if TYPE_CHECKING:
     from collections.abc import Mapping
@@ -98,6 +100,7 @@ def _make_manager(
     send_event: Any = None,
     *,
     headers: Mapping[str, str] | None = None,
+    replay_buffer: bool = True,
 ) -> ThreadRunManager:
     # Auth context is propagated via ``ApiRoute``'s ``with_user`` wrapper
     # — ops reads it off the context var, so we don't thread it through
@@ -108,6 +111,7 @@ def _make_manager(
         threads=Threads,
         send_event=send_event,
         headers=headers,
+        replay_buffer=replay_buffer,
     )
 
 
@@ -143,8 +147,12 @@ async def _thread_events(request: Request) -> Response:
         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"``).
+
+        A thread the caller isn't allowed to read returns 403 or 404 before
+        the stream starts, and a malformed thread ID returns 422.
     """
     thread_id = request.path_params["thread_id"]
+    thread_uuid = validate_uuid(thread_id, "Invalid thread ID: must be a UUID")
     try:
         body = orjson.loads(await request.body())
     except Exception:
@@ -217,6 +225,10 @@ async def _thread_events(request: Request) -> Response:
         else None
     )
 
+    # Checked here, before the 200, because clients retry a 200 that ends in
+    # an error instead of giving up.
+    auth_filters = await Threads.Stream.check_thread_stream_auth(thread_uuid)
+
     # Bounded LRU dedup: ``recent_eids`` is the eviction order, ``delivered``
     # is the O(1) membership view. When the deque hits its cap, the oldest
     # entry rolls off; we mirror that on ``delivered`` to keep them in sync.
@@ -241,7 +253,10 @@ async def _thread_events(request: Request) -> Response:
         pending_events.append(event)
         flush_pending.set()
 
-    manager = _make_manager(thread_id, send_event=on_event)
+    # SSE never replays from the session's buffer: it has no subscribe or
+    # reconnect commands, and ``start_thread_stream`` replays from the
+    # thread's event stream.
+    manager = _make_manager(thread_id, send_event=on_event, replay_buffer=False)
 
     filter_sub = Subscription(
         id=str(uuid4()),
@@ -264,7 +279,7 @@ async def _thread_events(request: Request) -> Response:
     # outbound events; the thread-level reader always replays from the
     # beginning so namespace-scoped projections see history. See
     # ``ThreadRunManager.start_thread_stream`` for the rationale.
-    manager.start_thread_stream()
+    manager.start_thread_stream(auth_filters=auth_filters)
 
     async def body_iter():
         try:
@@ -377,20 +392,51 @@ async def _thread_command(request: Request) -> Response:
 # ---------------------------------------------------------------------------
 
 
+async def _close_for_failed_access_check(websocket: WebSocket, exc: Exception) -> None:
+    if isinstance(exc, HTTPException) and exc.status_code < 500:
+        await websocket.close(code=4000 + exc.status_code)
+        return
+    logger.exception("Thread stream access check failed")
+    await websocket.send_text(_THREAD_STREAM_FAILED_DATA.decode())
+    await websocket.close(code=1011, reason="thread stream ended")
+
+
 async def _thread_websocket(websocket: WebSocket) -> None:
     """Full-duplex protocol connection scoped to a thread.
 
     Supports ``run.start``, ``input.respond``, ``subscription.subscribe``,
     ``subscription.unsubscribe``, ``agent.getTree``.
+
+    A 4xx from the thread's access check closes the socket with 4000 plus the
+    status (4403, 4422). A 404 can be a thread the client minted and has yet
+    to create, so the socket then waits for a ``run.start``, which checks
+    access like any run start, and closes with 4404 if another command comes
+    first. Any other failure of the check, a 5xx included, gets the stream
+    error frame and a 1011 close, as when the stream fails later.
     """
     thread_id = websocket.path_params["thread_id"]
+    # Browsers report a refused upgrade only as a 1006 close, so accept first
+    # to make the close code readable.
     await websocket.accept()
+    try:
+        thread_uuid = validate_uuid(thread_id, "Invalid thread ID: must be a UUID")
+    except HTTPException as exc:
+        await _close_for_failed_access_check(websocket, exc)
+        return
+    awaiting_thread = False
+    auth_filters: Any = None
+    try:
+        auth_filters = await Threads.Stream.check_thread_stream_auth(thread_uuid)
+    except Exception as exc:
+        if not (isinstance(exc, HTTPException) and exc.status_code == 404):
+            await _close_for_failed_access_check(websocket, exc)
+            return
+        awaiting_thread = True
 
     async def ws_send_event(event: dict[str, Any]) -> None:
         await websocket.send_text(orjson.dumps(event).decode("utf-8"))
 
     manager = _make_manager(thread_id, send_event=ws_send_event)
-    manager.start_thread_stream()
 
     # Watchdog: when the thread-stream consumer stops, send the error frame
     # (if it wasn't cancelled) and close the socket, instead of leaving the
@@ -405,7 +451,11 @@ async def _thread_websocket(websocket: WebSocket) -> None:
         with contextlib.suppress(Exception):
             await websocket.close(code=1011, reason="thread stream ended")
 
-    watchdog = asyncio.create_task(_stream_watchdog())
+    def start_stream(filters: Any) -> asyncio.Task[None]:
+        manager.start_thread_stream(auth_filters=filters)
+        return asyncio.create_task(_stream_watchdog())
+
+    watchdog = None if awaiting_thread else start_stream(auth_filters)
 
     try:
         while True:
@@ -438,16 +488,30 @@ async def _thread_websocket(websocket: WebSocket) -> None:
                 )
                 continue
 
+            if awaiting_thread and payload["method"] != "run.start":
+                await websocket.close(code=4404)
+                return
             response = await manager.handle_command(payload)
             await websocket.send_text(orjson.dumps(response).decode("utf-8"))
+            if awaiting_thread and response.get("type") == "success":
+                try:
+                    auth_filters = await Threads.Stream.check_thread_stream_auth(
+                        thread_uuid
+                    )
+                except Exception as exc:
+                    await _close_for_failed_access_check(websocket, exc)
+                    return
+                watchdog = start_stream(auth_filters)
+                awaiting_thread = False
     except WebSocketDisconnect:
         pass
     except Exception:
         logger.exception("Protocol WebSocket error")
     finally:
-        watchdog.cancel()
-        with contextlib.suppress(asyncio.CancelledError, Exception):
-            await watchdog
+        if watchdog is not None:
+            watchdog.cancel()
+            with contextlib.suppress(asyncio.CancelledError, Exception):
+                await watchdog
         await manager.close()
 
 

{langgraph_api-0.18.0.dev3 → langgraph_api-0.18.0.dev4}/langgraph_api/config/__init__.py

@@ -507,7 +507,8 @@ FF_CRONS_ENABLED = env("FF_CRONS_ENABLED", cast=bool, default=True)
 FF_LOG_DROPPED_EVENTS = env("FF_LOG_DROPPED_EVENTS", cast=bool, default=False)
 FF_LOG_QUERY_AND_PARAMS = env("FF_LOG_QUERY_AND_PARAMS", cast=bool, default=False)
 # Opt-in handling of drained runs: the server's control signalling to the
-# graph and its handling of drained runs, together.
+# graph and its handling of drained runs, together. On, a Postgres-backed
+# replica that is shutting down also drains its in-flight runs.
 # Off: no control is created or seeded, and GraphDrained lands in the
 # catch-all error branch.
 FF_RESUME_DRAINED_RUNS = env("FF_RESUME_DRAINED_RUNS", cast=bool, default=False)
@@ -535,8 +536,6 @@ RESUME_DRAINED_RUNS = _resolve_resume_drained_runs(
     is_postgres=IS_POSTGRES_BACKEND,
     langgraph_supported=DRAIN_RESUME_SUPPORT,
 )
-# Not in public docs: internal feature flag
-FF_USE_REDIS_QUEUE = env("FF_USE_REDIS_QUEUE", cast=bool, default=True)
 
 
 # Internal flag intended for testing only
@@ -811,7 +810,6 @@ __all__ = [
     "FF_PYSPY_PROFILING_ENABLED",
     "FF_PYSPY_PROFILING_MAX_DURATION_SECS",
     "FF_RESUME_DRAINED_RUNS",
-    "FF_USE_REDIS_QUEUE",
     "GRPC_CLIENT_HTTP2_INITIAL_WINDOW_SIZE",
     "GRPC_CLIENT_MAX_RECV_MSG_BYTES",
     "GRPC_CLIENT_MAX_SEND_MSG_BYTES",

{langgraph_api-0.18.0.dev3 → langgraph_api-0.18.0.dev4}/langgraph_api/drain.py

@@ -10,6 +10,7 @@ guarded and the placeholders below never match or instantiate anything.
 from __future__ import annotations
 
 import contextvars
+import threading
 from typing import Any
 
 # The control of the run whose top-level graph this context is executing. The
@@ -47,17 +48,35 @@ try:
         The request is visible only where this is provably the run's top-level
         loop: in a context the server marked for this control (see
         mark_top_level) and outside any graph node. So the run drains only at
-        a top-level step boundary, after that step's subgraphs have finished.
+        a top-level step boundary, after that step's subgraphs have finished,
+        and never before its first step.
         Graph code inside a node, and threads a node starts, see no drain
         (drain_requested False, drain_reason None).
         """
 
+        __slots__ = ("_first_check_done",)
+
+        def __init__(self) -> None:
+            super().__init__()
+            self._first_check_done = False
+
         def _visible(self) -> bool:
             return _TOP_LEVEL_CONTROL.get() is self and not _in_graph_node()
 
         @property
         def drain_requested(self) -> bool:
-            return self._visible() and RunControl.drain_requested.fget(self)
+            if not self._visible():
+                return False
+            # LangGraph checks once per top-level step boundary, before the
+            # step. Only a server drain can be pending at the first check. A
+            # run started with a Command has no checkpoint of its own until its
+            # first step ends, so if it drained there, its next claim would
+            # re-send the Command and LangGraph would apply it again. So a run
+            # always completes a step before it drains.
+            if not self._first_check_done:
+                self._first_check_done = True
+                return False
+            return RunControl.drain_requested.fget(self)
 
         @property
         def drain_reason(self) -> str | None:
@@ -79,6 +98,11 @@ except ImportError:
 
     DRAIN_SUPPORT = False
 
+# Reason the server passes to request_drain() when its pod is shutting down.
+# Graph code can pass any reason (request_drain() defaults to "shutdown"), so
+# this distinct value is what tells server drains from graph drains in logs.
+SERVER_SHUTDOWN_DRAIN_REASON = "server_shutdown"
+
 
 def mark_top_level(control: ServerRunControl | None) -> None:
     """Mark the current context as running ``control``'s top-level graph."""
@@ -92,10 +116,48 @@ def new_run_control() -> ServerRunControl | None:
     return None
 
 
+class RunControlRegistry:
+    """Controls of the runs a queue drains at shutdown, keyed by run ID.
+
+    Workers can finish on background threads (isolated loops), so every access
+    takes a lock and ``drain_all`` works on a snapshot. Controls are registered
+    before the run starts, and removed only by the claim that registered them,
+    so a fast-finishing or superseded claim can't leave or remove the wrong
+    entry.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._controls: dict[str, ServerRunControl] = {}
+
+    def add(self, run_id: Any, control: ServerRunControl) -> None:
+        """Register a run's control before the run starts."""
+        with self._lock:
+            self._controls[str(run_id)] = control
+
+    def release(self, run_id: Any, control: ServerRunControl | None) -> None:
+        """Remove a run's control if it is still the one this claim registered."""
+        if control is None:
+            return
+        with self._lock:
+            if self._controls.get(str(run_id)) is control:
+                del self._controls[str(run_id)]
+
+    def drain_all(self, reason: str) -> int:
+        """Request a drain from every registered run; return how many."""
+        with self._lock:
+            controls = list(self._controls.values())
+        for control in controls:
+            control.request_drain(reason)
+        return len(controls)
+
+
 __all__ = [
     "DRAIN_SUPPORT",
+    "SERVER_SHUTDOWN_DRAIN_REASON",
     "GraphDrained",
     "RunControl",
+    "RunControlRegistry",
     "ServerRunControl",
     "mark_top_level",
     "new_run_control",

{langgraph_api-0.18.0.dev3 → langgraph_api-0.18.0.dev4}/langgraph_api/event_streaming/service.py

@@ -22,7 +22,6 @@ import asyncio
 import contextlib
 import inspect
 import re
-import time
 from collections.abc import Awaitable, Callable, Mapping
 from typing import Any, cast, get_args
 from uuid import UUID, uuid4
@@ -46,6 +45,7 @@ from langgraph_api.event_streaming.session import (
 from langgraph_api.event_streaming.types import Subscription
 from langgraph_api.feature_flags import FF_V2_EVENT_STREAMING, PREFER_GRPC_CHECKPOINTER
 from langgraph_api.schema import MultitaskStrategy
+from langgraph_api.validation import sanitize_reserved_keys
 
 logger = structlog.stdlib.get_logger(__name__)
 
@@ -145,10 +145,7 @@ 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
 # langgraph resumes interrupts by id only when every key of the resume map has
 # this shape; any other key turns the whole map into one value for whichever
 # interrupt is pending.
@@ -192,6 +189,9 @@ class ThreadRunManager:
     One ``ThreadRunManager`` is created per connection (HTTP SSE stream or
     WebSocket). It is not shared across connections — each observer owns
     its own view of the thread's run stream.
+
+    ``replay_buffer=False`` keeps no per-run replay buffer, for connections
+    that never replay from it.
     """
 
     def __init__(
@@ -202,12 +202,14 @@ class ThreadRunManager:
         threads: Any,
         send_event: EventSink | None = None,
         headers: Mapping[str, str] | None = None,
+        replay_buffer: bool = True,
     ) -> None:
         self._thread_id = thread_id
         self._runs = runs
         self._threads = threads
         self._send_event = send_event
         self._headers = headers if headers is not None else {}
+        self._replay_buffer = replay_buffer
         self._session: EventStreamingSession | None = None
         self._current_run_id: str | None = None
         self._queued_events: list[dict[str, Any]] = []
@@ -291,7 +293,7 @@ class ThreadRunManager:
                 active=True,
             )
 
-    def start_thread_stream(self) -> None:
+    def start_thread_stream(self, *, auth_filters: Any = None) -> None:
         """Start consuming the thread-level stream for this connection.
 
         Always start from the beginning of the thread's event stream
@@ -306,14 +308,19 @@ class ThreadRunManager:
         produce output…". The SSE/WS sink applies the caller's ``since``
         as a seq filter on outbound events, and the SDK dedups by
         ``event_id``, so repeat observers don't see duplicates.
+
+        ``auth_filters`` is what the route's ``check_thread_stream_auth``
+        returned, passed on so the stream doesn't run the read handler again.
         """
         if self._thread_source_task is not None:
             return
         self._thread_source_task = asyncio.create_task(
-            self._consume_thread_stream(last_event_id="-")
+            self._consume_thread_stream(last_event_id="-", auth_filters=auth_filters)
         )
 
-    async def _consume_thread_stream(self, *, last_event_id: str | None) -> None:
+    async def _consume_thread_stream(
+        self, *, last_event_id: str | None, auth_filters: Any
+    ) -> None:
         try:
             async for (
                 event,
@@ -324,6 +331,7 @@ class ThreadRunManager:
                 self._thread_id,
                 stream_modes=["run_modes", "lifecycle"],
                 last_event_id=last_event_id,
+                auth_filters=auth_filters,
             ):
                 if not run_id or run_id == "*":
                     continue
@@ -781,40 +789,15 @@ class ThreadRunManager:
         if not capabilities.ok:
             raise ProtocolV2UnsupportedError(capabilities)
 
+        # Drop server-owned configurable and metadata keys before the run
+        # config is built, as the REST request parser does for its bodies.
+        sanitize_reserved_keys(params)
         config = params.get("config") if _is_record(params.get("config")) else {}
 
-        # ``input.respond`` checked its interrupts already and always resumes;
-        # the lookups below can wait seconds on a busy thread.
-        force_resume = params.get("force_resume")
-        current_run = None if force_resume else await self._fetch_current_run()
-
-        current_status = None
-        if current_run is not None:
-            current_status = (
-                current_run["status"]
-                if _is_record(current_run)
-                else getattr(current_run, "status", None)
-            )
-
-        has_interrupts = False
-        if params.get("input") is not None and not force_resume:
-            has_interrupts = await self._has_pending_interrupts()
-        if has_interrupts and not _keyed_by_interrupt_id(params["input"]):
-            # One answer can't say which of several pending interrupts it is
-            # for: langgraph fails the run, or picks one when they share a
-            # subgraph task. Only a paused thread's row is current, so a run in
-            # flight keeps resuming as before.
-            paused_on = await self._collect_interrupt_ids_unless_busy()
-            if paused_on is not None and len(paused_on) > 1:
-                raise _AmbiguousResumeError(
-                    f"run.start input can't say which of the {len(paused_on)} "
-                    "pending interrupts it answers; answer them with input.respond."
-                )
-
+        # ``input.respond`` checked its interrupts already and always resumes.
         is_resume = params.get("input") is not None and (
-            force_resume
-            or (current_run is not None and current_status == "interrupted")
-            or has_interrupts
+            bool(params.get("force_resume"))
+            or await self._run_start_resumes(params["input"])
         )
 
         run_config: dict[str, Any] = {
@@ -903,6 +886,16 @@ class ThreadRunManager:
         except Exception:
             raise
 
+        # ``input.respond`` clears the interrupts it answered itself.
+        if is_resume and not params.get("force_resume") and self._session is not None:
+            # Until the stream rebinds to the resumed run, input sent next must
+            # not answer these interrupts a second time.
+            answered = params["input"]
+            if _keyed_by_interrupt_id(answered):
+                for interrupt_id in answered:
+                    self._session.clear_pending_interrupt(interrupt_id)
+            else:
+                self._session._pending_interrupts.clear()
         return run
 
     async def _ensure_run_session(
@@ -959,6 +952,7 @@ class ThreadRunManager:
             get_thread_state=self._make_get_thread_state(thread_id),
             source=None,
             send=self._make_send(),
+            max_buffer_size=None if self._replay_buffer else 0,
         )
 
         self._session = session
@@ -1086,19 +1080,6 @@ class ThreadRunManager:
     # Run lookup
     # ------------------------------------------------------------------
 
-    async def _fetch_current_run(self) -> dict[str, Any] | None:
-        """Fetch the currently-bound run from storage.
-
-        ``Runs.get`` uses keyword-only ``thread_id`` / ``ctx`` args so we
-        cannot call it positionally. We also rely on ``ApiRoute``'s
-        ``with_user`` to populate the auth context var instead of
-        passing ``ctx=self._auth`` (which is a starlette
-        ``AuthCredentials``, not a ``BaseAuthContext``).
-        """
-        if self._current_run_id is None:
-            return None
-        return await self._fetch_run_by_id(self._current_run_id)
-
     async def _fetch_run_by_id(self, run_id: str) -> dict[str, Any] | None:
         """Fetch a run by id without searching for the latest run."""
         from langgraph_runtime.database import connect  # noqa: PLC0415
@@ -1127,41 +1108,6 @@ class ThreadRunManager:
     # Interrupt detection
     # ------------------------------------------------------------------
 
-    async def _lookup_interrupt_in_thread_state(
-        self, interrupt_id: str
-    ) -> list[str] | None:
-        """Existence check for ``interrupt_id`` against persisted thread state.
-
-        Fallback for ``input.respond`` on stateless HTTP transports, where the
-        fresh session hasn't observed ``input.requested`` yet. Backed by the
-        durable thread-row map (see :meth:`_collect_persisted_interrupt_ids`).
-
-        Returns ``[]`` if the interrupt exists, else ``None``. The ``[]`` is a
-        sentinel, not a namespace — the map carries no namespace, so callers
-        must treat it as "found, namespace unknown" and trust the client claim.
-        """
-        found = await self._collect_persisted_interrupt_ids()
-        if found is None:
-            return None
-        return [] if interrupt_id in found else None
-
-    async def _collect_persisted_interrupt_ids(self) -> set[str] | None:
-        """Collect interrupt ids from the durable thread-row ``interrupts`` map.
-
-        ``Threads.set_status`` writes ``{task_id: [{id, value}, ...]}`` onto the
-        thread row atomically with the status whenever a run pauses. Reading it
-        is a plain row fetch (same ``connect()`` + ``Threads.get`` path as
-        :meth:`_get_thread_assistant_id`) — unlike ``Threads.State.get`` it does
-        not rebuild the graph, so it can't spuriously raise and reject a
-        legitimate resume, and it survives reconnects/redeploys.
-
-        Returns the set of interrupt ids (empty when none are pending), or
-        ``None`` if the fetch failed — callers treat ``None`` as "unavailable"
-        and fall open rather than fabricating ``no_such_interrupt``.
-        """
-        thread = await self._fetch_thread_row()
-        return None if thread is None else self._interrupt_ids(thread)
-
     async def _fetch_thread_row(self) -> dict[str, Any] | None:
         """Return the durable thread row, or ``None`` if the fetch failed."""
         from langgraph_runtime.database import connect  # noqa: PLC0415
@@ -1182,6 +1128,11 @@ class ThreadRunManager:
 
     @staticmethod
     def _interrupt_ids(thread: dict[str, Any]) -> set[str]:
+        """Ids in the row's ``interrupts`` map, written with the status when a run ends.
+
+        Read instead of ``Threads.State.get``, which rebuilds the graph and can
+        raise, turning a valid answer into ``no_such_interrupt``.
+        """
         interrupts_map = thread.get("interrupts")
         if not _is_record(interrupts_map):
             return set()
@@ -1197,40 +1148,6 @@ 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 _collect_interrupt_ids_unless_busy(self) -> set[str] | None:
         """Persisted interrupt ids, or ``None`` while a run is in flight.
 
@@ -1247,16 +1164,45 @@ class ThreadRunManager:
             return None
         return self._interrupt_ids(thread)
 
-    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;
-        # otherwise consult the durable thread-row map. A lookup failure
-        # (``None``) reads as "none pending" — ``run.start`` then falls back to
-        # the ``current_status == "interrupted"`` signal for resume-vs-start.
-        if self._session is not None and self._session._pending_interrupts:
+    async def _run_start_resumes(self, value: Any) -> bool:
+        """Whether ``run.start`` input answers the interrupts the thread is paused on.
+
+        Decided without waiting, from one read of the thread row. Interrupts
+        reach the row only when their run ends, so while a run is in flight the
+        input is a new run for the multitask strategy (``enqueue``, the default,
+        queues it behind the running one), never an answer for whichever
+        interrupt is open when that run pauses. The exception is the run this
+        connection streams: the session reports it ``interrupted`` as soon as it
+        raises an interrupt, so input sent after that answers the streamed
+        interrupts, until this connection resumes them or that run ends. When
+        the row can't be read, the streamed interrupts decide. The last run's
+        status isn't consulted: a run that pauses on an interrupt ends
+        ``success``, and ``interrupted`` means it was cancelled; any interrupt it
+        left open is in the row.
+
+        Raises ``_AmbiguousResumeError`` when the input would answer several
+        interrupts and isn't keyed by interrupt id.
+        """
+        if _keyed_by_interrupt_id(value):
             return True
-        found = await self._collect_settled_interrupt_ids()
-        return bool(found)
+        session = self._session
+        streamed = set(session._pending_interrupts) if session is not None else set()
+        thread = await self._fetch_thread_row()
+        if thread is None:
+            paused_on = streamed
+        elif thread.get("status") == _IN_FLIGHT_THREAD_STATUS:
+            paused_on = set() if session is None or session.run_done else streamed
+        else:
+            paused_on = self._interrupt_ids(thread)
+        if len(paused_on) > 1:
+            # One answer can't say which of several pending interrupts it is
+            # for: langgraph fails the run, or picks one when they share a
+            # subgraph task.
+            raise _AmbiguousResumeError(
+                f"run.start input can't say which of the {len(paused_on)} "
+                "pending interrupts it answers; answer them with input.respond."
+            )
+        return bool(paused_on)
 
     # ------------------------------------------------------------------
     # Command forwarding