Upload folder using huggingface_hub (part 2)

src/agentscope/agent/_config.py

@@ -0,0 +1,172 @@
+# -*- coding: utf-8 -*-
+"""The agent config classes."""
+
+from pydantic import BaseModel, Field
+
+from ..model import ChatModelBase
+
+
+class SummarySchema(BaseModel):
+    """The compressed memory model, used to generate summary of old memories"""
+
+    task_overview: str = Field(
+        description=(
+            "The user's core request and success criteria.\n"
+            "Any clarifications or constraints they specified"
+        ),
+    )
+    current_state: str = Field(
+        description=(
+            "What has been completed so far.\n"
+            "File created, modified, or analyzed (with paths if relevant).\n"
+            "Key outputs or artifacts produced."
+        ),
+    )
+    important_discoveries: str = Field(
+        description=(
+            "Technical constraints or requirements uncovered.\n"
+            "Decisions made and their rationale.\n"
+            "Errors encountered and how they were resolved.\n"
+            "What approaches were tried that didn't work (and why)"
+        ),
+    )
+    next_steps: str = Field(
+        description=(
+            "Specific actions needed to complete the task.\n"
+            "Any blockers or open questions to resolve.\n"
+            "Priority order if multiple steps remain"
+        ),
+    )
+    context_to_preserve: str = Field(
+        description=(
+            "User preferences or style requirements.\n"
+            "Domain-specific details that aren't obvious.\n"
+            "Any promises made to the user"
+        ),
+    )
+    """Whether to execute multiple tool calls in parallel within one
+    reasoning step."""
+
+
+class ContextConfig(BaseModel):
+    """The context related configuration in AgentScope"""
+
+    model_config = {"arbitrary_types_allowed": True}
+    """Allow arbitrary types in the pydantic model."""
+
+    trigger_ratio: float = Field(default=0.8, gt=0, lt=0.9)
+    """When the token exceeds this ratio of the maximum context length, the
+    context will be compressed. To reserve the context for context compression,
+    the maximum ratio is 0.9."""
+
+    reserve_ratio: float = Field(default=0.1, gt=0, lt=0.9)
+    """The ratio of the tokens to reserve in context compression, which should
+    be smaller than the trigger ratio."""
+
+    compression_prompt: str = Field(
+        default=(
+            "<system-hint>You have been working on the task described above "
+            "but have not yet completed it. "
+            "Now write a continuation summary that will allow you to resume "
+            "work efficiently in a future context window where the "
+            "conversation history will be replaced with this summary. "
+            "Your summary should be structured, concise, and actionable."
+            "</system-hint>"
+        ),
+        # ``format: textarea`` is a hint for schema-driven UI renderers
+        # to use a multi-line input. Plain JSON Schema doesn't natively
+        # express this, so we piggy-back on ``json_schema_extra``.
+        json_schema_extra={"format": "textarea"},
+    )
+    """The prompt used to guide the compression model to generate the
+    compressed summary, which will be wrapped into a user message and
+    attach to the end of the current memory."""
+
+    summary_template: str = Field(
+        default=(
+            "<system-info>Here is a summary of your previous work\n"
+            "# Task Overview\n"
+            "{task_overview}\n\n"
+            "# Current State\n"
+            "{current_state}\n\n"
+            "# Important Discoveries\n"
+            "{important_discoveries}\n\n"
+            "# Next Steps\n"
+            "{next_steps}\n\n"
+            "# Context to Preserve\n"
+            "{context_to_preserve}"
+            "</system-info>"
+        ),
+        json_schema_extra={"format": "textarea"},
+    )
+    """The string template to present the compressed summary to the agent,
+    which will be formatted with the fields from the
+    `compression_summary_model`."""
+
+    summary_schema: dict = Field(
+        default_factory=SummarySchema.model_json_schema,
+    )
+    """The structured model used to guide the agent to generate the
+    structured compressed summary."""
+
+    tool_result_limit: int = Field(
+        title="Tool Result Limit",
+        default=50000,
+        description=(
+            "The maximum length of the tool results in tokens. "
+            "If exceeded, the tool result will be truncated."
+        ),
+    )
+    """The tool result limit to avoid tool result bursting."""
+
+
+class ReActConfig(BaseModel):
+    """The reasoning related configuration"""
+
+    max_iters: int = Field(
+        title="Max Iterations",
+        default=20,
+        description="The maximum number of reasoning-acting iterations in "
+        "one reply",
+    )
+    """The maximum number of iterations for the reasoning-acting loop."""
+
+    stop_on_reject: bool = Field(
+        title="Rejection Handling",
+        default=False,
+        description="Whether to stop replying when being rejected to "
+        "execute tools.",
+    )
+    """If stop reasoning when tool call(s) are rejected. If `True`, the agent
+    won't continue reasoning and wait for outside interaction from the user.
+    """
+
+
+class ModelConfig(BaseModel):
+    """The model related configuration."""
+
+    # TODO: remove this line after PR #1564 is merged, where the ChatModel
+    #  will be child class of BaseModel
+    model_config = {"arbitrary_types_allowed": True}
+
+    max_retries: int = Field(
+        default=0,
+        ge=0,
+        description=(
+            "Number of retries on top of the initial call before falling "
+            "over to the fallback model. ``0`` means call the model exactly "
+            "once and immediately move to the fallback on failure. Same "
+            "semantics as ``ChatModelBase.max_retries``. Defaults to 0 to "
+            "avoid compounding with the model's own inner retry loop."
+        ),
+    )
+    """Number of retries on top of the initial call before falling over to
+    the fallback model. ``0`` means a single attempt with no retries.
+    Mirrors the semantics of ``ChatModelBase.max_retries``."""
+
+    fallback_model: ChatModelBase | None = Field(
+        default=None,
+        description="The fallback model used when the main model fails.",
+    )
+    """The fallback model used when the main model fails. Also supports the
+    max_retries logic."""

src/agentscope/agent/_utils.py

@@ -0,0 +1,17 @@
+# -*- coding: utf-8 -*-
+"""The utility classes used in building the agent class."""
+from dataclasses import dataclass
+from typing import Literal
+
+from ..message import ToolCallBlock
+
+
+@dataclass
+class _ToolCallBatch:
+    """A batch of tool calls that execute either sequentially or
+    concurrently."""
+
+    type: Literal["sequential", "concurrent"]
+    """The batch type"""
+    tool_calls: list[ToolCallBlock]
+    """The list of tool calls in the batch."""

src/agentscope/app/__init__.py

@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+"""The FastAPI based agent service module, which contains all service-related
+components and a configurable FastAPI app factory.
+"""
+
+from ._app import create_app
+from ._types import SubAgentTemplate
+
+__all__ = [
+    "create_app",
+    "SubAgentTemplate",
+]

src/agentscope/app/_app.py

@@ -0,0 +1,263 @@
+# -*- coding: utf-8 -*-
+"""AgentScope app factory."""
+from typing import Type, TYPE_CHECKING, Any
+
+from ._lifespan import lifespan
+from .rag.blob_store import BlobStoreBase, LocalBlobStore
+from .rag.knowledge_base_manager import KnowledgeBaseManagerBase
+from .workspace_manager import WorkspaceManagerBase
+from ._router import (
+    agent_router,
+    chat_router,
+    credential_router,
+    knowledge_base_router,
+    model_router,
+    tts_model_router,
+    schedule_router,
+    session_router,
+    workspace_router,
+)
+from ._types import AgentMiddlewareFactory, AgentToolFactory, SubAgentTemplate
+from .message_bus import MessageBus
+from .storage import StorageBase
+from ..agent import Agent
+from ..credential import CredentialFactory, CredentialBase
+from ..rag import (
+    ApproxTokenChunker,
+    ChunkerBase,
+    ParserBase,
+    TextParser,
+)
+from .._version import __version__
+
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+    from fastapi.middleware import Middleware as FastAPIMiddleware
+else:
+    FastAPI = Any
+    FastAPIMiddleware = Any
+
+
+def create_app(
+    storage: StorageBase,
+    message_bus: MessageBus,
+    workspace_manager: WorkspaceManagerBase,
+    knowledge_base_manager: KnowledgeBaseManagerBase | None = None,
+    knowledge_parsers: list[ParserBase] | dict[str, ParserBase] | None = None,
+    knowledge_chunker: ChunkerBase | None = None,
+    blob_store: BlobStoreBase | None = None,
+    enable_index_worker: bool = True,
+    *,
+    extra_credentials: list[Type[CredentialBase]] | None = None,
+    extra_middlewares: list[FastAPIMiddleware] | None = None,
+    extra_agent_middlewares: AgentMiddlewareFactory | None = None,
+    extra_agent_tools: AgentToolFactory | None = None,
+    custom_subagent_templates: list[SubAgentTemplate] | None = None,
+    custom_agent_cls: Type[Agent] | None = None,
+    title: str = "AgentScope",
+    version: str = __version__,
+) -> FastAPI:
+    """Create and configure a FastAPI application.
+
+    This is the primary entry point for embedding AgentScope into an existing
+    service or running it standalone.  All built-in routers are registered
+    automatically; pass ``extra_middlewares`` to add your own.
+
+    Usage — standalone::
+
+        app = create_app(
+            storage=RedisStorage(),
+            message_bus=RedisMessageBus(),
+            workspace_manager=LocalWorkspaceManager(),
+        )
+        uvicorn.run(app, host="0.0.0.0", port=8000)
+
+    Usage — mount onto an existing app::
+
+        root = FastAPI()
+        agentscope_app = create_app(
+            storage=RedisStorage(),
+            message_bus=RedisMessageBus(),
+            workspace_manager=LocalWorkspaceManager(),
+        )
+        root.mount("/agentscope", agentscope_app)
+
+    Args:
+        storage (`StorageBase`):
+            The storage backend.  Its lifecycle (``__aenter__`` /
+            ``__aexit__``) is managed by the app lifespan.
+        message_bus (`MessageBus`):
+            The live message bus used for cross-session inbox delivery
+            and idle-session triggers. Required — the bus is intentionally
+            decoupled from ``storage`` so the persistence backend (e.g.
+            SQL) can differ from the transport backend (Redis). Its
+            lifecycle is also managed by the app lifespan.
+        workspace_manager (`WorkspaceManagerBase`):
+            The workspace manager. Required — every chat run and every
+            ``/workspace`` endpoint depends on it. Its lifecycle (
+            ``__aenter__`` / ``__aexit__``) is managed by the app
+            lifespan. Pass a :class:`~agentscope.app._manager.
+            LocalWorkspaceManager` for local-directory workspaces.
+        knowledge_base_manager (`KnowledgeBaseManagerBase | None`, \
+         optional):
+            The knowledge base manager that owns knowledge base
+            lifecycle and serves
+            :class:`~agentscope.rag.KnowledgeBase`
+            runtime handles to both HTTP service and agent code.
+            The manager carries its own vector store instance — its
+            ``__aenter__`` / ``__aexit__`` enter and release that
+            vector store, so the caller does not pass the vector
+            store separately.  ``None`` disables knowledge base
+            endpoints entirely.
+        knowledge_parsers (`list[ParserBase] | dict[str, ParserBase] | \
+         None`, optional):
+            Parsers registered for knowledge base document uploads.
+            Pass a **list** to have the service route by each parser's
+            ``supported_media_types`` (later entries override earlier
+            ones for overlapping types, with a warning); pass a
+            **dict** ``media_type → parser`` for explicit routing
+            (one parser bound to multiple types, type aliases, ...).
+            Defaults to ``[TextParser()]`` when
+            ``knowledge_base_manager`` is set.
+        knowledge_chunker (`ChunkerBase | None`, optional):
+            The chunker shared across every knowledge base.  Defaults
+            to :class:`~agentscope.rag.ApproxTokenChunker()` when
+            ``knowledge_base_manager`` is set.
+        blob_store (`BlobStoreBase | None`, optional):
+            Backend storing uploaded document bytes between the
+            upload endpoint and the indexing worker.  Required when
+            ``knowledge_base_manager`` is set; defaults to
+            :class:`~agentscope.app.rag.blob_store.LocalBlobStore`
+            rooted at ``./blobs``.  Its lifecycle (``__aenter__`` /
+            ``__aexit__``) is managed by the app lifespan.
+        enable_index_worker (`bool`, defaults to ``True``):
+            When ``True`` (embedded deployment) the API process starts
+            an :class:`~agentscope.app._service.IndexWorker` and an
+            :class:`~agentscope.app._service.IndexSweeper` in its
+            lifespan, and dispatches indexing tasks via an
+            in-process queue.  When ``False`` (dedicated deployment)
+            the API process performs no indexing — a separate worker
+            process is expected to consume tasks from the message
+            bus.  No effect when ``knowledge_base_manager`` is
+            ``None``.
+        extra_credentials (`list[Type[CredentialBase]] | None`, optional):
+            Additional :class:`~agentscope.credential.CredentialBase`
+            subclasses to register before the app starts.  Equivalent to
+            calling :func:`~agentscope.credential.CredentialFactory.
+            register_credential` for each class.
+        extra_middlewares (`list[Middleware] | None`, optional):
+            Additional ASGI middlewares to add to the application.
+        extra_agent_middlewares (`AgentMiddlewareFactory | None`, optional):
+            An async factory ``(user_id, agent_id, session_id) -> awaitable
+            of list[MiddlewareBase]`` that produces extra
+            :class:`~agentscope.middleware.MiddlewareBase` instances to
+            attach to the agent on each invocation.  Called once per agent
+            assembly (i.e. per chat turn / scheduled trigger), so it can
+            return user/session-specific middleware (auth, audit logging,
+            tenant isolation, etc.).  The returned middlewares are appended
+            to the framework-supplied ones (e.g. ``ToolOffloadMiddleware``).
+        extra_agent_tools (`AgentToolFactory | None`, optional):
+            An async factory ``(user_id, agent_id, session_id) -> awaitable
+            of list[ToolBase]`` that produces extra
+            :class:`~agentscope.tool.ToolBase` instances to register in the
+            agent's toolkit on each invocation.  Useful when tool
+            availability depends on the caller (per-tenant integrations,
+            user-specific credentials).  The returned tools are added to
+            the workspace-derived tools in the toolkit's ``"basic"`` group.
+        custom_subagent_templates (`list[SubAgentTemplate] | None`, optional):
+            Reusable blueprints for sub-agent creation within teams.
+            Each template defines a sub-agent *type* (e.g. ``"researcher"``,
+            ``"coder"``) with pre-configured system prompt, context config,
+            ReAct config, permission context, and task context. When
+            registered, the ``AgentCreate`` tool exposes a
+            ``subagent_type`` parameter so the leader agent can route to
+            the appropriate template.  See
+            :class:`~agentscope.app._types.SubAgentTemplate` for details.
+        custom_agent_cls (`Type[Agent] | None`, optional):
+            A custom :class:`~agentscope.agent.Agent` subclass to use
+            when assembling agents.  When ``None`` (default), the
+            built-in :class:`~agentscope.agent.Agent` is used.
+        title (`str`, defaults to ``"AgentScope"``):
+            OpenAPI title shown in the docs UI.
+        version (`str`, defaults to the package version):
+            API version shown in the docs UI.
+
+    Returns:
+        `FastAPI`: A fully configured application ready to serve requests.
+    """
+    from fastapi import FastAPI
+
+    # Register any user-supplied credential types before the app starts
+    for cls in extra_credentials or []:
+        CredentialFactory.register_credential(cls)
+
+    app = FastAPI(title=title, version=version, lifespan=lifespan)
+
+    # Attach shared state that lifespan and dependencies read from app.state
+    app.state.storage = storage
+    app.state.message_bus = message_bus
+    app.state.workspace_manager = workspace_manager
+    app.state.knowledge_base_manager = knowledge_base_manager
+    app.state.extra_agent_middlewares = extra_agent_middlewares
+    app.state.extra_agent_tools = extra_agent_tools
+    app.state.custom_agent_cls = custom_agent_cls
+
+    # Parser / chunker / blob-store defaults only make sense when the
+    # KB feature is actually enabled.  When ``knowledge_base_manager`` is
+    # ``None`` every KB endpoint is disabled, so leaving these as ``None``
+    # avoids unused imports being eagerly constructed at app startup.
+    if knowledge_base_manager is not None:
+        app.state.knowledge_parsers = (
+            knowledge_parsers
+            if knowledge_parsers is not None
+            else [TextParser()]
+        )
+        app.state.knowledge_chunker = knowledge_chunker or ApproxTokenChunker()
+        app.state.blob_store = (
+            blob_store
+            if blob_store is not None
+            else LocalBlobStore(root_dir="./blobs")
+        )
+    else:
+        app.state.knowledge_parsers = knowledge_parsers
+        app.state.knowledge_chunker = knowledge_chunker
+        app.state.blob_store = blob_store
+    app.state.enable_index_worker = (
+        enable_index_worker and knowledge_base_manager is not None
+    )
+
+    # Validate custom sub-agent templates for duplicate types and store in
+    #  app.state
+    templates = custom_subagent_templates or []
+    seen_types: set[str] = set()
+    duplicates: set[str] = set()
+    for t in templates:
+        if t.type in seen_types:
+            duplicates.add(t.type)
+        seen_types.add(t.type)
+    if duplicates:
+        raise ValueError(
+            f"Duplicate sub_agent_template type(s): {duplicates}",
+        )
+    app.state.custom_subagent_templates = {t.type: t for t in templates}
+
+    # Built-in routers
+    for router in (
+        agent_router,
+        chat_router,
+        credential_router,
+        knowledge_base_router,
+        schedule_router,
+        session_router,
+        workspace_router,
+        model_router,
+        tts_model_router,
+    ):
+        app.include_router(router)
+
+    # Optional extra middlewares
+    for middleware in extra_middlewares or []:
+        app.add_middleware(middleware.cls, **middleware.kwargs)
+
+    return app

src/agentscope/app/_bus_ops.py

@@ -0,0 +1,167 @@
+# -*- coding: utf-8 -*-
+"""Business-level operations built on top of MessageBus primitives.
+
+These helpers compose generic bus primitives (``log_append``, ``publish``,
+``queue_push``) with domain-specific key layouts from ``MessageBusKeys``.
+They live here — between the transport layer (``message_bus``) and the
+service layer (``_service``) — so that neither layer needs to know about the
+other's internals.
+
+.. list-table::
+   :widths: 30 70
+
+   * - :func:`publish_session_event`
+     - Append an event to the session replay log and fan it out live.
+   * - :func:`enqueue_run_trigger`
+     - Enqueue a typed run trigger and signal dispatchers.
+   * - :func:`enqueue_index_task`
+     - Enqueue a knowledge-document indexing task and signal consumers.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+from .message_bus._keys import MessageBusKeys
+
+if TYPE_CHECKING:
+    from .message_bus._base import MessageBus
+
+    from agentscope.event import (
+        ExternalExecutionResultEvent,
+        UserConfirmResultEvent,
+    )
+
+
+# ── publish_session_event ──────────────────────────────────────────────
+
+
+async def publish_session_event(
+    bus: "MessageBus",
+    session_id: str,
+    event: dict,
+) -> str:
+    """Append event to replay log + fan out live.
+
+    Args:
+        bus (`MessageBus`):
+            The application message bus.
+        session_id (`str`):
+            The session this event belongs to.
+        event (`dict`):
+            JSON-serializable event payload.
+
+    Returns:
+        `str`:
+            The replay-log entry id assigned by the backend.
+    """
+    key = MessageBusKeys.session_events(session_id)
+    entry_id = await bus.log_append(
+        key,
+        event,
+        max_len=MessageBusKeys.SESSION_REPLAY_MAX_LEN,
+    )
+    await bus.publish(key, {**event, "_entry_id": entry_id})
+    return entry_id
+
+
+# ── enqueue_run_trigger ────────────────────────────────────────────────
+
+
+async def enqueue_run_trigger(
+    bus: "MessageBus",
+    user_id: str,
+    session_id: str,
+    agent_id: str,
+    *,
+    kind: Literal["wake", "resume"] = MessageBusKeys.WAKEUP_KIND_WAKE,
+    inputs: UserConfirmResultEvent
+    | ExternalExecutionResultEvent
+    | None = None,
+) -> None:
+    """Enqueue a typed run trigger and signal dispatchers.
+
+    ``kind`` selects how the dispatcher handles the entry:
+
+    - ``wake`` — idle-session wake-up.  The dispatcher skips the entry
+      when the session is already running (the live run drains the inbox
+      itself).  ``inputs`` must be ``None``.
+    - ``resume`` — resume a HITL-parked session with a user confirmation
+      or external execution result.  The dispatcher waits (with backoff)
+      until the parked run releases its lock, then spawns with
+      ``input_msg`` set to the deserialised event.
+
+    The payload is serialised to a plain dict before being pushed to the
+    wakeup queue; the ``MessageBus`` transport layer never sees event
+    types.
+
+    Args:
+        bus (`MessageBus`):
+            The application message bus.
+        user_id (`str`):
+            The owning user id.
+        session_id (`str`):
+            The session to trigger a run for.
+        agent_id (`str`):
+            The agent id that owns the session.
+        kind:
+            Trigger kind.  Defaults to ``"wake"``.
+        inputs:
+            The input event for ``resume`` triggers.  Ignored (and
+            should be ``None``) for ``wake``.  The function calls
+            ``model_dump(mode="json")`` internally — callers pass the
+            event object, not a pre-serialised dict.
+    """
+    await bus.queue_push(
+        MessageBusKeys.wakeup_queue(),
+        {
+            "user_id": user_id,
+            "session_id": session_id,
+            "agent_id": agent_id,
+            "kind": kind,
+            "input": inputs.model_dump(mode="json") if inputs else None,
+        },
+    )
+    await bus.publish(MessageBusKeys.wakeup_signal(), {})
+
+
+# ── enqueue_index_task ─────────────────────────────────────────────────
+
+
+async def enqueue_index_task(
+    bus: "MessageBus",
+    user_id: str,
+    knowledge_base_id: str,
+    document_id: str,
+) -> None:
+    """Enqueue a knowledge-document indexing task and signal consumers.
+
+    Pushes a structured payload onto the durable index-task queue and
+    publishes a signal so any subscribed
+    :class:`~agentscope.app._service.IndexTaskConsumer` drains it within
+    one ``subscribe`` round-trip.
+
+    The push happens *before* the publish so a worker woken by the
+    signal is guaranteed to find the entry on its drain.  Re-enqueuing
+    the same document is safe — the worker's lease CAS rejects
+    duplicates — so the queue may legitimately hold multiple entries
+    for the same document (one from upload, one from sweeper).
+
+    Args:
+        bus (`MessageBus`):
+            The application message bus.
+        user_id (`str`):
+            The owning user id.
+        knowledge_base_id (`str`):
+            The parent knowledge base id.
+        document_id (`str`):
+            The document id to index.
+    """
+    await bus.queue_push(
+        MessageBusKeys.index_tasks_queue(),
+        {
+            "user_id": user_id,
+            "knowledge_base_id": knowledge_base_id,
+            "document_id": document_id,
+        },
+    )
+    await bus.publish(MessageBusKeys.index_tasks_signal(), {})

src/agentscope/app/_lifespan.py

@@ -0,0 +1,180 @@
+# -*- coding: utf-8 -*-
+"""The lifespan of the agent service."""
+import socket
+import uuid
+from contextlib import AsyncExitStack, asynccontextmanager
+from typing import TYPE_CHECKING, Any, AsyncIterator
+
+from ._manager import (
+    BackgroundTaskManager,
+    CancelDispatcher,
+    ChatRunRegistry,
+    SchedulerManager,
+    WakeupDispatcher,
+)
+from ._service import (
+    ChatService,
+    IndexSweeper,
+    IndexTaskConsumer,
+    IndexWorker,
+    KnowledgeBaseService,
+    SessionService,
+)
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+else:
+    FastAPI = Any
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+    """Manage startup and shutdown of all application-wide resources.
+
+    Every resource with a lifecycle is an async context manager and is
+    entered through a single :class:`AsyncExitStack`. The stack tears
+    them down in reverse order on shutdown — including when an entry
+    later in the sequence raises during startup, so no resource leaks
+    on partial failure.
+
+    Service-layer ``ChatService`` and ``SessionService`` have no
+    lifecycle of their own and are constructed inline.
+    """
+    storage = app.state.storage
+    message_bus = app.state.message_bus
+    workspace_manager = app.state.workspace_manager
+    knowledge_base_manager = app.state.knowledge_base_manager
+    blob_store = app.state.blob_store
+    enable_index_worker = app.state.enable_index_worker
+
+    async with AsyncExitStack() as stack:
+        await stack.enter_async_context(storage)
+        await stack.enter_async_context(message_bus)
+        await stack.enter_async_context(workspace_manager)
+        if knowledge_base_manager is not None:
+            # ``KnowledgeBaseManagerBase.__aenter__`` enters the bound
+            # vector store too, so a single context covers both.
+            await stack.enter_async_context(knowledge_base_manager)
+        if blob_store is not None:
+            await stack.enter_async_context(blob_store)
+
+        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.
+        # Entered before the wake-up + cancel dispatchers so they can
+        # share the same registry; exited last so its shutdown can
+        # cancel any leftover runs after the dispatchers stop.
+        chat_run_registry = await stack.enter_async_context(ChatRunRegistry())
+        app.state.chat_run_registry = chat_run_registry
+
+        # Scheduler is independent of ChatService now (its fire path
+        # pushes to inbox + enqueues wakeup via the bus), so we build it
+        # before ChatService and inject it via the constructor.
+        scheduler = await stack.enter_async_context(
+            SchedulerManager(
+                storage=storage,
+                message_bus=message_bus,
+            ),
+        )
+        app.state.scheduler_manager = scheduler
+
+        chat_service = ChatService(
+            storage=storage,
+            workspace_manager=workspace_manager,
+            scheduler_manager=scheduler,
+            background_task_manager=bg_manager,
+            message_bus=message_bus,
+            knowledge_base_manager=knowledge_base_manager,
+            extra_agent_middlewares=app.state.extra_agent_middlewares,
+            extra_agent_tools=app.state.extra_agent_tools,
+            custom_subagent_templates=app.state.custom_subagent_templates,
+            custom_agent_cls=app.state.custom_agent_cls,
+        )
+        app.state.chat_service = chat_service
+
+        app.state.session_service = SessionService(
+            storage=storage,
+            message_bus=message_bus,
+        )
+
+        # ---------------- Knowledge-base wiring ----------------
+        knowledge_base_service = None
+        if knowledge_base_manager is not None:
+            # Indexing is uniformly driven by the message bus: the
+            # service publishes an index-task entry, and a consumer
+            # (in-process or in a dedicated worker process) drains it.
+            #
+            # * Embedded — ``enable_index_worker=True``: this lifespan
+            #   additionally starts an :class:`IndexWorker` plus an
+            #   :class:`IndexTaskConsumer` that subscribes to the same
+            #   channel. The ``InMemoryMessageBus`` makes the round
+            #   trip near-free; everything runs in one binary.
+            #
+            # * Dedicated — ``enable_index_worker=False``: this
+            #   lifespan does NOT start a worker. One or more separate
+            #   processes (``python -m agentscope.app.rag.index_worker``)
+            #   run their own consumer + worker pair subscribed to the
+            #   same channel.
+            #
+            # The sweeper STILL runs in the API process either way,
+            # because the API is the only resource guaranteed to be
+            # live whenever uploads happen — if the publish ever races
+            # a worker restart the durable queue catches the task, and
+            # if the queue write itself failed the sweeper eventually
+            # re-enqueues from storage.
+            if enable_index_worker:
+                node_id = f"{socket.gethostname()}:{uuid.uuid4().hex[:8]}"
+                worker = IndexWorker(
+                    storage=storage,
+                    blob_store=blob_store,
+                    knowledge_base_manager=knowledge_base_manager,
+                    parsers=app.state.knowledge_parsers,
+                    chunker=app.state.knowledge_chunker,
+                    node_id=node_id,
+                )
+                await stack.enter_async_context(
+                    IndexTaskConsumer(
+                        message_bus=message_bus,
+                        worker=worker,
+                    ),
+                )
+
+            sweeper = IndexSweeper(
+                storage=storage,
+                message_bus=message_bus,
+            )
+            await sweeper.start()
+            stack.push_async_callback(sweeper.stop)
+
+            knowledge_base_service = KnowledgeBaseService(
+                storage=storage,
+                knowledge_base_manager=knowledge_base_manager,
+                blob_store=blob_store,
+                message_bus=message_bus,
+            )
+
+        app.state.knowledge_base_service = knowledge_base_service
+
+        # Dispatchers need live references somewhere, or they would be
+        # garbage-collected; the AsyncExitStack holds those references
+        # for us, so we don't need local bindings or app.state slots.
+        await stack.enter_async_context(
+            WakeupDispatcher(
+                message_bus=message_bus,
+                storage=storage,
+                chat_service=chat_service,
+                chat_run_registry=chat_run_registry,
+            ),
+        )
+        await stack.enter_async_context(
+            CancelDispatcher(
+                message_bus=message_bus,
+                registry=chat_run_registry,
+                bg_manager=bg_manager,
+            ),
+        )
+
+        yield

src/agentscope/app/_manager/__init__.py

@@ -0,0 +1,17 @@
+# -*- coding: utf-8 -*-
+"""The agent service managers, used in FastAPI lifespan to manage
+application-wide resources."""
+
+from ._scheduler import SchedulerManager
+from ._wakeup_dispatcher import WakeupDispatcher
+from ._cancel_dispatcher import CancelDispatcher
+from ._chat_run_registry import ChatRunRegistry
+from ._background_task_manager import BackgroundTaskManager
+
+__all__ = [
+    "BackgroundTaskManager",
+    "CancelDispatcher",
+    "ChatRunRegistry",
+    "SchedulerManager",
+    "WakeupDispatcher",
+]

src/agentscope/app/_manager/_background_task_manager.py

@@ -0,0 +1,469 @@
+# -*- 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, TYPE_CHECKING
+
+import shortuuid
+from pydantic import BaseModel, Field
+
+from agentscope.message import TextBlock, ToolResultState
+from agentscope.permission import (
+    PermissionContext,
+    PermissionDecision,
+    PermissionBehavior,
+)
+from agentscope.tool import ToolBase, ToolChunk
+from agentscope._logging import logger
+from ..message_bus import MessageBusKeys
+
+if TYPE_CHECKING:
+    from ..message_bus import MessageBus
+
+
+@dataclass
+class BackgroundTask:
+    """Metadata for a single background task.
+
+    Attributes:
+        asyncio_task (`asyncio.Task`):
+            The running asyncio task.
+        session_id (`str`):
+            The session id of the originating request.
+        agent_id (`str`):
+            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.
+    """
+
+    asyncio_task: asyncio.Task
+    """The running asyncio task."""
+
+    session_id: str
+    """The session id of the background task."""
+
+    agent_id: str
+    """The agent that created the background task."""
+
+    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 _ToolStopParams(BaseModel):
+    """The params of the stop tool."""
+
+    task_id: str = Field(
+        description="The task id of the background tool to stop.",
+    )
+
+
+class ToolStop(ToolBase):
+    """A tool to stop a running background tool execution."""
+
+    name: str = "ToolStop"
+    """The tool name."""
+
+    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 = _ToolStopParams.model_json_schema()
+    """The input schema."""
+
+    is_concurrency_safe: bool = True
+    is_read_only: bool = False
+    is_state_injected: bool = False
+    is_external_tool: bool = False
+    is_mcp: bool = False
+    mcp_name: str | None = None
+
+    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 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,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Check permission for the tool usage.
+
+        Args:
+            tool_input (`dict[str, Any]`):
+                The tool input parameters.
+            context (`PermissionContext`):
+                The permission context.
+
+        Returns:
+            `PermissionDecision`:
+                Always returns ALLOW.
+        """
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            message=f"{self.name} is always allowed to be called.",
+        )
+
+    async def __call__(self, task_id: str) -> ToolChunk:
+        """Stop the background task.
+
+        Args:
+            task_id (`str`):
+                The task id.
+
+        Returns:
+            `ToolChunk`:
+                The tool chunk.
+        """
+        # 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.registry_exists(
+            MessageBusKeys.bg_tasks(self._session_id),
+            task_id,
+        ):
+            await self._message_bus.publish(
+                MessageBusKeys.task_cancel_channel(),
+                {"task_id": 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"Cancel request sent for task {task_id}. "
+                        f"The owning worker will stop it shortly.",
+                    ),
+                ],
+                state=ToolResultState.SUCCESS,
+            )
+
+        # Path 3: task not found anywhere.
+        return ToolChunk(
+            content=[
+                TextBlock(
+                    text=f"TaskNotFoundError: The task {task_id} "
+                    f"does not exist.",
+                ),
+            ],
+            state=ToolResultState.ERROR,
+        )
+
+
+class BackgroundTaskManager:
+    """Tracks background asyncio task lifecycle within the agent service.
+
+    Responsibilities:
+
+    - **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 a done callback that cleans up both sides.
+
+    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, 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()
+
+    # ------------------------------------------------------------------
+    # Task registration
+    # ------------------------------------------------------------------
+
+    async def register_task(
+        self,
+        asyncio_task: asyncio.Task,
+        session_id: str,
+        agent_id: str,
+        user_id: str,
+        tool_name: str = "",
+    ) -> str:
+        """Register an already-running asyncio 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`):
+                The already-running task to register.
+            session_id (`str`):
+                The originating session id.
+            agent_id (`str`):
+                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`:
+                The generated task id.
+        """
+        bg_task = BackgroundTask(
+            asyncio_task=asyncio_task,
+            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.registry_set(
+            MessageBusKeys.bg_tasks(session_id),
+            task_id,
+            metadata,
+            ttl_secs=MessageBusKeys.BG_TASKS_TTL_SECS,
+        )
+
+        logger.info(
+            "Background task registered: task_id=%s, session_id=%s, "
+            "agent_id=%s, tool_name=%s",
+            task_id,
+            session_id,
+            agent_id,
+            tool_name,
+        )
+
+        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 _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.registry_del(
+                MessageBusKeys.bg_tasks(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:`ToolStop` tool.
+        """
+        return [ToolStop(self.tasks, self._message_bus, session_id)]
+
+    # ------------------------------------------------------------------
+    # Session-scoped cancel
+    # ------------------------------------------------------------------
+
+    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 session
+        cancel broadcast. Returns the number of tasks cancelled on this
+        process.
+
+        Args:
+            session_id (`str`):
+                The session whose tasks should be cancelled.
+
+        Returns:
+            `int`:
+                Number of tasks cancelled locally.
+        """
+        cancelled = 0
+        for bg_task in list(self.tasks.values()):
+            if bg_task.session_id != session_id:
+                continue
+            logger.info(
+                "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,
+            )
+            bg_task.asyncio_task.cancel()
+            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.
+
+        Returns:
+            `Self`: This manager instance.
+        """
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        """Cancel all running background tasks on context exit."""
+        count = len(self.tasks)
+        logger.info(
+            "Shutting down BackgroundTaskManager: cancelling %d task(s).",
+            count,
+        )
+        for bg_task in list(self.tasks.values()):
+            logger.info(
+                "Cancelling background task on shutdown: task_id=%s, "
+                "session_id=%s, agent_id=%s",
+                bg_task.id,
+                bg_task.session_id,
+                bg_task.agent_id,
+            )
+            bg_task.asyncio_task.cancel()
+        self.tasks.clear()

src/agentscope/app/_manager/_cancel_dispatcher.py

@@ -0,0 +1,186 @@
+# -*- coding: utf-8 -*-
+"""Single per-process dispatcher for cross-process cancels.
+
+Subscribes to two bus channels:
+
+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 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
+
+from ..._logging import logger
+from ..message_bus import MessageBusKeys
+
+if TYPE_CHECKING:
+    from ..message_bus import MessageBus
+    from ._background_task_manager import BackgroundTaskManager
+    from ._chat_run_registry import ChatRunRegistry
+
+
+class CancelDispatcher:
+    """Subscribes to bus cancel channels and cancels matching local
+    tasks.
+
+    Args:
+        message_bus (`MessageBus`):
+            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.
+    """
+
+    def __init__(
+        self,
+        message_bus: "MessageBus",
+        registry: "ChatRunRegistry",
+        bg_manager: "BackgroundTaskManager",
+    ) -> None:
+        """Bind dependencies.
+
+        Args:
+            message_bus (`MessageBus`):
+                Application message bus.
+            registry (`ChatRunRegistry`):
+                The per-process chat-run registry.
+            bg_manager (`BackgroundTaskManager`):
+                The per-process background task manager.
+        """
+        self._bus = message_bus
+        self._registry = registry
+        self._bg_manager = bg_manager
+        self._session_task: asyncio.Task | None = None
+        self._task_cancel_task: asyncio.Task | None = None
+
+    async def __aenter__(self) -> Self:
+        """Start both dispatcher loops and wait until their bus
+        subscriptions are live.
+
+        Returns:
+            `Self`: This dispatcher instance.
+        """
+        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 session_ready.wait()
+        await task_ready.wait()
+        return self
+
+    async def __aexit__(self, *exc: object) -> 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
+
+    # ------------------------------------------------------------------
+    # Session-level cancel loop
+    # ------------------------------------------------------------------
+
+    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.
+        """
+        try:
+            async for payload in self._bus.subscribe(
+                MessageBusKeys.session_cancel_channel(),
+                on_ready=ready.set,
+            ):
+                sid = payload.get("session_id")
+                if isinstance(sid, str):
+                    self._cancel_session(sid)
+        except Exception:  # pylint: disable=broad-except
+            logger.exception(
+                "CancelDispatcher session-cancel loop crashed.",
+            )
+        finally:
+            # Unblock ``__aenter__`` even if subscribe failed before
+            # ``on_ready`` ran, so startup cannot deadlock.
+            ready.set()
+
+    def _cancel_session(self, session_id: str) -> None:
+        """Cancel every locally-tracked task for a session.
+
+        Args:
+            session_id (`str`):
+                The session whose runs and BG tasks should be cancelled.
+        """
+        task = self._registry.get(session_id)
+        if task is not None and not task.done():
+            logger.info(
+                "CancelDispatcher: cancelling local chat run for "
+                "session %s",
+                session_id,
+            )
+            task.cancel()
+
+        bg_cancelled = self._bg_manager.cancel_session_tasks(session_id)
+        if bg_cancelled:
+            logger.info(
+                "CancelDispatcher: cancelled %d local BG task(s) for "
+                "session %s",
+                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 payload in self._bus.subscribe(
+                MessageBusKeys.task_cancel_channel(),
+                on_ready=ready.set,
+            ):
+                task_id = payload.get("task_id")
+                if not isinstance(task_id, str):
+                    continue
+                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()

src/agentscope/app/_manager/_chat_run_registry.py

@@ -0,0 +1,134 @@
+# -*- coding: utf-8 -*-
+"""Per-process registry of in-flight ``ChatService.run`` asyncio tasks.
+
+Owns the asyncio.Task handles only — it is not the public cancel
+entry point. The cross-process cancel path goes through the bus's
+:meth:`~agentscope.app.message_bus.MessageBus.session_publish_cancel`
+broadcast, picked up locally by
+:class:`~agentscope.app._manager.CancelDispatcher`, which then looks
+up the task here and calls ``.cancel()`` on it.
+
+A given ``session_id`` can have at most one entry. Concurrent runs for
+the same session are already prevented at a cluster level by
+:meth:`~agentscope.app.message_bus.MessageBus.session_run` (the
+distributed lock), so a second :meth:`spawn` for the same id is treated
+as a programming error.
+"""
+import asyncio
+from typing import Coroutine, Self
+
+from ..._logging import logger
+
+
+class ChatRunRegistry:
+    """In-process index of active chat-run asyncio tasks, keyed by
+    session id.
+
+    Used by :class:`~agentscope.app._manager.CancelDispatcher` to find
+    and cancel the local task for a given session, and by the lifespan
+    to cancel any leftover runs on application shutdown.
+    """
+
+    def __init__(self) -> None:
+        """Initialise an empty registry."""
+        self._tasks: dict[str, asyncio.Task] = {}
+
+    def spawn(
+        self,
+        coro: Coroutine,
+        *,
+        session_id: str,
+        name: str | None = None,
+    ) -> asyncio.Task:
+        """Create and register an asyncio task that runs ``coro``.
+
+        The task auto-removes from the registry when it finishes (via
+        ``add_done_callback``).
+
+        Args:
+            coro (`Coroutine`):
+                A coroutine — typically ``chat_service.run(...)`` — to
+                run as a background task.
+            session_id (`str`):
+                The session this run belongs to. Used as the registry
+                key for later cancel lookup.
+            name (`str | None`, optional):
+                Optional task name passed through to
+                :func:`asyncio.create_task`. Defaults to
+                ``f"chat-run:{session_id}"``.
+
+        Returns:
+            `asyncio.Task`:
+                The created task. Callers normally do not need to keep
+                the reference — the registry holds it for the task's
+                lifetime.
+
+        Raises:
+            `RuntimeError`:
+                When a non-finished task is already registered for
+                ``session_id``. Callers are expected to coordinate via
+                the distributed session lock before spawning.
+        """
+        existing = self._tasks.get(session_id)
+        if existing is not None and not existing.done():
+            raise RuntimeError(
+                f"Session {session_id!r} already has an active chat run "
+                "in this process.",
+            )
+
+        task = asyncio.create_task(
+            coro,
+            name=name or f"chat-run:{session_id}",
+        )
+        self._tasks[session_id] = task
+
+        def _cleanup(t: asyncio.Task) -> None:
+            # Only remove the entry if it still points at this task —
+            # a fresh spawn for the same sid may have replaced it.
+            if self._tasks.get(session_id) is t:
+                self._tasks.pop(session_id, None)
+
+        task.add_done_callback(_cleanup)
+        return task
+
+    def get(self, session_id: str) -> asyncio.Task | None:
+        """Return the registered task for ``session_id``, or ``None``.
+
+        Args:
+            session_id (`str`):
+                The session whose task to look up.
+
+        Returns:
+            `asyncio.Task | None`:
+                The task if one is currently registered for the
+                session, else ``None``.
+        """
+        return self._tasks.get(session_id)
+
+    async def __aenter__(self) -> Self:
+        """No-op enter; the registry has no startup work.
+
+        Returns:
+            `Self`: This registry instance.
+        """
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        """Cancel every still-running task on application shutdown.
+
+        Each task is cancelled and awaited so its ``finally`` blocks
+        and any ``async with`` cleanups (notably the bus's session
+        run-lock release) execute before the process exits.
+        """
+        if not self._tasks:
+            return
+        logger.info(
+            "ChatRunRegistry shutdown: cancelling %d in-flight chat run(s).",
+            len(self._tasks),
+        )
+        tasks = list(self._tasks.values())
+        for task in tasks:
+            task.cancel()
+        # Wait for every cancel to land; swallow CancelledError per task.
+        await asyncio.gather(*tasks, return_exceptions=True)
+        self._tasks.clear()

src/agentscope/app/_manager/_scheduler/__init__.py

@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+"""The scheduler related components."""
+
+from ._scheduler_manager import SchedulerManager
+
+__all__ = [
+    "SchedulerManager",
+]

src/agentscope/app/_manager/_scheduler/_scheduler_manager.py

@@ -0,0 +1,432 @@
+# -*- coding: utf-8 -*-
+"""The cron scheduler manager class."""
+import json
+from collections.abc import Callable, Coroutine
+
+from typing import Self
+
+from ....message import HintBlock
+from ....permission import PermissionContext
+from ....state import AgentState
+from ....tool import ToolBase
+from ...._logging import logger
+from ._tools import ScheduleCreate, ScheduleDelete, ScheduleList, ScheduleView
+from ...message_bus import MessageBus, MessageBusKeys
+from ..._bus_ops import enqueue_run_trigger
+from ...storage import (
+    StorageBase,
+    ScheduleRecord,
+    ChatModelConfig,
+    SessionConfig,
+    SessionSource,
+)
+
+
+class SchedulerManager:
+    """The cron scheduler manager, responsible for managing scheduled-task
+    lifecycle within the agent service.
+
+    The manager owns both the in-memory APScheduler instance and the trigger
+    logic that fires scheduled tasks. Triggers do not call ``ChatService``
+    directly; instead they push a :class:`HintBlock` to the target session's
+    inbox and enqueue a wakeup, so that the application-wide
+    :class:`WakeupDispatcher` (running on any process) picks up the work.
+    This keeps the scheduler decoupled from ``ChatService`` and makes the
+    fire path consistent with team / background-tool result delivery.
+    """
+
+    def __init__(
+        self,
+        storage: StorageBase,
+        message_bus: MessageBus,
+    ) -> None:
+        """Initialize the scheduler manager.
+
+        Args:
+            storage (`StorageBase`):
+                The storage backend used for persistence and session
+                creation.
+            message_bus (`MessageBus`):
+                The application message bus. Each scheduled fire pushes
+                a :class:`HintBlock` to the target session's inbox and
+                enqueues a wakeup via this bus.
+        """
+        from apscheduler.schedulers.asyncio import AsyncIOScheduler
+
+        self._storage = storage
+        self._message_bus = message_bus
+        self._scheduler = AsyncIOScheduler()
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def __aenter__(self) -> Self:
+        """Start APScheduler and re-register persisted schedules.
+
+        Reading all schedules from storage and restoring them is the
+        only thing a caller would ever do right after starting this
+        manager, so the work lives inside the context entry — the
+        lifespan does not need to remember to call :meth:`restore`.
+
+        Returns:
+            `Self`: This manager instance.
+        """
+        logger.info("SchedulerManager starting APScheduler")
+        self._scheduler.start()
+        logger.info("SchedulerManager APScheduler started")
+
+        records = await self._storage.list_all_schedules()
+        if records:
+            await self.restore(records)
+
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        """Shut down the underlying APScheduler on context exit."""
+        logger.info("SchedulerManager shutting down APScheduler")
+        self._scheduler.shutdown()
+        logger.info("SchedulerManager APScheduler shut down")
+
+    # ------------------------------------------------------------------
+    # Trigger construction
+    # ------------------------------------------------------------------
+
+    def _build_trigger(
+        self,
+        record: ScheduleRecord,
+    ) -> Callable[[], Coroutine]:
+        """Build the zero-argument coroutine executed by APScheduler on each
+        trigger fire.
+
+        The returned coroutine:
+
+        1. Skips execution when the schedule is disabled.
+        2. Resolves or creates the target session (stateful reuses a fixed
+           session; non-stateful creates a fresh one on every fire).
+        3. Calls :class:`~agentscope.app._service._chat.ChatService` and
+           drains the response stream (fire-and-forget).
+        4. Catches and logs all exceptions to prevent APScheduler from
+           removing the job on failure.
+
+        Args:
+            record (`ScheduleRecord`):
+                The persisted schedule record that describes what to run.
+
+        Returns:
+            `Callable[[], Coroutine]`:
+                A zero-argument async callable suitable for APScheduler.
+        """
+        # Closure-friendly references so APScheduler doesn't have to
+        # re-look these up on every fire.
+        storage = self._storage
+        message_bus = self._message_bus
+
+        async def _trigger() -> None:
+            logger.info(
+                "[Schedule:%s(%s)] Trigger fired",
+                record.id,
+                record.data.name,
+            )
+
+            if not record.data.enabled:
+                logger.info(
+                    "[Schedule:%s(%s)] Skipped — schedule disabled",
+                    record.id,
+                    record.data.name,
+                )
+                return
+
+            try:
+                if record.data.stateful:
+                    stateful_session_id = f"{record.id}_stateful"
+                    logger.info(
+                        "[Schedule:%s(%s)] Stateful mode, "
+                        "looking up session %s",
+                        record.id,
+                        record.data.name,
+                        stateful_session_id,
+                    )
+                    session = await storage.get_session(
+                        record.user_id,
+                        record.agent_id,
+                        stateful_session_id,
+                    )
+                    if session is None:
+                        logger.info(
+                            "[Schedule:%s(%s)] First fire, "
+                            "creating stateful session",
+                            record.id,
+                            record.data.name,
+                        )
+                        state = AgentState()
+                        state.permission_context = PermissionContext(
+                            mode=record.data.permission_mode,
+                        )
+                        session_config = SessionConfig(
+                            workspace_id="",
+                            chat_model_config=record.data.chat_model_config,
+                        )
+                        session = await storage.upsert_session(
+                            user_id=record.user_id,
+                            agent_id=record.agent_id,
+                            config=session_config,
+                            state=state,
+                            session_id=stateful_session_id,
+                            source=SessionSource.SCHEDULE,
+                            source_schedule_id=record.id,
+                        )
+                    else:
+                        logger.info(
+                            "[Schedule:%s(%s)] Reusing existing "
+                            "stateful session %s",
+                            record.id,
+                            record.data.name,
+                            session.id,
+                        )
+                else:
+                    logger.info(
+                        "[Schedule:%s(%s)] Non-stateful mode, "
+                        "creating fresh session",
+                        record.id,
+                        record.data.name,
+                    )
+                    state = AgentState()
+                    state.permission_context = PermissionContext(
+                        mode=record.data.permission_mode,
+                    )
+                    session = await storage.upsert_session(
+                        user_id=record.user_id,
+                        agent_id=record.agent_id,
+                        config=SessionConfig(
+                            workspace_id="",
+                            chat_model_config=record.data.chat_model_config,
+                        ),
+                        state=state,
+                        source=SessionSource.SCHEDULE,
+                        source_schedule_id=record.id,
+                    )
+
+                logger.info(
+                    "[Schedule:%s(%s)] Session ready: %s, "
+                    "delivering prompt via inbox + wakeup",
+                    record.id,
+                    record.data.name,
+                    session.id,
+                )
+
+                # Wrap the schedule prompt in an XML tag so the LLM
+                # recognises it as a system-driven trigger rather than
+                # a regular user turn — same shape as team / system
+                # notification hints.
+                hint = HintBlock(
+                    hint=(
+                        f"<scheduled-task>\n"
+                        f"{record.data.description}\n"
+                        f"</scheduled-task>"
+                    ),
+                    source=json.dumps(
+                        {
+                            "label": "schedule",
+                            "sublabel": record.data.name,
+                        },
+                        ensure_ascii=False,
+                    ),
+                )
+                await message_bus.queue_push(
+                    MessageBusKeys.inbox(session.id),
+                    hint.model_dump(mode="json"),
+                )
+                await enqueue_run_trigger(
+                    message_bus,
+                    user_id=record.user_id,
+                    session_id=session.id,
+                    agent_id=record.agent_id,
+                )
+
+                logger.info(
+                    "[Schedule:%s(%s)] Wakeup enqueued for session %s",
+                    record.id,
+                    record.data.name,
+                    session.id,
+                )
+
+            except Exception:
+                logger.exception(
+                    "[Schedule:%s(%s)] Trigger failed",
+                    record.id,
+                    record.data.name,
+                )
+
+        return _trigger
+
+    # ------------------------------------------------------------------
+    # Schedule management
+    # ------------------------------------------------------------------
+
+    async def register_schedule(self, record: ScheduleRecord) -> str:
+        """Persist-and-register a schedule record with APScheduler.
+
+        Builds the trigger coroutine via :meth:`_build_trigger` and adds the
+        job to APScheduler.  This is the single entry point used by both the
+        HTTP API and the :class:`ScheduleCreate` agent tool.
+
+        Args:
+            record (`ScheduleRecord`):
+                The fully-populated record (already persisted to storage).
+
+        Returns:
+            `str`:
+                The APScheduler job ID (equal to ``record.id``).
+        """
+
+        from apscheduler.triggers.cron import CronTrigger
+
+        logger.info(
+            "Registering schedule %s(%s) cron=%s tz=%s",
+            record.id,
+            record.data.name,
+            record.data.cron_expression,
+            record.data.timezone,
+        )
+
+        # ``CronTrigger.from_crontab`` is a thin helper that only forwards
+        # the 5 parsed fields and ``timezone`` — it has no parameter for
+        # ``start_date`` / ``end_date``.  Parse the expression ourselves so
+        # the configured activation window is honoured.
+        fields = record.data.cron_expression.split()
+        if len(fields) != 5:
+            raise ValueError(
+                "Expected a 5-field cron expression, got "
+                f"{record.data.cron_expression!r}",
+            )
+        minute, hour, day, month, day_of_week = fields
+
+        trigger = self._build_trigger(record)
+        job = self._scheduler.add_job(
+            trigger,
+            trigger=CronTrigger(
+                minute=minute,
+                hour=hour,
+                day=day,
+                month=month,
+                day_of_week=day_of_week,
+                timezone=record.data.timezone,
+                start_date=record.data.started_at,
+                end_date=record.data.ended_at,
+            ),
+            id=record.id,
+            name=record.data.name,
+            misfire_grace_time=300,
+        )
+        logger.info(
+            "Schedule %s(%s) registered, next_run=%s",
+            record.id,
+            record.data.name,
+            job.next_run_time,
+        )
+        return job.id
+
+    async def remove_schedule(self, job_id: str) -> None:
+        """Remove a job from APScheduler.
+
+        Args:
+            job_id (`str`):
+                The APScheduler job ID to remove.
+        """
+        from apscheduler.jobstores.base import JobLookupError
+
+        logger.info("Removing schedule job %s", job_id)
+        try:
+            self._scheduler.remove_job(job_id)
+            logger.info("Schedule job %s removed", job_id)
+        except JobLookupError:
+            logger.warning("Schedule job %s not found in APScheduler", job_id)
+
+    async def restore(self, records: list[ScheduleRecord]) -> None:
+        """Re-register persisted schedules on service startup.
+
+        Only enabled schedules are restored.
+
+        Args:
+            records (`list[ScheduleRecord]`):
+                All schedule records loaded from storage on startup.
+        """
+        enabled = [r for r in records if r.data.enabled]
+        logger.info(
+            "Restoring schedules: %d total, %d enabled",
+            len(records),
+            len(enabled),
+        )
+        for record in enabled:
+            await self.register_schedule(record)
+        logger.info("Schedule restore complete")
+
+    async def list_tasks(self) -> list[dict]:
+        """Return a summary of all currently registered APScheduler jobs.
+
+        Returns:
+            `list[dict]`:
+                Each entry contains ``id``, ``name``, and ``next_run``.
+        """
+        return [
+            {
+                "id": job.id,
+                "name": job.name,
+                "next_run": job.next_run_time,
+            }
+            for job in self._scheduler.get_jobs()
+        ]
+
+    # ------------------------------------------------------------------
+    # Agent tools
+    # ------------------------------------------------------------------
+
+    async def list_tools(
+        self,
+        user_id: str,
+        agent_id: str,
+        chat_model_config: ChatModelConfig,
+    ) -> list[ToolBase]:
+        """Return the agent-facing tools provided by the scheduler manager.
+
+        Args:
+            user_id (`str`):
+                The authenticated user who owns the schedules.
+            agent_id (`str`):
+                The agent that will be run by newly created schedules.
+            chat_model_config (`ChatModelConfig`):
+                Model configuration inherited from the current session and
+                stored on new :class:`~...ScheduleRecord` objects.
+
+        Returns:
+            `list[ToolBase]`:
+                The four schedule tools: :class:`ScheduleCreate`,
+                :class:`ScheduleView`, :class:`ScheduleDelete`, and
+                :class:`ScheduleList`.
+        """
+        return [
+            ScheduleCreate(
+                user_id=user_id,
+                agent_id=agent_id,
+                chat_model_config=chat_model_config,
+                storage=self._storage,
+                scheduler_manager=self,
+            ),
+            ScheduleView(
+                user_id=user_id,
+                scheduler=self._scheduler,
+                storage=self._storage,
+            ),
+            ScheduleDelete(
+                user_id=user_id,
+                scheduler=self._scheduler,
+                storage=self._storage,
+                message_bus=self._message_bus,
+            ),
+            ScheduleList(
+                user_id=user_id,
+                scheduler=self._scheduler,
+                storage=self._storage,
+            ),
+        ]

src/agentscope/app/_manager/_scheduler/_tools/__init__.py

@@ -0,0 +1,14 @@
+# -*- coding: utf-8 -*-
+"""The schedule related tools."""
+
+from ._schedule_create import ScheduleCreate
+from ._schedule_delete import ScheduleDelete
+from ._schedule_list import ScheduleList
+from ._schedule_view import ScheduleView
+
+__all__ = [
+    "ScheduleCreate",
+    "ScheduleDelete",
+    "ScheduleList",
+    "ScheduleView",
+]

src/agentscope/app/_manager/_scheduler/_tools/_schedule_create.py

@@ -0,0 +1,253 @@
+# -*- coding: utf-8 -*-
+"""The schedule create tool."""
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from .....message import ToolResultState, TextBlock
+from .....permission import (
+    PermissionContext,
+    PermissionDecision,
+    PermissionBehavior,
+    PermissionMode,
+)
+from .....state import AgentState
+from .....tool import ToolBase, ToolChunk
+from ....storage import (
+    ScheduleData,
+    ScheduleRecord,
+    ScheduleSource,
+    ChatModelConfig,
+)
+
+
+class _ScheduleCreateParams(BaseModel):
+    """The params for the schedule create tool."""
+
+    name: str = Field(description="Display name of the schedule.")
+
+    description: str = Field(
+        default="",
+        description="Description of the schedule, including its purpose.",
+    )
+
+    cron_expression: str = Field(
+        description="Standard 5-field cron expression, e.g. '0 9 * * 1-5'.",
+    )
+
+    timezone: str = Field(
+        default="UTC",
+        description="IANA timezone name used to evaluate the cron expression, "
+        "e.g. 'America/New_York' or 'Asia/Shanghai'.",
+    )
+
+    enabled: bool = Field(
+        default=True,
+        description="Whether the schedule is active immediately after "
+        "creation. Set to False to create a disabled schedule.",
+    )
+
+    started_at: datetime | None = Field(
+        default=None,
+        description="ISO-8601 datetime at which the schedule becomes active. "
+        "Defaults to the current time when not specified.",
+    )
+
+    ended_at: datetime | None = Field(
+        default=None,
+        description="ISO-8601 datetime at which the schedule stops firing. "
+        "If not set the schedule runs indefinitely.",
+    )
+
+    stateful: bool = Field(
+        default=False,
+        description="If True, consecutive executions share the same session "
+        "context. If False, each execution gets a fresh session.",
+    )
+
+    permission_mode: str = Field(
+        default=PermissionMode.DONT_ASK.value,
+        description=(
+            "Permission mode for the agent during scheduled execution. "
+            f"Allowed values: {[m.value for m in PermissionMode]}. "
+            "Defaults to 'dont_ask' since no user is present."
+        ),
+    )
+
+
+class ScheduleCreate(ToolBase):
+    """The schedule create tool.
+
+    Creates a new scheduled task that will execute the current agent at a
+    given cron interval.  The record is persisted to storage and immediately
+    registered with the in-memory APScheduler.
+
+    The schedule inherits the model configuration of the current session.
+    The agent that creates the schedule is also the agent that will be run
+    on each trigger.
+    """
+
+    name: str = "ScheduleCreate"
+
+    description: str = """Create a new recurring scheduled task for yourself. \
+You will be notified in a new session each time the schedule is triggered.
+
+**About the cron expression:**
+- Determine your current timezone first, that's very important for setting a \
+correct cron expression. Get it by bash command like `date +%z`, \
+`cat /etc/timezone` or directly ask the user.
+- Determine whether the task should run once or recur at an interval, \
+then set the cron expression accordingly.
+- For a one-off task, query the current time first and set the cron \
+expression to fire at that specific moment.
+- Set `started_at` and `ended_at` to match the user's requirements. \
+When in doubt, ask for clarification before creating the schedule.
+
+**About the description field:**
+- The `description` is the only context available to you when the \
+schedule fires in a new session. Include all necessary details: the goal, \
+expected output, constraints, relevant file paths, and anything else needed \
+to complete the task independently.
+"""
+
+    input_schema: dict = _ScheduleCreateParams.model_json_schema()
+
+    is_concurrency_safe: bool = False
+    is_read_only: bool = False
+    is_state_injected: bool = True
+    is_external_tool: bool = False
+    is_mcp: bool = False
+    mcp_name: str | None = None
+
+    def __init__(
+        self,
+        user_id: str,
+        agent_id: str,
+        chat_model_config: ChatModelConfig,
+        storage: Any,
+        scheduler_manager: Any,
+    ) -> None:
+        """Initialize the schedule create tool.
+
+        Args:
+            user_id (`str`):
+                The authenticated user who owns this schedule.
+            agent_id (`str`):
+                The agent that will be executed on each trigger.
+            chat_model_config (`ChatModelConfig`):
+                Model configuration inherited from the current session.
+            storage (`Any`):
+                The storage backend used to persist the schedule record.
+            scheduler_manager (`Any`):
+                The scheduler manager used to register the APScheduler job.
+                Must expose a ``register_schedule(record)`` coroutine.
+        """
+        self._user_id = user_id
+        self._agent_id = agent_id
+        self._chat_model_config = chat_model_config
+        self._storage = storage
+        self._scheduler_manager = scheduler_manager
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Check permission for the tool usage."""
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            message=f"{self.name} is always allowed to be called.",
+        )
+
+    async def __call__(  # type: ignore[override]
+        self,
+        name: str,
+        cron_expression: str,
+        description: str = "",
+        timezone: str = "UTC",
+        enabled: bool = True,
+        started_at: datetime | None = None,
+        ended_at: datetime | None = None,
+        stateful: bool = False,
+        permission_mode: str = PermissionMode.DONT_ASK.value,
+        _agent_state: AgentState | None = None,
+    ) -> ToolChunk:
+        """Create a new scheduled task.
+
+        Args:
+            name (`str`):
+                Display name of the schedule.
+            cron_expression (`str`):
+                Standard 5-field cron expression, e.g. ``'0 9 * * 1-5'``.
+            description (`str`, optional):
+                Human-readable description of what this schedule does.
+            timezone (`str`, optional):
+                IANA timezone name, e.g. ``'Asia/Shanghai'``.
+            enabled (`bool`, optional):
+                Whether the schedule is active immediately after creation.
+            started_at (`datetime | None`, optional):
+                Datetime at which the schedule becomes active. Defaults to
+                the current time when not specified.
+            ended_at (`datetime | None`, optional):
+                Datetime at which the schedule stops firing. If not set the
+                schedule runs indefinitely.
+            stateful (`bool`, optional):
+                Whether consecutive executions share the same session context.
+            permission_mode (`str`, optional):
+                Permission mode value string.
+            _agent_state (`AgentState | None`, optional):
+                Injected agent state; provides the source session ID.
+
+        Returns:
+            `ToolChunk`:
+                A chunk with the new schedule ID on success, or an error
+                description on failure.
+        """
+        try:
+            perm_mode = PermissionMode(permission_mode)
+        except ValueError:
+            perm_mode = PermissionMode.DONT_ASK
+
+        source_session_id = (
+            _agent_state.session_id if _agent_state is not None else ""
+        )
+
+        record = ScheduleRecord(
+            user_id=self._user_id,
+            agent_id=self._agent_id,
+            data=ScheduleData(
+                name=name,
+                description=description,
+                enabled=enabled,
+                cron_expression=cron_expression,
+                timezone=timezone,
+                started_at=started_at or datetime.now(),
+                ended_at=ended_at,
+                stateful=stateful,
+                permission_mode=perm_mode,
+                source=ScheduleSource.AGENT,
+                source_session_id=source_session_id,
+                chat_model_config=self._chat_model_config,
+            ),
+        )
+
+        await self._storage.upsert_schedule(self._user_id, record)
+        await self._scheduler_manager.register_schedule(record)
+
+        return ToolChunk(
+            content=[
+                TextBlock(
+                    text=(
+                        f"Schedule {name!r} created successfully.\n"
+                        f"Schedule ID: {record.id}\n"
+                        f"Cron: {cron_expression} (timezone: {timezone})\n"
+                        f"Enabled: {enabled}\n"
+                        f"Started at: {record.data.started_at}\n"
+                        f"Ended at: {ended_at or '(no end time)'}\n"
+                        f"Stateful: {stateful}"
+                    ),
+                ),
+            ],
+            state=ToolResultState.SUCCESS,
+        )

src/agentscope/app/_manager/_scheduler/_tools/_schedule_delete.py

@@ -0,0 +1,154 @@
+# -*- coding: utf-8 -*-
+"""Schedule delete tool – removes a job from the scheduler and storage."""
+from typing import Any
+
+from pydantic import BaseModel, Field
+from apscheduler.jobstores.base import JobLookupError
+
+from .....message import ToolResultState, TextBlock
+from .....permission import (
+    PermissionContext,
+    PermissionDecision,
+    PermissionBehavior,
+)
+from .....tool import ToolBase, ToolChunk
+from ....message_bus import MessageBus
+from ....storage._base import StorageBase
+
+
+class _ScheduleDeleteParams(BaseModel):
+    """The params for the schedule delete tool."""
+
+    schedule_id: str = Field(
+        description="The schedule ID to delete (permanently remove).",
+    )
+
+
+class ScheduleDelete(ToolBase):
+    """The schedule delete tool.
+
+    Permanently removes the given scheduled job from APScheduler,
+    storage, and the message bus. Every execution session spawned by
+    the schedule is cancelled (if running) and has its bus state
+    purged. The job cannot be recovered after removal.
+    """
+
+    name: str = "ScheduleDelete"
+
+    description: str = (
+        "Permanently delete a scheduled task by its schedule ID. "
+        "After this call the task will no longer be executed and its record "
+        "will be deleted from storage."
+    )
+    input_schema: dict = _ScheduleDeleteParams.model_json_schema()
+
+    is_concurrency_safe: bool = False
+    is_read_only: bool = False
+    is_state_injected: bool = False
+    is_external_tool: bool = False
+    is_mcp: bool = False
+    mcp_name: str | None = None
+
+    def __init__(
+        self,
+        user_id: str,
+        scheduler: Any,
+        storage: StorageBase,
+        message_bus: MessageBus,
+    ) -> None:
+        """Initialize the schedule delete tool.
+
+        Args:
+            user_id (`str`):
+                The authenticated user; used to scope the storage deletion.
+            scheduler (`Any`):
+                The ``AsyncIOScheduler`` instance whose job will be removed.
+            storage (`StorageBase`):
+                The storage backend used to delete the persisted record.
+            message_bus (`MessageBus`):
+                The message bus used to cancel in-flight chat runs for
+                any execution session spawned by this schedule and to
+                purge their per-session bus state.
+        """
+        self._user_id = user_id
+        self._scheduler = scheduler
+        self._storage = storage
+        self._message_bus = message_bus
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Check permission for the tool usage."""
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            message=f"{self.name} is always allowed to be called.",
+        )
+
+    async def __call__(
+        self,
+        schedule_id: str,
+    ) -> ToolChunk:  # type: ignore[override]
+        """Permanently delete the scheduled task with the given ID.
+
+        Delegates the storage + bus cascade to
+        :meth:`SessionService.delete_schedule`, which cancels in-flight
+        runs for any session this schedule spawned and purges their
+        bus state before dropping the schedule record. The APScheduler
+        job is removed separately because it lives in-process and the
+        service layer is bus/storage-only.
+
+        Args:
+            schedule_id (`str`):
+                The unique identifier of the schedule to delete.
+
+        Returns:
+            `ToolChunk`:
+                A chunk describing the result of the delete operation.
+        """
+
+        # Remove from the in-memory scheduler (best-effort; may already be
+        # absent if the job finished naturally or the server restarted)
+        try:
+            self._scheduler.remove_job(schedule_id)
+        except JobLookupError:
+            pass
+
+        # Local import to avoid a circular dependency between
+        # ``_manager`` and ``_service`` at module load.
+        from ...._service import SessionService  # noqa: PLC0415
+
+        session_service = SessionService(
+            storage=self._storage,
+            message_bus=self._message_bus,
+        )
+        deleted = await session_service.delete_schedule(
+            self._user_id,
+            schedule_id,
+        )
+
+        if not deleted:
+            return ToolChunk(
+                content=[
+                    TextBlock(
+                        text=(
+                            f"ScheduleNotFoundError: Schedule with id "
+                            f"{schedule_id!r} not found in storage."
+                        ),
+                    ),
+                ],
+                state=ToolResultState.ERROR,
+            )
+
+        return ToolChunk(
+            content=[
+                TextBlock(
+                    text=(
+                        f"Schedule {schedule_id!r} has been permanently "
+                        f"deleted."
+                    ),
+                ),
+            ],
+            state=ToolResultState.SUCCESS,
+        )

src/agentscope/app/_manager/_scheduler/_tools/_schedule_list.py

@@ -0,0 +1,115 @@
+# -*- coding: utf-8 -*-
+"""The tool to list the scheduled jobs in the cron scheduler manager."""
+from typing import Any
+
+from pydantic import BaseModel
+
+from .....message import ToolResultState, TextBlock
+from .....permission import (
+    PermissionContext,
+    PermissionDecision,
+    PermissionBehavior,
+)
+from .....tool import ToolBase, ToolChunk
+from ....storage import StorageBase
+
+
+class _ScheduleListParams(BaseModel):
+    """The params for the schedule list tool."""
+
+
+class ScheduleList(ToolBase):
+    """The schedule list tool.
+
+    Lists all scheduled tasks owned by the current user.  Each entry is
+    fetched from storage (rich :class:`ScheduleData`) and augmented with
+    ``next_run_time`` from the in-memory APScheduler job when available.
+    """
+
+    name: str = "ScheduleList"
+
+    description: str = (
+        "List all scheduled tasks for the current user. "
+        "Shows schedule ID, name, cron expression, timezone, next run time, "
+        "enabled/disabled status, and whether the schedule is stateful."
+    )
+    input_schema: dict = _ScheduleListParams.model_json_schema()
+
+    is_concurrency_safe: bool = True
+    is_read_only: bool = True
+    is_state_injected: bool = False
+    is_external_tool: bool = False
+    is_mcp: bool = False
+    mcp_name: str | None = None
+
+    def __init__(
+        self,
+        user_id: str,
+        scheduler: Any,
+        storage: StorageBase,
+    ) -> None:
+        """Initialize the schedule list tool.
+
+        Args:
+            user_id (`str`):
+                The authenticated user; used to scope the storage lookup.
+            scheduler (`Any`):
+                The ``AsyncIOScheduler`` instance for reading ``next_run_time``
+            storage (`StorageBase`):
+                The storage backend that holds the persisted schedule records.
+        """
+        self._user_id = user_id
+        self._scheduler = scheduler
+        self._storage = storage
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Check permission for the tool usage."""
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            message=f"{self.name} is always allowed to be called.",
+        )
+
+    async def __call__(self) -> ToolChunk:  # type: ignore[override]
+        """List all scheduled tasks for the current user.
+
+        Returns:
+            `ToolChunk`:
+                A chunk containing a formatted list of all scheduled tasks,
+                or a message indicating none exist.
+        """
+        records = await self._storage.list_schedules(self._user_id)
+
+        if not records:
+            return ToolChunk(
+                content=[TextBlock(text="No scheduled tasks found.")],
+                state=ToolResultState.SUCCESS,
+            )
+
+        # Build a map of schedule_id -> next_run_time from the live scheduler
+        next_run_map: dict[str, str] = {
+            job.id: str(job.next_run_time)
+            for job in self._scheduler.get_jobs()
+        }
+
+        lines: list[str] = [f"Found {len(records)} scheduled task(s):\n"]
+        for record in records:
+            enabled_str = "enabled" if record.data.enabled else "disabled"
+            next_run = next_run_map.get(record.id, "not in scheduler")
+            lines.append(
+                f"- [{enabled_str}] {record.data.name!r}  (ID: {record.id})\n"
+                f"  Cron:      {record.data.cron_expression}"
+                f" ({record.data.timezone})\n"
+                f"  Next run:  {next_run}\n"
+                f"  Stateful:  {record.data.stateful}"
+                f"  |  Agent: {record.agent_id}\n"
+                f"  Source:    {record.data.source.value}\n",
+            )
+
+        return ToolChunk(
+            content=[TextBlock(text="\n".join(lines))],
+            state=ToolResultState.SUCCESS,
+        )

src/agentscope/app/_manager/_scheduler/_tools/_schedule_view.py

@@ -0,0 +1,138 @@
+# -*- coding: utf-8 -*-
+"""The schedule view tool."""
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from .....message import ToolResultState, TextBlock
+from .....permission import (
+    PermissionContext,
+    PermissionDecision,
+    PermissionBehavior,
+)
+from .....tool import ToolBase, ToolChunk
+from ....storage import StorageBase
+
+
+class _ScheduleViewParams(BaseModel):
+    """The params for the schedule view tool."""
+
+    schedule_id: str = Field(
+        description="The schedule ID.",
+    )
+
+
+class ScheduleView(ToolBase):
+    """The schedule view tool.
+
+    Fetches the persisted :class:`ScheduleRecord` from storage and enriches
+    it with the ``next_run_time`` from the in-memory APScheduler job.
+    """
+
+    name: str = "ScheduleView"
+
+    description: str = (
+        "View the full details of a scheduled task by its schedule ID, "
+        "including cron expression, timezone, stateful flag, permission "
+        "mode, and the next scheduled run time."
+    )
+    input_schema: dict = _ScheduleViewParams.model_json_schema()
+
+    is_concurrency_safe: bool = True
+    is_read_only: bool = True
+    is_state_injected: bool = False
+    is_external_tool: bool = False
+    is_mcp: bool = False
+    mcp_name: str | None = None
+
+    def __init__(
+        self,
+        user_id: str,
+        scheduler: Any,
+        storage: StorageBase,
+    ) -> None:
+        """Initialize the schedule view tool.
+
+        Args:
+            user_id (`str`):
+                The authenticated user; used to scope the storage lookup.
+            scheduler (`Any`):
+                The ``AsyncIOScheduler`` instance for
+                reading ``next_run_time``.
+            storage (`StorageBase`):
+                The storage backend that holds the persisted schedule records.
+        """
+        self._user_id = user_id
+        self._scheduler = scheduler
+        self._storage = storage
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: PermissionContext,
+    ) -> PermissionDecision:
+        """Check permission for the tool usage."""
+        return PermissionDecision(
+            behavior=PermissionBehavior.ALLOW,
+            message=f"{self.name} is always allowed to be called.",
+        )
+
+    async def __call__(
+        self,
+        schedule_id: str,
+    ) -> ToolChunk:  # type: ignore[override]
+        """View the full details of a scheduled task.
+
+        Args:
+            schedule_id (`str`):
+                The unique identifier of the schedule to view.
+
+        Returns:
+            `ToolChunk`:
+                A chunk containing the formatted schedule details, or an
+                error description if the schedule is not found.
+        """
+        record = await self._storage.get_schedule(self._user_id, schedule_id)
+
+        if record is None:
+            return ToolChunk(
+                content=[
+                    TextBlock(
+                        text=(
+                            f"ScheduleNotFoundError: Schedule with "
+                            f"id {schedule_id!r} not found."
+                        ),
+                    ),
+                ],
+                state=ToolResultState.ERROR,
+            )
+
+        job = self._scheduler.get_job(schedule_id)
+        next_run = (
+            str(job.next_run_time)
+            if job is not None
+            else "not in scheduler (may be disabled)"
+        )
+        enabled_str = "enabled" if record.data.enabled else "disabled"
+
+        text = (
+            f"Schedule ID:     {record.id}\n"
+            f"Name:            {record.data.name}\n"
+            f"Description:     {record.data.description or '(none)'}\n"
+            f"Status:          {enabled_str}\n"
+            f"Cron:            {record.data.cron_expression}"
+            f" (timezone: {record.data.timezone})\n"
+            f"Next run:        {next_run}\n"
+            f"Stateful:        {record.data.stateful}\n"
+            f"Permission mode: {record.data.permission_mode.value}\n"
+            f"Source:          {record.data.source.value}\n"
+            f"Source session:  {record.data.source_session_id or '(none)'}\n"
+            f"Agent ID:        {record.agent_id}\n"
+            f"Created at:      {record.created_at}\n"
+            f"Updated at:      {record.updated_at}\n"
+        )
+
+        return ToolChunk(
+            content=[TextBlock(text=text)],
+            state=ToolResultState.SUCCESS,
+        )

src/agentscope/app/_manager/_wakeup_dispatcher.py

@@ -0,0 +1,371 @@
+# -*- coding: utf-8 -*-
+"""Single per-process dispatcher for all cross-session run triggers.
+
+One asyncio task per process. Subscribes to the shared trigger signal
+channel and drains the durable trigger queue on each signal. It is the
+**sole** site that spawns :meth:`ChatService.run` into the shared
+:class:`ChatRunRegistry`, which is what makes concurrent-spawn races
+(two writers contending for one session's run slot → a spurious "already
+has an active chat run" 409) structurally impossible: every run trigger
+funnels through this one serial consumer.
+
+Each queue entry carries a ``kind`` that selects how a busy session is
+handled:
+
+- ``wake`` (idle-session wake-up, ``input_msg=None``): skipped while the
+  session is already running — the live run will drain the inbox.
+- ``resume`` (a parked HITL run being fed its result): must *not* be
+  skipped while running, because the session is typically still running
+  the parked tail at trigger time. It is re-queued after a short backoff
+  until the parked run releases its session lock, then spawned with the
+  carried input event.
+
+All bus keys live on the :class:`MessageBus` base class (see
+``enqueue_wakeup`` / ``enqueue_input``, ``dequeue_wakeups``,
+``subscribe_wakeup_signal``, ``session_is_running``), so this file has
+no hard-coded key strings.
+"""
+import asyncio
+from typing import TYPE_CHECKING, Self
+
+from pydantic import TypeAdapter
+
+from ..._logging import logger
+from ...event import UserConfirmResultEvent, ExternalExecutionResultEvent
+from ..message_bus import MessageBusKeys
+from .._bus_ops import enqueue_run_trigger
+
+if TYPE_CHECKING:
+    from ..message_bus import MessageBus
+    from ..storage import StorageBase
+    from .._service import ChatService
+    from ._chat_run_registry import ChatRunRegistry
+
+# Parses a queued ``resume`` input dict back into its concrete event,
+# discriminated by the ``type`` field shared by both result events.
+_RESUME_INPUT_ADAPTER: TypeAdapter = TypeAdapter(
+    UserConfirmResultEvent | ExternalExecutionResultEvent,
+)
+
+# Delay before re-queuing a ``resume`` trigger whose target session is
+# still running (the parked run is finishing and about to free its
+# lock). Short enough to feel instant to the user, long enough to avoid
+# a hot re-enqueue loop while the lock is held.
+_RESUME_RETRY_BACKOFF_SECS = 0.1
+
+
+class WakeupDispatcher:
+    """One asyncio task per process, draining the shared trigger queue.
+
+    Args:
+        message_bus (`MessageBus`):
+            Application message bus. Used for signal subscription,
+            queue drain, ``session_is_running`` checks, and re-queuing
+            deferred ``resume`` triggers.
+        storage (`StorageBase`):
+            Persistent storage backend. Consulted before spawning a
+            run so triggers whose target session has been deleted are
+            dropped instead of crashing :class:`ChatService.run`.
+        chat_service (`ChatService`):
+            Drives the actual chat run when a trigger fires.
+        chat_run_registry (`ChatRunRegistry`):
+            Per-process registry that holds the spawned task handle so
+            it can be located by :class:`CancelDispatcher`.
+    """
+
+    def __init__(
+        self,
+        message_bus: "MessageBus",
+        storage: "StorageBase",
+        chat_service: "ChatService",
+        chat_run_registry: "ChatRunRegistry",
+    ) -> None:
+        """Bind dependencies.
+
+        Args:
+            message_bus (`MessageBus`):
+                Application message bus.
+            storage (`StorageBase`):
+                Persistent storage backend.
+            chat_service (`ChatService`):
+                Drives session runs via :meth:`ChatService.run`.
+            chat_run_registry (`ChatRunRegistry`):
+                Shared chat-run registry to spawn into.
+        """
+        self._bus = message_bus
+        self._storage = storage
+        self._chat_service = chat_service
+        self._registry = chat_run_registry
+        self._task: asyncio.Task | None = None
+        # Detached backoff timers for deferred ``resume`` re-enqueues.
+        # Held so they are not garbage-collected mid-sleep and can be
+        # cancelled on shutdown.
+        self._retry_tasks: set[asyncio.Task] = set()
+
+    async def __aenter__(self) -> Self:
+        """Start the dispatcher loop and wait until its bus
+        subscription is live.
+
+        Also performs an initial drain right after subscription so
+        triggers produced while this process was down (durable in
+        the queue) are picked up immediately on startup.
+
+        Returns:
+            `Self`: This dispatcher instance.
+        """
+        ready = asyncio.Event()
+        self._task = asyncio.create_task(
+            self._loop(ready),
+            name="wakeup-dispatcher",
+        )
+        await ready.wait()
+        await self._drain_and_dispatch()
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        """Cancel the dispatcher loop and any pending retries."""
+        retries = list(self._retry_tasks)
+        for retry in retries:
+            retry.cancel()
+        for retry in retries:
+            try:
+                await retry
+            except asyncio.CancelledError:
+                pass
+        self._retry_tasks.clear()
+        if self._task is None:
+            return
+        self._task.cancel()
+        try:
+            await self._task
+        except asyncio.CancelledError:
+            pass
+        self._task = None
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    async def _loop(self, ready: asyncio.Event) -> None:
+        """Long-lived loop: subscribe to the signal channel and drain
+        the queue on every received signal.
+
+        Args:
+            ready (`asyncio.Event`):
+                Signalled after the underlying SUBSCRIBE completes.
+                :meth:`start` blocks on this so callers can publish a
+                trigger immediately after start without racing.
+        """
+        try:
+            async for _signal in self._bus.subscribe(
+                MessageBusKeys.wakeup_signal(),
+                on_ready=ready.set,
+            ):
+                await self._drain_and_dispatch()
+        except Exception:  # pylint: disable=broad-except
+            logger.exception(
+                "WakeupDispatcher loop crashed; subscription ended.",
+            )
+
+    async def _drain_and_dispatch(self) -> None:
+        """Read up to a batch of trigger entries and dispatch each."""
+        try:
+            raw_entries = await self._bus.queue_drain(
+                MessageBusKeys.wakeup_queue(),
+                max_count=64,
+            )
+            entries = [payload for _entry_id, payload in raw_entries]
+        except Exception:  # pylint: disable=broad-except
+            logger.exception("WakeupDispatcher: dequeue_wakeups failed.")
+            return
+
+        for payload in entries:
+            try:
+                user_id = payload["user_id"]
+                session_id = payload["session_id"]
+                agent_id = payload["agent_id"]
+            except (KeyError, TypeError):
+                logger.warning(
+                    "WakeupDispatcher: skipping malformed trigger entry %r",
+                    payload,
+                )
+                continue
+            # Entries from older producers omit ``kind`` — treat as wake.
+            kind = payload.get("kind", MessageBusKeys.WAKEUP_KIND_WAKE)
+            await self._dispatch_one(
+                user_id=user_id,
+                session_id=session_id,
+                agent_id=agent_id,
+                kind=kind,
+                raw_input=payload.get("input"),
+            )
+
+    async def _dispatch_one(
+        self,
+        user_id: str,
+        session_id: str,
+        agent_id: str,
+        kind: str,
+        raw_input: dict | None,
+    ) -> None:
+        """Dispatch a single trigger entry by its ``kind``.
+
+        Args:
+            user_id (`str`):
+                The owning user id.
+            session_id (`str`):
+                The session to trigger.
+            agent_id (`str`):
+                The agent that owns the session.
+            kind (`str`):
+                Trigger kind (``wake`` / ``resume``); see module docstring.
+            raw_input (`dict | None`):
+                Serialised input event for ``resume`` triggers, else
+                ``None``.
+        """
+        is_resume = kind == MessageBusKeys.WAKEUP_KIND_RESUME
+
+        # Parse the resume input early so every downstream path
+        # (lock-retry, spawn-retry) receives a typed event object
+        # rather than a raw dict.
+        input_msg: UserConfirmResultEvent | ExternalExecutionResultEvent | None
+        input_msg = None
+        if is_resume:
+            if raw_input is None:
+                logger.warning(
+                    "WakeupDispatcher: dropping resume trigger for session "
+                    "%s — no input event carried.",
+                    session_id,
+                )
+                return
+            try:
+                input_msg = _RESUME_INPUT_ADAPTER.validate_python(raw_input)
+            except Exception:  # pylint: disable=broad-except
+                logger.exception(
+                    "WakeupDispatcher: dropping resume trigger for session "
+                    "%s — input event failed to parse: %r",
+                    session_id,
+                    raw_input,
+                )
+                return
+
+        if await self._bus.is_locked(
+            MessageBusKeys.session_lock(session_id),
+        ):
+            if is_resume:
+                # The session is busy finishing its parked tail. Do NOT
+                # drop the resume — re-queue it after a short backoff so
+                # it lands once the parked run releases its lock.
+                self._schedule_resume_retry(
+                    user_id,
+                    session_id,
+                    agent_id,
+                    input_msg,
+                )
+            # ``wake`` triggers are safe to drop while running — the
+            # live run drains the inbox itself.
+            return
+
+        # Orphan guard: the queue is unaware of session lifecycle. A
+        # trigger enqueued before the session was deleted (e.g. by a
+        # BG-task completion callback or a schedule trigger) will still
+        # arrive here. Drop it rather than letting ChatService.run crash
+        # on a missing storage record.
+        if (
+            await self._storage.get_session(user_id, agent_id, session_id)
+            is None
+        ):
+            logger.warning(
+                "WakeupDispatcher: dropping %s trigger for session %s "
+                "(agent %s, user %s) — session no longer exists in "
+                "storage; it was likely enqueued before the session was "
+                "deleted.",
+                kind,
+                session_id,
+                agent_id,
+                user_id,
+            )
+            return
+
+        try:
+            self._registry.spawn(
+                self._chat_service.run(
+                    user_id=user_id,
+                    session_id=session_id,
+                    agent_id=agent_id,
+                    input_msg=input_msg,
+                ),
+                session_id=session_id,
+                name=f"{kind}-run:{session_id}",
+            )
+        except RuntimeError:
+            # A local run was registered between the running-check and
+            # the spawn. For ``wake`` that run will drain the inbox; for
+            # ``resume`` re-queue so the result is not lost.
+            if is_resume:
+                self._schedule_resume_retry(
+                    user_id,
+                    session_id,
+                    agent_id,
+                    input_msg,
+                )
+            else:
+                logger.debug(
+                    "WakeupDispatcher: skipping wake trigger for session "
+                    "%s; a local run is already registered.",
+                    session_id,
+                )
+
+    def _schedule_resume_retry(
+        self,
+        user_id: str,
+        session_id: str,
+        agent_id: str,
+        input_msg: UserConfirmResultEvent
+        | ExternalExecutionResultEvent
+        | None,
+    ) -> None:
+        """Re-enqueue a ``resume`` trigger after a short backoff.
+
+        Spawns a detached timer that sleeps, then re-enqueues the resume
+        (which re-fires the signal, re-driving the drain). This keeps the
+        resume alive across the window where the parked run still holds
+        the session lock, without a hot re-enqueue loop.
+
+        Args:
+            user_id (`str`):
+                The owning user id.
+            session_id (`str`):
+                The session to resume.
+            agent_id (`str`):
+                The agent that owns the session.
+            input_msg:
+                The parsed input event to redeliver.
+        """
+
+        async def _retry() -> None:
+            try:
+                await asyncio.sleep(_RESUME_RETRY_BACKOFF_SECS)
+                await enqueue_run_trigger(
+                    self._bus,
+                    user_id=user_id,
+                    session_id=session_id,
+                    agent_id=agent_id,
+                    kind=MessageBusKeys.WAKEUP_KIND_RESUME,
+                    inputs=input_msg,
+                )
+            except asyncio.CancelledError:
+                pass
+            except Exception:  # pylint: disable=broad-except
+                logger.exception(
+                    "WakeupDispatcher: failed to re-enqueue resume trigger "
+                    "for session %s.",
+                    session_id,
+                )
+
+        task = asyncio.create_task(
+            _retry(),
+            name=f"resume-retry:{session_id}",
+        )
+        self._retry_tasks.add(task)
+        task.add_done_callback(self._retry_tasks.discard)

src/agentscope/app/_router/__init__.py

@@ -0,0 +1,23 @@
+# -*- coding: utf-8 -*-
+"""App routers."""
+from ._agent import agent_router
+from ._chat import chat_router
+from ._credential import credential_router
+from ._knowledge_base import knowledge_base_router
+from ._schedule import schedule_router
+from ._session import session_router
+from ._model import model_router
+from ._tts_model import tts_model_router
+from ._workspace import workspace_router
+
+__all__ = [
+    "agent_router",
+    "model_router",
+    "tts_model_router",
+    "chat_router",
+    "credential_router",
+    "knowledge_base_router",
+    "schedule_router",
+    "session_router",
+    "workspace_router",
+]

src/agentscope/app/_router/_agent.py

@@ -0,0 +1,214 @@
+# -*- coding: utf-8 -*-
+"""Agent router — CRUD endpoints for agent configurations."""
+from datetime import datetime
+
+from fastapi import APIRouter, Depends, HTTPException, status
+
+from ...agent import ContextConfig, ReActConfig
+from ..deps import get_current_user_id, get_session_service, get_storage
+from ._schema import (
+    AgentSchemaResponse,
+    ListAgentsResponse,
+    CreateAgentRequest,
+    CreateAgentResponse,
+    UpdateAgentRequest,
+)
+from .._service import SessionService
+from ..storage import StorageBase, AgentData, AgentRecord
+
+agent_router = APIRouter(
+    prefix="/agent",
+    tags=["agent"],
+    responses={404: {"description": "Not found"}},
+)
+
+
+@agent_router.get(
+    "/schema",
+    response_model=AgentSchemaResponse,
+    summary="Get JSON Schema fragments for the agent form",
+)
+async def get_agent_schema() -> AgentSchemaResponse:
+    """Return the JSON Schema fragments used by the frontend to render
+    the agent create / edit forms.
+
+    The frontend uses three sections — identity, context config, and
+    react config — so we return them as separate self-contained schemas
+    rather than a single ``AgentData`` schema with ``$ref``s.
+
+    Returns:
+        `AgentSchemaResponse`:
+            Schemas for the three form sections.
+    """
+    # Slice ``AgentData``'s schema down to the identity-relevant fields.
+    # Going through ``AgentData.model_json_schema()`` (rather than building
+    # a dict by hand) keeps Pydantic as the single source of truth for
+    # defaults, titles, descriptions, and the ``format: textarea`` hint.
+    agent_schema = AgentData.model_json_schema()
+    identity_keys = ("name", "system_prompt")
+    identity = {
+        "type": "object",
+        "title": "Identity",
+        "properties": {
+            k: v
+            for k, v in agent_schema.get("properties", {}).items()
+            if k in identity_keys
+        },
+        "required": [
+            r for r in agent_schema.get("required", []) if r in identity_keys
+        ],
+    }
+
+    context_schema = ContextConfig.model_json_schema()
+    # ``summary_schema`` holds a Pydantic JSON Schema describing how the
+    # compression model should structure its output. The end-user is not
+    # expected to edit it from the form, so we hide it.
+    context_schema.get("properties", {}).pop("summary_schema", None)
+
+    return AgentSchemaResponse(
+        identity=identity,
+        context_config=context_schema,
+        react_config=ReActConfig.model_json_schema(),
+    )
+
+
+@agent_router.get(
+    "/",
+    response_model=ListAgentsResponse,
+    summary="List all agents",
+)
+async def list_agents(
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+) -> ListAgentsResponse:
+    """Return all agent records belonging to the authenticated user.
+
+    Args:
+        user_id (`str`):
+            Injected authenticated user ID.
+        storage (`StorageBase`):
+            Injected storage backend.
+
+    Returns:
+        `ListAgentsResponse`:
+            All agent records and their total count.
+    """
+    agents = await storage.list_agents(user_id)
+    return ListAgentsResponse(agents=agents, total=len(agents))
+
+
+@agent_router.post(
+    "/",
+    response_model=CreateAgentResponse,
+    status_code=status.HTTP_201_CREATED,
+    summary="Create a new agent",
+)
+async def create_agent(
+    body: CreateAgentRequest,
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+) -> CreateAgentResponse:
+    """Create and persist a new agent configuration.
+
+    Args:
+        body (`CreateAgentRequest`):
+            Agent configuration to store.
+        user_id (`str`):
+            Injected authenticated user ID.
+        storage (`StorageBase`):
+            Injected storage backend.
+
+    Returns:
+        `CreateAgentResponse`:
+            The server-assigned agent identifier.
+    """
+    record = AgentRecord(
+        user_id=user_id,
+        data=AgentData(
+            name=body.name,
+            system_prompt=body.system_prompt,
+            context_config=body.context_config,
+            react_config=body.react_config,
+        ),
+    )
+    agent_id = await storage.upsert_agent(user_id, record)
+    return CreateAgentResponse(agent_id=agent_id)
+
+
+@agent_router.patch(
+    "/{agent_id}",
+    response_model=AgentRecord,
+    summary="Update an agent",
+)
+async def update_agent(
+    agent_id: str,
+    body: UpdateAgentRequest,
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+) -> AgentRecord:
+    """Partially update an existing agent configuration.
+
+    Only the fields present in the request body are updated; all other fields
+    keep their current values.
+
+    Args:
+        agent_id (`str`): The agent to update.
+        body (`UpdateAgentRequest`): Fields to update.
+        user_id (`str`): Injected authenticated user ID.
+        storage (`StorageBase`): Injected storage backend.
+
+    Returns:
+        `AgentRecord`: The full agent record after the update.
+
+    Raises:
+        `HTTPException`: 404 if the agent does not exist or does not belong
+            to the authenticated user.
+    """
+    agents = await storage.list_agents(user_id)
+    existing = next((a for a in agents if a.id == agent_id), None)
+    if existing is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Agent '{agent_id}' not found.",
+        )
+
+    updates = body.model_dump(exclude_none=True)
+    updated_data = existing.data.model_copy(update=updates)
+    updated_agent = existing.model_copy(
+        update={"data": updated_data, "updated_at": datetime.now()},
+    )
+    await storage.upsert_agent(user_id, updated_agent)
+    return updated_agent
+
+
+@agent_router.delete(
+    "/{agent_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+    summary="Delete an agent",
+)
+async def delete_agent(
+    agent_id: str,
+    user_id: str = Depends(get_current_user_id),
+    session_service: SessionService = Depends(get_session_service),
+) -> None:
+    """Permanently delete an agent configuration.
+
+    Cascades through every session owned by this agent (and, for team
+    leaders, through every worker session) — cancelling any in-flight
+    chat run, removing storage records, and purging bus state.
+
+    Args:
+        agent_id (`str`): The agent to delete.
+        user_id (`str`): Injected authenticated user ID.
+        session_service (`SessionService`): Injected session service.
+
+    Raises:
+        `HTTPException`: 404 if the agent does not exist or does not belong
+            to the authenticated user.
+    """
+    deleted = await session_service.delete_agent(user_id, agent_id)
+    if not deleted:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Agent '{agent_id}' not found.",
+        )

src/agentscope/app/_router/_chat.py

@@ -0,0 +1,160 @@
+# -*- coding: utf-8 -*-
+"""Chat router — fire-and-forget trigger for chat runs.
+
+The endpoint no longer returns an SSE stream. Instead, it kicks off a
+chat run as a background task and returns immediately. Events produced
+by the run are published to the message bus and delivered to the
+frontend via the long-lived ``GET /sessions/{sid}/stream`` SSE
+connection provided by the session router.
+
+Two trigger paths, deliberately asymmetric:
+
+- **New user message(s)** are spawned directly into the
+  :class:`ChatRunRegistry`. The registry's single-run-per-session rule
+  surfaces as a 409, which is exactly the desired double-submit guard.
+- **HITL results** (``UserConfirmResultEvent`` /
+  ``ExternalExecutionResultEvent``) are *enqueued* onto the shared
+  run-trigger queue and drained by the single
+  :class:`WakeupDispatcher`. Routing the resume through the queue keeps
+  the dispatcher the sole spawn site, so a resume can never collide with
+  the worker's still-finishing parked run (the old 409 race) — the
+  dispatcher serialises them.
+"""
+from fastapi import APIRouter, Depends, HTTPException, status
+
+from ..deps import (
+    get_chat_run_registry,
+    get_chat_service,
+    get_current_user_id,
+    get_message_bus,
+)
+from ._schema import ChatRequest, ChatTriggerResponse
+from .._manager import ChatRunRegistry
+from .._service import (
+    ChatService,
+    SessionProjection,
+    SubagentHitlProjector,
+)
+from ..message_bus import MessageBus, MessageBusKeys
+from .._bus_ops import enqueue_run_trigger
+from ...event import UserConfirmResultEvent, ExternalExecutionResultEvent
+
+chat_router = APIRouter(
+    prefix="/chat",
+    tags=["chat"],
+    responses={404: {"description": "Not found"}},
+)
+
+
+@chat_router.post(
+    "/",
+    response_model=ChatTriggerResponse,
+    summary="Trigger a chat run (fire-and-forget)",
+)
+async def chat(
+    request: ChatRequest,
+    user_id: str = Depends(get_current_user_id),
+    chat_service: ChatService = Depends(get_chat_service),
+    chat_run_registry: ChatRunRegistry = Depends(get_chat_run_registry),
+    message_bus: MessageBus = Depends(get_message_bus),
+) -> ChatTriggerResponse:
+    """Trigger a chat run for the specified session.
+
+    Events produced during the run are published to the message bus and
+    delivered to any active ``GET /sessions/{session_id}/stream`` SSE
+    subscriber. The caller does **not** receive events from this
+    endpoint's response body.
+
+    Accepts the same ``input`` payloads as before:
+
+    - ``Msg`` / ``list[Msg]``: new user message(s) — spawned directly.
+    - ``UserConfirmResultEvent`` / ``ExternalExecutionResultEvent``:
+      resume a paused tool call (human-in-the-loop) — routed to the
+      owning session and enqueued for the dispatcher.
+    - ``None``: continue from current state — spawned directly.
+
+    Args:
+        request (`ChatRequest`):
+            JSON body with ``agent_id``, ``session_id``, and ``input``.
+        user_id (`str`):
+            Injected user id.
+        chat_service (`ChatService`):
+            Injected application-wide chat service.
+        chat_run_registry (`ChatRunRegistry`):
+            Injected per-process chat-run registry.
+        message_bus (`MessageBus`):
+            Injected message bus, used to resolve subagent-confirm
+            routing and to enqueue resume triggers.
+
+    Returns:
+        `ChatTriggerResponse`:
+            Confirms the run was scheduled (for a resume, that it was
+            enqueued).
+
+    Raises:
+        `HTTPException`:
+            409 if a chat run for this session is already in flight in
+            this process (the registry enforces single-run-per-session).
+            Only direct-spawn paths (new messages / ``None``) can raise
+            this; the enqueued resume path never does.
+    """
+    # ------------------------------------------------------------------
+    # HITL resume — route to the owning session, then enqueue.
+    #
+    # A confirmation / external-result POSTed to a *leader* session may
+    # actually belong to a team *member*: the leader is the single front
+    # door clients talk to. Resolve the owning worker HERE, then enqueue
+    # a ``resume`` trigger for that session. The single WakeupDispatcher
+    # drains it — spawning under the *worker* session id, serialised
+    # behind any still-finishing parked run, so there is no registry
+    # collision (no 409) and the leader's run slot is never occupied by
+    # the worker's resume.
+    # ------------------------------------------------------------------
+    if isinstance(
+        request.input,
+        (UserConfirmResultEvent, ExternalExecutionResultEvent),
+    ):
+        run_session_id = request.session_id
+        run_agent_id = request.agent_id
+        target = await SubagentHitlProjector.resolve(
+            SessionProjection(message_bus),
+            request.session_id,
+            request.input.reply_id,
+        )
+        if target is not None:
+            run_session_id = target["worker_session_id"]
+            run_agent_id = target["worker_agent_id"]
+
+        await enqueue_run_trigger(
+            message_bus,
+            user_id=user_id,
+            session_id=run_session_id,
+            agent_id=run_agent_id,
+            kind=MessageBusKeys.WAKEUP_KIND_RESUME,
+            inputs=request.input,
+        )
+        return ChatTriggerResponse(status="started", session_id=run_session_id)
+
+    # ------------------------------------------------------------------
+    # New user message(s) / None — spawn directly. The registry's
+    # single-run-per-session rule is the desired double-submit guard.
+    # ------------------------------------------------------------------
+    try:
+        chat_run_registry.spawn(
+            chat_service.run(
+                user_id=user_id,
+                session_id=request.session_id,
+                agent_id=request.agent_id,
+                input_msg=request.input,
+            ),
+            session_id=request.session_id,
+        )
+    except RuntimeError as e:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=str(e),
+        ) from e
+    return ChatTriggerResponse(
+        status="started",
+        session_id=request.session_id,
+    )

src/agentscope/app/_router/_credential.py

@@ -0,0 +1,164 @@
+# -*- coding: utf-8 -*-
+"""Credential router — CRUD endpoints for API key credentials."""
+from fastapi import APIRouter, Depends, HTTPException, status
+
+from ..deps import get_current_user_id, get_storage
+from ._schema import (
+    CreateCredentialRequest,
+    CreateCredentialResponse,
+    ListCredentialsResponse,
+    ListCredentialSchemasResponse,
+    UpdateCredentialRequest,
+)
+from ..storage import StorageBase, CredentialRecord
+from ...credential import CredentialFactory
+
+credential_router = APIRouter(
+    prefix="/credential",
+    tags=["credential"],
+    responses={404: {"description": "Not found"}},
+)
+
+
+@credential_router.get(
+    "/schemas",
+    response_model=ListCredentialSchemasResponse,
+    summary="List JSON schemas for all credential types",
+)
+async def list_credential_schemas() -> ListCredentialSchemasResponse:
+    """Return JSON schemas for all registered credential types.
+
+    Used by the frontend to render credential creation forms dynamically.
+    """
+
+    return ListCredentialSchemasResponse(
+        schemas=CredentialFactory.list_schemas(),
+    )
+
+
+@credential_router.get(
+    "/",
+    response_model=ListCredentialsResponse,
+    summary="List all credentials",
+)
+async def list_credentials(
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+) -> ListCredentialsResponse:
+    """Return all credential records belonging to the authenticated user.
+
+    Args:
+        user_id (`str`):
+            Injected authenticated user ID.
+        storage (`StorageBase`):
+            Injected storage backend.
+
+    Returns:
+        `ListCredentialsResponse`:
+            All credential records and their total count.
+    """
+    credentials = await storage.list_credentials(user_id)
+    return ListCredentialsResponse(
+        credentials=credentials,
+        total=len(credentials),
+    )
+
+
+@credential_router.post(
+    "/",
+    response_model=CreateCredentialResponse,
+    status_code=status.HTTP_201_CREATED,
+    summary="Create a new credential",
+)
+async def create_credential(
+    body: CreateCredentialRequest,
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+) -> CreateCredentialResponse:
+    """Store a new credential.
+
+    Args:
+        body (`CreateCredentialRequest`): Credential payload to store.
+        user_id (`str`): Injected authenticated user ID.
+        storage (`StorageBase`): Injected storage backend.
+
+    Returns:
+        `CreateCredentialResponse`: The server-assigned credential identifier.
+    """
+    credential_id = await storage.upsert_credential(
+        user_id,
+        CredentialFactory.from_dict(body.data),
+    )
+    return CreateCredentialResponse(credential_id=credential_id)
+
+
+@credential_router.patch(
+    "/{credential_id}",
+    response_model=CredentialRecord,
+    summary="Update a credential",
+)
+async def update_credential(
+    credential_id: str,
+    body: UpdateCredentialRequest,
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+) -> CredentialRecord:
+    """Replace the payload of an existing credential.
+
+    Args:
+        credential_id (`str`): The credential to update.
+        body (`UpdateCredentialRequest`): New credential payload.
+        user_id (`str`): Injected authenticated user ID.
+        storage (`StorageBase`): Injected storage backend.
+
+    Returns:
+        `CredentialRecord`: The updated credential record.
+
+    Raises:
+        `HTTPException`: 404 if the credential does not exist or does not
+            belong to the authenticated user.
+    """
+    credentials = await storage.list_credentials(user_id)
+    existing = next((c for c in credentials if c.id == credential_id), None)
+    if existing is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Credential '{credential_id}' not found.",
+        )
+
+    credential = CredentialFactory.from_dict(body.data)
+    credential.id = credential_id
+    await storage.upsert_credential(user_id, credential)
+    # Re-fetch to return the persisted record with updated timestamps.
+    credentials = await storage.list_credentials(user_id)
+    updated = next(c for c in credentials if c.id == credential_id)
+    return updated
+
+
+@credential_router.delete(
+    "/{credential_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+    summary="Delete a credential",
+)
+async def delete_credential(
+    credential_id: str,
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+) -> None:
+    """Permanently delete a credential.
+
+    Args:
+        credential_id (`str`): The credential to delete.
+        user_id (`str`): Injected authenticated user ID.
+        storage (`StorageBase`): Injected storage backend.
+
+    Raises:
+        `HTTPException`: 404 if the credential does not exist or does not
+            belong to the authenticated user.
+    """
+    deleted = await storage.delete_credential(user_id, credential_id)
+    if not deleted:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Credential '{credential_id}' not found.",
+        )

src/agentscope/app/_router/_knowledge_base.py

@@ -0,0 +1,574 @@
+# -*- coding: utf-8 -*-
+"""Knowledge base router — manage knowledge bases and their documents.
+
+A knowledge base is the user-facing concept; physically each one maps
+to a single vector store collection (in the MVP isolation strategy).
+The HTTP layer is intentionally thin — every endpoint translates the
+request into a single :class:`~agentscope.app._service.
+KnowledgeBaseService` call and returns the result.
+"""
+from fastapi import (
+    APIRouter,
+    Depends,
+    File,
+    Form,
+    Path,
+    Query,
+    UploadFile,
+    status,
+)
+
+from ..deps import (
+    get_current_user_id,
+    get_knowledge_base_manager,
+    get_knowledge_base_service,
+    get_knowledge_parsers,
+    get_storage,
+)
+from ._schema import (
+    CreateKnowledgeBaseRequest,
+    CreateKnowledgeBaseResponse,
+    KbEmbeddingProvider,
+    KbMiddlewareParametersSchemaResponse,
+    KnowledgeBaseView,
+    KnowledgeDocumentView,
+    ListKbEmbeddingModelsResponse,
+    ListKnowledgeBasesResponse,
+    ListKnowledgeDocumentsResponse,
+    ListKnowledgeDocumentStatusResponse,
+    ListSupportedContentTypesResponse,
+    SearchKnowledgeBaseRequest,
+    SearchKnowledgeBaseResponse,
+    UpdateKnowledgeBaseRequest,
+    UploadKnowledgeDocumentResponse,
+)
+from ...credential import CredentialFactory
+from ..rag.knowledge_base_manager import KnowledgeBaseManagerBase
+from ..storage import StorageBase
+from .._service import KnowledgeBaseService
+from ...middleware import RAGMiddleware
+from ...rag import ParserBase
+
+
+knowledge_base_router = APIRouter(
+    prefix="/knowledge_bases",
+    tags=["knowledge_bases"],
+    responses={404: {"description": "Not found"}},
+)
+
+
+@knowledge_base_router.get(
+    "/embedding_models",
+    response_model=ListKbEmbeddingModelsResponse,
+    summary="List embedding models compatible with the KB dimension policy",
+)
+async def list_kb_embedding_models(
+    user_id: str = Depends(get_current_user_id),
+    storage: "StorageBase" = Depends(get_storage),
+    manager: "KnowledgeBaseManagerBase" = Depends(
+        get_knowledge_base_manager,
+    ),
+) -> ListKbEmbeddingModelsResponse:
+    """List embedding models the user can pick at KB-creation time.
+
+    Walks the caller's credentials, looks up each provider's
+    embedding model class, gathers its model cards, and projects
+    each card through the manager's :class:`DimensionPolicy`.
+    Incompatible cards are dropped; matryoshka cards under a
+    ``FIXED`` / ``LOCKED_BY_EXISTING`` policy are narrowed to the
+    locked dimension.  Providers that end up with zero compatible
+    models are omitted from the response entirely.
+
+    Args:
+        user_id (`str`):
+            Injected authenticated user ID.
+        storage (`StorageBase`):
+            Injected storage backend used to enumerate credentials.
+        manager (`KnowledgeBaseManagerBase`):
+            Injected knowledge base manager.
+
+    Returns:
+        `ListKbEmbeddingModelsResponse`:
+            One entry per credential with at least one compatible
+            embedding model, plus the policy used for filtering.
+    """
+    policy = await manager.get_dimension_policy()
+    credentials = await storage.list_credentials(user_id)
+
+    providers: list[KbEmbeddingProvider] = []
+    for credential in credentials:
+        credential_type = credential.data.get("type")
+        if not credential_type:
+            continue
+        credential_cls = CredentialFactory.get_credential_class(
+            credential_type,
+        )
+        if credential_cls is None:
+            continue
+        embedding_cls = credential_cls.get_embedding_model_class()
+        if embedding_cls is None:
+            continue
+
+        filtered = []
+        for card in embedding_cls.list_models():
+            projected = policy.filter_card(card)
+            if projected is not None:
+                filtered.append(projected)
+        if not filtered:
+            continue
+        providers.append(
+            KbEmbeddingProvider(credential=credential, models=filtered),
+        )
+
+    return ListKbEmbeddingModelsResponse(providers=providers, policy=policy)
+
+
+@knowledge_base_router.get(
+    "/middleware/parameters_schema",
+    response_model=KbMiddlewareParametersSchemaResponse,
+    summary="JSON Schema for the KB middleware's tunable parameters",
+)
+async def get_kb_middleware_parameters_schema(
+    _: str = Depends(get_current_user_id),
+) -> KbMiddlewareParametersSchemaResponse:
+    """Return the parameter schema for
+    :class:`agentscope.middleware.RAGMiddleware`.
+
+    The schema is shaped like every other ``parameter_schema`` served
+    by this service — title / description / default / enum / minimum
+    / maximum — so the front-end can render the session-level KB
+    attachment form with the same schema-driven component used for
+    model parameters.
+
+    Args:
+        _ (`str`):
+            Injected authenticated user ID; only used to gate the
+            endpoint behind authentication.
+
+    Returns:
+        `KbMiddlewareParametersSchemaResponse`:
+            The JSON Schema describing the middleware's
+            user-tunable parameters.
+    """
+    return KbMiddlewareParametersSchemaResponse(
+        parameter_schema=(RAGMiddleware.Parameters.model_json_schema()),
+    )
+
+
+@knowledge_base_router.get(
+    "/supported_content_types",
+    response_model=ListSupportedContentTypesResponse,
+    summary="List file types the configured parsers can ingest",
+)
+async def list_supported_content_types(
+    _: str = Depends(get_current_user_id),
+    parsers: list[ParserBase]
+    | dict[str, ParserBase] = Depends(
+        get_knowledge_parsers,
+    ),
+) -> ListSupportedContentTypesResponse:
+    """Advertise the union of media types and filename extensions every
+    registered parser accepts.
+
+    Used by the front-end to populate the document picker's ``accept``
+    attribute and to reject drag-dropped files whose extension lies
+    outside the supported set before the upload starts.  Routing on
+    upload still goes through the media type — this endpoint is a
+    capability hint, not authoritative dispatch.
+
+    Args:
+        _ (`str`):
+            Injected authenticated user ID; only used to gate the
+            endpoint behind authentication.
+        parsers (`list[ParserBase] | dict[str, ParserBase]`):
+            Injected parser registry — the same value the index worker
+            uses to dispatch uploads.
+
+    Returns:
+        `ListSupportedContentTypesResponse`:
+            Deduplicated, sorted unions of ``media_types`` and
+            ``extensions``.
+    """
+    parser_iter = parsers.values() if isinstance(parsers, dict) else parsers
+    media_types: set[str] = set()
+    extensions: set[str] = set()
+    for parser in parser_iter:
+        media_types.update(parser.supported_media_types)
+        extensions.update(parser.supported_extensions())
+    return ListSupportedContentTypesResponse(
+        media_types=sorted(media_types),
+        extensions=sorted(extensions),
+    )
+
+
+# ----------------------------------------------------------------------
+# Knowledge base management
+# ----------------------------------------------------------------------
+
+
+@knowledge_base_router.post(
+    "/",
+    response_model=CreateKnowledgeBaseResponse,
+    status_code=status.HTTP_201_CREATED,
+    summary="Create a new knowledge base",
+)
+async def create_knowledge_base(
+    body: CreateKnowledgeBaseRequest,
+    user_id: str = Depends(get_current_user_id),
+    service: "KnowledgeBaseService" = Depends(get_knowledge_base_service),
+) -> CreateKnowledgeBaseResponse:
+    """Create a new knowledge base for the authenticated user.
+
+    Allocates a fresh vector store collection sized to the embedding
+    model's output dimension and persists the knowledge base record.
+
+    Args:
+        body (`CreateKnowledgeBaseRequest`):
+            Knowledge base name, description, and embedding model
+            configuration.
+        user_id (`str`):
+            Injected authenticated user ID.
+        service (`KnowledgeBaseService`):
+            Injected knowledge base service.
+
+    Returns:
+        `CreateKnowledgeBaseResponse`:
+            The server-assigned knowledge base identifier.
+    """
+    record = await service.create_knowledge_base(
+        user_id=user_id,
+        name=body.name,
+        description=body.description,
+        embedding_model_config=body.embedding_model_config,
+    )
+    return CreateKnowledgeBaseResponse(knowledge_base_id=record.id)
+
+
+@knowledge_base_router.get(
+    "/",
+    response_model=ListKnowledgeBasesResponse,
+    summary="List the caller's knowledge bases",
+)
+async def list_knowledge_bases(
+    user_id: str = Depends(get_current_user_id),
+    service: "KnowledgeBaseService" = Depends(get_knowledge_base_service),
+) -> ListKnowledgeBasesResponse:
+    """Return all knowledge bases owned by the authenticated user.
+
+    Args:
+        user_id (`str`):
+            Injected authenticated user ID.
+        service (`KnowledgeBaseService`):
+            Injected knowledge base service.
+
+    Returns:
+        `ListKnowledgeBasesResponse`:
+            The user's knowledge bases.
+    """
+    records = await service.list_knowledge_bases(user_id)
+    views = [
+        KnowledgeBaseView(
+            id=record.id,
+            name=record.name,
+            description=record.description,
+            embedding_model_config=record.embedding_model_config,
+            created_at=record.created_at,
+            updated_at=record.updated_at,
+        )
+        for record in records
+    ]
+    return ListKnowledgeBasesResponse(knowledge_bases=views, total=len(views))
+
+
+@knowledge_base_router.patch(
+    "/{knowledge_base_id}",
+    response_model=KnowledgeBaseView,
+    summary="Update mutable fields on a knowledge base",
+)
+async def update_knowledge_base(
+    body: UpdateKnowledgeBaseRequest,
+    knowledge_base_id: str = Path(description="The knowledge base id."),
+    user_id: str = Depends(get_current_user_id),
+    service: "KnowledgeBaseService" = Depends(get_knowledge_base_service),
+) -> KnowledgeBaseView:
+    """Update mutable fields on a knowledge base.
+
+    Only ``name`` and ``description`` can be updated.  The embedding
+    model configuration is pinned at creation time and cannot be
+    changed.
+
+    Args:
+        body (`UpdateKnowledgeBaseRequest`):
+            The fields to update; omitted fields stay unchanged.
+        knowledge_base_id (`str`):
+            The knowledge base to update.
+        user_id (`str`):
+            Injected authenticated user ID.
+        service (`KnowledgeBaseService`):
+            Injected knowledge base service.
+
+    Returns:
+        `KnowledgeBaseView`:
+            The knowledge base record after the update.
+    """
+    record = await service.update_knowledge_base(
+        user_id=user_id,
+        knowledge_base_id=knowledge_base_id,
+        name=body.name,
+        description=body.description,
+    )
+    return KnowledgeBaseView(
+        id=record.id,
+        name=record.name,
+        description=record.description,
+        embedding_model_config=record.embedding_model_config,
+        created_at=record.created_at,
+        updated_at=record.updated_at,
+    )
+
+
+@knowledge_base_router.delete(
+    "/{knowledge_base_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+    summary="Delete a knowledge base",
+)
+async def delete_knowledge_base(
+    knowledge_base_id: str = Path(description="The knowledge base id."),
+    user_id: str = Depends(get_current_user_id),
+    service: "KnowledgeBaseService" = Depends(get_knowledge_base_service),
+) -> None:
+    """Permanently delete a knowledge base.
+
+    Drops the underlying vector store collection together with every
+    associated document and the knowledge base record itself.
+
+    Args:
+        knowledge_base_id (`str`):
+            The knowledge base to delete.
+        user_id (`str`):
+            Injected authenticated user ID.
+        service (`KnowledgeBaseService`):
+            Injected knowledge base service.
+    """
+    await service.delete_knowledge_base(user_id, knowledge_base_id)
+
+
+# ----------------------------------------------------------------------
+# Document management
+# ----------------------------------------------------------------------
+
+
+@knowledge_base_router.get(
+    "/{knowledge_base_id}/documents",
+    response_model=ListKnowledgeDocumentsResponse,
+    summary="List documents registered in a knowledge base",
+)
+async def list_knowledge_documents(
+    knowledge_base_id: str = Path(description="The knowledge base id."),
+    user_id: str = Depends(get_current_user_id),
+    service: "KnowledgeBaseService" = Depends(get_knowledge_base_service),
+) -> ListKnowledgeDocumentsResponse:
+    """List every document registered against a knowledge base.
+
+    Reads from the storage backend (service-mode source of truth), so
+    documents in any lifecycle state — including ``pending`` /
+    ``parsing`` / ``error`` — are returned alongside ``ready`` ones.
+
+    Args:
+        knowledge_base_id (`str`):
+            The target knowledge base id.
+        user_id (`str`):
+            Injected authenticated user ID.
+        service (`KnowledgeBaseService`):
+            Injected knowledge base service.
+
+    Returns:
+        `ListKnowledgeDocumentsResponse`:
+            One view per registered document.
+    """
+    records = await service.list_documents(user_id, knowledge_base_id)
+    views = [KnowledgeDocumentView.from_record(r) for r in records]
+    return ListKnowledgeDocumentsResponse(
+        documents=views,
+        total=len(views),
+    )
+
+
+@knowledge_base_router.get(
+    "/{knowledge_base_id}/documents/status",
+    response_model=ListKnowledgeDocumentStatusResponse,
+    summary="Batch-query indexing status of one or more documents",
+)
+async def list_knowledge_document_status(
+    knowledge_base_id: str = Path(description="The knowledge base id."),
+    ids: str = Query(
+        description=(
+            "Comma-separated list of document ids to query. "
+            "Missing ids are silently omitted from the response."
+        ),
+    ),
+    user_id: str = Depends(get_current_user_id),
+    service: "KnowledgeBaseService" = Depends(get_knowledge_base_service),
+) -> ListKnowledgeDocumentStatusResponse:
+    """Return the current lifecycle state of a batch of documents.
+
+    Designed for the front-end's status polling loop: the page sends
+    every in-flight document id at once so per-document round-trips
+    do not multiply with concurrency.
+
+    Args:
+        knowledge_base_id (`str`):
+            The target knowledge base id.
+        ids (`str`):
+            Comma-separated document ids.
+        user_id (`str`):
+            Injected authenticated user ID.
+        service (`KnowledgeBaseService`):
+            Injected knowledge base service.
+
+    Returns:
+        `ListKnowledgeDocumentStatusResponse`:
+            Views for the matched documents.
+    """
+    document_ids = [tok for tok in (s.strip() for s in ids.split(",")) if tok]
+    records = await service.get_document_status(
+        user_id,
+        knowledge_base_id,
+        document_ids,
+    )
+    return ListKnowledgeDocumentStatusResponse(
+        items=[KnowledgeDocumentView.from_record(r) for r in records],
+    )
+
+
+@knowledge_base_router.post(
+    "/{knowledge_base_id}/documents",
+    response_model=UploadKnowledgeDocumentResponse,
+    status_code=status.HTTP_201_CREATED,
+    summary="Upload a document into a knowledge base",
+)
+async def upload_knowledge_document(
+    knowledge_base_id: str = Path(description="The knowledge base id."),
+    file: UploadFile = File(
+        description="The document to index (PDF, TXT, Markdown, …).",
+    ),
+    content_type: str
+    | None = Form(
+        default=None,
+        description=(
+            "Override the IANA media type used to route the upload. "
+            "Defaults to the type guessed from the filename."
+        ),
+    ),
+    user_id: str = Depends(get_current_user_id),
+    service: "KnowledgeBaseService" = Depends(get_knowledge_base_service),
+) -> UploadKnowledgeDocumentResponse:
+    """Register an uploaded document and dispatch it for indexing.
+
+    The HTTP connection covers only the upload phase: the request body
+    is streamed into the blob store, a ``pending`` document record is
+    persisted, the indexing task is dispatched, and the response is
+    returned.  Parsing / chunking / embedding happen asynchronously in
+    a worker; the client tracks progress via
+    :func:`list_knowledge_document_status`.
+
+    Args:
+        knowledge_base_id (`str`):
+            The knowledge base to receive the document.
+        file (`UploadFile`):
+            The uploaded file (multipart/form-data).
+        content_type (`str | None`, optional):
+            Override the IANA media type used to route the upload.
+        user_id (`str`):
+            Injected authenticated user ID.
+        service (`KnowledgeBaseService`):
+            Injected knowledge base service.
+
+    Returns:
+        `UploadKnowledgeDocumentResponse`:
+            The server-assigned document id, filename, and the
+            initial lifecycle state (always ``"pending"``).
+    """
+    record = await service.register_document(
+        user_id=user_id,
+        knowledge_base_id=knowledge_base_id,
+        filename=file.filename or "uploaded_file",
+        stream=file.file,
+        size=file.size or 0,
+        content_type=content_type or file.content_type,
+    )
+    return UploadKnowledgeDocumentResponse(
+        document_id=record.id,
+        filename=record.data.filename,
+        status=record.data.status,
+    )
+
+
+@knowledge_base_router.delete(
+    "/{knowledge_base_id}/documents/{document_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+    summary="Delete a document from a knowledge base",
+)
+async def delete_knowledge_document(
+    knowledge_base_id: str = Path(description="The knowledge base id."),
+    document_id: str = Path(description="The document id."),
+    user_id: str = Depends(get_current_user_id),
+    service: "KnowledgeBaseService" = Depends(get_knowledge_base_service),
+) -> None:
+    """Remove a document and all its chunks from a knowledge base.
+
+    Args:
+        knowledge_base_id (`str`):
+            The knowledge base the document belongs to.
+        document_id (`str`):
+            The document to delete.
+        user_id (`str`):
+            Injected authenticated user ID.
+        service (`KnowledgeBaseService`):
+            Injected knowledge base service.
+    """
+    await service.delete_document(user_id, knowledge_base_id, document_id)
+
+
+# ----------------------------------------------------------------------
+# Search
+# ----------------------------------------------------------------------
+
+
+@knowledge_base_router.post(
+    "/{knowledge_base_id}/search",
+    response_model=SearchKnowledgeBaseResponse,
+    summary="Search a knowledge base by natural-language query",
+)
+async def search_knowledge_base(
+    body: SearchKnowledgeBaseRequest,
+    knowledge_base_id: str = Path(description="The knowledge base id."),
+    user_id: str = Depends(get_current_user_id),
+    service: "KnowledgeBaseService" = Depends(get_knowledge_base_service),
+) -> SearchKnowledgeBaseResponse:
+    """Run a similarity search over a knowledge base.
+
+    Embeds the query with the knowledge base's configured embedding
+    model and returns the top-K most similar chunks.
+
+    Args:
+        body (`SearchKnowledgeBaseRequest`):
+            The query text and ``top_k``.
+        knowledge_base_id (`str`):
+            The knowledge base to search.
+        user_id (`str`):
+            Injected authenticated user ID.
+        service (`KnowledgeBaseService`):
+            Injected knowledge base service.
+
+    Returns:
+        `SearchKnowledgeBaseResponse`:
+            Matched chunks ordered by descending similarity.
+    """
+    results = await service.search(
+        user_id=user_id,
+        knowledge_base_id=knowledge_base_id,
+        query=body.query,
+        top_k=body.top_k,
+    )
+    return SearchKnowledgeBaseResponse(results=results, total=len(results))

src/agentscope/app/_router/_model.py

@@ -0,0 +1,40 @@
+# -*- coding: utf-8 -*-
+"""The model router."""
+
+from fastapi import APIRouter, Depends, HTTPException, status
+
+from ._schema import ListModelsResponse, ListModelsRequest
+from ...credential import CredentialFactory
+
+model_router = APIRouter(
+    prefix="/model",
+    tags=["model"],
+    responses={404: {"description": "Not found"}},
+)
+
+
+@model_router.get(
+    "/",
+    response_model=ListModelsResponse,
+    summary="List all candidate models under the given credential type",
+)
+async def list_models(
+    body: ListModelsRequest = Depends(),
+) -> ListModelsResponse:
+    """Return all candidate models under the given credential type.
+
+    Args:
+        body (ListModelsRequest): The request body.
+
+    Returns:
+        `ListModelsResponse`: The response body.
+    """
+    credential_cls = CredentialFactory.get_credential_class(body.provider)
+    if credential_cls is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Provider '{body.provider}' not found.",
+        )
+
+    models = credential_cls.get_chat_model_class().list_models()
+    return ListModelsResponse(models=models, total=len(models))

src/agentscope/app/_router/_schedule.py

@@ -0,0 +1,239 @@
+# -*- coding: utf-8 -*-
+"""Schedule router — CRUD endpoints for scheduled agent tasks."""
+from datetime import datetime
+
+from fastapi import APIRouter, Depends, HTTPException, status
+
+from .._manager import SchedulerManager
+from ..deps import (
+    get_current_user_id,
+    get_scheduler_manager,
+    get_session_service,
+    get_storage,
+)
+from ._schema import (
+    CreateScheduleRequest,
+    CreateScheduleResponse,
+    ListSchedulesResponse,
+    ScheduleSessionsResponse,
+    UpdateScheduleRequest,
+)
+from .._service import SessionService
+from ..storage import (
+    StorageBase,
+    ScheduleData,
+    ScheduleRecord,
+    ScheduleSource,
+)
+
+schedule_router = APIRouter(
+    prefix="/schedule",
+    tags=["schedule"],
+    responses={404: {"description": "Not found"}},
+)
+
+
+@schedule_router.get(
+    "/",
+    response_model=ListSchedulesResponse,
+    summary="List all schedules",
+)
+async def list_schedules(
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+) -> ListSchedulesResponse:
+    """List all schedules owned by the current user.
+
+    Args:
+        user_id (`str`): Authenticated user ID.
+        storage (`StorageBase`): Storage instance.
+
+    Returns:
+        `ListSchedulesResponse`:
+            Paginated list of schedule records.
+    """
+    schedules = await storage.list_schedules(user_id)
+    return ListSchedulesResponse(schedules=schedules, total=len(schedules))
+
+
+@schedule_router.post(
+    "/",
+    response_model=CreateScheduleResponse,
+    status_code=status.HTTP_201_CREATED,
+    summary="Create a new schedule",
+)
+async def create_schedule(
+    body: CreateScheduleRequest,
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+    scheduler: SchedulerManager = Depends(get_scheduler_manager),
+) -> CreateScheduleResponse:
+    """Create a new schedule and register it with the scheduler.
+
+    Args:
+        body (`CreateScheduleRequest`): Schedule configuration.
+        user_id (`str`): Authenticated user ID.
+        storage (`StorageBase`): Storage instance.
+        scheduler (`SchedulerManager`): Scheduler manager.
+
+    Returns:
+        `CreateScheduleResponse`:
+            The ID of the newly created schedule.
+
+    Raises:
+        `HTTPException`: 404 if the specified agent does not exist.
+    """
+    agent = await storage.get_agent(user_id, body.agent_id)
+    if agent is None or agent.user_id != user_id:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Agent '{body.agent_id}' not found.",
+        )
+
+    record = ScheduleRecord(
+        user_id=user_id,
+        agent_id=body.agent_id,
+        data=ScheduleData(
+            name=body.name,
+            description=body.description,
+            cron_expression=body.cron_expression,
+            timezone=body.timezone,
+            enabled=body.enabled,
+            stateful=body.stateful,
+            permission_mode=body.permission_mode,
+            chat_model_config=body.chat_model_config,
+            source=ScheduleSource.USER,
+            started_at=datetime.now(),
+        ),
+    )
+    await storage.upsert_schedule(user_id, record)
+
+    if record.data.enabled:
+        await scheduler.register_schedule(record)
+
+    return CreateScheduleResponse(schedule_id=record.id)
+
+
+@schedule_router.patch(
+    "/{schedule_id}",
+    response_model=ScheduleRecord,
+    summary="Update a schedule",
+)
+async def update_schedule(
+    schedule_id: str,
+    body: UpdateScheduleRequest,
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+    scheduler: SchedulerManager = Depends(get_scheduler_manager),
+) -> ScheduleRecord:
+    """Partially update a schedule.
+
+    Fields omitted from the request body keep their current values.
+    Changing ``cron_expression`` or ``timezone`` immediately reschedules the
+    APScheduler job.  Setting ``enable=False`` removes the job from the
+    scheduler without deleting the record.
+
+    Args:
+        schedule_id (`str`): ID of the schedule to update.
+        body (`UpdateScheduleRequest`): Fields to update.
+        user_id (`str`): Authenticated user ID.
+        storage (`StorageBase`): Storage instance.
+        scheduler (`SchedulerManager`): Scheduler manager.
+
+    Returns:
+        `ScheduleRecord`:
+            The updated schedule record.
+
+    Raises:
+        `HTTPException`: 404 if the schedule does not exist.
+    """
+    existing = await storage.get_schedule(user_id, schedule_id)
+    if existing is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Schedule '{schedule_id}' not found.",
+        )
+
+    updates = body.model_dump(exclude_none=True)
+    updated_data = existing.data.model_copy(update=updates)
+    updated_record = existing.model_copy(
+        update={"data": updated_data, "updated_at": datetime.now()},
+    )
+    await storage.upsert_schedule(user_id, updated_record)
+
+    # Always remove the existing job first; re-register only if still enabled.
+    await scheduler.remove_schedule(schedule_id)
+    if updated_record.data.enabled:
+        await scheduler.register_schedule(updated_record)
+
+    return updated_record
+
+
+@schedule_router.delete(
+    "/{schedule_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+    summary="Delete a schedule",
+)
+async def delete_schedule(
+    schedule_id: str,
+    user_id: str = Depends(get_current_user_id),
+    session_service: SessionService = Depends(get_session_service),
+    scheduler: SchedulerManager = Depends(get_scheduler_manager),
+) -> None:
+    """Permanently delete a schedule.
+
+    Cancels any in-flight chat run for sessions this schedule has
+    triggered, removes their records via the session service, and
+    finally unregisters the APScheduler job.
+
+    Args:
+        schedule_id (`str`): ID of the schedule to delete.
+        user_id (`str`): Authenticated user ID.
+        session_service (`SessionService`): Injected session service.
+        scheduler (`SchedulerManager`): Scheduler manager.
+
+    Raises:
+        `HTTPException`: 404 if the schedule does not exist.
+    """
+    deleted = await session_service.delete_schedule(user_id, schedule_id)
+    if not deleted:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Schedule '{schedule_id}' not found.",
+        )
+    await scheduler.remove_schedule(schedule_id)
+
+
+@schedule_router.get(
+    "/{schedule_id}/sessions",
+    response_model=ScheduleSessionsResponse,
+    summary="List execution sessions for a schedule",
+)
+async def list_schedule_sessions(
+    schedule_id: str,
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+) -> ScheduleSessionsResponse:
+    """Return all sessions triggered by a given schedule.
+
+    Args:
+        schedule_id (`str`): ID of the schedule.
+        user_id (`str`): Authenticated user ID.
+        storage (`StorageBase`): Storage instance.
+
+    Returns:
+        `ScheduleSessionsResponse`:
+            List of execution sessions ordered by creation time (newest first).
+
+    Raises:
+        `HTTPException`: 404 if the schedule does not exist.
+    """
+    existing = await storage.get_schedule(user_id, schedule_id)
+    if existing is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Schedule '{schedule_id}' not found.",
+        )
+
+    sessions = await storage.list_sessions_by_schedule(user_id, schedule_id)
+    return ScheduleSessionsResponse(sessions=sessions, total=len(sessions))

src/agentscope/app/_router/_schema/__init__.py

@@ -0,0 +1,110 @@
+# -*- coding: utf-8 -*-
+"""Schema models for the agent service."""
+
+from ._chat import ChatRequest, ChatTriggerResponse
+from ._model import ListModelsResponse, ListModelsRequest
+from ._tts_model import ListTTSModelsResponse, ListTTSModelsRequest
+from ._schedule import (
+    CreateScheduleRequest,
+    CreateScheduleResponse,
+    ListSchedulesResponse,
+    ScheduleSessionsResponse,
+    UpdateScheduleRequest,
+)
+from ._agent import (
+    AgentSchemaResponse,
+    ListAgentsResponse,
+    CreateAgentRequest,
+    CreateAgentResponse,
+    UpdateAgentRequest,
+)
+from ._credential import (
+    CreateCredentialRequest,
+    CreateCredentialResponse,
+    UpdateCredentialRequest,
+    ListCredentialsResponse,
+    ListCredentialSchemasResponse,
+)
+from ._knowledge_base import (
+    CreateKnowledgeBaseRequest,
+    CreateKnowledgeBaseResponse,
+    KbEmbeddingProvider,
+    KbMiddlewareParametersSchemaResponse,
+    KnowledgeBaseView,
+    KnowledgeDocumentView,
+    ListKbEmbeddingModelsResponse,
+    ListKnowledgeBasesResponse,
+    ListKnowledgeDocumentsResponse,
+    ListKnowledgeDocumentStatusResponse,
+    ListSupportedContentTypesResponse,
+    SearchKnowledgeBaseRequest,
+    SearchKnowledgeBaseResponse,
+    UpdateKnowledgeBaseRequest,
+    UploadKnowledgeDocumentResponse,
+)
+from ._session import (
+    CreateSessionRequest,
+    CreateSessionResponse,
+    UpdateSessionRequest,
+    ListSessionsResponse,
+    ListMessagesResponse,
+    SessionView,
+    TeamDetailResponse,
+    TeamMemberView,
+)
+
+__all__ = [
+    # Agent
+    "AgentSchemaResponse",
+    "ListAgentsResponse",
+    "CreateAgentRequest",
+    "CreateAgentResponse",
+    "UpdateAgentRequest",
+    "ListSchedulesResponse",
+    # Chat
+    "ChatRequest",
+    "ChatTriggerResponse",
+    # Credential
+    "CreateCredentialRequest",
+    "CreateCredentialResponse",
+    "UpdateCredentialRequest",
+    "ListCredentialsResponse",
+    "ListCredentialSchemasResponse",
+    # Knowledge base
+    "CreateKnowledgeBaseRequest",
+    "CreateKnowledgeBaseResponse",
+    "KbEmbeddingProvider",
+    "KbMiddlewareParametersSchemaResponse",
+    "KnowledgeBaseView",
+    "KnowledgeDocumentView",
+    "ListKbEmbeddingModelsResponse",
+    "ListKnowledgeBasesResponse",
+    "ListKnowledgeDocumentsResponse",
+    "ListKnowledgeDocumentStatusResponse",
+    "ListSupportedContentTypesResponse",
+    "SearchKnowledgeBaseRequest",
+    "SearchKnowledgeBaseResponse",
+    "UpdateKnowledgeBaseRequest",
+    "UploadKnowledgeDocumentResponse",
+    # Model
+    "ListModelsRequest",
+    "ListModelsResponse",
+    # TTS Model
+    "ListTTSModelsRequest",
+    "ListTTSModelsResponse",
+    # Schedule
+    "CreateScheduleRequest",
+    "CreateScheduleResponse",
+    "ListSchedulesResponse",
+    "ScheduleSessionsResponse",
+    "UpdateScheduleRequest",
+    # Session
+    "CreateSessionRequest",
+    "CreateSessionResponse",
+    "UpdateSessionRequest",
+    "ListSessionsResponse",
+    "ListMessagesResponse",
+    "SessionView",
+    "TeamDetailResponse",
+    "TeamMemberView",
+]

src/agentscope/app/_router/_schema/_agent.py

@@ -0,0 +1,82 @@
+# -*- coding: utf-8 -*-
+"""Request / response schemas for the agent router."""
+from pydantic import BaseModel, Field
+
+from ....agent import ContextConfig, ReActConfig
+from ...storage import AgentRecord
+
+
+class CreateAgentRequest(BaseModel):
+    """Request body for creating a new agent."""
+
+    name: str = Field(description="Display name of the agent.")
+    system_prompt: str = Field(
+        default="You're a helpful assistant.",
+        description="Base system prompt fed to the agent.",
+    )
+    context_config: ContextConfig = Field(
+        default_factory=ContextConfig,
+        description="Context-window management configuration.",
+    )
+    react_config: ReActConfig = Field(
+        default_factory=ReActConfig,
+        description="ReAct loop configuration.",
+    )
+
+
+class CreateAgentResponse(BaseModel):
+    """Response body after creating an agent."""
+
+    agent_id: str = Field(description="Server-assigned agent identifier.")
+
+
+class UpdateAgentRequest(BaseModel):
+    """Request body for partially updating an agent.
+
+    Omit any field to keep its current value.
+    """
+
+    name: str | None = Field(default=None, description="New display name.")
+    system_prompt: str | None = Field(
+        default=None,
+        description="New system prompt.",
+    )
+    context_config: ContextConfig | None = Field(
+        default=None,
+        description="New context configuration.",
+    )
+    react_config: ReActConfig | None = Field(
+        default=None,
+        description="New ReAct loop configuration.",
+    )
+
+
+class ListAgentsResponse(BaseModel):
+    """Response body for listing agents."""
+
+    agents: list[AgentRecord] = Field(description="Agent records.")
+    total: int = Field(description="Total number of agents.")
+
+
+class AgentSchemaResponse(BaseModel):
+    """JSON Schema fragments used by the frontend to render the agent
+    create / edit forms.
+
+    Each fragment is a self-contained JSON Schema object so the frontend
+    doesn't need to follow ``$ref`` links across fragments. The frontend
+    pairs each property with an i18n key derived from its path, so labels
+    and descriptions remain localizable independently of the backend.
+    """
+
+    identity: dict = Field(
+        description=(
+            "Schema for the agent's identity fields (``name``, "
+            "``system_prompt``)."
+        ),
+    )
+    context_config: dict = Field(
+        description="Schema for ``ContextConfig``.",
+    )
+    react_config: dict = Field(
+        description="Schema for ``ReActConfig``.",
+    )

src/agentscope/app/_router/_schema/_chat.py

@@ -0,0 +1,45 @@
+# -*- coding: utf-8 -*-
+"""The chat endpoint schema."""
+
+from pydantic import BaseModel, Field
+
+from ....message import Msg
+from ....event import UserConfirmResultEvent, ExternalExecutionResultEvent
+
+
+class ChatRequest(BaseModel):
+    """Request body for the chat endpoint."""
+
+    agent_id: str = Field(
+        description="Agent ID for the chat endpoint.",
+    )
+
+    session_id: str = Field(
+        description="The session to send the message to.",
+    )
+
+    input: (
+        Msg
+        | list[Msg]
+        | UserConfirmResultEvent
+        | ExternalExecutionResultEvent
+        | None
+    ) = Field(
+        description="The input message(s), or agent event, or None.",
+    )
+
+
+class ChatTriggerResponse(BaseModel):
+    """Response body for the fire-and-forget chat trigger.
+
+    Confirms that the chat run was scheduled. Events produced by the
+    run arrive separately via the session's SSE stream endpoint.
+    """
+
+    status: str = Field(
+        default="started",
+        description='Always ``"started"`` when the trigger succeeded.',
+    )
+    session_id: str = Field(
+        description="Echo of the session id the run was started for.",
+    )

src/agentscope/app/_router/_schema/_credential.py

@@ -0,0 +1,42 @@
+# -*- coding: utf-8 -*-
+"""Request / response schemas for the credential router."""
+from pydantic import BaseModel, Field
+
+from ...storage import CredentialRecord
+
+
+class CreateCredentialRequest(BaseModel):
+    """Request body for creating a new credential."""
+
+    data: dict = Field(description="Credential payload (e.g. API keys).")
+
+
+class CreateCredentialResponse(BaseModel):
+    """Response body after creating a credential."""
+
+    credential_id: str = Field(
+        description="Server-assigned credential identifier.",
+    )
+
+
+class UpdateCredentialRequest(BaseModel):
+    """Request body for updating an existing credential."""
+
+    data: dict = Field(description="New credential payload.")
+
+
+class ListCredentialsResponse(BaseModel):
+    """Response body for listing credentials."""
+
+    credentials: list[CredentialRecord] = Field(
+        description="Credential records.",
+    )
+    total: int = Field(description="Total number of credentials.")
+
+
+class ListCredentialSchemasResponse(BaseModel):
+    """Response body for listing credential type schemas."""
+
+    schemas: list[dict] = Field(
+        description="JSON schemas for all registered credential types.",
+    )

src/agentscope/app/_router/_schema/_knowledge_base.py

@@ -0,0 +1,292 @@
+# -*- coding: utf-8 -*-
+"""Request / response schemas for the knowledge base router."""
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+from ...storage import (
+    CredentialRecord,
+    EmbeddingModelConfig,
+    KnowledgeDocumentRecord,
+    KnowledgeDocumentStatus,
+)
+from ....embedding import EmbeddingModelCard
+from ....rag import VectorSearchResult
+from ...rag.knowledge_base_manager._dimension_policy import DimensionPolicy
+
+
+class CreateKnowledgeBaseRequest(BaseModel):
+    """Request body for creating a new knowledge base."""
+
+    name: str = Field(description="Display name of the knowledge base.")
+    description: str = Field(
+        default="",
+        description="Free-form description shown in the UI.",
+    )
+    embedding_model_config: EmbeddingModelConfig = Field(
+        description=(
+            "Embedding model used both at indexing and at query time. "
+            "Cannot be changed after creation — switching would "
+            "invalidate every previously inserted vector."
+        ),
+    )
+
+
+class CreateKnowledgeBaseResponse(BaseModel):
+    """Response body after creating a knowledge base."""
+
+    knowledge_base_id: str = Field(
+        description="Server-assigned knowledge base identifier.",
+    )
+
+
+class UpdateKnowledgeBaseRequest(BaseModel):
+    """Request body for updating a knowledge base.
+
+    Only mutable fields can be set here.  The embedding model
+    configuration is pinned at creation time and cannot be changed —
+    switching it would invalidate every previously inserted vector.
+    """
+
+    name: str | None = Field(
+        default=None,
+        description="New display name; omit to leave unchanged.",
+    )
+    description: str | None = Field(
+        default=None,
+        description="New free-form description; omit to leave unchanged.",
+    )
+
+
+class KnowledgeBaseView(BaseModel):
+    """A knowledge base record as exposed to API clients.
+
+    Mirrors :class:`KnowledgeBaseRecord` with the internal
+    ``user_id`` / ``collection_name`` fields stripped — clients have
+    no business introspecting either.
+    """
+
+    id: str = Field(description="The knowledge base identifier.")
+    name: str = Field(description="Display name of the knowledge base.")
+    description: str = Field(description="Free-form description.")
+    embedding_model_config: EmbeddingModelConfig = Field(
+        description="Embedding model configuration pinned at creation.",
+    )
+    created_at: datetime = Field(description="Creation timestamp.")
+    updated_at: datetime = Field(description="Last-update timestamp.")
+
+
+class ListKnowledgeBasesResponse(BaseModel):
+    """Response body for listing the caller's knowledge bases."""
+
+    knowledge_bases: list[KnowledgeBaseView] = Field(
+        description="All knowledge bases owned by the caller.",
+    )
+    total: int = Field(description="Total number of returned items.")
+
+
+class KnowledgeDocumentView(BaseModel):
+    """A document record as exposed to API clients.
+
+    Surfaces both the static fields the UI needs to render a row
+    (``filename`` / ``size``) and the live lifecycle fields the front
+    end polls (``status`` / ``error`` / ``chunk_count``).  Internal
+    fields (``user_id`` / ``blob_uri`` / ``processing_node`` / lease)
+    are deliberately omitted — clients have no business introspecting
+    them.
+    """
+
+    id: str = Field(description="The document identifier.")
+    filename: str = Field(description="Original filename at upload time.")
+    size: int = Field(description="Document size in bytes.")
+    content_type: str | None = Field(
+        default=None,
+        description="IANA media type recorded at upload time, if any.",
+    )
+    status: KnowledgeDocumentStatus = Field(
+        description="Current lifecycle state of the document.",
+    )
+    error: str | None = Field(
+        default=None,
+        description=(
+            "Human-readable failure reason when ``status == 'error'``."
+        ),
+    )
+    chunk_count: int = Field(
+        default=0,
+        description="Number of chunks indexed so far.",
+    )
+    created_at: datetime = Field(description="Upload timestamp.")
+    updated_at: datetime = Field(
+        description="Last status transition timestamp.",
+    )
+
+    @classmethod
+    def from_record(
+        cls,
+        record: KnowledgeDocumentRecord,
+    ) -> "KnowledgeDocumentView":
+        """Project a storage record onto the API view.
+
+        Centralised so router code stays a one-liner and the field
+        mapping has exactly one source of truth.
+        """
+        return cls(
+            id=record.id,
+            filename=record.data.filename,
+            size=record.data.size,
+            content_type=record.data.content_type,
+            status=record.data.status,
+            error=record.data.error,
+            chunk_count=record.data.chunk_count,
+            created_at=record.created_at,
+            updated_at=record.updated_at,
+        )
+
+
+class ListKnowledgeDocumentsResponse(BaseModel):
+    """Response body for listing documents inside a knowledge base."""
+
+    documents: list[KnowledgeDocumentView] = Field(
+        description="One view per registered document.",
+    )
+    total: int = Field(description="Total number of returned items.")
+
+
+class ListKnowledgeDocumentStatusResponse(BaseModel):
+    """Response body for batch document-status polling."""
+
+    items: list[KnowledgeDocumentView] = Field(
+        description=(
+            "Subset of the requested documents that still exist. "
+            "Missing ids are silently omitted — clients may legitimately "
+            "ask about a document that was deleted between two polls."
+        ),
+    )
+
+
+class UploadKnowledgeDocumentResponse(BaseModel):
+    """Response body after uploading a document into a knowledge base."""
+
+    document_id: str = Field(
+        description="Server-assigned document identifier.",
+    )
+    filename: str = Field(
+        description="The original filename of the uploaded document.",
+    )
+    status: KnowledgeDocumentStatus = Field(
+        description=(
+            "Lifecycle state immediately after upload — always "
+            "``'pending'`` in the happy path; surfaced so the client "
+            "can seed its progress tracker without an extra round-trip."
+        ),
+    )
+
+
+class SearchKnowledgeBaseRequest(BaseModel):
+    """Request body for searching a knowledge base."""
+
+    query: str = Field(description="The natural-language search query.")
+    top_k: int = Field(
+        default=5,
+        ge=1,
+        le=50,
+        description="Maximum number of results to return.",
+    )
+
+
+class SearchKnowledgeBaseResponse(BaseModel):
+    """Response body for a knowledge base search."""
+
+    results: list[VectorSearchResult] = Field(
+        description="Matched chunks ordered by descending similarity score.",
+    )
+    total: int = Field(description="Total number of returned results.")
+
+
+class KbEmbeddingProvider(BaseModel):
+    """One credential and the embedding models it can serve.
+
+    The model cards have been projected through the manager's
+    dimension policy: incompatible models are removed and matryoshka
+    cards are narrowed to the locked dimension when applicable.
+    """
+
+    credential: CredentialRecord = Field(
+        description="The credential record exposing these models.",
+    )
+    models: list[EmbeddingModelCard] = Field(
+        description=(
+            "Embedding model cards available under this credential, "
+            "filtered to those compatible with the manager's "
+            "dimension policy."
+        ),
+    )
+
+
+class ListKbEmbeddingModelsResponse(BaseModel):
+    """Response body listing KB-compatible embedding models.
+
+    The list is pre-filtered server-side against the manager's
+    dimension policy.  The policy itself is also returned so the
+    front-end can render an explanatory banner and lock the dimension
+    selector when applicable.
+    """
+
+    providers: list[KbEmbeddingProvider] = Field(
+        description=(
+            "One entry per credential that has at least one "
+            "compatible embedding model."
+        ),
+    )
+    policy: DimensionPolicy = Field(
+        description=(
+            "The dimension policy used to filter the cards; surfaced "
+            "verbatim so the UI can explain *why* models were filtered."
+        ),
+    )
+
+
+class KbMiddlewareParametersSchemaResponse(BaseModel):
+    """Response body exposing the KB middleware's parameters schema.
+
+    The schema is derived from
+    :class:`agentscope.middleware.RAGMiddleware.Parameters`
+    via ``model_json_schema()`` so the front-end can render the
+    session-level KB attachment form with the same schema-driven
+    component used for model parameters.
+    """
+
+    parameter_schema: dict = Field(
+        description=(
+            "JSON Schema produced by `RAGMiddleware.Parameters"
+            "model_json_schema()`.  Shaped identically to the "
+            "`parameter_schema` field on `ModelCard`."
+        ),
+    )
+
+
+class ListSupportedContentTypesResponse(BaseModel):
+    """Response body advertising the parser-supported upload types.
+
+    Aggregated across every parser registered on the app — the union of
+    each parser's :attr:`supported_media_types` and
+    :meth:`supported_extensions`.  The front-end uses this to populate
+    ``<input accept>`` and to reject unsupported drops on the client
+    before the file leaves the browser.
+    """
+
+    media_types: list[str] = Field(
+        description=(
+            "Union of IANA media types every registered parser claims "
+            "to handle.  Deduplicated and sorted."
+        ),
+    )
+    extensions: list[str] = Field(
+        description=(
+            "Filename extensions (each starting with `.`) every "
+            "registered parser claims to handle.  Deduplicated and "
+            "sorted.  Derived from `mimetypes` by the base parser; "
+            "subclasses may override the default."
+        ),
+    )

src/agentscope/app/_router/_schema/_mcp.py

@@ -0,0 +1,127 @@
+# -*- coding: utf-8 -*-
+"""MCP schemas for API requests and responses."""
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+from ....mcp import StdioMCPConfig, HttpMCPConfig
+
+
+class ConnectionScope(str, Enum):
+    """MCP connection scope and lifecycle strategy.
+
+    This determines how MCP connections are managed in the service layer.
+    """
+
+    SHARED = "shared"
+    """Shared connection across all agents/users.
+    - One connection per MCP config, shared globally
+    - Created on first use, destroyed on application shutdown
+    - Use case: Stateless HTTP MCP (e.g., weather API, web search)
+    """
+
+    ISOLATED = "isolated"
+    """Isolated connection per agent.
+    - One connection per (MCP config, agent)
+    - Created on first use per agent, destroyed on agent session end
+    - Use case: Stateful MCP (e.g., browser-use), STDIO MCP
+    """
+
+    EPHEMERAL = "ephemeral"
+    """Ephemeral connection per request.
+    - New connection created for each request, destroyed immediately after
+    - No connection pooling
+    - Use case: Low-frequency stateless HTTP MCP
+    """
+
+
+class MCPBase(BaseModel):
+    """Base MCP fields shared across request/response schemas."""
+
+    name: str = Field(
+        title="MCP Name",
+        description="The unique name to identify this MCP configuration.",
+    )
+
+    connection_scope: ConnectionScope = Field(
+        title="Connection Scope",
+        description="The connection scope and lifecycle strategy.",
+    )
+
+    mcp_config: StdioMCPConfig | HttpMCPConfig = Field(
+        discriminator="type",
+        title="MCP Config",
+        description="The base MCP server configuration.",
+    )
+
+    def validate_config(self) -> None:
+        """Validate the configuration.
+
+        Raises:
+            ValueError: If the configuration is invalid.
+        """
+        # STDIO MCP cannot use ephemeral mode
+        if (
+            self.mcp_config.type == "stdio_mcp"
+            and self.connection_scope == ConnectionScope.EPHEMERAL
+        ):
+            raise ValueError(
+                "STDIO MCP does not support ephemeral mode. "
+                "Use 'shared' or 'isolated' instead.",
+            )
+
+
+class MCPCreateRequest(MCPBase):
+    """Request body for creating a new MCP configuration.
+
+    Used in POST /mcp endpoint. Does not include server-generated fields
+    like creator_id, created_at, updated_at.
+    """
+
+
+class MCPUpdateRequest(BaseModel):
+    """Request body for partially updating an MCP configuration.
+
+    Used in PATCH /mcp/{name} endpoint. All fields are optional.
+    """
+
+    connection_scope: ConnectionScope | None = Field(
+        default=None,
+        description="New connection scope.",
+    )
+    mcp_config: StdioMCPConfig | HttpMCPConfig | None = Field(
+        default=None,
+        discriminator="type",
+        description="New MCP server configuration.",
+    )
+
+
+class MCPResponse(MCPBase):
+    """Response model for MCP configuration with server-generated metadata.
+
+    Used in GET /mcp/{name}, GET /mcp (list), and POST /mcp responses.
+    Includes all fields from MCPBase plus server-assigned metadata.
+    """
+
+    creator_id: str = Field(
+        description="User ID of the creator.",
+    )
+
+    created_at: float = Field(
+        description="Creation timestamp (Unix epoch).",
+    )
+
+    updated_at: float = Field(
+        description="Last-updated timestamp (Unix epoch).",
+    )
+
+
+class ListMCPsResponse(BaseModel):
+    """Response model for listing MCP configurations."""
+
+    mcps: list[MCPResponse] = Field(
+        description="List of MCP configurations.",
+    )
+    total: int = Field(
+        description="Total number of MCP configurations.",
+    )

src/agentscope/app/_router/_schema/_model.py

@@ -0,0 +1,21 @@
+# -*- coding: utf-8 -*-
+"""The chat model configuration, used as DTO layer."""
+
+from pydantic import BaseModel, Field
+
+from ....model import ModelCard
+
+
+class ListModelsResponse(BaseModel):
+    """List the candidate models response."""
+
+    models: list[ModelCard] = Field(description="The candidate models.")
+    total: int = Field(description="The total number of candidates.")
+
+
+class ListModelsRequest(BaseModel):
+    """List the candidate models request."""
+
+    provider: str = Field(
+        description="The provider type, e.g. openai, dashscope, etc.",
+    )

src/agentscope/app/_router/_schema/_schedule.py

@@ -0,0 +1,118 @@
+# -*- coding: utf-8 -*-
+"""Request / response schemas for the schedule router."""
+from pydantic import BaseModel, Field
+
+from ...storage import (
+    ScheduleRecord,
+    SessionRecord,
+    ChatModelConfig,
+)
+from ....permission import PermissionMode
+
+
+class CreateScheduleRequest(BaseModel):
+    """Request body for creating a new schedule."""
+
+    name: str = Field(description="Display name of the schedule.")
+
+    description: str = Field(default="", description="Optional description.")
+
+    cron_expression: str = Field(
+        description="Standard 5-field cron expression, e.g. '0 9 * * 1-5'.",
+    )
+
+    timezone: str = Field(
+        default="UTC",
+        description="IANA timezone name, e.g. 'America/New_York' or "
+        "'Asia/Shanghai'.",
+    )
+
+    agent_id: str = Field(description="Agent to run when the schedule fires.")
+
+    chat_model_config: ChatModelConfig = Field(
+        description="Model configuration for the auto-created session.",
+    )
+
+    enabled: bool = Field(
+        default=True,
+        description="Whether the schedule is active immediately "
+        "after creation.",
+    )
+
+    stateful: bool = Field(
+        default=False,
+        description="If True, consecutive executions share the same session "
+        "context.",
+    )
+
+    permission_mode: PermissionMode = Field(
+        default=PermissionMode.DONT_ASK,
+        description="Permission level for the agent during "
+        "scheduled execution.",
+    )
+
+
+class CreateScheduleResponse(BaseModel):
+    """Response body after creating a schedule."""
+
+    schedule_id: str = Field(
+        description="Server-assigned schedule identifier.",
+    )
+
+
+class UpdateScheduleRequest(BaseModel):
+    """Request body for partially updating a schedule.
+
+    Omit any field to keep its current value.  Changing ``cron_expression``
+    or ``timezone`` will reschedule the APScheduler job immediately.
+    Changing ``enable`` to ``False`` removes the job from the scheduler
+    without deleting the record; setting it back to ``True`` re-registers it.
+    """
+
+    name: str | None = Field(default=None, description="New display name.")
+
+    description: str | None = Field(
+        default=None,
+        description="New description.",
+    )
+
+    cron_expression: str | None = Field(
+        default=None,
+        description="New cron expression. Reschedules the task immediately.",
+    )
+
+    timezone: str | None = Field(
+        default=None,
+        description="New IANA timezone name.",
+    )
+
+    enabled: bool | None = Field(
+        default=None,
+        description="Set to False to pause the schedule without deleting it.",
+    )
+
+    stateful: bool | None = Field(
+        default=None,
+        description="Change whether executions share session context.",
+    )
+
+    permission_mode: PermissionMode | None = Field(
+        default=None,
+        description="New permission mode.",
+    )
+
+
+class ListSchedulesResponse(BaseModel):
+    """Response body for listing schedules."""
+
+    schedules: list[ScheduleRecord] = Field(description="Schedule records.")
+    total: int = Field(description="Total number of schedules.")
+
+
+class ScheduleSessionsResponse(BaseModel):
+    """Response body for listing execution sessions of a schedule."""
+
+    sessions: list[SessionRecord] = Field(
+        description="Sessions triggered by this schedule.",
+    )
+    total: int = Field(description="Total number of execution sessions.")

src/agentscope/app/_router/_schema/_session.py

@@ -0,0 +1,188 @@
+# -*- coding: utf-8 -*-
+"""Request / response schemas for the session router."""
+from pydantic import BaseModel, Field
+
+from ....permission import PermissionMode
+from ...storage import (
+    AgentRecord,
+    ChatModelConfig,
+    SessionKnowledgeConfig,
+    TTSModelConfig,
+    SessionRecord,
+    TeamRecord,
+)
+
+
+class TeamMemberView(BaseModel):
+    """One row in :attr:`TeamDetailResponse.members`.
+
+    Pairs each member's :class:`AgentRecord` with its single
+    ``session_id`` so the UI can subscribe to the worker's chat
+    stream without a separate lookup.
+    """
+
+    agent: AgentRecord = Field(
+        description="The worker agent record.",
+    )
+    session_id: str | None = Field(
+        default=None,
+        description=(
+            "The worker's session id. ``None`` if the agent is in an "
+            "inconsistent state (worker without a session)."
+        ),
+    )
+
+
+class TeamDetailResponse(BaseModel):
+    """Resolved team detail embedded inside :class:`SessionView.team`."""
+
+    team: TeamRecord = Field(description="The team record.")
+    leader_agent: AgentRecord | None = Field(
+        default=None,
+        description=(
+            "Leader's agent record (resolved from the team's "
+            "``session_id`` → session.agent_id)."
+        ),
+    )
+    members: list[TeamMemberView] = Field(
+        default_factory=list,
+        description=(
+            "Worker agents listed in :attr:`TeamData.member_ids`, each "
+            "paired with its single session id when available."
+        ),
+    )
+
+
+class CreateSessionRequest(BaseModel):
+    """Request body for creating a new session."""
+
+    agent_id: str = Field(description="Agent this session belongs to.")
+    workspace_id: str | None = Field(
+        default=None,
+        description="Workspace this session belongs to.",
+    )
+    name: str | None = Field(
+        default=None,
+        description="Display name. Defaults to current datetime if omitted.",
+    )
+    chat_model_config: ChatModelConfig | None = Field(
+        default=None,
+        description="Model provider and parameters. "
+        "Can be set later via PATCH.",
+    )
+    fallback_chat_model_config: ChatModelConfig | None = Field(
+        default=None,
+        description="Fallback model used when the primary model fails. "
+        "Can be set later via PATCH.",
+    )
+    tts_model_config: TTSModelConfig | None = Field(
+        default=None,
+        description="TTS model configuration. Can be set later via PATCH.",
+    )
+    knowledge_config: SessionKnowledgeConfig | None = Field(
+        default=None,
+        description=(
+            "Knowledge bases attached to this session plus the "
+            "`RAGMiddleware` parameters. Can be set later "
+            "via PATCH."
+        ),
+    )
+
+
+class CreateSessionResponse(BaseModel):
+    """Response body after creating a session."""
+
+    session_id: str = Field(description="Server-assigned session identifier.")
+
+
+class UpdateSessionRequest(BaseModel):
+    """Request body for updating an existing session.
+
+    Omit any field to keep its current value.
+    """
+
+    name: str | None = Field(
+        default=None,
+        description="New display name.",
+    )
+    chat_model_config: ChatModelConfig | None = Field(
+        default=None,
+        description="New model configuration. "
+        "Replaces the existing one entirely. "
+        "Pass null to clear; omit to leave unchanged.",
+    )
+    fallback_chat_model_config: ChatModelConfig | None = Field(
+        default=None,
+        description="New fallback model configuration. "
+        "Pass null to clear; omit to leave unchanged.",
+    )
+    tts_model_config: TTSModelConfig | None = Field(
+        default=None,
+        description="New TTS model configuration. "
+        "Pass null to clear; omit to leave unchanged.",
+    )
+    knowledge_config: SessionKnowledgeConfig | None = Field(
+        default=None,
+        description=(
+            "New knowledge base attachment + middleware parameters. "
+            "Pass null to clear; omit to leave unchanged."
+        ),
+    )
+    permission_mode: PermissionMode | None = Field(
+        default=None,
+        description="New permission mode for the session.",
+    )
+
+
+class SessionView(BaseModel):
+    """Per-session bundle with everything the frontend needs to
+    render either the list view or open a session.
+
+    Bundles three orthogonal pieces of information so opening a
+    session does not require a waterfall of follow-up requests:
+
+    - the persisted :class:`SessionRecord` itself (config + state),
+    - whether the session has an active chat run right now,
+    - the team detail (resolved leader + members) when the session
+      participates in a team.
+
+    Messages are intentionally **not** included here — they are
+    paginated separately via ``GET /sessions/{id}/messages``.
+    """
+
+    session: SessionRecord = Field(
+        description=(
+            "The persisted session record. Includes ``state`` "
+            "(``permission_context`` / ``tool_context`` / "
+            "``tasks_context``) inline."
+        ),
+    )
+    is_running: bool = Field(
+        description="Whether a chat run is currently active on this session.",
+    )
+    team: TeamDetailResponse | None = Field(
+        default=None,
+        description=(
+            "Resolved team detail when ``session.team_id`` is set "
+            "(leader agent + member agents with their session ids). "
+            "``None`` when the session does not participate in any team."
+        ),
+    )
+
+
+class ListSessionsResponse(BaseModel):
+    """Response body for listing sessions."""
+
+    sessions: list[SessionView] = Field(
+        description="Session views (record + is_running + team).",
+    )
+    total: int = Field(description="Total number of sessions.")
+
+
+class ListMessagesResponse(BaseModel):
+    """Response body for listing messages in a session."""
+
+    messages: list = Field(description="Messages in chronological order.")
+    is_running: bool = Field(
+        description="Whether the session is currently running.",
+    )

src/agentscope/app/_router/_schema/_tts_model.py

@@ -0,0 +1,23 @@
+# -*- coding: utf-8 -*-
+"""The TTS model configuration, used as DTO layer."""
+
+from pydantic import BaseModel, Field
+
+from ....tts import TTSModelCard
+
+
+class ListTTSModelsResponse(BaseModel):
+    """List the candidate TTS models response."""
+
+    models: list[TTSModelCard] = Field(
+        description="The candidate TTS models.",
+    )
+    total: int = Field(description="The total number of candidates.")
+
+
+class ListTTSModelsRequest(BaseModel):
+    """List the candidate TTS models request."""
+
+    provider: str = Field(
+        description="The provider type, e.g. dashscope_credential.",
+    )

src/agentscope/app/_router/_session.py

@@ -0,0 +1,680 @@
+# -*- coding: utf-8 -*-
+"""Session router — create, list, update, delete, stream, and get messages."""
+import asyncio
+import json
+from typing import AsyncGenerator
+
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from fastapi.responses import StreamingResponse
+
+from ..._utils._common import _generate_id
+from ..deps import (
+    get_current_user_id,
+    get_message_bus,
+    get_session_service,
+    get_storage,
+)
+from ._schema import (
+    CreateSessionRequest,
+    CreateSessionResponse,
+    ListMessagesResponse,
+    ListSessionsResponse,
+    SessionView,
+    TeamDetailResponse,
+    TeamMemberView,
+    UpdateSessionRequest,
+)
+from ..message_bus import MessageBus, MessageBusKeys
+from .._service import SessionService, SessionProjection, SubagentHitlProjector
+from ..storage import (
+    AgentRecord,
+    ChatModelConfig,
+    SessionKnowledgeConfig,
+    TTSModelConfig,
+    SessionConfig,
+    SessionRecord,
+    StorageBase,
+    TeamRecord,
+)
+from ...message import ToolCallState
+from ...event import CustomEvent
+
+
+async def _build_team_detail(
+    storage: StorageBase,
+    user_id: str,
+    team: TeamRecord,
+) -> TeamDetailResponse:
+    """Resolve a team's leader agent + member agents into a
+    :class:`TeamDetailResponse` for the session list endpoint.
+
+    Args:
+        storage (`StorageBase`):
+            Application storage. Used to look up the leader session,
+            each member agent, and each member's session.
+        user_id (`str`):
+            The owner user id.
+        team (`TeamRecord`):
+            The team to resolve. Caller has already loaded it.
+
+    Returns:
+        `TeamDetailResponse`:
+            The team plus its resolved leader and member agents (each
+            member paired with its session id when available).
+    """
+    leader_agent: AgentRecord | None = None
+    leader_session = await storage.get_session(user_id, "", team.session_id)
+    if leader_session is not None:
+        leader_agent = await storage.get_agent(
+            user_id,
+            leader_session.agent_id,
+        )
+
+    members: list[TeamMemberView] = []
+    for member_id in team.data.member_ids:
+        agent = await storage.get_agent(user_id, member_id)
+        if agent is None:
+            continue
+        sessions = await storage.list_sessions(user_id, member_id)
+        session_id = sessions[0].id if sessions else None
+        members.append(TeamMemberView(agent=agent, session_id=session_id))
+
+    return TeamDetailResponse(
+        team=team,
+        leader_agent=leader_agent,
+        members=members,
+    )
+
+
+session_router = APIRouter(
+    prefix="/sessions",
+    tags=["sessions"],
+    responses={404: {"description": "Not found"}},
+)
+
+
+async def _ensure_credential_exists(
+    storage: StorageBase,
+    user_id: str,
+    config: ChatModelConfig | TTSModelConfig | None,
+) -> None:
+    """Validate that the credential referenced by ``config`` belongs to the
+    given user. No-op when ``config`` is ``None``.
+
+    Args:
+        storage (`StorageBase`): Injected storage backend.
+        user_id (`str`): The authenticated user ID.
+        config (`ChatModelConfig | TTSModelConfig | None`): Model config to
+            validate. Pass ``None`` to skip the check.
+
+    Raises:
+        `HTTPException`: 404 if the credential does not exist or does not
+            belong to the user.
+    """
+    if config is None:
+        return
+    credentials = await storage.list_credentials(user_id)
+    if not any(c.id == config.credential_id for c in credentials):
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Credential '{config.credential_id}' not found.",
+        )
+
+
+async def _ensure_knowledge_bases_exist(
+    storage: StorageBase,
+    user_id: str,
+    config: SessionKnowledgeConfig | None,
+) -> None:
+    """Validate every KB id in ``config`` belongs to the given user.
+
+    No-op when ``config`` is ``None`` or its ``knowledge_base_ids``
+    list is empty.
+
+    Args:
+        storage (`StorageBase`): Injected storage backend.
+        user_id (`str`): The authenticated user ID.
+        config (`SessionKnowledgeConfig | None`):
+            Knowledge config to validate.  Pass ``None`` to skip.
+
+    Raises:
+        `HTTPException`: 404 if any KB id does not exist or is not
+            owned by the user.
+    """
+    if config is None or not config.knowledge_base_ids:
+        return
+    for kb_id in config.knowledge_base_ids:
+        kb = await storage.get_knowledge_base(user_id, kb_id)
+        if kb is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Knowledge base '{kb_id}' not found.",
+            )
+
+
+@session_router.get(
+    "/",
+    response_model=ListSessionsResponse,
+    summary="List sessions for an agent",
+)
+async def list_sessions(
+    agent_id: str = Query(description="Filter sessions by agent ID."),
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+    message_bus: MessageBus = Depends(get_message_bus),
+) -> ListSessionsResponse:
+    """Return all sessions for an agent as enriched
+    :class:`SessionView` entries.
+
+    Each entry bundles three things the chat UI needs to render
+    without follow-up requests: the session record (incl.
+    ``state``), whether a chat run is currently active, and — when
+    the session participates in a team — the resolved team detail
+    (leader agent + member agents with their session ids).
+
+    Args:
+        agent_id (`str`):
+            Agent whose sessions to list.
+        user_id (`str`):
+            Injected authenticated user ID.
+        storage (`StorageBase`):
+            Injected storage backend.
+        message_bus (`MessageBus`):
+            Injected message bus (used for ``session_is_running``).
+
+    Returns:
+        `ListSessionsResponse`:
+            Enriched session views and their count.
+
+    Raises:
+        `HTTPException`: 404 if the agent does not exist or does not
+            belong to the authenticated user.
+    """
+    # Direct ownership check via get_agent — handles both source=user
+    # and source=team agents (the latter aren't returned by
+    # storage.list_agents but are still owned by the user; reachable
+    # via team navigation).
+    agent = await storage.get_agent(user_id, agent_id)
+    if agent is None or agent.user_id != user_id:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Agent '{agent_id}' not found.",
+        )
+
+    sessions = await storage.list_sessions(user_id, agent_id)
+    views: list[SessionView] = []
+    for session in sessions:
+        team_detail = None
+        if session.team_id:
+            team_record = await storage.get_team(user_id, session.team_id)
+            if team_record is not None:
+                team_detail = await _build_team_detail(
+                    storage,
+                    user_id,
+                    team_record,
+                )
+        views.append(
+            SessionView(
+                session=session,
+                is_running=await message_bus.is_locked(
+                    MessageBusKeys.session_lock(session.id),
+                ),
+                team=team_detail,
+            ),
+        )
+    return ListSessionsResponse(sessions=views, total=len(views))
+
+
+@session_router.post(
+    "/",
+    response_model=CreateSessionResponse,
+    status_code=status.HTTP_201_CREATED,
+    summary="Create a new session",
+)
+async def create_session(
+    body: CreateSessionRequest,
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+) -> CreateSessionResponse:
+    """Create (or resume) a session for a given agent and workspace.
+
+    At most one session exists per ``(user_id, agent_id, workspace_id)``
+    triple — a second call with the same triple updates the existing session
+    rather than creating a duplicate.
+
+    Args:
+        body (`CreateSessionRequest`): Agent, workspace, and model config.
+        user_id (`str`): Injected authenticated user ID.
+        storage (`StorageBase`): Injected storage backend.
+
+    Returns:
+        `CreateSessionResponse`: The session identifier.
+
+    Raises:
+        `HTTPException`: 404 if the agent or credential does not exist or
+            does not belong to the authenticated user.
+    """
+    agent = await storage.get_agent(user_id, body.agent_id)
+    if agent is None or agent.user_id != user_id:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Agent '{body.agent_id}' not found.",
+        )
+
+    await _ensure_credential_exists(storage, user_id, body.chat_model_config)
+    await _ensure_credential_exists(
+        storage,
+        user_id,
+        body.fallback_chat_model_config,
+    )
+    await _ensure_credential_exists(storage, user_id, body.tts_model_config)
+    await _ensure_knowledge_bases_exist(
+        storage,
+        user_id,
+        body.knowledge_config,
+    )
+
+    session_record = await storage.upsert_session(
+        user_id=user_id,
+        agent_id=body.agent_id,
+        config=SessionConfig(
+            workspace_id=body.workspace_id or _generate_id(),
+            chat_model_config=body.chat_model_config,
+            fallback_chat_model_config=body.fallback_chat_model_config,
+            tts_model_config=body.tts_model_config,
+            knowledge_config=body.knowledge_config,
+            **({"name": body.name} if body.name is not None else {}),
+        ),
+    )
+    return CreateSessionResponse(session_id=session_record.id)
+
+
+@session_router.delete(
+    "/{session_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+    summary="Delete a session",
+)
+async def delete_session(
+    session_id: str,
+    agent_id: str = Query(description="Agent the session belongs to."),
+    user_id: str = Depends(get_current_user_id),
+    session_service: SessionService = Depends(get_session_service),
+) -> None:
+    """Permanently delete a session and all its associated state.
+
+    Cancels any in-flight chat run for this session (and for every
+    worker session if this one is a team leader) before dropping
+    storage records and bus state. The cancel path is cross-process:
+    whichever worker is actually running the session will receive the
+    cancel broadcast and abort.
+
+    Args:
+        session_id (`str`): The session to delete.
+        agent_id (`str`): The agent the session belongs to.
+        user_id (`str`): Injected authenticated user ID.
+        session_service (`SessionService`): Injected session service.
+
+    Raises:
+        `HTTPException`: 404 if the session does not exist or does not belong
+            to the authenticated user.
+    """
+    deleted = await session_service.delete_session(
+        user_id,
+        agent_id,
+        session_id,
+    )
+    if not deleted:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Session '{session_id}' not found.",
+        )
+
+
+@session_router.patch(
+    "/{session_id}",
+    response_model=SessionRecord,
+    summary="Update a session",
+)
+async def update_session(
+    session_id: str,
+    body: UpdateSessionRequest,
+    agent_id: str = Query(description="Agent the session belongs to."),
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+) -> SessionRecord:
+    """Update the model configuration of an existing session.
+
+    Args:
+        session_id (`str`): The session to update.
+        body (`UpdateSessionRequest`): Fields to update.
+        user_id (`str`): Injected authenticated user ID.
+        storage (`StorageBase`): Injected storage backend.
+
+    Returns:
+        `SessionRecord`: The full session record after the update.
+
+    Raises:
+        `HTTPException`: 404 if the session, agent, or credential does not
+            exist or does not belong to the authenticated user.
+    """
+    existing = await storage.get_session(user_id, agent_id, session_id)
+    if existing is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Session '{session_id}' not found.",
+        )
+
+    await _ensure_credential_exists(storage, user_id, body.chat_model_config)
+    await _ensure_credential_exists(
+        storage,
+        user_id,
+        body.fallback_chat_model_config,
+    )
+    await _ensure_credential_exists(storage, user_id, body.tts_model_config)
+    await _ensure_knowledge_bases_exist(
+        storage,
+        user_id,
+        body.knowledge_config,
+    )
+
+    updated_state = existing.state
+    if body.permission_mode is not None:
+        updated_ctx = existing.state.permission_context.model_copy(
+            update={"mode": body.permission_mode},
+        )
+
+        updated_state = existing.state.model_copy(
+            update={
+                "permission_context": updated_ctx,
+            },
+        )
+
+    # PATCH semantics: only fields explicitly present in the request body are
+    # applied. ``exclude_unset=True`` lets clients distinguish "leave
+    # unchanged" (omit) from "clear" (send ``null``) — required for clearing
+    # ``fallback_chat_model_config``.
+    config_updates = body.model_dump(
+        exclude_unset=True,
+        exclude={"permission_mode"},
+    )
+
+    return await storage.upsert_session(
+        user_id=user_id,
+        agent_id=agent_id,
+        config=SessionConfig.model_validate(
+            {**existing.config.model_dump(mode="json"), **config_updates},
+        ),
+        state=updated_state,
+        session_id=session_id,
+    )
+
+
+# ----------------------------------------------------------------------
+# Messages: fetch persisted messages for a session
+# ----------------------------------------------------------------------
+
+
+@session_router.get(
+    "/{session_id}/messages",
+    response_model=ListMessagesResponse,
+    summary="List messages for a session",
+)
+async def list_messages(
+    session_id: str,
+    agent_id: str = Query(description="Agent the session belongs to."),
+    offset: int = Query(0, ge=0, description="Pagination offset."),
+    limit: int = Query(50, ge=1, le=200, description="Max messages."),
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+    message_bus: MessageBus = Depends(get_message_bus),
+) -> ListMessagesResponse:
+    """Return persisted messages for a session.
+
+    Args:
+        session_id: The session to query.
+        agent_id: Agent the session belongs to.
+        offset: Pagination offset.
+        limit: Maximum number of messages to return.
+        user_id: Injected authenticated user ID.
+        storage: Injected storage backend.
+        message_bus: Injected message bus.
+
+    Returns:
+        Messages and running status.
+    """
+    existing = await storage.get_session(user_id, agent_id, session_id)
+    if existing is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Session '{session_id}' not found.",
+        )
+
+    messages = await storage.list_messages(
+        user_id,
+        session_id,
+        offset=offset,
+        limit=limit,
+    )
+    return ListMessagesResponse(
+        messages=messages,
+        is_running=await message_bus.is_locked(
+            MessageBusKeys.session_lock(session_id),
+        ),
+    )
+
+
+# ----------------------------------------------------------------------
+# Stream: live SSE connection for session events
+# ----------------------------------------------------------------------
+
+_HEARTBEAT_INTERVAL_SECS = 30
+# Interval between SSE heartbeat comment frames (``:\\n\\n``).
+
+
+async def _worker_still_asking(
+    storage: StorageBase,
+    user_id: str,
+    worker_agent_id: str,
+    worker_session_id: str,
+    reply_id: str,
+) -> bool:
+    """Return whether a worker session is still parked on the ASKING
+    tool call identified by ``reply_id``.
+
+    This is the reconcile-on-read check (design §3.5): the worker
+    session's own ``state.context`` is the single source of truth for
+    "does this confirmation still need answering". A leader-side
+    pending projection whose worker has already resolved / cancelled
+    the call is a ghost and must not be replayed.
+
+    Mirrors the wakeup guard in
+    :meth:`ChatService._run_impl` — a request is "still asking" when
+    the tail ``AssistantMsg`` of the worker carries a tool call in
+    ``ASKING`` or ``SUBMITTED`` state for the matching ``reply_id``.
+
+    Args:
+        storage (`StorageBase`):
+            Application storage.
+        user_id (`str`):
+            The owner user id.
+        worker_agent_id (`str`):
+            The worker agent that owns the session.
+        worker_session_id (`str`):
+            The worker session to inspect.
+        reply_id (`str`):
+            The reply id the pending request belongs to.
+
+    Returns:
+        `bool`:
+            ``True`` if the worker is still awaiting confirmation for
+            ``reply_id``; ``False`` otherwise (resolved, cancelled, or
+            the session/record is gone).
+    """
+    session = await storage.get_session(
+        user_id,
+        worker_agent_id,
+        worker_session_id,
+    )
+    if session is None or not session.state.context:
+        return False
+    last_msg = session.state.context[-1]
+    if last_msg.role != "assistant" or last_msg.id != reply_id:
+        return False
+    return any(
+        tc.state in (ToolCallState.ASKING, ToolCallState.SUBMITTED)
+        for tc in last_msg.get_content_blocks("tool_call")
+    )
+
+
+@session_router.get(
+    "/{session_id}/stream",
+    summary="Subscribe to a session's event stream (SSE)",
+    response_description="Server-Sent Events stream of AgentEvent objects",
+)
+async def stream_session_events(
+    session_id: str,
+    agent_id: str = Query(description="Agent the session belongs to."),
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+    message_bus: MessageBus = Depends(get_message_bus),
+) -> StreamingResponse:
+    """Subscribe to a session's live event stream.
+
+    Returns a ``text/event-stream`` that first replays any buffered
+    events from the current run's replay log (if a run is in progress
+    or just finished), then streams live events as they are produced
+    by :meth:`ChatService.run`. The connection stays open
+    until the client disconnects — subsequent runs on the same session
+    are delivered over the same connection.
+
+    A heartbeat comment frame (``:\\n\\n``) is sent every 30 seconds to
+    keep the connection alive through reverse proxies.
+
+    Args:
+        session_id (`str`):
+            The session to subscribe to.
+        agent_id (`str`):
+            The agent that owns the session (used for ownership
+            validation).
+        user_id (`str`):
+            Injected authenticated user id.
+        storage (`StorageBase`):
+            Injected storage backend (ownership check only).
+        message_bus (`MessageBus`):
+            Injected message bus (replay + live subscription).
+
+    Returns:
+        `StreamingResponse`:
+            SSE stream of AgentEvent frames + periodic heartbeats.
+    """
+    existing = await storage.get_session(user_id, agent_id, session_id)
+    if existing is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Session '{session_id}' not found.",
+        )
+
+    async def _sse_generator() -> AsyncGenerator[str, None]:
+        # 1. Replay buffered events from the current run (if any).
+        for _entry_id, event in await message_bus.log_read(
+            MessageBusKeys.session_events(session_id),
+            max_count=MessageBusKeys.SESSION_REPLAY_MAX_LEN,
+        ):
+            yield f"data: {json.dumps(event)}\n\n"
+
+        # 1b. Inject pending subagent HITL cards projected onto this
+        #     session as a team leader (design §3.5). These live in a
+        #     durable Redis hash — NOT in the replay log (trimmed per
+        #     run) nor in the leader's own Msg history — so a fresh
+        #     reconnect after the worker parked still surfaces them.
+        #
+        #     Reconcile-on-read: the worker session's own context is the
+        #     SSOT. Inject only when the worker is still ASKING; drop and
+        #     delete ghosts (worker resolved/cancelled without clearing).
+        projection = SessionProjection(message_bus)
+        for payload in await projection.list(
+            session_id,
+            SubagentHitlProjector.KIND,
+        ):
+            if not await _worker_still_asking(
+                storage,
+                user_id,
+                payload["worker_agent_id"],
+                payload["worker_session_id"],
+                payload["reply_id"],
+            ):
+                await projection.delete(
+                    session_id,
+                    SubagentHitlProjector.KIND,
+                    SubagentHitlProjector.entry_id(
+                        payload["worker_session_id"],
+                        payload["reply_id"],
+                    ),
+                )
+                continue
+            custom = CustomEvent(
+                name=SubagentHitlProjector.EVT_REQUIRE,
+                value=payload,
+            )
+            yield f"data: {json.dumps(custom.model_dump(mode='json'))}\n\n"
+
+        # 2. Live subscribe via a background feeder task that pushes
+        #    events into a queue. The main loop reads from the queue
+        #    with a timeout so we can interleave heartbeat frames.
+        #
+        #    We avoid calling ``wait_for(__anext__())`` on the async
+        #    generator directly because cancelling a suspended
+        #    ``__anext__`` leaves the generator in a "running" state
+        #    that prevents ``aclose()`` from working.
+        queue: asyncio.Queue[dict | None] = asyncio.Queue()
+
+        async def _feeder() -> None:
+            """Read from the bus subscription and forward to the queue.
+
+            Pushes ``None`` as a sentinel when the subscription ends
+            (which in practice only happens if the bus shuts down).
+            """
+            try:
+                async for evt in message_bus.subscribe(
+                    MessageBusKeys.session_events(session_id),
+                ):
+                    await queue.put(
+                        {k: v for k, v in evt.items() if k != "_entry_id"},
+                    )
+            except asyncio.CancelledError:
+                pass
+            finally:
+                await queue.put(None)
+
+        feeder_task = asyncio.create_task(
+            _feeder(),
+            name=f"sse-feeder:{session_id}",
+        )
+
+        try:
+            while True:
+                try:
+                    item = await asyncio.wait_for(
+                        queue.get(),
+                        timeout=_HEARTBEAT_INTERVAL_SECS,
+                    )
+                    if item is None:
+                        break
+                    yield f"data: {json.dumps(item)}\n\n"
+                except asyncio.TimeoutError:
+                    yield ":\n\n"
+        finally:
+            feeder_task.cancel()
+            try:
+                await feeder_task
+            except asyncio.CancelledError:
+                pass
+
+    return StreamingResponse(
+        _sse_generator(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "X-Accel-Buffering": "no",
+        },
+    )

src/agentscope/app/_router/_tts_model.py

@@ -0,0 +1,40 @@
+# -*- coding: utf-8 -*-
+"""The TTS model router."""
+
+from fastapi import APIRouter, Depends, HTTPException, status
+
+from ._schema import ListTTSModelsResponse, ListTTSModelsRequest
+from ...credential import CredentialFactory
+
+tts_model_router = APIRouter(
+    prefix="/tts-model",
+    tags=["tts-model"],
+    responses={404: {"description": "Not found"}},
+)
+
+
+@tts_model_router.get(
+    "/",
+    response_model=ListTTSModelsResponse,
+    summary="List all candidate TTS models under the given credential type",
+)
+async def list_tts_models(
+    body: ListTTSModelsRequest = Depends(),
+) -> ListTTSModelsResponse:
+    """Return all candidate TTS models under the given credential type.
+
+    Args:
+        body (ListTTSModelsRequest): The request body.
+
+    Returns:
+        `ListTTSModelsResponse`: The response body.
+    """
+    credential_cls = CredentialFactory.get_credential_class(body.provider)
+    if credential_cls is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Provider '{body.provider}' not found.",
+        )
+
+    models = credential_cls.list_tts_models()
+    return ListTTSModelsResponse(models=models, total=len(models))

src/agentscope/app/_router/_workspace.py

@@ -0,0 +1,220 @@
+# -*- coding: utf-8 -*-
+"""Workspace router — manage MCP clients and skills on a workspace."""
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from pydantic import BaseModel, Field
+
+from ..deps import (
+    get_current_user_id,
+    get_storage,
+    get_workspace_manager,
+)
+from ..workspace_manager import WorkspaceManagerBase
+from ..storage import StorageBase
+from ...mcp import MCPClient
+from ...skill import Skill
+from ...workspace import WorkspaceBase
+
+workspace_router = APIRouter(prefix="/workspace", tags=["workspace"])
+
+
+class AddSkillRequest(BaseModel):
+    """The request to add skill."""
+
+    skill_path: str
+
+
+class ToolInfo(BaseModel):
+    """The tool info."""
+
+    name: str
+    description: str | None = None
+
+
+class MCPClientStatus(MCPClient):
+    """MCPClient enriched with live tool list and health status."""
+
+    is_healthy: bool = False
+    tools: list[ToolInfo] = Field(default_factory=list)
+
+
+async def _resolve_workspace(
+    user_id: str,
+    agent_id: str,
+    session_id: str,
+    storage: StorageBase,
+    workspace_manager: WorkspaceManagerBase,
+) -> WorkspaceBase:
+    """Resolve the workspace for the given session, raising 404 if not
+    found."""
+    session_record = await storage.get_session(user_id, agent_id, session_id)
+    if session_record is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Session {session_id!r} not found.",
+        )
+    return await workspace_manager.get_workspace(
+        user_id,
+        agent_id,
+        session_id,
+        session_record.config.workspace_id,
+    )
+
+
+# ---------------------------------------------------------------------------
+# MCP endpoints
+# ---------------------------------------------------------------------------
+
+
+@workspace_router.get("/mcp")
+async def list_mcps(
+    agent_id: str = Query(...),
+    session_id: str = Query(...),
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+    workspace_manager: WorkspaceManagerBase = Depends(get_workspace_manager),
+) -> list[MCPClientStatus]:
+    """Return all MCP clients with live tool list and health status."""
+    workspace = await _resolve_workspace(
+        user_id,
+        agent_id,
+        session_id,
+        storage,
+        workspace_manager,
+    )
+    clients = await workspace.list_mcps()
+
+    results = []
+    for client in clients:
+        base = client.model_dump()
+        try:
+            mcp_tools = await client.list_tools()
+            tools = [
+                ToolInfo(name=t.name, description=t.description)
+                for t in mcp_tools
+            ]
+            results.append(
+                MCPClientStatus(
+                    **base,
+                    is_healthy=True,
+                    tools=tools,
+                ),
+            )
+        except Exception:
+            results.append(
+                MCPClientStatus(
+                    **base,
+                    is_healthy=False,
+                ),
+            )
+
+    return results
+
+
+@workspace_router.post("/mcp", status_code=status.HTTP_201_CREATED)
+async def add_mcp(
+    mcp: MCPClient,
+    agent_id: str = Query(...),
+    session_id: str = Query(...),
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+    workspace_manager: WorkspaceManagerBase = Depends(get_workspace_manager),
+) -> None:
+    """Add an MCP client to the session's workspace."""
+    workspace = await _resolve_workspace(
+        user_id,
+        agent_id,
+        session_id,
+        storage,
+        workspace_manager,
+    )
+    await workspace.add_mcp(mcp)
+
+
+@workspace_router.delete(
+    "/mcp/{mcp_name}",
+    status_code=status.HTTP_204_NO_CONTENT,
+)
+async def remove_mcp(
+    mcp_name: str,
+    agent_id: str = Query(...),
+    session_id: str = Query(...),
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+    workspace_manager: WorkspaceManagerBase = Depends(get_workspace_manager),
+) -> None:
+    """Remove an MCP client from the session's workspace by name."""
+    workspace = await _resolve_workspace(
+        user_id,
+        agent_id,
+        session_id,
+        storage,
+        workspace_manager,
+    )
+    await workspace.remove_mcp(mcp_name)
+
+
+# ---------------------------------------------------------------------------
+# Skill endpoints
+# ---------------------------------------------------------------------------
+
+
+@workspace_router.get("/skill")
+async def list_skills(
+    agent_id: str = Query(...),
+    session_id: str = Query(...),
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+    workspace_manager: WorkspaceManagerBase = Depends(get_workspace_manager),
+) -> list[Skill]:
+    """Return all skills available in the session's workspace."""
+    workspace = await _resolve_workspace(
+        user_id,
+        agent_id,
+        session_id,
+        storage,
+        workspace_manager,
+    )
+    return await workspace.list_skills()
+
+
+@workspace_router.post("/skill", status_code=status.HTTP_201_CREATED)
+async def add_skill(
+    body: AddSkillRequest,
+    agent_id: str = Query(...),
+    session_id: str = Query(...),
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+    workspace_manager: WorkspaceManagerBase = Depends(get_workspace_manager),
+) -> None:
+    """Add a skill to the session's workspace from the given path."""
+    workspace = await _resolve_workspace(
+        user_id,
+        agent_id,
+        session_id,
+        storage,
+        workspace_manager,
+    )
+    await workspace.add_skill(body.skill_path)
+
+
+@workspace_router.delete(
+    "/skill/{skill_name}",
+    status_code=status.HTTP_204_NO_CONTENT,
+)
+async def remove_skill(
+    skill_name: str,
+    agent_id: str = Query(...),
+    session_id: str = Query(...),
+    user_id: str = Depends(get_current_user_id),
+    storage: StorageBase = Depends(get_storage),
+    workspace_manager: WorkspaceManagerBase = Depends(get_workspace_manager),
+) -> None:
+    """Remove a skill from the session's workspace by name."""
+    workspace = await _resolve_workspace(
+        user_id,
+        agent_id,
+        session_id,
+        storage,
+        workspace_manager,
+    )
+    await workspace.remove_skill(skill_name)

src/agentscope/app/_service/__init__.py

@@ -0,0 +1,29 @@
+# -*- coding: utf-8 -*-
+"""Service layer for the AgentScope app."""
+from ._chat import ChatService
+from ._embedding import get_embedding_model
+from ._index_sweeper import IndexSweeper
+from ._index_task_consumer import IndexTaskConsumer
+from ._index_worker import IndexWorker
+from ._knowledge_base import KnowledgeBaseService
+from ._model import get_model
+from ._tts_model import get_tts_model
+from ._session import SessionService
+from ._session_projection import SessionProjection
+from ._projectors import SubagentHitlProjector
+from ._toolkit import get_toolkit
+
+__all__ = [
+    "ChatService",
+    "IndexSweeper",
+    "IndexTaskConsumer",
+    "IndexWorker",
+    "KnowledgeBaseService",
+    "SessionService",
+    "SessionProjection",
+    "SubagentHitlProjector",
+    "get_embedding_model",
+    "get_model",
+    "get_tts_model",
+    "get_toolkit",
+]

src/agentscope/app/_service/_chat.py

@@ -0,0 +1,588 @@
+# -*- coding: utf-8 -*-
+"""Chat service encapsulating agent execution + persistence logic.
+
+This is the single source of truth for running an agent against a
+session. Both the HTTP chat endpoint and the wakeup dispatcher call
+:meth:`ChatService.run`, guaranteeing identical message persistence,
+middleware wiring, and state handling.
+
+Events produced by the agent are not exposed back through this method
+— they are published to the message bus inside the run, and any client
+that wants them subscribes through the
+``GET /sessions/{sid}/stream`` SSE endpoint.
+"""
+from fastapi import HTTPException
+
+from ..message_bus import MessageBus, MessageBusKeys
+from .._bus_ops import publish_session_event
+from ..rag.knowledge_base_manager import KnowledgeBaseManagerBase
+from ..storage import StorageBase, AgentRecord, SessionRecord
+from .._manager import BackgroundTaskManager, SchedulerManager
+from ..workspace_manager import WorkspaceManagerBase
+from ..middleware import (
+    InboxMiddleware,
+    StateChangeMiddleware,
+    ToolOffloadMiddleware,
+)
+from ...middleware import TTSMiddleware, RAGMiddleware
+from ...rag import KnowledgeBase
+from .._types import (
+    AgentMiddlewareFactory,
+    AgentToolFactory,
+    EventProjector,
+    SubAgentTemplate,
+)
+from ._model import get_model
+from ._tts_model import get_tts_model
+from ._toolkit import get_toolkit
+from ._session_projection import SessionProjection
+from ._projectors import SubagentHitlProjector
+
+from ..._logging import logger
+from ...agent import Agent, ModelConfig
+from ...event import (
+    AgentEvent,
+    ReplyStartEvent,
+    UserConfirmResultEvent,
+    ExternalExecutionResultEvent,
+)
+from ...message import AssistantMsg, Msg, ToolCallState
+from ...permission import AdditionalWorkingDirectory
+
+
+class ChatService:
+    """Run an agent against a session, persisting input/reply messages
+    and updated agent state.
+
+    Shared by the HTTP chat endpoint and the wakeup dispatcher so both
+    paths go through identical validation, assembly, and persistence.
+
+    Session serialisation and event fan-out are both handled by the
+    :class:`MessageBus`: :meth:`bus.session_run` acquires a distributed
+    lock (guaranteeing at most one chat run per session across all
+    processes), and :meth:`bus.session_publish_event` writes each event
+    to both a replay log (for late-joining subscribers) and a live
+    Pub/Sub channel.
+    """
+
+    def __init__(
+        self,
+        storage: StorageBase,
+        workspace_manager: WorkspaceManagerBase,
+        scheduler_manager: SchedulerManager,
+        background_task_manager: BackgroundTaskManager,
+        message_bus: MessageBus,
+        knowledge_base_manager: KnowledgeBaseManagerBase | None = None,
+        extra_agent_middlewares: AgentMiddlewareFactory | None = None,
+        extra_agent_tools: AgentToolFactory | None = None,
+        custom_subagent_templates: dict[str, SubAgentTemplate] | None = None,
+        custom_agent_cls: type[Agent] | None = None,
+        extra_projectors: list[EventProjector] | None = None,
+    ) -> None:
+        """Initialize chat service.
+
+        Args:
+            storage (`StorageBase`):
+                Application storage backend.
+            workspace_manager (`WorkspaceManagerBase`):
+                Provides per-session workspace (tools, MCPs, skills) used
+                during agent assembly.
+            scheduler_manager (`SchedulerManager`):
+                Application scheduler — passed through to
+                :func:`get_toolkit` so the agent toolkit gets the four
+                ``Schedule*`` tools.
+            background_task_manager (`BackgroundTaskManager`):
+                Tracks offloaded long-running tool tasks. Also provides
+                the :class:`ToolStop` tool through
+                :func:`get_toolkit`.
+            message_bus (`MessageBus`):
+                Application-wide message bus. Provides session-level
+                distributed locking (via :meth:`session_run`), event
+                replay + live fan-out (via :meth:`session_publish_event`),
+                and inbox delivery (via :class:`InboxMiddleware`).
+            knowledge_base_manager (`KnowledgeBaseManagerBase | None`, \
+             optional):
+                The application's knowledge base manager.  When
+                provided and the session config carries a
+                ``knowledge_config``, a
+                :class:`~agentscope.middleware.RAGMiddleware`
+                is attached to the agent at run time.  ``None``
+                disables knowledge-base wiring even for sessions that
+                have one configured.
+            extra_agent_middlewares (`AgentMiddlewareFactory | None`, \
+             optional):
+                Async factory invoked at every chat turn to produce
+                user/session-specific middlewares to attach to the agent.
+            extra_agent_tools (`AgentToolFactory | None`, optional):
+                Async factory invoked at every chat turn to produce
+                user/session-specific tools to register in the toolkit.
+            custom_subagent_templates (`dict[str, SubAgentTemplate] | None`,\
+             optional):
+                Sub-agent template registry, keyed by template type.
+                Passed through to :func:`get_toolkit` so that
+                ``AgentCreate`` can route to the appropriate template
+                when a ``subagent_type`` is specified.
+            custom_agent_cls (`type[Agent] | None`, optional):
+                Custom :class:`Agent` subclass for assembling agents.
+                Falls back to :class:`Agent` when ``None``.
+            extra_projectors (`list[EventProjector] | None`, optional):
+                Additional cross-session event projectors to run after
+                the built-in ones (mirrors the ``extra_agent_*``
+                injection style). Each is invoked once per produced
+                event to mirror a UI feed onto another session; see
+                :class:`~agentscope.app._types.EventProjector`.
+        """
+        self._storage = storage
+        self._workspace_manager = workspace_manager
+        self._scheduler_manager = scheduler_manager
+        self._background_task_manager = background_task_manager
+        self._message_bus = message_bus
+        self._knowledge_base_manager = knowledge_base_manager
+        self._extra_agent_middlewares = extra_agent_middlewares
+        self._extra_agent_tools = extra_agent_tools
+        self._sub_agent_templates = custom_subagent_templates
+        self._agent_cls = custom_agent_cls or Agent
+        self._projection = SessionProjection(message_bus)
+        self._projectors: list[EventProjector] = [
+            SubagentHitlProjector(storage),
+            *(extra_projectors or []),
+        ]
+
+    async def run(
+        self,
+        user_id: str,
+        session_id: str,
+        agent_id: str,
+        input_msg: Msg
+        | list[Msg]
+        | UserConfirmResultEvent
+        | ExternalExecutionResultEvent
+        | None = None,
+    ) -> None:
+        """Drive a chat run to completion.
+
+        Persists input messages (Case A) or the incoming continuation
+        event applied to the existing reply (Case B), runs the agent
+        while publishing every produced event to the message bus, and
+        persists the rebuilt reply ``Msg`` + updated agent state when
+        finished.
+
+        Session serialisation is handled by the bus's distributed lock
+        (:meth:`MessageBus.session_run`); events are simultaneously
+        persisted to the replay log and fanned out on the live channel
+        via :meth:`MessageBus.session_publish_event`. Exceptions are
+        logged and swallowed so a single failed fire does not tear
+        down its trigger (HTTP request task, wakeup dispatcher, …).
+
+        Args:
+            user_id (`str`):
+                Authenticated caller's user ID.
+            session_id (`str`):
+                Target session ID.
+            agent_id (`str`):
+                Agent to run.
+            input_msg:
+                One of:
+
+                - ``Msg`` / ``list[Msg]``: new user message(s) (Case A).
+                - ``None``: continue from current state — used by the
+                  wakeup dispatcher when there is no fresh user input
+                  but pending inbox content needs draining (Case A
+                  with no input).
+                - ``UserConfirmResultEvent`` /
+                  ``ExternalExecutionResultEvent``: resume an awaiting
+                  tool call (Case B).
+        """
+        try:
+            await self._run_impl(user_id, session_id, agent_id, input_msg)
+        except Exception as e:
+            logger.exception(
+                "ChatService.run failed for user_id=%s session_id=%s "
+                "agent_id=%s, error=%s",
+                user_id,
+                session_id,
+                agent_id,
+                str(e),
+            )
+
+    async def _run_impl(
+        self,
+        user_id: str,
+        session_id: str,
+        agent_id: str,
+        input_msg: Msg
+        | list[Msg]
+        | UserConfirmResultEvent
+        | ExternalExecutionResultEvent
+        | None,
+    ) -> None:
+        """The actual chat-run body; wrapped by :meth:`run` for error
+        swallowing. Separated so the try/except doesn't bury the
+        per-step logic at one extra indentation level."""
+
+        # ----------------------------------------------------------------
+        # 1. Load records + resolve workspace ONCE here, reused below.
+        # Reject missing records up front with a clear error so the
+        # downstream assembly code can rely on non-None values.
+        # ----------------------------------------------------------------
+        agent_record = await self._storage.get_agent(user_id, agent_id)
+        if agent_record is None:
+            raise HTTPException(
+                status_code=404,
+                detail=f"Agent {agent_id!r} not found.",
+            )
+        session_record = await self._storage.get_session(
+            user_id,
+            agent_id,
+            session_id,
+        )
+        if session_record is None:
+            raise HTTPException(
+                status_code=404,
+                detail=(
+                    f"Session {session_id!r} not found for "
+                    f"agent {agent_id!r}."
+                ),
+            )
+        workspace = await self._workspace_manager.get_workspace(
+            user_id,
+            agent_id,
+            session_id,
+            session_record.config.workspace_id,
+        )
+
+        # Add workspace working directory to the permission context
+        if (
+            workspace.workdir
+            not in session_record.state.permission_context.working_directories
+        ):
+            session_record.state.permission_context.working_directories[
+                workspace.workdir
+            ] = AdditionalWorkingDirectory(
+                path=workspace.workdir,
+                source="session",
+            )
+
+        # ----------------------------------------------------------------
+        # 2. Middlewares — framework-supplied first, then caller extras.
+        # Background-tool completions deliver their results via
+        # ``message_bus.inbox_push + enqueue_wakeup``, so the dispatcher
+        # (any process) wakes an idle session — no in-process retrigger
+        # plumbing is needed here.
+        # ----------------------------------------------------------------
+        middlewares: list = [
+            InboxMiddleware(self._message_bus),
+            StateChangeMiddleware(
+                message_bus=self._message_bus,
+                session_id=session_id,
+            ),
+            ToolOffloadMiddleware(
+                bg_manager=self._background_task_manager,
+                message_bus=self._message_bus,
+                user_id=user_id,
+                agent_id=agent_id,
+            ),
+        ]
+        if self._extra_agent_middlewares is not None:
+            middlewares.extend(
+                await self._extra_agent_middlewares(
+                    user_id,
+                    agent_id,
+                    session_id,
+                ),
+            )
+
+        # ----------------------------------------------------------------
+        # 2b. TTS middleware — inject when the session has a TTS config.
+        # ----------------------------------------------------------------
+        tts_cfg = session_record.config.tts_model_config
+        if tts_cfg is not None:
+            tts_model = await get_tts_model(
+                user_id,
+                tts_cfg,
+                self._storage,
+            )
+            middlewares.append(TTSMiddleware(tts_model))
+
+        # ----------------------------------------------------------------
+        # 2c. Knowledge-base middleware — inject when the session has KBs
+        # attached.  Each KB resolves to its own :class:`KnowledgeBase` handle
+        # (own embedding model + vector store), so the middleware can
+        # retrieve across heterogeneous KBs in one fan-out.
+        # ----------------------------------------------------------------
+        kb_cfg = session_record.config.knowledge_config
+        if (
+            kb_cfg is not None
+            and kb_cfg.knowledge_base_ids
+            and self._knowledge_base_manager is not None
+        ):
+            knowledges: list[KnowledgeBase] = []
+            for kb_id in kb_cfg.knowledge_base_ids:
+                try:
+                    knowledge = (
+                        await self._knowledge_base_manager.get_knowledge(
+                            user_id,
+                            kb_id,
+                        )
+                    )
+                except Exception:  # pylint: disable=broad-except
+                    # A KB the session referenced was deleted (or its
+                    # credential revoked) — log and skip so the chat
+                    # turn can still run with the remaining KBs.
+                    logger.exception(
+                        "Skipping knowledge base %r for session %r: "
+                        "failed to resolve runtime handle.",
+                        kb_id,
+                        session_id,
+                    )
+                    continue
+                knowledges.append(knowledge)
+            if knowledges:
+                middlewares.append(
+                    RAGMiddleware(
+                        knowledge_bases=knowledges,
+                        parameters=RAGMiddleware.Parameters(
+                            **(kb_cfg.parameters or {}),
+                        ),
+                    ),
+                )
+
+        # ----------------------------------------------------------------
+        # 3. Toolkit (workspace tools + planning + ToolStop + schedule +
+        # team + extras + skills + mcps).
+        # ----------------------------------------------------------------
+        toolkit = await get_toolkit(
+            storage=self._storage,
+            workspace=workspace,
+            scheduler_manager=self._scheduler_manager,
+            background_task_manager=self._background_task_manager,
+            message_bus=self._message_bus,
+            middlewares=middlewares,
+            user_id=user_id,
+            agent_record=agent_record,
+            session_record=session_record,
+            extra_factory=self._extra_agent_tools,
+            sub_agent_templates=self._sub_agent_templates,
+        )
+
+        # ----------------------------------------------------------------
+        # 4. Model + fallback (resolved from session's config).
+        # ----------------------------------------------------------------
+        model_cfg = session_record.config.chat_model_config
+        if not model_cfg:
+            raise HTTPException(
+                status_code=404,
+                detail=f"No model configuration found for agent {agent_id}",
+            )
+        model = await get_model(user_id, model_cfg, self._storage)
+
+        fallback_cfg = session_record.config.fallback_chat_model_config
+        fallback_model = (
+            await get_model(user_id, fallback_cfg, self._storage)
+            if fallback_cfg is not None
+            else None
+        )
+
+        # ----------------------------------------------------------------
+        # 5. Assemble the Agent.
+        # ----------------------------------------------------------------
+        agent_state = session_record.state
+        agent_state.session_id = session_id
+        agent = self._agent_cls(
+            name=agent_record.data.name,
+            system_prompt=agent_record.data.system_prompt,
+            model=model,
+            toolkit=toolkit,
+            model_config=ModelConfig(fallback_model=fallback_model),
+            context_config=agent_record.data.context_config,
+            react_config=agent_record.data.react_config,
+            state=agent_state,
+            middlewares=middlewares,
+            offloader=workspace,
+        )
+
+        # ----------------------------------------------------------------
+        # 6. Guard: skip wake-up driven runs when the agent is parked on
+        # an awaiting tool call.
+        #
+        # Wake-ups deliver pending inbox content (team messages, etc.) by
+        # poking the dispatcher to run the session with ``input_msg=None``.
+        # If the agent is currently parked on an ``ASKING`` or
+        # ``SUBMITTED`` tool call (waiting for user confirmation or
+        # external-execution results), kicking off another ``None`` run
+        # would hit :meth:`Agent._check_incoming_event`, which rightly
+        # rejects ``None`` when there is something to confirm — and fail
+        # the run noisily. The inbox content is safe to leave queued:
+        # whenever the user does confirm (or the external result lands),
+        # the resuming run's next reasoning step lets
+        # :class:`InboxMiddleware` drain the queue naturally.
+        # ----------------------------------------------------------------
+        if input_msg is None and agent.state.context:
+            last_msg = agent.state.context[-1]
+            if last_msg.role == "assistant" and last_msg.name == agent.name:
+                awaiting = [
+                    tc
+                    for tc in last_msg.get_content_blocks("tool_call")
+                    if tc.state
+                    in (ToolCallState.ASKING, ToolCallState.SUBMITTED)
+                ]
+                if awaiting:
+                    logger.info(
+                        "Skipping wake-up for session %s: agent is parked "
+                        "on %d awaiting tool call(s); inbox messages will "
+                        "be drained when the agent resumes.",
+                        session_id,
+                        len(awaiting),
+                    )
+                    return
+
+        # ----------------------------------------------------------------
+        # 7. Run the agent inside the distributed session lock
+        # ----------------------------------------------------------------
+        lock_key = MessageBusKeys.session_lock(session_id)
+        events_key = MessageBusKeys.session_events(session_id)
+        async with self._message_bus.acquire_lock(
+            lock_key,
+            ttl_secs=MessageBusKeys.SESSION_RUN_TTL_SECS,
+        ):
+            try:
+                reply_msg: Msg | None = None
+
+                if input_msg is None or isinstance(input_msg, (Msg, list)):
+                    # Case A: new reply (user message(s), or retrigger with
+                    # empty input)
+                    if isinstance(input_msg, (Msg, list)):
+                        input_msgs = (
+                            [input_msg]
+                            if isinstance(input_msg, Msg)
+                            else input_msg
+                        )
+                        for msg in input_msgs:
+                            await self._storage.upsert_message(
+                                user_id,
+                                session_id,
+                                msg,
+                            )
+
+                    async for event in agent.reply_stream(inputs=input_msg):
+                        await publish_session_event(
+                            self._message_bus,
+                            session_id,
+                            event.model_dump(mode="json"),
+                        )
+                        await self._project_event(
+                            user_id,
+                            session_record,
+                            agent_record,
+                            event,
+                        )
+                        if isinstance(event, ReplyStartEvent):
+                            reply_msg = AssistantMsg(
+                                id=event.reply_id,
+                                name=event.name,
+                                content=[],
+                            )
+                        elif reply_msg is not None:
+                            reply_msg.append_event(event)
+
+                else:
+                    # Case B: continuation (UserConfirmResult
+                    #  / ExternalExecResult)
+                    reply_msg = await self._storage.get_message(
+                        user_id,
+                        session_id,
+                        agent.state.reply_id,
+                    )
+
+                    if reply_msg is None:
+                        logger.warning(
+                            "Reply message %r not found in storage for "
+                            "session %r; tool-call state changes from the "
+                            "incoming event will not be persisted.",
+                            agent.state.reply_id,
+                            session_id,
+                        )
+                    elif input_msg:
+                        reply_msg.append_event(input_msg)
+
+                    async for event in agent.reply_stream(inputs=input_msg):
+                        await publish_session_event(
+                            self._message_bus,
+                            session_id,
+                            event.model_dump(mode="json"),
+                        )
+                        await self._project_event(
+                            user_id,
+                            session_record,
+                            agent_record,
+                            event,
+                        )
+                        if reply_msg is not None:
+                            reply_msg.append_event(event)
+
+                # Persist the reply Msg (upsert: overwrite if same id,
+                # append if new).
+                if reply_msg is not None:
+                    await self._storage.upsert_message(
+                        user_id,
+                        session_id,
+                        reply_msg,
+                    )
+
+                # Persist the updated agent state. MUST happen inside
+                # the session lock: if we released the lock first,
+                # another process could acquire it and load a stale
+                # state from storage before this write lands.
+                await self._storage.update_session_state(
+                    user_id=user_id,
+                    agent_id=agent_id,
+                    session_id=session_id,
+                    state=agent.state,
+                )
+            finally:
+                await self._message_bus.log_trim(events_key)
+
+    async def _project_event(
+        self,
+        user_id: str,
+        session_record: SessionRecord,
+        agent_record: AgentRecord,
+        event: AgentEvent,
+    ) -> None:
+        """Run every registered projector against one produced event.
+
+        Each :class:`~agentscope.app._types.EventProjector` decides
+        whether the event is relevant to its cross-session UI feed and,
+        if so, mirrors it onto the owning session via the shared
+        :class:`SessionProjection`. Projectors are independent: one
+        failing must neither tear down the producing run nor block the
+        others, so each call is guarded individually and its error
+        logged. Adding a feed means adding a projector — no change here.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            session_record (`SessionRecord`):
+                The currently-running session's record.
+            agent_record (`AgentRecord`):
+                The currently-running agent's record.
+            event (`AgentEvent`):
+                The event just published to this session's channel.
+        """
+        for projector in self._projectors:
+            try:
+                await projector.maybe_project(
+                    user_id,
+                    session_record,
+                    agent_record,
+                    event,
+                    self._projection,
+                )
+            except Exception as e:  # pylint: disable=broad-except
+                logger.warning(
+                    "Projector %s failed on event %s from session %s: %s",
+                    type(projector).__name__,
+                    type(event).__name__,
+                    session_record.id,
+                    str(e),
+                )

src/agentscope/app/_service/_embedding.py

@@ -0,0 +1,101 @@
+# -*- coding: utf-8 -*-
+"""Embedding model service: builds an EmbeddingModelBase from stored
+credential + config.
+
+Mirrors :mod:`._model` (which does the same for chat models).
+"""
+from fastapi import HTTPException, status
+
+from ..storage import StorageBase, EmbeddingModelConfig
+from ...credential import CredentialFactory
+from ...embedding import EmbeddingModelBase
+
+
+async def get_embedding_model(
+    user_id: str,
+    config: EmbeddingModelConfig,
+    storage: StorageBase,
+) -> EmbeddingModelBase:
+    """Construct an embedding model from a stored credential and config.
+
+    This is the embedding counterpart of
+    :func:`~agentscope.app._service._model.get_model`.  It loads the
+    user's credential from storage, resolves the matching embedding
+    model class, looks up the model card for ``context_size``, and
+    constructs a ready-to-use instance.
+
+    Args:
+        user_id (`str`):
+            The authenticated user id (credential owner).
+        config (`EmbeddingModelConfig`):
+            The embedding model configuration containing
+            ``type``, ``credential_id``, ``model``, and
+            ``parameters``.
+        storage (`StorageBase`):
+            The storage backend for loading credentials.
+
+    Returns:
+        `EmbeddingModelBase`:
+            A configured embedding model instance.
+
+    Raises:
+        `HTTPException`:
+            404 if the credential is not found.
+            400 if the provider does not support embedding.
+    """
+    # 1. Load credential from storage.
+    credential_record = await storage.get_credential(
+        user_id,
+        config.credential_id,
+    )
+    if credential_record is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Credential {config.credential_id!r} not found.",
+        )
+
+    credential = CredentialFactory.from_dict(credential_record.data)
+
+    # 2. Resolve the embedding model class from the credential type.
+    credential_cls = CredentialFactory.get_credential_class(config.type)
+    if credential_cls is None:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Provider {config.type!r} not found.",
+        )
+
+    embedding_cls = credential_cls.get_embedding_model_class()
+    if embedding_cls is None:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=(
+                f"Provider {config.type!r} does not support "
+                f"embedding models."
+            ),
+        )
+
+    # 3. Look up the model card for context_size.
+    context_size: int | None = None
+    for card in embedding_cls.list_models():
+        if card.name == config.model:
+            context_size = card.context_size
+            break
+
+    # 4. Build parameters (provider-specific, no dimensions).
+    parameters = (
+        embedding_cls.Parameters(**config.parameters)
+        if config.parameters
+        else None
+    )
+
+    # 5. Construct the model — dimensions is first-class, not in parameters.
+    kwargs: dict = {
+        "credential": credential,
+        "model": config.model,
+        "dimensions": config.dimensions,
+        "parameters": parameters,
+    }
+    if context_size is not None:
+        kwargs["context_size"] = context_size
+
+    return embedding_cls(**kwargs)

src/agentscope/app/_service/_index_sweeper.py

@@ -0,0 +1,150 @@
+# -*- coding: utf-8 -*-
+"""Background sweep for stuck knowledge-document indexing jobs.
+
+The indexing pipeline relies on two storage-level signals to keep
+moving when something goes wrong:
+
+- a *lease* per in-flight document — its ``lease_expires_at`` is the
+  upper bound on how long a worker may sit on the document before
+  another worker is allowed to take over;
+- a *creation timestamp* on every ``pending`` record — used to catch
+  documents that were never picked up by a worker (e.g. process died
+  right after the upload endpoint persisted the record).
+
+The sweeper periodically scans storage for both classes of stuck
+records and re-enqueues them on the index-task channel.  Re-enqueue is
+safe because the worker's CAS lease acquisition rejects duplicates,
+so multiple nodes running their own sweeper does not produce double
+processing.
+"""
+import asyncio
+from datetime import datetime, timedelta
+from typing import TYPE_CHECKING
+
+from ..._logging import logger
+from .._bus_ops import enqueue_index_task
+
+if TYPE_CHECKING:
+    from ..message_bus import MessageBus
+    from ..storage import StorageBase
+
+
+class IndexSweeper:
+    """Periodically re-enqueues documents stuck in indexing.
+
+    Lifecycle is wired into the app's lifespan: :meth:`start` schedules
+    the background task and runs an immediate sweep so that documents
+    left stuck by the previous process generation get picked up at
+    once; :meth:`stop` cancels the loop on shutdown.
+    """
+
+    def __init__(
+        self,
+        storage: "StorageBase",
+        message_bus: "MessageBus",
+        interval: timedelta = timedelta(seconds=60),
+        pending_grace: timedelta = timedelta(minutes=5),
+    ) -> None:
+        """Initialize the sweeper.
+
+        Args:
+            storage (`StorageBase`):
+                Used to find stuck records and as the contract holder
+                for the lease semantics.
+            message_bus (`MessageBus`):
+                The same bus the upload endpoint uses.  Re-enqueuing
+                a document re-enters the worker pipeline, where the
+                CAS lease acquisition decides whether to actually
+                process or bail.
+            interval (`timedelta`, defaults to ``60s``):
+                How often the loop wakes up.  Roughly one order of
+                magnitude shorter than the typical lease TTL — fast
+                enough to recover from crashes within a few minutes,
+                slow enough not to thrash storage.
+            pending_grace (`timedelta`, defaults to ``5min``):
+                A record may legitimately sit in ``pending`` while the
+                bus push is still queued; only after this grace period
+                do we treat the record as orphaned.
+        """
+        self._storage = storage
+        self._bus = message_bus
+        self._interval = interval
+        self._pending_grace = pending_grace
+        self._task: asyncio.Task[None] | None = None
+
+    async def start(self) -> None:
+        """Start the background sweep loop and run one immediate sweep."""
+        if self._task is not None:
+            return
+        # Catch up from any state the previous generation left behind.
+        await self._sweep_once()
+        self._task = asyncio.create_task(
+            self._loop(),
+            name="kb-index-sweeper",
+        )
+
+    async def stop(self) -> None:
+        """Cancel the sweep loop and wait for it to exit."""
+        if self._task is None:
+            return
+        self._task.cancel()
+        try:
+            await self._task
+        except asyncio.CancelledError:
+            pass
+        self._task = None
+
+    async def _loop(self) -> None:
+        """Run sweeps forever until cancelled."""
+        interval_seconds = self._interval.total_seconds()
+        while True:
+            try:
+                await asyncio.sleep(interval_seconds)
+            except asyncio.CancelledError:
+                return
+            try:
+                await self._sweep_once()
+            except asyncio.CancelledError:
+                return
+            except Exception:  # noqa: BLE001 — keep the loop alive
+                logger.exception("Sweep iteration failed")
+
+    async def _sweep_once(self) -> None:
+        """Find and re-enqueue every stuck document.
+
+        De-duplication: a document showing up in both the
+        expired-lease and orphan-pending queries (a record that was
+        never picked up and whose lease pre-dates the grace period)
+        is enqueued only once per sweep, by record id.
+        """
+        now = datetime.now()
+        pending_threshold = now - self._pending_grace
+
+        seen: set[str] = set()
+        stuck = (
+            await self._storage.list_knowledge_documents_with_expired_lease(
+                now=now,
+            )
+        )
+        orphans = await self._storage.list_knowledge_documents_pending_since(
+            threshold=pending_threshold,
+        )
+        for record in (*stuck, *orphans):
+            if record.id in seen:
+                continue
+            seen.add(record.id)
+            try:
+                await enqueue_index_task(
+                    self._bus,
+                    user_id=record.user_id,
+                    knowledge_base_id=record.knowledge_base_id,
+                    document_id=record.id,
+                )
+            except Exception:  # noqa: BLE001 — keep iterating
+                logger.exception(
+                    "Failed to re-enqueue document %s",
+                    record.id,
+                )
+
+        if seen:
+            logger.info("Re-enqueued %d stuck document(s)", len(seen))

src/agentscope/app/_service/_index_task_consumer.py

@@ -0,0 +1,216 @@
+# -*- coding: utf-8 -*-
+"""Single per-worker-process consumer of the shared index-task channel.
+
+One asyncio task per worker process. Subscribes to the shared
+:meth:`~agentscope.app.message_bus.MessageBusKeys.index_tasks_signal`
+channel and drains the durable
+:meth:`~agentscope.app.message_bus.MessageBusKeys.index_tasks_queue`
+on each signal. For each queued entry it invokes
+:meth:`IndexWorker.process` directly — the worker holds its own
+semaphore so we can fire-and-forget multiple ``process`` calls without
+overrunning resources.
+
+Mirrors :class:`~agentscope.app._manager.WakeupDispatcher`. The two
+patterns are deliberately identical: both subscribe to a signal,
+drain a queue, dispatch each entry, and run forever inside an
+``async with`` block. Keeping them shaped the same makes it cheap to
+reason about either one once you've read the other.
+
+The bus exposes only transport-level primitives — there is no
+``enqueue_index_task`` or ``dequeue_index_task`` method on it. The
+key constants live on :class:`~agentscope.app.message_bus.
+MessageBusKeys` (next to every other application-layer key) and the
+composition is inline here because the consumer is the only sink for
+the channel; introducing a separate ``IndexTaskBroker`` would be
+ceremony without gain.
+"""
+import asyncio
+from typing import TYPE_CHECKING, Any, Self
+
+from ..message_bus import MessageBusKeys
+from ..._logging import logger
+
+if TYPE_CHECKING:
+    from ..message_bus import MessageBus
+    from ._index_worker import IndexWorker
+
+
+class IndexTaskConsumer:
+    """Subscribe-then-drain consumer that feeds :class:`IndexWorker`.
+
+    Args:
+        message_bus (`MessageBus`):
+            Application message bus. The consumer only uses the two
+            transport-level primitives — ``subscribe`` (for the
+            signal channel) and ``queue_drain`` (for the durable
+            task queue).
+        worker (`IndexWorker`):
+            The worker that owns the parse → chunk → index pipeline.
+            ``process`` is invoked once per queue entry; the worker's
+            internal semaphore + lease CAS handle concurrency and
+            deduplication.
+        max_batch (`int`, defaults to ``32``):
+            Maximum entries drained per signal. Keeps a single
+            signal from monopolising the loop when the queue is
+            backed up; remaining entries are picked up on the next
+            signal or the next sweeper-driven eager drain.
+    """
+
+    def __init__(
+        self,
+        message_bus: "MessageBus",
+        worker: "IndexWorker",
+        max_batch: int = 32,
+    ) -> None:
+        self._bus = message_bus
+        self._worker = worker
+        self._max_batch = max_batch
+        self._task: asyncio.Task | None = None
+        # In-flight ``worker.process`` calls. Tracked so ``__aexit__``
+        # can cancel + drain them; otherwise the event-loop teardown
+        # would swallow exceptions raised inside the worker.
+        self._inflight: set[asyncio.Task[Any]] = set()
+
+    async def __aenter__(self) -> Self:
+        """Start the consumer loop and wait until its subscription
+        is live.
+
+        After the subscription is established, an initial drain runs
+        synchronously so tasks queued while every worker was down
+        get picked up immediately on startup, without waiting for
+        a fresh signal.
+        """
+        ready = asyncio.Event()
+        self._task = asyncio.create_task(
+            self._loop(ready),
+            name="index-task-consumer",
+        )
+        await ready.wait()
+        await self._drain_and_dispatch()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: Any,
+    ) -> None:
+        """Cancel the consumer loop and drain any in-flight work.
+
+        Cancellation of the worker's ``process`` calls is a clean
+        shutdown signal — the worker holds the storage lease and
+        will let it expire so the sweeper re-dispatches the document
+        on the next loop tick.
+        """
+        if self._task is not None:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+            self._task = None
+
+        for task in list(self._inflight):
+            task.cancel()
+        if self._inflight:
+            await asyncio.gather(*self._inflight, return_exceptions=True)
+        self._inflight.clear()
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    async def _loop(self, ready: asyncio.Event) -> None:
+        """Long-lived loop: subscribe to the signal and drain on each
+        received signal.
+
+        Args:
+            ready (`asyncio.Event`):
+                Signalled after the underlying SUBSCRIBE completes.
+                :meth:`__aenter__` blocks on this so the producer
+                can publish a signal immediately after start-up
+                without racing.
+        """
+        try:
+            async for _signal in self._bus.subscribe(
+                MessageBusKeys.index_tasks_signal(),
+                on_ready=ready.set,
+            ):
+                await self._drain_and_dispatch()
+        except Exception:  # pylint: disable=broad-except
+            logger.exception(
+                "IndexTaskConsumer loop crashed; subscription ended.",
+            )
+        finally:
+            # If ``subscribe`` raises before ``on_ready`` fires, the
+            # ``__aenter__`` coroutine would deadlock on ``ready.wait()``.
+            # Set the event unconditionally on the way out so startup
+            # cannot stall on a transient bus failure.
+            ready.set()
+
+    async def _drain_and_dispatch(self) -> None:
+        """Read up to a batch of task entries and dispatch each one."""
+        try:
+            entries = await self._bus.queue_drain(
+                MessageBusKeys.index_tasks_queue(),
+                max_count=self._max_batch,
+            )
+        except Exception:  # pylint: disable=broad-except
+            logger.exception("IndexTaskConsumer: drain failed.")
+            return
+
+        for _entry_id, payload in entries:
+            try:
+                user_id = payload["user_id"]
+                knowledge_base_id = payload["knowledge_base_id"]
+                document_id = payload["document_id"]
+            except (KeyError, TypeError):
+                logger.warning(
+                    "IndexTaskConsumer: skipping malformed entry %r",
+                    payload,
+                )
+                continue
+
+            self._spawn(
+                user_id=user_id,
+                knowledge_base_id=knowledge_base_id,
+                document_id=document_id,
+            )
+
+    def _spawn(
+        self,
+        *,
+        user_id: str,
+        knowledge_base_id: str,
+        document_id: str,
+    ) -> None:
+        """Run :meth:`IndexWorker.process` as a tracked background task.
+
+        We do not ``await`` ``worker.process`` inline — a slow parse
+        would block draining the next signal. The worker holds its
+        own concurrency semaphore, so spawning many tasks at once is
+        safe; they will queue at the semaphore.
+        """
+        task = asyncio.create_task(
+            self._worker.process(
+                user_id=user_id,
+                knowledge_base_id=knowledge_base_id,
+                document_id=document_id,
+            ),
+            name=f"index-task:{knowledge_base_id}:{document_id}",
+        )
+        self._inflight.add(task)
+        task.add_done_callback(self._on_done)
+
+    def _on_done(self, task: asyncio.Task[Any]) -> None:
+        """Drop the task reference and log any uncaught exception."""
+        self._inflight.discard(task)
+        if task.cancelled():
+            return
+        exc = task.exception()
+        if exc is not None:
+            logger.exception(
+                "IndexTaskConsumer: worker.process(%s) raised",
+                task.get_name(),
+                exc_info=exc,
+            )

src/agentscope/app/_service/_index_worker.py

@@ -0,0 +1,534 @@
+# -*- coding: utf-8 -*-
+"""Background indexing pipeline for one knowledge document.
+
+The :class:`IndexWorker` owns the post-upload half of the document
+lifecycle.  Given a ``document_id`` it:
+
+1. acquires the processing lease via storage CAS (so only one worker
+   in the cluster handles the document at a time);
+2. reads the bytes back from the blob store (streamed);
+3. routes to a parser by IANA media type;
+4. chunks the resulting sections;
+5. embeds + writes to the vector store through
+   :class:`~agentscope.rag.KnowledgeBase`;
+6. transitions the status through ``parsing → chunking → indexing →
+   ready`` (or ``error``) on the way.
+
+The worker is intentionally embeddable: a single instance can live
+inside the API process (embedded deployment) or inside a dedicated
+worker process (dedicated deployment).  Coordination across workers
+is done entirely through the storage lease — workers do not need to
+know about each other.
+"""
+import asyncio
+import contextlib
+import mimetypes
+from concurrent.futures import ProcessPoolExecutor
+from datetime import timedelta
+from typing import TYPE_CHECKING
+
+from ..._logging import logger
+
+if TYPE_CHECKING:
+    from ..rag.blob_store import BlobStoreBase
+    from ..rag.knowledge_base_manager import KnowledgeBaseManagerBase
+    from ..storage import StorageBase
+    from ...rag import ChunkerBase, ParserBase, Section
+
+# Read blob bytes in chunks bounded so the worker never holds the whole
+# file in memory at once even when the parser is byte-oriented.
+_READ_CHUNK = 1 << 20  # 1 MiB
+
+
+def _build_parser_registry(
+    parsers: "list[ParserBase] | dict[str, ParserBase]",
+) -> "dict[str, ParserBase]":
+    """Normalise the user-supplied parser registry.
+
+    Two input shapes are accepted:
+
+    - **List** — each parser's ``supported_media_types`` is expanded;
+      duplicate media types resolve to the **last** parser in the list
+      (so callers can layer custom parsers over the defaults), with a
+      warning logged for each override so silent shadowing is not
+      possible.
+    - **Dict** — the caller's mapping is used verbatim.  This is the
+      escape hatch for callers who want full control over routing (one
+      parser bound to multiple types, type aliases, etc.); a warning is
+      logged when a parser is registered against a media type it does
+      not declare in ``supported_media_types``, since that almost
+      always indicates a typo.
+
+    Args:
+        parsers (`list[ParserBase] | dict[str, ParserBase]`):
+            The user-supplied parser registry.
+
+    Returns:
+        `dict[str, ParserBase]`:
+            The resolved ``media_type → parser`` routing table.
+    """
+    if isinstance(parsers, dict):
+        for media_type, parser in parsers.items():
+            declared = getattr(parser, "supported_media_types", ())
+            if declared and media_type not in declared:
+                logger.warning(
+                    "Parser %s registered for media type %r but it only "
+                    "declares %s — proceeding with the caller-supplied "
+                    "mapping.",
+                    type(parser).__name__,
+                    media_type,
+                    list(declared),
+                )
+        return dict(parsers)
+
+    registry: dict[str, "ParserBase"] = {}
+    for parser in parsers:
+        for media_type in parser.supported_media_types:
+            previous = registry.get(media_type)
+            if previous is not None and previous is not parser:
+                logger.warning(
+                    "Parser %s overrides %s for media type %r — later "
+                    "entries in `parsers` win.  Pass a "
+                    "`dict[str, ParserBase]` if you want explicit "
+                    "routing.",
+                    type(parser).__name__,
+                    type(previous).__name__,
+                    media_type,
+                )
+            registry[media_type] = parser
+    return registry
+
+
+class IndexWorker:
+    """Drive one document through parse → chunk → index.
+
+    Multiple invocations of :meth:`process` are run concurrently up to
+    a per-worker semaphore.  The semaphore protects shared resources
+    that scale with the number of in-flight parses (memory for big
+    PDFs, embedding API rate budget), while the lease CAS in storage
+    protects against the *cross-worker* version of the same race.
+    """
+
+    def __init__(
+        self,
+        storage: "StorageBase",
+        blob_store: "BlobStoreBase",
+        knowledge_base_manager: "KnowledgeBaseManagerBase",
+        parsers: "list[ParserBase] | dict[str, ParserBase]",
+        chunker: "ChunkerBase",
+        node_id: str,
+        max_concurrency: int = 4,
+        lease_ttl: timedelta = timedelta(seconds=90),
+        parser_executor: ProcessPoolExecutor | None = None,
+    ) -> None:
+        """Initialize the worker.
+
+        Args:
+            storage (`StorageBase`):
+                Document records, lease, status.
+            blob_store (`BlobStoreBase`):
+                Source of the document bytes.
+            knowledge_base_manager (`KnowledgeBaseManagerBase`):
+                Resolves the :class:`KnowledgeBase` runtime for embedding
+                and vector store writes.
+            parsers (`list[ParserBase] | dict[str, ParserBase]`):
+                Parsers used to dispatch uploads by IANA media type.
+                Two input shapes are accepted:
+
+                - **List** — each parser's ``supported_media_types`` is
+                  expanded into a routing table; later entries override
+                  earlier ones for overlapping types, with a warning
+                  logged at construction time.
+                - **Dict** — caller-supplied ``media_type → parser``
+                  routing table used verbatim.  ``supported_media_types``
+                  is **not** consulted, but a warning is logged if a
+                  parser is registered against a media type it does not
+                  declare.
+
+                Same registry the upload service uses, passed in by DI.
+            chunker (`ChunkerBase`):
+                The shared chunker.
+            node_id (`str`):
+                Stable identifier for this worker process.  Used as
+                ``processing_node`` on the lease so the sweeper can
+                tell whose work expired.  Typically
+                ``f"{hostname}:{pid}:{uuid}"``.
+            max_concurrency (`int`, defaults to ``4``):
+                Maximum number of documents processed concurrently by
+                this worker.  Higher values trade memory for
+                throughput; tune per embedding-API rate limits and
+                per-document parse cost.
+            lease_ttl (`timedelta`, defaults to ``90s``):
+                How long a single processing lease lives.  The worker
+                renews periodically so long-running parses do not
+                trip the sweeper.
+            parser_executor (`ProcessPoolExecutor | None`, optional):
+                Process pool used to off-load CPU-intensive parses
+                (PDF, Office).  ``None`` runs parses in the event-loop
+                thread, which is fine for plain text but unsafe for
+                third-party byte-oriented parsers.  Injected so a
+                single pool can be shared across the app (built in
+                lifespan).
+        """
+        self._storage = storage
+        self._blob_store = blob_store
+        self._manager = knowledge_base_manager
+        self._parsers_by_media_type = _build_parser_registry(parsers)
+        self._chunker = chunker
+        self._node_id = node_id
+        self._lease_ttl = lease_ttl
+        self._sem = asyncio.Semaphore(max_concurrency)
+        self._parser_executor = parser_executor
+        # Renewal cadence: refresh while there is still half the lease
+        # left so a one-cycle missed renewal doesn't drop the lease.
+        self._renew_interval = max(lease_ttl / 2, timedelta(seconds=5))
+
+    async def process(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        document_id: str,
+    ) -> None:
+        """Run the full indexing pipeline for one document.
+
+        Steps:
+
+        1. **Lease** — CAS-acquire the processing lease; bail if some
+           other worker already holds it (duplicate dispatch / sweep).
+        2. **Throttle** — wait on the per-worker semaphore so the
+           number of in-flight parses stays bounded.
+        3. **Pipeline** — parse → chunk → embed + write vector store,
+           updating status before each phase.  A background heartbeat
+           keeps the lease alive while parsing runs.
+        4. **Finalise** — on success mark ``ready`` with the final
+           chunk count; on failure mark ``error`` with a sanitised
+           message.  The lease is released regardless.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            knowledge_base_id (`str`):
+                The parent knowledge base id.
+            document_id (`str`):
+                The document to process.
+        """
+        acquired = await self._storage.acquire_knowledge_document_lease(
+            user_id=user_id,
+            knowledge_base_id=knowledge_base_id,
+            document_id=document_id,
+            processing_node=self._node_id,
+            lease_ttl=self._lease_ttl,
+        )
+        if not acquired:
+            logger.debug(
+                "Skipping %s — another worker holds the lease.",
+                document_id,
+            )
+            return
+
+        pipeline_task = asyncio.create_task(
+            self._guarded_pipeline(
+                user_id,
+                knowledge_base_id,
+                document_id,
+            ),
+            name=f"pipeline:{document_id}",
+        )
+        heartbeat_task = asyncio.create_task(
+            self._heartbeat(user_id, knowledge_base_id, document_id),
+            name=f"lease-renew:{document_id}",
+        )
+        try:
+            # Race the pipeline against the heartbeat: if the heartbeat
+            # returns first, the lease was stolen mid-flight (e.g. the
+            # sweeper reaped this worker after a renewal gap) — we MUST
+            # stop the pipeline before it writes the vector store again,
+            # otherwise the worker that just took over and this one will
+            # both insert the same chunks.
+            await asyncio.wait(
+                {pipeline_task, heartbeat_task},
+                return_when=asyncio.FIRST_COMPLETED,
+            )
+
+            if not pipeline_task.done():
+                # Heartbeat reached the end first; only `_heartbeat`'s
+                # lost-lease branch returns, so cancel the pipeline and
+                # surface it as a terminal error for this document.
+                pipeline_task.cancel()
+                with contextlib.suppress(
+                    asyncio.CancelledError,
+                    Exception,
+                ):
+                    await pipeline_task
+                raise RuntimeError(
+                    f"Lost lease on {document_id} during processing; "
+                    "another worker has taken over.",
+                )
+
+            # Pipeline finished first; stop the heartbeat and re-raise
+            # whatever the pipeline raised (if anything).
+            heartbeat_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await heartbeat_task
+            await pipeline_task
+        except Exception as exc:  # noqa: BLE001 — terminal error sink
+            await self._mark_error(
+                user_id,
+                knowledge_base_id,
+                document_id,
+                exc,
+            )
+        finally:
+            # Release is CAS-guarded server-side on ``processing_node``
+            # (storage._base.release_knowledge_document_lease) — calling
+            # it after a stolen lease is a safe no-op.
+            await self._storage.release_knowledge_document_lease(
+                user_id=user_id,
+                knowledge_base_id=knowledge_base_id,
+                document_id=document_id,
+                processing_node=self._node_id,
+            )
+
+    async def _guarded_pipeline(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        document_id: str,
+    ) -> None:
+        """Run the throttled pipeline inside the per-worker semaphore."""
+        async with self._sem:
+            await self._run_pipeline(
+                user_id,
+                knowledge_base_id,
+                document_id,
+            )
+
+    # ------------------------------------------------------------------
+    # Pipeline
+    # ------------------------------------------------------------------
+
+    async def _run_pipeline(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        document_id: str,
+    ) -> None:
+        """Walk the document through parse → chunk → index."""
+        record = await self._storage.get_knowledge_document(
+            user_id,
+            knowledge_base_id,
+            document_id,
+        )
+        if record is None:
+            logger.warning(
+                "Document %s vanished before processing.",
+                document_id,
+            )
+            return
+
+        data = record.data
+        media_type = (
+            data.content_type or mimetypes.guess_type(data.filename)[0]
+        )
+        if not media_type:
+            raise ValueError(
+                f"Cannot determine media type for {data.filename!r}.",
+            )
+        parser = self._parsers_by_media_type.get(media_type)
+        if parser is None:
+            raise ValueError(
+                f"No parser registered for media type {media_type!r}.",
+            )
+
+        # ---- parsing ----
+        await self._storage.update_knowledge_document_status(
+            user_id,
+            knowledge_base_id,
+            document_id,
+            "parsing",
+        )
+        file_bytes = await self._read_blob(data.blob_uri)
+        sections = await self._parse(parser, file_bytes, data.filename)
+
+        # ---- chunking ----
+        await self._storage.update_knowledge_document_status(
+            user_id,
+            knowledge_base_id,
+            document_id,
+            "chunking",
+        )
+        chunks = await self._chunker.chunk(sections)
+
+        # ---- indexing ----
+        await self._storage.update_knowledge_document_status(
+            user_id,
+            knowledge_base_id,
+            document_id,
+            "indexing",
+        )
+        knowledge = await self._manager.get_knowledge(
+            user_id,
+            knowledge_base_id,
+        )
+        await knowledge.insert_document(
+            chunks=chunks,
+            document_id=document_id,
+            document_metadata={
+                "filename": data.filename,
+                "media_type": media_type,
+                "size_bytes": data.size,
+            },
+        )
+
+        # ---- ready ----
+        await self._storage.update_knowledge_document_status(
+            user_id,
+            knowledge_base_id,
+            document_id,
+            "ready",
+            chunk_count=len(chunks),
+        )
+
+    async def _parse(
+        self,
+        parser: "ParserBase",
+        file_bytes: bytes,
+        filename: str,
+    ) -> "list[Section]":
+        """Run the parser, optionally on the process pool."""
+        if self._parser_executor is None:
+            return await parser.parse(file_bytes, filename)
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(
+            self._parser_executor,
+            _run_parser_sync,
+            parser,
+            file_bytes,
+            filename,
+        )
+
+    async def _read_blob(self, blob_uri: str) -> bytes:
+        """Stream the blob into memory in bounded chunks.
+
+        We buffer the whole file before handing it to the parser
+        because today's parser API is byte-oriented (``parse(file:
+        bytes, filename: str)``).  The read loop still avoids large
+        single allocations and gives us a single place to upgrade to a
+        true streaming parser API later — only this method needs to
+        change.
+        """
+        buffer = bytearray()
+        async with self._blob_store.open(blob_uri) as fp:
+            while True:
+                chunk = await fp.read(_READ_CHUNK)
+                if not chunk:
+                    break
+                buffer.extend(chunk)
+        return bytes(buffer)
+
+    # ------------------------------------------------------------------
+    # Lease heartbeat
+    # ------------------------------------------------------------------
+
+    async def _heartbeat(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        document_id: str,
+    ) -> None:
+        """Renew the lease in the background while processing runs.
+
+        Two exit paths:
+
+        - The surrounding pipeline finishes first and cancels this
+          task — silent return via :class:`asyncio.CancelledError`.
+        - The renewal fails (the sweeper reaped this worker and
+          another worker now holds the lease).  The task **returns
+          normally** in this case; :meth:`process` is racing this task
+          against the pipeline and treats a normal return as the
+          "lost-lease" signal, cancelling the pipeline before it
+          double-writes the vector store.
+
+        Anything other than ``ok=False`` keeps the loop alive.
+        """
+        interval_seconds = self._renew_interval.total_seconds()
+        while True:
+            try:
+                await asyncio.sleep(interval_seconds)
+            except asyncio.CancelledError:
+                return
+            ok = await self._storage.renew_knowledge_document_lease(
+                user_id=user_id,
+                knowledge_base_id=knowledge_base_id,
+                document_id=document_id,
+                processing_node=self._node_id,
+                lease_ttl=self._lease_ttl,
+            )
+            if not ok:
+                logger.warning(
+                    "Lost lease on %s while processing.",
+                    document_id,
+                )
+                return
+
+    # ------------------------------------------------------------------
+    # Error sink
+    # ------------------------------------------------------------------
+
+    async def _mark_error(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        document_id: str,
+        exc: BaseException,
+    ) -> None:
+        """Persist a sanitised error and mark the document failed."""
+        logger.exception(
+            "Indexing failed for %s/%s",
+            knowledge_base_id,
+            document_id,
+            exc_info=exc,
+        )
+        message = _sanitise_error(exc)
+        try:
+            await self._storage.update_knowledge_document_status(
+                user_id,
+                knowledge_base_id,
+                document_id,
+                "error",
+                error=message,
+            )
+        except Exception:  # noqa: BLE001 — last-resort log
+            logger.exception(
+                "Failed to persist error status for %s",
+                document_id,
+            )
+
+
+# ----------------------------------------------------------------------
+# Module-level helpers (picklable for ProcessPoolExecutor)
+# ----------------------------------------------------------------------
+
+
+def _run_parser_sync(
+    parser: "ParserBase",
+    file_bytes: bytes,
+    filename: str,
+) -> "list[Section]":
+    """Run an async parser to completion inside a sync executor."""
+    return asyncio.run(parser.parse(file_bytes, filename))
+
+
+def _sanitise_error(exc: BaseException) -> str:
+    """Reduce an exception to a single user-facing line.
+
+    Only the exception class name + first line of its message are
+    kept — stack traces and filesystem paths stay inside the worker
+    log and out of the user-visible record.
+    """
+    raw = str(exc) or exc.__class__.__name__
+    first_line = raw.splitlines()[0].strip()
+    cls = exc.__class__.__name__
+    if not first_line:
+        return cls
+    return f"{cls}: {first_line[:240]}"

src/agentscope/app/_service/_knowledge_base.py

@@ -0,0 +1,515 @@
+# -*- coding: utf-8 -*-
+"""Knowledge base service: HTTP-side orchestration.
+
+The router stays thin and DTO-shaped; everything HTTP-side that needs
+to coordinate persistence, the blob store, the indexing pipeline,
+and the vector store goes through this service.
+
+The split with :class:`~agentscope.rag.KnowledgeBase`
+is deliberate.  ``KnowledgeBase`` is a **library-mode** handle that only
+depends on the vector store; embedded users instantiate one and drive
+the parse → chunk → embed pipeline themselves.  ``KnowledgeBaseService``
+is **service-mode** orchestration: it owns the document records
+(status / blob / lease) and is the single source of truth for "what
+documents exist in this KB" when the app is running over HTTP.  The
+two views are intentionally not blended — mixing library-mode inserts
+with service-mode listing would leave records out of sync, and the
+project's stance is that a knowledge base is managed end-to-end in one
+mode.
+"""
+import uuid
+from typing import IO, TYPE_CHECKING
+
+from fastapi import HTTPException, status
+
+from ..rag.knowledge_base_manager import (
+    DimensionPolicyError,
+    KnowledgeBaseNotFoundError,
+)
+from ..storage import (
+    KnowledgeDocumentData,
+    KnowledgeDocumentRecord,
+)
+from ..._logging import logger
+from .._bus_ops import enqueue_index_task
+
+if TYPE_CHECKING:
+    from ..rag.blob_store import BlobStoreBase
+    from ..rag.knowledge_base_manager import KnowledgeBaseManagerBase
+    from ..message_bus import MessageBus
+    from ..storage import (
+        EmbeddingModelConfig,
+        KnowledgeBaseRecord,
+        StorageBase,
+    )
+    from ...rag import VectorSearchResult
+
+
+class KnowledgeBaseService:
+    """HTTP service for knowledge bases.
+
+    Owns the document lifecycle in service mode: register on upload,
+    enqueue an index task, query status during indexing, and clean up
+    record + blob + vector store on delete.  All parsing / chunking /
+    embedding work happens inside the
+    :class:`~agentscope.app._service.IndexWorker`; the service only
+    hands off (via the message bus) and observes.
+    """
+
+    def __init__(
+        self,
+        storage: "StorageBase",
+        knowledge_base_manager: "KnowledgeBaseManagerBase",
+        blob_store: "BlobStoreBase",
+        message_bus: "MessageBus",
+    ) -> None:
+        """Initialize the service.
+
+        Args:
+            storage (`StorageBase`):
+                The application storage backend; documents are
+                persisted here, not inside the vector store.
+            knowledge_base_manager (`KnowledgeBaseManagerBase`):
+                Resolves the :class:`KnowledgeBase` runtime used to clear
+                vector store records on document deletion.
+            blob_store (`BlobStoreBase`):
+                Owns the bytes from upload until the worker is done.
+                The service writes on upload and deletes on document
+                removal.
+            message_bus (`MessageBus`):
+                Application message bus.  The service publishes one
+                index-task entry per uploaded document via
+                :func:`~agentscope.app._bus_ops.enqueue_index_task`;
+                a co-located or out-of-process
+                :class:`IndexTaskConsumer` drains and processes them.
+        """
+        self._storage = storage
+        self._manager = knowledge_base_manager
+        self._blob_store = blob_store
+        self._bus = message_bus
+
+    # ------------------------------------------------------------------
+    # Knowledge base CRUD
+    # ------------------------------------------------------------------
+
+    async def create_knowledge_base(
+        self,
+        user_id: str,
+        name: str,
+        description: str,
+        embedding_model_config: "EmbeddingModelConfig",
+    ) -> "KnowledgeBaseRecord":
+        """Delegate creation to the manager, mapping policy errors.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            name (`str`):
+                Display name.
+            description (`str`):
+                Free-form description.
+            embedding_model_config (`EmbeddingModelConfig`):
+                Embedding model configuration; pinned to the record.
+
+        Returns:
+            `KnowledgeBaseRecord`:
+                The newly persisted record.
+
+        Raises:
+            `HTTPException`:
+                ``409`` when the requested embedding dimension
+                violates the manager's dimension policy.
+        """
+        try:
+            return await self._manager.create_knowledge_base(
+                user_id=user_id,
+                name=name,
+                description=description,
+                embedding_model_config=embedding_model_config,
+            )
+        except DimensionPolicyError as exc:
+            raise HTTPException(
+                status_code=status.HTTP_409_CONFLICT,
+                detail=str(exc),
+            ) from exc
+
+    async def list_knowledge_bases(
+        self,
+        user_id: str,
+    ) -> "list[KnowledgeBaseRecord]":
+        """List all knowledge base records owned by the given user.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+
+        Returns:
+            `list[KnowledgeBaseRecord]`:
+                All knowledge base records belonging to the user.
+        """
+        return await self._manager.list_knowledge_bases(user_id)
+
+    async def update_knowledge_base(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        name: str | None = None,
+        description: str | None = None,
+    ) -> "KnowledgeBaseRecord":
+        """Update mutable fields on a knowledge base, raising 404 if absent.
+
+        Only ``name`` and ``description`` are mutable.  The embedding
+        model configuration is pinned at creation time.
+        """
+        record = await self._manager.update_knowledge_base(
+            user_id=user_id,
+            knowledge_base_id=knowledge_base_id,
+            name=name,
+            description=description,
+        )
+        if record is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Knowledge base {knowledge_base_id!r} not found.",
+            )
+        return record
+
+    async def delete_knowledge_base(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+    ) -> None:
+        """Delete a knowledge base, raising 404 if absent.
+
+        Documents under the KB are cascade-deleted at the storage
+        layer; blob files referenced by those records are released
+        best-effort here so disk space is reclaimed even though the
+        manager + storage cascade would otherwise orphan them.
+        """
+        documents = await self._storage.list_knowledge_documents(
+            user_id,
+            knowledge_base_id,
+        )
+        for document in documents:
+            await self._delete_blob_quietly(document.data.blob_uri)
+
+        deleted = await self._manager.delete_knowledge_base(
+            user_id,
+            knowledge_base_id,
+        )
+        if not deleted:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Knowledge base {knowledge_base_id!r} not found.",
+            )
+
+    # ------------------------------------------------------------------
+    # Document management
+    # ------------------------------------------------------------------
+
+    async def register_document(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        filename: str,
+        stream: IO[bytes],
+        size: int,
+        content_type: str | None = None,
+    ) -> KnowledgeDocumentRecord:
+        """Persist an uploaded document and enqueue it for indexing.
+
+        Streams ``stream`` into the blob store (so the bytes never
+        live fully in memory), records a ``pending`` document, and
+        pushes an index-task entry onto the message bus.  Returns
+        immediately — a worker (in-process or dedicated) takes over
+        from here and the client tracks progress via
+        :meth:`get_document_status`.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            knowledge_base_id (`str`):
+                The target knowledge base id.
+            filename (`str`):
+                The original filename.
+            stream (`IO[bytes]`):
+                A synchronous binary stream — typically
+                ``UploadFile.file`` from FastAPI.
+            size (`int`):
+                Byte length declared by the uploader.  Persisted on
+                the record for the UI; not authoritative.
+            content_type (`str | None`, optional):
+                IANA media type; ``None`` lets the worker fall back
+                to a filename guess at processing time.
+
+        Returns:
+            `KnowledgeDocumentRecord`:
+                The persisted record (``status='pending'``) with the
+                final ``blob_uri`` filled in.
+
+        Raises:
+            `HTTPException`:
+                ``404`` if the knowledge base does not exist.
+        """
+        # Authorise before touching the blob store: raising after a
+        # write would leave the blob orphaned.
+        await self._authorise_kb(user_id, knowledge_base_id)
+
+        document_id = uuid.uuid4().hex
+        blob_uri = await self._blob_store.write_stream(
+            key=f"kb/{knowledge_base_id}/{document_id}",
+            stream=stream,
+        )
+
+        record = KnowledgeDocumentRecord(
+            id=document_id,
+            user_id=user_id,
+            knowledge_base_id=knowledge_base_id,
+            data=KnowledgeDocumentData(
+                filename=filename,
+                size=size,
+                content_type=content_type,
+                blob_uri=blob_uri,
+            ),
+        )
+        try:
+            stored = await self._storage.upsert_knowledge_document(
+                user_id,
+                record,
+            )
+        except Exception:
+            # Storage write failed — drop the blob so the orphan
+            # sweeper doesn't later see a referenced-by-nobody file.
+            await self._delete_blob_quietly(blob_uri)
+            raise
+
+        await enqueue_index_task(
+            self._bus,
+            user_id=user_id,
+            knowledge_base_id=knowledge_base_id,
+            document_id=document_id,
+        )
+        return stored
+
+    async def list_documents(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+    ) -> list[KnowledgeDocumentRecord]:
+        """List every document registered against a knowledge base.
+
+        Service-mode source of truth: reads from storage, NOT the
+        vector store.  Documents in ``pending`` / ``parsing`` /
+        ``chunking`` / ``indexing`` / ``error`` show up here even
+        though they have no chunks in the vector store yet.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            knowledge_base_id (`str`):
+                The target knowledge base id.
+
+        Returns:
+            `list[KnowledgeDocumentRecord]`:
+                Every document registered against the knowledge base,
+                in unspecified order.
+
+        Raises:
+            `HTTPException`:
+                ``404`` if the knowledge base does not exist.
+        """
+        await self._authorise_kb(user_id, knowledge_base_id)
+        return await self._storage.list_knowledge_documents(
+            user_id,
+            knowledge_base_id,
+        )
+
+    async def get_document_status(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        document_ids: list[str],
+    ) -> list[KnowledgeDocumentRecord]:
+        """Batch-fetch documents for status polling.
+
+        The endpoint backing this method accepts a comma-separated list
+        of ids so the front-end can ask "what's the state of these N
+        in-flight uploads" in a single round-trip.  Records that do
+        not exist or do not belong to the user are silently skipped —
+        the front-end may legitimately ask about a document that was
+        deleted between two polls.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            knowledge_base_id (`str`):
+                The target knowledge base id.
+            document_ids (`list[str]`):
+                Document ids to look up.
+
+        Returns:
+            `list[KnowledgeDocumentRecord]`:
+                One record per matched id; missing ids omitted.
+
+        Raises:
+            `HTTPException`:
+                ``404`` if the knowledge base does not exist.
+        """
+        await self._authorise_kb(user_id, knowledge_base_id)
+        records: list[KnowledgeDocumentRecord] = []
+        for document_id in document_ids:
+            record = await self._storage.get_knowledge_document(
+                user_id,
+                knowledge_base_id,
+                document_id,
+            )
+            if record is not None:
+                records.append(record)
+        return records
+
+    async def delete_document(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        document_id: str,
+    ) -> None:
+        """Remove a document end-to-end: vector store, record, blob.
+
+        Order is chosen so that a crash mid-way always leaves a
+        recoverable state:
+
+        1. Vector store delete (idempotent — re-deleting an already
+           empty document_id is harmless).
+        2. Storage record delete.
+        3. Blob delete (idempotent).
+
+        A failure at step 1 surfaces as an exception to the caller and
+        the record + blob are left untouched, so a retry sees the same
+        state.  Failures at steps 2/3 leave a small amount of orphan
+        data but the user-visible deletion has already succeeded from
+        the vector store's point of view.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            knowledge_base_id (`str`):
+                The target knowledge base id.
+            document_id (`str`):
+                The document to delete.
+
+        Raises:
+            `HTTPException`:
+                ``404`` if the knowledge base does not exist.
+        """
+        record = await self._storage.get_knowledge_document(
+            user_id,
+            knowledge_base_id,
+            document_id,
+        )
+        if record is None:
+            # 404 if the KB does not exist, otherwise treat the
+            # missing document as already-deleted (idempotent).
+            await self._authorise_kb(user_id, knowledge_base_id)
+            return
+
+        knowledge = await self._resolve_knowledge(user_id, knowledge_base_id)
+        await knowledge.delete_document(document_id)
+        await self._storage.delete_knowledge_document(
+            user_id,
+            knowledge_base_id,
+            document_id,
+        )
+        await self._delete_blob_quietly(record.data.blob_uri)
+
+    # ------------------------------------------------------------------
+    # Search
+    # ------------------------------------------------------------------
+
+    async def search(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+        query: str,
+        top_k: int = 5,
+    ) -> "list[VectorSearchResult]":
+        """Search a knowledge base by text query.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            knowledge_base_id (`str`):
+                The knowledge base to search.
+            query (`str`):
+                The natural-language query.
+            top_k (`int`, defaults to ``5``):
+                Maximum number of results.
+
+        Returns:
+            `list[VectorSearchResult]`:
+                The top hits ordered by descending similarity score.
+
+        Raises:
+            `HTTPException`:
+                ``404`` if the knowledge base does not exist.
+        """
+        knowledge = await self._resolve_knowledge(user_id, knowledge_base_id)
+        return await knowledge.search(queries=[query], top_k=top_k)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    async def _authorise_kb(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+    ) -> "KnowledgeBaseRecord":
+        """Look the KB record up so we can 404 cleanly.
+
+        The check is intentionally separate from :meth:`_resolve_knowledge`
+        because document-level endpoints (list / delete) need to refuse
+        unknown KBs without paying the embedding-model construction cost
+        that :meth:`_resolve_knowledge` triggers.
+        """
+        record = await self._storage.get_knowledge_base(
+            user_id,
+            knowledge_base_id,
+        )
+        if record is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Knowledge base {knowledge_base_id!r} not found.",
+            )
+        return record
+
+    async def _resolve_knowledge(
+        self,
+        user_id: str,
+        knowledge_base_id: str,
+    ) -> "object":
+        """Resolve a :class:`KnowledgeBase` and translate not-found to 404."""
+        try:
+            return await self._manager.get_knowledge(
+                user_id,
+                knowledge_base_id,
+            )
+        except KnowledgeBaseNotFoundError as exc:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=str(exc),
+            ) from exc
+
+    async def _delete_blob_quietly(self, blob_uri: str) -> None:
+        """Best-effort blob delete — swallow backend errors.
+
+        Treated as cleanup: if the blob store is unavailable the
+        record/vector-store state is still consistent and a future
+        sweep can reclaim the disk space.  Surface only via logs.
+        """
+        try:
+            await self._blob_store.delete(blob_uri)
+        except Exception:  # noqa: BLE001 — cleanup only
+            logger.exception(
+                "Failed to delete blob %s",
+                blob_uri,
+            )

src/agentscope/app/_service/_model.py

@@ -0,0 +1,50 @@
+# -*- coding: utf-8 -*-
+"""Model service: builds a ChatModelBase from stored credential + config."""
+from fastapi import HTTPException, status
+
+from ..storage import StorageBase, ChatModelConfig
+from ...credential import CredentialFactory
+from ...model import ChatModelBase
+
+
+async def get_model(
+    user_id: str,
+    config: ChatModelConfig,
+    storage: StorageBase,
+) -> ChatModelBase:
+    """Get the model instance from the configuration and storage.
+
+    Args:
+        user_id (`str`):
+            The user id.
+        config (`ChatModelConfig`):
+            The chat model configuration.
+        storage (`StorageBase`):
+            The storage instance.
+
+    Returns:
+        `ChatModelBase`:
+            The model instance.
+    """
+    credential_record = await storage.get_credential(
+        user_id,
+        config.credential_id,
+    )
+    if credential_record is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Credential {config.credential_id!r} not found.",
+        )
+
+    credential = CredentialFactory.from_dict(credential_record.data)
+    model_cls = credential.get_chat_model_class()
+    parameters = (
+        model_cls.Parameters(**config.parameters)
+        if config.parameters
+        else None
+    )
+    return model_cls(
+        credential=credential,
+        model=config.model,
+        parameters=parameters,
+    )

src/agentscope/app/_service/_projectors/__init__.py

@@ -0,0 +1,13 @@
+# -*- coding: utf-8 -*-
+"""Built-in event projectors.
+
+Each projector mirrors one cross-session UI feed onto the owning
+session via the shared
+:class:`~agentscope.app._service._session_projection.SessionProjection`
+primitive. See :class:`~agentscope.app._types.EventProjector`.
+"""
+from ._subagent_hitl import SubagentHitlProjector
+
+__all__ = [
+    "SubagentHitlProjector",
+]

src/agentscope/app/_service/_projectors/_subagent_hitl.py

@@ -0,0 +1,270 @@
+# -*- coding: utf-8 -*-
+"""Projector that bridges team-member HITL events to leader sessions.
+
+When a team *member* (worker) session hits a tool call that needs human
+confirmation, the worker run parks on an ``ASKING`` tool call in its
+**own** session — invisible to a client subscribed only to the *leader*
+session's event stream. This projector mirrors each such pending
+request onto the leader session so the leader UI can render and resolve
+it, and clears it when the request is answered.
+
+It is a thin strategy over the generic
+:class:`~agentscope.app._service._session_projection.SessionProjection`
+primitive: this file holds only the HITL-specific policy (which events
+matter, how to resolve the leader, what the card payload looks like).
+The durable hash, live notification, and key conventions all live in
+the shared primitive.
+
+Persistence model (see the design doc, §2.4):
+
+- **Authoritative state** is the worker session's own ``state.context``
+  (the ``ASKING`` tool call). The projection is only a mirror.
+- The projected hash entry carries **no TTL**: a legitimate
+  confirmation can stay pending indefinitely. Stale entries (worker
+  cancelled/crashed without clearing) are healed by reconcile-on-read
+  at SSE replay time.
+"""
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from ....event import (
+    RequireUserConfirmEvent,
+    RequireExternalExecutionEvent,
+    UserConfirmResultEvent,
+    ExternalExecutionResultEvent,
+    ReplyEndEvent,
+)
+
+if TYPE_CHECKING:
+    from ...storage import AgentRecord, SessionRecord, StorageBase
+    from ....event import AgentEvent
+    from .._session_projection import SessionProjection
+
+
+class SubagentHitlProjector:
+    """Project pending team-member HITL requests onto leader sessions.
+
+    Holds the storage handle it needs to resolve a worker's team (and
+    thus its leader). The :class:`SessionProjection` it writes through
+    is passed in per call by
+    :class:`~agentscope.app._service.ChatService`, which also resolves
+    confirm-routing and SSE replay through this projector's
+    :meth:`resolve` / :meth:`entry_id` helpers.
+    """
+
+    KIND = "subagent_hitl"
+    """Projection feed key (namespaces the entry within a session's
+    shared projection hash)."""
+
+    EVT_REQUIRE = "subagent_require_user_confirm"
+    """``CustomEvent.name`` used to push/replay a pending request to the
+    leader's event stream."""
+
+    EVT_RESULT = "subagent_user_confirm_result"
+    """``CustomEvent.name`` used to tell the leader UI a pending request
+    has been resolved and its card should be cleared."""
+
+    def __init__(self, storage: "StorageBase") -> None:
+        """Bind the storage backend.
+
+        Args:
+            storage (`StorageBase`):
+                Application storage, used to resolve the team (and hence
+                the leader session) a worker session belongs to.
+        """
+        self._storage = storage
+
+    @staticmethod
+    def entry_id(worker_session_id: str, reply_id: str) -> str:
+        """Return the projection entry id for one pending request.
+
+        Args:
+            worker_session_id (`str`):
+                The worker session that emitted the HITL request.
+            reply_id (`str`):
+                The worker-side reply id the request belongs to.
+
+        Returns:
+            `str`:
+                The entry id, ``"{worker_session_id}:{reply_id}"``.
+        """
+        return f"{worker_session_id}:{reply_id}"
+
+    async def maybe_project(
+        self,
+        user_id: str,
+        session_record: "SessionRecord",
+        agent_record: "AgentRecord",
+        event: "AgentEvent",
+        projection: "SessionProjection",
+    ) -> None:
+        """Mirror a worker HITL event onto its team's leader session.
+
+        When a *worker* session emits an HITL request, write the pending
+        card (durable entry + live notification) onto the leader; when
+        it resolves one or its reply ends, clear the card. No-op for
+        non-team sessions and for the leader session itself (a leader's
+        own HITL reaches its client directly).
+
+        Args:
+            user_id (`str`):
+                The owner of the running session.
+            session_record (`SessionRecord`):
+                The currently-running session's record.
+            agent_record (`AgentRecord`):
+                The currently-running agent's record. Only
+                ``source == "team"`` agents forward.
+            event (`AgentEvent`):
+                The event just published to this session's channel.
+            projection (`SessionProjection`):
+                Shared primitive used to write the durable entry and the
+                live notification.
+        """
+        # Fast path: only team-member sessions forward anything, and
+        # only for the event kinds we care about.
+        if agent_record.source != "team" or not session_record.team_id:
+            return
+        if not isinstance(
+            event,
+            (
+                RequireUserConfirmEvent,
+                RequireExternalExecutionEvent,
+                UserConfirmResultEvent,
+                ExternalExecutionResultEvent,
+                ReplyEndEvent,
+            ),
+        ):
+            return
+
+        team = await self._storage.get_team(
+            user_id,
+            session_record.team_id,
+        )
+        if team is None or team.session_id == session_record.id:
+            # No team, or this IS the leader session — nothing to mirror.
+            return
+        leader_sid = team.session_id
+
+        if isinstance(
+            event,
+            (RequireUserConfirmEvent, RequireExternalExecutionEvent),
+        ):
+            payload = {
+                "worker_session_id": session_record.id,
+                "worker_agent_id": agent_record.id,
+                "worker_agent_name": agent_record.data.name,
+                "reply_id": event.reply_id,
+                "event_type": (
+                    "require_user_confirm"
+                    if isinstance(event, RequireUserConfirmEvent)
+                    else "require_external_execution"
+                ),
+                "event": event.model_dump(mode="json"),
+                "created_at": datetime.now().isoformat(),
+            }
+            await projection.upsert(
+                leader_sid,
+                self.KIND,
+                self.entry_id(session_record.id, event.reply_id),
+                payload,
+            )
+            await projection.publish(leader_sid, self.EVT_REQUIRE, payload)
+        else:
+            # Clear the pending card. ``ReplyEndEvent`` is the primary
+            # clear signal (the resume's continuation event is NOT
+            # republished through the stream); the explicit result
+            # events clear early when they do flow through. All are
+            # idempotent — deleting an already-gone entry is a no-op.
+            await projection.delete(
+                leader_sid,
+                self.KIND,
+                self.entry_id(session_record.id, event.reply_id),
+            )
+            await projection.publish(
+                leader_sid,
+                self.EVT_RESULT,
+                {
+                    "worker_session_id": session_record.id,
+                    "reply_id": event.reply_id,
+                },
+            )
+
+    @classmethod
+    async def resolve(
+        cls,
+        projection: "SessionProjection",
+        leader_sid: str,
+        reply_id: str,
+    ) -> dict | None:
+        """Find the pending entry for ``reply_id`` under a leader.
+
+        Used by the confirm-routing entry point (the chat router): given
+        a confirm result POSTed to the leader session, locate which
+        worker session it actually belongs to so the result can be
+        forwarded there.
+
+        Args:
+            projection (`SessionProjection`):
+                The shared projection store to scan.
+            leader_sid (`str`):
+                The leader session the confirm result was POSTed to.
+            reply_id (`str`):
+                The worker-side reply id carried by the confirm result.
+
+        Returns:
+            `dict | None`:
+                The stored payload (with ``worker_session_id`` /
+                ``worker_agent_id``), or ``None`` when no pending entry
+                matches — meaning the confirm is the leader's own.
+        """
+        for entry in await projection.list(leader_sid, cls.KIND):
+            if entry.get("reply_id") == reply_id:
+                return entry
+        return None
+
+    @classmethod
+    async def purge(
+        cls,
+        projection: "SessionProjection",
+        leader_sid: str,
+    ) -> None:
+        """Drop every pending HITL entry for a leader session.
+
+        Used when the leader session (or its team) is deleted. Scoped to
+        this feed so other projections on the same session survive.
+
+        Args:
+            projection (`SessionProjection`):
+                The shared projection store.
+            leader_sid (`str`):
+                The leader session to purge.
+        """
+        await projection.purge(leader_sid, cls.KIND)
+
+    @classmethod
+    async def drop_worker(
+        cls,
+        projection: "SessionProjection",
+        leader_sid: str,
+        worker_sid: str,
+    ) -> None:
+        """Drop every pending entry that originated from one worker.
+
+        Used when a single worker session is deleted while the leader
+        survives.
+
+        Args:
+            projection (`SessionProjection`):
+                The shared projection store.
+            leader_sid (`str`):
+                The leader session the entries are projected onto.
+            worker_sid (`str`):
+                The worker session whose entries should be dropped.
+        """
+        for entry in await projection.list(leader_sid, cls.KIND):
+            if entry.get("worker_session_id") == worker_sid:
+                await projection.delete(
+                    leader_sid,
+                    cls.KIND,
+                    cls.entry_id(worker_sid, entry["reply_id"]),
+                )

src/agentscope/app/_service/_session.py

@@ -0,0 +1,473 @@
+# -*- coding: utf-8 -*-
+"""Cross-resource session lifecycle service.
+
+Owns the "stop in-flight runs + delete records + drop bus state"
+cascades that ``DELETE /sessions/{sid}``, ``DELETE /agents/{aid}``,
+``DELETE /schedules/{sid}`` and the agent-facing
+:class:`~agentscope.app._tools.TeamDelete` /
+:class:`~agentscope.app._manager._scheduler._tools.ScheduleDelete`
+tools all share.
+
+Layering
+========
+
+Methods deliberately delegate down the cascade so the bus-touching
+logic lives in exactly one place — :meth:`delete_session`. Higher-level
+methods only orchestrate which sessions to delete, then ask storage
+to clean its own non-session scope (records, indexes, back-refs).
+
+::
+
+    delete_session    ← atomic: cancel run, storage.delete_session,
+                        bus.session_purge
+        │
+    delete_team       → service.delete_agent per worker
+                      → storage.delete_team    (record + leader detach)
+        │
+    delete_agent      → service.delete_session per session
+                      → service.delete_schedule per owned schedule
+                      → storage.delete_agent   (agent record + team back-refs)
+        │
+    delete_schedule   → service.delete_session per spawned session
+                      → storage.delete_schedule (schedule record + indexes)
+
+Storage's own internal cascades (e.g.
+``storage.delete_agent`` re-iterating sessions) become idempotent
+no-ops because the records are already gone — they still execute, but
+do no work and never touch the bus, so the storage layer stays
+unaware of the message bus.
+
+Separation of concerns
+======================
+
+Storage and message bus are treated as distinct backends — they may
+live in different databases in the future. The service is the **only**
+component that touches both in the same call. Storage code never
+imports the bus; bus code never imports storage.
+"""
+import asyncio
+
+from ..message_bus import MessageBus, MessageBusKeys
+from ..storage import StorageBase
+from ._session_projection import SessionProjection
+from ._projectors import SubagentHitlProjector
+from ..._logging import logger
+
+
+class SessionService:
+    """Cancel in-flight chat runs and cascade-delete related records.
+
+    The cancel side broadcasts via
+    :meth:`MessageBus.session_publish_cancel`, then polls
+    :meth:`MessageBus.session_is_running` until the run-lock clears or
+    a timeout expires — so the implementation is multi-process and
+    multi-node by construction.
+
+    Args:
+        storage (`StorageBase`):
+            Persistent storage backend. Owns durable records and their
+            cascades among themselves.
+        message_bus (`MessageBus`):
+            Live message bus. Owns transient per-session state (events
+            log, inbox, run-lock, cancel channel).
+    """
+
+    _CANCEL_POLL_INTERVAL_SECS: float = 0.1
+    """Interval between :meth:`MessageBus.session_is_running` polls
+    while waiting for a cancelled run to release its distributed
+    run-lock."""
+
+    def __init__(
+        self,
+        storage: StorageBase,
+        message_bus: MessageBus,
+    ) -> None:
+        """Bind dependencies.
+
+        Args:
+            storage (`StorageBase`): Persistent storage backend.
+            message_bus (`MessageBus`): Live message bus.
+        """
+        self._storage = storage
+        self._bus = message_bus
+        self._projection = SessionProjection(message_bus)
+
+    # ------------------------------------------------------------------
+    # Cancel
+    # ------------------------------------------------------------------
+
+    async def cancel_session_run(
+        self,
+        session_id: str,
+        *,
+        timeout: float = 10.0,
+    ) -> bool:
+        """Broadcast a session cancel and wait for the chat-run lock to
+        clear.
+
+        Publishes one cancel payload on the bus's shared cancel channel,
+        unconditionally. Every process's
+        :class:`~agentscope.app._manager.CancelDispatcher` reacts to the
+        broadcast by cancelling whatever it locally holds for the
+        session — the chat-run asyncio task **and** any background
+        tasks owned by that session. The publisher does not need to
+        know which worker holds which piece.
+
+        After publishing, polls
+        :meth:`MessageBus.session_is_running` until the distributed
+        chat-run lock clears. Only the chat run holds a distributed
+        lock; BG tasks do not, so this poll only waits for the chat
+        run. Returns immediately when no chat run was active.
+
+        Idempotent: calling on an idle session just sends a no-op
+        broadcast and observes a clear lock.
+
+        Args:
+            session_id (`str`):
+                The session whose chat run + BG tasks should be
+                cancelled.
+            timeout (`float`, defaults to ``10.0``):
+                Maximum seconds to wait for the chat-run lock to
+                release. On timeout the method returns ``False`` so
+                callers can proceed (e.g. with cascade delete) instead
+                of hanging on a process that may have died.
+
+        Returns:
+            `bool`:
+                ``True`` if the chat-run lock was confirmed released
+                within ``timeout`` seconds (or was never held).
+                ``False`` if the lock was still held when the timeout
+                expired.
+        """
+        await self._bus.publish(
+            MessageBusKeys.session_cancel_channel(),
+            {"session_id": session_id},
+        )
+
+        deadline = asyncio.get_event_loop().time() + timeout
+        while True:
+            if not await self._bus.is_locked(
+                MessageBusKeys.session_lock(session_id),
+            ):
+                return True
+            if asyncio.get_event_loop().time() >= deadline:
+                logger.warning(
+                    "Session %s did not release its run-lock within "
+                    "%.1fs after cancel; proceeding anyway.",
+                    session_id,
+                    timeout,
+                )
+                return False
+            await asyncio.sleep(self._CANCEL_POLL_INTERVAL_SECS)
+
+    # ------------------------------------------------------------------
+    # Delete cascades — every higher-level method delegates to
+    # ``delete_session`` so the cancel + bus-purge logic exists in
+    # exactly one place.
+    # ------------------------------------------------------------------
+
+    async def delete_session(
+        self,
+        user_id: str,
+        agent_id: str,
+        session_id: str,
+    ) -> bool:
+        """Cancel, delete and bus-purge a single session.
+
+        This is the atomic primitive — every other cascade delegates
+        here for per-session work.
+
+        Steps:
+
+        1. Cancel any in-flight run for ``session_id`` (cross-process
+           via the bus cancel channel).
+        2. Delete the session record (and its storage-side cascade:
+           message log, schedule-session index, team dissolution when
+           this session leads one — recursive into worker agents).
+        3. Purge transient bus state for ``session_id`` (events log,
+           inbox).
+
+        Worker sessions that storage cascades through are picked up
+        here too: when this session is a team leader,
+        ``storage.delete_session`` calls ``storage.delete_team`` →
+        ``storage.delete_agent`` → ``storage.delete_session`` for each
+        worker, and we mirror that on the bus side by purging worker
+        sessions identified up front via
+        :meth:`_team_worker_session_ids`.
+
+        Args:
+            user_id (`str`): The owner user id.
+            agent_id (`str`): The agent that owns the session.
+            session_id (`str`): The session to delete.
+
+        Returns:
+            `bool`:
+                ``True`` if the session record existed and was deleted,
+                ``False`` otherwise. Mirrors
+                :meth:`StorageBase.delete_session`.
+        """
+        # Identify all bus-purge targets before storage mutates anything.
+        worker_sids = await self._team_worker_session_ids(
+            user_id,
+            agent_id,
+            session_id,
+        )
+        all_sids = [session_id, *worker_sids]
+
+        # Clean leader-side subagent HITL projections before storage
+        # cascades remove the records we need to resolve roles from.
+        await self._purge_subagent_hitl(user_id, agent_id, session_id)
+
+        await self._cancel_runs(all_sids)
+        deleted = await self._storage.delete_session(
+            user_id,
+            agent_id,
+            session_id,
+        )
+        await self._purge_bus(all_sids)
+        return deleted
+
+    async def delete_team(self, user_id: str, team_id: str) -> bool:
+        """Cancel, delete and bus-purge a team.
+
+        Delegates worker dissolution to :meth:`delete_agent` (one call
+        per ``member_id``) so the per-session cancel + bus purge runs
+        for each worker. The leader's own session is **not** deleted —
+        teams dissolve, leaders survive (and have their ``team_id``
+        cleared by ``storage.delete_team``).
+
+        Args:
+            user_id (`str`): The owner user id.
+            team_id (`str`): The team to dissolve.
+
+        Returns:
+            `bool`:
+                ``True`` if the team record existed and was deleted.
+        """
+        team = await self._storage.get_team(user_id, team_id)
+        if team is None:
+            # Still call storage.delete_team so it can clean any index
+            # residue, but the return value will be False.
+            return await self._storage.delete_team(user_id, team_id)
+
+        for member_id in team.data.member_ids:
+            await self.delete_agent(user_id, member_id)
+
+        # storage.delete_team will iterate member_ids again to delete
+        # each worker agent — those calls are now no-ops because the
+        # agents are already gone, leaving only the leader-detach and
+        # team-record cleanup work.
+        return await self._storage.delete_team(user_id, team_id)
+
+    async def delete_agent(self, user_id: str, agent_id: str) -> bool:
+        """Cancel, delete and bus-purge every session and schedule
+        owned by an agent, then drop the agent record.
+
+        Delegates per-session work to :meth:`delete_session` and
+        per-schedule work to :meth:`delete_schedule`, then asks
+        storage to clean the remaining agent-scoped state (the agent
+        record, the agent index entry, and any team back-references).
+
+        Args:
+            user_id (`str`): The owner user id.
+            agent_id (`str`): The agent to delete.
+
+        Returns:
+            `bool`:
+                ``True`` if the agent record existed and was deleted.
+        """
+        for session in await self._storage.list_sessions(user_id, agent_id):
+            await self.delete_session(user_id, agent_id, session.id)
+
+        for schedule in await self._storage.list_schedules(user_id):
+            if schedule.agent_id == agent_id:
+                await self.delete_schedule(user_id, schedule.id)
+
+        # storage.delete_agent re-iterates sessions and schedules —
+        # those re-runs are idempotent no-ops because the records were
+        # already removed above. What remains is the agent record,
+        # the agent index entry, and team back-reference scrubbing.
+        return await self._storage.delete_agent(user_id, agent_id)
+
+    async def delete_schedule(
+        self,
+        user_id: str,
+        schedule_id: str,
+    ) -> bool:
+        """Cancel, delete and bus-purge every session spawned by a
+        schedule, then drop the schedule record.
+
+        Args:
+            user_id (`str`): The owner user id.
+            schedule_id (`str`): The schedule to delete.
+
+        Returns:
+            `bool`:
+                ``True`` if the schedule record existed and was deleted.
+        """
+        for session in await self._storage.list_sessions_by_schedule(
+            user_id,
+            schedule_id,
+        ):
+            await self.delete_session(
+                user_id,
+                session.agent_id,
+                session.id,
+            )
+
+        # storage.delete_schedule re-iterates the same sessions —
+        # idempotent no-ops; only schedule record + indexes remain.
+        return await self._storage.delete_schedule(user_id, schedule_id)
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    async def _team_worker_session_ids(
+        self,
+        user_id: str,
+        agent_id: str,
+        session_id: str,
+    ) -> list[str]:
+        """Return the session ids of every worker in the team that
+        ``session_id`` leads, or ``[]`` when the session does not lead
+        a team.
+
+        Mirrors :meth:`StorageBase.delete_session`'s own team-leader
+        cascade so the bus side can purge the same sessions.
+
+        Args:
+            user_id (`str`): The owner user id.
+            agent_id (`str`):
+                The agent that owns ``session_id``. May be empty when
+                unknown; team-leader lookup does not depend on it.
+            session_id (`str`):
+                The candidate leader session.
+
+        Returns:
+            `list[str]`:
+                Worker session ids, empty when this session is not a
+                team leader.
+        """
+        session = await self._storage.get_session(
+            user_id,
+            agent_id,
+            session_id,
+        )
+        if session is None or not session.team_id:
+            return []
+        team = await self._storage.get_team(user_id, session.team_id)
+        if team is None or team.session_id != session_id:
+            return []
+        sids: list[str] = []
+        for member_id in team.data.member_ids:
+            worker_sessions = await self._storage.list_sessions(
+                user_id,
+                member_id,
+            )
+            sids.extend(s.id for s in worker_sessions)
+        return sids
+
+    async def _cancel_runs(self, session_ids: list[str]) -> None:
+        """Cancel every in-flight run in ``session_ids`` concurrently.
+
+        Args:
+            session_ids (`list[str]`):
+                Sessions whose runs should be cancelled.
+        """
+        if not session_ids:
+            return
+        await asyncio.gather(
+            *(self.cancel_session_run(sid) for sid in session_ids),
+        )
+
+    async def _purge_bus(self, session_ids: list[str]) -> None:
+        """Drop bus state (events log + inbox) for each id concurrently.
+
+        Args:
+            session_ids (`list[str]`):
+                Sessions whose bus state should be purged.
+        """
+        if not session_ids:
+            return
+        await asyncio.gather(
+            *(self._purge_session_bus(sid) for sid in session_ids),
+        )
+
+    async def _purge_session_bus(self, session_id: str) -> None:
+        """Drop all per-session bus state for one session."""
+        await self._bus.log_trim(
+            MessageBusKeys.session_events(session_id),
+        )
+        await self._bus.queue_delete(
+            MessageBusKeys.inbox(session_id),
+        )
+        await self._bus.registry_drop(
+            MessageBusKeys.bg_tasks(session_id),
+        )
+
+    async def _purge_subagent_hitl(
+        self,
+        user_id: str,
+        agent_id: str,
+        session_id: str,
+    ) -> None:
+        """Clean leader-side subagent HITL projections for a session
+        about to be deleted (design §3.7).
+
+        Two cases, resolved from the session's role:
+
+        - **Leader session** (it leads a team): purge the entire hash
+          keyed by this session — every projected member card goes.
+        - **Worker session** (it has a ``team_id`` but is not the
+          leader): drop just this worker's entries from the *leader's*
+          hash, leaving sibling members' cards intact.
+
+        Must run before storage cascades remove the team / session
+        records this resolution depends on. Failures are swallowed — a
+        stale projection is self-healed by reconcile-on-read and must
+        not block the delete cascade.
+
+        Args:
+            user_id (`str`):
+                The owner user id.
+            agent_id (`str`):
+                The agent that owns ``session_id``.
+            session_id (`str`):
+                The session being deleted.
+        """
+        try:
+            session = await self._storage.get_session(
+                user_id,
+                agent_id,
+                session_id,
+            )
+            if session is None or not session.team_id:
+                # Not in a team — also clear any hash that may have been
+                # created with this session as a (future) leader key.
+                await SubagentHitlProjector.purge(self._projection, session_id)
+                return
+
+            team = await self._storage.get_team(user_id, session.team_id)
+            if team is None:
+                await SubagentHitlProjector.purge(self._projection, session_id)
+                return
+
+            if team.session_id == session_id:
+                # Leader session — drop the whole projection store.
+                await SubagentHitlProjector.purge(self._projection, session_id)
+            else:
+                # Worker session — drop only its entries from the
+                # leader's store.
+                await SubagentHitlProjector.drop_worker(
+                    self._projection,
+                    team.session_id,
+                    session_id,
+                )
+        except Exception as e:  # pylint: disable=broad-except
+            logger.warning(
+                "Failed to purge subagent HITL projection for session "
+                "%s: %s",
+                session_id,
+                str(e),
+            )

src/agentscope/app/_service/_session_projection.py

@@ -0,0 +1,186 @@
+# -*- coding: utf-8 -*-
+"""Generic cross-session UI projection primitive.
+
+A *projection* mirrors a UI card owned by one session onto another
+session's event stream, so a client subscribed only to the target
+session can render and resolve it. The canonical use is team HITL: a
+worker (member) session parks on a tool call awaiting confirmation in
+its own session — invisible to a client watching only the *leader* —
+so the pending request is projected onto the leader.
+
+This class is **pure mechanism**: it knows nothing about teams,
+workers, leaders, or HITL. It is the reusable substrate every such
+feature shares — a durable per-session hash plus a live notification —
+so a new projection feature is a small strategy object (an
+``EventProjector``) over this primitive, not a new bus wrapper class.
+
+Backed entirely by the message-bus generic registry primitives
+(``registry_*``) and :meth:`MessageBus.session_publish_event`; no
+business methods are added to ``MessageBus``. Key conventions live in
+:class:`~agentscope.app.message_bus.MessageBusKeys`.
+
+Persistence model:
+
+- The Redis hash is the **only durable** record of a projected card —
+  the target session's event channel (replay log + pub/sub) is not
+  durable across runs. It carries **no TTL**: a legitimate card can
+  stay pending indefinitely. Authoritative truth for whether a card is
+  still live lives in the *owning* session's own state; stale hash
+  entries are healed by reconcile-on-read at SSE replay time, not by
+  expiry.
+- ``kind`` partitions the hash so one target session can host several
+  independent feeds (HITL, progress, errors, …) without collision.
+"""
+import json
+from typing import TYPE_CHECKING
+
+from ..message_bus import MessageBusKeys
+from .._bus_ops import publish_session_event
+from ...event import CustomEvent
+
+if TYPE_CHECKING:
+    from ..message_bus import MessageBus
+
+
+class SessionProjection:
+    """Durable per-session store of UI cards projected from elsewhere.
+
+    A thin stateless wrapper around the message bus — construct one
+    wherever needed (it holds only a bus reference). Entries are grouped
+    per ``(target_session_id, kind)``; within a feed each entry is keyed
+    by a caller-chosen ``entry_id``.
+
+    Live notification piggybacks on the target session's existing event
+    channel via :meth:`publish`, so front-ends receive updates over the
+    same ``GET /sessions/{sid}/stream`` SSE connection they already use.
+    """
+
+    def __init__(self, message_bus: "MessageBus") -> None:
+        """Bind the message bus.
+
+        Args:
+            message_bus (`MessageBus`):
+                Application message bus; only its generic ``registry_*``
+                primitives and :meth:`session_publish_event` are used.
+        """
+        self._bus = message_bus
+
+    async def upsert(
+        self,
+        target_sid: str,
+        kind: str,
+        entry_id: str,
+        payload: dict,
+    ) -> None:
+        """Persist (or overwrite) one projected entry.
+
+        Args:
+            target_sid (`str`):
+                The session the entry is projected onto.
+            kind (`str`):
+                The projection feed (e.g. ``"subagent_hitl"``).
+            entry_id (`str`):
+                Identity of the entry within the feed.
+            payload (`dict`):
+                The entry to store (JSON-serializable).
+        """
+        await self._bus.registry_set(
+            MessageBusKeys.projection_namespace(target_sid),
+            MessageBusKeys.projection_field(kind, entry_id),
+            json.dumps(payload),
+        )
+
+    async def delete(
+        self,
+        target_sid: str,
+        kind: str,
+        entry_id: str,
+    ) -> None:
+        """Remove one projected entry.
+
+        Idempotent: a no-op when the entry is already gone.
+
+        Args:
+            target_sid (`str`):
+                The session the entry was projected onto.
+            kind (`str`):
+                The projection feed.
+            entry_id (`str`):
+                Identity of the entry within the feed.
+        """
+        await self._bus.registry_del(
+            MessageBusKeys.projection_namespace(target_sid),
+            MessageBusKeys.projection_field(kind, entry_id),
+        )
+
+    async def list(self, target_sid: str, kind: str) -> list[dict]:
+        """Return every entry in one feed for a target session.
+
+        Args:
+            target_sid (`str`):
+                The session whose projections to read.
+            kind (`str`):
+                The projection feed to filter by.
+
+        Returns:
+            `list[dict]`:
+                All stored payloads in the feed; empty when none.
+        """
+        raw = await self._bus.registry_getall(
+            MessageBusKeys.projection_namespace(target_sid),
+        )
+        prefix = MessageBusKeys.projection_field_prefix(kind)
+        return [
+            json.loads(value)
+            for field, value in raw.items()
+            if field.startswith(prefix)
+        ]
+
+    async def purge(self, target_sid: str, kind: str | None = None) -> None:
+        """Drop projected entries for a target session.
+
+        Args:
+            target_sid (`str`):
+                The session to purge.
+            kind (`str | None`, optional):
+                When given, drop only that feed's entries (preserving
+                other feeds on the same session). When ``None``, drop
+                the session's entire projection store in one shot.
+        """
+        if kind is None:
+            await self._bus.registry_drop(
+                MessageBusKeys.projection_namespace(target_sid),
+            )
+            return
+        ns = MessageBusKeys.projection_namespace(target_sid)
+        prefix = MessageBusKeys.projection_field_prefix(kind)
+        raw = await self._bus.registry_getall(ns)
+        for field in raw:
+            if field.startswith(prefix):
+                await self._bus.registry_del(ns, field)
+
+    async def publish(
+        self,
+        target_sid: str,
+        event_name: str,
+        value: dict,
+    ) -> None:
+        """Send a live ``CustomEvent`` to a target session's channel.
+
+        Notifies front-ends subscribed to the target session that a
+        projected card should be rendered or cleared.
+
+        Args:
+            target_sid (`str`):
+                The session to notify.
+            event_name (`str`):
+                The ``CustomEvent.name`` carried to the front-end.
+            value (`dict`):
+                The event payload.
+        """
+        custom = CustomEvent(name=event_name, value=value)
+        await publish_session_event(
+            self._bus,
+            target_sid,
+            custom.model_dump(mode="json"),
+        )