flowra 0.0.92.dev109__tar.gz → 0.0.92.dev110__tar.gz

{flowra-0.0.92.dev109 → flowra-0.0.92.dev110}/CHANGELOG.md

@@ -9,29 +9,24 @@ and this project adheres to [Semantic Versioning](https://semver.org).
 
 ### Added
 - **`BeforeToolCallsEvent`: answer a model message's tool calls before any
-  runs.** Emitted once per model message with tool calls, a single call
-  included, with every call of the message in `tool_uses`, a call the response cut off
-  included (an answer under its id is not used). A handler puts a
-  `ToolResult` into `results` under a call's id to answer that call itself:
-  it does not run, the other calls run as usual, and its result reaches the
-  model in the message's order. An answered call gets no
-  `BeforeToolCallEvent` and no `ToolCallSpan`; it goes through
-  `AfterToolCallEvent` and counts toward `max_consecutive_errors` like any
-  result. An error answered without an `error_kind` gets
-  `ToolErrorKind.EXECUTION`; a key that is not the id of a call in the message
-  raises `ValueError`. Answered calls are kept in the turn's state, so they
-  survive a resume before the results are collected.
+  runs.** It fires once per model message that has tool calls, even when it
+  has only one, and lists them in `tool_uses`. A handler puts a `ToolResult`
+  into `results` under a call's id: that call does not run, and the model gets
+  the handler's answer. Use it for a rule about the message as a whole, such as
+  a tool that must be called alone. Details in
+  [Pre-built events](docs/observability.md#pre-built-events).
 - **`AfterToolCallEvent.prefilled`**: true for a call answered in
   `BeforeToolCallsEvent`, so a handler can tell that the tool did not run.
 
 ### Changed
-- **A call's answer carries an `error_kind` exactly when it is an error.**
-  `ToolCallResult` sets `ToolErrorKind.EXECUTION` for an error that came
-  without a kind — a `ToolResult(is_error=True)` a tool or an agent tool
-  returns, "Tool execution interrupted" — and drops a kind from an answer that
-  is not an error. `AfterToolCallEvent.error_kind` and `ToolCallSpan.error_kind`
-  follow, so a consumer telling an error by its kind no longer reads such an
-  error as a success.
+- **A call's answer carries an `error_kind` exactly when it is an error.** An
+  error that comes without a kind reaches `AfterToolCallEvent` and
+  `ToolCallSpan` as `ToolErrorKind.EXECUTION`, and an answer that is not an
+  error carries no kind. A consumer that tells an error by its kind now sees
+  every error. Details in [Error handling](docs/tools.md#errors-the-tool-chooses).
+- **A `BeforeToolCallEvent` handler that changes a call's `id` raises
+  `ValueError`.** The id ties a call to its result, so a replaced `tool_use`
+  keeps it.
 
 ## [0.0.91] - 2026-10-20
 

{flowra-0.0.92.dev109 → flowra-0.0.92.dev110}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: flowra
-Version: 0.0.92.dev109
+Version: 0.0.92.dev110
 Summary: Flowra — flow infrastructure for building stateful LLM agents
 Project-URL: Repository, https://github.com/anna-money/flowra
 Project-URL: Changelog, https://github.com/anna-money/flowra/blob/master/CHANGELOG.md

{flowra-0.0.92.dev109 → flowra-0.0.92.dev110}/context7.json

@@ -134,7 +134,7 @@
     "RENDER: ChatConfig.render / TurnConfig.render (PromptRender = Callable[[Prompt], Prompt | Awaitable[Prompt]]; Prompt from flowra.lib.turn has system and messages) is called once per LLM call of the turn (not per fallback attempt), before LLMCaller, with the system messages and the conversation (history, then turn messages). What it returns is sent to every fallback link; each link's request_extensions apply after it, and each attempt's LLMCallSpan carries the request with them applied. Stored history and turn messages are not changed, so a marker block can be rendered from live state on each call; build new messages, never edit the given ones. Messages left with no blocks are not sent, none left at all is a ValueError before the call; a tool call must still be followed straight away by its results (Claude and OpenAI Chat Completions reject anything in between); an error in render is raised from the turn as is; an interrupt stops an async render and ends the turn INTERRUPTED",
     "TurnAgent lifecycle: __post_init__ emits TurnReadyEvent(context, turn_messages) — fires on both creation and crash recovery. ChatAgent subscribes and emits ConversationReadyEvent(conversation, context) with a Conversation view combining history + turn messages",
     "Conversation class (from flowra.lib.chat): read-only Sequence view over history + turn_messages. Supports len(), indexing, slicing, forward/reverse iteration. Live — reflects changes to underlying lists. Properties: history_len, turn_len. Method without_pending_tool_use() -> list[UserMessage | AssistantMessage] returns messages with ToolUseBlocks stripped from the last AssistantMessage (drops the message entirely if it becomes empty) — use it inside an agent-as-tool to feed the parent conversation to a child LLM call without the unresolved tool-use that spawned it",
-    "TurnAgent hook events: StartTurnEvent (messages, metadata — mutate messages to augment input), MessageAcceptedEvent, StartIterationEvent, TextReasoningEvent (each TextBlock with text in response), ThinkingEvent (each ThinkingBlock with text; not redacted or signature-only thoughts), ServerToolCallEvent (server-side tool call from intermediate messages, e.g. tool search), ServerToolResultEvent (server-side tool result), ResultMessageEvent, BeforeToolCallsEvent (once per model message with tool calls, before any runs; tool_uses is every call of the message, a cut-off call included (an answer under its id is not used); put a ToolResult into results under a call's id to answer it without running it — that call gets no BeforeToolCallEvent and no ToolCallSpan, its result goes through AfterToolCallEvent with prefilled=True and max_consecutive_errors in message order, an error without error_kind gets EXECUTION; a key not among the message's call ids raises ValueError), BeforeToolCallEvent (has tool_definition: ToolDefinition | None; mutable tool_use, headers, meta — see ToolCallInfo; not emitted for a call answered in BeforeToolCallsEvent), AfterToolCallEvent (fires after execution, and for a call answered in BeforeToolCallsEvent; has error_kind; prefilled is true for a call answered in BeforeToolCallsEvent; result is a single ToolResultBlock; append TextBlock/MediaBlock to additional_blocks to attach them to this call's result — they go at the end of its content, also when max_consecutive_errors replaces it, so they stay with their call and never land between the results of parallel calls; mark one transient to keep it out of saved history; being part of the result, a MediaBlock there takes the providers' rules for media in a tool result (Chat Completions raises, Gemini before 3 does not see it) and a transient block ends the non-transient cache prefix before the result). Delta events: TextDeltaEvent, ThinkingDeltaEvent (from flowra.lib.observability — shared with LLMCallAgent). UsageEvent emitted after each LLM call + subscribed to accumulate usage from child agents (e.g. agent_as_tool). Span-hooks: LLMCallSpan, ToolCallSpan. Request transforms (prompt caching, tool search) are NOT hooks — they live on LLMConfig.request_extensions. A conversation transform for every fallback link goes in ChatConfig.render / TurnConfig.render (see RENDER)",
+    "TurnAgent hook events: StartTurnEvent (messages, metadata — mutate messages to augment input), MessageAcceptedEvent, StartIterationEvent, TextReasoningEvent (each TextBlock with text in response), ThinkingEvent (each ThinkingBlock with text; not redacted or signature-only thoughts), ServerToolCallEvent (server-side tool call from intermediate messages, e.g. tool search), ServerToolResultEvent (server-side tool result), ResultMessageEvent, BeforeToolCallsEvent (once per model message that has tool calls, even when it has only one, before any runs; tool_uses is every call of the message, a cut-off call included (an answer under its id is not used); put a ToolResult into results under a call's id to answer it without running it — that call gets no BeforeToolCallEvent and no ToolCallSpan, its result goes through AfterToolCallEvent with prefilled=True and max_consecutive_errors in message order, an error without error_kind gets EXECUTION; an answered call is not looked up in the registry, so an answer to an unknown or denied tool reaches the model as given, not as Unknown tool; a key not among the message's call ids raises ValueError), BeforeToolCallEvent (has tool_definition: ToolDefinition | None; mutable tool_use (a replacement keeps the call's id; changing it raises ValueError), headers, meta — see ToolCallInfo; not emitted for a call answered in BeforeToolCallsEvent), AfterToolCallEvent (fires after execution, and for a call answered in BeforeToolCallsEvent; has error_kind; prefilled is true for a call answered in BeforeToolCallsEvent; result is a single ToolResultBlock; append TextBlock/MediaBlock to additional_blocks to attach them to this call's result — they go at the end of its content, also when max_consecutive_errors replaces it, so they stay with their call and never land between the results of parallel calls; mark one transient to keep it out of saved history; being part of the result, a MediaBlock there takes the providers' rules for media in a tool result (Chat Completions raises, Gemini before 3 does not see it) and a transient block ends the non-transient cache prefix before the result). Delta events: TextDeltaEvent, ThinkingDeltaEvent (from flowra.lib.observability — shared with LLMCallAgent). UsageEvent emitted after each LLM call + subscribed to accumulate usage from child agents (e.g. agent_as_tool). Span-hooks: LLMCallSpan, ToolCallSpan. Request transforms (prompt caching, tool search) are NOT hooks — they live on LLMConfig.request_extensions. A conversation transform for every fallback link goes in ChatConfig.render / TurnConfig.render (see RENDER)",
     "When TextDeltaEvent or ThinkingDeltaEvent handlers are registered, TurnAgent automatically uses provider.stream() instead of provider.call()",
 
     "AGENTS AS TOOLS: Tools can delegate to sub-agents via ToolCallAgentContext.call_agent(). make_agent_tool(AgentClass, name, description) creates an ExecutableTool with input_schema from spec type and output_schema from result type (ToolResult excluded). @agent_tool decorator marks an agent class as a tool, get_agent_tool() extracts the ExecutableTool. ToolCallAgent spawns the sub-agent and serializes its result as a ToolResultBlock. Agent tools can return ToolResult directly to signal errors to the parent LLM or answer with blocks (e.g. return ToolResult(content='...', is_error=True)) — the agent completes normally; with is_error=True the parent LLM sees a tool error and can retry. Compile-time validation: step return types must be a subset of Agent's generic result type parameter. The sub-agent must be declared by the agent running the tool or one of its registry ancestors (top level works); it receives services of its own registry ancestors, not the calling chat's (unless the chat is one of them)",

{flowra-0.0.92.dev109 → flowra-0.0.92.dev110}/docs/agents.md

@@ -808,9 +808,10 @@ Lifecycle events (from `flowra.lib.turn`):
 | `ResultMessageEvent`     | LLM finished (END_TURN)                  | `continue_messages`                           |
 
 A tool call cut off by the output limit appears in `BeforeToolCallsEvent` but
-fires no `BeforeToolCallEvent` or `AfterToolCallEvent`, and a call answered in
-`BeforeToolCallsEvent` does not run; see
-[Pre-built events](observability.md#pre-built-events) in Observability.
+fires no `BeforeToolCallEvent` or `AfterToolCallEvent`. A call a handler answers
+in `BeforeToolCallsEvent.results` does not run; it still fires
+`AfterToolCallEvent`. See [Pre-built events](observability.md#pre-built-events)
+in Observability.
 
 Streaming events (from `flowra.lib.observability`):
 

{flowra-0.0.92.dev109 → flowra-0.0.92.dev110}/docs/observability.md

@@ -69,21 +69,18 @@ def add_hint(event: Event[AfterToolCallEvent]) -> None:
 runtime.hooks.on(AfterToolCallEvent, add_hint)
 ```
 
-A tool call cut off by the output limit (see [TurnAgent](agents.md#turnagent)) is
-never executed. It gets an error result directly, with no `BeforeToolCallEvent`,
-`AfterToolCallEvent` or `ToolCallSpan`, so hooks that audit or rewrite tool
-results don't see it; it does appear in `BeforeToolCallsEvent.tool_uses`, and an
-answer put under its id is not used.
-
-`BeforeToolCallsEvent` fires once per model message with tool calls, a single
-call included, before any of them runs. A handler answers a call itself by
-putting a `ToolResult` into `results` under the call's id: that call does not
+`BeforeToolCallsEvent` fires once per model message that has tool calls, even
+when it has only one, before any of them runs. A handler answers a call itself
+by putting a `ToolResult` into `results` under the call's id: that call does not
 run, and the others run as usual. An answered call gets no `BeforeToolCallEvent`
 and no `ToolCallSpan`; its result goes through `AfterToolCallEvent` (with
 `prefilled=True`) and `max_consecutive_errors` like any other, in the message's
 order. An error answered without an `error_kind` arrives with
-`ToolErrorKind.EXECUTION`, as any error a tool gives without one does. A key that is not the id of a call in the message
-fails the step with `ValueError`.
+`ToolErrorKind.EXECUTION`, as any error a tool gives without one does. An
+answered call is not looked up in the registry, so a handler can answer a call
+to a tool that is unknown or denied: the model gets the handler's answer, not
+`Unknown tool`. A key that is not the id of a call in the message raises
+`ValueError`.
 
 ```python
 from flowra.agent import Event
@@ -104,6 +101,12 @@ def reply_alone(event: Event[BeforeToolCallsEvent]) -> None:
 runtime.hooks.on(BeforeToolCallsEvent, reply_alone)
 ```
 
+A tool call cut off by the output limit (see [TurnAgent](agents.md#turnagent)) is
+never executed. It gets an error result directly, with no `BeforeToolCallEvent`,
+`AfterToolCallEvent` or `ToolCallSpan`, so hooks that audit or rewrite tool
+results don't see it. It does appear in `BeforeToolCallsEvent.tool_uses`, but an
+answer put under its id is not used.
+
 A tool call that fails the run (an exception raised around a tool's executor,
 see [Error handling](tools.md#what-fails-the-run)) has no result:
 `AfterToolCallEvent` doesn't fire, and its `ToolCallSpan` closes with `error`
@@ -137,8 +140,10 @@ runtime = AgentRuntime(agents={...}, services={...})
 runtime.hooks.on(BeforeToolCallEvent, on_before_tool)
 ```
 
-A `BeforeToolCallEvent` handler can also fill `headers` and `meta` to pass
-per-call data to the tool — see [ToolCallInfo](tools.md#toolcallinfo).
+A `BeforeToolCallEvent` handler can replace `tool_use` to change a call's input,
+but the new block keeps the call's `id`: changing the id raises `ValueError`.
+It can also fill `headers` and `meta` to pass per-call data to the
+tool — see [ToolCallInfo](tools.md#toolcallinfo).
 
 Use `event.context.find_spec(SpecType)` to walk the execution stack and find
 the spec of a parent agent — useful for identifying which model or session is

{flowra-0.0.92.dev109 → flowra-0.0.92.dev110}/docs/tools.md

@@ -685,8 +685,10 @@ async def respond(params: RespondParams) -> Sent:
 list of blocks; `exc.result` is the `ToolResult` it stands for. Returning
 `ToolResult(content=..., is_error=True, error_kind=ToolErrorKind.EXECUTION)`
 gives the same answer. Without `error_kind`, an error still reaches hooks and
-spans as `EXECUTION`: a call's answer carries a kind exactly when it is an
-error, so `error_kind is not None` and `is_error` never disagree.
+spans as `EXECUTION`. What they receive (`ToolCallResult`, `AfterToolCallEvent`,
+`ToolCallSpan`) carries a kind exactly when it is an error, so there
+`error_kind is not None` and `is_error` never disagree. The `ToolResult` that
+`registry.execute` returns keeps the kind the tool gave it.
 
 `ToolError` is for `@tool` functions: only their executor answers it. An agent
 behind an [agent tool](#agents-as-tools) returns its error as a `ToolResult`

{flowra-0.0.92.dev109 → flowra-0.0.92.dev110}/flowra/lib/turn/agent.py

@@ -36,7 +36,7 @@ from ...llm import (
     Usage,
     UserMessage,
 )
-from ...tools import ToolRegistry, ToolResult
+from ...tools import ToolRegistry
 from ..config_value import resolve_config_value
 from ..llm_caller import DEFAULT_LLM_CALLER, LLMCaller
 from ..observability import UsageEvent
@@ -64,10 +64,18 @@ __all__ = ["TurnAgent"]
 logger = logging.getLogger(__name__)
 
 
+@dataclasses.dataclass(frozen=True, slots=True, kw_only=True)
+class _AnsweredCalls:
+    """The calls a ``BeforeToolCallsEvent`` handler answered, with the ids of the message's calls that can run,
+    in the message's order."""
+
+    results: list[ToolCallResult]
+    call_order: list[str]
+
+
 class TurnAgent(Agent[TurnSpec, TurnResult]):
     __slots__ = (
-        "__answered_tool_results",
-        "__call_order",
+        "__answered_calls",
         "__caller",
         "__config",
         "__consecutive_errors",
@@ -100,8 +108,7 @@ class TurnAgent(Agent[TurnSpec, TurnResult]):
         self.__usage = store.ephemeral.slot(Scalar[Usage | None], "usage")
         self.__consecutive_errors = store.ephemeral.slot(Scalar[dict[str, int]], "consecutive_errors")
         self.__incomplete_tool_result = store.ephemeral.slot(Scalar[ToolResultBlock | None], "incomplete_tool_result")
-        self.__answered_tool_results = store.ephemeral.slot(Scalar[list[ToolCallResult]], "answered_tool_results")
-        self.__call_order = store.ephemeral.slot(Scalar[list[str]], "call_order")
+        self.__answered_calls = store.ephemeral.slot(Scalar[_AnsweredCalls | None], "answered_calls")
         self.__interrupt = interrupt
         self.__context = TurnAgentContext()
         self.__config = config
@@ -296,9 +303,9 @@ class TurnAgent(Agent[TurnSpec, TurnResult]):
         consecutive_errors = dict(self.__consecutive_errors.get({}))
         max_consecutive = await resolve_config_value(self.__config.max_consecutive_errors)
 
-        answered = self.__answered_tool_results.get([])
-        answered_ids = {tc_result.tool_use.id for tc_result in answered}
-        collected = self.__in_call_order([*answered, *results]) if answered else results
+        answered = self.__answered_calls.get(None)
+        answered_ids = {tc_result.tool_use.id for tc_result in answered.results} if answered is not None else set()
+        collected = self.__in_call_order(answered, results) if answered is not None else results
         for tc_result in collected:
             after_event = await self.__hooks.emit(
                 AfterToolCallEvent(
@@ -343,9 +350,8 @@ class TurnAgent(Agent[TurnSpec, TurnResult]):
         if incomplete_result is not None:
             result_blocks.append(incomplete_result)
             self.__incomplete_tool_result.set(None)
-        if answered:
-            self.__answered_tool_results.set([])
-            self.__call_order.set([])
+        if answered is not None:
+            self.__answered_calls.set(None)
 
         self.__consecutive_errors.set(consecutive_errors)
         user_message = UserMessage(blocks=list(result_blocks))
@@ -398,13 +404,14 @@ class TurnAgent(Agent[TurnSpec, TurnResult]):
                 raise ValueError(f"No tool call {tool_use_id!r} in this message")
         # Answers are taken from the calls that can run, so the cut-off call keeps its own error result
         answered = [
-            self.__answered_result(tool_use, calls_event.results[tool_use.id])
+            ToolCallResult.from_tool_result(tool_use, calls_event.results[tool_use.id])
             for tool_use in tool_uses
             if tool_use.id in calls_event.results
         ]
         if answered:
-            self.__answered_tool_results.set(answered)
-            self.__call_order.set([tool_use.id for tool_use in tool_uses])
+            self.__answered_calls.set(
+                _AnsweredCalls(results=answered, call_order=[tool_use.id for tool_use in tool_uses])
+            )
 
         amendments: dict[str, ToolUseBlock] = {}
         final_calls: list[BeforeToolCallEvent] = []
@@ -418,6 +425,11 @@ class TurnAgent(Agent[TurnSpec, TurnResult]):
                     context=self.__context,
                 )
             )
+            if before_event.tool_use.id != tool_use.id:
+                raise ValueError(
+                    f"A BeforeToolCallEvent handler changed the id of tool call {tool_use.id!r} to "
+                    f"{before_event.tool_use.id!r}; a call's id must stay as the model gave it"
+                )
             final_calls.append(before_event)
             if before_event.tool_use is not tool_use:
                 amendments[tool_use.id] = before_event.tool_use
@@ -447,19 +459,12 @@ class TurnAgent(Agent[TurnSpec, TurnResult]):
         ]
         return Spawn(children=children, then=self.collect_results)
 
-    def __in_call_order(self, results: list[ToolCallResult]) -> list[ToolCallResult]:
+    @staticmethod
+    def __in_call_order(answered: _AnsweredCalls, results: list[ToolCallResult]) -> list[ToolCallResult]:
         # By the order the message's calls had when they were made, kept beside the answers: it holds
         # whatever the history looks like by the time the results are collected
-        position = {tool_use_id: i for i, tool_use_id in enumerate(self.__call_order.get([]))}
-        return sorted(results, key=lambda tc_result: position[tc_result.tool_use.id])
-
-    @staticmethod
-    def __answered_result(tool_use: ToolUseBlock, result: ToolResult) -> ToolCallResult:
-        return ToolCallResult(
-            tool_use=tool_use,
-            result=ToolResultBlock(tool_use_id=tool_use.id, content=result.blocks, is_error=result.is_error),
-            error_kind=result.error_kind,
-        )
+        position = {tool_use_id: i for i, tool_use_id in enumerate(answered.call_order)}
+        return sorted([*answered.results, *results], key=lambda tc_result: position[tc_result.tool_use.id])
 
     @staticmethod
     def __incomplete_tool_use_message(stop_reason: StopReason) -> str:

{flowra-0.0.92.dev109 → flowra-0.0.92.dev110}/flowra/lib/turn/hook_events.py

@@ -105,6 +105,8 @@ class BeforeToolCallsEvent:
     An answer under the cut-off call's id is not used: that call always gets its own error result.
     Put a ``ToolResult`` into ``results`` under a call's id to answer it without running it: the
     other calls run as usual, and the result reaches the model as that call's answer.
+    An answered call is not looked up in the registry, so a handler can answer a call to a tool that
+    is unknown or denied: the model gets the handler's answer, not ``Unknown tool``.
     """
 
     tool_uses: list[ToolUseBlock]
@@ -117,7 +119,8 @@ class BeforeToolCallEvent:
     """Emitted before each tool execution.
 
     Replace ``tool_use`` to modify tool parameters (e.g. sanitize input,
-    inject defaults).
+    inject defaults). The replacement keeps the call's ``id``: changing it
+    raises ``ValueError``.
 
     Fill ``headers`` and ``meta`` to pass per-call data the model never sees:
     MCP tools send them as HTTP headers and ``params._meta`` of the

{flowra-0.0.92.dev109 → flowra-0.0.92.dev110}/flowra/lib/turn/tool_call/agent.py

@@ -58,6 +58,14 @@ class ToolCallResult:
         error_kind = (self.error_kind or ToolErrorKind.EXECUTION) if self.result.is_error else None
         object.__setattr__(self, "error_kind", error_kind)
 
+    @classmethod
+    def from_tool_result(cls, tool_use: ToolUseBlock, result: ToolResult) -> "ToolCallResult":
+        return cls(
+            tool_use=tool_use,
+            result=ToolResultBlock(tool_use_id=tool_use.id, content=result.blocks, is_error=result.is_error),
+            error_kind=result.error_kind,
+        )
+
 
 class ToolCallAgent(Agent[ToolCallSpec, ToolCallResult]):
     """Executes a single tool call and returns the result.
@@ -150,12 +158,7 @@ class ToolCallAgent(Agent[ToolCallSpec, ToolCallResult]):
                 then=self.collect_agent_result,
             )
 
-        result = ToolResultBlock(
-            tool_use_id=tool_use.id,
-            content=execution_result.blocks,
-            is_error=execution_result.is_error,
-        )
-        return ToolCallResult(tool_use=tool_use, result=result, error_kind=execution_result.error_kind)
+        return ToolCallResult.from_tool_result(tool_use, execution_result)
 
     @step("collect_agent_result")
     async def collect_agent_result(self, agent_result: Annotated[Any, agent_arg.CHILD]) -> ToolCallResult:
@@ -163,19 +166,9 @@ class ToolCallAgent(Agent[ToolCallSpec, ToolCallResult]):
         if isinstance(agent_result, Interrupted):
             return self.__error_result(tool_use, "Tool execution interrupted")
         if isinstance(agent_result, ToolResult):
-            result = ToolResultBlock(
-                tool_use_id=tool_use.id,
-                content=agent_result.blocks,
-                is_error=agent_result.is_error,
-            )
-            error_kind = agent_result.error_kind
-        else:
-            result = ToolResultBlock(
-                tool_use_id=tool_use.id,
-                content=[TextBlock(text=format_result(agent_result))],
-            )
-            error_kind = None
-        return ToolCallResult(tool_use=tool_use, result=result, error_kind=error_kind)
+            return ToolCallResult.from_tool_result(tool_use, agent_result)
+        result = ToolResultBlock(tool_use_id=tool_use.id, content=[TextBlock(text=format_result(agent_result))])
+        return ToolCallResult(tool_use=tool_use, result=result)
 
     @staticmethod
     def __error_result(tool_use: ToolUseBlock, content: str, error_kind: ToolErrorKind | None = None) -> ToolCallResult:

{flowra-0.0.92.dev109 → flowra-0.0.92.dev110}/flowra/version.py

@@ -1,4 +1,4 @@
 # Updated by CI/CD pipeline (the __version__ line only)
 __all__ = ["__version__"]
 
-__version__ = "0.0.92.dev109"
+__version__ = "0.0.92.dev110"

{flowra-0.0.92.dev109 → flowra-0.0.92.dev110}/tests/lib/test_turn_agent.py

@@ -19,7 +19,7 @@ from flowra.agent import (
 )
 from flowra.agent.flow.hooks import HooksImpl
 from flowra.lib import LLMConfig
-from flowra.lib.observability import LLMCallSpan, TextDeltaEvent, ThinkingDeltaEvent, UsageEvent
+from flowra.lib.observability import LLMCallSpan, TextDeltaEvent, ThinkingDeltaEvent, ToolCallSpan, UsageEvent
 from flowra.lib.turn import (
     AfterToolCallEvent,
     BeforeToolCallEvent,
@@ -2466,8 +2466,8 @@ def _calls_a_and_b() -> ScriptedProvider:
     )
 
 
-def _cut_off_after_a(provider_type: type[ScriptedProvider]) -> ScriptedProvider:
-    return provider_type(
+def _cut_off_after_a() -> ScriptedProvider:
+    return ScriptedProvider(
         LLMResponse(
             messages=[
                 AssistantMessage(
@@ -2527,6 +2527,25 @@ class TestTurnAgentBeforeToolCalls:
         assert before == ["b1"]
         assert after == {"a1": True, "b1": False}
 
+    async def test_answered_call_gets_no_tool_call_span(self) -> None:
+        spans: list[str] = []
+
+        def record_span(event: Event[ToolCallSpan]) -> SpanExitHandler:
+            spans.append(event.data.tool_use.id)
+
+            def on_exit(error: BaseException | None = None) -> None:
+                pass
+
+            return on_exit
+
+        hooks = _answer_by_name({"a": ToolResult(content="no", is_error=True)})
+        hooks.on_span(ToolCallSpan, record_span)
+        registry = ToolRegistry([_recording_tool("a", []), _recording_tool("b", [])])
+
+        await _run_turn(_calls_a_and_b(), registry, hooks=hooks)
+
+        assert spans == ["b1"]
+
     async def test_answered_error_without_kind_gets_execution(self) -> None:
         kinds: dict[str, ToolErrorKind | None] = {}
         hooks = _answer_by_name({"a": ToolResult(content="no", is_error=True)})
@@ -2601,6 +2620,15 @@ class TestTurnAgentBeforeToolCalls:
         seen = _result_blocks(provider.requests[1].messages[-1])
         assert [(b.tool_use_id, b.text) for b in seen] == [("a1", "no a"), ("b1", "no b")]
 
+    async def test_answer_to_a_tool_not_in_the_registry_reaches_the_model(self) -> None:
+        hooks = _answer_by_name({"a": ToolResult(content="handled")})
+        provider = _calls_a_and_b()
+
+        await _run_turn(provider, ToolRegistry([_recording_tool("b", [])]), hooks=hooks)
+
+        a_seen, _ = _result_blocks(provider.requests[1].messages[-1])
+        assert (a_seen.tool_use_id, a_seen.text, a_seen.is_error) == ("a1", "handled", False)
+
     async def test_answered_call_cannot_finish_the_turn(self) -> None:
         hooks = _answer_by_name({"finish": ToolResult(content="not now", is_error=True)})
         provider = ScriptedProvider(
@@ -2666,6 +2694,17 @@ class TestTurnAgentBeforeToolCalls:
         assert (a_result.tool_use_id, a_result.text, a_result.is_error) == ("a1", "no", True)
         assert (b_result.tool_use_id, b_result.text, b_result.is_error) == ("b1", "OK", False)
 
+    async def test_before_tool_call_changing_a_calls_id_raises(self) -> None:
+        def change_id(event: Event[BeforeToolCallEvent]) -> None:
+            event.data.tool_use = dataclasses.replace(event.data.tool_use, id="other")
+
+        hooks = HooksImpl()
+        hooks.on(BeforeToolCallEvent, change_id)
+        registry = ToolRegistry([_recording_tool("a", []), _recording_tool("b", [])])
+
+        with pytest.raises(ValueError, match="changed the id of tool call 'a1' to 'other'"):
+            await _run_turn(_calls_a_and_b(), registry, hooks=hooks)
+
     async def test_answered_error_counts_toward_max_consecutive_errors(self) -> None:
         hooks = _answer_by_name({"a": ToolResult(content="no", is_error=True)})
         provider = ScriptedProvider(
@@ -2687,6 +2726,54 @@ class TestTurnAgentBeforeToolCalls:
         assert second.text == "Tool a has failed 2 times consecutively. Please try a different approach."
         assert second.is_error is True
 
+    async def test_answered_non_error_resets_max_consecutive_errors(self) -> None:
+        @tool("a")
+        def failing_tool() -> ToolResult:
+            """Always fail."""
+            return ToolResult(content="a failed", is_error=True)
+
+        def answer_a2(event: Event[BeforeToolCallsEvent]) -> None:
+            if event.data.tool_uses[0].id == "a2":
+                event.data.results["a2"] = ToolResult(content="cached")
+
+        hooks = HooksImpl()
+        hooks.on(BeforeToolCallsEvent, answer_a2)
+        provider = ScriptedProvider(
+            *(
+                LLMResponse(
+                    messages=[AssistantMessage(blocks=[ToolUseBlock(id=call_id, name="a", input={})])],
+                    stop_reason=StopReason.TOOL_USE,
+                )
+                for call_id in ("a1", "a2", "a3")
+            ),
+            LLMResponse(messages=[AssistantMessage(blocks=[TextBlock(text="Done")])], stop_reason=StopReason.END_TURN),
+        )
+
+        result = await _run_turn(provider, ToolRegistry([failing_tool]), hooks=hooks, max_consecutive_errors=2)
+
+        [third] = _result_blocks(result.messages[6])
+        assert (third.tool_use_id, third.text, third.is_error) == ("a3", "a failed", True)
+
+    async def test_round_answering_nothing_after_one_that_answered_holds_only_its_own_call(self) -> None:
+        hooks = _answer_by_name({"a": ToolResult(content="no", is_error=True)})
+        provider = ScriptedProvider(
+            LLMResponse(
+                messages=[AssistantMessage(blocks=[ToolUseBlock(id="a1", name="a", input={})])],
+                stop_reason=StopReason.TOOL_USE,
+            ),
+            LLMResponse(
+                messages=[AssistantMessage(blocks=[ToolUseBlock(id="b1", name="b", input={})])],
+                stop_reason=StopReason.TOOL_USE,
+            ),
+            LLMResponse(messages=[AssistantMessage(blocks=[TextBlock(text="Done")])], stop_reason=StopReason.END_TURN),
+        )
+        registry = ToolRegistry([_recording_tool("a", []), _recording_tool("b", [])])
+
+        result = await _run_turn(provider, registry, hooks=hooks)
+
+        assert result.status == TurnStatus.COMPLETED
+        assert [(b.tool_use_id, b.text) for b in _result_blocks(result.messages[4])] == [("b1", "b ran")]
+
     async def test_single_call_message_emits_the_event(self) -> None:
         executed: list[str] = []
         seen: list[list[str]] = []
@@ -2709,7 +2796,7 @@ class TestTurnAgentBeforeToolCalls:
     async def test_before_tool_calls_sees_the_cut_off_call(self) -> None:
         seen: list[list[str]] = []
         hooks = _answer_by_name({}, seen)
-        provider = _cut_off_after_a(ScriptedProvider)
+        provider = _cut_off_after_a()
 
         await _run_turn(provider, ToolRegistry([_recording_tool("a", [])]), hooks=hooks)
 
@@ -2736,9 +2823,7 @@ class TestTurnAgentBeforeToolCalls:
         hooks = _answer_by_name({"b": ToolResult(content="mine")})
         hooks.on(AfterToolCallEvent, lambda event: after.append(event.data.tool_use.id))
 
-        result = await _run_turn(
-            _cut_off_after_a(ScriptedProvider), ToolRegistry([_recording_tool("a", executed)]), hooks=hooks
-        )
+        result = await _run_turn(_cut_off_after_a(), ToolRegistry([_recording_tool("a", executed)]), hooks=hooks)
 
         a_result, b_result = _result_blocks(result.messages[2])
         assert (a_result.tool_use_id, a_result.text) == ("a1", "a ran")
@@ -2747,6 +2832,19 @@ class TestTurnAgentBeforeToolCalls:
         assert "output token limit" in b_result.text
         assert after == ["a1"]
 
+    async def test_answer_to_a_complete_call_beside_a_cut_off_one(self) -> None:
+        executed: list[str] = []
+        hooks = _answer_by_name({"a": ToolResult(content="mine")})
+        registry = ToolRegistry([_recording_tool("a", executed), _recording_tool("b", executed)])
+
+        result = await _run_turn(_cut_off_after_a(), registry, hooks=hooks)
+
+        assert executed == []
+        a_result, b_result = _result_blocks(result.messages[2])
+        assert (a_result.tool_use_id, a_result.text, a_result.is_error) == ("a1", "mine", False)
+        assert (b_result.tool_use_id, b_result.is_error) == ("b1", True)
+        assert "output token limit" in b_result.text
+
     async def test_answered_call_survives_a_resume_before_results_are_collected(self) -> None:
         class CrashError(Exception):
             pass