agentirc-cli 6.0.0__tar.gz → 6.0.2__tar.gz

{agentirc_cli-6.0.0 → agentirc_cli-6.0.2}/.github/workflows/pages.yml

@@ -28,6 +28,12 @@ jobs:
       - name: Setup Pages
         uses: actions/configure-pages@v5
 
+      - name: Gather AgentIRC docs
+        run: |
+          rm -rf docs/agentirc
+          mkdir -p docs/agentirc
+          cp -r culture/agentirc/docs/. docs/agentirc
+
       - name: Build with Jekyll
         run: bundle exec jekyll build
         env:

{agentirc_cli-6.0.0 → agentirc_cli-6.0.2}/.gitignore

@@ -182,9 +182,9 @@ cython_debug/
 .abstra/
 
 # Visual Studio Code
-#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
 #  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
-#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  and can be added to the global gitignore or merged into this file. However, if you prefer,
 #  you could uncomment the following to ignore the entire vscode folder
 # .vscode/
 
@@ -215,3 +215,6 @@ safety-results.json
 # Superpowers & worktrees
 .superpowers/
 .worktrees/
+
+# Generated docs (source of truth is culture/agentirc/docs/)
+docs/agentirc/

{agentirc_cli-6.0.0 → agentirc_cli-6.0.2}/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to this project will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [6.0.2] - 2026-04-10
+
+
+### Changed
+
+- AgentIRC local docs with Jekyll pipeline copy step
+
+## [6.0.1] - 2026-04-10
+
+
+### Fixed
+
+- agent create/join/delete/archive/unarchive/rename crash with manifest-format server.yaml (#208)
+- Auto-migrate legacy agents.yaml to manifest format on first load
+- Server rename/archive/unarchive now work with manifest format
+
 ## [6.0.0] - 2026-04-10
 
 

{agentirc_cli-6.0.0 → agentirc_cli-6.0.2}/PKG-INFO

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

{agentirc_cli-6.0.0 → agentirc_cli-6.0.2}/_config.yml

@@ -45,6 +45,7 @@ exclude:
   - .gitignore
   - .github/
   - .claude/
+  - culture/
   - server/
   - clients/
   - protocol/commands.py

agentirc_cli-6.0.2/culture/agentirc/CLAUDE.md

@@ -0,0 +1,125 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Is
+
+AgentIRC is a custom async Python IRCd (IRC server) built from scratch for AI agent collaboration. It is **not** a wrapper around existing IRC servers. ~4,300 lines of pure async Python (asyncio). Located at `culture/agentirc/` within the culture project.
+
+## Running
+
+```bash
+# Start the server directly
+python -m culture.agentirc --name spark --host 0.0.0.0 --port 6667
+
+# With peer linking
+python -m culture.agentirc --name spark --port 6667 \
+  --link thor:192.168.1.10:6667:secretpass \
+  --link orin:192.168.1.11:6667:secretpass:restricted
+
+# Via the culture CLI (typical usage)
+culture server start --name spark
+```
+
+## Testing
+
+Always use `/run-tests` from the parent culture project. Tests are in `tests/` at the repo root, not inside agentirc.
+
+Key test files for agentirc:
+
+- `test_connection.py`, `test_channel.py`, `test_messaging.py` — core IRC
+- `test_skills.py` — skill lifecycle, event dispatch, command routing
+- `test_rooms.py`, `test_rooms_integration.py`, `test_room_persistence.py` — managed rooms
+- `test_threads.py`, `test_thread_buffer.py` — thread system
+- `test_federation.py`, `test_rooms_federation.py` — S2S linking
+- `test_link_reconnect.py` — link failover and recovery
+- `test_mentions.py`, `test_mention_alias.py` — @-mention parsing
+- `test_history.py`, `test_persistence.py` — storage layer
+
+Tests use real TCP connections, no mocks. The `conftest.py` provides:
+
+- `server` — an IRCd on a random port
+- `make_client(nick, user)` — connects a raw TCP test client
+- `linked_servers` — two federated IRCd instances with completed handshake
+- `make_client_a` / `make_client_b` — clients for each linked server
+
+All nicks in tests must use `testserv-<name>` format (matching the test server name). For linked server tests, use `alpha-<name>` and `beta-<name>`.
+
+## Architecture
+
+### Core Loop
+
+`ircd.py` is the orchestrator. On startup: bind TCP listener, load default skills (history, icon, rooms, threads), restore persistent rooms from disk, start webhook HTTP listener.
+
+Each incoming TCP connection is dispatched based on the first message: `PASS` → server-to-server link (`server_link.py`), otherwise → client connection (`client.py`).
+
+### Three Client Types
+
+1. **Client** (`client.py`) — local TCP connection, handles all IRC commands
+2. **RemoteClient** (`remote_client.py`) — ghost representing a user on a peer server. **`send()` is a no-op**; message relay happens at the `ServerLink` level
+3. **VirtualClient** — bots loaded via `culture.bots.BotManager`
+
+All three share the same nick lookup namespace (`ircd.clients` + `ircd.remote_clients`), so WHOIS/WHO/NAMES work transparently.
+
+### Event System
+
+Events flow through a sequenced log (`ircd._event_log`, capped at 10,000 entries). Each event gets a monotonically increasing `_seq`. Skills receive events via `on_event()`. Server links relay events to peers via a dispatch table (`_RELAY_DISPATCH` in `server_link.py`).
+
+The `_origin` key in event data marks events received from a peer — prevents re-relay loops and excludes them from backfill replay.
+
+### Federation (server_link.py)
+
+The most complex file (886 lines). Key concepts:
+
+- **Handshake**: PASS + SERVER (order-flexible, both required)
+- **Trust levels**: `"full"` (relay everything) or `"restricted"` (only channels in `shared_with`)
+- **S2S commands**: All prefixed with `S` (SNICK, SJOIN, SMSG, STOPIC, SROOMMETA, etc.)
+- **Backfill**: On reconnect, peer requests `BACKFILL <name> <last_seq>`, server replays locally-originated events since that seq
+- **Channel filtering**: `+R` mode = never federate; `+S <server>` = relay only to listed peers
+
+### Skills (skill.py + skills/)
+
+Server-level extensions — not bots, no nicks, invisible to clients. Four default skills loaded at startup:
+
+| Skill | File | Commands | Storage |
+|-------|------|----------|---------|
+| HistorySkill | `skills/history.py` | HISTORY RECENT, HISTORY SEARCH | SQLite (`history.db`) |
+| RoomsSkill | `skills/rooms.py` | ROOMCREATE, ROOMMETA, TAGS, ROOMINVITE, ROOMKICK, ROOMARCHIVE | JSON (`rooms/`) |
+| ThreadsSkill | `skills/threads.py` | THREAD CREATE/REPLY, THREADS, THREADCLOSE [PROMOTE] | JSON (`threads/`) |
+| IconSkill | `skills/icon.py` | ICON | In-memory only |
+
+To add a skill: subclass `Skill`, set `name` and `commands`, implement `on_event()` and/or `on_command()`. Skills are registered at startup only — no hot-reload.
+
+### Managed Rooms vs Plain Channels
+
+Plain channels (created by JOIN) are ephemeral — deleted when empty. Managed rooms (created by ROOMCREATE) have a `room_id`, are persistent by default, support metadata (purpose, instructions, tags, agent_limit), and survive being empty.
+
+Tag-based auto-invitation: when room tags or agent tags change, the server automatically sends ROOMINVITE to matching agents. Tags fire **only on change** — setting the same tags twice won't re-invite.
+
+### Thread Promotion
+
+`THREADCLOSE PROMOTE` converts a thread into a breakout channel. It auto-joins participants, replays thread history as NOTICEs, and archives the original thread. The breakout is a **plain channel** (not a managed room), so it will disappear if emptied.
+
+## Non-Obvious Behaviors
+
+- **Nick format enforced**: All nicks must be `<servername>-<agent>`. Rejected otherwise.
+- **Auto-op**: First joiner gets op if no ops exist, but only among **local** members (RemoteClients never auto-promoted).
+- **Buffer cap**: Client read buffer limited to 8192 bytes; oldest data discarded on overflow.
+- **Room ID format**: `"R" + base36(timestamp_ms + counter)` — generation uses a threading lock in `rooms_util.py`.
+- **Mention parsing**: `@<nick>` in PRIVMSG/NOTICE triggers server-side notification to the mentioned user (if in same channel).
+- **Empty room notice**: When a persistent managed room empties, the owner gets a NOTICE suggesting archival.
+
+## Documentation
+
+AgentIRC has its own `docs/` folder. These pages are the source of truth
+for the AgentIRC section on culture.dev. CI copies them to `docs/agentirc/`
+before the Jekyll build. Add or edit pages here — they use standard Just
+The Docs front matter with `parent: AgentIRC`.
+
+## Key Dependencies
+
+- `culture.protocol.message` / `culture.protocol.replies` — shared IRC message parsing and numeric replies
+- `culture.aio.maybe_await` — utility for async/sync interop
+- `culture.bots` — BotManager, VirtualClient, webhook HTTP listener
+- `aiohttp` — webhook listener
+- `sqlite3` (stdlib) — history persistence

agentirc_cli-6.0.2/culture/agentirc/docs/agentirc-architecture.md

@@ -0,0 +1,178 @@
+---
+title: "AgentIRC Architecture"
+parent: "AgentIRC"
+nav_order: 2
+---
+
+<!-- markdownlint-disable MD025 -->
+
+# AgentIRC Architecture
+
+Code-level internals for contributors modifying the server. For the
+conceptual layer overview, see `docs/architecture/server-architecture.md`
+at the repo root.
+
+## Startup Sequence
+
+`IRCd.start()` executes in this order:
+
+1. **Register default skills** — HistorySkill, IconSkill, RoomsSkill,
+   ThreadsSkill. Each skill's `start()` is called, which may load
+   persisted state from disk.
+2. **Restore persistent rooms** — reads JSON files from
+   `{data_dir}/rooms/`, recreates `Channel` objects with full metadata.
+3. **Initialize BotManager** — loads bot definitions from
+   `~/.culture/bots/`, creates VirtualClients.
+4. **Bind TCP socket** — `asyncio.start_server()` on
+   `config.host:config.port`.
+5. **Start webhook HTTP listener** — binds on `127.0.0.1:webhook_port`.
+   Non-fatal if port is unavailable.
+
+## Connection Routing
+
+`_handle_connection()` reads the first chunk from the socket and peeks
+at the first line:
+
+- **PASS** → server-to-server link. Creates a `ServerLink` and calls
+  `link.handle(initial_msg=...)`.
+- **Anything else** → client connection. Creates a `Client` and calls
+  `client.handle(initial_msg=...)`.
+
+Both accept the initial data so the peeked line is not lost. This means
+the first command from any connection is always processed — there is no
+"discard and re-read" step.
+
+## Three Client Types
+
+| Type | Location | Purpose |
+|------|----------|---------|
+| `Client` | `client.py` | Local TCP connection. Handles all C2S commands. |
+| `RemoteClient` | `remote_client.py` | Ghost for a user on a peer server. **`send()` is a no-op** — relay happens at the `ServerLink` level. |
+| `VirtualClient` | `culture/bots/` | Bot loaded by BotManager. Hooks into the server via the bot framework. |
+
+All three share one namespace. `IRCd.get_client(nick)` checks
+`self.clients` → `self.remote_clients` → `self.bot_manager` in order.
+This makes WHOIS, WHO, and NAMES work transparently across all types.
+
+## Command Dispatch
+
+In `client.py`, `_dispatch(msg)` routes incoming commands:
+
+1. Look for `_handle_{command.lower()}()` method on the Client instance.
+   Standard IRC commands (NICK, JOIN, PRIVMSG, MODE, etc.) are handled
+   this way.
+2. If no method found, call `server.get_skill_for_command(command)`.
+   Skills register the custom verbs they handle (e.g., RoomsSkill
+   registers `ROOMCREATE`, `ROOMMETA`, `TAGS`, etc.). The first matching
+   skill's `on_command()` is called.
+3. If neither matches and the client is registered, send
+   `ERR_UNKNOWNCOMMAND`.
+
+**Where to add new commands:**
+
+- Standard IRC behavior → add `_handle_<command>` to `Client`
+- Extension command → create or modify a Skill and add the verb to its
+  `commands` set
+
+## Event System
+
+Events are the backbone of skill notifications and federation relay.
+
+### Lifecycle
+
+1. Something happens (message sent, user joins, room metadata changes).
+2. Code creates an `Event(type, channel, nick, data)`.
+3. `IRCd.emit_event(event)` is called:
+   - Assigns monotonic `_seq` via `next_seq()`
+   - Appends `(seq, event)` to `_event_log` (deque, maxlen 10,000)
+   - Calls `on_event()` on every registered skill
+   - If `event.data` does NOT contain `_origin`, relays to all linked
+     peers via `link.relay_event()`
+
+### The `_origin` Flag
+
+When a peer relays an event to us, we emit it locally with
+`data["_origin"] = peer_name`. This prevents:
+
+- **Re-relay** — events from peers are not forwarded to other peers
+- **Backfill duplication** — only locally-originated events are replayed
+  during backfill recovery
+
+### EventType Values
+
+```text
+MESSAGE, JOIN, PART, QUIT, TOPIC, ROOMMETA, TAGS,
+ROOMARCHIVE, THREAD_CREATE, THREAD_MESSAGE, THREAD_CLOSE
+```
+
+## Skill Lifecycle
+
+```python
+class Skill:
+    name: str = ""
+    commands: set[str] = set()
+
+    async def start(self, server: IRCd) -> None
+    async def stop(self) -> None
+    async def on_event(self, event: Event) -> None
+    async def on_command(self, client: Client, msg: Message) -> None
+```
+
+Skills are registered at startup only — there is no hot-reload. Adding
+a new skill requires a server restart.
+
+The four default skills:
+
+| Skill | Commands |
+|-------|----------|
+| HistorySkill | `HISTORY` |
+| IconSkill | `ICON` |
+| RoomsSkill | `ROOMCREATE`, `ROOMMETA`, `TAGS`, `ROOMINVITE`, `ROOMKICK`, `ROOMARCHIVE` |
+| ThreadsSkill | `THREAD`, `THREADS`, `THREADCLOSE` |
+
+## Persistence
+
+Three storage backends, all optional (require `data_dir` in config):
+
+| Store | Format | Location | Notes |
+|-------|--------|----------|-------|
+| `RoomStore` | JSON | `{data_dir}/rooms/{ROOM_ID}.json` | Room ID sanitized to alphanumeric only |
+| `ThreadStore` | JSON | `{data_dir}/threads/{safe_key}.json` | Key = sanitized channel + thread name |
+| `HistoryStore` | SQLite | `{data_dir}/history.db` | WAL journaling, 30-day retention, auto-prune on startup |
+
+Rooms and threads are loaded at startup. History is loaded by the
+HistorySkill during its `start()` hook.
+
+## Federation Internals
+
+`server_link.py` maps EventTypes to S2S relay methods via
+`_RELAY_DISPATCH`. Trust filtering happens in `should_relay(channel)`:
+
+- Channel with `+R` mode → never relayed
+- Channel in peer's `shared_with` set → relayed only to that peer
+- Peer with `trust="restricted"` → only relays channels both sides
+  agreed to share
+
+On reconnect, peers exchange `BACKFILL <name> <last_seq>` requests. The
+server replays events from `_event_log` where `seq > last_seq` and
+`_origin` is not set (locally-originated only).
+
+See `docs/architecture/layer4-federation.md` at the repo root for the
+conceptual overview and `culture/protocol/extensions/federation.md` for
+the wire spec.
+
+## Key Invariants
+
+These are easy to violate if you don't know about them:
+
+- **Nick format**: all nicks must match `{servername}-{agent}`. Enforced
+  at registration in `_handle_nick()`.
+- **Auto-op**: first joiner to an empty channel gets operator, but only
+  among **local** members. `RemoteClient` instances are excluded from
+  auto-promotion to avoid federation inconsistency.
+- **Buffer cap**: client read buffer capped at 8,192 bytes. Overflow
+  discards oldest data (not newest).
+- **Empty cleanup**: non-persistent channels are deleted when the last
+  member leaves. Persistent managed rooms stay and notify the owner.
+- **Room ID format**: `"R" + base36(timestamp_ms + counter)`. Generation
+  uses a `threading.Lock` in `rooms_util.py` for atomicity.

agentirc_cli-6.0.2/culture/agentirc/docs/agentirc-features.md

@@ -0,0 +1,192 @@
+---
+title: "AgentIRC Features"
+parent: "AgentIRC"
+nav_order: 4
+---
+
+<!-- markdownlint-disable MD025 -->
+
+# AgentIRC Features
+
+AgentIRC extends standard IRC with managed rooms, conversation threads,
+agent tags, and message history. This doc covers the behavioral overview.
+For raw IRC command syntax, see [Raw IRC Skills](agentirc-skill.md). For
+wire protocol specs, see `culture/protocol/extensions/` at the repo root.
+
+## Managed Rooms
+
+Full docs: `docs/rooms.md` at the repo root.
+
+### Room vs Plain Channel
+
+Plain channels (created by `JOIN`) have no metadata, no persistence, and
+are deleted when the last member leaves.
+
+Managed rooms (created by `ROOMCREATE`) add:
+
+- **Room ID** — immutable unique identifier (e.g., `R7K2M9`)
+- **Owner** — transferable via `ROOMMETA #room owner new-nick`
+- **Purpose and Instructions** — what the room is for and how to behave
+- **Tags** — drive self-organizing membership (see Agent Tags below)
+- **Persistence** — room survives being empty (default: true)
+- **Archiving** — rename to `-archived`, metadata preserved, joins
+  rejected
+
+### Key Behaviors
+
+- Creator is auto-joined as channel operator
+- When a persistent room empties, the owner gets a NOTICE suggesting
+  archival
+- Archived rooms reject `JOIN` and get renamed (e.g.,
+  `#room-archived`, `#room-archived#2`)
+- The original name is freed for reuse — a new room gets a new ID
+
+## Conversation Threads
+
+Full docs: `docs/architecture/threads.md` at the repo root.
+
+### What Threads Are
+
+Lightweight inline sub-conversations anchored to a channel. Thread
+messages appear as regular PRIVMSG with a `[thread:name]` prefix, so
+standard IRC clients (weechat, irssi) display them without special
+support:
+
+```text
+<alice> [thread:auth-refactor] Let's refactor the auth module
+<bob>   [thread:auth-refactor] I'll take token refresh
+```
+
+### Lifecycle
+
+```text
+CREATE  →  REPLY (repeat)  →  CLOSE    (archived, summary posted)
+                               PROMOTE  (becomes breakout channel)
+```
+
+- **Create** — any channel member, with an initial message
+- **Reply** — any channel member. Capped at 500 messages per thread
+  (oldest trimmed).
+- **Close** — thread creator or channel operator. Optional summary
+  posted to the parent channel.
+- **Promote** — thread creator or channel operator. Converts the thread
+  into a full breakout channel.
+
+### Thread Names
+
+1-32 characters. Alphanumeric and hyphens only. Must start and end with
+an alphanumeric character.
+
+Valid: `auth-refactor`, `bug42`, `deploy-2026-04`
+
+### Mentions in Threads
+
+`@nick` in thread messages triggers a server NOTICE to the mentioned
+user. This works across federation — remote agents are notified too.
+
+## Thread Promotion
+
+When a thread outgrows inline format, promote it to a breakout channel:
+
+```text
+THREADCLOSE PROMOTE #general auth-refactor
+```
+
+### What Happens
+
+1. **Breakout channel created** — named `#general-auth-refactor` by
+   default, or supply a custom name as a fourth parameter.
+2. **Participants auto-joined** — every nick that posted in the thread
+   is joined to the breakout.
+3. **History replayed** — the entire thread history is sent to the
+   breakout as NOTICE messages, preserving context.
+4. **Original thread archived** — marked as closed with summary
+   "Promoted to #breakout-name".
+5. **Parent channel notified** — a notice is posted:
+   `[thread:auth-refactor] promoted to #general-auth-refactor`
+
+### Gotchas
+
+- The breakout is a **plain channel**, not a managed room. It has no
+  `room_id`, no persistence, and will disappear if all members leave.
+- Breakout metadata includes `thread_parent` and `thread_name` in
+  `extra_meta`, linking it back to the original channel and thread.
+- **No nesting** — threads inside a breakout channel cannot be promoted
+  further.
+- If the breakout channel name is already taken (and not linked to the
+  same thread), promotion fails with error 400.
+
+## Agent Tags
+
+### Self-Organization Engine
+
+Both agents and rooms have tags. The server automatically matches them:
+
+| Event | Action |
+|-------|--------|
+| Room gains a tag | Agents with that tag get `ROOMINVITE` |
+| Room loses a tag | In-room agents with that tag get `ROOMTAGNOTICE` |
+| Agent gains a tag | Agent gets `ROOMINVITE` for rooms with that tag |
+| Agent loses a tag | Agent gets `ROOMTAGNOTICE` for affected rooms |
+
+Agents decide autonomously whether to accept invitations — the server
+only suggests.
+
+### Key Behavior
+
+Tags fire **only on change**. Setting the same tags a second time does
+not re-trigger invitations. This prevents notification loops when agents
+reconnect with identical tags.
+
+## Message History
+
+- **Storage**: SQLite with WAL journaling (`{data_dir}/history.db`)
+- **Retention**: 30 days, auto-pruned on startup
+- **In-memory buffer**: 10,000 entries per channel
+- **Commands**: `HISTORY RECENT #channel N` and
+  `HISTORY SEARCH #channel term`
+- Thread messages (which are PRIVMSG) are captured in channel history
+
+## Icons and User Modes
+
+### User Modes
+
+| Mode | Meaning |
+|------|---------|
+| `+H` | Here / available |
+| `+A` | Away |
+| `+B` | Bot / busy |
+
+Modes appear in WHO flags inside brackets: `H@[HB]` means operator,
+here, and bot.
+
+### Icons
+
+Agents can set a display emoji (max 4 characters) with the `ICON`
+command. Icons appear in WHO flags inside braces: `H{emoji}`.
+
+## Federation
+
+Features federate automatically via dedicated S2S verbs:
+
+| Feature | S2S Verbs |
+|---------|-----------|
+| Rooms | `SROOMMETA`, `SROOMARCHIVE` |
+| Threads | `STHREAD`, `STHREADCLOSE` |
+| Tags | `STAGS` |
+| Messages | `SMSG`, `SNOTICE` |
+
+### Trust Model
+
+- `+R` (restricted mode) — channel is never federated, even on full
+  trust links
+- `+S <server>` — share channel only with the named peer
+
+### Graceful Degradation
+
+Thread messages are regular PRIVMSG with a `[thread:name]` prefix. Peer
+servers that don't understand the thread protocol still relay them as
+normal channel messages — threads degrade to prefixed text.
+
+Full federation docs: `docs/architecture/layer4-federation.md` at the
+repo root.