feat(service): expose background tasks via REST endpoints

[XiuShenAl]

AgentScope Version

2.0.1

Description

Background

ToolOffloadMiddleware offloads tool calls that exceed the timeout to background asyncio tasks. However, there was no REST endpoint for the frontend to observe the status of these background tasks, leaving users unaware of ongoing or recently-completed executions (issue #1720).

Changes

• BackgroundTask dataclass — added five fields: summary (≤128-char human-readable invocation summary), started_at (Unix epoch), completed_at, status (TaskStatus enum: running / completed / failed / cancelled), and error_summary.
• TaskStatus enum — new str enum tracking the full task lifecycle.
• _on_done callback — rewritten from "remove on completion" to "update status + capacity-based eviction". Terminal-state tasks are retained (up to _MAX_RETAINED_TASKS = 50) so frontends can observe outcomes via polling.
• BackgroundTaskManager — added list_tasks(user_id, session_id?) and get_task(task_id, user_id) query methods; register_task gains a summary keyword argument (backward-compatible default "").
• ToolOffloadMiddleware — added _make_summary helper that generates a concise summary from the tool name and JSON input, passed to register_task at offload time.
• New _router/_background_task.py — two read-only endpoints, both user-isolated via Depends(get_current_user_id):
  • GET /background-tasks — list all tasks for the current user (optional ?session_id= filter)
  • GET /background-tasks/{task_id} — single task detail; returns 404 for missing or cross-user access
• New _router/_schema/_background_task.py — BackgroundTaskInfo and ListBackgroundTasksResponse Pydantic models; to_info conversion helper.
• No DELETE endpoint is provided — task cancellation remains exclusively via the ToolStop agent tool, consistent with the architectural decision in PR feat(agent_team): refactor the agent service to support agent team #1776.
• ToolStop, CancelDispatcher, MessageBus, and Redis metadata schema are unchanged.

How to test

1. Start the AgentScope service and trigger a tool call that exceeds timeout_secs (e.g. a Bash tool running sleep 30).
2. Poll GET /background-tasks with the X-User-ID header — the task should appear with status: "running".
3. Wait for completion; re-poll — status transitions to "completed" and completed_at is populated.
4. Use a different X-User-ID to access the same task_id — should return 404.
5. Run the unit test suite: pytest tests/background_task_endpoint_test.py tests/tool_offload_middleware_test.py -v

Checklist

• An issue has been created for this PR (closes feat(service): add new endpoint to expose the background tasks #1720)
• I have read the CONTRIBUTING.md
• Docstrings are in Google style
• Related documentation has been updated (e.g. links, examples, etc.) in documentation repository
• Code is ready for review