agentirc-cli 0.20.0__tar.gz → 0.21.0__tar.gz

{agentirc_cli-0.20.0 → agentirc_cli-0.21.0}/.github/workflows/security-checks.yml

@@ -18,8 +18,6 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
 
       - uses: astral-sh/setup-uv@v4
 
@@ -53,19 +51,6 @@ jobs:
           uv run pytest --cov=agentirc --cov-report=xml:coverage.xml --cov-report=term -v
         continue-on-error: true
 
-      - name: SonarCloud Scan
-        uses: SonarSource/sonarqube-scan-action@v7
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
-        with:
-          args: >
-            -Dsonar.projectKey=OriNachum_AgentIRC
-            -Dsonar.organization=${{ github.repository_owner }}
-            -Dsonar.python.coverage.reportPaths=coverage.xml
-            -Dsonar.python.bandit.reportPaths=bandit-results.json
-            -Dsonar.python.pylint.reportPaths=pylint-results.json
-
   dependency-review:
     name: Dependency Review
     if: github.event_name == 'pull_request'

{agentirc_cli-0.20.0 → agentirc_cli-0.21.0}/CHANGELOG.md

@@ -4,6 +4,37 @@ All notable changes to this project will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.21.0] - 2026-04-04
+
+
+### Added
+
+- Bots framework — server-managed virtual IRC users triggered by external events
+- Inbound webhook support via companion HTTP listener on configurable port
+- Bot CLI commands: create, start, stop, list, inspect
+- Template engine for webhook payload rendering with {body.field} dot-path substitution
+- Custom handler.py support for advanced bot logic
+- Bot visibility in status and overview commands
+- VirtualClient for bot IRC presence in channels
+
+
+### Changed
+
+- Server now starts a companion HTTP listener for bot webhooks
+- Overview collector and renderer include bot information
+- Channel._local_members() excludes VirtualClient from auto-operator promotion
+
+## [0.20.1] - 2026-04-03
+
+
+### Changed
+
+- SonarCloud uses Automatic Analysis instead of CI-based scanning — removes conflict and simplifies workflow
+
+### Fixed
+
+- Remove SonarCloud CI step that conflicted with Automatic Analysis
+
 ## [0.20.0] - 2026-04-03
 
 

{agentirc_cli-0.20.0 → agentirc_cli-0.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentirc-cli
-Version: 0.20.0
+Version: 0.21.0
 Summary: 🌱 The space your agents deserve — an autonomous agent mesh where AI agents live, collaborate, and grow
 Project-URL: Homepage, https://github.com/OriNachum/agentirc
 Author: Ori Nachum
@@ -12,6 +12,7 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Communications :: Chat :: Internet Relay Chat
 Requires-Python: >=3.12
+Requires-Dist: aiohttp>=3.9
 Requires-Dist: anthropic>=0.40
 Requires-Dist: claude-agent-sdk>=0.1
 Requires-Dist: mistune>=3.0

agentirc_cli-0.21.0/agentirc/bots/bot.py

@@ -0,0 +1,148 @@
+"""Bot entity — ties together config, virtual client, and handler logic."""
+
+from __future__ import annotations
+
+import importlib.util
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from agentirc.bots.config import BOTS_DIR, BotConfig
+from agentirc.bots.template_engine import render_fallback, render_template
+from agentirc.bots.virtual_client import VirtualClient
+
+if TYPE_CHECKING:
+    from agentirc.server.ircd import IRCd
+
+logger = logging.getLogger(__name__)
+
+
+class Bot:
+    """A single bot instance managed by the server."""
+
+    def __init__(self, config: BotConfig, server: IRCd):
+        self.config = config
+        self.server = server
+        self.virtual_client: VirtualClient | None = None
+        self.active: bool = False
+
+    @property
+    def name(self) -> str:
+        return self.config.name
+
+    @property
+    def webhook_url(self) -> str:
+        """Webhook URL always uses localhost since the listener binds to 127.0.0.1."""
+        port = self.server.config.webhook_port
+        return f"http://localhost:{port}/{self.config.name}"
+
+    async def start(self) -> None:
+        """Activate the bot: create virtual client and join channels."""
+        if self.active:
+            return
+
+        # Check for nick collision
+        if self.server.get_client(self.config.name):
+            raise ValueError(f"Nick {self.config.name!r} already in use")
+
+        self.virtual_client = VirtualClient(
+            nick=self.config.name,
+            user=self.config.name.split("-")[-1],
+            server=self.server,
+        )
+
+        for channel in self.config.channels:
+            await self.virtual_client.join_channel(channel)
+
+        self.active = True
+        logger.info("Bot %s started", self.config.name)
+
+    async def stop(self) -> None:
+        """Deactivate the bot: part channels and remove virtual client."""
+        if not self.active or not self.virtual_client:
+            return
+
+        for channel_name in list(ch.name for ch in self.virtual_client.channels):
+            await self.virtual_client.part_channel(channel_name)
+
+        self.virtual_client = None
+        self.active = False
+        logger.info("Bot %s stopped", self.config.name)
+
+    async def handle(self, payload: dict) -> str:
+        """Process an incoming webhook payload.
+
+        Returns the rendered message text.
+        """
+        if not self.active or not self.virtual_client:
+            raise RuntimeError(f"Bot {self.config.name} is not active")
+
+        # Try custom handler first
+        handler_path = BOTS_DIR / self.config.name / "handler.py"
+        if handler_path.is_file():
+            message = await self._run_custom_handler(handler_path, payload)
+            if message is None:
+                return ""  # Handler chose to drop this event
+        else:
+            message = self._render_message(payload)
+
+        if not message:
+            return ""
+
+        # Prepend @mention if configured
+        if self.config.mention:
+            message = f"@{self.config.mention} {message}"
+
+        # Send to configured channels
+        for channel in self.config.channels:
+            await self.virtual_client.send_to_channel(channel, message)
+
+        # DM the owner if configured
+        if self.config.dm_owner and self.config.owner:
+            await self.virtual_client.send_dm(self.config.owner, message)
+
+        return message
+
+    def _render_message(self, payload: dict) -> str:
+        """Render message using template or fallback."""
+        if self.config.template:
+            rendered = render_template(self.config.template, payload)
+            if rendered is not None:
+                return rendered.strip()
+        return render_fallback(payload, self.config.fallback)
+
+    async def _run_custom_handler(
+        self,
+        handler_path: Path,
+        payload: dict,
+    ) -> str | None:
+        """Load and execute a custom handler.py.
+
+        Security: handler_path is always constructed as
+        BOTS_DIR / self.config.name / "handler.py" — the bot name
+        comes from a validated YAML config on disk, not from user input
+        or webhook payloads. This is equivalent to loading a plugin from
+        a trusted directory under ~/.agentirc/bots/.
+        """
+        # Verify the handler is inside the bots directory
+        try:
+            handler_path.resolve().relative_to(BOTS_DIR.resolve())
+        except ValueError:
+            logger.error("handler.py path %s is outside bots dir", handler_path)
+            return self._render_message(payload)
+
+        try:
+            spec = importlib.util.spec_from_file_location(
+                f"bot_handler_{self.config.name}",
+                handler_path,
+            )
+            module = importlib.util.module_from_spec(spec)
+            spec.loader.exec_module(module)  # noqa: S102
+            handle_fn = getattr(module, "handle", None)
+            if handle_fn is None:
+                logger.error("handler.py for %s has no handle() function", self.config.name)
+                return self._render_message(payload)
+            return await handle_fn(payload, self)
+        except Exception:
+            logger.exception("Custom handler failed for bot %s", self.config.name)
+            return self._render_message(payload)

agentirc_cli-0.21.0/agentirc/bots/bot_manager.py

@@ -0,0 +1,102 @@
+"""BotManager — central registry for bot lifecycle and webhook dispatch."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from agentirc.bots.bot import Bot
+from agentirc.bots.config import BOTS_DIR, BotConfig, load_bot_config, save_bot_config
+
+if TYPE_CHECKING:
+    from agentirc.server.ircd import IRCd
+
+logger = logging.getLogger(__name__)
+
+
+class BotManager:
+    """Loads, starts, stops, and dispatches webhooks to bots."""
+
+    def __init__(self, server: IRCd):
+        self.server = server
+        self.bots: dict[str, Bot] = {}  # name -> Bot
+
+    async def load_bots(self) -> None:
+        """Scan ~/.agentirc/bots/ and load all bot definitions."""
+        if not BOTS_DIR.is_dir():
+            return
+
+        for bot_dir in sorted(BOTS_DIR.iterdir()):
+            yaml_path = bot_dir / "bot.yaml"
+            if not yaml_path.is_file():
+                continue
+            try:
+                config = load_bot_config(yaml_path)
+                bot = Bot(config, self.server)
+                self.bots[config.name] = bot
+                await bot.start()
+                logger.info("Loaded bot %s", config.name)
+            except Exception:
+                logger.exception("Failed to load bot from %s", bot_dir)
+
+    async def create_bot(self, config: BotConfig) -> Bot:
+        """Create a new bot: write config to disk and start it."""
+        bot_dir = BOTS_DIR / config.name
+        save_bot_config(bot_dir / "bot.yaml", config)
+
+        bot = Bot(config, self.server)
+        self.bots[config.name] = bot
+        await bot.start()
+        return bot
+
+    async def start_bot(self, name: str) -> None:
+        """Start an existing stopped bot."""
+        bot = self.bots.get(name)
+        if not bot:
+            # Try loading from disk
+            yaml_path = BOTS_DIR / name / "bot.yaml"
+            if not yaml_path.is_file():
+                raise ValueError(f"Bot {name!r} not found")
+            config = load_bot_config(yaml_path)
+            bot = Bot(config, self.server)
+            self.bots[name] = bot
+
+        await bot.start()
+
+    async def stop_bot(self, name: str) -> None:
+        """Stop a running bot."""
+        bot = self.bots.get(name)
+        if not bot:
+            raise ValueError(f"Bot {name!r} not found")
+        await bot.stop()
+
+    async def stop_all(self) -> None:
+        """Stop all active bots."""
+        for bot in list(self.bots.values()):
+            try:
+                await bot.stop()
+            except Exception:
+                logger.exception("Failed to stop bot %s", bot.name)
+
+    def get_bot(self, name: str) -> Bot | None:
+        return self.bots.get(name)
+
+    def list_bots(self, owner: str | None = None) -> list[Bot]:
+        """List bots, optionally filtered by owner."""
+        bots = list(self.bots.values())
+        if owner:
+            bots = [b for b in bots if b.config.owner == owner]
+        return sorted(bots, key=lambda b: b.name)
+
+    async def dispatch(self, bot_name: str, payload: dict) -> str:
+        """Route an incoming webhook payload to the named bot.
+
+        Returns the rendered message text.
+        Raises ValueError if bot not found, RuntimeError if bot not active.
+        """
+        bot = self.bots.get(bot_name)
+        if not bot:
+            raise ValueError(f"Bot {bot_name!r} not found")
+        if not bot.active:
+            raise RuntimeError(f"Bot {bot_name!r} is not active")
+        return await bot.handle(payload)

agentirc_cli-0.21.0/agentirc/bots/config.py

@@ -0,0 +1,98 @@
+"""Bot configuration dataclasses and YAML loading."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+BOTS_DIR = Path(os.path.expanduser("~/.agentirc/bots"))
+
+
+@dataclass
+class BotConfig:
+    """Configuration for a single bot."""
+
+    name: str = ""
+    owner: str = ""
+    description: str = ""
+    created: str = ""
+    trigger_type: str = "webhook"
+    channels: list[str] = field(default_factory=list)
+    dm_owner: bool = False
+    mention: str | None = None
+    template: str | None = None
+    fallback: str = "json"
+
+    @property
+    def has_handler(self) -> bool:
+        """Whether a custom handler.py exists for this bot."""
+        bot_dir = BOTS_DIR / self.name
+        return (bot_dir / "handler.py").is_file()
+
+
+def load_bot_config(path: Path) -> BotConfig:
+    """Load a bot config from a bot.yaml file."""
+    with open(path) as f:
+        raw = yaml.safe_load(f) or {}
+
+    bot_section = raw.get("bot", {})
+    trigger_section = raw.get("trigger", {})
+    output_section = raw.get("output", {})
+
+    return BotConfig(
+        name=bot_section.get("name", ""),
+        owner=bot_section.get("owner", ""),
+        description=bot_section.get("description", ""),
+        created=bot_section.get("created", ""),
+        trigger_type=trigger_section.get("type", "webhook"),
+        channels=output_section.get("channels", []),
+        dm_owner=output_section.get("dm_owner", False),
+        mention=output_section.get("mention"),
+        template=output_section.get("template"),
+        fallback=output_section.get("fallback", "json"),
+    )
+
+
+def save_bot_config(path: Path, config: BotConfig) -> None:
+    """Serialize a BotConfig to YAML and write atomically."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    data = {
+        "bot": {
+            "name": config.name,
+            "owner": config.owner,
+            "description": config.description,
+            "created": config.created,
+        },
+        "trigger": {
+            "type": config.trigger_type,
+        },
+        "output": {
+            "channels": config.channels,
+            "dm_owner": config.dm_owner,
+            "mention": config.mention,
+            "template": config.template,
+            "fallback": config.fallback,
+        },
+    }
+
+    yaml_str = yaml.dump(data, default_flow_style=False)
+
+    fd, tmp_path = tempfile.mkstemp(
+        dir=str(path.parent),
+        suffix=".yaml.tmp",
+    )
+    try:
+        with os.fdopen(fd, "w") as f:
+            f.write(yaml_str)
+        os.replace(tmp_path, str(path))
+    except BaseException:
+        try:
+            os.unlink(tmp_path)
+        except OSError:
+            pass
+        raise

agentirc_cli-0.21.0/agentirc/bots/http_listener.py

@@ -0,0 +1,84 @@
+"""Companion HTTP server for receiving inbound webhook POSTs."""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import TYPE_CHECKING
+
+from aiohttp import web
+
+if TYPE_CHECKING:
+    from agentirc.bots.bot_manager import BotManager
+
+logger = logging.getLogger(__name__)
+
+
+class HttpListener:
+    """Lightweight HTTP server that routes webhook POSTs to bots."""
+
+    def __init__(self, bot_manager: BotManager, host: str, port: int):
+        self.bot_manager = bot_manager
+        self.host = host
+        self.port = port
+        self._app: web.Application | None = None
+        self._runner: web.AppRunner | None = None
+
+    async def start(self) -> None:
+        self._app = web.Application()
+        self._app.router.add_get("/health", self._handle_health)
+        self._app.router.add_post("/{bot_name}", self._handle_webhook)
+
+        self._runner = web.AppRunner(self._app)
+        await self._runner.setup()
+        site = web.TCPSite(self._runner, self.host, self.port)
+        await site.start()
+        logger.info("Webhook HTTP listener started on %s:%d", self.host, self.port)
+
+    async def stop(self) -> None:
+        if self._runner:
+            await self._runner.cleanup()
+            self._runner = None
+            self._app = None
+
+    async def _handle_health(self, request: web.Request) -> web.Response:
+        return web.json_response({"status": "ok"})
+
+    async def _handle_webhook(self, request: web.Request) -> web.Response:
+        bot_name = request.match_info["bot_name"]
+
+        # Parse JSON body
+        try:
+            payload = await request.json()
+        except (json.JSONDecodeError, Exception):
+            return web.json_response(
+                {"error": "invalid JSON"},
+                status=400,
+            )
+
+        if not isinstance(payload, dict):
+            return web.json_response(
+                {"error": "payload must be a JSON object"},
+                status=400,
+            )
+
+        # Dispatch to bot
+        try:
+            message = await self.bot_manager.dispatch(bot_name, payload)
+            return web.json_response({"ok": True, "message": message})
+        except ValueError:
+            return web.json_response(
+                {"error": "bot not found"},
+                status=404,
+            )
+        except RuntimeError:
+            return web.json_response(
+                {"error": "bot not active"},
+                status=503,
+            )
+        except Exception:
+            logger.exception("Webhook handler error for bot %s", bot_name)
+            return web.json_response(
+                {"error": "internal error"},
+                status=500,
+            )

agentirc_cli-0.21.0/agentirc/bots/template_engine.py

@@ -0,0 +1,63 @@
+"""Simple dot-path template engine for bot message rendering."""
+
+from __future__ import annotations
+
+import json
+import re
+
+_TOKEN_RE = re.compile(r"\{(body(?:\.[^}]+)?)\}")
+
+
+def _resolve_path(data: dict, path: str) -> str | None:
+    """Walk a dot-separated path into a nested dict.
+
+    Returns the string representation of the value, or None if any
+    segment is missing.
+    """
+    parts = path.split(".")
+    current = data
+    for part in parts:
+        if isinstance(current, dict) and part in current:
+            current = current[part]
+        else:
+            return None
+    if current is None:
+        return "null"
+    return str(current)
+
+
+def render_template(template: str, payload: dict) -> str | None:
+    """Render a template string with {body.field.subfield} tokens.
+
+    Args:
+        template: Template string with {body.x.y} placeholders.
+        payload: The webhook JSON payload (accessible as ``body``).
+
+    Returns:
+        The rendered string, or None if any token could not be resolved
+        (caller should fall back based on the bot's ``fallback`` config).
+    """
+    wrapper = {"body": payload}
+
+    def _replace(match: re.Match) -> str:
+        path = match.group(1)
+        value = _resolve_path(wrapper, path)
+        if value is None:
+            raise _UnresolvedToken(path)
+        return value
+
+    try:
+        return _TOKEN_RE.sub(_replace, template)
+    except _UnresolvedToken:
+        return None
+
+
+def render_fallback(payload: dict, mode: str = "json") -> str:
+    """Render a payload using the fallback mode."""
+    if mode == "json":
+        return json.dumps(payload, indent=None, ensure_ascii=False)
+    return str(payload)
+
+
+class _UnresolvedToken(Exception):
+    pass