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

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

@@ -4,6 +4,35 @@ 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
+
+- Harness-side OTEL: 3 spans (harness.irc.connect, harness.irc.message.handle, harness.llm.call) and 4 LLM metrics (culture.harness.llm.tokens.input/output, call.duration, calls).
+- W3C traceparent injection on outbound IRC + extraction on inbound — single trace_id now spans server, federation, and harness in the cross-process tree.
+- Per-backend telemetry citation across claude/codex/copilot/acp with all-backends parity test (24 tests across 6 dimensions) locking down drift.
+- docs/agentirc/harness-telemetry.md — new operator guide for the harness OTEL pillar.
+
+### Changed
+
+- packages/agent-harness/{telemetry.py,config.py,culture.yaml,irc_transport.py,daemon.py} — reference module for the citation pattern.
+- culture/clients/{claude,codex,copilot,acp}/{telemetry.py,config.py,culture.yaml,irc_transport.py,daemon.py,agent_runner.py} — telemetry citation, harness.llm.call span wrap, record_llm_call invocation.
+- tests/harness/ — 70 new tests (24 parity + 46 module/runner/transport/daemon).
+
+### Fixed
+
+- Code-quality fixes from review: zero-token usage extraction (0 no longer silenced), tracer-name from constant (no hardcoded strings), module-top imports of record_llm_call across all 4 backends.
+
 ## [8.5.0] - 2026-04-25
 
 ### Added

{agentirc_cli-8.5.0 → agentirc_cli-8.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentirc-cli
-Version: 8.5.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.5.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.5.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.5.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.5.0 → agentirc_cli-8.7.0}/culture/clients/acp/agent_runner.py

@@ -12,9 +12,16 @@ import logging
 import os
 import shutil
 import tempfile
-from typing import Any, Awaitable, Callable
+import time
+from typing import TYPE_CHECKING, Any, Awaitable, Callable
+
+from opentelemetry import trace as _otel_trace
 
 from culture.aio import maybe_await
+from culture.clients.acp.telemetry import _HARNESS_TRACER_NAME, record_llm_call
+
+if TYPE_CHECKING:
+    from culture.clients.acp.telemetry import HarnessMetricsRegistry
 
 logger = logging.getLogger(__name__)
 
@@ -36,6 +43,8 @@ class ACPAgentRunner:
         on_exit: Callable[[int], Awaitable[None]] | None = None,
         on_message: Callable[[dict[str, Any]], Awaitable[None]] | None = None,
         on_turn_error: Callable[[], Awaitable[None] | None] | None = None,
+        metrics: HarnessMetricsRegistry | None = None,
+        nick: str = "",
     ) -> None:
         self.model = model
         self.directory = directory
@@ -44,6 +53,8 @@ class ACPAgentRunner:
         self.on_exit = on_exit
         self.on_message = on_message
         self.on_turn_error = on_turn_error
+        self._metrics = metrics
+        self._nick = nick
 
         self._isolated_home: str | None = None
         self._process: asyncio.subprocess.Process | None = None
@@ -431,16 +442,47 @@ class ACPAgentRunner:
 
     async def _execute_single_prompt(self, text: str) -> None:
         """Send one prompt and handle its result, managing the busy flag."""
-        try:
-            self._busy = True
-            resp = await self._send_prompt_with_retry(text)
-            await self._handle_prompt_result(resp)
-        except Exception:
-            logger.exception("ACP turn error")
-            if self.on_turn_error:
-                await maybe_await(self.on_turn_error())
-        finally:
-            self._busy = False
+        start_perf = time.perf_counter()
+        outcome = "success"
+        tracer = _otel_trace.get_tracer(_HARNESS_TRACER_NAME)
+        with tracer.start_as_current_span(
+            "harness.llm.call",
+            attributes={
+                "harness.backend": "acp",
+                "harness.model": self.model,
+                "harness.nick": self._nick,
+            },
+        ):
+            try:
+                self._busy = True
+                resp = await self._send_prompt_with_retry(text)
+                await self._handle_prompt_result(resp)
+            except TimeoutError:  # bubbles from _send_prompt_with_retry's retry-then-fail
+                outcome = "timeout"
+                logger.exception("ACP turn timeout")
+                if self.on_turn_error:
+                    await maybe_await(self.on_turn_error())
+            except Exception:
+                outcome = "error"
+                logger.exception("ACP turn error")
+                if self.on_turn_error:
+                    await maybe_await(self.on_turn_error())
+            finally:
+                self._busy = False
+        duration_ms = (time.perf_counter() - start_perf) * 1000.0
+        if self._metrics is not None:
+            # ACP token usage MAY arrive in session/update stopReason payload;
+            # current implementation does not extract — usage=None for v1.
+            # When we add extraction (per backing agent), thread through here.
+            record_llm_call(
+                self._metrics,
+                backend="acp",
+                model=self.model,
+                nick=self._nick,
+                usage=None,
+                duration_ms=duration_ms,
+                outcome=outcome,
+            )
 
     async def _prompt_loop(self) -> None:
         """Process queued prompts one at a time."""

{agentirc_cli-8.5.0 → agentirc_cli-8.7.0}/culture/clients/acp/config.py

@@ -62,6 +62,27 @@ class AgentConfig:
     icon: str | None = None
 
 
+@dataclass
+class TelemetryConfig:
+    """OpenTelemetry settings for the agent harness.
+
+    ``enabled: false`` by default so freshly installed harnesses don't
+    try to connect to a non-existent OTLP collector. Flip to ``true``
+    once your collector is running.
+    """
+
+    enabled: bool = False
+    service_name: str = "culture.harness.acp"
+    otlp_endpoint: str = "http://localhost:4317"
+    otlp_protocol: str = "grpc"  # grpc | http/protobuf (only grpc supported initially)
+    otlp_timeout_ms: int = 5000
+    otlp_compression: str = "gzip"
+    traces_enabled: bool = True
+    traces_sampler: str = "parentbased_always_on"
+    metrics_enabled: bool = True
+    metrics_export_interval_ms: int = 10000
+
+
 @dataclass
 class DaemonConfig:
     """Top-level daemon configuration."""
@@ -69,6 +90,7 @@ class DaemonConfig:
     server: ServerConnConfig = field(default_factory=ServerConnConfig)
     supervisor: SupervisorConfig = field(default_factory=SupervisorConfig)
     webhooks: WebhookConfig = field(default_factory=WebhookConfig)
+    telemetry: TelemetryConfig = field(default_factory=TelemetryConfig)
     buffer_size: int = 500
     poll_interval: int = 60
     sleep_start: str = "23:00"
@@ -91,6 +113,7 @@ def load_config(path: str | Path) -> DaemonConfig:
     supervisor = SupervisorConfig(**raw.get("supervisor", {}))
 
     webhooks = WebhookConfig(**raw.get("webhooks", {}))
+    telemetry = TelemetryConfig(**raw.get("telemetry", {}))
 
     agents = []
     known_agent_fields = {f.name for f in AgentConfig.__dataclass_fields__.values()}
@@ -102,6 +125,7 @@ def load_config(path: str | Path) -> DaemonConfig:
         server=server,
         supervisor=supervisor,
         webhooks=webhooks,
+        telemetry=telemetry,
         buffer_size=raw.get("buffer_size", 500),
         poll_interval=raw.get("poll_interval", 60),
         sleep_start=raw.get("sleep_start", "23:00"),

agentirc_cli-8.7.0/culture/clients/acp/culture.yaml

@@ -0,0 +1,32 @@
+suffix: harness-acp
+backend: claude
+model: claude-opus-4-6
+channels:
+  - "#harness"
+acp_command:
+  - opencode
+  - acp
+system_prompt: |
+  You maintain the ACP agent backend in culture/clients/acp/.
+  Listen on #harness for propagation instructions from spark-harness.
+  Apply changes using the citation pattern (cite, don't import),
+  adapting for ACP (Cline, OpenCode, Kiro)
+  specifics (agent_runner.py, supervisor.py).
+tags:
+  - harness
+  - acp
+
+# OpenTelemetry configuration for the agent harness.
+# Set enabled: true once your OTLP collector is running.
+# See docs/agentirc/harness-telemetry.md for a setup guide.
+telemetry:
+  enabled: false                          # master switch — flip to true to start exporting
+  service_name: culture.harness.acp       # overridden per-backend (e.g. culture.harness.acp)
+  otlp_endpoint: http://localhost:4317    # OTLP/gRPC receiver endpoint
+  otlp_protocol: grpc                     # grpc or http/protobuf
+  otlp_timeout_ms: 5000                   # export request timeout in milliseconds
+  otlp_compression: gzip                  # gzip | none
+  traces_enabled: true                    # enable distributed tracing
+  traces_sampler: parentbased_always_on   # honor the server's sampling decision
+  metrics_enabled: true                   # enable LLM call metrics export
+  metrics_export_interval_ms: 10000       # how often to push metric batches (ms)

{agentirc_cli-8.5.0 → agentirc_cli-8.7.0}/culture/clients/acp/daemon.py

@@ -25,6 +25,7 @@ from culture.clients.acp.irc_transport import IRCTransport
 from culture.clients.acp.message_buffer import MessageBuffer
 from culture.clients.acp.socket_server import SocketServer
 from culture.clients.acp.supervisor import Supervisor, make_sdk_evaluate_fn
+from culture.clients.acp.telemetry import init_harness_telemetry
 from culture.clients.acp.webhook import AlertEvent, WebhookClient
 from culture.pidfile import remove_pid, write_pid
 
@@ -71,6 +72,8 @@ class ACPDaemon:
         self._socket_server: SocketServer | None = None
         self._agent_runner: ACPAgentRunner | None = None
         self._supervisor: Supervisor | None = None
+        self._tracer = None
+        self._metrics = None
 
         # FIFO queue of relay targets — each @mention enqueues a target,
         # each agent response dequeues one, ensuring correct routing even
@@ -134,6 +137,9 @@ class ACPDaemon:
         self._pid_name = f"agent-{self.agent.nick}"
         write_pid(self._pid_name, os.getpid())
 
+        # 0.5. OTEL telemetry (if telemetry.enabled, installs SDK providers; else no-op).
+        self._tracer, self._metrics = init_harness_telemetry(self.config)
+
         # 1. Message buffer
         self._buffer = MessageBuffer(max_per_channel=self.config.buffer_size)
 
@@ -148,6 +154,9 @@ class ACPDaemon:
             on_mention=self._on_mention,
             tags=list(self.agent.tags),
             on_roominvite=self._on_roominvite,
+            tracer=self._tracer,
+            metrics=self._metrics,
+            backend="acp",
         )
         await self._transport.connect()
 
@@ -389,6 +398,8 @@ class ACPDaemon:
             on_exit=self._on_agent_exit,
             on_message=self._on_agent_message,
             on_turn_error=self._on_turn_error,
+            metrics=self._metrics,
+            nick=self.agent.nick,
         )
         # Absorb the system prompt response without relaying to IRC
         self._mention_targets.append(None)