agentirc-cli 8.1.0__tar.gz → 8.2.0__tar.gz

{agentirc_cli-8.1.0 → agentirc_cli-8.2.0}/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to this project will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [8.2.0] - 2026-04-24
+
+### Added
+
+- OpenTelemetry foundation: `culture/telemetry/` package with TracerProvider bootstrap, W3C trace context extract/inject helpers for IRCv3 tags, and `TelemetryConfig` block in `server.yaml`.
+- Protocol extension: `culture.dev/traceparent` and `culture.dev/tracestate` IRCv3 tags (`culture/protocol/extensions/tracing.md`).
+- Server-side tracing: `IRCd.emit_event`, `Client._dispatch`, `Client._process_buffer` (with parse-error compensation), and PRIVMSG dispatch/delivery paths now emit spans.
+- Outbound traceparent injection on `Client.send` and `Client.send_raw` when a span is active.
+- Operator docs at `docs/agentirc/telemetry.md` and starter collector config at `docs/agentirc/otelcol-template.yaml`; `docs/reference/server/config.md` documents the new `telemetry` block.
+- Dependencies: `opentelemetry-api`, `opentelemetry-sdk`, `opentelemetry-exporter-otlp-proto-grpc`, `opentelemetry-semantic-conventions`.
+
 ## [8.1.0] - 2026-04-23
 
 ### Added

{agentirc_cli-8.1.0 → agentirc_cli-8.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentirc-cli
-Version: 8.1.0
+Version: 8.2.0
 Summary: Legacy alias for culture — install culture instead
 Project-URL: Homepage, https://github.com/OriNachum/culture
 Author: Ori Nachum
@@ -18,6 +18,10 @@ Requires-Dist: aiohttp>=3.9
 Requires-Dist: anthropic>=0.40
 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-sdk>=1.25
+Requires-Dist: opentelemetry-semantic-conventions>=0.46b0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: textual>=1.0
 Provides-Extra: copilot

{agentirc_cli-8.1.0 → agentirc_cli-8.2.0}/_config.culture.yml

@@ -36,6 +36,8 @@ aux_links:
     - "/agentirc/"
   "Agent Experience":
     - "https://culture.dev/agex/"
+  "Agent First Interop":
+    - "https://culture.dev/afi/"
   "Citation CLI":
     - "/citation-cli/"
   "GitHub":
@@ -49,5 +51,6 @@ footer_content: >-
   Inspectable CLI via <a href="/reference/cli/devex/">culture devex</a>
   (explain / overview / learn at every level).
   Agent Experience via <a href="https://culture.dev/agex/">agex-cli</a>.
+  Agent First Interop via <a href="https://culture.dev/afi/">afi-cli</a>.
   Code distribution via <a href="/citation-cli/">Citation CLI</a>.
   Source on <a href="https://github.com/agentculture/culture">GitHub</a>.

{agentirc_cli-8.1.0 → agentirc_cli-8.2.0}/_data/sites.yml

@@ -1,3 +1,4 @@
+afi: https://culture.dev/afi/
 agentirc: https://culture.dev/agentirc/
 agex: https://culture.dev/agex/
 citation_cli: https://culture.dev/citation-cli/

{agentirc_cli-8.1.0 → agentirc_cli-8.2.0}/_includes/head_custom.html

@@ -4,4 +4,5 @@
 <link rel="icon" type="image/png" sizes="16x16" href="{{ '/assets/images/favicon-16x16.png' | relative_url }}">
 <link rel="apple-touch-icon" sizes="180x180" href="{{ '/assets/images/apple-touch-icon.png' | relative_url }}">
 <link rel="related" href="{{ site.data.sites.agex }}" title="Agent Experience">
+<link rel="related" href="{{ site.data.sites.afi }}" title="Agent First Interop">
 <link rel="related" href="{{ site.data.sites.citation_cli }}" title="Citation CLI">

{agentirc_cli-8.1.0 → agentirc_cli-8.2.0}/culture/agentirc/client.py

@@ -6,12 +6,59 @@ import logging
 import re
 from typing import TYPE_CHECKING
 
+from opentelemetry import trace as _otel_trace
+from opentelemetry.trace import NonRecordingSpan, SpanContext, TraceFlags
+from opentelemetry.trace.propagation import set_span_in_context
+
 from culture.agentirc.channel import Channel
 from culture.agentirc.skill import Event, EventType
 from culture.aio import maybe_await
 from culture.constants import SYSTEM_USER_PREFIX
 from culture.protocol import replies
 from culture.protocol.message import Message
+from culture.telemetry.context import TRACEPARENT_TAG as _TP_TAG_NAME
+from culture.telemetry.context import (
+    extract_traceparent_from_tags,
+)
+from culture.telemetry.context import inject_traceparent as _inject_traceparent
+
+# OTEL instrumentation name (must match `_CULTURE_TRACER_NAME` in
+# culture/telemetry/tracing.py so trace consumers see one consistent value).
+_TRACER_NAME = "culture.agentirc"
+# Span attribute keys for PRIVMSG body capture, defined once so a future
+# rename / sanitization layer has one edit point.
+_ATTR_BODY = "irc.message.body"
+_ATTR_SIZE = "irc.message.size"
+
+
+def _context_from_traceparent(tp: str):
+    """Build an OTEL context whose current span is a NonRecordingSpan
+    synthesized from a W3C traceparent string. The `_dispatch` span we
+    start next will be a child of this context."""
+    # Format: 00-<trace-id>-<parent-id>-<flags>
+    _, trace_hex, parent_hex, flags_hex = tp.split("-")
+    span_ctx = SpanContext(
+        trace_id=int(trace_hex, 16),
+        span_id=int(parent_hex, 16),
+        is_remote=True,
+        trace_flags=TraceFlags(int(flags_hex, 16)),
+    )
+    return set_span_in_context(NonRecordingSpan(span_ctx))
+
+
+def _current_traceparent() -> str | None:
+    """Return the W3C traceparent for the currently-active span, or None
+    if no span is recording (no-op tracer / sampler dropped).
+    """
+    span = _otel_trace.get_current_span()
+    ctx = span.get_span_context()
+    if not ctx.is_valid:
+        return None
+    return (
+        f"00-{format(ctx.trace_id, '032x')}-{format(ctx.span_id, '016x')}"
+        f"-{format(int(ctx.trace_flags), '02x')}"
+    )
+
 
 if TYPE_CHECKING:
     from culture.agentirc.ircd import IRCd
@@ -45,6 +92,14 @@ class Client:
         return f"{self.nick}!{self.user}@{self.host}"
 
     async def send(self, message: Message) -> None:
+        # Only inject trace context for clients that negotiated IRCv3
+        # message-tags; otherwise older clients would see an unexpected @-tag
+        # block and `send_tagged`'s tag-stripping for non-capable clients
+        # would be undone here.
+        if "message-tags" in self.caps:
+            tp = _current_traceparent()
+            if tp is not None:
+                _inject_traceparent(message, traceparent=tp, tracestate=None)
         try:
             self.writer.write(message.format().encode("utf-8"))
             await self.writer.drain()
@@ -55,7 +110,15 @@ class Client:
         """Write a pre-formatted IRC line to the client socket.
 
         Appends CRLF internally, matching ServerLink.send_raw convention.
+        Injects `culture.dev/traceparent` as an IRCv3 tag when a span is active
+        AND the client negotiated the `message-tags` capability.
         """
+        if "message-tags" in self.caps:
+            tp = _current_traceparent()
+            if tp is not None:
+                # send_raw takes a pre-formatted line without an existing tag
+                # block; prefix a fresh @tag.
+                line = f"@{_TP_TAG_NAME}={tp} {line}"
         try:
             self.writer.write(f"{line}\r\n".encode("utf-8"))
             await self.writer.drain()
@@ -84,13 +147,28 @@ class Client:
 
     async def _process_buffer(self, buffer: str) -> str:
         """Parse and dispatch all complete lines from buffer, return remainder."""
-        while "\n" in buffer:
-            line, buffer = buffer.split("\n", 1)
-            if line.strip():
-                msg = Message.parse(line)
+        # Per-call get_tracer: test fixture swaps provider between tests.
+        with _otel_trace.get_tracer(_TRACER_NAME).start_as_current_span(
+            "irc.client.process_buffer"
+        ) as span:
+            while "\n" in buffer:
+                line, buffer = buffer.split("\n", 1)
+                if not line.strip():
+                    continue
+                try:
+                    msg = Message.parse(line)
+                except Exception as exc:  # noqa: BLE001 -- widen for any parser failure
+                    span.add_event(
+                        "irc.parse_error",
+                        attributes={
+                            "line_preview": line[:64],
+                            "error": type(exc).__name__,
+                        },
+                    )
+                    continue
                 if msg.command:
                     await self._dispatch(msg)
-        return buffer
+            return buffer
 
     async def handle(self, initial_msg: str | None = None) -> None:
         buffer = ""
@@ -110,20 +188,41 @@ class Client:
             buffer = await self._process_buffer(buffer)
 
     async def _dispatch(self, msg: Message) -> None:
-        handler = getattr(self, f"_handle_{msg.command.lower()}", None)
-        if handler:
-            await maybe_await(handler(msg))
-        else:
-            skill = self.server.get_skill_for_command(msg.command)
-            if skill and self._registered:
-                try:
-                    await skill.on_command(self, msg)
-                except Exception:
-                    logging.getLogger(__name__).exception(
-                        "Skill %s failed on command %s", skill.name, msg.command
-                    )
+        extract = extract_traceparent_from_tags(msg, peer=None)
+        parent_ctx = None
+        if extract.status == "valid":
+            parent_ctx = _context_from_traceparent(extract.traceparent)
+
+        attrs = {
+            "irc.command": msg.command,
+            "irc.prefix_nick": (msg.prefix.split("!")[0] if msg.prefix else ""),
+            "culture.trace.origin": "local" if extract.status == "missing" else "remote",
+        }
+        if extract.status in ("malformed", "too_long"):
+            attrs["culture.trace.dropped_reason"] = extract.status
+
+        # Per-call get_tracer: test fixture swaps provider between tests.
+        with _otel_trace.get_tracer(_TRACER_NAME).start_as_current_span(
+            f"irc.command.{msg.command}",
+            context=parent_ctx,
+            attributes=attrs,
+        ):
+            handler = getattr(self, f"_handle_{msg.command.lower()}", None)
+            if handler:
+                await maybe_await(handler(msg))
             else:
-                await self.send_numeric(replies.ERR_UNKNOWNCOMMAND, msg.command, "Unknown command")
+                skill = self.server.get_skill_for_command(msg.command)
+                if skill and self._registered:
+                    try:
+                        await skill.on_command(self, msg)
+                    except Exception:
+                        logging.getLogger(__name__).exception(
+                            "Skill %s failed on command %s", skill.name, msg.command
+                        )
+                else:
+                    await self.send_numeric(
+                        replies.ERR_UNKNOWNCOMMAND, msg.command, "Unknown command"
+                    )
 
     async def _handle_ping(self, msg: Message) -> None:
         token = msg.params[0] if msg.params else ""
@@ -615,46 +714,64 @@ class Client:
         await self.send_numeric(replies.RPL_UMODEIS, mode_str)
 
     async def _send_to_channel(self, channel, target, relay, text, is_notice):
-        for member in list(channel.members):
-            if member is not self:
-                await member.send(relay)
-        event_data = {"text": text}
-        if is_notice:
-            event_data["notice"] = True
-        await self.server.emit_event(
-            Event(
-                type=EventType.MESSAGE,
-                channel=target,
-                nick=self.nick,
-                data=event_data,
+        with _otel_trace.get_tracer(_TRACER_NAME).start_as_current_span(
+            "irc.privmsg.deliver.channel",
+            attributes={
+                "irc.channel": target,
+                _ATTR_BODY: text,
+                _ATTR_SIZE: len(text),
+                "irc.notice": is_notice,
+            },
+        ):
+            for member in list(channel.members):
+                if member is not self:
+                    await member.send(relay)
+            event_data = {"text": text}
+            if is_notice:
+                event_data["notice"] = True
+            await self.server.emit_event(
+                Event(
+                    type=EventType.MESSAGE,
+                    channel=target,
+                    nick=self.nick,
+                    data=event_data,
+                )
             )
-        )
 
     async def _send_to_client(self, target, relay, text, is_notice):
         from culture.agentirc.remote_client import RemoteClient
 
-        recipient = self.server.get_client(target)
-        if not recipient:
-            return False
-        if isinstance(recipient, RemoteClient):
-            s2s_cmd = "SNOTICE" if is_notice else "SMSG"
-            await recipient.link.send_raw(
-                f":{self.server.config.name} {s2s_cmd} {target} {self.nick} :{text}"
-            )
-        else:
-            await recipient.send(relay)
-        event_data = {"text": text, "target": target}
-        if is_notice:
-            event_data["notice"] = True
-        await self.server.emit_event(
-            Event(
-                type=EventType.MESSAGE,
-                channel=None,
-                nick=self.nick,
-                data=event_data,
+        with _otel_trace.get_tracer(_TRACER_NAME).start_as_current_span(
+            "irc.privmsg.deliver.dm",
+            attributes={
+                "irc.target.nick": target,
+                _ATTR_BODY: text,
+                _ATTR_SIZE: len(text),
+                "irc.notice": is_notice,
+            },
+        ):
+            recipient = self.server.get_client(target)
+            if not recipient:
+                return False
+            if isinstance(recipient, RemoteClient):
+                s2s_cmd = "SNOTICE" if is_notice else "SMSG"
+                await recipient.link.send_raw(
+                    f":{self.server.config.name} {s2s_cmd} {target} {self.nick} :{text}"
+                )
+            else:
+                await recipient.send(relay)
+            event_data = {"text": text, "target": target}
+            if is_notice:
+                event_data["notice"] = True
+            await self.server.emit_event(
+                Event(
+                    type=EventType.MESSAGE,
+                    channel=None,
+                    nick=self.nick,
+                    data=event_data,
+                )
             )
-        )
-        return True
+            return True
 
     async def _handle_privmsg(self, msg: Message) -> None:
         if len(msg.params) < 2:
@@ -665,28 +782,37 @@ class Client:
 
         target = msg.params[0]
         text = msg.params[1]
-        relay = Message(prefix=self.prefix, command="PRIVMSG", params=[target, text])
-
-        if target.startswith("#"):
-            channel = self.server.channels.get(target)
-            if not channel:
-                await self.send_numeric(
-                    replies.ERR_NOSUCHCHANNEL, target, replies.MSG_NOSUCHCHANNEL
-                )
-                return
-            if self not in channel.members:
-                await self.send_numeric(
-                    replies.ERR_CANNOTSENDTOCHAN, target, "Cannot send to channel"
-                )
-                return
-            await self._send_to_channel(channel, target, relay, text, False)
-            await self._notify_mentions(target, text)
-        else:
-            found = await self._send_to_client(target, relay, text, False)
-            if not found:
-                await self.send_numeric(replies.ERR_NOSUCHNICK, target, replies.MSG_NOSUCHNICK)
-                return
-            await self._notify_mentions(None, text)
+        # Per-call get_tracer: test fixture swaps provider between tests.
+        with _otel_trace.get_tracer(_TRACER_NAME).start_as_current_span(
+            "irc.privmsg.dispatch",
+            attributes={
+                "irc.target": target,
+                _ATTR_BODY: text,
+                _ATTR_SIZE: len(text),
+            },
+        ):
+            relay = Message(prefix=self.prefix, command="PRIVMSG", params=[target, text])
+
+            if target.startswith("#"):
+                channel = self.server.channels.get(target)
+                if not channel:
+                    await self.send_numeric(
+                        replies.ERR_NOSUCHCHANNEL, target, replies.MSG_NOSUCHCHANNEL
+                    )
+                    return
+                if self not in channel.members:
+                    await self.send_numeric(
+                        replies.ERR_CANNOTSENDTOCHAN, target, "Cannot send to channel"
+                    )
+                    return
+                await self._send_to_channel(channel, target, relay, text, False)
+                await self._notify_mentions(target, text)
+            else:
+                found = await self._send_to_client(target, relay, text, False)
+                if not found:
+                    await self.send_numeric(replies.ERR_NOSUCHNICK, target, replies.MSG_NOSUCHNICK)
+                    return
+                await self._notify_mentions(None, text)
 
     async def _notify_mentions(self, channel_name: str | None, text: str) -> None:
         from culture.agentirc.remote_client import RemoteClient

{agentirc_cli-8.1.0 → agentirc_cli-8.2.0}/culture/agentirc/config.py

@@ -12,6 +12,20 @@ class LinkConfig:
     trust: str = "full"  # "full" or "restricted"
 
 
+@dataclass
+class TelemetryConfig:
+    """OpenTelemetry settings. Mirrors server.yaml `telemetry:` block."""
+
+    enabled: bool = False
+    service_name: str = "culture.agentirc"
+    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"  # gzip | none
+    traces_enabled: bool = True
+    traces_sampler: str = "parentbased_always_on"
+
+
 @dataclass
 class ServerConfig:
     """Configuration for a culture server instance."""
@@ -23,3 +37,4 @@ class ServerConfig:
     data_dir: str = ""
     links: list[LinkConfig] = field(default_factory=list)
     system_bots: dict = field(default_factory=dict)
+    telemetry: TelemetryConfig = field(default_factory=TelemetryConfig)

{agentirc_cli-8.1.0 → agentirc_cli-8.2.0}/culture/agentirc/ircd.py

@@ -8,6 +8,8 @@ import logging
 from collections import deque
 from typing import TYPE_CHECKING
 
+from opentelemetry import trace as _otel_trace
+
 from culture.agentirc.channel import Channel
 from culture.agentirc.config import ServerConfig
 from culture.agentirc.events import NO_SURFACE_EVENT_TYPES, render_event
@@ -33,7 +35,10 @@ class IRCd:
     """The culture IRC server."""
 
     def __init__(self, config: ServerConfig):
+        from culture.telemetry import init_telemetry
+
         self.config = config
+        self.tracer = init_telemetry(config)
         self.clients: dict[str, Client | VirtualClient] = {}  # nick -> Client
         self.channels: dict[str, Channel] = {}  # name -> Channel
         self.skills: list[Skill] = []
@@ -166,36 +171,60 @@ class IRCd:
         self._seq += 1
         return self._seq
 
-    async def emit_event(self, event: Event) -> None:
-        # 1) Sequence + log.
-        seq = self.next_seq()
-        self._event_log.append((seq, event))
+    @staticmethod
+    def _build_event_span_attrs(event: Event, origin_tag: str | None) -> dict[str, str]:
+        # event.type may be an EventType enum OR a plain string — federated
+        # events forward unknown types verbatim (see _parse_event_type in
+        # server_link.py).
+        event_type_str = event.type.value if hasattr(event.type, "value") else str(event.type)
+        attrs: dict[str, str] = {
+            "event.type": event_type_str,
+            "event.origin": "federated" if origin_tag else "local",
+        }
+        if event.channel:
+            attrs["event.channel"] = event.channel
+        if origin_tag:
+            attrs["culture.federation.peer"] = origin_tag
+        return attrs
 
-        # 2) Run skill hooks.
+    async def _run_skill_hooks(self, event: Event) -> None:
         for skill in self.skills:
             try:
                 await skill.on_event(event)
             except Exception:
                 logger.exception("Skill %s failed on event %s", skill.name, event.type)
 
-        # 3) Relay to linked peers — only relay locally-originated events
-        # (no mesh routing; scope is direct peers only)
-        if not event.data.get("_origin"):
-            for peer_name, link in list(self.links.items()):
-                try:
-                    await link.relay_event(event)
-                except Exception:
-                    logger.exception("Failed to relay event to %s", peer_name)
-
-        # 4) Dispatch to event-triggered bots.
-        if self.bot_manager is not None:
+    async def _relay_to_peers(self, event: Event) -> None:
+        for peer_name, link in list(self.links.items()):
             try:
-                await self.bot_manager.on_event(event)
+                await link.relay_event(event)
             except Exception:
-                logger.exception("bot_manager.on_event failed")
+                logger.exception("Failed to relay event to %s", peer_name)
+
+    async def _dispatch_to_bots(self, event: Event) -> None:
+        if self.bot_manager is None:
+            return
+        try:
+            await self.bot_manager.on_event(event)
+        except Exception:
+            logger.exception("bot_manager.on_event failed")
 
-        # 5) Surface as tagged PRIVMSG from system-<server>.
-        await self._surface_event_privmsg(event)
+    async def emit_event(self, event: Event) -> None:
+        origin_tag = event.data.get("_origin")
+        attrs = self._build_event_span_attrs(event, origin_tag)
+        # Per-call get_tracer: the `tracing_exporter` test fixture swaps the
+        # global provider between tests; a cached Tracer would bind to the
+        # first test's provider and stop delivering to later ones.
+        with _otel_trace.get_tracer("culture.agentirc").start_as_current_span(
+            "irc.event.emit", attributes=attrs
+        ):
+            seq = self.next_seq()
+            self._event_log.append((seq, event))
+            await self._run_skill_hooks(event)
+            if not origin_tag:
+                await self._relay_to_peers(event)
+            await self._dispatch_to_bots(event)
+            await self._surface_event_privmsg(event)
 
     _NO_SURFACE_TYPES = NO_SURFACE_EVENT_TYPES
 

{agentirc_cli-8.1.0 → agentirc_cli-8.2.0}/culture/config.py

@@ -15,6 +15,8 @@ from pathlib import Path
 
 import yaml
 
+from culture.agentirc.config import TelemetryConfig
+
 logger = logging.getLogger("culture")
 
 
@@ -98,6 +100,7 @@ class ServerConfig:
     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"
@@ -202,6 +205,7 @@ def load_server_config(path: str | Path) -> ServerConfig:
     server = ServerConnConfig(**raw.get("server", {}))
     supervisor = SupervisorConfig(**raw.get("supervisor", {}))
     webhooks = WebhookConfig(**raw.get("webhooks", {}))
+    telemetry = TelemetryConfig(**raw.get("telemetry", {}))
 
     manifest = raw.get("agents") or {}
     if not isinstance(manifest, dict):
@@ -211,6 +215,7 @@ def load_server_config(path: str | Path) -> ServerConfig:
         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"),
@@ -258,6 +263,7 @@ def _load_legacy_config(path: str | Path) -> ServerConfig:
     server = ServerConnConfig(**raw.get("server", {}))
     supervisor = SupervisorConfig(**raw.get("supervisor", {}))
     webhooks = WebhookConfig(**raw.get("webhooks", {}))
+    telemetry = TelemetryConfig(**raw.get("telemetry", {}))
 
     agents = []
     known = _KNOWN_AGENT_FIELDS | {"nick", "directory"}
@@ -278,6 +284,7 @@ def _load_legacy_config(path: str | Path) -> ServerConfig:
         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"),
@@ -354,10 +361,12 @@ def migrate_legacy_to_manifest(path: str | Path) -> ServerConfig:
     server = ServerConnConfig(**raw.get("server", {}))
     supervisor = SupervisorConfig(**raw.get("supervisor", {}))
     webhooks = WebhookConfig(**raw.get("webhooks", {}))
+    telemetry = TelemetryConfig(**raw.get("telemetry", {}))
     config = ServerConfig(
         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"),
@@ -516,6 +525,7 @@ def save_server_config(path: str | Path, config: ServerConfig) -> None:
         "server": asdict(config.server),
         "supervisor": asdict(config.supervisor),
         "webhooks": asdict(config.webhooks),
+        "telemetry": asdict(config.telemetry),
         "buffer_size": config.buffer_size,
         "poll_interval": config.poll_interval,
         "sleep_start": config.sleep_start,

agentirc_cli-8.2.0/culture/protocol/extensions/tracing.md

@@ -0,0 +1,31 @@
+# Extension: W3C Trace Context over IRC
+
+**Tags:**
+
+- `culture.dev/traceparent` — the W3C `traceparent` header value, verbatim (55 chars, format `00-<32-hex-trace-id>-<16-hex-parent-id>-<2-hex-flags>`). MUST match the W3C regex. If malformed, servers MUST silently drop the tag (treat as absent).
+- `culture.dev/tracestate` — the W3C `tracestate` header value (comma-separated `key=value` list, vendor-specific). Optional. MUST be ≤ 512 bytes after IRCv3 unescape. If longer, servers MUST drop the tag.
+
+**Scope:** outbound on every client-originated message when a span context is active (PRIVMSG, NOTICE, JOIN, PART, KICK, MODE, SEVENT, SMSG, SNOTICE). On federation relay, the tags are re-injected from the *current* server's span context — they are not copied verbatim from the received message. This produces a parent-per-hop span tree instead of collapsing all hops into one.
+
+**Inbound handling.** On every ingress (local client `_dispatch` and S2S `_dispatch`):
+
+1. Tag absent → start a new root span. Attribute: `culture.trace.origin=local`.
+2. Tag present and valid → start a child span linked to the extracted context. Attributes: `culture.trace.origin=remote`, `culture.federation.peer=<peer>`.
+3. Tag present but malformed or over the length cap → drop the tag, start a new root span. Attributes: `culture.trace.origin=remote`, `culture.trace.dropped_reason=malformed|too_long`, `culture.federation.peer=<peer>`. Log a rate-limited warning. Increment `culture.trace.inbound{result=malformed|too_long, peer=<peer>}`.
+
+**Length caps** (hard-coded, not configurable):
+
+- `traceparent`: exactly 55 characters.
+- `tracestate`: ≤ 512 bytes post-unescape.
+
+**Non-goal.** Trace context is not authenticated. Federation peer trust is the authorization mechanism; tracing is observability only. An operator who cares about forged trace IDs from upstream peers should rely on peer trust, not on tag validation.
+
+**Compat.** Additive IRCv3 tag. Peers that don't recognize the tag pass it through on relay (standard IRCv3 tag behavior). No wire version bump. Project version bumps as a minor per `CLAUDE.md`.
+
+**Example.**
+
+User on `spark` sends:
+
+    @culture.dev/traceparent=00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01 PRIVMSG #general :hi
+
+Server `spark` starts span `irc.command.PRIVMSG` as a child of the extracted context, relays the event via SEVENT to `thor`, re-injecting its own span's traceparent. Server `thor` sees trace ID `4bf92f35…4736` and starts another child span — the collector stitches both spans into one trace.

agentirc_cli-8.2.0/culture/telemetry/__init__.py

@@ -0,0 +1,22 @@
+"""OpenTelemetry integration for Culture.
+
+Public surface re-exported here; call sites import from `culture.telemetry`.
+"""
+
+from culture.telemetry.context import (
+    TRACEPARENT_TAG,
+    TRACESTATE_TAG,
+    ExtractResult,
+    extract_traceparent_from_tags,
+    inject_traceparent,
+)
+from culture.telemetry.tracing import init_telemetry
+
+__all__ = [
+    "ExtractResult",
+    "TRACEPARENT_TAG",
+    "TRACESTATE_TAG",
+    "extract_traceparent_from_tags",
+    "init_telemetry",
+    "inject_traceparent",
+]