agentirc-cli 9.4.1__tar.gz → 9.5.0a2__tar.gz

{agentirc_cli-9.4.1 → agentirc_cli-9.5.0a2}/CHANGELOG.md

@@ -4,6 +4,53 @@ All notable changes to this project will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [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

{agentirc_cli-9.4.1 → agentirc_cli-9.5.0a2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentirc-cli
-Version: 9.4.1
+Version: 9.5.0a2
 Summary: Agent-friendly IRCd: server core for AI agent meshes
 Project-URL: Homepage, https://github.com/agentculture/agentirc
 Project-URL: Issues, https://github.com/agentculture/agentirc/issues

{agentirc_cli-9.4.1 → agentirc_cli-9.5.0a2}/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.1 → agentirc_cli-9.5.0a2}/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

{agentirc_cli-9.4.1 → agentirc_cli-9.5.0a2}/agentirc/config.py

@@ -53,13 +53,21 @@ class ServerConfig:
     links: list[LinkConfig] = field(default_factory=list)
     system_bots: dict = field(default_factory=dict)
     telemetry: TelemetryConfig = field(default_factory=TelemetryConfig)
+    # Bot extension API (9.5.0): per-subscription event-queue bound. When
+    # exceeded, the subscription is dropped with EVENTERR :backpressure-overflow
+    # and the bot reconciles via re-subscribe + BACKFILL. Behavior wires up in
+    # 9.5.0a3; the field is exposed in 9.5.0a1 so consumers can pin against the
+    # public surface.
+    event_subscription_queue_max: int = 1024
 
     @classmethod
     def from_yaml(cls, path: str | Path) -> "ServerConfig":
         """Load a ServerConfig from a YAML file.
 
         Recognises top-level ``server`` (host/port/name), ``telemetry``,
-        ``links``, ``webhook_port``, ``data_dir``, and ``system_bots``.
+        ``links``, ``webhook_port``, ``data_dir``, ``system_bots``, and
+        ``event_subscription_queue_max`` (added in 9.5.0a1; consumed by
+        the subscription registry that lands in 9.5.0a3).
         Unknown top-level keys (``supervisor``, ``agents``, ``buffer_size``,
         ``poll_interval``, ``sleep_start``, ``sleep_end``) are silently
         ignored — those belong to culture's broader process supervisor,
@@ -104,7 +112,7 @@ def _yaml_kwargs(raw: dict[str, Any]) -> dict[str, Any]:
     for key in ("name", "host", "port"):
         if key in server_section:
             kwargs[key] = server_section[key]
-    for key in ("webhook_port", "data_dir"):
+    for key in ("webhook_port", "data_dir", "event_subscription_queue_max"):
         if key in raw:
             kwargs[key] = raw[key]
     links_section = raw.get("links") or []

{agentirc_cli-9.4.1 → agentirc_cli-9.5.0a2}/agentirc/ircd.py

@@ -275,31 +275,63 @@ class IRCd:
     _NO_SURFACE_TYPES = NO_SURFACE_EVENT_TYPES
 
     @staticmethod
-    def _build_event_payload(event: Event) -> dict:
-        """Build the public event payload, enriched with canonical actor/channel."""
-        payload = {k: v for k, v in event.data.items() if not k.startswith("_")}
-        # Emitters that only set Event.nick (not data['nick']) still get a
-        # correct render + payload thanks to setdefault.
-        if event.nick:
-            payload.setdefault("nick", event.nick)
-        if event.channel:
-            payload.setdefault("channel", event.channel)
-        return payload
+    def _build_event_envelope(event: Event) -> dict:
+        """Build the public 5-field event envelope.
+
+        Shape (semver-stable as of 9.5.0a2)::
+
+            {
+                "type": str,            # wire-form event type, e.g. "user.join"
+                "channel": str | None,  # channel name or None
+                "nick": str,            # actor's nickname (empty for purely-server events)
+                "data": dict,           # type-specific payload, _-prefixed keys stripped
+                "timestamp": float,     # Unix epoch seconds with sub-second precision
+            }
+
+        See ``docs/superpowers/specs/2026-05-01-bot-extension-api-design.md``
+        § Decision A for the rationale and federation-interop story.
+        """
+        type_wire = event.type.value if hasattr(event.type, "value") else str(event.type)
+        return {
+            "type": type_wire,
+            "channel": event.channel,
+            "nick": event.nick,
+            "data": {k: v for k, v in event.data.items() if not k.startswith("_")},
+            "timestamp": event.timestamp,
+        }
 
     @staticmethod
-    def _encode_event_data(payload: dict, type_wire: str) -> str:
-        """Base64-encode the payload as JSON; fall back to '{}' on TypeError."""
+    def _encode_event_data(envelope: dict, type_wire: str) -> str:
+        """Base64-encode the envelope as canonical JSON.
+
+        On serialization failure the fallback is a *minimal but well-formed*
+        envelope ``{type, channel, nick, data, timestamp}`` with empty
+        ``data`` and current wall-clock ``timestamp`` — never a bare ``{}``.
+        Subscribers and federation peers depend on the 5-field shape; an
+        empty-dict fallback would fail the receiver's envelope sniff and
+        be misclassified as legacy data-only, which is worse than emitting
+        an event with no type-specific payload.
+        """
         try:
             return base64.b64encode(
-                json.dumps(payload, separators=(",", ":"), sort_keys=True).encode("utf-8")
+                json.dumps(envelope, separators=(",", ":"), sort_keys=True).encode("utf-8")
             ).decode("ascii")
         except (TypeError, ValueError) as exc:
             logger.warning(
-                "Event %s payload not JSON-serializable, surfacing with empty payload: %s",
+                "Event %s envelope not JSON-serializable, surfacing empty envelope: %s",
                 type_wire,
                 exc,
             )
-            return base64.b64encode(b"{}").decode("ascii")
+            empty_envelope = {
+                "type": type_wire,
+                "channel": envelope.get("channel") if isinstance(envelope, dict) else None,
+                "nick": envelope.get("nick", "") if isinstance(envelope, dict) else "",
+                "data": {},
+                "timestamp": time.time(),
+            }
+            return base64.b64encode(
+                json.dumps(empty_envelope, separators=(",", ":"), sort_keys=True).encode("utf-8")
+            ).decode("ascii")
 
     async def _deliver_to_members(self, channel, msg: Message, type_wire: str) -> None:
         """Send the surfaced PRIVMSG to channel members (skipping VirtualClients)."""
@@ -352,9 +384,17 @@ class IRCd:
         origin_server = event.data.get("_origin") or self.config.name
         system_nick = f"{SYSTEM_USER_PREFIX}{origin_server}"
 
-        payload = self._build_event_payload(event)
-        encoded = self._encode_event_data(payload, type_wire)
-        body = event.data.get("_render") or render_event(type_wire, payload, event.channel)
+        envelope = self._build_event_envelope(event)
+        encoded = self._encode_event_data(envelope, type_wire)
+        # Render templates expect the type-specific data dict (with nick/channel
+        # merged in for backward compat with the pre-9.5 render-function shape),
+        # not the envelope. Reconstruct the legacy data shape for render only.
+        render_data = dict(envelope["data"])
+        if event.nick:
+            render_data.setdefault("nick", event.nick)
+        if event.channel:
+            render_data.setdefault("channel", event.channel)
+        body = event.data.get("_render") or render_event(type_wire, render_data, event.channel)
 
         msg = Message(
             tags={EVENT_TAG_TYPE: type_wire, EVENT_TAG_DATA: encoded},

{agentirc_cli-9.4.1 → agentirc_cli-9.5.0a2}/agentirc/protocol.py

@@ -1,6 +1,6 @@
-"""Public protocol surface for agentirc — verbs, numerics, and tags.
+"""Public protocol surface for agentirc — verbs, numerics, tags, and the bot extension API.
 
-Semver-tracked module. Three categories of constants live here:
+Semver-tracked module. Five categories of public symbols live here:
 
 1. **Verb names** — IRC command verbs as bare uppercase tokens. Mostly
    RFC 2812 (PRIVMSG, JOIN, QUIT, ...), plus agentirc skill verbs
@@ -14,6 +14,16 @@ Semver-tracked module. Three categories of constants live here:
    consumers don't reach into the underscore namespace.
 3. **Message tag names** — IRCv3 tag keys for traceparent/tracestate
    and agentirc-specific event tags.
+4. **Event types and the Event dataclass** — :class:`EventType`
+   (a :class:`enum.StrEnum` of 20 dotted-lowercase wire strings) and
+   :class:`Event` (a frozen-shape dataclass). Plus 20 ``EVENT_TYPE_*``
+   per-type string constants for callers that prefer bare strings over
+   enum-coercion at JSON boundaries. Added in 9.5.0a1 as part of the
+   bot extension API.
+5. **Bot extension verbs and capability** — ``EVENTSUB``, ``EVENTUNSUB``,
+   ``EVENT``, ``EVENTERR``, ``EVENTPUB`` verb constants and
+   ``BOT_CAP = "agentirc.io/bot"``. Reserved in 9.5.0a1; daemon
+   behavior wires up in 9.5.0a3 / 9.5.0 final.
 
 Existing call sites under ``agentirc.ircd``, ``agentirc.server_link``
 and the skills modules still use inline string literals. Migrating them
@@ -31,6 +41,11 @@ clients and federation. They need a coordinated cross-repo bump.
 
 from __future__ import annotations
 
+import time
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
 # ---------------------------------------------------------------------------
 # Numeric reply codes (re-exported from the internal module)
 # ---------------------------------------------------------------------------
@@ -132,6 +147,7 @@ SROOMMETA = "SROOMMETA"
 SROOMARCHIVE = "SROOMARCHIVE"
 STAGS = "STAGS"
 STHREAD = "STHREAD"
+SEVENT = "SEVENT"
 BACKFILL = "BACKFILL"
 BACKFILLEND = "BACKFILLEND"
 
@@ -164,6 +180,90 @@ ROOMETAEND = "ROOMETAEND"  # SIC: typo preserved for wire compat (ROOMMETAEND ta
 ROOMETASET = "ROOMETASET"  # SIC: typo preserved for wire compat (ROOMMETASET target)
 
 
+# ---------------------------------------------------------------------------
+# Bot extension API (9.5.0)
+# ---------------------------------------------------------------------------
+# Public Event dataclass + EventType enum, per-type string constants, the
+# EVENTSUB / EVENTUNSUB / EVENT / EVENTERR / EVENTPUB verb names, and the
+# bot-CAP token. See docs/superpowers/specs/2026-05-01-bot-extension-api-design.md
+# for the wire format and verb syntax. Behavior wiring lands in 9.5.0a2/a3;
+# 9.5.0a1 ships these symbols only.
+
+# `EventType` is `StrEnum` so `EventType.JOIN == "user.join"` is True at JSON
+# boundaries. Adding a new member is a minor bump; renaming or removing one
+# is a major bump.
+
+
+class EventType(StrEnum):
+    MESSAGE = "message"
+    JOIN = "user.join"
+    PART = "user.part"
+    QUIT = "user.quit"
+    TOPIC = "topic"
+    ROOMMETA = "room.meta"
+    TAGS = "tags.update"
+    ROOMARCHIVE = "room.archive"
+    THREAD_CREATE = "thread.create"
+    THREAD_MESSAGE = "thread.message"
+    THREAD_CLOSE = "thread.close"
+    AGENT_CONNECT = "agent.connect"
+    AGENT_DISCONNECT = "agent.disconnect"
+    CONSOLE_OPEN = "console.open"
+    CONSOLE_CLOSE = "console.close"
+    SERVER_WAKE = "server.wake"
+    SERVER_SLEEP = "server.sleep"
+    SERVER_LINK = "server.link"
+    SERVER_UNLINK = "server.unlink"
+    ROOM_CREATE = "room.create"
+
+
+@dataclass
+class Event:
+    # `type` is widened to `EventType | str` so federation peers can deliver
+    # event types this version doesn't recognise without raising. Subscribers
+    # must tolerate unknown types (forward-compat).
+    type: EventType | str
+    channel: str | None
+    nick: str
+    data: dict[str, Any] = field(default_factory=dict)
+    timestamp: float = field(default_factory=time.time)
+
+
+# Per-type string constants — parallel to `EventType` for callers that prefer
+# bare strings (e.g. comparing JSON-decoded `type` field without enum-coercing).
+EVENT_TYPE_MESSAGE = "message"
+EVENT_TYPE_USER_JOIN = "user.join"
+EVENT_TYPE_USER_PART = "user.part"
+EVENT_TYPE_USER_QUIT = "user.quit"
+EVENT_TYPE_TOPIC = "topic"
+EVENT_TYPE_ROOM_META = "room.meta"
+EVENT_TYPE_TAGS_UPDATE = "tags.update"
+EVENT_TYPE_ROOM_ARCHIVE = "room.archive"
+EVENT_TYPE_THREAD_CREATE = "thread.create"
+EVENT_TYPE_THREAD_MESSAGE = "thread.message"
+EVENT_TYPE_THREAD_CLOSE = "thread.close"
+EVENT_TYPE_AGENT_CONNECT = "agent.connect"
+EVENT_TYPE_AGENT_DISCONNECT = "agent.disconnect"
+EVENT_TYPE_CONSOLE_OPEN = "console.open"
+EVENT_TYPE_CONSOLE_CLOSE = "console.close"
+EVENT_TYPE_SERVER_WAKE = "server.wake"
+EVENT_TYPE_SERVER_SLEEP = "server.sleep"
+EVENT_TYPE_SERVER_LINK = "server.link"
+EVENT_TYPE_SERVER_UNLINK = "server.unlink"
+EVENT_TYPE_ROOM_CREATE = "room.create"
+
+# Bot extension verbs.
+EVENTSUB = "EVENTSUB"
+EVENTUNSUB = "EVENTUNSUB"
+EVENT = "EVENT"
+EVENTERR = "EVENTERR"
+EVENTPUB = "EVENTPUB"
+
+# Bot-CAP token. Vendored namespace per IRCv3 conventions, prevents collision
+# with hypothetical bare-`bot` caps from non-agentirc IRC servers.
+BOT_CAP = "agentirc.io/bot"
+
+
 __all__ = [
     # Numerics
     "ERR_ALREADYREGISTRED",
@@ -245,6 +345,7 @@ __all__ = [
     "BACKFILL",
     "BACKFILLEND",
     "SERVER",
+    "SEVENT",
     "SJOIN",
     "SMSG",
     "SNICK",
@@ -256,4 +357,33 @@ __all__ = [
     "STAGS",
     "STHREAD",
     "STOPIC",
+    # Bot extension API (9.5.0)
+    "BOT_CAP",
+    "EVENT",
+    "EVENTERR",
+    "EVENTPUB",
+    "EVENTSUB",
+    "EVENTUNSUB",
+    "Event",
+    "EventType",
+    "EVENT_TYPE_AGENT_CONNECT",
+    "EVENT_TYPE_AGENT_DISCONNECT",
+    "EVENT_TYPE_CONSOLE_CLOSE",
+    "EVENT_TYPE_CONSOLE_OPEN",
+    "EVENT_TYPE_MESSAGE",
+    "EVENT_TYPE_ROOM_ARCHIVE",
+    "EVENT_TYPE_ROOM_CREATE",
+    "EVENT_TYPE_ROOM_META",
+    "EVENT_TYPE_SERVER_LINK",
+    "EVENT_TYPE_SERVER_SLEEP",
+    "EVENT_TYPE_SERVER_UNLINK",
+    "EVENT_TYPE_SERVER_WAKE",
+    "EVENT_TYPE_TAGS_UPDATE",
+    "EVENT_TYPE_THREAD_CLOSE",
+    "EVENT_TYPE_THREAD_CREATE",
+    "EVENT_TYPE_THREAD_MESSAGE",
+    "EVENT_TYPE_TOPIC",
+    "EVENT_TYPE_USER_JOIN",
+    "EVENT_TYPE_USER_PART",
+    "EVENT_TYPE_USER_QUIT",
 ]

{agentirc_cli-9.4.1 → agentirc_cli-9.5.0a2}/agentirc/server_link.py

@@ -11,6 +11,7 @@ from typing import TYPE_CHECKING
 from opentelemetry import trace as otel_trace
 from opentelemetry.context import Context as _OtelContext
 
+from agentirc import protocol
 from agentirc.remote_client import RemoteClient
 from agentirc.skill import Event, EventType
 from agentirc._internal.aio import maybe_await
@@ -887,34 +888,83 @@ class ServerLink:
         except ValueError:
             return type_str
 
+    @staticmethod
+    def _is_envelope(decoded: dict) -> bool:
+        """Sniff whether a decoded SEVENT payload is a 9.5+ 5-field envelope.
+
+        9.5+ peers emit ``{type, channel, nick, data, timestamp}`` with a
+        nested ``data`` dict. 9.4 and earlier peers emit the type-specific
+        ``data`` dict directly (no outer envelope, no top-level ``type``).
+        Both are valid SEVENT payloads on the wire; this sniff lets a 9.5
+        receiver tolerate either shape so federations can roll forward one
+        peer at a time.
+        """
+        return (
+            isinstance(decoded.get("type"), str)
+            and isinstance(decoded.get("data"), dict)
+        )
+
     async def _handle_sevent(self, msg: Message) -> None:
         """Ingest a generic federated event from a peer.
 
-        Wire format: SEVENT <origin-server> <seq> <type> <channel_or_*> :<b64-json-data>
+        Wire format: SEVENT <origin-server> <seq> <type> <channel_or_*> :<b64-json>
+
+        The base64-JSON payload is the 5-field envelope from 9.5+ peers, or
+        a bare type-specific data dict from ≤9.4 peers (asymmetric tolerance
+        via :meth:`_is_envelope`). Either way we reconstruct an :class:`Event`
+        with all five fields populated, falling back to ``time.time()`` for
+        ``timestamp`` only when the legacy peer didn't provide one.
         """
         if len(msg.params) < 5:
             return
         origin, _seq, type_str, target, b64 = msg.params[:5]
-        channel = None if target == "*" else target
+        verb_channel = None if target == "*" else target
 
         if origin != self.peer_name:
             logger.warning("SEVENT origin %s != peer %s", origin, self.peer_name)
 
-        if channel is not None and not self._check_incoming_trust(channel):
+        if verb_channel is not None and not self._check_incoming_trust(verb_channel):
             return
 
-        data = self._decode_sevent_payload(b64, self.peer_name)
-        if data is None:
+        decoded = self._decode_sevent_payload(b64, self.peer_name)
+        if decoded is None:
             return
 
+        if self._is_envelope(decoded):
+            # 9.5+ envelope. Verb-arg type wins on mismatch (defensive — the
+            # SEVENT line is the canonical type carrier).
+            raw_data = decoded["data"]
+            nick = decoded.get("nick") or f"{SYSTEM_USER_PREFIX}{origin}"
+            timestamp = decoded.get("timestamp")
+            if not isinstance(timestamp, (int, float)):
+                timestamp = time.time()
+        else:
+            # ≤9.4 legacy: decoded dict IS the data payload.
+            raw_data = decoded
+            nick = raw_data.get("nick", f"{SYSTEM_USER_PREFIX}{origin}")
+            timestamp = time.time()
+
+        # Verb-arg channel is authoritative for routing and trust: the
+        # _check_incoming_trust() above gated on it. Ignore any channel claim
+        # in the envelope — a malformed/malicious peer must not be able to
+        # bypass trust by sending target="*" while putting a restricted
+        # channel name in the envelope.
+        channel = verb_channel
+
+        # Strip incoming `_`-prefixed keys from the peer-supplied data before
+        # we add our own `_origin` marker. `_render` and similar server-side
+        # hints must not be peer-controllable; allowing them would let a
+        # peer dictate the human-readable surfacing on this server.
+        data = {k: v for k, v in raw_data.items() if not k.startswith("_")}
         data["_origin"] = origin
         type_enum = self._parse_event_type(type_str)
 
         ev = Event(
             type=type_enum,
             channel=channel,
-            nick=data.get("nick", f"{SYSTEM_USER_PREFIX}{origin}"),
+            nick=nick,
             data=data,
+            timestamp=timestamp,
         )
         await self.server.emit_event(ev)
 
@@ -1014,14 +1064,14 @@ class ServerLink:
             else:
                 # If no typed relay exists, fall back to generic SEVENT.
                 # v1 assumes all peers support SEVENT; cap negotiation is deferred — see plan task 12.
-                payload = self.server._build_event_payload(event)
-                encoded = self.server._encode_event_data(payload, event_type_str)
+                envelope = self.server._build_event_envelope(event)
+                encoded = self.server._encode_event_data(envelope, event_type_str)
                 target = event.channel or "*"
                 # Egress trust check: channel-scoped events respect should_relay; global events always relay
                 if event.channel is None or self.should_relay(event.channel):
                     seq = self.server._seq  # current local seq; peer stores but doesn't re-sequence
                     await self.send_raw(
-                        f":{origin} SEVENT {origin} {seq} {event_type_str} {target} :{encoded}"
+                        f":{origin} {protocol.SEVENT} {origin} {seq} {event_type_str} {target} :{encoded}"
                     )
                     relayed = True
 

{agentirc_cli-9.4.1 → agentirc_cli-9.5.0a2}/agentirc/skill.py

@@ -1,9 +1,15 @@
 from __future__ import annotations
 
-import time
-from dataclasses import dataclass, field
-from enum import Enum
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
+
+# Event and EventType moved to agentirc.protocol in 9.5.0a1 as part of the
+# bot extension API public surface. This module keeps re-exporting them so
+# internal call sites and any pre-9.5 vendored consumers keep working; the
+# re-export is removed in 9.6.0 once Phase A2 confirms no consumer relies on
+# this path.
+from agentirc.protocol import Event, EventType
+
+__all__ = ["Event", "EventType", "Skill"]
 
 if TYPE_CHECKING:
     from agentirc.client import Client
@@ -11,39 +17,6 @@ if TYPE_CHECKING:
     from agentirc._internal.protocol.message import Message
 
 
-class EventType(Enum):
-    MESSAGE = "message"
-    JOIN = "user.join"
-    PART = "user.part"
-    QUIT = "user.quit"
-    TOPIC = "topic"
-    ROOMMETA = "room.meta"
-    TAGS = "tags.update"
-    ROOMARCHIVE = "room.archive"
-    THREAD_CREATE = "thread.create"
-    THREAD_MESSAGE = "thread.message"
-    THREAD_CLOSE = "thread.close"
-    # Lifecycle + link events introduced by mesh-events feature.
-    AGENT_CONNECT = "agent.connect"
-    AGENT_DISCONNECT = "agent.disconnect"
-    CONSOLE_OPEN = "console.open"
-    CONSOLE_CLOSE = "console.close"
-    SERVER_WAKE = "server.wake"
-    SERVER_SLEEP = "server.sleep"
-    SERVER_LINK = "server.link"
-    SERVER_UNLINK = "server.unlink"
-    ROOM_CREATE = "room.create"
-
-
-@dataclass
-class Event:
-    type: EventType
-    channel: str | None
-    nick: str
-    data: dict[str, Any] = field(default_factory=dict)
-    timestamp: float = field(default_factory=time.time)
-
-
 class Skill:
     name: str = ""
     commands: set[str] = set()

{agentirc_cli-9.4.1 → agentirc_cli-9.5.0a2}/docs/api-stability.md

@@ -12,6 +12,35 @@ import only from these three modules.
 | [`agentirc.cli`](#agentirccli) | `main()`, `dispatch(argv) -> int` | Public, semver-tracked |
 | [`agentirc.protocol`](#agentircprotocol) | Verb constants, numeric reply codes, IRCv3/extension tag names | Public, semver-tracked |
 
+> **Bot extension API — phased rollout:**
+>
+> - **9.5.0a1 (shipped):** `agentirc.protocol` exports the `Event`
+>   dataclass, the `EventType` enum (now `StrEnum`), 20 per-type
+>   `EVENT_TYPE_*` string constants, the `EVENTSUB`/`EVENTUNSUB`/
+>   `EVENT`/`EVENTERR`/`EVENTPUB` verb constants, and the
+>   `BOT_CAP = "agentirc.io/bot"` capability identifier.
+>   `ServerConfig` gains the `event_subscription_queue_max: int = 1024`
+>   field. **Declarations slice — symbols are importable but inert.**
+> - **9.5.0a2 (current alpha — wire-format slice):** `IRCd._build_event_payload`
+>   replaced by `IRCd._build_event_envelope`. Federated `SEVENT` payload
+>   and the IRCv3 `event-data` tag on `#system` PRIVMSGs now carry the
+>   canonical 5-field envelope `{type, channel, nick, data, timestamp}`.
+>   `ServerLink._handle_sevent` sniffs the shape so 9.5 receivers
+>   tolerate both envelope (9.5+ peers) and legacy data-only (≤9.4
+>   peers); 9.5→9.4 emit breaks until peers upgrade. Internal change;
+>   no new public symbols. See CHANGELOG `[9.5.0a2]` § Notes.
+> - **9.5.0a3 (planned):** bot-CAP behavior, `EVENTSUB`/`EVENTUNSUB`
+>   handlers, the in-memory `SubscriptionRegistry`, and `EVENTPUB`
+>   handler. Daemon starts advertising `BOT_CAP` in `CAP LS` output.
+> - **9.5.0 (final):** `webhook_port` no longer bound; `cli.md` /
+>   `deployment.md` updated; this block flips from "phased rollout" to
+>   "current," and the version-history table picks up a 9.5.0 row.
+>
+> Wire format and verb syntax are specified in
+> [`docs/superpowers/specs/2026-05-01-bot-extension-api-design.md`](superpowers/specs/2026-05-01-bot-extension-api-design.md);
+> a quick reference for bot authors is at [`docs/extension-api.md`](extension-api.md).
+> Tracking issue: [agentculture/agentirc#15](https://github.com/agentculture/agentirc/issues/15).
+
 ## Semver contract
 
 Following [SemVer 2.0](https://semver.org/):
@@ -179,6 +208,35 @@ Re-exported from `agentirc._internal.protocol.replies`. About 33 names:
 Re-exported from `agentirc._internal.telemetry.context`:
 `TRACEPARENT_TAG`, `TRACESTATE_TAG`, `EVENT_TAG_TYPE`, `EVENT_TAG_DATA`.
 
+### Reserved for 9.5.0: bot extension surface
+
+These additions are **specified but not yet implemented**. They will land
+together as a single minor bump in 9.5.0 — see the design spec at
+[`docs/superpowers/specs/2026-05-01-bot-extension-api-design.md`](superpowers/specs/2026-05-01-bot-extension-api-design.md)
+for rationale, federation behavior, and acceptance criteria, and
+[`docs/extension-api.md`](extension-api.md) for the bot-author quick
+reference.
+
+- **Event verbs:** `EVENTSUB`, `EVENTUNSUB`, `EVENT`, `EVENTERR`, `EVENTPUB`. Subscribers stream events with filter syntax (`type=`/`channel=`/`nick=` AND-ed globs); `EVENTPUB` lets a bot emit its own typed events back into the stream (server-side validation of `type` against `EVENT_TYPE_RE`; `nick` and `timestamp` derived server-side, not trusted from the client).
+- **Bot capability:** `BOT_CAP = "agentirc.io/bot"`. When negotiated via
+  the existing CAP REQ/ACK flow, the connection is treated as a bot:
+  silent JOIN/PART/QUIT broadcasts, no auto-op on channel creation,
+  `+` prefix in NAMES output, `B` flag in WHO output, authorized to
+  issue `EVENTSUB`.
+- **Event dataclass and enum:** `Event` and `EventType` (currently
+  internal in `agentirc.skill`). Promoted to public for Python consumers.
+  Wire format — not the Python class names — is the contract; non-Python
+  bots pin against the JSON shape documented in `extension-api.md`.
+- **Per-type string constants:** `EVENT_TYPE_MESSAGE`,
+  `EVENT_TYPE_USER_JOIN`, …, one per type-string in the canonical
+  vocabulary. Convenience for callers that prefer non-enum-aware
+  constants.
+
+The `ServerConfig` additions (one new field
+`event_subscription_queue_max: int = 1024`) and the `webhook_port`
+binding-removal are described under
+[`agentirc.config`](#agentircconfig) once 9.5.0 lands.
+
 ### Wire-format quirks (preserved verbatim)
 
 Four known wire-format issues are **preserved** rather than fixed,