hermes-ssh 0.3.1__py3-none-any.whl

hermes_ssh-0.3.1.dist-info/METADATA

@@ -0,0 +1,273 @@
+Metadata-Version: 2.4
+Name: hermes-ssh
+Version: 0.3.1
+Summary: SSH remote execution plugin for Hermes Agent
+Project-URL: Homepage, https://github.com/TheEpTic/hermes-plugins
+Project-URL: Repository, https://github.com/TheEpTic/hermes-plugins
+Project-URL: Issues, https://github.com/TheEpTic/hermes-plugins/issues
+Project-URL: Changelog, https://github.com/TheEpTic/hermes-plugins/blob/main/hermes-ssh/CHANGELOG.md
+Author-email: TheEpTic <nexus@eptic.me>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,devops,hermes,remote,ssh
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: cryptography<49,>=48.0.1
+Provides-Extra: dev
+Requires-Dist: black==26.5.1; extra == 'dev'
+Requires-Dist: mypy==1.16.0; extra == 'dev'
+Requires-Dist: pytest==9.0.3; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# hermes-ssh
+
+[![CI](https://github.com/TheEpTic/hermes-plugins/actions/workflows/ci.yml/badge.svg)](https://github.com/TheEpTic/hermes-plugins/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+
+SSH remote execution plugin for [Hermes Agent](https://github.com/NousResearch/hermes-agent).
+
+Run commands on remote servers, track sessions, reuse connections — all from inside Hermes.
+
+```
+/ssh web1 uptime
+ssh_machines add name=web1 host=192.168.1.50
+ssh_sessions list
+```
+
+## Quick Start
+
+> **Requires Python 3.11+** and an OpenSSH client (`ssh`) on the host system.
+
+### Option 1: Deploy script (recommended)
+
+```bash
+git clone https://github.com/TheEpTic/hermes-plugins.git
+cd hermes-plugins/hermes-ssh
+./deploy.sh
+```
+
+Then restart Hermes with `/reset`.
+
+### Option 2: Manual symlink
+
+```bash
+git clone https://github.com/TheEpTic/hermes-plugins.git
+ln -s "$(pwd)/hermes-plugins/hermes-ssh/src/ssh_tools" ~/.hermes/plugins/hermes-ssh
+```
+
+Then `/reset` in Hermes. The symlink points at the source tree, but Python modules are imported once, so code changes still require `/reset` or a Hermes process restart before they load.
+
+### Option 3: As a Python package
+
+```bash
+pip install git+https://github.com/TheEpTic/hermes-plugins.git#subdirectory=hermes-ssh
+```
+
+Then enable it and restart Hermes:
+
+```bash
+hermes plugins enable hermes-ssh
+```
+
+## Features
+
+### `ssh_terminal` — Run Commands
+
+Execute any command on a remote machine. Commands run through `bash -c` with `pipefail`, so pipelines work correctly.
+
+```bash
+# Synchronous (waits for completion)
+ssh_terminal machine=web1 command="df -h"
+
+# Background (returns immediately)
+ssh_terminal machine=web1 command="tail -f /var/log/syslog" background=true
+
+# With timeout
+ssh_terminal machine=web1 command="make -j4" timeout=300
+```
+
+**Output truncation:** When output exceeds `max_output_chars` (default: 50,000), the full output is saved under the plugin's restricted output directory and a summary with the file path is returned. The LLM can then use `read_file` to access the complete output.
+
+**Background commands:** Long-running commands can be backgrounded. The plugin tracks the process and lets you poll for status or retrieve output later.
+
+```bash
+# Check if still running
+ssh_terminal poll=<session_id>
+
+# Read output from completed command
+ssh_terminal read_output=<session_id>
+
+# Or via ssh_sessions
+ssh_sessions action=poll session_id=<session_id>
+ssh_sessions action=read_output session_id=<session_id>
+```
+
+### `ssh_machines` — Machine Registry
+
+Register servers once, refer to them by name or alias.
+
+```bash
+# Add a server
+ssh_machines action=add name=web1 host=192.168.1.50 user=deploy key=~/.ssh/id_ed25519
+
+# Add with aliases and tags
+ssh_machines action=add name=prod-web host=10.0.0.1 aliases=web1,tags=production,web
+
+# List all machines
+ssh_machines action=list
+
+# Test connectivity
+ssh_machines action=test name=web1
+
+# Get full details
+ssh_machines action=inspect name=web1
+```
+
+Machine names must be alphanumeric with dots, hyphens, or underscores (1-64 chars). Slashes, spaces, and glob characters are rejected.
+
+### `ssh_sessions` — Session Tracking
+
+Every command creates a session. Sessions track the PID, machine, command count, and idle time.
+
+```bash
+# List active sessions
+ssh_sessions action=list
+
+# Kill a session (terminates the SSH process)
+ssh_sessions action=kill session_id=<session_id>
+
+# Clean up all idle sessions (>30 min)
+ssh_sessions action=cleanup
+
+# Remove old closed sessions (>24 hours)
+ssh_sessions action=prune
+```
+
+Idle sessions are automatically killed by a background checker after 30 minutes. Closed sessions are pruned after 24 hours.
+
+### `/ssh` Slash Command
+
+Quick access from chat without remembering tool names:
+
+```
+/ssh                     # List machines and sessions
+/ssh web1                # Inspect a machine
+/ssh web1 uptime         # Run a command
+/ssh web1 docker ps      # Run a command
+/ssh test                # Test connectivity to all machines
+/ssh cleanup             # Kill all idle sessions
+/ssh help                # Show help
+```
+
+## Configuration
+
+All settings live in `src/ssh_tools/config.py` as an `SSHConfig` dataclass:
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `default_port` | 22 | SSH port for new machines |
+| `default_user` | root | SSH user for new machines |
+| `connect_timeout` | 5s | SSH handshake timeout |
+| `command_timeout` | 30s | Command execution timeout |
+| `max_output_chars` | 50,000 | Output truncation threshold |
+| `idle_check_interval` | 60s | Seconds between idle checks |
+| `idle_timeout_minutes` | 30m | Auto-kill after this idle time |
+| `closed_prune_hours` | 24h | Remove closed sessions after this |
+| `strict_host_key_checking` | accept-new | SSH host key verification |
+
+## Architecture
+
+```
+src/ssh_tools/
+├── __init__.py          # Plugin registration + Hermes hooks
+├── config.py            # SSHConfig (immutable dataclass)
+├── manager.py           # SSHManager — all state and operations
+├── models.py            # Machine, Session dataclasses
+├── schemas.py           # Tool schemas (LLM-facing)
+├── utils.py             # ok(), err(), require() helpers
+├── py.typed             # PEP 561 marker
+└── handlers/
+    ├── terminal.py      # ssh_terminal (execute, poll, read_output)
+    ├── machines.py      # ssh_machines (add/list/remove/test/inspect)
+    ├── sessions.py      # ssh_sessions (list/kill/cleanup/prune/poll/read_output)
+    └── slash.py         # /ssh slash command
+```
+
+**Key design decisions:**
+
+- `SSHManager` owns all state. Thread-safe. No module-level mutable state.
+- Handlers are thin closures — validate params, dispatch to manager, return JSON.
+- JSON files use atomic writes (temp file + `os.replace`) for crash safety.
+- Data directory has restricted permissions (0o700). Audit log and output files use 0o600.
+- Machine names are validated to prevent path traversal and glob injection.
+- Connection reuse via `ControlMaster` with 5-minute persist window.
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for the full picture.
+
+**Defaults you should know about:**
+
+- `StrictHostKeyChecking=accept-new` — accepts first-seen host keys but rejects changed keys. Set to `yes` for strict production hosts.
+- Machine credentials are encrypted at rest in `~/.hermes/ssh-tools/machines.json`. Data directory is 0o700.
+- All commands execute with the permissions of the Hermes agent process.
+
+**Hardening applied:**
+
+- Machine names validated against `^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$`
+- Output files written with 0o600 permissions
+- Audit log created with 0o600 permissions
+- Atomic JSON writes prevent corruption on crash
+- Orphaned temp files cleaned on startup
+
+## Requirements
+
+- Python 3.11+
+- OpenSSH client (`ssh`)
+- [Hermes Agent](https://github.com/NousResearch/hermes-agent)
+
+## Troubleshooting
+
+**Connection refused**
+The remote host may not be listening on the expected port, or a firewall is blocking the connection. Verify with `ssh -v user@host` outside of Hermes.
+
+**Permission denied (publickey)**
+The SSH key path stored in the machine registry may be incorrect, or the remote host doesn't have the corresponding public key in `~/.ssh/authorized_keys`. Verify with `ssh -i /path/to/key user@host`.
+
+**Command timeout**
+Commands exceeding `command_timeout` (default 30s) are killed. Increase the timeout or use `background=true` for long-running work.
+
+**Output looks truncated**
+This is intentional — large outputs are saved under the restricted plugin output directory and a summary is returned. Use `read_output` or `read_file` on the returned path for the full output.
+
+**Session stuck as "active" after process died**
+If the agent restarted, background process references are lost. Use `ssh_sessions action=cleanup` to kill stale sessions, or `ssh_sessions action=prune` to remove old closed ones.
+
+## Development
+
+```bash
+git clone https://github.com/TheEpTic/hermes-plugins.git
+cd hermes-plugins/hermes-ssh
+python -m venv .venv && source .venv/bin/activate
+pip install -e '.[dev]'
+
+# Run checks
+black --check src/ssh_tools/ tests/
+mypy src/ssh_tools/
+pytest
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

hermes_ssh-0.3.1.dist-info/RECORD

@@ -0,0 +1,21 @@
+ssh_tools/__init__.py,sha256=4DiMx-AhnNmAuHHbTmkrTtqiMkw6aSFqlCl9QEg4IDY,2639
+ssh_tools/approval.py,sha256=30Npl1rCAueeKKRds3_fXB8zL5J-CD4GnzpSMgx5q3k,1372
+ssh_tools/config.py,sha256=CBLNn2oaTe5D0NDaCpVbCATYoOJp4ZtdO4p1R_0hN7c,2103
+ssh_tools/manager.py,sha256=VemehZRhUjbWqLDUzbkQvcO2XDGxRwmCeOJQFV9xWpY,33067
+ssh_tools/migrate.py,sha256=8tgdnW30J-Ladps9eUR8IFr65GxJcg7a551YflBZU9Q,3548
+ssh_tools/models.py,sha256=mGjMgZctdFO_omN8gW79_Nc_TADKbGnI9DUij31qd0I,2985
+ssh_tools/plugin.yaml,sha256=soHtlL0RAZUWYjIyKNPBFAaxDUof0ryYdN-DaBc2LZk,303
+ssh_tools/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ssh_tools/schemas.py,sha256=N-jyf-n3l4yJG8OekaNG583IouglIB75HqRs-tPEfvc,4690
+ssh_tools/storage.py,sha256=bUcEyRf8gGtO6rqaKylzJqxs2I6yoUSE_8F3Df9439s,6002
+ssh_tools/utils.py,sha256=p2qjZijTLEfu6boIc5f0vG3Z7IRrkOoiWOC_4nloseo,1018
+ssh_tools/handlers/__init__.py,sha256=9zbDGQV7qlVa7AIAmkIL0HQFQ4YjjcBs00Vb-UC56Jw,244
+ssh_tools/handlers/machines.py,sha256=gGl5Z1daWqChqXm8wrkK2HeNPLxAr-DrJFM0TIcOKHQ,3308
+ssh_tools/handlers/sessions.py,sha256=HvLoI91uXaxdg2qNiNUuM0IXQkQpakIrqpNfynUcjr0,3025
+ssh_tools/handlers/slash.py,sha256=ezj7b4qxZcGJf2vsl2yIty-oBpJMmc8DusqpxF9wGeA,4859
+ssh_tools/handlers/terminal.py,sha256=QdQj2t627ea9QhmxCGpmd-zs3785eC282bAMpJeqBdk,2993
+hermes_ssh-0.3.1.dist-info/METADATA,sha256=YNoTSrfQEzv2h9cbIoxbJalW8WW-ajTj0CGTSflmrLI,9684
+hermes_ssh-0.3.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+hermes_ssh-0.3.1.dist-info/entry_points.txt,sha256=sifscbypKTTI9jbsFRDf5eSYdf5qvXAaOW9uE9N61j8,46
+hermes_ssh-0.3.1.dist-info/licenses/LICENSE,sha256=eA6I1UzoZMbxfsHuSp1YD6bVF9QkWcPiEf-CQcMF-Jw,1065
+hermes_ssh-0.3.1.dist-info/RECORD,,

hermes_ssh-0.3.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

hermes_ssh-0.3.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[hermes_agent.plugins]
+hermes-ssh = ssh_tools

hermes_ssh-0.3.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TheEpTic
+
+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.

ssh_tools/__init__.py

@@ -0,0 +1,92 @@
+"""hermes-ssh — SSH remote execution plugin for Hermes Agent.
+
+Provides:
+  - ssh_terminal: Run commands on remote machines via SSH
+  - ssh_machines: Machine registry (add/list/remove/test/inspect)
+  - ssh_sessions: Active session tracking (list/kill/cleanup)
+  - /ssh slash command for quick access
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from .handlers import handle_ssh_machines, handle_ssh_sessions, handle_ssh_terminal
+from .handlers.slash import create_slash_handler
+from .manager import SSHManager
+from .schemas import SSH_MACHINES_SCHEMA, SSH_SESSIONS_SCHEMA, SSH_TERMINAL_SCHEMA
+
+__version__ = "0.2.0"
+__all__ = [
+    "SSH_MACHINES_SCHEMA",
+    "SSH_SESSIONS_SCHEMA",
+    "SSH_TERMINAL_SCHEMA",
+    "SSHManager",
+    "handle_ssh_machines",
+    "handle_ssh_sessions",
+    "handle_ssh_terminal",
+    "register",
+]
+
+logger = logging.getLogger(__name__)
+
+# Module-level manager — initialized in register()
+_manager: SSHManager | None = None
+
+
+def _get_manager() -> SSHManager:
+    global _manager
+    if _manager is None:
+        raise RuntimeError("hermes-ssh plugin not registered. Call register() first.")
+    return _manager
+
+
+# ---------------------------------------------------------------------------
+# Plugin registration
+# ---------------------------------------------------------------------------
+
+
+def register(ctx: Any) -> None:
+    """Register SSH tools with Hermes."""
+    global _manager
+    if _manager is not None:
+        logger.debug("hermes-ssh: already registered, skipping")
+        return
+    _manager = SSHManager()
+
+    # Tools
+    ctx.register_tool(
+        name="ssh_terminal",
+        toolset="ssh_tools",
+        schema=SSH_TERMINAL_SCHEMA,
+        handler=handle_ssh_terminal(_manager),
+        description="Run a command on a remote machine via SSH.",
+    )
+    ctx.register_tool(
+        name="ssh_machines",
+        toolset="ssh_tools",
+        schema=SSH_MACHINES_SCHEMA,
+        handler=handle_ssh_machines(_manager),
+        description="Manage the SSH machine registry.",
+    )
+    ctx.register_tool(
+        name="ssh_sessions",
+        toolset="ssh_tools",
+        schema=SSH_SESSIONS_SCHEMA,
+        handler=handle_ssh_sessions(_manager),
+        description="Manage active SSH sessions.",
+    )
+
+    # Slash command
+    slash_handler = create_slash_handler(_get_manager)
+    ctx.register_command(
+        "ssh",
+        handler=slash_handler,
+        description="SSH session management — machines, sessions, idle alerts.",
+    )
+
+    # Start background idle checker
+    _manager.start_idle_checker()
+
+    logger.info("hermes-ssh plugin loaded")

ssh_tools/approval.py

@@ -0,0 +1,40 @@
+"""Hermes dangerous-command approval integration."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+try:
+    from tools.approval import (
+        _get_approval_mode,
+        check_dangerous_command as _check_dangerous,
+    )  # pyright: ignore[reportMissingImports]
+except ImportError:
+    _check_dangerous = None
+    _get_approval_mode = None
+    logger.warning("Hermes approval system not available — SSH commands will fail closed")
+
+
+def check_approval(command: str) -> dict[str, Any] | None:
+    """Return a denial result, or None when the command is approved/unchecked."""
+    if _check_dangerous is None:
+        return {
+            "approved": False,
+            "message": "SSH command blocked: Hermes approval system is unavailable",
+        }
+    if _get_approval_mode is not None and _get_approval_mode() == "off":
+        return None
+    result: dict[str, Any] = _check_dangerous(command, env_type="ssh")
+    if result.get("status") == "approval_required":
+        description = str(result.get("description") or "command flagged")
+        result = {
+            **result,
+            "message": (
+                f"approval required: {description}. the user must reply with /approve or /deny.\n\n"
+                f"command:\n```\n{command}\n```"
+            ),
+        }
+    return result

ssh_tools/config.py

@@ -0,0 +1,68 @@
+"""Centralized configuration for ssh-tools plugin."""
+
+from __future__ import annotations
+
+import contextlib
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+PLUGIN_DIR = Path(__file__).parent
+DEFAULT_DATA_DIR = Path.home() / ".hermes" / "ssh-tools"
+
+
+@dataclass(frozen=True)
+class SSHConfig:
+    """Immutable plugin configuration."""
+
+    data_dir: Path = field(default=DEFAULT_DATA_DIR)
+
+    # SSH defaults
+    default_port: int = 22
+    default_user: str = "root"
+    connect_timeout: int = 5
+    command_timeout: int = 30
+    strict_host_key_checking: str = "accept-new"
+
+    # Output
+    max_output_chars: int = 50_000  # save to output_dir if exceeded
+
+    # Session management
+    idle_check_interval: int = 60  # seconds between idle checks
+    idle_timeout_minutes: int = 30  # auto-kill after this
+    closed_prune_hours: int = 24  # remove closed sessions after this
+
+    # Paths (derived from data_dir)
+    @property
+    def machines_file(self) -> Path:
+        return self.data_dir / "machines.json"
+
+    @property
+    def sessions_file(self) -> Path:
+        return self.data_dir / "sessions.json"
+
+    @property
+    def socket_dir(self) -> Path:
+        return self.data_dir / "sockets"
+
+    @property
+    def output_dir(self) -> Path:
+        return self.data_dir / "outputs"
+
+    def ensure_dirs(self) -> None:
+        """Create all required directories with restricted permissions."""
+        self.data_dir.mkdir(parents=True, exist_ok=True)
+        self.socket_dir.mkdir(parents=True, exist_ok=True)
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+        # Clean orphaned temp files from previous crashes
+        for tmp in self.data_dir.glob("*.tmp"):
+            with contextlib.suppress(OSError):
+                tmp.unlink()
+        # Restrict permissions — data dir contains machine credentials
+        for d in (self.data_dir, self.socket_dir, self.output_dir):
+            with contextlib.suppress(OSError):
+                os.chmod(d, 0o700)
+
+
+# Module-level default — importable, overridable for tests
+DEFAULT_CONFIG = SSHConfig()

ssh_tools/handlers/__init__.py

@@ -0,0 +1,7 @@
+"""Tool handlers for hermes-ssh."""
+
+from .machines import handle_ssh_machines
+from .sessions import handle_ssh_sessions
+from .terminal import handle_ssh_terminal
+
+__all__ = ["handle_ssh_machines", "handle_ssh_sessions", "handle_ssh_terminal"]

ssh_tools/handlers/machines.py

@@ -0,0 +1,97 @@
+"""Handler for the ssh_machines tool."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from ..models import Machine
+from ..utils import err, ok, require
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from ..manager import SSHManager
+
+
+def handle_ssh_machines(manager: SSHManager) -> Callable[[dict[str, Any]], str]:
+    """Create a handler for ssh_machines that captures manager via closure."""
+
+    def _handle(params: dict[str, Any], **kwargs: Any) -> str:
+        action = params.get("action", "list")
+
+        if action == "list":
+            machines = manager.list_machines()
+            return ok(
+                machines={
+                    name: {
+                        "host": m.host,
+                        "user": m.user,
+                        "port": m.port,
+                        "aliases": m.aliases or [],
+                        "tags": m.tags or [],
+                        "description": m.description,
+                    }
+                    for name, m in machines.items()
+                },
+                count=len(machines),
+            )
+
+        if action == "add":
+            error = require(params, "name", "host")
+            if error:
+                return err(error)
+            try:
+                machine = manager.add_machine(
+                    Machine(
+                        name=params["name"],
+                        host=params["host"],
+                        user=params.get("user", "root"),
+                        port=params.get("port", 22),
+                        key=params.get("key", ""),
+                        aliases=params.get("aliases", []),
+                        tags=params.get("tags", []),
+                        description=params.get("description", ""),
+                    )
+                )
+            except ValueError as exc:
+                return err(str(exc))
+            return ok(machine=machine.to_dict())
+
+        if action == "remove":
+            error = require(params, "name")
+            if error:
+                return err(error)
+            name = params["name"]
+            if not isinstance(name, str):
+                return err("name must be a string")
+            removed = manager.remove_machine(name)
+            return ok(
+                success=removed,
+                message=f"Removed '{name}'" if removed else f"'{name}' not found",
+            )
+
+        if action == "inspect":
+            error = require(params, "name")
+            if error:
+                return err(error)
+            name = params["name"]
+            if not isinstance(name, str):
+                return err("name must be a string")
+            inspected = manager.get_machine(name)
+            if not inspected:
+                return err(f"Machine '{name}' not found")
+            canonical = manager.resolve_name(name)
+            return ok(name=canonical, machine=inspected.to_dict())
+
+        if action == "test":
+            error = require(params, "name")
+            if error:
+                return err(error)
+            name = params["name"]
+            if not isinstance(name, str):
+                return err("name must be a string")
+            return ok(**manager.test_machine(name))
+
+        return err(f"Unknown action: {action}")
+
+    return _handle