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

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

@@ -4,6 +4,30 @@ 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
+
+- `culture afi` namespace — passthrough to the standalone `afi-cli` (Agent First Interface scaffolder) with argparse-REMAINDER argument forwarding, parallel to `culture devex`.
+- Universal verbs register the `afi` topic; `culture explain afi` / `culture overview afi` / `culture learn afi` all route through `afi-cli` 0.3+ and `culture explain` no longer marks `culture afi` as coming-soon.
+- `afi-cli>=0.3,<1.0` as a library dependency (0.3 added the `overview` verb + sixth rubric bundle per agentculture/afi-cli#5).
+- `culture/cli/_passthrough.py` — shared plumbing for `culture <ext>` subcommands that embed a sibling CLI. Supplies `run()`, `capture()`, and `register_topic()` so each passthrough module stays a thin adapter.
+
+### Changed
+
+- `culture/cli/devex.py` refactored onto the new shared passthrough helper. Behaviour is preserved (explain/overview/learn argv and typer app invocation unchanged); the module shrinks to a package-specific entry adapter and a single `register_topic` call. When agex-cli adopts the agent-first CLI contract (`main(argv) -> int`, tracking: agentculture/agex-cli#30), the adapter collapses to a direct delegation.
+
 ## [8.0.0] - 2026-04-22
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentirc-cli
-Version: 8.0.0
+Version: 8.2.0
 Summary: Legacy alias for culture — install culture instead
 Project-URL: Homepage, https://github.com/OriNachum/culture
 Author: Ori Nachum
@@ -12,11 +12,16 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Communications :: Chat :: Internet Relay Chat
 Requires-Python: >=3.12
+Requires-Dist: afi-cli<1.0,>=0.3
 Requires-Dist: agex-cli<1.0,>=0.13
 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.0.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.0.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.0.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.0.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.0.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.0.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.0.0 → agentirc_cli-8.2.0}/culture/cli/__init__.py

@@ -8,6 +8,7 @@ Commands are organized into noun-based groups:
     culture bot      {create,start,stop,list,inspect,archive,unarchive}
     culture skills   {install}
     culture devex    {...developer-experience passthrough (powered by agex-cli)...}
+    culture afi      {...agent-first interface passthrough (powered by afi-cli)...}
 
 Universal verbs (available at the root):
     culture explain [topic]    full description of topic (default: culture)
@@ -22,9 +23,9 @@ import logging
 import sys
 
 from culture import __version__
-from culture.cli import agent, bot, channel, devex, introspect, mesh, server, skills
+from culture.cli import afi, agent, bot, channel, devex, introspect, mesh, server, skills
 
-GROUPS = [agent, server, mesh, channel, bot, skills, devex, introspect]
+GROUPS = [agent, server, mesh, channel, bot, skills, devex, afi, introspect]
 
 
 def _names_of(group) -> set[str]: