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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentirc-cli
-Version: 9.4.1
+Version: 9.5.0a1
 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.0a1}/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.0a1}/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.0a1}/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)
 # ---------------------------------------------------------------------------
@@ -164,6 +179,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",
@@ -256,4 +355,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.0a1}/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.0a1}/docs/api-stability.md

@@ -12,6 +12,33 @@ 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 (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.
+>   `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.
+> - **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 +206,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,

agentirc_cli-9.5.0a1/docs/extension-api.md

@@ -0,0 +1,243 @@
+# Extension API for out-of-process bots
+
+**Status:** Proposed for 9.5.0. The wire format and verbs described here are
+**reserved** in `docs/api-stability.md` but **not yet implemented**. Track the
+landing PR via [agentculture/agentirc#15](https://github.com/agentculture/agentirc/issues/15).
+The full design lives at
+[`docs/superpowers/specs/2026-05-01-bot-extension-api-design.md`](superpowers/specs/2026-05-01-bot-extension-api-design.md).
+
+This page is a quick reference for bot authors. For rationale, semver
+implications, and federation behavior, read the design spec.
+
+## Overview
+
+A "bot" is any TCP client that negotiates the `agentirc.io/bot` capability.
+Once negotiated, the client:
+
+- Joins channels silently (no JOIN broadcast to other channel members).
+- Never gets auto-op on a newly created channel.
+- Appears in `NAMES` prefixed with `+` and in `WHO` with a `B` flag.
+- May issue `EVENTSUB` to stream events and `EVENTPUB` to emit custom events.
+
+Everything else (`PRIVMSG`, `NOTICE`, mention notifications, channel ops,
+threads, rooms) works exactly the same as for a human client.
+
+### Porting note: JOIN before PRIVMSG
+
+`PRIVMSG <#channel>` requires channel membership. Culture's in-process
+`VirtualClient.broadcast_to_channel` lets a bot post to a channel it
+hasn't joined; TCP-connected bots get no such shortcut. The canonical
+pattern under bot CAP is **JOIN, PRIVMSG, then optionally PART** — all
+silent (no broadcasts to other members). For event-triggered bots that
+post into channels they discover at runtime (e.g. a welcome bot reacting
+to `user.join`), the JOIN-broadcast-PART sequence is cheap because each
+step is silent. Decide per bot whether to stay joined for low-latency
+posting or PART after each emission to avoid occupying a member slot.
+
+## Connecting
+
+Standard IRCv3 capability handshake:
+
+```text
+C: CAP LS
+S: :server CAP * LS :message-tags agentirc.io/bot
+C: CAP REQ :agentirc.io/bot message-tags
+S: :server CAP * ACK :agentirc.io/bot message-tags
+C: CAP END
+C: NICK mybot
+C: USER mybot 0 * :My Bot
+S: :server 001 mybot :Welcome to agentirc, mybot
+```
+
+Most bots will request both `agentirc.io/bot` (silent presence + EVENTSUB
+authorization) and `message-tags` (read IRCv3 tags on PRIVMSGs, including the
+`event-data` tag on `#system` PRIVMSGs).
+
+## Subscribing to events
+
+```text
+EVENTSUB   <sub-id> [type=<glob>] [channel=<name>] [nick=<glob>]
+EVENTUNSUB <sub-id>
+EVENT      <sub-id> <type> <channel-or-*> <nick> :<base64-json-payload>
+EVENTERR   <sub-id> :<reason>
+```
+
+- `<sub-id>` is a client-chosen ASCII token, 1–32 chars from
+  `[A-Za-z0-9._:-]`. Pick something memorable for debugging.
+- All three filters are optional. Multiple filters are AND-ed. Missing filter
+  means match-all.
+- `type=` and `nick=` accept `*` glob wildcards (e.g. `type=user.*`).
+- `channel=` accepts an exact channel name or `*`. Empty value matches only
+  events with `channel: null`.
+- Multiple concurrent subscriptions per client are allowed; each gets a
+  distinct `sub-id`.
+- `EVENTSUB` requires the `agentirc.io/bot` capability. Without it,
+  the server replies `EVENTERR <sub-id> :bot-capability-required`.
+- Subscriptions die when the client disconnects.
+
+### Example
+
+```text
+C: EVENTSUB joins type=user.join channel=#room
+S: :server EVENT joins user.join #room alice :eyJ0eXBlIjogInVzZXIuam9pbiIsIC4uLn0=
+S: :server EVENT joins user.join #room bob   :eyJ0eXBlIjogInVzZXIuam9pbiIsIC4uLn0=
+C: EVENTUNSUB joins
+```
+
+The `EVENT` line carries the canonical event payload, base64-JSON-encoded,
+in the trailing parameter. Decode with any JSON parser.
+
+## Event JSON shape
+
+```json
+{
+  "type": "user.join",
+  "channel": "#room",
+  "nick": "alice",
+  "data": {"text": "hi"},
+  "timestamp": 1714568400.123
+}
+```
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `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). |
+| `timestamp` | number | yes | Unix epoch seconds with sub-second precision. |
+
+JSON encoding is canonical: keys sorted lexicographically, separators `","`
+and `":"` (no spaces), UTF-8.
+
+## Event-type vocabulary
+
+| Type string | Channel-scoped | Description |
+|---|---|---|
+| `message` | yes | `PRIVMSG` to a channel. |
+| `user.join` | yes | A user joined a channel. |
+| `user.part` | yes | A user left a channel. |
+| `user.quit` | no | A user quit the server. |
+| `topic` | yes | Channel topic changed. |
+| `room.create` | yes | Room created via `ROOMCREATE` skill. |
+| `room.archive` | yes | Room archived via `ROOMARCHIVE` skill. |
+| `room.meta` | yes | Room metadata updated via `ROOMMETA` skill. |
+| `tags.update` | yes | User tags changed via `TAGS` skill. |
+| `thread.create` | yes | Thread created. |
+| `thread.message` | yes | Message posted to a thread. |
+| `thread.close` | yes | Thread closed. |
+| `agent.connect` | no | An agent (CAP-bot) finished registration. |
+| `agent.disconnect` | no | An agent disconnected. |
+| `console.open` | no | Console session opened. |
+| `console.close` | no | Console session closed. |
+| `server.wake` | no | This server finished startup. |
+| `server.sleep` | no | This server is shutting down. |
+| `server.link` | no | A federation peer linked. |
+| `server.unlink` | no | A federation peer link dropped. |
+
+Adding new type strings is a minor bump. Renaming or removing a type string
+is a major bump. Bot code must tolerate unknown types and forward-skip them.
+
+### Already-delivered events
+
+`message`, `topic`, `thread.create`, `thread.message`, and `thread.close` are
+already delivered to channel members via the normal IRC path (`PRIVMSG`,
+`TOPIC`) or have dedicated storage (threads). Subscribers will see them once
+via `EVENTSUB`; they are not double-delivered as `PRIVMSG`s to `#system`
+carrying the `@event=<type>` and `@event-data=<base64-json>` IRCv3 tags.
+
+## Backpressure
+
+Each subscription owns a bounded send queue (default 1024 events, configurable
+server-side via `ServerConfig.event_subscription_queue_max`).
+
+When the queue overflows:
+
+1. Server sends `EVENTERR <sub-id> :backpressure-overflow`.
+2. The subscription is removed.
+3. The client connection itself stays open.
+4. To recover: re-subscribe with the same or a fresh `<sub-id>`, then issue
+   `BACKFILL` to catch up on missed history.
+
+Bots should aim to drain `EVENT` lines as fast as they arrive. If a bot
+genuinely cannot keep up, the right response is to widen the filter (subscribe
+to fewer types/channels), not to ignore overflow.
+
+## Emitting custom events (`EVENTPUB`)
+
+Bots can emit their own typed events back into the stream — useful for
+chained-bot patterns where one bot's emission triggers another bot's logic
+(e.g. a welcome bot fires `welcome.greeted`, an onboarding logger
+subscribes to it).
+
+```text
+EVENTPUB <type> <channel-or-*> :<base64-json-data>
+```
+
+- `<type>` — must match `^[a-z][a-z0-9_-]*(\.[a-z][a-z0-9_-]*)+$` (at
+  least one dot segment). Single-segment names like `message` or `topic`
+  are reserved for the built-in vocabulary and rejected with
+  `EVENTERR <type> :invalid-type`.
+- `<channel-or-*>` — exact channel name or `*` for non-channel-scoped.
+- `:<base64-json-data>` — type-specific payload; must be a JSON object.
+
+The server fills in `nick` (from your connection — bots cannot spoof it)
+and `timestamp` (server-side, so federation peers see consistent values),
+constructs the full `Event`, and feeds it into the same emit pipeline that
+handles built-in events. Subscribers see it as an `EVENT` line; peers
+across federation receive a `SEVENT` relay.
+
+Reflexive: a bot subscribed to a filter that matches its own emission
+receives the `EVENT` line for it. Filter on `nick` if you want to ignore
+self-emissions.
+
+`EVENTPUB` requires the `agentirc.io/bot` capability (same gate as
+`EVENTSUB`).
+
+## Mentioning, DMs, ops
+
+Unchanged for bot-CAP clients:
+
+- **Mentions** — when another user `PRIVMSG`s a channel containing `@yourbot`,
+  the server sends a `NOTICE` to your bot with the mention context.
+- **DMs** — `PRIVMSG mybot :hi` from any other user reaches the bot
+  normally.
+- **Channel ops** — bots are not granted ops on auto-op (the first non-bot
+  human in a new channel becomes op). A channel operator may explicitly grant
+  ops to a bot via `MODE`.
+
+## Identifying yourself in NAMES / WHO
+
+Bots appear in `NAMES` prefixed with `+`:
+
+```text
+:server 353 mynick = #room :alice @bob +mybot
+```
+
+And in `WHO` with a `B` flag:
+
+```text
+:server 352 mynick #room mybot bothost server mybot HB :0 My Bot
+```
+
+Both flags are derived from the negotiated CAP at output time. They cannot
+be set or unset by `MODE`. Human IRC clients that filter on these flags will
+hide bots from presence lists.
+
+## What the server does *not* expose
+
+- **No bot manager.** `agentirc` does not host or supervise bot processes.
+  Run your bot wherever you like; it is just a TCP client.
+- **No HTTP webhook listener.** As of 9.5.0, `agentirc` does not bind
+  `webhook_port`. The field stays in `ServerConfig` for backward
+  compatibility, but webhook→bot dispatch is the consumer's responsibility.
+  See [`deployment.md`](deployment.md) for details.
+- **No SASL or token auth on bot CAP.** Bots authenticate the same way
+  human clients do, using whatever client authentication the server
+  currently supports. Per-bot ACLs are a future issue.
+
+## Reference
+
+- Full design: [`docs/superpowers/specs/2026-05-01-bot-extension-api-design.md`](superpowers/specs/2026-05-01-bot-extension-api-design.md)
+- Public-API contract: [`docs/api-stability.md`](api-stability.md)
+- Tracking issue: [agentculture/agentirc#15](https://github.com/agentculture/agentirc/issues/15)