test: assert the contract arun can actually keep, not the mis-bind

test_extra_positional_args_reach_run came in with kyegomez#1871 and asserts that
arun(task, img, "EXTRA") forwards "EXTRA" positionally to run(). That is
the behaviour this PR removes, so the test locked the defect in.

It only ever passed because its stub is declared
`fake_run(*args, **kwargs)`, which accepts anything positionally and so
cannot observe where the argument actually lands. Against the real
signature it lands on `imgs`:

    >>> inspect.signature(Agent.run).bind_partial(None, "T", "I", "EXTRA")
    {'task': 'T', 'img': 'I', 'imgs': 'EXTRA'}

`imgs` is a List[str] of image paths, not run()'s own *args.

Replaced with two tests that use a stub with the real parameter names,
so a mis-bind is visible:

  - task/img/kwargs reach run() as themselves
  - a third positional raises TypeError at the arun boundary instead of
    being silently bound to imgs

The second fails on master's agent.py and passes here, which is the
whole point of the change.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: ayaangazali

conversation_conversation-test.json

@@ -0,0 +1,6 @@
+[
+    {
+        "role": "user",
+        "content": "Hello"
+    }
+]

swarms/structs/conversation.py

@@ -453,13 +453,15 @@ def add_in_memory(
         role: str,
         content: Union[str, dict, list, Any],
         category: Optional[str] = None,
+        metadata: Optional[dict] = None,
     ):
         """Add a message to the conversation history.
 
         Args:
             role (str): The role of the speaker (e.g., 'User', 'System').
             content (Union[str, dict, list]): The content of the message to be added.
             category (Optional[str]): Optional category for the message.
+            metadata (Optional[dict]): Optional metadata for the message.
         """
         # Base message with role and timestamp
         message = {
@@ -476,6 +478,9 @@ def add_in_memory(
         if category:
             message["category"] = category
 
+        if metadata:
+            message["metadata"] = metadata
+
         # Add message to conversation history
         self.conversation_history.append(message)
         self._str_cache = None
@@ -587,7 +592,10 @@ def add(
             category (Optional[str]): Optional category for the message.
         """
         result = self.add_in_memory(
-            role=role, content=content, category=category
+            role=role,
+            content=content,
+            category=category,
+            metadata=metadata,
         )
 
         # Ensure autosave happens after the message is added

tests/structs/test_agent.py

@@ -2926,27 +2926,53 @@ def _bare_agent(self):
         agent.to_dict = lambda: {}
         return agent
 
-    def test_extra_positional_args_reach_run(self):
-        """`task=`/`img=` as keywords alongside *args made every extra
-        positional collide with `task`, so arun(task, img, extra) raised
-        `TypeError: run() got multiple values for argument 'task'`.
-        """
+    def test_task_and_img_reach_run_with_kwargs(self):
+        """The forwarding arun is actually able to do."""
         import asyncio
 
         agent = self._bare_agent()
         seen = {}
 
-        def fake_run(*args, **kwargs):
-            seen["args"] = args
+        def fake_run(task=None, img=None, **kwargs):
+            seen["task"] = task
+            seen["img"] = img
             seen["kwargs"] = kwargs
             return "ok"
 
         agent.run = fake_run
 
-        result = asyncio.run(Agent.arun(agent, "T", "I", "EXTRA"))
+        result = asyncio.run(
+            Agent.arun(agent, "T", "I", streaming_callback=None)
+        )
 
         assert result == "ok"
-        assert seen["args"] == ("T", "I", "EXTRA")
+        assert seen["task"] == "T"
+        assert seen["img"] == "I"
+        assert seen["kwargs"] == {"streaming_callback": None}
+
+    def test_a_third_positional_is_refused_not_bound_to_imgs(self):
+        """It has to fail loudly, because there is no correct place for it.
+
+        run()'s positionals after `img` are imgs/correct_answer/
+        streaming_callback/n, so forwarding a third positional through does
+        not reach run()'s own *args -- it lands on `imgs`, a List[str] of
+        image paths:
+
+            >>> inspect.signature(Agent.run).bind_partial(
+            ...     None, "T", "I", "EXTRA").arguments
+            {'task': 'T', 'img': 'I', 'imgs': 'EXTRA'}
+
+        A stub declared as ``fake_run(*args, **kwargs)`` cannot see that --
+        it accepts anything positionally -- which is why the real signature
+        is used here.
+        """
+        import asyncio
+
+        agent = self._bare_agent()
+        agent.run = lambda task=None, img=None, imgs=None, **kw: "ok"
+
+        with pytest.raises(TypeError):
+            asyncio.run(Agent.arun(agent, "T", "I", "EXTRA"))
 
     def test_error_path_does_not_await_a_sync_handler(self):
         """`_handle_run_error` is sync and re-raises; seven other call sites