420NexusIrcD

Structured IRC Operations & Autonomous Agent Orchestration Platform

420NexusIrcD is a modular, high-performance platform designed for complex IRC operations, autonomous worker automation, and Proxmox-based agent orchestration. It bridges classic IRC communication with modern KI-workloads and infrastructure management.

🚀 Core Principles

1. IRC-First Intelligence: Advanced IRCv3 transport with ZNC playback filtering and deep event hooks.
2. Autonomous Automation: Distributed worker queue with atomic claim-locks and intelligent routing.
3. Infrastructure Orchestration: Native support for Proxmox LXC agent deployment and lifecycle management.
4. Security & Guarding: Policy-aware execution (ReplyGuard), role-based access control, and comprehensive audit logging.

🛠 System Architecture

The platform is strictly decoupled into functional layers:

Frontend (retro_client)

• V2.1 Desktop UI: PySide6-based interface with modular Dock-System.
• Management Hubs: Integrated control for Plugins, Modules, and Worker Profiles.
• Agents Console: Live-monitoring, audit logs, and real-time status badges for orchestrated agents.
• Work Board: Kanban-style task tracking and manual intervention palette.

Orchestration & Workers

• worker_queue: Centralized task management with priority queuing and stale-requeue logic.
• agent_orchestrator: Registry-based deployment skeleton for Proxmox LXC containers.
• agentd: Async job scheduler connecting workers to specific runtimes (Shell, Ollama, etc.).

Core & Integration

• ircstack: High-level IRC transport with WHOIS/NAMES synchronization and ZNC support.
• plugin_sdk: Capability-gated plugin system with asynchronus lifecycle hooks.
• module_hub / plugin_hub: Dynamic runtime control for enabling/disabling system components without restart.
• memory_hub: 6-layer cognitive memory stack with optional persistent Postgres backend.
• control_services: Central policy engine, ledger, and activity persistence.

📊 Architecture Snapshot

graph TD
  subgraph UI Layer [Desktop Frontend]
    UI["retro_client (V2.1)"]
    AC["Agents Console"]
    HB["Module/Plugin Hub"]
  end

  subgraph Orchestration [Automation Layer]
    WQ["worker_queue"]
    AO["agent_orchestrator"]
    AD["agentd (Scheduler)"]
  end

  subgraph Connectivity [Communication Layer]
    IRC["ircstack (IRCv3/ZNC)"]
    LS["lorastack (LoRa)"]
    MCP["mcp_gateway"]
  end

  subgraph Registry [Data & Policy]
    PR["Worker Profiles"]
    AR["Agents Registry"]
    CS["control_services (Ledger)"]
  end

  UI <--> Engine["main.py engine"]
  Engine <--> WQ
  Engine <--> AO
  Engine <--> HB
  WQ <--> AD
  AD <--> AO
  Engine <--> IRC
  AO <--> AR
  WQ <--> PR
  AD --> CS

🏁 Quick Start

Prerequisites

• Python 3.11+
• Proxmox VE (optional for agent orchestration)
• ZNC / IRC Server (optional)

1. Environment Setup

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install all packages in editable mode
pip install -r requirements.txt
pip install -e ./packages/ircstack -e ./packages/agentd -e ./packages/plugin_sdk \
            -e ./packages/control_services -e ./packages/retro_client \
            -e ./packages/worker_queue -e ./packages/agent_orchestrator \
            -e ./packages/module_hub -e ./packages/plugin_hub

2. Launch

# Start UI Mode (Full Suite)
python main.py

# Enable Agent Orchestrator via CLI
python main.py --enable-orchestrator

# Headless Ops Mode
python main.py --headless --config config.yaml

3. Persistent Memory (optional)

# Enable DB-backed memory storage
export MEMORY_DB_URL='postgresql+psycopg2://bot_user:<password>@192.168.1.110:5432/zentrale_memory'

Then set modules.memory_hub: true in config.yaml.
The memory hub stores entries in table nexus_memories by default.

4. Persistent Instruction Bus (optional)

# Enable DB-backed instruction bus storage
export INSTRUCTION_BUS_DB_URL='postgresql+psycopg2://bot_user:<password>@192.168.1.110:5432/zentrale_memory'

Then set modules.instruction_bus: true in module settings.
The bus stores entries in table nexus_instruction_bus by default.

🛡 Security & Guarding

• ReplyGuard: Protects channels from automated spam. Modes: active, muted (internal work only), restricted.
• Role-Gate: RBAC for IRC commands. Roles: brain_admin (full control), operator (task management), observer (read-only).
• DCC Policy: CTCP DCC requests are blocked by default and require explicit capability authorization.

📂 Repository Structure

• packages/: Modularized platform components (reusable libraries).
• plugins/: High-level feature extensions (e.g., work_manager).
• config/: Runtime configurations (Agents Registry, Worker Profiles).
• docs/: Deep-dive documentation and architectural masterplans.
• tests/: Comprehensive E2E and unit test suites (Pytest).

🖥 Operations Console

The platform provides a unified management interface for real-time monitoring and control:

• Agents Console: A live stream of all orchestrated activities. Filter by agent, channel, or severity. Export logs for deep-dive analysis.
• System Hub: Toggle platform modules and plugins at runtime. Critical changes trigger restart warnings and automatic configuration snapshots.
• Plugin/Module Manager: Advanced UIs for granular control of the platform's lifecycle. Track load status, active hooks, and detailed error logs for each plugin and module.
• Command Styles: Customize the visual representation of bot commands and system messages. Configure foreground/background colors, icons, and prefixes with live preview and persistent storage.
• Ollama Settings: Configure local LLM integration. Features include model discovery (fetch from API), parameter tuning (temperature, max tokens), and integrated connectivity testing.
• Notifications & Sounds: Modular notification system with configurable audio alerts for mentions, PMs, and system events. Includes per-event volume control and sound file selection.
• Instruction Bus: Intermediate communication layer for agent-to-agent and agent-to-system coordination. Supports hard-guarded IRC promotion, manual intervention (Ack/Nack), and persistent logging. Includes a dedicated Bus Policy manager to define promotion whitelists, restricted mode rules, and payload limits.
• Remote Daemon Mode: Decouple the UI from the engine. Run the engine as a background service (--daemon) and connect from any client (--remote). Features include WebSocket-based live event streaming and REST-controlled management.
• Plugin Sources: Manage external plugin repositories directly from the UI. Add or remove paths with real-time validation and persistent storage in config.yaml.
• Routing Engine: Define granular rules for task distribution. Each route supports specific runtimes (Ollama, Shell) and priority levels.
• Debug Monitor: Live telemetry for queue depth, active worker count, and orchestrator health.

📋 Modul-Matrix

Modul	Status	Description
ircstack	✅	IRCv3 + ZNC Integration, Event-Driven
worker_queue	✅	Atomic Task Claims, Priority Queuing
agent_orchestrator	✅	Proxmox LXC Registry & P1 Deployment
retro_client	✅	PySide6 V2.1 UI, Dock Management
module_hub	✅	Dynamic Module Lifecycle
plugin_hub	✅	Plugin Toggle & Discovery Control
agentd	✅	KI-Agent Scheduler & Ollama/Shell Runtimes

---

Generated by Liz (Gemini CLI) for Das Imperium.