@craftsamo/signal-tools 0.0.0 → 0.1.0

package/src/hermes/signal_tools_hermes/listing.py

@@ -0,0 +1,75 @@
+"""The tools the command line offers for the current settings."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from . import project
+from .runtime import CliError, Runtime, Unavailable
+
+#: How long ``list`` may take, in seconds.
+LIST_TIMEOUT_SECONDS = 30
+
+#: The write class of a tool that changes nothing.
+READ_CLASS = "read"
+
+#: The fields of a listed tool that are text.
+_TEXT_FIELDS = ("id", "title", "description", "toolset", "class")
+
+
+@dataclass(frozen=True)
+class ToolInfo:
+    """One tool as ``list`` describes it."""
+
+    id: str
+    title: str
+    description: str
+    toolset: str
+    write_class: str
+    input_schema: dict[str, Any]
+
+    @classmethod
+    def from_listing(cls, entry: Any) -> ToolInfo:
+        """Read one element of the ``list`` array.
+
+        Raises:
+            Unavailable: the element lacks a field the plugin needs.
+        """
+        if (
+            not isinstance(entry, dict)
+            or not all(isinstance(entry.get(field), str) for field in _TEXT_FIELDS)
+            or not isinstance(entry.get("input_schema"), dict)
+        ):
+            raise Unavailable(f"{project.CLI_NAME} listed a tool the plugin cannot read: {entry!r}")
+        return cls(
+            id=entry["id"],
+            title=entry["title"],
+            description=entry["description"],
+            toolset=entry["toolset"],
+            write_class=entry["class"],
+            input_schema=entry["input_schema"],
+        )
+
+
+def list_tools(runtime: Runtime, flags: list[str]) -> list[ToolInfo]:
+    """Ask the command line which tools the settings select.
+
+    Raises:
+        Unavailable: the command line failed or answered with something else than a tool list.
+    """
+    try:
+        result = runtime.run(["list", *flags], timeout=LIST_TIMEOUT_SECONDS)
+    except CliError as error:
+        raise Unavailable(str(error)) from error
+    if result.code != 0:
+        detail = result.stderr.strip() or f"exit status {result.code}"
+        raise Unavailable(f"`{project.CLI_NAME} list` failed: {detail}")
+    try:
+        listing = json.loads(result.stdout)
+    except json.JSONDecodeError as error:
+        raise Unavailable(f"`{project.CLI_NAME} list` did not answer with JSON") from error
+    if not isinstance(listing, list):
+        raise Unavailable(f"`{project.CLI_NAME} list` did not answer with a list")
+    return [ToolInfo.from_listing(entry) for entry in listing]

package/src/hermes/signal_tools_hermes/plugin.py

@@ -0,0 +1,36 @@
+"""The plugin's entry point."""
+
+from __future__ import annotations
+
+import logging
+
+from .approval import register_approval
+from .context import PluginContext
+from .listing import list_tools
+from . import project
+from .runtime import Unavailable, locate_runtime
+from .settings import SettingsError, directory_flags, settings_flags
+from .skills import register_skills
+from .tools import register_tools
+
+logger = logging.getLogger(__name__)
+
+
+def register(ctx: PluginContext) -> None:
+    """Register the tools the settings select, the approval hook and the skills.
+
+    The tools run in the package's command line, so node and ``dist/cli.js``
+    must be there and ``list`` must answer. When they are not, or a setting is
+    wrong, this logs one warning and registers nothing; it never raises.
+    """
+    try:
+        runtime = locate_runtime()
+        flags = settings_flags(ctx)
+        tools = list_tools(runtime, flags)
+    except (Unavailable, SettingsError) as error:
+        logger.warning("%s is not available and registers nothing: %s", project.PLUGIN_NAME, error)
+        return
+
+    register_tools(ctx, runtime, tools, flags)
+    register_approval(ctx, runtime, tools, directory_flags(ctx))
+    register_skills(ctx, runtime.skills_dir)

package/src/hermes/signal_tools_hermes/project.py

@@ -0,0 +1,22 @@
+"""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 = "signal-tools"
+
+#: The built command-line name used in error and log messages.
+CLI_NAME = "signal-tools-cli"
+
+#: The prefix skills start with: skills named ``<SKILL_PREFIX><topic>`` are registered without it.
+SKILL_PREFIX = "signal-"
+
+#: The emoji each toolset is shown with; empty by default until a project adds its own.
+TOOLSET_EMOJI: dict[str, str] = {"account": "🪪"}
+
+__all__ = [
+    "CLI_NAME",
+    "PLUGIN_NAME",
+    "SKILL_PREFIX",
+    "TOOLSET_EMOJI",
+]

package/src/hermes/signal_tools_hermes/runtime.py

@@ -0,0 +1,161 @@
+"""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
+from contextlib import suppress
+from dataclasses import dataclass
+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/signal_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(frozen=True)
+class Runtime:
+    """What the plugin needs from its install: node, the built command line and the skills folder."""
+
+    node: str
+    cli: Path
+    skills_dir: Path
+
+    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.
+
+        Raises:
+            CliError: the command line timed out or could not be started.
+        """
+        try:
+            process = subprocess.Popen(
+                [self.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,
+            )
+        except OSError as error:
+            raise CliError(f"{project.CLI_NAME} could not be started: {error}") from error
+        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 _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/signal_tools_hermes/settings.py

@@ -0,0 +1,113 @@
+"""The plugin's settings, turned into the flags of the command line."""
+
+from __future__ import annotations
+
+from typing import Any
+
+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 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 ``SIGNAL_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

package/src/hermes/signal_tools_hermes/skills.py

@@ -0,0 +1,95 @@
+"""Registering the package's skills, which sit in ``skills/<skill>/SKILL.md``."""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+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]*$")
+#: 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`` and ``description`` of a skill's frontmatter; only plain and quoted single-line values count."""
+    match = _FRONTMATTER.match(text)
+    found: dict[str, str] = {}
+    for line in (match.group(1) if match else "").splitlines():
+        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 ``signal-tools:things``."""
+    return name.removeprefix(project.SKILL_PREFIX) or name
+
+
+def register_skills(ctx: PluginContext, skills_dir: Path) -> 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.
+    A skill Hermes refuses is logged and skipped, so it never costs the tools.
+    """
+    if not skills_dir.is_dir():
+        return
+    registered: 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:
+            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/signal_tools_hermes/tools.py

@@ -0,0 +1,79 @@
+"""Registering the tools the command line lists, and running one through it."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from typing import Any
+
+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.
+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>``, 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):
+        return error_result(f"{error['code']}: {error['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."""
+
+    def handler(args: dict[str, Any], **kwargs: Any) -> str:
+        try:
+            result = runtime.run(
+                ["run", tool_id, "--cwd", agent_cwd(), *flags],
+                stdin=json.dumps(args),
+                timeout=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]) -> None:
+    """Register each listed tool under its own ID, grouped in one Hermes toolset per package toolset."""
+    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,
+        )