cyclo-manager 1.1.0.dev2__tar.gz → 1.1.0.dev4__tar.gz

{cyclo_manager-1.1.0.dev2 → cyclo_manager-1.1.0.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cyclo-manager
-Version: 1.1.0.dev2
+Version: 1.1.0.dev4
 Summary: cyclo_manager CLI: pip-installable launcher for cyclo_manager server and UI containers. Run 'cyclo_manager up' to start Docker stack.
 License-Expression: Apache-2.0
 Requires-Python: >=3.10
@@ -38,6 +38,7 @@ For the full monorepo (API source, UI source, dev compose), see the [repository
 - [What `cyclo_manager up` does](#what-cyclo_manager-up-does)
 - [Host agent (`cyclo_host_agent`)](#host-agent-cyclo_host_agent)
 - [Compose services](#compose-services)
+- [Recording storage](#recording-storage)
 - [Configuration](#configuration)
 - [Agent sockets on the host](#agent-sockets-on-the-host)
 - [Environment variables](#environment-variables)
@@ -134,6 +135,10 @@ The API container reaches it at `/agents/host/host_agent.sock` (see bundled `con
 - Update repos on allowed branches (`main`, `jazzy`) using stash or reset workflows.
 - Stop/start a repo's `docker/container.sh` helper during an update when requested by the UI.
 - Run Cyclo Manager package updates from the UI by delegating to `cyclo_manager update`.
+- Provide host CPU/memory/disk statistics and process information. CPU summaries
+  share a background sampler's average of the latest three one-second samples.
+- Serve the Files UI's browsing, filename search, upload, text editing, Git diff
+  and file/directory management operations under the configured workspace.
 
 `cyclo_manager up` installs the `refresh-host-agent` CLI subcommand into sudoers. It is registered as `sys.executable -m cyclo_manager_cli.cli refresh-host-agent` with `SETENV`, so UI-triggered updates can pass the current `PYTHONPATH` to sudo and do not depend on `PATH`. The command is idempotent and refreshes the socket directory, sudoers file, systemd unit, and service state after package upgrades.
 
@@ -145,10 +150,10 @@ Repository scanning and the Files UI use `CYCLO_HOST_AGENT_WORKSPACE` when set.
 
 Defined in [`cyclo_manager_cli/docker/docker-compose.yml`](cyclo_manager_cli/docker/docker-compose.yml). All services use **`network_mode: host`**.
 
-| Compose service | Container name | `cyclo_manager up` | Image (example) |
+| Compose service | Container name | `cyclo_manager up` | Image in this checkout |
 |-----------------|----------------|--------------------|-----------------|
-| `cyclo_manager` | `cyclo_manager` | **Started** | `robotis/cyclo-manager:1.0.0` |
-| `ui` | `cyclo_manager_ui` | **Started** | `robotis/cyclo-manager-ui:1.0.0` |
+| `cyclo_manager` | `cyclo_manager` | **Started** | `robotis/cyclo-manager:1.1.0` |
+| `ui` | `cyclo_manager_ui` | **Started** | `robotis/cyclo-manager-ui:1.1.0` |
 | `rmw_zenoh` | `zenoh_daemon` | **Created only** | `robotis/zenoh-daemon:latest` |
 | `novnc-server` | `novnc-server` | **Created only** | `robotis/novnc-server:latest` |
 
@@ -156,6 +161,27 @@ Start optional containers from the UI or manually, e.g. `docker start zenoh_daem
 
 ---
 
+## Recording storage
+
+The packaged stack and dev compose both mount:
+
+```yaml
+- ${HOME}/cyclo_manager_ros_bags:/cyclo_manager_ros_bags
+```
+
+Compose resolves `${HOME}` on the host at invocation time. The API container uses
+`RECORDINGS_DIR=/cyclo_manager_ros_bags`, which is also the server default when the
+variable is absent. The host directory is independent of
+`CYCLO_HOST_AGENT_WORKSPACE`; each recording stores its metadata and MCAP bag under
+its generated ID. Container recreation, `down` and package updates preserve this
+bind-mounted data. Applying a new mount requires container recreation.
+
+Recording and playback run in the API container using `rosbag2_py` and the MCAP
+storage plugin included in the manager image. They are not host-agent jobs.
+See [Record & Play](../docs/record-play.md) for capture, repeat playback and stops.
+
+---
+
 ## Configuration
 
 The CLI always mounts the **bundled** config into the API container. There is **no** `-c` / `--config` flag on the pip CLI.
@@ -168,10 +194,13 @@ The API reads it as `CONFIG_FILE=/app/config.yml` inside the container.
 
 | Key | Description |
 |-----|-------------|
-| **`supported_robot_containers`** | Robot Docker container names that can open the System page (e.g. `ai_worker`, `open_manipulator`). Each must be a key in `sockets` and cannot be `host_agent`. |
+| **`supported_robot_containers`** | Containers eligible for System navigation and server-side motion profile detection (e.g. `ai_worker`, `open_manipulator`). Each must be a key in `sockets` and cannot be `host_agent`. |
 | **`sockets`** | Map of logical name → agent **Unix socket path as seen inside the API container** (under `/agents/...`). Include robot/service containers and `host_agent`. |
 
-s6 **service names** are not listed in config; each in-container agent reports them at runtime.
+s6 **service names** are defined in the manager's System/motion profiles, not in
+this config. Motion detection checks the existing individual status endpoints for
+`ai_worker_bringup` and `open_manipulator_bringup`, then reads `/run/robot_type`
+inside the selected container through Docker. This needs no new s6-agent endpoint.
 
 ### Example (bundled default)
 
@@ -198,6 +227,7 @@ On the host, sockets typically live under:
 ```text
 /var/run/robotis/agent_sockets/
 ├── ai_worker/s6_agent.sock
+├── open_manipulator/s6_agent.sock
 ├── cyclo_intelligence/s6_agent.sock
 └── host/host_agent.sock          ← created by cyclo_manager up
 ```
@@ -220,7 +250,11 @@ So `/agents/ai_worker/s6_agent.sock` in config corresponds to the host path abov
 | **`CYCLO_HOST_AGENT_WORKSPACE`** | User or CLI-generated systemd unit | Workspace scanned by `cyclo_host_agent` for managed git repositories and used as the Files UI/API root |
 | **`HOSTNAME`** | CLI (default: machine hostname) | Passed to API as `HOST_HOSTNAME` |
 | **`CONFIG_FILE`** | Compose (`/app/config.yml`) | Path inside the API container |
-| **`ROS_DOMAIN_ID`** | **Not** set by CLI | Set inside robot containers (e.g. `~/.bashrc`) so DDS matches your fleet |
+| **`HOME`** | Host environment used by Compose | Selects the host `${HOME}/cyclo_manager_ros_bags` bind-mount directory |
+| **`RECORDINGS_DIR`** | Compose (`/cyclo_manager_ros_bags`) | Server-side recording directory inside the API container; same default without the variable |
+| **`ROS_DOMAIN_ID`** | Manager image shell startup (`30`); not set by CLI | Must match the robot; the manager image configures it in `/root/.bashrc`, which the API startup sources |
+| **`RMW_IMPLEMENTATION`** | Manager image shell startup (`rmw_zenoh_cpp`) | ROS middleware used by the manager; requires a reachable Zenoh router |
+| **`NEXT_PUBLIC_API_URL`** | UI dev/build environment | Browser API address; production bundles embed it at build time, so a compose runtime value does not reconfigure a prebuilt UI |
 
 ---
 
@@ -234,6 +268,12 @@ With `network_mode: host` and default ports:
 | cyclo_manager API | http://127.0.0.1:8081 |
 | OpenAPI (Swagger) | http://127.0.0.1:8081/docs |
 
+These loopback URLs apply on the robot host. From another device, use the robot's
+hostname/IP and a browser-reachable API URL. Both compose files contain a UI
+runtime value of `http://127.0.0.1:8081`; it takes effect in development, while a
+production bundle uses its build-time value or hostname fallback. See the
+[UI API address guide](../cyclo_manager_ui/README_UI.md#api-address).
+
 ---
 
 ## Custom config and development
@@ -247,6 +287,11 @@ For development (local API/UI source, custom `config.yml`, hot reload):
 docker compose -f docker-compose.dev.yml up
 ```
 
+The dev compose command starts all defined services and does not install the host
+agent. API/UI source mounts do not update the Python code used by the separately
+installed `cyclo_host_agent.service`; install the updated CLI package and refresh
+that service when testing host-agent changes.
+
 See the [root README](../README.md#development).
 
 ---
@@ -259,7 +304,7 @@ Python dependencies declared in [`pyproject.toml`](pyproject.toml):
 |---------|---------|
 | **fastapi** | `cyclo_host_agent` HTTP API |
 | **uvicorn** | `cyclo_host_agent` server |
-| **psutil** | Declared package dependency for host/system utility support |
+| **psutil** | Host CPU sampler, memory/disk statistics and process inspection |
 
 The **`cyclo_manager`** CLI itself uses only the Python standard library plus **`subprocess`** calls to **`docker compose`**, **`pip`**, **`systemctl`**, and **`sudo`**.
 

{cyclo_manager-1.1.0.dev2 → cyclo_manager-1.1.0.dev4}/README.md

@@ -24,6 +24,7 @@ For the full monorepo (API source, UI source, dev compose), see the [repository
 - [What `cyclo_manager up` does](#what-cyclo_manager-up-does)
 - [Host agent (`cyclo_host_agent`)](#host-agent-cyclo_host_agent)
 - [Compose services](#compose-services)
+- [Recording storage](#recording-storage)
 - [Configuration](#configuration)
 - [Agent sockets on the host](#agent-sockets-on-the-host)
 - [Environment variables](#environment-variables)
@@ -120,6 +121,10 @@ The API container reaches it at `/agents/host/host_agent.sock` (see bundled `con
 - Update repos on allowed branches (`main`, `jazzy`) using stash or reset workflows.
 - Stop/start a repo's `docker/container.sh` helper during an update when requested by the UI.
 - Run Cyclo Manager package updates from the UI by delegating to `cyclo_manager update`.
+- Provide host CPU/memory/disk statistics and process information. CPU summaries
+  share a background sampler's average of the latest three one-second samples.
+- Serve the Files UI's browsing, filename search, upload, text editing, Git diff
+  and file/directory management operations under the configured workspace.
 
 `cyclo_manager up` installs the `refresh-host-agent` CLI subcommand into sudoers. It is registered as `sys.executable -m cyclo_manager_cli.cli refresh-host-agent` with `SETENV`, so UI-triggered updates can pass the current `PYTHONPATH` to sudo and do not depend on `PATH`. The command is idempotent and refreshes the socket directory, sudoers file, systemd unit, and service state after package upgrades.
 
@@ -131,10 +136,10 @@ Repository scanning and the Files UI use `CYCLO_HOST_AGENT_WORKSPACE` when set.
 
 Defined in [`cyclo_manager_cli/docker/docker-compose.yml`](cyclo_manager_cli/docker/docker-compose.yml). All services use **`network_mode: host`**.
 
-| Compose service | Container name | `cyclo_manager up` | Image (example) |
+| Compose service | Container name | `cyclo_manager up` | Image in this checkout |
 |-----------------|----------------|--------------------|-----------------|
-| `cyclo_manager` | `cyclo_manager` | **Started** | `robotis/cyclo-manager:1.0.0` |
-| `ui` | `cyclo_manager_ui` | **Started** | `robotis/cyclo-manager-ui:1.0.0` |
+| `cyclo_manager` | `cyclo_manager` | **Started** | `robotis/cyclo-manager:1.1.0` |
+| `ui` | `cyclo_manager_ui` | **Started** | `robotis/cyclo-manager-ui:1.1.0` |
 | `rmw_zenoh` | `zenoh_daemon` | **Created only** | `robotis/zenoh-daemon:latest` |
 | `novnc-server` | `novnc-server` | **Created only** | `robotis/novnc-server:latest` |
 
@@ -142,6 +147,27 @@ Start optional containers from the UI or manually, e.g. `docker start zenoh_daem
 
 ---
 
+## Recording storage
+
+The packaged stack and dev compose both mount:
+
+```yaml
+- ${HOME}/cyclo_manager_ros_bags:/cyclo_manager_ros_bags
+```
+
+Compose resolves `${HOME}` on the host at invocation time. The API container uses
+`RECORDINGS_DIR=/cyclo_manager_ros_bags`, which is also the server default when the
+variable is absent. The host directory is independent of
+`CYCLO_HOST_AGENT_WORKSPACE`; each recording stores its metadata and MCAP bag under
+its generated ID. Container recreation, `down` and package updates preserve this
+bind-mounted data. Applying a new mount requires container recreation.
+
+Recording and playback run in the API container using `rosbag2_py` and the MCAP
+storage plugin included in the manager image. They are not host-agent jobs.
+See [Record & Play](../docs/record-play.md) for capture, repeat playback and stops.
+
+---
+
 ## Configuration
 
 The CLI always mounts the **bundled** config into the API container. There is **no** `-c` / `--config` flag on the pip CLI.
@@ -154,10 +180,13 @@ The API reads it as `CONFIG_FILE=/app/config.yml` inside the container.
 
 | Key | Description |
 |-----|-------------|
-| **`supported_robot_containers`** | Robot Docker container names that can open the System page (e.g. `ai_worker`, `open_manipulator`). Each must be a key in `sockets` and cannot be `host_agent`. |
+| **`supported_robot_containers`** | Containers eligible for System navigation and server-side motion profile detection (e.g. `ai_worker`, `open_manipulator`). Each must be a key in `sockets` and cannot be `host_agent`. |
 | **`sockets`** | Map of logical name → agent **Unix socket path as seen inside the API container** (under `/agents/...`). Include robot/service containers and `host_agent`. |
 
-s6 **service names** are not listed in config; each in-container agent reports them at runtime.
+s6 **service names** are defined in the manager's System/motion profiles, not in
+this config. Motion detection checks the existing individual status endpoints for
+`ai_worker_bringup` and `open_manipulator_bringup`, then reads `/run/robot_type`
+inside the selected container through Docker. This needs no new s6-agent endpoint.
 
 ### Example (bundled default)
 
@@ -184,6 +213,7 @@ On the host, sockets typically live under:
 ```text
 /var/run/robotis/agent_sockets/
 ├── ai_worker/s6_agent.sock
+├── open_manipulator/s6_agent.sock
 ├── cyclo_intelligence/s6_agent.sock
 └── host/host_agent.sock          ← created by cyclo_manager up
 ```
@@ -206,7 +236,11 @@ So `/agents/ai_worker/s6_agent.sock` in config corresponds to the host path abov
 | **`CYCLO_HOST_AGENT_WORKSPACE`** | User or CLI-generated systemd unit | Workspace scanned by `cyclo_host_agent` for managed git repositories and used as the Files UI/API root |
 | **`HOSTNAME`** | CLI (default: machine hostname) | Passed to API as `HOST_HOSTNAME` |
 | **`CONFIG_FILE`** | Compose (`/app/config.yml`) | Path inside the API container |
-| **`ROS_DOMAIN_ID`** | **Not** set by CLI | Set inside robot containers (e.g. `~/.bashrc`) so DDS matches your fleet |
+| **`HOME`** | Host environment used by Compose | Selects the host `${HOME}/cyclo_manager_ros_bags` bind-mount directory |
+| **`RECORDINGS_DIR`** | Compose (`/cyclo_manager_ros_bags`) | Server-side recording directory inside the API container; same default without the variable |
+| **`ROS_DOMAIN_ID`** | Manager image shell startup (`30`); not set by CLI | Must match the robot; the manager image configures it in `/root/.bashrc`, which the API startup sources |
+| **`RMW_IMPLEMENTATION`** | Manager image shell startup (`rmw_zenoh_cpp`) | ROS middleware used by the manager; requires a reachable Zenoh router |
+| **`NEXT_PUBLIC_API_URL`** | UI dev/build environment | Browser API address; production bundles embed it at build time, so a compose runtime value does not reconfigure a prebuilt UI |
 
 ---
 
@@ -220,6 +254,12 @@ With `network_mode: host` and default ports:
 | cyclo_manager API | http://127.0.0.1:8081 |
 | OpenAPI (Swagger) | http://127.0.0.1:8081/docs |
 
+These loopback URLs apply on the robot host. From another device, use the robot's
+hostname/IP and a browser-reachable API URL. Both compose files contain a UI
+runtime value of `http://127.0.0.1:8081`; it takes effect in development, while a
+production bundle uses its build-time value or hostname fallback. See the
+[UI API address guide](../cyclo_manager_ui/README_UI.md#api-address).
+
 ---
 
 ## Custom config and development
@@ -233,6 +273,11 @@ For development (local API/UI source, custom `config.yml`, hot reload):
 docker compose -f docker-compose.dev.yml up
 ```
 
+The dev compose command starts all defined services and does not install the host
+agent. API/UI source mounts do not update the Python code used by the separately
+installed `cyclo_host_agent.service`; install the updated CLI package and refresh
+that service when testing host-agent changes.
+
 See the [root README](../README.md#development).
 
 ---
@@ -245,7 +290,7 @@ Python dependencies declared in [`pyproject.toml`](pyproject.toml):
 |---------|---------|
 | **fastapi** | `cyclo_host_agent` HTTP API |
 | **uvicorn** | `cyclo_host_agent` server |
-| **psutil** | Declared package dependency for host/system utility support |
+| **psutil** | Host CPU sampler, memory/disk statistics and process inspection |
 
 The **`cyclo_manager`** CLI itself uses only the Python standard library plus **`subprocess`** calls to **`docker compose`**, **`pip`**, **`systemctl`**, and **`sudo`**.
 

cyclo_manager-1.1.0.dev4/cyclo_host_agent/cpu_usage.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+#
+# Copyright 2026 ROBOTIS CO., LTD.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# Author: Hyungyu Kim
+
+"""Continuous host CPU sampling, independent of HTTP requests."""
+
+from collections import deque
+import logging
+import threading
+
+import psutil
+
+logger = logging.getLogger(__name__)
+
+CPU_SAMPLE_INTERVAL_SECONDS = 1.0
+CPU_AVERAGE_SAMPLES = 3
+
+
+class CpuUsageSampler:
+    """Keep the mean of the latest three consecutive one-second CPU samples."""
+
+    def __init__(self, interval: float = CPU_SAMPLE_INTERVAL_SECONDS) -> None:
+        """Initialize the sampler without starting a background thread."""
+        self._interval = interval
+        self._samples: deque[float] = deque(maxlen=CPU_AVERAGE_SAMPLES)
+        self._lock = threading.Lock()
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+
+    def start(self) -> None:
+        """Start one sampling thread and discard samples from any previous run."""
+        if self._thread is not None and self._thread.is_alive():
+            return
+        with self._lock:
+            self._samples.clear()
+        self._stop.clear()
+        self._thread = threading.Thread(
+            target=self._run, name='host-cpu-sampler', daemon=True,
+        )
+        self._thread.start()
+
+    def stop(self) -> None:
+        """Wake and join the sampler on application shutdown."""
+        self._stop.set()
+        if self._thread is not None:
+            self._thread.join()
+            self._thread = None
+
+    def average(self) -> float | None:
+        """Return a cached average, or None before the first complete interval."""
+        with self._lock:
+            if not self._samples:
+                return None
+            return round(sum(self._samples) / len(self._samples), 1)
+
+    def _run(self) -> None:
+        while not self._stop.is_set():
+            try:
+                # Prime and read on the same thread. The initial value is not a sample.
+                psutil.cpu_percent(interval=None)
+                while not self._stop.wait(self._interval):
+                    sample = psutil.cpu_percent(interval=None)
+                    with self._lock:
+                        self._samples.append(float(sample))
+            except Exception:
+                # Re-prime after a failure instead of mixing stale measurement intervals.
+                with self._lock:
+                    self._samples.clear()
+                logger.exception('Failed to sample host CPU usage')
+                self._stop.wait(self._interval)

{cyclo_manager-1.1.0.dev2 → cyclo_manager-1.1.0.dev4}/cyclo_host_agent/main.py

@@ -18,6 +18,8 @@
 
 """Cyclo host agent: FastAPI server on Unix Domain Socket for host-level operations."""
 
+import asyncio
+from contextlib import asynccontextmanager
 import logging
 from pathlib import Path
 
@@ -34,10 +36,22 @@ logger = logging.getLogger(__name__)
 
 SOCKET_PATH = '/var/run/robotis/agent_sockets/host/host_agent.sock'
 
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Run the shared CPU sampler for the lifetime of the host agent."""
+    system_stats.cpu_sampler.start()
+    try:
+        yield
+    finally:
+        await asyncio.to_thread(system_stats.cpu_sampler.stop)
+
+
 app = FastAPI(
     title='cyclo_host_agent',
     description='Host agent for Cyclo Manager: repo management.',
     version=__version__,
+    lifespan=lifespan,
 )
 
 app.include_router(repos.router)

{cyclo_manager-1.1.0.dev2 → cyclo_manager-1.1.0.dev4}/cyclo_host_agent/routers/files.py

@@ -18,6 +18,7 @@
 
 """Host file browser and editor endpoints."""
 
+import asyncio
 import os
 import shutil
 import subprocess
@@ -71,6 +72,21 @@ def _safe_path(relative_path: str = '') -> tuple[Path, str]:
     return target, rel
 
 
+def _safe_nofollow_path(relative_path: str = '') -> tuple[Path, str]:
+    raw_path = Path(relative_path)
+    if raw_path.is_absolute() or '..' in raw_path.parts:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail='Path escapes file root')
+
+    lexical_target = FILE_ROOT_PATH / raw_path
+    parent = lexical_target.parent.resolve()
+    if parent != FILE_ROOT_PATH and FILE_ROOT_PATH not in parent.parents:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail='Path escapes file root')
+
+    target = parent / lexical_target.name
+    rel = '' if target == FILE_ROOT_PATH else target.relative_to(FILE_ROOT_PATH).as_posix()
+    return target, rel
+
+
 def _safe_filename(filename: str) -> str:
     name = Path(filename).name
     if name in {'', '.', '..'} or name != filename or '/' in filename or '\\' in filename:
@@ -80,7 +96,8 @@ def _safe_filename(filename: str) -> str:
 
 def _is_binary(path: Path) -> bool:
     try:
-        return b'\x00' in path.read_bytes()[:8192]
+        with path.open('rb') as file:
+            return b'\x00' in file.read(8192)
     except OSError:
         return True
 
@@ -262,7 +279,7 @@ def _git_head_content(repo_root: Path, repo_path: str) -> str:
 
 
 @router.get('/tree', response_model=FileTreeResponse)
-async def list_directory(
+def list_directory(
     path: str = '',
     show_hidden: bool = Query(False),
 ) -> FileTreeResponse:
@@ -286,7 +303,7 @@ async def list_directory(
 
 
 @router.get('/search', response_model=FileSearchResponse)
-async def search_files(
+def search_files(
     query: str,
     path: str = '',
     show_hidden: bool = Query(False),
@@ -340,7 +357,7 @@ async def search_files(
 
 
 @router.get('/read', response_model=FileReadResponse)
-async def read_file(
+def read_file(
     path: str,
 ) -> FileReadResponse:
     """Read a UTF-8 text file under the configured file root."""
@@ -366,7 +383,7 @@ async def read_file(
 
 
 @router.get('/diff', response_model=FileDiffResponse)
-async def diff_file(
+def diff_file(
     path: str,
 ) -> FileDiffResponse:
     """Return original and current file content for a git diff view."""
@@ -397,7 +414,7 @@ async def diff_file(
 
 
 @router.post('/write', response_model=FileOperationResponse)
-async def write_file(req: FileWriteRequest) -> FileOperationResponse:
+def write_file(req: FileWriteRequest) -> FileOperationResponse:
     """Write a UTF-8 text file under the configured file root."""
     target, rel = _safe_path(req.path)
     if target.exists() and not target.is_file():
@@ -417,10 +434,10 @@ async def write_file(req: FileWriteRequest) -> FileOperationResponse:
 
 
 @router.post('/create', response_model=FileOperationResponse)
-async def create_path(req: FileCreateRequest) -> FileOperationResponse:
+def create_path(req: FileCreateRequest) -> FileOperationResponse:
     """Create a file or folder under the configured file root."""
-    target, rel = _safe_path(req.path)
-    if target.exists():
+    target, rel = _safe_nofollow_path(req.path)
+    if target.exists() or target.is_symlink():
         raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail='Path already exists')
     try:
         if req.type == 'directory':
@@ -440,17 +457,17 @@ async def create_path(req: FileCreateRequest) -> FileOperationResponse:
 
 
 @router.post('/rename', response_model=FileOperationResponse)
-async def rename_path(req: FileRenameRequest) -> FileOperationResponse:
+def rename_path(req: FileRenameRequest) -> FileOperationResponse:
     """Rename a file or folder under the configured file root."""
-    target, _ = _safe_path(req.path)
-    if not target.exists():
+    target, _ = _safe_nofollow_path(req.path)
+    if not target.exists() and not target.is_symlink():
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail='Path not found')
     if '/' in req.new_name or '\\' in req.new_name or req.new_name in {'', '.', '..'}:
         raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail='Invalid name')
-    destination = (target.parent / req.new_name).resolve()
+    destination = target.parent / req.new_name
     if destination != FILE_ROOT_PATH and FILE_ROOT_PATH not in destination.parents:
         raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail='Path escapes file root')
-    if destination.exists():
+    if destination.exists() or destination.is_symlink():
         raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail='Destination already exists')
     try:
         target.rename(destination)
@@ -473,34 +490,37 @@ async def upload_file(
         raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail='Path is not a directory')
 
     safe_name = _safe_filename(filename)
-    destination = (target_dir / safe_name).resolve()
+    destination = target_dir / safe_name
     if destination != FILE_ROOT_PATH and FILE_ROOT_PATH not in destination.parents:
         raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail='Path escapes file root')
     if destination.exists() and destination.is_dir():
         raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail='A folder with that name already exists')
-    overwritten = destination.exists()
+    overwritten = destination.exists() or destination.is_symlink()
     if overwritten and not overwrite:
         raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail='File already exists')
 
     temp_path = target_dir / f'.{safe_name}.{uuid.uuid4().hex}.uploading'
     size_bytes = 0
     try:
-        with temp_path.open('wb') as output:
+        output = await asyncio.to_thread(temp_path.open, 'wb')
+        try:
             async for chunk in request.stream():
                 size_bytes += len(chunk)
                 if size_bytes > MAX_UPLOAD_BYTES:
                     raise HTTPException(status_code=status.HTTP_413_REQUEST_ENTITY_TOO_LARGE, detail='File is too large to upload')
-                output.write(chunk)
-        os.replace(temp_path, destination)
+                await asyncio.to_thread(output.write, chunk)
+        finally:
+            await asyncio.to_thread(output.close)
+        await asyncio.to_thread(os.replace, temp_path, destination)
     except HTTPException:
         try:
-            temp_path.unlink(missing_ok=True)
+            await asyncio.to_thread(temp_path.unlink, missing_ok=True)
         except OSError:
             pass
         raise
     except OSError as exc:
         try:
-            temp_path.unlink(missing_ok=True)
+            await asyncio.to_thread(temp_path.unlink, missing_ok=True)
         except OSError:
             pass
         raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=str(exc))
@@ -517,18 +537,20 @@ async def upload_file(
 
 
 @router.delete('', response_model=FileOperationResponse)
-async def delete_path(
+def delete_path(
     path: str,
     recursive: bool = Query(False),
 ) -> FileOperationResponse:
     """Delete a file or folder under the configured file root."""
-    target, rel = _safe_path(path)
+    target, rel = _safe_nofollow_path(path)
     if target == FILE_ROOT_PATH:
         raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail='Cannot delete file root')
-    if not target.exists():
+    if not target.exists() and not target.is_symlink():
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail='Path not found')
     try:
-        if target.is_dir():
+        if target.is_symlink():
+            target.unlink()
+        elif target.is_dir():
             if recursive:
                 shutil.rmtree(target)
             else:

{cyclo_manager-1.1.0.dev2 → cyclo_manager-1.1.0.dev4}/cyclo_host_agent/routers/repos.py

@@ -343,6 +343,7 @@ async def _update_reset(repo_path: Path, preserve_files: list[str]) -> UpdateRes
 # ── container helper ───────────────────────────────────────────────────────────
 
 _container_start_status_by_repo: dict[str, dict] = {}
+_container_start_tasks: set[asyncio.Task[None]] = set()
 
 
 def _prune_container_start_jobs() -> None:
@@ -424,6 +425,20 @@ async def _read_container_job_stream(stream: asyncio.StreamReader, job: dict) ->
             _update_container_job_from_line(job, line)
 
 
+async def _stop_container_start_process(
+    proc: asyncio.subprocess.Process | None,
+    readers: list[asyncio.Task],
+) -> None:
+    """Stop a container-start subprocess and consume its reader tasks."""
+    if proc is not None and proc.returncode is None:
+        try:
+            proc.kill()
+        except ProcessLookupError:
+            pass
+        await proc.wait()
+    await asyncio.gather(*readers, return_exceptions=True)
+
+
 async def _run_container_sh(repo_path: Path, action: str) -> tuple[bool, str]:
     script = repo_path / 'docker' / 'container.sh'
     if not script.exists():
@@ -448,52 +463,58 @@ async def _run_container_start(repo_path: Path, name: str) -> None:
     job = _container_start_status_by_repo.get(name)
     if job is None:
         return
-    script = repo_path / 'docker' / 'container.sh'
-    if not script.exists():
-        _set_container_job_status(
-            job,
-            running=False,
-            success=False,
-            error=f'container.sh not found at {script}',
-        )
-        return
-
-    env = os.environ.copy()
-    env['COMPOSE_PROGRESS'] = 'plain'
-    env['COMPOSE_ANSI'] = 'never'
-    proc = await asyncio.create_subprocess_exec(
-        'bash', str(script), 'start',
-        cwd=str(repo_path / 'docker'),
-        env=env,
-        stdin=asyncio.subprocess.PIPE,
-        stdout=asyncio.subprocess.PIPE,
-        stderr=asyncio.subprocess.PIPE,
-    )
-    if proc.stdin is not None:
-        proc.stdin.write(b'y\n')
-        await proc.stdin.drain()
-        proc.stdin.close()
-
-    readers = [
-        asyncio.create_task(_read_container_job_stream(proc.stdout, job)),
-        asyncio.create_task(_read_container_job_stream(proc.stderr, job)),
-    ]
+    proc: asyncio.subprocess.Process | None = None
+    readers: list[asyncio.Task] = []
     try:
+        script = repo_path / 'docker' / 'container.sh'
+        if not script.exists():
+            raise FileNotFoundError(f'container.sh not found at {script}')
+
+        env = os.environ.copy()
+        env['COMPOSE_PROGRESS'] = 'plain'
+        env['COMPOSE_ANSI'] = 'never'
+        proc = await asyncio.create_subprocess_exec(
+            'bash', str(script), 'start',
+            cwd=str(repo_path / 'docker'),
+            env=env,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        if proc.stdin is not None:
+            proc.stdin.write(b'y\n')
+            await proc.stdin.drain()
+            proc.stdin.close()
+
+        readers = [
+            asyncio.create_task(_read_container_job_stream(proc.stdout, job)),
+            asyncio.create_task(_read_container_job_stream(proc.stderr, job)),
+        ]
         await asyncio.wait_for(proc.wait(), timeout=CONTAINER_SCRIPT_TIMEOUT)
         await asyncio.gather(*readers)
     except asyncio.TimeoutError:
-        proc.kill()
-        await proc.wait()
-        await asyncio.gather(*readers, return_exceptions=True)
-        _append_container_job_output(job, 'Timeout waiting for container.sh')
+        error = 'Timeout waiting for container.sh'
+        await _stop_container_start_process(proc, readers)
+        _append_container_job_output(job, error)
+        _set_container_job_status(job, running=False, success=False, error=error)
+        return
+    except asyncio.CancelledError:
+        await _stop_container_start_process(proc, readers)
         _set_container_job_status(
             job,
             running=False,
             success=False,
-            error='Timeout waiting for container.sh',
+            error='Container start operation was cancelled',
         )
+        raise
+    except Exception as exc:
+        await _stop_container_start_process(proc, readers)
+        error = str(exc) or type(exc).__name__
+        _append_container_job_output(job, error)
+        _set_container_job_status(job, running=False, success=False, error=error)
         return
 
+    assert proc is not None
     if proc.returncode == 0:
         _set_container_job_status(
             job,
@@ -569,7 +590,9 @@ async def start_repo_container(name: str) -> ContainerStartStatusResponse:
         return _build_container_start_status_response(existing)
 
     job = _new_container_start_status(name)
-    asyncio.create_task(_run_container_start(repo_path, name))
+    task = asyncio.create_task(_run_container_start(repo_path, name))
+    _container_start_tasks.add(task)
+    task.add_done_callback(_container_start_tasks.discard)
     return _build_container_start_status_response(job)
 
 

{cyclo_manager-1.1.0.dev2 → cyclo_manager-1.1.0.dev4}/cyclo_host_agent/routers/system_stats.py

@@ -21,21 +21,30 @@
 import time
 from pathlib import Path
 
+from cyclo_host_agent.cpu_usage import CpuUsageSampler
 from cyclo_host_agent.models import (
     HostProcessesResponse,
     HostProcessInfo,
     HostSystemStatsResponse,
 )
-from fastapi import APIRouter, Query
+from fastapi import APIRouter, HTTPException, Query
 import psutil
 
 router = APIRouter(prefix='/system', tags=['system'])
+cpu_sampler = CpuUsageSampler()
 
 PROCESS_SAMPLE_INTERVAL_SECONDS = 0.2
 PROCESS_DEFAULT_LIMIT = 80
 EXTRA_STORAGE_MOUNT_PATHS = ('/mnt/ssd', '/data')
 
 
+def _cpu_average() -> float:
+    value = cpu_sampler.average()
+    if value is None:
+        raise HTTPException(status_code=503, detail='CPU measurement is warming up')
+    return value
+
+
 def _temperature() -> float | None:
     try:
         sensors = psutil.sensors_temperatures()
@@ -84,7 +93,8 @@ def _sample_processes(limit: int = PROCESS_DEFAULT_LIMIT) -> HostProcessesRespon
         except (psutil.NoSuchProcess, psutil.AccessDenied):
             continue
 
-    overall_cpu_percent = psutil.cpu_percent(interval=PROCESS_SAMPLE_INTERVAL_SECONDS)
+    # Process usage keeps its short measurement window; total CPU uses the shared average.
+    time.sleep(PROCESS_SAMPLE_INTERVAL_SECONDS)
     mem = psutil.virtual_memory()
 
     processes: list[HostProcessInfo] = []
@@ -111,7 +121,7 @@ def _sample_processes(limit: int = PROCESS_DEFAULT_LIMIT) -> HostProcessesRespon
 
     processes.sort(key=lambda item: item.cpu_percent, reverse=True)
     return HostProcessesResponse(
-        cpu_percent=round(float(overall_cpu_percent), 1),
+        cpu_percent=_cpu_average(),
         memory_used_mb=int(mem.used // (1024 * 1024)),
         memory_total_mb=int(mem.total // (1024 * 1024)),
         processes=processes[:max(1, min(limit, 500))],
@@ -119,9 +129,9 @@ def _sample_processes(limit: int = PROCESS_DEFAULT_LIMIT) -> HostProcessesRespon
 
 
 @router.get('/status', response_model=HostSystemStatsResponse)
-async def get_system_stats() -> HostSystemStatsResponse:
-    """Return host CPU, memory, disk, and uptime stats."""
-    cpu_percent = psutil.cpu_percent(interval=PROCESS_SAMPLE_INTERVAL_SECONDS)
+def get_system_stats() -> HostSystemStatsResponse:
+    """Return host stats with CPU averaged over the latest three one-second samples."""
+    cpu_percent = _cpu_average()
     mem = psutil.virtual_memory()
     disk = psutil.disk_usage('/')
     extra_storage_path, extra_storage_disk = _extra_storage_disk_usage()
@@ -149,7 +159,7 @@ async def get_system_stats() -> HostSystemStatsResponse:
 
 
 @router.get('/processes', response_model=HostProcessesResponse)
-async def get_system_processes(
+def get_system_processes(
     limit: int = Query(PROCESS_DEFAULT_LIMIT, ge=1, le=500),
 ) -> HostProcessesResponse:
     """Return host process CPU/memory usage sorted by CPU usage."""

{cyclo_manager-1.1.0.dev2 → cyclo_manager-1.1.0.dev4}/cyclo_manager.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cyclo-manager
-Version: 1.1.0.dev2
+Version: 1.1.0.dev4
 Summary: cyclo_manager CLI: pip-installable launcher for cyclo_manager server and UI containers. Run 'cyclo_manager up' to start Docker stack.
 License-Expression: Apache-2.0
 Requires-Python: >=3.10
@@ -38,6 +38,7 @@ For the full monorepo (API source, UI source, dev compose), see the [repository
 - [What `cyclo_manager up` does](#what-cyclo_manager-up-does)
 - [Host agent (`cyclo_host_agent`)](#host-agent-cyclo_host_agent)
 - [Compose services](#compose-services)
+- [Recording storage](#recording-storage)
 - [Configuration](#configuration)
 - [Agent sockets on the host](#agent-sockets-on-the-host)
 - [Environment variables](#environment-variables)
@@ -134,6 +135,10 @@ The API container reaches it at `/agents/host/host_agent.sock` (see bundled `con
 - Update repos on allowed branches (`main`, `jazzy`) using stash or reset workflows.
 - Stop/start a repo's `docker/container.sh` helper during an update when requested by the UI.
 - Run Cyclo Manager package updates from the UI by delegating to `cyclo_manager update`.
+- Provide host CPU/memory/disk statistics and process information. CPU summaries
+  share a background sampler's average of the latest three one-second samples.
+- Serve the Files UI's browsing, filename search, upload, text editing, Git diff
+  and file/directory management operations under the configured workspace.
 
 `cyclo_manager up` installs the `refresh-host-agent` CLI subcommand into sudoers. It is registered as `sys.executable -m cyclo_manager_cli.cli refresh-host-agent` with `SETENV`, so UI-triggered updates can pass the current `PYTHONPATH` to sudo and do not depend on `PATH`. The command is idempotent and refreshes the socket directory, sudoers file, systemd unit, and service state after package upgrades.
 
@@ -145,10 +150,10 @@ Repository scanning and the Files UI use `CYCLO_HOST_AGENT_WORKSPACE` when set.
 
 Defined in [`cyclo_manager_cli/docker/docker-compose.yml`](cyclo_manager_cli/docker/docker-compose.yml). All services use **`network_mode: host`**.
 
-| Compose service | Container name | `cyclo_manager up` | Image (example) |
+| Compose service | Container name | `cyclo_manager up` | Image in this checkout |
 |-----------------|----------------|--------------------|-----------------|
-| `cyclo_manager` | `cyclo_manager` | **Started** | `robotis/cyclo-manager:1.0.0` |
-| `ui` | `cyclo_manager_ui` | **Started** | `robotis/cyclo-manager-ui:1.0.0` |
+| `cyclo_manager` | `cyclo_manager` | **Started** | `robotis/cyclo-manager:1.1.0` |
+| `ui` | `cyclo_manager_ui` | **Started** | `robotis/cyclo-manager-ui:1.1.0` |
 | `rmw_zenoh` | `zenoh_daemon` | **Created only** | `robotis/zenoh-daemon:latest` |
 | `novnc-server` | `novnc-server` | **Created only** | `robotis/novnc-server:latest` |
 
@@ -156,6 +161,27 @@ Start optional containers from the UI or manually, e.g. `docker start zenoh_daem
 
 ---
 
+## Recording storage
+
+The packaged stack and dev compose both mount:
+
+```yaml
+- ${HOME}/cyclo_manager_ros_bags:/cyclo_manager_ros_bags
+```
+
+Compose resolves `${HOME}` on the host at invocation time. The API container uses
+`RECORDINGS_DIR=/cyclo_manager_ros_bags`, which is also the server default when the
+variable is absent. The host directory is independent of
+`CYCLO_HOST_AGENT_WORKSPACE`; each recording stores its metadata and MCAP bag under
+its generated ID. Container recreation, `down` and package updates preserve this
+bind-mounted data. Applying a new mount requires container recreation.
+
+Recording and playback run in the API container using `rosbag2_py` and the MCAP
+storage plugin included in the manager image. They are not host-agent jobs.
+See [Record & Play](../docs/record-play.md) for capture, repeat playback and stops.
+
+---
+
 ## Configuration
 
 The CLI always mounts the **bundled** config into the API container. There is **no** `-c` / `--config` flag on the pip CLI.
@@ -168,10 +194,13 @@ The API reads it as `CONFIG_FILE=/app/config.yml` inside the container.
 
 | Key | Description |
 |-----|-------------|
-| **`supported_robot_containers`** | Robot Docker container names that can open the System page (e.g. `ai_worker`, `open_manipulator`). Each must be a key in `sockets` and cannot be `host_agent`. |
+| **`supported_robot_containers`** | Containers eligible for System navigation and server-side motion profile detection (e.g. `ai_worker`, `open_manipulator`). Each must be a key in `sockets` and cannot be `host_agent`. |
 | **`sockets`** | Map of logical name → agent **Unix socket path as seen inside the API container** (under `/agents/...`). Include robot/service containers and `host_agent`. |
 
-s6 **service names** are not listed in config; each in-container agent reports them at runtime.
+s6 **service names** are defined in the manager's System/motion profiles, not in
+this config. Motion detection checks the existing individual status endpoints for
+`ai_worker_bringup` and `open_manipulator_bringup`, then reads `/run/robot_type`
+inside the selected container through Docker. This needs no new s6-agent endpoint.
 
 ### Example (bundled default)
 
@@ -198,6 +227,7 @@ On the host, sockets typically live under:
 ```text
 /var/run/robotis/agent_sockets/
 ├── ai_worker/s6_agent.sock
+├── open_manipulator/s6_agent.sock
 ├── cyclo_intelligence/s6_agent.sock
 └── host/host_agent.sock          ← created by cyclo_manager up
 ```
@@ -220,7 +250,11 @@ So `/agents/ai_worker/s6_agent.sock` in config corresponds to the host path abov
 | **`CYCLO_HOST_AGENT_WORKSPACE`** | User or CLI-generated systemd unit | Workspace scanned by `cyclo_host_agent` for managed git repositories and used as the Files UI/API root |
 | **`HOSTNAME`** | CLI (default: machine hostname) | Passed to API as `HOST_HOSTNAME` |
 | **`CONFIG_FILE`** | Compose (`/app/config.yml`) | Path inside the API container |
-| **`ROS_DOMAIN_ID`** | **Not** set by CLI | Set inside robot containers (e.g. `~/.bashrc`) so DDS matches your fleet |
+| **`HOME`** | Host environment used by Compose | Selects the host `${HOME}/cyclo_manager_ros_bags` bind-mount directory |
+| **`RECORDINGS_DIR`** | Compose (`/cyclo_manager_ros_bags`) | Server-side recording directory inside the API container; same default without the variable |
+| **`ROS_DOMAIN_ID`** | Manager image shell startup (`30`); not set by CLI | Must match the robot; the manager image configures it in `/root/.bashrc`, which the API startup sources |
+| **`RMW_IMPLEMENTATION`** | Manager image shell startup (`rmw_zenoh_cpp`) | ROS middleware used by the manager; requires a reachable Zenoh router |
+| **`NEXT_PUBLIC_API_URL`** | UI dev/build environment | Browser API address; production bundles embed it at build time, so a compose runtime value does not reconfigure a prebuilt UI |
 
 ---
 
@@ -234,6 +268,12 @@ With `network_mode: host` and default ports:
 | cyclo_manager API | http://127.0.0.1:8081 |
 | OpenAPI (Swagger) | http://127.0.0.1:8081/docs |
 
+These loopback URLs apply on the robot host. From another device, use the robot's
+hostname/IP and a browser-reachable API URL. Both compose files contain a UI
+runtime value of `http://127.0.0.1:8081`; it takes effect in development, while a
+production bundle uses its build-time value or hostname fallback. See the
+[UI API address guide](../cyclo_manager_ui/README_UI.md#api-address).
+
 ---
 
 ## Custom config and development
@@ -247,6 +287,11 @@ For development (local API/UI source, custom `config.yml`, hot reload):
 docker compose -f docker-compose.dev.yml up
 ```
 
+The dev compose command starts all defined services and does not install the host
+agent. API/UI source mounts do not update the Python code used by the separately
+installed `cyclo_host_agent.service`; install the updated CLI package and refresh
+that service when testing host-agent changes.
+
 See the [root README](../README.md#development).
 
 ---
@@ -259,7 +304,7 @@ Python dependencies declared in [`pyproject.toml`](pyproject.toml):
 |---------|---------|
 | **fastapi** | `cyclo_host_agent` HTTP API |
 | **uvicorn** | `cyclo_host_agent` server |
-| **psutil** | Declared package dependency for host/system utility support |
+| **psutil** | Host CPU sampler, memory/disk statistics and process inspection |
 
 The **`cyclo_manager`** CLI itself uses only the Python standard library plus **`subprocess`** calls to **`docker compose`**, **`pip`**, **`systemctl`**, and **`sudo`**.
 

{cyclo_manager-1.1.0.dev2 → cyclo_manager-1.1.0.dev4}/cyclo_manager.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ README.md
 pyproject.toml
 setup.cfg
 cyclo_host_agent/__init__.py
+cyclo_host_agent/cpu_usage.py
 cyclo_host_agent/main.py
 cyclo_host_agent/models.py
 cyclo_host_agent/routers/__init__.py
@@ -18,4 +19,5 @@ cyclo_manager.egg-info/top_level.txt
 cyclo_manager_cli/__init__.py
 cyclo_manager_cli/cli.py
 cyclo_manager_cli/config/config.yml
-cyclo_manager_cli/docker/docker-compose.yml
+cyclo_manager_cli/docker/docker-compose.yml
+tests/test_cpu_usage.py

{cyclo_manager-1.1.0.dev2 → cyclo_manager-1.1.0.dev4}/cyclo_manager_cli/__init__.py

@@ -18,4 +18,4 @@
 
 """cyclo_manager CLI - pip-installable launcher for cyclo_manager server and UI containers."""
 
-__version__ = '1.0.0'
+__version__ = '1.1.0'

{cyclo_manager-1.1.0.dev2 → cyclo_manager-1.1.0.dev4}/cyclo_manager_cli/docker/docker-compose.yml

@@ -21,8 +21,10 @@ services:
       - ${CYCLO_MANAGER_CONFIG_FILE}:/app/config.yml # For hot-reload on config changes
       - /var/run/docker.sock:/var/run/docker.sock # For Docker API access
       - /:/host_root:ro # For host disk usage and OS info
+      - ${HOME}/cyclo_manager_ros_bags:/cyclo_manager_ros_bags
     environment:
       - CONFIG_FILE=/app/config.yml
+      - RECORDINGS_DIR=/cyclo_manager_ros_bags
       - HOST_HOSTNAME=${HOSTNAME}
 
   ui:

{cyclo_manager-1.1.0.dev2 → cyclo_manager-1.1.0.dev4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cyclo-manager"
-version = "1.1.0.dev2"
+version = "1.1.0.dev4"
 description = "cyclo_manager CLI: pip-installable launcher for cyclo_manager server and UI containers. Run 'cyclo_manager up' to start Docker stack."
 readme = "README.md"
 license = "Apache-2.0"

cyclo_manager-1.1.0.dev4/tests/test_cpu_usage.py

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+#
+# Copyright 2026 ROBOTIS CO., LTD.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# Author: Hyungyu Kim
+
+"""Regression tests for continuous CPU sampling and shared API summaries."""
+
+from types import SimpleNamespace
+import threading
+import time
+import unittest
+from unittest.mock import Mock, call, patch
+
+from cyclo_host_agent.cpu_usage import CpuUsageSampler
+from cyclo_host_agent.main import app, lifespan
+from cyclo_host_agent.routers import system_stats
+from fastapi import HTTPException
+
+
+class CpuUsageTests(unittest.TestCase):
+    """Check measurement windows, startup behavior, and sampling ownership."""
+
+    def test_rolling_window_discards_prime_and_oldest_sample(self):
+        """Average available samples at startup and only the last three afterward."""
+        sampler = CpuUsageSampler()
+        observed = []
+
+        def next_interval(interval):
+            self.assertEqual(interval, 1.0)
+            observed.append(sampler.average())
+            if len(observed) == 5:
+                sampler._stop.set()
+                return True
+            return False
+
+        with patch('cyclo_host_agent.cpu_usage.psutil.cpu_percent',
+                   side_effect=[99.0, 10.0, 20.0, 60.0, 90.0]) as cpu:
+            with patch.object(sampler._stop, 'wait', side_effect=next_interval):
+                sampler._run()
+        self.assertEqual(observed, [None, 10.0, 15.0, 30.0, 56.7])
+        self.assertEqual(cpu.call_args_list, [call(interval=None)] * 5)
+
+    def test_background_sampling_is_independent_of_readers(self):
+        """Prime and sample on one thread, even without API requests."""
+        sampler = CpuUsageSampler(interval=0.01)
+        thread_ids = []
+
+        def cpu_percent(interval):
+            thread_ids.append(threading.get_ident())
+            return 30.0
+
+        with patch('cyclo_host_agent.cpu_usage.psutil.cpu_percent',
+                   side_effect=cpu_percent):
+            sampler.start()
+            worker = sampler._thread
+            try:
+                sampler.start()
+                self.assertIs(sampler._thread, worker)
+                deadline = time.monotonic() + 2
+                while sampler.average() is None and time.monotonic() < deadline:
+                    time.sleep(0.005)
+                self.assertEqual(sampler.average(), 30.0)
+            finally:
+                sampler.stop()
+            self.assertFalse(worker.is_alive())
+            count = len(thread_ids)
+            for _ in range(50):
+                self.assertEqual(sampler.average(), 30.0)
+            self.assertEqual(len(thread_ids), count)
+            self.assertGreaterEqual(count, 2)
+            self.assertEqual(len(set(thread_ids)), 1)
+            self.assertNotEqual(thread_ids[0], threading.get_ident())
+            sampler._interval = 1.0
+            sampler.start()
+            try:
+                self.assertIsNone(sampler.average())
+            finally:
+                sampler.stop()
+
+    def test_warmup_does_not_report_a_fake_zero(self):
+        """Return a retryable response before a complete sample exists."""
+        with patch.object(system_stats, 'cpu_sampler', CpuUsageSampler()):
+            with self.assertRaises(HTTPException) as result:
+                system_stats.get_system_stats()
+        self.assertEqual(result.exception.status_code, 503)
+
+    def test_sampling_failure_clears_history_and_primes_again(self):
+        """Do not keep old CPU values when a measurement fails."""
+        sampler = CpuUsageSampler()
+        observed = []
+
+        def next_interval(interval):
+            observed.append(sampler.average())
+            if len(observed) == 5:
+                sampler._stop.set()
+                return True
+            return False
+
+        with patch('cyclo_host_agent.cpu_usage.psutil.cpu_percent',
+                   side_effect=[99.0, 10.0, OSError('CPU read failed'), 99.0, 60.0]), \
+                patch('cyclo_host_agent.cpu_usage.logger.exception') as log, \
+                patch.object(sampler._stop, 'wait', side_effect=next_interval):
+            sampler._run()
+        self.assertEqual(observed, [None, 10.0, None, None, 60.0])
+        log.assert_called_once()
+
+    def test_status_and_process_summary_read_the_same_average(self):
+        """Total CPU is shared while process rows retain their own measurements."""
+        process = Mock()
+        process.as_dict.return_value = {
+            'pid': 42, 'username': 'robot', 'cpu_percent': 80.0,
+            'memory_percent': 1.0, 'memory_info': SimpleNamespace(rss=1024),
+            'cmdline': ['robot-node'], 'name': 'robot-node',
+        }
+        with patch.object(system_stats.cpu_sampler, 'average', return_value=12.3), \
+                patch.object(system_stats.psutil, 'cpu_percent',
+                             side_effect=AssertionError('API must not resample total CPU')), \
+                patch.object(system_stats.psutil, 'virtual_memory',
+                             return_value=SimpleNamespace(used=1024**3, total=8*1024**3)), \
+                patch.object(system_stats.psutil, 'disk_usage',
+                             return_value=SimpleNamespace(used=10*1024**3, total=100*1024**3)), \
+                patch.object(system_stats, '_extra_storage_disk_usage', return_value=(None, None)), \
+                patch.object(system_stats, '_temperature', return_value=None), \
+                patch.object(system_stats.psutil, 'process_iter', return_value=[process]), \
+                patch.object(system_stats.psutil, 'cpu_count', return_value=4), \
+                patch.object(system_stats.time, 'sleep') as sleep:
+            status = system_stats.get_system_stats()
+            processes = system_stats._sample_processes()
+        self.assertEqual(status.cpu_percent, 12.3)
+        self.assertEqual(processes.cpu_percent, status.cpu_percent)
+        self.assertEqual(processes.processes[0].cpu_percent, 20.0)
+        process.cpu_percent.assert_called_once_with(None)
+        sleep.assert_called_once_with(0.2)
+
+
+class CpuLifespanTests(unittest.IsolatedAsyncioTestCase):
+    """Check sampler cleanup when the API exits."""
+
+    async def test_lifespan_stops_sampler_even_on_failure(self):
+        """Stop the background worker on both normal and exceptional shutdown."""
+        sampler = Mock()
+        with patch.object(system_stats, 'cpu_sampler', sampler):
+            async with lifespan(app):
+                sampler.start.assert_called_once_with()
+                sampler.stop.assert_not_called()
+            sampler.stop.assert_called_once_with()
+            sampler.reset_mock()
+            with self.assertRaises(RuntimeError):
+                async with lifespan(app):
+                    raise RuntimeError('shutdown')
+            sampler.start.assert_called_once_with()
+            sampler.stop.assert_called_once_with()
+
+
+if __name__ == '__main__':
+    unittest.main()