calfkit 0.3.2__tar.gz → 0.3.3__tar.gz

calfkit-0.3.3/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.3.3"
+}

{calfkit-0.3.2 → calfkit-0.3.3}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.3.3](https://github.com/calf-ai/calfkit-sdk/compare/v0.3.2...v0.3.3) (2026-05-22)
+
+
+### Bug Fixes
+
+* (agent,tool) surface tool exceptions to the agent instead of hanging ([#146](https://github.com/calf-ai/calfkit-sdk/issues/146)) ([05162cc](https://github.com/calf-ai/calfkit-sdk/commit/05162cc2512285e7dfcb64a30c7c8bca2f9fe50d))
+
 ## [0.3.2](https://github.com/calf-ai/calfkit-sdk/compare/v0.3.1...v0.3.2) (2026-05-21)
 
 

{calfkit-0.3.2 → calfkit-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: calfkit
-Version: 0.3.2
+Version: 0.3.3
 Summary: Build AI workflows and agents as fully-distributed and event-driven microservices.
 Project-URL: Homepage, https://github.com/calf-ai/calf-sdk
 Project-URL: Repository, https://github.com/calf-ai/calf-sdk

calfkit-0.3.3/calfkit/exceptions.py

@@ -0,0 +1,60 @@
+from typing import Any
+
+
+class DeserializationError(Exception):
+    """Raised when client-side output deserialization fails."""
+
+
+class ToolExecutionError(Exception):
+    """The original traceback is not preserved across the Kafka boundary; it is
+    logged at the worker that ran the tool. ``exc_type`` and ``exc_message`` are
+    the only forensic data available at the agent.
+    """
+
+    def __init__(self, *, tool_name: str, tool_call_id: str, exc_type: str, exc_message: str):
+        self.tool_name = tool_name
+        self.tool_call_id = tool_call_id
+        self.exc_type = exc_type
+        self.exc_message = exc_message
+        super().__init__(f"Tool {tool_name!r} (call_id={tool_call_id}) raised {exc_type}: {exc_message}")
+
+    def __reduce__(self) -> tuple[Any, ...]:
+        # Bypass keyword-only ``__init__`` during reconstruction by routing
+        # through a module-level helper that uses ``__new__``. A naive
+        # ``(self.__class__, (), state)`` reduction would call ``__init__()``
+        # with no args and fail because the keyword arguments are required.
+        return (
+            _reconstruct_tool_execution_error,
+            (),
+            {
+                "tool_name": self.tool_name,
+                "tool_call_id": self.tool_call_id,
+                "exc_type": self.exc_type,
+                "exc_message": self.exc_message,
+            },
+        )
+
+    def __setstate__(self, state: dict[str, Any] | None) -> None:
+        # ``__reduce__`` above always provides a dict, but the supertype
+        # signature allows ``None`` (Liskov); treat ``None`` as a no-op so
+        # subclasses constructed without state don't crash.
+        if state is None:
+            return
+        self.tool_name = state["tool_name"]
+        self.tool_call_id = state["tool_call_id"]
+        self.exc_type = state["exc_type"]
+        self.exc_message = state["exc_message"]
+        Exception.__init__(
+            self,
+            f"Tool {self.tool_name!r} (call_id={self.tool_call_id}) raised {self.exc_type}: {self.exc_message}",
+        )
+
+
+def _reconstruct_tool_execution_error() -> "ToolExecutionError":
+    """Create a bare ``ToolExecutionError`` for reconstruction via ``__setstate__``.
+
+    Bypasses the keyword-only ``__init__`` so state restoration can populate
+    fields directly. Must be module-level (not a lambda or local closure) so
+    it can be located by fully-qualified name during deserialization.
+    """
+    return ToolExecutionError.__new__(ToolExecutionError)

{calfkit-0.3.2 → calfkit-0.3.3}/calfkit/models/state.py

@@ -1,16 +1,18 @@
 import logging
 from dataclasses import dataclass, field
-from typing import Annotated, Any, Generic
+from typing import Annotated, Any, ClassVar, Generic, Literal
 
-from pydantic import BaseModel, ConfigDict, Discriminator, Field
+from pydantic import BaseModel, ConfigDict, Discriminator, Field, Tag, field_validator
 from typing_extensions import TypeVar
 
+from calfkit._vendor.pydantic_ai.exceptions import ModelRetry
 from calfkit._vendor.pydantic_ai.messages import (
     ModelMessage,
     ModelRequest,
+    RetryPromptPart,
     ToolCallPart,
+    ToolReturn,
 )
-from calfkit._vendor.pydantic_ai.tools import DeferredToolCallResult as ToolCallResult
 from calfkit.models.node_schema import BaseToolNodeSchema
 from calfkit.models.payload import ContentPart
 
@@ -58,28 +60,102 @@ class CoreMessageState(BaseAgentActivityState):
         self.uncommitted_message = None
 
 
+class FailedToolCall(BaseModel):
+    """Wire-format representation of a tool that raised on the worker side.
+
+    Stored in ``State.tool_results`` in the same slot a successful ``ToolReturn``
+    would occupy; consumers must handle both shapes. The ``marker_kind`` literal
+    is the discriminator tag consulted by ``_calf_tool_result_discriminator`` so
+    this value reconstructs as a typed instance (rather than a plain ``dict``)
+    when ``State`` round-trips through JSON across the Kafka boundary.
+
+    String fields are clamped to bounded lengths (see ``_MAX_LENGTHS``) rather
+    than rejected for wire-size safety: a tool that raises with an enormous
+    ``str(exc)`` must not itself cause construction to raise inside the worker's
+    ``except Exception`` block (which would prevent the failure reply from ever
+    being published and hang the agent).
+    """
+
+    model_config = ConfigDict(extra="ignore", frozen=True)
+    tool_name: str
+    tool_call_id: str = Field(min_length=1)
+    exc_type: str
+    exc_message: str
+    marker_kind: Literal["calfkit-tool-error"] = "calfkit-tool-error"
+
+    _MAX_LENGTHS: ClassVar[dict[str, int]] = {
+        "tool_name": 256,
+        "tool_call_id": 128,
+        "exc_type": 256,
+        "exc_message": 4096,
+    }
+
+    @field_validator("tool_name", "tool_call_id", "exc_type", "exc_message", mode="before")
+    @classmethod
+    def _clamp_string_fields(cls, v: Any, info: Any) -> Any:
+        if isinstance(v, str):
+            limit = cls._MAX_LENGTHS.get(info.field_name)
+            if limit is not None and len(v) > limit:
+                return v[:limit]
+        return v
+
+
+def _calf_tool_result_discriminator(x: Any) -> str | None:
+    """Tag extractor for the ``CalfToolResult`` discriminated union.
+
+    Mirrors ``calfkit._vendor.pydantic_ai.tools._deferred_tool_call_result_discriminator``
+    with an added ``marker_kind`` branch for ``FailedToolCall``. Without this, a
+    serialized marker arrives as a plain ``dict`` after a Kafka hop because the
+    upstream discriminator only recognizes ``kind`` / ``part_kind``.
+
+    Returns only string tags; non-string values are treated as missing so the
+    union falls through to the ``Any`` arm rather than silently misrouting.
+    Keep this in sync with the upstream helper if a new pydantic-ai tag is added.
+    """
+    for key in ("marker_kind", "kind", "part_kind"):
+        v = x.get(key) if isinstance(x, dict) else getattr(x, key, None)
+        if isinstance(v, str):
+            return v
+    return None
+
+
+CalfToolResult = Annotated[
+    Annotated[ToolReturn, Tag("tool-return")]
+    | Annotated[ModelRetry, Tag("model-retry")]
+    | Annotated[RetryPromptPart, Tag("retry-prompt")]
+    | Annotated[FailedToolCall, Tag("calfkit-tool-error")],
+    Discriminator(_calf_tool_result_discriminator),
+]
+"""Calfkit-side tagged union for values stored in ``State.tool_results``.
+
+Flattens pydantic-ai's ``DeferredToolCallResult`` (``ToolReturn`` / ``ModelRetry``
+/ ``RetryPromptPart``) and adds calfkit's ``FailedToolCall``. Flattening (rather
+than ``DeferredToolCallResult | FailedToolCall``) is required because Pydantic's
+discriminated-union machinery does not compose nested ``Discriminator``
+annotations reliably.
+"""
+
+
 class InFlightToolsState(BaseAgentActivityState):
     """State of all in-progress tool calls and results.
     Tool calls and results are in-progress when all tool calls have not been completed and committed to message history."""  # noqa: E501
 
     model_config = ConfigDict(extra="ignore")
 
-    # Map of tool call IDS to tool calls
     tool_calls: dict[str, ToolCallPart] = Field(default_factory=dict)
 
-    # Map of tool call IDs to tool results
-    tool_results: dict[str, ToolCallResult | Any] = Field(default_factory=dict)
+    tool_results: dict[str, CalfToolResult | Any] = Field(default_factory=dict)
 
     def add_tool_call(self, tool_call: ToolCallPart) -> None:
         self.tool_calls[tool_call.tool_call_id] = tool_call
 
-    def add_tool_result(self, tool_call_id: str, tool_result: ToolCallResult | Any) -> None:
+    def add_tool_result(self, tool_call_id: str, tool_result: CalfToolResult | Any) -> None:
         self.tool_results[tool_call_id] = tool_result
 
     def get_tool_call(self, tool_call_id: str) -> ToolCallPart | None:
         return self.tool_calls.get(tool_call_id)
 
-    def get_tool_result(self, tool_call_id: str) -> ToolCallResult | Any | None:
+    def get_tool_result(self, tool_call_id: str) -> CalfToolResult | Any | None:
         return self.tool_results.get(tool_call_id)
 
     def all_call_ids_complete(self, *call_ids: str) -> bool:
@@ -102,17 +178,6 @@ class State(CoreMessageState, InFlightToolsState):
     overrides: OverridesState | None = None
 
 
-# class State(BaseModel):
-#     """mutable data model to track state of an execution among one or more agents,
-#     sharing correlation id"""
-
-#     model_config = ConfigDict(extra="ignore")
-#     run_state: AgentActivityState = Field(default_factory=AgentActivityState)
-
-
-# ---------------------------------------------------------------------------
-# Experimental PartialState implementation
-# ---------------------------------------------------------------------------
 AgentStateSubsetT = TypeVar("AgentStateSubsetT", CoreMessageState, InFlightToolsState)
 
 PartialState = Annotated[CoreMessageState | InFlightToolsState | Any, Discriminator("kind")]
@@ -135,7 +200,7 @@ class PendingToolBatch:
     base_state: State
 
     # map of tool call IDs to tool call results
-    collected_results: dict[str, ToolCallResult | Any] = field(default_factory=dict)
+    collected_results: dict[str, CalfToolResult | Any] = field(default_factory=dict)
 
     @property
     def is_complete(self) -> bool:

{calfkit-0.3.2 → calfkit-0.3.3}/calfkit/nodes/agent.py

@@ -2,6 +2,8 @@ import logging
 from collections.abc import Callable
 from typing import Any, ClassVar, Generic, cast
 
+from pydantic import ValidationError
+
 from calfkit._protocol import NodeKind
 from calfkit._types import AgentOutputT
 from calfkit._vendor.pydantic_ai import Agent as InternalAgentLoop
@@ -11,19 +13,18 @@ from calfkit._vendor.pydantic_ai.output import OutputSpec
 from calfkit._vendor.pydantic_ai.settings import ModelSettings
 from calfkit._vendor.pydantic_ai.tools import DeferredToolResults
 from calfkit._vendor.pydantic_ai.toolsets.external import ExternalToolset
+from calfkit.exceptions import ToolExecutionError
 from calfkit.models import Call, DataPart, NodeResult, ReturnCall, State, TailCall, TextPart
 from calfkit.models.actions import Silent
 from calfkit.models.node_schema import BaseToolNodeSchema
 from calfkit.models.session_context import SessionRunContext
-from calfkit.models.state import PendingToolBatch
+from calfkit.models.state import FailedToolCall, PendingToolBatch
 from calfkit.nodes.base import BaseNodeDef, GateFunction
-from calfkit.nodes.tool import ToolNodeDef
+from calfkit.nodes.tool import BaseToolNodeDef, ToolNodeDef, _safe_exc_message
 from calfkit.providers.pydantic_ai.model_client import PydanticModelClient
 
 logger = logging.getLogger(__name__)
 
-NoneType = type(None)
-
 
 class BaseAgentNodeDef(
     Generic[AgentOutputT],
@@ -85,11 +86,17 @@ class BaseAgentNodeDef(
         elif self.tools:
             tools_registry = {tool.tool_schema.name: tool for tool in self.tools}
 
+        # ``latest_tool_calls()`` walks ``message_history`` in reverse on each call;
+        # cache once for all pre-model uses. The post-model use after
+        # ``result.new_messages()`` is extended into history must re-call to see
+        # the model's new tool calls.
+        latest_tool_calls = ctx.state.latest_tool_calls()
+
         logger.debug(
             "[%s] agent run entered node=%s pending_tool_calls=%d history_len=%d",
             ctx.deps.correlation_id[:8],
             self.name,
-            len(ctx.state.latest_tool_calls()),
+            len(latest_tool_calls),
             len(ctx.state.message_history),
         )
 
@@ -99,7 +106,61 @@ class BaseAgentNodeDef(
             if batch and not batch.is_complete:
                 return Silent()
 
-        latest_tool_calls = ctx.state.latest_tool_calls()
+        # Collect all FailedToolCall results in this turn so operators see every
+        # failure in a parallel batch; raise on the first after logging all.
+        # Also defend against corrupt marker dicts: a payload with the calfkit
+        # marker tag that fails ``FailedToolCall`` validation (e.g. schema drift
+        # during rolling deploy, a required field added without default, a
+        # tampered wire payload) round-trips through the union's ``| Any`` arm
+        # as a plain ``dict``. Synthesize a typed marker so the silent-failure
+        # path closes — operators still see the raise and the corrupt-keys
+        # context.
+        failed_tool_calls: list[FailedToolCall] = []
+        for tc in latest_tool_calls:
+            result = ctx.state.tool_results.get(tc.tool_call_id)
+            if isinstance(result, FailedToolCall):
+                failed_tool_calls.append(result)
+            elif isinstance(result, dict) and result.get("marker_kind") == "calfkit-tool-error":
+                logger.error(
+                    "[%s] corrupt FailedToolCall marker detected node=%s tool_call_id=%s raw_keys=%s; "
+                    "likely schema drift or version skew across the Kafka boundary",
+                    ctx.deps.correlation_id[:8],
+                    self.name,
+                    tc.tool_call_id,
+                    sorted(result.keys()),
+                )
+                # Synthesize a typed marker with sentinel fields known to pass
+                # FailedToolCall's validators. tc.tool_call_id is the LLM-emitted
+                # correlation key; fall back to "<missing>" if it's empty so
+                # ``min_length=1`` doesn't itself raise.
+                raw_tool_name = result.get("tool_name")
+                failed_tool_calls.append(
+                    FailedToolCall(
+                        tool_name=raw_tool_name if isinstance(raw_tool_name, str) and raw_tool_name else "<unknown>",
+                        tool_call_id=tc.tool_call_id or "<missing>",
+                        exc_type="CorruptFailedToolCallMarker",
+                        exc_message=f"Marker dict failed validation as FailedToolCall (likely schema drift); raw_keys={sorted(result.keys())}",
+                    )
+                )
+        if failed_tool_calls:
+            for failure in failed_tool_calls:
+                logger.error(
+                    "[%s] tool execution error detected node=%s tool=%s tool_call_id=%s exc_type=%s exc_message=%s",
+                    ctx.deps.correlation_id[:8],
+                    self.name,
+                    failure.tool_name,
+                    failure.tool_call_id,
+                    failure.exc_type,
+                    failure.exc_message,
+                )
+            first = failed_tool_calls[0]
+            raise ToolExecutionError(
+                tool_name=first.tool_name,
+                tool_call_id=first.tool_call_id,
+                exc_type=first.exc_type,
+                exc_message=first.exc_message,
+            )
+
         tool_results = None
 
         if len(latest_tool_calls) > 0:
@@ -141,14 +202,13 @@ class BaseAgentNodeDef(
             model_settings=run_model_settings,
         )
         if isinstance(result.output, DeferredToolRequests):
-            # The LLM called one or more tools
             logger.debug(
                 "[%s] model returned DeferredToolRequests tool_count=%d node=%s",
                 ctx.deps.correlation_id[:8],
                 len(result.output.calls),
                 self.name,
             )
-            messages = result.new_messages()  # preserve conversation history
+            messages = result.new_messages()
             ctx.state.message_history.extend(messages)
             latest_tool_calls = ctx.state.latest_tool_calls()
 
@@ -166,7 +226,9 @@ class BaseAgentNodeDef(
                             tool_call_id=tool_call.tool_call_id,
                         ),
                     )
-                elif tool_node.subscribe_topics is None:
+                    continue
+
+                if tool_node.subscribe_topics is None:
                     logger.error(
                         "tool=%s is unreachable. No subscribe topics were provided for the tool node.",
                         tool_call.tool_name,
@@ -179,8 +241,89 @@ class BaseAgentNodeDef(
                             tool_call_id=tool_call.tool_call_id,
                         ),
                     )
+                    continue
+
+                # Parse args from the LLM's emission. Applies to ALL dispatch
+                # paths so that malformed-JSON args from override (schema-only)
+                # tools are also surfaced as RetryPromptPart instead of escaping
+                # to the worker's hard FailedToolCall path.
+                #
+                # ``args_as_dict()`` can raise more than just ValueError /
+                # AssertionError: ``pydantic_core.from_json`` raises TypeError
+                # when ``args`` is a non-string/non-bytes value (e.g. an int or
+                # list emitted by an off-spec provider). Catch broadly so any
+                # parse failure surfaces as an LLM-retryable RetryPromptPart
+                # rather than escaping ``run()`` and hanging the caller.
+                try:
+                    args = tool_call.args_as_dict()
+                except Exception as e:
+                    content = f"Malformed tool arguments: {type(e).__name__}: {_safe_exc_message(e)}"
+                    logger.warning(
+                        "[%s] tool=%s args parse failed at dispatch: %s",
+                        ctx.deps.correlation_id[:8],
+                        tool_call.tool_name,
+                        content,
+                        exc_info=True,
+                    )
+                    ctx.state.add_tool_result(
+                        tool_call.tool_call_id,
+                        RetryPromptPart(
+                            content=content,
+                            tool_name=tool_call.tool_name,
+                            tool_call_id=tool_call.tool_call_id,
+                        ),
+                    )
+                    continue
+
+                # Validate against the schema if we have a runtime validator.
+                # Override-mode schemas (BaseToolNodeSchema-only) skip this step
+                # and dispatch unvalidated; this is the documented carve-out.
+                if isinstance(tool_node, BaseToolNodeDef):
+                    try:
+                        tool_node.validate_call_args(args)
+                    except ValidationError as e:
+                        validation_errors = e.errors(include_url=False, include_context=False)
+                        logger.warning(
+                            "[%s] tool=%s arg validation failed at dispatch: %s",
+                            ctx.deps.correlation_id[:8],
+                            tool_call.tool_name,
+                            validation_errors,
+                        )
+                        ctx.state.add_tool_result(
+                            tool_call.tool_call_id,
+                            RetryPromptPart(
+                                content=validation_errors,
+                                tool_name=tool_call.tool_name,
+                                tool_call_id=tool_call.tool_call_id,
+                            ),
+                        )
+                        continue
+                    except Exception as e:
+                        # A user-authored Pydantic ``field_validator`` raised
+                        # something other than ``ValidationError`` (e.g.
+                        # ``RuntimeError``, ``TypeError``, a custom exception).
+                        # Surface as ``RetryPromptPart`` so the LLM can retry
+                        # rather than letting the exception escape ``run()`` and
+                        # silently hang the caller.
+                        validator_content = f"Tool argument validator raised {type(e).__name__}: {_safe_exc_message(e)}"
+                        logger.warning(
+                            "[%s] tool=%s arg validator raised %s; surfacing as RetryPromptPart",
+                            ctx.deps.correlation_id[:8],
+                            tool_call.tool_name,
+                            type(e).__name__,
+                            exc_info=True,
+                        )
+                        ctx.state.add_tool_result(
+                            tool_call.tool_call_id,
+                            RetryPromptPart(
+                                content=validator_content,
+                                tool_name=tool_call.tool_name,
+                                tool_call_id=tool_call.tool_call_id,
+                            ),
+                        )
+                        continue
 
-            if ctx.state.all_call_ids_complete(*[tc.tool_call_id for tc in latest_tool_calls]):  # All tool calls were invalid, we need to retry.
+            if ctx.state.all_call_ids_complete(*[tc.tool_call_id for tc in latest_tool_calls]):
                 # TODO: maybe consider a node retry return type that doesn't require round trip to itself.
                 # Tailcall to itself is a roundtrip.
                 logger.debug("[%s] all tool calls invalid, TailCall retry node=%s", ctx.deps.correlation_id[:8], self.name)

calfkit-0.3.3/calfkit/nodes/tool.py

@@ -0,0 +1,200 @@
+import logging
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import Any, ClassVar
+
+import pydantic_core
+from typing_extensions import Self
+
+from calfkit._protocol import NodeKind
+from calfkit._vendor.pydantic_ai import Tool
+from calfkit._vendor.pydantic_ai.exceptions import ModelRetry
+from calfkit._vendor.pydantic_ai.messages import RetryPromptPart, ToolReturn
+from calfkit.models import SessionRunContext, Silent, State, ToolContext
+from calfkit.models.actions import NodeResult, ReturnCall
+from calfkit.models.node_schema import BaseToolNodeSchema
+from calfkit.models.state import FailedToolCall
+from calfkit.nodes.base import BaseNodeDef, GateFunction
+
+logger = logging.getLogger(__name__)
+
+
+def _safe_exc_message(e: BaseException) -> str:
+    """Best-effort string of an exception, robust against broken ``__str__``.
+
+    A bare ``str(e)`` can itself raise (if the exception's ``__str__`` is
+    broken or its args don't coerce). Inside the worker's ``except Exception``
+    block that would propagate out, prevent the FailedToolCall from being
+    constructed, and re-introduce the silent-hang failure mode this module
+    exists to prevent. Mirrors stdlib ``traceback._some_str`` with a ``repr``
+    fallback.
+    """
+    try:
+        return str(e)
+    except Exception:
+        try:
+            return repr(e)
+        except Exception:
+            return f"<unprintable {type(e).__name__}>"
+
+
+@dataclass
+class BaseToolNodeDef(BaseToolNodeSchema, BaseNodeDef):
+    _node_kind: ClassVar[NodeKind] = "tool"
+    _tool: Tool
+    gates: list[GateFunction] = field(default_factory=list)
+
+    def validate_call_args(self, args_dict: dict[str, Any]) -> Any:
+        """Validate ``args_dict`` against this tool's argument schema.
+
+        Raises ``pydantic.ValidationError`` on mismatch. Used by the agent to
+        fail-fast on LLM-produced malformed args before dispatching the call
+        across the Kafka boundary.
+
+        Note: tools with unannotated parameters (which default to ``Any`` in
+        pydantic-ai's function-schema) or with ``**kwargs`` (where extra fields
+        are allowed) bypass meaningful validation here — the worker-side
+        ``except Exception`` catch is the safety net for those.
+        """
+        return self._tool.function_schema.validator.validate_python(args_dict)
+
+
+class ToolNodeDef(BaseToolNodeDef):
+    @classmethod
+    def create_tool_node(
+        cls,
+        func: Callable[..., Any],
+        subscribe_topics: str | list[str],
+        publish_topic: str,
+        gates: list[GateFunction] | None = None,
+    ) -> Self:
+        if not isinstance(subscribe_topics, (list, tuple)):
+            subscribe_topics = [subscribe_topics]
+        tool = Tool(func)
+        return cls(
+            node_id=f"tool_{func.__name__}",
+            tool_schema=tool.tool_def,
+            subscribe_topics=subscribe_topics,
+            publish_topic=publish_topic,
+            _tool=tool,
+            gates=list(gates) if gates else [],
+        )
+
+    async def run(self, ctx: SessionRunContext, tool_call_id: str) -> NodeResult[State]:
+        logger.debug(
+            "[%s] tool run entered tool=%s tool_call_id=%s emitter=%s",
+            ctx.deps.correlation_id[:8],
+            self.name,
+            tool_call_id,
+            ctx.emitter_node_id,
+        )
+        tool_call_part = ctx.state.get_tool_call(tool_call_id)
+        if tool_call_part is None:
+            logger.warning(
+                "tool node reached but no matching tool call found in run state for tool_call_id=%s",
+                tool_call_id,
+            )
+            return Silent()
+
+        tool_call_ctx = ToolContext(
+            deps=ctx.deps,
+            agent_name=ctx.emitter_node_id,
+            tool_call_id=tool_call_part.tool_call_id,
+            tool_name=tool_call_part.tool_name,
+            messages=ctx.state.message_history,
+            run_id=ctx.deps.correlation_id,
+        )
+
+        # TODO(#143): bounded retries / backoff for non-ModelRetry exceptions.
+        # ModelRetry below provides LLM-visible retry per pydantic-ai semantics
+        # but is not yet rate-limited on the deferred path.
+        try:
+            result = await self._tool.function_schema.call(tool_call_part.args_as_dict(), tool_call_ctx)
+            # Construct the ToolReturn and eagerly verify it is wire-safe BEFORE
+            # storing in state. FastStream's envelope serialization at publish
+            # time would raise PydanticSerializationError on a non-serializable
+            # return_value, killing the worker handler before the reply
+            # publishes — the silent-hang failure mode this module exists to
+            # prevent. By serializing inside the try block, any failure flows
+            # through ``except Exception`` below and surfaces as a FailedToolCall.
+            tool_return = ToolReturn(return_value=result, metadata={"tool_call_id": tool_call_part.tool_call_id})
+            pydantic_core.to_json(tool_return)
+        except ModelRetry as e:
+            logger.warning(
+                "[%s] tool=%s raised ModelRetry: %s",
+                ctx.deps.correlation_id[:8],
+                self.name,
+                e.message,
+            )
+            ctx.state.add_tool_result(
+                tool_call_part.tool_call_id,
+                RetryPromptPart(
+                    content=e.message,
+                    tool_name=tool_call_part.tool_name,
+                    tool_call_id=tool_call_part.tool_call_id,
+                ),
+            )
+            return ReturnCall[State](state=ctx.state)
+        except Exception as e:
+            logger.exception(
+                "[%s] tool=%s tool_call_id=%s raised %s; surfacing FailedToolCall to agent",
+                ctx.deps.correlation_id[:8],
+                self.name,
+                tool_call_part.tool_call_id,
+                type(e).__name__,
+            )
+            # Construct the marker defensively: a validator on FailedToolCall (e.g.,
+            # min_length on tool_call_id) could itself raise inside this except block
+            # and re-introduce the silent-hang failure mode we exist to prevent.
+            try:
+                marker: FailedToolCall = FailedToolCall(
+                    tool_name=tool_call_part.tool_name,
+                    tool_call_id=tool_call_part.tool_call_id,
+                    exc_type=type(e).__name__,
+                    exc_message=_safe_exc_message(e),
+                )
+            except Exception as construct_err:
+                logger.exception(
+                    "[%s] tool=%s tool_call_id=%s failed to construct FailedToolCall (%s); using fallback sentinel marker",
+                    ctx.deps.correlation_id[:8],
+                    self.name,
+                    tool_call_part.tool_call_id,
+                    type(construct_err).__name__,
+                )
+                # Fallback: preserve real ``tool_name`` / ``tool_call_id`` from
+                # ``tool_call_part`` when they are valid strings (so operators
+                # don't lose the correlation key in the raised ToolExecutionError);
+                # only substitute sentinels for fields that are themselves
+                # problematic. ``isinstance(..., str)`` and truthy guards keep
+                # construction total even if the originals are the cause of the
+                # primary failure (e.g. empty ``tool_call_id``).
+                fallback_tool_name = (
+                    tool_call_part.tool_name if isinstance(tool_call_part.tool_name, str) and tool_call_part.tool_name else "<unknown>"
+                )
+                fallback_tool_call_id = (
+                    tool_call_part.tool_call_id if isinstance(tool_call_part.tool_call_id, str) and tool_call_part.tool_call_id else "<missing>"
+                )
+                marker = FailedToolCall(
+                    tool_name=fallback_tool_name,
+                    tool_call_id=fallback_tool_call_id,
+                    exc_type="FailedToolCallConstructionError",
+                    exc_message=f"Failed to construct primary marker: {_safe_exc_message(construct_err)}",
+                )
+            ctx.state.add_tool_result(tool_call_part.tool_call_id, marker)
+            return ReturnCall[State](state=ctx.state)
+
+        # ``tool_return`` was constructed and serialization-verified inside the
+        # try block above; reuse it rather than constructing twice.
+        ctx.state.add_tool_result(tool_call_part.tool_call_id, tool_return)
+
+        logger.debug("[%s] tool completed tool=%s", ctx.deps.correlation_id[:8], self.name)
+        return ReturnCall[State](state=ctx.state)
+
+
+def agent_tool(func: Callable[..., Any] | Callable[..., Awaitable[Any]]) -> ToolNodeDef:
+    """Decorator to turn a function into a deployable tool node that agents can call"""
+    subscribe_topic = f"tool.{func.__name__}.input"
+    publish_topic = f"tool.{func.__name__}.output"
+    tool_node = ToolNodeDef.create_tool_node(func=func, subscribe_topics=subscribe_topic, publish_topic=publish_topic)
+
+    return tool_node