langgraph-api 0.8.7__tar.gz → 0.9.0.dev1__tar.gz

{langgraph_api-0.8.7 → langgraph_api-0.9.0.dev1}/Makefile

@@ -1,7 +1,7 @@
 .PHONY: build release lint format test test_watch start start-inmem start-inmem-license-oss start start-js-server build-go-server start-go-server stop-go-server check-version check-base-imports test-a2a-tck test-a2a-tck-mandatory start-test-a2a-tck start-test-a2a-tck-mandatory start-test-a2a-tck-watch test-mcp-conformance start-test-mcp-conformance list-mcp-scenarios
 
 # Environment variables
-LANGSERVE_GRAPHS_ALL = '{"agent": {"path": "./tests/graphs/agent.py:graph", "description": "agent"}, "assistant_id_runtime": "./tests/graphs/assistant_id_runtime.py:graph", "custom_lifespan": "./tests/graphs/my_router.py:graph", "single_node": "./tests/graphs/single_node.py:graph", "benchmark": "./tests/graphs/benchmark.py:graph", "config_graph": "./tests/graphs/config_graph.py:graph", "other": "./tests/graphs/other.py:make_graph", "weather": "./tests/graphs/weather.py:mk_weather_graph", "searchy": "./tests/graphs/searchy.py:graph", "agent_simple": "./tests/graphs/agent_simple.py:graph", "simple_runtime": "./tests/graphs/simple_runtime.py:graph", "agent_interrupt": "./tests/graphs/agent_interrupt.py:graph", "agent_parallel_interrupt": "./tests/graphs/agent_parallel_interrupt.py:graph", "message_type_test": "./tests/graphs/message_type_test.py:graph", "remote_subgraph_parent": "./tests/graphs/remote_subgraph_parent.py:graph", "simple_remote": "./tests/graphs/simple_remote.py:graph", "nested_subgraphs": "./tests/graphs/nested_subgraphs.py:graph", "functional_fibonacci": "./tests/graphs/functional_fibonacci.py:fibonacci", "state_graph_fibonacci": "./tests/graphs/state_graph_fibonacci.py:fibonacci", "max_concurrency_graph": "./tests/graphs/max_concurrency_graph.py:graph", "unserializable_subgraph": "./tests/graphs/unserializable_subgraph.py:graph", "agent_interrupt_text": "./tests/graphs/agent_interrupt_text.py:graph", "agent_echo_stream": "./tests/graphs/agent_echo_stream.py:graph", "runtime_graph": "./tests/graphs/runtime_graph.py:graph", "tool_call_chunk_stream": "./tests/graphs/tool_call_chunk_stream.py:graph", "ui_tool_call_stream": "./tests/graphs/ui_tool_call_stream.py:graph"}'
+LANGSERVE_GRAPHS_ALL = '{"agent": {"path": "./tests/graphs/agent.py:graph", "description": "agent"}, "assistant_id_runtime": "./tests/graphs/assistant_id_runtime.py:graph", "custom_lifespan": "./tests/graphs/my_router.py:graph", "single_node": "./tests/graphs/single_node.py:graph", "benchmark": "./tests/graphs/benchmark.py:graph", "config_graph": "./tests/graphs/config_graph.py:graph", "other": "./tests/graphs/other.py:make_graph", "weather": "./tests/graphs/weather.py:mk_weather_graph", "searchy": "./tests/graphs/searchy.py:graph", "agent_simple": "./tests/graphs/agent_simple.py:graph", "simple_runtime": "./tests/graphs/simple_runtime.py:graph", "agent_interrupt": "./tests/graphs/agent_interrupt.py:graph", "agent_parallel_interrupt": "./tests/graphs/agent_parallel_interrupt.py:graph", "message_type_test": "./tests/graphs/message_type_test.py:graph", "remote_subgraph_parent": "./tests/graphs/remote_subgraph_parent.py:graph", "simple_remote": "./tests/graphs/simple_remote.py:graph", "nested_subgraphs": "./tests/graphs/nested_subgraphs.py:graph", "functional_fibonacci": "./tests/graphs/functional_fibonacci.py:fibonacci", "state_graph_fibonacci": "./tests/graphs/state_graph_fibonacci.py:fibonacci", "max_concurrency_graph": "./tests/graphs/max_concurrency_graph.py:graph", "unserializable_subgraph": "./tests/graphs/unserializable_subgraph.py:graph", "agent_interrupt_text": "./tests/graphs/agent_interrupt_text.py:graph", "agent_echo_stream": "./tests/graphs/agent_echo_stream.py:graph", "agent_tool_stream": "./tests/graphs/agent_tool_stream.py:graph", "runtime_graph": "./tests/graphs/runtime_graph.py:graph", "tool_call_chunk_stream": "./tests/graphs/tool_call_chunk_stream.py:graph", "ui_tool_call_stream": "./tests/graphs/ui_tool_call_stream.py:graph", "agent_metrics_stream": "./tests/graphs/agent_metrics_stream.py:graph", "agent_multimodal_stream": "./tests/graphs/agent_multimodal_stream.py:graph", "agent_bedtime_story": "./tests/graphs/agent_bedtime_story.py:graph", "delta_channel": "./tests/graphs/delta_channel.py:graph", "delta_channel_freq": "./tests/graphs/delta_channel_freq.py:graph", "delta_channel_files": "./tests/graphs/delta_channel_files.py:graph", "delta_channel_files_freq": "./tests/graphs/delta_channel_files_freq.py:graph", "delta_channel_legacy": "./tests/graphs/delta_channel_migration.py:graph_legacy", "delta_channel_delta": "./tests/graphs/delta_channel_migration.py:graph_delta", "delta_channel_messages_freq": "./tests/graphs/delta_channel_messages.py:graph_freq", "delta_channel_messages": "./tests/graphs/delta_channel_messages.py:graph", "delta_channel_messages_legacy": "./tests/graphs/delta_channel_messages.py:graph_legacy", "delta_channel_messages_remove": "./tests/graphs/delta_channel_messages.py:graph_remove", "delta_channel_messages_update": "./tests/graphs/delta_channel_messages.py:graph_update", "delta_channel_messages_delta": "./tests/graphs/delta_channel_messages.py:graph_delta"}'
 LANGSERVE_GRAPHS_AUTH = '{"agent": {"path": "./tests/graphs/agent.py:graph", "description": "agent"}, "assistant_id_runtime": "./tests/graphs/assistant_id_runtime.py:graph", "config_graph": "./tests/graphs/config_graph.py:graph", "other": "./tests/graphs/other.py:make_graph", "weather": "./tests/graphs/weather.py:mk_weather_graph", "searchy": "./tests/graphs/searchy.py:graph", "agent_simple": "./tests/graphs/agent_simple.py:graph", "simple_runtime": "./tests/graphs/simple_runtime.py:graph", "agent_parallel_interrupt": "./tests/graphs/agent_parallel_interrupt.py:graph", "functional_fibonacci": "./tests/graphs/functional_fibonacci.py:fibonacci", "state_graph_fibonacci": "./tests/graphs/state_graph_fibonacci.py:fibonacci", "runtime_graph": "./tests/graphs/runtime_graph.py:graph"}'
 
 # Go server management

{langgraph_api-0.8.7 → langgraph_api-0.9.0.dev1}/PKG-INFO

@@ -1,19 +1,20 @@
 Metadata-Version: 2.4
 Name: langgraph-api
-Version: 0.8.7
+Version: 0.9.0.dev1
 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
 Requires-Python: >=3.11
 Requires-Dist: cloudpickle>=3.0.0
-Requires-Dist: cryptography<47.0,>=42.0.0
-Requires-Dist: grpcio-health-checking<1.79.0,>=1.78.0
-Requires-Dist: grpcio-tools==1.78.0
-Requires-Dist: grpcio<1.79.0,>=1.78.0
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: grpcio-health-checking<1.81.0,>=1.80.0
+Requires-Dist: grpcio-tools==1.80.0
+Requires-Dist: grpcio<1.81.0,>=1.80.0
 Requires-Dist: httptools>=0.5.0; platform_system != 'Windows'
 Requires-Dist: httpx>=0.25.0
 Requires-Dist: jsonschema-rs<0.45,>=0.20.0
 Requires-Dist: langchain-core>=0.3.64
+Requires-Dist: langchain-protocol<0.1,>=0.0.15
 Requires-Dist: langgraph-checkpoint<5,>=3.0.1
 Requires-Dist: langgraph-runtime-inmem<0.29.0,>=0.28.0
 Requires-Dist: langgraph-sdk>=0.3.5
@@ -34,6 +35,7 @@ Requires-Dist: uuid-utils>=0.12.0
 Requires-Dist: uvicorn>=0.26.0
 Requires-Dist: uvloop>=0.18.0; platform_system != 'Windows'
 Requires-Dist: watchfiles>=0.13
+Requires-Dist: websockets>=13.0
 Requires-Dist: zstandard>=0.23.0
 Description-Content-Type: text/markdown
 
@@ -48,7 +50,7 @@ For production use, see the various [deployment options](https://langchain-ai.gi
 Install the `langgraph-cli` package with the `inmem` extra. Your CLI version must be no lower than `0.1.55`.
 
 ```bash
-pip install -U langgraph-cli[inmem]
+pip install -U "langgraph-cli[inmem]"
 ```
 
 ## Quickstart

{langgraph_api-0.8.7 → langgraph_api-0.9.0.dev1}/README.md

@@ -9,7 +9,7 @@ For production use, see the various [deployment options](https://langchain-ai.gi
 Install the `langgraph-cli` package with the `inmem` extra. Your CLI version must be no lower than `0.1.55`.
 
 ```bash
-pip install -U langgraph-cli[inmem]
+pip install -U "langgraph-cli[inmem]"
 ```
 
 ## Quickstart

{langgraph_api-0.8.7 → langgraph_api-0.9.0.dev1}/benchmark/continuous/uv.lock

@@ -25,14 +25,14 @@ wheels = [
 
 [[package]]
 name = "click"
-version = "8.3.2"
+version = "8.3.3"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "colorama", marker = "sys_platform == 'win32'" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/57/75/31212c6bf2503fdf920d87fee5d7a86a2e3bcf444984126f13d8e4016804/click-8.3.2.tar.gz", hash = "sha256:14162b8b3b3550a7d479eafa77dfd3c38d9dc8951f6f69c78913a8f9a7540fd5", size = 302856, upload-time = "2026-04-03T19:14:45.118Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/bb/63/f9e1ea081ce35720d8b92acde70daaedace594dc93b693c869e0d5910718/click-8.3.3.tar.gz", hash = "sha256:398329ad4837b2ff7cbe1dd166a4c0f8900c3ca3a218de04466f38f6497f18a2", size = 328061, upload-time = "2026-04-22T15:11:27.506Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/e4/20/71885d8b97d4f3dde17b1fdb92dbd4908b00541c5a3379787137285f602e/click-8.3.2-py3-none-any.whl", hash = "sha256:1924d2c27c5653561cd2cae4548d1406039cb79b858b747cfea24924bbc1616d", size = 108379, upload-time = "2026-04-03T19:14:43.505Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/44/c1221527f6a71a01ec6fbad7fa78f1d50dfa02217385cf0fa3eec7087d59/click-8.3.3-py3-none-any.whl", hash = "sha256:a2bf429bb3033c89fa4936ffb35d5cb471e3719e1f3c8a7c3fff0b8314305613", size = 110502, upload-time = "2026-04-22T15:11:25.044Z" },
 ]
 
 [[package]]
@@ -120,25 +120,25 @@ dependencies = [
 
 [package.metadata]
 requires-dist = [
-    { name = "click", specifier = ">=8.3.2" },
+    { name = "click", specifier = ">=8.3.3" },
     { name = "datadog-api-client", specifier = ">=2.0.0" },
     { name = "httpx", specifier = ">=0.27.0" },
-    { name = "langgraph-sdk", specifier = ">=0.2.10" },
+    { name = "langgraph-sdk", specifier = ">=0.3.13" },
     { name = "python-dateutil", specifier = ">=2.8.0" },
     { name = "structlog", specifier = ">=24.1.0" },
 ]
 
 [[package]]
 name = "langgraph-sdk"
-version = "0.3.12"
+version = "0.3.14"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "httpx" },
     { name = "orjson" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/fd/a1/012f0e0f5c9fd26f92bdc9d244756ad673c428230156ef668e6ec7c18cee/langgraph_sdk-0.3.12.tar.gz", hash = "sha256:c9c9ec22b3c0fcd352e2b8f32a815164f69446b8648ca22606329f4ff4c59a71", size = 194932, upload-time = "2026-03-18T22:15:54.592Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/02/f1/134046c20bc4a4a15d410d1d21c9e298a3e9923777b4cc867b8669bc636b/langgraph_sdk-0.3.14.tar.gz", hash = "sha256:acd1674c538e97f3cdaa610f6dd7e34bc9bad30167f0ccc482dcd563325e81f5", size = 198162, upload-time = "2026-05-05T18:40:03.524Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/17/4d/4f796e86b03878ab20d9b30aaed1ad459eda71a5c5b67f7cfe712f3548f2/langgraph_sdk-0.3.12-py3-none-any.whl", hash = "sha256:44323804965d6ec2a07127b3cf08a0428ea6deaeb172c2d478d5cd25540e3327", size = 95834, upload-time = "2026-03-18T22:15:53.545Z" },
+    { url = "https://files.pythonhosted.org/packages/34/96/1c9f9fbfe756ddd850a2585e7f1949d8ebb97fdaa7a5eff8f45ed1314670/langgraph_sdk-0.3.14-py3-none-any.whl", hash = "sha256:68935bf6f4924eda92617a9e5dfb4f4281197508c648cb9d62ff083907607f9d", size = 97028, upload-time = "2026-05-05T18:40:02.099Z" },
 ]
 
 [[package]]
@@ -220,9 +220,9 @@ wheels = [
 
 [[package]]
 name = "urllib3"
-version = "2.6.3"
+version = "2.7.0"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/c7/24/5f1b3bdffd70275f6661c76461e25f024d5a38a46f04aaca912426a2b1d3/urllib3-2.6.3.tar.gz", hash = "sha256:1b62b6884944a57dbe321509ab94fd4d3b307075e0c2eae991ac71ee15ad38ed", size = 435556, upload-time = "2026-01-07T16:24:43.925Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/53/0c/06f8b233b8fd13b9e5ee11424ef85419ba0d8ba0b3138bf360be2ff56953/urllib3-2.7.0.tar.gz", hash = "sha256:231e0ec3b63ceb14667c67be60f2f2c40a518cb38b03af60abc813da26505f4c", size = 433602, upload-time = "2026-05-07T16:13:18.596Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/39/08/aaaad47bc4e9dc8c725e68f9d04865dbcb2052843ff09c97b08904852d84/urllib3-2.6.3-py3-none-any.whl", hash = "sha256:bf272323e553dfb2e87d9bfd225ca7b0f467b919d7bbd355436d3fd37cb0acd4", size = 131584, upload-time = "2026-01-07T16:24:42.685Z" },
+    { url = "https://files.pythonhosted.org/packages/7f/3e/5db95bcf282c52709639744ca2a8b149baccf648e39c8cc87553df9eae0c/urllib3-2.7.0-py3-none-any.whl", hash = "sha256:9fb4c81ebbb1ce9531cce37674bbc6f1360472bc18ca9a553ede278ef7276897", size = 131087, upload-time = "2026-05-07T16:13:17.151Z" },
 ]

{langgraph_api-0.8.7 → langgraph_api-0.9.0.dev1}/benchmark/ramp.js

@@ -1,6 +1,8 @@
 import { sleep } from 'k6';
 import { Counter, Trend } from 'k6/metrics';
-import { randomIntBetween } from 'https://jslib.k6.io/k6-utils/1.2.0/index.js';
+function randomIntBetween(min, max) {
+  return Math.floor(Math.random() * (max - min + 1) + min);
+}
 import { Benchmarks } from './benchmark-runners/dist/benchmarks.js';
 import { get_profile } from './benchmark-runners/dist/benchmark_profiles.js';
 

{langgraph_api-0.8.7 → langgraph_api-0.9.0.dev1}/constraints.txt

@@ -18,9 +18,9 @@ structlog>=24.1.0
 cloudpickle>=3.0.0
 truststore>=0.1
 protobuf>=6.32.1,<7.0.0
-grpcio>=1.78.0,<1.79.0
-grpcio-tools>=1.78.0,<1.79.0
-grpcio-health-checking>=1.78.0,<1.79.0
+grpcio>=1.80.0,<1.81.0
+grpcio-tools>=1.80.0,<1.81.0
+grpcio-health-checking>=1.80.0,<1.81.0
 opentelemetry-api>=0.0.1
 opentelemetry-sdk>=0.0.1
 opentelemetry-exporter-otlp-proto-http>=0.0.1

langgraph_api-0.9.0.dev1/langgraph_api/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.9.0.dev1"

{langgraph_api-0.8.7 → langgraph_api-0.9.0.dev1}/langgraph_api/api/__init__.py

@@ -15,6 +15,7 @@ from starlette.routing import BaseRoute, Route
 from langgraph_api import timing
 from langgraph_api.api.a2a import a2a_routes
 from langgraph_api.api.assistants import assistants_routes
+from langgraph_api.api.event_streaming import event_streaming_routes
 from langgraph_api.api.mcp import mcp_routes
 from langgraph_api.api.meta import meta_info, meta_metrics
 from langgraph_api.api.openapi import get_openapi_spec
@@ -30,7 +31,10 @@ from langgraph_api.config import (
     LANGGRAPH_ENCRYPTION,
     MIGRATIONS_PATH,
 )
-from langgraph_api.feature_flags import IS_POSTGRES_OR_GRPC_BACKEND
+from langgraph_api.feature_flags import (
+    FF_V2_EVENT_STREAMING,
+    IS_POSTGRES_OR_GRPC_BACKEND,
+)
 from langgraph_api.graph import js_bg_tasks
 from langgraph_api.grpc.client import get_shared_client
 from langgraph_api.js.base import is_js_path
@@ -131,6 +135,20 @@ if HTTP_CONFIG:
         protected_routes.extend(mcp_routes)
     if not HTTP_CONFIG.get("disable_a2a"):
         protected_routes.extend(a2a_routes)
+    # ``disable_runs`` also gates event streaming because the v2 transport
+    # exposes run-creating commands (``run.start`` / ``run.cancel`` /
+    # ``run.attach`` over the WS, plus the ``/runs/{run_id}/protocol``
+    # attach route). If an operator hardens a deployment with
+    # ``disable_runs=true``, leaving event streaming open would be a
+    # backdoor that lets clients create runs anyway. ``disable_event_streaming``
+    # is the narrow knob (turn off just v2); ``disable_runs`` is the broad
+    # knob (no run-related functionality at all).
+    if (
+        FF_V2_EVENT_STREAMING
+        and not HTTP_CONFIG.get("disable_runs")
+        and not HTTP_CONFIG.get("disable_event_streaming")
+    ):
+        protected_routes.extend(event_streaming_routes)
 else:
     protected_routes.extend(assistants_routes)
     protected_routes.extend(runs_routes)
@@ -141,6 +159,8 @@ else:
     protected_routes.extend(ui_routes)
     protected_routes.extend(mcp_routes)
     protected_routes.extend(a2a_routes)
+    if FF_V2_EVENT_STREAMING:
+        protected_routes.extend(event_streaming_routes)
 
 
 def _metadata_fn(app_import: str) -> dict[str, str]:

langgraph_api-0.9.0.dev1/langgraph_api/api/event_streaming.py

@@ -0,0 +1,438 @@
+"""V2 event streaming transport routes (thread-centric).
+
+These routes implement the v2 event streaming protocol — see
+:mod:`langgraph_api.event_streaming` for the session/normalizer layer that
+shapes the wire events. Connections are scoped to a thread via the URL
+path; there is no server-side session state across connections.
+
+Endpoints:
+
+* ``POST /threads/{thread_id}/stream/events`` — SSE stream with
+  ``EventStreamRequest`` filter body. Each connection IS the subscription;
+  closing the connection unsubscribes.
+* ``POST /threads/{thread_id}/commands`` — JSON command request/response.
+* ``WebSocket /threads/{thread_id}/stream/events`` — full-duplex commands and events.
+  ``subscription.subscribe`` / ``subscription.unsubscribe`` manage
+  subscriptions for the lifetime of the socket.
+* ``WebSocket /threads/{thread_id}/runs/{run_id}/protocol`` — compatibility
+  route that auto-binds to an existing run on connection.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from collections import deque
+from typing import TYPE_CHECKING, Any
+from uuid import uuid4
+
+import orjson
+import structlog
+from starlette.responses import Response
+from starlette.websockets import WebSocketDisconnect
+
+from langgraph_api.event_streaming.service import ThreadRunManager
+from langgraph_api.event_streaming.session import _is_supported_channel
+from langgraph_api.event_streaming.types import Subscription
+from langgraph_api.feature_flags import IS_POSTGRES_OR_GRPC_BACKEND
+from langgraph_api.route import ApiRoute, ApiWebSocketRoute
+from langgraph_api.serde import json_dumpb
+from langgraph_api.sse import EventSourceResponse
+
+if TYPE_CHECKING:
+    from starlette.requests import Request
+    from starlette.websockets import WebSocket
+
+if IS_POSTGRES_OR_GRPC_BACKEND:
+    from langgraph_api.grpc.ops import Runs, Threads
+else:
+    from langgraph_runtime.ops import Runs, Threads
+
+logger = structlog.stdlib.get_logger(__name__)
+
+
+# Maximum number of recently-delivered ``event_id`` values an SSE
+# connection remembers for dedup. The dedup window only needs to cover
+# the brief race where a single event arrives both via the thread
+# source consumer and via the session's send callback (subscription
+# install handoff); after that, events flow through one path
+# consistently. Cap chosen with ample headroom — a pathological
+# replay storm of 2k events still fits in <50 KB of strings per
+# connection, vs. the unbounded set this replaces.
+_DELIVERED_DEDUP_WINDOW = 2048
+
+
+def _json_response(content: Any, *, status_code: int = 200) -> Response:
+    """JSON response backed by the repo's orjson helper.
+
+    Starlette's default ``JSONResponse`` uses stdlib ``json`` which cannot
+    serialize ``UUID`` / ``datetime`` / ``bytes`` — values that regularly
+    appear in command responses (e.g. ``run_id`` from ``create_valid_run``).
+    Using ``json_dumpb`` matches the serialization used on the event
+    stream and keeps the two surfaces consistent.
+    """
+    return Response(
+        json_dumpb(content),
+        status_code=status_code,
+        media_type="application/json",
+    )
+
+
+def _make_manager(thread_id: str, send_event: Any = None) -> ThreadRunManager:
+    # Auth context is propagated via ``ApiRoute``'s ``with_user`` wrapper
+    # — ops reads it off the context var, so we don't thread it through
+    # the manager explicitly.
+    return ThreadRunManager(
+        thread_id=thread_id,
+        runs=Runs,
+        threads=Threads,
+        send_event=send_event,
+    )
+
+
+# ---------------------------------------------------------------------------
+# POST /threads/{thread_id}/stream/events — SSE event stream
+# ---------------------------------------------------------------------------
+
+
+async def _thread_events(request: Request) -> Response:
+    """SSE stream scoped to a thread.
+
+    Body is an ``EventStreamRequest``:
+
+        {
+          "channels": ["values", "messages", ...],
+          "namespaces": [["ns1"], ["ns2", "child"]],   // optional
+          "depth": 2,                                     // optional
+          "since": 42                                     // optional seq
+        }
+
+    On reconnect, clients pass the last ``seq`` they received as
+    ``since`` in the body. Buffered events with ``seq > since`` are
+    replayed before the stream goes live. The endpoint is POST-only, so
+    browser-native ``EventSource`` auto-resume (``Last-Event-ID``)
+    doesn't apply — clients drive resume explicitly via the body.
+
+    The filter applies for the lifetime of the connection; closing the
+    connection unsubscribes. No state is persisted server-side beyond the
+    connection.
+    """
+    thread_id = request.path_params["thread_id"]
+    try:
+        body = orjson.loads(await request.body())
+    except Exception:
+        return _json_response({"detail": "Invalid JSON body"}, status_code=400)
+
+    channels = body.get("channels") if isinstance(body, dict) else None
+    if not isinstance(channels, list) or not channels:
+        return _json_response(
+            {"detail": "channels is required and must be a non-empty array"},
+            status_code=400,
+        )
+    # Reject unknown channel names up front — otherwise the SSE stream
+    # would stay open indefinitely with no events flowing, confusing
+    # clients that expected a subscription-level error. Aligns the
+    # HTTP endpoint with the ``subscription.subscribe`` command which
+    # already short-circuits with ``invalid_argument``. ``custom:<name>``
+    # passes through ``_is_supported_channel`` unchanged.
+    bad: list[str] = []
+    validated: list[str] = []
+    for c in channels:
+        if not isinstance(c, str):
+            bad.append(repr(c))
+            continue
+        if not _is_supported_channel(c):
+            bad.append(c)
+            continue
+        validated.append(c)
+    if bad:
+        return _json_response(
+            {
+                "detail": (
+                    "channels contains unsupported entries: "
+                    + ", ".join(bad[:5])
+                    + ". Allowed: values, updates, messages, tools, custom, "
+                    "lifecycle, input, tasks, or any `custom:<name>`."
+                )
+            },
+            status_code=400,
+        )
+    channels = validated
+
+    namespaces = body.get("namespaces") if isinstance(body, dict) else None
+    if not isinstance(namespaces, list):
+        namespaces = None
+    else:
+        # only accept list[list[str]]
+        filtered_ns: list[list[str]] = []
+        for ns in namespaces:
+            if isinstance(ns, list) and all(isinstance(seg, str) for seg in ns):
+                filtered_ns.append(ns)
+        namespaces = filtered_ns or None
+
+    depth = body.get("depth") if isinstance(body, dict) else None
+    # ``bool`` is a subclass of ``int``, so a JSON ``"depth": false`` would
+    # otherwise fall through as ``depth=0`` ("only the exact prefix
+    # namespace, no deeper") and silently mute every nested-subgraph
+    # event. Treat any non-int (including bool) as "no depth limit".
+    if not isinstance(depth, int) or isinstance(depth, bool) or depth < 0:
+        depth = None
+
+    raw_since = body.get("since") if isinstance(body, dict) else None
+    # Reject ``bool`` explicitly — ``isinstance(True, int)`` is ``True``
+    # so a JSON ``"since": true`` would otherwise pass as ``since=1``
+    # and silently skip the first buffered event on reconnect.
+    since: int | None = (
+        raw_since
+        if isinstance(raw_since, int)
+        and not isinstance(raw_since, bool)
+        and raw_since >= 0
+        else None
+    )
+
+    # Bounded LRU dedup: ``recent_eids`` is the eviction order, ``delivered``
+    # is the O(1) membership view. When the deque hits its cap, the oldest
+    # entry rolls off; we mirror that on ``delivered`` to keep them in sync.
+    recent_eids: deque[str] = deque(maxlen=_DELIVERED_DEDUP_WINDOW)
+    delivered: set[str] = set()
+    pending_events: list[dict[str, Any]] = []
+    flush_pending = asyncio.Event()
+
+    async def on_event(event: dict[str, Any]) -> None:
+        eid = event.get("event_id")
+        if eid is None or eid in delivered:
+            return
+        # Guard against events with seq <= since slipping through (e.g.
+        # events delivered via the session's send callback before the
+        # subscription is installed with replay).
+        if since is not None and event.get("seq", 0) <= since:
+            return
+        if len(recent_eids) == recent_eids.maxlen:
+            delivered.discard(recent_eids[0])
+        recent_eids.append(eid)
+        delivered.add(eid)
+        pending_events.append(event)
+        flush_pending.set()
+
+    manager = _make_manager(thread_id, send_event=on_event)
+
+    filter_sub = Subscription(
+        id=str(uuid4()),
+        channels=set(channels),
+        namespaces=namespaces,
+        depth=depth,
+        active=False,
+    )
+    await logger.adebug(
+        "Installing event streaming subscription",
+        thread_id=thread_id,
+        subscription_id=filter_sub.id,
+        channels=sorted(filter_sub.channels),
+        depth=depth,
+        since=since,
+    )
+
+    manager.install_subscription(filter_sub)
+    # ``since`` is enforced by ``on_event`` above as a seq filter on
+    # outbound events; the thread-level reader always replays from the
+    # beginning so namespace-scoped projections see history. See
+    # ``ThreadRunManager.start_thread_stream`` for the rationale.
+    manager.start_thread_stream()
+
+    async def body_iter():
+        try:
+            while True:
+                # Race ``flush_pending`` against the thread-stream consumer
+                # ending. If the consumer dies (transient join_event_streaming
+                # error, or normal shutdown), we want this loop to exit
+                # rather than wedge forever waiting for events that will
+                # never arrive.
+                flush_task = asyncio.create_task(flush_pending.wait())
+                done_task = asyncio.create_task(manager.wait_for_thread_stream_end())
+                try:
+                    done, _pending = await asyncio.wait(
+                        {flush_task, done_task},
+                        return_when=asyncio.FIRST_COMPLETED,
+                    )
+                finally:
+                    for p in (flush_task, done_task):
+                        if not p.done():
+                            p.cancel()
+                            with contextlib.suppress(asyncio.CancelledError, Exception):
+                                await p
+                stream_finished = done_task in done
+                # Always drain whatever was buffered before exiting so a
+                # final batch that arrived alongside the consumer's exit
+                # still reaches the client.
+                flush_pending.clear()
+                events = pending_events[:]
+                pending_events.clear()
+                for event in events:
+                    # The wire ``event_id`` (inside the JSON body) carries
+                    # the durable upstream Redis stream entry id used by
+                    # the client's ``seenEventIds`` for cross-session
+                    # dedup. The SSE ``id:`` field carries the protocol
+                    # ``seq`` (session-local monotonic int) so server
+                    # logs and traces can correlate against the body
+                    # ``since`` cursor a reconnecting client sends.
+                    sse_id = event.get("seq")
+                    method = event.get("method", "event")
+                    yield (
+                        method.encode() if isinstance(method, str) else b"event",
+                        json_dumpb(event),
+                        str(sse_id).encode() if isinstance(sse_id, int) else None,
+                    )
+                if stream_finished:
+                    break
+        finally:
+            await manager.close()
+
+    return EventSourceResponse(body_iter())
+
+
+# ---------------------------------------------------------------------------
+# POST /threads/{thread_id}/commands — JSON command
+# ---------------------------------------------------------------------------
+
+
+async def _thread_command(request: Request) -> Response:
+    """Handle a single protocol command scoped to a thread.
+
+    Commands are stateless in the HTTP transport: a fresh manager is
+    created, the command is dispatched, and results are returned. For
+    ``run.start`` this creates/resumes a run; subsequent event streaming
+    happens over a separate ``POST .../stream`` connection.
+    """
+    thread_id = request.path_params["thread_id"]
+    try:
+        payload = orjson.loads(await request.body())
+    except Exception:
+        return _json_response({"detail": "Invalid JSON body"}, status_code=400)
+
+    if (
+        not isinstance(payload, dict)
+        or not isinstance(payload.get("id"), int)
+        or not isinstance(payload.get("method"), str)
+    ):
+        await logger.awarning(
+            "Rejected malformed event streaming command",
+            thread_id=thread_id,
+            payload_id=payload.get("id") if isinstance(payload, dict) else None,
+            payload_method=payload.get("method") if isinstance(payload, dict) else None,
+            payload_type=type(payload).__name__,
+        )
+        return _json_response(
+            {
+                "type": "error",
+                "id": payload.get("id") if isinstance(payload, dict) else None,
+                "error": "invalid_argument",
+                "message": "Protocol commands must include an integer id and string method.",
+            },
+            status_code=400,
+        )
+
+    manager = _make_manager(thread_id)
+    try:
+        resp = await manager.handle_command(payload)
+        return _json_response(resp)
+    finally:
+        # Commands that create runs (e.g. run.start) leave the run executing in
+        # the background on the worker queue. Downstream clients observe it via
+        # the thread-level ``POST .../stream/events`` source.
+        await manager.close()
+
+
+# ---------------------------------------------------------------------------
+# WebSocket /threads/{thread_id}/stream/events
+# ---------------------------------------------------------------------------
+
+
+async def _thread_websocket(websocket: WebSocket) -> None:
+    """Full-duplex protocol connection scoped to a thread.
+
+    Supports ``run.start``, ``input.respond``, ``subscription.subscribe``,
+    ``subscription.unsubscribe``, ``agent.getTree``.
+    """
+    thread_id = websocket.path_params["thread_id"]
+    await websocket.accept()
+
+    async def ws_send_event(event: dict[str, Any]) -> None:
+        await websocket.send_text(orjson.dumps(event).decode("utf-8"))
+
+    manager = _make_manager(thread_id, send_event=ws_send_event)
+    manager.start_thread_stream()
+
+    # Watchdog: when the thread-stream consumer ends (transient
+    # ``join_event_streaming`` failure or normal shutdown), close the socket so
+    # the client sees a clean disconnect instead of an open connection
+    # that will never deliver another event. ``receive_text`` below
+    # raises ``WebSocketDisconnect`` once the close lands, exiting the
+    # loop through its existing handler.
+    async def _stream_watchdog() -> None:
+        await manager.wait_for_thread_stream_end()
+        with contextlib.suppress(Exception):
+            await websocket.close(code=1011, reason="thread stream ended")
+
+    watchdog = asyncio.create_task(_stream_watchdog())
+
+    try:
+        while True:
+            raw = await websocket.receive_text()
+            try:
+                payload = orjson.loads(raw)
+            except Exception:
+                await websocket.send_json(
+                    {
+                        "type": "error",
+                        "id": None,
+                        "error": "invalid_argument",
+                        "message": "Protocol commands must be valid JSON.",
+                    }
+                )
+                continue
+
+            if (
+                not isinstance(payload, dict)
+                or not isinstance(payload.get("id"), int)
+                or not isinstance(payload.get("method"), str)
+            ):
+                await websocket.send_json(
+                    {
+                        "type": "error",
+                        "id": payload.get("id") if isinstance(payload, dict) else None,
+                        "error": "invalid_argument",
+                        "message": "Protocol commands must include an integer id and string method.",
+                    }
+                )
+                continue
+
+            response = await manager.handle_command(payload)
+            await websocket.send_text(orjson.dumps(response).decode("utf-8"))
+    except WebSocketDisconnect:
+        pass
+    except Exception:
+        logger.exception("Protocol WebSocket error")
+    finally:
+        watchdog.cancel()
+        with contextlib.suppress(asyncio.CancelledError, Exception):
+            await watchdog
+        await manager.close()
+
+
+# ---------------------------------------------------------------------------
+# Route list
+# ---------------------------------------------------------------------------
+
+event_streaming_routes: list[ApiRoute | ApiWebSocketRoute] = [
+    ApiRoute(
+        "/threads/{thread_id}/stream/events",
+        _thread_events,
+        methods=["POST"],
+    ),
+    ApiRoute(
+        "/threads/{thread_id}/commands",
+        _thread_command,
+        methods=["POST"],
+    ),
+    ApiWebSocketRoute("/threads/{thread_id}/stream/events", _thread_websocket),
+]