agentirc-cli 8.6.0__tar.gz → 8.7.1__tar.gz

{agentirc_cli-8.6.0 → agentirc_cli-8.7.1}/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to this project will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [8.7.1] - 2026-04-27
+
+### Added
+
+- `tests/test_socket_path_convergence.py`: parametric regression test asserting all 8 daemon+skill resolvers agree with the CLI's `agent_socket_path()` for both `XDG_RUNTIME_DIR` set and unset.
+- `tests/test_constants.py`: unit tests pinning `culture_runtime_dir()` contract (env precedence, `~/.culture/run/` fallback, mode 0700).
+
+### Changed
+
+- `culture channel {message,list,read}`: when `CULTURE_NICK` is set but the daemon IPC is unreachable or rejects the request, the CLI now prints a stderr warning naming the nick, the socket path, and the GitHub issue tracker before falling back to the peek-nick observer. The fallback itself is preserved for human use (no `CULTURE_NICK`).
+
+### Fixed
+
+- Converged all socket-path resolvers (4 backend daemons, 4 skill irc_clients, overview collector, harness package reference impl) on `culture_runtime_dir()` so the CLI and daemon agree on the IPC socket path when `XDG_RUNTIME_DIR` is unset (macOS default). Previously the daemon listened on `/tmp/culture-<nick>.sock` while the CLI looked in `~/.culture/run/`, causing `culture channel message` to silently fall back to an anonymous `_peek<random>` nick (#302, regression of #203).
+
+## [8.7.0] - 2026-04-26
+
+### Added
+
+- OTEL bot instrumentation (Plan 7): bot.event.dispatch and bot.run spans, culture.bot.invocations counter, culture.bot.webhook.duration histogram, aiohttp-server auto-instrumentation on the webhook listener.
+
+### Changed
+
+- docs/agentirc/telemetry.md updated with the 8.7.0 section; harness-telemetry.md cross-link updated.
+
 ## [8.6.0] - 2026-04-26
 
 ### Added

{agentirc_cli-8.6.0 → agentirc_cli-8.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentirc-cli
-Version: 8.6.0
+Version: 8.7.1
 Summary: Legacy alias for culture — install culture instead
 Project-URL: Homepage, https://github.com/OriNachum/culture
 Author: Ori Nachum
@@ -20,6 +20,7 @@ Requires-Dist: claude-agent-sdk>=0.1
 Requires-Dist: mistune>=3.0
 Requires-Dist: opentelemetry-api>=1.25
 Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.25
+Requires-Dist: opentelemetry-instrumentation-aiohttp-server>=0.46b0
 Requires-Dist: opentelemetry-sdk>=1.25
 Requires-Dist: opentelemetry-semantic-conventions>=0.46b0
 Requires-Dist: pyyaml>=6.0

{agentirc_cli-8.6.0 → agentirc_cli-8.7.1}/culture/bots/bot.py

@@ -8,6 +8,8 @@ import time
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
+from opentelemetry import trace as _otel_trace
+
 from culture.agentirc.skill import Event, EventType
 from culture.bots.config import BOTS_DIR, BotConfig
 from culture.bots.template_engine import render_fallback, render_template
@@ -125,19 +127,28 @@ class Bot:
 
         Returns the rendered message text.
         """
-        if not self.active or not self.virtual_client:
-            raise RuntimeError(f"Bot {self.config.name} is not active")
-
-        message = await self._resolve_message(payload)
-        if not message:
-            return ""
-
-        if self.config.mention:
-            message = f"@{self.config.mention} {message}"
-
-        await self._deliver(message, payload)
-        await self._maybe_fire_event(payload)
-        return message
+        # Span opens before the active-check so, if handle() is invoked for an
+        # inactive bot, the failure still surfaces in tracing with ERROR
+        # status and bot.name set instead of only raising.
+        with _otel_trace.get_tracer("culture.agentirc").start_as_current_span(
+            "bot.run",
+            attributes={"bot.name": self.config.name},
+        ) as span:
+            if not self.active or not self.virtual_client:
+                span.set_status(_otel_trace.StatusCode.ERROR, "bot not active")
+                raise RuntimeError(f"Bot {self.config.name} is not active")
+
+            message = await self._resolve_message(payload)
+            if not message:
+                span.set_attribute("bot.run.empty_message", True)
+                return ""
+
+            if self.config.mention:
+                message = f"@{self.config.mention} {message}"
+
+            await self._deliver(message, payload)
+            await self._maybe_fire_event(payload)
+            return message
 
     async def _resolve_message(self, payload: dict) -> str:
         """Render the message from custom handler or template."""

{agentirc_cli-8.6.0 → agentirc_cli-8.7.1}/culture/bots/bot_manager.py

@@ -2,9 +2,12 @@
 
 from __future__ import annotations
 
+import asyncio
 import logging
 from typing import TYPE_CHECKING
 
+from opentelemetry import trace as _otel_trace
+
 from culture.bots.bot import Bot
 from culture.bots.config import (
     BOT_CONFIG_FILE,
@@ -88,32 +91,58 @@ class BotManager:
     async def on_event(self, event) -> None:
         """Evaluate event-triggered bots against an event and dispatch matches."""
         # Snapshot: handle() may call emit_event() which re-enters on_event().
-        bots_snapshot = list(self.bots.values())
-        for bot in bots_snapshot:
-            cfg = bot.config
-            if cfg.trigger_type != "event":
-                continue
-            compiled = getattr(cfg, "_compiled_filter", None)
-            if compiled is None:
-                continue
-            ctx = {
-                "type": event.type.value if hasattr(event.type, "value") else str(event.type),
-                "channel": event.channel,
-                "nick": event.nick,
-                "data": dict(event.data),
-            }
-            try:
-                if not evaluate(compiled, ctx):
-                    continue
-            except Exception:
-                logger.exception("Filter evaluation failed for bot %s", cfg.name)
-                continue
-            if not await self._try_start_bot(bot):
-                continue
+        ctx = {
+            "type": event.type.value if hasattr(event.type, "value") else str(event.type),
+            "channel": event.channel,
+            "nick": event.nick,
+            "data": dict(event.data),
+        }
+        for bot in list(self.bots.values()):
+            if self._matches_event(bot, ctx):
+                await self._dispatch_to_bot(bot, ctx)
+
+    def _matches_event(self, bot: Bot, ctx: dict) -> bool:
+        """True iff `bot` is event-triggered and its filter accepts `ctx`."""
+        cfg = bot.config
+        if cfg.trigger_type != "event":
+            return False
+        compiled = getattr(cfg, "_compiled_filter", None)
+        if compiled is None:
+            return False
+        try:
+            return bool(evaluate(compiled, ctx))
+        except Exception:
+            logger.exception("Filter evaluation failed for bot %s", cfg.name)
+            return False
+
+    async def _dispatch_to_bot(self, bot: Bot, ctx: dict) -> None:
+        """Lazily start the bot and run handle() inside a bot.event.dispatch span."""
+        if not await self._try_start_bot(bot):
+            return
+        cfg = bot.config
+        event_type_str = ctx["type"]
+        with _otel_trace.get_tracer("culture.agentirc").start_as_current_span(
+            "bot.event.dispatch",
+            attributes={"bot.name": cfg.name, "event.type": event_type_str},
+        ) as span:
+            outcome = "success"
             try:
                 await bot.handle({"event": ctx})
-            except Exception:
-                logger.exception("Bot %s handle() failed for event %s", cfg.name, event.type)
+            except asyncio.CancelledError:
+                raise
+            except Exception as exc:
+                outcome = "error"
+                span.set_status(_otel_trace.StatusCode.ERROR, str(exc))
+                logger.exception("Bot %s handle() failed for event %s", cfg.name, ctx["type"])
+            finally:
+                self.server.metrics.bot_invocations.add(
+                    1,
+                    {
+                        "bot": cfg.name,
+                        "event.type": event_type_str,
+                        "outcome": outcome,
+                    },
+                )
 
     def load_system_bots(self) -> None:
         """Discover and register system bots from the package."""

{agentirc_cli-8.6.0 → agentirc_cli-8.7.1}/culture/bots/http_listener.py

@@ -4,9 +4,11 @@ from __future__ import annotations
 
 import json
 import logging
+import time
 from typing import TYPE_CHECKING
 
 from aiohttp import web
+from opentelemetry.instrumentation.aiohttp_server import AioHttpServerInstrumentor
 
 if TYPE_CHECKING:
     from culture.bots.bot_manager import BotManager
@@ -25,7 +27,16 @@ class HttpListener:
         self._runner: web.AppRunner | None = None
 
     async def start(self) -> None:
-        self._app = web.Application()
+        # Patch aiohttp.web.Application to auto-inject the OTEL server
+        # middleware. Deferred from import time so just importing this module
+        # has no side effect. Re-instrument each start() so the captured
+        # tracer/meter rebinds to the *current* TracerProvider — important for
+        # tests that swap providers between runs, harmless in production.
+        instrumentor = AioHttpServerInstrumentor()
+        if instrumentor.is_instrumented_by_opentelemetry:
+            instrumentor.uninstrument()
+        instrumentor.instrument()
+        self._app = web.Application(middlewares=[self._record_webhook_duration])
         self._app.router.add_get("/health", self._handle_health)
         self._app.router.add_post("/{bot_name}", self._handle_webhook)
 
@@ -41,6 +52,29 @@ class HttpListener:
             self._runner = None
             self._app = None
 
+    @web.middleware
+    async def _record_webhook_duration(self, request, handler):
+        """Record per-request duration into culture.bot.webhook.duration."""
+        bot_name = request.match_info.get("bot_name") or "_unrouted"
+        start = time.perf_counter()
+        # Default for the "handler raised a non-HTTPException" path: aiohttp
+        # converts unhandled exceptions to 500 responses outside this
+        # middleware, so the histogram should report 5xx for them.
+        status_class = "5xx"
+        try:
+            response = await handler(request)
+            status_class = f"{response.status // 100}xx"
+            return response
+        except web.HTTPException as exc:
+            status_class = f"{exc.status // 100}xx"
+            raise
+        finally:
+            duration = time.perf_counter() - start
+            self.bot_manager.server.metrics.bot_webhook_duration.record(
+                duration,
+                {"bot": bot_name, "status_class": status_class},
+            )
+
     async def _handle_health(self, request: web.Request) -> web.Response:
         return web.json_response({"status": "ok"})
 

{agentirc_cli-8.6.0 → agentirc_cli-8.7.1}/culture/cli/channel.py

@@ -24,11 +24,43 @@ def _valid_nick(nick: str) -> bool:
     return len(parts) == 2 and all(parts)
 
 
+_ISSUE_TRACKER_URL = "https://github.com/agentculture/culture/issues"
+
+
+def _warn_observer_fallback(operation: str) -> None:
+    """Warn on stderr when an observer-fallback command silently went anonymous.
+
+    Called only by the three commands that do fall back to the observer
+    connection (`message`, `list`, `read`). `topic` and the `_require_ipc`
+    commands exit on failure instead, so this helper is not used there —
+    a misleading "falling back" notice would contradict the actual error.
+
+    Issue #302: a daemon/CLI socket-path mismatch on macOS hid behind the
+    silent peek fallback for two releases. The warning names the issue
+    tracker so the next reproducer takes seconds to file.
+    """
+    nick = os.environ.get("CULTURE_NICK")
+    if not nick or not _valid_nick(nick):
+        return  # Human use without CULTURE_NICK — observer is the intended path.
+    sock = agent_socket_path(nick)
+    print(
+        f"Warning: agent daemon IPC for {nick} failed ({sock}).\n"
+        f"  Falling back to observer connection — `{operation}` will not run\n"
+        f"  through the agent daemon and the action will not appear under {nick}.\n"
+        f"  Verify the daemon is running:    culture agent status {nick}\n"
+        f"  If it is running, this is a bug. Please open an issue:\n"
+        f"    {_ISSUE_TRACKER_URL}",
+        file=sys.stderr,
+    )
+
+
 def _try_ipc(msg_type: str, **kwargs) -> dict | None:
     """Try to route a command through the agent daemon's IPC socket.
 
     Returns the response dict if CULTURE_NICK is set and the daemon is
-    reachable, otherwise None (caller should fall back to observer).
+    reachable, otherwise None (caller should fall back to observer or
+    surface its own error — see `_warn_observer_fallback` for the
+    observer-fallback path).
     """
     nick = os.environ.get("CULTURE_NICK")
     if not nick or not _valid_nick(nick):
@@ -169,6 +201,7 @@ def _cmd_list(args: argparse.Namespace) -> None:
             print(f"  {ch}")
         return
 
+    _warn_observer_fallback("channel list")
     observer = get_observer(args.config)
     channels = asyncio.run(observer.list_channels())
 
@@ -199,6 +232,7 @@ def _cmd_read(args: argparse.Namespace) -> None:
             print(f"<{nick}> {text}")
         return
 
+    _warn_observer_fallback("channel read")
     observer = get_observer(args.config)
     messages = asyncio.run(observer.read_channel(channel, limit=args.limit))
 
@@ -267,6 +301,7 @@ def _cmd_message(args: argparse.Namespace) -> None:
         print(f"Sent to {target}")
         return
 
+    _warn_observer_fallback("channel message")
     observer = get_observer(args.config)
     asyncio.run(observer.send_message(target, text))
     print(f"Sent to {target}")

agentirc_cli-8.7.1/culture/cli/shared/constants.py

@@ -0,0 +1,54 @@
+"""Shared constants for culture CLI modules."""
+
+import os
+import stat
+
+from culture.bots.config import BOT_CONFIG_FILE  # noqa: F401
+
+DEFAULT_CONFIG = os.path.expanduser("~/.culture/server.yaml")
+LOG_DIR = os.path.expanduser("~/.culture/logs")
+
+_CONFIG_HELP = "Config file path"
+_SERVER_NAME_HELP = "Server name"
+_BOT_NAME_HELP = "Bot name"
+
+DEFAULT_CHANNEL = "#general"
+NO_AGENTS_MSG = "No agents configured"
+CULTURE_DIR = ".culture"
+AGENTS_YAML = "agents.yaml"
+
+DEFAULT_SERVER_CONFIG = os.path.expanduser("~/.culture/server.yaml")
+LEGACY_CONFIG = os.path.expanduser("~/.culture/agents.yaml")
+
+
+def culture_runtime_dir() -> str:
+    """Return a user-private directory for culture daemon sockets.
+
+    Resolution order:
+
+    1. ``$XDG_RUNTIME_DIR`` when set (Linux/systemd default — already
+       user-private at ``/run/user/<uid>``).
+    2. ``~/.culture/run/`` otherwise (typical macOS path), created mode
+       0700 if missing and re-tightened to 0700 on every call so a
+       hand-created or pre-existing dir cannot leak sockets.
+
+    Raises ``RuntimeError`` when neither ``XDG_RUNTIME_DIR`` nor a
+    resolvable home directory is available — silently writing a literal
+    ``~/.culture/run`` directory in CWD would surprise callers and the
+    daemons (which now route through this resolver) would fail at
+    socket-bind time anyway.
+    """
+    xdg = os.environ.get("XDG_RUNTIME_DIR")
+    if xdg:
+        return xdg
+    home = os.path.expanduser("~")
+    if not home or home == "~" or not os.path.isabs(home):
+        raise RuntimeError(
+            "culture_runtime_dir(): cannot resolve a home directory "
+            "(os.path.expanduser('~') returned %r). Set $HOME or "
+            "$XDG_RUNTIME_DIR before running culture commands." % home
+        )
+    fallback = os.path.join(home, ".culture", "run")
+    os.makedirs(fallback, mode=0o700, exist_ok=True)
+    os.chmod(fallback, stat.S_IRWXU)
+    return fallback

{agentirc_cli-8.6.0 → agentirc_cli-8.7.1}/culture/clients/acp/daemon.py

@@ -18,6 +18,7 @@ import time
 from collections import deque
 
 from culture.aio import maybe_await
+from culture.cli.shared.constants import culture_runtime_dir
 from culture.clients.acp.agent_runner import ACPAgentRunner
 from culture.clients.acp.config import AgentConfig, DaemonConfig
 from culture.clients.acp.ipc import make_response
@@ -62,7 +63,7 @@ class ACPDaemon:
         self.skip_agent = skip_agent
 
         self._socket_path = os.path.join(
-            socket_dir or os.environ.get("XDG_RUNTIME_DIR", "/tmp"),
+            socket_dir or culture_runtime_dir(),
             f"culture-{agent.nick}.sock",
         )
 

{agentirc_cli-8.6.0 → agentirc_cli-8.7.1}/culture/clients/acp/skill/irc_client.py

@@ -16,6 +16,7 @@ import os
 import sys
 from typing import Any
 
+from culture.cli.shared.constants import culture_runtime_dir
 from culture.clients.acp.ipc import (
     MSG_TYPE_RESPONSE,
     MSG_TYPE_WHISPER,
@@ -192,8 +193,7 @@ def _sock_path_from_env() -> str:
     if not nick:
         print("ERROR: CULTURE_NICK environment variable is not set", file=sys.stderr)
         sys.exit(1)
-    runtime_dir = os.environ.get("XDG_RUNTIME_DIR", "/tmp")
-    return os.path.join(runtime_dir, f"culture-{nick}.sock")
+    return os.path.join(culture_runtime_dir(), f"culture-{nick}.sock")
 
 
 def _parse_ask_timeout(remaining: list[str]) -> tuple[int, list[str]]:

{agentirc_cli-8.6.0 → agentirc_cli-8.7.1}/culture/clients/claude/daemon.py

@@ -8,6 +8,7 @@ import re
 import time
 
 from culture.aio import maybe_await
+from culture.cli.shared.constants import culture_runtime_dir
 from culture.clients.claude.agent_runner import AgentRunner
 from culture.clients.claude.config import AgentConfig, DaemonConfig
 from culture.clients.claude.ipc import make_response
@@ -51,7 +52,7 @@ class AgentDaemon:
         self.skip_claude = skip_claude
 
         self._socket_path = os.path.join(
-            socket_dir or os.environ.get("XDG_RUNTIME_DIR", "/tmp"),
+            socket_dir or culture_runtime_dir(),
             f"culture-{agent.nick}.sock",
         )
 

{agentirc_cli-8.6.0 → agentirc_cli-8.7.1}/culture/clients/claude/skill/irc_client.py

@@ -16,6 +16,7 @@ import os
 import sys
 from typing import Any
 
+from culture.cli.shared.constants import culture_runtime_dir
 from culture.clients.claude.ipc import (
     MSG_TYPE_RESPONSE,
     MSG_TYPE_WHISPER,
@@ -189,8 +190,7 @@ def _sock_path_from_env() -> str:
     if not nick:
         print("ERROR: CULTURE_NICK environment variable is not set", file=sys.stderr)
         sys.exit(1)
-    runtime_dir = os.environ.get("XDG_RUNTIME_DIR", "/tmp")
-    return os.path.join(runtime_dir, f"culture-{nick}.sock")
+    return os.path.join(culture_runtime_dir(), f"culture-{nick}.sock")
 
 
 def _parse_ask_timeout(remaining: list[str]) -> tuple[int, list[str]]:

{agentirc_cli-8.6.0 → agentirc_cli-8.7.1}/culture/clients/codex/daemon.py

@@ -15,6 +15,7 @@ import time
 from collections import deque
 
 from culture.aio import maybe_await
+from culture.cli.shared.constants import culture_runtime_dir
 from culture.clients.codex.agent_runner import CodexAgentRunner
 from culture.clients.codex.config import AgentConfig, DaemonConfig
 from culture.clients.codex.ipc import make_response
@@ -66,7 +67,7 @@ class CodexDaemon:
         self.skip_codex = skip_codex
 
         self._socket_path = os.path.join(
-            socket_dir or os.environ.get("XDG_RUNTIME_DIR", "/tmp"),
+            socket_dir or culture_runtime_dir(),
             f"culture-{agent.nick}.sock",
         )
 

{agentirc_cli-8.6.0 → agentirc_cli-8.7.1}/culture/clients/codex/skill/irc_client.py

@@ -16,6 +16,7 @@ import os
 import sys
 from typing import Any
 
+from culture.cli.shared.constants import culture_runtime_dir
 from culture.clients.codex.ipc import (
     MSG_TYPE_RESPONSE,
     MSG_TYPE_WHISPER,
@@ -189,8 +190,7 @@ def _sock_path_from_env() -> str:
     if not nick:
         print("ERROR: CULTURE_NICK environment variable is not set", file=sys.stderr)
         sys.exit(1)
-    runtime_dir = os.environ.get("XDG_RUNTIME_DIR", "/tmp")
-    return os.path.join(runtime_dir, f"culture-{nick}.sock")
+    return os.path.join(culture_runtime_dir(), f"culture-{nick}.sock")
 
 
 def _parse_ask_timeout(remaining: list[str]) -> tuple[int, list[str]]:

{agentirc_cli-8.6.0 → agentirc_cli-8.7.1}/culture/clients/copilot/daemon.py

@@ -15,6 +15,7 @@ import time
 from collections import deque
 
 from culture.aio import maybe_await
+from culture.cli.shared.constants import culture_runtime_dir
 from culture.clients.copilot.agent_runner import CopilotAgentRunner
 from culture.clients.copilot.config import AgentConfig, DaemonConfig
 from culture.clients.copilot.ipc import make_response
@@ -59,7 +60,7 @@ class CopilotDaemon:
         self.skip_copilot = skip_copilot
 
         self._socket_path = os.path.join(
-            socket_dir or os.environ.get("XDG_RUNTIME_DIR", "/tmp"),
+            socket_dir or culture_runtime_dir(),
             f"culture-{agent.nick}.sock",
         )
 

{agentirc_cli-8.6.0 → agentirc_cli-8.7.1}/culture/clients/copilot/skill/irc_client.py

@@ -16,6 +16,7 @@ import os
 import sys
 from typing import Any
 
+from culture.cli.shared.constants import culture_runtime_dir
 from culture.clients.copilot.ipc import (
     MSG_TYPE_RESPONSE,
     MSG_TYPE_WHISPER,
@@ -192,8 +193,7 @@ def _sock_path_from_env() -> str:
     if not nick:
         print("ERROR: CULTURE_NICK environment variable is not set", file=sys.stderr)
         sys.exit(1)
-    runtime_dir = os.environ.get("XDG_RUNTIME_DIR", "/tmp")
-    return os.path.join(runtime_dir, f"culture-{nick}.sock")
+    return os.path.join(culture_runtime_dir(), f"culture-{nick}.sock")
 
 
 def _parse_ask_timeout(remaining: list[str]) -> tuple[int, list[str]]:

{agentirc_cli-8.6.0 → agentirc_cli-8.7.1}/culture/overview/collector.py

@@ -7,6 +7,7 @@ import glob
 import os
 
 from culture.bots.config import BOT_CONFIG_FILE
+from culture.cli.shared.constants import culture_runtime_dir
 from culture.protocol.message import Message as IRCMessage
 
 from .model import Agent, BotInfo, MeshState, Message, Room
@@ -428,8 +429,7 @@ async def _enrich_via_ipc(agents: dict[str, Agent], server_name: str) -> None:
     """Enrich local agents with daemon IPC status data."""
     from culture.clients.claude.ipc import decode_message, encode_message, make_request
 
-    runtime_dir = os.environ.get("XDG_RUNTIME_DIR", "/tmp")
-    socket_pattern = os.path.join(runtime_dir, "culture-*.sock")
+    socket_pattern = os.path.join(culture_runtime_dir(), "culture-*.sock")
 
     for sock_path in glob.glob(socket_pattern):
         # Extract nick from socket filename: culture-<nick>.sock

{agentirc_cli-8.6.0 → agentirc_cli-8.7.1}/culture/telemetry/metrics.py

@@ -63,6 +63,9 @@ class MetricsRegistry:
     # Audit (Plan 4)
     audit_writes: Counter
     audit_queue_depth: UpDownCounter
+    # Bots (Plan 7)
+    bot_invocations: Counter
+    bot_webhook_duration: Histogram
 
 
 def reset_for_tests() -> None:
@@ -168,6 +171,16 @@ def _build_registry(meter: Meter) -> MetricsRegistry:
             "culture.audit.queue_depth",
             description="Audit queue depth (records waiting to flush to disk)",
         ),
+        # Bots (Plan 7)
+        bot_invocations=meter.create_counter(
+            "culture.bot.invocations",
+            description="Bot dispatch invocations by bot, event.type, outcome=success|error",
+        ),
+        bot_webhook_duration=meter.create_histogram(
+            "culture.bot.webhook.duration",
+            unit="s",
+            description="Webhook request handler duration by bot and status_class=2xx|3xx|4xx|5xx",
+        ),
     )
 
 

{agentirc_cli-8.6.0 → agentirc_cli-8.7.1}/docs/agentirc/harness-telemetry.md

@@ -230,7 +230,7 @@ corresponding key is present in `usage` with an `int` value.
 
 ## What's not in 8.6.0
 
-- **Bot-side OTEL instrumentation** — Plan 6.
+- **Bot-side OTEL instrumentation** — shipped in 8.7.0 (Plan 7). See [`telemetry.md`](telemetry.html#what-you-get-in-870).
 - **Tracestate injection** — server-parity-deferred. Both server-side
   `client.py` / `server_link.py` and the harness currently pass `tracestate=None`
   when injecting. A future plan will add `current_tracestate()` to

{agentirc_cli-8.6.0 → agentirc_cli-8.7.1}/docs/agentirc/telemetry.md

@@ -9,7 +9,7 @@ nav_order: 90
 
 Culture ships with first-class OpenTelemetry support: traces for every IRC command and event, W3C trace context carried across federation via a new IRCv3 tag, and a local collector pattern that keeps Culture's surface small.
 
-This page covers the **Foundation + Server Tracing** release (culture 8.2.0), **Federation Trace-Context Relay** (culture 8.3.0), the **Metrics Pillar** (culture 8.4.0), the **Audit JSONL Sink** (culture 8.5.0), and **Harness-side OTEL** (culture 8.6.0). Bot instrumentation ships in a subsequent release.
+This page covers the **Foundation + Server Tracing** release (culture 8.2.0), **Federation Trace-Context Relay** (culture 8.3.0), the **Metrics Pillar** (culture 8.4.0), the **Audit JSONL Sink** (culture 8.5.0), **Harness-side OTEL** (culture 8.6.0), and **Bot Instrumentation** (culture 8.7.0).
 
 ## What you get in 8.2.0
 
@@ -189,11 +189,47 @@ For full configuration details, the per-backend `service.name` table, the
 end-to-end test recipe, and a list of what's deferred, see the operator guide at
 [`docs/agentirc/harness-telemetry.html`](harness-telemetry.html).
 
-## What's not in 8.6.0
+## What you get in 8.7.0
+
+Bot instrumentation lands. Event-triggered dispatch and webhook-triggered dispatch each get their own span tree, both stitched into the same trace as the upstream client/server activity that triggered them.
+
+Event-trigger path:
+
+```text
+irc.command.PRIVMSG (or any event-emitting verb)
+└── irc.event.emit
+    └── bot.event.dispatch  (one per matched bot)
+        └── bot.run         (Bot.handle body)
+            └── irc.privmsg.deliver.channel | .dm
+```
+
+Webhook path:
+
+```text
+HTTP POST /<bot_name>      (auto-instrumented inbound span)
+└── bot.run                (Bot.handle body)
+    └── irc.privmsg.deliver.*
+```
+
+New spans:
+
+- `bot.event.dispatch` — one per matched bot inside `BotManager.on_event`. Attributes: `bot.name`, `event.type`. Status `ERROR` if `Bot.handle` raises.
+- `bot.run` — wraps `Bot.handle` for both event and webhook paths. Attributes: `bot.name`, optional `bot.run.empty_message=True` if the rendered message is empty.
+
+The webhook HTTP server is auto-instrumented via [`opentelemetry-instrumentation-aiohttp-server`](https://pypi.org/project/opentelemetry-instrumentation-aiohttp-server/). Each request produces an inbound HTTP server span (verb + path + status code) that becomes the parent of `bot.run`. If the caller sends a `traceparent` header, the request joins their existing trace.
+
+New metrics:
+
+- `culture.bot.invocations` — Counter. Labels: `bot`, `event.type`, `outcome=success|error`. Increments only after the bot has matched the filter and been started — filter rejections and startup failures are logged but not counted.
+- `culture.bot.webhook.duration` — Histogram, `s`. Labels: `bot`, `status_class=2xx|3xx|4xx|5xx`. Recorded by a per-request middleware on the webhook listener. `bot=_unrouted` is used for `/health` and other non-bot paths so the histogram never silently mis-attributes.
+
+Bots add no new wire protocol surface. Trace context flows in via the existing IRCv3 `culture.dev/traceparent` tag for events and via the standard W3C `traceparent` HTTP header for webhooks.
+
+## What's not in 8.7.0
 
 The design spec at `docs/superpowers/specs/2026-04-24-otel-observability-design.md` covers the full three-pillar scope. These pieces remain deferred:
 
-- Bot webhook HTTP instrumentation + bot metrics (`culture.bot.invocations`, `culture.bot.webhook.duration`).
+- Outbound webhook delivery instrumentation (`opentelemetry-instrumentation-aiohttp-client`) — bots currently make no outbound HTTP calls; will be added when that feature lands.
 - Outbound `culture.s2s.messages` (records inbound only — outbound needs a clean verb-extraction site).
 - OTEL Logs export of audit records (best-effort duplicate; JSONL stays source of truth either way).
 - `audit-prune` CLI for retention; operators prune manually in v1.