hermes-irc-extras 0.2.0__tar.gz

hermes_irc_extras-0.2.0/LICENSE

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

hermes_irc_extras-0.2.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: hermes-irc-extras
+Version: 0.2.0
+Summary: Hermes Agent plugin: Additional features and security extensions for the IRC relay (unverified SSL, SASL).
+Author-email: b3nw <b3nw@duck.com>
+License: MIT
+Project-URL: Homepage, https://github.com/b3nw/hermes-irc-extras
+Project-URL: Repository, https://github.com/b3nw/hermes-irc-extras
+Project-URL: Issues, https://github.com/b3nw/hermes-irc-extras/issues
+Project-URL: Changelog, https://github.com/b3nw/hermes-irc-extras/blob/main/CHANGELOG.md
+Keywords: hermes-agent,plugin,irc,relay,ssl,sasl
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: pytest-timeout>=2; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: pyyaml>=6; extra == "dev"
+Dynamic: license-file
+
+# hermes-irc-extras
+
+A plugin for [Hermes Agent](https://hermes-agent.nousresearch.com/) that adds features and security options to the IRC gateway adapter.
+
+The first feature implements an option to **Accept Invalid or Self-Signed TLS Certificates** (`IRC_ALLOW_INVALID_SSL`) for connections to private IRC bouncers (such as ZNC), InspIRCd, or ergo test networks.
+
+The second adds opt-in **passive channel logging** (`IRC_ENABLE_CHANNEL_LOGGING`) so the agent can search channel scrollback without spending a turn on every message it sees.
+
+## Features & Configuration
+
+- **Precedence-Aware:** Environment variables (`IRC_ALLOW_INVALID_SSL`) override `config.yaml` (`allow_invalid_ssl`) parameters.
+- **Defensive Boolean Parsing:** Unquoted or quoted string values in configuration (e.g. `"true"`, `"yes"`, `"1"`, `"false"`, `"0"`, `"no"`) are defensively parsed.
+- **Dynamic UI Integration:** Automatic integration with Hermes WebUI and Desktop UI configuration cards.
+
+### Setup
+
+Configure the option in your `.env` or `config.yaml`:
+
+#### Environment Variables (`.env`)
+```bash
+IRC_ALLOW_INVALID_SSL=true
+```
+
+#### Configuration File (`config.yaml`)
+```yaml
+gateway:
+  platforms:
+    irc:
+      enabled: true
+      server: "irc.mybouncer.internal"
+      port: 6697
+      use_tls: true
+      allow_invalid_ssl: true
+```
+
+## Passive Channel Logging (opt-in, default OFF)
+
+Lets the agent monitor channels and query scrollback **without spending LLM turns on
+messages nobody addressed to it**. Every `PRIVMSG` is written to a local SQLite database
+before the adapter's own addressing/authorization gates run; those gates are unchanged, so
+unaddressed traffic and traffic from users outside `IRC_ALLOWED_USERS` is recorded and then
+dropped — zero agent turns, zero API cost, no reply to the channel.
+
+When enabled, two read-only tools are registered for the agent:
+
+- `search_irc_logs(query, channel?, nick?, hours?, limit?)` — FTS5 keyword/phrase search.
+- `get_channel_history(channel, nick?, hours?, limit?)` — recent chronological scrollback.
+
+```bash
+IRC_ENABLE_CHANNEL_LOGGING=true          # default: false
+IRC_CHANNEL_LOG_DB_PATH=                 # default: {profile}/state/irc_channel_logs.db
+IRC_CHANNEL_LOG_RETENTION_DAYS=14        # 0 keeps everything; pruning is automatic
+```
+
+```yaml
+gateway:
+  platforms:
+    irc:
+      extra:
+        enable_channel_logging: true
+        channel_log_db_path: null
+        channel_log_retention_days: 14
+```
+
+⚠️ **This records other people's conversations.** Enabling it logs every message in the
+channels the bot sits in, including from users who cannot instruct the agent at all — and
+every direct message sent to the bot. Each row keeps the sender's nick and their
+`user@host` (their hostname or cloak) next to the message text, the channel and the
+timestamp; direct messages are filed under the sender's nick and are readable through the
+same two tools. Old rows are pruned on the retention schedule above, and a new database
+file is created with owner-only (`0600`) permissions — but any account that can read the
+profile directory can still read the log. Check local expectations, any network policy and
+any data-protection obligation before turning it on. Nothing is written while the flag is
+off — the database is not even created.
+
+⚠️ **Log contents are untrusted input.** Tool results are framed in the host's
+`<untrusted_tool_result>` data boundary (with the boundary token defanged inside the
+payload) so a passer-by in a logged channel cannot use the log as an indirect
+prompt-injection channel into the agent.
+
+## Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/b3nw/hermes-irc-extras.git ~/.hermes/plugins/hermes-irc-extras
+
+# Install in editable mode
+pip install -e ~/.hermes/plugins/hermes-irc-extras
+```
+
+## Running Tests
+
+```bash
+pip install -e ".[dev]"
+pytest tests/test_irc_extras.py
+```
+
+## Security Warning
+
+⚠️ **Disabling TLS verification leaves the connection vulnerable to Man-in-the-Middle (MITM) attacks.** The traffic remains encrypted but is no longer authenticated. Enable this option only with servers and networks you control.
+
+## License
+
+MIT License — see [LICENSE](LICENSE).

hermes_irc_extras-0.2.0/README.md

@@ -0,0 +1,104 @@
+# hermes-irc-extras
+
+A plugin for [Hermes Agent](https://hermes-agent.nousresearch.com/) that adds features and security options to the IRC gateway adapter.
+
+The first feature implements an option to **Accept Invalid or Self-Signed TLS Certificates** (`IRC_ALLOW_INVALID_SSL`) for connections to private IRC bouncers (such as ZNC), InspIRCd, or ergo test networks.
+
+The second adds opt-in **passive channel logging** (`IRC_ENABLE_CHANNEL_LOGGING`) so the agent can search channel scrollback without spending a turn on every message it sees.
+
+## Features & Configuration
+
+- **Precedence-Aware:** Environment variables (`IRC_ALLOW_INVALID_SSL`) override `config.yaml` (`allow_invalid_ssl`) parameters.
+- **Defensive Boolean Parsing:** Unquoted or quoted string values in configuration (e.g. `"true"`, `"yes"`, `"1"`, `"false"`, `"0"`, `"no"`) are defensively parsed.
+- **Dynamic UI Integration:** Automatic integration with Hermes WebUI and Desktop UI configuration cards.
+
+### Setup
+
+Configure the option in your `.env` or `config.yaml`:
+
+#### Environment Variables (`.env`)
+```bash
+IRC_ALLOW_INVALID_SSL=true
+```
+
+#### Configuration File (`config.yaml`)
+```yaml
+gateway:
+  platforms:
+    irc:
+      enabled: true
+      server: "irc.mybouncer.internal"
+      port: 6697
+      use_tls: true
+      allow_invalid_ssl: true
+```
+
+## Passive Channel Logging (opt-in, default OFF)
+
+Lets the agent monitor channels and query scrollback **without spending LLM turns on
+messages nobody addressed to it**. Every `PRIVMSG` is written to a local SQLite database
+before the adapter's own addressing/authorization gates run; those gates are unchanged, so
+unaddressed traffic and traffic from users outside `IRC_ALLOWED_USERS` is recorded and then
+dropped — zero agent turns, zero API cost, no reply to the channel.
+
+When enabled, two read-only tools are registered for the agent:
+
+- `search_irc_logs(query, channel?, nick?, hours?, limit?)` — FTS5 keyword/phrase search.
+- `get_channel_history(channel, nick?, hours?, limit?)` — recent chronological scrollback.
+
+```bash
+IRC_ENABLE_CHANNEL_LOGGING=true          # default: false
+IRC_CHANNEL_LOG_DB_PATH=                 # default: {profile}/state/irc_channel_logs.db
+IRC_CHANNEL_LOG_RETENTION_DAYS=14        # 0 keeps everything; pruning is automatic
+```
+
+```yaml
+gateway:
+  platforms:
+    irc:
+      extra:
+        enable_channel_logging: true
+        channel_log_db_path: null
+        channel_log_retention_days: 14
+```
+
+⚠️ **This records other people's conversations.** Enabling it logs every message in the
+channels the bot sits in, including from users who cannot instruct the agent at all — and
+every direct message sent to the bot. Each row keeps the sender's nick and their
+`user@host` (their hostname or cloak) next to the message text, the channel and the
+timestamp; direct messages are filed under the sender's nick and are readable through the
+same two tools. Old rows are pruned on the retention schedule above, and a new database
+file is created with owner-only (`0600`) permissions — but any account that can read the
+profile directory can still read the log. Check local expectations, any network policy and
+any data-protection obligation before turning it on. Nothing is written while the flag is
+off — the database is not even created.
+
+⚠️ **Log contents are untrusted input.** Tool results are framed in the host's
+`<untrusted_tool_result>` data boundary (with the boundary token defanged inside the
+payload) so a passer-by in a logged channel cannot use the log as an indirect
+prompt-injection channel into the agent.
+
+## Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/b3nw/hermes-irc-extras.git ~/.hermes/plugins/hermes-irc-extras
+
+# Install in editable mode
+pip install -e ~/.hermes/plugins/hermes-irc-extras
+```
+
+## Running Tests
+
+```bash
+pip install -e ".[dev]"
+pytest tests/test_irc_extras.py
+```
+
+## Security Warning
+
+⚠️ **Disabling TLS verification leaves the connection vulnerable to Man-in-the-Middle (MITM) attacks.** The traffic remains encrypted but is no longer authenticated. Enable this option only with servers and networks you control.
+
+## License
+
+MIT License — see [LICENSE](LICENSE).

hermes_irc_extras-0.2.0/hermes_irc_extras/__init__.py

@@ -0,0 +1,50 @@
+"""hermes-irc-extras — Additional features and security extensions for the IRC relay.
+
+A standalone, fork-free Hermes Agent plugin.
+"""
+
+from __future__ import annotations
+
+import logging
+
+__version__ = "0.2.0"
+
+logger = logging.getLogger(__name__)
+
+
+def register(ctx=None) -> None:
+    """Plugin entry point — called once at startup by the Hermes plugin loader.
+
+    Safely installs the IRC extras monkeypatches onto the core adapter modules
+    without modifying the core files on disk. If the host environment does not
+    support these extensions, logs a warning and exits cleanly without throwing.
+
+    When channel logging is enabled — in the environment or in ``config.yaml``
+    — also registers the log inspection tools so the agent can query scrollback
+    on demand. With logging off (the default) no tools are registered at all.
+    The context is handed to the patch module as well: an adapter whose own
+    config turns logging on can then register the tools itself, late.
+    """
+    from .patches import apply_patches, note_plugin_context
+
+    try:
+        active = apply_patches()
+    except Exception:
+        logger.exception("hermes-irc-extras: unexpected error during initialization")
+        return
+
+    try:
+        from .tools import register_tools
+
+        note_plugin_context(ctx, register_tools(ctx))
+    except Exception:
+        # A tool-registration failure must not cost the host the SSL patches.
+        logger.exception("hermes-irc-extras: failed to register IRC channel log tools")
+
+    if active:
+        logger.info("hermes-irc-extras v%s active", __version__)
+    else:
+        logger.warning(
+            "hermes-irc-extras v%s loaded but INACTIVE (host unavailable "
+            "or unsupported adapter signature)", __version__
+        )