by-framework 0.2.2.dev12__tar.gz → 0.2.2.dev13__tar.gz

{by_framework-0.2.2.dev12 → by_framework-0.2.2.dev13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: by-framework
-Version: 0.2.2.dev12
+Version: 0.2.2.dev13
 Summary: 分布式 Agent 调度框架
 License-File: LICENSE
 Requires-Python: >=3.12

{by_framework-0.2.2.dev12 → by_framework-0.2.2.dev13}/docs/architecture/KEY_FILES.md

@@ -194,9 +194,14 @@ Entry anatomy:
   and *no* reply — registration happens before the dispatch `xadd`, so a
   failed `xadd` leaves exactly that. Synthesized failures must stay shaped
   like a sub-agent's own failure (`error`/`error_code` in `reply_data`,
-  same stream, same header id reversal). Two switches, and they must stay
-  separate: *compensation* (the triage, replies, renewals, cancellation) is
-  off unless `BY_FRAMEWORK_WAIT_SWEEPER_ENABLED` is set and is the rollback
+  same stream, same header id reversal). `_synthesize_failure()` seeds its
+  reply's metadata from `child.get("metadata")` — the callee's execution
+  snapshot, where `context.py`'s `initialize_execution()` persists the
+  caller's original dispatch metadata — instead of an empty dict, so a
+  caller that never gets a real reply at all still gets its own metadata
+  back, consistent with every other reply shape to it. Two switches, and
+  they must stay separate: *compensation* (the triage, replies, renewals,
+  cancellation) is off unless `BY_FRAMEWORK_WAIT_SWEEPER_ENABLED` is set and is the rollback
   switch for the whole liveness feature, while *pruning* is on by default
   (`BY_FRAMEWORK_WAIT_PRUNE_ENABLED`) because nothing else ever removes a
   wait-index entry — with compensation off, every call whose reply never
@@ -340,6 +345,14 @@ Entry anatomy:
   `ask_user` round is the common one) posts its result to a control stream
   nobody consumes and, worse, stops emitting the end-of-stream event the user
   is waiting on, because it now believes it owes an agent a reply.
+  `_resolve_reply_command()` restores `header.metadata` from the same
+  execution snapshot (`existing_data["metadata"]`) as a full *replacement*,
+  never merged with the resuming command's own metadata: that metadata
+  belongs to whatever woke this execution up (an `ask_user` answer, or a
+  sub-call's reply), not to the original caller, and leaking it would let a
+  transient hop overwrite the caller's own data instead of being layered
+  under `task_result.metadata` like `_enqueue_agent_return()`'s merge
+  already does correctly.
   The success path must NOT reply while `context._is_suspended` — a suspended
   execution has no result, and forwarding the value the handler returned in
   order to unwind both wakes the caller early and consumes the single reply it
@@ -397,7 +410,12 @@ Entry anatomy:
   so: it is bookkeeping, not the dispatch.
   `initialize_execution()`'s payload carries `source_agent_type` and
   `task_group_id` because they are the only durable record of who a
-  suspended callee owes its reply to (see `worker.py`).
+  suspended callee owes its reply to (see `worker.py`). It also carries
+  `metadata` (a copy of the dispatched `command.header.metadata`) for the
+  same reason: it is the only durable record of what the caller's metadata
+  *was*, and `worker.py`'s `_resolve_reply_command()` reads it back
+  verbatim so a caller's metadata survives however many times the callee
+  suspends and resumes before it finally replies.
   `_suspended_state` records *which* state the execution is waiting in and is
   what the framework persists; keep it set/rolled-back in lockstep with
   `_is_suspended`.

{by_framework-0.2.2.dev12 → by_framework-0.2.2.dev13}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "by-framework"
-version = "0.2.2.dev12"
+version = "0.2.2.dev13"
 description = "分布式 Agent 调度框架"
 readme = "README.md"
 requires-python = ">=3.12"

{by_framework-0.2.2.dev12 → by_framework-0.2.2.dev13}/src/by_framework/core/wait_sweeper.py

@@ -999,7 +999,7 @@ class WaitIndexSweeper:
             ),
             extra_payload={},
             error_code=error_code,
-            metadata={},
+            metadata=dict(child.get("metadata") or {}),
         )
         return outcome if emitted else OUTCOME_UNROUTABLE
 

{by_framework-0.2.2.dev12 → by_framework-0.2.2.dev13}/src/by_framework/worker/context.py

@@ -875,6 +875,11 @@ class AgentContext:
                         # the reply belongs to — the resume message itself
                         # describes the hop that woke it, not this dispatch.
                         "task_group_id": task_group_id,
+                        # A's original dispatch metadata, so a resumed reply
+                        # can restore it as the base layer instead of
+                        # inheriting whatever message last woke this
+                        # execution up (see _resolve_reply_command).
+                        "metadata": dict(command.header.metadata),
                         "stream_name": delivery_stream,
                         "status": "QUEUED",
                         "route_policy": route_policy,

{by_framework-0.2.2.dev12 → by_framework-0.2.2.dev13}/src/by_framework/worker/worker.py

@@ -343,6 +343,14 @@ class GatewayWorker(ABC):
         Treating "is a resume" as "has no caller" is what used to make an
         A -> B -> C chain silently drop B's result on the floor.
 
+        ``header.metadata`` is restored the same way, as a full replacement
+        rather than a merge with the waking message's own metadata: the
+        waking message (an ``ask_user`` answer, or a sub-call's reply) is
+        transient plumbing for that hop, not something A ever sent or asked
+        for. If A's original metadata is missing from the snapshot (an
+        execution recorded before this field existed), this degrades to an
+        empty dict rather than leaking the waking message's metadata to A.
+
         A root execution's record names ``CLIENT_SOURCE_AGENT_TYPE`` as its
         source, which is a marker rather than an agent type — it has to be
         excluded explicitly, or every client-dispatched execution that ever
@@ -365,6 +373,7 @@ class GatewayWorker(ABC):
                 source_agent_type=caller_agent_type,
                 parent_message_id=str(snapshot.get("parent_message_id", "") or ""),
                 task_group_id=str(snapshot.get("task_group_id", "") or ""),
+                metadata=dict(snapshot.get("metadata") or {}),
             ),
         )
 

{by_framework-0.2.2.dev12 → by_framework-0.2.2.dev13}/tests/core/test_wait_sweeper.py

@@ -456,6 +456,10 @@ class TestOddEntries(unittest.IsolatedAsyncioTestCase):
             target_agent_type="agent-b",
             status=AgentState.COMPLETED.value,
             worker_id="worker-b",
+            # A's original dispatch metadata, persisted at
+            # initialize_execution() time: the synthesized failure must
+            # restore it instead of emitting an empty dict.
+            metadata={"caller": "original", "request_id": "req-1"},
         )
         _due_member(
             self.redis,
@@ -475,6 +479,13 @@ class TestOddEntries(unittest.IsolatedAsyncioTestCase):
             reply["body"]["reply_data"]["error_code"],
             LivenessErrorCode.REPLY_LOST_RECOVERED,
         )
+        # A's original metadata rides along the synthesized failure, same as
+        # every other reply shape to A — not discarded as `{}`.
+        reply_metadata = reply["header"]["metadata"]
+        self.assertEqual(reply_metadata["caller"], "original")
+        self.assertEqual(reply_metadata["request_id"], "req-1")
+        # The sweeper's own provenance keys still ride on top.
+        self.assertEqual(reply_metadata["synthesized_by"], "wait_sweeper")
 
     async def test_dead_worker_reply_mirrors_a_real_agent_return(self):
         self._add_suspended_caller()

{by_framework-0.2.2.dev12 → by_framework-0.2.2.dev13}/tests/integration/test_nested_chain.py

@@ -219,10 +219,13 @@ class WorkspaceManagerStub:
 class ChainAgent(GatewayWorker):
     """Calls `next_agent_type` on first contact, answers on resume."""
 
-    def __init__(self, agent_type, next_agent_type, *args, **kwargs):
+    def __init__(
+        self, agent_type, next_agent_type, *args, dispatch_metadata=None, **kwargs
+    ):
         super().__init__(*args, **kwargs)
         self.agent_type = agent_type
         self.next_agent_type = next_agent_type
+        self.dispatch_metadata = dispatch_metadata
         self.dispatch_calls = 0
         self.resume_payloads: list[Any] = []
 
@@ -235,12 +238,20 @@ class ChainAgent(GatewayWorker):
             return {
                 "status": AgentState.COMPLETED.value,
                 "reply_data": {"from": self.agent_type, "sub": command.reply_data},
+                # Own metadata this link contributes: must override
+                # same-named keys from whatever it was dispatched with, while
+                # leaving other inherited keys untouched.
+                "metadata": {
+                    "agent": self.agent_type,
+                    "tag": f"from-{self.agent_type}",
+                },
             }
         self.dispatch_calls += 1
         await context.call_agent(
             target_agent_type=self.next_agent_type,
             content="delegate",
             wait_for_reply=True,
+            metadata=self.dispatch_metadata,
         )
         return {"status": AgentState.QUEUED.value}
 
@@ -261,6 +272,9 @@ class AskingMiddleAgent(GatewayWorker):
             return {
                 "status": AgentState.COMPLETED.value,
                 "reply_data": {"from": "agent-b", "user_said": command.content},
+                # Own metadata this link contributes: must override
+                # same-named keys from A's original dispatch metadata.
+                "metadata": {"agent": "agent-b", "tag": "from-agent-b"},
             }
         return await context.ask_user("which colour?")
 
@@ -318,7 +332,17 @@ class TestNestedChain(unittest.IsolatedAsyncioTestCase):
         workspace = WorkspaceManagerStub()
 
         self.agent_a = ChainAgent(
-            "agent-a", "agent-b", "worker-a", self.redis, self.registry, workspace
+            "agent-a",
+            "agent-b",
+            "worker-a",
+            self.redis,
+            self.registry,
+            workspace,
+            # A's own dispatch metadata to B: the "A's original metadata"
+            # this task is about. Must reach A's own reply intact even
+            # though B suspends (via a nested call_agent to C) before B
+            # finally replies.
+            dispatch_metadata={"caller": "agent-a", "tag": "keep"},
         )
         self.agent_b = ChainAgent(
             "agent-b", "agent-c", "worker-b", self.redis, self.registry, workspace
@@ -373,6 +397,12 @@ class TestNestedChain(unittest.IsolatedAsyncioTestCase):
         # Addressed to A's suspended execution, and identifying B's sub-task.
         self.assertEqual(reply.header.message_id, "msg-root")
         self.assertEqual(reply.header.source_agent_type, "agent-b")
+        # A's own dispatch metadata to B survives B suspending on a nested
+        # call_agent to C, and B's own returned metadata overrides same-named
+        # keys instead of being discarded or replacing the whole dict.
+        self.assertEqual(reply.header.metadata["caller"], "agent-a")
+        self.assertEqual(reply.header.metadata["tag"], "from-agent-b")
+        self.assertEqual(reply.header.metadata["agent"], "agent-b")
 
         await self._step("agent-a")  # A resumes with B's answer
 
@@ -437,7 +467,15 @@ class TestSubAgentAsksTheUser(unittest.IsolatedAsyncioTestCase):
         workspace = WorkspaceManagerStub()
 
         self.agent_a = ChainAgent(
-            "agent-a", "agent-b", "worker-a", self.redis, self.registry, workspace
+            "agent-a",
+            "agent-b",
+            "worker-a",
+            self.redis,
+            self.registry,
+            workspace,
+            # A's own dispatch metadata to B: must reach A's reply intact
+            # even though B suspends on ask_user before it replies.
+            dispatch_metadata={"caller": "agent-a", "tag": "keep"},
         )
         self.agent_b = AskingMiddleAgent(
             "worker-b", self.redis, self.registry, workspace
@@ -472,7 +510,7 @@ class TestSubAgentAsksTheUser(unittest.IsolatedAsyncioTestCase):
         await runner._run_once()
         await runner.wait_for_tasks()
 
-    async def _answer_the_user_prompt(self, message_id, answer="Pink"):
+    async def _answer_the_user_prompt(self, message_id, answer="Pink", metadata=None):
         """What a client sends when the person replies.
 
         `GatewayClient.send_message(action_type=RESUME)` reuses the suspended
@@ -487,6 +525,7 @@ class TestSubAgentAsksTheUser(unittest.IsolatedAsyncioTestCase):
                     session_id=self.session_id,
                     trace_id="trace-ask",
                     target_agent_type="agent-b",
+                    metadata=metadata or {},
                 ),
                 content=answer,
             ).to_redis_payload(),
@@ -512,7 +551,12 @@ class TestSubAgentAsksTheUser(unittest.IsolatedAsyncioTestCase):
         await self._step("agent-b")
         b_dispatch = _dispatched_message_id(self.redis, "agent-b")
 
-        await self._answer_the_user_prompt(b_dispatch)
+        await self._answer_the_user_prompt(
+            b_dispatch,
+            # The answering client's own metadata for this hop: transient
+            # plumbing that must not leak through to A.
+            metadata={"caller": "should-not-leak", "client_tag": "should-not-leak"},
+        )
         await self._step("agent-b")
 
         self.assertEqual(self.agent_b.user_answers, ["Pink"])
@@ -522,6 +566,14 @@ class TestSubAgentAsksTheUser(unittest.IsolatedAsyncioTestCase):
         # record its own dispatch wrote, which is the whole point.
         self.assertEqual(replies_to_a[0].header.message_id, "msg-root")
         self.assertEqual(replies_to_a[0].header.source_agent_type, "agent-b")
+        # A's own dispatch metadata to B survives the ask_user round-trip —
+        # it is NOT replaced by the answering client's own resume metadata —
+        # and B's own returned metadata overrides same-named keys.
+        reply_metadata = replies_to_a[0].header.metadata
+        self.assertEqual(reply_metadata["caller"], "agent-a")
+        self.assertEqual(reply_metadata["tag"], "from-agent-b")
+        self.assertEqual(reply_metadata["agent"], "agent-b")
+        self.assertNotIn("client_tag", reply_metadata)
 
         await self._step("agent-a")
 

{by_framework-0.2.2.dev12 → by_framework-0.2.2.dev13}/tests/worker/test_context.py

@@ -1508,3 +1508,34 @@ async def test_dispatch_records_task_group_id_on_the_execution():
     payload = init_execution.await_args.args[0]
     assert payload["task_group_id"] == group["task_group_id"]
     assert payload["source_agent_type"] == "agent-a"
+
+
+@pytest.mark.asyncio
+async def test_dispatch_records_caller_metadata_on_the_execution():
+    """A resumed sub-task rebuilds its reply header's metadata from this
+    snapshot, not from whatever message wakes it — so the caller's original
+    metadata has to be persisted here, same as the routing fields above."""
+    from unittest.mock import patch
+
+    mock_redis = _online_redis()
+    ctx = AgentContext(
+        session_id="s1",
+        trace_id="t1",
+        redis_client=mock_redis,
+        current_agent_id="agent-a",
+        message_id="parent-msg",
+    )
+
+    with patch(
+        "by_framework.core.registry.WorkerRegistry.initialize_execution",
+        new_callable=AsyncMock,
+    ) as init_execution:
+        await ctx.call_agent(
+            target_agent_type="agent-b",
+            content="one",
+            metadata={"caller": "agent-a", "request_id": "req-1"},
+        )
+
+    payload = init_execution.await_args.args[0]
+    assert payload["metadata"]["caller"] == "agent-a"
+    assert payload["metadata"]["request_id"] == "req-1"

{by_framework-0.2.2.dev12 → by_framework-0.2.2.dev13}/tests/worker/test_gateway_worker.py

@@ -1017,6 +1017,10 @@ async def test_resumed_execution_replies_to_its_own_caller_not_the_sub_agent(tmp
             target_agent_type="structured_agent",
             parent_message_id="msg-c",  # B's sub-task
             task_group_id="tg-of-c",  # B's OWN group, not the one B belongs to
+            # C's own metadata for this hop: transient plumbing that must not
+            # leak through to A — A's original metadata below is the base
+            # instead.
+            metadata={"caller": "should-not-leak", "from_c": "should-not-leak"},
         ),
         status=AgentState.COMPLETED.value,
         reply_data={"from": "c"},
@@ -1038,6 +1042,9 @@ async def test_resumed_execution_replies_to_its_own_caller_not_the_sub_agent(tmp
             "source_agent_type": "agent-a",
             "parent_message_id": "msg-a",
             "task_group_id": "tg-of-a",
+            # A's original dispatch metadata, persisted at
+            # initialize_execution() time.
+            "metadata": {"caller": "original", "request_id": "req-1"},
             **snapshot_fields,
         },
     )
@@ -1055,6 +1062,13 @@ async def test_resumed_execution_replies_to_its_own_caller_not_the_sub_agent(tmp
     assert reply.header.task_group_id == "tg-of-a"
     assert reply.header.source_agent_type == "structured_agent"
     assert reply.reply_data == {"answer": 42}
+    # A's original metadata is the base, B's own task_result.metadata
+    # (StructuredResultWorker returns {"tokens": 123, "caller": "overridden"})
+    # overrides same-named keys; C's waking metadata does not leak through.
+    assert reply.header.metadata["caller"] == "overridden"
+    assert reply.header.metadata["request_id"] == "req-1"
+    assert reply.header.metadata["tokens"] == 123
+    assert "from_c" not in reply.header.metadata
 
 
 @pytest.mark.asyncio

{by_framework-0.2.2.dev12 → by_framework-0.2.2.dev13}/uv.lock

@@ -315,7 +315,7 @@ wheels = [
 
 [[package]]
 name = "by-framework"
-version = "0.2.2.dev12"
+version = "0.2.2.dev13"
 source = { editable = "." }
 dependencies = [
     { name = "dill" },