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

by_framework-0.2.2.dev14/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Fixed
+- A resumed agent can read its own request metadata again. Previously,
+  `command.header.metadata` after a suspend (`ask_user`, or a `call_agent`
+  hop) held only the metadata of the message that woke the agent up, and
+  everything it had originally been dispatched with was gone. It is now the
+  original dispatch metadata with the waking message's merged on top (the
+  waking message wins on key collisions). Handlers that treated the resumed
+  header's metadata as "only what this hop just sent" will now see additional
+  keys. Per-hop trace fields (`trace_parent_span_id`,
+  `framework_parent_span_id`, `langfuse_parent_observation_id`) still
+  describe the current hop and are not restored from the record. Executions
+  recorded before this change are unaffected — they degrade to the previous
+  behaviour rather than erroring.
+
+### Added
+- Standardized Open Source governance files (CONTRIBUTING, CODE_OF_CONDUCT, SECURITY).
+- GitHub Issue and Pull Request templates.
+- Dependabot configuration for dependency monitoring.
+
+## [0.2.0] - 2026-05-13
+### Initial release

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

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

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

@@ -260,7 +260,13 @@ Entry anatomy:
   implementations fall back to minting a fresh execution_id. Root-dispatch
   trace writes (`_write_trace_root_start/_end`) must only fire when
   `not parent_message_id` — firing them on every `call_agent` hop would
-  duplicate trace roots.
+  duplicate trace roots. `initialize_execution()`'s payload carries the
+  dispatch `metadata`: a root agent suspends (an `ask_user` round is the
+  common case) and comes back on a `ResumeCommand` carrying the *callee's*
+  metadata, so the record is the only place its own request metadata still
+  exists for `worker.py`'s inbound restore to find. `runner.py` records the
+  same field independently on first pickup, which is what makes this work
+  for dispatchers that don't write it (TS/Java callers, a bare `xadd`).
 
 - `src/by_framework/worker/runner.py` — `WorkerRunner`, the consume loop:
   `XREADGROUP` fetch, command dispatch, resume/suspend bookkeeping, denylist
@@ -290,7 +296,16 @@ Entry anatomy:
   suspended caller persists as `WAITING_AGENT`/`WAITING_USER` precisely to
   keep that inference true; reusing QUEUED for any post-pickup state silently
   makes a resume re-derive its identity from the message header instead of
-  the record. Every `ResumeCommand` passes the `core/wait_gate.py`
+  the record. On a **non-resume** pickup it also writes `header.metadata`
+  onto the record (as an `update_execution_status` kwarg, or in the
+  `save_execution` fallback payload): `header.metadata` *is* the dispatch
+  metadata by definition, so recording it here — rather than trusting
+  whoever sent the message to have done it — is what makes
+  `worker.py`'s inbound restore work for a client root dispatch and for a
+  TS/Java caller, neither of which writes the field. The `ResumeCommand`
+  guard is load-bearing: a resume writing its own waking metadata over the
+  record would destroy the stored original that the restore exists to
+  recover, and nothing else keeps a copy. Every `ResumeCommand` passes the `core/wait_gate.py`
   idempotency gate *here*, before the execution lookup — and being upstream
   of `GatewayWorker` is what also puts it before Task Group join, whose
   `HINCRBY completed` a duplicate would push past `total` and aggregate a
@@ -353,6 +368,22 @@ Entry anatomy:
   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.
+  That is the OUTBOUND direction. The INBOUND one — what this execution's own
+  handler reads — is `_restore_inbound_metadata()`, and it is deliberately a
+  different rule: the original dispatch metadata from the same snapshot is
+  the base and the waking message's metadata is **merged on top** (waking
+  message wins collisions), because this agent *is* the addressee of that
+  message. Without it, everything a handler was dispatched with disappears
+  the moment it first suspends. Two constraints keep the directions from
+  contaminating each other: the restore must build a NEW command
+  (`prepare_command_for_processing()` returns the *same* object for the base
+  worker, so an in-place header mutation would rewrite `raw_command`'s and
+  leak the merge into the reply), and `_resolve_reply_command()` must keep
+  taking `raw_command`. The shared merge rule, including which framework
+  trace keys are excluded from the restored base, lives in
+  `_resume_metadata.py` — one copy, because the last time these two files
+  each carried their own version of a resume rule the processor was left
+  behind for a whole commit.
   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
@@ -431,8 +462,22 @@ Entry anatomy:
   to no execution. `_resolve_reply_header()` must read a resumed execution's
   caller from the execution record, not from the resume header (which names
   the sub-agent), while excluding `CLIENT_SOURCE_AGENT_TYPE` for the reason
-  spelled out under `worker.py`; and no callback may be sent while
-  `context._is_suspended` (with the same terminal-status exception).
+  spelled out under `worker.py`; it restores **four** fields from that record
+  — `source_agent_type`, `parent_message_id`, `task_group_id` and
+  `metadata` — the last one as a full replacement, never merged with the
+  waking message's own metadata, exactly as `worker.py`'s
+  `_resolve_reply_command()` does (restoring only the three routing fields is
+  the drift this entry warns about: it shipped that way and leaked the waking
+  hop's metadata to the caller); `_restore_inbound_metadata()` mirrors
+  `worker.py`'s inbound merge for what the *handler* reads, and must run even
+  when `_resolve_reply_header()` returned `None` — a client-dispatched root
+  is owed no reply but still has its own metadata to get back, so the two
+  must not share a short-circuit. `_load_execution_snapshot()` is the single
+  registry read feeding both directions; being fail-soft there is what keeps
+  a registry error a degrade rather than a lost reply. The reply is built
+  from `raw_command`, never the inbound-restored one. And no callback may be
+  sent while `context._is_suspended` (with the same terminal-status
+  exception).
   Being a *second* entry point for replies, it carries the same
   `core/wait_gate.py` gate as `runner.py` — a gate on one of two doors is not
   a gate, and an ungated reply here would both wake a resolved caller and
@@ -441,6 +486,25 @@ Entry anatomy:
   `call_agents`' queued stand-ins on the same terms as `worker.py` — after
   the handler returns, never when it raised.
 
+- `src/by_framework/worker/_resume_metadata.py` — the one copy of the
+  **inbound** resume-metadata rule, shared by `worker.py` and `processor.py`
+  so the two cannot drift again. `merge_resume_metadata()` puts the
+  execution's original dispatch metadata underneath the waking message's
+  (waking message wins collisions) — the opposite of the outbound
+  replacement, because a resumed handler *is* the addressee of the message
+  that woke it. `FRAMEWORK_HOP_METADATA_KEYS` (`trace_parent_span_id`,
+  `framework_parent_span_id`, `langfuse_parent_observation_id`) are dropped
+  from the restored base: the framework injects them per dispatch, so a
+  stored copy describes the hop that *created* the execution, and
+  `context.py`'s `_resolve_call_langfuse_parent_id()` reads that key straight
+  off the current command — restoring it would parent a post-resume call to
+  an observation from before the suspend. The filter belongs here, at read
+  time, and not at write time: the outbound path deliberately restores the
+  stored dict verbatim, trace keys included, to stay identical to the
+  non-suspended reply. A missing/absent stored value degrades to the waking
+  message's metadata unchanged, which is the pre-restore behaviour, so old
+  records and cross-SDK callers need no migration or version gate.
+
 - `src/by_framework/core/registry.py` — `WorkerRegistry`: Redis-backed worker
   membership/heartbeat/execution-state, admin lifecycle, locking primitives.
   `mark_execution_finished()` must stamp `finished_at` only

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

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

{by_framework-0.2.2.dev13 → by_framework-0.2.2.dev14}/src/by_framework/client/client.py

@@ -971,6 +971,12 @@ class GatewayClient:
                         "parent_message_id": params["parent_message_id"] or "",
                         "source_agent_type": CLIENT_SOURCE_AGENT_TYPE,
                         "target_agent_type": params["target_agent_type"],
+                        # What this execution was dispatched with, so a worker
+                        # can restore it after the execution suspends and
+                        # resumes (see worker/_resume_metadata.py). Only the
+                        # non-RESUME branch reaches here, so this never
+                        # overwrites a suspended execution's original.
+                        "metadata": dict(metadata or {}),
                         "stream_name": route.stream_name,
                         "status": "QUEUED",
                         "route_policy": route_policy,

by_framework-0.2.2.dev14/src/by_framework/worker/_resume_metadata.py

@@ -0,0 +1,65 @@
+"""The inbound half of a resumed execution's metadata.
+
+Two different directions restore metadata on a resume, and they are NOT the
+same rule. Keep them apart:
+
+- **Outbound** (``GatewayWorker._resolve_reply_command`` /
+  ``GatewayProcessor._resolve_reply_header``): the header a resumed execution
+  *sends* to its caller. The stored dispatch metadata **replaces**
+  ``header.metadata`` wholesale — the waking hop's data is plumbing the
+  original caller never asked for, and ``_enqueue_agent_return``'s
+  ``{**header.metadata, **task_result.metadata}`` is the one sanctioned
+  channel for a handler to forward part of it.
+- **Inbound** (this module): the header a resumed execution's own handler
+  *reads*. Here the waking message's metadata is legitimate payload — an
+  ``ask_user`` answer's metadata was sent BY a client TO this agent — so it is
+  merged on top of the original dispatch metadata rather than discarded.
+
+Without this, everything a handler was originally dispatched with disappears
+the first time it suspends: it comes back seeing only whatever woke it up.
+"""
+
+from typing import Any, Mapping, Optional
+
+# Injected per dispatch by AgentContext._dispatch_single_task, not supplied by
+# business code. A stored copy of them is stale by definition — it describes
+# the hop that dispatched the execution, not the hop resuming it now — so they
+# are dropped from the restored base and always come from the current message.
+# Letting them through would surface a dispatch-time span id where the waking
+# message has none, and AgentContext._resolve_call_langfuse_parent_id() reads
+# exactly that as its last-resort fallback: a call made after a resume would
+# parent to the original dispatch's observation.
+FRAMEWORK_HOP_METADATA_KEYS = frozenset(
+    {
+        "trace_parent_span_id",
+        "framework_parent_span_id",
+        "langfuse_parent_observation_id",
+    }
+)
+
+
+def merge_resume_metadata(
+    stored: Optional[Mapping[str, Any]],
+    incoming: Optional[Mapping[str, Any]],
+) -> dict[str, Any]:
+    """Merge an execution's original dispatch metadata under this hop's.
+
+    ``stored`` is the ``metadata`` field of the execution record (what the
+    execution was originally dispatched with); ``incoming`` is the waking
+    message's own metadata. The waking message wins on key collisions: it is
+    the newer, more specific hop, and this keeps the property that every key a
+    handler can read today stays readable — the restore only ever adds keys.
+
+    A ``stored`` that is missing (an execution recorded before this field
+    existed, or one dispatched by an SDK that doesn't write it) degrades to
+    ``incoming`` unchanged, i.e. exactly the pre-restore behaviour.
+
+    Neither argument is mutated.
+    """
+    merged = {
+        key: value
+        for key, value in (stored or {}).items()
+        if key not in FRAMEWORK_HOP_METADATA_KEYS
+    }
+    merged.update(incoming or {})
+    return merged

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

@@ -24,6 +24,7 @@ from by_framework.core.protocol.results import (
 from by_framework.core.runtime.file_permissions import FilePermissionPolicy
 from by_framework.core.wait_gate import consume_wait_entry, emit_orphaned_reply
 from by_framework.core.wait_reply import flush_pending_group_replies
+from by_framework.worker._resume_metadata import merge_resume_metadata
 from by_framework.worker.context import AgentContext
 
 ContextHandler = Callable[
@@ -99,8 +100,18 @@ class GatewayProcessor:
                 )
                 return None
 
-        reply_header = await self._resolve_reply_header(command)
+        # One lookup feeds both directions: the header this execution replies
+        # with, and the header its own handler reads. They are different
+        # rules over the same record — see _resolve_reply_header and
+        # _restore_inbound_metadata.
+        snapshot = (
+            await self._load_execution_snapshot(command) if is_agent_return else None
+        )
+        raw_command = command
+        reply_header = self._resolve_reply_header(command, snapshot)
         has_source_agent = reply_header is not None
+        command = self._restore_inbound_metadata(command, is_agent_return, snapshot)
+        header = command.header
 
         context = AgentContext(
             session_id=header.session_id,
@@ -163,8 +174,10 @@ class GatewayProcessor:
                 getattr(context, "_is_suspended", False)
             ) and not is_terminal_state(task_result.status)
             if has_source_agent and not is_suspended:
+                # raw_command, not the inbound-restored one: the reply is the
+                # outbound direction and must not inherit the inbound merge.
                 await self._enqueue_callback(
-                    command,
+                    raw_command,
                     task_result.status,
                     task_result.reply_data,
                     content=task_result.content,
@@ -210,7 +223,7 @@ class GatewayProcessor:
 
             if has_source_agent:
                 await self._enqueue_callback(
-                    command,
+                    raw_command,
                     AgentState.FAILED.value,
                     {"error": str(e)},
                     reply_header=reply_header,
@@ -221,47 +234,101 @@ class GatewayProcessor:
             )
             raise
 
-    async def _resolve_reply_header(
+    async def _load_execution_snapshot(
         self, command: GatewayCommand
-    ) -> Optional[MessageHeader]:
-        """Return the header describing the caller this execution owes a reply
-        to, or None when nobody is waiting.
+    ) -> Optional[dict[str, Any]]:
+        """Read the execution record the original dispatch wrote.
 
-        Mirrors ``GatewayWorker._resolve_reply_command``: a resume's header
-        describes the sub-agent that just finished, so the caller has to be
-        read back from the execution record the original dispatch wrote — and,
-        for the same reason as there, ``CLIENT_SOURCE_AGENT_TYPE`` is not a
-        caller. It is what a client writes on a root execution's record, and
-        nothing consumes its control stream.
+        Fetched once per resume and shared by both restore directions.
+        Fail-soft: a registry error degrades to "no record", which each caller
+        then handles as its own no-op.
         """
         header = command.header
-        if not isinstance(command, ResumeCommand):
-            return header if header.source_agent_type else None
-
-        execution: Optional[dict[str, Any]] = None
         try:
             from by_framework.core.registry import WorkerRegistry
 
-            execution = await WorkerRegistry(self.redis).get_execution_by_message_id(
+            return await WorkerRegistry(self.redis).get_execution_by_message_id(
                 header.message_id, session_id=header.session_id
             )
         except Exception as error:  # pylint: disable=broad-exception-caught
             self.logger.warning(
-                "[%s] Could not resolve the caller of resumed execution %s: %s",
+                "[%s] Could not load the execution record of resumed execution "
+                "%s: %s",
                 self.worker_id,
                 header.message_id,
                 error,
             )
             return None
 
-        caller_agent_type = str((execution or {}).get("source_agent_type", "") or "")
+    def _resolve_reply_header(
+        self,
+        command: GatewayCommand,
+        snapshot: Optional[dict[str, Any]],
+    ) -> Optional[MessageHeader]:
+        """Return the header describing the caller this execution owes a reply
+        to, or None when nobody is waiting.
+
+        Mirrors ``GatewayWorker._resolve_reply_command``: a resume's header
+        describes the sub-agent that just finished, so the caller has to be
+        read back from the execution record the original dispatch wrote — and,
+        for the same reason as there, ``CLIENT_SOURCE_AGENT_TYPE`` is not a
+        caller. It is what a client writes on a root execution's record, and
+        nothing consumes its control stream.
+
+        Four fields come from that snapshot, not from the waking message:
+        ``source_agent_type``, ``parent_message_id``, ``task_group_id`` and
+        ``metadata``. The last one is restored as a full replacement rather
+        than a merge, exactly as ``GatewayWorker._resolve_reply_command``
+        does it: the waking message (an ``ask_user`` answer, or a sub-call's
+        reply) is transient plumbing for that one hop, not something the
+        caller ever sent. A snapshot missing the field (an execution recorded
+        before it existed) degrades to an empty dict rather than leaking the
+        waking message's metadata to the caller.
+
+        This is the OUTBOUND direction only. What the handler itself reads is
+        ``_restore_inbound_metadata``, which merges rather than replaces —
+        and which must run even when this returns None, since a
+        client-dispatched root has no caller but still has its own metadata
+        to get back.
+        """
+        header = command.header
+        if not isinstance(command, ResumeCommand):
+            return header if header.source_agent_type else None
+
+        caller_agent_type = str((snapshot or {}).get("source_agent_type", "") or "")
         if not caller_agent_type or caller_agent_type == CLIENT_SOURCE_AGENT_TYPE:
             return None
         return replace(
             header,
             source_agent_type=caller_agent_type,
-            parent_message_id=str((execution or {}).get("parent_message_id", "") or ""),
-            task_group_id=str((execution or {}).get("task_group_id", "") or ""),
+            parent_message_id=str((snapshot or {}).get("parent_message_id", "") or ""),
+            task_group_id=str((snapshot or {}).get("task_group_id", "") or ""),
+            metadata=dict((snapshot or {}).get("metadata") or {}),
+        )
+
+    @staticmethod
+    def _restore_inbound_metadata(
+        command: GatewayCommand,
+        is_agent_return: bool,
+        snapshot: Optional[dict[str, Any]],
+    ) -> GatewayCommand:
+        """Give a resumed handler its own dispatch metadata back.
+
+        Mirrors ``GatewayWorker._restore_inbound_metadata``, including its
+        merge-don't-replace rule and its no-mutation rule; see that docstring
+        for why the inbound direction differs from the outbound one.
+        """
+        if not is_agent_return:
+            return command
+        return replace(
+            command,
+            header=replace(
+                command.header,
+                metadata=merge_resume_metadata(
+                    (snapshot or {}).get("metadata"),
+                    command.header.metadata,
+                ),
+            ),
         )
 
     async def _enqueue_callback(

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

@@ -625,11 +625,33 @@ class WorkerRunner:
             if registry:
                 if existing_execution:
                     if hasattr(registry, "update_execution_status"):
+                        status_fields: dict[str, Any] = {
+                            "worker_id": self.worker.worker_id
+                        }
+                        if not isinstance(command, ResumeCommand):
+                            # The dispatch metadata, recorded by whoever is
+                            # executing the message rather than by whoever
+                            # sent it: header.metadata IS the dispatch
+                            # metadata by definition, so this is correct for
+                            # every dispatcher — including a client root
+                            # dispatch and a TS/Java caller, neither of which
+                            # writes the field (see context.py's
+                            # initialize_execution, which does, and is kept
+                            # because it is the only record that exists
+                            # before a callee is ever picked up).
+                            # _handle_message reads it back to restore what
+                            # this execution was originally asked for once it
+                            # resumes.
+                            #
+                            # A ResumeCommand must NOT write it: the waking
+                            # message's metadata would overwrite the very
+                            # original this exists to preserve.
+                            status_fields["metadata"] = dict(header.metadata)
                         await registry.update_execution_status(
                             execution_id,
                             header.session_id,
                             "RUNNING",
-                            worker_id=self.worker.worker_id,
+                            **status_fields,
                         )
                 elif hasattr(registry, "save_execution"):
                     await registry.save_execution(
@@ -641,6 +663,12 @@ class WorkerRunner:
                             "parent_message_id": header.parent_message_id or "",
                             "worker_id": self.worker.worker_id,
                             "target_agent_type": header.target_agent_type,
+                            # Same reason as the update branch above. This one
+                            # is the no-existing-record fallback, so there is
+                            # no stored original to protect and no ResumeCommand
+                            # guard to make: whatever woke this is all this
+                            # execution has ever been told.
+                            "metadata": dict(header.metadata),
                             "stream_name": stream_name,
                             "redis_message_id": msg_id,
                             "status": "RUNNING",

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

@@ -59,6 +59,7 @@ from by_framework.trace.span_recorder import TraceSpan, str_to_uint64
 from by_framework.worker.context import AgentContext, current_agent_context_var
 from by_framework.worker.heartbeat import WorkerHeartbeat
 
+from ._resume_metadata import merge_resume_metadata
 from .sandbox.hook_sandbox import active_workspace
 
 
@@ -377,6 +378,47 @@ class GatewayWorker(ABC):
             ),
         )
 
+    @staticmethod
+    def _restore_inbound_metadata(
+        command: GatewayCommand,
+        is_agent_return: bool,
+        execution: Optional["RunningExecution"],
+    ) -> GatewayCommand:
+        """Give a resumed handler its own dispatch metadata back.
+
+        The mirror image of ``_resolve_reply_command``, and deliberately not
+        the same rule. That one rebuilds the header this execution *sends*;
+        this one rebuilds the header it *reads*. A resumed handler otherwise
+        sees only the metadata of whatever woke it up — an ``ask_user``
+        answer's, or a sub-call's reply — and everything the execution was
+        originally dispatched with is gone from the moment it first suspends.
+
+        Merged, not replaced (the opposite of the outbound direction): this
+        agent IS the addressee of the waking message, so its metadata is real
+        payload here rather than someone else's plumbing. Original dispatch
+        metadata is the base, the waking message wins on collisions. See
+        ``_resume_metadata.py`` for why the framework's per-hop trace keys are
+        excluded from the base.
+
+        Returns a NEW command — never mutates. ``prepare_command_for_processing``
+        returns the *same* object for the base worker (only ``ByaiWorker``
+        rebuilds it), so mutating the header here would also rewrite
+        ``raw_command``'s and leak this merge into the reply that goes out.
+        """
+        if not is_agent_return:
+            return command
+        snapshot = getattr(execution, "existing_data", None) or {}
+        return replace(
+            command,
+            header=replace(
+                command.header,
+                metadata=merge_resume_metadata(
+                    snapshot.get("metadata"),
+                    command.header.metadata,
+                ),
+            ),
+        )
+
     @staticmethod
     def _apply_suspended_status(
         task_result: AgentTaskResult,
@@ -682,6 +724,7 @@ class GatewayWorker(ABC):
         is_agent_return = isinstance(raw_command, ResumeCommand)
         reply_command = self._resolve_reply_command(raw_command, execution)
         has_source_agent = reply_command is not None
+        command = self._restore_inbound_metadata(command, is_agent_return, execution)
 
         # Get workspace dir from workspace_manager if available
         # Note: We don't use hasattr check because it doesn't work well with mocks

{by_framework-0.2.2.dev13 → by_framework-0.2.2.dev14}/tests/client/test_client.py

@@ -1340,6 +1340,34 @@ async def test_client_send_message_ask_agent_does_not_query_registry_for_resume_
     mock_registry.initialize_execution.assert_awaited_once()
 
 
+@pytest.mark.asyncio
+async def test_client_root_dispatch_records_its_metadata_on_the_execution():
+    """A root execution's own dispatch metadata has to be on its record.
+
+    The agent will suspend (an `ask_user` round is the common case) and come
+    back on a ResumeCommand carrying the *callee's* metadata; the only way it
+    can still read what the client originally sent is for the client to have
+    recorded it here.
+    """
+    mock_redis = AsyncMock()
+    mock_registry = AsyncMock()
+
+    client = GatewayClient(redis_client=mock_redis, registry=mock_registry)
+    await client.send_message(
+        target_agent_type="langgraph_agent",
+        session_id="s1",
+        content="hello",
+        action_type="ASK_AGENT",
+        message_id="msg-new",
+        target_worker_id="worker-42",
+        metadata={"tenant": "acme", "req": "r-1"},
+    )
+
+    initialized = mock_registry.initialize_execution.await_args.args[0]
+    assert initialized["metadata"]["tenant"] == "acme"
+    assert initialized["metadata"]["req"] == "r-1"
+
+
 @pytest.mark.asyncio
 async def test_client_send_message_resume_falls_back_when_registry_lacks_lookup():
     """A registry double/implementation without get_execution_by_message_id
@@ -1349,6 +1377,7 @@ async def test_client_send_message_resume_falls_back_when_registry_lacks_lookup(
     mock_redis = AsyncMock()
 
     class RegistryWithoutLookup:
+
         async def initialize_execution(self, execution):
             return None