@craftsamo/whatsapp-tools 0.0.0-stage → 0.1.0

package/src/hermes/whatsapp_tools_hermes/project.py

@@ -0,0 +1,47 @@
+"""The plugin's identity and constants that differ between tool packages."""
+
+from __future__ import annotations
+
+#: The plugin's name: used as a log prefix, approval rule key prefix and Hermes toolset prefix.
+PLUGIN_NAME = "whatsapp-tools"
+
+#: The built command-line name used in error and log messages.
+CLI_NAME = "whatsapp-tools-cli"
+
+#: The prefix skills start with: skills named ``<SKILL_PREFIX><topic>`` are registered without it.
+SKILL_PREFIX = "whatsapp-"
+
+#: The emoji each toolset is shown with.
+TOOLSET_EMOJI: dict[str, str] = {
+    "account": "🪪",
+    "chats": "💬",
+    "contacts": "📇",
+    "history": "📜",
+    "files": "📎",
+    "sends": "📤",
+    "actions": "🔧",
+}
+
+#: The settings the tools themselves read, beside the ones every plugin takes: each snake_case name and its type
+#: (``text``, ``boolean``, ``number`` or ``list``), as in ``src/project.ts``. A setting ``a_b`` becomes the flag
+#: ``--a-b`` of the command line.
+OPTIONS: dict[str, str] = {}
+
+#: How long one call of a tool may take, in seconds, for a tool that may take longer than the default.
+#: ``whatsapp_history_backfill`` waits up to 300 seconds for the phone, so it gets a margin above that;
+#: ``whatsapp_file_save`` may wait 150 seconds for WhatsApp's server and then 150 for the phone;
+#: ``whatsapp_file_send`` ends within 280 seconds however many files it sends, and gets the same margin.
+TOOL_TIMEOUT_SECONDS: dict[str, float] = {
+    "whatsapp_history_backfill": 330,
+    "whatsapp_file_save": 330,
+    "whatsapp_file_send": 330,
+}
+
+__all__ = [
+    "CLI_NAME",
+    "OPTIONS",
+    "PLUGIN_NAME",
+    "SKILL_PREFIX",
+    "TOOLSET_EMOJI",
+    "TOOL_TIMEOUT_SECONDS",
+]

package/src/hermes/whatsapp_tools_hermes/runtime.py

@@ -0,0 +1,204 @@
+"""Where the plugin finds node, the command line it calls, and how it runs it."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import signal
+import subprocess
+import threading
+from collections.abc import Callable
+from contextlib import suppress
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from . import project
+
+#: Whether processes have groups the plugin can signal as a whole.
+_POSIX = os.name == "posix"
+
+#: How long a command line that was sent ``SIGTERM`` may keep running before it is sent ``SIGKILL``, in seconds.
+TERMINATE_GRACE_SECONDS = 2
+
+#: The repository root, where ``plugin.yaml`` sits: this file is
+#: ``<root>/src/hermes/whatsapp_tools_hermes/runtime.py``.
+PLUGIN_DIR = Path(__file__).resolve().parents[3]
+
+#: The built command line, relative to ``PLUGIN_DIR``.
+CLI_PATH = Path("dist") / "cli.js"
+
+#: The folder holding ``<skill>/SKILL.md`` files, relative to ``PLUGIN_DIR``.
+SKILLS_PATH = Path("skills")
+
+
+class Unavailable(Exception):
+    """The plugin cannot offer its tools; the message says why, for one log line."""
+
+
+class CliError(Exception):
+    """The command line could not run to its end (it timed out or could not start)."""
+
+
+@dataclass(frozen=True)
+class CliResult:
+    """What a finished command line left behind."""
+
+    code: int
+    stdout: str
+    stderr: str
+
+
+@dataclass
+class Runtime:
+    """What the plugin needs from its install: node, the built command line and the skills folder.
+
+    ``node`` is the path found when the plugin was registered. A version manager names one
+    version in it and may remove that version while Hermes runs, so a call that finds it gone
+    looks for node again with ``find_node`` and keeps what it finds.
+    """
+
+    node: str
+    cli: Path
+    skills_dir: Path
+    find_node: Callable[[], str | None] = field(default=lambda: _find_node(), compare=False, repr=False)
+    _lock: threading.Lock = field(default_factory=threading.Lock, init=False, compare=False, repr=False)
+
+    def run(self, args: list[str], *, stdin: str = "", timeout: float) -> CliResult:
+        """Run ``node <cli> <args>`` with ``stdin`` as its input, without a shell.
+
+        On POSIX the command line leads a process group of its own, which a timeout stops
+        as a whole. When the recorded node is gone, it is looked for again once before the
+        call fails.
+
+        Raises:
+            CliError: the command line timed out or could not be started, or node is gone.
+        """
+        node = self.node
+        try:
+            process = self._start(node, args)
+        except OSError as error:
+            if os.path.exists(node):
+                raise CliError(f"{project.CLI_NAME} could not be started: {error}") from error
+            found = self._find_again(node)
+            if found is None:
+                raise CliError(
+                    f"{project.CLI_NAME} could not be started: node is gone from {node}; install Node.js 24 or later, "
+                    "then restart Hermes from a shell where `node` runs"
+                ) from error
+            try:
+                process = self._start(found, args)
+            except OSError as again:
+                raise CliError(f"{project.CLI_NAME} could not be started: {again}") from again
+        try:
+            stdout, stderr = process.communicate(input=stdin, timeout=timeout)
+        except subprocess.TimeoutExpired as error:
+            _stop(process)
+            raise CliError(f"{project.CLI_NAME} did not finish within {timeout:g} seconds") from error
+        except BaseException:
+            _stop(process)
+            raise
+        return CliResult(process.returncode, stdout, stderr)
+
+    def _start(self, node: str, args: list[str]) -> subprocess.Popen[str]:
+        """Start ``node <cli> <args>`` with its pipes open, leading a process group of its own on POSIX."""
+        return subprocess.Popen(
+            [node, str(self.cli), *args],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            env=dict(os.environ),
+            start_new_session=_POSIX,
+        )
+
+    def _find_again(self, gone: str) -> str | None:
+        """Node found again in place of ``gone``, kept as ``node``; ``None`` when there is no other.
+
+        Calls that find the same node gone at once look for it once: a later one takes what the first kept.
+        """
+        with self._lock:
+            if self.node != gone:
+                return self.node
+            try:
+                found = self.find_node()
+            except Exception:  # a lookup that fails finds nothing
+                found = None
+            if not found or found == gone:
+                return None
+            self.node = found
+            return found
+
+
+def _signal_group(process: subprocess.Popen[str], signal_number: int) -> None:
+    """Send a signal to the child and everything it started, which share the child's process group."""
+    try:
+        os.killpg(process.pid, signal_number)
+    except ProcessLookupError:
+        pass
+
+
+def _stop(process: subprocess.Popen[str]) -> None:
+    """Stop the child and, on POSIX, the whole process group it leads, then collect what it left.
+
+    The group gets ``SIGTERM`` and ``TERMINATE_GRACE_SECONDS`` to end, then ``SIGKILL``, so a
+    child process the command line started does not outlive the call.
+    """
+    try:
+        if _POSIX:
+            _signal_group(process, signal.SIGTERM)
+        else:
+            process.terminate()
+        try:
+            process.communicate(timeout=TERMINATE_GRACE_SECONDS)
+        except subprocess.TimeoutExpired:
+            if _POSIX:
+                _signal_group(process, signal.SIGKILL)
+            else:
+                process.kill()
+            try:
+                process.communicate(timeout=TERMINATE_GRACE_SECONDS)
+            except subprocess.TimeoutExpired:
+                # Something left the group while holding the pipes; do not wait for it, only for the child itself.
+                with suppress(subprocess.TimeoutExpired):
+                    process.wait(timeout=TERMINATE_GRACE_SECONDS)
+    finally:
+        for stream in (process.stdin, process.stdout, process.stderr):
+            if stream is not None:
+                stream.close()
+
+
+def _find_node() -> str | None:
+    """Hermes' own node when it has installed one, else the one on ``PATH``."""
+    try:
+        from hermes_constants import find_node_executable
+
+        node = find_node_executable("node")
+    except Exception:  # any failure of Hermes' lookup falls back to PATH
+        node = None
+    return node or shutil.which("node")
+
+
+def locate_runtime() -> Runtime:
+    """Find node and the built command line.
+
+    Raises:
+        Unavailable: node or ``dist/cli.js`` is missing.
+    """
+    node = _find_node()
+    if node is None:
+        raise Unavailable("node was not found; install Node.js 24 or later")
+    cli = PLUGIN_DIR / CLI_PATH
+    if not cli.is_file():
+        raise Unavailable(f"{cli} is missing; run `pnpm run build` in {PLUGIN_DIR}")
+    return Runtime(node=node, cli=cli, skills_dir=PLUGIN_DIR / SKILLS_PATH)
+
+
+def agent_cwd() -> str:
+    """The directory the agent works in, which relative paths or contextual targets refer to."""
+    try:
+        from agent.runtime_cwd import resolve_agent_cwd
+    except ImportError:
+        return os.getcwd()
+    return str(resolve_agent_cwd())

package/src/hermes/whatsapp_tools_hermes/settings.py

@@ -0,0 +1,171 @@
+"""The plugin's settings, turned into the flags of the command line."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping
+from typing import Any
+
+from . import project
+from .context import PluginContext
+
+#: The value of ``toolsets`` that turns on every toolset.
+ALL_TOOLSETS = "all"
+
+
+class SettingsError(ValueError):
+    """A setting has a value of the wrong type."""
+
+
+def _names(key: str, value: Any) -> str | None:
+    """A list of names as the comma-separated text a flag takes; ``None`` for no names."""
+    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+        raise SettingsError(f'setting "{key}" must be a list of names')
+    return ",".join(value) or None
+
+
+def _directory_flags(ctx: PluginContext, key: str, flag: str) -> list[str]:
+    """Read the directory setting ``key`` and return ``[flag, value]``, or ``[]`` when absent.
+
+    Raises:
+        SettingsError: the setting is present but not a non-empty string.
+    """
+    value = ctx.get_config(key)
+    if value is None:
+        return []
+    if not isinstance(value, str) or not value.strip():
+        raise SettingsError(f'setting "{key}" must be a path')
+    return [flag, value]
+
+
+def state_dir_flags(ctx: PluginContext) -> list[str]:
+    """Read ``state_dir`` and return ``["--state-dir", value]``, or ``[]`` when absent.
+
+    Raises:
+        SettingsError: the setting is present but not a non-empty string.
+    """
+    return _directory_flags(ctx, "state_dir", "--state-dir")
+
+
+def download_dir_flags(ctx: PluginContext) -> list[str]:
+    """Read ``download_dir`` and return ``["--download-dir", value]``, or ``[]`` when absent.
+
+    Raises:
+        SettingsError: the setting is present but not a non-empty string.
+    """
+    return _directory_flags(ctx, "download_dir", "--download-dir")
+
+
+def _is_path_item(item: Any) -> bool:
+    """Whether ``item`` is a non-empty string that survives the flag's comma-separated form whole."""
+    return isinstance(item, str) and bool(item.strip()) and "," not in item
+
+
+def send_dirs_flags(ctx: PluginContext) -> list[str]:
+    """Read ``send_dirs`` and return ``["--send-dirs", "a,b"]``, or ``[]`` when absent or empty.
+
+    The flag is comma-separated, so a path holding a comma is refused rather than split in two.
+
+    Raises:
+        SettingsError: the setting is present but not a list of non-empty strings without commas.
+    """
+    value = ctx.get_config("send_dirs")
+    if value is None:
+        return []
+    if not isinstance(value, list) or not all(_is_path_item(item) for item in value):
+        raise SettingsError('setting "send_dirs" must be a list of paths without commas')
+    return ["--send-dirs", ",".join(value)] if value else []
+
+
+def directory_flags(ctx: PluginContext) -> list[str]:
+    """The flags of the directory settings, which is all the ``target`` command takes."""
+    return state_dir_flags(ctx) + download_dir_flags(ctx) + send_dirs_flags(ctx)
+
+
+def language_setting(ctx: PluginContext) -> str | None:
+    """The ``language`` setting, stripped; ``None`` when it is absent, blank or not a string.
+
+    It is no flag of ``settings_flags``: only ``target`` takes a language.
+    """
+    value = ctx.get_config("language")
+    return (value.strip() or None) if isinstance(value, str) else None
+
+
+def emoji_setting(ctx: PluginContext, defaults: Mapping[str, str] | None = None) -> dict[str, str]:
+    """The emoji per toolset: ``defaults`` (``project.TOOLSET_EMOJI``) with string entries of ``emoji`` merged over it.
+
+    A setting that is not a ``dict``, and an entry whose key or value is not a
+    ``str``, are ignored so a typo never takes every tool away. It is no flag
+    of ``settings_flags``.
+    """
+    merged = dict(project.TOOLSET_EMOJI if defaults is None else defaults)
+    value = ctx.get_config("emoji")
+    if isinstance(value, dict):
+        merged.update({key: item for key, item in value.items() if isinstance(key, str) and isinstance(item, str)})
+    return merged
+
+
+def _option_flag(name: str, kind: str, value: Any) -> list[str]:
+    flag = f"--{name.replace('_', '-')}"
+    if kind == "text":
+        if not isinstance(value, str):
+            raise SettingsError(f'setting "{name}" must be text')
+        return [flag, text] if (text := value.strip()) else []
+    if kind == "boolean":
+        if not isinstance(value, bool):
+            raise SettingsError(f'setting "{name}" must be true or false')
+        return [flag] if value else []
+    if kind == "number":
+        if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
+            raise SettingsError(f'setting "{name}" must be a finite number')
+        return [flag, str(value)]
+    if kind == "list":
+        if not isinstance(value, list) or not all(isinstance(item, str) and "," not in item for item in value):
+            raise SettingsError(f'setting "{name}" must be a list of strings without commas')
+        items = [item.strip() for item in value if item.strip()]
+        return [flag, ",".join(items)] if items else []
+    raise SettingsError(f'unknown option type "{kind}" for "{name}"')
+
+
+def option_flags(ctx: PluginContext, options: Mapping[str, str] | None = None) -> list[str]:
+    """The package's tool options as flags, with absent settings left to the command line's environment."""
+    flags: list[str] = []
+    for name, kind in (project.OPTIONS if options is None else options).items():
+        value = ctx.get_config(name)
+        if value is not None:
+            flags += _option_flag(name, kind, value)
+    return flags
+
+
+def settings_flags(ctx: PluginContext) -> list[str]:
+    """Read the plugin's settings and return the flags that say the same.
+
+    A setting that is absent gives no flag, so the command line's own defaults
+    (and ``WHATSAPP_TOOLS_*`` variables) apply. A wrong type is refused rather
+    than ignored, since ignoring ``read_only`` would loosen what the person asked for.
+
+    Raises:
+        SettingsError: a setting has a value of the wrong type.
+    """
+    flags: list[str] = []
+
+    toolsets = ctx.get_config("toolsets")
+    if toolsets == ALL_TOOLSETS:
+        flags += ["--toolsets", ALL_TOOLSETS]
+    elif toolsets is not None and (names := _names("toolsets", toolsets)):
+        flags += ["--toolsets", names]
+
+    read_only = ctx.get_config("read_only")
+    if read_only is not None and not isinstance(read_only, bool):
+        raise SettingsError('setting "read_only" must be true or false')
+    if read_only:
+        flags.append("--read-only")
+
+    for key, flag in (("tools", "--tools"), ("exclude_tools", "--exclude-tools")):
+        value = ctx.get_config(key)
+        if value is not None and (names := _names(key, value)):
+            flags += [flag, names]
+
+    flags += directory_flags(ctx)
+
+    return [*flags, *option_flags(ctx)]

package/src/hermes/whatsapp_tools_hermes/skills.py

@@ -0,0 +1,131 @@
+"""Registering the package's skills, which sit in ``skills/<skill>/SKILL.md``."""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from collections.abc import Collection
+from pathlib import Path
+
+from .context import PluginContext
+from . import project
+
+logger = logging.getLogger(__name__)
+
+SKILL_FILE = "SKILL.md"
+
+#: Skills are named ``<SKILL_PREFIX><topic>``; Hermes already shows the plugin's name before the skill's.
+NAME_PREFIX = project.SKILL_PREFIX
+
+_FRONTMATTER = re.compile(r"\A---[ \t]*\r?\n((?:.*?\r?\n)?)---[ \t]*(?:\r?\n|\Z)", re.DOTALL)
+_KEY_LINE = re.compile(r"^(name|description)[ \t]*:[ \t]*(.*?)[ \t]*$")
+#: ``metadata:`` with no value (a comment may follow), which opens a block of keys.
+_METADATA_OPEN = re.compile(r"^metadata[ \t]*:(?:[ \t]+#.*)?[ \t]*$")
+#: The ``toolset`` key of a ``metadata`` block, with its raw value.
+_TOOLSET_LINE = re.compile(r"^toolset[ \t]*:[ \t]*(.*?)[ \t]*$")
+#: A comment line; with a blank one, it never ends a ``metadata`` block.
+_COMMENT_LINE = re.compile(r"^[ \t]*#")
+#: Where a YAML value stops being a plain one-line scalar this reader understands.
+_UNSUPPORTED_VALUE_START = re.compile(r"^[>|\[{&*!%@`]")
+_TRAILING_COMMENT = re.compile(r"[ \t]+#.*$")
+#: A quoted scalar with nothing after its closing quote but an optional comment.
+_SINGLE_QUOTED = re.compile(r"^'((?:[^']|'')*)'(?:[ \t]+#.*)?$")
+_DOUBLE_QUOTED = re.compile(r'^"((?:[^"\\]|\\.)*)"(?:[ \t]+#.*)?$')
+
+
+def _unquote(value: str) -> str | None:
+    """The text of a quoted scalar, or ``None`` when it is not a well-formed one."""
+    single = _SINGLE_QUOTED.match(value)
+    if single:
+        return single.group(1).replace("''", "'")
+    double = _DOUBLE_QUOTED.match(value)
+    if not double:
+        return None
+    try:
+        return json.loads(f'"{double.group(1)}"')
+    except json.JSONDecodeError:
+        return None
+
+
+def _scalar(raw: str) -> str | None:
+    """A plain or quoted single-line scalar; anything else (block, flow, anchor, empty) reads as absent."""
+    if raw == "" or _UNSUPPORTED_VALUE_START.match(raw):
+        return None
+    if raw.startswith(('"', "'")):
+        return _unquote(raw)
+    return _TRAILING_COMMENT.sub("", raw).strip() or None
+
+
+def read_frontmatter(text: str) -> dict[str, str]:
+    """The ``name``, ``description`` and ``toolset`` of a skill's frontmatter; only plain and quoted single-line values count.
+
+    ``toolset`` is the skill's link to a toolset, read from ``metadata.toolset``
+    (a ``toolset`` key among the ``metadata`` block's own keys). A top-level
+    ``toolset``, a flow ``metadata: {...}`` and deeper nesting give no link.
+    """
+    match = _FRONTMATTER.match(text)
+    found: dict[str, str] = {}
+    in_metadata = False
+    indent: str | None = None
+    for line in (match.group(1) if match else "").splitlines():
+        if not line.strip() or _COMMENT_LINE.match(line):
+            continue
+        if line[0] in " \t":
+            if not in_metadata:
+                continue
+            if indent is None:
+                indent = line[: len(line) - len(line.lstrip(" \t"))]
+            link = _TOOLSET_LINE.match(line[len(indent) :]) if line.startswith(indent) else None
+            value = _scalar(link.group(1)) if link else None
+            if value is not None:
+                found["toolset"] = value
+            continue
+        in_metadata = bool(_METADATA_OPEN.match(line))
+        indent = None
+        key_line = _KEY_LINE.match(line)
+        value = _scalar(key_line.group(2)) if key_line else None
+        if key_line and value is not None:
+            found[key_line.group(1)] = value
+    return found
+
+
+def short_name(name: str) -> str:
+    """A skill's name without its leading prefix: e.g. ``example-things`` is shown as ``whatsapp-tools:things``."""
+    return name.removeprefix(project.SKILL_PREFIX) or name
+
+
+def register_skills(ctx: PluginContext, skills_dir: Path, toolsets: Collection[str] | None = None) -> None:
+    """Register every ``<skills_dir>/<skill>/SKILL.md``; a missing folder registers nothing.
+
+    A skill is named by its frontmatter ``name`` (its folder's name when it has
+    none). When two folders give the same name, the first in folder order wins,
+    even when that one is left out by ``toolsets``. With ``toolsets`` given, a
+    skill linked to a toolset not in it is not registered; an unlinked skill
+    always is, and ``None`` registers every skill. A skill Hermes refuses is
+    logged and skipped, so it never costs the tools nor claims its name.
+    """
+    if not skills_dir.is_dir():
+        return
+    registered: set[str] = set()
+    filtered: set[str] = set()
+    for folder in sorted(path for path in skills_dir.iterdir() if path.is_dir()):
+        path = folder / SKILL_FILE
+        try:
+            text = path.read_text(encoding="utf-8-sig")
+        except OSError:
+            continue
+        found = read_frontmatter(text)
+        name = short_name(found.get("name", folder.name))
+        if name in registered or name in filtered:
+            continue
+        link = found.get("toolset")
+        if toolsets is not None and link is not None and link not in toolsets:
+            filtered.add(name)
+            continue
+        try:
+            ctx.register_skill(name, path, description=found.get("description", ""))
+        except (ValueError, OSError) as error:
+            logger.warning("%s: skill %s was not registered: %s", project.PLUGIN_NAME, folder.name, error)
+            continue
+        registered.add(name)

package/src/hermes/whatsapp_tools_hermes/tools.py

@@ -0,0 +1,97 @@
+"""Registering the tools the command line lists, and running one through it."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable, Mapping
+from typing import Any
+
+from .approval import PIN_ARGUMENT, parse_pin, run_arguments
+from .context import PluginContext
+from .listing import ToolInfo
+from . import project
+from .runtime import CliError, Runtime, agent_cwd
+
+#: How long one call may take, in seconds: a ceiling above what a tool call is expected to take.
+#: ``project.TOOL_TIMEOUT_SECONDS`` gives a longer one to the tools that need it.
+RUN_TIMEOUT_SECONDS = 150
+
+#: The toolset name of a tool in ``hermes tools``: the package's toolset after this prefix.
+TOOLSET_PREFIX = f"{project.PLUGIN_NAME}-"
+
+#: The emoji each toolset is shown with.
+TOOLSET_EMOJI = project.TOOLSET_EMOJI
+
+
+def error_result(message: str) -> str:
+    """The JSON a failed call returns to the model."""
+    return json.dumps({"error": message})
+
+
+def _read_document(stdout: str) -> dict[str, Any] | None:
+    """The JSON object a command line wrote, or ``None`` when it wrote something else."""
+    try:
+        document = json.loads(stdout)
+    except json.JSONDecodeError:
+        return None
+    return document if isinstance(document, dict) else None
+
+
+def _failure(code: int, stdout: str, stderr: str) -> str:
+    """The error result of a command line that did not succeed: its ``<code>: <message>`` and details line, or its stderr."""
+    error = (_read_document(stdout) or {}).get("error")
+    if isinstance(error, dict) and isinstance(error.get("code"), str) and isinstance(error.get("message"), str):
+        message = f"{error['code']}: {error['message']}"
+        details = error.get("details")
+        if isinstance(details, dict):
+            message = f"{message}\n" + json.dumps(details, ensure_ascii=False, separators=(",", ":"))
+        return error_result(message)
+    detail = stderr.strip() or f"exit status {code}"
+    return error_result(f"{project.CLI_NAME} failed: {detail}")
+
+
+def make_handler(runtime: Runtime, tool_id: str, flags: list[str]) -> Callable[..., str]:
+    """The handler Hermes calls for one tool: it takes the arguments as one dict and never raises.
+
+    The pin the pin hook set (``PIN_ARGUMENT``) is taken out of the arguments and, when it is a
+    pin, passed to ``run`` as ``--pin``; anything else runs as if there were none.
+    """
+
+    def handler(args: dict[str, Any], **kwargs: Any) -> str:
+        try:
+            pin = parse_pin(args.get(PIN_ARGUMENT))
+            result = runtime.run(
+                ["run", tool_id, "--cwd", agent_cwd(), *flags, *([f"--pin={pin}"] if pin else [])],
+                stdin=json.dumps(run_arguments(args)),
+                timeout=project.TOOL_TIMEOUT_SECONDS.get(tool_id, RUN_TIMEOUT_SECONDS),
+            )
+        except CliError as error:
+            return error_result(str(error))
+        except Exception as error:  # a tool call must reach the model as a result, whatever went wrong
+            return error_result(f"{tool_id} could not run: {error}")
+        document = _read_document(result.stdout)
+        if result.code == 0 and document is not None and "result" in document:
+            return result.stdout.strip()
+        return _failure(result.code, result.stdout, result.stderr)
+
+    return handler
+
+
+def register_tools(
+    ctx: PluginContext,
+    runtime: Runtime,
+    tools: list[ToolInfo],
+    flags: list[str],
+    emoji: Mapping[str, str] | None = None,
+) -> None:
+    """Register each listed tool under its own ID, grouped in one Hermes toolset per package toolset."""
+    toolset_emoji = TOOLSET_EMOJI if emoji is None else emoji
+    for tool in tools:
+        ctx.register_tool(
+            name=tool.id,
+            toolset=TOOLSET_PREFIX + tool.toolset.replace("_", "-"),
+            schema={"name": tool.id, "description": tool.description, "parameters": tool.input_schema},
+            handler=make_handler(runtime, tool.id, flags),
+            emoji=toolset_emoji.get(tool.toolset, ""),
+            description=tool.title,
+        )