agentirc-cli 9.4.0__tar.gz → 9.5.0__tar.gz

{agentirc_cli-9.4.0 → agentirc_cli-9.5.0}/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/).
 
+## [9.5.0] - 2026-05-02
+
+Closes [agentculture/agentirc#15](https://github.com/agentculture/agentirc/issues/15) — out-of-process bot extension API. Unblocks [agentculture/culture#308](https://github.com/agentculture/culture/issues/308) Phase A2 (bot rewrite against the public API).
+
+### Added
+
+- **IRCv3 `agentirc.io/bot` capability.** Advertised in `CAP LS` output. When negotiated via `CAP REQ`, gates four behaviours: silent JOIN/PART/QUIT broadcasts (other channel members see nothing), no auto-op on a fresh-channel first-joiner, `+` prefix in NAMES output, `B` flag in WHO output. Channel membership is added normally; events still fire (subscribers see them via `EVENTSUB`).
+- **`EVENTSUB` / `EVENTUNSUB` / `EVENT` / `EVENTERR` IRC verbs** for streaming events to bots out-of-process. `EVENTSUB <sub-id> [type=<glob>] [channel=<name>] [nick=<glob>]`: filters AND-ed; `type` and `nick` accept `fnmatch`-style globs; `channel` accepts an exact name, `*`, or empty (nick-scoped only). Multiple concurrent subscriptions per client are allowed. Wire format: `:server EVENT <sub-id> <type> <channel-or-*> <nick> :<base64-json-envelope>` carrying the canonical 5-field envelope. Per-subscription bounded queue (default 1024); on overflow the server emits `EVENTERR <sub-id> :backpressure-overflow` and drops the subscription (connection stays open). Subscriptions die on client disconnect.
+- **`EVENTPUB` IRC verb** for bots to emit custom-typed events back into the stream. `EVENTPUB <type> <channel-or-*> :<base64-json-data>`. Type validated against `EVENT_TYPE_RE` (dotted lowercase, ≥1 dot — single-segment names like `message` and `topic` are reserved for built-in vocabulary). Server fills `nick` from the bot's connection nick (not spoofable) and `timestamp` from `time.time()` so federation peers see consistent clocks. `_`-prefixed keys are stripped from the payload before emit.
+- New internal module `agentirc._internal.event_subscriptions` with the `Subscription` dataclass and `SubscriptionRegistry`. `IRCd.subscription_registry` exposes the registry; `IRCd.emit_event` dispatches every event through it.
+- `agentirc.protocol.SEVENT` verb constant (added in 9.5.0a2; reaffirmed here).
+
+### Changed
+
+- **`webhook_port` is no longer bound by `IRCd.start()`.** The field stays in `ServerConfig` so culture's `~/.culture/server.yaml` keeps loading unchanged, but `agentirc` no longer instantiates the HTTP listener. Consumers that need webhook→bot dispatch host their own listener (see `docs/deployment.md`). No deprecation warning at runtime — the docs change is sufficient.
+- `Channel.add()` no longer auto-ops bot-CAP clients (real or `VirtualClient`). A bot joining an empty channel stays unprivileged; the next human becomes op.
+- `Channel.get_prefix()` returns `+` for bot-CAP members in NAMES output.
+- `Client._build_who_flags()` adds the `B` flag for bot-CAP members in WHO output (composes with `H` and `@`/`+`).
+- `VirtualClient` gains a class-level `caps = frozenset({"agentirc.io/bot", "message-tags"})` so the in-process system bot is treated identically to a real CAP-bot.
+- `Client._handle_cap` `CAP LS` reply now lists supported caps from a class-level `_SUPPORTED_CAPS` frozenset (centralised; removing a cap is a major bump).
+- `agentirc/_internal/bots/http_listener.py` module docstring notes the no-op stub is scheduled for removal in 9.6.0.
+
+### Notes
+
+- This is the **final slice** of the bot extension API. `9.5.0a1` shipped the public `agentirc.protocol` declarations; `9.5.0a2` switched the federation wire format to the 5-field envelope; this release wires the actual behaviour.
+- **Federation interop unchanged from 9.5.0a2.** 9.4→9.5 federation works (sniff tolerance); 9.5→9.4 emit breaks until peers upgrade.
+- The `agentirc.skill.{Event, EventType}` re-export shim from 9.5.0a1 stays through the 9.x line; removal is scheduled for 10.0.0.
+- The `agentirc/_internal/bots/` synthesize stubs (`bot_manager.py`, `http_listener.py`) stay through the 9.5.x cycle; removal is scheduled for 9.6.0 once Phase A2 confirms no consumer imports them.
+
+## [9.5.0a2] - 2026-05-02
+
+### Changed
+
+- **Wire format: SEVENT payload and IRCv3 `event-data` tag now carry the 5-field envelope** `{type, channel, nick, data, timestamp}`. Both the federation seam (`SEVENT` between linked servers) and the human-visible `#system` PRIVMSG `event-data` tag emit the new shape via `IRCd._build_event_envelope` + `IRCd._encode_event_data`. Type-specific keys (e.g. `text`, `room_id`, `purpose`) now nest under `data`; `nick` and `channel` remain at the top level. See `docs/superpowers/specs/2026-05-01-bot-extension-api-design.md` § Decision A for the rationale.
+- `IRCd._build_event_payload` is replaced by `IRCd._build_event_envelope` (internal — no public API impact). Old name removed; the only two callsites (`_surface_event_privmsg` and `ServerLink.relay_event`'s SEVENT fallback) updated in the same commit.
+
+### Added
+
+- `ServerLink._is_envelope(decoded)` — sniff helper that recognises the new envelope shape vs. the legacy data-only dict at decode time. `_handle_sevent` uses it for asymmetric tolerance (see Notes).
+- `agentirc.protocol.SEVENT` — verb-name constant for the federation event-relay verb. Used by the new test suite and the outbound relay path. Other agentirc-side string-literal callsites are tracked separately in [#11](https://github.com/agentculture/agentirc/issues/11).
+- `tests/test_wire_format_envelope.py` — 12 tests including a golden-file byte-equality lock-in for the canonical JSON encoding (any future change to the encoder that breaks this is a wire-format break and requires a major bump), plus regression guards for the trust-bypass and underscore-injection fixes below.
+
+### Security
+
+- **`ServerLink._handle_sevent` now treats the SEVENT verb-arg channel as authoritative.** The previous draft of this PR (pre-review) used the envelope's `channel` field on the receive side, which would have allowed a malformed/malicious peer to bypass `_check_incoming_trust` by sending `target="*"` (no trust check) while putting a restricted channel name in the envelope. The verb-arg channel is what the trust gate already protects, so the receiver now ignores any envelope channel claim and uses `verb_channel` for both the trust check and the resulting `Event.channel`.
+- **Peer-supplied `_`-prefixed keys are stripped from incoming SEVENT data before emit.** `_render` and similar server-internal hints would otherwise let a peer dictate human-readable surfacing on this server. The receiver strips every key starting with `_` from the decoded data before adding its own `_origin` marker.
+
+### Fixed
+
+- **`IRCd._encode_event_data` fallback now produces a valid 5-field envelope instead of `b"{}"`.** A serialization failure used to emit a bare empty dict, which fails the receiver's envelope sniff and is misclassified as legacy data-only — worse than emitting an event with no type-specific payload. The fallback now emits `{type, channel, nick, data: {}, timestamp: time.time()}` so consumers can still parse the shape.
+
+### Notes
+
+- **Federation interop story.** A 9.5 daemon's `_handle_sevent` sniffs the decoded payload: if it has a top-level `type` (string) and `data` (dict), treat as 9.5+ envelope; otherwise treat as ≤9.4 legacy data-only and reconstruct an `Event` from the SEVENT verb args + the bare data dict. This gives 9.5 receivers asymmetric tolerance — they read traffic from both upgraded and pre-9.5 peers — so federations can roll forward one peer at a time. The reverse direction (9.5 emit → 9.4 receive) does **not** work; 9.4 daemons have no sniff and will fail to find expected `data` fields. Operators must either upgrade all peers in lockstep, or roll one at a time and accept that 9.5-emitted events drop on still-9.4 peers until those peers also upgrade. This matches the migration cost the spec calls out.
+- **Audit JSONL is unchanged.** `agentirc/_internal/telemetry/audit.py:build_audit_record` continues to record the legacy data-only payload (data dict with `nick`/`channel` merged in via `setdefault`, `_`-prefixed keys stripped). Ops dashboards and downstream log processors that read the audit JSONL keep their existing field shape; the 5-field envelope is reserved for the public network surface (SEVENT payload + IRCv3 `event-data` tag).
+- **Audit timestamp on legacy peers.** When `_handle_sevent` decodes a legacy payload from a ≤9.4 peer, no originating timestamp is available; the receiver assigns `time.time()` to the reconstructed `Event.timestamp`. 9.5+ peers preserve the originating timestamp.
+- This is the **wire-format slice** of the bot extension API. The next slice (9.5.0a3) wires the bot CAP behavior (`agentirc.io/bot`), the `EVENTSUB`/`EVENTUNSUB`/`EVENTPUB` handlers, and the `SubscriptionRegistry`. 9.5.0 final adds `webhook_port` unbinding and flips `docs/api-stability.md` to "current".
+- Tracks [agentculture/agentirc#15](https://github.com/agentculture/agentirc/issues/15).
+
+## [9.5.0a1] - 2026-05-02
+
+### Added
+
+- Public `agentirc.protocol` exports for the bot extension API: the `Event` dataclass, the `EventType` enum, 20 per-type `EVENT_TYPE_*` string constants, the `EVENTSUB` / `EVENTUNSUB` / `EVENT` / `EVENTERR` / `EVENTPUB` verb constants, and the `BOT_CAP = "agentirc.io/bot"` capability identifier. `Event.type` is widened to `EventType | str` so federation peers can deliver event types this version doesn't recognise. See `docs/superpowers/specs/2026-05-01-bot-extension-api-design.md` for the full design and `docs/extension-api.md` for the bot-author quick reference.
+- `ServerConfig.event_subscription_queue_max: int = 1024` — per-subscription queue bound. Recognised by `ServerConfig.from_yaml` and `cli._resolve_config()` as a top-level YAML key. Consumed by the subscription registry that lands in 9.5.0a3.
+- `agentirc.skill` keeps re-exporting `Event` and `EventType` for backward compat; the re-export shim is removed in 9.6.0 once Phase A2 confirms no consumer relies on the path.
+
+### Changed
+
+- `EventType` upgraded from `enum.Enum` to `enum.StrEnum`. Members keep their `.value` strings unchanged, but Python consumers now observe new identity semantics: `isinstance(EventType.JOIN, str)` is `True`, `EventType.JOIN == "user.join"` is `True`, JSON serialization emits the bare string. Internal call sites verified — none compare `EventType.X` against a bare string today, so the truthier equality is pure improvement; downstream consumers that did string-equality round-trips against `EventType` see strictly more matches, never fewer.
+
+### Notes
+
+- This is the **declarations slice** of the bot extension API. No daemon-level behavior changes: `EVENTSUB` etc. are reserved verb constants but the daemon does not yet handle them; `BOT_CAP` is exported but not yet advertised in `CAP LS` output. The wire-format envelope refactor lands in 9.5.0a2; the bot CAP behavior, subscription verbs, `EVENTPUB`, and `webhook_port` unbinding land in 9.5.0a3 / 9.5.0 final.
+- Tracks [agentculture/agentirc#15](https://github.com/agentculture/agentirc/issues/15).
+
+## [9.4.1] - 2026-05-01
+
+### Documentation
+
+- Marked the bootstrap closed in `docs/superpowers/specs/2026-04-30-bootstrap-design.md` and `CLAUDE.md`. Tasks 16–18 (tag `v9.4.0`, verify PyPI publish, report-back to culture) are done; the spec status note now reads as a closed timeline ("Released ✅"), and `CLAUDE.md`'s "Current state" reads "bootstrap complete (9.4.0 released)" with a non-blocking follow-ups list linking to issues #7–#12 (Track A wire-format fixes, steward backport, callsite sweep, A2 test migration).
+- Fixed 14 stale `OriNachum/*` GitHub URLs in `pyproject.toml` and the bootstrap spec to canonical `agentculture/*` paths. Investigation showed these weren't merely stylistic — `https://github.com/OriNachum/culture` returns 404 and `https://github.com/OriNachum/agentirc` 301-redirects to the wrong path. URL fixes only; sha256s are content-hashed and unaffected. `cite check` still passes.
+
+### Notes
+
+- Functionally identical to `9.4.0`. Published as a fresh PyPI release because `publish.yml` triggers on push-to-`main` and PyPI rejects re-publishing the same version with different sha256.
+
 ## [9.4.0] - 2026-05-01
 
 ### Added

{agentirc_cli-9.4.0 → agentirc_cli-9.5.0}/CLAUDE.md

@@ -2,9 +2,9 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-## Current state: bootstrap functionally + docs complete (9.4.0); release ceremony remains
+## Current state: bootstrap complete (9.4.0 released)
 
-This repo is the agentirc server-core extraction out of the sibling project [`culture`](https://github.com/OriNachum/culture). As of 9.4.0:
+This repo is the agentirc server-core extraction out of the sibling project [`culture`](https://github.com/agentculture/culture). As of 9.4.0 (tagged at `5590256` and live on PyPI):
 
 - **Server-core** (`agentirc/{ircd,server_link,channel,events,skill,remote_client,…}.py`, `agentirc/skills/{rooms,threads,history,icon}.py`) — vendored from `culture@df50942` via the `cite-don't-copy` pattern (see `[tool.citation]` in `pyproject.toml`).
 - **Client transport** (`agentirc/client.py`) — vendored from `culture/agentirc/client.py` in PR-B2.
@@ -15,13 +15,13 @@ This repo is the agentirc server-core extraction out of the sibling project [`cu
 - **Internal support** (`agentirc/_internal/`) — `aio`, `constants`, `protocol/`, `telemetry/`, `virtual_client`, `pidfile`, `cli_shared/`, `bots/` stubs.
 - **Bootstrap docs** (PR-B4, 9.4.0) — `docs/api-stability.md` (3 public modules + semver contract), `docs/cli.md` (verb table, flag reference, exit codes, YAML/CLI precedence, agentirc-vs-culture diff table), `docs/deployment.md` (on-disk footprint, systemd `Type=simple` example, container deployment, multi-host federation, log rotation, coexistence with culture, backup).
 
-End-to-end verified: `agentirc start --port <p>` boots a real IRCd, TCP NICK/USER handshake returns `001 RPL_WELCOME`, `agentirc stop` shuts cleanly. `agentirc serve --config server.yaml --port 9999` correctly overlays CLI flag on YAML.
+End-to-end verified: `agentirc start --port <p>` boots a real IRCd, TCP NICK/USER handshake returns `001 RPL_WELCOME`, `agentirc stop` shuts cleanly. `agentirc serve --config server.yaml --port 9999` correctly overlays CLI flag on YAML. `pip install agentirc-cli==9.4.0` from real PyPI in a clean venv produces both `agentirc` and `agentirc-cli` binaries; both reach the same `agentirc.cli:main` entry point. Acceptance audit recorded at [`docs/superpowers/specs/2026-05-01-task14-audit.md`](docs/superpowers/specs/2026-05-01-task14-audit.md). Culture-side cutover unblocked via [agentculture/culture#308](https://github.com/agentculture/culture/issues/308).
 
-What is **not** done yet:
-- **Acceptance-criteria spot-check** (Task 14 in the bootstrap spec) — read-only audit to confirm every bullet in §"Acceptance criteria" is ✅ before tagging.
-- **Release ceremony** (Tasks 16–18) — tag `v9.4.0`, the existing `publish.yml` CI pushes to PyPI on push to `main`, then report version + source SHA back so culture's cutover PR can pin against it.
-- **Cross-repo wire-format fixes (Track A)** — `ROOMETAEND`/`ROOMETASET` typos, `ERR_NOSUCHCHANNEL` overload, `STHREAD` collapse. Each requires culture-side change first then agentirc bump.
-- **Steward backport** — port the 9.3.0 `pr-sonar.sh` + `workflow.sh` SonarCloud wiring back to the steward skills repo.
+**Outstanding follow-ups (non-blocking; the bootstrap itself is closed):**
+- **Cross-repo wire-format fixes (Track A)** — [#7](https://github.com/agentculture/agentirc/issues/7) (`ROOMETAEND`/`ROOMETASET` typos), [#8](https://github.com/agentculture/agentirc/issues/8) (`ERR_NOSUCHCHANNEL` overload), [#9](https://github.com/agentculture/agentirc/issues/9) (`STHREAD` verb collapse). Each requires culture-side change first then agentirc bump.
+- **Steward backport** — [#10](https://github.com/agentculture/agentirc/issues/10). Port the 9.3.0 `pr-sonar.sh` + `workflow.sh sonar` wiring upstream so other workspace projects pick it up via re-vendoring.
+- **Optional callsite sweep** — [#11](https://github.com/agentculture/agentirc/issues/11). Replace inline IRC verb / numeric-reply string literals in `ircd.py`/`server_link.py`/`skills/*.py` with `agentirc.protocol.<NAME>` imports. Pure refactor.
+- **A2 bot-fixtured tests (low-priority)** — [#12](https://github.com/agentculture/agentirc/issues/12). Currently in culture; could be migrated to agentirc via subprocess-fixture rewrite if culture's coverage drifts.
 
 Read the bootstrap spec at `docs/superpowers/specs/2026-04-30-bootstrap-design.md` for the full plan; it is the operative source of truth and is intentionally self-contained. The culture-side counterpart spec is at `../culture/docs/superpowers/specs/2026-04-30-agentirc-extraction-design.md` — not normally needed, but explains *why* if a decision looks arbitrary.
 

{agentirc_cli-9.4.0 → agentirc_cli-9.5.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: agentirc-cli
-Version: 9.4.0
+Version: 9.5.0
 Summary: Agent-friendly IRCd: server core for AI agent meshes
-Project-URL: Homepage, https://github.com/OriNachum/agentirc
-Project-URL: Issues, https://github.com/OriNachum/agentirc/issues
+Project-URL: Homepage, https://github.com/agentculture/agentirc
+Project-URL: Issues, https://github.com/agentculture/agentirc/issues
 Author: Ori Nachum
 License: MIT License
         

{agentirc_cli-9.4.0 → agentirc_cli-9.5.0}/agentirc/_internal/bots/http_listener.py

@@ -1,10 +1,18 @@
-"""No-op ``HttpListener`` stub.
+"""No-op ``HttpListener`` stub (scheduled for removal in 9.6.0).
 
 Pairs with the no-op :class:`agentirc._internal.bots.bot_manager.BotManager`.
 The real implementation lives in ``culture.bots.http_listener`` and exposes
 a webhook surface for triggering bot events. In a standalone agentirc
 deployment there is nothing to listen for, so ``start()`` and ``stop()``
 are no-ops.
+
+As of 9.5.0, :class:`agentirc.ircd.IRCd` no longer instantiates this stub —
+the webhook listener is the consumer's responsibility (see
+``docs/api-stability.md`` and ``docs/deployment.md``). The class itself
+stays in the codebase for one cycle so any vendored test or culture-runtime
+override that imports it keeps working; it is scheduled for deletion in
+9.6.0 once Phase A2 of agentculture/culture#308 confirms no consumer
+imports it.
 """
 
 from __future__ import annotations

agentirc_cli-9.5.0/agentirc/_internal/event_subscriptions.py

@@ -0,0 +1,282 @@
+"""Per-client event subscription registry for the bot extension API (9.5.0).
+
+Public-facing wire format and verb syntax are described in the design spec at
+``docs/superpowers/specs/2026-05-01-bot-extension-api-design.md`` § Decision B.
+This module is internal — consumers interact via the ``EVENTSUB``/``EVENTUNSUB``
+IRC verbs handled by :class:`agentirc.client.Client`.
+
+Design points:
+
+- One :class:`Subscription` per ``sub-id`` per client. Multiple concurrent
+  subscriptions per client are allowed; each gets its own bounded queue and
+  its own drain task.
+- Filter fields are AND-ed; ``type`` and ``nick`` accept ``fnmatch``-style
+  globs (``*``/``?``/``[]``); ``channel`` is exact match (or ``"*"`` for any
+  channel, or ``""`` for nick-scoped events only).
+- Backpressure: a per-subscription ``asyncio.Queue`` bounded by
+  ``ServerConfig.event_subscription_queue_max``. On overflow, the registry
+  sends ``EVENTERR <sub-id> :backpressure-overflow`` and removes the
+  subscription. The connection itself stays open — the bot can re-subscribe
+  with the same or a fresh ``sub-id`` and use ``BACKFILL`` to recover.
+- The drain task encodes events via :func:`agentirc.ircd.IRCd._build_event_envelope`
+  + :func:`agentirc.ircd.IRCd._encode_event_data`, so the ``EVENT`` line on the
+  wire carries the same canonical 5-field envelope as the federated ``SEVENT``
+  payload and the IRCv3 ``event-data`` tag.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import fnmatch
+import logging
+import re
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Callable
+
+if TYPE_CHECKING:
+    from agentirc.client import Client
+    from agentirc.protocol import Event
+
+logger = logging.getLogger(__name__)
+
+
+# A per-subscription channel filter that matches every channel, including the
+# nick-scoped ``None`` case.
+CHANNEL_ANY = "*"
+# A per-subscription channel filter that matches only nick-scoped events
+# (events with ``event.channel is None``).
+CHANNEL_NICK_SCOPED_ONLY = ""
+
+# Channel-filter format for ``EVENTSUB``: an exact channel name (``#``-prefixed),
+# the literal ``*`` (any channel including nick-scoped), or the empty string
+# (nick-scoped events only). Anything else is rejected so subscribers don't
+# silently bind a filter that never matches.
+_CHANNEL_FILTER_RE = re.compile(r"^(#[^\s,]+|\*|)$")
+
+
+# ---------------------------------------------------------------------------
+# Filter-parameter dispatch table for EVENTSUB
+# ---------------------------------------------------------------------------
+# Each handler receives the partially-built ``filters`` dict and the value
+# from one ``key=value`` token; it mutates ``filters`` and returns either
+# ``None`` on success or an error-reason string suitable for
+# ``EVENTERR <sub-id> :<reason>``. ``Client._parse_eventsub_filters`` walks
+# the tokens and dispatches via :data:`FILTER_HANDLERS`.
+
+
+def _set_type_glob(filters: dict, value: str) -> str | None:
+    filters["type_glob"] = value or "*"
+    return None
+
+
+def _set_channel(filters: dict, value: str) -> str | None:
+    if not _CHANNEL_FILTER_RE.match(value):
+        return f"invalid-channel-filter {value}"
+    filters["channel"] = CHANNEL_NICK_SCOPED_ONLY if value == "" else value
+    return None
+
+
+def _set_nick_glob(filters: dict, value: str) -> str | None:
+    filters["nick_glob"] = value or "*"
+    return None
+
+
+FILTER_HANDLERS: dict[str, Callable[[dict, str], "str | None"]] = {
+    "type": _set_type_glob,
+    "channel": _set_channel,
+    "nick": _set_nick_glob,
+}
+
+
+@dataclass
+class Subscription:
+    """A single subscription owned by a client.
+
+    Constructed by :meth:`SubscriptionRegistry.add`; do not instantiate
+    directly. ``queue`` and ``drain_task`` are populated by the registry.
+    """
+
+    sub_id: str
+    type_glob: str = "*"
+    channel: str = CHANNEL_ANY
+    nick_glob: str = "*"
+    queue: asyncio.Queue = field(default_factory=asyncio.Queue)
+    drain_task: asyncio.Task | None = None
+    dropped: bool = False
+
+    def matches(self, event: Event) -> bool:
+        """Return True if *event* satisfies the AND-ed filter fields."""
+        type_str = str(event.type)
+        if self.type_glob != "*" and not fnmatch.fnmatchcase(type_str, self.type_glob):
+            return False
+        if self.channel != CHANNEL_ANY:
+            if self.channel == CHANNEL_NICK_SCOPED_ONLY:
+                if event.channel is not None:
+                    return False
+            else:
+                if event.channel != self.channel:
+                    return False
+        if self.nick_glob != "*" and not fnmatch.fnmatchcase(event.nick, self.nick_glob):
+            return False
+        return True
+
+
+class SubscriptionRegistry:
+    """Routes events to per-client subscription queues.
+
+    Owned by :class:`agentirc.ircd.IRCd`. ``IRCd.emit_event`` calls
+    :meth:`dispatch` on every event; subscriber clients drain their per-sub
+    queues via background tasks.
+    """
+
+    def __init__(self, *, queue_max: int = 1024) -> None:
+        self._subs: dict[Client, dict[str, Subscription]] = {}
+        self._queue_max = queue_max
+
+    @property
+    def queue_max(self) -> int:
+        return self._queue_max
+
+    def get(self, client: Client, sub_id: str) -> Subscription | None:
+        return self._subs.get(client, {}).get(sub_id)
+
+    def list_for_client(self, client: Client) -> list[Subscription]:
+        return list(self._subs.get(client, {}).values())
+
+    def add(
+        self,
+        client: Client,
+        sub_id: str,
+        *,
+        type_glob: str = "*",
+        channel: str = CHANNEL_ANY,
+        nick_glob: str = "*",
+    ) -> Subscription | None:
+        """Register a new subscription. Returns None on sub-id collision.
+
+        The caller is responsible for sending the appropriate ``EVENTERR``
+        when the result is ``None``.
+        """
+        per_client = self._subs.setdefault(client, {})
+        if sub_id in per_client:
+            return None
+        sub = Subscription(
+            sub_id=sub_id,
+            type_glob=type_glob,
+            channel=channel,
+            nick_glob=nick_glob,
+            queue=asyncio.Queue(maxsize=self._queue_max),
+        )
+        per_client[sub_id] = sub
+        sub.drain_task = asyncio.create_task(
+            self._drain(client, sub),
+            name=f"event-sub-drain[{sub_id}]",
+        )
+        return sub
+
+    def remove(self, client: Client, sub_id: str) -> bool:
+        """Cancel and forget *sub_id* on *client*. Returns True on hit."""
+        per_client = self._subs.get(client)
+        if not per_client or sub_id not in per_client:
+            return False
+        sub = per_client.pop(sub_id)
+        sub.dropped = True
+        if sub.drain_task is not None and not sub.drain_task.done():
+            sub.drain_task.cancel()
+        if not per_client:
+            self._subs.pop(client, None)
+        return True
+
+    def remove_client(self, client: Client) -> None:
+        """Cancel every subscription owned by *client*. Called on disconnect."""
+        per_client = self._subs.pop(client, {})
+        for sub in per_client.values():
+            sub.dropped = True
+            if sub.drain_task is not None and not sub.drain_task.done():
+                sub.drain_task.cancel()
+
+    async def dispatch(self, event: Event) -> None:
+        """Enqueue *event* on every matching subscription.
+
+        On queue overflow, mark the subscription dropped, send the bot an
+        ``EVENTERR <sub-id> :backpressure-overflow`` line, and remove the
+        subscription from the registry. The bot's connection stays open.
+        """
+        # ``dispatch`` may call ``_handle_overflow`` which awaits
+        # ``client.send_raw``; while that yields, another coroutine can call
+        # ``add`` or ``remove`` and mutate the dicts. The ``list()`` snapshots
+        # avoid ``RuntimeError: dictionary changed size during iteration``.
+        for client, per_client in list(self._subs.items()):  # NOSONAR python:S7504: defensive snapshot vs. concurrent mutation
+            for sub in list(per_client.values()):  # NOSONAR python:S7504: defensive snapshot vs. concurrent mutation
+                if sub.dropped:
+                    continue
+                if not sub.matches(event):
+                    continue
+                try:
+                    sub.queue.put_nowait(event)
+                except asyncio.QueueFull:
+                    await self._handle_overflow(client, sub)
+
+    async def _handle_overflow(self, client: Client, sub: Subscription) -> None:
+        sub.dropped = True
+        try:
+            await client.send_raw(f"EVENTERR {sub.sub_id} :backpressure-overflow")
+        except Exception:
+            logger.exception(
+                "Failed to send backpressure-overflow EVENTERR for sub %s",
+                sub.sub_id,
+            )
+        self.remove(client, sub.sub_id)
+
+    async def _drain(self, client: Client, sub: Subscription) -> None:
+        """Pull events off *sub.queue* and send them as ``EVENT`` lines.
+
+        Imports :mod:`agentirc.ircd` and :mod:`agentirc.protocol` lazily to
+        avoid an import cycle (``ircd.py`` instantiates this registry).
+        """
+        from agentirc.ircd import IRCd
+        from agentirc.protocol import EVENT
+
+        server_name = client.server.config.name
+
+        # ``CancelledError`` (raised when ``remove``/``remove_client`` cancels
+        # the drain task) propagates out of this coroutine naturally — no
+        # cleanup is needed because the registry already removed the
+        # subscription before cancelling the task.
+        while True:
+            event = await sub.queue.get()
+            if sub.dropped:
+                return
+
+            type_wire = str(event.type)
+            target = event.channel if event.channel is not None else "*"
+            envelope = IRCd._build_event_envelope(event)
+            encoded = IRCd._encode_event_data(envelope, type_wire)
+            line = (
+                f":{server_name} {EVENT} {sub.sub_id} {type_wire} "
+                f"{target} {event.nick} :{encoded}"
+            )
+            try:
+                await client.send_raw(line)
+            except Exception:
+                # Connection is gone or send failed; let the disconnect
+                # cleanup path remove this subscription.
+                logger.debug(
+                    "EVENT send to %s sub %s failed; awaiting disconnect cleanup",
+                    getattr(client, "nick", "<?>"),
+                    sub.sub_id,
+                )
+                return
+
+
+__all__ = [
+    "CHANNEL_ANY",
+    "CHANNEL_NICK_SCOPED_ONLY",
+    "Subscription",
+    "SubscriptionRegistry",
+]
+
+
+# Re-export ``Any`` to satisfy strict-import linters that flag the typing import
+# above. (Subscription.queue is parameterized in docstrings only.)
+_ = Any

{agentirc_cli-9.4.0 → agentirc_cli-9.5.0}/agentirc/_internal/telemetry/audit.py

@@ -313,6 +313,13 @@ def build_audit_record(
 
     See culture/protocol/extensions/audit.md for the field set.
     """
+    # Audit JSONL records the legacy data-only payload (data dict with
+    # nick/channel merged in via setdefault, _-prefixed keys stripped).
+    # This intentionally diverges from the 9.5+ public wire envelope built
+    # by IRCd._build_event_envelope: ops dashboards and downstream log
+    # processors that read the audit JSONL keep their existing field shape;
+    # the 5-field envelope is reserved for the public network surface
+    # (SEVENT payload + IRCv3 event-data tag).
     payload = {k: v for k, v in (event.data or {}).items() if not k.startswith("_")}
     if event.nick:
         payload.setdefault("nick", event.nick)

{agentirc_cli-9.4.0 → agentirc_cli-9.5.0}/agentirc/_internal/virtual_client.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import logging
 from typing import TYPE_CHECKING
 
+from agentirc.protocol import BOT_CAP
 from agentirc.skill import Event, EventType
 from agentirc._internal.protocol.message import Message
 
@@ -27,6 +28,17 @@ class VirtualClient:
     in channel.members, NAMES, WHO, and WHOIS transparently.
     """
 
+    # The in-process system bot is treated identically to a real CAP-bot
+    # everywhere: external code paths (``Channel._local_members``,
+    # ``Channel.get_prefix``, ``Client._build_who_flags``) read this attr
+    # via ``getattr(member, "caps", ...)`` and apply the no-auto-op,
+    # ``+``-prefix, and ``B``-flag rules; the methods on this class
+    # (``join_channel``/``part_channel``) check it themselves to suppress
+    # their own JOIN/PART broadcasts to other channel members. Class-level
+    # so every instance gets the same caps; VirtualClients don't negotiate
+    # caps the way real Clients do.
+    caps: frozenset[str] = frozenset({BOT_CAP, "message-tags"})
+
     def __init__(self, nick: str, user: str, server: IRCd):
         self.nick = nick
         self.user = user
@@ -63,14 +75,19 @@ class VirtualClient:
         # Ensure bot is never auto-promoted to operator
         channel.operators.discard(self)
 
-        join_msg = Message(
-            prefix=self.prefix,
-            command="JOIN",
-            params=[channel_name],
-        )
-        for member in [*channel.members]:
-            if member is not self:
-                await member.send(join_msg)
+        # Bot-CAP clients (the entire VirtualClient class) skip the
+        # per-member JOIN broadcast — silent presence to other members.
+        # Channel membership above is already added; the user.join event
+        # below still fires so EVENTSUB subscribers see it.
+        if BOT_CAP not in self.caps:
+            join_msg = Message(
+                prefix=self.prefix,
+                command="JOIN",
+                params=[channel_name],
+            )
+            for member in [*channel.members]:
+                if member is not self:
+                    await member.send(join_msg)
 
         if emit_event:
             await self.server.emit_event(
@@ -83,14 +100,17 @@ class VirtualClient:
         if not channel or self not in channel.members:
             return
 
-        part_msg = Message(
-            prefix=self.prefix,
-            command="PART",
-            params=[channel_name],
-        )
-        for member in [*channel.members]:
-            if member is not self:
-                await member.send(part_msg)
+        # Symmetric with join_channel — bot-CAP clients skip the per-member
+        # PART broadcast. The user.part event below still fires.
+        if BOT_CAP not in self.caps:
+            part_msg = Message(
+                prefix=self.prefix,
+                command="PART",
+                params=[channel_name],
+            )
+            for member in [*channel.members]:
+                if member is not self:
+                    await member.send(part_msg)
 
         await self.server.emit_event(
             Event(

{agentirc_cli-9.4.0 → agentirc_cli-9.5.0}/agentirc/channel.py

@@ -2,6 +2,8 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, Union
 
+from agentirc.protocol import BOT_CAP
+
 if TYPE_CHECKING:
     from agentirc.client import Client
     from agentirc.remote_client import RemoteClient
@@ -40,18 +42,36 @@ class Channel:
         return self.room_id is not None
 
     def _local_members(self) -> set[Client]:
-        """Return only local (non-remote, non-virtual) members."""
+        """Return only local (non-remote, non-virtual, non-bot-CAP) members.
+
+        Used as the auto-op eligibility predicate by :meth:`add`. Bot-CAP
+        clients are excluded so a bot joining an empty channel never becomes
+        op — a human joining later does.
+        """
         from agentirc.remote_client import RemoteClient
         from agentirc._internal.virtual_client import VirtualClient
 
-        return {m for m in self.members if not isinstance(m, (RemoteClient, VirtualClient))}
+        return {
+            m
+            for m in self.members
+            if not isinstance(m, (RemoteClient, VirtualClient))
+            and BOT_CAP not in getattr(m, "caps", frozenset())
+        }
 
     def add(self, client: Client) -> None:
-        # Only grant op to the first LOCAL joiner
+        # Only grant op to the first LOCAL joiner. Bot-CAP clients
+        # (real or VirtualClient) are excluded — they never auto-op,
+        # so a bot joining an empty channel stays unprivileged and
+        # the next human becomes op.
         if not self._local_members():
             from agentirc.remote_client import RemoteClient
+            from agentirc._internal.virtual_client import VirtualClient
 
-            if not isinstance(client, RemoteClient):
+            is_op_eligible = (
+                not isinstance(client, (RemoteClient, VirtualClient))
+                and BOT_CAP not in getattr(client, "caps", frozenset())
+            )
+            if is_op_eligible:
                 self.operators.add(client)
         self.members.add(client)
 
@@ -77,4 +97,11 @@ class Channel:
             return "@"
         if client in self.voiced:
             return "+"
+        # Bot-CAP clients render with the voice prefix in NAMES output —
+        # the closest standard IRC mode for "non-disruptive participant",
+        # so vanilla IRC clients filter bots from presence panels by
+        # checking the ``+`` prefix. Op wins on conflict (above), so an
+        # explicitly-opped bot still renders as ``@``.
+        if BOT_CAP in getattr(client, "caps", frozenset()):
+            return "+"
         return ""

{agentirc_cli-9.4.0 → agentirc_cli-9.5.0}/agentirc/cli.py

@@ -185,6 +185,9 @@ def _resolve_config(args: argparse.Namespace) -> "ServerConfig":  # noqa: F821 (
             args.data_dir, raw.get("data_dir"), os.path.expanduser("~/.culture/data")
         )
     )
+    event_subscription_queue_max = _pick(
+        None, raw.get("event_subscription_queue_max"), 1024
+    )
 
     cfg = ServerConfig(
         name=name or "agentirc",
@@ -195,6 +198,7 @@ def _resolve_config(args: argparse.Namespace) -> "ServerConfig":  # noqa: F821 (
         links=_resolve_links(getattr(args, "link", None), raw.get("links") or []),
         system_bots=raw.get("system_bots") or {},
         telemetry=_build_telemetry(raw.get("telemetry") or {}),
+        event_subscription_queue_max=event_subscription_queue_max,
     )
 
     args.name = name  # may be None — handler resolves via default-server file