langgraph-api 0.18.0.dev5__tar.gz → 0.18.0.dev7__tar.gz

{langgraph_api-0.18.0.dev5 → langgraph_api-0.18.0.dev7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langgraph-api
-Version: 0.18.0.dev5
+Version: 0.18.0.dev7
 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.dev5 → langgraph_api-0.18.0.dev7}/benchmark/package.json

@@ -15,7 +15,7 @@
   },
   "devDependencies": {
     "@types/k6": "^2.0.0",
-    "typescript": "^5.9.3"
+    "typescript": "^6.0.3"
   },
   "overrides": {
     "body-parser": "1.20.8",

{langgraph_api-0.18.0.dev5 → langgraph_api-0.18.0.dev7}/benchmark/yarn.lock

@@ -493,9 +493,9 @@ path-to-regexp@~0.1.13:
   integrity sha512-A/AGNMFN3c8bOlvV9RreMdrv7jsmF9XIfDeCd87+I8RNg6s78BhJxMu69NEMHBSJFxKidViTEdruRwEk/WIKqA==
 
 proxy-addr@~2.0.7:
-  version "2.0.7"
-  resolved "https://registry.yarnpkg.com/proxy-addr/-/proxy-addr-2.0.7.tgz#f19fe69ceab311eeb94b42e70e8c2070f9ba1025"
-  integrity sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg==
+  version "2.0.8"
+  resolved "https://registry.yarnpkg.com/proxy-addr/-/proxy-addr-2.0.8.tgz#624e760fd8ab06b1b8320c2f8506d4422cf8e932"
+  integrity sha512-5nnx0yGyVUcY6t9RnWcARWtwT9F1D8O9rt08htPvnd49W1IgZtmLkhu9WfMzQj1cFxjHIO6connUNVW5k7AVyQ==
   dependencies:
     forwarded "0.2.0"
     ipaddr.js "1.9.1"
@@ -670,10 +670,10 @@ type-is@^1.6.18, type-is@~1.6.18:
     media-typer "0.3.0"
     mime-types "~2.1.24"
 
-typescript@^5.9.3:
-  version "5.9.3"
-  resolved "https://registry.yarnpkg.com/typescript/-/typescript-5.9.3.tgz#5b4f59e15310ab17a216f5d6cf53ee476ede670f"
-  integrity sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==
+typescript@^6.0.3:
+  version "6.0.3"
+  resolved "https://registry.yarnpkg.com/typescript/-/typescript-6.0.3.tgz#90251dc007916e972786cb94d74d15b185577d21"
+  integrity sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw==
 
 undici-types@~8.3.0:
   version "8.3.0"

langgraph_api-0.18.0.dev7/langgraph_api/__init__.py

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

{langgraph_api-0.18.0.dev5 → langgraph_api-0.18.0.dev7}/langgraph_api/api/threads.py

@@ -1,9 +1,11 @@
-from typing import get_args
+from contextlib import aclosing
+from typing import TYPE_CHECKING, Any, get_args
 
 from starlette.exceptions import HTTPException
 from starlette.responses import Response
 from starlette.routing import BaseRoute
 
+from langgraph_api import config as lg_api_config
 from langgraph_api.config import USE_CUSTOM_CHECKPOINTER
 from langgraph_api.encryption.shared import (
     using_encryption,
@@ -14,6 +16,7 @@ from langgraph_api.feature_flags import (
 )
 from langgraph_api.route import ApiRequest, ApiResponse, ApiRoute
 from langgraph_api.schema import THREAD_FIELDS, ThreadStreamMode
+from langgraph_api.serde import Fragment, json_dumpb
 from langgraph_api.sse import EventSourceResponse
 from langgraph_api.state import state_snapshot_to_thread_state
 from langgraph_api.utils import (
@@ -44,6 +47,11 @@ if IS_POSTGRES_OR_GRPC_BACKEND:
 else:
     from langgraph_runtime.ops import Threads
 
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+    from langgraph.types import StateSnapshot
+
 
 @retry_db
 async def create_thread(
@@ -320,14 +328,7 @@ async def get_thread_history(
             **get_configurable_headers(request.headers),
         }
     }
-    async with connect(supports_core_api=PREFER_GRPC_CHECKPOINTER) as conn:
-        states = [
-            state_snapshot_to_thread_state(c)
-            for c in await Threads.State.list(
-                conn, config=config, limit=limit, before=before
-            )
-        ]
-    return ApiResponse(states)
+    return await _history_response(config=config, limit=limit, before=before)
 
 
 @retry_db
@@ -342,18 +343,65 @@ async def get_thread_history_post(
     config["configurable"].update(payload.get("checkpoint", {}))
     config["configurable"].update(get_configurable_headers(request.headers))
     config["configurable"]["thread_id"] = thread_id
+    return await _history_response(
+        config=config,
+        limit=int(payload.get("limit") or 1),
+        before=payload.get("before"),
+        metadata=payload.get("metadata"),
+    )
+
+
+async def _history_response(**kwargs: Any) -> ApiResponse:
+    budget = lg_api_config.THREAD_HISTORY_MAX_STATE_BYTES
     async with connect(supports_core_api=PREFER_GRPC_CHECKPOINTER) as conn:
-        states = [
-            state_snapshot_to_thread_state(c)
-            for c in await Threads.State.list(
-                conn,
-                config=config,
-                limit=int(payload.get("limit") or 1),
-                before=payload.get("before"),
-                metadata=payload.get("metadata"),
-            )
-        ]
-    return ApiResponse(states)
+        entries = await _serialize_history(
+            _history_states(conn, incremental=bool(budget), **kwargs),
+            budget=budget,
+        )
+    return ApiResponse(entries)
+
+
+def _history_states(
+    conn: Any, *, incremental: bool, **kwargs: Any
+) -> "AsyncIterator[StateSnapshot]":
+    if hasattr(Threads.State, "iterate"):
+        return Threads.State.iterate(conn, incremental=incremental, **kwargs)
+    # langgraph-runtime-inmem releases before ``iterate`` only have ``list``.
+    return _listed_history_states(conn, **kwargs)
+
+
+async def _listed_history_states(
+    conn: Any, **kwargs: Any
+) -> "AsyncIterator[StateSnapshot]":
+    for state in await Threads.State.list(conn, **kwargs):
+        yield state
+
+
+async def _serialize_history(
+    states: "AsyncIterator[StateSnapshot]", *, budget: int
+) -> list[Fragment]:
+    """Serialize history entries until they reach ``budget`` bytes (0: no limit).
+
+    The newest entry is always returned. Each later entry is returned only if
+    the response stays within the budget, and history stops at the first one
+    that does not.
+    """
+    entries: list[Fragment] = []
+    total_bytes = 1  # the response array's opening bracket
+    async with aclosing(states):
+        async for state in states:
+            entry = json_dumpb(state_snapshot_to_thread_state(state))
+            # Drop the decoded state before the next checkpoint loads.
+            del state
+            # Each entry also adds a comma or the closing bracket.
+            total_bytes += len(entry) + 1
+            if budget and entries and total_bytes > budget:
+                break
+            entries.append(Fragment(entry))
+            if budget and total_bytes >= budget:
+                # Nothing more can fit, so don't load another checkpoint.
+                break
+    return entries
 
 
 @retry_db

{langgraph_api-0.18.0.dev5 → langgraph_api-0.18.0.dev7}/langgraph_api/config/__init__.py

@@ -240,6 +240,23 @@ HTTP_MAX_REQUEST_BODY_BYTES = env(
     "HTTP_MAX_REQUEST_BODY_BYTES", cast=int, default=300 * 1024 * 1024
 )
 
+
+def _validate_thread_history_budget(budget: int) -> int:
+    if budget < 0:
+        raise ValueError(
+            "LANGGRAPH_THREAD_HISTORY_MAX_STATE_BYTES must be 0 (disabled) or a "
+            f"positive number of bytes, got {budget}."
+        )
+    return budget
+
+
+# Byte budget for one history response, counted as the serialized size of its
+# entries; every entry carries the full thread state. History stops before the
+# entry that would cross it but always returns the newest. 0 disables it.
+THREAD_HISTORY_MAX_STATE_BYTES = _validate_thread_history_budget(
+    env("LANGGRAPH_THREAD_HISTORY_MAX_STATE_BYTES", cast=int, default=0)
+)
+
 # gRPC message size limits (300MB default)
 # Not in public docs: infrastructure, set by platform
 LSD_GRPC_SERVER_MAX_RECV_MSG_BYTES = env(
@@ -565,6 +582,7 @@ LANGGRAPH_ENCRYPTION = env(
 )
 # Not in public docs: set by SaaS control plane, not user-configurable
 LANGSMITH_TENANT_ID = env("LANGSMITH_TENANT_ID", cast=str, default=None)
+LANGSMITH_HOST_PROJECT_ID = env("LANGSMITH_HOST_PROJECT_ID", cast=str, default=None)
 LANGSMITH_AUTH_VERIFY_TENANT_ID = env(
     "LANGSMITH_AUTH_VERIFY_TENANT_ID",
     cast=bool,
@@ -870,6 +888,7 @@ __all__ = [
     "STREAM_PUBLISH_RETRY_JITTER",
     "STREAM_PUBLISH_RETRY_MAX_DURATION_SECS",
     "STREAM_PUBLISH_RETRY_MAX_INTERVAL_SECS",
+    "THREAD_HISTORY_MAX_STATE_BYTES",
     "THREAD_TTL",
     "TRACING",
     "UI_USE_BUNDLER",

{langgraph_api-0.18.0.dev5 → langgraph_api-0.18.0.dev7}/langgraph_api/errors.py

@@ -1,5 +1,6 @@
 import jsonschema_rs
 import structlog
+from langgraph.errors import EmptyInputError, InvalidUpdateError
 from starlette.exceptions import HTTPException
 from starlette.requests import Request
 from starlette.responses import JSONResponse, Response
@@ -63,6 +64,21 @@ async def overloaded_error_handler(request, exc: ValueError):
     )
 
 
+def app_exception_handlers() -> dict:
+    """The exception handlers shared by the server app and the operator routes."""
+    # Imported here because the runtime imports this module while it loads.
+    from langgraph_runtime.retry import OVERLOADED_EXCEPTIONS  # noqa: PLC0415
+
+    return {
+        HTTPException: http_exception_handler,
+        ValueError: value_error_handler,
+        InvalidUpdateError: value_error_handler,
+        EmptyInputError: value_error_handler,
+        jsonschema_rs.ValidationError: validation_error_handler,
+        RemoteException: remote_exception_handler,
+    } | {exc: overloaded_error_handler for exc in OVERLOADED_EXCEPTIONS}
+
+
 class UserInterrupt(Exception):
     def __init__(self, message="User interrupted the run"):
         super().__init__(message)

{langgraph_api-0.18.0.dev5 → langgraph_api-0.18.0.dev7}/langgraph_api/grpc/ops/runs.py

@@ -71,6 +71,7 @@ from langgraph_api.utils import get_auth_ctx
 
 if TYPE_CHECKING:
     from collections.abc import AsyncIterator, Sequence
+    from datetime import datetime
 
     from langgraph_api.schema import (
         IfNotExists,
@@ -79,6 +80,7 @@ if TYPE_CHECKING:
         PoolStats,
         QueueStats,
         Run,
+        RunCancelProgress,
         RunSelectField,
         RunStatus,
     )
@@ -755,6 +757,25 @@ class Runs(Authenticated):
         client = await get_shared_client()
         await client.runs.Cancel(pb.CancelRunRequest(**request_kwargs))
 
+    @staticmethod
+    async def cancel_accepted_before(
+        conn,
+        accepted_before: datetime,
+        *,
+        reason: str,
+    ) -> RunCancelProgress:
+        """Applies no auth filters, so only the operator route may call it."""
+        client = await get_shared_client()
+        response = await client.runs.CancelAcceptedBefore(
+            pb.CancelAcceptedBeforeRequest(
+                accepted_before=accepted_before, reason=reason
+            )
+        )
+        return {
+            "not_yet_reached": response.not_yet_reached,
+            "finishing": response.finishing,
+        }
+
     @staticmethod
     async def stats(conn) -> QueueStats:
         """Get queue statistics (not exposed via API, no auth)."""

{langgraph_api-0.18.0.dev5 → langgraph_api-0.18.0.dev7}/langgraph_api/grpc/ops/threads.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import asyncio
-from contextlib import AsyncExitStack
+from contextlib import AsyncExitStack, aclosing
 from datetime import UTC
 from http import HTTPStatus
 from typing import TYPE_CHECKING, Any, Literal
@@ -46,7 +46,11 @@ from langgraph_api.grpc.ops import (
 from langgraph_api.grpc.ops.runs import Runs
 from langgraph_api.schema import ThreadUpdateResponse
 from langgraph_api.serde import json_dumpb, json_dumpb_optional, json_loads
-from langgraph_api.state import patch_interrupt, state_snapshot_to_thread_state
+from langgraph_api.state import (
+    iter_state_history,
+    patch_interrupt,
+    state_snapshot_to_thread_state,
+)
 from langgraph_api.utils import fetchone
 
 if TYPE_CHECKING:
@@ -1330,7 +1334,7 @@ class Threads(Authenticated):
                 )
 
         @staticmethod
-        async def list(
+        async def iterate(
             conn,  # Still needed for checkpointer
             *,
             config: dict[str, Any],
@@ -1338,8 +1342,13 @@ class Threads(Authenticated):
             before: Any = None,
             metadata: Any = None,
             ctx: Any = None,
-        ) -> list[StateSnapshot]:
-            """Get the history of a thread."""
+            incremental: bool = False,
+        ) -> AsyncIterator[StateSnapshot]:
+            """Yield the history of a thread.
+
+            With ``incremental``, checkpoints load in growing pages, so a
+            caller that stops early does not load the rest of ``limit``.
+            """
             async with conn.pipeline():
                 thread, graph_id = await asyncio.gather(
                     Threads.get(
@@ -1372,18 +1381,26 @@ class Threads(Authenticated):
                     store=(await api_store.get_store()),
                     access_context="threads.read",
                 ) as graph:
-                    return [
-                        c
-                        async for c in graph.aget_state_history(
+                    before_config = (
+                        {"configurable": {"checkpoint_id": before}}
+                        if isinstance(before, str)
+                        else before
+                    )
+                    history = (
+                        iter_state_history(
+                            graph,
                             config,
                             limit=limit,
                             filter=metadata,
-                            before=(
-                                {"configurable": {"checkpoint_id": before}}
-                                if isinstance(before, str)
-                                else before
-                            ),
+                            before=before_config,
                         )
-                    ]
-            else:
-                return []
+                        if incremental
+                        else graph.aget_state_history(
+                            config, limit=limit, filter=metadata, before=before_config
+                        )
+                    )
+                    async with aclosing(history) as states:
+                        async for c in states:
+                            yield c
+                            # Drop the entry before the next page loads.
+                            del c

{langgraph_api-0.18.0.dev5 → langgraph_api-0.18.0.dev7}/langgraph_api/js/package.json

@@ -20,7 +20,7 @@
     "hono": "^4.13.7",
     "p-queue": "^9.3.1",
     "p-retry": "^7.1.1",
-    "typescript": "^5.9.3",
+    "typescript": "^6.0.3",
     "undici": "^7.29.1",
     "uuid": "^14.0.1",
     "winston": "^3.19.0",

{langgraph_api-0.18.0.dev5 → langgraph_api-0.18.0.dev7}/langgraph_api/js/yarn.lock

@@ -1506,9 +1506,9 @@ postcss-modules@^6.0.1:
     string-hash "^1.1.3"
 
 postcss-selector-parser@^7.0.0:
-  version "7.1.5"
-  resolved "https://registry.yarnpkg.com/postcss-selector-parser/-/postcss-selector-parser-7.1.5.tgz#ee7b090724eb60739b530660e5b402200e694a97"
-  integrity sha512-KvvtD7SrlBP7dlgkBghEE3r84CABm5SmV2aNcG4oCA+qDnJ/tvKonFVvwWAyyWUEwxuNawdfEAZKP9zM3oZ2Uw==
+  version "7.1.6"
+  resolved "https://registry.yarnpkg.com/postcss-selector-parser/-/postcss-selector-parser-7.1.6.tgz#45e970f2d93d4547d6754167ed1132f43012c4bf"
+  integrity sha512-7qASPzhKF2l2KLboRZux8CCTRMdGiV08vWmyKzPz22qZ7ZjQBOeY7rNzNoCLSUiftJ7HUq0GERHmxw/t0dCdMw==
   dependencies:
     cssesc "^3.0.0"
     util-deprecate "^1.0.2"
@@ -1630,9 +1630,9 @@ siginfo@^2.0.0:
   integrity sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==
 
 source-map-js@^1.2.1:
-  version "1.2.1"
-  resolved "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz"
-  integrity sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==
+  version "1.2.2"
+  resolved "https://registry.yarnpkg.com/source-map-js/-/source-map-js-1.2.2.tgz#79fb88d97535a21cb27162cb05d211b67acea4ab"
+  integrity sha512-KGj/8Y43x35aZVDtt+J4mK1hoLGHULMYfSkODJNQjNDC3oW1PqPoxMwo0pLUsWM/UEGzON/NxeHywEfNXNP3Vw==
 
 stack-trace@0.0.x:
   version "0.0.10"
@@ -1732,10 +1732,10 @@ type-fest@^0.7.1:
   resolved "https://registry.npmjs.org/type-fest/-/type-fest-0.7.1.tgz"
   integrity sha512-Ne2YiiGN8bmrmJJEuTWTLJR32nh/JdL1+PSicowtNb0WFpn59GK8/lfD61bVtzguz7b3PBt74nxpv/Pw5po5Rg==
 
-typescript@^5.9.3:
-  version "5.9.3"
-  resolved "https://registry.yarnpkg.com/typescript/-/typescript-5.9.3.tgz#5b4f59e15310ab17a216f5d6cf53ee476ede670f"
-  integrity sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==
+typescript@^6.0.3:
+  version "6.0.3"
+  resolved "https://registry.yarnpkg.com/typescript/-/typescript-6.0.3.tgz#90251dc007916e972786cb94d74d15b185577d21"
+  integrity sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw==
 
 undici-types@~8.3.0:
   version "8.3.0"

langgraph_api-0.18.0.dev7/langgraph_api/operator_routes.py

@@ -0,0 +1,223 @@
+"""Operator routes: deployment-wide actions a LangSmith admin can take on a deployment.
+
+They are served before every other middleware, so customer middleware and custom
+auth handlers can't block or filter them. Instead, host-backend checks the admin's
+permission and calls them with a short-lived service token scoped to one operation on
+this deployment, which LangSmith verifies. See THREAT_MODEL.md.
+"""
+
+from __future__ import annotations
+
+import contextlib
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from typing import TYPE_CHECKING, Any
+from uuid import UUID
+
+import httpx
+import structlog
+from starlette.applications import Starlette
+from starlette.exceptions import HTTPException
+from starlette.responses import JSONResponse, Response
+from starlette.routing import Route
+
+from langgraph_api import config
+from langgraph_api.auth.langsmith.client import create_client
+from langgraph_api.errors import app_exception_handlers
+from langgraph_api.feature_flags import IS_POSTGRES_OR_GRPC_BACKEND
+from langgraph_runtime.database import connect
+
+if IS_POSTGRES_OR_GRPC_BACKEND:
+    from langgraph_api.grpc.ops import Runs
+else:
+    from langgraph_runtime.ops import Runs
+
+if TYPE_CHECKING:
+    from starlette.requests import Request
+    from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+logger = structlog.stdlib.get_logger(__name__)
+
+CANCEL_RUNS_PATH = "/operator/runs/cancel"
+
+_OPERATOR_TOKEN_PATH = "/auth/operator-token"
+_INTERRUPT = "interrupt"
+
+# host-backend fixes the boundary at the press and mints every token after it, so a
+# boundary later than the token's issue time would cancel runs accepted after the
+# press. The allowance only covers clock differences between host-backend replicas.
+_BOUNDARY_SKEW = timedelta(seconds=5)
+
+# The route's refusal for each LangSmith answer other than 200. Anything not listed
+# means LangSmith couldn't answer.
+_LANGSMITH_REFUSALS = {
+    401: (401, "invalid_token"),
+    # A LangSmith release without operator tokens can't authorize this route.
+    404: (503, "langsmith_upgrade_required"),
+    405: (503, "langsmith_upgrade_required"),
+}
+
+
+@dataclass(frozen=True)
+class _OperatorToken:
+    """The cancellation a verified operator token authorizes."""
+
+    operation_id: UUID
+    user_id: UUID
+    accepted_before: datetime
+
+
+class OperatorRoutesMiddleware:
+    """Serves the operator routes and passes every other request through."""
+
+    def __init__(self, app: ASGIApp, mount_prefix: str | None = None) -> None:
+        self.app = app
+        self.cancel_runs_paths = {CANCEL_RUNS_PATH}
+        if mount_prefix:
+            self.cancel_runs_paths.add(mount_prefix + CANCEL_RUNS_PATH)
+        # Its own small app with the server's error handlers, since these requests
+        # never reach the main app.
+        self.operator_app = Starlette(
+            routes=[
+                Route(path, cancel_runs, methods=["POST"])
+                for path in self.cancel_runs_paths
+            ],
+            exception_handlers=app_exception_handlers(),
+        )
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http" or scope["path"] not in self.cancel_runs_paths:
+            await self.app(scope, receive, send)
+            return
+        status = None
+
+        async def send_recording_status(message: Message) -> None:
+            nonlocal status
+            if message["type"] == "http.response.start":
+                status = message["status"]
+            await send(message)
+
+        # Every operator request gets exactly one log line, including ones that fail
+        # unexpectedly; customer request logging never sees them.
+        try:
+            await self.operator_app(scope, receive, send_recording_status)
+        except Exception:
+            await logger.aexception("Operator request", **_log_fields(scope, status))
+            raise
+        await logger.ainfo("Operator request", **_log_fields(scope, status))
+
+
+def _log_fields(scope: Scope, status: int | None) -> dict[str, Any]:
+    # cancel_runs records the verified operation and the progress on the request state.
+    learned = scope.get("state", {}).get("operator_log_fields", {})
+    return {
+        "path": scope["path"],
+        "method": scope["method"],
+        "status": status,
+    } | learned
+
+
+async def cancel_runs(request: Request) -> Response:
+    """Interrupt every in-flight run accepted at or before the token's boundary.
+
+    The operation, boundary and user all come from the verified token; the request
+    body is ignored. One call cancels a bounded amount of work and returns how many
+    targets are still in flight, and the caller repeats it until both counts are zero.
+    """
+    token = await _verify_token(request)
+    log_fields = {
+        "operation_id": str(token.operation_id),
+        "user_id": str(token.user_id),
+    }
+    request.state.operator_log_fields = log_fields
+
+    # Built only from fixed text and UUIDs, never from text in the request.
+    reason = (
+        f"cancelled by kill switch (operation {token.operation_id}, "
+        f"requested by LangSmith user {token.user_id})"
+    )
+    async with connect() as conn:
+        progress = await Runs.cancel_accepted_before(
+            conn, token.accepted_before, reason=reason
+        )
+    log_fields.update(progress)
+    return JSONResponse(progress)
+
+
+async def _verify_token(request: Request) -> _OperatorToken:
+    """Return the cancellation the request's operator token authorizes here.
+
+    LangSmith checks the token's signature, audience, subject and expiry on every
+    call, with no cache. This route checks that the token names this deployment and
+    an interrupt. Anything short of that is a refusal.
+    """
+    tenant_id = _as_uuid(config.LANGSMITH_TENANT_ID)
+    deployment_id = _as_uuid(config.LANGSMITH_HOST_PROJECT_ID)
+    if tenant_id is None or deployment_id is None:
+        # Only a deployment LangSmith manages is sent operator tokens.
+        raise HTTPException(404)
+    token = request.headers.get("x-service-key")
+    if not token:
+        raise HTTPException(401, "missing_token")
+    # A client per call, so nothing one verification leaves behind (such as a
+    # cookie) reaches the next.
+    auth = create_client()
+    try:
+        response = await auth.get(
+            _OPERATOR_TOKEN_PATH, headers={"X-Service-Key": token}
+        )
+    except httpx.HTTPError as exc:
+        raise HTTPException(503, "langsmith_unavailable") from exc
+    finally:
+        await auth.client.aclose()
+    if response.status_code != 200:
+        status, detail = _LANGSMITH_REFUSALS.get(
+            response.status_code, (503, "langsmith_unavailable")
+        )
+        raise HTTPException(status, detail)
+    try:
+        claims = response.json()
+    except ValueError as exc:
+        raise HTTPException(503, "langsmith_unavailable") from exc
+    if not isinstance(claims, dict):
+        raise HTTPException(503, "langsmith_unavailable")
+
+    operation_id = _as_uuid(claims.get("operation_id"))
+    user_id = _as_uuid(claims.get("user_id"))
+    accepted_before = _as_datetime(claims.get("accepted_before"))
+    issued_at = _as_timestamp(claims.get("issued_at"))
+    if (
+        _as_uuid(claims.get("tenant_id")) != tenant_id
+        or _as_uuid(claims.get("deployment_id")) != deployment_id
+        or claims.get("action") != _INTERRUPT
+        or operation_id is None
+        or user_id is None
+        or accepted_before is None
+        or issued_at is None
+        or accepted_before > issued_at + _BOUNDARY_SKEW
+    ):
+        raise HTTPException(403, "forbidden")
+    return _OperatorToken(operation_id, user_id, accepted_before)
+
+
+def _as_uuid(value: Any) -> UUID | None:
+    if isinstance(value, str):
+        with contextlib.suppress(ValueError):
+            return UUID(value)
+    return None
+
+
+def _as_timestamp(value: Any) -> datetime | None:
+    if isinstance(value, int | float) and not isinstance(value, bool):
+        with contextlib.suppress(OverflowError, OSError, ValueError):
+            return datetime.fromtimestamp(value, UTC)
+    return None
+
+
+def _as_datetime(value: Any) -> datetime | None:
+    if isinstance(value, str):
+        with contextlib.suppress(ValueError):
+            parsed = datetime.fromisoformat(value)
+            if parsed.tzinfo is not None:
+                return parsed
+    return None

{langgraph_api-0.18.0.dev5 → langgraph_api-0.18.0.dev7}/langgraph_api/schema.py

@@ -325,6 +325,15 @@ class QueueStats(TypedDict):
     pending_unblocked_runs_wait_time_max_secs: float | None
 
 
+class RunCancelProgress(TypedDict):
+    """Targets of a cancel-by-boundary still in flight."""
+
+    not_yet_reached: int
+    """Targets with no cancel intent yet."""
+    finishing: int
+    """Targets that have a cancel intent and haven't stopped yet."""
+
+
 # Canonical field sets for select= validation and type aliases for ops
 
 # Assistant select fields (intentionally excludes 'context')