flowra 0.0.92.dev108__tar.gz → 0.0.92.dev109__tar.gz

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

@@ -24,6 +24,15 @@ and this project adheres to [Semantic Versioning](https://semver.org).
 - **`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.
+
 ## [0.0.91] - 2026-10-20
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: flowra
-Version: 0.0.92.dev108
+Version: 0.0.92.dev109
 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.dev108 → flowra-0.0.92.dev109}/context7.json

@@ -48,7 +48,7 @@
     "McpConnection connects to remote MCP servers for tool discovery over Streamable HTTP. McpConnection.snapshot() returns a frozen ToolRegistry; the tool list is refreshed in the background (server ttlMs, 60s default) with add_on_tools_changed(callback) for changes, and tools with invalid x-mcp-header annotations are dropped. Speaks both MCP protocol eras and detects on connect: stateless 2026-07-28 (no handshake/session; x-mcp-header args mirrored into Mcp-Param-* headers) and handshake-based 2025-03-26 to 2025-11-25 (any other version fails connect()). McpConnection.session (McpSession) exposes stateless: bool, protocol_version and session_id. A tool call needing client input (MRTR) returns a tool error; subscriptions/listen and MRTR are not implemented. McpConnection.call_tool(name, args, headers=..., meta=...) adds per-call HTTP headers and params._meta (kept on the reconnect retry; Content-Type/Accept/Mcp-* headers and the protocol's io.modelcontextprotocol/* _meta keys raise ValueError)",
     "ToolCallInfo (flowra.tools) carries per-call headers and meta, empty by default — flowra sets none itself. Fill them in a BeforeToolCallEvent handler (event.data.headers / event.data.meta); they are stored in ToolCallSpec, so a resumed call gets the same values (generate idempotency keys there, not in the tool). ToolCallAgent passes ToolCallInfo in services: MCP snapshot tools send them with tools/call, a @tool reads them by declaring an info: ToolCallInfo parameter",
     "ToolRegistry is immutable, accepts @tool-decorated functions or ExecutableTools: ToolRegistry([my_func, other_func])",
-    "TOOL ERRORS: the executor built by @tool catches the decorated function's exceptions (and argument validation/service binding errors) and returns ToolResult(content='Error: {e}', is_error=True, error_kind=EXECUTION, or SCHEMA_VALIDATION for invalid arguments) — so registry.execute and a direct get_tool(f).executor(...) call both return the error result. A ToolResult the function returns is the answer as it is (not serialized); ToolResult.content is str | list[TextBlock | MediaBlock], and ToolCallAgent puts its blocks into the ToolResultBlock as they are (metadata and transient kept; a str is one TextBlock; ToolResult.blocks / ToolResult.text). A '-> ToolResult' annotation gives no output_schema; '-> Answer | ToolResult' gives Answer's. raise ToolError(content, error_kind=EXECUTION) (str or blocks) to answer with an error the tool chose: the executor returns exc.result (is_error=True, content as written, no 'Error: ' prefix, no log); only the @tool executor answers it — an agent behind an agent tool returns ToolResult(is_error=True) instead, and a ToolError raised in an agent fails the run like any exception. InterruptedError is the exception: the executor raises it, and ToolCallAgent answers 'Tool execution interrupted'. ToolRegistry.execute does not catch: an exception from code around an executor (a wrapper via dataclasses.replace(tool, executor=...), a custom ExecutableTool executor) propagates through ToolCallAgent to AgentRuntime.run/resume as itself (session stays resumable); return ToolResult(is_error=True) from such code to answer the model. ToolCallAgent answers InterruptedError raised around a tool with 'Tool execution interrupted'. McpConnection never raises for a call, except ValueError for invalid per-call headers/_meta (set by a BeforeToolCallEvent handler, it fails the run and a resume repeats it, since the values are stored with the call): unknown/removed tools → UNKNOWN_TOOL; a result's MCP content comes back as blocks (text and resource text → TextBlock; image, audio and resource blob → MediaBlock; resource_link and unknown types → TextBlock with the block as JSON), with what the flowra block does not carry in metadata['mcp'] (text/image/audio: every field but type, content (text/data) and, for media, mimeType (annotations, _meta, any other), no metadata when none, so plain text is a plain TextBlock; resource: the whole block but the resource's text/blob, uri and mimeType under metadata['mcp']['resource']; resource_link and unknown types: type, annotations, _meta); a malformed block makes the response invalid; isError → the server's blocks, JSON-RPC errors → the server's text; transport failures → 'temporarily unavailable' (retried once if the reconnect succeeds); invalid responses → 'returned an invalid response', not retried. When one of several parallel steps (e.g. parallel tool calls) raises, the engine cancels and awaits its siblings, then re-raises the original exception (no ExceptionGroup). Agent tool executors (make_agent_tool/@agent_tool) answer invalid arguments with SCHEMA_VALIDATION/EXECUTION results like @tool; with valid arguments, one called outside ToolCallAgent raises RuntimeError",
+    "TOOL ERRORS: the executor built by @tool catches the decorated function's exceptions (and argument validation/service binding errors) and returns ToolResult(content='Error: {e}', is_error=True, error_kind=EXECUTION, or SCHEMA_VALIDATION for invalid arguments) — so registry.execute and a direct get_tool(f).executor(...) call both return the error result. A ToolResult the function returns is the answer as it is (not serialized), except that what hooks and spans see (ToolCallResult, AfterToolCallEvent, ToolCallSpan) carries an error_kind exactly when it is an error — EXECUTION for an error given without one, None for a non-error; ToolResult.content is str | list[TextBlock | MediaBlock], and ToolCallAgent puts its blocks into the ToolResultBlock as they are (metadata and transient kept; a str is one TextBlock; ToolResult.blocks / ToolResult.text). A '-> ToolResult' annotation gives no output_schema; '-> Answer | ToolResult' gives Answer's. raise ToolError(content, error_kind=EXECUTION) (str or blocks) to answer with an error the tool chose: the executor returns exc.result (is_error=True, content as written, no 'Error: ' prefix, no log); only the @tool executor answers it — an agent behind an agent tool returns ToolResult(is_error=True) instead, and a ToolError raised in an agent fails the run like any exception. InterruptedError is the exception: the executor raises it, and ToolCallAgent answers 'Tool execution interrupted'. ToolRegistry.execute does not catch: an exception from code around an executor (a wrapper via dataclasses.replace(tool, executor=...), a custom ExecutableTool executor) propagates through ToolCallAgent to AgentRuntime.run/resume as itself (session stays resumable); return ToolResult(is_error=True) from such code to answer the model. ToolCallAgent answers InterruptedError raised around a tool with 'Tool execution interrupted'. McpConnection never raises for a call, except ValueError for invalid per-call headers/_meta (set by a BeforeToolCallEvent handler, it fails the run and a resume repeats it, since the values are stored with the call): unknown/removed tools → UNKNOWN_TOOL; a result's MCP content comes back as blocks (text and resource text → TextBlock; image, audio and resource blob → MediaBlock; resource_link and unknown types → TextBlock with the block as JSON), with what the flowra block does not carry in metadata['mcp'] (text/image/audio: every field but type, content (text/data) and, for media, mimeType (annotations, _meta, any other), no metadata when none, so plain text is a plain TextBlock; resource: the whole block but the resource's text/blob, uri and mimeType under metadata['mcp']['resource']; resource_link and unknown types: type, annotations, _meta); a malformed block makes the response invalid; isError → the server's blocks, JSON-RPC errors → the server's text; transport failures → 'temporarily unavailable' (retried once if the reconnect succeeds); invalid responses → 'returned an invalid response', not retried. When one of several parallel steps (e.g. parallel tool calls) raises, the engine cancels and awaits its siblings, then re-raises the original exception (no ExceptionGroup). Agent tool executors (make_agent_tool/@agent_tool) answer invalid arguments with SCHEMA_VALIDATION/EXECUTION results like @tool; with valid arguments, one called outside ToolCallAgent raises RuntimeError",
     "ToolRegistry.builder() returns ToolRegistryBuilder with .add(source, prefix=..., filter=..., on_duplicate='error'|'skip') and .build() for composing registries from multiple sources. filter is a single Callable[[ExecutableTool], bool]; use the `tool_filter` module for common cases: tool_filter.INCLUDE_SUFFIX(*names) whitelists, tool_filter.EXCLUDE_SUFFIX(*names) blacklists (both match exact name or __name suffix), tool_filter.ALL_OF(*filters)/tool_filter.ANY_OF(*filters) compose. Import: from flowra.tools import tool_filter",
     "Duplicate tool names are detected eagerly at the ToolRegistryBuilder.add() call where the collision is introduced. Default on_duplicate='error' raises ValueError; on_duplicate='skip' silently drops repeats (first occurrence wins). ToolRegistry(...) constructor also raises on duplicate names. OnDuplicate type alias is exported from flowra.tools",
     "ToolRegistry is a ConfigValue[ToolRegistry | None] in ChatConfig and TurnConfig (field name: tools)",

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

@@ -82,7 +82,7 @@ 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`. A key that is not the id of a call in the message
+`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`.
 
 ```python

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

@@ -684,8 +684,9 @@ async def respond(params: RespondParams) -> Sent:
 `ToolError(content, error_kind=ToolErrorKind.EXECUTION)` takes a string or a
 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`, the model sees the same, but hooks
-and spans get `None`).
+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.
 
 `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.dev108 → flowra-0.0.92.dev109}/flowra/lib/turn/agent.py

@@ -36,7 +36,7 @@ from ...llm import (
     Usage,
     UserMessage,
 )
-from ...tools import ToolErrorKind, ToolRegistry, ToolResult
+from ...tools import ToolRegistry, ToolResult
 from ..config_value import resolve_config_value
 from ..llm_caller import DEFAULT_LLM_CALLER, LLMCaller
 from ..observability import UsageEvent
@@ -67,6 +67,7 @@ logger = logging.getLogger(__name__)
 class TurnAgent(Agent[TurnSpec, TurnResult]):
     __slots__ = (
         "__answered_tool_results",
+        "__call_order",
         "__caller",
         "__config",
         "__consecutive_errors",
@@ -100,6 +101,7 @@ class TurnAgent(Agent[TurnSpec, TurnResult]):
         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.__interrupt = interrupt
         self.__context = TurnAgentContext()
         self.__config = config
@@ -296,7 +298,7 @@ class TurnAgent(Agent[TurnSpec, TurnResult]):
 
         answered = self.__answered_tool_results.get([])
         answered_ids = {tc_result.tool_use.id for tc_result in answered}
-        collected = self.__in_message_order([*answered, *results]) if answered else results
+        collected = self.__in_call_order([*answered, *results]) if answered else results
         for tc_result in collected:
             after_event = await self.__hooks.emit(
                 AfterToolCallEvent(
@@ -343,6 +345,7 @@ class TurnAgent(Agent[TurnSpec, TurnResult]):
             self.__incomplete_tool_result.set(None)
         if answered:
             self.__answered_tool_results.set([])
+            self.__call_order.set([])
 
         self.__consecutive_errors.set(consecutive_errors)
         user_message = UserMessage(blocks=list(result_blocks))
@@ -401,6 +404,7 @@ class TurnAgent(Agent[TurnSpec, TurnResult]):
         ]
         if answered:
             self.__answered_tool_results.set(answered)
+            self.__call_order.set([tool_use.id for tool_use in tool_uses])
 
         amendments: dict[str, ToolUseBlock] = {}
         final_calls: list[BeforeToolCallEvent] = []
@@ -443,21 +447,18 @@ class TurnAgent(Agent[TurnSpec, TurnResult]):
         ]
         return Spawn(children=children, then=self.collect_results)
 
-    def __in_message_order(self, results: list[ToolCallResult]) -> list[ToolCallResult]:
-        # Every collected call, answered or run, is one of the last assistant message in the turn
-        message = next(m for m in reversed(self.__turn_messages.get_all()) if isinstance(m, AssistantMessage))
-        position = {block.id: i for i, block in enumerate(message.blocks) if isinstance(block, ToolUseBlock)}
+    def __in_call_order(self, 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:
-        # Consumers tell an error by its kind: an error answered without one gets the default ToolError uses,
-        # and an answer that is not an error carries none
-        error_kind = (result.error_kind or ToolErrorKind.EXECUTION) if result.is_error else None
         return ToolCallResult(
             tool_use=tool_use,
             result=ToolResultBlock(tool_use_id=tool_use.id, content=result.blocks, is_error=result.is_error),
-            error_kind=error_kind,
+            error_kind=result.error_kind,
         )
 
     @staticmethod

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

@@ -43,10 +43,21 @@ class ToolCallSpec:
 
 @dataclasses.dataclass(frozen=True, slots=True, kw_only=True)
 class ToolCallResult:
+    """A call's answer as the turn reads it.
+
+    ``error_kind`` is set exactly when ``result.is_error``: an error the tool gave no kind is ``EXECUTION``,
+    the kind ``ToolError`` defaults to, and an answer that is not an error carries none. Hooks and spans tell
+    an error by its kind, so the two never disagree.
+    """
+
     tool_use: ToolUseBlock
     result: ToolResultBlock
     error_kind: ToolErrorKind | None = None
 
+    def __post_init__(self) -> None:
+        error_kind = (self.error_kind or ToolErrorKind.EXECUTION) if self.result.is_error else None
+        object.__setattr__(self, "error_kind", error_kind)
+
 
 class ToolCallAgent(Agent[ToolCallSpec, ToolCallResult]):
     """Executes a single tool call and returns the result.

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

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

{flowra-0.0.92.dev108 → flowra-0.0.92.dev109}/tests/lib/test_tool_call_agent.py

@@ -7,8 +7,8 @@ from flowra.agent import AgentRuntime, InterruptedError
 from flowra.lib import LLMConfig
 from flowra.lib.turn import TurnConfig
 from flowra.lib.turn.tool_call import ToolCallAgent, ToolCallResult, ToolCallSpec
-from flowra.llm import LLMProvider, LLMRequest, LLMResponse, ToolUseBlock
-from flowra.tools import ToolRegistry, tool
+from flowra.llm import LLMProvider, LLMRequest, LLMResponse, ToolResultBlock, ToolUseBlock
+from flowra.tools import ToolErrorKind, ToolRegistry, ToolResult, tool
 
 
 class _UnusedProvider(LLMProvider):
@@ -37,6 +37,18 @@ def stopped_tool() -> str:
     raise InterruptedError
 
 
+@tool("refusing")
+def refusing_tool() -> ToolResult:
+    """Answer with an error of its own, naming no kind."""
+    return ToolResult(content="no", is_error=True)
+
+
+@tool("kind_without_error")
+def kind_without_error_tool() -> ToolResult:
+    """Answer successfully while naming a kind."""
+    return ToolResult(content="fine", error_kind=ToolErrorKind.EXECUTION)
+
+
 class TestToolCallAgent:
     async def test_execute_tool_call(self) -> None:
         registry = ToolRegistry([add_tool])
@@ -217,6 +229,7 @@ class TestToolCallAgent:
         assert result.result.tool_use_id == "call_2"
         assert result.result.text == "Tool execution interrupted"
         assert result.result.is_error is True
+        assert result.error_kind == ToolErrorKind.EXECUTION
 
     async def test_a_tool_that_raises_interrupted_is_interrupted_not_failed(
         self, caplog: pytest.LogCaptureFixture
@@ -242,3 +255,57 @@ class TestToolCallAgent:
         assert result.result.text == "Tool execution interrupted"
         assert result.result.is_error is True
         assert caplog.records == []
+
+    @pytest.mark.parametrize(
+        ("tool_name", "error_kind"),
+        [("refusing", ToolErrorKind.EXECUTION), ("kind_without_error", None)],
+    )
+    async def test_a_tool_answer_carries_a_kind_exactly_when_it_is_an_error(
+        self, tool_name: str, error_kind: ToolErrorKind | None
+    ) -> None:
+        runtime = AgentRuntime(
+            agents={"tool_call": ToolCallAgent},
+            services={
+                TurnConfig: TurnConfig(
+                    tools=ToolRegistry([refusing_tool, kind_without_error_tool]),
+                    llm_config=LLMConfig(provider=_UNUSED_PROVIDER, model="test"),
+                    system=[],
+                    history=[],
+                )
+            },
+        )
+
+        result = await runtime.run(
+            agent=ToolCallAgent, spec=ToolCallSpec(tool_use=ToolUseBlock(id="call_4", name=tool_name, input={}))
+        )
+
+        assert isinstance(result, ToolCallResult)
+        assert result.error_kind == error_kind
+
+
+class TestToolCallResult:
+    def test_an_error_without_a_kind_gets_execution(self) -> None:
+        result = ToolCallResult(
+            tool_use=ToolUseBlock(id="c", name="t", input={}),
+            result=ToolResultBlock(tool_use_id="c", content=[], is_error=True),
+        )
+
+        assert result.error_kind == ToolErrorKind.EXECUTION
+
+    def test_an_error_keeps_the_kind_it_has(self) -> None:
+        result = ToolCallResult(
+            tool_use=ToolUseBlock(id="c", name="t", input={}),
+            result=ToolResultBlock(tool_use_id="c", content=[], is_error=True),
+            error_kind=ToolErrorKind.SCHEMA_VALIDATION,
+        )
+
+        assert result.error_kind == ToolErrorKind.SCHEMA_VALIDATION
+
+    def test_an_answer_that_is_not_an_error_carries_no_kind(self) -> None:
+        result = ToolCallResult(
+            tool_use=ToolUseBlock(id="c", name="t", input={}),
+            result=ToolResultBlock(tool_use_id="c", content=[]),
+            error_kind=ToolErrorKind.EXECUTION,
+        )
+
+        assert result.error_kind is None