Skip to content

Build and run agents you can see, understand and trust.

refactor(channel): deliver a reply from the node that produced it (#2395)

DavdGao801dd1ef97e7
diff --git a/src/agentscope/app/_bus_ops.py b/src/agentscope/app/_bus_ops.py
index 4cce280b2..eb7f1e23e 100644
--- a/src/agentscope/app/_bus_ops.py
+++ b/src/agentscope/app/_bus_ops.py
@@ -363,49 +363,3 @@ async def enqueue_index_task(
},
)
await bus.publish(MessageBusKeys.index_tasks_signal(), {})
-
-
-# ── enqueue_channel_output ─────────────────────────────────────────────
-
-
-async def enqueue_channel_output(
- bus: "MessageBus",
- *,
- session_id: str,
- channel_id: str,
- chat_id: str,
- user_id: str,
- agent_id: str,
-) -> None:
- """Signal that a channel-bound session is producing output.
-
- Pushes one signal onto the durable channel-outbound queue and nudges
- the consumers. Whichever node hosts the channel drains it and
- forwards the reply back to the platform chat. Called once at the
- start of a channel-bound run, before the reply is produced.
-
- Args:
- bus (`MessageBus`):
- The application message bus.
- session_id (`str`):
- The session about to produce output.
- channel_id (`str`):
- The owning channel (locates the adapter + presentation).
- chat_id (`str`):
- The platform chat to deliver the reply to.
- user_id (`str`):
- The owning user id.
- agent_id (`str`):
- The agent id that owns the session.
- """
- await bus.queue_push(
- MessageBusKeys.channel_outbound_queue(),
- {
- "session_id": session_id,
- "channel_id": channel_id,
- "chat_id": chat_id,
- "user_id": user_id,
- "agent_id": agent_id,
- },
- )
- await bus.publish(MessageBusKeys.channel_outbound_signal(), {})
diff --git a/src/agentscope/app/_lifespan.py b/src/agentscope/app/_lifespan.py
index f5050e14e..dc5f73e18 100644
--- a/src/agentscope/app/_lifespan.py
+++ b/src/agentscope/app/_lifespan.py
@@ -125,6 +125,7 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]:
channel_clients = await stack.enter_async_context(
ChannelClients(
storage=storage,
+ message_bus=message_bus,
type_registry=channel_type_registry,
),
)
diff --git a/src/agentscope/app/_service/_chat.py b/src/agentscope/app/_service/_chat.py
index 755865e28..0c50bceab 100644
--- a/src/agentscope/app/_service/_chat.py
+++ b/src/agentscope/app/_service/_chat.py
@@ -22,7 +22,6 @@ from fastapi import HTTPException
from .._bus_ops import (
abandon_inbox_consumer,
deliver_to_inbox,
- enqueue_channel_output,
enqueue_run_trigger,
has_pending_inbox_or_release,
publish_session_event,
@@ -1011,20 +1010,21 @@ class ChatService:
# 7. Run the agent (still under the session lock)
# -----------------------------------------------------------------
events_key = MessageBusKeys.session_events(session_id)
- # Channel-bound run: signal the output forwarder so the reply
- # is streamed back to the platform chat. Covers scheduled /
- # background wakes, not just inbound channel messages.
+ # Channel-bound run: start streaming the reply back to the
+ # platform chat. Delivery is plain REST, so this node does it
+ # rather than handing the run to whichever one holds the
+ # channel's connection. Covers scheduled / background wakes,
+ # not just inbound channel messages.
if (
session_record.source == SessionSource.CHANNEL
and session_record.source_channel_id
and session_record.source_chat_id
+ and self._channel_clients is not None
):
- await enqueue_channel_output(
- self._message_bus,
+ await self._channel_clients.deliver(
session_id=session_id,
channel_id=session_record.source_channel_id,
chat_id=session_record.source_chat_id,
- user_id=user_id,
agent_id=agent_id,
)
reply_msg: Msg | None = None
diff --git a/src/agentscope/app/channel/_clients.py b/src/agentscope/app/channel/_clients.py
index a962e73b2..e5c84b4b9 100644
--- a/src/agentscope/app/channel/_clients.py
+++ b/src/agentscope/app/channel/_clients.py
@@ -1,5 +1,8 @@
# -*- coding: utf-8 -*-
-"""Channel instances for processes that do not hold the connection.
+"""The channel runtime of a process that holds no connection.
+
+Owns two things: the channel instances such a process builds, and the
+reply deliveries it runs through them.
A channel has exactly one piece of connection-bound state: the inbound
long connection opened by ``start_listening``. Everything else — sending
@@ -20,16 +23,25 @@ therefore keep no state across calls.
A replaced instance is retired rather than closed: a run that borrowed
it still holds it — its platform tools stay callable for the whole turn
— and closing the HTTP client underneath would break them. Retired
-instances are released when the
-factory shuts down, which bounds what a rotation costs to one idle
-client per rotation.
+instances are released when this shuts down, which bounds what a
+rotation costs to one idle client per rotation.
+
+Deliveries are owned here for the same reason the connections are owned
+by the lifecycle dispatcher: a background task needs a component whose
+lifecycle can cancel it. The node running the agent is the one that
+delivers, and that node may well have no dispatcher — this is what it
+has instead.
"""
+import asyncio
+from contextlib import aclosing
from types import TracebackType
from ..._logging import logger
+from ..message_bus import MessageBus
from ..storage import StorageBase
-from ._base import ChannelBase
+from ._base import ChannelBase, ChannelEvent
from ._registry import ChannelTypeRegistry
+from ._stream import open_reply_stream
class ChannelClients:
@@ -38,19 +50,24 @@ class ChannelClients:
def __init__(
self,
storage: StorageBase,
+ message_bus: MessageBus,
type_registry: ChannelTypeRegistry,
) -> None:
- """Bind storage and the registry that knows the channel classes.
+ """Bind storage, the bus, and the registry of channel classes.
Args:
storage (`StorageBase`): Source of channel records.
+ message_bus (`MessageBus`): Where a delivery reads the run's
+ events from.
type_registry (`ChannelTypeRegistry`): Builds instances from
a record's type, credentials and config.
"""
self._storage = storage
+ self._bus = message_bus
self._types = type_registry
self._cache: dict[str, tuple[str, ChannelBase]] = {}
self._retired: list[ChannelBase] = []
+ self._deliveries: set[asyncio.Task] = set()
async def __aenter__(self) -> "ChannelClients":
"""Enter the factory's lifecycle; nothing is built up front."""
@@ -62,11 +79,14 @@ class ChannelClients:
exc: BaseException | None,
tb: TracebackType | None,
) -> None:
- """Release every instance this factory built.
+ """Stop delivering, then release every instance built here.
- Nothing is borrowing them by now: the runs that could have are
- torn down with the process.
+ Deliveries go first: they are what borrows the instances, so
+ nothing is using one by the time it is closed.
"""
+ for task in list(self._deliveries):
+ task.cancel()
+ await asyncio.gather(*self._deliveries, return_exceptions=True)
for channel_id in list(self._cache):
self._retire(channel_id)
for channel in self._retired:
@@ -133,3 +153,78 @@ class ChannelClients:
self._retire(channel_id)
self._cache[channel_id] = (version, channel)
return channel
+
+ async def deliver(
+ self,
+ *,
+ session_id: str,
+ channel_id: str,
+ chat_id: str,
+ agent_id: str,
+ ) -> None:
+ """Start streaming a run's reply back to its platform chat.
+
+ Returns as soon as the delivery is under way — the caller is
+ mid-run and must not wait on the platform. The task is held here
+ so it is neither garbage-collected in flight nor left behind at
+ shutdown.
+
+ Args:
+ session_id (`str`): The run whose reply is delivered.
+ channel_id (`str`): The channel the session came from.
+ chat_id (`str`): The platform chat to deliver into.
+ agent_id (`str`): The agent that owns the session; pinned on
+ a confirmation card so a click resumes this exact run.
+ """
+ channel = await self.get(channel_id)
+ if channel is None:
+ logger.error(
+ "channel '%s' has no client; the reply for session '%s' "
+ "cannot be delivered",
+ channel_id,
+ session_id,
+ )
+ return
+
+ # Synthetic send target — a background run has no inbound
+ # message. Carries the run's identity so a confirmation card can
+ # pin its exact target and skip re-resolving routing on click.
+ target = ChannelEvent(
+ channel_id=channel_id,
+ channel_user_id="",
+ chat_id=chat_id,
+ metadata={"session_id": session_id, "agent_id": agent_id},
+ )
+
+ # Subscribe before returning: the caller is about to run the
+ # agent, and the run drops its event log when it persists, so a
+ # subscription opened any later could miss the whole reply.
+ try:
+ events = await open_reply_stream(self._bus, session_id)
+ except Exception: # pylint: disable=broad-except
+ logger.exception(
+ "channel '%s' could not read the reply for session '%s'",
+ channel_id,
+ session_id,
+ )
+ return
+
+ async def _run() -> None:
+ """Feed the run's event stream to the channel."""
+ try:
+ async with aclosing(events):
+ await channel.send_response(target, events)
+ except Exception: # pylint: disable=broad-except
+ logger.exception(
+ "channel '%s' failed to deliver the reply for "
+ "session '%s'",
+ channel_id,
+ session_id,
+ )
+
+ task = asyncio.create_task(
+ _run(),
+ name=f"channel-deliver:{session_id}",
+ )
+ self._deliveries.add(task)
+ task.add_done_callback(self._deliveries.discard)
diff --git a/src/agentscope/app/channel/_dispatcher.py b/src/agentscope/app/channel/_dispatcher.py
index be8ea3735..8503761d7 100644
--- a/src/agentscope/app/channel/_dispatcher.py
+++ b/src/agentscope/app/channel/_dispatcher.py
@@ -10,24 +10,19 @@ It answers no queries. With the connections in a dedicated worker the
API replicas have no dispatcher to ask, so status is published to the
bus and read from there instead.
-It also forwards each channel-bound run's output back to the platform:
-on an outbound signal it subscribes to the run's event stream (gap-free
-— subscribe **first**, then replay the log, deduplicating by Redis-Stream
-``entry_id``) and hands that stream to the local channel's
-``send_response``, which folds and delivers it. The channel owns
-rendering (streaming, confirmation cards); the dispatcher only feeds it
-the events.
+Holding the connections is all it does. A reply never comes back here:
+delivery is plain REST, so the node running the agent builds its own
+client and sends it directly.
"""
import asyncio
import socket
import time
-from contextlib import aclosing, asynccontextmanager
+from contextlib import asynccontextmanager
from dataclasses import dataclass
-from typing import AsyncGenerator, AsyncIterator
+from typing import AsyncIterator
from ..._logging import logger
from ..._utils._common import _generate_id
-from ...event import EventType
from ..message_bus import MessageBus, MessageBusKeys
from ..storage import ChannelRecord, StorageBase
from ._base import (
@@ -40,17 +35,10 @@ from ._base import (
from ._gateway import ChannelGateway
from ._registry import ChannelTypeRegistry
-# Max seconds to wait for a channel-bound run's reply before giving up.
-RESPONSE_TIMEOUT_SECS = 60.0
# How often the heartbeat is refreshed; well inside
# ``LIVENESS_TTL_SECS`` so a live node never looks expired to a reader.
LIVENESS_REFRESH_SECS = 10
-# Events that end a reply's event stream.
-_TERMINAL_EVENTS = frozenset(
- {EventType.REPLY_END, EventType.REQUIRE_USER_CONFIRM},
-)
-
@dataclass
class ChannelInstance:
@@ -88,7 +76,6 @@ class ChannelLifecycleDispatcher:
self._instances: dict[str, ChannelInstance] = {}
self._node_id = f"{socket.gethostname()}:{_generate_id()[:8]}"
self._tasks: list[asyncio.Task] = []
- self._forward_tasks: set[asyncio.Task] = set()
@asynccontextmanager
async def lifespan(self) -> AsyncIterator[None]:
@@ -98,18 +85,13 @@ class ChannelLifecycleDispatcher:
self._tasks = [
asyncio.create_task(self._listen(), name="channel-lifecycle"),
asyncio.create_task(self._periodic(), name="channel-heartbeat"),
- asyncio.create_task(self._outbound(), name="channel-outbound"),
]
try:
yield
finally:
- for task in (*self._tasks, *self._forward_tasks):
+ for task in self._tasks:
task.cancel()
- await asyncio.gather(
- *self._tasks,
- *self._forward_tasks,
- return_exceptions=True,
- )
+ await asyncio.gather(*self._tasks, return_exceptions=True)
for cid in set(self._instances):
await self._stop(cid)
@@ -218,163 +200,6 @@ class ChannelLifecycleDispatcher:
await asyncio.sleep(backoff)
backoff = min(backoff * 2, 30.0)
- async def _outbound(self) -> None:
- """Drain channel-output signals and forward each run's reply; the
- per-run lease makes the at-least-once drain effectively once."""
- await self._drain_outbound()
- backoff = 1.0
- while True:
- try:
- async for _ in self._bus.subscribe(
- MessageBusKeys.channel_outbound_signal(),
- ):
- backoff = 1.0
- await self._drain_outbound()
- except asyncio.CancelledError: # pylint: disable=try-except-raise
- raise
- except Exception: # pylint: disable=broad-except
- logger.warning("channel outbound subscription lost")
- await asyncio.sleep(backoff)
- backoff = min(backoff * 2, 30.0)
-
- async def _drain_outbound(self) -> None:
- """Forward every queued output signal this node can serve."""
- try:
- jobs = await self._bus.queue_drain(
- MessageBusKeys.channel_outbound_queue(),
- )
- except Exception: # pylint: disable=broad-except
- logger.exception("channel outbound drain failed")
- return
- for _entry_id, job in jobs:
- inst = self._instances.get(job.get("channel_id", ""))
- if inst is None:
- # Not hosted here (reconcile lag). Under no-sharding every
- # node hosts every enabled channel, so drop this stale one.
- continue
- task = asyncio.create_task(
- self._forward(job, inst.channel),
- name=f"channel-forward:{job.get('session_id', '')}",
- )
- self._forward_tasks.add(task)
- task.add_done_callback(self._forward_tasks.discard)
-
- # -- Output forwarding (a run's reply → the platform) --
-
- async def _forward(self, job: dict, channel: ChannelBase) -> None:
- """Feed one channel-bound run's event stream to ``send_response``.
-
- The channel folds and delivers it (streaming, confirmation cards);
- this only subscribes and hands over the stream.
-
- Args:
- job (`dict`):
- ``{session_id, channel_id, chat_id, user_id, agent_id}``
- from the outbound signal.
- channel (`ChannelBase`): The local channel for ``channel_id``.
- """
- record = await self._storage.get_channel(job["channel_id"])
- if record is None:
- return
- # Dedup across nodes: the drain is at-least-once, so claim a
- # per-run lease first — only the winner forwards, the rest skip.
- lock_key = MessageBusKeys.channel_forward_lease(job["session_id"])
- if not await self._bus.try_lock(
- lock_key,
- ttl_secs=int(RESPONSE_TIMEOUT_SECS) + 10,
- ):
- return
- # Synthetic send target — background runs have no inbound message.
- # Carry the run's identity so a confirmation card can pin its exact
- # target and skip routing re-resolution on click.
- target = ChannelEvent(
- channel_id=job["channel_id"],
- channel_user_id="",
- chat_id=job["chat_id"],
- metadata={
- "session_id": job["session_id"],
- "agent_id": job["agent_id"],
- },
- )
- try:
- async with aclosing(
- self._event_stream(job["session_id"]),
- ) as events:
- await asyncio.wait_for(
- channel.send_response(target, events),
- timeout=RESPONSE_TIMEOUT_SECS,
- )
- except (asyncio.TimeoutError, TimeoutError):
- pass # leave whatever was delivered
- except Exception: # pylint: disable=broad-except
- logger.exception("channel send_response failed")
- finally:
- await self._bus.unlock(lock_key)
-
- async def _event_stream(
- self,
- session_id: str,
- ) -> AsyncGenerator[dict, None]:
- """Yield a run's events gap-free, stopping after the terminal one.
-
- Subscribe **first** (buffering live events), replay the log, then
- go live — deduplicating by ``entry_id`` so the seam is neither
- missed nor double-counted.
-
- Args:
- session_id (`str`): The run's session, whose events are read.
-
- Yields:
- `dict`: Each session event, up to and including the terminal
- ``REPLY_END`` / ``REQUIRE_USER_CONFIRM``.
- """
- event_key = MessageBusKeys.session_events(session_id)
- ready = asyncio.Event()
- queue: asyncio.Queue[dict] = asyncio.Queue()
- seen: set[str] = set()
-
- async def feeder() -> None:
- """Buffer live subscription events into the local queue."""
- try:
- async for evt in self._bus.subscribe(
- event_key,
- on_ready=ready.set,
- ):
- await queue.put(evt)
- except asyncio.CancelledError:
- pass
-
- feeder_task = asyncio.create_task(feeder())
- try:
- await asyncio.wait_for(ready.wait(), timeout=5.0)
- for entry_id, evt in await self._bus.log_read(
- event_key,
- max_count=MessageBusKeys.SESSION_REPLAY_MAX_LEN,
- ):
- seen.add(str(entry_id))
- yield evt
- if evt.get("type", "") in _TERMINAL_EVENTS:
- return
- while True:
- evt = await queue.get()
- eid = evt.get("_entry_id")
- if eid is not None:
- if str(eid) in seen:
- continue
- seen.add(str(eid))
- yield evt
- if evt.get("type", "") in _TERMINAL_EVENTS:
- return
- finally:
- feeder_task.cancel()
- try:
- await feeder_task
- except (
- asyncio.CancelledError,
- Exception,
- ): # pylint: disable=broad-except
- pass
-
async def _periodic(self) -> None:
"""Reconcile and publish status on a fixed interval.
diff --git a/src/agentscope/app/channel/_stream.py b/src/agentscope/app/channel/_stream.py
new file mode 100644
index 000000000..ca7e264b7
--- /dev/null
+++ b/src/agentscope/app/channel/_stream.py
@@ -0,0 +1,119 @@
+# -*- coding: utf-8 -*-
+"""Read one run's reply off the bus as a gap-free event stream.
+
+Consumed by whichever node delivers a channel-bound run's reply. It
+reads from the shared bus rather than from the run's own generator, so
+the reader and the run are decoupled — the reader can start before the
+run does, or attach to one already in flight.
+"""
+import asyncio
+from typing import AsyncGenerator
+
+from ...event import EventType
+from ..message_bus import MessageBus, MessageBusKeys
+
+# Events that end a reply's stream: the run either finished or parked
+# waiting on something from outside. A parked run publishes no
+# ``REPLY_END`` until it is resumed, so treating these as terminal is
+# what keeps a reader from waiting on a reply that is not coming.
+
+# How long to wait for the bus subscription to come up.
+_SUBSCRIBE_TIMEOUT_SECS = 5.0
+_TERMINAL_EVENTS = frozenset(
+ {
+ EventType.REPLY_END,
+ EventType.REQUIRE_USER_CONFIRM,
+ EventType.REQUIRE_EXTERNAL_EXECUTION,
+ },
+)
+
+
+async def open_reply_stream(
+ bus: MessageBus,
+ session_id: str,
+) -> AsyncGenerator[dict, None]:
+ """Subscribe to a run's events and return a gap-free reader.
+
+ The subscription is live by the time this returns, which is what the
+ caller needs: a run drops its whole event log when it persists, so a
+ reader that only subscribes afterwards would find nothing to replay
+ and then wait on a feed that has already gone quiet.
+
+ Args:
+ bus (`MessageBus`): The application message bus.
+ session_id (`str`): The run's session, whose events are read.
+
+ Returns:
+ `AsyncGenerator[dict, None]`: Yields each session event up to and
+ including the terminal one. Close it to drop the subscription.
+ """
+ event_key = MessageBusKeys.session_events(session_id)
+ ready = asyncio.Event()
+ queue: asyncio.Queue[dict] = asyncio.Queue()
+
+ async def feeder() -> None:
+ """Buffer live subscription events into the local queue."""
+ try:
+ async for evt in bus.subscribe(event_key, on_ready=ready.set):
+ await queue.put(evt)
+ except asyncio.CancelledError:
+ pass
+
+ feeder_task = asyncio.create_task(feeder())
+ try:
+ await asyncio.wait_for(ready.wait(), timeout=_SUBSCRIBE_TIMEOUT_SECS)
+ except BaseException:
+ feeder_task.cancel()
+ raise
+ return _read(bus, event_key, queue, feeder_task)
+
+
+async def _read(
+ bus: MessageBus,
+ event_key: str,
+ queue: "asyncio.Queue[dict]",
+ feeder_task: "asyncio.Task",
+) -> AsyncGenerator[dict, None]:
+ """Replay the log, then go live, stopping at the terminal event.
+
+ Deduplicates by ``entry_id`` so the seam between the two is neither
+ missed nor double-counted.
+
+ Args:
+ bus (`MessageBus`): The application message bus.
+ event_key (`str`): The session's event log / channel key.
+ queue (`asyncio.Queue[dict]`): Live events buffered so far.
+ feeder_task (`asyncio.Task`): The subscription, cancelled on close.
+
+ Yields:
+ `dict`: Each session event, up to and including the terminal one.
+ """
+ seen: set[str] = set()
+ try:
+ for entry_id, evt in await bus.log_read(
+ event_key,
+ max_count=MessageBusKeys.SESSION_REPLAY_MAX_LEN,
+ ):
+ seen.add(str(entry_id))
+ yield evt
+ if evt.get("type", "") in _TERMINAL_EVENTS:
+ return
+ while True:
+ evt = await queue.get()
+ eid = evt.get("_entry_id")
+ if eid is not None:
+ if str(eid) in seen:
+ continue
+ seen.add(str(eid))
+ yield evt
+ if evt.get("type", "") in _TERMINAL_EVENTS:
+ return
+ finally:
+ feeder_task.cancel()
+ try:
+ await feeder_task
+ except (
+ asyncio.CancelledError,
+ Exception,
+ ): # pylint: disable=broad-except
+ pass
diff --git a/src/agentscope/app/message_bus/_keys.py b/src/agentscope/app/message_bus/_keys.py
index b1d95da8b..3c20e524e 100644
--- a/src/agentscope/app/message_bus/_keys.py
+++ b/src/agentscope/app/message_bus/_keys.py
@@ -288,32 +288,18 @@ class MessageBusKeys: # pylint: disable=too-many-public-methods
return cls._INDEX_TASKS_SIGNAL
# ------------------------------------------------------------------
- # Channel output forwarding — a durable queue of "a channel session
- # is producing output" signals. Each node running channel adapters
- # drains it; the node that pops a signal (and hosts that channel)
- # subscribes to the session's event stream and forwards the reply
- # back to the platform chat. Queue + atomic pop → exactly one node
- # forwards, even though every node runs the adapter.
+ # Channels. A reply never travels through the bus: delivery is plain
+ # REST, so the node running the agent sends it directly. What does
+ # cross nodes is coordination — reconcile nudges, the status
+ # heartbeat that lets a connection-free replica answer, and the
+ # per-chat buffers.
# ------------------------------------------------------------------
- _CHANNEL_OUTBOUND_QUEUE = "agentscope:channel:outbound"
- _CHANNEL_OUTBOUND_SIGNAL = "agentscope:channel:outbound:wake"
_CHANNEL_LIFECYCLE = "agentscope:channel:lifecycle"
_CHANNEL_LIVENESS = "agentscope:channel:liveness:{cid}"
_CHANNEL_MEDIA = "agentscope:channel:media:{cid}:{chat}:{uid}"
- _CHANNEL_FORWARD = "agentscope:channel:forward:{sid}"
_CHANNEL_SEEN_CHATS = "agentscope:channel:seen_chats:{cid}"
- @classmethod
- def channel_outbound_queue(cls) -> str:
- """Durable queue of channel output-forward signals."""
- return cls._CHANNEL_OUTBOUND_QUEUE
-
- @classmethod
- def channel_outbound_signal(cls) -> str:
- """Pub/sub nudge for channel output-forward consumers."""
- return cls._CHANNEL_OUTBOUND_SIGNAL
-
@classmethod
def channel_lifecycle(cls) -> str:
"""Pub/sub channel that nudges every node to reconcile its
@@ -339,11 +325,6 @@ class MessageBusKeys: # pylint: disable=too-many-public-methods
uid=user_id,
)
- @classmethod
- def channel_forward_lease(cls, session_id: str) -> str:
- """Per-run lock so exactly one node forwards a reply."""
- return cls._CHANNEL_FORWARD.format(sid=session_id)
-
@classmethod
def channel_seen_chats(cls, channel_id: str) -> str:
"""Registry namespace of chat_ids the bot has been messaged in."""
diff --git a/tests/channel_clients_test.py b/tests/channel_clients_test.py
index 8371a5168..cb9c43d34 100644
--- a/tests/channel_clients_test.py
+++ b/tests/channel_clients_test.py
@@ -3,9 +3,11 @@
A process that does not hold a channel's long connection must still be
able to use the channel: attach its platform tools to an agent, deliver
-a reply, and report its status. These cover the two pieces that make
-that work — the client factory and the status heartbeat.
+a reply, and report its status. These cover the three pieces that make
+that work — the client factory, the deliveries it owns, and the status
+heartbeat.
"""
+import asyncio
import time
from datetime import datetime
from typing import Any, AsyncIterator
@@ -59,6 +61,8 @@ class _FakeChannel(ChannelBase):
self.status = ChannelStatus()
self.listened = False
self.closed = False
+ self.sent_to = ""
+ self.returned = False
@property
def channel_id(self) -> str:
@@ -81,7 +85,11 @@ class _FakeChannel(ChannelBase):
event: ChannelEvent,
events: AsyncIterator[dict],
) -> None:
- """No-op; delivery is not what these tests exercise."""
+ """Record the target, then consume the run's events."""
+ self.sent_to = event.chat_id
+ async for _ in events:
+ pass
+ self.returned = True
class _Storage:
@@ -124,6 +132,7 @@ class ChannelClientsTest(IsolatedAsyncioTestCase):
def _clients(self, storage: _Storage) -> ChannelClients:
return ChannelClients(
storage=storage,
+ message_bus=InMemoryMessageBus(),
type_registry=ChannelTypeRegistry([_FakeChannel]),
)
@@ -205,11 +214,67 @@ class ChannelClientsTest(IsolatedAsyncioTestCase):
"""A record whose class this process was not given is skipped."""
clients = ChannelClients(
storage=_Storage(_record()),
+ message_bus=InMemoryMessageBus(),
type_registry=ChannelTypeRegistry([]),
)
self.assertIsNone(await clients.get("chan-1"))
+class ChannelDeliveryTest(IsolatedAsyncioTestCase):
+ """Deliveries run in the background but stay owned."""
+
+ def _clients(self, bus: InMemoryMessageBus) -> ChannelClients:
+ return ChannelClients(
+ storage=_Storage(_record()),
+ message_bus=bus,
+ type_registry=ChannelTypeRegistry([_FakeChannel]),
+ )
+
+ async def _deliver(self, clients: ChannelClients) -> None:
+ await clients.deliver(
+ session_id="s-1",
+ channel_id="chan-1",
+ chat_id="chat-1",
+ agent_id="agent-x",
+ )
+
+ async def test_returns_while_the_reply_is_still_going_out(self) -> None:
+ """The caller is mid-run holding the session lock, so it must not
+ wait on the platform."""
+ bus = InMemoryMessageBus()
+ async with self._clients(bus) as clients:
+ await self._deliver(clients)
+ await asyncio.sleep(0.05)
+
+ channel = await clients.get("chan-1")
+ self.assertEqual(channel.sent_to, "chat-1")
+ self.assertFalse(channel.returned)
+
+ async def test_shutdown_cancels_a_delivery_in_flight(self) -> None:
+ """A delivery outliving the process would be an orphan."""
+ bus = InMemoryMessageBus()
+ clients = self._clients(bus)
+ async with clients:
+ await self._deliver(clients)
+ await asyncio.sleep(0.05)
+ channel = await clients.get("chan-1")
+ self.assertEqual(channel.sent_to, "chat-1")
+
+ self.assertFalse(channel.returned)
+ self.assertEqual(len(clients._deliveries), 0) # pylint: disable=W0212
+
+ async def test_an_unbuildable_channel_delivers_nothing(self) -> None:
+ """A disabled channel must not raise into the run."""
+ bus = InMemoryMessageBus()
+ storage = _Storage(_record(enabled=False))
+ async with ChannelClients(
+ storage=storage,
+ message_bus=bus,
+ type_registry=ChannelTypeRegistry([_FakeChannel]),
+ ) as clients:
+ await self._deliver(clients)
+
+
class ChannelStatusTest(IsolatedAsyncioTestCase):
"""Status is read from the heartbeat, not from local instances."""
diff --git a/tests/channel_stream_test.py b/tests/channel_stream_test.py
new file mode 100644
index 000000000..690f49089
--- /dev/null
+++ b/tests/channel_stream_test.py
@@ -0,0 +1,191 @@
+# -*- coding: utf-8 -*-
+"""Tests for the channel reply-delivery stream.
+
+``event_stream`` replaced a durable outbound queue: instead of handing
+a run off to whichever node held the channel's connection, the node
+running the agent reads the run's events off the bus and delivers them
+itself. Missing an event or replaying one twice is a lost or duplicated
+reply, and never terminating strands the session, so those are what
+these cover.
+"""
+import asyncio
+from contextlib import aclosing
+from unittest import IsolatedAsyncioTestCase
+
+from agentscope.app._bus_ops import publish_session_event
+from agentscope.app.channel._stream import open_reply_stream
+from agentscope.app.message_bus import InMemoryMessageBus
+from agentscope.event import (
+ ReplyEndEvent,
+ ReplyStartEvent,
+ RequireExternalExecutionEvent,
+ RequireUserConfirmEvent,
+)
+from agentscope.types import ReplyFinishedReason
+
+
+async def _drain(bus: InMemoryMessageBus, session_id: str) -> list[str]:
+ """Collect the stream's event types until it terminates."""
+ types: list[str] = []
+ stream = await open_reply_stream(bus, session_id)
+ async with aclosing(stream) as events:
+ async for evt in events:
+ types.append(evt.get("type", ""))
+ return types
+
+
+async def _publish(
+ bus: InMemoryMessageBus,
+ session_id: str,
+ event: object,
+) -> None:
+ """Publish one agent event onto the session's stream."""
+ await publish_session_event(
+ bus,
+ session_id,
+ event.model_dump(mode="json"),
+ )
+
+
+def _start() -> ReplyStartEvent:
+ """A reply-start event."""
+ return ReplyStartEvent(reply_id="r-1", session_id="s-1", name="a")
+
+
+def _end() -> ReplyEndEvent:
+ """A terminal reply-end event."""
+ return ReplyEndEvent(
+ reply_id="r-1",
+ session_id="s-1",
+ name="a",
+ finished_reason=ReplyFinishedReason.COMPLETED,
+ )
+
+
+def _confirm() -> RequireUserConfirmEvent:
+ """A run parked awaiting the user's approval."""
+ return RequireUserConfirmEvent(
+ reply_id="r-1",
+ session_id="s-1",
+ name="a",
+ tool_calls=[],
+ )
+
+
+def _external() -> RequireExternalExecutionEvent:
+ """A run parked awaiting an external executor."""
+ return RequireExternalExecutionEvent(
+ reply_id="r-1",
+ session_id="s-1",
+ name="a",
+ tool_calls=[],
+ )
+
+
+class _SeamBus(InMemoryMessageBus):
+ """Publishes an event while the replay read is in flight.
+
+ That reproduces the one case the stream deduplicates: an event
+ arriving after the subscription opened but before the replay
+ finished is written to the log *and* pushed to the live feed.
+ """
+
+ def __init__(self) -> None:
+ super().__init__()
+ self._seam_published = False
+
+ async def log_read(self, key: str, **kwargs: object) -> list:
+ """Slip one event into the window, then replay as usual."""
+ if not self._seam_published:
+ self._seam_published = True
+ await _publish(self, "s-1", _start())
+ return await super().log_read(key, **kwargs)
+
+
+class EventStreamTest(IsolatedAsyncioTestCase):
+ """The stream is gap-free and always terminates."""
+
+ async def test_replays_events_published_before_subscribing(
+ self,
+ ) -> None:
+ """A run that finished before delivery started is still sent —
+ this is what makes a late reader safe."""
+ bus = InMemoryMessageBus()
+ await _publish(bus, "s-1", _start())
+ await _publish(bus, "s-1", _end())
+
+ self.assertListEqual(
+ await _drain(bus, "s-1"),
+ ["REPLY_START", "REPLY_END"],
+ )
+
+ async def test_delivers_events_published_while_streaming(self) -> None:
+ """The common case: delivery starts first, events arrive after."""
+ bus = InMemoryMessageBus()
+
+ async def _run() -> None:
+ await asyncio.sleep(0.01)
+ await _publish(bus, "s-1", _start())
+ await _publish(bus, "s-1", _end())
+
+ drained, _ = await asyncio.gather(_drain(bus, "s-1"), _run())
+ self.assertListEqual(drained, ["REPLY_START", "REPLY_END"])
+
+ async def test_seam_events_are_not_delivered_twice(self) -> None:
+ """An event landing between subscribe and replay reaches the
+ stream both ways; it must be yielded once.
+
+ This is why the stream tracks entry ids, and the window is too
+ narrow to hit by timing, so the bus forces it.
+ """
+ bus = _SeamBus()
+ await _publish(bus, "s-1", _start())
+
+ async def _finish() -> None:
+ await asyncio.sleep(0.02)
+ await _publish(bus, "s-1", _end())
+
+ drained, _ = await asyncio.gather(_drain(bus, "s-1"), _finish())
+ self.assertListEqual(
+ drained,
+ ["REPLY_START", "REPLY_START", "REPLY_END"],
+ )
+
+ async def test_stops_at_the_terminal_event(self) -> None:
+ """Anything published after the run ended belongs to the next
+ reply, not this delivery."""
+ bus = InMemoryMessageBus()
+ await _publish(bus, "s-1", _start())
+ await _publish(bus, "s-1", _end())
+ await _publish(bus, "s-1", _start())
+
+ self.assertListEqual(
+ await _drain(bus, "s-1"),
+ ["REPLY_START", "REPLY_END"],
+ )
+
+ async def test_a_run_parked_on_confirmation_terminates(self) -> None:
+ """A parked run publishes no ``REPLY_END`` until it is resumed."""
+ bus = InMemoryMessageBus()
+ await _publish(bus, "s-1", _start())
+ await _publish(bus, "s-1", _confirm())
+
+ self.assertListEqual(
+ await asyncio.wait_for(_drain(bus, "s-1"), timeout=2.0),
+ ["REPLY_START", "REQUIRE_USER_CONFIRM"],
+ )
+
+ async def test_a_run_parked_on_external_execution_terminates(
+ self,
+ ) -> None:
+ """The same, for a tool executed outside the agent. Waiting for a
+ ``REPLY_END`` here would block delivery while the caller holds
+ the session lock, so nothing could resume the run."""
+ bus = InMemoryMessageBus()
+ await _publish(bus, "s-1", _start())
+ await _publish(bus, "s-1", _external())
+
+ self.assertListEqual(
+ await asyncio.wait_for(_drain(bus, "s-1"), timeout=2.0),
+ ["REPLY_START", "REQUIRE_EXTERNAL_EXECUTION"],
+ )
diff --git a/tests/service_chat_channel_delivery_test.py b/tests/service_chat_channel_delivery_test.py
new file mode 100644
index 000000000..9754f4657
--- /dev/null
+++ b/tests/service_chat_channel_delivery_test.py
@@ -0,0 +1,305 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access, using-constant-test
+"""A channel-bound run hands its reply to the channel runtime.
+
+The run's own node delivers the reply now, so what matters is that the
+run starts a delivery aimed at the right chat, and that the delivery
+still sees the whole reply when the run finishes before the channel
+starts reading — which is the normal case, a platform call being slower
+than the agent's last event.
+"""
+import asyncio
+from types import SimpleNamespace
+from typing import Any, AsyncGenerator, AsyncIterator
+from unittest import IsolatedAsyncioTestCase
+from unittest.mock import patch
+
+from pydantic import BaseModel
+
+from agentscope.agent import ContextConfig, ReActConfig
+from agentscope.app._service import ChatService
+from agentscope.app.channel import (
+ ChannelBase,
+ ChannelClients,
+ ChannelEvent,
+ ChannelStatus,
+ ChannelTypeRegistry,
+)
+from agentscope.app.message_bus import InMemoryMessageBus
+from agentscope.event import ReplyEndEvent, ReplyStartEvent
+from agentscope.types import ReplyFinishedReason
+from agentscope.message import TextBlock, UserMsg
+from agentscope.app.storage import (
+ AgentData,
+ AgentRecord,
+ ChannelBinding,
+ ChannelRecord,
+ ChatModelConfig,
+ RoutingConfig,
+ SessionConfig,
+ SessionRecord,
+ SessionSettings,
+ SessionSource,
+)
+
+
+class _RecordingChannel(ChannelBase):
+ """Captures the send target and the events it was fed."""
+
+ channel_type = "fake"
+ display_name = "Fake"
+ platform_bot_id_field = "bot_id"
+ instances: list["_RecordingChannel"] = []
+
+ class Credentials(BaseModel):
+ """Credentials for the fake platform."""
+
+ bot_id: str
+
+ class Config(BaseModel):
+ """Options for the fake platform."""
+
+ def __init__(
+ self,
+ channel_id: str,
+ credentials: "Credentials",
+ config: "Config", # pylint: disable=unused-argument
+ ) -> None:
+ """Register this instance so the test can inspect it."""
+ del credentials
+ self._channel_id = channel_id
+ self.status = ChannelStatus()
+ self.target: ChannelEvent | None = None
+ self.seen: list[str] = []
+ self.done = asyncio.Event()
+ _RecordingChannel.instances.append(self)
+
+ @property
+ def channel_id(self) -> str:
+ """The unique channel instance identifier."""
+ return self._channel_id
+
+ async def start_listening( # pylint: disable=unused-argument
+ self,
+ emit: Any,
+ ) -> None:
+ """Unused: this test only exercises the outbound half."""
+
+ async def send_response(
+ self,
+ event: ChannelEvent,
+ events: AsyncIterator[dict],
+ ) -> None:
+ """Record the target, then drain the run's events."""
+ self.target = event
+ async for evt in events:
+ self.seen.append(evt.get("type", ""))
+ self.done.set()
+
+
+class _Storage:
+ """Serve one channel-bound session, its agent, and its channel."""
+
+ def __init__(
+ self,
+ session: SessionRecord,
+ agent: AgentRecord,
+ channel: ChannelRecord,
+ ) -> None:
+ self.session = session
+ self.agent = agent
+ self.channel = channel
+
+ async def get_session(self, *_: object, **__: object) -> SessionRecord:
+ """Return a detached copy."""
+ return self.session.model_copy(deep=True)
+
+ async def get_agent(self, *_: object, **__: object) -> AgentRecord:
+ """Return a detached copy."""
+ return self.agent.model_copy(deep=True)
+
+ async def get_channel(self, *_: object, **__: object) -> ChannelRecord:
+ """Return the one channel this stub serves."""
+ return self.channel
+
+ async def update_session_state(self, *_: object, **__: object) -> None:
+ """Accept the post-run state persistence."""
+
+ async def upsert_message(self, *_: object, **__: object) -> None:
+ """Accept persisted reply messages."""
+
+
+class _WorkspaceManager:
+ """Return a minimal workspace handle."""
+
+ async def get_workspace(self, *_: object, **__: object) -> object:
+ """Return an inert workspace."""
+ return SimpleNamespace(workdir="/tmp/agentscope-delivery-test")
+
+
+class ChannelDeliveryFromTheRunTest(IsolatedAsyncioTestCase):
+ """The run starts the delivery; the channel runtime owns it."""
+
+ def setUp(self) -> None:
+ """Isolate the instances each test observes."""
+ _RecordingChannel.instances.clear()
+
+ def _fixture(self, source: SessionSource) -> tuple:
+ """Build a session of ``source`` plus its agent and channel."""
+ user_id = "user-1"
+ agent = AgentRecord(
+ id="agent-1",
+ user_id=user_id,
+ data=AgentData(
+ name="a",
+ context_config=ContextConfig(),
+ react_config=ReActConfig(),
+ ),
+ )
+ session = SessionRecord(
+ id="session-1",
+ user_id=user_id,
+ agent_id=agent.id,
+ source=source,
+ source_channel_id=(
+ "chan-1" if source is SessionSource.CHANNEL else None
+ ),
+ source_chat_id=(
+ "chat-1" if source is SessionSource.CHANNEL else None
+ ),
+ config=SessionConfig(
+ workspace_id="ws-1",
+ chat_model_config=ChatModelConfig(
+ type="test",
+ credential_id="cred-1",
+ model="m",
+ parameters={},
+ ),
+ ),
+ )
+ channel = ChannelRecord(
+ id="chan-1",
+ channel_type="fake",
+ user_id=user_id,
+ credentials={"bot_id": "bot-1"},
+ routing=RoutingConfig(
+ bindings=[ChannelBinding(match_value="*", agent_id=agent.id)],
+ ),
+ session=SessionSettings(chat_model_config={"type": "test"}),
+ created_at="t",
+ updated_at="t",
+ )
+ return user_id, agent, session, channel
+
+ async def _run(self, source: SessionSource) -> ChannelClients:
+ """Drive one run to completion and return the channel runtime."""
+ user_id, agent, session, channel = self._fixture(source)
+ storage = _Storage(session, agent, channel)
+ bus = InMemoryMessageBus()
+ clients = ChannelClients(
+ storage=storage,
+ message_bus=bus,
+ type_registry=ChannelTypeRegistry([_RecordingChannel]),
+ )
+
+ class _Agent:
+ """Reply with nothing; the run's own events are enough."""
+
+ def __init__(self, *, state: object = None, **_: object) -> None:
+ self.state = state
+
+ async def reply_stream(
+ self,
+ inputs: object,
+ ) -> AsyncGenerator[object, None]:
+ """Emit a minimal, well-formed reply."""
+ del inputs
+ yield ReplyStartEvent(
+ reply_id="r-1",
+ session_id="session-1",
+ name="a",
+ )
+ yield ReplyEndEvent(
+ reply_id="r-1",
+ session_id="session-1",
+ name="a",
+ finished_reason=ReplyFinishedReason.COMPLETED,
+ )
+
+ async def _get_toolkit(**_: object) -> object:
+ return object()
+
+ async def _get_model(*_: object, **__: object) -> object:
+ return object()
+
+ class _Access:
+ """Resolve the run's own agent."""
+
+ async def resolve_agent(self, *_: object) -> AgentRecord:
+ """Return a detached copy."""
+ return agent.model_copy(deep=True)
+
+ service = ChatService(
+ storage=storage,
+ workspace_manager=_WorkspaceManager(),
+ scheduler_manager=object(),
+ background_task_manager=object(),
+ message_bus=bus,
+ resource_access_service=_Access(),
+ custom_agent_cls=_Agent,
+ channel_clients=clients,
+ )
+ with (
+ patch(
+ "agentscope.app._service._chat.get_toolkit",
+ new=_get_toolkit,
+ ),
+ patch("agentscope.app._service._chat.get_model", new=_get_model),
+ ):
+ await service._run_impl(
+ user_id,
+ session.id,
+ agent.id,
+ UserMsg(name="u", content=[TextBlock(text="hi")]),
+ )
+ return clients
+
+ async def test_the_reply_reaches_the_chat_the_session_came_from(
+ self,
+ ) -> None:
+ """The run finishes before the channel starts reading, so the
+ delivery has to replay the log rather than miss the reply."""
+ clients = await self._run(SessionSource.CHANNEL)
+ try:
+ self.assertEqual(len(_RecordingChannel.instances), 1)
+ channel = _RecordingChannel.instances[0]
+ await asyncio.wait_for(channel.done.wait(), timeout=2.0)
+
+ assert channel.target is not None
+ self.assertDictEqual(
+ {
+ "chat_id": channel.target.chat_id,
+ "channel_id": channel.target.channel_id,
+ "metadata": channel.target.metadata,
+ "events": channel.seen,
+ },
+ {
+ "chat_id": "chat-1",
+ "channel_id": "chan-1",
+ "metadata": {
+ "session_id": "session-1",
+ "agent_id": "agent-1",
+ },
+ "events": ["REPLY_START", "REPLY_END"],
+ },
+ )
+ finally:
+ await clients.__aexit__(None, None, None)
+
+ async def test_a_web_session_delivers_nothing(self) -> None:
+ """Only a channel-originated run has a chat to reply into."""
+ clients = await self._run(SessionSource.USER)
+ try:
+ self.assertListEqual(_RecordingChannel.instances, [])
+ finally:
+ await clients.__aexit__(None, None, None)