flowra 0.0.91__tar.gz → 0.0.92.dev109__tar.gz

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

@@ -5,6 +5,34 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com),
 and this project adheres to [Semantic Versioning](https://semver.org).
 
+## [Unreleased]
+
+### 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.
+- **`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.91 → flowra-0.0.92.dev109}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: flowra
-Version: 0.0.91
+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.91 → 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)",
@@ -129,12 +129,12 @@
 
     "PRE-BUILT AGENTS — TurnAgent: single-turn LLM tool loop with hooks and caching",
     "TurnAgent sends messages to LLM, executes tool calls, feeds results back, repeats until done",
-    "TurnAgent stop handling: a response without tool calls ends the turn with TurnStatus.COMPLETED and TurnResult.stop_reason (END_TURN, MAX_TOKENS, STOP_SEQUENCE, OTHER, SCHEMA_VALIDATION_FAILED, REFUSAL). On REFUSAL TurnResult.refusal is set, result_message is None and messages keep the turn so far (tool calls included) with no empty assistant message. If a response stopped with anything but END_TURN/TOOL_USE ends on a tool call, that call was cut off: it is not run and gets an error ToolResultBlock (no Before/AfterToolCallEvent, no ToolCallSpan, not counted in max_consecutive_errors), the complete calls before it run, and the loop continues so the model can retry (bounded by max_llm_calls). History never holds an unanswered tool_use",
+    "TurnAgent stop handling: a response without tool calls ends the turn with TurnStatus.COMPLETED and TurnResult.stop_reason (END_TURN, MAX_TOKENS, STOP_SEQUENCE, OTHER, SCHEMA_VALIDATION_FAILED, REFUSAL). On REFUSAL TurnResult.refusal is set, result_message is None and messages keep the turn so far (tool calls included) with no empty assistant message. If a response stopped with anything but END_TURN/TOOL_USE ends on a tool call, that call was cut off: it is not run and gets an error ToolResultBlock (it appears in BeforeToolCallsEvent.tool_uses; no BeforeToolCallEvent/AfterToolCallEvent, no ToolCallSpan, not counted in max_consecutive_errors), the complete calls before it run, and the loop continues so the model can retry (bounded by max_llm_calls). History never holds an unanswered tool_use",
     "TurnConfig configures TurnAgent: TurnConfig(llm_config=LLMConfig(model='...'), system=[...], history=[...])",
     "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, BeforeToolCallEvent (has tool_definition: ToolDefinition | None; mutable tool_use, headers, meta — see ToolCallInfo), AfterToolCallEvent (has error_kind; 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 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)",
     "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.91 → flowra-0.0.92.dev109}/docs/agents.md

@@ -802,11 +802,14 @@ Lifecycle events (from `flowra.lib.turn`):
 | `ThinkingEvent`          | Non-empty thinking block in LLM response | —                                             |
 | `ServerToolCallEvent`    | Server-side tool call (e.g. tool search) | —                                             |
 | `ServerToolResultEvent`  | Server-side tool result                  | —                                             |
+| `BeforeToolCallsEvent`   | Message with tool calls, before any runs | `results`                                     |
 | `BeforeToolCallEvent`    | Before tool execution                    | `tool_use`, `headers`, `meta`                 |
-| `AfterToolCallEvent`     | After tool execution                     | `result`, `additional_blocks`, `additional_messages` |
+| `AfterToolCallEvent`     | After tool execution or answer           | `result`, `additional_blocks`, `additional_messages` |
 | `ResultMessageEvent`     | LLM finished (END_TURN)                  | `continue_messages`                           |
 
-Tool calls cut off by the output limit fire no tool events; see
+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.
 
 Streaming events (from `flowra.lib.observability`):

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

@@ -35,8 +35,9 @@ Events from `TurnAgent` (and `ChatAgent`, which uses it internally):
 | `ThinkingEvent`          | Non-empty thinking block in LLM response | —                                             |
 | `ServerToolCallEvent`    | Server-side tool call (e.g. tool search) | —                                             |
 | `ServerToolResultEvent`  | Server-side tool result                  | —                                             |
+| `BeforeToolCallsEvent`   | Message with tool calls, before any runs | `results`                                     |
 | `BeforeToolCallEvent`    | Before tool execution                    | `tool_use`, `headers`, `meta`                 |
-| `AfterToolCallEvent`     | After tool execution                     | `result`, `additional_blocks`, `additional_messages` |
+| `AfterToolCallEvent`     | After tool execution or answer           | `result`, `additional_blocks`, `additional_messages` |
 | `ResultMessageEvent`     | LLM finished (END_TURN)                  | `continue_messages`                           |
 
 `AfterToolCallEvent.additional_blocks` go at the end of that call's result, so a
@@ -71,7 +72,37 @@ 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.
+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
+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`.
+
+```python
+from flowra.agent import Event
+from flowra.lib.turn import BeforeToolCallsEvent
+from flowra.tools import ToolResult
+
+
+def reply_alone(event: Event[BeforeToolCallsEvent]) -> None:
+    if len(event.data.tool_uses) < 2:
+        return
+    for tool_use in event.data.tool_uses:
+        if tool_use.name == "send_reply":
+            event.data.results[tool_use.id] = ToolResult(
+                content="Call send_reply on its own, in a message with no other tool calls.", is_error=True
+            )
+
+
+runtime.hooks.on(BeforeToolCallsEvent, reply_alone)
+```
 
 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:

{flowra-0.0.91 → 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.91 → flowra-0.0.92.dev109}/flowra/lib/turn/__init__.py

@@ -4,6 +4,7 @@ from .context import TurnAgentContext
 from .hook_events import (
     AfterToolCallEvent,
     BeforeToolCallEvent,
+    BeforeToolCallsEvent,
     MessageAcceptedEvent,
     ResultMessageEvent,
     ServerToolCallEvent,
@@ -20,6 +21,7 @@ from .tool_call import ToolCallAgentContext, agent_tool, get_agent_tool, make_ag
 __all__ = [
     "AfterToolCallEvent",
     "BeforeToolCallEvent",
+    "BeforeToolCallsEvent",
     "MessageAcceptedEvent",
     "Prompt",
     "PromptRender",

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

@@ -36,7 +36,7 @@ from ...llm import (
     Usage,
     UserMessage,
 )
-from ...tools import ToolRegistry
+from ...tools import ToolRegistry, ToolResult
 from ..config_value import resolve_config_value
 from ..llm_caller import DEFAULT_LLM_CALLER, LLMCaller
 from ..observability import UsageEvent
@@ -45,6 +45,7 @@ from .context import TurnAgentContext
 from .hook_events import (
     AfterToolCallEvent,
     BeforeToolCallEvent,
+    BeforeToolCallsEvent,
     MessageAcceptedEvent,
     ResultMessageEvent,
     ServerToolCallEvent,
@@ -65,6 +66,8 @@ logger = logging.getLogger(__name__)
 
 class TurnAgent(Agent[TurnSpec, TurnResult]):
     __slots__ = (
+        "__answered_tool_results",
+        "__call_order",
         "__caller",
         "__config",
         "__consecutive_errors",
@@ -97,6 +100,8 @@ 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.__interrupt = interrupt
         self.__context = TurnAgentContext()
         self.__config = config
@@ -246,7 +251,7 @@ class TurnAgent(Agent[TurnSpec, TurnResult]):
                 )
 
             case StopReason.TOOL_USE:
-                return await self.__call_tools(response, tool_uses, registry, allowed_tools, denied_tools)
+                return await self.__call_tools(response, tool_uses, None, registry, allowed_tools, denied_tools)
 
             case StopReason.REFUSAL:
                 # The provider declined: no output to keep, and an empty assistant message would make
@@ -268,7 +273,7 @@ class TurnAgent(Agent[TurnSpec, TurnResult]):
                 # A response cut off mid tool call ends on that call, and only that call is incomplete
                 cut_off = response.message.blocks[-1] is tool_uses[-1]
                 if not cut_off:
-                    return await self.__call_tools(response, tool_uses, registry, allowed_tools, denied_tools)
+                    return await self.__call_tools(response, tool_uses, None, registry, allowed_tools, denied_tools)
 
                 # Answer the cut-off call with an error so history stays valid and the model can retry
                 self.__incomplete_tool_result.set(
@@ -278,7 +283,9 @@ class TurnAgent(Agent[TurnSpec, TurnResult]):
                         is_error=True,
                     )
                 )
-                return await self.__call_tools(response, tool_uses[:-1], registry, allowed_tools, denied_tools)
+                return await self.__call_tools(
+                    response, tool_uses[:-1], tool_uses[-1], registry, allowed_tools, denied_tools
+                )
 
     @step("collect_results")
     async def collect_results(
@@ -289,13 +296,17 @@ class TurnAgent(Agent[TurnSpec, TurnResult]):
         consecutive_errors = dict(self.__consecutive_errors.get({}))
         max_consecutive = await resolve_config_value(self.__config.max_consecutive_errors)
 
-        for tc_result in results:
+        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
+        for tc_result in collected:
             after_event = await self.__hooks.emit(
                 AfterToolCallEvent(
                     tool_use=tc_result.tool_use,
                     result=tc_result.result,
                     error_kind=tc_result.error_kind,
                     context=self.__context,
+                    prefilled=tc_result.tool_use.id in answered_ids,
                 )
             )
 
@@ -332,6 +343,9 @@ 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([])
 
         self.__consecutive_errors.set(consecutive_errors)
         user_message = UserMessage(blocks=list(result_blocks))
@@ -370,13 +384,33 @@ class TurnAgent(Agent[TurnSpec, TurnResult]):
         self,
         response: LLMResponse,
         tool_uses: list[ToolUseBlock],
+        cut_off: ToolUseBlock | None,
         registry: ToolRegistry | None,
         allowed_tools: set[str] | None,
         denied_tools: set[str] | None,
     ) -> Spawn:
+        message_calls = [*tool_uses, cut_off] if cut_off is not None else list(tool_uses)
+        # Taken before the emit, so a handler changing the event's list cannot widen what may be answered
+        call_ids = {tool_use.id for tool_use in message_calls}
+        calls_event = await self.__hooks.emit(BeforeToolCallsEvent(tool_uses=message_calls, context=self.__context))
+        for tool_use_id in calls_event.results:
+            if tool_use_id not in call_ids:
+                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])
+            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])
+
         amendments: dict[str, ToolUseBlock] = {}
         final_calls: list[BeforeToolCallEvent] = []
         for tool_use in tool_uses:
+            if tool_use.id in calls_event.results:
+                continue
             before_event = await self.__hooks.emit(
                 BeforeToolCallEvent(
                     tool_use=tool_use,
@@ -413,6 +447,20 @@ class TurnAgent(Agent[TurnSpec, TurnResult]):
         ]
         return Spawn(children=children, then=self.collect_results)
 
+    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:
+        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,
+        )
+
     @staticmethod
     def __incomplete_tool_use_message(stop_reason: StopReason) -> str:
         if stop_reason == StopReason.MAX_TOKENS:

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

@@ -14,12 +14,13 @@ from ...llm import (
     ToolUseBlock,
     UserMessage,
 )
-from ...tools import ToolDefinition, ToolErrorKind
+from ...tools import ToolDefinition, ToolErrorKind, ToolResult
 from .context import TurnAgentContext
 
 __all__ = [
     "AfterToolCallEvent",
     "BeforeToolCallEvent",
+    "BeforeToolCallsEvent",
     "MessageAcceptedEvent",
     "ResultMessageEvent",
     "ServerToolCallEvent",
@@ -96,6 +97,21 @@ class ResultMessageEvent:
     continue_messages: list[UserMessage] = dataclasses.field(default_factory=list)
 
 
+@dataclasses.dataclass(slots=True, kw_only=True)
+class BeforeToolCallsEvent:
+    """Emitted once per model message with tool calls, before any of them runs.
+
+    ``tool_uses`` is every call of the message in its order, a call the response cut off included.
+    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.
+    """
+
+    tool_uses: list[ToolUseBlock]
+    context: TurnAgentContext
+    results: dict[str, ToolResult] = dataclasses.field(default_factory=dict)
+
+
 @dataclasses.dataclass(slots=True, kw_only=True)
 class BeforeToolCallEvent:
     """Emitted before each tool execution.
@@ -112,6 +128,9 @@ class BeforeToolCallEvent:
 
     Neither this nor ``AfterToolCallEvent`` fires for a call the response cut
     off (e.g. at ``MAX_TOKENS``): that call is not run.
+
+    Not emitted for a call answered in ``BeforeToolCallsEvent``; that call still gets
+    ``AfterToolCallEvent``, with ``prefilled=True``.
     """
 
     tool_use: ToolUseBlock
@@ -123,7 +142,7 @@ class BeforeToolCallEvent:
 
 @dataclasses.dataclass(slots=True, kw_only=True)
 class AfterToolCallEvent:
-    """Emitted after each tool execution.
+    """Emitted after each tool execution, and for a call answered in ``BeforeToolCallsEvent``.
 
     Replace ``result`` to modify tool output (e.g. sanitize errors, redact PII).
     Append to ``additional_blocks`` to attach blocks (e.g. a hint as a ``TextBlock``)
@@ -136,12 +155,15 @@ class AfterToolCallEvent:
     this result.
     Append to ``additional_messages`` to inject standalone messages after the
     message with the tool results.
+
+    ``prefilled`` is true for a call answered in ``BeforeToolCallsEvent``: the tool did not run.
     """
 
     tool_use: ToolUseBlock
     result: ToolResultBlock
     error_kind: ToolErrorKind | None
     context: TurnAgentContext
+    prefilled: bool = False
     additional_blocks: list[ToolResultContentBlock] = dataclasses.field(default_factory=list)
     additional_messages: list[UserMessage] = dataclasses.field(default_factory=list)
 

{flowra-0.0.91 → 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.91 → 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.91"
+__version__ = "0.0.92.dev109"

{flowra-0.0.91 → 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