Channel Platform Architecture
TheChannelPlatform serves as the high-level coordinator within the daemon crates/palyra-daemon/src/channels.rs#106-110. It encapsulates the ConnectorSupervisor, which manages individual connector instances and their associated storage.
Data Flow: Inbound & Outbound
The system uses a decoupled architecture where the daemon communicates with connectors via aConnectorRouter implementation. For the daemon, this is typically the GrpcChannelRouter crates/palyra-daemon/src/channels.rs#125-126.
- Inbound Flow: A platform adapter (e.g.,
DiscordConnectorAdapter) receives a message, wraps it in anInboundMessageEvent, and submits it to theConnectorSupervisor. The supervisor then uses theConnectorRouterto dispatch it into the daemon’s internal run orchestration pipeline. - Outbound Flow: When an agent produces a response, the daemon enqueues an
OutboundMessageRequestcrates/palyra-connectors/src/lib.rs#10. The supervisor picks this up, identifies the correct adapter, and attempts delivery.
Connector Management & Supervision
TheConnectorSupervisor is responsible for the health and persistence of all connectors crates/palyra-connector-core/src/supervisor.rs. It uses a SQLite-backed ConnectorStore to persist instance specifications and message queues crates/palyra-daemon/src/channels.rs#119.
System Entity Mapping: Connector Supervision
| Component | Code Entity | Responsibility |
|---|---|---|
| Supervisor | ConnectorSupervisor | Manages adapter lifecycles and task scheduling. |
| Store | ConnectorStore | Persists ConnectorInstanceRecord and OutboxEntryRecord. |
| Adapter | ConnectorAdapter | Trait for platform-specific logic (Discord, Echo, etc.). |
| Router | ConnectorRouter | Interface for dispatching inbound messages to the daemon. |
Connectors & Adapters
Palyra supports multiple connector types, categorized by theirConnectorAvailability crates/palyra-connectors/src/lib.rs#5.
- Supported: Fully functional connectors like
DiscordConnectorAdaptercrates/palyra-connectors/src/connectors/mod.rs#7. - Internal/Test: The
EchoConnectorAdapter, used for integration testing and simulating failures like crashes crates/palyra-connectors/src/connectors/echo.rs#21-24. - Deferred: Connectors in the roadmap but not yet active, such as
SlackConnectorAdapterandTelegramConnectorAdaptercrates/palyra-connectors/src/connectors/slack.rs#18-20, crates/palyra-connectors/src/connectors/telegram.rs#18-20.
Discord Connector
The Discord connector is the primary production-ready channel. It handles:- Onboarding: Probing bot identity and verifying permissions crates/palyra-daemon/src/transport/http/handlers/admin/channels/connectors/discord.rs#6-8.
- Normalization: Converting Discord-specific IDs into canonical identities crates/palyra-daemon/src/channels.rs#164-165.
- Lifecycle: Support for
login,logout, andremoveoperations via the CLI and Admin API crates/palyra-daemon/src/transport/http/handlers/admin/channels/connectors/discord.rs#42-110.
Reliability: Dead-Letter Queues & Retries
The supervisor maintains an outbox for each connector. If a delivery fails, the system classifies the error viaRetryClass crates/palyra-connectors/src/lib.rs#11:
- Transient: Retried with exponential backoff.
- Permanent: Moved to the
DeadLetterRecordcrates/palyra-connectors/src/lib.rs#8.
Channel Routing & Security
TheChannelRouter manages how inbound messages are mapped to agent sessions and enforces access control crates/palyra-daemon/src/channel_router.rs#178-192.
Routing Rules
Each channel can be configured with specificChannelRoutingRule parameters:
- Inbound Filtering:
allow_fromanddeny_fromlists crates/palyra-daemon/src/channel_router.rs#165-166. - Mention Requirements:
mention_patternsandrequire_mentionflags crates/palyra-daemon/src/channel_router.rs#164. - Session Isolation:
isolate_session_by_senderdetermines if users share a session or have private ones crates/palyra-daemon/src/channel_router.rs#169.
Direct Message (DM) Pairing
To prevent spam and unauthorized access via DMs, Palyra implements aDirectMessagePolicy crates/palyra-daemon/src/channel_router.rs#57-61:
- Deny: All DMs are ignored.
- Allow: All DMs are processed.
- Pairing: Requires a
PairingCodeRecord. Users must provide a valid code to establish aPairingGrantRecordcrates/palyra-daemon/src/channel_router.rs#104-110.
Code Logic: DM Pairing Flow
Sources: crates/palyra-daemon/src/channel_router.rs#84-158Webhook Ingestion
TheWebhookRegistry manages generic HTTP callback integrations crates/palyra-daemon/src/webhooks.rs#107-111. Webhooks allow external systems to push data into Palyra’s event stream.
Configuration & Security
- Registry: Stored in
webhooks.tomlwithin the state root crates/palyra-daemon/src/webhooks.rs#16. - Secrets: Each webhook integration references a secret in the
Vaultfor signature verification crates/palyra-daemon/src/webhooks.rs#37. - Validation: Inbound payloads are limited by
max_payload_bytes(default 64KB) and can be filtered byallowed_eventscrates/palyra-daemon/src/webhooks.rs:23, 38.
Implementation Details
TheWebhookRegistry provides a list_views method to return WebhookIntegrationView objects for the UI, ensuring that readiness is checked (verifying if the secret exists in the vault) before reporting the integration as “Ready” crates/palyra-daemon/src/webhooks.rs:189-216, 75-86.
Sources: crates/palyra-daemon/src/webhooks.rs#52-72, crates/palyra-daemon/src/webhooks.rs#178-187
Administrative Interface
The daemon exposes HTTP handlers for managing the channel platform under the/admin/v1/channels and /admin/v1/webhooks paths.
Channel Operations Snapshot
Thebuild_channel_operations_snapshot function aggregates real-time metrics for the UI crates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#55-61:
- Saturation State: Reports if the channel is
healthy,rate_limited,backpressured, ordead_letteredcrates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#114-147. - Queue Depth: Monitors
pending_outbox,due_outbox, andclaimed_outboxcrates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#167-178.
CLI Commands
Thepalyra channels and palyra webhooks command families provide terminal access to these features crates/palyra-cli/src/commands/channels/mod.rs#61-63.
Sources: crates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#29-53, crates/palyra-cli/src/commands/channels/mod.rs#206-224