Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
refactor(bg_task): refactor the background task manager for multiprocess and distributed deployment (#1849)
DavdGaof0da92fc6ae9
diff --git a/src/agentscope/app/_lifespan.py b/src/agentscope/app/_lifespan.pyindex c99bfef3a..6025c9b68 100644--- a/src/agentscope/app/_lifespan.py+++ b/src/agentscope/app/_lifespan.py@@ -40,7 +40,9 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]:await stack.enter_async_context(message_bus)await stack.enter_async_context(workspace_manager)- bg_manager = await stack.enter_async_context(BackgroundTaskManager())+ bg_manager = await stack.enter_async_context(+ BackgroundTaskManager(message_bus=message_bus),+ )app.state.background_task_manager = bg_manager# Per-process registry of in-flight chat-run asyncio tasks.diff --git a/src/agentscope/app/_manager/_background_task_manager.py b/src/agentscope/app/_manager/_background_task_manager.pyindex 6cf772b69..6394f90af 100644--- a/src/agentscope/app/_manager/_background_task_manager.py+++ b/src/agentscope/app/_manager/_background_task_manager.py@@ -1,9 +1,11 @@# -*- coding: utf-8 -*-"""The background task manager."""import asyncio+import json+import timefrom collections import OrderedDictfrom dataclasses import dataclass, field-from typing import Any, Self+from typing import Any, Self, TYPE_CHECKINGimport shortuuidfrom pydantic import BaseModel, Field@@ -17,6 +19,9 @@ from agentscope.permission import (from agentscope.tool import ToolBase, ToolChunkfrom agentscope._logging import logger+if TYPE_CHECKING:+ from ..message_bus import MessageBus+@dataclassclass BackgroundTask:@@ -31,6 +36,8 @@ class BackgroundTask:The name of the agent that created the task.user_id (`str`):The user id of the originating request.+ tool_name (`str`):+ The name of the tool that was offloaded.id (`str`):Auto-generated unique task identifier."""@@ -47,28 +54,35 @@ class BackgroundTask:user_id: str"""The user id of the originating request."""+ tool_name: str+ """The name of the offloaded tool."""+id: str = field(default_factory=shortuuid.uuid)"""The background task id."""-class _TaskStopParams(BaseModel):- """The params of the stop task."""+class _ToolStopParams(BaseModel):+ """The params of the stop tool."""task_id: str = Field(- description="The task id of the stop task.",+ description="The task id of the background tool to stop.",)-class TaskStop(ToolBase):- """A tool to stop a running background task."""+class ToolStop(ToolBase):+ """A tool to stop a running background tool execution."""- name: str = "TaskStop"+ name: str = "ToolStop""""The tool name."""- description: str = "Stop a background task by its task id."+ description: str = (+ "Stop a background tool execution by its task id. "+ "Use this when you want to cancel a previously offloaded tool "+ "that is still running in the background."+ )"""The tool description."""- input_schema: dict = _TaskStopParams.model_json_schema()+ input_schema: dict = _ToolStopParams.model_json_schema()"""The input schema."""is_concurrency_safe: bool = True@@ -78,15 +92,28 @@ class TaskStop(ToolBase):is_mcp: bool = Falsemcp_name: str | None = None- def __init__(self, background_tasks: dict[str, BackgroundTask]) -> None:- """Initialize the TaskStop tool.+ def __init__(+ self,+ background_tasks: dict[str, BackgroundTask],+ message_bus: "MessageBus",+ session_id: str,+ ) -> None:+ """Initialize the ToolStop tool.Args:background_tasks (`dict[str, BackgroundTask]`):- A reference to the background tasks managed by the- :class:`BackgroundTaskManager`.+ A reference to the local background tasks managed by+ the :class:`BackgroundTaskManager`.+ message_bus (`MessageBus`):+ The application message bus, used to check the global+ registry and broadcast cross-worker cancel requests.+ session_id (`str`):+ The current session id, used to scope Redis registry+ lookups."""self.background_tasks = background_tasks+ self._message_bus = message_bus+ self._session_id = session_idasync def check_permissions(self,@@ -121,30 +148,64 @@ class TaskStop(ToolBase):`ToolChunk`:The tool chunk."""- if task_id not in self.background_tasks:+ # Path 1: task is on this worker — cancel directly.+ # Only cancel when the task belongs to the same session as this+ # ToolStop instance, so a leaked/guessed task_id from another+ # session cannot trigger cross-session cancellation on a shared+ # worker.+ local_task = self.background_tasks.get(task_id)+ if (+ local_task is not None+ and local_task.session_id == self._session_id+ ):+ self.background_tasks.pop(task_id, None)+ local_task.asyncio_task.cancel()+ logger.info(+ "Background task stopped via ToolStop (local): task_id=%s, "+ "session_id=%s, agent_id=%s",+ task_id,+ local_task.session_id,+ local_task.agent_id,+ )+ return ToolChunk(+ content=[+ TextBlock(text=f"Task {task_id} stopped successfully."),+ ],+ state=ToolResultState.SUCCESS,+ )++ # Path 2: task exists in the global registry (another worker, or+ # a different session on this worker).+ if await self._message_bus.bg_task_exists(+ self._session_id,+ task_id,+ ):+ await self._message_bus.task_publish_cancel(task_id)+ logger.info(+ "Background task cancel broadcast via ToolStop (remote): "+ "task_id=%s, session_id=%s",+ task_id,+ self._session_id,+ )return ToolChunk(content=[TextBlock(- text=f"TaskNotFoundError: The task {task_id} "- f"does not exist.",+ text=f"Cancel request sent for task {task_id}. "+ f"The owning worker will stop it shortly.",),],- state=ToolResultState.ERROR,+ state=ToolResultState.SUCCESS,)- # Cancel and pop the task- task = self.background_tasks.pop(task_id)- task.asyncio_task.cancel()- logger.info(- "Background task stopped via TaskStop tool: task_id=%s, "- "session_id=%s, agent_id=%s",- task_id,- task.session_id,- task.agent_id,- )+ # Path 3: task not found anywhere.return ToolChunk(- content=[TextBlock(text=f"Task {task_id} stopped successfully.")],- state=ToolResultState.SUCCESS,+ content=[+ TextBlock(+ text=f"TaskNotFoundError: The task {task_id} "+ f"does not exist.",+ ),+ ],+ state=ToolResultState.ERROR,)@@ -153,19 +214,28 @@ class BackgroundTaskManager:Responsibilities:- - **Task registry**: track running tasks so they can be cancelled- via :class:`TaskStop` and on application shutdown.+ - **Global registry**: register/unregister tasks in Redis so any+ process can query which tasks are alive for a session.+ - **Local handle cache**: hold ``asyncio.Task`` references for+ cancel and shutdown.- **Task scheduling**: convenience method for creating a task from- a plain coroutine with an optional completion callback.+ a plain coroutine with a done callback that cleans up both sides.- Completion results are **not** stored here — producers deliver them- via the :class:`MessageBus` inbox + wakeup path (same as team- messages), so any process's :class:`WakeupDispatcher` can pick up- the result and drive the next chat run.+ Completion results are delivered via the :class:`MessageBus` inbox+ + wakeup path (same as team messages), so any process's+ :class:`WakeupDispatcher` can pick up the result."""- def __init__(self) -> None:- """Initialise the background task manager."""+ def __init__(self, message_bus: "MessageBus") -> None:+ """Initialise the background task manager.++ Args:+ message_bus (`MessageBus`):+ The application message bus; used for the global BG+ task registry (Redis Hash) and task-level cancel+ broadcasts.+ """+ self._message_bus = message_busself.tasks: OrderedDict[str, BackgroundTask] = OrderedDict()# ------------------------------------------------------------------@@ -178,14 +248,13 @@ class BackgroundTaskManager:session_id: str,agent_id: str,user_id: str,+ tool_name: str = "",) -> str:- """Register an already-running asyncio task and return its id.+ """Register an already-running asyncio task.- The task auto-removes from the registry when it finishes (via- ``add_done_callback``). Post-completion work (e.g. delivering- the result back through the message bus) is the caller's- responsibility — typically by spawning a separate watcher- coroutine that awaits the same task.+ Writes to both the local handle cache and the global Redis+ registry. The task auto-removes from both when it finishes+ (via ``add_done_callback``).Args:asyncio_task (`asyncio.Task`):@@ -196,6 +265,8 @@ class BackgroundTaskManager:The agent record id that owns the task.user_id (`str`):The user id of the originating request.+ tool_name (`str`, optional):+ The name of the offloaded tool.Returns:`str`:@@ -206,29 +277,95 @@ class BackgroundTaskManager:session_id=session_id,agent_id=agent_id,user_id=user_id,+ tool_name=tool_name,)task_id = bg_task.idself.tasks[task_id] = bg_task++ # Register in the global Redis registry.+ metadata = json.dumps(+ {+ "tool_name": tool_name,+ "agent_id": agent_id,+ "started_at": time.time(),+ },+ )+ await self._message_bus.bg_task_register(+ session_id,+ task_id,+ metadata,+ )+logger.info("Background task registered: task_id=%s, session_id=%s, "- "agent_id=%s",+ "agent_id=%s, tool_name=%s",task_id,session_id,agent_id,+ tool_name,)- asyncio_task.add_done_callback(- lambda _t: self.tasks.pop(task_id, None),- )++ def _on_done(_t: asyncio.Task) -> None:+ self.tasks.pop(task_id, None)+ # Schedule async Redis cleanup (fire-and-forget). Wrap in a+ # coroutine that logs failures so the bus error (e.g. Redis+ # connection drop) does not surface as+ # ``Task exception was never retrieved``.+ try:+ asyncio.ensure_future(+ self._safe_bg_task_unregister(session_id, task_id),+ )+ except RuntimeError:+ # Event loop already closed during shutdown.+ pass++ asyncio_task.add_done_callback(_on_done)return task_id- async def list_tools(self) -> list[ToolBase]:- """List the background tasks related tools.+ async def _safe_bg_task_unregister(+ self,+ session_id: str,+ task_id: str,+ ) -> None:+ """Unregister a finished background task, logging any failure.++ Args:+ session_id (`str`):+ The session id of the finished task.+ task_id (`str`):+ The task id to unregister from the global registry.+ """+ try:+ await self._message_bus.bg_task_unregister(+ session_id,+ task_id,+ )+ except Exception as e: # pylint: disable=broad-except+ logger.exception(+ "Failed to unregister background task from the global "+ "registry: task_id=%s, session_id=%s, error=%s",+ task_id,+ session_id,+ str(e),+ )++ # ------------------------------------------------------------------+ # Tool listing+ # ------------------------------------------------------------------++ async def list_tools(self, session_id: str) -> list[ToolBase]:+ """List the background task tools for a given session.++ Args:+ session_id (`str`):+ The current session id (for ToolStop's registry+ lookups).Returns:`list[ToolBase]`:- A list containing the :class:`TaskStop` tool.+ A list containing the :class:`ToolStop` tool."""- return [TaskStop(self.tasks)]+ return [ToolStop(self.tasks, self._message_bus, session_id)]# ------------------------------------------------------------------# Session-scoped cancel@@ -237,26 +374,13 @@ class BackgroundTaskManager:def cancel_session_tasks(self, session_id: str) -> int:"""Cancel every locally-tracked task whose owner session matches.- Called by :class:`CancelDispatcher` on each incoming cancel- broadcast. The dispatcher fires this on every process; each- process only cancels the tasks it actually holds, so a session- whose BG tasks all live on other processes is a silent no-op- here. Returns the number of tasks cancelled on this process so- callers can log the local effect.-- The matching tasks' ``add_done_callback`` from- :meth:`register_task` removes them from ``self.tasks`` once the- cancel actually takes effect, so no explicit pop is needed.- Watcher coroutines (e.g.- :class:`~agentscope.app._middleware.ToolOffloadMiddleware`'s- ``_deliver_when_done``) catch :class:`asyncio.CancelledError`- and skip result delivery, so cancelling here will not push a- stale inbox/wakeup for a session being deleted.+ Called by :class:`CancelDispatcher` on each incoming session+ cancel broadcast. Returns the number of tasks cancelled on this+ process.Args:session_id (`str`):- The session whose tasks should be cancelled on this- process.+ The session whose tasks should be cancelled.Returns:`int`:@@ -267,8 +391,8 @@ class BackgroundTaskManager:if bg_task.session_id != session_id:continuelogger.info(- "Cancelling background task for deleted/cancelled "- "session: task_id=%s, session_id=%s, agent_id=%s",+ "Cancelling background task for session cancel: "+ "task_id=%s, session_id=%s, agent_id=%s",bg_task.id,bg_task.session_id,bg_task.agent_id,@@ -277,6 +401,42 @@ class BackgroundTaskManager:cancelled += 1return cancelled+ # ------------------------------------------------------------------+ # Single-task cancel (called by CancelDispatcher on bus signal)+ # ------------------------------------------------------------------++ def cancel_task(self, task_id: str) -> bool:+ """Cancel a single locally-tracked task by its id.++ Called by :class:`CancelDispatcher` when a task-level cancel+ broadcast arrives. Returns whether the task was found and+ cancelled on this process.++ Args:+ task_id (`str`):+ The task to cancel.++ Returns:+ `bool`:+ ``True`` if the task was found locally and cancelled.+ """+ bg_task = self.tasks.get(task_id)+ if bg_task is None:+ return False+ logger.info(+ "Cancelling background task via bus signal: "+ "task_id=%s, session_id=%s, agent_id=%s",+ task_id,+ bg_task.session_id,+ bg_task.agent_id,+ )+ bg_task.asyncio_task.cancel()+ return True++ # ------------------------------------------------------------------+ # Lifecycle+ # ------------------------------------------------------------------+async def __aenter__(self) -> Self:"""Enter the async context. No setup required.@@ -286,12 +446,7 @@ class BackgroundTaskManager:return selfasync def __aexit__(self, *exc: object) -> None:- """Cancel all running background tasks on context exit.-- Each task's asyncio task is cancelled. Any watcher coroutine- awaiting these tasks will see ``CancelledError`` and skip its- post-completion work (e.g. result delivery).- """+ """Cancel all running background tasks on context exit."""count = len(self.tasks)logger.info("Shutting down BackgroundTaskManager: cancelling %d task(s).",diff --git a/src/agentscope/app/_manager/_cancel_dispatcher.py b/src/agentscope/app/_manager/_cancel_dispatcher.pyindex 999d0845a..86cff396f 100644--- a/src/agentscope/app/_manager/_cancel_dispatcher.py+++ b/src/agentscope/app/_manager/_cancel_dispatcher.py@@ -1,22 +1,17 @@# -*- coding: utf-8 -*--"""Single per-process dispatcher for cross-process session cancels.+"""Single per-process dispatcher for cross-process cancels.-Subscribes to the bus's shared cancel-broadcast channel. For each-incoming ``session_id``, performs every session-scoped cancel a worker-process can do locally:+Subscribes to two bus channels:-1. Look the session up in the local :class:`ChatRunRegistry` — if a- chat-run task is tracked here, cancel it.-2. Ask the local :class:`BackgroundTaskManager` to cancel every BG- task it tracks for that session.+1. **Session cancel** — cancel all local work for a session (chat run+ + all BG tasks). Triggered by session deletion or explicit abort.+2. **Task cancel** — cancel a single BG task by task_id. Triggered by+ the :class:`ToolStop` agent tool when the target task lives on a+ different worker.-Processes whose registry / BG-manager do not hold anything for the-session simply do no work — the publisher does not need to know which-worker holds which piece; it broadcasts and lets each holder self-select.--Symmetric to :class:`WakeupDispatcher`: both are one asyncio task per-process; one starts runs in response to wake-ups, the other ends them-in response to cancels.+Processes whose registry / BG-manager do not hold the targeted session+or task simply do no work — the publisher does not need to know which+worker holds what; it broadcasts and lets each holder self-select."""import asynciofrom typing import TYPE_CHECKING, Self@@ -30,22 +25,17 @@ if TYPE_CHECKING:class CancelDispatcher:- """Subscribes to the bus cancel channel and cancels every local- session-scoped task (chat run + BG tasks) on match.+ """Subscribes to bus cancel channels and cancels matching local+ tasks.Args:message_bus (`MessageBus`):- Application message bus. Used for- :meth:`~agentscope.app.message_bus.MessageBus.- session_subscribe_cancel`.+ Application message bus.registry (`ChatRunRegistry`):The per-process chat-run registry whose tasks may becancelled.bg_manager (`BackgroundTaskManager`):- The per-process background task manager. Its- :meth:`~BackgroundTaskManager.cancel_session_tasks` is- invoked on every incoming cancel; it returns silently when- no local BG task matches the session.+ The per-process background task manager."""def __init__(@@ -67,74 +57,72 @@ class CancelDispatcher:self._bus = message_busself._registry = registryself._bg_manager = bg_manager- self._task: asyncio.Task | None = None+ self._session_task: asyncio.Task | None = None+ self._task_cancel_task: asyncio.Task | None = Noneasync def __aenter__(self) -> Self:- """Start the dispatcher loop and wait until its bus- subscription is live.-- Blocking on the readiness signal means a process that publishes- a cancel immediately after the dispatcher starts will not lose- the message to a SUBSCRIBE/PUBLISH race.+ """Start both dispatcher loops and wait until their bus+ subscriptions are live.Returns:`Self`: This dispatcher instance."""- ready = asyncio.Event()- self._task = asyncio.create_task(- self._loop(ready),- name="cancel-dispatcher",+ session_ready = asyncio.Event()+ task_ready = asyncio.Event()++ self._session_task = asyncio.create_task(+ self._session_cancel_loop(session_ready),+ name="cancel-dispatcher:session",+ )+ self._task_cancel_task = asyncio.create_task(+ self._task_cancel_loop(task_ready),+ name="cancel-dispatcher:task",)- await ready.wait()++ await session_ready.wait()+ await task_ready.wait()return selfasync def __aexit__(self, *exc: object) -> None:- """Cancel the dispatcher loop on context exit."""- if self._task is None:- return- self._task.cancel()- try:- await self._task- except asyncio.CancelledError:- pass- self._task = None+ """Cancel both dispatcher loops on context exit."""+ for task in (self._session_task, self._task_cancel_task):+ if task is None:+ continue+ task.cancel()+ try:+ await task+ except asyncio.CancelledError:+ pass+ self._session_task = None+ self._task_cancel_task = None# ------------------------------------------------------------------- # Internals+ # Session-level cancel loop# ------------------------------------------------------------------- async def _loop(self, ready: asyncio.Event) -> None:- """Long-lived loop: yield each incoming cancel and act on it.+ async def _session_cancel_loop(self, ready: asyncio.Event) -> None:+ """Subscribe to session cancel channel and act on each signal.Args:ready (`asyncio.Event`):Signalled after the underlying SUBSCRIBE completes.- :meth:`__aenter__` blocks on this so callers can- publish a cancel immediately after start without- racing the subscription."""try:async for session_id in self._bus.session_subscribe_cancel(on_ready=ready.set,):- self._cancel_local(session_id)+ self._cancel_session(session_id)except Exception: # pylint: disable=broad-exceptlogger.exception(- "CancelDispatcher loop crashed; subscription ended.",+ "CancelDispatcher session-cancel loop crashed.",)+ finally:+ # Unblock ``__aenter__`` even if subscribe failed before+ # ``on_ready`` ran, so startup cannot deadlock.+ ready.set()- def _cancel_local(self, session_id: str) -> None:- """Cancel every locally-tracked task for ``session_id``.-- Fans out to:-- - the chat-run task in :class:`ChatRunRegistry`, if registered- on this process;- - every BG task in :class:`BackgroundTaskManager` whose owner- session matches.-- Both lookups are silent no-ops when the local process holds no- matching state.+ def _cancel_session(self, session_id: str) -> None:+ """Cancel every locally-tracked task for a session.Args:session_id (`str`):@@ -157,3 +145,34 @@ class CancelDispatcher:bg_cancelled,session_id,)++ # ------------------------------------------------------------------+ # Task-level cancel loop+ # ------------------------------------------------------------------++ async def _task_cancel_loop(self, ready: asyncio.Event) -> None:+ """Subscribe to the task cancel channel and act on each signal.++ Args:+ ready (`asyncio.Event`):+ Signalled after the underlying SUBSCRIBE completes.+ """+ try:+ async for task_id in self._bus.task_subscribe_cancel(+ on_ready=ready.set,+ ):+ cancelled = self._bg_manager.cancel_task(task_id)+ if cancelled:+ logger.info(+ "CancelDispatcher: cancelled local BG task %s "+ "via task-level broadcast.",+ task_id,+ )+ except Exception: # pylint: disable=broad-except+ logger.exception(+ "CancelDispatcher task-cancel loop crashed.",+ )+ finally:+ # Unblock ``__aenter__`` even if subscribe failed before+ # ``on_ready`` ran, so startup cannot deadlock.+ ready.set()diff --git a/src/agentscope/app/_service/_chat.py b/src/agentscope/app/_service/_chat.pyindex da7a82203..de5a2023a 100644--- a/src/agentscope/app/_service/_chat.py+++ b/src/agentscope/app/_service/_chat.py@@ -84,7 +84,7 @@ class ChatService:``Schedule*`` tools.background_task_manager (`BackgroundTaskManager`):Tracks offloaded long-running tool tasks. Also provides- the :class:`TaskStop` tool through+ the :class:`ToolStop` tool through:func:`get_toolkit`.message_bus (`MessageBus`):Application-wide message bus. Provides session-level@@ -234,7 +234,7 @@ class ChatService:)# ----------------------------------------------------------------- # 2. Toolkit (workspace tools + planning + TaskStop + schedule ++ # 2. Toolkit (workspace tools + planning + ToolStop + schedule +# team + extras + skills + mcps).# ----------------------------------------------------------------toolkit = await get_toolkit(diff --git a/src/agentscope/app/_service/_toolkit.py b/src/agentscope/app/_service/_toolkit.pyindex dcc45a1ef..fc34cb2f6 100644--- a/src/agentscope/app/_service/_toolkit.py+++ b/src/agentscope/app/_service/_toolkit.py@@ -3,7 +3,7 @@The single entry point :func:`get_toolkit` gathers every tool source —workspace builtins, MCPs, skills, planning tools (Task*), background-task-control (TaskStop), schedule control (Schedule*), team participation+control (ToolStop), schedule control (Schedule*), team participationtools, and caller-supplied extras — into one :class:`Toolkit`."""from typing import Any@@ -44,7 +44,7 @@ async def get_toolkit(1. Workspace builtins (Bash / Read / Write / Grep / …)2. Planning tools (:class:`TaskCreate` / :class:`TaskList` /:class:`TaskGet` / :class:`TaskUpdate`)- 3. Background-task control (:class:`TaskStop`, from+ 3. Background-task control (:class:`ToolStop`, from:meth:`BackgroundTaskManager.list_tools`)4. Schedule control (:class:`ScheduleCreate` / :class:`ScheduleView`/ :class:`ScheduleDelete` / :class:`ScheduleList`, from@@ -74,7 +74,7 @@ async def get_toolkit(persists schedules through it.background_task_manager (`BackgroundTaskManager`):Application background-task registry. Provides the- :class:`TaskStop` tool bound to its live task dict.+ :class:`ToolStop` tool bound to its live task dict.message_bus (`MessageBus`):Application message bus; passed to team tools so they canpush HintBlocks + wakeups when delivering inter-session@@ -110,7 +110,9 @@ optional):tools += [TaskCreate(), TaskList(), TaskGet(), TaskUpdate()]# Background-task control.- tools += await background_task_manager.list_tools()+ tools += await background_task_manager.list_tools(+ session_id=session_record.id,+ )# Schedule control. Requires a model config on this session because# ``ScheduleCreate`` records it into new ``ScheduleRecord`` instances.diff --git a/src/agentscope/app/message_bus/_base.py b/src/agentscope/app/message_bus/_base.pyindex 59985bff3..f818c4ce7 100644--- a/src/agentscope/app/message_bus/_base.py+++ b/src/agentscope/app/message_bus/_base.py@@ -364,6 +364,93 @@ class MessageBus(ABC): # pylint: disable=too-many-public-methods``True`` if some process holds the lock right now."""+ # ------------------------------------------------------------------+ # Mode F — registry map (hash-keyed namespace)+ # ------------------------------------------------------------------++ @abstractmethod+ async def registry_set(+ self,+ namespace: str,+ field: str,+ value: str,+ *,+ ttl_secs: int | None = None,+ ) -> None:+ """Set ``field`` to ``value`` in the registry at ``namespace``.++ If the namespace does not exist it is created. When+ ``ttl_secs`` is supplied, the namespace's TTL is refreshed+ (sliding) — individual fields do not carry independent TTLs.++ Args:+ namespace (`str`):+ Registry key (e.g. ``"agentscope:bg_tasks:sess123"``).+ field (`str`):+ Field name within the registry.+ value (`str`):+ Serialized value to store.+ ttl_secs (`int | None`, optional):+ Refresh the namespace expiry to this many seconds.+ """++ @abstractmethod+ async def registry_del(self, namespace: str, field: str) -> None:+ """Remove ``field`` from the registry at ``namespace``.++ A no-op when the field or namespace does not exist.++ Args:+ namespace (`str`):+ Registry key.+ field (`str`):+ Field to remove.+ """++ @abstractmethod+ async def registry_exists(self, namespace: str, field: str) -> bool:+ """Return whether ``field`` exists in the registry at+ ``namespace``.++ Args:+ namespace (`str`):+ Registry key.+ field (`str`):+ Field to check.++ Returns:+ `bool`:+ ``True`` if the field is present.+ """++ @abstractmethod+ async def registry_getall(+ self,+ namespace: str,+ ) -> dict[str, str]:+ """Return all field-value pairs in the registry at+ ``namespace``.++ Args:+ namespace (`str`):+ Registry key.++ Returns:+ `dict[str, str]`:+ All entries. Empty dict when the namespace is absent.+ """++ @abstractmethod+ async def registry_drop(self, namespace: str) -> None:+ """Delete the entire registry at ``namespace``.++ Idempotent: a no-op when the namespace does not exist.++ Args:+ namespace (`str`):+ Registry key to delete.+ """+# ==================================================================# Domain helpers — concrete on the base class so all backends# share the same key conventions and serialisation rules.@@ -586,12 +673,12 @@ class MessageBus(ABC): # pylint: disable=too-many-public-methodsasync def session_purge(self, session_id: str) -> None:"""Delete all per-session bus state.- Drops the events log and the inbox queue. The distributed- run-lock is intentionally not touched: callers must ensure no- run is in flight (e.g. by publishing cancel via- :meth:`session_publish_cancel` and polling- :meth:`is_locked` until it clears) before calling this.- Any residual lock key expires on its own after at most+ Drops the events log, the inbox queue, and the BG task+ registry. The distributed run-lock is intentionally not+ touched: callers must ensure no run is in flight (e.g. by+ publishing cancel via :meth:`session_publish_cancel` and+ polling :meth:`is_locked` until it clears) before calling+ this. Any residual lock key expires on its own after at most:attr:`_SESSION_RUN_TTL_SECS`.Idempotent: a no-op when the keys are already absent.@@ -602,6 +689,7 @@ class MessageBus(ABC): # pylint: disable=too-many-public-methods"""await self.log_trim(self._SESSION_EVENTS_KEY.format(sid=session_id))await self.queue_delete(self._INBOX_KEY.format(sid=session_id))+ await self.bg_task_purge(session_id)# Inbox -----------------------------------------------------------@@ -745,3 +833,157 @@ class MessageBus(ABC): # pylint: disable=too-many-public-methodson_ready=on_ready,):yield payload++ # Background task registry -------------------------------------------++ _BG_TASKS_KEY = "agentscope:bg_tasks:{sid}"+ """Per-session registry of in-flight background tasks."""++ _BG_TASKS_TTL_SECS = 86400+ """Fallback TTL for the per-session BG task registry (24 h).++ This TTL is *not* the primary cleanup path — finished tasks remove+ themselves via :meth:`bg_task_unregister` and session deletion+ triggers :meth:`bg_task_purge`. It is only a safety net for+ abandoned entries left behind by a crashed worker whose session is+ also never explicitly purged. Sized so that virtually every+ realistic long-running tool finishes (and unregisters) before the+ fallback kicks in, while still bounding orphan growth in Redis.+ """++ _TASK_CANCEL_KEY = "agentscope:task:cancel"+ """Pub/Sub channel for single-task cancel broadcasts."""++ async def bg_task_register(+ self,+ session_id: str,+ task_id: str,+ metadata: str,+ ) -> None:+ """Register a background task in the global registry.++ Args:+ session_id (`str`):+ The session that owns this task.+ task_id (`str`):+ Unique task identifier.+ metadata (`str`):+ JSON-serialized task metadata (e.g. ``tool_name``,+ ``agent_id``, ``started_at``).+ """+ await self.registry_set(+ self._BG_TASKS_KEY.format(sid=session_id),+ task_id,+ metadata,+ ttl_secs=self._BG_TASKS_TTL_SECS,+ )++ async def bg_task_unregister(+ self,+ session_id: str,+ task_id: str,+ ) -> None:+ """Remove a background task from the global registry.++ Args:+ session_id (`str`):+ The session that owns this task.+ task_id (`str`):+ Task identifier to remove.+ """+ await self.registry_del(+ self._BG_TASKS_KEY.format(sid=session_id),+ task_id,+ )++ async def bg_task_exists(+ self,+ session_id: str,+ task_id: str,+ ) -> bool:+ """Check whether a background task is registered.++ Args:+ session_id (`str`):+ The session that owns this task.+ task_id (`str`):+ Task identifier to check.++ Returns:+ `bool`:+ ``True`` if the task is in the registry.+ """+ return await self.registry_exists(+ self._BG_TASKS_KEY.format(sid=session_id),+ task_id,+ )++ async def bg_task_list(+ self,+ session_id: str,+ ) -> dict[str, str]:+ """List all background tasks for a session.++ Args:+ session_id (`str`):+ The session whose tasks to list.++ Returns:+ `dict[str, str]`:+ ``{task_id: metadata_json}`` for all registered tasks.+ """+ return await self.registry_getall(+ self._BG_TASKS_KEY.format(sid=session_id),+ )++ async def bg_task_purge(self, session_id: str) -> None:+ """Delete all background task entries for a session.++ Used during session deletion to clean up the registry in one+ shot. Actual task cancellation is handled separately by+ :class:`CancelDispatcher`.++ Args:+ session_id (`str`):+ The session whose registry to delete.+ """+ await self.registry_drop(+ self._BG_TASKS_KEY.format(sid=session_id),+ )++ async def task_publish_cancel(self, task_id: str) -> None:+ """Broadcast a cancel request for a single background task.++ Sent on a transient Pub/Sub channel; only processes that hold+ the target task react. Others ignore the message.++ Args:+ task_id (`str`):+ The task to cancel.+ """+ await self.publish(self._TASK_CANCEL_KEY, {"task_id": task_id})++ async def task_subscribe_cancel(+ self,+ *,+ on_ready: Callable[[], None] | None = None,+ ) -> AsyncGenerator[str, None]:+ """Subscribe to the task-level cancel channel.++ Yields task ids as cancel requests arrive.++ Args:+ on_ready (`Callable[[], None] | None`, optional):+ Forwarded to the underlying :meth:`subscribe`.++ Yields:+ `str`:+ The task id from each incoming cancel payload.+ """+ async for payload in self.subscribe(+ self._TASK_CANCEL_KEY,+ on_ready=on_ready,+ ):+ tid = payload.get("task_id")+ if isinstance(tid, str):+ yield tiddiff --git a/src/agentscope/app/message_bus/_redis_message_bus.py b/src/agentscope/app/message_bus/_redis_message_bus.pyindex 4016f3cdc..d6d6b8880 100644--- a/src/agentscope/app/message_bus/_redis_message_bus.py+++ b/src/agentscope/app/message_bus/_redis_message_bus.py@@ -379,6 +379,85 @@ class RedisMessageBus(MessageBus):# XTRIM MINID drops entries with id < before_id.await self._client.xtrim(key, minid=before_id)+ # ------------------------------------------------------------------+ # Mode F — registry map (hash-keyed namespace)+ # ------------------------------------------------------------------++ async def registry_set(+ self,+ namespace: str,+ field: str,+ value: str,+ *,+ ttl_secs: int | None = None,+ ) -> None:+ """Set ``field`` in the Redis Hash at ``namespace``.++ Args:+ namespace (`str`):+ Hash key.+ field (`str`):+ Hash field.+ value (`str`):+ Value to store.+ ttl_secs (`int | None`, optional):+ Refresh the key's expiry (sliding TTL).+ """+ await self._client.hset(namespace, field, value)+ if ttl_secs is not None:+ await self._client.expire(namespace, ttl_secs)++ async def registry_del(self, namespace: str, field: str) -> None:+ """Remove ``field`` from the Redis Hash at ``namespace``.++ Args:+ namespace (`str`):+ Hash key.+ field (`str`):+ Hash field to remove.+ """+ await self._client.hdel(namespace, field)++ async def registry_exists(self, namespace: str, field: str) -> bool:+ """Return whether ``field`` exists in the Hash at ``namespace``.++ Args:+ namespace (`str`):+ Hash key.+ field (`str`):+ Hash field to check.++ Returns:+ `bool`:+ ``True`` if the field exists.+ """+ return bool(await self._client.hexists(namespace, field))++ async def registry_getall(+ self,+ namespace: str,+ ) -> dict[str, str]:+ """Return all field-value pairs from the Hash at ``namespace``.++ Args:+ namespace (`str`):+ Hash key.++ Returns:+ `dict[str, str]`:+ All entries. Empty dict when the key is absent.+ """+ return await self._client.hgetall(namespace) or {}++ async def registry_drop(self, namespace: str) -> None:+ """Delete the entire Hash at ``namespace``.++ Args:+ namespace (`str`):+ Hash key to delete.+ """+ await self._client.delete(namespace)+# ------------------------------------------------------------------# Mode D — transient broadcast# ------------------------------------------------------------------diff --git a/src/agentscope/app/middleware/_tool_offload_middleware.py b/src/agentscope/app/middleware/_tool_offload_middleware.pyindex 044cc8604..10f966f31 100644--- a/src/agentscope/app/middleware/_tool_offload_middleware.py+++ b/src/agentscope/app/middleware/_tool_offload_middleware.py@@ -53,7 +53,7 @@ class ToolOffloadMiddleware(MiddlewareBase): # pylint: disable=abstract-methodArgs:bg_manager (`BackgroundTaskManager`):Application-level background task manager. Used to register- the running asyncio task so :class:`TaskStop` can target it.+ the running asyncio task so :class:`ToolStop` can target it.message_bus (`MessageBus`):Application message bus. The completion callback uses it topush the result HintBlock to the session's inbox and to@@ -116,7 +116,7 @@ class ToolOffloadMiddleware(MiddlewareBase): # pylint: disable=abstract-method- The running task is **not** cancelled.- It is registered with :attr:`_bg_manager` so that- :class:`TaskStop` can target it and shutdown can cancel it.+ :class:`ToolStop` can target it and shutdown can cancel it.- A separate watcher coroutine is spawned to await the task'scompletion and then push the result as a:class:`HintBlock` to the session inbox + enqueue a wakeup.@@ -239,7 +239,7 @@ class ToolOffloadMiddleware(MiddlewareBase): # pylint: disable=abstract-method"""Wait for the offloaded tool to finish, then push itsresult to the session inbox + enqueue a wakeup.- On cancellation (e.g. ``TaskStop``) or unhandled exception+ On cancellation (e.g. ``ToolStop``) or unhandled exceptionno result is delivered — the agent is left without acompletion notification in those edge cases."""@@ -360,6 +360,7 @@ class ToolOffloadMiddleware(MiddlewareBase): # pylint: disable=abstract-methodsession_id=session_id,agent_id=self._agent_id,user_id=self._user_id,+ tool_name=tool_name,)logger.info(diff --git a/tests/service_cancel_dispatcher_test.py b/tests/service_cancel_dispatcher_test.pyindex 6b2f0c4a1..7be20a881 100644--- a/tests/service_cancel_dispatcher_test.py+++ b/tests/service_cancel_dispatcher_test.py@@ -22,7 +22,9 @@ from agentscope.app._manager import (CancelDispatcher,ChatRunRegistry,)+from agentscope.app._manager._background_task_manager import ToolStopfrom agentscope.app.message_bus import MessageBus+from agentscope.message import ToolResultStateclass _FakeBus(MessageBus):@@ -35,6 +37,7 @@ class _FakeBus(MessageBus):def __init__(self) -> None:self._channels: dict[str, asyncio.Queue] = {}self._locks: set[str] = set()+ self._registries: dict[str, dict[str, str]] = {}def _channel(self, key: str) -> asyncio.Queue:return self._channels.setdefault(key, asyncio.Queue())@@ -117,6 +120,30 @@ class _FakeBus(MessageBus):async def is_locked(self, key: str) -> bool:return key in self._locks+ # Mode F — registry (in-memory dict)+ async def registry_set(+ self,+ namespace: str,+ field: str,+ value: str,+ *,+ ttl_secs: int | None = None,+ ) -> None:+ self._registries.setdefault(namespace, {})[field] = value++ async def registry_del(self, namespace: str, field: str) -> None:+ if namespace in self._registries:+ self._registries[namespace].pop(field, None)++ async def registry_exists(self, namespace: str, field: str) -> bool:+ return field in self._registries.get(namespace, {})++ async def registry_getall(self, namespace: str) -> dict[str, str]:+ return dict(self._registries.get(namespace, {}))++ async def registry_drop(self, namespace: str) -> None:+ self._registries.pop(namespace, None)+async def _yield_a_few_times(ticks: int = 8) -> None:"""Yield the event loop a few times so spawned tasks make progress."""@@ -141,7 +168,7 @@ class TestCancelDispatcher(IsolatedAsyncioTestCase):cancels the registered asyncio task."""bus = _FakeBus()registry = ChatRunRegistry()- bg_manager = BackgroundTaskManager()+ bg_manager = BackgroundTaskManager(message_bus=bus)async with bg_manager, registry, CancelDispatcher(message_bus=bus,@@ -167,7 +194,7 @@ class TestCancelDispatcher(IsolatedAsyncioTestCase):cancels each of them; tasks for other sessions are untouched."""bus = _FakeBus()registry = ChatRunRegistry()- bg_manager = BackgroundTaskManager()+ bg_manager = BackgroundTaskManager(message_bus=bus)async with bg_manager, registry, CancelDispatcher(message_bus=bus,@@ -215,7 +242,7 @@ class TestCancelDispatcher(IsolatedAsyncioTestCase):ignored — no exception, no spurious cancel."""bus = _FakeBus()registry = ChatRunRegistry()- bg_manager = BackgroundTaskManager()+ bg_manager = BackgroundTaskManager(message_bus=bus)async with bg_manager, registry, CancelDispatcher(message_bus=bus,@@ -252,7 +279,7 @@ class TestCancelDispatcher(IsolatedAsyncioTestCase):and the local BG task(s) for the session, not just one."""bus = _FakeBus()registry = ChatRunRegistry()- bg_manager = BackgroundTaskManager()+ bg_manager = BackgroundTaskManager(message_bus=bus)async with bg_manager, registry, CancelDispatcher(message_bus=bus,@@ -288,7 +315,7 @@ class TestBackgroundTaskManagerCancelSessionTasks(IsolatedAsyncioTestCase):async def test_cancels_only_matching_session(self) -> None:"""Only tasks whose ``session_id`` matches are cancelled; thereturn value reports the local count."""- bg_manager = BackgroundTaskManager()+ bg_manager = BackgroundTaskManager(message_bus=_FakeBus())async with bg_manager:task_a = asyncio.create_task(_NeverEndingCoro.run())task_b = asyncio.create_task(_NeverEndingCoro.run())@@ -319,7 +346,7 @@ class TestBackgroundTaskManagerCancelSessionTasks(IsolatedAsyncioTestCase):async def test_no_matches_returns_zero(self) -> None:"""A session with no locally-registered tasks returns 0 anddoes no work."""- bg_manager = BackgroundTaskManager()+ bg_manager = BackgroundTaskManager(message_bus=_FakeBus())async with bg_manager:task = asyncio.create_task(_NeverEndingCoro.run())await bg_manager.register_task(@@ -334,3 +361,103 @@ class TestBackgroundTaskManagerCancelSessionTasks(IsolatedAsyncioTestCase):0,)self.assertFalse(task.cancelled())+++class TestToolStopRemoteCancel(IsolatedAsyncioTestCase):+ """Verifies the cross-worker cancel path of :class:`ToolStop`.++ A "worker A" registers a BG task in the shared bus registry, and a+ "worker B" — which has the task only in the global registry, not in+ its local cache — issues ``ToolStop``. The dispatcher on worker A+ must receive the broadcast and cancel the task locally.+ """++ async def test_remote_cancel_via_toolstop_broadcast(self) -> None:+ """ToolStop on a worker without the task publishes a task-level+ cancel; the owning worker's CancelDispatcher cancels the task."""+ bus = _FakeBus()++ # Worker A — owns the task and runs CancelDispatcher.+ bg_manager_owner = BackgroundTaskManager(message_bus=bus)+ registry_owner = ChatRunRegistry()++ # Worker B — only sees the task via the shared registry.+ bg_manager_caller = BackgroundTaskManager(message_bus=bus)++ async with bg_manager_owner, registry_owner, CancelDispatcher(+ message_bus=bus,+ registry=registry_owner,+ bg_manager=bg_manager_owner,+ ), bg_manager_caller:+ owned_task = asyncio.create_task(_NeverEndingCoro.run())+ task_id = await bg_manager_owner.register_task(+ owned_task,+ session_id="sess-shared",+ agent_id="agent",+ user_id="u",+ tool_name="LongRunningTool",+ )++ # Worker B's ToolStop: task_id is in the global registry but+ # not in worker B's local cache, so the remote-cancel path+ # is taken.+ tool_stop = ToolStop(+ background_tasks=bg_manager_caller.tasks,+ message_bus=bus,+ session_id="sess-shared",+ )+ chunk = await tool_stop(task_id=task_id)++ self.assertEqual(chunk.state, ToolResultState.SUCCESS)+ self.assertIn(+ "Cancel request sent",+ chunk.content[0].text,+ )++ for _ in range(50):+ if owned_task.cancelled() or owned_task.done():+ break+ await asyncio.sleep(0.01)++ self.assertTrue(owned_task.cancelled() or owned_task.done())++ async def test_toolstop_does_not_cancel_other_session_locally(+ self,+ ) -> None:+ """A ToolStop instance bound to session A must not cancel a+ locally-tracked task that belongs to session B, even if the+ guessed task_id is correct."""+ bus = _FakeBus()+ bg_manager = BackgroundTaskManager(message_bus=bus)++ async with bg_manager:+ victim_task = asyncio.create_task(_NeverEndingCoro.run())+ victim_task_id = await bg_manager.register_task(+ victim_task,+ session_id="sess-victim",+ agent_id="agent-v",+ user_id="u",+ )++ # ToolStop is bound to a *different* session; it should not+ # cancel ``victim_task`` directly. The shared registry is+ # also keyed by the bound session id, so the lookup misses+ # and we fall through to "not found".+ tool_stop = ToolStop(+ background_tasks=bg_manager.tasks,+ message_bus=bus,+ session_id="sess-attacker",+ )+ chunk = await tool_stop(task_id=victim_task_id)++ await _yield_a_few_times()++ self.assertEqual(chunk.state, ToolResultState.ERROR)+ self.assertIn(+ "TaskNotFoundError",+ chunk.content[0].text,+ )+ self.assertFalse(victim_task.cancelled())+ self.assertIn(victim_task_id, bg_manager.tasks)++ victim_task.cancel()diff --git a/tests/service_inbox_middleware_test.py b/tests/service_inbox_middleware_test.pyindex e1a9cd1f6..93833da5a 100644--- a/tests/service_inbox_middleware_test.py+++ b/tests/service_inbox_middleware_test.py@@ -127,6 +127,29 @@ class _FakeBus(MessageBus):async def is_locked(self, key: str) -> bool:raise NotImplementedError+ # Mode F — registry (unused)+ async def registry_set(+ self,+ namespace: str,+ field: str,+ value: str,+ *,+ ttl_secs: int | None = None,+ ) -> None:+ raise NotImplementedError++ async def registry_del(self, namespace: str, field: str) -> None:+ raise NotImplementedError++ async def registry_exists(self, namespace: str, field: str) -> bool:+ raise NotImplementedError++ async def registry_getall(self, namespace: str) -> dict[str, str]:+ raise NotImplementedError++ async def registry_drop(self, namespace: str) -> None:+ raise NotImplementedError+def _make_agent(*,diff --git a/tests/service_message_bus_test.py b/tests/service_message_bus_test.pyindex 5bcdd2be3..309462280 100644--- a/tests/service_message_bus_test.py+++ b/tests/service_message_bus_test.py@@ -364,6 +364,214 @@ class TestInboxAndWakeupHelpers(IsolatedAsyncioTestCase):)+class TestRegistryPrimitive(IsolatedAsyncioTestCase):+ """Mode F — ``registry_*`` hash-keyed namespace operations."""++ async def asyncSetUp(self) -> None:+ self.fr = fakeredis.aioredis.FakeRedis(decode_responses=True)+ self._stack = AsyncExitStack()+ self.bus = await self._stack.enter_async_context(_make_bus(self.fr))++ async def asyncTearDown(self) -> None:+ await self._stack.aclose()+ await self.fr.aclose()++ async def test_set_then_exists_and_getall(self) -> None:+ """``registry_set`` stores a field under a namespace; ``exists``+ is True, ``getall`` returns the full mapping."""+ await self.bus.registry_set("ns", "f1", "v1")+ await self.bus.registry_set("ns", "f2", "v2")++ self.assertTrue(await self.bus.registry_exists("ns", "f1"))+ self.assertTrue(await self.bus.registry_exists("ns", "f2"))+ self.assertFalse(await self.bus.registry_exists("ns", "missing"))+ self.assertFalse(await self.bus.registry_exists("other-ns", "f1"))++ self.assertEqual(+ await self.bus.registry_getall("ns"),+ {"f1": "v1", "f2": "v2"},+ )++ async def test_set_overwrites_existing_field(self) -> None:+ """A second ``registry_set`` for the same field overwrites the+ previous value (``HSET`` semantics)."""+ await self.bus.registry_set("ns", "f", "v1")+ await self.bus.registry_set("ns", "f", "v2")+ self.assertEqual(+ await self.bus.registry_getall("ns"),+ {"f": "v2"},+ )++ async def test_del_removes_only_the_named_field(self) -> None:+ """``registry_del`` removes a single field; siblings survive."""+ await self.bus.registry_set("ns", "keep", "k")+ await self.bus.registry_set("ns", "drop", "d")++ await self.bus.registry_del("ns", "drop")++ self.assertFalse(await self.bus.registry_exists("ns", "drop"))+ self.assertTrue(await self.bus.registry_exists("ns", "keep"))+ self.assertEqual(+ await self.bus.registry_getall("ns"),+ {"keep": "k"},+ )++ async def test_del_missing_field_is_noop(self) -> None:+ """Deleting a non-existent field does not raise."""+ await self.bus.registry_del("ns", "nope")+ await self.bus.registry_set("ns", "keep", "k")+ await self.bus.registry_del("ns", "still-missing")+ self.assertEqual(+ await self.bus.registry_getall("ns"),+ {"keep": "k"},+ )++ async def test_getall_on_missing_namespace_returns_empty_dict(+ self,+ ) -> None:+ """``registry_getall`` for an unknown namespace returns ``{}``+ rather than ``None``."""+ self.assertEqual(await self.bus.registry_getall("ghost"), {})++ async def test_drop_deletes_entire_namespace(self) -> None:+ """``registry_drop`` removes every field under the namespace."""+ await self.bus.registry_set("ns", "f1", "v1")+ await self.bus.registry_set("ns", "f2", "v2")++ await self.bus.registry_drop("ns")++ self.assertFalse(await self.bus.registry_exists("ns", "f1"))+ self.assertFalse(await self.bus.registry_exists("ns", "f2"))+ self.assertEqual(await self.bus.registry_getall("ns"), {})++ async def test_drop_missing_namespace_is_noop(self) -> None:+ """Dropping a namespace that was never written does not raise."""+ await self.bus.registry_drop("never-existed")++ async def test_set_with_ttl_applies_expire_and_refreshes(self) -> None:+ """``registry_set`` with ``ttl_secs`` sets a TTL on the hash key;+ a subsequent set with a longer ``ttl_secs`` refreshes it."""+ await self.bus.registry_set("ns", "f", "v", ttl_secs=60)+ ttl_first = await self.fr.ttl("ns")+ self.assertGreater(ttl_first, 0)+ self.assertLessEqual(ttl_first, 60)++ # Refresh with a much larger TTL — must overwrite the old one.+ await self.bus.registry_set("ns", "f", "v", ttl_secs=3600)+ ttl_refreshed = await self.fr.ttl("ns")+ self.assertGreater(ttl_refreshed, 60)++ async def test_set_without_ttl_leaves_namespace_persistent(+ self,+ ) -> None:+ """Without ``ttl_secs`` the namespace has no expiry (TTL == -1)."""+ await self.bus.registry_set("ns", "f", "v")+ self.assertEqual(await self.fr.ttl("ns"), -1)+++class TestBackgroundTaskRegistryHelpers(IsolatedAsyncioTestCase):+ """Domain helpers built on Mode F: ``bg_task_register / unregister /+ exists / list / purge`` plus ``task_publish_cancel /+ task_subscribe_cancel``."""++ async def asyncSetUp(self) -> None:+ self.fr = fakeredis.aioredis.FakeRedis(decode_responses=True)+ self._stack = AsyncExitStack()+ self.bus = await self._stack.enter_async_context(_make_bus(self.fr))++ async def asyncTearDown(self) -> None:+ await self._stack.aclose()+ await self.fr.aclose()++ async def test_register_then_exists_list_unregister(self) -> None:+ """End-to-end registry round-trip for a single session."""+ sid = "s-bg"++ self.assertFalse(await self.bus.bg_task_exists(sid, "t1"))++ await self.bus.bg_task_register(sid, "t1", '{"tool":"a"}')+ await self.bus.bg_task_register(sid, "t2", '{"tool":"b"}')++ self.assertTrue(await self.bus.bg_task_exists(sid, "t1"))+ self.assertTrue(await self.bus.bg_task_exists(sid, "t2"))+ self.assertEqual(+ await self.bus.bg_task_list(sid),+ {"t1": '{"tool":"a"}', "t2": '{"tool":"b"}'},+ )++ await self.bus.bg_task_unregister(sid, "t1")+ self.assertFalse(await self.bus.bg_task_exists(sid, "t1"))+ self.assertTrue(await self.bus.bg_task_exists(sid, "t2"))+ self.assertEqual(+ await self.bus.bg_task_list(sid),+ {"t2": '{"tool":"b"}'},+ )++ async def test_register_isolates_sessions(self) -> None:+ """Tasks registered under one session id are invisible to other+ session ids."""+ await self.bus.bg_task_register("s1", "t", "{}")++ self.assertTrue(await self.bus.bg_task_exists("s1", "t"))+ self.assertFalse(await self.bus.bg_task_exists("s2", "t"))+ self.assertEqual(await self.bus.bg_task_list("s2"), {})++ async def test_register_applies_fallback_ttl(self) -> None:+ """``bg_task_register`` sets the per-session fallback TTL on the+ hash key so abandoned entries can't accumulate forever."""+ sid = "s-ttl"+ await self.bus.bg_task_register(sid, "t", "{}")++ ttl = await self.fr.ttl(self.bus._BG_TASKS_KEY.format(sid=sid))+ self.assertGreater(ttl, 0)+ self.assertLessEqual(ttl, self.bus._BG_TASKS_TTL_SECS)++ # A second register-call refreshes the TTL back near the cap.+ await asyncio.sleep(0) # let any fakeredis internals settle+ await self.bus.bg_task_register(sid, "t2", "{}")+ ttl_refreshed = await self.fr.ttl(+ self.bus._BG_TASKS_KEY.format(sid=sid),+ )+ self.assertGreater(ttl_refreshed, 0)++ async def test_purge_clears_all_session_entries(self) -> None:+ """``bg_task_purge`` deletes every task entry for a session in+ a single call (used during session deletion)."""+ sid = "s-purge"+ await self.bus.bg_task_register(sid, "t1", "{}")+ await self.bus.bg_task_register(sid, "t2", "{}")+ # Other session must survive.+ await self.bus.bg_task_register("s-keep", "t", "{}")++ await self.bus.bg_task_purge(sid)++ self.assertEqual(await self.bus.bg_task_list(sid), {})+ self.assertFalse(await self.bus.bg_task_exists(sid, "t1"))+ self.assertTrue(await self.bus.bg_task_exists("s-keep", "t"))++ async def test_task_publish_cancel_reaches_subscriber(self) -> None:+ """``task_publish_cancel`` fans out to every active+ ``task_subscribe_cancel`` listener; the yielded value is the+ ``task_id`` from the payload."""+ ready = asyncio.Event()+ received: list[str] = []++ async def _consumer() -> None:+ async for tid in self.bus.task_subscribe_cancel(+ on_ready=ready.set,+ ):+ received.append(tid)+ break++ task = asyncio.create_task(_consumer())+ await asyncio.wait_for(ready.wait(), timeout=2.0)++ await self.bus.task_publish_cancel("task-X")+ await asyncio.wait_for(task, timeout=2.0)++ self.assertEqual(received, ["task-X"])++class TestBaseClassIsAbstract(IsolatedAsyncioTestCase):"""``MessageBus`` itself cannot be instantiated."""diff --git a/tests/service_toolkit_test.py b/tests/service_toolkit_test.pyindex c132d164d..47589e220 100644--- a/tests/service_toolkit_test.py+++ b/tests/service_toolkit_test.py@@ -8,7 +8,7 @@ Verifies the assembly rules:- workspace builtins are always included;- the four ``Task*`` planning tools are always included;-- :class:`TaskStop` (from ``BackgroundTaskManager``) is always included;+- :class:`ToolStop` (from ``BackgroundTaskManager``) is always included;- the four ``Schedule*`` tools only when ``session.config.chat_model_config``is set (they need a model to fire new runs with);- team tools are role-gated by ``agent_record.source``: ``"team"`` →@@ -146,7 +146,7 @@ class TestGetToolkitBaseAssembly(IsolatedAsyncioTestCase):async def test_user_agent_gets_all_sources(self) -> None:"""A user-owned agent receives workspace, planning, scheduling,- TaskStop, and the four leader-side team tools."""+ ToolStop, and the four leader-side team tools."""agent = _make_agent(source="user")session = _make_session(user_id="u",@@ -170,7 +170,9 @@ class TestGetToolkitBaseAssembly(IsolatedAsyncioTestCase):storage=_NoOpStorage(), # type: ignore[arg-type]message_bus=_NullBus(), # type: ignore[arg-type]),- background_task_manager=BackgroundTaskManager(),+ background_task_manager=BackgroundTaskManager(+ message_bus=_NullBus(), # type: ignore[arg-type]+ ),message_bus=_NullBus(), # type: ignore[arg-type]user_id="u",agent_record=agent,@@ -186,7 +188,7 @@ class TestGetToolkitBaseAssembly(IsolatedAsyncioTestCase):{"TaskCreate", "TaskList", "TaskGet", "TaskUpdate"} <= names,)# Background task control present.- self.assertIn("TaskStop", names)+ self.assertIn("ToolStop", names)# Schedule control present (model_config is set).self.assertTrue({@@ -222,7 +224,9 @@ class TestGetToolkitWorkerVariant(IsolatedAsyncioTestCase):storage=_NoOpStorage(), # type: ignore[arg-type]message_bus=_NullBus(), # type: ignore[arg-type]),- background_task_manager=BackgroundTaskManager(),+ background_task_manager=BackgroundTaskManager(+ message_bus=_NullBus(), # type: ignore[arg-type]+ ),message_bus=_NullBus(), # type: ignore[arg-type]user_id="u",agent_record=agent,@@ -256,7 +260,9 @@ class TestGetToolkitSchedulingGuard(IsolatedAsyncioTestCase):storage=_NoOpStorage(), # type: ignore[arg-type]message_bus=_NullBus(), # type: ignore[arg-type]),- background_task_manager=BackgroundTaskManager(),+ background_task_manager=BackgroundTaskManager(+ message_bus=_NullBus(), # type: ignore[arg-type]+ ),message_bus=_NullBus(), # type: ignore[arg-type]user_id="u",agent_record=agent,@@ -309,7 +315,9 @@ class TestGetToolkitExtraFactory(IsolatedAsyncioTestCase):storage=_NoOpStorage(), # type: ignore[arg-type]message_bus=_NullBus(), # type: ignore[arg-type]),- background_task_manager=BackgroundTaskManager(),+ background_task_manager=BackgroundTaskManager(+ message_bus=_NullBus(), # type: ignore[arg-type]+ ),message_bus=_NullBus(), # type: ignore[arg-type]user_id="u",agent_record=agent,diff --git a/tests/service_wakeup_dispatcher_test.py b/tests/service_wakeup_dispatcher_test.pyindex f262c8ffb..6a2aa53ae 100644--- a/tests/service_wakeup_dispatcher_test.py+++ b/tests/service_wakeup_dispatcher_test.py@@ -148,6 +148,31 @@ class _FakeBus(MessageBus):async def is_locked(self, key: str) -> bool:return key in self._locks+ # Mode F — registry (unused by WakeupDispatcher; raise so any+ # accidental dependency surfaces immediately rather than silently+ # passing through a stub).+ async def registry_set(+ self,+ namespace: str,+ field: str,+ value: str,+ *,+ ttl_secs: int | None = None,+ ) -> None:+ raise NotImplementedError++ async def registry_del(self, namespace: str, field: str) -> None:+ raise NotImplementedError++ async def registry_exists(self, namespace: str, field: str) -> bool:+ raise NotImplementedError++ async def registry_getall(self, namespace: str) -> dict[str, str]:+ raise NotImplementedError++ async def registry_drop(self, namespace: str) -> None:+ raise NotImplementedError+class _FakeChatService:"""Records calls to :meth:`run` so tests can assert dispatch."""diff --git a/tests/tool_offload_middleware_test.py b/tests/tool_offload_middleware_test.pyindex 1542de632..f03d75354 100644--- a/tests/tool_offload_middleware_test.py+++ b/tests/tool_offload_middleware_test.py@@ -152,7 +152,9 @@ class ToolOffloadMiddlewareTest(IsolatedAsyncioTestCase):async def asyncSetUp(self) -> None:"""Set up test fixtures."""self.mock_model = MockModel()- self.bg_manager = BackgroundTaskManager()+ self.bg_manager = BackgroundTaskManager(+ message_bus=MagicMock(spec=MessageBus),+ )# ------------------------------------------------------------------# Helper@@ -345,8 +347,8 @@ class ToolOffloadMiddlewareTest(IsolatedAsyncioTestCase):agent_id="a",)- async def test_task_stop_cancels_background_task(self) -> None:- """TaskStop tool cancels the running background asyncio task."""+ async def test_tool_stop_cancels_background_task(self) -> None:+ """ToolStop tool cancels the running background asyncio task."""toolkit = Toolkit(tools=[SlowTool()])agent, _ = self._make_agent(toolkit, timeout_secs=0.05)@@ -364,12 +366,16 @@ class ToolOffloadMiddlewareTest(IsolatedAsyncioTestCase):self.assertEqual(len(self.bg_manager.tasks), 1)task_id = next(iter(self.bg_manager.tasks))- asyncio_task = self.bg_manager.tasks[task_id].asyncio_task+ bg_task = self.bg_manager.tasks[task_id]+ asyncio_task = bg_task.asyncio_task- # Call TaskStop- task_stop_tools = await self.bg_manager.list_tools()- task_stop = task_stop_tools[0]- result = await task_stop(task_id=task_id)+ # Call ToolStop bound to the same session as the registered+ # background task, so the local cancel path matches.+ tool_stop_tools = await self.bg_manager.list_tools(+ session_id=bg_task.session_id,+ )+ tool_stop = tool_stop_tools[0]+ result = await tool_stop(task_id=task_id)text = result.content[0].text # type: ignore[union-attr]self.assertIn("stopped successfully", text)