agentirc-cli 9.0.0__tar.gz → 9.1.0__tar.gz

agentirc_cli-9.1.0/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/).
+
+## [9.1.0] - 2026-04-30
+
+### Added
+
+- Server-core vendored from `culture` at SHA `df50942`. The `agentirc`
+  package now contains the IRCd (`ircd.py`), server-to-server linking
+  (`server_link.py`), channel/event/store/skill modules, `remote_client.py`
+  (peer-server ghost client), and the four built-in skills
+  (`skills/{rooms,threads,history,icon}.py`).
+- Internal vendored support modules under `agentirc/_internal/`:
+  - `aio` (`maybe_await`)
+  - `constants` (system user/channel constants)
+  - `protocol/` (IRC `Message` and numeric `replies`)
+  - `telemetry/` (OpenTelemetry audit/tracing/metrics — full subpackage)
+  - `virtual_client` (`VirtualClient` for in-process bot integration)
+  - `bots/{bot_manager,http_listener}` (no-op stubs; culture replaces
+    these at runtime when wrapping an `IRCd`)
+- `[tool.citation]` block in `pyproject.toml` enumerating every vendored
+  file with a quote/paraphrase/synthesize status, source URL, and
+  sha256, validated by `cite check`.
+- Runtime dependencies: `opentelemetry-api`, `opentelemetry-sdk`,
+  `opentelemetry-exporter-otlp-proto-grpc` (all `>=1.22`).
+- Dev dependency: `citation-cli` (provides the `cite` console script).
+
+### Changed
+
+- Bootstrap spec deviation: `remote_client.py` was originally listed as
+  "do not copy" but turned out to be server-side (used by `server_link`
+  and `virtual_client` for peer-server users in channel member lists).
+  Vendored as public `agentirc/remote_client.py`. See commit `8b4a6d8`.
+
+### Notes
+
+- `agentirc/cli.py` still ships only `version`; the `serve|start|stop|
+  restart|status|link|logs` lifecycle verbs remain stubs. The real CLI
+  is the next slice (PR-B2).
+- Tests are not migrated yet (PR-B3).
+
+## [9.0.0] - 2026-04-30
+
+### Added
+
+- Initial bootstrap of `agentirc-cli` as an installable Python package.
+- Skeleton `agentirc/{__init__,__main__,cli}.py` with `version` verb
+  wired up and lifecycle verbs (`serve|start|stop|restart|status|link|
+  logs`) as stubs.
+- Console scripts: both `agentirc` and `agentirc-cli` map to
+  `agentirc.cli:main`.
+- Major version starts at `9.0.0` to leapfrog the
+  `agentirc-cli==8.7.X.devN` squat that culture previously published to
+  TestPyPI, so dev releases sort as the actual "Latest".

{agentirc_cli-9.0.0 → agentirc_cli-9.1.0}/CLAUDE.md

@@ -2,11 +2,20 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-## Current state: skeleton package, pre-extraction
+## Current state: server-core landed (9.1.0), CLI stubbed (PR-B2 next)
 
-This repo is being bootstrapped from a server-core extraction out of the sibling project [`culture`](https://github.com/OriNachum/culture). The package skeleton is in place — `pyproject.toml`, `agentirc/__init__.py`, `agentirc/__main__.py`, `agentirc/cli.py` (stub) — and `pip install -e .` produces working `agentirc` and `agentirc-cli` console scripts. The IRCd server core has **not** been copied from culture yet; all lifecycle verbs (`serve`, `start`, `stop`, `restart`, `status`, `link`, `logs`) currently exit non-zero with a "not yet implemented" message. **Read the bootstrap spec before doing anything else**; it is the operative source of truth and is intentionally self-contained.
+This repo is the agentirc server-core extraction out of the sibling project [`culture`](https://github.com/OriNachum/culture). As of 9.1.0, the IRCd server core is in place — `agentirc/{ircd,server_link,channel,events,skill,remote_client,…}.py` and `agentirc/skills/{rooms,threads,history,icon}.py` are all present, copied from `culture@df50942` via the `cite-don't-copy` pattern (see `[tool.citation]` in `pyproject.toml`). Internal vendored support modules live under `agentirc/_internal/` (`aio`, `constants`, `protocol/`, `telemetry/`, `virtual_client`, `bots/` stubs).
 
-The culture-side counterpart spec is at `../culture/docs/superpowers/specs/2026-04-30-agentirc-extraction-design.md`. You should not need to open it to act, but it explains the *why* if a decision in the agentirc spec looks arbitrary.
+What is **not** done yet:
+- **`agentirc/cli.py`** is still the Shape A stub. All lifecycle verbs (`serve`, `start`, `stop`, `restart`, `status`, `link`, `logs`) print "not yet implemented" and exit 1. The real CLI lands in PR-B2 (extracted from `../culture/culture/cli/server.py`).
+- **`agentirc/protocol.py`** does not exist yet (PR-B2 also).
+- **Test suite migration** is PR-B3.
+
+Read the bootstrap spec at `docs/superpowers/specs/2026-04-30-bootstrap-design.md` for the full plan; it is the operative source of truth and is intentionally self-contained. The culture-side counterpart spec is at `../culture/docs/superpowers/specs/2026-04-30-agentirc-extraction-design.md` — not normally needed, but explains *why* if a decision looks arbitrary.
+
+### Cite-don't-copy
+
+Vendored culture code is tracked under `[tool.citation]` in `pyproject.toml` using the workspace's [`citation-cli`](https://github.com/OriNachum/citation-cli) tool. Each vendored file has a `quote` (verbatim copy), `paraphrase` (copied with import rewrites), or `synthesize` (rewritten as agentirc-native) status. Run `cite check` to verify integrity. When pulling new culture changes, update the citation entries' source URLs and sha256s — the manifest is the provenance ledger.
 
 ## Three names, one project
 
@@ -22,9 +31,9 @@ There are three different names in play. Don't conflate them:
 
 ## What lives here vs. in culture
 
-- **Server-core (here):** `ircd.py`, `server_link.py`, `channel.py`, `config.py`, `events.py`, the stores (`room_store`, `thread_store`, `history_store`), `rooms_util.py`, `skill.py`, and the `skills/` directory (`rooms`, `threads`, `history`, `icon`).
-- **Stays in culture:** `client.py`, `remote_client.py`, and any test that exercises the IRC *client transport* rather than the server.
-- **Newly created here:** `agentirc/cli.py` (extracted from `../culture/culture/cli/server.py`), `agentirc/__main__.py`, and `agentirc/protocol.py` (consolidates verb names, numerics, and extension tag names that today are inlined as string literals in `ircd.py` / `client.py`).
+- **Server-core (here):** `ircd.py`, `server_link.py`, `channel.py`, `config.py`, `events.py`, the stores (`room_store`, `thread_store`, `history_store`), `rooms_util.py`, `skill.py`, `remote_client.py`, and the `skills/` directory (`rooms`, `threads`, `history`, `icon`). Vendored support under `agentirc/_internal/` (`aio`, `constants`, `protocol/`, `telemetry/`, `virtual_client`, `bots/` stubs).
+- **Stays in culture:** `client.py` (full IRC client transport, used by bots) and any test that exercises the IRC *client transport* rather than the server. Note: the bootstrap spec originally also listed `remote_client.py` as "stays in culture", but it turned out to be a 43-line server-side ghost-client stub used by `server_link.py`; it's vendored here. See PR-B1 commit history.
+- **Newly created here:** `agentirc/cli.py` (today: skeleton stub from PR Shape A; PR-B2 extracts the real one from `../culture/culture/cli/server.py`), `agentirc/__main__.py`. **Coming in PR-B2:** `agentirc/protocol.py` (consolidates verb names, numerics, and extension tag names currently inlined as string literals in `ircd.py` / `client.py`).
 
 When migrating tests, the rule is: pure server tests come here, transport tests stay in culture, mixed tests stay in culture and get rewritten to drive `agentirc serve` as a subprocess fixture rather than importing `IRCd` directly. When unsure, **prefer copying the test here** — this repo owns the IRCd.
 
@@ -34,7 +43,7 @@ Only three modules are public. Everything else is internal and may be refactored
 
 | Module | Members |
 |---|---|
-| `agentirc.config` | `ServerConfig`, `LinkConfig`, `PeerSpec` |
+| `agentirc.config` | `ServerConfig`, `LinkConfig`, `TelemetryConfig` |
 | `agentirc.cli` | `main()`, `dispatch(argv) -> int` |
 | `agentirc.protocol` | verb name constants, numeric reply codes, extension tag names |
 
@@ -51,7 +60,7 @@ Do not rename on-disk artifacts during the bootstrap. That is explicitly out of
 ## Hard invariants
 
 - **No imports back into culture.** After the bootstrap, `git grep -E '^(from|import) culture' agentirc/ tests/` must return nothing. CI should enforce this.
-- **No file rewrites in the bootstrap.** Files copy from `../culture/culture/agentirc/` as-is, with import paths rewritten (`from culture.agentirc.X` → `from agentirc.X`) and nothing else. Improvements ship in follow-up PRs.
+- **Cite-don't-copy adaptation only.** Files copy from `../culture/` with import paths rewritten and minimal adaptation where the dependency boundary forces it (e.g. `culture.bots.{bot_manager,http_listener}` are stubbed to no-ops in `agentirc/_internal/bots/`). All adaptations are recorded in `[tool.citation]` with status `paraphrase` or `synthesize`. Improvements beyond what's needed for the dependency boundary ship in follow-up PRs.
 - **Single synthetic first commit.** Message format: `Initial import from culture@<SHA>` where `<SHA>` is the culture commit ID the caller provides. No cherry-picked history.
 - **No backend SDKs, no `culture` console script.** agentirc must not depend on `claude-agent-sdk`, `anthropic`, `agex-cli`, `afi-cli`, `github-copilot-sdk`, or any other agent/backend SDK, and must not declare a `culture` console script. Those are culture concerns — agent backends and the `culture` command live in `../culture` and stay there.
 

{agentirc_cli-9.0.0 → agentirc_cli-9.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentirc-cli
-Version: 9.0.0
+Version: 9.1.0
 Summary: Agent-friendly IRCd: server core for AI agent meshes
 Project-URL: Homepage, https://github.com/OriNachum/agentirc
 Project-URL: Issues, https://github.com/OriNachum/agentirc/issues
@@ -37,9 +37,13 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Communications :: Chat :: Internet Relay Chat
 Requires-Python: >=3.10
+Requires-Dist: opentelemetry-api>=1.22
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.22
+Requires-Dist: opentelemetry-sdk>=1.22
 Provides-Extra: dev
 Requires-Dist: bandit; extra == 'dev'
 Requires-Dist: black; extra == 'dev'
+Requires-Dist: citation-cli; extra == 'dev'
 Requires-Dist: flake8; extra == 'dev'
 Requires-Dist: isort; extra == 'dev'
 Requires-Dist: pylint; extra == 'dev'

agentirc_cli-9.1.0/agentirc/_internal/aio.py

@@ -0,0 +1,12 @@
+"""Async utilities for culture."""
+
+from __future__ import annotations
+
+import asyncio
+
+
+async def maybe_await(result):
+    """Await the result only if it's a coroutine, otherwise return directly."""
+    if asyncio.iscoroutine(result):
+        return await result
+    return result

agentirc_cli-9.1.0/agentirc/_internal/bots/bot_manager.py

@@ -0,0 +1,38 @@
+"""No-op ``BotManager`` stub.
+
+agentirc is a pure IRCd; bot infrastructure (loading agent backends from
+config, dispatching events to them, graceful shutdown) is a culture concern
+and lives in ``culture.bots.bot_manager``. This stub keeps ``IRCd.start()``
+import-clean for standalone agentirc deployments. Culture's
+:class:`culture.bots.bot_manager.BotManager` is API-compatible and replaces
+this stub when culture wraps an ``IRCd`` (today by subclassing / attribute
+replacement; eventually via a real injection point).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from agentirc.ircd import IRCd
+    from agentirc.skill import Event
+
+
+class BotManager:
+    def __init__(self, server: "IRCd") -> None:
+        self.server = server
+
+    async def load_bots(self) -> None:  # NOSONAR S7503: stub method must remain async to match the abstract contract real implementations override.
+        return None
+
+    def load_system_bots(self) -> None:
+        return None
+
+    def get_bot(self, _nick: str):
+        return None
+
+    async def on_event(self, _event: "Event") -> None:  # NOSONAR S7503: stub method must remain async to match the abstract contract real implementations override.
+        return None
+
+    async def stop_all(self) -> None:  # NOSONAR S7503: stub method must remain async to match the abstract contract real implementations override.
+        return None

agentirc_cli-9.1.0/agentirc/_internal/bots/http_listener.py

@@ -0,0 +1,28 @@
+"""No-op ``HttpListener`` stub.
+
+Pairs with the no-op :class:`agentirc._internal.bots.bot_manager.BotManager`.
+The real implementation lives in ``culture.bots.http_listener`` and exposes
+a webhook surface for triggering bot events. In a standalone agentirc
+deployment there is nothing to listen for, so ``start()`` and ``stop()``
+are no-ops.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from agentirc._internal.bots.bot_manager import BotManager
+
+
+class HttpListener:
+    def __init__(self, bot_manager: "BotManager", host: str, port: int) -> None:
+        self.bot_manager = bot_manager
+        self.host = host
+        self.port = port
+
+    async def start(self) -> None:  # NOSONAR S7503: stub method must remain async to match the abstract contract real implementations override.
+        return None
+
+    async def stop(self) -> None:  # NOSONAR S7503: stub method must remain async to match the abstract contract real implementations override.
+        return None

agentirc_cli-9.1.0/agentirc/_internal/constants.py

@@ -0,0 +1,17 @@
+"""Project-wide constants. Keep strings here, never in source code."""
+
+from __future__ import annotations
+
+import re
+
+# System pseudo-user and channel
+SYSTEM_USER_PREFIX = "system-"
+SYSTEM_CHANNEL = "#system"
+SYSTEM_USER_REALNAME = "Culture system messages"
+
+# IRCv3 message-tag keys we emit/consume
+EVENT_TAG_TYPE = "event"
+EVENT_TAG_DATA = "event-data"
+
+# Event-type name regex (dotted lowercase, ≥2 segments)
+EVENT_TYPE_RE = re.compile(r"^[a-z][a-z0-9_-]*(\.[a-z][a-z0-9_-]*)+$")

agentirc_cli-9.1.0/agentirc/_internal/protocol/message.py

@@ -0,0 +1,128 @@
+from dataclasses import dataclass, field
+
+_TAG_UNESCAPE = {
+    "\\:": ";",
+    "\\s": " ",
+    "\\\\": "\\",
+    "\\r": "\r",
+    "\\n": "\n",
+}
+_TAG_ESCAPE = {v: k for k, v in _TAG_UNESCAPE.items()}
+
+
+def _unescape_tag_value(value: str) -> str:
+    out = []
+    i = 0
+    while i < len(value):
+        if value[i] == "\\" and i + 1 < len(value):
+            two = value[i : i + 2]
+            # Per IRCv3 spec, unknown escapes drop the backslash (yield only
+            # the second char). Known escapes map to their defined character.
+            out.append(_TAG_UNESCAPE.get(two, value[i + 1]))
+            i += 2
+            continue
+        out.append(value[i])
+        i += 1
+    return "".join(out)
+
+
+def _escape_tag_value(value: str) -> str:
+    out = []
+    for ch in value:
+        if ch in _TAG_ESCAPE:
+            out.append(_TAG_ESCAPE[ch])
+        else:
+            out.append(ch)
+    return "".join(out)
+
+
+@dataclass
+class Message:
+    """An IRC protocol message per RFC 2812 §2.3.1 with IRCv3 message-tags.
+
+    Wire format: [@tags SPACE] [:prefix SPACE] command [params] CRLF
+    """
+
+    prefix: str | None = None
+    command: str = ""
+    params: list[str] = field(default_factory=list)
+    tags: dict[str, str] = field(default_factory=dict)
+
+    @staticmethod
+    def _parse_tag_block(line: str) -> "tuple[dict[str, str], str]":
+        """Extract leading @tag block from a wire line.
+
+        Returns (tags_dict, remaining_line). If no tag block, returns ({}, line).
+        """
+        if not line.startswith("@"):
+            return {}, line
+        if " " not in line:
+            return {}, ""  # malformed — no command after tags
+        tag_blob, rest = line[1:].split(" ", 1)
+        tags: dict[str, str] = {}
+        for piece in tag_blob.split(";"):
+            if not piece:
+                continue
+            if "=" in piece:
+                key, value = piece.split("=", 1)
+                tags[key] = _unescape_tag_value(value)
+            else:
+                tags[piece] = ""
+        return tags, rest
+
+    @classmethod
+    def parse(cls, line: str) -> "Message":
+        line = line.rstrip("\r\n")
+        tags, line = cls._parse_tag_block(line)
+
+        if not line:
+            # malformed @-only input
+            return cls(tags=tags, prefix=None, command="", params=[])
+
+        prefix = None
+        if line.startswith(":"):
+            if " " not in line:
+                return cls(tags=tags, prefix=None, command="", params=[])
+            prefix, line = line.split(" ", 1)
+            prefix = prefix[1:]
+
+        trailing = None
+        if " :" in line:
+            line, trailing = line.split(" :", 1)
+
+        parts = line.split()
+        if not parts:
+            return cls(tags=tags, prefix=prefix, command="", params=[])
+        command = parts[0].upper()
+        params = parts[1:]
+        if trailing is not None:
+            params.append(trailing)
+
+        return cls(tags=tags, prefix=prefix, command=command, params=params)
+
+    def format(self) -> str:
+        parts = []
+
+        if self.tags:
+            tag_pieces = []
+            for key, value in self.tags.items():
+                if value == "":
+                    tag_pieces.append(key)
+                else:
+                    tag_pieces.append(f"{key}={_escape_tag_value(value)}")
+            parts.append("@" + ";".join(tag_pieces))
+
+        if self.prefix:
+            parts.append(f":{self.prefix}")
+        parts.append(self.command)
+
+        if self.params:
+            for param in self.params[:-1]:
+                parts.append(param)
+            last = self.params[-1]
+            if " " in last or not last or last.startswith(":"):
+                parts.append(f":{last}")
+            else:
+                parts.append(last)
+
+        return " ".join(parts) + "\r\n"

agentirc_cli-9.1.0/agentirc/_internal/protocol/replies.py

@@ -0,0 +1,52 @@
+"""IRC numeric reply codes (RFC 2812 §5)."""
+
+# Connection registration
+RPL_WELCOME = "001"
+RPL_YOURHOST = "002"
+RPL_CREATED = "003"
+RPL_MYINFO = "004"
+
+# Channel
+RPL_LISTSTART = "321"
+RPL_LIST = "322"
+RPL_LISTEND = "323"
+RPL_TOPIC = "332"
+RPL_NOTOPIC = "331"
+RPL_NAMREPLY = "353"
+RPL_ENDOFNAMES = "366"
+
+# Mode
+RPL_UMODEIS = "221"
+RPL_CHANNELMODEIS = "324"
+
+# Discovery
+RPL_WHOISUSER = "311"
+RPL_WHOISSERVER = "312"
+RPL_ENDOFWHOIS = "318"
+RPL_WHOISCHANNELS = "319"
+RPL_WHOREPLY = "352"
+RPL_ENDOFWHO = "315"
+
+# Errors
+ERR_NOSUCHNICK = "401"
+ERR_NOSUCHSERVER = "402"
+ERR_NOSUCHCHANNEL = "403"
+ERR_CANNOTSENDTOCHAN = "404"
+ERR_UNKNOWNCOMMAND = "421"
+ERR_NONICKNAMEGIVEN = "431"
+ERR_ERRONEUSNICKNAME = "432"
+ERR_NICKNAMEINUSE = "433"
+ERR_USERNOTINCHANNEL = "441"
+ERR_NOTONCHANNEL = "442"
+ERR_NEEDMOREPARAMS = "461"
+ERR_ALREADYREGISTRED = "462"
+ERR_CHANOPRIVSNEEDED = "482"
+ERR_USERSDONTMATCH = "502"
+
+# Error/reply message texts
+MSG_NEEDMOREPARAMS = "Not enough parameters"
+MSG_NOSUCHCHANNEL = "No such channel"
+MSG_NOSUCHNICK = "No such nick"
+MSG_NOTONCHANNEL = "You're not on that channel"
+MSG_ENDOFWHO = "End of WHO list"
+MSG_NOSUCHTHREAD = "No such thread"

agentirc_cli-9.1.0/agentirc/_internal/telemetry/__init__.py

@@ -0,0 +1,34 @@
+"""OpenTelemetry integration for Culture.
+
+Public surface re-exported here; call sites import from `culture.telemetry`.
+"""
+
+from agentirc._internal.telemetry.audit import AuditSink, build_audit_record, init_audit, utc_iso_timestamp
+from agentirc._internal.telemetry.context import (
+    TRACEPARENT_TAG,
+    TRACESTATE_TAG,
+    ExtractResult,
+    context_from_traceparent,
+    current_traceparent,
+    extract_traceparent_from_tags,
+    inject_traceparent,
+)
+from agentirc._internal.telemetry.metrics import MetricsRegistry, init_metrics
+from agentirc._internal.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",
+]