agent-relay 3.2.15 → 3.2.17

package/packages/sdk-py/src/agent_relay/communicate/adapters/agno.py

@@ -9,10 +9,10 @@ if TYPE_CHECKING:
 
 
 def _format_instructions_with_inbox(messages: list[Any], base_instructions: str) -> str:
-    content = "\n\nNew messages from other agents:\n"
+    content = "New messages from other agents:\n"
     for message in messages:
         content += f"  {message.sender}: {message.text}\n"
-    return f"{content}\n{base_instructions}" if base_instructions else content
+    return f"{base_instructions}\n\n{content}" if base_instructions else content
 
 
 def on_relay(agent: Any, relay: "Relay | None" = None) -> Any:
@@ -45,11 +45,8 @@ def on_relay(agent: Any, relay: "Relay | None" = None) -> Any:
 
     agent.tools.extend([relay_send, relay_inbox, relay_post, relay_agents])
 
-    # 2. Wrap instructions with a local buffer so we don't starve relay_inbox tool
+    # 2. Wrap instructions
     orig_instructions = agent.instructions
-    pending_messages: list[Any] = []
-
-    relay.on_message(lambda msg: pending_messages.append(msg))
 
     async def instructions_wrapper(*args: Any, **kwargs: Any) -> str:
         if callable(orig_instructions):
@@ -63,11 +60,10 @@ def on_relay(agent: Any, relay: "Relay | None" = None) -> Any:
             base = orig_instructions
 
         base = base or ""
-        if not pending_messages:
+        messages = await relay.inbox()
+        if not messages:
             return base
 
-        messages = list(pending_messages)
-        pending_messages.clear()
         return _format_instructions_with_inbox(messages, base)
 
     agent.instructions = instructions_wrapper

package/packages/sdk-py/src/agent_relay/communicate/adapters/claude_sdk.py

@@ -9,7 +9,7 @@ if TYPE_CHECKING:
     from ..core import Relay
 
 
-def on_relay(name: str, options: Any, relay: "Relay | None" = None) -> Any:
+def on_relay(options: Any, relay: "Relay | None" = None, *, name: str | None = None) -> Any:
     """Wrap Claude Agent SDK query options to connect them to the relay."""
     try:
         from claude_agent_sdk.types import HookResult
@@ -24,10 +24,8 @@ def on_relay(name: str, options: Any, relay: "Relay | None" = None) -> Any:
         from ..core import Relay
         relay = Relay(agent_name)
 
-    hooks = getattr(options, "hooks", None)
-    if hooks is None:
-        hooks = SimpleNamespace(post_tool_use=None, stop=None)
-        options.hooks = hooks
+    if getattr(options, "hooks", None) is None:
+        options.hooks = SimpleNamespace(post_tool_use=None, stop=None)
 
     # 1. Inject Relaycast MCP server
     mcp_config = {"name": "relaycast", "command": "agent-relay", "args": ["mcp"]}
@@ -46,8 +44,8 @@ def on_relay(name: str, options: Any, relay: "Relay | None" = None) -> Any:
         return content
 
     # 3. Hook wrappers
-    orig_post = getattr(hooks, "post_tool_use", None)
-    orig_stop = getattr(hooks, "stop", None)
+    orig_post = options.hooks.post_tool_use if hasattr(options.hooks, "post_tool_use") else None
+    orig_stop = options.hooks.stop if hasattr(options.hooks, "stop") else None
 
     async def post_tool_use_hook(*args, **kwargs):
         res = None

package/packages/sdk-py/src/agent_relay/communicate/adapters/crewai.py

@@ -47,18 +47,9 @@ class _RelayBackstory:
     def _resolve_sync(self) -> str:
         messages = self._drain_buffer()
         try:
-            loop = asyncio.get_running_loop()
-        except RuntimeError:
-            loop = None
-
-        if loop is None:
             messages.extend(self._relay.inbox_sync())
-        else:
-            # Running inside an event loop — use a thread to avoid blocking
-            import concurrent.futures
-            with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
-                polled = pool.submit(asyncio.run, self._relay.inbox()).result()
-                messages.extend(polled)
+        except Exception:
+            pass  # Buffer messages are still available
         return _format_backstory(self._dedupe(messages), self._base_backstory)
 
     async def _resolve_async(self) -> str:
@@ -136,8 +127,7 @@ def on_relay(agent: Any, relay: "Relay | None" = None) -> Any:
     def _buffer_message(message: Any) -> None:
         backstory_buffer.append(message)
 
-    unsubscribe = relay.on_message(_buffer_message)
+    relay.on_message(_buffer_message)
     agent.backstory = _RelayBackstory(relay, agent.backstory or "", backstory_buffer)
-    agent._relay_unsubscribe = unsubscribe  # type: ignore[attr-defined]
 
     return agent

package/packages/sdk-py/src/agent_relay/communicate/adapters/google_adk.py

@@ -47,7 +47,10 @@ def on_relay(agent: Any, relay: "Relay | None" = None) -> Any:
             if inspect.isawaitable(orig_result):
                 orig_result = await orig_result
 
-        # Always inject relay messages, even if the original callback returned a result
+        # If original callback short-circuited (returned Content), respect that
+        if orig_result is not None:
+            return orig_result
+
         messages = await relay.inbox()
         if messages:
             from google.genai.types import Content, Part
@@ -63,7 +66,7 @@ def on_relay(agent: Any, relay: "Relay | None" = None) -> Any:
                     )
                 )
 
-        return orig_result
+        return None
 
     agent.before_model_callback = relay_callback
     return agent

package/packages/sdk-py/src/agent_relay/communicate/adapters/openai_agents.py

@@ -10,10 +10,10 @@ if TYPE_CHECKING:
 
 
 def _format_instructions_with_inbox(messages: list[Any], base_instructions: str) -> str:
-    content = "\n\nNew messages from other agents:\n"
+    content = "New messages from other agents:\n"
     for message in messages:
         content += f"  {message.sender}: {message.text}\n"
-    return f"{content}\n{base_instructions}" if base_instructions else content
+    return f"{base_instructions}\n\n{content}" if base_instructions else content
 
 
 def on_relay(agent: Any, relay: "Relay | None" = None) -> Any:
@@ -57,11 +57,8 @@ def on_relay(agent: Any, relay: "Relay | None" = None) -> Any:
         function_tool(relay_agents)
     ])
 
-    # 2. Wrap instructions with a local buffer so we don't starve relay_inbox tool
+    # 2. Wrap instructions
     orig_instructions = agent.instructions
-    pending_messages: list[Any] = []
-
-    relay.on_message(lambda msg: pending_messages.append(msg))
 
     async def instructions_wrapper(*args: Any, **kwargs: Any) -> str:
         if callable(orig_instructions):
@@ -75,11 +72,10 @@ def on_relay(agent: Any, relay: "Relay | None" = None) -> Any:
             base = orig_instructions
 
         base = base or ""
-        if not pending_messages:
+        messages = await relay.inbox()
+        if not messages:
             return base
 
-        messages = list(pending_messages)
-        pending_messages.clear()
         return _format_instructions_with_inbox(messages, base)
 
     agent.instructions = instructions_wrapper

package/packages/sdk-py/src/agent_relay/communicate/core.py

@@ -10,7 +10,7 @@ from inspect import isawaitable
 from typing import Any, Callable
 
 from .transport import RelayTransport
-from .types import Message, MessageCallback, RelayConfig, RelayConfigError, RelayAuthError
+from .types import Message, MessageCallback, RelayAuthError, RelayConfig, RelayConfigError
 
 MAX_PENDING_MESSAGES = 10_000
 
@@ -85,11 +85,6 @@ class Relay:
 
         return unsubscribe
 
-
-    async def join(self, channel: str) -> None:
-        await self._ensure_connected()
-        await self.transport.join_channel(channel)
-
     async def agents(self) -> list[str]:
         await self._ensure_connected()
         return await self.transport.list_agents()
@@ -160,25 +155,17 @@ class Relay:
             try:
                 await self.transport.connect()
                 self._ws_connected = True
+            except (RelayConfigError, RelayAuthError):
+                raise
             except Exception:
                 # WebSocket failed — register agent via HTTP and fall back to polling
                 await self.transport.register_agent()
                 self._ws_connected = False
                 self._start_poll_loop()
-
-            from contextlib import suppress
-            for ch in self.config.channels:
-                with suppress(Exception):
-                    await self.transport.join_channel(ch)
-
             self._connected = True
             self._connect_future.set_result(None)
-            self._connect_future = None
-        except Exception as exc:
-            # Ensure future is always resolved so waiters don't hang
-            if not self._connect_future.done():
-                self._connect_future.set_exception(exc)
-            self._connect_future = None
+        except BaseException as exc:
+            self._connect_future.set_exception(exc)
             raise
 
     def _schedule_connect(self) -> None:
@@ -262,10 +249,6 @@ def on_relay(agent: Any, relay: Relay | None = None) -> Any:
         relay = Relay(getattr(agent, "name", "Agent"))
 
     cls_module = type(agent).__module__
-    if cls_module.startswith("claude_agent_sdk"):
-        agent_name = getattr(agent, "name", "Agent")
-        from .adapters.claude_sdk import on_relay as _adapt
-        return _adapt(agent_name, agent, relay)
     if cls_module.startswith("agents"):
         from .adapters.openai_agents import on_relay as _adapt
         return _adapt(agent, relay)
@@ -284,8 +267,8 @@ def on_relay(agent: Any, relay: Relay | None = None) -> Any:
 
     raise TypeError(
         f"on_relay() doesn't recognize {type(agent).__name__} from {cls_module}. "
-        "Supported frameworks: Claude Agent SDK, OpenAI Agents, Google ADK, Agno, Swarms, CrewAI (Python). "
-        "For Claude Agent SDK, you can also import directly: "
+        "Supported frameworks: OpenAI Agents, Google ADK, Agno, Swarms, CrewAI (Python). "
+        "For Claude Agent SDK, import the adapter directly: "
         "from agent_relay.communicate.adapters.claude_sdk import on_relay"
     )
 

package/packages/sdk-py/src/agent_relay/communicate/transport.py

@@ -136,211 +136,66 @@ class RelayTransport:
         self._message_callback = callback
 
     async def register_agent(self) -> str:
-        """Register agent, or rotate token if it already exists (registerOrRotate pattern)."""
         self._require_config(require_workspace=True)
 
         if self.agent_id is not None and self.token is not None:
             return self.agent_id
 
-        try:
-            payload = await self.send_http(
-                "POST",
-                "/v1/agents",
-                payload={"name": self.agent_name, "type": "agent"},
-            )
-        except RelayConnectionError as exc:
-            if exc.status_code == 409:
-                # Agent already exists — get its info and rotate the token
-                from urllib.parse import quote
-                agent_payload = await self.send_http(
-                    "GET",
-                    f"/v1/agents/{quote(self.agent_name, safe='')}",
-                )
-                agent_data = agent_payload.get("data", agent_payload)
-                self.agent_id = agent_data["id"]
-
-                rotate_payload = await self.send_http(
-                    "POST",
-                    f"/v1/agents/{quote(self.agent_name, safe='')}/rotate-token",
-                )
-                rotate_data = rotate_payload.get("data", rotate_payload)
-                self.token = rotate_data["token"]
-                return self.agent_id
-            raise
-        # Relaycast API wraps in {ok, data: {...}}
-        data = payload.get("data", payload)
-        self.agent_id = data["id"]
-        self.token = data["token"]
+        payload = await self.send_http(
+            "POST",
+            "/v1/agents/register",
+            payload={"name": self.agent_name, "workspace": self.config.workspace},
+        )
+        self.agent_id = payload["agent_id"]
+        self.token = payload["token"]
         return self.agent_id
 
     async def unregister_agent(self) -> None:
-        if self.agent_id is None or self.token is None:
+        if self.agent_id is None:
             await self._close_session_if_idle()
             return
 
-        await self._send_http_as_agent("POST", "/v1/agents/disconnect")
+        agent_id = self.agent_id
+        await self.send_http("DELETE", f"/v1/agents/{agent_id}")
         self.agent_id = None
         self.token = None
         await self._close_session_if_idle()
 
     async def send_dm(self, recipient: str, text: str) -> str:
         await self._ensure_registered()
-        payload = await self._send_http_as_agent(
+        payload = await self.send_http(
             "POST",
-            "/v1/dm",
-            payload={"to": recipient, "text": text},
+            "/v1/messages/dm",
+            payload={"to": recipient, "text": text, "from": self.agent_name},
         )
-        if payload is None:
-            return ""
-        data = payload.get("data", payload)
-        return data.get("id", data.get("message_id", ""))
+        return payload["message_id"]
 
     async def post_message(self, channel: str, text: str) -> str:
         await self._ensure_registered()
-        from urllib.parse import quote
-
-        payload = await self._send_http_as_agent(
+        payload = await self.send_http(
             "POST",
-            f"/v1/channels/{quote(channel, safe='')}/messages",
-            payload={"text": text},
+            "/v1/messages/channel",
+            payload={"channel": channel, "text": text, "from": self.agent_name},
         )
-        if payload is None:
-            return ""
-        data = payload.get("data", payload)
-        return data.get("id", data.get("message_id", ""))
+        return payload["message_id"]
 
     async def reply(self, message_id: str, text: str) -> str:
         await self._ensure_registered()
-        from urllib.parse import quote
-
-        payload = await self._send_http_as_agent(
+        payload = await self.send_http(
             "POST",
-            f"/v1/messages/{quote(message_id, safe='')}/replies",
-            payload={"text": text},
-        )
-        if payload is None:
-            return ""
-        data = payload.get("data", payload)
-        return data.get("id", data.get("message_id", ""))
-
-
-    async def join_channel(self, channel: str) -> None:
-        await self._ensure_registered()
-        from urllib.parse import quote
-        await self._send_http_as_agent(
-            'POST',
-            f'/v1/channels/{quote(channel, safe="")}/join',
+            "/v1/messages/reply",
+            payload={"message_id": message_id, "text": text, "from": self.agent_name},
         )
+        return payload["message_id"]
 
     async def check_inbox(self) -> list[Message]:
         await self._ensure_registered()
-        from urllib.parse import quote
-
-        payload = await self._send_http_as_agent("GET", "/v1/inbox")
-        data = payload.get("data", payload)
-        messages: list[Message] = []
-
-        # Fetch unread DM conversations
-        for dm in data.get("unread_dms", []):
-            conv_id = dm.get("conversation_id", "")
-            sender = dm.get("from", "unknown")
-            # Fetch actual messages from the conversation
-            try:
-                conv_payload = await self._send_http_as_agent(
-                    "GET", f"/v1/dm/{quote(conv_id, safe='')}/messages"
-                )
-                conv_data = conv_payload.get("data", conv_payload)
-                items = conv_data if isinstance(conv_data, list) else []
-                for item in items:
-                    messages.append(Message(
-                        sender=item.get("agent_name", sender),
-                        text=item.get("text", ""),
-                        channel=None,
-                        thread_id=conv_id,
-                        timestamp=item.get("created_at"),
-                        message_id=item.get("id"),
-                    ))
-            except Exception:
-                # Fall back to the summary last_message
-                last = dm.get("last_message", {})
-                if last.get("text"):
-                    messages.append(Message(
-                        sender=sender,
-                        text=last["text"],
-                        channel=None,
-                        thread_id=conv_id,
-                        timestamp=last.get("created_at"),
-                        message_id=last.get("id"),
-                    ))
-
-        # Also include unread channel mentions
-        for mention in data.get("mentions", []):
-            messages.append(Message(
-                sender=mention.get("from", mention.get("agent_name", "unknown")),
-                text=mention.get("text", ""),
-                channel=mention.get("channel_name"),
-                thread_id=mention.get("thread_id"),
-                timestamp=mention.get("created_at"),
-                message_id=mention.get("id"),
-            ))
-
-        return messages
+        payload = await self.send_http("GET", f"/v1/inbox/{self.agent_id}")
+        return [self._message_from_payload(item) for item in payload.get("messages", [])]
 
     async def list_agents(self) -> list[str]:
         payload = await self.send_http("GET", "/v1/agents")
-        data = payload.get("data", payload)
-        if isinstance(data, list):
-            return [a.get("name", a) if isinstance(a, dict) else a for a in data]
-        return list(data.get("agents", []))
-
-    async def _send_http_as_agent(
-        self,
-        method: str,
-        path: str,
-        *,
-        payload: dict[str, Any] | None = None,
-    ) -> Any:
-        """Like send_http but authenticates with the per-agent token."""
-        await self._ensure_registered()
-        session = await self._ensure_session()
-        url = f"{self._base_url()}{path}"
-        headers = {"Authorization": f"Bearer {self.token}"}
-
-        for attempt in range(1, HTTP_RETRY_ATTEMPTS + 1):
-            try:
-                async with session.request(method, url, json=payload, headers=headers) as response:
-                    if response.status == 401:
-                        raise RelayAuthError(await self._error_message(response))
-
-                    if 500 <= response.status <= 599:
-                        message = await self._error_message(response)
-                        if attempt < HTTP_RETRY_ATTEMPTS:
-                            await asyncio.sleep(min(2 ** (attempt - 1), WS_RECONNECT_MAX_DELAY))
-                            continue
-                        raise RelayConnectionError(response.status, message)
-
-                    if response.status >= 400:
-                        raise RelayConnectionError(
-                            response.status,
-                            await self._error_message(response),
-                        )
-
-                    if response.status == 204:
-                        return None
-
-                    if response.content_type == "application/json":
-                        return await response.json()
-
-                    return await response.text()
-            except (RelayAuthError, RelayConnectionError):
-                raise
-            except aiohttp.ClientError as exc:
-                if attempt < HTTP_RETRY_ATTEMPTS:
-                    await asyncio.sleep(min(2 ** (attempt - 1), WS_RECONNECT_MAX_DELAY))
-                    continue
-                raise RelayConnectionError(0, str(exc)) from exc
-
-        raise RelayConnectionError(500, "Unexpected transport retry failure")
+        return list(payload.get("agents", []))
 
     async def _ensure_registered(self) -> None:
         if self.agent_id is None or self.token is None:
@@ -382,7 +237,7 @@ class RelayTransport:
         from urllib.parse import quote
 
         session = await self._ensure_session()
-        ws_url = f"{self._ws_base_url()}/v1/ws?token={quote(self.token, safe='')}"
+        ws_url = f"{self._ws_base_url()}/v1/ws/{self.agent_id}?token={quote(self.token, safe='')}"
         self._ws = await session.ws_connect(ws_url)
 
     def _ws_base_url(self) -> str:
@@ -431,58 +286,30 @@ class RelayTransport:
 
     async def _dispatch_ws_payload(self, raw_payload: str) -> None:
         payload = json.loads(raw_payload)
-        event_type = payload.get("type", "")
-
-        if event_type == "ping":
+        if payload.get("type") == "ping":
             if self._ws is not None and not self._ws.closed:
                 await self._ws.send_json({"type": "pong"})
             return
-
-        # Accept message.created, dm.received, direct_message.received, thread.reply, and legacy "message"
-        message_events = {"message.created", "dm.received", "direct_message.received",
-                          "thread.reply", "message", "group_dm.received"}
-        if event_type not in message_events:
+        if payload.get("type") != "message":
             return
 
         callback = self._message_callback
         if callback is None:
             return
 
-        try:
-            msg = self._message_from_payload(payload)
-        except (KeyError, TypeError):
-            return
-
-        result = callback(msg)
+        result = callback(self._message_from_payload(payload))
         if isawaitable(result):
             await result
 
     @staticmethod
     def _message_from_payload(payload: dict[str, Any]) -> Message:
-        # Support both flat and nested message structures
-        m = payload.get("message") if isinstance(payload.get("message"), dict) else payload
-        sender = (
-            m.get("sender")
-            or m.get("agent_name")
-            or m.get("from")
-            or m.get("agentName")
-            or payload.get("agent_name")
-            or payload.get("from")
-            or "unknown"
-        )
-        text = m.get("text", "")
-        channel = m.get("channel") or m.get("channel_name") or m.get("channelName") or payload.get("channel") or payload.get("channel_name")
-        thread_id = m.get("thread_id") or m.get("threadId") or m.get("conversation_id") or m.get("conversationId") or payload.get("thread_id")
-        timestamp = m.get("timestamp") or m.get("created_at") or m.get("createdAt") or payload.get("timestamp")
-        message_id = m.get("id") or m.get("message_id") or m.get("messageId") or payload.get("message_id")
-
         return Message(
-            sender=sender,
-            text=text,
-            channel=channel,
-            thread_id=thread_id,
-            timestamp=timestamp,
-            message_id=message_id,
+            sender=payload["sender"],
+            text=payload["text"],
+            channel=payload.get("channel"),
+            thread_id=payload.get("thread_id"),
+            timestamp=payload.get("timestamp"),
+            message_id=payload.get("message_id"),
         )
 
     @staticmethod
@@ -492,10 +319,6 @@ class RelayTransport:
         except Exception:
             text = await response.text()
             return text or response.reason or "Request failed"
-        # Relaycast wraps errors as {ok: false, error: {code, message}}
-        error = payload.get("error")
-        if isinstance(error, dict) and error.get("message"):
-            return str(error["message"])
         return str(payload.get("message") or response.reason or "Request failed")
 
 

package/packages/sdk-py/src/agent_relay/communicate/types.py

@@ -15,7 +15,7 @@ class Message:
     text: str
     channel: str | None = None
     thread_id: str | None = None
-    timestamp: str | float | None = None
+    timestamp: float | None = None
     message_id: str | None = None
 
 

package/packages/sdk-py/src/agent_relay/protocol.py

@@ -12,6 +12,7 @@ PROTOCOL_VERSION = 1
 
 AgentRuntime = Literal["pty", "headless"]
 HeadlessProvider = Literal["claude", "opencode"]
+MessageInjectionMode = Literal["wait", "steer"]
 
 
 @dataclass

package/packages/sdk-py/src/agent_relay/relay.py

@@ -16,7 +16,7 @@ from dataclasses import dataclass, field
 from typing import Any, Awaitable, Callable, Optional
 
 from .client import AgentRelayClient
-from .protocol import AgentRuntime, BrokerEvent
+from .protocol import AgentRuntime, BrokerEvent, MessageInjectionMode
 
 # ── Public types ──────────────────────────────────────────────────────────────
 
@@ -36,6 +36,7 @@ class Message:
     text: str
     thread_id: Optional[str] = None
     data: Optional[dict[str, Any]] = None
+    mode: Optional[MessageInjectionMode] = None
 
 
 @dataclass
@@ -197,6 +198,7 @@ class Agent:
         thread_id: Optional[str] = None,
         priority: Optional[int] = None,
         data: Optional[dict[str, Any]] = None,
+        mode: Optional[MessageInjectionMode] = None,
     ) -> Message:
         client = await self._relay._ensure_started()
         result = await client.send_message(
@@ -206,6 +208,7 @@ class Agent:
             thread_id=thread_id,
             priority=priority,
             data=data,
+            mode=mode,
         )
 
         event_id = result.get("event_id", secrets.token_hex(8))
@@ -216,6 +219,7 @@ class Agent:
             text=text,
             thread_id=thread_id,
             data=data,
+            mode=mode,
         )
         # Don't fire hook for unsupported operations
         if event_id != "unsupported_operation" and self._relay.on_message_sent:
@@ -259,6 +263,7 @@ class HumanHandle:
         thread_id: Optional[str] = None,
         priority: Optional[int] = None,
         data: Optional[dict[str, Any]] = None,
+        mode: Optional[MessageInjectionMode] = None,
     ) -> Message:
         client = await self._relay._ensure_started()
         result = await client.send_message(
@@ -268,6 +273,7 @@ class HumanHandle:
             thread_id=thread_id,
             priority=priority,
             data=data,
+            mode=mode,
         )
 
         event_id = result.get("event_id", secrets.token_hex(8))
@@ -278,6 +284,7 @@ class HumanHandle:
             text=text,
             thread_id=thread_id,
             data=data,
+            mode=mode,
         )
         # Don't fire hook for unsupported operations
         if event_id != "unsupported_operation" and self._relay.on_message_sent:
@@ -772,6 +779,7 @@ class AgentRelay:
                     to=event.get("target", ""),
                     text=event.get("body", ""),
                     thread_id=event.get("thread_id"),
+                    mode=event.get("injection_mode") or event.get("mode"),
                 )
                 if self.on_message_received:
                     self.on_message_received(msg)

package/packages/sdk-py/src/agent_relay/types.py

@@ -562,6 +562,7 @@ class RunOptions:
     vars: dict[str, str | int | bool] | None = None
     trajectories: TrajectoryConfig | Literal[False] | dict[str, Any] | bool | None = None
     on_event: WorkflowEventCallback | None = None
+    dry_run: bool | None = None
 
 
 @dataclass