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

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

@@ -4,6 +4,34 @@ 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
+
+- Marked the bootstrap closed in `docs/superpowers/specs/2026-04-30-bootstrap-design.md` and `CLAUDE.md`. Tasks 16–18 (tag `v9.4.0`, verify PyPI publish, report-back to culture) are done; the spec status note now reads as a closed timeline ("Released ✅"), and `CLAUDE.md`'s "Current state" reads "bootstrap complete (9.4.0 released)" with a non-blocking follow-ups list linking to issues #7–#12 (Track A wire-format fixes, steward backport, callsite sweep, A2 test migration).
+- Fixed 14 stale `OriNachum/*` GitHub URLs in `pyproject.toml` and the bootstrap spec to canonical `agentculture/*` paths. Investigation showed these weren't merely stylistic — `https://github.com/OriNachum/culture` returns 404 and `https://github.com/OriNachum/agentirc` 301-redirects to the wrong path. URL fixes only; sha256s are content-hashed and unaffected. `cite check` still passes.
+
+### Notes
+
+- Functionally identical to `9.4.0`. Published as a fresh PyPI release because `publish.yml` triggers on push-to-`main` and PyPI rejects re-publishing the same version with different sha256.
+
 ## [9.4.0] - 2026-05-01
 
 ### Added

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

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

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

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

{agentirc_cli-9.4.0 → agentirc_cli-9.5.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.0 → 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.0 → 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.0 → 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.0 → 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,