release(langgraph): 1.2.17 (#9418 )

Bumps langgraph from 1.2.16 to 1.2.17. Includes: - Apply an explicit `recursion_limit` equal to the default (#9417) - Keep the caller's namespace in `RemoteGraph.stream(subgraphs=True)` (#9401)
fix(langgraph): apply an explicit recursion_limit equal to the default (#9417 )
2026-10-25 08:21:40 +01:00 · 2026-10-24 01:02:32 +00:00 · 2026-10-24 00:56:19 +00:00 · 2026-10-23 19:24:04 -04:00 · 2026-10-23 14:18:08 +00:00 · 2026-10-23 09:32:43 -04:00
37 changed files with 919 additions and 84 deletions
@@ -36,11 +36,11 @@ wheels = [

 [[package]]
 name = "certifi"
-version = "2026.4.22"
+version = "2026.10.19"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/25/ee/6caf7a40c36a1220410afe15a1cc64993a1f864871f698c0f93acb72842a/certifi-2026.4.22.tar.gz", hash = "sha256:8d455352a37b71bf76a79caa83a3d6c25afee4a385d632127b6afb3963f1c580", size = 137077, upload-time = "2026-04-22T11:26:11.191Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/a6/bd/1436c50cc46699de0230fbaacc1d1de7bfec413176099949e9d5112e88f2/certifi-2026.10.19.tar.gz", hash = "sha256:035c1e85572b141bf1c3a3eff0e33a8eb74917522f2559075ff8d2fea780a1ae", size = 137598, upload-time = "2026-10-20T02:24:16.604Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/22/30/7cd8fdcdfbc5b869528b079bfb76dcdf6056b1a2097a662e5e8c04f42965/certifi-2026.4.22-py3-none-any.whl", hash = "sha256:3cb2210c8f88ba2318d29b0388d1023c8492ff72ecdde4ebdaddbb13a31b1c4a", size = 135707, upload-time = "2026-04-22T11:26:09.372Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/51/29046e48f693c54e5b7412216d447a1d8362c9653148d98c02cdf65fa733/certifi-2026.10.19-py3-none-any.whl", hash = "sha256:42d35340cc5b9ba78e818ddbff0c5b1c2b779de448a340fd1b989f5fa8670e1b", size = 136464, upload-time = "2026-10-20T02:24:15.072Z" },
 ]

 [[package]]
@@ -40,11 +40,11 @@ wheels = [

 [[package]]
 name = "certifi"
-version = "2026.1.4"
+version = "2026.10.19"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/e0/2d/a891ca51311197f6ad14a7ef42e2399f36cf2f9bd44752b3dc4eab60fdc5/certifi-2026.1.4.tar.gz", hash = "sha256:ac726dd470482006e014ad384921ed6438c457018f4b3d204aea4281258b2120", size = 154268, upload-time = "2026-01-04T02:42:41.825Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/a6/bd/1436c50cc46699de0230fbaacc1d1de7bfec413176099949e9d5112e88f2/certifi-2026.10.19.tar.gz", hash = "sha256:035c1e85572b141bf1c3a3eff0e33a8eb74917522f2559075ff8d2fea780a1ae", size = 137598, upload-time = "2026-10-20T02:24:16.604Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/e6/ad/3cc14f097111b4de0040c83a525973216457bbeeb63739ef1ed275c1c021/certifi-2026.1.4-py3-none-any.whl", hash = "sha256:9943707519e4add1115f44c2bc244f782c0249876bf51b6599fee1ffbedd685c", size = 152900, upload-time = "2026-01-04T02:42:40.15Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/51/29046e48f693c54e5b7412216d447a1d8362c9653148d98c02cdf65fa733/certifi-2026.10.19-py3-none-any.whl", hash = "sha256:42d35340cc5b9ba78e818ddbff0c5b1c2b779de448a340fd1b989f5fa8670e1b", size = 136464, upload-time = "2026-10-20T02:24:15.072Z" },
 ]

 [[package]]
@@ -1364,6 +1364,17 @@ def test_search_empty_prefix_is_unconstrained(store: SqliteStore) -> None:
    }


+@pytest.mark.parametrize("batched", [False, True])
+def test_search_rejects_nul_namespace_prefix(store: SqliteStore, batched: bool) -> None:
+    store.put(("a",), "key", {"v": 1})
+
+    with pytest.raises(InvalidNamespaceError, match="NUL"):
+        if batched:
+            store.batch([SearchOp(("a\x00",))])
+        else:
+            store.search(("a\x00",))
+
+
 def test_namespace_labels_with_trailing_newline(store: SqliteStore) -> None:
    """Labels may contain newlines, and must not match a differently-named label.

@@ -49,11 +49,11 @@ wheels = [

 [[package]]
 name = "certifi"
-version = "2026.1.4"
+version = "2026.10.19"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/e0/2d/a891ca51311197f6ad14a7ef42e2399f36cf2f9bd44752b3dc4eab60fdc5/certifi-2026.1.4.tar.gz", hash = "sha256:ac726dd470482006e014ad384921ed6438c457018f4b3d204aea4281258b2120", size = 154268, upload-time = "2026-01-04T02:42:41.825Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/a6/bd/1436c50cc46699de0230fbaacc1d1de7bfec413176099949e9d5112e88f2/certifi-2026.10.19.tar.gz", hash = "sha256:035c1e85572b141bf1c3a3eff0e33a8eb74917522f2559075ff8d2fea780a1ae", size = 137598, upload-time = "2026-10-20T02:24:16.604Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/e6/ad/3cc14f097111b4de0040c83a525973216457bbeeb63739ef1ed275c1c021/certifi-2026.1.4-py3-none-any.whl", hash = "sha256:9943707519e4add1115f44c2bc244f782c0249876bf51b6599fee1ffbedd685c", size = 152900, upload-time = "2026-01-04T02:42:40.15Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/51/29046e48f693c54e5b7412216d447a1d8362c9653148d98c02cdf65fa733/certifi-2026.10.19-py3-none-any.whl", hash = "sha256:42d35340cc5b9ba78e818ddbff0c5b1c2b779de448a340fd1b989f5fa8670e1b", size = 136464, upload-time = "2026-10-20T02:24:15.072Z" },
 ]

 [[package]]
@@ -1333,6 +1333,10 @@ def _validate_namespace_labels(namespace: tuple[str, ...]) -> None:
            raise InvalidNamespaceError(
                f"Invalid namespace label '{label}' found in {namespace}. Namespace labels cannot contain periods ('.')."
            )
+        elif "\x00" in label:
+            raise InvalidNamespaceError(
+                f"Invalid namespace label '{label}' found in {namespace}. Namespace labels cannot contain NUL bytes ('\\x00')."
+            )
        elif not label:
            raise InvalidNamespaceError(
                f"Namespace labels cannot be empty strings. Got {label} in {namespace}"
@@ -532,7 +532,7 @@ async def test_cannot_put_empty_namespace() -> None:
    assert (await async_store.aget(("valid", "namespace"), "key")) is None


-INVALID_NAMESPACES = [("foo.bar",), ("foo", ""), (123,)]
+INVALID_NAMESPACES = [("foo.bar",), ("foo\x00",), ("foo", ""), (123,)]
 NAMESPACE_METHODS = ["get", "delete", "search", "prefix", "suffix"]


@@ -51,11 +51,11 @@ wheels = [

 [[package]]
 name = "certifi"
-version = "2026.1.4"
+version = "2026.10.19"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/e0/2d/a891ca51311197f6ad14a7ef42e2399f36cf2f9bd44752b3dc4eab60fdc5/certifi-2026.1.4.tar.gz", hash = "sha256:ac726dd470482006e014ad384921ed6438c457018f4b3d204aea4281258b2120", size = 154268, upload-time = "2026-01-04T02:42:41.825Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/a6/bd/1436c50cc46699de0230fbaacc1d1de7bfec413176099949e9d5112e88f2/certifi-2026.10.19.tar.gz", hash = "sha256:035c1e85572b141bf1c3a3eff0e33a8eb74917522f2559075ff8d2fea780a1ae", size = 137598, upload-time = "2026-10-20T02:24:16.604Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/e6/ad/3cc14f097111b4de0040c83a525973216457bbeeb63739ef1ed275c1c021/certifi-2026.1.4-py3-none-any.whl", hash = "sha256:9943707519e4add1115f44c2bc244f782c0249876bf51b6599fee1ffbedd685c", size = 152900, upload-time = "2026-01-04T02:42:40.15Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/51/29046e48f693c54e5b7412216d447a1d8362c9653148d98c02cdf65fa733/certifi-2026.10.19-py3-none-any.whl", hash = "sha256:42d35340cc5b9ba78e818ddbff0c5b1c2b779de448a340fd1b989f5fa8670e1b", size = 136464, upload-time = "2026-10-20T02:24:15.072Z" },
 ]

 [[package]]
@@ -23,6 +23,7 @@ from langgraph_cli.schemas import (
    GraphDef,
    HttpConfig,
    IndexConfig,
+    PriorityConfig,
    SecurityConfig,
    SerdeConfig,
    StoreConfig,
@@ -113,6 +114,7 @@ def add_descriptions_to_schema(schema, cls):
                StoreConfig,
                IndexConfig,
                AuthConfig,
+                PriorityConfig,
                SecurityConfig,
                HttpConfig,
                CorsConfig,
@@ -1776,17 +1776,17 @@ baseline-browser-mapping@^2.11.12:
  integrity sha512-H0ulySigv6icDJ1F7SjtdCD6PrhTpdYCmP0CactWy1+ekh0AFd0o1Wn5T8b+hnTmdBx19u9yhL6wvCylXMY7zw==

 brace-expansion@^1.1.7:
-  version "1.1.11"
-  resolved "https://registry.yarnpkg.com/brace-expansion/-/brace-expansion-1.1.11.tgz#3c7fcbf529d87226f3d2f52b966ff5271eb441dd"
-  integrity sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==
+  version "1.1.21"
+  resolved "https://registry.yarnpkg.com/brace-expansion/-/brace-expansion-1.1.21.tgz#edf4fab5c64d051aea5a8def49aba1c7522279f3"
+  integrity sha512-9zeA+KLZNNzglF2TPKRQEDyx6Yby7daAkuy8MiPzpXPsYDWi/DRM8jmwUDxokQjYqBpv5DgPiwD4h4ZZSy1Ujw==
  dependencies:
    balanced-match "^1.0.0"
    concat-map "0.0.1"

 brace-expansion@^2.0.2:
-  version "2.0.2"
-  resolved "https://registry.yarnpkg.com/brace-expansion/-/brace-expansion-2.0.2.tgz#54fc53237a613d854c7bd37463aad17df87214e7"
-  integrity sha512-Jt0vHyM+jmUBqojB7E1NIYadt0vI0Qxjxd2TErW94wDz+E2LAm5vKMXXwg6ZZBTHPuUlDgQHKXvjGBdfcF1ZDQ==
+  version "2.1.7"
+  resolved "https://registry.yarnpkg.com/brace-expansion/-/brace-expansion-2.1.7.tgz#14ea3836731823bb24740225ea43b941b436f9d1"
+  integrity sha512-uZbew1NqdmPDTMJ8ah1y+b+9QEJrfkXFk3RcTQw3X0jW/xRUvFKsg1CfQdSYGdTbXZWExtU3J3ccxtnfw1Fi0g==
  dependencies:
    balanced-match "^1.0.0"

@@ -581,9 +581,9 @@ base64-js@^1.5.1:
  integrity sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==

 brace-expansion@^1.1.7:
-  version "1.1.12"
-  resolved "https://registry.yarnpkg.com/brace-expansion/-/brace-expansion-1.1.12.tgz#ab9b454466e5a8cc3a187beaad580412a9c5b843"
-  integrity sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==
+  version "1.1.21"
+  resolved "https://registry.yarnpkg.com/brace-expansion/-/brace-expansion-1.1.21.tgz#edf4fab5c64d051aea5a8def49aba1c7522279f3"
+  integrity sha512-9zeA+KLZNNzglF2TPKRQEDyx6Yby7daAkuy8MiPzpXPsYDWi/DRM8jmwUDxokQjYqBpv5DgPiwD4h4ZZSy1Ujw==
  dependencies:
    balanced-match "^1.0.0"
    concat-map "0.0.1"
@@ -1 +1 @@
-__version__ = "0.4.37"
+__version__ = "0.4.38"
@@ -847,6 +847,7 @@ def dev(
        store=config_json.get("store"),
        wait_for_client=wait_for_client,
        auth=config_json.get("auth"),
+        priority=config_json.get("priority"),
        http=config_json.get("http"),
        ui=config_json.get("ui"),
        ui_config=config_json.get("ui_config"),
@@ -442,6 +442,7 @@ def validate_config(
        "store": config.get("store"),
        "auth": config.get("auth"),
        "encryption": config.get("encryption"),
+        "priority": config.get("priority"),
        "http": config.get("http"),
        # Pass through webhooks config so it can be injected into the image
        "webhooks": config.get("webhooks"),
@@ -606,6 +607,19 @@ def validate_config(
                    f"Invalid encryption.path format: '{encryption_conf['path']}'. "
                    "Must be in format './path/to/file.py:attribute_name'"
                )
+    # Validate priority config
+    if priority_conf := config.get("priority"):
+        if "path" in priority_conf:
+            if ":" not in priority_conf["path"]:
+                raise ValueError(
+                    f"Invalid priority.path format: '{priority_conf['path']}'. "
+                    "Must be in format './path/to/file.py:attribute_name'"
+                )
+            if _is_node_graph(priority_conf["path"]):
+                raise ValueError(
+                    "JavaScript priority callbacks are not supported: "
+                    f"'{priority_conf['path']}'. Use a Python file or module instead."
+                )
    if http_conf := config.get("http"):
        if "app" in http_conf:
            if ":" not in http_conf["app"]:
@@ -649,6 +663,7 @@ _KNOWN_CONFIG_KEYS = {
    "store",
    "auth",
    "encryption",
+    "priority",
    "http",
    "webhooks",
    "checkpointer",
@@ -1080,6 +1095,49 @@ def _update_encryption_path(
    )


+def _update_priority_path(
+    config_path: pathlib.Path, config: Config, local_deps: LocalDeps
+) -> None:
+    """Update priority.path to use Docker container paths."""
+    priority_conf = config.get("priority")
+    if not priority_conf or not (path_str := priority_conf.get("path")):
+        return
+
+    module_str, sep, attr_str = path_str.partition(":")
+    if not sep or not module_str.startswith("."):
+        return  # Already validated or absolute path
+
+    resolved = config_path.parent / module_str
+    if not resolved.exists():
+        raise FileNotFoundError(
+            f"Priority file not found: {resolved} (from {path_str})"
+        )
+    if not resolved.is_file():
+        raise IsADirectoryError(f"Priority path must be a file: {resolved}")
+
+    # Check faux packages first (they take precedence)
+    for faux_path, (_, destpath) in local_deps.faux_pkgs.items():
+        if resolved.is_relative_to(faux_path):
+            new_path = f"{destpath}/{resolved.relative_to(faux_path)}:{attr_str}"
+            priority_conf["path"] = new_path
+            return
+
+    # Check real packages
+    for real_path in local_deps.real_pkgs:
+        if resolved.is_relative_to(real_path):
+            new_path = (
+                f"/deps/{real_path.name}/{resolved.relative_to(real_path)}:{attr_str}"
+            )
+            priority_conf["path"] = new_path
+            return
+
+    raise ValueError(
+        f"Priority file '{resolved}' not covered by dependencies.\n"
+        "Add its parent directory to the 'dependencies' array in your config.\n"
+        f"Current dependencies: {config['dependencies']}"
+    )
+
+
 def _update_checkpointer_path(
    config_path: pathlib.Path, config: Config, local_deps: LocalDeps
 ) -> None:
@@ -1213,6 +1271,9 @@ def _build_runtime_env_vars(config: Config) -> list[str]:
    if (encryption_config := config.get("encryption")) is not None:
        env_vars.append(f"ENV LANGGRAPH_ENCRYPTION='{json.dumps(encryption_config)}'")

+    if (priority_config := config.get("priority")) is not None:
+        env_vars.append(f"ENV LANGGRAPH_PRIORITY='{json.dumps(priority_config)}'")
+
    if (http_config := config.get("http")) is not None:
        env_vars.append(f"ENV LANGGRAPH_HTTP='{json.dumps(http_config)}'")

@@ -1380,6 +1441,8 @@ def python_config_to_docker(
    _update_auth_path(config_path, config, local_deps)
    # Rewrite encryption path, so it points to the correct location in the Docker container
    _update_encryption_path(config_path, config, local_deps)
+    # Rewrite priority path, so it points to the correct location in the Docker container
+    _update_priority_path(config_path, config, local_deps)
    # Rewrite checkpointer path, so it points to the correct location in the Docker container
    _update_checkpointer_path(config_path, config, local_deps)
    # Rewrite HTTP app path, so it points to the correct location in the Docker container
@@ -373,6 +373,27 @@ class EncryptionConfig(TypedDict, total=False):
    """


+class PriorityConfig(TypedDict, total=False):
+    """Configuration for custom run priority logic.
+
+    Allows you to decide each thread's priority settings with a Python function
+    that the server calls at the first run on a thread with no settings, which
+    can come long after the thread was created."""
+
+    path: str
+    """Required. Path to an instance of the Priority() class that registers an assign function.
+
+    Format: "path/to/file.py:my_priority"
+
+    Example:
+        {
+            "priority": {
+                "path": "./priority.py:my_priority"
+            }
+        }
+    """
+
+
 class CorsConfig(TypedDict, total=False):
    """Specifies Cross-Origin Resource Sharing (CORS) rules for your server.

@@ -753,6 +774,13 @@ class Config(TypedDict, total=False):
    Allows you to implement custom encryption for sensitive data stored in the database.
    """

+    priority: PriorityConfig | None
+    """Optional. Custom run priority config, including the path to your Python priority logic.
+
+    Allows you to decide each thread's priority settings at the first run on a thread with no settings,
+    which can come long after the thread was created.
+    """
+
    http: HttpConfig | None
    """Optional. Configuration for the built-in HTTP server, controlling which custom routes are exposed
    and how cross-origin requests are handled.
@@ -784,6 +812,7 @@ __all__ = [
    "CheckpointerConfig",
    "AuthConfig",
    "EncryptionConfig",
+    "PriorityConfig",
    "HttpConfig",
    "MiddlewareOrders",
    "Distros",
@@ -910,6 +910,7 @@ def python_config_to_docker_uv_lock(
    for section, key in [
        ("auth", "path"),
        ("encryption", "path"),
+        ("priority", "path"),
        ("checkpointer", "path"),
        ("http", "app"),
    ]:
@@ -196,6 +196,17 @@
                }
              ]
            },
+            "priority": {
+              "anyOf": [
+                {
+                  "$ref": "#/$defs/PriorityConfig"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Optional. Custom run priority config, including the path to your Python priority logic.\n\nAllows you to decide each thread's priority settings at the first run on a thread with no settings,\nwhich can come long after the thread was created.\n"
+            },
            "source": {
              "anyOf": [
                {
@@ -438,6 +449,17 @@
                }
              ]
            },
+            "priority": {
+              "anyOf": [
+                {
+                  "$ref": "#/$defs/PriorityConfig"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Optional. Custom run priority config, including the path to your Python priority logic.\n\nAllows you to decide each thread's priority settings at the first run on a thread with no settings,\nwhich can come long after the thread was created.\n"
+            },
            "source": {
              "$ref": "#/$defs/UvSource"
            },
@@ -666,6 +688,17 @@
                }
              ]
            },
+            "priority": {
+              "anyOf": [
+                {
+                  "$ref": "#/$defs/PriorityConfig"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Optional. Custom run priority config, including the path to your Python priority logic.\n\nAllows you to decide each thread's priority settings at the first run on a thread with no settings,\nwhich can come long after the thread was created.\n"
+            },
            "source": {
              "anyOf": [
                {
@@ -1170,6 +1203,18 @@
      },
      "required": []
    },
+    "PriorityConfig": {
+      "title": "PriorityConfig",
+      "description": "Configuration for custom run priority logic.\n\nAllows you to decide each thread's priority settings with a Python function\nthat the server calls at the first run on a thread with no settings, which\ncan come long after the thread was created.",
+      "type": "object",
+      "properties": {
+        "path": {
+          "type": "string",
+          "description": "Required. Path to an instance of the Priority() class that registers an assign function.\n"
+        }
+      },
+      "required": []
+    },
    "UvSource": {
      "title": "UvSource",
      "description": "Deployment source rooted at a uv project or workspace.",
@@ -196,6 +196,17 @@
                }
              ]
            },
+            "priority": {
+              "anyOf": [
+                {
+                  "$ref": "#/$defs/PriorityConfig"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Optional. Custom run priority config, including the path to your Python priority logic.\n\nAllows you to decide each thread's priority settings at the first run on a thread with no settings,\nwhich can come long after the thread was created.\n"
+            },
            "source": {
              "anyOf": [
                {
@@ -438,6 +449,17 @@
                }
              ]
            },
+            "priority": {
+              "anyOf": [
+                {
+                  "$ref": "#/$defs/PriorityConfig"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Optional. Custom run priority config, including the path to your Python priority logic.\n\nAllows you to decide each thread's priority settings at the first run on a thread with no settings,\nwhich can come long after the thread was created.\n"
+            },
            "source": {
              "$ref": "#/$defs/UvSource"
            },
@@ -666,6 +688,17 @@
                }
              ]
            },
+            "priority": {
+              "anyOf": [
+                {
+                  "$ref": "#/$defs/PriorityConfig"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Optional. Custom run priority config, including the path to your Python priority logic.\n\nAllows you to decide each thread's priority settings at the first run on a thread with no settings,\nwhich can come long after the thread was created.\n"
+            },
            "source": {
              "anyOf": [
                {
@@ -1170,6 +1203,18 @@
      },
      "required": []
    },
+    "PriorityConfig": {
+      "title": "PriorityConfig",
+      "description": "Configuration for custom run priority logic.\n\nAllows you to decide each thread's priority settings with a Python function\nthat the server calls at the first run on a thread with no settings, which\ncan come long after the thread was created.",
+      "type": "object",
+      "properties": {
+        "path": {
+          "type": "string",
+          "description": "Required. Path to an instance of the Priority() class that registers an assign function.\n"
+        }
+      },
+      "required": []
+    },
    "UvSource": {
      "title": "UvSource",
      "description": "Deployment source rooted at a uv project or workspace.",
@@ -2,10 +2,12 @@ import json
 import pathlib
 import re
 import shutil
+import sys
 import tempfile
 import textwrap
 from contextlib import contextmanager
 from pathlib import Path
+from unittest.mock import MagicMock

 import click
 from click.testing import CliRunner
@@ -371,6 +373,32 @@ def test_dev_command_requires_ssl_certfile_and_keyfile_together(tmp_path) -> Non
    assert "Both --ssl-certfile and --ssl-keyfile must be provided" in result.output


+def test_dev_command_passes_priority_to_the_server(tmp_path, monkeypatch) -> None:
+    config_path = tmp_path / "langgraph.json"
+    config_path.write_text(
+        json.dumps(
+            {
+                "dependencies": ["."],
+                "graphs": {"agent": "./agent.py:graph"},
+                "priority": {"path": "./priority.py:priority"},
+            }
+        ),
+        encoding="utf-8",
+    )
+    # The test environment doesn't install langgraph-api, so stand in for its server.
+    server = MagicMock()
+    monkeypatch.setitem(sys.modules, "langgraph_api.cli", server)
+    # dev appends the working directory and its dependencies to sys.path.
+    monkeypatch.setattr(sys, "path", list(sys.path))
+
+    result = CliRunner().invoke(cli, ["dev", "--config", str(config_path)])
+
+    assert result.exit_code == 0, result.output
+    assert server.run_server.call_args.kwargs["priority"] == {
+        "path": "./priority.py:priority"
+    }
+
+
 def test_deploy_list_command(monkeypatch) -> None:
    runner = CliRunner()
    captured: dict[str, str] = {}
@@ -16,6 +16,7 @@ from langgraph_cli.config import (
    config_to_docker,
    default_base_image,
    docker_tag,
+    get_unknown_keys,
    has_disallowed_build_command_content,
    validate_config,
    validate_config_file,
@@ -155,6 +156,7 @@ def test_validate_config():
        "store": None,
        "auth": None,
        "encryption": None,
+        "priority": None,
        "webhooks": None,
        "checkpointer": None,
        "http": None,
@@ -184,6 +186,7 @@ def test_validate_config():
        "store": None,
        "auth": None,
        "encryption": None,
+        "priority": None,
        "webhooks": None,
        "checkpointer": None,
        "http": None,
@@ -1289,6 +1292,109 @@ def test_config_to_docker_python_encryption_formatted():
    )


+@pytest.mark.parametrize(
+    "path", ["./priority.py:priority", "my_package.priority:priority"]
+)
+def test_config_to_docker_python_priority(path: str):
+    # Test that priority config is kept by validation and isn't an unknown key
+    raw_config = {
+        "python_version": "3.11",
+        "graphs": {"agent": "./agent.py:graph"},
+        "dependencies": ["."],
+        "priority": {"path": path},
+    }
+    validated = validate_config(raw_config)
+
+    assert validated["priority"] == {"path": path}
+    assert get_unknown_keys(raw_config) == []
+
+
+def test_config_to_docker_python_priority_bad_path():
+    # Test that invalid priority path format raises ValueError
+    with pytest.raises(ValueError, match="Invalid priority.path format"):
+        validate_config(
+            {
+                "python_version": "3.11",
+                "graphs": {"agent": "./agent.py:graph"},
+                "dependencies": ["."],
+                "priority": {"path": "./priority.py"},  # Missing :attribute
+            }
+        )
+
+
+@pytest.mark.parametrize("ext", [".ts", ".mts", ".cts", ".js", ".mjs", ".cjs"])
+def test_config_to_docker_python_priority_js_path(ext: str):
+    # Test that a JavaScript priority path is rejected
+    with pytest.raises(ValueError, match="JavaScript priority callbacks"):
+        validate_config(
+            {
+                "python_version": "3.11",
+                "graphs": {"agent": "./agent.py:graph"},
+                "dependencies": ["."],
+                "priority": {"path": f"./priority{ext}:priority"},
+            }
+        )
+
+
+def test_config_to_docker_nodejs_priority():
+    # Test that a Node.js-only project can name a Python priority file
+    actual_docker_stdin, _ = config_to_docker(
+        PATH_TO_CONFIG,
+        validate_config(
+            {
+                "node_version": "20",
+                "graphs": {"agent": "./graphs/agent.js:graph"},
+                "priority": {"path": "./priority.py:priority"},
+            }
+        ),
+        base_image="langchain/langgraphjs-api",
+    )
+    assert (
+        """ENV LANGGRAPH_PRIORITY='{"path": "./priority.py:priority"}'"""
+        in actual_docker_stdin
+    )
+
+
+def test_config_to_docker_python_priority_formatted():
+    # Test that priority config is written to the Docker output with its container path
+    actual_docker_stdin, _ = config_to_docker(
+        PATH_TO_CONFIG,
+        validate_config(
+            {
+                "python_version": "3.11",
+                "dependencies": ["."],
+                "graphs": {"agent": "./graphs/agent.py:graph"},
+                "priority": {"path": "./agent.py:my_priority"},
+            }
+        ),
+        base_image="langchain/langgraph-api",
+    )
+    assert (
+        "ENV LANGGRAPH_PRIORITY="
+        """'{"path": "/deps/outer-unit_tests/unit_tests/agent.py:my_priority"}'"""
+        in actual_docker_stdin
+    )
+
+
+def test_config_to_docker_python_priority_not_in_dependencies():
+    # Test that a priority file outside the dependencies raises ValueError
+    with pytest.raises(
+        ValueError, match="Priority file .* not covered by dependencies"
+    ):
+        config_to_docker(
+            PATH_TO_CONFIG,
+            validate_config(
+                {
+                    "python_version": "3.11",
+                    "dependencies": ["./graphs"],
+                    "graphs": {"agent": "./graphs/agent.py:graph"},
+                    "priority": {"path": "./agent.py:my_priority"},
+                }
+            ),
+            base_image="langchain/langgraph-api",
+        )
+
+
 def test_config_to_docker_nodejs_internal_docker_tag():
    graphs = {"agent": "./graphs/agent.js:graph"}
    actual_docker_stdin, additional_contexts = config_to_docker(
@@ -1731,6 +1837,38 @@ def test_config_to_docker_uv_lock_honors_root_workspace_sources():
        )


+def test_config_to_docker_uv_lock_rewrites_priority_path():
+    with tempfile.TemporaryDirectory() as tmpdir:
+        tmpdir_path = pathlib.Path(tmpdir)
+        project_root, config_path = _write_uv_lock_workspace(
+            tmpdir_path,
+            agent_sources="[tool.uv.sources]\nshared = { workspace = true }",
+        )
+        (project_root / "libs" / "shared" / "src" / "shared" / "priority.py").touch()
+
+        config = validate_config(
+            {
+                "python_version": "3.11",
+                "graphs": {
+                    "agent": "../../apps/agent/src/agent/graph.py:graph",
+                },
+                "source": {"kind": "uv", "root": "../..", "package": "agent"},
+                "priority": {
+                    "path": "../../libs/shared/src/shared/priority.py:priority"
+                },
+            }
+        )
+        docker, _ = config_to_docker(
+            config_path, config, base_image="langchain/langgraph-api:0.2.47"
+        )
+
+        assert (
+            "ENV LANGGRAPH_PRIORITY="
+            """'{"path": "/deps/workspace/libs/shared/src/shared/priority.py:priority"}'"""
+            in docker
+        )
+
+
 def test_config_to_docker_uv_lock_ignores_unrelated_workspace_package_sources():
    with tempfile.TemporaryDirectory() as tmpdir:
        tmpdir_path = pathlib.Path(tmpdir)
@@ -52,11 +52,11 @@ wheels = [

 [[package]]
 name = "certifi"
-version = "2026.2.25"
+version = "2026.10.19"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/af/2d/7bf41579a8986e348fa033a31cdd0e4121114f6bce2457e8876010b092dd/certifi-2026.2.25.tar.gz", hash = "sha256:e887ab5cee78ea814d3472169153c2d12cd43b14bd03329a39a9c6e2e80bfba7", size = 155029, upload-time = "2026-02-25T02:54:17.342Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/a6/bd/1436c50cc46699de0230fbaacc1d1de7bfec413176099949e9d5112e88f2/certifi-2026.10.19.tar.gz", hash = "sha256:035c1e85572b141bf1c3a3eff0e33a8eb74917522f2559075ff8d2fea780a1ae", size = 137598, upload-time = "2026-10-20T02:24:16.604Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/9a/3c/c17fb3ca2d9c3acff52e30b309f538586f9f5b9c9cf454f3845fc9af4881/certifi-2026.2.25-py3-none-any.whl", hash = "sha256:027692e4402ad994f1c42e52a4997a9763c646b73e4096e4d5d6db8af1d6f0fa", size = 153684, upload-time = "2026-02-25T02:54:15.766Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/51/29046e48f693c54e5b7412216d447a1d8362c9653148d98c02cdf65fa733/certifi-2026.10.19-py3-none-any.whl", hash = "sha256:42d35340cc5b9ba78e818ddbff0c5b1c2b779de448a340fd1b989f5fa8670e1b", size = 136464, upload-time = "2026-10-20T02:24:15.072Z" },
 ]

 [[package]]
@@ -26,11 +26,11 @@ wheels = [

 [[package]]
 name = "certifi"
-version = "2026.5.20"
+version = "2026.10.19"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/f3/ce/ee2ecad540810a79593028e88299baeae54d346cc7a0d94b6199988b89b1/certifi-2026.5.20.tar.gz", hash = "sha256:69dea482ab64caa7b9f6aba1c6bf48bb6a5448d1c0f1b17ab42ad8c763a5344d", size = 135422, upload-time = "2026-05-20T11:46:50.073Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/a6/bd/1436c50cc46699de0230fbaacc1d1de7bfec413176099949e9d5112e88f2/certifi-2026.10.19.tar.gz", hash = "sha256:035c1e85572b141bf1c3a3eff0e33a8eb74917522f2559075ff8d2fea780a1ae", size = 137598, upload-time = "2026-10-20T02:24:16.604Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/59/8c/57e832b7af6d7c5abe66eb3fbe3a3a32f4d11ea23a1aa7131371035be991/certifi-2026.5.20-py3-none-any.whl", hash = "sha256:3c52e209ba0a4ad7aebe60436a4ab349c39e1e602e8c134221e546902ad25897", size = 134134, upload-time = "2026-05-20T11:46:48.578Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/51/29046e48f693c54e5b7412216d447a1d8362c9653148d98c02cdf65fa733/certifi-2026.10.19-py3-none-any.whl", hash = "sha256:42d35340cc5b9ba78e818ddbff0c5b1c2b779de448a340fd1b989f5fa8670e1b", size = 136464, upload-time = "2026-10-20T02:24:15.072Z" },
 ]

 [[package]]
@@ -168,11 +168,11 @@ wheels = [

 [[package]]
 name = "certifi"
-version = "2026.2.25"
+version = "2026.10.19"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/af/2d/7bf41579a8986e348fa033a31cdd0e4121114f6bce2457e8876010b092dd/certifi-2026.2.25.tar.gz", hash = "sha256:e887ab5cee78ea814d3472169153c2d12cd43b14bd03329a39a9c6e2e80bfba7", size = 155029, upload-time = "2026-02-25T02:54:17.342Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/a6/bd/1436c50cc46699de0230fbaacc1d1de7bfec413176099949e9d5112e88f2/certifi-2026.10.19.tar.gz", hash = "sha256:035c1e85572b141bf1c3a3eff0e33a8eb74917522f2559075ff8d2fea780a1ae", size = 137598, upload-time = "2026-10-20T02:24:16.604Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/9a/3c/c17fb3ca2d9c3acff52e30b309f538586f9f5b9c9cf454f3845fc9af4881/certifi-2026.2.25-py3-none-any.whl", hash = "sha256:027692e4402ad994f1c42e52a4997a9763c646b73e4096e4d5d6db8af1d6f0fa", size = 153684, upload-time = "2026-02-25T02:54:15.766Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/51/29046e48f693c54e5b7412216d447a1d8362c9653148d98c02cdf65fa733/certifi-2026.10.19-py3-none-any.whl", hash = "sha256:42d35340cc5b9ba78e818ddbff0c5b1c2b779de448a340fd1b989f5fa8670e1b", size = 136464, upload-time = "2026-10-20T02:24:15.072Z" },
 ]

 [[package]]
@@ -2292,28 +2292,28 @@ wheels = [

 [[package]]
 name = "uv"
-version = "0.11.15"
+version = "0.13.4"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/da/34/609d5d01ba21dc8f0974610ca7802fbb2c946a0c38665cfe5c5aeddbefb5/uv-0.11.15.tar.gz", hash = "sha256:755f959ec6a2fd8ccb6ee76ad90ab759d2eb1f4797444078645dd1ee4bca92d6", size = 4159545, upload-time = "2026-05-18T19:57:48.133Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/79/55/609455d21e87430c11fe734abfced50a3bdf177b2f49d41fbb19c199cbc3/uv-0.13.4.tar.gz", hash = "sha256:b0bff5b9a5061f7a35b1d0c1a94c19af134222c48eb7aadc42f85a038be1b248", size = 7482486, upload-time = "2026-10-20T15:12:06.801Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/a6/7c/dcc230c5911884d8848145dabcac8fb95a5ed6f9fe1c57fae8242618f28a/uv-0.11.15-py3-none-linux_armv6l.whl", hash = "sha256:83b04ab49514a0a761ffedb36a748ee81f87746671e72088e5f32c9585e5f1a9", size = 23110183, upload-time = "2026-05-18T19:57:23.051Z" },
-    { url = "https://files.pythonhosted.org/packages/f4/f3/efd4e044b60eb9c3c12ee386be098d56c335538ccec7caa49349cfba9344/uv-0.11.15-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:b6cae61f737be075b90be9e3f07d961072aed7019f4c9b8ed5c5d41c4d6cade3", size = 22637941, upload-time = "2026-05-18T19:57:26.752Z" },
-    { url = "https://files.pythonhosted.org/packages/a6/b8/48627f895a1569e576822e0a8416aa4797eb4a4551de21a4ad97b9b5819d/uv-0.11.15-py3-none-macosx_11_0_arm64.whl", hash = "sha256:9accae33619a9166e5c48531deb455d672cfb89f9357a00975e669c76b0bd49f", size = 21258803, upload-time = "2026-05-18T19:57:05.473Z" },
-    { url = "https://files.pythonhosted.org/packages/af/50/4bc8a148274feabee2d9c9f1fa15009e10c0228dfe57981ee3ea2ef1d481/uv-0.11.15-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.musllinux_1_1_aarch64.whl", hash = "sha256:c0cf52cd6d50bb9e05e2d968f45f80761107e4cbc8d4a26d9758f9d8274aaec1", size = 23066178, upload-time = "2026-05-18T19:57:33.058Z" },
-    { url = "https://files.pythonhosted.org/packages/a9/56/139fc3bec9a8b0a25bfe2196123adb9f16124da437bf4fbcf0d21cfcafb2/uv-0.11.15-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.musllinux_1_1_armv7l.whl", hash = "sha256:49dc6ed70bff00937384f96cdc4b1a4742d18e5504ec2c4a1214dba2dee5687a", size = 22705332, upload-time = "2026-05-18T19:57:36.714Z" },
-    { url = "https://files.pythonhosted.org/packages/ca/b0/b18b3dd204f8c213236a1ebd148e009861637129a8cce34df0e9aa22ed40/uv-0.11.15-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:adb9a89352539fdd8f7cd5f9966cf9f94fc5b98e0ccdf5003a04123dc6423bec", size = 22707534, upload-time = "2026-05-18T19:58:04.117Z" },
-    { url = "https://files.pythonhosted.org/packages/76/36/3ca09f95572df99d361b49c96b1297149e96e120d8d1ecf074095a4b6da4/uv-0.11.15-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:40ff67e3f8e8a7533781a2e892a534975a93acb83ea35460e64e7b2bf2111774", size = 24096607, upload-time = "2026-05-18T19:58:11.625Z" },
-    { url = "https://files.pythonhosted.org/packages/64/be/3bdee21a296bbf5336a526e3613d0e7d4538dacc39c62d7fcba55d15f6b0/uv-0.11.15-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:c6463a299ed7e6b5a800ed6f108af8e1588352629424133ddef7572b0e1e1118", size = 25082562, upload-time = "2026-05-18T19:57:40.69Z" },
-    { url = "https://files.pythonhosted.org/packages/cd/73/f371f3689ffe741066468d001d85f739fc4b5574de83b639ef19b5e8a7f4/uv-0.11.15-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:68c1e62d4b78578b90b833553286b65d6a7e327537716441068583ba652ec4f5", size = 24253391, upload-time = "2026-05-18T19:57:18.47Z" },
-    { url = "https://files.pythonhosted.org/packages/d3/16/fe392d618af6b00c064b3e718d585dcf791546a77c5123a5bec07ce53a0a/uv-0.11.15-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:98edf1bdaf82447014852051d93e3ee95012509c567bf057fd117e6bdbd9a807", size = 24415871, upload-time = "2026-05-18T19:58:19.651Z" },
-    { url = "https://files.pythonhosted.org/packages/6e/24/2e92a052fb6334fcd746d1c7cb57847c204b118c84f5da53c0f9e129f7b7/uv-0.11.15-py3-none-manylinux_2_28_aarch64.whl", hash = "sha256:be8f76d25bcf4c92bb384240ac1bf9aa7f51063d0bdeca4c9cf0ec3ed8b145e0", size = 23159007, upload-time = "2026-05-18T19:57:10.653Z" },
-    { url = "https://files.pythonhosted.org/packages/3d/2e/6923d0658d164bb2c435ed1868aa2d49b3074594679917a001ff92dc95bb/uv-0.11.15-py3-none-manylinux_2_31_riscv64.musllinux_1_1_riscv64.whl", hash = "sha256:f9f4fbbf4fe485522054f3c7496c6e8e932d6436e4200ff3daf718db0b7c7bd5", size = 23769385, upload-time = "2026-05-18T19:58:15.856Z" },
-    { url = "https://files.pythonhosted.org/packages/a4/99/7e34cd949e57360814e8064cc9fb7104df445d0f6a663504e5f7473480aa/uv-0.11.15-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:0ed920e896b2fd13a35031707e307e42fbb2681458b967440a17272d86d49137", size = 23860973, upload-time = "2026-05-18T19:57:55.575Z" },
-    { url = "https://files.pythonhosted.org/packages/28/98/8fe1f5f9d816e94569a0298dd8e0936801097625fa1952162951f0d628b6/uv-0.11.15-py3-none-musllinux_1_1_i686.whl", hash = "sha256:41d907611f3e6a13262807fd7f0a17849f76285ca80f536f6b3943732bdc6656", size = 23431392, upload-time = "2026-05-18T19:57:59.814Z" },
-    { url = "https://files.pythonhosted.org/packages/cc/6b/76a1ce2fa860026913a5941700cdc7d715fce9c3277a3fa3489cf2523ca0/uv-0.11.15-py3-none-musllinux_1_1_x86_64.whl", hash = "sha256:e3b68f8bf1a4568710f77e5bda9182ce7682811d89a8e7468c22460e032b234d", size = 24519478, upload-time = "2026-05-18T19:57:51.165Z" },
-    { url = "https://files.pythonhosted.org/packages/43/60/1d58e8a05718cb50494763115710b73846cacb651fd735d285233fd72c59/uv-0.11.15-py3-none-win32.whl", hash = "sha256:8e2da3076761086a5b76869c3f38ef0509c836046ef41ddd19485dfd7271dca9", size = 22020178, upload-time = "2026-05-18T19:58:07.64Z" },
-    { url = "https://files.pythonhosted.org/packages/55/53/40fcefcb348af660488597ed3c01363df7344e60611f8883750dc596f5c6/uv-0.11.15-py3-none-win_amd64.whl", hash = "sha256:cc3915ab291a1ecaf31de05f5d8bd70d09c66fe9911a53f70d9efa62ff0dbd8a", size = 24668779, upload-time = "2026-05-18T19:57:44.894Z" },
-    { url = "https://files.pythonhosted.org/packages/e5/7d/fa3a9960c95af9bbe2a629048760d0b9b4fead8ccd4f2235af747ec7cdf0/uv-0.11.15-py3-none-win_arm64.whl", hash = "sha256:4f39426a13dee24897aed60c4b98058c66f18bd983885ac5f4a54a04b24fbddf", size = 23198178, upload-time = "2026-05-18T19:57:14.68Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/bd/4349da5356b17a1c0e36c8552c809925f86f6292de9b1f599f01e8e8093d/uv-0.13.4-py3-none-linux_armv6l.whl", hash = "sha256:205a4f93e568fb24f45a2f3834f1c0a8f1adb5f396bf473c71030ed707dce048", size = 18272390, upload-time = "2026-10-20T15:11:02.468Z" },
+    { url = "https://files.pythonhosted.org/packages/21/f2/0cb77a1ae43959772f8f7873eb1f4061907fbb1694ce55c79b231f639b1d/uv-0.13.4-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:b4bbacea78c9db136cd2ec3147cbfd9ed910b4db5e1877109bd74d0e73bb2eaf", size = 17384113, upload-time = "2026-10-20T15:11:07.172Z" },
+    { url = "https://files.pythonhosted.org/packages/26/44/5a8733dd1b2e8d6f9cffd1ff6428a3e11dcc7e146a7657e32cfb8d9fb4a4/uv-0.13.4-py3-none-macosx_11_0_arm64.whl", hash = "sha256:95f4eb2b991b53b50ec2b18ab612fca8ba1e7a75a47af0331fb8bcd21da3eb03", size = 14433723, upload-time = "2026-10-20T15:11:10.185Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/39/be14f051bf34a1822d634819890a2d0cba3b69101e633fb7b9f54d7b4020/uv-0.13.4-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.musllinux_1_1_aarch64.whl", hash = "sha256:e90ab42825587821096cb0d071e387468da38cfa22818c91f9c0b3c0453048e8", size = 17816443, upload-time = "2026-10-20T15:11:13.674Z" },
+    { url = "https://files.pythonhosted.org/packages/97/a0/5df0f8bc6367dd37b98432a7c462e2918554f6db2a71211574852b8f0727/uv-0.13.4-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.musllinux_1_1_armv7l.whl", hash = "sha256:3a9dcb6762c3ba249d8c084315ba03839082af3ece3536cc4164ec735c351d68", size = 17828025, upload-time = "2026-10-20T15:11:16.806Z" },
+    { url = "https://files.pythonhosted.org/packages/8b/9c/2fed5357700b7c304b94214979e4efe680c3bc6e337a97eedaa372fe0947/uv-0.13.4-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:8ae6ff2b07892379dc767c9064c2b8bbfac88e767edac7ce28e1b0f15d86abb4", size = 17843737, upload-time = "2026-10-20T15:11:20.043Z" },
+    { url = "https://files.pythonhosted.org/packages/4c/2e/ee026284f096236dc3e1abed0316f9edab65c0ea176ea0072c064e62478d/uv-0.13.4-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:25cc14ff4fd8335d3be2cc493a621a003fdafcb0fb1c953c905daabe4def5ab8", size = 18576350, upload-time = "2026-10-20T15:11:24.035Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/f1/67fbdb649c8c5d0cb38ea74829080479b77c8631cda5d77fc1b28f027ca7/uv-0.13.4-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:77062b02856c74697f48328d8a6583ab07e6da0a993e86c2db46f3d1da27c637", size = 19831234, upload-time = "2026-10-20T15:11:27.627Z" },
+    { url = "https://files.pythonhosted.org/packages/bd/00/7d49e3a1a3e98e5244fa38e0c964dc8de568bf3bb101257a63dc2602efed/uv-0.13.4-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:fb0e2028d9a8929884344afb7d91d0f65d9783f640d28aede89fca3602bedde9", size = 19702886, upload-time = "2026-10-20T15:11:31.128Z" },
+    { url = "https://files.pythonhosted.org/packages/4b/a1/de02c0913726728eca56ee258875cbba9c7b0572c63f494fd9f55c7852e3/uv-0.13.4-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:05e4332791b4d55b6dde8695b7fa6079b26991519f44760887c5dfbd5ca4fe53", size = 17181168, upload-time = "2026-10-20T15:11:34.583Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/cd/f4a3c7377674366798c56aabd0f9a1f05687c3939f5ba857a3ea6093ff84/uv-0.13.4-py3-none-manylinux_2_28_aarch64.whl", hash = "sha256:7b3cdf868e5415631fe797b648c0d6945d38d388f23367bdd0b6332e80a1fcb0", size = 16502020, upload-time = "2026-10-20T15:11:37.88Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/f4/ce79657c5a0f51b602db9a663529baafff03b9fe8cc41e09ad3f7246b88a/uv-0.13.4-py3-none-manylinux_2_31_riscv64.musllinux_1_1_riscv64.whl", hash = "sha256:4e6b08578c920b86910897f36bb6da7229c8e7e0187976570e2a538cb28b777e", size = 18000980, upload-time = "2026-10-20T15:11:41.59Z" },
+    { url = "https://files.pythonhosted.org/packages/21/e6/7d77022d5661f8e01578bc5423bf02af408220e7e7ac5ee15eb94742c7cb/uv-0.13.4-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:d86a5dec8ab30c70519c71ca5085c8aaf28664836cbc600951cedaa3fc678cbf", size = 18179083, upload-time = "2026-10-20T15:11:45.191Z" },
+    { url = "https://files.pythonhosted.org/packages/f4/40/1bf0324800d38009774ba087a6fbffddc76a3e5bf42c081b9298b1236fb5/uv-0.13.4-py3-none-musllinux_1_1_i686.whl", hash = "sha256:5d89d1028c2e22977d9215cbb79cfe12559cb0c8a507a12e2f3a7e47930cf1bf", size = 18010389, upload-time = "2026-10-20T15:11:48.963Z" },
+    { url = "https://files.pythonhosted.org/packages/1e/ec/f352ca2cc3b4b6191bb4ec8cdf4bc190eed0ba8bda4c33b7fd66c5d33cec/uv-0.13.4-py3-none-musllinux_1_1_x86_64.whl", hash = "sha256:52b5c753a7c2d5f8323a70bb4c93118988356331d0758afa6446c81f974e7196", size = 19004998, upload-time = "2026-10-20T15:11:52.628Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/4f/fc05ff4292edfe785b47874ec86d3d83ca2bf735cff8a9d2170ffb66ad83/uv-0.13.4-py3-none-win32.whl", hash = "sha256:d333f01852b817ba05612de31474739da1af7e5463d119b30a9c4331eba1f408", size = 16190502, upload-time = "2026-10-20T15:11:56.657Z" },
+    { url = "https://files.pythonhosted.org/packages/2f/b9/b526eab6c72eacc705a58378f6850fde046b28c86fed01bd42da61367c6b/uv-0.13.4-py3-none-win_amd64.whl", hash = "sha256:b2ff80397273fff0e02c20eacae6882834c811827d6fc08f658db156fe754386", size = 15331833, upload-time = "2026-10-20T15:11:59.733Z" },
+    { url = "https://files.pythonhosted.org/packages/7c/f7/4d5fa89d3d10ff6a84e547ef6e02c45b2f2d50e66682da778acf60db63f1/uv-0.13.4-py3-none-win_arm64.whl", hash = "sha256:deffa5a4afdb48f3e44fb26e80377d256b330ddcad0373daff4b54f6162b43a4", size = 15690151, upload-time = "2026-10-20T15:12:02.74Z" },
 ]

 [[package]]
@@ -29,7 +29,19 @@ from langgraph._internal._constants import (
    NS_SEP,
 )

-DEFAULT_RECURSION_LIMIT = int(getenv("LANGGRAPH_DEFAULT_RECURSION_LIMIT", "10007"))
+
+class _DefaultRecursionLimit(int):
+    """The limit `ensure_config` fills in when none is given.
+
+    `merge_configs` skips values of this type rather than any equal value, so an
+    explicit limit that happens to equal the default still applies. It checks the
+    type, not identity, because copying or pickling a config rebuilds the value.
+    """
+
+
+DEFAULT_RECURSION_LIMIT = _DefaultRecursionLimit(
+    getenv("LANGGRAPH_DEFAULT_RECURSION_LIMIT", "10007")
+)
 DELTA_MAX_SUPERSTEPS_SINCE_SNAPSHOT = int(
    getenv("LANGGRAPH_DELTA_MAX_SUPERSTEPS_SINCE_SNAPSHOT", "5000")
 )
@@ -182,7 +194,7 @@ def merge_configs(*configs: RunnableConfig | None) -> RunnableConfig:
                    base.get("callbacks"), cast(Callbacks, value)
                )
            elif key == "recursion_limit":
-                if config["recursion_limit"] != DEFAULT_RECURSION_LIMIT:
+                if not isinstance(config["recursion_limit"], _DefaultRecursionLimit):
                    base["recursion_limit"] = config["recursion_limit"]
            else:
                base[key] = config[key]  # type: ignore[literal-required]
@@ -861,11 +861,6 @@ class RemoteGraph(PregelProtocol):
                    )
                yield {"type": mode, "ns": ns, "data": chunk.data, "interrupts": ints}
            elif subgraphs:
-                if NS_SEP in chunk.event:
-                    mode, ns_ = chunk.event.split(NS_SEP, 1)
-                    ns = tuple(ns_.split(NS_SEP))
-                else:
-                    mode, ns = chunk.event, ()
                if req_single:
                    yield ns, chunk.data
                else:
@@ -1016,11 +1011,6 @@ class RemoteGraph(PregelProtocol):
                    )
                yield {"type": mode, "ns": ns, "data": chunk.data, "interrupts": ints}
            elif subgraphs:
-                if NS_SEP in chunk.event:
-                    mode, ns_ = chunk.event.split(NS_SEP, 1)
-                    ns = tuple(ns_.split(NS_SEP))
-                else:
-                    mode, ns = chunk.event, ()
                if req_single:
                    yield ns, chunk.data
                else:
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"

 [project]
 name = "langgraph"
-version = "1.2.16"
+version = "1.2.17"
 description = "Building stateful, multi-actor applications with LLMs"
 authors = []
 requires-python = ">=3.10"
@@ -1,11 +1,19 @@
+from collections.abc import Callable
+
 import pytest
 from langchain_core.callbacks import AsyncCallbackManager, BaseCallbackHandler

-from langgraph._internal._config import get_async_callback_manager_for_config
+from langgraph._internal._config import (
+    DEFAULT_RECURSION_LIMIT,
+    get_async_callback_manager_for_config,
+)
 from langgraph.graph import StateGraph
+from langgraph.pregel import Pregel

 pytestmark = pytest.mark.anyio

+EXPLICIT_DEFAULT_LIMIT = int(DEFAULT_RECURSION_LIMIT)
+

 def test_new_async_manager_includes_tags() -> None:
    config = {"callbacks": None}
@@ -114,3 +122,27 @@ async def test_with_config_tags_preserved_on_invoke() -> None:
    await graph.ainvoke({}, {"tags": ["invoke"]})
    assert "bound" in captured, "bound tag was dropped by ensure_config overwrite"
    assert "invoke" in captured, "invoke-time tag not present"
+
+
+@pytest.mark.parametrize(
+    "rebind",
+    [
+        lambda g: g.with_config(recursion_limit=EXPLICIT_DEFAULT_LIMIT),
+        lambda g: g.with_config({"recursion_limit": EXPLICIT_DEFAULT_LIMIT}),
+        lambda g: g.with_config(
+            {"recursion_limit": 1}, recursion_limit=EXPLICIT_DEFAULT_LIMIT
+        ),
+        lambda g: g.with_config(recursion_limit=EXPLICIT_DEFAULT_LIMIT).with_config(
+            tags=["t"]
+        ),
+    ],
+    ids=["kwarg", "config", "kwarg_over_config", "kept_by_later_with_config"],
+)
+def test_with_config_applies_recursion_limit_equal_to_default(
+    rebind: Callable[[Pregel], Pregel],
+) -> None:
+    builder = StateGraph(dict)
+    builder.add_node("node", lambda state: state)
+    builder.add_edge("__start__", "node")
+    graph = builder.compile().with_config(recursion_limit=EXPLICIT_DEFAULT_LIMIT + 1)
+    assert rebind(graph).config["recursion_limit"] == EXPLICIT_DEFAULT_LIMIT
@@ -819,6 +819,50 @@ async def test_astream():
    ]


+_CALLER_CONFIG: RunnableConfig = {
+    "configurable": {"thread_id": "thread_1", "checkpoint_ns": "outer:123"}
+}
+_SUBGRAPH_PARTS = [
+    StreamPart(event="values|sub:abc", data={"chunk": "inner"}),
+    StreamPart(event="values", data={"chunk": "root"}),
+]
+_CALLER_PREFIXED = [
+    (("outer:123", "sub:abc"), {"chunk": "inner"}),
+    (("outer:123",), {"chunk": "root"}),
+]
+
+
+def test_stream_subgraphs_keeps_caller_namespace():
+    mock_sync_client = MagicMock()
+    mock_sync_client.runs.stream.return_value = _SUBGRAPH_PARTS
+    remote_pregel = RemoteGraph("test_graph_id", sync_client=mock_sync_client)
+
+    stream_parts = list(
+        remote_pregel.stream(
+            {"input": "data"}, _CALLER_CONFIG, stream_mode="values", subgraphs=True
+        )
+    )
+
+    assert stream_parts == _CALLER_PREFIXED
+
+
+async def test_astream_subgraphs_keeps_caller_namespace():
+    mock_async_client = MagicMock()
+    async_iter = MagicMock()
+    async_iter.__aiter__.return_value = _SUBGRAPH_PARTS
+    mock_async_client.runs.stream.return_value = async_iter
+    remote_pregel = RemoteGraph("test_graph_id", client=mock_async_client)
+
+    stream_parts = [
+        part
+        async for part in remote_pregel.astream(
+            {"input": "data"}, _CALLER_CONFIG, stream_mode="values", subgraphs=True
+        )
+    ]
+
+    assert stream_parts == _CALLER_PREFIXED
+
+
 def test_invoke():
    # set up test
    mock_sync_client = MagicMock()
@@ -1,4 +1,6 @@
+import copy
 import functools
+import pickle
 import sys
 import uuid
 from collections.abc import Callable
@@ -25,6 +27,7 @@ from pydantic import BaseModel, Field
 from typing_extensions import NotRequired, Required, TypedDict

 from langgraph._internal._config import (
+    DEFAULT_RECURSION_LIMIT,
    _is_not_empty,
    _merge_callbacks,
    ensure_config,
@@ -620,6 +623,30 @@ def test_merge_configs_merges_metadata_lc_versions() -> None:
    assert merged["metadata"]["lc_agent_name"] == "agent"


+@pytest.mark.parametrize(
+    "rebuild",
+    [
+        lambda config: config,
+        copy.deepcopy,
+        lambda config: pickle.loads(pickle.dumps(config)),
+    ],
+    ids=["as_is", "deepcopy", "pickle"],
+)
+def test_merge_configs_skips_the_injected_default_recursion_limit(
+    rebuild: Callable[[RunnableConfig], RunnableConfig],
+) -> None:
+    merged = merge_configs({"recursion_limit": 50}, rebuild(ensure_config()))
+    assert merged["recursion_limit"] == 50
+
+
+def test_merge_configs_applies_an_explicit_recursion_limit_equal_to_default() -> None:
+    explicit_default = int(DEFAULT_RECURSION_LIMIT)
+    merged = merge_configs(
+        {"recursion_limit": 50}, {"recursion_limit": explicit_default}
+    )
+    assert merged["recursion_limit"] == explicit_default
+
+
 def test_ensure_config_merges_metadata_lc_versions() -> None:
    a = {
        "metadata": {
@@ -202,11 +202,11 @@ wheels = [

 [[package]]
 name = "certifi"
-version = "2026.1.4"
+version = "2026.10.19"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/e0/2d/a891ca51311197f6ad14a7ef42e2399f36cf2f9bd44752b3dc4eab60fdc5/certifi-2026.1.4.tar.gz", hash = "sha256:ac726dd470482006e014ad384921ed6438c457018f4b3d204aea4281258b2120", size = 154268, upload-time = "2026-01-04T02:42:41.825Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/a6/bd/1436c50cc46699de0230fbaacc1d1de7bfec413176099949e9d5112e88f2/certifi-2026.10.19.tar.gz", hash = "sha256:035c1e85572b141bf1c3a3eff0e33a8eb74917522f2559075ff8d2fea780a1ae", size = 137598, upload-time = "2026-10-20T02:24:16.604Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/e6/ad/3cc14f097111b4de0040c83a525973216457bbeeb63739ef1ed275c1c021/certifi-2026.1.4-py3-none-any.whl", hash = "sha256:9943707519e4add1115f44c2bc244f782c0249876bf51b6599fee1ffbedd685c", size = 152900, upload-time = "2026-01-04T02:42:40.15Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/51/29046e48f693c54e5b7412216d447a1d8362c9653148d98c02cdf65fa733/certifi-2026.10.19-py3-none-any.whl", hash = "sha256:42d35340cc5b9ba78e818ddbff0c5b1c2b779de448a340fd1b989f5fa8670e1b", size = 136464, upload-time = "2026-10-20T02:24:15.072Z" },
 ]

 [[package]]
@@ -1451,7 +1451,7 @@ wheels = [

 [[package]]
 name = "langgraph"
-version = "1.2.16"
+version = "1.2.17"
 source = { editable = "." }
 dependencies = [
    { name = "langchain-core" },
@@ -1919,7 +1919,7 @@ requires-dist = [
    { name = "langchain-core", specifier = ">=1.4.0,<2" },
    { name = "langchain-protocol", specifier = ">=0.0.15" },
    { name = "orjson", specifier = ">=3.11.5" },
-    { name = "websockets", specifier = ">=14,<17" },
+    { name = "websockets", specifier = ">=14" },
 ]

 [package.metadata.requires-dev]
@@ -49,11 +49,11 @@ wheels = [

 [[package]]
 name = "certifi"
-version = "2026.1.4"
+version = "2026.10.19"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/e0/2d/a891ca51311197f6ad14a7ef42e2399f36cf2f9bd44752b3dc4eab60fdc5/certifi-2026.1.4.tar.gz", hash = "sha256:ac726dd470482006e014ad384921ed6438c457018f4b3d204aea4281258b2120", size = 154268, upload-time = "2026-01-04T02:42:41.825Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/a6/bd/1436c50cc46699de0230fbaacc1d1de7bfec413176099949e9d5112e88f2/certifi-2026.10.19.tar.gz", hash = "sha256:035c1e85572b141bf1c3a3eff0e33a8eb74917522f2559075ff8d2fea780a1ae", size = 137598, upload-time = "2026-10-20T02:24:16.604Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/e6/ad/3cc14f097111b4de0040c83a525973216457bbeeb63739ef1ed275c1c021/certifi-2026.1.4-py3-none-any.whl", hash = "sha256:9943707519e4add1115f44c2bc244f782c0249876bf51b6599fee1ffbedd685c", size = 152900, upload-time = "2026-01-04T02:42:40.15Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/51/29046e48f693c54e5b7412216d447a1d8362c9653148d98c02cdf65fa733/certifi-2026.10.19-py3-none-any.whl", hash = "sha256:42d35340cc5b9ba78e818ddbff0c5b1c2b779de448a340fd1b989f5fa8670e1b", size = 136464, upload-time = "2026-10-20T02:24:15.072Z" },
 ]

 [[package]]
@@ -286,7 +286,7 @@ wheels = [

 [[package]]
 name = "langgraph"
-version = "1.2.16"
+version = "1.2.17"
 source = { editable = "../langgraph" }
 dependencies = [
    { name = "langchain-core" },
@@ -614,7 +614,7 @@ requires-dist = [
    { name = "langchain-core", specifier = ">=1.4.0,<2" },
    { name = "langchain-protocol", specifier = ">=0.0.15" },
    { name = "orjson", specifier = ">=3.11.5" },
-    { name = "websockets", specifier = ">=14,<17" },
+    { name = "websockets", specifier = ">=14" },
 ]

 [package.metadata.requires-dev]
@@ -34,6 +34,14 @@
 - **`thread.output`** — awaitable that resolves to the terminal thread state
  `values` dict after the run lifecycle completes.

+- **`Priority` (beta)** — register an async function with `@priority.assign`
+  and name the object in the `priority` section of `langgraph.json`. The
+  server calls the function with a `PriorityContext` at the first run on a
+  thread with no settings and stores the `PrioritySettings` it returns
+  (`priority`, `fairness_group`, `fairness_weight`) on the thread. Requires
+  `langgraph-api` 0.18.0 or later and a `langgraph-cli` that supports the
+  section; older versions of either ignore it.
+
 ### Changed

 - `client.threads.stream()` now accepts `transport="sse"` (default) or
@@ -2,14 +2,19 @@ from langgraph_sdk.auth import Auth
 from langgraph_sdk.client import get_client, get_sync_client
 from langgraph_sdk.encryption import Encryption
 from langgraph_sdk.encryption.types import DecryptResult, EncryptionContext
+from langgraph_sdk.priority import Priority
+from langgraph_sdk.priority.types import PriorityContext, PrioritySettings

-__version__ = "0.4.8"
+__version__ = "0.4.9"

 __all__ = [
    "Auth",
    "DecryptResult",
    "Encryption",
    "EncryptionContext",
+    "Priority",
+    "PriorityContext",
+    "PrioritySettings",
    "get_client",
    "get_sync_client",
 ]
@@ -0,0 +1,155 @@
+"""Custom run priority for LangGraph.
+
+.. warning::
+    This API is in beta and may change in future versions.
+
+This module lets developers decide the priority settings of each thread with
+an async function that the server calls at the first run on a thread with no
+settings. The function is registered on an object that `langgraph.json` names,
+and runs server-side.
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import typing
+import warnings
+from collections.abc import Awaitable, Callable
+
+from langgraph_sdk.encryption import DuplicateHandlerError, LangGraphBetaWarning
+from langgraph_sdk.priority import types
+
+_AssignHandler = Callable[
+    [types.PriorityContext], Awaitable[types.PrioritySettings | None]
+]
+_AssignHandlerT = typing.TypeVar("_AssignHandlerT", bound=_AssignHandler)
+
+
+@functools.lru_cache(maxsize=1)
+def _warn_priority_beta() -> None:
+    warnings.warn(
+        "The Priority API is in beta and may change in future versions.",
+        LangGraphBetaWarning,
+        stacklevel=4,
+    )
+
+
+def _validate_handler(fn: typing.Callable) -> None:
+    """Validate that the assign handler is async and takes one parameter.
+
+    Raises:
+        TypeError: If the handler is not an async function or has wrong parameter count
+    """
+    if not inspect.iscoroutinefunction(fn):
+        raise TypeError(
+            f"Priority assign handler must be an async function, got {type(fn)}"
+        )
+
+    sig = inspect.signature(fn)
+    params = [
+        p
+        for p in sig.parameters.values()
+        if p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)
+    ]
+    if len(params) != 1:
+        raise TypeError(
+            "Priority assign handler must accept exactly 1 parameter (ctx), "
+            f"got {len(params)}"
+        )
+
+
+class Priority:
+    """Decide the priority settings of your LangGraph application's threads.
+
+    .. warning::
+        This API is in beta and may change in future versions.
+
+    To use, create a separate Python file and add the path to the file to your
+    LangGraph API configuration file (`langgraph.json`). Within that file, create
+    an instance of the Priority class and register an assign function with
+    `@priority.assign`.
+
+    Example `langgraph.json` file:
+
+    ```json
+    {
+      "dependencies": ["."],
+      "graphs": {
+        "agent": "./my_agent/agent.py:graph"
+      },
+      "env": ".env",
+      "priority": {
+        "path": "./priority.py:priority"
+      }
+    }
+    ```
+
+    The server calls the assign function at the first run on a thread with no
+    settings, which can come long after the thread was created, and stores the
+    settings it returns on the thread. Later runs on the thread use the stored
+    settings. The function can be called more than once for one thread, for
+    example after it raises, and only one result is stored, so keep it free of
+    side effects.
+
+    ???+ example "Basic Usage"
+
+        ```python
+        from langgraph_sdk import Priority, PriorityContext, PrioritySettings
+
+        priority = Priority()
+
+        @priority.assign
+        async def assign(ctx: PriorityContext) -> PrioritySettings | None:
+            return {
+                "priority": 3 if "premium" in ctx.permissions else 0,
+                # Stored unencrypted, so an opaque ID rather than personal data.
+                "fairness_group": ctx.user["org_id"],
+            }
+        ```
+    """
+
+    __slots__ = ("_assign_handler",)
+
+    types = types
+    """Reference to priority type definitions.
+
+    Provides access to the type definitions used by the priority system:
+    PriorityContext and PrioritySettings.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the Priority instance."""
+        _warn_priority_beta()
+        self._assign_handler: _AssignHandler | None = None
+
+    def assign(self, fn: _AssignHandlerT) -> _AssignHandlerT:
+        """Register the function that assigns a thread's priority settings.
+
+        The function receives a `PriorityContext` and returns `PrioritySettings`,
+        or `None` for the defaults.
+
+        Example:
+            ```python
+            @priority.assign
+            async def assign(ctx: PriorityContext) -> PrioritySettings | None:
+                if ctx.cron_id is not None:
+                    return {"priority": -2}
+                return None
+            ```
+
+        Args:
+            fn: The assign handler function
+
+        Returns:
+            The registered handler function
+
+        Raises:
+            DuplicateHandlerError: If an assign handler is already registered
+            TypeError: If the handler has an invalid signature
+        """
+        if self._assign_handler is not None:
+            raise DuplicateHandlerError("Priority assign handler already registered")
+        _validate_handler(fn)
+        self._assign_handler = fn
+        return fn
@@ -0,0 +1,67 @@
+"""Priority types for LangGraph.
+
+This module defines the context the server passes to the function registered
+with `@priority.assign`, and the settings that function returns.
+"""
+
+from __future__ import annotations
+
+import typing
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from langgraph_sdk.auth.types import BaseUser
+
+
+@dataclass(frozen=True, slots=True)
+class PriorityContext:
+    """Context passed to the `@priority.assign` function at the first run on a thread with no settings."""
+
+    user: BaseUser
+    """The user from the deployment's auth, custom auth or LangSmith auth. Without auth, `user.identity` is empty."""
+
+    permissions: Sequence[str]
+    """The user's permissions from the same auth. Without auth, it's empty."""
+
+    thread_id: str | None
+    """The thread's ID, or `None` when the run creates its thread without being given an ID."""
+
+    thread_metadata: dict[str, typing.Any]
+    """The thread's metadata."""
+
+    assistant_id: str
+    """The ID of the assistant the run uses."""
+
+    graph_id: str
+    """The ID of the graph the assistant runs."""
+
+    assistant_metadata: dict[str, typing.Any]
+    """The assistant's metadata."""
+
+    run_metadata: dict[str, typing.Any]
+    """The run's metadata."""
+
+    cron_id: str | None
+    """The ID of the cron that started the run, or `None` when no cron started it."""
+
+
+class PrioritySettings(typing.TypedDict, total=False):
+    """Priority settings returned by the `@priority.assign` function.
+
+    Every key is optional: a missing key or a key set to `None` takes its
+    default, and returning `None` instead of a dict gives every key its default.
+    A value outside its range, or an empty `fairness_group`, is an error.
+    """
+
+    priority: int | None
+    """An integer from -5 to 5, where 5 runs first and -5 runs last. Defaults to 0."""
+
+    fairness_group: str | None
+    """The thread's fairness group, a non-empty string. Defaults to `"default"`.
+
+    The server stores it unencrypted, even when the deployment uses custom
+    encryption, so use an opaque ID rather than personal data.
+    """
+
+    fairness_weight: int | None
+    """The weight of the thread's fairness group, an integer from 1 to 100. Defaults to 1."""
@@ -16,7 +16,7 @@ dependencies = [
    "orjson>=3.11.5",
    "langchain-protocol>=0.0.15",
    "langchain-core>=1.4.0,<2",
-    "websockets>=14,<17",
+    "websockets>=14",
 ]

 [tool.hatch.version]
@@ -0,0 +1,128 @@
+import dataclasses
+
+import pytest
+
+import langgraph_sdk
+from langgraph_sdk import Priority, PriorityContext, PrioritySettings
+from langgraph_sdk.encryption import DuplicateHandlerError, LangGraphBetaWarning
+from langgraph_sdk.priority import _warn_priority_beta
+
+
+class _User:
+    is_authenticated = True
+    display_name = "user-1"
+    identity = "user-1"
+    permissions: tuple[str, ...] = ()
+
+    def __getitem__(self, key):
+        return getattr(self, key)
+
+    def __contains__(self, key):
+        return hasattr(self, key)
+
+    def __iter__(self):
+        return iter(("identity", "display_name", "is_authenticated", "permissions"))
+
+
+def _context(thread_id: str | None) -> PriorityContext:
+    return PriorityContext(
+        user=_User(),
+        permissions=[],
+        thread_id=thread_id,
+        thread_metadata={},
+        assistant_id="assistant-1",
+        graph_id="agent",
+        assistant_metadata={"tier": "gold"},
+        run_metadata={},
+        cron_id=None,
+    )
+
+
+async def _no_params() -> PrioritySettings | None:
+    return None
+
+
+async def _two_params(_ctx: PriorityContext, _extra: object) -> PrioritySettings | None:
+    return None
+
+
+def test_priority_and_its_types_are_exported():
+    assert {"Priority", "PriorityContext", "PrioritySettings"} <= set(
+        langgraph_sdk.__all__
+    )
+    assert Priority.types.PriorityContext is PriorityContext
+    assert Priority.types.PrioritySettings is PrioritySettings
+
+
+def test_construction_warns_that_priority_is_beta():
+    # The warning fires once per process, so an earlier test may have used it up.
+    _warn_priority_beta.cache_clear()
+    with pytest.warns(LangGraphBetaWarning, match="Priority API is in beta"):
+        Priority()
+
+
+def test_assign_registers_and_returns_the_function():
+    priority = Priority()
+
+    async def assign(_ctx: PriorityContext) -> PrioritySettings | None:
+        return {"priority": 3, "fairness_group": "org-42"}
+
+    assert priority.assign(assign) is assign
+    assert priority._assign_handler is assign
+
+
+def test_assign_rejects_a_sync_function():
+    priority = Priority()
+
+    def assign(_ctx: PriorityContext) -> PrioritySettings | None:
+        return None
+
+    with pytest.raises(TypeError, match="must be an async function"):
+        priority.assign(assign)  # ty: ignore[invalid-argument-type]
+    assert priority._assign_handler is None
+
+
+@pytest.mark.parametrize("fn", [_no_params, _two_params])
+def test_assign_rejects_the_wrong_number_of_parameters(fn):
+    priority = Priority()
+
+    with pytest.raises(TypeError, match="must accept exactly 1 parameter"):
+        priority.assign(fn)
+    assert priority._assign_handler is None
+
+
+def test_assign_rejects_a_second_function():
+    priority = Priority()
+
+    @priority.assign
+    async def first(_ctx: PriorityContext) -> PrioritySettings | None:
+        return None
+
+    with pytest.raises(DuplicateHandlerError):
+
+        @priority.assign
+        async def second(_ctx: PriorityContext) -> PrioritySettings | None:
+            return None
+
+    assert priority._assign_handler is first
+
+
+def test_context_accepts_no_thread_id():
+    # `make lint` type-checks this call too, so `thread_id` must accept None there.
+    assert _context(thread_id=None).thread_id is None
+
+
+def test_context_is_frozen():
+    ctx = _context(thread_id="thread-1")
+
+    with pytest.raises(dataclasses.FrozenInstanceError):
+        ctx.thread_id = "thread-2"  # ty: ignore[invalid-assignment]
+
+
+def test_every_settings_key_is_optional():
+    assert PrioritySettings.__optional_keys__ == {
+        "priority",
+        "fairness_group",
+        "fairness_weight",
+    }
+    assert PrioritySettings.__required_keys__ == frozenset()
@@ -1,5 +1,5 @@
 version = 1
-revision = 5
+revision = 3
 requires-python = ">=3.10"
 resolution-markers = [
    "python_full_version >= '3.15'",
@@ -40,11 +40,11 @@ wheels = [

 [[package]]
 name = "certifi"
-version = "2026.2.25"
+version = "2026.10.19"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/af/2d/7bf41579a8986e348fa033a31cdd0e4121114f6bce2457e8876010b092dd/certifi-2026.2.25.tar.gz", hash = "sha256:e887ab5cee78ea814d3472169153c2d12cd43b14bd03329a39a9c6e2e80bfba7", size = 155029, upload-time = "2026-02-25T02:54:17.342Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/a6/bd/1436c50cc46699de0230fbaacc1d1de7bfec413176099949e9d5112e88f2/certifi-2026.10.19.tar.gz", hash = "sha256:035c1e85572b141bf1c3a3eff0e33a8eb74917522f2559075ff8d2fea780a1ae", size = 137598, upload-time = "2026-10-20T02:24:16.604Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/9a/3c/c17fb3ca2d9c3acff52e30b309f538586f9f5b9c9cf454f3845fc9af4881/certifi-2026.2.25-py3-none-any.whl", hash = "sha256:027692e4402ad994f1c42e52a4997a9763c646b73e4096e4d5d6db8af1d6f0fa", size = 153684, upload-time = "2026-02-25T02:54:15.766Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/51/29046e48f693c54e5b7412216d447a1d8362c9653148d98c02cdf65fa733/certifi-2026.10.19-py3-none-any.whl", hash = "sha256:42d35340cc5b9ba78e818ddbff0c5b1c2b779de448a340fd1b989f5fa8670e1b", size = 136464, upload-time = "2026-10-20T02:24:15.072Z" },
 ]

 [[package]]
@@ -301,7 +301,7 @@ wheels = [

 [[package]]
 name = "langgraph"
-version = "1.2.16"
+version = "1.2.17"
 source = { editable = "../langgraph" }
 dependencies = [
    { name = "langchain-core" },
@@ -525,7 +525,7 @@ requires-dist = [
    { name = "langchain-core", specifier = ">=1.4.0,<2" },
    { name = "langchain-protocol", specifier = ">=0.0.15" },
    { name = "orjson", specifier = ">=3.11.5" },
-    { name = "websockets", specifier = ">=14,<17" },
+    { name = "websockets", specifier = ">=14" },
 ]

 [package.metadata.requires-dev]