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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentirc-cli
-Version: 8.6.0
+Version: 8.7.0
 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.0}/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.0}/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.0}/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.0}/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.0}/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.0}/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.

{agentirc_cli-8.6.0 → agentirc_cli-8.7.0}/docs/superpowers/specs/2026-04-24-otel-observability-design.md

@@ -91,7 +91,7 @@ Documents the audit JSONL schema and file layout as a stable contract.
 ### `culture/bots/`
 
 - `BotManager.on_event` — span `bot.event.dispatch` per matched bot, attrs `bot.name`, `event.type`. Metric `culture.bot.invocations{bot, event.type, outcome}`.
-- `http_listener` webhook sender — enable `opentelemetry-instrumentation-aiohttp-client`. Outbound HTTP becomes child spans with traceparent sent as HTTP header automatically. Post-span hook maps status to `status_class` label for `culture.bot.webhook.duration` histogram.
+- `http_listener` webhook receiver — enable `opentelemetry-instrumentation-aiohttp-server`. Inbound HTTP becomes a server span that parents `bot.run`; W3C `traceparent` headers from callers stitch incoming webhooks into their existing trace. A local middleware records the `culture.bot.webhook.duration` histogram (unit `s`) with `{bot, status_class}` labels. **Note (Phase 7, 8.7.0):** the originally-specified outbound `aiohttp-client` instrumentation is deferred — bots make no outbound HTTP calls today; will be added when that feature lands.
 - `Bot` execution — span `bot.run`.
 
 ### `packages/agent-harness/irc_transport.py` (reference, cited into each backend)

{agentirc_cli-8.6.0 → agentirc_cli-8.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentirc-cli"
-version = "8.6.0"
+version = "8.7.0"
 description = "Legacy alias for culture — install culture instead"
 readme = "README.md"
 license = "MIT"
@@ -26,6 +26,7 @@ dependencies = [
     "opentelemetry-sdk>=1.25",
     "opentelemetry-exporter-otlp-proto-grpc>=1.25",
     "opentelemetry-semantic-conventions>=0.46b0",
+    "opentelemetry-instrumentation-aiohttp-server>=0.46b0",
 ]
 
 [project.urls]

{agentirc_cli-8.6.0 → agentirc_cli-8.7.0}/tests/telemetry/_metrics_helpers.py

@@ -64,3 +64,12 @@ def get_histogram_count(reader, name: str, attrs: dict | None = None) -> int:
         if _attrs_match(dict(point.attributes), attrs):
             total += point.count
     return total
+
+
+def get_histogram_sum(reader, name: str, attrs: dict | None = None) -> float:
+    """Sum of recorded values for histogram points matching `attrs`. 0.0 if absent."""
+    total = 0.0
+    for point in _walk_data_points(reader, name):
+        if _attrs_match(dict(point.attributes), attrs):
+            total += point.sum
+    return total

agentirc_cli-8.7.0/tests/telemetry/conftest.py

@@ -0,0 +1,33 @@
+"""Shared fixtures for telemetry integration tests."""
+
+from __future__ import annotations
+
+import pytest_asyncio
+
+from culture.bots.bot_manager import BotManager
+from culture.bots.http_listener import HttpListener
+
+
+@pytest_asyncio.fixture
+async def webhook_server(server, tmp_path, monkeypatch):
+    """IRCd + BotManager + running HttpListener on a random local port.
+
+    Yields ``(server, mgr, port)``. The HttpListener is torn down and all
+    bots stopped at the end of the test.
+    """
+    monkeypatch.setattr("culture.bots.config.BOTS_DIR", tmp_path)
+    monkeypatch.setattr("culture.bots.bot.BOTS_DIR", tmp_path)
+    monkeypatch.setattr("culture.bots.bot_manager.BOTS_DIR", tmp_path)
+
+    mgr = BotManager(server)
+    server.bot_manager = mgr
+
+    listener = HttpListener(mgr, "127.0.0.1", 0)
+    await listener.start()
+    site = next(iter(listener._runner._sites))
+    port = site._server.sockets[0].getsockname()[1]
+
+    yield server, mgr, port
+
+    await listener.stop()
+    await mgr.stop_all()

agentirc_cli-8.7.0/tests/telemetry/test_bot_event_dispatch_span.py

@@ -0,0 +1,138 @@
+"""Spans for BotManager.on_event — bot.event.dispatch (Plan 7)."""
+
+from __future__ import annotations
+
+import pytest
+
+from culture.agentirc.skill import Event, EventType
+
+
+@pytest.mark.asyncio
+async def test_bot_event_dispatch_span_per_match(tracing_exporter, server_with_bot):
+    """A matched event-triggered bot produces one bot.event.dispatch span with attrs."""
+    server, _ = server_with_bot(
+        bot_name="testserv-watcher",
+        trigger_type="event",
+        event_filter="type == 'topic'",
+        channels=["#general"],
+        template="hi {event.nick}",
+    )
+
+    await server.emit_event(
+        Event(
+            type=EventType.TOPIC,
+            channel="#general",
+            nick="testserv-newcomer",
+            data={"body": "hi"},
+        )
+    )
+
+    spans = tracing_exporter.get_finished_spans()
+    dispatch_spans = [
+        s
+        for s in spans
+        if s.name == "bot.event.dispatch" and s.attributes.get("bot.name") == "testserv-watcher"
+    ]
+    assert len(dispatch_spans) == 1, [s.name for s in spans]
+    span = dispatch_spans[0]
+    assert span.attributes["bot.name"] == "testserv-watcher"
+    assert span.attributes["event.type"] == "topic"
+
+    # Parented under irc.event.emit (contextvars-propagated).
+    emit_spans = [s for s in spans if s.name == "irc.event.emit"]
+    assert span.parent is not None
+    assert any(span.parent.span_id == e.context.span_id for e in emit_spans)
+
+
+@pytest.mark.asyncio
+async def test_bot_event_dispatch_span_one_per_matched_bot(tracing_exporter, server_with_bots):
+    """Two bots match the same event → two bot.event.dispatch spans, one per bot."""
+    server, _ = server_with_bots(
+        [
+            {
+                "bot_name": "testserv-a",
+                "trigger_type": "event",
+                "event_filter": "type == 'topic'",
+                "channels": ["#x"],
+                "template": "a",
+            },
+            {
+                "bot_name": "testserv-b",
+                "trigger_type": "event",
+                "event_filter": "type == 'topic'",
+                "channels": ["#x"],
+                "template": "b",
+            },
+        ]
+    )
+
+    await server.emit_event(
+        Event(type=EventType.TOPIC, channel="#x", nick="testserv-z", data={"body": "y"})
+    )
+
+    dispatch_spans = [
+        s
+        for s in tracing_exporter.get_finished_spans()
+        if s.name == "bot.event.dispatch"
+        and s.attributes.get("bot.name") in {"testserv-a", "testserv-b"}
+    ]
+    bot_names = sorted(s.attributes["bot.name"] for s in dispatch_spans)
+    assert bot_names == ["testserv-a", "testserv-b"]
+
+
+@pytest.mark.asyncio
+async def test_no_dispatch_span_when_filter_rejects(tracing_exporter, server_with_bot):
+    """Filter rejection produces no bot.event.dispatch span for that bot."""
+    server, _ = server_with_bot(
+        bot_name="testserv-silent",
+        trigger_type="event",
+        event_filter="channel == '#never'",
+        channels=["#general"],
+        template="x",
+    )
+
+    await server.emit_event(
+        Event(type=EventType.TOPIC, channel="#other", nick="testserv-q", data={"body": "x"})
+    )
+
+    dispatch_spans = [
+        s
+        for s in tracing_exporter.get_finished_spans()
+        if s.name == "bot.event.dispatch" and s.attributes.get("bot.name") == "testserv-silent"
+    ]
+    assert dispatch_spans == []
+
+
+@pytest.mark.asyncio
+async def test_bot_event_dispatch_span_error_status_on_handle_raise(
+    tracing_exporter, server_with_bot, monkeypatch
+):
+    """When Bot.handle raises, the dispatch span carries StatusCode.ERROR."""
+    from opentelemetry.trace import StatusCode
+
+    server, _ = server_with_bot(
+        bot_name="testserv-broken",
+        trigger_type="event",
+        event_filter="type == 'topic'",
+        channels=["#err"],
+        template="x",
+    )
+    bot = server.bot_manager.bots["testserv-broken"]
+
+    async def boom(payload):
+        raise RuntimeError("kaboom")
+
+    monkeypatch.setattr(bot, "handle", boom)
+
+    await server.emit_event(
+        Event(type=EventType.TOPIC, channel="#err", nick="testserv-x", data={"body": "x"})
+    )
+
+    dispatch_spans = [
+        s
+        for s in tracing_exporter.get_finished_spans()
+        if s.name == "bot.event.dispatch" and s.attributes.get("bot.name") == "testserv-broken"
+    ]
+    assert len(dispatch_spans) == 1
+    assert dispatch_spans[0].status.status_code == StatusCode.ERROR
+    assert "kaboom" in (dispatch_spans[0].status.description or "")

agentirc_cli-8.7.0/tests/telemetry/test_bot_run_span.py

@@ -0,0 +1,91 @@
+"""Spans for Bot.handle — bot.run (Plan 7)."""
+
+from __future__ import annotations
+
+import pytest
+
+from culture.agentirc.skill import Event, EventType
+
+
+@pytest.mark.asyncio
+async def test_bot_run_span_parented_under_dispatch(tracing_exporter, server_with_bot):
+    """bot.run span exists and is parented under bot.event.dispatch in the event path."""
+    server, _ = server_with_bot(
+        bot_name="testserv-runner",
+        trigger_type="event",
+        event_filter="type == 'topic'",
+        channels=["#room"],
+        template="hi {event.nick}",
+    )
+
+    await server.emit_event(
+        Event(type=EventType.TOPIC, channel="#room", nick="testserv-x", data={"body": "y"})
+    )
+
+    spans = tracing_exporter.get_finished_spans()
+    run_spans = [
+        s
+        for s in spans
+        if s.name == "bot.run" and s.attributes.get("bot.name") == "testserv-runner"
+    ]
+    assert len(run_spans) == 1
+    run = run_spans[0]
+    assert run.attributes["bot.name"] == "testserv-runner"
+
+    dispatch = next(
+        s
+        for s in spans
+        if s.name == "bot.event.dispatch" and s.attributes.get("bot.name") == "testserv-runner"
+    )
+    assert run.parent is not None
+    assert run.parent.span_id == dispatch.context.span_id
+
+
+@pytest.mark.asyncio
+async def test_bot_run_span_marks_empty_message(tracing_exporter, server_with_bot):
+    """Empty rendered message sets bot.run.empty_message=True."""
+    # Whitespace-only template strips to "" inside Bot._render_message,
+    # forcing the empty-message branch deterministically.
+    server, _ = server_with_bot(
+        bot_name="testserv-empty",
+        trigger_type="event",
+        event_filter="type == 'topic'",
+        channels=["#z"],
+        template="   ",
+    )
+
+    await server.emit_event(
+        Event(type=EventType.TOPIC, channel="#z", nick="testserv-y", data={"body": "x"})
+    )
+
+    run_spans = [
+        s
+        for s in tracing_exporter.get_finished_spans()
+        if s.name == "bot.run" and s.attributes.get("bot.name") == "testserv-empty"
+    ]
+    assert len(run_spans) == 1
+    assert run_spans[0].attributes.get("bot.run.empty_message") is True
+
+
+@pytest.mark.asyncio
+async def test_bot_run_span_via_dispatch_method(tracing_exporter, server_with_bot):
+    """Calling BotManager.dispatch(...) directly (webhook path proxy) still produces bot.run."""
+    server, _ = server_with_bot(
+        bot_name="testserv-direct",
+        trigger_type="webhook",
+        channels=["#hooks"],
+        template="hi {body}",
+    )
+
+    bot = server.bot_manager.bots["testserv-direct"]
+    await bot.start()
+
+    await server.bot_manager.dispatch("testserv-direct", {"body": "ping"})
+
+    run_spans = [
+        s
+        for s in tracing_exporter.get_finished_spans()
+        if s.name == "bot.run" and s.attributes.get("bot.name") == "testserv-direct"
+    ]
+    assert len(run_spans) == 1
+    assert run_spans[0].attributes["bot.name"] == "testserv-direct"