docs and fixes

Author: v1r3n

README.md

@@ -34,9 +34,20 @@ If you find [Conductor](https://github.com/conductor-oss/conductor) useful, plea
 
 ## Start Conductor Server
 
-If you don't already have a Conductor server running, pick one:
+#### Conductor CLI
+```shell
+# Installs conductor cli
+npm install -g @conductor-oss/conductor-cli
+
+# Start the open source conductor server on port 8080
+conductor server start
+# see conductor server --help for all the available commands
+```
+
 
-**Docker Compose (recommended, includes UI):**
+Alternatively, if you want to use docker
+
+**Docker Compose**
 
 ```shell
 docker run -p 8080:8080 conductoross/conductor:latest
@@ -48,15 +59,6 @@ The UI will be available at `http://localhost:8080` and the API at `http://local
 curl -sSL https://raw.githubusercontent.com/conductor-oss/conductor/main/conductor_server.sh | sh
 ```
 
-**Conductor CLI**
-```shell
-# Installs conductor cli
-npm install -g @conductor-oss/conductor-cli
-
-# Start the open source conductor server
-conductor server start
-# see conductor server --help for all the available commands
-```
 
 ## Install the SDK
 

SDK_UPDATE_v1.md

@@ -21,7 +21,7 @@
 
 @dataclass
 class Settings:
-    llm_model: str = "anthropic/claude-sonnet-4-6"
+    llm_model: str = "openai/gpt-4o"
     secondary_llm_model: str = "openai/gpt-4o"
 
     @classmethod

docs/design/AGENT_SDK_PORTING_SPEC.md

@@ -492,22 +492,62 @@ async def __call__(self, result: str = "", iteration: int = 0) -> object:
 
 
 class CheckTransferEntry:
-    """Detect transfer tool calls (was ``check_transfer_worker``; stateless)."""
+    """Detect transfer tool calls (was ``check_transfer_worker``; stateless).
+
+    Selection is first-wins: when the LLM emits multiple transfer calls in one
+    turn only the first is honored (the swarm loop can only hand off to one
+    agent). The others are surfaced as ``dropped_transfers`` so the intent is
+    visible in the task output instead of silently discarded — the transfer
+    tool descriptions instruct the model to call at most one per turn.
+
+    ``transfer_message`` carries the transfer tool's ``message`` argument (the
+    hand-off note for the receiving agent); the server compiler records it in
+    the conversation as ``[agent -> target]: <message>``.
+    """
 
     async def __call__(self, tool_calls: object = None, _unused: str = "") -> object:
+        transfers = []
         for tc in tool_calls or []:
-            name = tc.get("name", "")
-            if "_transfer_to_" in name:
-                return {"is_transfer": True, "transfer_to": name.split("_transfer_to_", 1)[1]}
-        return {"is_transfer": False, "transfer_to": ""}
+            name = tc.get("name", "") or ""
+            if "_transfer_to_" not in name:
+                continue
+            params = tc.get("inputParameters") or {}
+            message = params.get("message")
+            transfers.append(
+                {
+                    "transfer_to": name.split("_transfer_to_", 1)[1],
+                    "message": "" if message is None else str(message),
+                }
+            )
+        if not transfers:
+            return {"is_transfer": False, "transfer_to": "", "transfer_message": ""}
+        first = transfers[0]
+        out = {
+            "is_transfer": True,
+            "transfer_to": first["transfer_to"],
+            "transfer_message": first["message"],
+        }
+        if len(transfers) > 1:
+            import logging
+
+            logging.getLogger(__name__).warning(
+                "Multiple transfer calls in one turn; honoring '%s', dropping %s",
+                first["transfer_to"],
+                [t["transfer_to"] for t in transfers[1:]],
+            )
+            out["dropped_transfers"] = transfers[1:]
+        return out
 
 
 class TransferNoopEntry:
     """No-op transfer tool (was the nested ``transfer_worker``; handoff is
-    detected by check_transfer from toolCalls output)."""
+    detected by check_transfer from toolCalls output). Echoes the hand-off
+    ``message`` so it is visible in the task output / UI."""
 
-    async def __call__(self) -> object:
-        return {}
+    async def __call__(self, message: str = "") -> object:
+        if not message:
+            return {}
+        return {"message": message}
 
 
 class TransferUnreachableEntry:

examples/agents/settings.py

@@ -1557,7 +1557,7 @@ def _register_hybrid_transfer_workers(
         for sub in agent.agents:
             tool_name = f"{agent.name}_transfer_to_{sub.name}"
             transfer_worker = TransferNoopEntry()
-            transfer_worker.__annotations__ = {"return": object}
+            transfer_worker.__annotations__ = {"message": str, "return": object}
             probe_spawn_safety(transfer_worker, tool_name, group="system")
             worker_task(
                 task_definition_name=tool_name,
@@ -1685,7 +1685,7 @@ def _register_swarm_transfer_workers(
                     transfer_worker.__annotations__ = {"return": str}
                 else:
                     transfer_worker = TransferNoopEntry()
-                    transfer_worker.__annotations__ = {"return": object}
+                    transfer_worker.__annotations__ = {"message": str, "return": object}
                 probe_spawn_safety(transfer_worker, tool_name, group="system")
                 worker_task(
                     task_definition_name=tool_name,

src/conductor/ai/agents/runtime/_worker_entries.py

@@ -329,9 +329,82 @@ def test_transfer_entries_pickle(self):
         )
 
         assert asyncio.run(pickle.loads(pickle.dumps(TransferNoopEntry()))()) == {}
+        # Echoes the hand-off message so it is visible in the task output.
+        assert asyncio.run(pickle.loads(pickle.dumps(TransferNoopEntry()))(message="do X")) == {
+            "message": "do X"
+        }
         msg = asyncio.run(pickle.loads(pickle.dumps(TransferUnreachableEntry("a_transfer_to_b")))())
         assert "a_transfer_to_b is not available" in msg
 
+    def test_check_transfer_extracts_message(self):
+        import asyncio
+
+        from conductor.ai.agents.runtime._worker_entries import CheckTransferEntry
+
+        entry = pickle.loads(pickle.dumps(CheckTransferEntry()))
+        out = asyncio.run(
+            entry(
+                tool_calls=[
+                    {
+                        "name": "ceo_transfer_to_engineering_lead",
+                        "inputParameters": {
+                            "method": "ceo_transfer_to_engineering_lead",
+                            "message": "Design the REST API",
+                        },
+                    }
+                ]
+            )
+        )
+        assert out == {
+            "is_transfer": True,
+            "transfer_to": "engineering_lead",
+            "transfer_message": "Design the REST API",
+        }
+
+    def test_check_transfer_no_transfer_and_missing_message(self):
+        import asyncio
+
+        from conductor.ai.agents.runtime._worker_entries import CheckTransferEntry
+
+        entry = CheckTransferEntry()
+        assert asyncio.run(entry(tool_calls=None)) == {
+            "is_transfer": False,
+            "transfer_to": "",
+            "transfer_message": "",
+        }
+        # Transfer without a message arg (older tool schema) → empty message
+        out = asyncio.run(
+            entry(tool_calls=[{"name": "a_transfer_to_b", "inputParameters": {"method": "x"}}])
+        )
+        assert out == {"is_transfer": True, "transfer_to": "b", "transfer_message": ""}
+
+    def test_check_transfer_multiple_calls_first_wins_and_reports_dropped(self):
+        import asyncio
+
+        from conductor.ai.agents.runtime._worker_entries import CheckTransferEntry
+
+        entry = CheckTransferEntry()
+        out = asyncio.run(
+            entry(
+                tool_calls=[
+                    {
+                        "name": "ceo_transfer_to_engineering_lead",
+                        "inputParameters": {"message": "eng task"},
+                    },
+                    {
+                        "name": "ceo_transfer_to_marketing_lead",
+                        "inputParameters": {"message": "mkt task"},
+                    },
+                ]
+            )
+        )
+        assert out["is_transfer"] is True
+        assert out["transfer_to"] == "engineering_lead"
+        assert out["transfer_message"] == "eng task"
+        assert out["dropped_transfers"] == [
+            {"transfer_to": "marketing_lead", "message": "mkt task"}
+        ]
+
 
 # ── Framework worker entries (Group C) ───────────────────────────────────