The `version="v3"` overloads of `stream_events`/`astream_events`
returned `Any`, and `GraphRunStream`/`AsyncGraphRunStream` attached
native projections via a runtime `setattr` loop invisible to type
checkers.
- Return `GraphRunStream` / `Awaitable[AsyncGraphRunStream]` from the v3
overloads.
- Declare the always-registered native projections (`values`,
`messages`, `lifecycle`, `subgraphs`) as typed class attributes on both
run streams.
- Add `assert_type` checks in `test_stream_events_v3.py`.
Opt-in native projections (`updates`, `custom`, `checkpoints`, `debug`,
`tasks`) are only present when their transformer is registered, so they
remain reached via `extensions[...]` rather than annotated as
always-present.
Closes#8038
## Description
The `ensure_config` merge introduced in #7926 caused a child graph
invoked inside a parent node to inherit the parent task's
`checkpoint_ns` from the ambient run context
(`var_child_runnable_config`), so the child's checkpoints were written
under an unreadable namespace and re-ran from scratch each turn (#8038).
The first explicitly passed `configurable` that carries a checkpoint
coordinate (a `thread_id`, or any
`checkpoint_ns`/`checkpoint_id`/`checkpoint_map`) now replaces the
ambient one, while subsequent explicit configs still shallow-merge —
preserving #7926's `with_config(...)` semantics.
## Contract
`ensure_config` merges an explicit `configurable` over the ambient run
context (`var_child_runnable_config`) with one rule: **an explicit
`configurable` that supplies its own checkpoint coordinate addresses its
own checkpoint lineage, so the ambient `configurable` is dropped rather
than merged over.** Coordinate keys are `thread_id`, `checkpoint_ns`,
`checkpoint_id`, and `checkpoint_map` (grouped as
`_CHECKPOINT_COORDINATE_KEYS`). A non-coordinate `configurable` keeps
the ambient and shallow-merges over it.
Below, each case shows the parent/child graph wiring that triggers it
and the resulting namespacing. The child is always a compiled subgraph
invoked from inside a parent node.
### 1. Subgraph invoked with no new config → ambient inherited
```python
child = StateGraph(ChildState).add_node("n", child_node).add_edge(START, "n").compile(checkpointer=checkpointer)
def parent_node(state):
child.invoke({}, config=None) # no explicit configurable
return {"result": "ok"}
parent = StateGraph(ParentState).add_node("p", parent_node).add_edge(START, "p").compile(checkpointer=checkpointer)
parent.invoke({"result": ""}, config={"configurable": {"thread_id": "parent"}})
```
Child inherits the parent task's `checkpoint_ns` (`p:<parent-task>`);
its checkpoints are written as a discoverable child of the parent run.
Pre-#7926 behavior, unchanged.
### 2. Subgraph invoked with a new thread_id → ambient dropped
```python
child = StateGraph(ChildState).add_node("n", child_node).add_edge(START, "n").compile(checkpointer=checkpointer)
child_config = {"configurable": {"thread_id": str(uuid4())}}
def parent_node(state):
child.invoke({}, config=child_config) # explicit new thread_id
return {"result": "ok"}
parent = StateGraph(ParentState).add_node("p", parent_node).add_edge(START, "p").compile(checkpointer=checkpointer)
parent.invoke({"result": ""}, config={"configurable": {"thread_id": "parent"}})
```
Child starts its own lineage on `child_config`'s thread; `checkpoint_ns
== ""`; `child.get_state(child_config)` reads back state across repeated
parent turns. Fixes#8038.
### 3. Subgraph invoked with the same thread_id as parent → ambient
still dropped
```python
child = StateGraph(ChildState).add_node("n", child_node).add_edge(START, "n").compile(checkpointer=checkpointer)
def parent_node(state):
# reuses the parent's thread_id as the child's own
child.invoke({}, config={"configurable": {"thread_id": state["parent_thread"]}})
return {"result": "ok"}
parent = StateGraph(ParentState).add_node("p", parent_node).add_edge(START, "p").compile(checkpointer=checkpointer)
parent_thread = str(uuid4())
parent.invoke({"parent_thread": parent_thread, "result": ""}, config={"configurable": {"thread_id": parent_thread}})
```
Child addresses its own root namespace on the shared thread;
`checkpoint_ns == ""`. The parent task's `checkpoint_ns` must not leak
in, or `child.get_state({"configurable": {"thread_id": parent_thread}})`
returns empty state and the child re-runs from scratch each turn.
### 4. Subagent invoked with a non-coordinate key only → ambient
inherited
```python
child = StateGraph(ChildState).add_node("n", child_node).add_edge(START, "n").compile(checkpointer=checkpointer)
def parent_node(state):
# ls_agent_type is not a checkpoint coordinate, so ambient is kept
child.invoke({}, config={"configurable": {"ls_agent_type": "subagent"}})
return {"result": "ok"}
parent = StateGraph(ParentState).add_node("p", parent_node).add_edge(START, "p").compile(checkpointer=checkpointer)
parent.invoke({"result": ""}, config={"configurable": {"thread_id": "parent"}})
```
Child remains a discoverable child of the parent run; ambient
`thread_id` and `checkpoint_ns` preserved (deepagents `task` tool
pattern).
### 5. with_config(...) + invoke-time thread_id → ambient dropped, then
merged
```python
# child compiled with a non-coordinate configurable via with_config
child = (
StateGraph(ChildState)
.add_node("n", child_node)
.add_edge(START, "n")
.compile(checkpointer=checkpointer)
.with_config({"configurable": {"ls_agent_type": "root"}})
)
def parent_node(state):
# invoke-time config supplies the thread_id; with_config's ls_agent_type survives
child.invoke({}, config={"configurable": {"thread_id": "child"}})
return {"result": "ok"}
parent = StateGraph(ParentState).add_node("p", parent_node).add_edge(START, "p").compile(checkpointer=checkpointer)
parent.invoke({"result": ""}, config={"configurable": {"thread_id": "parent"}})
```
First coordinate-bearing config (`thread_id`) drops the ambient;
subsequent explicit configs still shallow-merge, so `ls_agent_type`
survives alongside `thread_id`. Preserves #7926 `with_config(...)`
semantics.
### Regression note
Cases 1, 4, and 5 are the pre-#7926 behavior and are preserved
unchanged. Cases 2 and 3 fix the regression introduced by #7926: an
explicit `thread_id` resets the ambient even when it equals the ambient
thread id, because a child reusing the parent's thread id still
addresses its own root namespace on that thread, not the parent task's.
## Self-Hosted Release Note
Fix regression where a nested subgraph with its own `thread_id` invoked
inside a parent node lost its persisted state across turns.
## Test Plan
- [x] `pytest tests/test_subgraph_persistence.py -k
test_child_with_own_thread_id_keeps_namespace` (case 2)
- [x] `pytest tests/test_utils.py -k
ensure_config_explicit_configurable_replaces_ambient` (case 2)
- [x] `pytest tests/test_utils.py -k
ensure_config_ambient_inherited_when_no_explicit_configurable` (case 1)
- [x] `pytest tests/test_utils.py -k
ensure_config_non_coordinate_config_keeps_ambient_checkpoint_ns` (case
4)
- [x] `pytest tests/test_utils.py -k
ensure_config_explicit_configurables_still_merge_over_ambient` (case 5)
- [x] `pytest tests/test_utils.py -k
ensure_config_same_thread_id_still_clears_ambient` (case 3)
Made by [Open SWE](https://openswe.vercel.app)
---------
Co-authored-by: Nick Hollon <274035459+nick-hollon-lc@users.noreply.github.com>
Co-authored-by: open-swe[bot] <open-swe@users.noreply.github.com>
## Description
v3 event streaming's `stream.abort()` (sync and async) only closed the
mux and stopped pumping, leaving the underlying `astream`/`stream`
generator — and any running subgraphs — alive until they finished,
burning resources. The fix closes the underlying graph iterator so
`GeneratorExit` propagates into in-flight nodes/subgraphs and cancels
them, matching v2's `aclose()` behavior. Fixes#8029.
## Release Note
v3 streaming `stream.abort()` now cancels running subgraphs instead of
letting them run to completion.
## Test Plan
- [x] `TEST="tests/test_pregel_stream_events_v3.py -k abort" make test`
(new `test_abort_cancels_running_subgraph` asserts the looping subgraph
stops after abort)
Made by [Open SWE](https://openswe.vercel.app)
---------
Co-authored-by: Nick Hollon <274035459+nick-hollon-lc@users.noreply.github.com>
Co-authored-by: open-swe[bot] <open-swe@users.noreply.github.com>
## Problem
Fixes#7953.
The v3 SSE and WebSocket stream transports build their default paths by
interpolating `thread_id` directly into the URL:
```python
self._commands_url = commands_path or f"/threads/{thread_id}/commands"
self._stream_url = stream_path or f"/threads/{thread_id}/stream/events"
```
This skips the `_quote_path_param` escaping that the rest of the SDK
adopted in #7893. A `thread_id` containing reserved characters or
dot-segments is then normalized by the HTTP/WebSocket stack before
transmission. For example, `thread_id = "../assistants/abc"`:
| | before |
|---|---|
| constructed | `/threads/../assistants/abc/commands` |
| wire path | `/assistants/abc/commands` |
So the value stops being one opaque identifier under
`/threads/{thread_id}/...` and silently hits a different resource.
## Fix
Reuse the existing `_quote_path_param` helper for the **default** paths
in all four transports (`http`, `sync_http`, `ws`, `sync_ws`). Explicit
`commands_path` / `stream_path` overrides are left untouched, so callers
that pass their own paths opt out of encoding as before.
`_quote_path_param("../assistants/abc")` → `..%2Fassistants%2Fabc`,
which the HTTP/WS stack no longer collapses.
## Tests
Adds `tests/streaming/test_transport_path_encoding.py` covering all four
transports:
- default `_commands_url` / `_stream_url` / `_stream_path` are
percent-encoded,
- the actual SSE wire path (async + sync) stays under `/threads/`,
- the built WebSocket URL (async + sync) stays under `/threads/`,
- explicit path overrides are left untouched.
`make format`, `make lint`, and `make test` all pass in `libs/sdk-py`
(491 passed).
## Summary
Refactors the four (now five) sdk-py streaming projections into
reusable, transport-agnostic `Decoder` classes and adds a new
`interleave_projections(channels)` method to `AsyncThreadStream` and
`SyncThreadStream` that drives multiple decoders from one shared
subscription, yielding `(channel_name, item)` tuples in arrival order
(the SDK analog of local `GraphRunStream.interleave`).
- **New `langgraph_sdk/stream/decoders.py`**: pure `feed(event) ->
Iterable[item]` state machines — `ValuesDecoder`, `MessagesDecoder`,
`ToolCallsDecoder`, `SubgraphsDecoder`, `ExtensionsDecoder` — behind a
`Decoder` Protocol. No subscription/queue/thread access.
- **Projection migration (async + sync)**: the five existing projections
now delegate their per-event logic to the decoders. Behavior-preserving
— the existing test suite is the regression net. Thread-coupled side
effects (active-stream registration, terminal-error-on-close, root-inbox
forwarding) stay in the projection wrappers; sync messages/tool_calls
keep their pre-dispatch contract (handle/stream resolved on yield) via a
FIFO-head buffer.
- **`interleave_projections`**: flat-namespace channel list (built-ins +
extension names), `tool_calls`↔`tools` wire mapping, subgraphs fed every
event, extensions keyed by bare name.
### Notable
- Fixes a latent sync bug surfaced by the refactor: two tool calls /
messages whose events interleave previously dropped the second; both now
surface. Locked in with a regression test.
- `Decoder.feed` takes `Mapping[str, Any]` (read-only), so the Protocol
is load-bearing in both stream files.
### Deferred (not in this PR)
- Wiring `RemoteGraph._RemoteGraphRunStream.interleave` to
`interleave_projections` (gated on #7927).
- Migrating the handle-scoped projections (`_Handle*Projection`) to the
decoders — hence the small, verified-identical helper duplication
between `decoders.py` and `_async/stream.py`.
- `interleave_projections` handles aren't registered for thread-close
cleanup (additive follow-up).
## Test Plan
- [x] `make test` in `libs/sdk-py` — 464 passed, 0 failures
- [x] `make format` / `make lint` (ruff + ty) clean
- [x] Per-decoder unit tests in `tests/streaming/test_decoders.py`
- [x] `interleave_projections` tests (single-channel, multi-channel
arrival order, builtin+extension mix, tool_calls public-name, subgraphs
discovery) async + sync
- [x] Existing projection suites pass unchanged (regression net for the
migration)
## Summary
- Adds `stream_events(version="v3")` and `astream_events(version="v3")`
to `RemoteGraph`, matching the local `CompiledStateGraph` surface and
unblocking polymorphic v3 streaming over `Graph | RemoteGraph`.
- Implementation is a thin adapter
(`libs/langgraph/langgraph/pregel/_remote_run_stream.py`) that wraps the
v3 SDK's `AsyncThreadStream` / `SyncThreadStream` and duck-types
`GraphRunStream` / `AsyncGraphRunStream`. No coupling to local v3 mux
internals.
- `v1` / `v2` paths unchanged. `astream_events(version='v1'|'v2')` still
raises `NotImplementedError` (separate gap).
### Scope decisions baked into this PR
- Unsupported v3 kwargs hard-reject at dispatch with
`NotImplementedError`: `control`, `transformers`, `interrupt_before`,
`interrupt_after`, and any unknown `**kwargs`. Server / SDK don't plumb
these through v3 yet; easy to lift later.
- Sync `interleave()` raises `NotImplementedError` pointing callers at
`astream_events`. Real sync interleave would need drainer threads;
deferred since most sync RemoteGraph callers just iterate raw events.
- Async `interleave()` is best-effort ordering (client receive order),
documented as a divergence from local v3's monotonic stamp ordering.
- Adapter `interrupted` / `interrupts` properties are **non-blocking**
snapshots of the SDK's current state. This differs from local
`(Async)GraphRunStream.interrupted`, which pump-drives the run to
terminal before returning. Callers needing a wait-for-interrupt pattern
should drain a projection (e.g., `interleave('values')`) until the SDK's
paused sentinel fires. Documented in the adapter docstrings.
### Audit of impact
Existing RemoteGraph callers in this org all use the v2 `.stream()` /
`.astream()` path (deepagents production wrapper, langgraph-api test
graphs, langgraph-supervisor TS type guard). **Zero callers** use
`stream_events` / `astream_events` on RemoteGraph today, so the new v3
methods are net-new surface — no risk of breaking existing consumers.
### Out of scope (follow-ups)
- Bumping `libs/langgraph/pyproject.toml`'s `langgraph-sdk` constraint
from `<0.4.0` to `<0.5.0`. Deferred until 0.4.0 publishes to PyPI; dev
resolution unaffected via the editable workspace dep.
- Real `astream_events(version='v1'|'v2')` implementation.
- Server-side plumbing for `control` / `interrupt_before` /
`interrupt_after` on v3 runs.
- Sync `interleave()` via drainer threads.
## Test plan
- [x] \`make test\` in \`libs/langgraph/\`: 1874 passed, 4 skipped (43
new in \`test_remote_graph_v3.py\`)
- [x] \`make lint\` in \`libs/langgraph/\`: ruff + mypy clean
- [x] \`pytest -m integration
tests/integration/test_remote_graph_v3.py\` in \`libs/sdk-py/\` against
the docker stack: 4/4 passed in 1.35s
- [x] Manual smoke: \`RemoteGraph('tools_agent',
url='http://localhost:2024').astream_events(..., version='v3')\`
end-to-end against the v3 integration api
- [x] Existing RemoteGraph v2 tests untouched (31 passed, 3 skipped with
docker up)
- [x] Will need rebase after \`langgraph-sdk 0.4.0\` lands on PyPI and
the version constraint is bumped in a separate PR
## Summary
Wraps every caller-supplied identifier (thread_id, assistant_id, run_id,
cron_id, checkpoint_id, namespace) interpolated into request URL paths
with `urllib.parse.quote(safe="")` via a new `_quote_path_param` helper.
All-dot strings are encoded as `%2E` triplets so they aren't collapsed
by httpx's client-side path normalization. Helper raises `TypeError` for
None/bytes inputs.
## Test plan
- [x] `make format` / `make lint` / `make test` from `libs/sdk-py`
## Summary
Restricts lc:2 JSON envelope revival in `JsonPlusSerializer` to the
default constructor; the `method` field is now ignored. Adds a
`logger.warning` when the default constructor raises so legacy payloads
that previously fell back to `construct(**kwargs)` are observable
instead of silently degrading.
## Test plan
- [x] `make format` / `make lint` / `make test` from `libs/checkpoint`
