agentirc-cli 9.5.0a1__tar.gz → 9.5.0a2__tar.gz

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

@@ -4,6 +4,36 @@ 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentirc-cli
-Version: 9.5.0a1
+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.5.0a1 → 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.5.0a1 → 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.5.0a1 → agentirc_cli-9.5.0a2}/agentirc/protocol.py

@@ -147,6 +147,7 @@ SROOMMETA = "SROOMMETA"
 SROOMARCHIVE = "SROOMARCHIVE"
 STAGS = "STAGS"
 STHREAD = "STHREAD"
+SEVENT = "SEVENT"
 BACKFILL = "BACKFILL"
 BACKFILLEND = "BACKFILLEND"
 
@@ -344,6 +345,7 @@ __all__ = [
     "BACKFILL",
     "BACKFILLEND",
     "SERVER",
+    "SEVENT",
     "SJOIN",
     "SMSG",
     "SNICK",

{agentirc_cli-9.5.0a1 → 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.5.0a1 → agentirc_cli-9.5.0a2}/docs/api-stability.md

@@ -14,19 +14,21 @@ import only from these three modules.
 
 > **Bot extension API — phased rollout:**
 >
-> - **9.5.0a1 (current alpha — declarations slice):** `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.
+> - **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. **The symbols are importable; the daemon does not yet handle
->   the verbs and does not advertise `BOT_CAP`** — calling them is a
->   no-op until the behavior slices land.
-> - **9.5.0a2 (planned):** wire-format envelope refactor —
->   `_build_event_payload`/`_encode_event_data` emit the 5-field envelope
->   `{type, channel, nick, data, timestamp}`; federated `SEVENT` shifts
->   to the new shape. Internal change; no new public symbols.
+>   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.

{agentirc_cli-9.5.0a1 → agentirc_cli-9.5.0a2}/docs/extension-api.md

@@ -104,7 +104,7 @@ in the trailing parameter. Decode with any JSON parser.
 | `type` | string | yes | One of the canonical event-type strings (see vocabulary below). Unknown types are tolerated — forward-compat. |
 | `channel` | string-or-null | yes | Channel name for channel-scoped events, `null` otherwise. |
 | `nick` | string | yes | Actor's nickname, or empty string for purely-server-emitted events. |
-| `data` | object | yes | Type-specific payload. Always an object. Keys starting with `_` are reserved metadata (e.g. `_origin` is the originating server name across federation links). |
+| `data` | object | yes | Type-specific payload. Always an object. Subscribers may observe `_`-prefixed metadata keys (most notably `_origin`, the originating server name across federation links). Such keys are **not transmitted** by the originating server — the encoder strips them at emit time, and the receiving server reconstructs `_origin` at decode time from the SEVENT verb args. Peers cannot inject `_render` or other server-internal hints across the federation seam. |
 | `timestamp` | number | yes | Unix epoch seconds with sub-second precision. |
 
 JSON encoding is canonical: keys sorted lexicographically, separators `","`

{agentirc_cli-9.5.0a1 → agentirc_cli-9.5.0a2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentirc-cli"
-version = "9.5.0a1"
+version = "9.5.0a2"
 description = "Agent-friendly IRCd: server core for AI agent meshes"
 readme = "README.md"
 requires-python = ">=3.11"

{agentirc_cli-9.5.0a1 → agentirc_cli-9.5.0a2}/tests/test_events_basic.py

@@ -168,8 +168,15 @@ async def test_event_data_is_base64_json(server, make_client):
         tags = line[at_idx + 1 : space_idx]
     data_piece = [p for p in tags.split(";") if p.startswith("event-data=")][0]
     b64 = data_piece.split("=", 1)[1]
-    decoded = json.loads(base64.b64decode(b64))
-    assert decoded["nick"] == "testserv-bob"
+    envelope = json.loads(base64.b64decode(b64))
+    # Envelope (9.5.0a2+): top-level nick is the event actor (event.nick,
+    # the system user emitting on behalf of the agent); data carries the
+    # type-specific payload, including the agent's own nick.
+    assert envelope["type"] == "agent.connect"
+    assert envelope["nick"] == "system-testserv"
+    assert envelope["data"]["nick"] == "testserv-bob"
+    assert envelope["channel"] is None
+    assert isinstance(envelope["timestamp"], (int, float))
 
 
 @pytest.mark.asyncio

{agentirc_cli-9.5.0a1 → agentirc_cli-9.5.0a2}/tests/test_events_lifecycle.py

@@ -24,6 +24,12 @@ from tests.conftest import IRCTestClient
 def _decode_event_payload(lines: str) -> dict:
     """Extract and decode the IRCv3 `event-data=<b64-json>` tag.
 
+    Returns the 5-field envelope ``{type, channel, nick, data, timestamp}``
+    introduced in 9.5.0a2. Pre-9.5 callers asserting on type-specific fields
+    (e.g. ``payload["text"]``, ``payload["room_id"]``) must navigate one
+    level deeper into ``payload["data"]``; ``nick`` and ``channel`` remain
+    top-level.
+
     ``lines`` is multi-line text as returned by ``recv_until``; scan each
     line for the ``@event=...`` tag blob and decode the matching
     ``event-data=`` value. Only tagged PRIVMSG-style lines start with ``@``.
@@ -305,17 +311,18 @@ async def test_room_create_emitted_on_roomcreate(server, make_client):
     assert "event=room.create" in line, f"Expected room.create tag, got: {line!r}"
     assert "testserv-creator created room #research" in line
 
-    # Lock the structured payload fields downstream consumers rely on.
-    payload = _decode_event_payload(line)
-    assert payload["nick"] == "testserv-creator"
-    assert payload["purpose"] == "AI research"
+    # Lock the structured envelope fields downstream consumers rely on.
+    # Envelope (9.5.0a2+): top-level type/channel/nick/data/timestamp;
+    # type-specific fields nested under data.
+    envelope = _decode_event_payload(line)
+    assert envelope["type"] == "room.create"
+    assert envelope["nick"] == "testserv-creator"
+    assert envelope["channel"] == "#research"
+    assert envelope["data"]["purpose"] == "AI research"
     # room_id is generated server-side — shape check only (starts with "R").
-    assert payload["room_id"].startswith(
+    assert envelope["data"]["room_id"].startswith(
         "R"
-    ), f"Expected room_id to start with R, got: {payload['room_id']!r}"
-    # The server enriches the payload with the channel when the event is
-    # channel-scoped (see IRCd._build_event_payload).
-    assert payload["channel"] == "#research"
+    ), f"Expected room_id to start with R, got: {envelope['data']['room_id']!r}"
 
 
 @pytest.mark.asyncio

agentirc_cli-9.5.0a2/tests/test_wire_format_envelope.py

@@ -0,0 +1,325 @@
+"""Wire-format envelope (9.5.0a2) tests.
+
+Locks in the public 5-field envelope shape that bot subscribers and
+federation peers exchange. Tests:
+
+- Golden-file byte lock: a known ``Event`` encodes to exactly one
+  base64 string. Any change to ``_build_event_envelope`` or
+  ``_encode_event_data`` that breaks this is a wire-format break and
+  must be a major bump per the semver contract.
+- Round-trip: encode → decode → reconstruct ``Event`` → equal to the
+  original (including the floating-point ``timestamp``).
+- Asymmetric sniff tolerance: ``ServerLink._handle_sevent`` decodes
+  both 9.5+ envelope shape AND ≤9.4 legacy data-only shape, letting
+  9.5 daemons read federation traffic from older peers during an
+  in-place upgrade.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import time
+
+import pytest
+
+from agentirc._internal.protocol.message import Message
+from agentirc.ircd import IRCd
+from agentirc.protocol import Event, EventType, SEVENT
+
+
+# ---------------------------------------------------------------------------
+# Golden-file byte lock
+# ---------------------------------------------------------------------------
+
+# A canonical ``user.join`` event with deterministic fields (fixed timestamp
+# so the encoded blob is reproducible across runs) and ``_origin`` in data
+# (must be stripped by ``_build_event_envelope``).
+_GOLDEN_EVENT = Event(
+    type=EventType.JOIN,
+    channel="#room",
+    nick="alice",
+    data={"text": "hi", "_origin": "should-strip"},
+    timestamp=1714568400.0,
+)
+
+# Locked-in expected wire bytes. Derived from the canonical JSON encoding:
+#   {"channel":"#room","data":{"text":"hi"},"nick":"alice","timestamp":1714568400.0,"type":"user.join"}
+# Sorted keys, separators=(",", ":"), UTF-8, then base64.
+_GOLDEN_BASE64 = (
+    "eyJjaGFubmVsIjoiI3Jvb20iLCJkYXRhIjp7InRleHQiOiJoaSJ9LCJuaWNrIjoi"
+    "YWxpY2UiLCJ0aW1lc3RhbXAiOjE3MTQ1Njg0MDAuMCwidHlwZSI6InVzZXIuam9pbiJ9"
+)
+
+
+# ---------------------------------------------------------------------------
+# Federation-test scaffolding helper
+# ---------------------------------------------------------------------------
+
+async def _send_sevent_and_get_event(
+    linked_servers,
+    payload: dict,
+    *,
+    verb_channel: str = "#room",
+    verb_type: str = "user.join",
+    pre_create_channel: bool = True,
+):
+    """Encode payload as SEVENT, dispatch through the alpha→beta link, return the resulting Event.
+
+    Used by every ``test_handle_sevent_*`` test to eliminate per-test
+    scaffolding (the encode + Message + link-lookup + dispatch + event-fetch
+    boilerplate). The payload may be a 9.5+ envelope or a ≤9.4 legacy data
+    dict; the receiver's ``ServerLink._is_envelope`` sniff handles both.
+    """
+    alpha, beta = linked_servers
+    encoded = base64.b64encode(
+        json.dumps(payload, separators=(",", ":"), sort_keys=True).encode("utf-8")
+    ).decode("ascii")
+    alpha_link = next(
+        link for link in beta.links.values() if link.peer_name == alpha.config.name
+    )
+    msg = Message(
+        prefix=None,
+        command=SEVENT,
+        params=[alpha.config.name, "1", verb_type, verb_channel, encoded],
+    )
+    if pre_create_channel and verb_channel != "*":
+        beta.get_or_create_channel(verb_channel)
+    before_count = len(beta._event_log)
+    await alpha_link._handle_sevent(msg)
+    assert len(beta._event_log) == before_count + 1
+    _, ev = beta._event_log[-1]
+    return ev
+
+
+def test_envelope_byte_lock():
+    """The canonical JSON encoding of a known Event matches the golden b64.
+
+    Locks the public wire format under the semver contract. Any change here
+    is a wire-format break — major bump required.
+    """
+    envelope = IRCd._build_event_envelope(_GOLDEN_EVENT)
+    encoded = IRCd._encode_event_data(envelope, "user.join")
+    assert encoded == _GOLDEN_BASE64, (
+        "Wire format break: _build_event_envelope + _encode_event_data no "
+        "longer produces the locked-in canonical encoding. If this is "
+        "intentional, a major version bump is required per docs/api-stability.md."
+    )
+
+
+def test_envelope_strips_underscore_keys():
+    """``_``-prefixed keys (federation metadata) must not leak into ``data``."""
+    envelope = IRCd._build_event_envelope(_GOLDEN_EVENT)
+    assert "_origin" not in envelope["data"]
+    assert envelope["data"] == {"text": "hi"}
+
+
+def test_envelope_shape():
+    """Exactly five keys, predictable types, top-level nick/channel."""
+    envelope = IRCd._build_event_envelope(_GOLDEN_EVENT)
+    assert set(envelope.keys()) == {"type", "channel", "nick", "data", "timestamp"}
+    assert envelope["type"] == "user.join"
+    assert envelope["channel"] == "#room"
+    assert envelope["nick"] == "alice"
+    assert envelope["data"] == {"text": "hi"}
+    # Use pytest.approx to avoid SonarCloud python:S1244 (float equality);
+    # the value round-trips exactly in IEEE 754 so default tolerance suffices.
+    assert envelope["timestamp"] == pytest.approx(1714568400.0)
+
+
+def test_envelope_round_trip():
+    """encode → decode → reconstruct preserves all 5 envelope fields."""
+    envelope = IRCd._build_event_envelope(_GOLDEN_EVENT)
+    encoded = IRCd._encode_event_data(envelope, "user.join")
+    decoded = json.loads(base64.b64decode(encoded))
+    assert decoded == envelope
+
+    # Reconstruct the Event from the decoded envelope (this is what
+    # _handle_sevent does on the receive side).
+    reconstructed = Event(
+        type=decoded["type"],
+        channel=decoded["channel"],
+        nick=decoded["nick"],
+        data=decoded["data"],
+        timestamp=decoded["timestamp"],
+    )
+    assert reconstructed.type == "user.join"
+    assert reconstructed.channel == "#room"
+    assert reconstructed.nick == "alice"
+    assert reconstructed.data == {"text": "hi"}
+    assert reconstructed.timestamp == pytest.approx(1714568400.0)
+
+
+def test_envelope_with_null_channel():
+    """A nick-scoped event has channel=None at the envelope's top level."""
+    ev = Event(
+        type=EventType.AGENT_CONNECT,
+        channel=None,
+        nick="system-alpha",
+        data={"nick": "agent-bob"},
+        timestamp=1714568500.5,
+    )
+    envelope = IRCd._build_event_envelope(ev)
+    assert envelope["channel"] is None
+    assert envelope["nick"] == "system-alpha"
+    assert envelope["data"]["nick"] == "agent-bob"
+
+
+# ---------------------------------------------------------------------------
+# Asymmetric sniff tolerance
+# ---------------------------------------------------------------------------
+
+def test_is_envelope_recognises_9_5_shape():
+    """Sniff returns True for the 5-field envelope shape."""
+    from agentirc.server_link import ServerLink
+
+    decoded = {
+        "type": "user.join",
+        "channel": "#room",
+        "nick": "alice",
+        "data": {"text": "hi"},
+        "timestamp": 1714568400.0,
+    }
+    assert ServerLink._is_envelope(decoded) is True
+
+
+def test_is_envelope_rejects_legacy_data_only_shape():
+    """Sniff returns False for the legacy data-only dict (no top-level type/data)."""
+    from agentirc.server_link import ServerLink
+
+    legacy = {"nick": "alice", "channel": "#room", "text": "hi"}
+    assert ServerLink._is_envelope(legacy) is False
+
+
+def test_is_envelope_rejects_partial_shapes():
+    """Sniff is strict — both `type` (string) AND `data` (dict) must be present."""
+    from agentirc.server_link import ServerLink
+
+    # Has `type` but no `data` dict
+    assert ServerLink._is_envelope({"type": "user.join", "nick": "alice"}) is False
+    # Has `data` but no `type`
+    assert ServerLink._is_envelope({"data": {"text": "hi"}}) is False
+    # `data` present but not a dict
+    assert ServerLink._is_envelope({"type": "user.join", "data": "not-a-dict"}) is False
+    # Empty dict
+    assert ServerLink._is_envelope({}) is False
+
+
+# ---------------------------------------------------------------------------
+# Federation interop via _handle_sevent
+# ---------------------------------------------------------------------------
+
+# These tests exercise _handle_sevent's sniff-and-reconstruct path directly.
+# They use the existing `linked_servers` fixture for the integration round-trip;
+# the unit-level sniff tests above lock in the helper.
+
+@pytest.mark.asyncio
+async def test_handle_sevent_decodes_9_5_envelope(linked_servers):
+    """A 9.5+ peer's envelope payload reconstructs an Event with all 5 fields."""
+    alpha, _ = linked_servers
+    envelope = {
+        "type": "user.join",
+        "channel": "#room",
+        "nick": "alice",
+        "data": {"text": "hi"},
+        "timestamp": 1714568400.0,
+    }
+    ev = await _send_sevent_and_get_event(linked_servers, envelope)
+
+    assert str(ev.type) == "user.join"
+    assert ev.channel == "#room"
+    assert ev.nick == "alice"
+    assert ev.data["text"] == "hi"
+    # Timestamp from the envelope should round-trip (originating peer's clock).
+    assert ev.timestamp == pytest.approx(1714568400.0)
+    # Receiver sets _origin to track the originating peer.
+    assert ev.data["_origin"] == alpha.config.name
+
+
+@pytest.mark.asyncio
+async def test_handle_sevent_ignores_envelope_channel_claim(linked_servers):
+    """Verb-arg channel is authoritative; envelope channel claim is ignored.
+
+    Regression guard for PR #18 review (Qodo 3176230784, Copilot 3176232442):
+    a malformed peer must not be able to bypass the trust check by sending
+    target="*" while putting a restricted channel name in the envelope. The
+    receiver always uses the SEVENT verb-arg channel for both the trust
+    check and the resulting Event.channel.
+    """
+    envelope = {
+        "type": "user.join",
+        # Peer claims #attack-target in the envelope, but verb-arg is "*".
+        "channel": "#attack-target",
+        "nick": "alice",
+        "data": {"text": "hi"},
+        "timestamp": 1714568400.0,
+    }
+    # verb_channel="*" → no trust check fires, no channel injection.
+    ev = await _send_sevent_and_get_event(
+        linked_servers, envelope, verb_channel="*", pre_create_channel=False
+    )
+
+    # Verb-arg "*" mapped to None. Envelope's "#attack-target" is dropped.
+    assert ev.channel is None, (
+        f"Envelope channel claim leaked through trust gate: {ev.channel!r}"
+    )
+
+
+@pytest.mark.asyncio
+async def test_handle_sevent_strips_underscore_metadata(linked_servers):
+    """`_`-prefixed keys in peer-supplied data are stripped before emit_event.
+
+    Regression guard for PR #18 review (Copilot 3176232430): a peer must not
+    be able to inject `_render` (or any other server-internal `_`-prefixed
+    metadata) via SEVENT and influence local surfacing. The receiver strips
+    every `_`-key from the decoded data before adding its own `_origin`.
+    """
+    alpha, _ = linked_servers
+    envelope = {
+        "type": "user.join",
+        "channel": "#room",
+        "nick": "alice",
+        "data": {
+            "text": "hi",
+            "_render": "ATTACKER-CONTROLLED RENDER STRING",
+            "_origin": "spoofed-origin",
+            "_secret_hint": "should-not-survive",
+        },
+        "timestamp": 1714568400.0,
+    }
+    ev = await _send_sevent_and_get_event(linked_servers, envelope)
+
+    # `text` (non-underscore) survives; all peer-supplied `_`-keys do not.
+    assert ev.data["text"] == "hi"
+    assert "_render" not in ev.data, "_render injection survived sevent decode"
+    assert "_secret_hint" not in ev.data
+    # `_origin` is set by the receiver to the actual peer name (not the
+    # spoofed value). The peer-supplied `_origin` was stripped first.
+    assert ev.data["_origin"] == alpha.config.name
+
+
+@pytest.mark.asyncio
+async def test_handle_sevent_decodes_legacy_data_only(linked_servers):
+    """A ≤9.4 peer's data-only payload still reconstructs cleanly via sniff fallback.
+
+    Locks asymmetric tolerance: 9.5 receiver tolerates the legacy 9.4 emit
+    shape so federations can roll forward one peer at a time. Without this
+    sniff, a half-upgraded federation would lose all events from the
+    not-yet-upgraded side.
+    """
+    alpha, _ = linked_servers
+    # Legacy shape: bare data dict, no top-level type or data wrapper.
+    # 9.4 emitters merged nick into the data dict via setdefault.
+    legacy_payload = {"nick": "alice", "channel": "#room", "text": "hi"}
+
+    before = time.time()
+    ev = await _send_sevent_and_get_event(linked_servers, legacy_payload)
+    after = time.time()
+
+    assert str(ev.type) == "user.join"
+    assert ev.channel == "#room"
+    assert ev.nick == "alice"
+    assert ev.data["text"] == "hi"
+    # Legacy peers don't ship a timestamp; receiver fills with time.time().
+    assert before <= ev.timestamp <= after
+    assert ev.data["_origin"] == alpha.config.name

{agentirc_cli-9.5.0a1 → agentirc_cli-9.5.0a2}/uv.lock

@@ -10,7 +10,7 @@ resolution-markers = [
 
 [[package]]
 name = "agentirc-cli"
-version = "9.5.0a1"
+version = "9.5.0a2"
 source = { editable = "." }
 dependencies = [
     { name = "opentelemetry-api" },