ovos-PHAL-plugin-app-launcher

This PHAL plugin for OpenVoiceOS manages OS-level desktop applications for ovos-skill-application-launcher or any other bus client. It scans .desktop files, launches and closes processes, and reports application state over the OVOS messagebus.

Why a split architecture?

In a single-box OVOS install, the skill and the OS run on the same machine, so subprocess.Popen calls from the skill work directly. A split between skill and plugin becomes necessary in these cases:

• ovos-core runs on a server or NUC while the desktop runs on a different device.
• The device OS changes (for example X11 desktop, Wayland, or a headless kiosk). Only the PHAL plugin needs to change; the skill stays the same.
• HiveMind multi-room setups: the skill runs on the ovos-core satellite, and the PHAL plugin runs on the satellite device where apps must open. Bus messages cross HiveMind transparently.

┌──────────────── ovos-core machine ─────────────────┐
│  ovos-skill-application-launcher                    │
│    • understands speech / intents                   │
│    • emits ovos.phal.app_launcher.* requests        │
│    • waits for responses, speaks result / error     │
└────────────────────┬───────────────────────────────┘
                     │  messagebus  (local or HiveMind)
┌────────────────── device machine ──────────────────┐
│  ovos-PHAL-plugin-app-launcher  (this repo)         │
│    • scans .desktop files                           │
│    • launches / closes processes via subprocess     │
│    • manages windows via wmctrl (optional)          │
│    • replies success / error                        │
└────────────────────────────────────────────────────┘

Bus event API

Each request and response pair uses the standard message.response() convention, so bus.wait_for_response works across HiveMind sessions.

Matching

launch, close, and is_running resolve the spoken name against the built application list (and, for close/is_running, against open window titles) with a fuzzy match. A name that scores below match_threshold is reported back as not found ({name, error: "No application matched '...'"} for launch, or excluded from window candidates for close) rather than being fuzzy-matched to some other, unrelated application.

Response and timeout guarantees

Every request gets exactly one response. When process enumeration fails mid-scan (a process exits while the plugin is looking at it, or access is denied), the handler answers with {name, error: str} instead of staying silent, so a wait_for_response caller never hangs on a race. Calls to wmctrl (window listing and window close) time out after 3 seconds; a hung window manager makes close fall back to the process-based path rather than blocking the handler.

Configuration

Add to ovos.conf under the PHAL section or plugin settings:

{
  "ovos-phal-plugin-app-launcher": {
    "skip_categories": ["Settings", "ConsoleOnly", "Building"],
    "skip_keywords": [],
    "target_categories": [],
    "target_keywords": [],
    "blacklist": [],
    "aliases": {"kcalc": ["calculator"]},
    "user_commands": {},
    "require_icon": true,
    "require_categories": true,
    "match_threshold": 0.85,
    "terminate_all": false,
    "disable_window_manager": false
  }
}

Installation

pip install ovos-PHAL-plugin-app-launcher
# optional: for window management
sudo apt install wmctrl

Related projects

• ovos-skill-application-launcher - the OVOS skill that sends launch, close, and status requests to this plugin.

Credits

Developed by TigreGótico for OpenVoiceOS.

This project was funded through the NGI0 Commons Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet programme, under the aegis of DG Communications Networks, Content and Technology under grant agreement No 101135429.