The agent engineering platform.
Python agentsaiai-agentsanthropicchatgptdeepagentsenterpriseframeworkgeminigenerative-ailangchainlanggraphllmmultiagentopen-sourceopenaipydanticpythonragtypescript
feat(core,langchain,standard-tests): read `tool-call-delta` in stream consumers (#41246)
Richard Scarrott560a5f2f8abd
diff --git a/libs/core/langchain_core/language_models/chat_model_stream.py b/libs/core/langchain_core/language_models/chat_model_stream.pyindex 612a6faf34..21f5374870 100644--- a/libs/core/langchain_core/language_models/chat_model_stream.py+++ b/libs/core/langchain_core/language_models/chat_model_stream.py@@ -29,6 +29,7 @@ if TYPE_CHECKING:from langchain_protocol.protocol import (ContentBlockDeltaData,ContentBlockFinishData,+ ContentBlockStartData,FinalizedContentBlock,InvalidToolCall,MessageFinishData,@@ -591,6 +592,8 @@ class _ChatModelStreamBase:self._text_per_block: dict[int, str] = {}self._reasoning_per_block: dict[int, str] = {}self._tool_call_chunks: dict[int, dict[str, Any]] = {}+ # Calls whose args stopped extending previous deltas; they yield no more deltas.+ self._quiet_tool_calls: set[int] = set()self._tool_calls_acc: list[ToolCall] = []self._invalid_tool_calls_acc: list[InvalidToolCall] = []self._server_tool_call_chunks: dict[int, dict[str, Any]] = {}@@ -672,6 +675,8 @@ class _ChatModelStreamBase:event_type = event.get("event")if event_type == "message-start":self._push_message_start(cast("MessageStartData", event))+ elif event_type == "content-block-start":+ self._push_content_block_start(cast("ContentBlockStartData", event))elif event_type == "content-block-delta":self._push_content_block_delta(cast("ContentBlockDeltaData", event))elif event_type == "content-block-finish":@@ -680,7 +685,6 @@ class _ChatModelStreamBase:self._finish(cast("MessageFinishData", event))elif event_type == "error":self.fail(RuntimeError(event.get("message", "Unknown error")))- # content-block-start is informational — no accumulation needed# -- Internal push API (called by dispatch) ----------------------------@@ -695,6 +699,53 @@ class _ChatModelStreamBase:if message_id:self._message_id = message_id+ def _push_content_block_start(self, data: ContentBlockStartData) -> None:+ """Process a `content-block-start` event.++ Seeds the chunk stores for tool-call blocks. `tool-call-delta`+ events don't repeat the call's `id` / `name`, or whether it is a+ client or server call, so the start is the only place to learn+ them. Other blocks need nothing from their start.+ """+ block = _event_content_block(data)+ idx = data.get("index")+ if block is None or idx is None:+ return+ btype = block.get("type")+ if btype == "tool_call_chunk":+ _merge_block_delta_into_store(self._tool_call_chunks, idx, dict(block))+ args = block.get("args")+ if isinstance(args, str) and args:+ self._push_tool_call_chunk(idx, args)+ elif btype == "server_tool_call_chunk":+ _merge_block_delta_into_store(+ self._server_tool_call_chunks, idx, dict(block)+ )++ def _push_tool_call_chunk(+ self, idx: int, args: str, *, provider_index: int | str | None = None+ ) -> None:+ """Push a `ToolCallChunk` delta for the client tool call at `idx`.++ Deltas don't always repeat `id` / `name`, so each item takes them+ from the call's store, letting consumers tell parallel calls apart.+ `provider_index` is the delta's own provider `index`, for deltas+ that carry one without it being kept in the store.+ """+ if idx in self._quiet_tool_calls:+ return+ chunk = self._tool_call_chunks[idx]+ item: ToolCallChunk = {+ "type": "tool_call_chunk",+ "id": chunk.get("id"),+ "name": chunk.get("name"),+ "args": args,+ }+ index = chunk.get("index", provider_index)+ if index is not None:+ item["index"] = index+ self._tool_calls_proj.push(item)+def _push_content_block_delta(self, data: ContentBlockDeltaData) -> None:"""Process a `content-block-delta` event."""delta = _event_delta(data)@@ -731,16 +782,16 @@ class _ChatModelStreamBase:idx = data.get("index")if idx is None:idx = tcc.get("index", len(self._tool_call_chunks)) # type: ignore[unreachable]+ held = self._tool_call_chunks.get(idx, {}).get("args") or ""_merge_block_delta_into_store(self._tool_call_chunks, idx, dict(tcc))- chunk_block: ToolCallChunk = {- "type": "tool_call_chunk",- "id": tcc.get("id"),- "name": tcc.get("name"),- "args": tcc.get("args"),- }- if "index" in tcc:- chunk_block["index"] = tcc["index"]- self._tool_calls_proj.push(chunk_block)+ # `block-delta` replaces `args` with a snapshot (older+ # cores); `.tool_calls` yields only the part it adds.+ args = tcc.get("args")+ if isinstance(args, str):+ if not args.startswith(held):+ self._quiet_tool_calls.add(idx)+ elif len(args) > len(held):+ self._push_tool_call_chunk(idx, args[len(held) :])elif btype == "server_tool_call_chunk":stcc = cast("ServerToolCallChunk", fields)idx = data.get("index")@@ -751,6 +802,23 @@ class _ChatModelStreamBase:idx,dict(stcc),)+ elif dtype == "tool-call-delta":+ # Appends to the call's args. The call's start says+ # whether it is a client or server call; a delta whose start+ # this stream never saw (say, trimmed from a replay window)+ # is left to `content-block-finish`, which carries the call.+ delta_args = delta.get("args")+ if event_idx is None or not isinstance(delta_args, str) or not delta_args:+ return+ if event_idx in self._tool_call_chunks:+ _merge_chunk_into_store(+ self._tool_call_chunks, event_idx, {"args": delta_args}+ )+ self._push_tool_call_chunk(event_idx, delta_args)+ elif event_idx in self._server_tool_call_chunks:+ _merge_chunk_into_store(+ self._server_tool_call_chunks, event_idx, {"args": delta_args}+ )elif dtype == "legacy-block-delta":fields = delta.get("fields")if not isinstance(fields, dict):@@ -762,15 +830,11 @@ class _ChatModelStreamBase:if idx is None:idx = tcc.get("index", len(self._tool_call_chunks)) # type: ignore[unreachable]_merge_chunk_into_store(self._tool_call_chunks, idx, dict(tcc))- legacy_chunk_block: ToolCallChunk = {- "type": "tool_call_chunk",- "id": tcc.get("id"),- "name": tcc.get("name"),- "args": tcc.get("args"),- }- if "index" in tcc:- legacy_chunk_block["index"] = tcc["index"]- self._tool_calls_proj.push(legacy_chunk_block)+ legacy_args = tcc.get("args")+ if legacy_args:+ self._push_tool_call_chunk(+ idx, legacy_args, provider_index=tcc.get("index")+ )elif btype == "server_tool_call_chunk":stcc = cast("ServerToolCallChunk", fields)idx = data.get("index")@@ -786,9 +850,13 @@ class _ChatModelStreamBase:# content-block finish event; there is no dedicated projection.returnelse:- # Transitional legacy path for old `content_block` deltas that- # should not be reachable after `_event_delta` conversion, kept- # here for custom in-tree test fixtures or third-party emitters.+ # Unknown delta variants land here and are ignored, as the+ # protocol requires; `content-block-finish` still carries the+ # complete block. The one exception is an event that also+ # carries a legacy `content_block`: a transitional path for+ # old deltas that should not be reachable after `_event_delta`+ # conversion, kept for custom test fixtures or third-party+ # emitters.block = data.get("content_block")if not isinstance(block, dict):return@@ -800,15 +868,11 @@ class _ChatModelStreamBase:if idx is None:idx = tcc.get("index", len(self._tool_call_chunks)) # type: ignore[unreachable]_merge_chunk_into_store(self._tool_call_chunks, idx, dict(tcc))- fallback_chunk_block: ToolCallChunk = {- "type": "tool_call_chunk",- "id": tcc.get("id"),- "name": tcc.get("name"),- "args": tcc.get("args"),- }- if "index" in tcc:- fallback_chunk_block["index"] = tcc["index"]- self._tool_calls_proj.push(fallback_chunk_block)+ fallback_args = tcc.get("args")+ if fallback_args:+ self._push_tool_call_chunk(+ idx, fallback_args, provider_index=tcc.get("index")+ )def _resolve_block_text(self, idx: int | None, full_text: str) -> str:"""Return authoritative text for a single text block at `idx`.diff --git a/libs/core/tests/unit_tests/language_models/test_chat_model_stream.py b/libs/core/tests/unit_tests/language_models/test_chat_model_stream.pyindex 534623bc9b..527c3f0722 100644--- a/libs/core/tests/unit_tests/language_models/test_chat_model_stream.py+++ b/libs/core/tests/unit_tests/language_models/test_chat_model_stream.py@@ -953,3 +953,329 @@ class TestAsyncChatModelStream:await stream.textwith pytest.raises(RuntimeError, match="async fail"):await stream+++# ---------------------------------------------------------------------------+# Tool-call args: `tool-call-delta` slices and `block-delta` snapshots+# ---------------------------------------------------------------------------++_ARGS_PARTS = ['{"path": ', '"a.py", ', '"content": ', '"hi"}']+++def _start(index: int, block: dict[str, Any]) -> dict[str, Any]:+ return {"event": "content-block-start", "index": index, "content": block}+++def _tool_call_start(+ index: int, *, id_: str | None = "c1", name: str | None = "write_file"+) -> dict[str, Any]:+ return _start(+ index, {"type": "tool_call_chunk", "id": id_, "name": name, "args": ""}+ )+++def _tool_call_delta(index: int, args: str) -> dict[str, Any]:+ return {+ "event": "content-block-delta",+ "index": index,+ "delta": {"type": "tool-call-delta", "args": args},+ }+++def _tool_call_finish(+ index: int, args: dict[str, Any], *, id_: str = "c1", name: str = "write_file"+) -> dict[str, Any]:+ return {+ "event": "content-block-finish",+ "index": index,+ "content": {"type": "tool_call", "id": id_, "name": name, "args": args},+ }+++def _dispatch_all(stream: ChatModelStream, events: list[dict[str, Any]]) -> None:+ for event in events:+ stream.dispatch(event)+++def _block_delta(index: int, **fields: Any) -> dict[str, Any]:+ return {+ "event": "content-block-delta",+ "index": index,+ "delta": {+ "type": "block-delta",+ "fields": {"type": "tool_call_chunk", **fields},+ },+ }+++def _slice_events() -> list[dict[str, Any]]:+ """One tool call streamed as `tool-call-delta` slices (emitting cores)."""+ return [+ {"event": "message-start", "role": "ai"},+ _tool_call_start(0),+ *[_tool_call_delta(0, part) for part in _ARGS_PARTS],+ _tool_call_finish(0, {"path": "a.py", "content": "hi"}),+ {"event": "message-finish"},+ ]+++def _snapshot_events() -> list[dict[str, Any]]:+ """The same tool call streamed as `block-delta` snapshots (older cores)."""+ snapshots = ["".join(_ARGS_PARTS[: i + 1]) for i in range(len(_ARGS_PARTS))]+ return [+ {"event": "message-start", "role": "ai"},+ _tool_call_start(0),+ *[+ _block_delta(0, id="c1", name="write_file", args=snapshot)+ for snapshot in snapshots+ ],+ _tool_call_finish(0, {"path": "a.py", "content": "hi"}),+ {"event": "message-finish"},+ ]+++_EXPECTED_DELTAS = [+ {"type": "tool_call_chunk", "id": "c1", "name": "write_file", "args": '{"path": '},+ {"type": "tool_call_chunk", "id": "c1", "name": "write_file", "args": '"a.py", '},+ {+ "type": "tool_call_chunk",+ "id": "c1",+ "name": "write_file",+ "args": '"content": ',+ },+ {"type": "tool_call_chunk", "id": "c1", "name": "write_file", "args": '"hi"}'},+]+++class TestToolCallArgs:+ """`.tool_calls` yields deltas whatever form the args arrive in."""++ def test_slice_stream_yields_deltas_carrying_id_and_name(self) -> None:+ stream = ChatModelStream()+ _dispatch_all(stream, _slice_events())++ assert list(stream.tool_calls) == _EXPECTED_DELTAS++ def test_snapshot_stream_yields_the_same_deltas(self) -> None:+ stream = ChatModelStream()+ _dispatch_all(stream, _snapshot_events())++ assert list(stream.tool_calls) == _EXPECTED_DELTAS++ def test_both_forms_assemble_the_same_tool_calls(self) -> None:+ from_slices = ChatModelStream()+ _dispatch_all(from_slices, _slice_events())+ from_snapshots = ChatModelStream()+ _dispatch_all(from_snapshots, _snapshot_events())++ expected = [+ {+ "type": "tool_call",+ "id": "c1",+ "name": "write_file",+ "args": {"path": "a.py", "content": "hi"},+ }+ ]+ assert from_slices.tool_calls.get() == expected+ assert from_snapshots.tool_calls.get() == expected+ assert from_slices.output == from_snapshots.output++ def test_call_whose_args_stop_extending_goes_quiet_until_finish(self) -> None:+ stream = ChatModelStream()+ _dispatch_all(+ stream,+ [+ {"event": "message-start", "role": "ai"},+ _tool_call_start(0),+ _block_delta(0, args='{"path": '),+ # Doesn't extend '{"path": ', so no delta can express it.+ _block_delta(0, args="{"),+ # Lines up again, but the call stays quiet.+ _block_delta(0, args='{"path": "a.py", '),+ _tool_call_delta(0, '"content": "hi"}'),+ _tool_call_finish(0, {"path": "a.py", "content": "hi"}),+ {"event": "message-finish"},+ ],+ )++ assert list(stream.tool_calls) == [+ {+ "type": "tool_call_chunk",+ "id": "c1",+ "name": "write_file",+ "args": '{"path": ',+ },+ ]+ assert stream.output.tool_calls == [+ {+ "type": "tool_call",+ "id": "c1",+ "name": "write_file",+ "args": {"path": "a.py", "content": "hi"},+ }+ ]++ def test_block_delta_without_args_yields_nothing_and_updates_id_and_name(+ self,+ ) -> None:+ stream = ChatModelStream()+ _dispatch_all(+ stream,+ [+ {"event": "message-start", "role": "ai"},+ _tool_call_start(0, id_=None, name=None),+ _tool_call_delta(0, '{"path": '),+ _block_delta(0, id="c1", name="write_file"),+ _tool_call_delta(0, '"a.py"}'),+ _tool_call_finish(0, {"path": "a.py"}),+ {"event": "message-finish"},+ ],+ )++ assert list(stream.tool_calls) == [+ {"type": "tool_call_chunk", "id": None, "name": None, "args": '{"path": '},+ {+ "type": "tool_call_chunk",+ "id": "c1",+ "name": "write_file",+ "args": '"a.py"}',+ },+ ]++ def test_unknown_delta_variant_is_ignored(self) -> None:+ stream = ChatModelStream()+ unknown = {+ "event": "content-block-delta",+ "index": 0,+ "delta": {"type": "future-delta", "args": "ignored"},+ }+ events = _slice_events()+ events.insert(3, unknown)+ _dispatch_all(stream, events)++ assert list(stream.tool_calls) == _EXPECTED_DELTAS+ assert stream.output.tool_calls[0]["args"] == {"path": "a.py", "content": "hi"}++ def test_deltas_carry_the_provider_index_from_the_start(self) -> None:+ stream = ChatModelStream()+ start = _start(+ 0,+ {+ "type": "tool_call_chunk",+ "id": "c1",+ "name": "write_file",+ "args": "",+ "index": 3,+ },+ )+ _dispatch_all(stream, [start, _tool_call_delta(0, "{}")])++ assert list(stream.tool_calls) == [+ {+ "type": "tool_call_chunk",+ "id": "c1",+ "name": "write_file",+ "args": "{}",+ "index": 3,+ }+ ]++ def test_tool_call_delta_without_a_seen_start_is_left_to_finish(self) -> None:+ stream = ChatModelStream()+ _dispatch_all(+ stream,+ [+ {"event": "message-start", "role": "ai"},+ # The start was trimmed from the replay window.+ *[_tool_call_delta(0, part) for part in _ARGS_PARTS],+ _tool_call_finish(0, {"path": "a.py", "content": "hi"}),+ {"event": "message-finish"},+ ],+ )++ assert list(stream.tool_calls) == []+ assert stream.output.tool_calls[0]["args"] == {"path": "a.py", "content": "hi"}++ def test_tool_call_deltas_assemble_a_call_with_no_finish(self) -> None:+ stream = ChatModelStream()+ events = [e for e in _slice_events() if e["event"] != "content-block-finish"]+ _dispatch_all(stream, events)++ assert stream.output.tool_calls == [+ {+ "type": "tool_call",+ "id": "c1",+ "name": "write_file",+ "args": {"path": "a.py", "content": "hi"},+ }+ ]++ def test_server_tool_call_deltas_append_without_yielding(self) -> None:+ stream = ChatModelStream()+ _dispatch_all(+ stream,+ [+ {"event": "message-start", "role": "ai"},+ _start(+ 0,+ {+ "type": "server_tool_call_chunk",+ "id": "s1",+ "name": "web_search",+ "args": "",+ },+ ),+ _tool_call_delta(0, '{"query": '),+ _tool_call_delta(0, '"weather"}'),+ # No content-block-finish: the message-finish sweep+ # parses what the deltas appended.+ {"event": "message-finish"},+ ],+ )++ assert list(stream.tool_calls) == []+ content = cast("list[dict[str, Any]]", stream.output.content)+ assert content[0]["type"] == "server_tool_call"+ assert content[0]["id"] == "s1"+ assert content[0]["args"] == {"query": "weather"}++ def test_args_on_the_start_are_the_first_delta(self) -> None:+ stream = ChatModelStream()+ start = _start(+ 0,+ {+ "type": "tool_call_chunk",+ "id": "c1",+ "name": "write_file",+ "args": _ARGS_PARTS[0],+ },+ )+ _dispatch_all(+ stream, [start, *[_tool_call_delta(0, part) for part in _ARGS_PARTS[1:]]]+ )++ assert list(stream.tool_calls) == _EXPECTED_DELTAS++ def test_legacy_content_block_deltas_carry_id_and_name(self) -> None:+ stream = ChatModelStream()+ legacy_parts = [+ {"type": "tool_call_chunk", "id": "c1", "name": "write_file", "args": ""},+ *[{"type": "tool_call_chunk", "args": part} for part in _ARGS_PARTS],+ ]+ _dispatch_all(+ stream,+ [+ {"event": "content-block-delta", "index": 0, "content_block": part}+ for part in legacy_parts+ ],+ )++ assert list(stream.tool_calls) == _EXPECTED_DELTAS++ @pytest.mark.asyncio+ async def test_async_stream_yields_the_same_deltas(self) -> None:+ stream = AsyncChatModelStream()+ for event in _slice_events():+ stream.dispatch(event)++ assert [d async for d in stream.tool_calls] == _EXPECTED_DELTASdiff --git a/libs/core/tests/unit_tests/language_models/test_chat_model_v3_stream.py b/libs/core/tests/unit_tests/language_models/test_chat_model_v3_stream.pyindex 9fccf8b26b..ebebd1c197 100644--- a/libs/core/tests/unit_tests/language_models/test_chat_model_v3_stream.py+++ b/libs/core/tests/unit_tests/language_models/test_chat_model_v3_stream.py@@ -1365,6 +1365,76 @@ class TestBedrockConverseToolCallArgs:assert text_blocks[0]["text"] == "Hello Boston!"+class _StreamingToolCallModel(BaseChatModel):+ """Fake model that streams one tool call's args across several chunks."""++ @property+ def _llm_type(self) -> str:+ return "streaming-tool-call-fake"++ def _generate(+ self,+ messages: list[BaseMessage],+ stop: list[str] | None = None,+ run_manager: CallbackManagerForLLMRun | None = None,+ **kwargs: Any,+ ) -> ChatResult:+ del messages, stop, run_manager, kwargs+ raise NotImplementedError++ def _stream(+ self,+ messages: list[BaseMessage],+ stop: list[str] | None = None,+ run_manager: CallbackManagerForLLMRun | None = None,+ **kwargs: Any,+ ) -> Iterator[ChatGenerationChunk]:+ del messages, stop, run_manager, kwargs+ # Opener carries the id and name; the args follow in slices.+ parts = ["", '{"path": ', '"a.py", ', '"content": ', '"hi"}']+ for i, part in enumerate(parts):+ yield ChatGenerationChunk(+ message=AIMessageChunk(+ content="",+ tool_call_chunks=[+ {+ "name": "write_file" if i == 0 else None,+ "args": part,+ "id": "call_1" if i == 0 else None,+ "index": 0,+ }+ ],+ )+ )+++_TOOL_CALL_DELTAS = [+ {+ "type": "tool_call_chunk",+ "id": "call_1",+ "name": "write_file",+ "args": args,+ "index": 0,+ }+ for args in ['{"path": ', '"a.py", ', '"content": ', '"hi"}']+]+++class TestToolCallsYieldDeltas:+ """`.tool_calls` yields args deltas, not the snapshots the bridge emits."""++ def test_stream_events_v3_tool_calls_yield_deltas(self) -> None:+ stream = _StreamingToolCallModel().stream_events("hi", version="v3")++ assert list(stream.tool_calls) == _TOOL_CALL_DELTAS++ @pytest.mark.asyncio+ async def test_astream_events_v3_tool_calls_yield_deltas(self) -> None:+ stream = await _StreamingToolCallModel().astream_events("hi", version="v3")++ assert [d async for d in stream.tool_calls] == _TOOL_CALL_DELTAS++class _CachedUsageModel(BaseChatModel):"""Replays an Anthropic-shaped usage split across stream chunks.diff --git a/libs/langchain_v1/langchain/agents/middleware/pii.py b/libs/langchain_v1/langchain/agents/middleware/pii.pyindex e4c7612731..84c6cf6445 100644--- a/libs/langchain_v1/langchain/agents/middleware/pii.py+++ b/libs/langchain_v1/langchain/agents/middleware/pii.py@@ -48,14 +48,15 @@ are typically well under 100) while bounding first-token latency.class _PIIStreamTransformer(StreamTransformer):- """Mutates `content-block-delta` text on `messages` events in flight.+ """Mutates `content-block-delta` text and tool-call args in flight.Runs before built-in stream transformers so the redacted text is whatevery downstream consumer sees — both the main protocol event log andthe `run.messages` projection that `MessagesTransformer` snapshots into.- Holds a sliding buffer of the most recent text per (run_id, content- block index) so PII patterns that straddle delta boundaries are caught.+ Holds a sliding buffer of the most recent text or tool-call args per+ (run_id, content block index) so PII patterns that straddle delta+ boundaries are caught.Anything older than `lookback` characters is redacted with the resolvedrule's strategy and emitted as the new delta text; the trailing tailstays in the buffer until a later delta extends it past the cap or the@@ -75,7 +76,8 @@ class _PIIStreamTransformer(StreamTransformer):super().__init__(scope)self._rule = ruleself._lookback = lookback- # Text/reasoning deltas keyed by `(run_id, content_block_index)`.+ # Text/reasoning/tool-call-args deltas keyed by+ # `(run_id, content_block_index)`.self._buffers: dict[tuple[str, int], str] = {}# Tool-output-delta buffers keyed by `tool_call_id`. Held in a# separate dict so `_drop_run` on the messages channel can't@@ -335,13 +337,19 @@ class _PIIStreamTransformer(StreamTransformer):# `(run_id, index)` naturally disjoint from text-delta keys.self._mutate_string_field_delta(delta, payload, run_id, "reasoning")return+ if delta_type == "tool-call-delta":+ # Tool-call args slices append, like text, so they get the+ # same lookback buffer. The withheld tail surfaces on+ # `content-block-finish`, whose parsed args are redacted.+ self._mutate_string_field_delta(delta, payload, run_id, "args")+ returnif delta_type == "block-delta":fields = delta.get("fields")if isinstance(fields, dict) and fields.get("type") in {"tool_call_chunk","server_tool_call_chunk",}:- self._mutate_tool_call_chunk_delta(fields)+ self._mutate_tool_call_chunk_delta(fields, payload, run_id)# Other delta types (`data-delta`, vendor block types) pass# through. The pre-streaming middleware scrubbed `.content` text# on state messages only; binary payloads and provider-specific@@ -356,8 +364,9 @@ class _PIIStreamTransformer(StreamTransformer):) -> None:"""Apply the lookback-buffer redaction to a string field on a delta.- Shared by `text-delta` (`field="text"`) and `reasoning-delta`- (`field="reasoning"`). Buffer is keyed by `(run_id, block_index)`;+ Shared by `text-delta` (`field="text"`), `reasoning-delta`+ (`field="reasoning"`) and `tool-call-delta` (`field="args"`).+ Buffer is keyed by `(run_id, block_index)`;block indices are unique within a message so different blocktypes share the same key space without collision."""@@ -388,14 +397,19 @@ class _PIIStreamTransformer(StreamTransformer):self._buffers[key] = combined[emit_end:]delta[field] = combined[:emit_end]- def _mutate_tool_call_chunk_delta(self, fields: dict[str, Any]) -> None:+ def _mutate_tool_call_chunk_delta(+ self,+ fields: dict[str, Any],+ payload: dict[str, Any],+ run_id: str,+ ) -> None:"""Redact cumulative tool-call args with lookback withholding.- Each `tool_call_chunk` `block-delta` event carries the full- accumulated args string (verified against `_compat_bridge.py`- — `delta_source = current` for these block types — and against- the consumer-side `_merge_block_delta_into_store`, which- replaces wholesale rather than appends).+ Cores that predate `tool-call-delta` stream tool-call args as+ `block-delta` events whose `args` carry the full accumulated+ string, which consumers apply as a replacement. Cores that emit+ `tool-call-delta` slices go through `_mutate_string_field_delta`+ instead.Detection runs on the full cumulative args so any complete PIIanywhere in the string is redacted before emission. Lookback@@ -415,6 +429,10 @@ class _PIIStreamTransformer(StreamTransformer):emit prefix — same residual exposure as PII longer thanthe lookback window on the text path. The `content-block-finish`snapshot redaction is the backstop.++ A replacement becomes the prefix that later `tool-call-delta`+ slices for the block append to, so the withheld tail is kept as+ that block's lookback buffer."""args = fields.get("args")if not isinstance(args, str) or not args:@@ -429,6 +447,9 @@ class _PIIStreamTransformer(StreamTransformer):emit_end = max(0, len(args) - self._lookback)fields["args"] = args[:emit_end]+ index = payload.get("index")+ if isinstance(index, int):+ self._buffers[run_id, index] = args[emit_end:]def _finalize_block(self, payload: dict[str, Any], run_id: str) -> None:index = payload.get("index")@@ -597,9 +618,10 @@ class PIIMiddleware(AgentMiddleware[AgentState[ResponseT], ContextT, ResponseT])* Streamed AI text deltas (`content-block-delta` of type`text-delta`)* Streamed tool-call arguments (`content-block-delta`- with `tool_call_chunk` / `server_tool_call_chunk`- fields, plus the finalized `tool_call` content block- on `content-block-finish`)+ of type `tool-call-delta`, or `block-delta` with+ `tool_call_chunk` / `server_tool_call_chunk` fields,+ plus the finalized `tool_call` content block on+ `content-block-finish`)* Tool execution events on the `tools` channel(`tool-started.input`, `tool-output-delta`,`tool-finished.output`, `tool-error.message`)diff --git a/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_pii.py b/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_pii.pyindex dee46efc40..6055dc4a14 100644--- a/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_pii.py+++ b/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_pii.py@@ -7,6 +7,7 @@# langgraph adds a `__getattr__` fallback (strict mode's `warn_unused_ignores`).import re+from collections.abc import Callablefrom typing import Anyimport pytest@@ -885,6 +886,53 @@ def _emitted_text(events: list[ProtocolEvent]) -> tuple[str, dict[int, str]]:return "".join(parts), final_by_index+def _make_tool_call_delta_event(+ delta: dict[str, Any], *, index: int = 0, run_id: str = "r1"+) -> ProtocolEvent:+ """Build a `messages` protocol event for a tool-call content-block delta."""+ return {+ "type": "event",+ "method": "messages",+ "params": {+ "namespace": [],+ "timestamp": 0,+ "data": (+ {"event": "content-block-delta", "index": index, "delta": delta},+ {"run_id": run_id},+ ),+ },+ }+++def _tool_call_slice(args: str) -> dict[str, Any]:+ return {"type": "tool-call-delta", "args": args}+++def _tool_call_snapshot(args: str | None = None, **fields: Any) -> dict[str, Any]:+ if args is not None:+ fields["args"] = args+ return {"type": "block-delta", "fields": {"type": "tool_call_chunk", **fields}}+++def _emitted_tool_call_args(events: list[ProtocolEvent]) -> str:+ """Rebuild streamed tool-call args the way a consumer would.++ `tool-call-delta` appends its slice; a `block-delta` carrying `args`+ replaces them.+ """+ args = ""+ for event in events:+ payload = event["params"]["data"][0]+ if payload.get("event") != "content-block-delta":+ continue+ delta = payload["delta"]+ if delta.get("type") == "tool-call-delta":+ args += delta["args"]+ elif delta.get("type") == "block-delta" and "args" in delta["fields"]:+ args = delta["fields"]["args"]+ return args++def _run_transformer(transformer: Any, events: list[ProtocolEvent]) -> list[ProtocolEvent]:"""Feed events through the transformer (mutates in place) and return them."""for event in events:@@ -1750,6 +1798,93 @@ class TestPIIStreamTransformer:with pytest.raises(PIIDetectionError):transformer.process(event)+ @pytest.mark.parametrize(+ "make_delta",+ [+ pytest.param(_tool_call_slice, id="slices"),+ pytest.param(_tool_call_snapshot, id="snapshots"),+ ],+ )+ def test_tool_call_pii_straddling_deltas_is_redacted(+ self, make_delta: Callable[[str], dict[str, Any]]+ ) -> None:+ """PII split across tool-call deltas never reaches the wire, in either form.++ `tool-call-delta` slices go through the same lookback buffer as+ text; `block-delta` snapshots (older cores) are redacted whole.+ Either way the consumer rebuilds the same args: the redacted args+ minus the held-back tail that `content-block-finish` carries.+ """+ rule = RedactionRule(pii_type="email").resolve()+ transformer = _PIIStreamTransformer(rule=rule, lookback=8)++ slices = ['{"to": "alice', '@example.com", ', '"subject": "hi"}']+ args = ["".join(slices[: i + 1]) for i in range(len(slices))]+ parts = slices if make_delta is _tool_call_slice else args+ events = [_make_tool_call_delta_event(make_delta(p)) for p in parts]+ _run_transformer(transformer, events)++ assert _emitted_tool_call_args(events) == '{"to": "[REDACTED_EMAIL]", "subject'++ def test_unknown_delta_variant_passes_through(self) -> None:+ """An unknown delta variant is left as is and doesn't disturb the buffer."""+ rule = RedactionRule(pii_type="email").resolve()+ transformer = _PIIStreamTransformer(rule=rule, lookback=8)++ unknown = {"type": "future-delta", "args": "x"}+ events = [+ _make_tool_call_delta_event(_tool_call_slice('{"to": "alice')),+ _make_tool_call_delta_event(dict(unknown)),+ _make_tool_call_delta_event(_tool_call_slice('@example.com", ')),+ _make_tool_call_delta_event(_tool_call_slice('"subject": "hi"}')),+ ]+ _run_transformer(transformer, events)++ assert events[1]["params"]["data"][0]["delta"] == unknown+ assert _emitted_tool_call_args(events) == '{"to": "[REDACTED_EMAIL]", "subject'++ def test_tool_call_slices_after_a_snapshot_extend_what_it_emitted(self) -> None:+ """A snapshot's withheld tail is the prefix later slices append to."""+ rule = RedactionRule(pii_type="email").resolve()+ transformer = _PIIStreamTransformer(rule=rule, lookback=8)++ events = [+ _make_tool_call_delta_event(_tool_call_snapshot('{"to": "alice')),+ _make_tool_call_delta_event(_tool_call_slice('@example.com", ')),+ _make_tool_call_delta_event(_tool_call_slice('"subject": "hi"}')),+ ]+ _run_transformer(transformer, events)++ assert _emitted_tool_call_args(events) == '{"to": "[REDACTED_EMAIL]", "subject'++ def test_tool_call_delta_block_strategy_raises(self) -> None:+ """`block` raises as soon as PII completes across tool-call slices."""+ rule = RedactionRule(pii_type="email", strategy="block").resolve()+ transformer = _PIIStreamTransformer(rule=rule)++ transformer.process(_make_tool_call_delta_event(_tool_call_slice('{"to": "alice')))+ with pytest.raises(PIIDetectionError):+ transformer.process(_make_tool_call_delta_event(_tool_call_slice('@example.com"}')))++ def test_args_free_block_delta_between_slices_passes_through(self) -> None:+ """A late `id` / `name` update leaves the slices' buffer intact."""+ rule = RedactionRule(pii_type="email").resolve()+ transformer = _PIIStreamTransformer(rule=rule, lookback=8)++ late_id = _tool_call_snapshot(id="c1", name="send_email")+ events = [+ _make_tool_call_delta_event(_tool_call_slice('{"to": "alice')),+ _make_tool_call_delta_event(late_id),+ _make_tool_call_delta_event(_tool_call_slice('@example.com", ')),+ _make_tool_call_delta_event(_tool_call_slice('"subject": "hi"}')),+ ]+ _run_transformer(transformer, events)++ assert events[1]["params"]["data"][0]["delta"] == _tool_call_snapshot(+ id="c1", name="send_email"+ )+ assert _emitted_tool_call_args(events) == '{"to": "[REDACTED_EMAIL]", "subject'+def test_pii_fully_inside_one_delta_is_redacted_on_finalize(self) -> None:"""A delta shorter than `lookback` is held until finalize redacts the snapshot."""rule = RedactionRule(pii_type="email").resolve()@@ -2219,7 +2354,9 @@ class TestPIIStreamingEndToEnd:surfaces.append(str(c.get("args")))elif p.get("event") == "content-block-delta":d = p.get("delta") or {}- if d.get("type") == "block-delta":+ if d.get("type") == "tool-call-delta":+ surfaces.append(str(d.get("args", "")))+ elif d.get("type") == "block-delta":f = d.get("fields") or {}if f.get("type") in {"tool_call_chunk",diff --git a/libs/standard-tests/langchain_tests/utils/stream_lifecycle.py b/libs/standard-tests/langchain_tests/utils/stream_lifecycle.pyindex 7cf50be031..e7d9ce8da9 100644--- a/libs/standard-tests/langchain_tests/utils/stream_lifecycle.py+++ b/libs/standard-tests/langchain_tests/utils/stream_lifecycle.py@@ -13,7 +13,11 @@ conforms to the protocol lifecycle rules:starting at 0.- For deltaable block types (`text`, `reasoning`, `tool_call_chunk`,`server_tool_call_chunk`), accumulated delta content matches the- final payload delivered on `content-block-finish`.+ final payload delivered on `content-block-finish`. Tool-call args may+ arrive as `tool-call-delta` slices, which append, or as `block-delta`+ snapshots, which replace; `tool-call-delta` only targets tool-call+ chunk blocks.+- Unknown delta variants are accepted and ignored.The validator accepts any iterable of protocol event dicts. It raises`AssertionError` on the first violation with a descriptive message.@@ -37,6 +41,8 @@ _DELTAABLE_TYPES = frozenset(})+_TOOL_CALL_CHUNK_TYPES = frozenset({"tool_call_chunk", "server_tool_call_chunk"})+def assert_valid_event_stream(events: Iterable[Any]) -> None:"""Assert that a stream of protocol events obeys the lifecycle contract.@@ -125,7 +131,13 @@ def assert_valid_event_stream(events: Iterable[Any]) -> None:delta = event.get("delta")if delta is None and "content_block" in event:delta = _legacy_block_to_delta(event["content_block"])- _accumulate_delta(delta_accum[idx], delta)+ if delta is not None and delta.get("type") == "tool-call-delta":+ start_type = start_events[idx].get("type")+ assert start_type in _TOOL_CALL_CHUNK_TYPES, (+ f"tool-call-delta at idx={idx} targets a {start_type!r} "+ f"block, not a tool-call chunk (event {i})"+ )+ _accumulate_delta(delta_accum[idx], delta, start_events[idx])elif ev == "content-block-finish":idx = event["index"]assert idx in open_indices, (@@ -170,7 +182,11 @@ def _legacy_block_to_delta(block: dict[str, Any]) -> dict[str, Any]:return {"type": "block-delta", "fields": block}-def _accumulate_delta(accum: dict[str, Any], delta: dict[str, Any] | None) -> None:+def _accumulate_delta(+ accum: dict[str, Any],+ delta: dict[str, Any] | None,+ start: dict[str, Any],+) -> None:"""Fold a delta block into the running accumulator for its index."""if delta is None:return@@ -181,6 +197,11 @@ def _accumulate_delta(accum: dict[str, Any], delta: dict[str, Any] | None) -> Noaccum["reasoning"] = accum.get("reasoning", "") + delta.get("reasoning", "")elif dtype == "data-delta":accum["data"] = accum.get("data", "") + delta.get("data", "")+ elif dtype == "tool-call-delta":+ # Appends a slice to the args so far: the last `block-delta`+ # snapshot's (older cores) or, before any, the start's.+ args = accum["args"] if "args" in accum else start.get("args")+ accum["args"] = (args or "") + (delta.get("args") or "")elif dtype == "block-delta":fields = delta.get("fields")if not isinstance(fields, dict):diff --git a/libs/standard-tests/tests/unit_tests/test_stream_lifecycle.py b/libs/standard-tests/tests/unit_tests/test_stream_lifecycle.pynew file mode 100644index 0000000000..97e12f5db9--- /dev/null+++ b/libs/standard-tests/tests/unit_tests/test_stream_lifecycle.py@@ -0,0 +1,137 @@+"""Tests for the content-block protocol stream validator."""++from typing import Any++import pytest++from langchain_tests.utils.stream_lifecycle import assert_valid_event_stream++_ARGS_PARTS = ['{"path": ', '"a.py", ', '"content": ', '"hi"}']+_ARGS = {"path": "a.py", "content": "hi"}+++def _tool_call_events(+ deltas: list[dict[str, Any]],+ *,+ finish_args: dict[str, Any] | None = None,+ start_args: str = "",+) -> list[dict[str, Any]]:+ """One tool call at index 0, with the given deltas between start and finish."""+ return [+ {"event": "message-start", "role": "ai"},+ {+ "event": "content-block-start",+ "index": 0,+ "content": {+ "type": "tool_call_chunk",+ "id": "c1",+ "name": "write_file",+ "args": start_args,+ },+ },+ *[+ {"event": "content-block-delta", "index": 0, "delta": delta}+ for delta in deltas+ ],+ {+ "event": "content-block-finish",+ "index": 0,+ "content": {+ "type": "tool_call",+ "id": "c1",+ "name": "write_file",+ "args": _ARGS if finish_args is None else finish_args,+ },+ },+ {"event": "message-finish"},+ ]+++def _slices(parts: list[str]) -> list[dict[str, Any]]:+ return [{"type": "tool-call-delta", "args": part} for part in parts]+++def _snapshots(parts: list[str]) -> list[dict[str, Any]]:+ return [+ {+ "type": "block-delta",+ "fields": {+ "type": "tool_call_chunk",+ "args": "".join(parts[: i + 1]),+ },+ }+ for i in range(len(parts))+ ]+++def test_tool_call_delta_args_must_match_finish() -> None:+ events = _tool_call_events(+ _slices(_ARGS_PARTS), finish_args={"path": "b.py", "content": "hi"}+ )++ with pytest.raises(AssertionError, match="tool_call args mismatch"):+ assert_valid_event_stream(events)+++ "deltas",+ [+ pytest.param(_slices(_ARGS_PARTS), id="slices"),+ pytest.param(_snapshots(_ARGS_PARTS), id="snapshots"),+ pytest.param(+ [*_snapshots(_ARGS_PARTS[:2]), *_slices(_ARGS_PARTS[2:])],+ id="snapshot then slices",+ ),+ ],+)+def test_tool_call_args_in_either_form_are_valid(deltas: list[dict[str, Any]]) -> None:+ assert_valid_event_stream(_tool_call_events(deltas))+++ "deltas",+ [+ pytest.param(_slices(_ARGS_PARTS[:-1]), id="slices"),+ pytest.param(_snapshots(_ARGS_PARTS)[:-1], id="snapshots"),+ ],+)+def test_incomplete_tool_call_args_are_invalid(deltas: list[dict[str, Any]]) -> None:+ with pytest.raises(AssertionError, match="tool_call args mismatch"):+ assert_valid_event_stream(_tool_call_events(deltas))+++def test_unknown_delta_variant_is_accepted() -> None:+ deltas = [{"type": "future-delta", "args": "ignored"}, *_slices(_ARGS_PARTS)]++ assert_valid_event_stream(_tool_call_events(deltas))+++def test_tool_call_delta_appends_to_args_on_the_start() -> None:+ events = _tool_call_events(_slices(_ARGS_PARTS[1:]), start_args=_ARGS_PARTS[0])++ assert_valid_event_stream(events)+++def test_tool_call_delta_on_a_text_block_is_invalid() -> None:+ events = [+ {"event": "message-start", "role": "ai"},+ {+ "event": "content-block-start",+ "index": 0,+ "content": {"type": "text", "text": ""},+ },+ {+ "event": "content-block-delta",+ "index": 0,+ "delta": {"type": "tool-call-delta", "args": "{}"},+ },+ {+ "event": "content-block-finish",+ "index": 0,+ "content": {"type": "text", "text": ""},+ },+ {"event": "message-finish"},+ ]++ with pytest.raises(AssertionError, match="tool-call-delta"):+ assert_valid_event_stream(events)