mcp-supervisor-workbench 0.1.0__py3-none-any.whl

mcp_supervisor_workbench/__init__.py

@@ -0,0 +1,36 @@
+"""
+MCP AI Supervisor Workbench — 中央控制台
+
+独立进程，提供所有 MCP Agent 的统一管理界面。
+"""
+
+from .config import WorkbenchConfig
+from .error_middleware import error_response
+from . import pid_manager
+from .server import AppState, WorkbenchServer, create_app
+
+
+def main() -> None:
+    """CLI entry point for the workbench server."""
+    import argparse
+    import logging
+
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s [%(name)s] %(levelname)s: %(message)s",
+    )
+
+    parser = argparse.ArgumentParser(description="MCP AI Supervisor Workbench")
+    parser.add_argument("--host", default="127.0.0.1", help="Host to bind (default: 127.0.0.1)")
+    parser.add_argument("--port", type=int, default=None, help="Port (default: 9766 or MCP_WORKBENCH_PORT)")
+    args = parser.parse_args()
+
+    server = WorkbenchServer(host=args.host, port=args.port)
+    print(f"\n  Workbench: http://{server.host}:{server.port}")
+    server.run()
+
+
+__all__ = [
+    "AppState", "WorkbenchConfig", "WorkbenchServer",
+    "create_app", "error_response", "main",
+]

mcp_supervisor_workbench/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running via: python -m mcp_supervisor_workbench"""
+
+from . import main
+
+main()

mcp_supervisor_workbench/agent_registry.py

@@ -0,0 +1,599 @@
+"""
+AgentRegistry — Workbench 核心模块：Agent 生命周期管理
+
+管理所有已注册 Agent 的注册、心跳、状态变更和超时清理。
+使用双索引（agent_id + project_directory）提供 O(1) 查询。
+
+迁移自 registry.py，主要变更：
+- threading.Lock → asyncio.Lock
+- 新增 _by_project 双索引
+- AgentStatus 枚举取代裸字符串
+- 路径标准化
+- 广播回调机制
+"""
+
+from __future__ import annotations
+
+import asyncio
+import enum
+import logging
+import os
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable, Coroutine
+
+from pydantic import BaseModel, Field
+
+from mcp_supervisor_core.log_writer import get_logger as _get_struct_logger
+
+logger = logging.getLogger(__name__)
+
+# Workbench 进程的结构化日志
+_reg_logger = _get_struct_logger("workbench")
+
+
+class AgentStatus(str, enum.Enum):
+    IDLE = "idle"
+    WAITING = "waiting"
+    ACTIVE = "active"
+    OFFLINE = "offline"
+
+
+@dataclass
+class AgentInfo:
+    agent_id: str
+    project_directory: str
+    web_url: str
+    port: int = 0
+    pid: int = 0
+    mode: str = "manual"
+    status: AgentStatus = AgentStatus.IDLE
+    registered_at: float = field(default_factory=time.time)
+    last_heartbeat: float = field(default_factory=time.time)
+    last_message_at: float | None = None
+    session_id: str | None = None
+    session_summary: str = ""
+    original_task: str | None = None
+    cursor_window_title: str = ""
+    vscode_pid: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "agent_id": self.agent_id,
+            "project_directory": self.project_directory,
+            "display_name": os.path.basename(self.project_directory),
+            "web_url": self.web_url,
+            "port": self.port,
+            "pid": self.pid,
+            "mode": self.mode,
+            "status": self.status.value,
+            "registered_at": self.registered_at,
+            "last_heartbeat": self.last_heartbeat,
+            "last_message_at": self.last_message_at,
+            "session_id": self.session_id,
+            "session_summary": self.session_summary,
+            "original_task": self.original_task,
+            "cursor_window_title": self.cursor_window_title,
+            "vscode_pid": self.vscode_pid,
+        }
+
+
+class AgentRegisterRequest(BaseModel):
+    """Pydantic model for agent registration API input validation."""
+    agent_id: str = Field(..., description="Agent UUID")
+    project_directory: str = Field(..., description="Absolute path to project")
+    web_url: str = Field("", description="Agent Web Server URL (optional, can be set later via heartbeat)")
+    port: int = Field(0, description="Agent Web Server port")
+    pid: int = Field(0, description="MCP process PID")
+    mode: str = Field("manual", description="semi or manual")
+    status: str = Field("idle", description="Initial agent status")
+    session_id: str | None = Field(None, description="Current session ID")
+    session_summary: str = Field("", description="Current session summary")
+    original_task: str | None = Field(None, description="Current task description")
+    cursor_window_title: str = Field("", description="Cursor window title")
+    vscode_pid: str = Field("", description="VSCode process PID")
+
+
+BroadcastCallback = Callable[[dict[str, Any]], Coroutine[Any, Any, None]]
+AgentWaitingCallback = Callable[[AgentInfo], Coroutine[Any, Any, None]]
+
+HEARTBEAT_TIMEOUT = 90  # Must match WorkbenchConfig.heartbeat_timeout
+STALE_RETENTION = 86400  # 24 hours: keep offline agents for display
+CHECK_INTERVAL = 30
+# active 状态下超过该时长无消息更新，则自动降为 idle。
+#
+# 背景：当前 MCP client 只在 Qoder 主动调用时上报 status；Qoder 完成一轮工作后
+# 不会主动回报 idle，导致 UI 上“AI 已收到消息，正在工作中”永久卡住。
+# 内存中添加时长兜底，将长时间 active 且无消息的 agent 主动降为 idle。
+# waiting 状态 = agent 真的在 interactive_feedback 等用户回复，不属于“伪忙”，不处理。
+ACTIVE_IDLE_TIMEOUT = 60
+
+
+from mcp_supervisor_core.paths import normalize_path as _normalize_path
+
+
+class AgentRegistry:
+    """Async-safe in-memory registry with dual indexing (agent_id + project_directory)."""
+
+    def __init__(
+        self,
+        heartbeat_timeout: float = HEARTBEAT_TIMEOUT,
+        stale_retention: float = STALE_RETENTION,
+        check_interval: float = CHECK_INTERVAL,
+        active_idle_timeout: float = ACTIVE_IDLE_TIMEOUT,
+    ) -> None:
+        self._agents: dict[str, AgentInfo] = {}
+        self._by_project: dict[str, str] = {}  # normalized_path → agent_id
+        self._replaced_agents: dict[str, float] = {}  # agent_id → replaced_at (黑名单)
+        self._lock = asyncio.Lock()
+
+        self._heartbeat_timeout = heartbeat_timeout
+        self._stale_retention = stale_retention
+        self._check_interval = check_interval
+        self._active_idle_timeout = active_idle_timeout
+
+        self._broadcast_callback: BroadcastCallback | None = None
+        self._on_agent_waiting: AgentWaitingCallback | None = None
+        self._check_task: asyncio.Task[None] | None = None
+
+    # ── Lifecycle ────────────────────────────────────────────────
+
+    def start(self) -> None:
+        """Start background heartbeat check loop. Call after event loop is running."""
+        if self._check_task is None or self._check_task.done():
+            self._check_task = asyncio.create_task(self._heartbeat_check_loop())
+
+    def stop(self) -> None:
+        """Cancel background tasks."""
+        if self._check_task and not self._check_task.done():
+            self._check_task.cancel()
+            self._check_task = None
+
+    # ── Callback Registration ────────────────────────────────────
+
+    def set_broadcast_callback(self, callback: BroadcastCallback) -> None:
+        self._broadcast_callback = callback
+
+    def set_on_agent_waiting(self, callback: AgentWaitingCallback) -> None:
+        self._on_agent_waiting = callback
+
+    # ── Core CRUD ────────────────────────────────────────────────
+
+    async def register_from_request(self, request: AgentRegisterRequest) -> AgentInfo:
+        """Register from a validated Pydantic request model (used by API routes)."""
+        return await self.register(
+            agent_id=request.agent_id,
+            project_directory=request.project_directory,
+            web_url=request.web_url,
+            port=request.port,
+            pid=request.pid,
+            mode=request.mode,
+            status=request.status,
+            session_id=request.session_id,
+            session_summary=request.session_summary,
+            original_task=request.original_task,
+            cursor_window_title=request.cursor_window_title,
+            vscode_pid=request.vscode_pid,
+        )
+
+    async def register(
+        self,
+        agent_id: str,
+        project_directory: str,
+        web_url: str,
+        *,
+        port: int = 0,
+        pid: int = 0,
+        mode: str = "manual",
+        status: str = "idle",
+        session_id: str | None = None,
+        session_summary: str = "",
+        original_task: str | None = None,
+        cursor_window_title: str = "",
+        vscode_pid: str = "",
+    ) -> AgentInfo:
+        """Register a new Agent or replace existing one for the same project.
+
+        被替换的 agent_id 会加入黑名单，防止旧进程心跳 404 后
+        通过 re-register 抢占新进程的注册。
+        """
+        norm_path = _normalize_path(project_directory)
+
+        async with self._lock:
+            # 检查是否在黑名单中（最近被替换的旧 agent_id）
+            if agent_id in self._replaced_agents:
+                replaced_at = self._replaced_agents[agent_id]
+                if time.time() - replaced_at < self._heartbeat_timeout * 2:
+                    _reg_logger.info(
+                        f"rejected={agent_id[:8]} project={os.path.basename(norm_path)} "
+                        f"reason=recently_replaced",
+                        "[REG_REJECT] 拒绝已被替换的旧 Agent 重新注册",
+                    )
+                    return AgentInfo(
+                        agent_id=agent_id, project_directory=norm_path,
+                        web_url=web_url, status=AgentStatus.OFFLINE,
+                    )
+                else:
+                    del self._replaced_agents[agent_id]
+
+            old_agent_id = self._by_project.get(norm_path)
+            if old_agent_id and old_agent_id != agent_id:
+                old_info = self._agents.get(old_agent_id)
+                if old_info:
+                    try:
+                        new_status = AgentStatus(status)
+                    except ValueError:
+                        new_status = AgentStatus.IDLE
+
+                    if (new_status == AgentStatus.OFFLINE
+                            and old_info.status in (AgentStatus.ACTIVE, AgentStatus.WAITING, AgentStatus.IDLE)):
+                        _reg_logger.info(
+                            f"rejected_agent={agent_id[:8]} existing_agent={old_agent_id[:8]} "
+                            f"project={os.path.basename(norm_path)} "
+                            f"new_status=offline existing_status={old_info.status.value} "
+                            f"new_web_url={web_url} existing_web_url={old_info.web_url}",
+                            "[REG_REJECT_OFFLINE_OVERRIDE] 拒绝 offline 注册覆盖在线 Agent",
+                        )
+                        return old_info
+
+                    self._agents.pop(old_agent_id, None)
+                    self._replaced_agents[old_agent_id] = time.time()
+                    logger.info(
+                        "Replacing agent %s with %s for project %s",
+                        old_agent_id, agent_id, norm_path,
+                    )
+
+            if agent_id in self._agents:
+                old_proj = _normalize_path(self._agents[agent_id].project_directory)
+                self._by_project.pop(old_proj, None)
+
+            try:
+                initial_status = AgentStatus(status)
+            except ValueError:
+                initial_status = AgentStatus.IDLE
+
+            now = time.time()
+            info = AgentInfo(
+                agent_id=agent_id,
+                project_directory=norm_path,
+                web_url=web_url,
+                port=port,
+                pid=pid,
+                mode=mode,
+                status=initial_status,
+                registered_at=now,
+                last_heartbeat=now,
+                session_id=session_id,
+                session_summary=session_summary,
+                original_task=original_task,
+                cursor_window_title=cursor_window_title,
+                vscode_pid=vscode_pid,
+            )
+            self._agents[agent_id] = info
+            self._by_project[norm_path] = agent_id
+
+        _reg_logger.info(
+            f"agent_id={agent_id[:8]} project={os.path.basename(norm_path)} pid={pid} port={port}",
+            "[REG_REGISTER] Agent 注册",
+        )
+
+        await self._broadcast(
+            {
+                "type": "project_online",
+                "project": info.to_dict(),
+            }
+        )
+        await self._broadcast(
+            {
+                "type": "agent_registered",
+                "agent_id": agent_id,
+                "project_directory": norm_path,
+                "status": initial_status.value,
+            }
+        )
+
+        if initial_status == AgentStatus.WAITING and self._on_agent_waiting:
+            try:
+                await self._on_agent_waiting(info)
+            except Exception:
+                logger.exception("on_agent_waiting callback failed during register")
+
+        return info
+
+    async def unregister(self, agent_id: str) -> bool:
+        """Remove an agent from the registry. Returns True if found."""
+        async with self._lock:
+            info = self._agents.pop(agent_id, None)
+            if info is None:
+                return False
+            norm = _normalize_path(info.project_directory)
+            if self._by_project.get(norm) == agent_id:
+                del self._by_project[norm]
+
+        # [REG_DEREGISTER] 记录 Agent 注销
+        _reg_logger.info(
+            f"agent_id={agent_id[:8]} project={os.path.basename(info.project_directory)}",
+            "[REG_DEREGISTER] Agent 注销",
+        )
+
+        # 广播 project_offline（React 前端使用）
+        await self._broadcast(
+            {
+                "type": "project_offline",
+                "project_directory": info.project_directory,
+                "last_message_at": info.last_message_at or 0,
+            }
+        )
+        # 兼容旧版 HTML 前端
+        await self._broadcast(
+            {
+                "type": "agent_deregistered",
+                "agent_id": agent_id,
+                "project_directory": info.project_directory,
+            }
+        )
+        return True
+
+    async def heartbeat(self, agent_id: str) -> bool:
+        """Update heartbeat timestamp. Returns False if agent not found."""
+        async with self._lock:
+            info = self._agents.get(agent_id)
+            if info is None:
+                return False
+            info.last_heartbeat = time.time()
+            if info.status == AgentStatus.OFFLINE:
+                info.status = AgentStatus.IDLE
+        # [REG_HEARTBEAT] 记录 Agent 心跳
+        _reg_logger.debug(
+            f"agent_id={agent_id[:8]} project={os.path.basename(info.project_directory)} "
+            f"status={info.status.value}",
+            "[REG_HEARTBEAT] Agent 心跳",
+        )
+        return True
+
+    async def update_status(
+        self,
+        agent_id: str,
+        status: str | AgentStatus,
+        **kwargs: Any,
+    ) -> bool:
+        """Update agent status with optional metadata. Returns False if not found."""
+        if isinstance(status, str):
+            try:
+                new_status = AgentStatus(status)
+            except ValueError:
+                return False
+        else:
+            new_status = status
+
+        async with self._lock:
+            info = self._agents.get(agent_id)
+            if info is None:
+                return False
+            previous = info.status
+            info.status = new_status
+            if "session_id" in kwargs:
+                info.session_id = kwargs["session_id"]
+            if "session_summary" in kwargs:
+                info.session_summary = kwargs["session_summary"]
+            if "original_task" in kwargs:
+                info.original_task = kwargs["original_task"]
+
+        await self._broadcast(
+            {
+                "type": "project_status_changed",
+                "agent_id": agent_id,
+                "project_directory": info.project_directory,
+                "status": new_status.value,
+                "previous_status": previous.value,
+                "session_id": info.session_id,
+                "session_summary": info.session_summary or "",
+            }
+        )
+
+        if new_status == AgentStatus.WAITING and self._on_agent_waiting:
+            if previous != AgentStatus.WAITING:
+                _reg_logger.info(
+                    f"agent_id={agent_id[:8]} project={os.path.basename(info.project_directory)} "
+                    f"previous={previous.value} → waiting",
+                    "[REG_STATUS_WAITING] Agent 状态变为 waiting，触发队列投递回调",
+                )
+                try:
+                    await self._on_agent_waiting(info)
+                except Exception:
+                    logger.exception("on_agent_waiting callback failed")
+
+        return True
+
+    def update_last_message(self, agent_id: str) -> bool:
+        """Update last_message_at timestamp (called synchronously from routes)."""
+        info = self._agents.get(agent_id)
+        if info is None:
+            return False
+        info.last_message_at = time.time()
+        return True
+
+    # ── Query ────────────────────────────────────────────────────
+
+    def get_agent(self, agent_id: str) -> AgentInfo | None:
+        return self._agents.get(agent_id)
+
+    def get_agent_by_project(self, project_directory: str) -> AgentInfo | None:
+        norm = _normalize_path(project_directory)
+        agent_id = self._by_project.get(norm)
+        if agent_id is None:
+            return None
+        return self._agents.get(agent_id)
+
+    def get_all_agents(self) -> list[AgentInfo]:
+        return list(self._agents.values())
+
+    def get_online_agents(self) -> list[AgentInfo]:
+        return [a for a in self._agents.values() if a.status != AgentStatus.OFFLINE]
+
+    def get_waiting_agents(self) -> list[AgentInfo]:
+        return [a for a in self._agents.values() if a.status == AgentStatus.WAITING]
+
+    def get_deliverable_agents(self) -> list[AgentInfo]:
+        """Return agents that can receive queued messages (waiting or idle)."""
+        return [a for a in self._agents.values()
+                if a.status in (AgentStatus.WAITING, AgentStatus.IDLE)]
+
+    def agent_count(self) -> int:
+        return len(self._agents)
+
+    def online_count(self) -> int:
+        return sum(1 for a in self._agents.values() if a.status != AgentStatus.OFFLINE)
+
+    # ── Heartbeat Check ──────────────────────────────────────────
+
+    async def check_heartbeats(self) -> list[str]:
+        """Check all agents for heartbeat timeout. Returns list of timed-out agent_ids."""
+        now = time.time()
+        timed_out: list[str] = []
+
+        async with self._lock:
+            for agent_id, info in self._agents.items():
+                if info.status == AgentStatus.OFFLINE:
+                    continue
+                if now - info.last_heartbeat > self._heartbeat_timeout:
+                    prev = info.status
+                    info.status = AgentStatus.OFFLINE
+                    timed_out.append(agent_id)
+                    # [REG_HEARTBEAT_TIMEOUT] Agent 心跳超时
+                    _hb_age = int(now - info.last_heartbeat)
+                    _reg_logger.warn(
+                        f"agent_id={agent_id[:8]} project={os.path.basename(info.project_directory)} "
+                        f"last_heartbeat_age_seconds={_hb_age}",
+                        "[REG_HEARTBEAT_TIMEOUT] Agent 心跳超时",
+                    )
+
+        for agent_id in timed_out:
+            info = self._agents.get(agent_id)
+            if info:
+                await self._broadcast(
+                    {
+                        "type": "project_status_changed",
+                        "agent_id": agent_id,
+                        "project_directory": info.project_directory,
+                        "status": AgentStatus.OFFLINE.value,
+                        "previous_status": "timeout",
+                    }
+                )
+
+        return timed_out
+
+    async def check_stale_active(self) -> list[str]:
+        """自动把长时间 active 但无消息更新的 agent 降为 idle。
+
+        背景：MCP client 仅在 Qoder 主动调用工具时上报 status，Qoder 自己自然完成一轮工作
+        后不会回报 idle，导致 project.status 永久卡住 active。本 sweep 在心跳循环里
+        同时跑（每 CHECK_INTERVAL），把 status=ACTIVE 且 “last_message_at 距今 > ACTIVE_IDLE_TIMEOUT”
+        的 agent 主动降为 IDLE 并广播，保证 UI 上“AI 工作中”能到时自动消失。
+
+        仅处理 ACTIVE：
+          - WAITING 是真等用户（MCP interactive_feedback 还阻塞着），不能降
+          - OFFLINE 已由 check_heartbeats 处理
+          - IDLE 本身就是目标状态
+        Returns list of demoted agent_ids.
+        """
+        now = time.time()
+        demoted: list[str] = []
+
+        async with self._lock:
+            for agent_id, info in self._agents.items():
+                if info.status != AgentStatus.ACTIVE:
+                    continue
+                # 无 last_message_at 时回退到 registered_at，避免刚注册就被降
+                reference_time = info.last_message_at or info.registered_at
+                age = now - reference_time
+                if age <= self._active_idle_timeout:
+                    continue
+                info.status = AgentStatus.IDLE
+                demoted.append(agent_id)
+                _reg_logger.info(
+                    f"agent_id={agent_id[:8]} project={os.path.basename(info.project_directory)} "
+                    f"idle_age_seconds={int(age)}",
+                    "[REG_ACTIVE_IDLE_SWEEP] Agent 长时 active 无消息更新，自动降为 idle",
+                )
+
+        for agent_id in demoted:
+            info = self._agents.get(agent_id)
+            if info:
+                await self._broadcast(
+                    {
+                        "type": "project_status_changed",
+                        "agent_id": agent_id,
+                        "project_directory": info.project_directory,
+                        "status": AgentStatus.IDLE.value,
+                        "previous_status": AgentStatus.ACTIVE.value,
+                        "session_id": info.session_id,
+                        "session_summary": info.session_summary or "",
+                    }
+                )
+
+        return demoted
+
+    async def cleanup_stale_agents(self) -> list[str]:
+        """Remove agents that have been offline longer than stale_retention.
+
+        Broadcasts project_offline for each removed agent so the frontend
+        drops them from the project list.
+        """
+        cutoff = time.time() - self._stale_retention
+        removed_infos: list[AgentInfo] = []
+
+        async with self._lock:
+            to_remove = [
+                aid for aid, info in self._agents.items()
+                if info.status == AgentStatus.OFFLINE
+                and info.last_heartbeat < cutoff
+            ]
+            for aid in to_remove:
+                info = self._agents.pop(aid)
+                norm = _normalize_path(info.project_directory)
+                if self._by_project.get(norm) == aid:
+                    del self._by_project[norm]
+                removed_infos.append(info)
+
+            # 同时清理过期的黑名单条目
+            blacklist_cutoff = time.time() - self._heartbeat_timeout * 2
+            expired_blacklist = [
+                aid for aid, ts in self._replaced_agents.items()
+                if ts < blacklist_cutoff
+            ]
+            for aid in expired_blacklist:
+                del self._replaced_agents[aid]
+
+        for info in removed_infos:
+            _reg_logger.info(
+                f"agent_id={info.agent_id[:8]} project={os.path.basename(info.project_directory)} "
+                f"offline_hours={int((time.time() - info.last_heartbeat) / 3600)}",
+                "[REG_STALE_REMOVED] 清理过期离线 Agent",
+            )
+            await self._broadcast({
+                "type": "project_offline",
+                "project_directory": info.project_directory,
+                "last_message_at": info.last_message_at or 0,
+            })
+
+        return [info.agent_id for info in removed_infos]
+
+    # ── Internal ─────────────────────────────────────────────────
+
+    async def _broadcast(self, event: dict[str, Any]) -> None:
+        if self._broadcast_callback:
+            try:
+                await self._broadcast_callback(event)
+            except Exception:
+                logger.exception("Broadcast callback failed for %s", event.get("type"))
+
+    async def _heartbeat_check_loop(self) -> None:
+        try:
+            while True:
+                await asyncio.sleep(self._check_interval)
+                await self.check_heartbeats()
+                await self.cleanup_stale_agents()
+                await self.check_stale_active()
+        except asyncio.CancelledError:
+            pass