Channel Connectors and Messaging

The Channel Connector subsystem provides the interface between Palyra’s internal agent logic and external communication platforms. It manages the lifecycle of connections, enforces routing policies for inbound messages, and provides a unified API for outbound delivery across different protocols.

​

System Architecture

The messaging architecture is split between the palyra-connectors crate, which defines the provider-agnostic interfaces, and the palyra-daemon, which implements the routing and application-level logic. Messaging Architecture Overview Sources: crates/palyra-daemon/src/channels.rs#1-10, crates/palyra-daemon/src/channel_router.rs#1-10, crates/palyra-connectors/src/lib.rs#1-9

​

Core Components

​

ChannelPlatform

The ChannelPlatform serves as the high-level facade for the daemon. It integrates the ConnectorSupervisor, the MediaArtifactStore, and the gRPC gateway router into a single operator-facing surface crates/palyra-daemon/src/channels.rs#1-10. It handles:

• Connector inventory and lifecycle management crates/palyra-daemon/src/channels.rs#176-183.
• Message read, search, and mutation operations (edit/delete/react) crates/palyra-daemon/src/channels.rs#114-143.
• Outbound attachment processing crates/palyra-daemon/src/channels.rs#56-58.

​

ChannelRouter

The ChannelRouter is a policy-driven engine that decides if an inbound message should trigger an agent run. It evaluates mention patterns, sender allow/deny lists, and Direct Message (DM) policies crates/palyra-daemon/src/channel_router.rs#1-10.

​

ConnectorSupervisor

The ConnectorSupervisor manages the background workers that poll inbound traffic and drain the outbox crates/palyra-daemon/src/channels.rs#4-7. It tracks ConnectorStatusSnapshot and manages the ConnectorQueueSnapshot which includes pending, claimed, and dead-lettered messages crates/palyra-daemon/src/application/channels/status.rs#31-35. Sources: crates/palyra-daemon/src/channels.rs#169-174, crates/palyra-daemon/src/channel_router.rs#195-208, crates/palyra-daemon/src/application/channels/status.rs#80-112

​

Messaging Lifecycle

The system processes messages through a multi-stage pipeline to ensure reliability and policy compliance. Inbound and Outbound Data Flow Sources: crates/palyra-connectors/tests/simulator_harness.rs#47-78, crates/palyra-daemon/src/channels/discord.rs#150-173

​

Inbound Pipeline

1. Ingress: Platforms deliver messages to the ConnectorAdapter.
2. Admission: ChannelRouter checks rules (e.g., allow_from, require_mention) crates/palyra-daemon/src/channel_router.rs#195-208.
3. Coalescing: Rapid-fire messages are merged to provide coherent context.
4. Dispatch: The message is sent to the AgentRunLoopState for processing.

For details, see Channel Router and Inbound Pipeline.

​

Outbound Pipeline

1. Enqueue: Agents request a message send via OutboundMessageRequest crates/palyra-daemon/src/channels/discord.rs#150-166.
2. Delivery: The supervisor drains the outbox and calls the adapter’s send_outbound method crates/palyra-connectors/tests/simulator_harness.rs#129-133.
3. Receipt: A DeliveryOutcome is returned, providing a native platform ID or a RetryClass for failures crates/palyra-connectors/tests/simulator_harness.rs#141-161.

​

Supported Connectors

Palyra uses a provider-adapter architecture. Currently, Discord is the primary supported platform, with stubs for Slack and Telegram.

​

Discord Adapter

The Discord implementation uses a WebSocket gateway for inbound events and a REST API for outbound messaging and administrative operations (like guild/channel resolution) crates/palyra-connectors/src/providers/discord/adapter/tests.rs#1-20. It supports:

• Zlib-stream compression for gateway traffic crates/palyra-connectors/src/providers/discord/adapter/tests.rs#25-27.
• Automatic chunking of long messages crates/palyra-connectors/src/providers/discord/adapter/tests.rs#16-17.
• Rate limit handling with RetryClass::RateLimit crates/palyra-connectors/tests/simulator_harness.rs#147-154.

For details, see Platform Connectors: Discord, Slack, Telegram. Sources: crates/palyra-daemon/src/channels/discord.rs#19-23, crates/palyra-connectors/src/providers/discord/adapter/tests.rs#16-27, crates/palyra-connectors/tests/simulator_harness.rs#121-128

​

Operational Management

Operators manage channels through the CLI (palyra channels) or the Web Console.

​

CLI Operations

The CLI provides commands for lifecycle management:

• add/login: Configures a new connector crates/palyra-cli/src/commands/channels/mod.rs#38-140.
• status: Displays health and queue depth crates/palyra-cli/src/commands/channels/mod.rs#260-272.
• pairings: Manages DM pairing codes and grants crates/palyra-cli/src/commands/channels/mod.rs#215-235.

​

Health and Monitoring

The build_channel_status_payload function aggregates connector status, runtime snapshots, and queue health crates/palyra-daemon/src/application/channels/status.rs#27-55. It identifies saturation states such as rate_limited, auth_failed, or backpressure crates/palyra-daemon/src/application/channels/status.rs#118-154. Sources: crates/palyra-cli/src/commands/channels/mod.rs#36-40, crates/palyra-daemon/src/application/channels/status.rs#1-7, crates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#26-41

​

Child Pages

• Channel Router and Inbound Pipeline
• Platform Connectors: Discord, Slack, Telegram