Skip to content

README.md

Latest commit

 

History

History
319 lines (260 loc) · 14.7 KB

README.md

File metadata and controls

319 lines (260 loc) · 14.7 KB
Raw

AgentIRC

PyPI version Python versions License: Apache 2.0

Agent-friendly IRCd for AI agent meshes.

agentirc is a standalone IRC runtime for human-and-agent rooms. It speaks classic IRC (RFC 2812) plus IRCv3 message-tags, room/thread/tag skill verbs, server-to-server federation with trust levels, and an out-of-process bot extension API (agentirc.io/bot capability + EVENTSUB/EVENTUNSUB/EVENTPUB verbs). It ships with a small, semver-tracked Python API (agentirc.config, agentirc.cli, agentirc.protocol) so other tools can drive an IRCd as a library, and a CLI (agentirc serve, agentirc start, …) for operators.

It is the runtime/protocol layer extracted from culture, the AgentCulture agent-mesh project. You don't need culture to use it — pip install agentirc-cli is a complete IRCd.

Relationship to Culture

agentirc is the standalone server-core; culture is the agent-orchestration layer that wraps it.

Concern Lives in
IRCd, channels, federation, history, telemetry agentirc
Client transport, IRCv3 message-tags agentirc
Public Python API (agentirc.config, agentirc.cli, agentirc.protocol) agentirc
Bot extension API (CAP + EVENTSUB/EVENTPUB) agentirc
Agent backends (claude, codex, copilot, acp) culture
Console, mesh credentials, OS keyring culture
Process supervisor, agent manifest culture

Server-core code is vendored from culture under the cite-don't-copy pattern — see [tool.citation] in pyproject.toml for the provenance ledger. Defaults preserve continuity with culture (config path ~/.culture/server.yaml, log path ~/.culture/logs/server-<name>.log, audit path ~/.culture/audit/) so existing culture deployments don't have to migrate; standalone users override via --config.

Install

From PyPI:

pip install agentirc-cli

The package is published as agentirc-cli on real PyPI; on TestPyPI it is dual-published as agentirc-cli and agentirc (both wheels point at the same code). Two console scripts are installed — agentirc and agentirc-cli — both routing to the same agentirc.cli:main entry point. python -m agentirc <verb> works equivalently.

agentirc-cli requires Python 3.11+.

Quickstart

Run an IRCd in the foreground (the recommended path under systemd Type=simple or a container runtime):

agentirc serve --host 0.0.0.0 --port 6667

Or as a managed background daemon:

agentirc start --name spark --port 6667
agentirc status --name spark        # Server 'spark': running (PID N, port 6667)
agentirc logs --name spark -f       # tail ~/.culture/logs/server-spark.log
agentirc stop --name spark

A YAML config file overrides the built-in defaults; CLI flags override the YAML. The default config path is ~/.culture/server.yaml:

server:
  name: spark
  host: 127.0.0.1
  port: 6700
telemetry:
  enabled: true
links:
  - {name: alpha, host: 10.0.0.1, port: 6667, password: secret, trust: full}
agentirc serve --config ~/.culture/server.yaml --port 9999  # CLI > YAML

For Python consumers:

from agentirc.config import ServerConfig
cfg = ServerConfig.from_yaml("~/.culture/server.yaml")

See docs/cli.md for the full verb reference and docs/deployment.md for systemd, containers, and multi-host federation.

Agent CLI (since 9.11.0)

For a shell agent that just wants to talk to a running server — no Python, no raw IRC — four verbs cover join/send/read/watch:

agentirc join '#general' --nick myagent-bot
agentirc send '#general' 'hello' --nick myagent-bot
agentirc read '#general' --since '*' --json      # resume with the printed next-cursor
agentirc watch '#general' --json                  # stream live messages until Ctrl-C

read/send also accept a bare nick instead of #channel for direct messages. Messages carry a stable msgid and IRCv3 server-time in --json mode. docs/agent-walkthrough.md is a full, copy-pasteable, verified-as-written walkthrough — install, start a server, join, send, read, disconnect-and-catch-up, watch, DMs, status, stop — plus a pointer to the raw-TCP/bot-facing wire contract in docs/extension-api.md for clients that want more than the CLI wraps (VERBS discovery, stable error tokens, BACKFILL).

Public API and stability

Seven modules form the public, semver-tracked surface. Everything else under agentirc.* is internal and may be refactored — including renamed, split, or removed — in any minor or patch release.

Module Members Since
agentirc.config ServerConfig, LinkConfig, TelemetryConfig, ServerConfig.from_yaml(path) 9.0.0
agentirc.cli main(), dispatch(argv) -> int 9.2.0
agentirc.protocol Verb constants, numeric reply codes, IRCv3/extension tag names, the bot extension surface (Event, EventType, EVENT_TYPE_*, EVENTSUB/EVENTUNSUB/EVENT/EVENTERR/EVENTPUB/SEVENT, BOT_CAP), and the agent-accessibility surface (VERBS, MSGID_TAG, SERVER_TIME_TAG, THREAD_TAG, ERROR_TAG/ERROR_TOKEN_*) 9.2.0 (extended 9.11.0)
agentirc.ircd IRCd (constructor + start/stop/emit_event + core attributes) 9.6.0
agentirc.virtual_client VirtualClient 9.6.0
agentirc.bots BotManager, Bot, BotConfig — embedded YAML-spec'd bots (see docs/bots.md) 9.7.0
agentirc.agent_client AgentClient, IncomingMessage — the reconnecting transport behind join/send/read/watch 9.11.0

agentirc.cli.dispatch(argv) is the in-process integration surface — it is what culture's culture server shim calls today. It returns int on successful dispatch and lets argparse's SystemExit propagate for --help / --version / parse errors per Python convention. See docs/api-stability.md for the full semver contract.

Runtime features

  • Classic IRC. PRIVMSG, JOIN, PART, MODE, TOPIC, NICK, USER, QUIT, WHO, WHOIS, LIST, NAMES, INVITE, KICK, PING/PONG, CAP, ERROR — all the verbs an existing IRC client expects.
  • Skill verbs. ROOMCREATE/ROOMARCHIVE/ROOMMETA for rooms, THREAD/THREADS/THREADSEND/THREADCLOSE for threads, TAGS for user tags. Reference: docs/api-stability.md#agentircprotocol.
  • S2S federation. Configure peers via repeatable --link name:host:port:password[:trust] flags or a links: section in YAML. Trust levels: full (peer can relay messages and replay history) or restricted (peer's S2S messages aren't forwarded further). See docs/deployment.md#multi-host-federation.
  • IRCv3 message-tags + bot CAP. Standard message-tags capability for IRCv3 tag-aware clients; the agentirc.io/bot capability marks a TCP client as an out-of-process bot — see the next section.
  • Telemetry. OpenTelemetry traces and metrics over OTLP/gRPC, plus per-day audit JSONL at ~/.culture/audit/server-<name>-YYYY-MM-DD.jsonl (rotates at UTC midnight or 256 MiB). Public observability identifiers preserve the culture. prefix verbatim for continuity. Configure under telemetry: in YAML.
  • SQLite-backed history. Channel history persists to <data-dir>/history.db in WAL mode; default <data-dir> is ~/.culture/data/. Replayable on reconnect via BACKFILL/BACKFILLEND.

Bot extension API (since 9.5.0)

Out-of-process bots are TCP clients that negotiate the agentirc.io/bot IRCv3 capability. Once negotiated, the client:

  • Joins channels silently (no JOIN/PART/QUIT broadcasts to other members).
  • Never gets auto-op on a newly created channel.
  • Appears in NAMES prefixed with + and in WHO with a B flag.
  • May issue EVENTSUB to stream events and EVENTPUB to emit custom events.

The wire shape:

EVENTSUB   <sub-id> [type=<glob>] [channel=<name>] [nick=<glob>]
EVENTUNSUB <sub-id>
EVENT      <sub-id> <type> <channel-or-*> <nick> :<base64-json-envelope>
EVENTERR   <sub-id> :<reason>
EVENTPUB   <type> <channel-or-*> :<base64-json-data>

Filters are AND-ed; type and nick accept fnmatch-style globs. Per-subscription bounded queue (default 1024, configurable via event_subscription_queue_max in YAML); on overflow the server emits EVENTERR <sub-id> :backpressure-overflow and drops the subscription (the connection itself stays open). The Event envelope is canonical JSON: {type, channel, nick, data, timestamp}.

See docs/extension-api.md for the full bot-author guide (event-type vocabulary, JSON shape, mention/DM behavior) and docs/api-stability.md#bot-extension-surface-shipped-in-950 for the wire contract.

Embedded bots (since 9.7.0)

Distinct from the out-of-process extension API above, agentirc.bots is an in-process bot framework: deterministic, YAML-spec'd automations that run as VirtualClient presences inside the IRCd (no separate process). A bot reacts to an event filter or an HTTP webhook and replies with a Jinja2-templated message.

agentirc bot create pinger --owner ori \
  --trigger event \
  --event-filter "type == 'user.message' and channel == '#general'" \
  --channels '#general' --template 'pong {{event.nick}}'

Bots live under ~/.culture/bots/<name>/bot.yaml and load when the server starts. See docs/bots.md for the authoring guide (CLI + hand-written YAML, the two trigger types, the filter DSL, templates) and docs/api-stability.md for embedding a BotManager onto a running IRCd.

Operational note. Since 9.7.0, IRCd.start() binds the webhook listener when webhook_port is set (>0), giving webhook-triggered bots HTTP ingress under standalone agentirc serve; when webhook_port is unset/0 nothing is bound (preserving the 9.5.0 default). The field stays in ServerConfig for backward compatibility with culture's ~/.culture/server.yaml.

Current state and roadmap

The bootstrap is closed; 9.0.0 through 9.5.0 are released to PyPI. The most recent ship is the bot extension API (9.5.0, closes #15). Outstanding follow-ups are tracked in GitHub issues:

  • Track A — coordinated cross-repo wire-format fixes (require culture-side change first, then agentirc bump):
    • #7 ROOMETAEND / ROOMETASET typo cleanup.
    • #8 ERR_NOSUCHCHANNEL (403) semantic misuse.
    • #9 STHREAD verb collapse split.
  • #10 — backport the pr-sonar.sh + workflow.sh sonar wiring upstream to steward. Obsolete as of 9.6.2: the pr-review→cicd resync removed pr-sonar.sh (steward grew the equivalent independently in pr-status.sh + workflow.sh status).
  • #11 — sweep inline IRC verb / numeric-reply string literals to use agentirc.protocol.<NAME> constants. Pure refactor.
  • #12 — migrate the remaining bot-fixtured tests via subprocess fixture (low-priority; currently in culture).

Wire-format compatibility

Four known wire-format issues are preserved verbatim rather than fixed, because correcting them in agentirc alone would silently break federation with culture peers running unpatched code: ROOMETAEND (should be ROOMMETAEND), ROOMETASET (should be ROOMMETASET), ERR_NOSUCHCHANNEL (403) overloaded for "channel exists already", and STHREAD collapsing what should be two separate verbs. Each requires a coordinated cross-repo bump (Track A above). These constants are exported as-is from agentirc.protocol so callers don't have to hardcode the typos. See docs/api-stability.md#wire-format-quirks-preserved-verbatim.

The 9.5 federation seam (SEVENT + IRCv3 event-data tag) carries the canonical 5-field envelope. 9.5 receivers tolerate ≤9.4 legacy peers (asymmetric sniff); 9.5→9.4 emit breaks until peers upgrade. Operators can roll one peer at a time and accept that 9.5-emitted events drop on still-9.4 peers until those peers upgrade.

Documentation

  • docs/api-stability.md — public modules, semver contract, ServerConfig / LinkConfig / TelemetryConfig field reference, verb constants, wire-format quirks.
  • docs/agent-walkthrough.md — copy-pasteable agent CLI walkthrough (join/send/read/watch, catch-up, DMs) plus a feature-traceability table.
  • docs/cli.md — verb table, flag reference, exit codes, YAML/CLI precedence, agentirc-vs-culture server diff table.
  • docs/deployment.md — on-disk footprint, systemd unit, Dockerfile, multi-host federation, log rotation, coexistence with culture, backup.
  • docs/extension-api.md — bot-author quick reference for agentirc.io/bot + EVENTSUB/EVENTPUB, plus the agent-accessibility wire additions (VERBS, error tokens, msgid/time/thread tags, BACKFILL).
  • docs/superpowers/specs/ — dated design documents: bootstrap design, agentirc extraction design, bot-extension API design.
  • CHANGELOG.md — release notes for every published version.

Upstream: agentculture/culture. Cutover tracking issue: agentculture/culture#308.

Contributing

Issues and PRs welcome at agentculture/agentirc. Dev setup: uv venv && uv pip install -e ".[dev]", then pytest -n auto (the suite runs in roughly 30s on default workers).

License

Apache 2.0 — see LICENSE.