@craftsamo/agent-github 0.0.0-stage → 0.2.0

package/src/hermes/agent_github_hermes/settings.py

@@ -0,0 +1,53 @@
+"""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 settings_flags(ctx: PluginContext) -> list[str]:
+    """Read ``toolsets``, ``read_only``, ``tools`` and ``exclude_tools`` and return the flags that say the same.
+
+    A setting that is absent gives no flag, so the command line's own defaults
+    (and ``AGENT_GITHUB_*`` 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]
+
+    return flags

package/src/hermes/agent_github_hermes/skills.py

@@ -0,0 +1,94 @@
+"""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
+
+logger = logging.getLogger(__name__)
+
+SKILL_FILE = "SKILL.md"
+
+#: Skills are named ``github-<topic>``; Hermes already shows the plugin's name before the skill's.
+NAME_PREFIX = "github-"
+
+_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 ``github-``: ``github-issues`` is shown as ``agent-github:issues``."""
+    return name.removeprefix(NAME_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("agent-github: skill %s was not registered: %s", folder.name, error)
+            continue
+        registered.add(name)

package/src/hermes/agent_github_hermes/tools.py

@@ -0,0 +1,85 @@
+"""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 .runtime import CliError, Runtime, agent_cwd
+
+#: How long one call may take, in seconds: above the 120 s the core gives each ``gh`` call.
+RUN_TIMEOUT_SECONDS = 150
+
+#: The toolset name of a tool in ``hermes tools``: the package's toolset after this prefix.
+TOOLSET_PREFIX = "agent-github-"
+
+#: The emoji each toolset is shown with.
+TOOLSET_EMOJI = {
+    "issues": "🎫",
+    "pull_requests": "🔀",
+    "projects": "📋",
+    "repos": "📦",
+    "releases": "🏷️",
+    "actions": "⚙️",
+}
+
+
+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"agent-github-cli 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,
+        )