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

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

@@ -4,6 +4,27 @@ All notable changes to this project will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [8.3.0] - 2026-04-25
+
+### Added
+
+- `irc.s2s.session` span over ServerLink connection lifetime.
+- `irc.s2s.<VERB>` per-verb spans on inbound federation messages with traceparent extraction and the inbound mitigation rules from `culture/protocol/extensions/tracing.md`.
+- `irc.s2s.relay` span on outbound relay enforcing the re-sign-per-hop rule.
+- `irc.client.session` span over Client connection lifetime (#290).
+- `irc.join` and `irc.part` spans (#290).
+- Public `culture.telemetry.context_from_traceparent` and `culture.telemetry.current_traceparent` helpers.
+- Single traceparent injection choke point at `ServerLink.send_raw`.
+- End-to-end propagation tests proving one `trace_id` spans federated client → server → relay → server hops.
+
+### Changed
+
+- `Client._dispatch` span name and `irc.command` attribute now uppercase, matching `ServerLink._dispatch` convention.
+
+### Fixed
+
+- `_replay_event` uses the hasattr-guarded comparison so string-typed federated `event.type` no longer skips the typed fast path. (#291)
+
 ## [8.2.0] - 2026-04-24
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentirc-cli
-Version: 8.2.0
+Version: 8.3.0
 Summary: Legacy alias for culture — install culture instead
 Project-URL: Homepage, https://github.com/OriNachum/culture
 Author: Ori Nachum

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

@@ -7,8 +7,8 @@ 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 opentelemetry.context import Context as _OtelContext
+from opentelemetry.trace import Span as _OtelSpan
 
 from culture.agentirc.channel import Channel
 from culture.agentirc.skill import Event, EventType
@@ -18,6 +18,8 @@ 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 (
+    context_from_traceparent,
+    current_traceparent,
     extract_traceparent_from_tags,
 )
 from culture.telemetry.context import inject_traceparent as _inject_traceparent
@@ -25,39 +27,12 @@ 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.
+# Span attribute keys, 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')}"
-    )
+_ATTR_NICK = "irc.client.nick"
+_ATTR_CHANNEL = "irc.channel"
 
 
 if TYPE_CHECKING:
@@ -86,6 +61,7 @@ class Client:
         self.caps: set[str] = set()
         self.modes: set[str] = set()
         self.icon: str | None = None
+        self._session_span: _OtelSpan | None = None
 
     @property
     def prefix(self) -> str:
@@ -97,7 +73,7 @@ class Client:
         # block and `send_tagged`'s tag-stripping for non-capable clients
         # would be undone here.
         if "message-tags" in self.caps:
-            tp = _current_traceparent()
+            tp = current_traceparent()
             if tp is not None:
                 _inject_traceparent(message, traceparent=tp, tracestate=None)
         try:
@@ -114,7 +90,7 @@ class Client:
         AND the client negotiated the `message-tags` capability.
         """
         if "message-tags" in self.caps:
-            tp = _current_traceparent()
+            tp = current_traceparent()
             if tp is not None:
                 # send_raw takes a pre-formatted line without an existing tag
                 # block; prefix a fresh @tag.
@@ -171,30 +147,42 @@ class Client:
             return buffer
 
     async def handle(self, initial_msg: str | None = None) -> None:
-        buffer = ""
-        if initial_msg:
-            buffer = initial_msg.replace("\r\n", "\n").replace("\r", "\n")
-            buffer = await self._process_buffer(buffer)
-        while True:
-            data = await self.reader.read(4096)
-            if not data:
-                break
-            buffer += data.decode("utf-8", errors="replace")
-            # Cap buffer to prevent unbounded memory growth (512 bytes per RFC 2812)
-            if len(buffer) > 8192:
-                buffer = buffer[-4096:]
-            # Normalize all line endings to \n for simpler parsing
-            buffer = buffer.replace("\r\n", "\n").replace("\r", "\n")
-            buffer = await self._process_buffer(buffer)
+        peer_info = self.writer.get_extra_info("peername")
+        remote_addr = f"{peer_info[0]}:{peer_info[1]}" if peer_info else ""
+        with _otel_trace.get_tracer(_TRACER_NAME).start_as_current_span(
+            "irc.client.session",
+            attributes={"irc.client.remote_addr": remote_addr},
+        ) as span:
+            self._session_span = span
+            try:
+                buffer = ""
+                if initial_msg:
+                    buffer = initial_msg.replace("\r\n", "\n").replace("\r", "\n")
+                    buffer = await self._process_buffer(buffer)
+                while True:
+                    data = await self.reader.read(4096)
+                    if not data:
+                        break
+                    buffer += data.decode("utf-8", errors="replace")
+                    # Cap buffer to prevent unbounded memory growth (512 bytes per RFC 2812)
+                    if len(buffer) > 8192:
+                        buffer = buffer[-4096:]
+                    # Normalize all line endings to \n for simpler parsing
+                    buffer = buffer.replace("\r\n", "\n").replace("\r", "\n")
+                    buffer = await self._process_buffer(buffer)
+            except (ConnectionError, asyncio.IncompleteReadError):
+                pass
 
     async def _dispatch(self, msg: Message) -> None:
         extract = extract_traceparent_from_tags(msg, peer=None)
-        parent_ctx = None
         if extract.status == "valid":
-            parent_ctx = _context_from_traceparent(extract.traceparent)
+            parent_ctx: _OtelContext | None = context_from_traceparent(extract.traceparent)
+        else:
+            parent_ctx = _OtelContext()  # force root: detach from session span
 
+        verb = msg.command.upper()
         attrs = {
-            "irc.command": msg.command,
+            "irc.command": verb,
             "irc.prefix_nick": (msg.prefix.split("!")[0] if msg.prefix else ""),
             "culture.trace.origin": "local" if extract.status == "missing" else "remote",
         }
@@ -203,7 +191,7 @@ class Client:
 
         # 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}",
+            f"irc.command.{verb}",
             context=parent_ctx,
             attributes=attrs,
         ):
@@ -304,6 +292,8 @@ class Client:
 
         self.nick = nick
         self.server.clients[nick] = self
+        if self._session_span is not None:
+            self._session_span.set_attribute(_ATTR_NICK, nick)
         await self._try_register()
 
     async def _handle_user(self, msg: Message) -> None:
@@ -355,45 +345,49 @@ class Client:
             return
 
         channel_name = msg.params[0]
-        if not channel_name.startswith("#"):
-            return
+        with _otel_trace.get_tracer(_TRACER_NAME).start_as_current_span(
+            "irc.join",
+            attributes={_ATTR_CHANNEL: channel_name, _ATTR_NICK: self.nick or ""},
+        ):
+            if not channel_name.startswith("#"):
+                return
 
-        # Block joins to archived rooms
-        existing = self.server.channels.get(channel_name)
-        if existing and existing.archived:
-            await self.send(
-                Message(
-                    prefix=self.server.config.name,
-                    command="NOTICE",
-                    params=[self.nick, f"{channel_name} is archived and cannot be joined"],
+            # Block joins to archived rooms
+            existing = self.server.channels.get(channel_name)
+            if existing and existing.archived:
+                await self.send(
+                    Message(
+                        prefix=self.server.config.name,
+                        command="NOTICE",
+                        params=[self.nick, f"{channel_name} is archived and cannot be joined"],
+                    )
                 )
-            )
-            return
+                return
 
-        channel = self.server.get_or_create_channel(channel_name)
-        if self in channel.members:
-            return
+            channel = self.server.get_or_create_channel(channel_name)
+            if self in channel.members:
+                return
 
-        channel.add(self)
-        self.channels.add(channel)
+            channel.add(self)
+            self.channels.add(channel)
 
-        # Notify all channel members (including self)
-        join_msg = Message(prefix=self.prefix, command="JOIN", params=[channel_name])
-        for member in list(channel.members):
-            await member.send(join_msg)
+            # Notify all channel members (including self)
+            join_msg = Message(prefix=self.prefix, command="JOIN", params=[channel_name])
+            for member in list(channel.members):
+                await member.send(join_msg)
 
-        # Send topic if set
-        if channel.topic:
-            await self.send_numeric(replies.RPL_TOPIC, channel_name, channel.topic)
+            # Send topic if set
+            if channel.topic:
+                await self.send_numeric(replies.RPL_TOPIC, channel_name, channel.topic)
 
-        # Send names list
-        await self._send_names(channel)
+            # Send names list
+            await self._send_names(channel)
 
-        # Emit event AFTER delivering all join-related numerics (topic, NAMES)
-        # so that the event PRIVMSG doesn't interleave with 353/366 in client buffers.
-        await self.server.emit_event(
-            Event(type=EventType.JOIN, channel=channel_name, nick=self.nick)
-        )
+            # Emit event AFTER delivering all join-related numerics (topic, NAMES)
+            # so that the event PRIVMSG doesn't interleave with 353/366 in client buffers.
+            await self.server.emit_event(
+                Event(type=EventType.JOIN, channel=channel_name, nick=self.nick)
+            )
 
     async def _handle_part(self, msg: Message) -> None:
         if not msg.params:
@@ -401,36 +395,40 @@ class Client:
             return
 
         channel_name = msg.params[0]
-        reason = msg.params[1] if len(msg.params) > 1 else ""
+        with _otel_trace.get_tracer(_TRACER_NAME).start_as_current_span(
+            "irc.part",
+            attributes={_ATTR_CHANNEL: channel_name, _ATTR_NICK: self.nick or ""},
+        ):
+            reason = msg.params[1] if len(msg.params) > 1 else ""
 
-        channel = self.server.channels.get(channel_name)
-        if not channel or self not in channel.members:
-            await self.send_numeric(
-                replies.ERR_NOTONCHANNEL,
-                channel_name,
-                replies.MSG_NOTONCHANNEL,
-            )
-            return
+            channel = self.server.channels.get(channel_name)
+            if not channel or self not in channel.members:
+                await self.send_numeric(
+                    replies.ERR_NOTONCHANNEL,
+                    channel_name,
+                    replies.MSG_NOTONCHANNEL,
+                )
+                return
 
-        part_params = [channel_name, reason] if reason else [channel_name]
-        part_msg = Message(prefix=self.prefix, command="PART", params=part_params)
-        for member in list(channel.members):
-            await member.send(part_msg)
+            part_params = [channel_name, reason] if reason else [channel_name]
+            part_msg = Message(prefix=self.prefix, command="PART", params=part_params)
+            for member in list(channel.members):
+                await member.send(part_msg)
 
-        await self.server.emit_event(
-            Event(
-                type=EventType.PART,
-                channel=channel_name,
-                nick=self.nick,
-                data={"reason": reason},
+            await self.server.emit_event(
+                Event(
+                    type=EventType.PART,
+                    channel=channel_name,
+                    nick=self.nick,
+                    data={"reason": reason},
+                )
             )
-        )
 
-        channel.remove(self)
-        self.channels.discard(channel)
+            channel.remove(self)
+            self.channels.discard(channel)
 
-        if not channel.members and not channel.persistent:
-            del self.server.channels[channel_name]
+            if not channel.members and not channel.persistent:
+                del self.server.channels[channel_name]
 
     async def _handle_topic(self, msg: Message) -> None:
         if not msg.params:

{agentirc_cli-8.2.0 → agentirc_cli-8.3.0}/culture/agentirc/server_link.py

@@ -7,12 +7,21 @@ import json
 import logging
 from typing import TYPE_CHECKING
 
+from opentelemetry import trace as otel_trace
+from opentelemetry.context import Context as _OtelContext
+
 from culture.agentirc.remote_client import RemoteClient
 from culture.agentirc.skill import Event, EventType
 from culture.aio import maybe_await
 from culture.bots.virtual_client import VirtualClient
 from culture.constants import SYSTEM_USER_PREFIX
 from culture.protocol.message import Message
+from culture.telemetry import context_from_traceparent, current_traceparent
+from culture.telemetry.context import TRACEPARENT_TAG, extract_traceparent_from_tags
+
+# OTEL instrumentation name (must match `_CULTURE_TRACER_NAME` in
+# culture/telemetry/tracing.py so all spans go through one tracer instance).
+_TRACER_NAME = "culture.agentirc"
 
 if TYPE_CHECKING:
     from culture.agentirc.ircd import IRCd
@@ -20,6 +29,64 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
+def _prepend_trace_tags(line: str, tp: str) -> str:
+    """Inject *tp* as the ``culture.dev/traceparent`` IRCv3 tag on *line*.
+
+    - Empty line → returned unchanged (defensive no-op).
+    - Line with no existing tag block (does not start with ``@``) → prepend
+      ``@culture.dev/traceparent=<tp> `` before the rest of the line.
+    - Line that already has a tag block (starts with ``@``) → merge the tag
+      into the existing block.  If the block already contains
+      ``culture.dev/traceparent``, its value is replaced with *tp*; otherwise
+      the new tag is appended with a ``;`` separator.
+
+    The helper is intentionally lenient: if the tag block is somehow
+    ill-formed the existing text is preserved and the new tag is appended —
+    tagging is best-effort, never load-bearing.
+
+    .. note:: Parsing limitation
+
+        This helper does not fully parse or unescape IRCv3 tag values; it
+        simply splits the tag block on ``;`` and separates each tag's key from
+        its value on the first ``=``. This is safe for current ``send_raw``
+        callers, which today emit no tags of their own. Revisit if a caller
+        begins authoring tags whose values may contain IRCv3-escaped
+        semicolons.
+    """
+    if not line:
+        return line
+
+    if not line.startswith("@"):
+        return f"@{TRACEPARENT_TAG}={tp} {line}"
+
+    # Split off the tag block: everything up to the first space, then the rest.
+    space_idx = line.find(" ")
+    if space_idx == -1:
+        # Malformed: entire line is a tag block with no message body.
+        # Append the tag and move on.
+        return f"{line};{TRACEPARENT_TAG}={tp}"
+
+    tag_block = line[1:space_idx]  # strip leading '@'
+    rest = line[space_idx + 1 :]
+
+    # Split existing tags on ';', drop empty entries (e.g. from an empty tag
+    # block like "@ :rest"), then replace or append the traceparent tag.
+    tags = [t for t in tag_block.split(";") if t]
+    replaced = False
+    new_tags = []
+    for tag in tags:
+        key = tag.split("=", 1)[0]
+        if key == TRACEPARENT_TAG:
+            new_tags.append(f"{TRACEPARENT_TAG}={tp}")
+            replaced = True
+        else:
+            new_tags.append(tag)
+    if not replaced:
+        new_tags.append(f"{TRACEPARENT_TAG}={tp}")
+
+    return f"@{';'.join(new_tags)} {rest}"
+
+
 class ServerLink:
     """A server-to-server link to a peer IRCd."""
 
@@ -47,6 +114,7 @@ class ServerLink:
         self._peer_pass: str | None = None
         self.last_seen_seq: int = 0
         self._squit_received: bool = False
+        self._session_span: otel_trace.Span | None = None
 
     def should_relay(self, channel_name: str) -> bool:
         """Check if a channel event should be relayed over this link."""
@@ -62,6 +130,12 @@ class ServerLink:
         return False
 
     async def send_raw(self, line: str) -> None:
+        tp = current_traceparent()
+        if tp:
+            try:
+                line = _prepend_trace_tags(line, tp)
+            except Exception:  # noqa: BLE001 - telemetry must never break the link
+                logger.debug("traceparent injection failed; sending untagged", exc_info=True)
         try:
             self.writer.write(f"{line}\r\n".encode("utf-8"))
             await self.writer.drain()
@@ -87,40 +161,68 @@ class ServerLink:
 
     async def handle(self, initial_msg: str | None = None) -> None:
         """Main S2S connection loop."""
-        try:
-            if self.initiator:
-                await self._send_handshake()
-
-            buffer = ""
-            if initial_msg:
-                buffer = initial_msg + "\n"
-                buffer = await self._process_buffer(buffer)
-
-            while True:
-                data = await self.reader.read(4096)
-                if not data:
-                    break
-                buffer += data.decode("utf-8", errors="replace")
-                buffer = buffer.replace("\r\n", "\n").replace("\r", "\n")
-                buffer = await self._process_buffer(buffer)
-        except (ConnectionError, asyncio.IncompleteReadError):
-            pass
-        finally:
-            await self.server._remove_link(self, squit=self._squit_received)
-            self.writer.close()
+        tracer = otel_trace.get_tracer(_TRACER_NAME)
+        direction = "outbound" if self.initiator else "inbound"
+        with tracer.start_as_current_span(
+            "irc.s2s.session",
+            attributes={"s2s.direction": direction},
+        ) as span:
+            self._session_span = span
             try:
-                await self.writer.wait_closed()
-            except ConnectionError:
+                if self.initiator:
+                    await self._send_handshake()
+
+                buffer = ""
+                if initial_msg:
+                    buffer = initial_msg + "\n"
+                    buffer = await self._process_buffer(buffer)
+
+                while True:
+                    data = await self.reader.read(4096)
+                    if not data:
+                        break
+                    buffer += data.decode("utf-8", errors="replace")
+                    buffer = buffer.replace("\r\n", "\n").replace("\r", "\n")
+                    buffer = await self._process_buffer(buffer)
+            except (ConnectionError, asyncio.IncompleteReadError):
                 pass
+            finally:
+                await self.server._remove_link(self, squit=self._squit_received)
+                self.writer.close()
+                try:
+                    await self.writer.wait_closed()
+                except ConnectionError:
+                    pass
 
     async def _send_handshake(self) -> None:
         await self.send_raw(f"PASS {self.password}")
         await self.send_raw(f"SERVER {self.server.config.name} 1 :{self.server.config.name} IRC")
 
     async def _dispatch(self, msg: Message) -> None:
+        verb = msg.command.upper()
         handler = getattr(self, f"_handle_{msg.command.lower()}", None)
-        if handler:
-            await maybe_await(handler(msg))
+
+        extracted = extract_traceparent_from_tags(msg, peer=self.peer_name)
+        if extracted.status == "valid":
+            parent_ctx: _OtelContext | None = context_from_traceparent(extracted.traceparent)
+        else:
+            parent_ctx = _OtelContext()  # force root: detach from session span
+
+        attrs = {
+            "irc.command": verb,
+            "culture.trace.origin": "remote",
+            "culture.federation.peer": self.peer_name or "",
+        }
+        if extracted.status in ("malformed", "too_long"):
+            attrs["culture.trace.dropped_reason"] = extracted.status
+
+        with otel_trace.get_tracer(_TRACER_NAME).start_as_current_span(
+            f"irc.s2s.{verb}",
+            context=parent_ctx,
+            attributes=attrs,
+        ):
+            if handler:
+                await maybe_await(handler(msg))
 
     # --- Handshake handlers ---
 
@@ -189,6 +291,8 @@ class ServerLink:
         await self._validate_peer_credentials()
 
         self._authenticated = True
+        if self._session_span is not None:
+            self._session_span.set_attribute("s2s.peer", self.peer_name)
         self.server.links[self.peer_name] = self
         self.server.cancel_link_retry(self.peer_name)
 
@@ -818,7 +922,11 @@ class ServerLink:
     async def _replay_event(self, seq: int, event: Event) -> None:
         """Replay a single event to the peer as S2S wire format."""
         origin = self.server.config.name
-        if event.type == EventType.MESSAGE:
+        # Federated events arrive with event.type as either an EventType enum
+        # or a plain string (when _parse_event_type sees an unknown wire type).
+        # Compare against the .value to handle both shapes — see #291.
+        event_type_str = event.type.value if hasattr(event.type, "value") else str(event.type)
+        if event_type_str == EventType.MESSAGE.value:
             target = event.channel or event.data.get("target", "")
             text = event.data.get("text", "")
             # Filter channel messages through trust check
@@ -833,23 +941,34 @@ class ServerLink:
 
     async def relay_event(self, event: Event) -> None:
         """Relay a local event to the peer in S2S wire format."""
-        origin = self.server.config.name
-        handler = self._RELAY_DISPATCH.get(event.type)
-        if handler:
-            await maybe_await(handler(self, event, origin))
-            return
+        event_type_str = event.type.value if hasattr(event.type, "value") else str(event.type)
+        attrs = {
+            "event.type": event_type_str,
+            "s2s.peer": self.peer_name or "",
+        }
+        # Single span name (no verb suffix): the wire verb is decided downstream
+        # by _RELAY_DISPATCH or the SEVENT fallback, after this span opens.
+        with otel_trace.get_tracer(_TRACER_NAME).start_as_current_span(
+            "irc.s2s.relay", attributes=attrs
+        ):
+            origin = self.server.config.name
+            handler = self._RELAY_DISPATCH.get(event.type)
+            if handler:
+                await maybe_await(handler(self, event, origin))
+                return
 
-        # If no typed relay exists, fall back to generic SEVENT.
-        # v1 assumes all peers support SEVENT; cap negotiation is deferred — see plan task 12.
-        type_str = event.type.value if hasattr(event.type, "value") else str(event.type)
-        payload = self.server._build_event_payload(event)
-        encoded = self.server._encode_event_data(payload, type_str)
-        target = event.channel or "*"
-        # Egress trust check: channel-scoped events respect should_relay; global events always relay
-        if event.channel is not None and not self.should_relay(event.channel):
-            return
-        seq = self.server._seq  # current local seq; peer stores but doesn't re-sequence
-        await self.send_raw(f":{origin} SEVENT {origin} {seq} {type_str} {target} :{encoded}")
+            # If no typed relay exists, fall back to generic SEVENT.
+            # v1 assumes all peers support SEVENT; cap negotiation is deferred — see plan task 12.
+            payload = self.server._build_event_payload(event)
+            encoded = self.server._encode_event_data(payload, event_type_str)
+            target = event.channel or "*"
+            # Egress trust check: channel-scoped events respect should_relay; global events always relay
+            if event.channel is not None and not self.should_relay(event.channel):
+                return
+            seq = self.server._seq  # current local seq; peer stores but doesn't re-sequence
+            await self.send_raw(
+                f":{origin} SEVENT {origin} {seq} {event_type_str} {target} :{encoded}"
+            )
 
     async def _relay_message(self, event: Event, origin: str) -> None:
         target = event.channel or event.data.get("target", "")

{agentirc_cli-8.2.0 → agentirc_cli-8.3.0}/culture/protocol/extensions/tracing.md

@@ -29,3 +29,9 @@ 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.
+
+**Re-sign per hop on the wire.** Concretely, the SEVENT line `spark` sends to `thor` looks like:
+
+    @culture.dev/traceparent=00-4bf92f3577b34da6a3ce929d0e0e4736-aaaaaaaaaaaaaaaa-01 :spark SEVENT spark 42 message #general :<base64>
+
+The trace-id (`4bf92f35…4736`) is preserved across the hop. The parent-id changes (`00f067aa…02b7` → `aaaaaaaa…aaaa`) because `spark` re-injects its own relay span's id, not the inbound parent-id verbatim. This produces a parent-per-hop span tree that mirrors the federation topology rather than collapsing every hop into one flat span.

{agentirc_cli-8.2.0 → agentirc_cli-8.3.0}/culture/telemetry/__init__.py

@@ -7,6 +7,8 @@ from culture.telemetry.context import (
     TRACEPARENT_TAG,
     TRACESTATE_TAG,
     ExtractResult,
+    context_from_traceparent,
+    current_traceparent,
     extract_traceparent_from_tags,
     inject_traceparent,
 )
@@ -16,6 +18,8 @@ __all__ = [
     "ExtractResult",
     "TRACEPARENT_TAG",
     "TRACESTATE_TAG",
+    "context_from_traceparent",
+    "current_traceparent",
     "extract_traceparent_from_tags",
     "init_telemetry",
     "inject_traceparent",