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

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

@@ -4,6 +4,21 @@ All notable changes to this project will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [8.5.0] - 2026-04-25
+
+### Added
+
+- `culture/telemetry/audit.py` — `AuditSink` with bounded `asyncio.Queue` + dedicated writer task + daily/size rotation + `0600`/`0700` perms.
+- Public `culture.telemetry.AuditSink`, `init_audit`, `build_audit_record`, `utc_iso_timestamp`.
+- `TelemetryConfig.audit_enabled` (default `True`), `audit_dir`, `audit_max_file_bytes`, `audit_rotate_utc_midnight`, `audit_queue_depth` — independent of `telemetry.enabled` (audit fires even with OTEL off).
+- `culture/protocol/extensions/audit.md` — JSONL record schema as a stable contract.
+- `docs/agentirc/audit.md` — operator guide.
+- Audit metrics extend the Plan-3 `MetricsRegistry`: `culture.audit.writes` (Counter, labels `outcome=ok|error`) and `culture.audit.queue_depth` (UpDownCounter).
+- `IRCd.__init__` creates the sink; `IRCd.start()` awaits `sink.start()`; `IRCd.stop()` awaits `sink.shutdown()` so SERVER_WAKE / SERVER_SLEEP both land in the JSONL.
+- `IRCd.emit_event` submits one record per event after the `irc.event.emit` span; `trace_id` / `span_id` captured inside the span for cross-pillar joins.
+- `Client._process_buffer` submits `PARSE_ERROR` records for malformed inbound lines.
+- Federation audit: federated `message` events arrive on the receiver with `origin=federated`, `peer=<peer_name>`. Federated lifecycle events (JOIN/PART/QUIT) are deferred — see #296.
+
 ## [8.4.0] - 2026-04-25
 
 ### Added

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

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

{agentirc_cli-8.4.0 → agentirc_cli-8.5.0}/culture/agentirc/client.py

@@ -17,6 +17,7 @@ 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.audit import utc_iso_timestamp as _utc_iso_timestamp
 from culture.telemetry.context import TRACEPARENT_TAG as _TP_TAG_NAME
 from culture.telemetry.context import (
     context_from_traceparent,
@@ -148,6 +149,7 @@ class Client:
                             "error": type(exc).__name__,
                         },
                     )
+                    self._submit_parse_error_audit(line, exc)
                     continue
                 # Record received bytes + message size for every successfully-parsed
                 # line.  +2 accounts for the \r\n that was stripped during line-split.
@@ -160,6 +162,49 @@ class Client:
                     await self._dispatch(msg)
             return buffer
 
+    def _submit_parse_error_audit(self, line: str, exc: BaseException) -> None:
+        """Build and submit a PARSE_ERROR audit record for a malformed inbound line.
+
+        The record cannot go through build_audit_record (which expects an Event);
+        PARSE_ERROR is a synthetic event_type with no Event object behind it.
+        """
+        # Capture trace/span ids from the active span (the
+        # `irc.client.process_buffer` we're inside of).
+        span = _otel_trace.get_current_span()
+        ctx = span.get_span_context()
+        trace_id_hex = format(ctx.trace_id, "032x") if ctx.is_valid else ""
+        span_id_hex = format(ctx.span_id, "016x") if ctx.is_valid else ""
+
+        peer_info = self.writer.get_extra_info("peername")
+        remote_addr = f"{peer_info[0]}:{peer_info[1]}" if peer_info else ""
+
+        tags: dict[str, str] = {}
+        tp = current_traceparent()
+        if tp:
+            tags["culture.dev/traceparent"] = tp
+
+        record = {
+            "ts": _utc_iso_timestamp(time.time()),
+            "server": self.server.config.name,
+            "event_type": "PARSE_ERROR",
+            "origin": "local",
+            "peer": "",
+            "trace_id": trace_id_hex,
+            "span_id": span_id_hex,
+            "actor": {
+                "nick": self.nick or "",
+                "kind": "human",
+                "remote_addr": remote_addr,
+            },
+            "target": {"kind": "", "name": ""},
+            "payload": {
+                "line_preview": line[:64],
+                "error": type(exc).__name__,
+            },
+            "tags": tags,
+        }
+        self.server.audit.submit(record)
+
     async def handle(self, initial_msg: str | None = None) -> None:
         peer_info = self.writer.get_extra_info("peername")
         remote_addr = f"{peer_info[0]}:{peer_info[1]}" if peer_info else ""

{agentirc_cli-8.4.0 → agentirc_cli-8.5.0}/culture/agentirc/config.py

@@ -26,6 +26,13 @@ class TelemetryConfig:
     traces_sampler: str = "parentbased_always_on"
     metrics_enabled: bool = True
     metrics_export_interval_ms: int = 10000
+    # Audit JSONL sink (Plan 4). Independent of `enabled` — audit fires
+    # even when telemetry is off so admins always have the trail.
+    audit_enabled: bool = True
+    audit_dir: str = "~/.culture/audit"
+    audit_max_file_bytes: int = 256 * 1024 * 1024  # 256 MiB
+    audit_rotate_utc_midnight: bool = True
+    audit_queue_depth: int = 10000
 
 
 @dataclass

{agentirc_cli-8.4.0 → agentirc_cli-8.5.0}/culture/agentirc/ircd.py

@@ -23,12 +23,14 @@ from culture.constants import (
     SYSTEM_USER_PREFIX,
 )
 from culture.protocol.message import Message
+from culture.telemetry import build_audit_record, current_traceparent
 
 logger = logging.getLogger(__name__)
 
 # Span/metric attribute keys defined once so a future rename has one edit point.
 _ATTR_EVENT_TYPE = "event.type"
 
+
 if TYPE_CHECKING:
     from culture.agentirc.client import Client
     from culture.agentirc.remote_client import RemoteClient
@@ -39,11 +41,12 @@ class IRCd:
     """The culture IRC server."""
 
     def __init__(self, config: ServerConfig):
-        from culture.telemetry import init_metrics, init_telemetry
+        from culture.telemetry import init_audit, init_metrics, init_telemetry
 
         self.config = config
         self.tracer = init_telemetry(config)
         self.metrics = init_metrics(config)
+        self.audit = init_audit(config, self.metrics)
         self.clients: dict[str, Client | VirtualClient] = {}  # nick -> Client
         self.channels: dict[str, Channel] = {}  # name -> Channel
         self.skills: list[Skill] = []
@@ -74,6 +77,8 @@ class IRCd:
         logger.info("Bootstrapping system identity...")
         self._bootstrap_system_identity()
 
+        await self.audit.start()
+
         await self.emit_event(
             Event(
                 type=EventType.SERVER_WAKE,
@@ -223,14 +228,25 @@ class IRCd:
         self.metrics.events_emitted.add(1, {_ATTR_EVENT_TYPE: event_type_str, "origin": origin_str})
         render_started = time.perf_counter()
 
+        trace_id_hex = ""
+        span_id_hex = ""
+        tp: str | None = None
+
         # 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
-        ):
+        ) as span:
             seq = self.next_seq()
             self._event_log.append((seq, event))
+            ctx = span.get_span_context()
+            if ctx.is_valid:
+                trace_id_hex = format(ctx.trace_id, "032x")
+                span_id_hex = format(ctx.span_id, "016x")
+            # Capture traceparent inside the span so trace_flags reflect
+            # the actual sampling decision for this span, not a hardcoded -01.
+            tp = current_traceparent()
             await self._run_skill_hooks(event)
             if not origin_tag:
                 await self._relay_to_peers(event)
@@ -240,6 +256,22 @@ class IRCd:
         render_ms = (time.perf_counter() - render_started) * 1000.0
         self.metrics.events_render_duration.record(render_ms, {_ATTR_EVENT_TYPE: event_type_str})
 
+        # Audit submit happens after the span exits so it doesn't sit inside
+        # the irc.event.emit span (would skew render duration). The trace_id/
+        # span_id captured inside the span point back at it for cross-pillar
+        # joins.
+        tags: dict[str, str] = {"culture.dev/traceparent": tp} if tp else {}
+        self.audit.submit(
+            build_audit_record(
+                server_name=self.config.name,
+                event=event,
+                origin_tag=origin_tag,
+                trace_id=trace_id_hex,
+                span_id=span_id_hex,
+                extra_tags=tags,
+            )
+        )
+
     _NO_SURFACE_TYPES = NO_SURFACE_EVENT_TYPES
 
     @staticmethod
@@ -395,6 +427,7 @@ class IRCd:
             if self._server:
                 self._server.close()
                 await self._server.wait_closed()
+            await self.audit.shutdown()
         finally:
             self._stopped.set()
 

agentirc_cli-8.5.0/culture/protocol/extensions/audit.md

@@ -0,0 +1,109 @@
+# Extension: Audit JSONL Sink
+
+The audit log is a durable, file-based JSON-Lines (`.jsonl`) trail of every event the server
+emits. It is **separate from OTEL traces / metrics / logs** — audit lands directly on local disk
+and never depends on a running collector. Admin-only "who said what to whom, when, via what path."
+
+## File Layout
+
+- **Path:** `<audit_dir>/<server_name>-<YYYY-MM-DD>.jsonl` where `<audit_dir>` defaults to
+  `~/.culture/audit/` (configurable via `telemetry.audit_dir`). The date is **UTC**.
+- **File mode:** `0600` (owner read/write only).
+- **Directory mode:** `0700` (owner only). Created on demand if missing; existing dir mode is
+  left as-is.
+- **Rotation suffix:** when the daily file hits the size cap, the next file gets `.1`, then
+  `.2`, … same date. New day starts a fresh file with no suffix.
+
+Example for server `spark` on 2026-04-27 with two size-cap rotations:
+
+```text
+~/.culture/audit/spark-2026-04-27.jsonl     # first 256 MiB
+~/.culture/audit/spark-2026-04-27.1.jsonl   # next 256 MiB
+~/.culture/audit/spark-2026-04-27.2.jsonl   # current
+```
+
+## Record Schema
+
+Each line in the file is a single JSON object. Lines never wrap. Keys are lowercase with `_`
+separators. Order is canonicalized at write time (stable across writes). Future schema additions
+are additive only — consumers must tolerate unknown keys.
+
+Keys within each record are alphabetically sorted (the writer uses
+`json.dumps(..., sort_keys=True)`). Consumers SHOULD NOT rely on
+insertion order; future producers may emit keys in any order.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `ts` | string | yes | ISO 8601 UTC timestamp with microsecond precision and trailing `Z` (e.g. `2026-04-27T14:32:05.123456Z`). |
+| `server` | string | yes | Server name from `ServerConfig.name`. |
+| `event_type` | string | yes | `EventType.value` (e.g. `message`, `user.join`, `room.create`) or the special string `PARSE_ERROR` for malformed inbound lines. |
+| `origin` | string | yes | `local` if the event originated on this server; `federated` if it arrived via a peer link. |
+| `peer` | string | yes | Peer server name when `origin=federated`; empty string `""` otherwise. |
+| `trace_id` | string | yes | OTEL trace-id (32 hex chars) of the active span at submit time, or `""` if no span. |
+| `span_id` | string | yes | OTEL span-id (16 hex chars) of the active span, or `""`. |
+| `actor` | object | yes | `{nick, kind, remote_addr}` describing who/what produced the event. |
+| `actor.nick` | string | yes | The nick from the event (`event.nick`), or `""`. |
+| `actor.kind` | string | yes | One of `human`, `bot`, `harness`. v1 always emits `human` — Plans 5/6 refine. |
+| `actor.remote_addr` | string | yes | `"<ip>:<port>"` if known (PARSE_ERROR via Client; empty for server-internal sites). |
+| `target` | object | yes | `{kind, name}` describing what the event affected. |
+| `target.kind` | string | yes | `channel` (event.channel set), `nick` (DM target), or `""` for global events. |
+| `target.name` | string | yes | The channel or nick; `""` for global. |
+| `payload` | object | yes | `event.data` with all underscore-prefix keys (`_origin`, etc.) stripped. May include `nick` / `channel` defaulted from `event.nick`/`event.channel`. |
+| `tags` | object | yes | IRCv3-style tag bag. v1 emits at most `culture.dev/traceparent` derived from the active span; empty `{}` if no span. |
+
+## Rotation
+
+Rotation fires when **either** condition is met, checked at the top of every record write:
+
+1. The current UTC date differs from `current_date` (daily roll, controlled by
+   `telemetry.audit_rotate_utc_midnight`).
+2. The current file size + the about-to-be-written record size exceeds
+   `telemetry.audit_max_file_bytes` (default 256 MiB).
+
+The new file is opened with `O_WRONLY | O_APPEND | O_CREAT` mode `0600`. Writes use a single
+`os.write` per record so partial-line interleaving is impossible.
+
+A record larger than `audit_max_file_bytes` is still written — the cap is a soft
+ceiling for accumulated bytes, not a hard reject. The oversized record lands in
+its own freshly-rotated file, and the next record triggers another rotation.
+
+## Durability
+
+Records flow through a bounded `asyncio.Queue` (depth `telemetry.audit_queue_depth`, default
+10000). A dedicated writer task drains the queue and writes each record. On queue overflow, the
+record is **dropped** and `culture.audit.writes{outcome=error}` increments. A stderr warning is
+logged.
+
+This is a deliberate trade-off: dropping records is preferable to blocking `IRCd.emit_event`. A
+real-world audit gap is rare and recoverable; a blocked event loop is catastrophic.
+
+No `fsync` per record — writes hit the page cache and rely on the OS to flush. A hard crash can
+lose the in-flight record.
+
+## Retention
+
+Files are not auto-pruned in v1. Operators prune manually:
+
+```bash
+find ~/.culture/audit -name 'spark-*.jsonl*' -mtime +30 -delete
+```
+
+A future `audit-prune` CLI is TODO.
+
+## Compat
+
+The schema is a stable contract:
+
+- New fields can be added in future versions; old consumers must tolerate unknown keys.
+- Existing keys keep their type and semantics across versions.
+- If a future version needs a breaking change, a top-level `schema_version` integer will be
+  added and bumped — until that exists, treat the schema as version 1.
+
+## Example
+
+PRIVMSG from `alpha-alice` (a federated client on the `alpha` peer) to channel `#general` on
+the local server `spark`:
+
+```json
+{"ts":"2026-04-27T14:32:05.123456Z","server":"spark","event_type":"message","origin":"federated","peer":"alpha","trace_id":"4bf92f3577b34da6a3ce929d0e0e4736","span_id":"00f067aa0ba902b7","actor":{"nick":"alpha-alice","kind":"human","remote_addr":""},"target":{"kind":"channel","name":"#general"},"payload":{"text":"hi","nick":"alpha-alice","channel":"#general"},"tags":{"culture.dev/traceparent":"00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"}}
+```

{agentirc_cli-8.4.0 → agentirc_cli-8.5.0}/culture/telemetry/__init__.py

@@ -3,6 +3,7 @@
 Public surface re-exported here; call sites import from `culture.telemetry`.
 """
 
+from culture.telemetry.audit import AuditSink, build_audit_record, init_audit, utc_iso_timestamp
 from culture.telemetry.context import (
     TRACEPARENT_TAG,
     TRACESTATE_TAG,
@@ -16,14 +17,18 @@ from culture.telemetry.metrics import MetricsRegistry, init_metrics
 from culture.telemetry.tracing import init_telemetry
 
 __all__ = [
+    "AuditSink",
     "ExtractResult",
     "MetricsRegistry",
     "TRACEPARENT_TAG",
     "TRACESTATE_TAG",
+    "build_audit_record",
     "context_from_traceparent",
     "current_traceparent",
     "extract_traceparent_from_tags",
+    "init_audit",
     "init_metrics",
     "init_telemetry",
     "inject_traceparent",
+    "utc_iso_timestamp",
 ]