hermes-mobile-plugin 0.0.15__tar.gz

hermes_mobile_plugin-0.0.15/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sachin Taware
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hermes_mobile_plugin-0.0.15/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: hermes-mobile-plugin
+Version: 0.0.15
+Summary: Hermes Mobile QR Plugin - Generates QR code for direct 8642 connection
+Author: Sachin Taware
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: qrcode>=7.4
+Requires-Dist: aiohttp>=3.8
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# Hermes Mobile Plugin
+
+<p align="center">
+  <img src="https://img.shields.io/github/v/tag/tawaresachin/hermes-mobile-plugin?label=version&color=blue&style=for-the-badge" alt="version">
+  <img src="https://img.shields.io/github/actions/workflow/status/tawaresachin/hermes-mobile-plugin/ci.yml?branch=main&label=CI&style=for-the-badge" alt="CI">
+  <img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="MIT">
+  <img src="https://img.shields.io/badge/platforms-Windows%20%7C%20macOS%20%7C%20Linux%20%7C%20Android-blueviolet?style=for-the-badge" alt="platforms">
+  <img src="https://img.shields.io/badge/Python-3.10+-yellow?style=for-the-badge" alt="python">
+</p>
+
+The server-side half of **Hermes Mobile**: one plugin that turns your running
+[Hermes Agent](https://hermes-agent.nousresearch.com) into a phone-ready hub — QR pairing, voice,
+files, and server management. No extra daemon, no cloud relay: everything is mounted on the
+gateway you already run (default port **8642**).
+
+> You install **Hermes Agent** from the official site, then this **one plugin**. That's the whole
+> server-side setup.
+
+## What you get
+
+<img src="docs/screenshots/qr-pairing.jpg" width="360" alt="Pairing screen">
+
+*Settings in the app after scanning the QR: server URL + key configured, connection live.*
+
+| Capability | What it means for you |
+|---|---|
+| **QR pairing** | `install` prints/opens a QR with URL + API key; the app scans it (camera or gallery) and configures + tests the connection itself. |
+| **Voice on-device** | Speech-to-text (Whisper) and text-to-speech routes on the gateway, so the phone mic/speaker work with zero extra services. |
+| **File transfer** | Upload attachments from the phone, download anything the agent creates — the chat shows real file cards, previewable in-app. |
+| **Context meter** | Live token usage / context window per session, straight from server truth. |
+| **Slash commands** | The app's `/` menu is built from your actual server commands, not a hardcoded list. |
+| **Update from your phone** | About screen checks and applies `hermes update` on the server — restart included. |
+| **Keep-awake control** | Toggle the Termux/system wake lock remotely so long runs aren't killed. |
+| **24/7 supervisor** | Optional watchdog auto-restarts the gateway if it ever dies, and survives reboots of the app. |
+| **Crash reports** | The app pushes its crash dumps here (`~/.hermes/mobile-logs/diag/`) so issues are diagnosable without cables. |
+| **Swarm-ready** | Turns started with the app's Swarm toggle carry their own orchestration directives — no extra server setup. |
+
+Nothing is re-implemented: STT/TTS reuse Hermes Agent's own provider chain, sessions/models are
+read from the agent's API. The plugin adds routes, not forks.
+
+## Install
+
+**[Download the latest release →](https://github.com/tawaresachin/hermes-mobile-plugin/releases/latest)**
+(every release ships a pure-Python `py3-none-any` wheel + sdist with `SHA256SUMS` checksums, built and version-verified by CI)
+
+Into the same Python environment your Hermes Agent runs in (its venv):
+
+```bash
+pip install git+https://github.com/tawaresachin/hermes-mobile-plugin@v0.0.12
+# or from the release page: pip install hermes_mobile_plugin-<ver>-py3-none-any.whl
+hermes-mobile-plugin install      # registers plugin + generates the QR
+```
+
+The plugin is pure Python — the one wheel runs unchanged on Windows, macOS, Linux and
+Termux (native deps resolve per-OS from PyPI at install time). Not on PyPI; GitHub Releases
+is the release channel, which matches how Hermes Agent itself updates from git.
+
+`install` copies the plugin into the Hermes home your agent actually resolves (`~/.hermes` on Linux/Termux, XDG dirs on macOS, `%LOCALAPPDATA%\hermes` on Windows) and (re)starts the gateway.
+Then grab the [Hermes Mobile APK](https://github.com/tawaresachin/hermes-mobile/releases), open
+**Settings → Connect with QR**, and scan. LAN, Tailscale, or any tunnel — the QR carries the
+address your phone can actually reach.
+
+## CLI
+
+```text
+hermes-mobile-plugin install      # set up + show QR
+hermes-mobile-plugin qr           # regenerate the QR (--no-browser)
+hermes-mobile-plugin status       # supervisor + gateway health
+hermes-mobile-plugin supervisor --start|--stop|—daemon 24/7 watchdog
+```
+
+## HTTP routes (all Bearer-key protected)
+
+Mounted on the api_server platform; the mobile app is the client.
+
+| Route | Purpose |
+|---|---|
+| `POST /api/audio/transcribe` · `POST /api/audio/speak` | STT / TTS |
+| `POST /api/audio/upload` · `GET /api/audio/download/{sid}/{name}` | attachments both ways |
+| `GET /api/mobile/file` | fetch agent-created files for MEDIA cards |
+| `GET /api/mobile/commands` · `POST /api/mobile/command/resolve` | slash-command menu |
+| `GET /api/mobile/context-usage` · `GET /api/mobile/context-window` | context meter |
+| `GET /api/mobile/update/check` · `POST /update/apply` · `GET /update/version` | server self-update |
+| `GET /api/system/status` · `POST /api/system/awake` | host status, keep-awake |
+| `POST /api/diag/log` · `GET /api/audio/health` | crash reports, liveness |
+
+## Cross-platform
+
+Runs wherever Hermes Agent runs — **Windows, macOS, Linux, Termux/Android** — with per-platform
+handling for process detachment, single-instance locks, launcher lookup (`hermes.exe` included),
+and keep-awake (termux-wake-lock / caffeine / powershell), degrading honestly when a mechanism
+doesn't exist. 53 tests cover the platform seams and the scripted-install paths.
+
+**Termux note:** the shell installer skips pip there (it can trigger NDK toolchain builds);
+Hermes Agent's own Termux environment must provide `pyyaml`, `qrcode` and `aiohttp` — the
+standard agent install does.
+
+## Development
+
+```bash
+git clone https://github.com/tawaresachin/hermes-mobile-plugin.git
+cd hermes-mobile-plugin
+pip install -e ".[dev]"
+PYTHONPATH=src pytest            # 53 tests
+```
+
+CI (`.github/workflows/ci.yml`) runs the suite on ubuntu/macos/windows on every push, plus
+sandboxed end-to-end dry-runs of `install.sh` (Linux + macOS, including the Termux skip-pip
+path) and `install.bat` (Windows, fake venv + redirected home). Version tags additionally
+build the wheel, verify the bundled manifest matches the tag, and attach it to the release.
+
+Releases are tagged `v<version>`; `plugin.yaml` is the single source of the version string
+(`PLUGIN_VERSION` derives from it — packaging metadata can't drift).
+
+## License
+
+MIT © 2026 Sachin Taware

hermes_mobile_plugin-0.0.15/README.md

@@ -0,0 +1,117 @@
+# Hermes Mobile Plugin
+
+<p align="center">
+  <img src="https://img.shields.io/github/v/tag/tawaresachin/hermes-mobile-plugin?label=version&color=blue&style=for-the-badge" alt="version">
+  <img src="https://img.shields.io/github/actions/workflow/status/tawaresachin/hermes-mobile-plugin/ci.yml?branch=main&label=CI&style=for-the-badge" alt="CI">
+  <img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="MIT">
+  <img src="https://img.shields.io/badge/platforms-Windows%20%7C%20macOS%20%7C%20Linux%20%7C%20Android-blueviolet?style=for-the-badge" alt="platforms">
+  <img src="https://img.shields.io/badge/Python-3.10+-yellow?style=for-the-badge" alt="python">
+</p>
+
+The server-side half of **Hermes Mobile**: one plugin that turns your running
+[Hermes Agent](https://hermes-agent.nousresearch.com) into a phone-ready hub — QR pairing, voice,
+files, and server management. No extra daemon, no cloud relay: everything is mounted on the
+gateway you already run (default port **8642**).
+
+> You install **Hermes Agent** from the official site, then this **one plugin**. That's the whole
+> server-side setup.
+
+## What you get
+
+<img src="docs/screenshots/qr-pairing.jpg" width="360" alt="Pairing screen">
+
+*Settings in the app after scanning the QR: server URL + key configured, connection live.*
+
+| Capability | What it means for you |
+|---|---|
+| **QR pairing** | `install` prints/opens a QR with URL + API key; the app scans it (camera or gallery) and configures + tests the connection itself. |
+| **Voice on-device** | Speech-to-text (Whisper) and text-to-speech routes on the gateway, so the phone mic/speaker work with zero extra services. |
+| **File transfer** | Upload attachments from the phone, download anything the agent creates — the chat shows real file cards, previewable in-app. |
+| **Context meter** | Live token usage / context window per session, straight from server truth. |
+| **Slash commands** | The app's `/` menu is built from your actual server commands, not a hardcoded list. |
+| **Update from your phone** | About screen checks and applies `hermes update` on the server — restart included. |
+| **Keep-awake control** | Toggle the Termux/system wake lock remotely so long runs aren't killed. |
+| **24/7 supervisor** | Optional watchdog auto-restarts the gateway if it ever dies, and survives reboots of the app. |
+| **Crash reports** | The app pushes its crash dumps here (`~/.hermes/mobile-logs/diag/`) so issues are diagnosable without cables. |
+| **Swarm-ready** | Turns started with the app's Swarm toggle carry their own orchestration directives — no extra server setup. |
+
+Nothing is re-implemented: STT/TTS reuse Hermes Agent's own provider chain, sessions/models are
+read from the agent's API. The plugin adds routes, not forks.
+
+## Install
+
+**[Download the latest release →](https://github.com/tawaresachin/hermes-mobile-plugin/releases/latest)**
+(every release ships a pure-Python `py3-none-any` wheel + sdist with `SHA256SUMS` checksums, built and version-verified by CI)
+
+Into the same Python environment your Hermes Agent runs in (its venv):
+
+```bash
+pip install git+https://github.com/tawaresachin/hermes-mobile-plugin@v0.0.12
+# or from the release page: pip install hermes_mobile_plugin-<ver>-py3-none-any.whl
+hermes-mobile-plugin install      # registers plugin + generates the QR
+```
+
+The plugin is pure Python — the one wheel runs unchanged on Windows, macOS, Linux and
+Termux (native deps resolve per-OS from PyPI at install time). Not on PyPI; GitHub Releases
+is the release channel, which matches how Hermes Agent itself updates from git.
+
+`install` copies the plugin into the Hermes home your agent actually resolves (`~/.hermes` on Linux/Termux, XDG dirs on macOS, `%LOCALAPPDATA%\hermes` on Windows) and (re)starts the gateway.
+Then grab the [Hermes Mobile APK](https://github.com/tawaresachin/hermes-mobile/releases), open
+**Settings → Connect with QR**, and scan. LAN, Tailscale, or any tunnel — the QR carries the
+address your phone can actually reach.
+
+## CLI
+
+```text
+hermes-mobile-plugin install      # set up + show QR
+hermes-mobile-plugin qr           # regenerate the QR (--no-browser)
+hermes-mobile-plugin status       # supervisor + gateway health
+hermes-mobile-plugin supervisor --start|--stop|—daemon 24/7 watchdog
+```
+
+## HTTP routes (all Bearer-key protected)
+
+Mounted on the api_server platform; the mobile app is the client.
+
+| Route | Purpose |
+|---|---|
+| `POST /api/audio/transcribe` · `POST /api/audio/speak` | STT / TTS |
+| `POST /api/audio/upload` · `GET /api/audio/download/{sid}/{name}` | attachments both ways |
+| `GET /api/mobile/file` | fetch agent-created files for MEDIA cards |
+| `GET /api/mobile/commands` · `POST /api/mobile/command/resolve` | slash-command menu |
+| `GET /api/mobile/context-usage` · `GET /api/mobile/context-window` | context meter |
+| `GET /api/mobile/update/check` · `POST /update/apply` · `GET /update/version` | server self-update |
+| `GET /api/system/status` · `POST /api/system/awake` | host status, keep-awake |
+| `POST /api/diag/log` · `GET /api/audio/health` | crash reports, liveness |
+
+## Cross-platform
+
+Runs wherever Hermes Agent runs — **Windows, macOS, Linux, Termux/Android** — with per-platform
+handling for process detachment, single-instance locks, launcher lookup (`hermes.exe` included),
+and keep-awake (termux-wake-lock / caffeine / powershell), degrading honestly when a mechanism
+doesn't exist. 53 tests cover the platform seams and the scripted-install paths.
+
+**Termux note:** the shell installer skips pip there (it can trigger NDK toolchain builds);
+Hermes Agent's own Termux environment must provide `pyyaml`, `qrcode` and `aiohttp` — the
+standard agent install does.
+
+## Development
+
+```bash
+git clone https://github.com/tawaresachin/hermes-mobile-plugin.git
+cd hermes-mobile-plugin
+pip install -e ".[dev]"
+PYTHONPATH=src pytest            # 53 tests
+```
+
+CI (`.github/workflows/ci.yml`) runs the suite on ubuntu/macos/windows on every push, plus
+sandboxed end-to-end dry-runs of `install.sh` (Linux + macOS, including the Termux skip-pip
+path) and `install.bat` (Windows, fake venv + redirected home). Version tags additionally
+build the wheel, verify the bundled manifest matches the tag, and attach it to the release.
+
+Releases are tagged `v<version>`; `plugin.yaml` is the single source of the version string
+(`PLUGIN_VERSION` derives from it — packaging metadata can't drift).
+
+## License
+
+MIT © 2026 Sachin Taware

hermes_mobile_plugin-0.0.15/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hermes-mobile-plugin"
+version = "0.0.15"
+description = "Hermes Mobile QR Plugin - Generates QR code for direct 8642 connection"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [{name = "Sachin Taware"}]
+dependencies = [
+    "pyyaml>=6.0",
+    "qrcode>=7.4",
+    "aiohttp>=3.8",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "black",
+    "ruff",
+]
+
+[project.scripts]
+hermes-mobile-plugin = "hermes_mobile_plugin.cli:main"
+hermes-mobile-install = "hermes_mobile_plugin.cli:install_plugin"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+# Ship the loader manifest inside the wheel so `hermes-mobile-install`
+# works from a pip install (no repo checkout) — the deploy code looks for
+# plugin.yaml beside the package when the repo root is not there.
+hermes_mobile_plugin = ["plugin.yaml"]
+
+[tool.black]
+line-length = 88
+target-version = ["py310"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"

hermes_mobile_plugin-0.0.15/setup.cfg

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

hermes_mobile_plugin-0.0.15/src/hermes_mobile_plugin/__init__.py

@@ -0,0 +1,215 @@
+"""Hermes Mobile QR Plugin - Clean architecture implementation.
+
+Generates a QR code for the Hermes Mobile App to connect directly to the
+Hermes Agent Desktop gateway (port 8642), and exposes voice STT/TTS routes
+on the gateway so the mobile app can speak and listen without an extra
+service.
+
+Both behaviors are opt-in via ``plugins.hermes-mobile-qr`` in
+``~/.hermes/config.yaml``:
+
+    plugins:
+      hermes-mobile-qr:
+        auto_generate: true     # QR code on startup
+        audio: true             # voice routes on api_server
+
+Audio routes are mounted via the standard plugin handler mechanism
+(``ctx.register_platform_handler("api_server", _wire)``), which gives
+the plugin a handle on the api_server's aiohttp ``web.Application``.
+"""
+
+import asyncio
+import logging
+import threading
+from pathlib import Path
+from typing import Any, Optional
+
+from .constants import PLUGIN_VERSION
+
+logger = logging.getLogger(__name__)
+
+
+class HermesMobileQRPlugin:
+    """Plugin that generates QR codes for mobile app connection to 8642 gateway.
+
+    Used by the legacy entry-point style loader. The standard
+    ``register(ctx)`` function below is the path the modern plugin loader
+    uses; both entry points are kept for backward compatibility.
+    """
+
+    def __init__(self, config: dict, plugin_dir: Path):
+        self.config = config
+        self.plugin_dir = plugin_dir
+        self._qr_generated = False
+
+    async def startup(self) -> None:
+        """Called when Hermes Agent starts up (legacy entry-point style)."""
+        try:
+            from .config import get_plugin_config
+            plugin_config = get_plugin_config(self.config)
+        except ImportError:
+            plugin_config = self.config.get("plugins", {}).get("hermes-mobile-qr", {})
+
+        if plugin_config.get("auto_generate", True):
+            logger.info("[Hermes Mobile QR v%s] Plugin starting...", PLUGIN_VERSION)
+            await self._generate_qr_and_start_supervisor()
+        else:
+            logger.info("[Hermes Mobile QR v%s] Auto-generate disabled", PLUGIN_VERSION)
+
+    async def shutdown(self) -> None:
+        logger.info("[Hermes Mobile QR] Plugin shutting down...")
+
+    async def _generate_qr_and_start_supervisor(self) -> None:
+        if self._qr_generated:
+            return
+        try:
+            from .qr_generator import generate_qr
+            await generate_qr(self.config, self.plugin_dir)
+            self._qr_generated = True
+            logger.info("[Hermes Mobile QR] QR code generated successfully")
+
+            from .supervisor import ensure_running
+            ensure_running()
+            logger.info("[Hermes Mobile QR] Gateway watchdog verified/spawned")
+
+        except Exception as e:
+            logger.warning("[Hermes Mobile QR] Failed to initialize: %s", e)
+
+# ---------------------------------------------------------------------------
+# Standard plugin entry point (register(ctx))
+# ---------------------------------------------------------------------------
+
+# Registration is keyed on the aiohttp app INSTANCE, not a global bool: a
+# second api_server connect onto a DIFFERENT app must still get its routes,
+# while a double-wire of the SAME app stays a no-op. (WeakSet so a dead app
+# never pins memory and tests get a clean slate per instance.)
+import weakref
+
+_audio_wired_apps = weakref.WeakSet()
+_audio_lock = threading.Lock()
+
+
+def _wire_audio_routes(native: Any, adapter: Any) -> None:
+    """Factory passed to ``ctx.register_platform_handler("api_server", ...)``.
+
+    Receives the api_server's aiohttp ``web.Application`` as ``native``
+    and registers the plugin's voice routes on it. Guarded per-app so a
+    second connect of the SAME app doesn't double-register, while a fresh
+    app (hot-reload, tests) still gets mounted.
+    """
+    with _audio_lock:
+        if native is not None and native in _audio_wired_apps:
+            logger.debug("[hermes-mobile-qr] Audio routes already registered on this app; skipping")
+            return
+        try:
+            from .audio_routes import register as _register_routes
+            from .system_routes import register as _register_system_routes
+            from .commands_routes import register as _register_command_routes
+            from .update_routes import register as _register_update_routes
+            from .providers_routes import register as _register_providers_routes
+        except Exception as exc:
+            logger.warning(
+                "[hermes-mobile-qr] Could not import route modules: %s", exc
+            )
+            return
+        if native is None:
+            logger.debug(
+                "[hermes-mobile-qr] api_server native is None; "
+                "audio routes not mounted on this run"
+            )
+            return
+        try:
+            _register_routes(native)
+            _register_system_routes(native)
+            _register_command_routes(native)
+            _register_update_routes(native)
+            _register_providers_routes(native)
+        except Exception as exc:
+            logger.exception(
+                "[hermes-mobile-qr] Failed to register audio routes: %s", exc
+            )
+            return
+        if native is not None:
+            _audio_wired_apps.add(native)
+
+
+async def _maybe_generate_qr(ctx: Any) -> None:
+    """Best-effort QR generation on startup, mirroring the legacy flow.
+
+    ``PluginContext`` exposes no ``.config``/``.plugin_dir`` attributes — the
+    QR payload needs the REAL platforms.api_server config, so load it from
+    config.yaml directly, and write the HTML next to the plugin package
+    (never the gateway's CWD).
+    """
+    try:
+        from .config import load_hermes_config, get_plugin_config
+        hermes_config = load_hermes_config()
+        plugin_config = get_plugin_config(hermes_config)
+    except ImportError:
+        hermes_config, plugin_config = {}, {}
+
+    if not plugin_config.get("auto_generate", True):
+        return
+
+    try:
+        from .constants import PLUGIN_DIR
+        from .qr_generator import generate_qr
+        out_dir = Path(ctx.plugin_dir) if getattr(ctx, "plugin_dir", None) else PLUGIN_DIR
+        await generate_qr(hermes_config, out_dir)
+        logger.info("[Hermes Mobile QR] QR code generated via register(ctx)")
+    except Exception as exc:
+        logger.warning("[Hermes Mobile QR] QR generation skipped: %s", exc)
+
+
+def register(ctx: Any) -> None:
+    """Standard plugin entry point. Called by Hermes plugin loader.
+
+    Registers the plugin's voice STT/TTS routes on the api_server
+    platform, and (if enabled) generates a QR code on startup.
+    """
+    logger.info(
+        "[Hermes Mobile QR v%s] register(ctx) called", PLUGIN_VERSION
+    )
+
+    # Register the api_server handler — always safe (idempotent guard).
+    try:
+        ctx.register_platform_handler("api_server", _wire_audio_routes)
+    except Exception as exc:
+        logger.warning(
+            "[Hermes Mobile QR] Could not register api_server handler: %s", exc
+        )
+
+    # Keep-alive: spawn the detached gateway watchdog. It lives OUTSIDE the
+    # gateway process, so if the gateway dies (crash, OOM, reboot script) it
+    # restarts it and the app reconnects. Idempotent via PID file.
+    try:
+        from .supervisor import ensure_running
+        ensure_running()
+    except Exception as exc:
+        logger.warning("[Hermes Mobile QR] Watchdog spawn failed: %s", exc)
+
+    # Fire-and-forget QR generation so we don't block loader. Scheduling
+    # only ever happens on an ALREADY-running loop: a run_until_complete
+    # fallback here could block the plugin loader (or start a stray loop
+    # beside the gateway's). No loop at register-time -> QR skipped until
+    # the next startup; the CLI covers the manual path.
+    try:
+        asyncio.get_running_loop().create_task(_maybe_generate_qr(ctx))
+    except RuntimeError:
+        logger.debug("[hermes-mobile-qr] no running loop at register(); QR gen deferred")
+
+
+# ---------------------------------------------------------------------------
+# Legacy entry point (kept for backward compatibility)
+# ---------------------------------------------------------------------------
+
+
+def create_plugin(config: dict, plugin_dir: Path) -> HermesMobileQRPlugin:
+    """Factory function called by the legacy Hermes plugin loader."""
+    return HermesMobileQRPlugin(config, plugin_dir)
+
+
+async def startup_hook(config: dict, plugin_dir: Path) -> None:
+    """Standalone startup hook if Hermes loader expects a function."""
+    plugin = create_plugin(config, plugin_dir)
+    await plugin.startup()