Skip to content

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

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.py
index 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.py
index 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 time
from collections import OrderedDict
from dataclasses import dataclass, field
-from typing import Any, Self
+from typing import Any, Self, TYPE_CHECKING
import shortuuid
from pydantic import BaseModel, Field
@@ -17,6 +19,9 @@ from agentscope.permission import (
from agentscope.tool import ToolBase, ToolChunk
from agentscope._logging import logger
+if TYPE_CHECKING:
+ from ..message_bus import MessageBus
+
@dataclass
class 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 = False
mcp_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_id
async 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_bus
self.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.id
self.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:
continue
logger.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 += 1
return 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 self
async 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.py
index 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 asyncio
from 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 be
cancelled.
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_bus
self._registry = registry
self._bg_manager = bg_manager
- self._task: asyncio.Task | None = None
+ self._session_task: asyncio.Task | None = None
+ self._task_cancel_task: asyncio.Task | None = None
async 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 self
async 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-except
logger.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.py
index 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.py
index 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 participation
tools, 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 can
push 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.py
index 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-methods
async 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-methods
on_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 tid
diff --git a/src/agentscope/app/message_bus/_redis_message_bus.py b/src/agentscope/app/message_bus/_redis_message_bus.py
index 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.py
index 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-method
Args:
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 to
push 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's
completion 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 its
result to the session inbox + enqueue a wakeup.
- On cancellation (e.g. ``TaskStop``) or unhandled exception
+ On cancellation (e.g. ``ToolStop``) or unhandled exception
no result is delivered — the agent is left without a
completion notification in those edge cases.
"""
@@ -360,6 +360,7 @@ class ToolOffloadMiddleware(MiddlewareBase): # pylint: disable=abstract-method
session_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.py
index 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 ToolStop
from agentscope.app.message_bus import MessageBus
+from agentscope.message import ToolResultState
class _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; the
return 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 and
does 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.py
index 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.py
index 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.py
index 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.py
index 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.py
index 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)