Plugins

UGENT channel plugins run as separate OS processes communicating via JSON-RPC over Unix domain sockets. Each channel is isolated — crashes don't cascade.

Plugin Setup

Interactive (REPL)

/plugin setup

The wizard lets you select which plugins to enable, configure swarm nodes, and writes instance-scoped config.

Auto (TUI)

/plugin setup

Non-interactive — generates instance-scoped config from global settings.

Migrate

/plugin migrate

Regenerates instance-scoped config from global config.

Plugin Registration

Plugins are registered in plugins.toml:

schema_version = 1

[[plugins]]
id = "telegram-main"
kind = "channel-telegram"
enabled = true
command = "./target/release/channel-telegram-worker"
args = ["--mode", "polling"]
env_refs = ["TELEGRAM_BOT_TOKEN"]

[plugins.limits]
max_in_flight = 64
max_retries = 5
heartbeat_secs = 30

[plugins.routing]
workspace = "/path/to/workspace"
allowed_senders = ["telegram:123456789"]

Building Plugins

Use the public plugin template:

cargo install cargo-generate
cargo generate --git https://github.com/unizhu/ugent-plugin-template

The template includes:

• Full lifecycle: heartbeat, inbound listener, outbound polling, graceful shutdown
• Crash-recovery outbox for in-flight messages
• Integration test with MockBridge
• CI workflow (fmt + clippy + test)

What You Implement

1. Channel API connection — connect to your channel (WebSocket, HTTP, webhook)
2. Inbound normalization — map channel messages to UGENT's inbound format
3. Outbound delivery — send responses back to the channel API
4. Media handling — download/upload attachments (optional)

Process Supervision

The plugin supervisor manages:

• Kill on drop — dropped handles don't leak processes
• Process groups — group-targeted termination (Unix)
• Parent-death signaling — reduces orphan risk (Linux)
• Two-phase shutdown — graceful terminate, then force-kill
• Circuit breaker — 3 consecutive cooldown rounds auto-disable a plugin
• Stale worker cleanup — reaps workers from previous crashed sessions

13 Channels

Channel	Kind	Notes
Telegram	channel-telegram	Polling or webhook mode
Slack	channel-slack	Socket Mode or webhook
Discord	channel-discord	Gateway WebSocket
LINE	channel-line	Messaging API + webhook
WeChat	channel-wechat	Personal account bridge
WeCom	channel-wecom	Enterprise WeChat
Weixin	channel-weixin	WeChat Official Account
Email	channel-email	Gmail push or IMAP
DingTalk	channel-dingtalk	Robot webhook
WhatsApp	channel-whatsapp	Cloud API or proxy
Salesforce	channel-salesforce-event	Platform Events
Web	channel-web	HTTP API + SSE streaming
Translation	channel-translate	Document/text translation pipeline

Web Channel API

The web channel provides an OpenAI-compatible API plus native UGENT streaming:

Endpoint	Purpose
POST /v1/chat/completions	OpenAI-compatible chat (stream + non-stream)
GET /v1/models	List available models
POST /v1/files	Upload files
GET /v1/files/{id}	Download files
GET /v1/ugent/events	SSE event stream
POST /v1/ugent/commands	Slash command execution
GET /v1/ugent/snapshot	Session bootstrap
POST /v1/ugent/stop	Cancel in-flight turn (per conversation)
GET /v1/ws/voice	Voice WebSocket transport