provide-uterm-platform 0.5.0__tar.gz

provide_uterm_platform-0.5.0/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: provide-uterm-platform
+Version: 0.5.0
+Summary: Platform-specific deployment targets (PTY, PAM, External Management Tier) for provide-uterm
+License-Expression: AGPL-3.0-or-later
+Requires-Python: >=3.11
+Requires-Dist: provide-uterm>=0.5.0
+Provides-Extra: pty
+Requires-Dist: provide-uterm>=0.5.0; extra == "pty"
+Provides-Extra: manager
+Requires-Dist: fastapi>=0.110; extra == "manager"
+Requires-Dist: uvicorn>=0.24; extra == "manager"
+Requires-Dist: pydantic>=2.0; extra == "manager"
+Requires-Dist: pyyaml>=6.0; extra == "manager"
+Requires-Dist: httpx2>=2.10; extra == "manager"
+Provides-Extra: all
+Requires-Dist: provide-uterm>=0.5.0; extra == "all"
+Requires-Dist: fastapi>=0.110; extra == "all"
+Requires-Dist: uvicorn>=0.24; extra == "all"
+Requires-Dist: pydantic>=2.0; extra == "all"
+Requires-Dist: pyyaml>=6.0; extra == "all"
+Requires-Dist: httpx2>=2.10; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.3; extra == "dev"
+Requires-Dist: pytest-cov>=7.0; extra == "dev"
+Requires-Dist: pytest-timeout>=2.4.0; extra == "dev"
+Requires-Dist: mypy>=1.19; extra == "dev"
+Requires-Dist: psutil>=5.9; extra == "dev"
+Requires-Dist: ruff>=0.15; extra == "dev"
+Requires-Dist: bandit>=1.9; extra == "dev"
+Requires-Dist: provide-uterm>=0.5.0; extra == "dev"
+Requires-Dist: fastapi>=0.110; extra == "dev"
+Requires-Dist: uvicorn>=0.24; extra == "dev"
+Requires-Dist: pydantic>=2.0; extra == "dev"
+Requires-Dist: pyyaml>=6.0; extra == "dev"
+Requires-Dist: httpx2>=2.10; extra == "dev"
+Requires-Dist: mcp>=2.0.0; extra == "dev"

provide_uterm_platform-0.5.0/VERSION

@@ -0,0 +1 @@
+0.5.0

provide_uterm_platform-0.5.0/pyproject.toml

@@ -0,0 +1,120 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "provide-uterm-platform"
+dynamic = ["version"]
+description = "Platform-specific deployment targets (PTY, PAM, External Management Tier) for provide-uterm"
+requires-python = ">=3.11"
+license = "AGPL-3.0-or-later"
+dependencies = [
+    "provide-uterm>=0.5.0",
+]
+
+[project.optional-dependencies]
+pty = ["provide-uterm>=0.5.0"]
+# ``httpx2`` is an import-time requirement, not an optional nicety: manager/ext.py
+# imports it at module scope and ext.py is reached eagerly from
+# ``provide.uterm.manager`` via app -> process -> process_impl / _monitor.
+manager = ["fastapi>=0.110", "uvicorn>=0.24", "pydantic>=2.0", "pyyaml>=6.0", "httpx2>=2.10"]
+all = ["provide-uterm>=0.5.0", "fastapi>=0.110", "uvicorn>=0.24", "pydantic>=2.0", "pyyaml>=6.0", "httpx2>=2.10"]
+dev = [
+    "pytest>=9.0",
+    "pytest-asyncio>=1.3",
+    "pytest-cov>=7.0",
+    "pytest-timeout>=2.4.0",
+    "mypy>=1.19",
+    "psutil>=5.9",
+    "ruff>=0.15",
+    "bandit>=1.9",
+    "provide-uterm>=0.5.0",
+    "fastapi>=0.110",
+    "uvicorn>=0.24",
+    "pydantic>=2.0",
+    "pyyaml>=6.0",
+    "httpx2>=2.10",
+    # The manager MCP tests build a real mcp.server.mcpserver.MCPServer to
+    # register the tools onto. The production module only needs the structural
+    # _ToolRegistrar protocol, so mcp is a test-only dependency.
+    "mcp>=2.0.0",
+]
+
+[project.scripts]
+uterm-manager = "provide.uterm.manager.cli:main"
+
+[tool.setuptools.dynamic]
+version = {file = "VERSION"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"provide.uterm" = ["py.typed"]
+"provide.uterm.pty" = ["py.typed", "_native/*"]
+
+[tool.pytest.ini_options]
+consider_namespace_packages = true
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+addopts = [
+    "--import-mode=importlib",
+    "-v",
+    "--strict-markers",
+    "--strict-config",
+    "--tb=short",
+    "-ra",
+    "--cov=provide.uterm.pty",
+    "--cov=provide.uterm.manager",
+    "--cov-branch",
+    "--cov-report=term-missing",
+    "--cov-fail-under=100",
+]
+markers = [
+    "requires_pam: requires /etc/pam.d/provide-uterm service config (skip in CI)",
+    "requires_pam_auth: requires /etc/pam.d/provide-uterm with working unix_chkpwd (skipped in Docker)",
+    "requires_root: requires root or CAP_SETUID to switch users",
+]
+
+[tool.coverage.report]
+fail_under = 100
+show_missing = true
+partial_branches = [
+    "pragma: no branch",
+    "if _libpam is not None:",
+]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+
+[tool.ruff.lint]
+select = [
+    "E", "W", "F", "I", "N", "UP", "B", "C4", "SIM", "TCH", "PTH",
+    "DTZ", "ICN", "ISC", "PERF", "PIE", "RET", "RSE", "TID", "S", "ARG", "RUF",
+]
+# Aligned with the workspace-root ruff config in ../../pyproject.toml, except
+# ``S110`` is left non-ignored at the production-code level so individual
+# try/except/pass blocks must justify themselves with ``# noqa: S110``.
+ignore = [
+    "E501", "S101", "S104", "S108", "S112", "S311", "S603", "S607",
+    "S604", "F811", "N806", "N814", "B017", "SIM105", "SIM117", "ARG001",
+    "ARG002", "PTH108", "SIM108", "PERF401",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401", "RUF022"]
+"tests/**/*.py" = ["E402", "B905", "S101", "S105", "S106", "S110", "ARG", "TCH", "RUF003", "RUF012", "RUF015", "RUF043", "RUF059"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.uv.sources]
+provide-uterm = { workspace = true }

provide_uterm_platform-0.5.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

provide_uterm_platform-0.5.0/src/provide/uterm/manager/__init__.py

@@ -0,0 +1,33 @@
+#
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+
+"""Generic swarm manager for agent orchestration.
+
+Public API::
+
+    from provide.uterm.manager import create_manager_app, ManagerConfig, AgentManager
+    from provide.uterm.manager.models import AgentStatusBase, SwarmStatus, SpawnBatchRequest
+    from provide.uterm.manager.protocols import (
+        AccountPoolPlugin, IdentityStorePlugin, ManagedAgentPlugin,
+        StatusUpdatePlugin, TimeseriesPlugin, WorkerRegistryPlugin,
+    )
+
+    app, manager = create_manager_app(ManagerConfig(), worker_registry={...})
+"""
+
+from __future__ import annotations
+
+from provide.uterm.manager.app import create_manager_app
+from provide.uterm.manager.config import ManagerConfig
+from provide.uterm.manager.core import AgentManager
+from provide.uterm.manager.models import AgentStatusBase, SwarmStatus
+
+__all__ = [
+    "AgentManager",
+    "AgentStatusBase",
+    "ManagerConfig",
+    "SwarmStatus",
+    "create_manager_app",
+]

provide_uterm_platform-0.5.0/src/provide/uterm/manager/_monitor.py

@@ -0,0 +1,271 @@
+#
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+"""Helper coroutines for AgentProcessManager.monitor_processes.
+
+Extracted to keep process.py under the 500-line limit.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from provide.telemetry import get_logger
+
+from provide.uterm.manager.constants import ACTIVE_STATES, RUNNING_STATES, TERMINAL_STATES
+from provide.uterm.manager.ext import EVENT_AGENT_EXITED
+
+if TYPE_CHECKING:
+    import subprocess
+
+    from provide.uterm.manager.process import AgentProcessManager
+
+logger = get_logger(__name__)
+
+_STOP_TIMEOUT_S = 5.0
+
+
+def _set_agent_exit_state(agent: Any, exit_code: int) -> None:
+    """Update agent state fields based on process exit code."""
+    if exit_code == 0:
+        if agent.state == "error" or agent.error_message:
+            agent.state = "error"
+            if not agent.exit_reason:
+                agent.exit_reason = "reported_error_then_exit_0"
+        else:
+            agent.state = "completed"
+            agent.completed_at = time.time()
+            agent.stopped_at = time.time()
+            if not agent.exit_reason:
+                agent.exit_reason = "target_reached"
+    else:
+        agent.state = "error"
+        if not agent.exit_reason:
+            agent.exit_reason = f"exit_code_{exit_code}"
+        if not agent.error_message:
+            agent.error_message = f"Process exited with code {exit_code}"
+        agent.stopped_at = time.time()
+
+
+async def _prune_terminal_agents(
+    pm: AgentProcessManager,
+) -> tuple[list[tuple[str, subprocess.Popen[bytes]]], list[Any]]:
+    """Remove terminal-state agents; return (stop_requests, dead_agents)."""
+
+    prune_stop_requests: list[tuple[str, subprocess.Popen[bytes]]] = []
+    async with pm.manager._state_lock:
+        dead_agents = [b for b in pm.manager.agents.values() if b.state in TERMINAL_STATES]
+        for dead in dead_agents:
+            with contextlib.suppress(OSError, RuntimeError):
+                pm.release_agent_account(dead.agent_id)
+            if (proc := pm.manager.processes.pop(dead.agent_id, None)) is not None:
+                prune_stop_requests.append((dead.agent_id, proc))
+            pm.manager.agents.pop(dead.agent_id, None)
+    return prune_stop_requests, dead_agents
+
+
+def _collect_spawn_configs(
+    active_agents: list[Any],
+    dead_agents: list[Any],
+    last_config: Any,
+) -> list[Any]:
+    """Collect available spawn configs from active agents, dead agents, or last known config."""
+    configs = [b.config for b in active_agents if b.config]
+    if not configs:
+        configs = [b.config for b in dead_agents if b.config]
+    if not configs and last_config:
+        configs = [last_config]
+    return configs
+
+
+def _cleanup_old_worker_logs(pm: AgentProcessManager) -> int:
+    """Delete stale .prev and orphan worker log files. Returns count deleted."""
+    from provide.uterm.manager.constants import WORKER_LOG_RETENTION_S
+
+    log_dir = Path(pm._log_dir) if pm._log_dir else Path("logs/workers")
+    if not log_dir.is_dir():
+        return 0
+    cutoff = time.time() - WORKER_LOG_RETENTION_S
+    deleted = 0
+    active_ids = set(pm.manager.agents.keys())
+    for f in log_dir.iterdir():
+        if not f.is_file():
+            continue
+        try:
+            mtime = f.stat().st_mtime
+        except OSError:
+            continue
+        if mtime >= cutoff:
+            continue
+        if f.suffix == ".prev" or (f.name.endswith(".log") and f.stem not in active_ids):
+            f.unlink(missing_ok=True)
+            deleted += 1
+    if deleted:
+        logger.info("worker_log_cleanup", deleted=deleted)
+    return deleted
+
+
+async def _handle_exited_processes(pm: AgentProcessManager) -> None:
+    """Update state for any agent processes that have exited."""
+    async with pm.manager._state_lock:
+        exited = [(bid, p) for bid, p in list(pm.manager.processes.items()) if p.poll() is not None]
+    for agent_id, process in exited:
+        exit_code = process.returncode
+        logger.warning(EVENT_AGENT_EXITED, agent_id=agent_id, exit_code=exit_code)
+        async with pm.manager._state_lock:
+            agent = pm.manager.agents.get(agent_id)
+            if agent is None:
+                pm.manager.processes.pop(agent_id, None)
+                continue
+            _set_agent_exit_state(agent, exit_code)
+            pm.manager.processes.pop(agent_id, None)
+        pm.release_agent_account(agent_id)
+        await pm.manager.broadcast_status()
+
+
+async def _handle_heartbeat_timeouts(pm: AgentProcessManager) -> None:
+    """Detect agents that have not sent a heartbeat and mark them as error."""
+    now = time.time()
+    heartbeat_timeout = pm.manager.config.heartbeat_timeout_s
+    heartbeat_timed_out: list[str] = []
+
+    heartbeat_stop_requests: list[tuple[str, subprocess.Popen[bytes]]] = []
+    async with pm.manager._state_lock:
+        for agent in list(pm.manager.agents.values()):
+            if agent.state in RUNNING_STATES and now - agent.last_update_time > heartbeat_timeout:
+                logger.warning("agent_heartbeat_timeout", agent_id=agent.agent_id, timeout_s=heartbeat_timeout)
+                agent.state = "error"
+                agent.error_message = (
+                    f"No heartbeat in {heartbeat_timeout:.0f}s - agent process may have crashed or is stuck"
+                )
+                agent.error_type = "HeartbeatTimeout"
+                agent.error_timestamp = time.time()
+                agent.exit_reason = "heartbeat_timeout"
+                agent.stopped_at = time.time()
+                if (proc := pm.manager.processes.pop(agent.agent_id, None)) is not None:
+                    heartbeat_stop_requests.append((agent.agent_id, proc))
+                heartbeat_timed_out.append(agent.agent_id)
+    for agent_id, proc in heartbeat_stop_requests:
+        await pm._stop_process_tree(agent_id=agent_id, process=proc, timeout_s=_STOP_TIMEOUT_S)
+    for bid in heartbeat_timed_out:
+        pm.release_agent_account(bid)
+    if heartbeat_timed_out:
+        await pm.manager.broadcast_status()
+
+
+def _handle_stale_queued(pm: AgentProcessManager) -> None:
+    """Launch agents that have been queued too long without spawning."""
+    now = time.time()
+    for agent in list(pm.manager.agents.values()):
+        if agent.state != "queued" or agent.pid != 0 or agent.started_at is not None:
+            pm._queued_since.pop(agent.agent_id, None)
+            continue
+        queued_since = pm._queued_since.get(agent.agent_id)
+        if queued_since is None:
+            pm._queued_since[agent.agent_id] = now
+            continue
+        if now - queued_since >= pm._queued_launch_delay:
+            if pm.manager.desired_agents > 0:
+                pm._queued_since.pop(agent.agent_id, None)
+                continue
+            logger.warning("stale_queued_agent_launching", agent_id=agent.agent_id, queued_s=round(now - queued_since))
+            pm._queued_since.pop(agent.agent_id, None)
+            if agent.config:
+                task = asyncio.create_task(pm._launch_queued_agent(agent.agent_id, agent.config))
+                pm._spawn_tasks.append(task)
+            else:
+                agent.state = "stopped"
+                agent.exit_reason = "no_config"
+
+
+async def _handle_bust_respawn(pm: AgentProcessManager) -> None:
+    """Kill agents that are in bust context if bust_respawn is enabled."""
+    if not pm.manager.bust_respawn or pm.manager.swarm_paused:
+        return
+    now = time.time()
+
+    bust_stop_requests: list[tuple[str, subprocess.Popen[bytes] | None, int | None]] = []
+    for agent in list(pm.manager.agents.values()):
+        if agent.state != "running":
+            continue
+        ctx = str(getattr(agent, "activity_context", "") or "").upper()
+        if ctx != "BUST":
+            continue
+        logger.info("bust_respawn_killing_agent", agent_id=agent.agent_id)
+        agent.state = "stopped"
+        agent.exit_reason = "bust_respawn"
+        agent.stopped_at = now
+        proc = pm.manager.processes.pop(agent.agent_id, None)
+        pid = agent.pid if agent.pid and agent.pid > 0 else None
+        bust_stop_requests.append((agent.agent_id, proc, pid))
+        pm.release_agent_account(agent.agent_id)
+    for agent_id, proc, pid in bust_stop_requests:
+        await pm._stop_process_tree(agent_id=agent_id, process=proc, pid=pid, timeout_s=_STOP_TIMEOUT_S)
+    await pm.manager.broadcast_status()
+
+
+async def _spawn_to_desired(
+    pm: AgentProcessManager,
+    deficit: int,
+    active_agents: list[Any],
+    dead_agents: list[Any],
+) -> None:
+    """Spawn *deficit* new agents to reach the desired count."""
+    configs_available = _collect_spawn_configs(active_agents, dead_agents, pm._last_spawn_config)
+    for _ in range(deficit):
+        if not configs_available:
+            break
+        config = configs_available[0]
+        async with pm.manager._state_lock:
+            new_agent_id = pm.allocate_agent_id()
+            if new_agent_id not in pm.manager.agents:  # pragma: no branch
+                pm.manager.agents[new_agent_id] = pm.manager._agent_status_class(
+                    agent_id=new_agent_id,
+                    pid=0,
+                    config=config,
+                    state="queued",
+                )
+        logger.info(
+            "desired_state_spawning",
+            agent_id=new_agent_id,
+            deficit=deficit,
+            desired=pm.manager.desired_agents,
+        )
+        task = asyncio.create_task(pm._launch_queued_agent(new_agent_id, config))
+        pm._spawn_tasks.append(task)
+
+
+async def _kill_excess(pm: AgentProcessManager, excess: int, active_agents: list[Any]) -> None:
+    """Kill *excess* agents to trim down to the desired count."""
+    to_kill = sorted(active_agents, key=lambda b: b.agent_id, reverse=True)[:excess]
+    for agent in to_kill:
+        logger.info("desired_state_killing", agent_id=agent.agent_id, excess=excess, desired=pm.manager.desired_agents)
+        with contextlib.suppress(OSError, ProcessLookupError, RuntimeError):
+            await pm.manager.kill_agent(agent.agent_id)
+        with contextlib.suppress(OSError, RuntimeError):
+            pm.release_agent_account(agent.agent_id)
+        async with pm.manager._state_lock:
+            pm.manager.agents.pop(agent.agent_id, None)
+            pm.manager.processes.pop(agent.agent_id, None)
+
+
+async def _handle_desired_state(pm: AgentProcessManager) -> None:
+    """Enforce the desired agent count: spawn deficits, kill excesses."""
+    if pm.manager.desired_agents <= 0 or pm.manager.swarm_paused:
+        return
+    prune_stop_requests, dead_agents = await _prune_terminal_agents(pm)
+    async with pm.manager._state_lock:
+        active_agents = [b for b in pm.manager.agents.values() if b.state in ACTIVE_STATES]
+        deficit = pm.manager.desired_agents - len(active_agents)
+
+    if deficit > 0:
+        await _spawn_to_desired(pm, deficit, active_agents, dead_agents)
+    elif deficit < 0:
+        await _kill_excess(pm, -deficit, active_agents)
+    for agent_id, proc in prune_stop_requests:
+        await pm._stop_process_tree(agent_id=agent_id, process=proc, timeout_s=_STOP_TIMEOUT_S)

provide_uterm_platform-0.5.0/src/provide/uterm/manager/app.py

@@ -0,0 +1,154 @@
+#
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+"""Application factory for the generic swarm manager."""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, Any
+
+from fastapi import APIRouter, FastAPI, WebSocket, WebSocketDisconnect
+from fastapi.middleware.cors import CORSMiddleware
+from provide.telemetry import get_logger
+
+from provide.uterm.manager.auth import setup_auth
+from provide.uterm.manager.core import AgentManager
+from provide.uterm.manager.process import AgentProcessManager
+from provide.uterm.manager.routes import router as swarm_router
+
+if TYPE_CHECKING:
+    from provide.uterm.manager.config import ManagerConfig
+    from provide.uterm.manager.models import AgentStatusBase
+    from provide.uterm.manager.protocols import (
+        AccountPoolPlugin,
+        IdentityStorePlugin,
+        ManagedAgentPlugin,
+        StatusUpdatePlugin,
+        TimeseriesPlugin,
+        WorkerRegistryPlugin,
+    )
+
+logger = get_logger(__name__)
+
+
+def create_manager_app(
+    config: ManagerConfig,
+    *,
+    agent_status_class: type[AgentStatusBase] | None = None,
+    worker_registry: dict[str, WorkerRegistryPlugin] | None = None,
+    account_pool: AccountPoolPlugin | None = None,
+    identity_store: IdentityStorePlugin | None = None,
+    managed_agent: ManagedAgentPlugin | None = None,
+    status_update: StatusUpdatePlugin | None = None,
+    timeseries: TimeseriesPlugin | None = None,
+    swarm_status_builder: Any | None = None,
+    extra_routers: list[APIRouter] | None = None,
+) -> tuple[FastAPI, AgentManager]:
+    """Create a FastAPI application wired to a generic AgentManager.
+
+    Returns ``(app, manager)`` so the caller can further customise
+    either before starting the server.
+    """
+    manager = AgentManager(
+        config,
+        agent_status_class=agent_status_class,
+        account_pool=account_pool,
+        identity_store=identity_store,
+        status_update=status_update,
+        timeseries_plugin=timeseries,
+        swarm_status_builder=swarm_status_builder,
+    )
+
+    process_mgr = AgentProcessManager(
+        manager,
+        worker_registry=worker_registry,
+        log_dir=config.log_dir,
+    )
+    if config.spawn_policy_webhook_url:
+        from provide.uterm.manager.ext import WebhookAgentSpawnPolicyGate
+
+        process_mgr.set_policy_gate(
+            WebhookAgentSpawnPolicyGate(
+                url=config.spawn_policy_webhook_url,
+                secret=config.spawn_policy_webhook_secret,
+                timeout_s=config.spawn_policy_webhook_timeout_s,
+            )
+        )
+    manager.agent_process_manager = process_mgr
+
+    app = FastAPI(title=config.title)
+    manager.app = app
+
+    # Auth
+    setup_auth(app, env_var=config.auth_token_env_var, config=config)
+
+    # CORS — credentials are always allowed, so a wildcard or empty origin list
+    # would expose this process-kill/spawn API to credentialed cross-site
+    # requests. Refuse such a config at build time and require an explicit
+    # allowlist.
+    cors_env = os.environ.get("UTERM_CORS_ORIGINS", "").strip()
+    origins = [o.strip() for o in cors_env.split(",") if o.strip()] if cors_env else config.cors_origins
+    if not origins:
+        raise ValueError(
+            "CORS origin allowlist is empty; credentialed CORS requires an explicit list of origins "
+            "(set UTERM_CORS_ORIGINS or ManagerConfig.cors_origins)"
+        )
+    if "*" in origins:
+        raise ValueError(
+            "CORS wildcard origin '*' is not allowed when credentials are enabled; list explicit origins instead"
+        )
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=origins,
+        allow_credentials=True,
+        allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"],
+        allow_headers=["*"],
+    )
+
+    # Wire state
+    app.state.swarm_manager = manager
+    if managed_agent is not None:
+        app.state.managed_agent_plugin = managed_agent
+
+    # Include routes
+    app.include_router(swarm_router)
+    for extra in extra_routers or []:
+        app.include_router(extra)
+
+    # WebSocket endpoint for dashboard push updates
+    @app.websocket("/ws/swarm")
+    async def websocket_endpoint(websocket: WebSocket) -> None:
+        await websocket.accept()
+        async with manager._ws_lock:
+            manager.websocket_clients.add(websocket)
+        try:
+            while True:
+                await websocket.receive_text()
+        except WebSocketDisconnect:
+            async with manager._ws_lock:
+                manager.websocket_clients.discard(websocket)
+        except Exception as e:  # pragma: no cover — requires mid-stream WS failure
+            logger.exception("websocket_error", error=str(e))
+            async with manager._ws_lock:
+                manager.websocket_clients.discard(websocket)
+
+    # WebSocket endpoint for MCP client lifecycle tracking
+    @app.websocket("/ws/mcp-client")
+    async def mcp_client_endpoint(websocket: WebSocket) -> None:
+        await websocket.accept()
+        await manager.register_mcp_client(websocket)
+        try:
+            while True:
+                await websocket.receive_text()
+        except WebSocketDisconnect:
+            await manager.unregister_mcp_client(websocket)
+        except Exception as e:  # pragma: no cover - requires mid-stream WS failure
+            logger.exception("mcp_client_websocket_error", error=str(e))
+            await manager.unregister_mcp_client(websocket)
+
+    # Load persisted state
+    manager._load_state()
+
+    return app, manager