Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
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.pyindex 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.pyindex 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.pyindex 755865e28..0c50bceab 100644--- a/src/agentscope/app/_service/_chat.py+++ b/src/agentscope/app/_service/_chat.py@@ -22,7 +22,6 @@ from fastapi import HTTPExceptionfrom .._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.CHANNELand session_record.source_channel_idand 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 = Nonediff --git a/src/agentscope/app/channel/_clients.py b/src/agentscope/app/channel/_clients.pyindex 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 inboundlong 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 borrowedit 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 aclosingfrom types import TracebackTypefrom ..._logging import logger+from ..message_bus import MessageBusfrom ..storage import StorageBase-from ._base import ChannelBase+from ._base import ChannelBase, ChannelEventfrom ._registry import ChannelTypeRegistry+from ._stream import open_reply_streamclass 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 froma record's type, credentials and config."""self._storage = storage+ self._bus = message_busself._types = type_registryself._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.pyindex 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 theAPI replicas have no dispatcher to ask, so status is published to thebus 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 asyncioimport socketimport time-from contextlib import aclosing, asynccontextmanager+from contextlib import asynccontextmanagerfrom dataclasses import dataclass-from typing import AsyncGenerator, AsyncIterator+from typing import AsyncIteratorfrom ..._logging import loggerfrom ..._utils._common import _generate_id-from ...event import EventTypefrom ..message_bus import MessageBus, MessageBusKeysfrom ..storage import ChannelRecord, StorageBasefrom ._base import (@@ -40,17 +35,10 @@ from ._base import (from ._gateway import ChannelGatewayfrom ._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},-)-@dataclassclass 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()@asynccontextmanagerasync 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:yieldfinally:- 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.pynew file mode 100644index 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+ passdiff --git a/src/agentscope/app/message_bus/_keys.py b/src/agentscope/app/message_bus/_keys.pyindex 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-methodsreturn 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-@classmethoddef 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-methodsuid=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)-@classmethoddef 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.pyindex 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 beable 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 asyncioimport timefrom datetime import datetimefrom typing import Any, AsyncIterator@@ -59,6 +61,8 @@ class _FakeChannel(ChannelBase):self.status = ChannelStatus()self.listened = Falseself.closed = False+ self.sent_to = ""+ self.returned = False@propertydef 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 = Trueclass _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.pynew file mode 100644index 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.pynew file mode 100644index 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)