agentirc-cli 6.2.2__tar.gz → 7.0.4__tar.gz

agentirc_cli-7.0.4/.claude/agents/doc-test-alignment.md

@@ -0,0 +1,154 @@
+---
+name: doc-test-alignment
+description: Audits a staged/branch diff for new public API surface (exceptions, classes, public functions, CLI commands, IRC protocol verbs, backend config fields) and reports whether `docs/` and `protocol/extensions/` mention them. Use at the end of a plan, before the first push, or when the user says "doc audit", "doc-test alignment", "check docs coverage".
+tools: Read, Grep, Glob, Bash
+model: sonnet
+color: cyan
+---
+
+# Doc-Test Alignment Auditor
+
+You audit a code change for **doc drift**: new public API surface that
+`docs/` doesn't mention. Run at the end of a plan (after tests pass, before
+push). Your job is to surface omissions, not to write docs.
+
+## Step 1 — Determine the diff
+
+If the caller passed a specific ref or file list, use that. Otherwise, audit
+the current branch against `main`:
+
+```bash
+git diff --name-only main...HEAD
+git diff main...HEAD -- '*.py' 'culture/cli/*' 'culture/agentirc/*'
+```
+
+If the branch has no commits ahead of `main`, fall back to staged changes:
+
+```bash
+git diff --cached --name-only
+git diff --cached -- '*.py'
+```
+
+If neither yields a diff, report "no changes to audit" and stop.
+
+## Step 2 — Extract new public API surface
+
+Run the patterns via the **Grep tool** (ripgrep / Rust regex engine — the
+Claude Code default). Patterns below are written in the Rust regex flavor
+that ripgrep accepts without any extra flags: `\s`, `(?:...)`, and character
+classes all work as written. Do **not** pipe these into POSIX `grep` / BRE
+— they will silently fail to match.
+
+Save the diff first, then search it:
+
+```bash
+git diff main...HEAD -- '*.py' 'culture/cli/*' 'culture/agentirc/*' > /tmp/branch-diff.patch
+```
+
+Then feed `/tmp/branch-diff.patch` to the Grep tool with each pattern below.
+
+| Surface type | Ripgrep pattern |
+|--------------|-----------------|
+| New exception class | `^\+class [A-Z][A-Za-z0-9_]*(\(.*(?:Error\|Exception).*\))?:` |
+| New public class | `^\+class [A-Z][A-Za-z0-9_]*` (exclude leading `_`) |
+| New public function | `^\+(async )?def [a-z][a-z0-9_]*\(` (exclude leading `_`) |
+| New CLI command | `^\+.*add_parser\(['"]` in `culture/cli/` |
+| New IRC verb | `^\+.*(_msg_handlers\[['"]\|commands\s*=).*['"][A-Z0-9]+['"]` |
+| New config field | `^\+.*@dataclass` or `^\+\s+[a-z_]+:\s+[A-Z].*=` in config modules |
+
+Ignore private symbols (leading `_`), test helpers (inside `tests/`), and
+internal-only classes (docstring contains "internal" or "private").
+
+List every match with:
+
+- symbol name
+- file path + starting line
+- kind (exception / class / function / CLI command / IRC verb / config field)
+
+## Step 3 — Check doc coverage
+
+For each extracted symbol, grep the documentation tree for a mention:
+
+```bash
+grep -r -l '<symbol>' docs/ protocol/extensions/ 2>/dev/null
+```
+
+Match rules:
+
+- **Exception**: must be referenced in at least one `docs/**/*.md` page. If
+  it's a new public exception raised across module boundaries, that's a
+  stronger obligation — flag loudly.
+- **CLI command**: must appear in `docs/` (user-facing command reference)
+  AND in the command's own module docstring.
+- **IRC verb / protocol extension**: MUST have a page under
+  `protocol/extensions/` (per the repository-root `CLAUDE.md`: "Extensions
+  use new verbs (never redefine existing commands), documented in
+  `protocol/extensions/`").
+- **Config field**: must appear in the relevant backend's `culture.yaml`
+  reference under `packages/agent-harness/culture.yaml` or
+  `docs/configuration.md`.
+- **Public function/class**: soft obligation — flag if the symbol is
+  imported from outside its module, skip if it's used only within its
+  package.
+
+## Step 4 — Check test coverage (light)
+
+For each public surface symbol, grep `tests/` for at least one reference:
+
+```bash
+grep -r -l '<symbol>' tests/ 2>/dev/null
+```
+
+If zero test files reference the symbol, flag it. This is a weak signal —
+the caller may have tested behavior without naming the symbol directly.
+Report as "likely untested" rather than "untested".
+
+## Step 5 — All-backends check (culture-specific)
+
+If the diff touches `culture/clients/<backend>/` OR `packages/agent-harness/`,
+list the other backends (`claude`, `codex`, `copilot`, `acp`) and report
+whether the same change appears in each. This enforces the project's
+"all-backends rule" (per the repository-root `CLAUDE.md`). A change in
+only one backend is a bug.
+
+## Step 6 — Report
+
+Output a concise table. Factual only: what symbols, what's missing,
+what's drifted. Do **not** write prose narration and do **not** suggest
+what the docs should say — leave doc wording to the caller. A brief
+counts-only summary line at the end is fine; skip it if everything is
+clean.
+
+```text
+## Doc-Test Alignment — <branch> vs main
+
+### New public API surface
+| Symbol | Kind | Location | Docs | Tests |
+|--------|------|----------|------|-------|
+| ConsoleConnectionLost | exception | culture/console/client.py:42 | MISSING | test_console_client.py |
+| _handle_reconnect | private | culture/console/app.py:412 | (skip — private) | — |
+
+### Protocol extensions
+(none in this diff)
+
+### All-backends drift
+Change touches `packages/agent-harness/irc_transport.py`:
+- claude: ✓ updated
+- codex: ✓ updated
+- copilot: ✗ NOT updated (divergent)
+- acp: ✗ NOT updated (divergent)
+
+### Summary
+Doc gaps: 1 · Likely untested: 0 · Backend drift: 2
+```
+
+If nothing is missing, output one line: `Doc-test alignment clean — no gaps detected.`
+
+## What NOT to do
+
+- Do not write documentation. Report gaps only.
+- Do not modify code or tests.
+- Do not fail loudly on borderline cases (internal-only helpers, test
+  utilities) — the caller is smarter than the heuristics; your value is in
+  catching the obvious omissions.
+- Do not re-run the test suite — `/run-tests` is the tool for that.

{agentirc_cli-6.2.2 → agentirc_cli-7.0.4}/.claude/skills/pr-review/SKILL.md

@@ -171,7 +171,15 @@ bash ~/.claude/skills/pr-review/scripts/pr-reply.sh --resolve <PR_NUMBER> <COMME
 - Always use `--resolve` to resolve the thread after replying
 - Every comment must get a reply — no silent fixes
 
-## Step 9 — Wait for merge
+## Step 9 — Check SonarCloud before declaring ready
+
+After CI is green and all inline threads are resolved, query SonarCloud
+for the branch via the `/sonarclaude` skill. SonarCloud findings do not
+always arrive as inline PR comments — a fully-resolved thread list plus an
+all-green `gh pr checks` is **not** sufficient evidence that the PR is
+clean. If `/sonarclaude` surfaces new findings, loop back to Step 7.
+
+## Step 10 — Wait for merge
 
 **Never merge the PR yourself.** The PR is merged manually on the GitHub site.
 

{agentirc_cli-6.2.2 → agentirc_cli-7.0.4}/.github/workflows/security-checks.yml

@@ -33,7 +33,7 @@ jobs:
         continue-on-error: true
 
       - name: Run Safety dependency check
-        run: uv run safety check --full-report --output json > safety-results.json
+        run: uv run safety check --output json > safety-results.json
         continue-on-error: true
 
       - name: Upload Security Results

{agentirc_cli-6.2.2 → agentirc_cli-7.0.4}/CHANGELOG.md

@@ -4,6 +4,93 @@ All notable changes to this project will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [7.0.4] - 2026-04-17
+
+
+### Fixed
+
+- Reduce cognitive complexity and fix code quality issues across CLI modules (SonarCloud S3776, S1192, S5886, S108)
+
+## [7.0.3] - 2026-04-17
+
+
+### Fixed
+
+- Duplicate _ERR_CHANNEL_PREFIX string in all 5 daemon files (S1192)
+- Cognitive complexity in claude/daemon.py _poll_loop (CC 22, S3776)
+- Cognitive complexity in agent-harness/daemon.py _poll_loop (CC 22, S3776)
+- Cognitive complexity in codex/daemon.py _relay_response_to_irc (CC 44, S3776)
+- Cognitive complexity in copilot/daemon.py _relay_response_to_irc (CC 23, S3776)
+- Cognitive complexity in acp/daemon.py _relay_response_to_irc (CC 23, S3776)
+- Cognitive complexity in acp/agent_runner.py start() (CC 17, S3776)
+
+## [7.0.2] - 2026-04-17
+
+
+### Fixed
+
+- Cognitive complexity in observer.py (CC 22→~13)
+- Cognitive complexity in ircd.py (CC 18→~12)
+- Cognitive complexity in server_link.py (CC 33→~14)
+
+## [7.0.1] - 2026-04-17
+
+
+### Fixed
+
+- Wrong AgentConfig/DaemonConfig import types in test helpers (S5655)
+- Constant if-False condition replaced with unreachable yield pattern (S5797)
+
+## [7.0.0] - 2026-04-17
+
+Mesh Events (issue #123) — lifecycle and activity notifications as IRCv3-tagged
+PRIVMSGs, event-triggered bots, and pub/sub composition chains.
+
+> Versions 6.3.0 through 6.11.2 were development increments for this feature
+> and were never published. Their changes are consolidated here as 7.0.0.
+
+### Breaking Changes
+
+None. Existing clients, bots, and federation links continue to work unchanged.
+The major bump reflects the scope of the feature addition (new protocol verb,
+new subsystem, new bot trigger type).
+
+### Added
+
+- **Event system** — `system-<server>` pseudo-user surfaces lifecycle events
+  as IRCv3-tagged PRIVMSGs with `@event=<type>;event-data=<b64json>` tags
+- **Built-in event catalog** — 18 event types across channel-scoped
+  (`user.join/part/quit`, `room.create/archive/meta`, `tags.update`) and global
+  (`agent.connect/disconnect`, `server.wake/sleep/link/unlink`,
+  `console.open/close`)
+- **IRCv3 message-tags** — `Message.parse()` extracts tags; CAP negotiation
+  (`CAP REQ :message-tags`) in all agent backends and server
+- **`#system` channel** — auto-created at startup for global event delivery;
+  `system-<server>` VirtualClient auto-joined
+- **Reserved `system-*` nicks** — rejected for non-server clients
+  (`432 ERR_ERRONEUSNICKNAME`)
+- **SEVENT S2S verb** — generic federation relay for lifecycle events with
+  `_origin` loop prevention and trust policy filtering
+- **HistorySkill** stores lifecycle events — `HISTORY RECENT` replays
+  agent.connect, server.wake, room.create, etc.
+- **Filter DSL** — safe recursive-descent expression parser (`==`, `!=`, `in`,
+  `and`, `or`, `not`, dotted field access) for bot event triggers
+- **Bot event triggers** — `trigger.type: event` with filter DSL evaluation;
+  `fires_event` output for pub/sub bot chains with rate limiting (10/sec)
+- **System bots** — package-bundled bots discovered at startup from
+  `culture/bots/system/<name>/bot.yaml`; welcome bot greets on `user.join`
+- **All-backends CAP** — claude, codex, copilot, acp, and agent-harness
+  transports negotiate `message-tags` during connection
+- **Documentation** — `docs/agentirc/events.md`, `docs/agentirc/bots.md`,
+  `culture/protocol/extensions/events.md`
+
+## [6.2.3] - 2026-04-15
+
+
+### Changed
+
+- docs: post-#231 retrospective — CLAUDE.md guidance for pre-branch checklist, format-before-commit, pre-push code review, SonarCloud pre-ready; new doc-test-alignment subagent; /pr-review skill step for SonarCloud query
+
 ## [6.2.2] - 2026-04-14
 
 

{agentirc_cli-6.2.2 → agentirc_cli-7.0.4}/CLAUDE.md

@@ -49,13 +49,18 @@ Each backend has its own `culture.yaml` in `culture/clients/<backend>/`.
 
 When implementing features, write a corresponding markdown doc in `docs/` describing the feature — its purpose, usage, and any protocol details. Keep `docs/` as the living reference for the project.
 
+Before the first push on a branch that adds public API surface (new exceptions, CLI commands, IRC verbs, backend config fields), invoke the `doc-test-alignment` subagent to surface doc gaps: `Agent(subagent_type="doc-test-alignment", ...)`. It reads the branch diff and reports missing `docs/` coverage, missing protocol extension pages, and all-backends drift — it does not write docs, only flags omissions.
+
 ## Git Workflow
 
+- **Before branching, run `git status`.** If `CHANGELOG.md`, any `CLAUDE.md`, or other files carry pre-existing unstaged changes on `main`, decide up front whether to stash, commit separately, or hand-split. `/version-bump` inserts a new section at the top of `CHANGELOG.md` and will interleave awkwardly with an existing `[Unreleased]` block if you don't.
 - Branch out for all changes
-- **Bump the version before creating a PR** — use `/version-bump patch` (bug fix), `minor` (new feature), or `major` (breaking change). This updates `pyproject.toml`, `culture/__init__.py`, and `CHANGELOG.md` in one step. Forgetting will fail the version-check CI job.
+- **Bump the version before creating a PR** — use `/version-bump patch` (bug fix), `minor` (new feature), or `major` (breaking change). This updates `pyproject.toml` and `CHANGELOG.md` (and `uv.lock` when applicable) in one step. Forgetting will fail the version-check CI job.
+- **Pre-push review for library/protocol code.** When the diff touches shared choke points (transport, `_send_raw`-style I/O, protocol parsers, anything in `packages/` or `culture/agentirc/`), invoke a code reviewer on the staged diff before the first push — typed exceptions and new error paths routinely create caller cleanup obligations that Qodo/human reviewers otherwise surface in the first review round. Use `Agent(subagent_type="superpowers:code-reviewer", ...)` or `/review-and-fix`.
 - Push to GitHub for agentic code review
 - Pull review comments, address feedback, push fixes
 - Reply to comments after pushing, resolve threads
+- **Before declaring the PR ready**, check SonarCloud for the branch via the `/sonarclaude` skill. SonarCloud findings do not always arrive as inline PR comments, so an all-green `gh pr checks` + all-resolved threads is not sufficient.
 
 ## Testing
 
@@ -64,6 +69,10 @@ When implementing features, write a corresponding markdown doc in `docs/` descri
 - No mocks for the server — tests spin up real server instances on random ports with real TCP connections
 - Validate each layer with real IRC clients (weechat/irssi)
 
+## Format Before Commit
+
+Pre-commit runs `black`, `isort`, `flake8`, `pylint`, `bandit`. `black`/`isort` failures reformat the file and reject the commit — you then have to `git add` the reformatted file and commit again. To avoid the re-commit loop, run `uv run black <files>` and `uv run isort <files>` on staged Python files **before** `git commit`.
+
 ## Nick Format
 
 `<server>-<agent>` (e.g., `thor-claude`, `spark-ori`). Globally unique by construction.

{agentirc_cli-6.2.2 → agentirc_cli-7.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentirc-cli
-Version: 6.2.2
+Version: 7.0.4
 Summary: Legacy alias for culture — install culture instead
 Project-URL: Homepage, https://github.com/OriNachum/culture
 Author: Ori Nachum

{agentirc_cli-6.2.2 → agentirc_cli-7.0.4}/culture/agentirc/client.py

@@ -9,6 +9,7 @@ from typing import TYPE_CHECKING
 from culture.agentirc.channel import Channel
 from culture.agentirc.skill import Event, EventType
 from culture.aio import maybe_await
+from culture.constants import SYSTEM_USER_PREFIX
 from culture.protocol import replies
 from culture.protocol.message import Message
 
@@ -35,6 +36,7 @@ class Client:
         self.channels: set[Channel] = set()
         self._registered = False
         self.tags: list[str] = []
+        self.caps: set[str] = set()
         self.modes: set[str] = set()
         self.icon: str | None = None
 
@@ -49,6 +51,28 @@ class Client:
         except OSError:
             pass  # Client disconnected; cleanup happens in ircd._handle_connection
 
+    async def send_raw(self, line: str) -> None:
+        """Write a pre-formatted IRC line to the client socket.
+
+        Appends CRLF internally, matching ServerLink.send_raw convention.
+        """
+        try:
+            self.writer.write(f"{line}\r\n".encode("utf-8"))
+            await self.writer.drain()
+        except OSError:
+            pass  # Client disconnected; cleanup happens in ircd._handle_connection
+
+    async def send_tagged(self, msg: Message) -> None:
+        """Send a Message, stripping tags for clients that haven't negotiated message-tags."""
+        if msg.tags and "message-tags" not in self.caps:
+            msg = Message(
+                tags={},
+                prefix=msg.prefix,
+                command=msg.command,
+                params=list(msg.params),
+            )
+        await self.send(msg)
+
     async def send_numeric(self, code: str, *params: str) -> None:
         target = self.nick or "*"
         msg = Message(
@@ -114,6 +138,29 @@ class Client:
     def _handle_pong(self, msg: Message) -> None:
         pass  # Client responding to our ping
 
+    async def _handle_cap(self, msg: Message) -> None:
+        sub = msg.params[0].upper() if msg.params else ""
+        if sub == "LS":
+            await self.send_raw(
+                f":{self.server.config.name} CAP {self.nick or '*'} LS :message-tags"
+            )
+        elif sub == "REQ":
+            requested = msg.params[1].split() if len(msg.params) >= 2 else []
+            supported = {"message-tags"}
+            if all(cap in supported for cap in requested):
+                self.caps.update(requested)
+                await self.send_raw(
+                    f":{self.server.config.name} CAP {self.nick or '*'}"
+                    f" ACK :{' '.join(requested)}"
+                )
+            else:
+                await self.send_raw(
+                    f":{self.server.config.name} CAP {self.nick or '*'}"
+                    f" NAK :{' '.join(requested)}"
+                )
+        elif sub == "END":
+            pass  # no registration-gating in v1
+
     async def _handle_nick(self, msg: Message) -> None:
         if not msg.params:
             await self.send_numeric(replies.ERR_NONICKNAMEGIVEN, "No nickname given")
@@ -121,6 +168,15 @@ class Client:
 
         nick = msg.params[0]
 
+        # Reject reserved system-* nick prefix
+        if nick.startswith(SYSTEM_USER_PREFIX):
+            await self.send_numeric(
+                replies.ERR_ERRONEUSNICKNAME,
+                nick,
+                "Nickname prefix 'system-' is reserved",
+            )
+            return
+
         # Enforce server name prefix
         expected_prefix = f"{self.server.config.name}-"
         if not nick.startswith(expected_prefix):
@@ -227,10 +283,6 @@ class Client:
         for member in list(channel.members):
             await member.send(join_msg)
 
-        await self.server.emit_event(
-            Event(type=EventType.JOIN, channel=channel_name, nick=self.nick)
-        )
-
         # Send topic if set
         if channel.topic:
             await self.send_numeric(replies.RPL_TOPIC, channel_name, channel.topic)
@@ -238,6 +290,12 @@ class Client:
         # Send names list
         await self._send_names(channel)
 
+        # Emit event AFTER delivering all join-related numerics (topic, NAMES)
+        # so that the event PRIVMSG doesn't interleave with 353/366 in client buffers.
+        await self.server.emit_event(
+            Event(type=EventType.JOIN, channel=channel_name, nick=self.nick)
+        )
+
     async def _handle_part(self, msg: Message) -> None:
         if not msg.params:
             await self.send_numeric(replies.ERR_NEEDMOREPARAMS, "PART", replies.MSG_NEEDMOREPARAMS)
@@ -451,7 +509,63 @@ class Client:
             for member in list(channel.members):
                 await member.send(mode_msg)
 
+    _VALID_USER_MODE_CHARS = frozenset("HABC")
+    _USER_MODE_EDGE_EVENTS: dict[tuple[str, bool], EventType] = {
+        ("A", True): EventType.AGENT_CONNECT,
+        ("A", False): EventType.AGENT_DISCONNECT,
+        ("C", True): EventType.CONSOLE_OPEN,
+        ("C", False): EventType.CONSOLE_CLOSE,
+    }
+
+    def _apply_user_mode_char(self, ch: str, adding: bool) -> EventType | None:
+        """Mutate ``self.modes`` for a single mode char and return the edge event, if any.
+
+        Returns None if the char is unknown or the transition was a no-op
+        (setting an already-set mode or clearing an already-clear one).
+        """
+        if ch not in self._VALID_USER_MODE_CHARS:
+            return None
+        had = ch in self.modes
+        if adding:
+            self.modes.add(ch)
+        else:
+            self.modes.discard(ch)
+        if had == adding:
+            return None
+        return self._USER_MODE_EDGE_EVENTS.get((ch, adding))
+
+    def _parse_mode_edges(self, modestring: str) -> list[EventType]:
+        """Apply each char of ``modestring`` and collect the emitted edge events."""
+        pending: list[EventType] = []
+        adding = True
+        for ch in modestring:
+            if ch == "+":
+                adding = True
+            elif ch == "-":
+                adding = False
+            else:
+                event = self._apply_user_mode_char(ch, adding)
+                if event is not None:
+                    pending.append(event)
+        return pending
+
+    async def _emit_user_mode_events(self, pending: list[EventType]) -> None:
+        for event_type in pending:
+            await self.server.emit_event(
+                Event(
+                    type=event_type,
+                    channel=None,
+                    nick=self.nick,
+                    data={"nick": self.nick},
+                )
+            )
+
     async def _handle_user_mode(self, msg: Message) -> None:
+        # Reject pre-registration so an unregistered socket cannot inject
+        # agent.connect / console.open into #system by sending MODE after NICK
+        # but before USER.
+        if not self._registered:
+            return
         target_nick = msg.params[0]
         if target_nick != self.nick:
             await self.send_numeric(
@@ -459,19 +573,11 @@ class Client:
                 "Can't change mode for other users",
             )
             return
-        if len(msg.params) > 1:
-            modestring = msg.params[1]
-            adding = True
-            for ch in modestring:
-                if ch == "+":
-                    adding = True
-                elif ch == "-":
-                    adding = False
-                elif ch in ("H", "A", "B"):
-                    if adding:
-                        self.modes.add(ch)
-                    else:
-                        self.modes.discard(ch)
+
+        modestring = msg.params[1] if len(msg.params) > 1 else ""
+        pending = self._parse_mode_edges(modestring)
+        await self._emit_user_mode_events(pending)
+
         mode_str = "+" + "".join(sorted(self.modes)) if self.modes else "+"
         await self.send_numeric(replies.RPL_UMODEIS, mode_str)
 

{agentirc_cli-6.2.2 → agentirc_cli-7.0.4}/culture/agentirc/config.py

@@ -22,3 +22,4 @@ class ServerConfig:
     webhook_port: int = 7680
     data_dir: str = ""
     links: list[LinkConfig] = field(default_factory=list)
+    system_bots: dict = field(default_factory=dict)

agentirc_cli-7.0.4/culture/agentirc/events.py

@@ -0,0 +1,117 @@
+"""Event type catalog and render-template registry.
+
+Event type names follow the dotted-lowercase convention enforced by
+`EVENT_TYPE_RE` in `culture.constants`. Render templates map a type to a
+function that produces the human-readable PRIVMSG body for humans and
+vanilla IRC clients. The structured payload is attached as IRCv3 message
+tags by the server's emit path (see `culture/agentirc/ircd.py`); this
+module is presentation-only.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable
+
+from culture.agentirc.skill import EventType
+from culture.constants import EVENT_TYPE_RE
+
+logger = logging.getLogger(__name__)
+
+# Event types whose content is already delivered to clients via the normal
+# IRC path (PRIVMSG, NOTICE, TOPIC) or has dedicated storage (threads).
+# Used by both IRCd._surface_event_privmsg (to avoid double-delivery) and
+# HistorySkill (to avoid double-storage).  Keep this as the single source
+# of truth — do not duplicate.
+NO_SURFACE_EVENT_TYPES: frozenset[str] = frozenset(
+    {
+        EventType.MESSAGE.value,
+        EventType.THREAD_CREATE.value,
+        EventType.THREAD_MESSAGE.value,
+        EventType.THREAD_CLOSE.value,
+        EventType.TOPIC.value,
+    }
+)
+
+RenderFn = Callable[[dict[str, Any], str | None], str]
+
+_TEMPLATES: dict[str, RenderFn] = {}
+
+
+def register(event_type: str, fn: RenderFn) -> None:
+    _TEMPLATES[event_type] = fn
+
+
+def validate_event_type(name: str) -> bool:
+    return bool(EVENT_TYPE_RE.match(name))
+
+
+def render_event(event_type: str, data: dict[str, Any], channel: str | None) -> str:
+    fn = _TEMPLATES.get(event_type)
+    if fn is None:
+        return f"{event_type} {data}"
+    try:
+        return fn(data, channel)
+    except Exception:
+        logger.exception("render template for %s failed", event_type)
+        return f"{event_type} {data}"
+
+
+# -------- built-in render templates --------
+
+
+def _nick_action(verb: str) -> RenderFn:
+    def _render(data, channel):
+        nick = data.get("nick", "<unknown>")
+        if channel:
+            return f"{nick} {verb} {channel}"
+        return f"{nick} {verb}"
+
+    return _render
+
+
+register("user.join", _nick_action("joined"))
+register("user.part", _nick_action("left"))
+register(
+    "user.quit",
+    lambda d, c: f"{d.get('nick', '<unknown>')} quit: {d.get('reason', '')}".rstrip(": "),
+)
+
+register("agent.connect", lambda d, c: f"{d.get('nick', '<unknown>')} connected")
+register(
+    "agent.disconnect",
+    lambda d, c: f"{d.get('nick', '<unknown>')} disconnected",
+)
+
+register("console.open", lambda d, c: f"{d.get('nick', '<unknown>')} opened a console")
+register("console.close", lambda d, c: f"{d.get('nick', '<unknown>')} closed their console")
+
+register("server.wake", lambda d, c: f"server {d.get('server', '<unknown>')} is up")
+register(
+    "server.sleep",
+    lambda d, c: f"server {d.get('server', '<unknown>')} is shutting down",
+)
+register("server.link", lambda d, c: f"linked to {d.get('peer', '<unknown>')}")
+register("server.unlink", lambda d, c: f"unlinked from {d.get('peer', '<unknown>')}")
+
+register("room.create", lambda d, c: f"{d.get('nick', '<unknown>')} created room {c}")
+register("room.archive", lambda d, c: f"{d.get('nick', '<unknown>')} archived {c}")
+register("room.meta", lambda d, c: f"{d.get('nick', '<unknown>')} updated {c} metadata")
+
+register(
+    "thread.create",
+    lambda d, c: f"{d.get('nick', '<unknown>')} started thread [{d.get('thread', '?')}] in {c}",
+)
+register(
+    "thread.message",
+    lambda d, c: f"[{d.get('thread', '?')}] {d.get('nick', '<unknown>')}: {d.get('text', '')}",
+)
+register(
+    "thread.close",
+    lambda d, c: f"thread [{d.get('thread', '?')}] in {c} closed",
+)
+
+register(
+    "tags.update",
+    lambda d, c: f"{d.get('nick', '<unknown>')} tags → {', '.join(d.get('tags', []))}",
+)