Engo

Engo is an IRC bot implemented in Go with Tengo as its embedded scripting language.

M0–M4 established the project foundation, robust IRC lifecycle, Tengo event/command API, transactional script lifecycle, persistence, timers and constrained HTTP access. M5 adds IRCv3 capability negotiation plus capability- and account-based authorization. PBMP integration adds an optional local management interface shared with LuCa and BotWeb.

Standalone-first rule

Standalone qualification requires the bot to build and pass its core test suite with PBMP, BotWeb, BotAI and BotLogic disabled. None of these integrations may become a required build/runtime dependency.

Engo MUST remain a fully functional IRC bot without PBMP, BotWeb, BotAI, BotLogic, or any other external Ploos service. PBMP management, BotWeb integration, BotAI capabilities and BotLogic are optional adapters/features only. Their absence, failure, or removal MUST NOT prevent normal IRC operation or make core bot functionality depend on an external control plane or AI service.

Status

M5 — IRCv3 and permissions (implementation in progress; CI qualification pending)

Implemented:

• Go module and cmd/engo executable
• IRC client with TLS support and TLS 1.2 minimum
• NICK / USER registration and IRCv3 CAP negotiation
• optional SASL PLAIN authentication
• IRC PING / PONG
• exponential reconnect/backoff
• graceful SIGINT/SIGTERM shutdown
• configuration validation
• embedded Tengo runtime
• example Tengo script
• unit test for script execution
• GitHub Actions CI
• Alpine OCI build
• MIT license
• transactional multi-script hot reload with allocation limits
• per-script persistent KV storage and timers
• constrained HTTPS client with hostname allowlist and SSRF defenses
• per-script capabilities (including explicit HTTP grants)
• IRCv3 account-tag, account-notify, extended-join and server-time negotiation
• account identity provenance tracking and fail-closed command permissions
• optional standalone architecture; external control planes are not required to run Engo

CI includes normal tests, race-detector tests, vet, Go build and Alpine container build. A current green GitHub Actions run has not yet been independently verified.

Run the Tengo proof of concept

go run ./cmd/engo

Without ENGO_SERVER, Engo executes the configured Tengo script and exits.

Connect to IRC

ENGO_SERVER=irc.example.net:6697 \
ENGO_NICK=engo \
go run ./cmd/engo

Configuration variables:

Variable	Default	Description
ENGO_SERVER	empty	IRC server as host:port; empty means no IRC connection
ENGO_NICK	engo	IRC nickname
ENGO_USER	engo	IRC username
ENGO_REALNAME	Engo IRC bot	IRC real name
ENGO_TLS	1	TLS enabled unless set to 0
ENGO_SCRIPT	scripts/examples/hello.tengo	Single Tengo script; used when ENGO_SCRIPTS_DIR is unset
ENGO_SCRIPTS_DIR	empty	Directory of .tengo scripts loaded transactionally
ENGO_SCRIPT_MAX_ALLOCS	100000	Maximum Tengo VM allocations per registration/event execution
ENGO_SASL_USERNAME	empty	SASL PLAIN authentication identity; requires password
ENGO_SASL_PASSWORD	empty	SASL PLAIN password; requires username
ENGO_RECONNECT_MIN	2s	Initial reconnect delay
ENGO_RECONNECT_MAX	2m	Maximum reconnect delay
ENGO_PBMP_SOCKET	empty	Optional local PBMP/1 Unix socket; e.g. /tmp/engo.pbmp.sock
ENGO_CHANNELS	empty	Comma-separated configured channels exposed through PBMP channels.list

OCI

docker build -t engo:dev .
docker run --rm engo:dev

Alpine Linux is the default OCI base where practical.

Project direction

Go owns protocol correctness, networking, TLS, lifecycle, security boundaries and resource management. Tengo scripts will define commands and event-driven bot behaviour through a controlled capability-based API.

See docs/ARCHITECTURE.md for the architecture and milestone roadmap.

License

MIT. See LICENSE.

Optional BotAI

Engo can use the separate BotAI service without depending on it for normal IRC operation. Set ENGO_BOTAI_URL to enable the !ai <message> command; ENGO_BOTAI_EXPERT defaults to auto. See docs/M1.1-BOTAI.md.

M1.2 adds optional in-memory bounded BotAI context (ENGO_BOTAI_HISTORY_MESSAGES, default 10, max 20) and !aireset; see docs/M1.2-BOTAI-CONTEXT.md.

M1.3 adds opt-in natural conversation with ENGO_BOTAI_CONVERSATION=1: PMs and explicit channel mentions can use BotAI while ordinary channel traffic and commands remain untouched. See docs/M1.3-BOTAI-CONVERSATION.md.

M1.4 bounds BotAI traffic with ENGO_BOTAI_MAX_CONCURRENT (default 2) and per-conversation ENGO_BOTAI_COOLDOWN (default 2s). See docs/M1.4-BOTAI-LIMITS.md.

M1.5 exposes privacy-safe, read-only BotAI operational status and counters through PBMP botai.status, suitable for optional BotWeb display. See docs/M1.5-BOTAI-PBMP.md.