loom-kernel 2.3.0__tar.gz → 2.3.1__tar.gz

{loom_kernel-2.3.0 → loom_kernel-2.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: loom-kernel
-Version: 2.3.0
+Version: 2.3.1
 Summary: Loom Python project
 License-File: LICENSE
 Classifier: Typing :: Typed

{loom_kernel-2.3.0 → loom_kernel-2.3.1}/docs/ai/providers.md

@@ -127,7 +127,7 @@ redacts itself:
 
 ```pycon
 >>> print(target)
-InferenceTarget(provider='bedrock', model='anthropic.claude-sonnet-4-...', region='eu-west-1', endpoint=None, output_mode=None, credentials_ref=<redacted>, options=<redacted>)
+InferenceTarget(provider='bedrock', model='anthropic.claude-sonnet-4-...', region='eu-west-1', endpoint=None, output_mode=None, streaming=True, credentials_ref=<redacted>, options=<redacted>)
 ```
 
 and **refuses** to be serialised at all when it carries a secret reference —
@@ -195,6 +195,34 @@ loom does not infer it per provider. Two consequences follow from that:
   model before the first request, so a wrong pin is found there, not at
   start-up.
 
+## Asking for the answer whole, not as a stream
+
+Loom streams every run, so it can supervise it as it happens; the provider
+is asked to stream too. Some models stream badly: on Bedrock, one family
+delivers a short tool call with its opening characters missing, one answer
+in two, while the same answer asked without streaming arrives whole -- the
+provider parses it before sending it. A binding can ask for that instead:
+
+```yaml
+ai:
+  models:
+    reasoning:
+      provider: bedrock
+      model: <model id>
+      streaming: false
+```
+
+What changes for that role, and only for it: each model request is answered in
+one piece. A run loses nothing else — the answer is validated and retried the
+same way, the usage is the same, and a `run_stream` caller still receives what
+the model said and every tool call and result, in order; the text simply
+arrives as one delta per text part instead of many. The policies
+(`run_timeout_ms`, `max_iterations`, `max_requests`) apply as before.
+
+It is the choice pydantic-ai offers between `run` and `run_stream`, made per
+model binding rather than per call: the artifact never has to know which model
+serves it, and a role can be moved back by deleting the line.
+
 ## What does not happen
 
 **No fallback routing.** An exhausted or failing provider fails the run. It is

{loom_kernel-2.3.0 → loom_kernel-2.3.1}/src/loom/ai/engines/pydantic_ai/_engine.py

@@ -32,6 +32,7 @@ carries the same gap forward once observed.
 from __future__ import annotations
 
 import asyncio
+import logging
 from collections.abc import AsyncGenerator, AsyncIterator, Mapping, Sequence
 from contextlib import AbstractAsyncContextManager, asynccontextmanager
 from dataclasses import fields
@@ -39,7 +40,14 @@ from time import perf_counter
 from types import MappingProxyType
 from typing import Any, Final, cast
 
-from pydantic_ai import Agent, AgentRunResult, AgentRunResultEvent, BinaryContent
+from pydantic_ai import (
+    Agent,
+    AgentRun,
+    AgentRunResult,
+    AgentRunResultEvent,
+    BinaryContent,
+    CallToolsNode,
+)
 from pydantic_ai.messages import ModelResponse, PartStartEvent
 from pydantic_ai.usage import RunUsage, UsageLimits
 
@@ -69,6 +77,8 @@ from loom.ai.errors import AgentRunError, AgentRunErrorCode, is_retriable
 from loom.core.di import LoomContainer
 from loom.core.identity import Identity
 
+_logger = logging.getLogger(__name__)
+
 RETRY_BACKOFF_MS = 200
 """Base wait before a retried attempt; doubled per attempt (FR-028).
 
@@ -76,6 +86,9 @@ A constant rather than a policy field: ``policies`` describes what the agent
 is allowed to spend, and no requirement asks the artifact to tune the wait.
 """
 
+MAX_LOGGED_CAUSE_CHARS = 500
+"""Cap on a logged failure cause: it is model-authored text, unbounded at the source."""
+
 _HEALTHY = HealthStatus(status="ok")
 
 # Counters :class:`~loom.ai.abc.AgentUsage` names itself, plus the engine's own
@@ -358,6 +371,7 @@ class PydanticAIEngine:
             except Exception as exc:
                 error = as_run_error(exc)
                 self._record(error.code)
+                self._log_cause(error, exc)
                 if self._may_retry(error.code, attempt):
                     await _backoff(attempt)
                     continue
@@ -412,8 +426,20 @@ class PydanticAIEngine:
         """
         error = as_run_error(exc)
         self._record(error.code)
+        self._log_cause(error, exc)
         return error, not emitted and self._may_retry(error.code, attempt)
 
+    def _log_cause(self, error: AgentRunError, exc: Exception) -> None:
+        """Log what the published failure cannot carry: the answer that caused it, truncated."""
+        if exc.__cause__ is not None:
+            cause = str(exc.__cause__)[:MAX_LOGGED_CAUSE_CHARS]
+            _logger.warning(
+                "agent %s failed with %s, raised from: %s",
+                self._plan.name,
+                error.code.value,
+                cause,
+            )
+
     def _apply_unpriced_spend_policy(self, result: AgentRunResult[Any]) -> int:
         """Act on this run's responses that pydantic-ai could not price.
 
@@ -537,7 +563,7 @@ class PydanticAIEngine:
             if not outcome:
                 raise AssertionError(
                     "unreachable: the engine's own event stream always ends with a "
-                    "trailing AgentRunResultEvent"
+                    "trailing AgentRunResultEvent, or, for a whole run, its own result"
                 )
             try:
                 final = self._conclude(outcome[0], spend, started, output_type)
@@ -572,8 +598,8 @@ class PydanticAIEngine:
         than relayed live, and flushed only once this attempt's
         ``AgentRunResultEvent`` arrives: an ``output_check`` rejection and a
         pydantic validation failure alike replay the model request inside
-        this same call, each replay's ``PartStartEvent`` starts again at
-        ``index=0``, and a delta already relayed cannot be un-sent. A plan
+        this same call, and each replay opens with a new response's first
+        part, at ``index=0``, so a delta already relayed cannot be un-sent. A plan
         that withholds nothing never buffers: *pending* stays empty and every
         mapped event is yielded as it arrives, exactly as before
         ``output_check`` existed.
@@ -582,40 +608,77 @@ class PydanticAIEngine:
         :attr:`_shaped_agent`, carrying no output validator, when given —
         pydantic-ai refuses a run-level ``output_type`` on an agent holding
         one — and :attr:`_agent`, the plan's own checked agent, otherwise.
+
+        A binding that declares ``streaming: false`` is served by
+        :meth:`_one_run_whole` instead, which relays the same events.
         """
-        withhold = self._withhold
         pending: list[AgentEvent] = []
         pinned: dict[str, Any] = {} if output_type is None else {"output_type": output_type}
         agent = self._agent if output_type is None else self._shaped_agent
-        async with agent.run_stream_events(
-            _user_prompt(prompt),
-            deps=deps,
-            usage=spend,
-            usage_limits=self._usage_limits,
+        run_args: dict[str, Any] = {
+            "deps": deps,
+            "usage": spend,
+            "usage_limits": self._usage_limits,
             **run_kwargs(conversation),
             **pinned,
-        ) as stream:
+        }
+        if not self._plan.inference.streaming:
+            async for relayed in self._one_run_whole(prompt, agent, run_args, pending, outcome):
+                yield relayed
+            return
+        async with agent.run_stream_events(_user_prompt(prompt), **run_args) as stream:
             async for event in stream:
                 if isinstance(event, AgentRunResultEvent):
                     outcome.append(event.result)
                     for held in pending:
                         yield held
                     return
-                mapped = self._relay_or_buffer(event, withhold, pending)
+                mapped = self._relay_or_buffer(event, self._withhold, pending)
                 if mapped is not None:
                     yield mapped
 
+    async def _one_run_whole(
+        self,
+        prompt: Prompt,
+        agent: Agent[Any, Any],
+        run_args: dict[str, Any],
+        pending: list[AgentEvent],
+        outcome: list[AgentRunResult[Any]],
+    ) -> AsyncIterator[AgentEvent]:
+        """One attempt whose model requests are answered whole, never streamed.
+
+        The run is driven node by node, as pydantic-ai's own ``run`` drives it,
+        so every request is answered in one piece -- parsed by the provider
+        before it is sent -- and the attempt keeps its validation, its tool
+        retries and its usage.
+        """
+        async with agent.iter(_user_prompt(prompt), **run_args) as run:
+            node = run.next_node
+            while not Agent.is_end_node(node):
+                if Agent.is_call_tools_node(node):
+                    async for event in _whole_response(node, run):
+                        mapped = self._relay_or_buffer(event, self._withhold, pending)
+                        if mapped is not None:
+                            yield mapped
+                node = await run.next(node)
+            # pydantic-ai leaves ``result`` typed optional though the ``End`` node just
+            # reached guarantees it; appended unconditionally, so a violated guarantee
+            # surfaces through ``_conclude``'s own classified failure, not a skipped outcome.
+            outcome.append(cast("AgentRunResult[Any]", run.result))
+        for held in pending:
+            yield held
+
     @staticmethod
     def _relay_or_buffer(
         event: object, withhold: bool, pending: list[AgentEvent]
     ) -> AgentEvent | None:
         """Translate one non-terminal stream *event* and apply the buffering policy.
 
-        A fresh replay's ``PartStartEvent`` at ``index=0`` discards whatever
-        this attempt had buffered so far. A mapped text delta is appended to
-        *pending* instead of returned when *withhold* is set, so the caller
-        never yields it directly; every other mapped event is returned as-is
-        for the caller to yield.
+        A new response's first part -- ``PartStartEvent`` at ``index=0`` --
+        discards whatever this attempt had buffered so far. A mapped text
+        delta is appended to *pending* instead of returned when *withhold*
+        is set, so the caller never yields it directly; every other mapped
+        event is returned as-is for the caller to yield.
         """
         if withhold and isinstance(event, PartStartEvent) and event.index == 0:
             pending.clear()
@@ -733,6 +796,21 @@ async def _backoff(attempt: int) -> None:
     await asyncio.sleep(RETRY_BACKOFF_MS * (2**attempt) / 1000)
 
 
+async def _whole_response(
+    node: CallToolsNode[Any, Any], run: AgentRun[Any, Any]
+) -> AsyncIterator[object]:
+    """Every engine event of one whole response: its own parts first, then its tool events.
+
+    A whole response carries its text already complete, so each part is offered as the
+    ``PartStartEvent`` a streamed run would have opened it with.
+    """
+    for index, part in enumerate(node.model_response.parts):
+        yield PartStartEvent(index=index, part=part)
+    async with node.stream(run.ctx) as events:
+        async for event in events:
+            yield event
+
+
 def _user_prompt(prompt: Prompt) -> str | Sequence[str | BinaryContent]:
     """The prompt as pydantic-ai takes it: an attachment becomes ``BinaryContent``."""
     if isinstance(prompt, str):

{loom_kernel-2.3.0 → loom_kernel-2.3.1}/src/loom/ai/engines/pydantic_ai/provider.py

@@ -38,6 +38,7 @@ from loom.ai.engines.pydantic_ai._mcp import SharedMcpToolsets
 from loom.ai.engines.pydantic_ai._models import ModelResolver, resolve_model
 from loom.ai.engines.pydantic_ai._native import supported_native_tools
 from loom.ai.engines.pydantic_ai._spec import build_agent_spec, build_output_type
+from loom.ai.errors import AgentCompilationError, streaming_required_by_capability
 from loom.ai.inference import InferenceTarget
 from loom.core.di import LoomContainer
 from loom.core.model import LoomType
@@ -149,7 +150,9 @@ class PydanticAIEngineProvider:
             AgentCompilationError: When the vendor SDK the binding needs is not
                 installed, a required provider setting is missing, a
                 templated instruction block needs the templating extra and
-                it is not installed, or a templated block fails to compile.
+                it is not installed, a templated block fails to compile, or
+                the plan sets ``streaming: false`` while a built capability
+                overrides ``wrap_run_event_stream``.
         """
         if not isinstance(plan, AgentPlan):
             raise TypeError(f"expected an AgentPlan, got {type(plan).__name__}")
@@ -161,6 +164,10 @@ class PydanticAIEngineProvider:
         )
         toolsets = build_toolsets(plan, container, mcp=self._mcp)
         capabilities = build_capabilities(plan, container)
+        if not plan.inference.streaming and any(
+            capability.has_wrap_run_event_stream for capability in capabilities
+        ):
+            raise AgentCompilationError([streaming_required_by_capability(plan.name)])
         output_type = build_output_type(plan)
         # The keyword is absent, not ``None``, when no mode is pinned: the
         # engine's default for ``output_type`` is ``str``, and passing ``None``

{loom_kernel-2.3.0 → loom_kernel-2.3.1}/src/loom/ai/errors.py

@@ -95,6 +95,7 @@ class AgentErrorCode(StrEnum):
 
     # Capabilities
     CAPABILITY_KIND_UNSUPPORTED = "CAPABILITY_KIND_UNSUPPORTED"
+    STREAMING_REQUIRED_BY_CAPABILITY = "STREAMING_REQUIRED_BY_CAPABILITY"
     NATIVE_TOOL_UNSUPPORTED = "NATIVE_TOOL_UNSUPPORTED"
     NATIVE_TOOL_DUPLICATE = "NATIVE_TOOL_DUPLICATE"
     CAPABILITY_EMPTY = "CAPABILITY_EMPTY"
@@ -577,6 +578,19 @@ def capability_kind_unsupported(component: str, kind: str, engine: str) -> Agent
     )
 
 
+def streaming_required_by_capability(component: str) -> AgentCompilationIssue:
+    """A granted capability keeps streaming, so ``streaming: false`` cannot be honoured."""
+    return AgentCompilationIssue(
+        code=AgentErrorCode.STREAMING_REQUIRED_BY_CAPABILITY,
+        message=(
+            f"{component}: bound with 'streaming: false', but a granted capability requires a "
+            "streamed run, so the binding cannot ask for whole answers"
+        ),
+        component=component,
+        field="ai.models",
+    )
+
+
 def native_tool_unsupported(
     component: str,
     *,

{loom_kernel-2.3.0 → loom_kernel-2.3.1}/src/loom/ai/inference.py

@@ -96,9 +96,9 @@ class _RedactedOptions(Mapping[str, Any]):
 class InferenceTarget(LoomFrozenStruct, frozen=True, kw_only=True):
     """One resolved model binding for a model role (``ai.models.<role>``).
 
-    ``repr``/``str`` show ``provider``, ``model``, ``region``, ``endpoint``
-    and ``output_mode``
-    but never the values of ``credentials_ref`` or ``options`` — the plan
+    ``repr``/``str`` show ``provider``, ``model``, ``region``, ``endpoint``,
+    ``output_mode`` and ``streaming``, but never the values of
+    ``credentials_ref`` or ``options`` — the plan
     carries this struct, so an unredacted repr in a start-up traceback is the
     concrete leak path.  Encoding the struct with msgspec raises when either
     secret-bearing field is set (see the module docstring for the rationale).
@@ -116,6 +116,12 @@ class InferenceTarget(LoomFrozenStruct, frozen=True, kw_only=True):
             would surface as a raw ``ValidationError`` instead of the
             ``OUTPUT_MODE_UNKNOWN`` issue naming the role.  The set is
             enforced by ``loom.ai.config._validate_model_binding``.
+        streaming: Whether the engine asks the provider for its answers as a
+            stream. ``False`` asks for each answer whole instead -- for a
+            model whose streamed tool calls arrive damaged -- and the
+            model's text then reaches the caller as one delta per text part
+            rather than many. ``AgentEngine.run`` has always been served
+            whole; only its streamed entry points change with this flag.
         credentials_ref: Reference resolved by the existing secrets resolver.
             Never a literal secret (FR-018).
         options: Vendor-specific settings.  Confined here; never reaches the
@@ -127,6 +133,7 @@ class InferenceTarget(LoomFrozenStruct, frozen=True, kw_only=True):
     region: str | None = None
     endpoint: str | None = None
     output_mode: str | None = None
+    streaming: bool = True
     credentials_ref: str | None = None
     options: Mapping[str, Any] = field(default_factory=dict)
 
@@ -145,6 +152,7 @@ class InferenceTarget(LoomFrozenStruct, frozen=True, kw_only=True):
             f" region={self.region!r},"
             f" endpoint={self.endpoint!r},"
             f" output_mode={self.output_mode!r},"
+            f" streaming={self.streaming!r},"
             f" credentials_ref={credentials},"
             f" options={options})"
         )

{loom_kernel-2.3.0 → loom_kernel-2.3.1}/tests/unit/ai/engines/test_pydantic_ai_failures.py

@@ -8,14 +8,17 @@ so the translation never drifts silently.
 
 from __future__ import annotations
 
+import logging
 import typing
+from collections.abc import AsyncIterator, Mapping
 
 import pytest
 from pydantic_ai.exceptions import ModelAPIError, ModelHTTPError, UnexpectedModelBehavior
-from pydantic_ai.messages import AgentStreamEvent
+from pydantic_ai.messages import AgentStreamEvent, ModelMessage, ModelResponse, ToolCallPart
+from pydantic_ai.models.function import AgentInfo, DeltaToolCall, DeltaToolCalls, FunctionModel
 
-from loom.ai.abc import AgentEngine
-from loom.ai.engines.pydantic_ai._engine import PydanticAIEngine
+from loom.ai.abc import AgentEngine, ErrorEvent
+from loom.ai.engines.pydantic_ai._engine import MAX_LOGGED_CAUSE_CHARS, PydanticAIEngine
 from loom.ai.engines.pydantic_ai._errors import classify
 from loom.ai.engines.pydantic_ai._events import IGNORED_EVENT_KINDS, MAPPED_EVENT_KINDS
 from loom.ai.errors import AgentRunErrorClass, AgentRunErrorCode, is_retriable, run_error_class
@@ -32,6 +35,7 @@ from tests.helpers.pydantic_ai_engine import (
 )
 
 _IDENTITY = Identity(subject="caller")
+_ANSWER: Mapping[str, str] = {"answer": "ok"}
 
 
 def _http(status: int) -> ModelHTTPError:
@@ -154,6 +158,77 @@ class TestTheUnreachableGuardStaysUnclassified:
                     pass
 
 
+def _damaged_stream_model(payload: bytes) -> FunctionModel:
+    """A model whose stream drops the first two characters of every tool call."""
+    text = payload.decode()
+
+    def respond(messages: list[ModelMessage], info: AgentInfo) -> ModelResponse:
+        return ModelResponse(parts=[ToolCallPart(info.output_tools[0].name, text)])
+
+    async def stream(
+        messages: list[ModelMessage], info: AgentInfo
+    ) -> AsyncIterator[DeltaToolCalls]:
+        name = info.output_tools[0].name
+        damaged = DeltaToolCall(name=name, json_args=text[2:], tool_call_id="c")
+        yield {0: damaged}
+
+    return FunctionModel(respond, stream_function=stream)
+
+
+def _damaged_whole_model(payload: bytes) -> FunctionModel:
+    """A model whose whole response drops the first two characters of its tool call."""
+    text = payload.decode()
+
+    def respond(messages: list[ModelMessage], info: AgentInfo) -> ModelResponse:
+        return ModelResponse(parts=[ToolCallPart(info.output_tools[0].name, text[2:])])
+
+    return FunctionModel(respond)
+
+
+async def test_the_answer_that_broke_the_schema_is_logged_and_never_published(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """The caller is told the code; the operator is told which answer broke it."""
+    engine = build_engine(make_plan(), _damaged_stream_model(encode(_ANSWER)))
+
+    with caplog.at_level(logging.WARNING):
+        async with engine.run_stream("assess", identity=_IDENTITY) as events:
+            failure = [event async for event in events][-1]
+
+    assert isinstance(failure, ErrorEvent)
+    assert "answer" not in failure.message
+    assert any('answer":"ok"}' in record.getMessage() for record in caplog.records)
+
+
+async def test_the_logged_cause_is_truncated(caplog: pytest.LogCaptureFixture) -> None:
+    """A run's damaged answer is model-authored text, so the log caps how much it keeps."""
+    huge_payload = encode({"answer": "x" * (MAX_LOGGED_CAUSE_CHARS * 2)})
+    engine = build_engine(make_plan(), _damaged_stream_model(huge_payload))
+
+    with caplog.at_level(logging.WARNING):
+        async with engine.run_stream("assess", identity=_IDENTITY) as events:
+            async for _ in events:
+                pass
+
+    cause_records = [
+        record.getMessage() for record in caplog.records if "raised from" in record.getMessage()
+    ]
+    assert cause_records
+    assert all(len(record) < MAX_LOGGED_CAUSE_CHARS * 2 for record in cause_records)
+
+
+async def test_the_answer_that_broke_the_schema_on_a_plain_run_is_logged_too(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """``engine.run`` shares ``_log_cause`` with the streamed path; this pins its own call site."""
+    engine = build_engine(make_plan(), _damaged_whole_model(encode(_ANSWER)))
+
+    with caplog.at_level(logging.WARNING), pytest.raises(AgentRunError):
+        await engine.run("assess", identity=_IDENTITY)
+
+    assert any("raised from" in record.getMessage() for record in caplog.records)
+
+
 class _AttemptCounter:
     """Callable raising the same failure and counting how often it was asked."""
 

loom_kernel-2.3.1/tests/unit/ai/engines/test_pydantic_ai_streaming_off.py

@@ -0,0 +1,207 @@
+"""A binding declaring ``streaming: false`` asks the provider for each answer whole.
+
+The run is still walked as events -- tool calls, tool results, the terminal
+one -- but the model is never asked to stream, so a model whose streamed tool
+calls arrive damaged can still be served.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Mapping
+from dataclasses import dataclass
+
+import msgspec
+from pydantic_ai.messages import (
+    ModelMessage,
+    ModelResponse,
+    TextPart,
+    ToolCallPart,
+    ToolReturnPart,
+)
+from pydantic_ai.models.function import AgentInfo, DeltaToolCall, DeltaToolCalls, FunctionModel
+from pydantic_ai.output import StructuredDict
+from pydantic_ai.toolsets import FunctionToolset
+
+from loom.ai.abc import (
+    ErrorEvent,
+    FinalEvent,
+    TextDeltaEvent,
+    ToolCallEvent,
+    ToolResultEvent,
+)
+from loom.ai.compiler import CompiledPythonCapability
+from loom.ai.inference import InferenceTarget
+from loom.core.di import LoomContainer
+from loom.core.identity import Identity
+from tests.helpers.pydantic_ai_engine import build_engine, encode, make_plan
+
+_IDENTITY = Identity(subject="caller")
+_ANSWER: Mapping[str, str] = {"answer": "ok"}
+_WHOLE = InferenceTarget(provider="bedrock", model="a-model", region="eu-west-1", streaming=False)
+_STREAMED = msgspec.structs.replace(_WHOLE, streaming=True)
+
+
+def _whole_only_model(payload: bytes) -> FunctionModel:
+    """A model that answers only when asked whole: it declares no stream function."""
+
+    def respond(messages: list[ModelMessage], info: AgentInfo) -> ModelResponse:
+        return ModelResponse(parts=[ToolCallPart(info.output_tools[0].name, payload.decode())])
+
+    return FunctionModel(respond)
+
+
+def _damaged_stream_model(payload: bytes) -> FunctionModel:
+    """A model whose stream drops the first two characters of every tool call."""
+    text = payload.decode()
+
+    def respond(messages: list[ModelMessage], info: AgentInfo) -> ModelResponse:
+        return ModelResponse(parts=[ToolCallPart(info.output_tools[0].name, text)])
+
+    async def stream(
+        messages: list[ModelMessage], info: AgentInfo
+    ) -> AsyncIterator[DeltaToolCalls]:
+        name = info.output_tools[0].name
+        damaged = DeltaToolCall(name=name, json_args=text[2:], tool_call_id="c")
+        yield {0: damaged}
+
+    return FunctionModel(respond, stream_function=stream)
+
+
+@dataclass(frozen=True)
+class _Bundle:
+    """The attributes a capability call is gated on."""
+
+    identity: Identity
+    container: LoomContainer
+
+
+class _CallerDeps:
+    """A factory whose bundle lets the agent reach its tools."""
+
+    def build(self, identity: Identity, container: LoomContainer, state: object = None) -> object:
+        return _Bundle(identity=identity, container=container)
+
+
+def _talking_model(payload: bytes) -> FunctionModel:
+    """A model that says something before answering."""
+
+    def respond(messages: list[ModelMessage], info: AgentInfo) -> ModelResponse:
+        said = TextPart("lo he mirado")
+        return ModelResponse(
+            parts=[said, ToolCallPart(info.output_tools[0].name, payload.decode())]
+        )
+
+    return FunctionModel(respond)
+
+
+def _two_texts_model(payload: bytes) -> FunctionModel:
+    """A model that says two things before answering."""
+
+    def respond(messages: list[ModelMessage], info: AgentInfo) -> ModelResponse:
+        parts = [
+            TextPart("lo he mirado"),
+            TextPart("y esto es lo que veo"),
+            ToolCallPart(info.output_tools[0].name, payload.decode()),
+        ]
+        return ModelResponse(parts=parts)
+
+    return FunctionModel(respond)
+
+
+def _tool_then_answer_model(payload: bytes) -> FunctionModel:
+    """A model that calls ``lookup`` first and answers on the turn after."""
+
+    def respond(messages: list[ModelMessage], info: AgentInfo) -> ModelResponse:
+        returned = any(
+            isinstance(part, ToolReturnPart)
+            for message in messages
+            for part in getattr(message, "parts", ())
+        )
+        if not returned:
+            return ModelResponse(parts=[ToolCallPart("_lookup", {"city": "Vigo"})])
+        return ModelResponse(parts=[ToolCallPart(info.output_tools[0].name, payload.decode())])
+
+    return FunctionModel(respond)
+
+
+async def test_the_text_of_a_whole_answer_reaches_the_caller_as_one_delta() -> None:
+    """Whole or streamed, a caller watching the run still sees what the model said."""
+    engine = build_engine(make_plan(inference=_WHOLE), _talking_model(encode(_ANSWER)))
+
+    async with engine.run_stream("assess", identity=_IDENTITY) as events:
+        seen = [event async for event in events]
+
+    assert [event for event in seen if isinstance(event, TextDeltaEvent)] == [
+        TextDeltaEvent(text="lo he mirado")
+    ]
+    assert isinstance(seen[-1], FinalEvent)
+    assert seen[-1].output == _ANSWER
+
+
+async def test_a_whole_answer_with_two_text_parts_reaches_the_caller_as_two_deltas() -> None:
+    """One delta per text part, not one per response: two parts, two deltas, in order."""
+    engine = build_engine(make_plan(inference=_WHOLE), _two_texts_model(encode(_ANSWER)))
+
+    async with engine.run_stream("assess", identity=_IDENTITY) as events:
+        seen = [event async for event in events]
+
+    assert [event for event in seen if isinstance(event, TextDeltaEvent)] == [
+        TextDeltaEvent(text="lo he mirado"),
+        TextDeltaEvent(text="y esto es lo que veo"),
+    ]
+    assert isinstance(seen[-1], FinalEvent)
+    assert seen[-1].output == _ANSWER
+
+
+async def _terminal(engine: object) -> object:
+    """The last event of a streamed run: what a supervised caller finally sees."""
+    async with engine.run_stream("assess", identity=_IDENTITY) as events:  # type: ignore[attr-defined]
+        return [event async for event in events][-1]
+
+
+async def test_a_damaged_stream_is_what_asking_whole_is_for() -> None:
+    model = _damaged_stream_model(encode(_ANSWER))
+
+    streamed = await _terminal(build_engine(make_plan(inference=_STREAMED), model))
+    whole = await _terminal(build_engine(make_plan(inference=_WHOLE), model))
+
+    assert isinstance(streamed, ErrorEvent)
+    assert isinstance(whole, FinalEvent)
+    assert whole.output == _ANSWER
+
+
+async def test_a_shaped_run_is_served_whole_too() -> None:
+    """``expect=``/``run_text`` reach the same attempt, so they get the same road."""
+    shape = StructuredDict({"type": "object"})
+    engine = build_engine(make_plan(inference=_WHOLE), _whole_only_model(encode(_ANSWER)))
+
+    async with engine.run_stream_shaped("assess", identity=_IDENTITY, output_type=shape) as events:
+        seen = [event async for event in events]
+
+    assert isinstance(seen[-1], FinalEvent)
+    assert seen[-1].output == _ANSWER
+
+
+async def test_tool_calls_and_their_results_still_reach_the_caller() -> None:
+    """A memoized node's stream must run its tool exactly once: ``run.next`` does not
+    re-execute a node the caller already streamed, so an event-shape assertion alone would
+    not catch a silent second execution of a granted operation."""
+    calls = 0
+
+    def _lookup(city: str) -> str:
+        nonlocal calls
+        calls += 1
+        return f"{city}: sunny"
+
+    capability = CompiledPythonCapability(
+        factory_ref="tests:factory",
+        factory=lambda context: FunctionToolset([_lookup], max_retries=0),
+    )
+    plan = msgspec.structs.replace(make_plan(inference=_WHOLE), capabilities=(capability,))
+    engine = build_engine(plan, _tool_then_answer_model(encode(_ANSWER)), deps=_CallerDeps())
+
+    async with engine.run_stream("weather?", identity=_IDENTITY) as events:
+        seen = [event async for event in events]
+
+    assert [type(event) for event in seen] == [ToolCallEvent, ToolResultEvent, FinalEvent]
+    assert calls == 1