calfkit 0.3.1__tar.gz → 0.3.2__tar.gz

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

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

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

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.3.2](https://github.com/calf-ai/calfkit-sdk/compare/v0.3.1...v0.3.2) (2026-05-21)
+
+
+### Bug Fixes
+
+* route tool returns to private inbox to prevent co-tenant leak ([#142](https://github.com/calf-ai/calfkit-sdk/issues/142)) ([197463f](https://github.com/calf-ai/calfkit-sdk/commit/197463f2f7f338bae53bf144e3a86cf27373e350))
+
+
+### Documentation
+
+* integrate DX review into v1 design and add reviewer artifact ([#138](https://github.com/calf-ai/calfkit-sdk/issues/138)) ([29a7961](https://github.com/calf-ai/calfkit-sdk/commit/29a7961d5c2d4e46fcb7e2e4a81f43116c34feb3))
+
 ## [0.3.1](https://github.com/calf-ai/calfkit-sdk/compare/v0.3.0...v0.3.1) (2026-05-19)
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: calfkit
-Version: 0.3.1
+Version: 0.3.2
 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.1 → calfkit-0.3.2}/ROADMAP.md

@@ -6,3 +6,4 @@ An index of potential features and changes under consideration for Calf SDK. Eac
 
 - [Calfkit 1.0](docs/calfkit-v1-design.md) — 1.0 rewrite proposal covering node, agent, and result shape changes
 - [Hook System](docs/hooks-design.md) — two-layer middleware proposal for pre/post-run extensibility on nodes
+- [Durable Fan-Out Aggregator](docs/durable-fanout-aggregator.md) — replace in-process `_pending_batches` with a Kafka-backed compacted-state aggregator for parallel tool calls

calfkit-0.3.2/calfkit/models/node_schema.py

@@ -0,0 +1,32 @@
+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]
+        # Reject empty subscribe_topics for every node kind (Agent, Consumer,
+        # Tool, …). Lives here rather than in ``BaseNodeDef.__init__`` because
+        # ``@dataclass`` subclasses like ``BaseToolNodeDef`` get an
+        # auto-generated ``__init__`` that bypasses ``BaseNodeDef.__init__``
+        # entirely; ``__post_init__`` is the one hook every subclass runs.
+        # Without this guard, ``Worker.register_handlers`` would still add
+        # ``_return_topic`` to the subscriber set (issue #141 fix), so the
+        # node would "register" successfully but have no public inbox — a
+        # silent zombie consumer.
+        if not self.subscribe_topics:
+            raise ValueError(f"node {self.node_id!r} requires at least one subscribe_topic; got empty list")
+
+
+@dataclass
+class BaseToolNodeSchema(BaseNodeSchema):
+    _: KW_ONLY
+    tool_schema: ToolDefinition

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

@@ -184,7 +184,7 @@ class BaseAgentNodeDef(
                 # 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)
-                return TailCall[State](target_topic=self.subscribe_topics[0], state=ctx.state)
+                return TailCall[State](target_topic=self._return_topic, state=ctx.state)
 
             pending_tool_calls = [tc for tc in latest_tool_calls if tc.tool_call_id not in ctx.state.tool_results]
 

{calfkit-0.3.1 → calfkit-0.3.2}/calfkit/nodes/base.py

@@ -68,12 +68,22 @@ class BaseNodeDef(BaseNodeSchema):
         Args:
             node_id: Unique identifier for the node.
             subscribe_topics: One or more topics the node consumes from.
+                Must be non-empty — a node with no public inbox cannot be
+                invoked by any client or peer. Without the validation in
+                :meth:`BaseNodeSchema.__post_init__`, ``Worker.register_handlers``
+                would still wire the node up to ``_return_topic`` (issue #141
+                fix), so the node would "register" successfully while being
+                functionally unreachable from the outside.
             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.
+
+        Raises:
+            ValueError: If ``subscribe_topics`` is empty. Enforced uniformly
+                across all node kinds in :meth:`BaseNodeSchema.__post_init__`.
         """
         super().__init__(
             node_id=node_id,
@@ -168,7 +178,7 @@ class BaseNodeDef(BaseNodeSchema):
             # Parallel fan-out: publish each Call with independent workflow_state
             for call in output:
                 wf_copy = envelope.internal_workflow_state.model_copy(deep=True)
-                wf_copy.invoke_frame(call, self.subscribe_topics[0])
+                wf_copy.invoke_frame(call, self._return_topic)
                 publish_envelope = Envelope(
                     context=SessionRunContext(state=call.state, deps=envelope.context.deps),
                     internal_workflow_state=wf_copy,
@@ -184,7 +194,7 @@ class BaseNodeDef(BaseNodeSchema):
 
         elif isinstance(output, Call):
             # push to callstack and call the target topic
-            envelope.internal_workflow_state.invoke_frame(output, self.subscribe_topics[0])
+            envelope.internal_workflow_state.invoke_frame(output, self._return_topic)
             publish_envelope = Envelope(
                 context=SessionRunContext(state=output.state, deps=envelope.context.deps),
                 internal_workflow_state=envelope.internal_workflow_state,
@@ -287,4 +297,26 @@ class BaseNodeDef(BaseNodeSchema):
 
     @property
     def _return_topic(self) -> str:
+        """Framework-private return inbox for this node instance.
+
+        Used as the ``callback_topic`` written into the call frame when this
+        node issues a tool ``Call`` (so the tool's ``ReturnCall`` knows where
+        to route back), and as the ``target_topic`` for the framework's
+        built-in all-invalid ``TailCall`` self-retry in
+        :meth:`BaseAgentNodeDef.run`. Must be uniquely owned by this
+        ``node_id`` — sharing it with another node's consumer group would
+        re-introduce the co-tenant tool-return leak (issue #141).
+        :meth:`Worker.register_handlers` automatically subscribes the node to
+        this topic under the worker's configured ``group_id`` (defaults to
+        the node's own ``node_id``).
+
+        The value is recomputed from ``node_id`` on every access. Do not
+        mutate ``node_id`` after the node has been registered with a worker:
+        the worker's subscription is bound to the old topic, so tool
+        ``ReturnCall`` responses (which target the call frame's
+        ``callback_topic``) and built-in ``TailCall`` self-retries (which
+        target ``_return_topic`` directly) would silently route into a topic
+        with no consumer. Ordinary tool ``Call`` publishes are unaffected —
+        they target the tool's input topic, not ``_return_topic``.
+        """
         return f"{self.node_id}.private.return"

{calfkit-0.3.1 → calfkit-0.3.2}/calfkit/worker/worker.py

@@ -36,14 +36,24 @@ class Worker:
         else:
             for node in self._nodes:
                 group_id = self._group_id or node.name
+                # Subscribe to the node's public inboxes plus its
+                # framework-private return inbox. The latter is where tool
+                # ``Call`` returns and ``TailCall`` self-retries are addressed
+                # exclusively to this node instance — see
+                # ``BaseNodeDef._return_topic`` (issue #141). ``dict.fromkeys``
+                # preserves declared order while removing duplicates, so a
+                # user who manually lists ``f'{node_id}.private.return'`` in
+                # ``subscribe_topics`` doesn't end up with a duplicate entry
+                # in registration logs / AsyncAPI / observability tooling.
+                topics = list(dict.fromkeys([*node.subscribe_topics, node._return_topic]))
                 logger.info(
                     "registering node=%s subscribe=%s publish=%s",
                     node.name,
-                    node.subscribe_topics,
+                    topics,
                     node.publish_topic,
                 )
                 subscriber = self._client._connection.subscriber(
-                    *node.subscribe_topics,
+                    *topics,
                     group_id=group_id,
                     max_workers=self._max_workers,
                     **self._extra_subscribe_kwargs,