@craftsamo/telegram-tools 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@craftsamo/telegram-tools",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Unofficial Telegram tools for coding agents: chats, messages, received files and sends.",
   "author": "craftsamo",
   "license": "LicenseRef-AGPL-3.0-Commons-Clause",

package/plugin.yaml

@@ -1,5 +1,5 @@
 name: telegram-tools
-version: 0.2.0
+version: 0.3.0
 description: "Unofficial Telegram tools for coding agents: chats, messages, received files and sends."
 manifest_version: 1
 requires_hermes: ">=0.22"
@@ -32,15 +32,15 @@ config_schema:
     type: list
     description: Single tools to remove by id. Wins over tools and toolsets.
   state_dir:
-    description: "Where every label's state lives; an absolute path, or one starting with ~. Defaults to $XDG_STATE_HOME/telegram-tools, or ~/.local/state/telegram-tools."
+    description: "Where every label's state lives; an absolute path, or one starting with ~. Blank means unset. Defaults to $XDG_STATE_HOME/telegram-tools when XDG_STATE_HOME is absolute, else ~/.local/state/telegram-tools."
   download_dir:
-    description: "Where received files are saved; an absolute path, or one starting with ~. Defaults to ~/Downloads/telegram-tools. Read by tools; no service restart needed."
+    description: "Where received files are saved; an absolute path, or one starting with ~. Blank means unset. Defaults to ~/Downloads/telegram-tools. Read by tools; no service restart needed."
   download_max_mb:
     type: int
     description: "The largest file a download takes, in MB; an integer from 1 to 2000, default 100. Read by tools; no service restart needed."
   send_dirs:
     type: list
-    description: "The directories files may be sent from, besides the working directory; absolute paths, or ones starting with ~, without commas. Defaults to none. Read by tools; no service restart needed."
+    description: "The directories files may be sent from, besides the working directory; absolute paths, or ones starting with ~, without commas. Blank items are dropped. Defaults to none. Read by tools; no service restart needed."
   keep_disappearing:
     type: bool
     description: Keeps disappearing and view-once messages for the user; off by default. Read by the sync service.
@@ -49,3 +49,6 @@ config_schema:
     description: Lets the mirror list channels; off by default. Read by the sync service.
   language:
     description: The language of the approval card, such as ja. Defaults to Hermes's display language, else English.
+  emoji:
+    type: dict
+    description: 'The emoji shown beside each toolset, by toolset name; "" shows none. Merged over the package''s emoji.'

package/src/hermes/telegram_tools_hermes/approval.py

@@ -155,15 +155,15 @@ def resolve_target(
     runtime: Runtime,
     tool_id: str,
     args: Any,
-    flags: list[str] | None = None,
     language: str | None = None,
     harness_language: Callable[[], str | None] = lambda: display_language(),
+    option_flags: list[str] | None = None,
 ) -> Target:
     """What ``target`` prints: ``["*"]`` for resources that cannot be told, no description for one absent or bad.
 
-    ``flags`` are the same settings flags ``run`` gets, so ``target`` resolves the call as ``run`` will.
     ``language`` is the plugin's ``language`` setting and ``harness_language`` reads Hermes' display language
-    per call; neither may fail the run, and ``target`` picks among them.
+    per call; neither may fail the run, and ``target`` picks among them. ``option_flags`` are the package's
+    own tool options as ``run`` gets them, so ``target`` resolves the call as ``run`` will.
     """
     try:
         result = runtime.run(
@@ -172,8 +172,8 @@ def resolve_target(
                 tool_id,
                 "--cwd",
                 agent_cwd(),
-                *(flags or []),
                 *language_flags(language, _known(harness_language)),
+                *(option_flags or []),
             ],
             stdin=json.dumps(run_arguments(args)),
             timeout=TARGET_TIMEOUT_SECONDS,
@@ -222,20 +222,21 @@ def _message(tool: ToolInfo, target: Target, surface: Callable[[], str | None])
 def make_hook(
     runtime: Runtime,
     tools: list[ToolInfo],
-    flags: list[str] | None = None,
     surface: Callable[[], str | None] = lambda: None,
     language: str | None = None,
     harness_language: Callable[[], str | None] = lambda: display_language(),
     pins: PinStash | None = None,
+    option_flags: list[str] | None = None,
 ) -> Callable[..., dict[str, str] | None]:
     """The ``pre_tool_call`` hook: it sends every call of these tools but a read to the person's approval.
 
     Whether a person is there to ask, and what happens when none is, is
-    Hermes' own gate to decide. ``flags`` are the same settings flags ``run``
-    gets, so ``target`` resolves the call as ``run`` will. ``language`` is the
-    plugin's ``language`` setting; ``harness_language`` is read on every call.
-    When ``pins`` is given, the pin ``target`` answered is kept in it under the
-    call's ``pin_key`` for the pin hook; the decision is the same either way.
+    Hermes' own gate to decide. ``language`` is the plugin's ``language``
+    setting; ``harness_language`` is read on every call. ``option_flags`` are
+    the package's own tool options as ``run`` gets them, so ``target`` resolves
+    the call as ``run`` will. When ``pins`` is given, the pin ``target``
+    answered is kept in it under the call's ``pin_key`` for the pin hook; the
+    decision is the same either way.
     """
     by_id = {tool.id: tool for tool in tools}
 
@@ -243,7 +244,7 @@ def make_hook(
         tool = by_id.get(tool_name)
         if tool is None or tool.write_class == READ_CLASS:
             return None
-        target = resolve_target(runtime, tool.id, args, flags, language, harness_language)
+        target = resolve_target(runtime, tool.id, args, language, harness_language, option_flags)
         call = pin_key(kwargs)
         if pins is not None and call is not None:
             # An entry left by a call that never reached the pin hook must not stand for this one.
@@ -304,12 +305,13 @@ def register_approval(
     ctx: PluginContext,
     runtime: Runtime,
     tools: list[ToolInfo],
-    flags: list[str] | None = None,
     language: str | None = None,
+    option_flags: list[str] | None = None,
 ) -> None:
     """Hold every non-read call of ``tools`` for approval, with the card in ``language`` (the plugin's setting).
 
-    ``flags`` are the same settings flags ``run`` gets, so ``target`` resolves the call as ``run`` will.
+    ``option_flags`` are the package's own tool options as ``run`` gets them, so ``target`` resolves the call as
+    ``run`` will.
 
     Two hooks, in this order, since Hermes runs them in registration order: the approval hook
     stashes the pin of what the card shows, then the pin hook gives it to the call.
@@ -317,6 +319,8 @@ def register_approval(
     pins = PinStash()
     ctx.register_hook(
         HOOK_NAME,
-        make_hook(runtime, tools, flags, surface=lambda: session_surface(ctx), language=language, pins=pins),
+        make_hook(
+            runtime, tools, surface=lambda: session_surface(ctx), language=language, pins=pins, option_flags=option_flags
+        ),
     )
     ctx.register_hook(HOOK_NAME, make_pin_hook(tools, pins))

package/src/hermes/telegram_tools_hermes/plugin.py

@@ -9,7 +9,7 @@ from .context import PluginContext
 from .listing import list_tools
 from . import project
 from .runtime import Unavailable, locate_runtime
-from .settings import SettingsError, language_setting, settings_flags
+from .settings import SettingsError, emoji_setting, language_setting, option_flags, settings_flags
 from .skills import register_skills
 from .tools import register_tools
 
@@ -33,6 +33,6 @@ def register(ctx: PluginContext) -> None:
         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, flags, language_setting(ctx))
+    register_tools(ctx, runtime, tools, flags, emoji_setting(ctx))
+    register_approval(ctx, runtime, tools, language_setting(ctx), option_flags(ctx))
     register_skills(ctx, runtime.skills_dir, {tool.toolset for tool in tools})

package/src/hermes/telegram_tools_hermes/project.py

@@ -21,8 +21,14 @@ TOOLSET_EMOJI: dict[str, str] = {
     "actions": "🔧",
 }
 
+#: The settings the tools themselves read: each snake_case name and a type (``text``, ``boolean``, ``number``,
+#: ``list``, ``path`` or ``paths``) or a dict with ``type`` and optional bounds (``integer``, ``min``, ``max``),
+#: as in ``src/project.ts``. Write OPTIONS on one line with double quotes. A setting ``a_b`` becomes ``--a-b``.
+OPTIONS: dict[str, str | dict[str, object]] = {"state_dir": "path", "download_dir": "path", "download_max_mb": {"type": "number", "integer": True, "min": 1, "max": 2000}, "send_dirs": "paths", "keep_disappearing": "boolean", "channels": "boolean"}
+
 __all__ = [
     "CLI_NAME",
+    "OPTIONS",
     "PLUGIN_NAME",
     "SKILL_PREFIX",
     "TOOLSET_EMOJI",

package/src/hermes/telegram_tools_hermes/settings.py

@@ -2,13 +2,15 @@
 
 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"
-MAX_DOWNLOAD_MB = 2000
 
 
 class SettingsError(ValueError):
@@ -22,41 +24,6 @@ def _names(key: str, value: Any) -> str | None:
     return ",".join(value) or None
 
 
-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.
-    """
-    state_dir = ctx.get_config("state_dir")
-    if state_dir is None:
-        return []
-    if not isinstance(state_dir, str) or not state_dir.strip():
-        raise SettingsError('setting "state_dir" must be a path')
-    return ["--state-dir", state_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 language_setting(ctx: PluginContext) -> str | None:
     """The ``language`` setting, stripped; ``None`` when it is absent, blank or not a string.
 
@@ -66,6 +33,58 @@ def language_setting(ctx: PluginContext) -> str | None:
     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, declaration: str | dict[str, object], value: Any) -> list[str]:
+    kind = declaration["type"] if isinstance(declaration, dict) else declaration
+    flag = f"--{name.replace('_', '-')}"
+    if kind in ("text", "path"):
+        if not isinstance(value, str):
+            expected = "a path" if kind == "path" else "text"
+            raise SettingsError(f'setting "{name}" must be {expected}')
+        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 in ("list", "paths"):
+        if not isinstance(value, list) or not all(isinstance(item, str) and "," not in item for item in value):
+            expected = "paths" if kind == "paths" else "strings"
+            raise SettingsError(f'setting "{name}" must be a list of {expected} 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 | dict[str, object]] | None = None) -> list[str]:
+    """The package's tool options as flags, with absent settings left to the command line's environment.
+
+    Bounds and path absoluteness are checked by the command line, not here.
+    """
+    flags: list[str] = []
+    for name, declaration in (project.OPTIONS if options is None else options).items():
+        value = ctx.get_config(name)
+        if value is not None:
+            flags += _option_flag(name, declaration, value)
+    return flags
+
+
 def settings_flags(ctx: PluginContext) -> list[str]:
     """Read the plugin's settings and return the flags that say the same.
 
@@ -84,36 +103,15 @@ def settings_flags(ctx: PluginContext) -> list[str]:
     elif toolsets is not None and (names := _names("toolsets", toolsets)):
         flags += ["--toolsets", names]
 
-    for key, flag in (
-        ("read_only", "--read-only"),
-        ("keep_disappearing", "--keep-disappearing"),
-        ("channels", "--channels"),
-    ):
-        value = ctx.get_config(key)
-        if value is not None and not isinstance(value, bool):
-            raise SettingsError(f'setting "{key}" must be true or false')
-        if value:
-            flags.append(flag)
+    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 += state_dir_flags(ctx)
-
-    download_dir = ctx.get_config("download_dir")
-    if download_dir is not None:
-        if not isinstance(download_dir, str) or not download_dir.strip():
-            raise SettingsError('setting "download_dir" must be a path')
-        flags += ["--download-dir", download_dir]
-
-    download_max_mb = ctx.get_config("download_max_mb")
-    if download_max_mb is not None:
-        if type(download_max_mb) is not int or not 1 <= download_max_mb <= MAX_DOWNLOAD_MB:
-            raise SettingsError(f'setting "download_max_mb" must be an integer from 1 to {MAX_DOWNLOAD_MB}')
-        flags += ["--download-max-mb", str(download_max_mb)]
-
-    flags += send_dirs_flags(ctx)
-
-    return flags
+    return [*flags, *option_flags(ctx)]

package/src/hermes/telegram_tools_hermes/tools.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import json
-from collections.abc import Callable
+from collections.abc import Callable, Mapping
 from typing import Any
 
 from .approval import PIN_ARGUMENT, parse_pin, run_arguments
@@ -76,14 +76,21 @@ def make_handler(runtime: Runtime, tool_id: str, flags: list[str]) -> Callable[.
     return handler
 
 
-def register_tools(ctx: PluginContext, runtime: Runtime, tools: list[ToolInfo], flags: list[str]) -> None:
+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, ""),
+            emoji=toolset_emoji.get(tool.toolset, ""),
             description=tool.title,
         )