calfkit 0.2.4__tar.gz → 0.2.6__tar.gz

{calfkit-0.2.4 → calfkit-0.2.6}/.github/workflows/release.yml

@@ -22,7 +22,7 @@ jobs:
     steps:
       - name: Run release-please
         id: release
-        uses: googleapis/release-please-action@v4
+        uses: googleapis/release-please-action@v5
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
 

{calfkit-0.2.4 → calfkit-0.2.6}/.github/workflows/security.yml

@@ -58,7 +58,7 @@ jobs:
         uses: actions/checkout@v6
 
       - name: Dependency Review
-        uses: actions/dependency-review-action@v4
+        uses: actions/dependency-review-action@v5
         with:
           fail-on-severity: high
           deny-licenses: GPL-3.0, AGPL-3.0

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

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

{calfkit-0.2.4 → calfkit-0.2.6}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.2.6](https://github.com/calf-ai/calfkit-sdk/compare/v0.2.5...v0.2.6) (2026-05-17)
+
+
+### Features
+
+* add gates to BaseNodeDef for pre-run event filtering ([#127](https://github.com/calf-ai/calfkit-sdk/issues/127)) ([9fbdbd0](https://github.com/calf-ai/calfkit-sdk/commit/9fbdbd072a4de4335c3774efa8775c0e8b43b2bd))
+
+## [0.2.5](https://github.com/calf-ai/calfkit-sdk/compare/v0.2.4...v0.2.5) (2026-04-11)
+
+
+### Features
+
+* add serializable node schemas and runtime tool overrides ([#121](https://github.com/calf-ai/calfkit-sdk/issues/121)) ([e464c08](https://github.com/calf-ai/calfkit-sdk/commit/e464c08e4f179e0cd622789a067718fdbd043c1f))
+
 ## [0.2.4](https://github.com/calf-ai/calfkit-sdk/compare/v0.2.3...v0.2.4) (2026-04-08)
 
 

{calfkit-0.2.4 → calfkit-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: calfkit
-Version: 0.2.4
+Version: 0.2.6
 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
@@ -316,6 +316,48 @@ result = await client.execute_node(
 
 <br>
 
+### Gating Node Invocations (Optional)
+
+When multiple agents share an input topic (each with its own consumer group), every agent receives every message published to that topic. A **gate stack** lets a node decide whether to handle an inbound event *before* `run()` runs — avoiding wasted LLM tokens on messages addressed elsewhere.
+
+Gates are predicates: `Callable[[SessionRunContext], bool | Awaitable[bool]]`. They stack with **AND semantics** in registration order and short-circuit on the first `False`, exception, or non-bool return. When any gate rejects, `run()` is skipped and the envelope is returned unchanged — the Kafka offset still commits.
+
+**Constructor form** — good for shared, cross-cutting predicates passed in as values:
+
+```python
+def is_scheduler_target(ctx) -> bool:
+    discord = ctx.deps.provided_deps.get("discord", {})
+    return discord.get("slash_target") == "scheduler"
+
+scheduler = Agent(
+    "scheduler",
+    subscribe_topics="discord.thread.123",
+    model_client=OpenAIResponsesModelClient(model_name="gpt-5.4-nano"),
+    gates=[is_scheduler_target],
+)
+```
+
+**Decorator form** — good for node-specific gates defined inline:
+
+```python
+scheduler = Agent("scheduler", subscribe_topics="discord.thread.123", model_client=...)
+
+@scheduler.gate
+def is_scheduler_target(ctx) -> bool:
+    discord = ctx.deps.provided_deps.get("discord", {})
+    return discord.get("slash_target") == "scheduler"
+```
+
+Constructor and decorator forms can be combined; constructor gates run first.
+
+**Idempotency requirement**: Kafka may redeliver an event before its offset commits, so gates may run more than once for the same logical message. Keep gate functions deterministic and side-effect-free.
+
+**Failure behavior**: If a gate raises or returns a non-bool, the framework logs the failure and rejects the message (fail-safe). Place cheap fast-reject gates first to maximize short-circuit efficiency.
+
+For tool-node gating, pass `gates=[...]` to `ToolNodeDef.create_tool_node(...)` directly; the `@agent_tool` decorator doesn't expose `gates=` because tool topics are typically 1:1.
+
+<br>
+
 ## Documentation
 
 Full documentation is coming soon. In the meantime, this README serves as the primary reference for getting started with Calfkit.

{calfkit-0.2.4 → calfkit-0.2.6}/README.md

@@ -278,6 +278,48 @@ result = await client.execute_node(
 
 <br>
 
+### Gating Node Invocations (Optional)
+
+When multiple agents share an input topic (each with its own consumer group), every agent receives every message published to that topic. A **gate stack** lets a node decide whether to handle an inbound event *before* `run()` runs — avoiding wasted LLM tokens on messages addressed elsewhere.
+
+Gates are predicates: `Callable[[SessionRunContext], bool | Awaitable[bool]]`. They stack with **AND semantics** in registration order and short-circuit on the first `False`, exception, or non-bool return. When any gate rejects, `run()` is skipped and the envelope is returned unchanged — the Kafka offset still commits.
+
+**Constructor form** — good for shared, cross-cutting predicates passed in as values:
+
+```python
+def is_scheduler_target(ctx) -> bool:
+    discord = ctx.deps.provided_deps.get("discord", {})
+    return discord.get("slash_target") == "scheduler"
+
+scheduler = Agent(
+    "scheduler",
+    subscribe_topics="discord.thread.123",
+    model_client=OpenAIResponsesModelClient(model_name="gpt-5.4-nano"),
+    gates=[is_scheduler_target],
+)
+```
+
+**Decorator form** — good for node-specific gates defined inline:
+
+```python
+scheduler = Agent("scheduler", subscribe_topics="discord.thread.123", model_client=...)
+
+@scheduler.gate
+def is_scheduler_target(ctx) -> bool:
+    discord = ctx.deps.provided_deps.get("discord", {})
+    return discord.get("slash_target") == "scheduler"
+```
+
+Constructor and decorator forms can be combined; constructor gates run first.
+
+**Idempotency requirement**: Kafka may redeliver an event before its offset commits, so gates may run more than once for the same logical message. Keep gate functions deterministic and side-effect-free.
+
+**Failure behavior**: If a gate raises or returns a non-bool, the framework logs the failure and rejects the message (fail-safe). Place cheap fast-reject gates first to maximize short-circuit efficiency.
+
+For tool-node gating, pass `gates=[...]` to `ToolNodeDef.create_tool_node(...)` directly; the `@agent_tool` decorator doesn't expose `gates=` because tool topics are typically 1:1.
+
+<br>
+
 ## Documentation
 
 Full documentation is coming soon. In the meantime, this README serves as the primary reference for getting started with Calfkit.

{calfkit-0.2.4 → calfkit-0.2.6}/calfkit/__init__.py

@@ -2,7 +2,7 @@ from importlib.metadata import version
 
 from calfkit.client import Client, InvocationHandle, NodeResult
 from calfkit.models import ToolContext
-from calfkit.nodes import Agent, BaseNodeDef, NodeDef, ToolNodeDef, agent_tool
+from calfkit.nodes import Agent, BaseNodeDef, GateFunction, NodeDef, ToolNodeDef, agent_tool
 from calfkit.providers import AnthropicModelClient, OpenAIModelClient, OpenAIResponsesModelClient
 from calfkit.worker import Worker
 
@@ -18,6 +18,7 @@ __all__ = [
     # nodes
     "Agent",
     "BaseNodeDef",
+    "GateFunction",
     "NodeDef",
     "ToolNodeDef",
     "agent_tool",

{calfkit-0.2.4 → calfkit-0.2.6}/calfkit/client/base.py

@@ -20,6 +20,7 @@ from calfkit.models.session_context import (
     SessionRunContext,
     WorkflowState,
 )
+from calfkit.models.state import OverridesState
 
 logger = logging.getLogger(__name__)
 
@@ -111,6 +112,7 @@ class BaseClient:
         reply_topic: str,
         correlation_id: str,
         state: State,
+        overrides: OverridesState | None = None,
         run_args: Sequence[Any] | None = None,
         deps: dict[str, Any] | None = None,
         output_type: type[Any] = _UNSET,
@@ -136,7 +138,7 @@ class BaseClient:
             await self._connection.start()
 
         call_stack = CallFrameStack()
-        call_stack.push(CallFrame(target_topic=topic, callback_topic=reply_topic, input_args=run_args))
+        call_stack.push(CallFrame(target_topic=topic, callback_topic=reply_topic, input_args=run_args, overrides=overrides))
 
         envelope = Envelope(
             internal_workflow_state=WorkflowState(call_stack=call_stack),

{calfkit-0.2.4 → calfkit-0.2.6}/calfkit/client/client.py

@@ -12,6 +12,8 @@ from calfkit.client.deserialize import _UNSET
 from calfkit.client.invocation_handle import InvocationHandle
 from calfkit.client.node_result import NodeResult
 from calfkit.models import State
+from calfkit.models.node_schema import BaseToolNodeSchema
+from calfkit.models.state import OverridesState
 
 
 class Client(BaseClient):
@@ -30,6 +32,7 @@ class Client(BaseClient):
         topic: str,
         *,
         output_type: type[OutputT],
+        tool_overrides: list[BaseToolNodeSchema] | None = ...,
         reply_topic: str | None = ...,
         correlation_id: str | None = ...,
         temp_instructions: str | None = ...,
@@ -44,6 +47,7 @@ class Client(BaseClient):
         user_prompt: str,
         topic: str,
         *,
+        tool_overrides: list[BaseToolNodeSchema] | None = ...,
         reply_topic: str | None = ...,
         correlation_id: str | None = ...,
         temp_instructions: str | None = ...,
@@ -57,6 +61,7 @@ class Client(BaseClient):
         user_prompt: str,
         topic: str,
         *,
+        tool_overrides: list[BaseToolNodeSchema] | None = None,
         output_type: type[Any] = _UNSET,
         reply_topic: str | None = None,
         correlation_id: str | None = None,
@@ -74,6 +79,7 @@ class Client(BaseClient):
         Args:
             user_prompt: The user message to send to the agent node.
             topic: The Kafka topic the target node subscribes to.
+            tool_overrides: Runtime agent tool overrides.
             output_type: The expected Python type for deserializing the agent's
                 output. When omitted, auto-detection is used (``DataPart`` →
                 ``TextPart`` fallback).
@@ -82,7 +88,7 @@ class Client(BaseClient):
             correlation_id: Unique identifier to correlate this request with its
                 reply. Auto-generated (uuid7) when ``None``.
             temp_instructions: Optional system-level instructions injected into
-                the user prompt as a one-shot override.
+                the user prompt as a temporary prompt addition.
             message_history: Prior conversation messages to include for
                 multi-turn context. Defaults to an empty history.
             run_args: Positional arguments forwarded to the node's ``run()``
@@ -107,6 +113,7 @@ class Client(BaseClient):
             correlation_id=correlation_id,
             run_args=run_args,
             state=state,
+            overrides=OverridesState(override_agent_tools=tool_overrides) if tool_overrides is not None else None,
             deps=deps,
             output_type=output_type,
         )
@@ -118,6 +125,7 @@ class Client(BaseClient):
         topic: str,
         *,
         output_type: type[OutputT],
+        tool_overrides: list[BaseToolNodeSchema] | None = ...,
         reply_topic: str | None = ...,
         correlation_id: str | None = ...,
         temp_instructions: str | None = ...,
@@ -133,6 +141,7 @@ class Client(BaseClient):
         user_prompt: str,
         topic: str,
         *,
+        tool_overrides: list[BaseToolNodeSchema] | None = ...,
         reply_topic: str | None = ...,
         correlation_id: str | None = ...,
         temp_instructions: str | None = ...,
@@ -147,6 +156,7 @@ class Client(BaseClient):
         user_prompt: str,
         topic: str,
         *,
+        tool_overrides: list[BaseToolNodeSchema] | None = None,
         output_type: type[Any] = _UNSET,
         reply_topic: str | None = None,
         correlation_id: str | None = None,
@@ -168,6 +178,7 @@ class Client(BaseClient):
         Args:
             user_prompt: The user message to send to the agent node.
             topic: The Kafka topic the target node subscribes to.
+            tool_overrides: Runtime agent tool overrides.
             output_type: The expected Python type for deserializing the agent's
                 output. When omitted, auto-detection is used.
             reply_topic: Topic the node should publish its reply to.
@@ -175,7 +186,7 @@ class Client(BaseClient):
             correlation_id: Unique identifier to correlate this request with its
                 reply. Auto-generated (uuid7) when ``None``.
             temp_instructions: Optional system-level instructions injected into
-                the user prompt as a one-shot override.
+                the user prompt as a temporary prompt addition.
             message_history: Prior conversation messages to include for
                 multi-turn context. Defaults to an empty history.
             run_args: Positional arguments forwarded to the node's ``run()``
@@ -195,6 +206,7 @@ class Client(BaseClient):
         handle = await self.invoke_node(
             user_prompt,
             topic,
+            tool_overrides=tool_overrides,
             output_type=output_type,
             reply_topic=reply_topic,
             correlation_id=correlation_id,

calfkit-0.2.6/calfkit/models/node_schema.py

@@ -0,0 +1,21 @@
+from dataclasses import KW_ONLY, dataclass
+
+from calfkit._vendor.pydantic_ai.tools import ToolDefinition
+
+
+@dataclass
+class BaseNodeSchema:
+    _: KW_ONLY
+    node_id: str
+    subscribe_topics: list[str]
+    publish_topic: str | None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.subscribe_topics, (list, tuple)):
+            self.subscribe_topics = [self.subscribe_topics]
+
+
+@dataclass
+class BaseToolNodeSchema(BaseNodeSchema):
+    _: KW_ONLY
+    tool_schema: ToolDefinition

{calfkit-0.2.4 → calfkit-0.2.6}/calfkit/models/session_context.py

@@ -7,7 +7,7 @@ from pydantic import BaseModel, ConfigDict, Field
 
 from calfkit._types import DepsT, StackItemT, StateT
 from calfkit.models.actions import _Call
-from calfkit.models.state import State
+from calfkit.models.state import OverridesState, State
 
 
 @dataclass
@@ -36,6 +36,7 @@ class CallFrame:
     callback_topic: str  # return address
     input_args: Sequence[Any] | None = field(default=None)
     frame_id: str = field(default_factory=lambda: uuid_utils.uuid7().hex)
+    overrides: OverridesState | None = field(default=None)
 
 
 CallFrameStack = Stack[CallFrame]

{calfkit-0.2.4 → calfkit-0.2.6}/calfkit/models/state.py

@@ -11,6 +11,7 @@ from calfkit._vendor.pydantic_ai.messages import (
     ToolCallPart,
 )
 from calfkit._vendor.pydantic_ai.tools import DeferredToolCallResult as ToolCallResult
+from calfkit.models.node_schema import BaseToolNodeSchema
 from calfkit.models.payload import ContentPart
 
 
@@ -18,6 +19,13 @@ class BaseAgentActivityState(BaseModel):
     model_config = ConfigDict(extra="ignore")
 
 
+class OverridesState(BaseAgentActivityState):
+    """State for storing any override objects"""
+
+    model_config = ConfigDict(extra="ignore")
+    override_agent_tools: list[BaseToolNodeSchema] | None
+
+
 class CoreMessageState(BaseAgentActivityState):
     """The state for committed messages and structured objects"""
 
@@ -90,6 +98,7 @@ class State(CoreMessageState, InFlightToolsState):
         default=None,
         description="Additional data that can be accessed programmatically by the application but is not sent to the LLM.",  # noqa: E501
     )
+    overrides: OverridesState | None = None
 
 
 # class State(BaseModel):

{calfkit-0.2.4 → calfkit-0.2.6}/calfkit/nodes/__init__.py

@@ -1,5 +1,5 @@
 from calfkit.nodes.agent import Agent, BaseAgentNodeDef
-from calfkit.nodes.base import BaseNodeDef
+from calfkit.nodes.base import BaseNodeDef, GateFunction
 from calfkit.nodes.node import NodeDef
 from calfkit.nodes.tool import BaseToolNodeDef, ToolNodeDef, agent_tool
 
@@ -8,6 +8,7 @@ __all__ = [
     "BaseAgentNodeDef",
     "BaseNodeDef",
     "BaseToolNodeDef",
+    "GateFunction",
     "NodeDef",
     "ToolNodeDef",
     "agent_tool",

{calfkit-0.2.4 → calfkit-0.2.6}/calfkit/nodes/agent.py

@@ -11,9 +11,10 @@ from calfkit._vendor.pydantic_ai.tools import DeferredToolResults
 from calfkit._vendor.pydantic_ai.toolsets.external import ExternalToolset
 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.nodes.base import BaseNodeDef
+from calfkit.nodes.base import BaseNodeDef, GateFunction
 from calfkit.nodes.tool import ToolNodeDef
 from calfkit.providers.pydantic_ai.model_client import PydanticModelClient
 
@@ -33,6 +34,7 @@ class BaseAgentNodeDef(
         system_prompt: str = "You are a helpful AI assistant.",
         subscribe_topics: str | list[str],
         publish_topic: str | None = None,
+        gates: list[GateFunction] | None = None,
         tools: list[ToolNodeDef] | None = None,
         model_client: PydanticModelClient,
         final_output_type: OutputSpec[AgentOutputT] = str,  # type: ignore[assignment]
@@ -44,7 +46,10 @@ class BaseAgentNodeDef(
         self.sequential_only_mode = sequential_only_mode
         self._pending_batches: dict[str, PendingToolBatch] = dict()
 
-        super().__init__(node_id=node_id, subscribe_topics=subscribe_topics, publish_topic=publish_topic)
+        if not isinstance(subscribe_topics, (list, tuple)):
+            subscribe_topics = [subscribe_topics]
+
+        super().__init__(node_id=node_id, subscribe_topics=subscribe_topics, publish_topic=publish_topic, gates=gates)
 
         self._agent_loop: InternalAgentLoop[dict[str, Any], AgentOutputT | DeferredToolRequests] = InternalAgentLoop(
             model_client, name=self.name, output_type=[final_output_type, DeferredToolRequests], deps_type=dict, instructions=system_prompt
@@ -64,7 +69,11 @@ class BaseAgentNodeDef(
                 del self._pending_batches[ctx.deps.correlation_id]
 
     async def run(self, ctx: SessionRunContext) -> NodeResult[State]:
-        tools_registry = {tool.tool_schema.name: tool for tool in self.tools} if self.tools else dict[str, ToolNodeDef]()
+        tools_registry = dict[str, BaseToolNodeSchema]()
+        if ctx.state.overrides is not None and ctx.state.overrides.override_agent_tools is not None:
+            tools_registry = {tool.tool_schema.name: tool for tool in ctx.state.overrides.override_agent_tools}
+        elif self.tools:
+            tools_registry = {tool.tool_schema.name: tool for tool in self.tools}
 
         logger.debug(
             "[%s] agent run entered node=%s pending_tool_calls=%d history_len=%d",

{calfkit-0.2.4 → calfkit-0.2.6}/calfkit/nodes/base.py

@@ -1,6 +1,7 @@
 import inspect
 import logging
 from abc import abstractmethod
+from collections.abc import Awaitable, Callable
 from typing import Annotated, Any
 
 from faststream import Context
@@ -17,17 +18,27 @@ from calfkit.models import (
     TailCall,
 )
 from calfkit.models.envelope import Envelope
+from calfkit.models.node_schema import BaseNodeSchema
 from calfkit.models.session_context import SessionRunContext
 
 logger = logging.getLogger(__name__)
 
 
+GateFunction = Callable[[SessionRunContext], bool | Awaitable[bool]]
+"""A predicate evaluated in ``handler()`` before ``run()``. Sync or async; must return ``bool``.
+
+Returning ``False`` (or raising, or returning a non-bool) skips ``run()`` and returns the
+envelope unchanged. Gates stack with AND semantics in registration order and short-circuit
+on the first rejection.
+"""
+
+
 # ---------------------------------------------------------------------------
 # Base node definition
 # ---------------------------------------------------------------------------
 
 
-class BaseNodeDef:
+class BaseNodeDef(BaseNodeSchema):
     _run_accepts_input: bool
 
     def __init_subclass__(cls, **kwargs: Any) -> None:
@@ -39,18 +50,70 @@ class BaseNodeDef:
 
     def __init__(
         self,
-        node_id: str,
         *,
-        subscribe_topics: str | list[str],
-        publish_topic: str | None,
-    ):
-        self._node_id = node_id
-        if isinstance(subscribe_topics, str):
-            self.subscribe_topics = [subscribe_topics]
-        elif subscribe_topics is not None:
-            self.subscribe_topics = list(subscribe_topics)
-        self.publish_topic = publish_topic
-        self._return_topic = f"{node_id}.private.return"
+        node_id: str,
+        subscribe_topics: list[str],
+        publish_topic: str | None = None,
+        gates: list[GateFunction] | None = None,
+    ) -> None:
+        """Initialize a node definition.
+
+        Args:
+            node_id: Unique identifier for the node.
+            subscribe_topics: One or more topics the node consumes from.
+            publish_topic: Optional default topic to publish results to.
+            gates: Optional list of predicates evaluated in ``handler()`` before
+                ``run()``. Stack with AND semantics in registration order;
+                short-circuits on the first ``False``, exception, or non-bool.
+                Returning anything other than ``True`` rejects the message:
+                ``run()`` is skipped and the envelope is returned unchanged.
+        """
+        super().__init__(
+            node_id=node_id,
+            subscribe_topics=subscribe_topics,
+            publish_topic=publish_topic,
+        )
+        self.gates: list[GateFunction] = list(gates) if gates else []
+
+    def gate(self, fn: GateFunction) -> GateFunction:
+        """Register a gate predicate. Usable as a decorator. Repeatable.
+
+        Multiple gates evaluate in registration order with AND semantics
+        (short-circuit on the first ``False``, exception, or non-bool return).
+        Returns ``fn`` unchanged so it remains callable.
+        """
+        self.gates.append(fn)
+        return fn
+
+    async def _evaluate_gates(self, ctx: SessionRunContext, correlation_id: str) -> bool:
+        for i, gate in enumerate(self.gates):
+            try:
+                result = gate(ctx)
+                if inspect.isawaitable(result):
+                    result = await result
+                if not isinstance(result, bool):
+                    raise TypeError(
+                        f"gate[{i}] {getattr(gate, '__name__', repr(gate))} for node={self.node_id} returned {type(result).__name__}; expected bool"
+                    )
+                if not result:
+                    logger.debug(
+                        "[%s] gate[%d]=%s rejected node=%s",
+                        correlation_id[:8],
+                        i,
+                        getattr(gate, "__name__", "?"),
+                        self.node_id,
+                    )
+                    return False
+            except Exception:
+                logger.exception(
+                    "[%s] gate[%d]=%s raised for node=%s; treating as reject",
+                    correlation_id[:8],
+                    i,
+                    getattr(gate, "__name__", "?"),
+                    self.node_id,
+                )
+                return False
+        return True
 
     # TODO: consider multiple abstract methods per node based on the incoming communication pattern,
     # like a delgation or emit. So the communication-specific handler can properly handle it
@@ -77,6 +140,8 @@ class BaseNodeDef:
 
     async def prepare_context(self, envelope: Envelope) -> SessionRunContext:
         ctx = envelope.context.model_copy(deep=True)
+        if envelope.internal_workflow_state.current_frame.overrides:
+            ctx.state.overrides = envelope.internal_workflow_state.current_frame.overrides
         return ctx
 
     async def _publish_action(self, output: NodeResult[State], envelope: Envelope, correlation_id: str, broker: BrokerAnnotation) -> Envelope:
@@ -107,7 +172,7 @@ class BaseNodeDef:
                 internal_workflow_state=envelope.internal_workflow_state,
             )
             target_topic = envelope.internal_workflow_state.current_frame.target_topic
-            logger.debug("[%s] Call target=%s frame_pushed node=%s", correlation_id[:8], target_topic, self._node_id)
+            logger.debug("[%s] Call target=%s frame_pushed node=%s", correlation_id[:8], target_topic, self.node_id)
             await broker.publish(
                 publish_envelope,
                 topic=target_topic,
@@ -121,7 +186,7 @@ class BaseNodeDef:
                 context=SessionRunContext(state=output.state, deps=envelope.context.deps),
                 internal_workflow_state=envelope.internal_workflow_state,
             )
-            logger.debug("[%s] ReturnCall callback=%s node=%s", correlation_id[:8], frame.callback_topic, self._node_id)
+            logger.debug("[%s] ReturnCall callback=%s node=%s", correlation_id[:8], frame.callback_topic, self.node_id)
             await broker.publish(
                 publish_envelope,
                 topic=frame.callback_topic,
@@ -138,7 +203,7 @@ class BaseNodeDef:
                 internal_workflow_state=envelope.internal_workflow_state,
             )
             target_topic = envelope.internal_workflow_state.current_frame.target_topic
-            logger.debug("[%s] TailCall target=%s node=%s", correlation_id[:8], target_topic, self._node_id)
+            logger.debug("[%s] TailCall target=%s node=%s", correlation_id[:8], target_topic, self.node_id)
             await broker.publish(
                 publish_envelope,
                 topic=target_topic,
@@ -164,21 +229,29 @@ class BaseNodeDef:
         correlation_id: Annotated[str, Context()],
         broker: BrokerAnnotation,
     ) -> Envelope:
-        logger.debug("[%s] handler entered node=%s", correlation_id[:8], self._node_id)
+        logger.debug("[%s] handler entered node=%s", correlation_id[:8], self.node_id)
         ctx = await self.prepare_context(envelope)
+
+        if not await self._evaluate_gates(ctx, correlation_id):
+            return envelope
+
         if self._run_accepts_input and envelope.internal_workflow_state.current_frame.input_args is not None:
             output = await self.run(ctx, *envelope.internal_workflow_state.current_frame.input_args)
         else:
             output = await self.run(ctx)
 
-        logger.debug("[%s] run() returned action=%s node=%s", correlation_id[:8], type(output).__name__, self._node_id)
+        logger.debug("[%s] run() returned action=%s node=%s", correlation_id[:8], type(output).__name__, self.node_id)
 
         return await self._publish_action(output, envelope, correlation_id, broker)
 
     @property
     def id(self) -> str:
-        return self._node_id
+        return self.node_id
 
     @property
     def name(self) -> str:
-        return self._node_id
+        return self.node_id
+
+    @property
+    def _return_topic(self) -> str:
+        return f"{self.node_id}.private.return"